GTK4: SplitView FFIs (`splitview_create`, `splitview_add_child`) not wired — co-blocks docs/examples/ui/layout/snippets.ts on Linux CI

[proggeramlug]

Context

docs/examples/ui/layout/snippets.ts imports SplitView and splitViewAddChild from perry/ui to demonstrate the split-pane layout pattern. The example compiles + links cleanly on macOS (NSSplitView) but fails on the GTK4-on-Ubuntu doc-tests CI runner with:

/usr/bin/ld: perry_llvm_*.ll:(.text+...): undefined reference to `perry_ui_splitview_create'
/usr/bin/ld: perry_llvm_*.ll:(.text+...): undefined reference to `perry_ui_splitview_add_child'

Co-blocker (alongside #217's overlay/reorder FFIs) for the gtk4 doc-tests gate on origin/main.

What's missing

FFI	macOS	GTK4 mapping
perry_ui_splitview_create	NSSplitView widget	gtk::Paned::new(Orientation::Horizontal)
perry_ui_splitview_add_child	addArrangedSubview:	Paned::set_start_child(&child) for first call, set_end_child(&child) for second

Implementation notes

• gtk::Paned is GTK4's split-pane primitive. It supports exactly two children (start_child + end_child), unlike NSSplitView which can hold N. Most uses of SplitView in TS pass exactly 2 children, but the API allows more.
• Decision needed: cap GTK4's splitview_add_child at 2 (third+ call → no-op or error), or nest Paneds recursively to support N children. The simplest+correct first cut is the 2-child cap, with a runtime warn if a third child arrives.
• Default orientation: macOS NSSplitView defaults to vertical-divider (horizontal arrangement). Match that with Orientation::Horizontal on Paned.
• The handle/separator is automatic on Paned; no need to wire a separate setOrientation API for the first cut unless it already exists on macOS.

Acceptance

• Both FFIs exported as #[no_mangle] pub extern "C" fn in crates/perry-ui-gtk4/src/lib.rs.
• If splitview rows exist in crates/perry-ui/src/styling_matrix.rs, flip the GTK4 cells from Missing to Wired. Verify ./target/release/styling-matrix --check is clean.
• cargo build --release -p perry-ui-gtk4 succeeds.
• docs/examples/ui/layout/snippets.ts compiles + links cleanly on Linux (in conjunction with GTK4: 4 widget overlay/reorder FFIs not wired — blocks docs/examples/ui/layout/snippets.ts on Linux CI #217's overlay/reorder fix).
• PR body explicitly notes the 2-child cap on GTK4 vs N-child on macOS, so it's discoverable when someone hits the limit.

Pointers

• macOS implementations: search crates/perry-ui-macos/src/ for perry_ui_splitview_create / _add_child.
• Existing GTK4 multi-child container patterns: search crates/perry-ui-gtk4/src/ for vstack_create / hstack_create / add_child — same shape, just Paned instead of Box.
• Failing doc-test: docs/examples/ui/layout/snippets.ts.

Related

• I hope it is easy and convenient to modify the component's style, similar to the style attribute in HTML. #185 (UI cross-platform audit)
• GTK4: 4 styling FFI gaps surfaced by #185 Phase B audit #202 (closed — same shape)
• GTK4: perry_ui_open_folder_dialog not wired — blocks docs/examples/ui/dialogs/snippets.ts on Linux CI #216 (sibling: GTK4 folder dialog)
• GTK4: 4 widget overlay/reorder FFIs not wired — blocks docs/examples/ui/layout/snippets.ts on Linux CI #217 (sibling: GTK4 overlay/reorder)

Estimated size

Small — ~30-50 LOC. The 2-vs-N child caveat is the only design decision worth flagging in the PR.

[proggeramlug]

Wired in v0.5.322 (commit e58ff60). New crates/perry-ui-gtk4/src/widgets/splitview.rs backed by gtk4::Paned::new(Orientation::Horizontal) (matches macOS NSSplitView's vertical-divider/side-by-side default).

• splitview_create(left_width) — accepts the macOS arg for signature parity but ignores it (Paned::set_position is a separate setter the user can call if needed).
• splitview_add_child — first call → set_start_child, second → set_end_child, third+ → no-op + warning.

2-vs-N caveat (per the issue's PR-body ask): GTK4 Paned supports exactly 2 children where macOS NSSplitView supports N. Users wanting >2 panes on Linux should nest SplitViews recursively. The runtime warning makes the cap discoverable when someone hits it.

docs/examples/ui/layout/snippets.ts now compiles + links + exits 0 in test mode on Linux GTK4.