@nativedesktop/panes 0.1.0

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@nativedesktop/panes",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://github.com/FormalSnake/NativeDesktop#readme",
+  "bugs": "https://github.com/FormalSnake/NativeDesktop/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FormalSnake/NativeDesktop.git",
+    "directory": "packages/panes"
+  },
+  "publishConfig": {
+  "access": "public"
+},
+"files": ["src"],
+"main": "./src/index.ts",
+"types": "./src/index.ts",
+"exports": {
+  ".": "./src/index.ts"
+},
+"peerDependencies": {
+  "@nativedesktop/react": "^0.1.0"
+},
+"devDependencies": {
+  "@types/react": "19.2.17",
+  "react": "19.2.7"
+}
+}

package/src/PaneTree.tsx

@@ -0,0 +1,136 @@
+/** @jsxImportSource @nativedesktop/react */
+// The pragma is load-bearing: this is a raw-src package, and Bun transpiles
+// node_modules TSX with the ROOT tsconfig's JSX settings, so the per-file
+// pragma is what guarantees the ND jsx-runtime regardless of the consumer.
+//
+// Hooks come from @nativedesktop/react, never react directly (dev-react.ts's
+// pinned-dispatcher contract for `nd dev` hot re-eval).
+
+import { useRef, useState } from "@nativedesktop/react";
+import type { ReactNode } from "react";
+import {
+  closePane,
+  focusNeighbor,
+  focusPane,
+  focusPaneAt,
+  setPaneRatio,
+  splitPane,
+  updatePane,
+} from "./model.ts";
+import type { PaneModel, PaneNode, SplitOrientation } from "./model.ts";
+
+export interface PaneTreeProps<T> {
+  model: PaneModel<T>;
+  onChange: (next: PaneModel<T>) => void;
+  /** Owns all per-pane chrome (focus ring, toolbar); PaneTree supplies only
+   * the flags and one expanding <box> wrapper per leaf. */
+  renderLeaf: (ctx: { id: string; data: T; focused: boolean; solo: boolean }) => ReactNode;
+  testID?: string;
+}
+
+export function PaneTree<T>(props: PaneTreeProps<T>): ReactNode {
+  // Latest-ref: the native positionChanged echo lands via a handler captured
+  // at an earlier render; applying it against that render's model would
+  // revert everything committed since (a concurrent split, another divider's
+  // drag). Both refs are refreshed every render, so handlers always see the
+  // current model and onChange.
+  const modelRef = useRef(props.model);
+  modelRef.current = props.model;
+  const onChangeRef = useRef(props.onChange);
+  onChangeRef.current = props.onChange;
+
+  const { model, renderLeaf, testID } = props;
+  if (!model.root) return null;
+  const solo = model.root.kind === "leaf";
+
+  function renderNode(node: PaneNode<T>): ReactNode {
+    if (node.kind === "leaf") {
+      return (
+        <box
+          key={node.id}
+          style={{ hexpand: true, vexpand: true }}
+          testID={testID ? `${testID}-leaf-${node.id}` : undefined}
+        >
+          {renderLeaf({ id: node.id, data: node.data, focused: node.id === model.focusedId, solo })}
+        </box>
+      );
+    }
+    return (
+      // Keyed on the split node id: orientation is create-only on both
+      // backends, so a structural collapse landing a DIFFERENT split at this
+      // position must remount rather than mutate.
+      <paned
+        key={node.id}
+        orientation={node.orientation}
+        position={node.ratio}
+        testID={testID ? `${testID}-split-${node.id}` : undefined}
+        onPositionChanged={(e) => {
+          // Exact 0/1 (or non-finite) is dropped: structural commits racing
+          // the backend's debounced echo report a zero-size mid-layout
+          // artifact at exactly those values, and feeding one to the model
+          // would collapse the pane on the next render. Anything inside
+          // (0, 1) is a settled drag and flows through — AppKit pins a
+          // 120pt minimum pane extent, but GTK only floors at the CHILD's
+          // own minimum size, so a min-size-zero child can rest out past
+          // the clamp bounds; setPaneRatio's clamp then updates the model
+          // and the position prop write snaps the native divider back to
+          // the bound instead of desyncing the two.
+          if (!Number.isFinite(e.position) || e.position <= 0 || e.position >= 1) return;
+          const current = modelRef.current;
+          // setPaneRatio returns the same reference when the clamped ratio is
+          // unchanged; skipping onChange there is what stops the programmatic
+          // write -> echo -> render -> write loop.
+          const next = setPaneRatio(current, node.id, e.position);
+          if (next !== current) onChangeRef.current(next);
+        }}
+      >
+        {renderNode(node.children[0])}
+        {renderNode(node.children[1])}
+      </paned>
+    );
+  }
+
+  return renderNode(model.root);
+}
+
+export interface UsePaneTree<T> {
+  model: PaneModel<T>;
+  /** The latest-ref invariant, built in: reads the model as of the last op,
+   * not the last render. */
+  latest: () => PaneModel<T>;
+  setModel(m: PaneModel<T>): void;
+  split(paneId: string, o: SplitOrientation, data: T): void;
+  close(paneId: string): void;
+  focus(paneId: string): void;
+  focusAt(index: number): void;
+  focusNeighbor(dir: "left" | "right" | "up" | "down"): void;
+  setRatio(splitId: string, ratio: number): void;
+  update(paneId: string, fn: (d: T) => T): void;
+}
+
+/** Holds the model in state and applies every op against a ref, never the
+ * render-time model, so an await-resuming op can't revert a concurrent
+ * divider drag. */
+export function usePaneTree<T>(initial: PaneModel<T> | (() => PaneModel<T>)): UsePaneTree<T> {
+  const [model, setState] = useState(initial);
+  const ref = useRef(model);
+
+  const apply = (next: PaneModel<T>): void => {
+    if (next === ref.current) return;
+    ref.current = next;
+    setState(next);
+  };
+
+  return {
+    model,
+    latest: () => ref.current,
+    setModel: apply,
+    split: (paneId, o, data) => apply(splitPane(ref.current, paneId, o, data)),
+    close: (paneId) => apply(closePane(ref.current, paneId)),
+    focus: (paneId) => apply(focusPane(ref.current, paneId)),
+    focusAt: (index) => apply(focusPaneAt(ref.current, index)),
+    focusNeighbor: (dir) => apply(focusNeighbor(ref.current, dir)),
+    setRatio: (splitId, ratio) => apply(setPaneRatio(ref.current, splitId, ratio)),
+    update: (paneId, fn) => apply(updatePane(ref.current, paneId, fn)),
+  };
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+export {
+  clampPaneRatio,
+  closePane,
+  emptyPanes,
+  focusNeighbor,
+  focusPane,
+  focusPaneAt,
+  migratePanes,
+  paneIdAt,
+  paneLeaves,
+  samePaneShape,
+  seedPanes,
+  setPaneRatio,
+  splitPane,
+  updatePane,
+} from "./model.ts";
+export type { PaneLeaf, PaneModel, PaneNode, PaneSplit, SplitOrientation } from "./model.ts";
+export { PaneTree, usePaneTree } from "./PaneTree.tsx";
+export type { PaneTreeProps, UsePaneTree } from "./PaneTree.tsx";

package/src/model.test.ts

@@ -0,0 +1,268 @@
+import { describe, expect, test } from "bun:test";
+import {
+  clampPaneRatio,
+  closePane,
+  emptyPanes,
+  focusNeighbor,
+  focusPane,
+  focusPaneAt,
+  migratePanes,
+  paneIdAt,
+  paneLeaves,
+  samePaneShape,
+  seedPanes,
+  setPaneRatio,
+  splitPane,
+  updatePane,
+} from "./model.ts";
+import type { PaneModel, PaneSplit } from "./model.ts";
+
+describe("clampPaneRatio", () => {
+  test("non-finite becomes 0.5, everything else clamps to [0.05, 0.95]", () => {
+    expect(clampPaneRatio(NaN)).toBe(0.5);
+    expect(clampPaneRatio(Infinity)).toBe(0.5);
+    expect(clampPaneRatio(-Infinity)).toBe(0.5);
+    expect(clampPaneRatio(-1)).toBe(0.05);
+    expect(clampPaneRatio(0)).toBe(0.05);
+    expect(clampPaneRatio(0.3)).toBe(0.3);
+    expect(clampPaneRatio(2)).toBe(0.95);
+  });
+});
+
+describe("seedPanes", () => {
+  test("empty input is the empty model", () => {
+    expect(seedPanes([])).toEqual(emptyPanes());
+  });
+
+  test("one leaf: root is that leaf, focused, nextId past it", () => {
+    const m = seedPanes(["a"]);
+    expect(m.root).toEqual({ kind: "leaf", id: "1", data: "a" });
+    expect(m.focusedId).toBe("1");
+    expect(m.nextId).toBe(2);
+  });
+
+  test("three leaves build a binary tree with all leaves in order", () => {
+    const m = seedPanes(["a", "b", "c"]);
+    expect(paneLeaves(m).map((l) => l.data)).toEqual(["a", "b", "c"]);
+    expect(m.root!.kind).toBe("split");
+  });
+
+  test("custom id function is used", () => {
+    const m = seedPanes(["a", "b"], (_d, i) => `pane-${i}`);
+    expect(paneLeaves(m).map((l) => l.id)).toEqual(["pane-0", "pane-1"]);
+  });
+
+  test("numeric custom ids advance nextId past them, so splits mint fresh ids", () => {
+    const m = seedPanes(["a", "b"], (d) => (d === "a" ? "7" : "8"));
+    expect(paneLeaves(m).map((l) => l.id)).toEqual(["7", "8"]);
+    expect((m.root as PaneSplit<string>).id).toBe("s9");
+    expect(m.nextId).toBe(10);
+    const split = splitPane(m, "7", "horizontal", "c");
+    expect(paneLeaves(split).map((l) => l.id)).toEqual(["7", "10", "8"]);
+  });
+});
+
+describe("splitPane", () => {
+  test("splits a leaf, focuses the new leaf, mints ids from nextId", () => {
+    const m0 = seedPanes(["a"]);
+    const m1 = splitPane(m0, "1", "horizontal", "b");
+    const root = m1.root as PaneSplit<string>;
+    expect(root.kind).toBe("split");
+    expect(root.id).toBe("s2");
+    expect(root.orientation).toBe("horizontal");
+    expect(root.ratio).toBe(0.5);
+    expect(paneLeaves(m1).map((l) => l.id)).toEqual(["1", "2"]);
+    expect(m1.focusedId).toBe("2");
+    expect(m1.nextId).toBe(3);
+  });
+
+  test("unknown pane id is a same-reference no-op", () => {
+    const m = seedPanes(["a"]);
+    expect(splitPane(m, "nope", "vertical", "b")).toBe(m);
+  });
+
+  test("splitting a split id is a same-reference no-op", () => {
+    const m = splitPane(seedPanes(["a"]), "1", "horizontal", "b");
+    expect(splitPane(m, "s2", "vertical", "c")).toBe(m);
+  });
+});
+
+describe("closePane", () => {
+  test("closing one of two leaves collapses the split to the sibling", () => {
+    const m1 = splitPane(seedPanes(["a"]), "1", "horizontal", "b");
+    const m2 = closePane(m1, "2");
+    expect(m2.root).toEqual({ kind: "leaf", id: "1", data: "a" });
+    expect(m2.focusedId).toBe("1");
+  });
+
+  test("closing an unfocused leaf keeps the focus", () => {
+    const m1 = splitPane(seedPanes(["a"]), "1", "horizontal", "b"); // focus 2
+    const m2 = closePane(m1, "1");
+    expect(m2.focusedId).toBe("2");
+  });
+
+  test("closing the root leaf empties the tree", () => {
+    const m = closePane(seedPanes(["a"]), "1");
+    expect(m.root).toBeUndefined();
+    expect(m.focusedId).toBe("");
+  });
+
+  test("unknown id is a same-reference no-op", () => {
+    const m = seedPanes(["a"]);
+    expect(closePane(m, "9")).toBe(m);
+  });
+
+  test("nested close replaces the parent split with the sibling subtree", () => {
+    let m = splitPane(seedPanes(["a"]), "1", "horizontal", "b"); // s2[1, 2]
+    m = splitPane(m, "2", "vertical", "c"); // s2[1, s3[2, 3]]
+    const closed = closePane(m, "3");
+    const root = closed.root as PaneSplit<string>;
+    expect(root.id).toBe("s2");
+    expect(paneLeaves(closed).map((l) => l.id)).toEqual(["1", "2"]);
+    expect(closed.focusedId).toBe("2"); // 3 was focused; sibling takes over
+  });
+});
+
+describe("focus", () => {
+  test("focusPane moves focus; already-focused is a same-reference no-op", () => {
+    const m1 = splitPane(seedPanes(["a"]), "1", "horizontal", "b");
+    const m2 = focusPane(m1, "1");
+    expect(m2.focusedId).toBe("1");
+    expect(focusPane(m2, "1")).toBe(m2);
+  });
+
+  test("focusPane on an unknown or split id is a no-op", () => {
+    const m = splitPane(seedPanes(["a"]), "1", "horizontal", "b");
+    expect(focusPane(m, "s2")).toBe(m);
+    expect(focusPane(m, "zzz")).toBe(m);
+  });
+
+  test("focusPaneAt / paneIdAt index leaves in layout order", () => {
+    let m = splitPane(seedPanes(["a"]), "1", "horizontal", "b");
+    m = splitPane(m, "2", "vertical", "c");
+    expect(paneIdAt(m, 0)).toBe("1");
+    expect(paneIdAt(m, 2)).toBe("3");
+    expect(paneIdAt(m, 3)).toBeUndefined();
+    expect(focusPaneAt(m, 0).focusedId).toBe("1");
+    expect(focusPaneAt(m, 9)).toBe(m);
+  });
+
+  test("focusNeighbor walks across the matching-axis split", () => {
+    // s2 horizontal [1, s3 vertical [2, 3]]
+    let m = splitPane(seedPanes(["a"]), "1", "horizontal", "b");
+    m = splitPane(m, "2", "vertical", "c");
+    m = focusPane(m, "1");
+    const right = focusNeighbor(m, "right");
+    expect(right.focusedId).toBe("2"); // nearest leaf along the shared edge
+    const down = focusNeighbor(right, "down");
+    expect(down.focusedId).toBe("3");
+    const up = focusNeighbor(down, "up");
+    expect(up.focusedId).toBe("2");
+    const left = focusNeighbor(up, "left");
+    expect(left.focusedId).toBe("1");
+  });
+
+  test("focusNeighbor with no neighbor on that side is a same-reference no-op", () => {
+    const m = splitPane(seedPanes(["a"]), "1", "horizontal", "b"); // focus 2
+    expect(focusNeighbor(m, "right")).toBe(m);
+    expect(focusNeighbor(m, "up")).toBe(m);
+  });
+});
+
+describe("setPaneRatio", () => {
+  test("sets the clamped ratio on the split", () => {
+    const m1 = splitPane(seedPanes(["a"]), "1", "horizontal", "b");
+    const m2 = setPaneRatio(m1, "s2", 0.3);
+    expect((m2.root as PaneSplit<string>).ratio).toBe(0.3);
+    const m3 = setPaneRatio(m2, "s2", 99);
+    expect((m3.root as PaneSplit<string>).ratio).toBe(0.95);
+  });
+
+  test("same clamped ratio is a same-reference no-op (echo guard)", () => {
+    const m1 = splitPane(seedPanes(["a"]), "1", "horizontal", "b");
+    const m2 = setPaneRatio(m1, "s2", 0.3);
+    expect(setPaneRatio(m2, "s2", 0.3)).toBe(m2);
+    expect(setPaneRatio(m2, "s2", NaN)).not.toBe(m2); // NaN clamps to 0.5
+  });
+
+  test("unknown or leaf id is a same-reference no-op", () => {
+    const m = splitPane(seedPanes(["a"]), "1", "horizontal", "b");
+    expect(setPaneRatio(m, "1", 0.3)).toBe(m);
+    expect(setPaneRatio(m, "zzz", 0.3)).toBe(m);
+  });
+});
+
+describe("updatePane", () => {
+  test("replaces leaf data; identical data is a same-reference no-op", () => {
+    const m1 = seedPanes([{ n: 1 }]);
+    const m2 = updatePane(m1, "1", (d) => ({ ...d, n: 2 }));
+    expect(paneLeaves(m2)[0]!.data).toEqual({ n: 2 });
+    expect(updatePane(m2, "1", (d) => d)).toBe(m2);
+    expect(updatePane(m2, "zzz", (d) => d)).toBe(m2);
+  });
+});
+
+describe("samePaneShape", () => {
+  test("ratio and data changes keep the shape; structure changes break it", () => {
+    const m1 = splitPane(seedPanes(["a"]), "1", "horizontal", "b");
+    const ratioChanged = setPaneRatio(m1, "s2", 0.2);
+    const dataChanged = updatePane(m1, "1", () => "z");
+    expect(samePaneShape(m1.root, ratioChanged.root)).toBe(true);
+    expect(samePaneShape(m1.root, dataChanged.root)).toBe(true);
+    expect(samePaneShape(m1.root, splitPane(m1, "2", "vertical", "c").root)).toBe(false);
+    expect(samePaneShape(m1.root, closePane(m1, "2").root)).toBe(false);
+    expect(samePaneShape(undefined, undefined)).toBe(true);
+    expect(samePaneShape(m1.root, undefined)).toBe(false);
+  });
+});
+
+describe("migratePanes", () => {
+  test("round-trips a real model through JSON", () => {
+    let m = splitPane(seedPanes(["a"]), "1", "horizontal", "b");
+    m = splitPane(m, "2", "vertical", "c");
+    m = setPaneRatio(m, "s2", 0.3);
+    const revived = migratePanes<string>(JSON.parse(JSON.stringify(m)), (d): d is string => typeof d === "string");
+    expect(revived).toEqual(m);
+  });
+
+  test("garbage input yields the empty model", () => {
+    expect(migratePanes(null)).toEqual(emptyPanes());
+    expect(migratePanes("nope")).toEqual(emptyPanes());
+    expect(migratePanes({ root: { kind: "what" } })).toEqual(emptyPanes());
+    expect(migratePanes({ root: { kind: "split", id: "s1", orientation: "diagonal", children: [] } })).toEqual(
+      emptyPanes(),
+    );
+  });
+
+  test("leaf data failing the guard rejects the whole tree", () => {
+    const bad = { root: { kind: "leaf", id: "1", data: 42 }, focusedId: "1", nextId: 2 };
+    expect(migratePanes<string>(bad, (d): d is string => typeof d === "string")).toEqual(emptyPanes());
+  });
+
+  test("ratios are clamped, focus falls back to the first leaf, nextId is recomputed", () => {
+    const raw = {
+      root: {
+        kind: "split",
+        id: "s9",
+        orientation: "horizontal",
+        ratio: 47,
+        children: [
+          { kind: "leaf", id: "4", data: "a" },
+          { kind: "leaf", id: "7", data: "b" },
+        ],
+      },
+      focusedId: "gone",
+      nextId: "bogus",
+    };
+    const m = migratePanes<string>(raw, (d): d is string => typeof d === "string");
+    expect((m.root as PaneSplit<string>).ratio).toBe(0.95);
+    expect(m.focusedId).toBe("4");
+    expect(m.nextId).toBe(10); // past s9
+  });
+
+  test("an explicitly empty root is preserved", () => {
+    const m: PaneModel<string> = migratePanes({ root: null, focusedId: "", nextId: 5 });
+    expect(m.root).toBeUndefined();
+    expect(m.nextId).toBe(5);
+  });
+});

package/src/model.ts

@@ -0,0 +1,298 @@
+// Pure split-pane tree model over the existing <paned> widget: no schema
+// change, no new widget, no ABI change. Every op returns the SAME reference
+// when nothing changed (unknown id, already focused, same clamped ratio),
+// which is what stops a native positionChanged echo from looping through a
+// render+persist cycle.
+
+export type SplitOrientation = "horizontal" | "vertical";
+
+export interface PaneLeaf<T> {
+  kind: "leaf";
+  id: string;
+  data: T;
+}
+
+export interface PaneSplit<T> {
+  kind: "split";
+  id: string;
+  orientation: SplitOrientation;
+  ratio: number;
+  children: [PaneNode<T>, PaneNode<T>];
+}
+
+export type PaneNode<T> = PaneLeaf<T> | PaneSplit<T>;
+
+export interface PaneModel<T> {
+  root: PaneNode<T> | undefined;
+  focusedId: string;
+  nextId: number;
+}
+
+/** Non-finite ratios panic a Debug/ReleaseSafe host, so this is a safety
+ * boundary, not a nicety: non-finite becomes 0.5, everything else clamps to
+ * [0.05, 0.95] so neither side collapses to an undraggable sliver. */
+export function clampPaneRatio(ratio: number): number {
+  if (!Number.isFinite(ratio)) return 0.5;
+  return Math.min(0.95, Math.max(0.05, ratio));
+}
+
+export function emptyPanes<T>(): PaneModel<T> {
+  return { root: undefined, focusedId: "", nextId: 1 };
+}
+
+/** Builds a balanced horizontal-split tree over `leaves` (even column widths
+ * via per-split ratios). Leaf ids default to "1".."n". */
+export function seedPanes<T>(leaves: readonly T[], id?: (data: T, i: number) => string): PaneModel<T> {
+  if (leaves.length === 0) return emptyPanes<T>();
+  const leafNodes: PaneLeaf<T>[] = leaves.map((data, i) => ({
+    kind: "leaf",
+    id: id ? id(data, i) : String(i + 1),
+    data,
+  }));
+  // Custom leaf ids can collide with ids minted later (`s${n}` below,
+  // `String(nextId)` in splitPane), so the counter starts past every numeric
+  // id actually issued — the same /^s?(\d+)$/ scan migratePanes uses.
+  let maxNumericId = 0;
+  for (const leaf of leafNodes) {
+    const match = /^s?(\d+)$/.exec(leaf.id);
+    if (match) maxNumericId = Math.max(maxNumericId, Number(match[1]));
+  }
+  let counter = Math.max(leaves.length, maxNumericId) + 1;
+  function build(lo: number, hi: number): PaneNode<T> {
+    if (hi - lo === 1) return leafNodes[lo]!;
+    const mid = lo + Math.ceil((hi - lo) / 2);
+    const splitId = `s${counter++}`;
+    return {
+      kind: "split",
+      id: splitId,
+      orientation: "horizontal",
+      ratio: (mid - lo) / (hi - lo),
+      children: [build(lo, mid), build(mid, hi)],
+    };
+  }
+  const root = build(0, leafNodes.length);
+  return { root, focusedId: leafNodes[0]!.id, nextId: counter };
+}
+
+function findNode<T>(node: PaneNode<T> | undefined, id: string): PaneNode<T> | undefined {
+  if (!node) return undefined;
+  if (node.id === id) return node;
+  if (node.kind === "split") return findNode(node.children[0], id) ?? findNode(node.children[1], id);
+  return undefined;
+}
+
+function firstLeaf<T>(node: PaneNode<T>): PaneLeaf<T> {
+  return node.kind === "leaf" ? node : firstLeaf(node.children[0]);
+}
+
+/** Path-copies the subtree containing `id`, applying `fn` to that node.
+ * Returns undefined when `id` is not in the tree. */
+function mapNode<T>(node: PaneNode<T>, id: string, fn: (node: PaneNode<T>) => PaneNode<T>): PaneNode<T> | undefined {
+  if (node.id === id) return fn(node);
+  if (node.kind === "leaf") return undefined;
+  const [a, b] = node.children;
+  const ma = mapNode(a, id, fn);
+  if (ma) return { ...node, children: [ma, b] };
+  const mb = mapNode(b, id, fn);
+  if (mb) return { ...node, children: [a, mb] };
+  return undefined;
+}
+
+/** Splits the leaf `paneId` in two: the existing leaf keeps side 0, the new
+ * leaf (holding `data`) takes side 1 and the focus. */
+export function splitPane<T>(
+  m: PaneModel<T>,
+  paneId: string,
+  orientation: SplitOrientation,
+  data: T,
+  id?: string,
+): PaneModel<T> {
+  const target = findNode(m.root, paneId);
+  if (!target || target.kind !== "leaf") return m;
+  const newLeafId = id ?? String(m.nextId);
+  const newLeaf: PaneLeaf<T> = { kind: "leaf", id: newLeafId, data };
+  const root = mapNode(m.root!, paneId, (leaf) => ({
+    kind: "split",
+    id: `s${m.nextId}`,
+    orientation,
+    ratio: 0.5,
+    children: [leaf, newLeaf],
+  }));
+  return { root, focusedId: newLeafId, nextId: m.nextId + 1 };
+}
+
+/** Removes the leaf `paneId`; its sibling subtree replaces the parent split.
+ * A focused close moves the focus to the sibling's first leaf. */
+export function closePane<T>(m: PaneModel<T>, paneId: string): PaneModel<T> {
+  if (!m.root) return m;
+  let sibling: PaneNode<T> | undefined;
+  // false: not in this subtree; null: this whole node was the closed leaf.
+  function removeFrom(node: PaneNode<T>): PaneNode<T> | null | false {
+    if (node.kind === "leaf") return node.id === paneId ? null : false;
+    const [a, b] = node.children;
+    const ra = removeFrom(a);
+    if (ra === null) {
+      sibling = b;
+      return b;
+    }
+    if (ra !== false) return { ...node, children: [ra, b] };
+    const rb = removeFrom(b);
+    if (rb === null) {
+      sibling = a;
+      return a;
+    }
+    if (rb !== false) return { ...node, children: [a, rb] };
+    return false;
+  }
+  const removed = removeFrom(m.root);
+  if (removed === false) return m;
+  if (removed === null) return { root: undefined, focusedId: "", nextId: m.nextId };
+  const focusedId = m.focusedId === paneId ? firstLeaf(sibling!).id : m.focusedId;
+  return { root: removed, focusedId, nextId: m.nextId };
+}
+
+export function focusPane<T>(m: PaneModel<T>, paneId: string): PaneModel<T> {
+  if (m.focusedId === paneId) return m;
+  const node = findNode(m.root, paneId);
+  if (!node || node.kind !== "leaf") return m;
+  return { ...m, focusedId: paneId };
+}
+
+export function focusPaneAt<T>(m: PaneModel<T>, index: number): PaneModel<T> {
+  const id = paneIdAt(m, index);
+  return id === undefined ? m : focusPane(m, id);
+}
+
+export function paneIdAt<T>(m: PaneModel<T>, index: number): string | undefined {
+  return paneLeaves(m)[index]?.id;
+}
+
+/** Ancestor-walking directional focus: exact for a binary tree, no layout
+ * round-trip. Finds the nearest ancestor split on the move's axis where the
+ * focused subtree sits on the departing side, then descends into the other
+ * child along the shared edge. */
+export function focusNeighbor<T>(m: PaneModel<T>, dir: "left" | "right" | "up" | "down"): PaneModel<T> {
+  if (!m.root || !m.focusedId) return m;
+  const path: PaneNode<T>[] = [];
+  function collect(node: PaneNode<T>): boolean {
+    path.push(node);
+    if (node.id === m.focusedId) return true;
+    if (node.kind === "split" && (collect(node.children[0]) || collect(node.children[1]))) return true;
+    path.pop();
+    return false;
+  }
+  if (!collect(m.root)) return m;
+  const axis: SplitOrientation = dir === "left" || dir === "right" ? "horizontal" : "vertical";
+  const forward = dir === "right" || dir === "down";
+  for (let i = path.length - 2; i >= 0; i--) {
+    const split = path[i] as PaneSplit<T>;
+    const childIndex = split.children[0] === path[i + 1] ? 0 : 1;
+    if (split.orientation !== axis || childIndex !== (forward ? 0 : 1)) continue;
+    let target = split.children[forward ? 1 : 0];
+    while (target.kind === "split") {
+      target = target.orientation === axis ? target.children[forward ? 0 : 1] : target.children[0];
+    }
+    return focusPane(m, target.id);
+  }
+  return m;
+}
+
+export function setPaneRatio<T>(m: PaneModel<T>, splitId: string, ratio: number): PaneModel<T> {
+  const node = findNode(m.root, splitId);
+  if (!node || node.kind !== "split") return m;
+  const clamped = clampPaneRatio(ratio);
+  if (clamped === node.ratio) return m;
+  const root = mapNode(m.root!, splitId, (split) => ({ ...(split as PaneSplit<T>), ratio: clamped }));
+  return { ...m, root };
+}
+
+export function updatePane<T>(m: PaneModel<T>, paneId: string, fn: (d: T) => T): PaneModel<T> {
+  const node = findNode(m.root, paneId);
+  if (!node || node.kind !== "leaf") return m;
+  const next = fn(node.data);
+  if (Object.is(next, node.data)) return m;
+  const root = mapNode(m.root!, paneId, (leaf) => ({ ...(leaf as PaneLeaf<T>), data: next }));
+  return { ...m, root };
+}
+
+/** Leaves in layout order (side 0 before side 1, depth-first). */
+export function paneLeaves<T>(m: PaneModel<T>): PaneLeaf<T>[] {
+  const out: PaneLeaf<T>[] = [];
+  function walk(node: PaneNode<T> | undefined): void {
+    if (!node) return;
+    if (node.kind === "leaf") out.push(node);
+    else {
+      walk(node.children[0]);
+      walk(node.children[1]);
+    }
+  }
+  walk(m.root);
+  return out;
+}
+
+/** Structural equality: ids, kinds and orientations, ignoring ratios and leaf
+ * data. This is the "structural change" test for a persist-on-close flush. */
+export function samePaneShape<T>(a: PaneNode<T> | undefined, b: PaneNode<T> | undefined): boolean {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  if (a.kind !== b.kind || a.id !== b.id) return false;
+  if (a.kind === "leaf" || b.kind === "leaf") return true;
+  return (
+    a.orientation === b.orientation &&
+    samePaneShape(a.children[0], b.children[0]) &&
+    samePaneShape(a.children[1], b.children[1])
+  );
+}
+
+/** Rebuilds a model from persisted unknown data. Anything malformed (wrong
+ * kinds, missing ids, non-binary children, data failing `isData`) rejects the
+ * whole tree back to emptyPanes(); ratios are clamped, focus falls back to
+ * the first leaf, and nextId is recomputed past every numeric id. */
+export function migratePanes<T>(raw: unknown, isData?: (d: unknown) => d is T): PaneModel<T> {
+  if (typeof raw !== "object" || raw === null) return emptyPanes<T>();
+  const candidate = raw as { root?: unknown; focusedId?: unknown; nextId?: unknown };
+  let maxNumericId = 0;
+  function noteId(id: string): void {
+    const match = /^s?(\d+)$/.exec(id);
+    if (match) maxNumericId = Math.max(maxNumericId, Number(match[1]));
+  }
+  function node(v: unknown): PaneNode<T> | null {
+    if (typeof v !== "object" || v === null) return null;
+    const n = v as { kind?: unknown; id?: unknown };
+    if (typeof n.id !== "string" || n.id.length === 0) return null;
+    if (n.kind === "leaf") {
+      const data = (v as { data?: unknown }).data;
+      if (isData && !isData(data)) return null;
+      noteId(n.id);
+      return { kind: "leaf", id: n.id, data: data as T };
+    }
+    if (n.kind === "split") {
+      const s = v as { orientation?: unknown; ratio?: unknown; children?: unknown };
+      if (s.orientation !== "horizontal" && s.orientation !== "vertical") return null;
+      if (!Array.isArray(s.children) || s.children.length !== 2) return null;
+      const a = node(s.children[0]);
+      const b = node(s.children[1]);
+      if (!a || !b) return null;
+      noteId(n.id);
+      return {
+        kind: "split",
+        id: n.id,
+        orientation: s.orientation,
+        ratio: clampPaneRatio(typeof s.ratio === "number" ? s.ratio : 0.5),
+        children: [a, b],
+      };
+    }
+    return null;
+  }
+  const root = candidate.root === undefined || candidate.root === null ? undefined : node(candidate.root);
+  if (root === null) return emptyPanes<T>();
+  const model: PaneModel<T> = { root, focusedId: "", nextId: 1 };
+  const leaves = paneLeaves(model);
+  if (leaves.length > 0) {
+    const focused = typeof candidate.focusedId === "string" ? candidate.focusedId : "";
+    model.focusedId = leaves.some((l) => l.id === focused) ? focused : leaves[0]!.id;
+  }
+  const rawNextId = typeof candidate.nextId === "number" && Number.isInteger(candidate.nextId) ? candidate.nextId : 1;
+  model.nextId = Math.max(rawNextId, maxNumericId + 1, 1);
+  return model;
+}