15 files changed, 1211 insertions, 0 deletions
diff --git a/src/features/layout/logic/collapse.test.ts b/src/features/layout/logic/collapse.test.ts
new file mode 100644
index 0000000..77e9f3c
--- /dev/null
+++ b/src/features/layout/logic/collapse.test.ts
@@ -0,0 +1,120 @@
+import { describe, expect, it } from "vitest";
+import {
+  bootDefaultOpen,
+  createCollapseStore,
+  parsePersistedOpen,
+  SIDEBAR_OPEN_KEY,
+  WIDE_BREAKPOINT,
+} from "./collapse";
+
+function fakeStorage(): { storage: Storage; raw(key: string): string | null } {
+  const map = new Map<string, string>();
+  const storage: Storage = {
+    get length() {
+      return map.size;
+    },
+    clear: () => map.clear(),
+    getItem: (key) => map.get(key) ?? null,
+    key: () => null,
+    removeItem: (key) => map.delete(key),
+    setItem: (key, value) => void map.set(key, value),
+  };
+  return { storage, raw: (key) => map.get(key) ?? null };
+}
+
+describe("bootDefaultOpen", () => {
+  it("defaults to open on wide screens (>= 1024px) and closed on narrow ones", () => {
+    expect(bootDefaultOpen(WIDE_BREAKPOINT)).toBe(true);
+    expect(bootDefaultOpen(1440)).toBe(true);
+    expect(bootDefaultOpen(1023)).toBe(false);
+    expect(bootDefaultOpen(0)).toBe(false);
+  });
+
+  it("defaults to open when the viewport is unknown (SSR/tests)", () => {
+    expect(bootDefaultOpen(undefined)).toBe(true);
+  });
+});
+
+describe("parsePersistedOpen", () => {
+  it("accepts today's bare JSON boolean format", () => {
+    expect(parsePersistedOpen("true")).toBe(true);
+    expect(parsePersistedOpen("false")).toBe(false);
+  });
+
+  it("ignores null, malformed JSON, and non-boolean values", () => {
+    expect(parsePersistedOpen(null)).toBeNull();
+    expect(parsePersistedOpen("{")).toBeNull();
+    expect(parsePersistedOpen('"true"')).toBeNull();
+    expect(parsePersistedOpen("{}")).toBeNull();
+  });
+});
+
+describe("createCollapseStore", () => {
+  it("uses the viewport default when nothing is persisted", () => {
+    const store = createCollapseStore({ viewportWidth: 1024 });
+    expect(store.isOpen("side")).toBe(true);
+    const narrow = createCollapseStore({ viewportWidth: 800 });
+    expect(narrow.isOpen("side")).toBe(false);
+  });
+
+  it("restores the persisted boolean over the viewport default", () => {
+    const { storage } = fakeStorage();
+    storage.setItem(SIDEBAR_OPEN_KEY, "false");
+    const store = createCollapseStore({ storage, viewportWidth: 1440 });
+    expect(store.isOpen("side")).toBe(false);
+  });
+
+  it("persists toggles as today's bare JSON boolean (same key, same bytes)", () => {
+    const { storage, raw } = fakeStorage();
+    const store = createCollapseStore({ storage, viewportWidth: 1024 });
+    store.toggle("side");
+    expect(raw(SIDEBAR_OPEN_KEY)).toBe("false");
+    store.toggle("side");
+    expect(raw(SIDEBAR_OPEN_KEY)).toBe("true");
+  });
+
+  it("tracks per-node state reactively", () => {
+    const store = createCollapseStore({ viewportWidth: 1024 });
+    const seen: boolean[] = [];
+    const unsubscribe = store.subscribe((state) =>
+      seen.push(state.openByNode.side ?? state.defaultOpen),
+    );
+    try {
+      store.setOpen("side", false);
+      store.setOpen("side", true);
+    } finally {
+      unsubscribe();
+    }
+    expect(seen).toEqual([true, false, true]);
+    expect(store.isOpen("side")).toBe(true);
+  });
+
+  it("an untracked node falls back to the default", () => {
+    const store = createCollapseStore({ viewportWidth: 800 });
+    expect(store.isOpen("other")).toBe(false);
+  });
+
+  it("survives storage failures (quota errors are swallowed)", () => {
+    const broken: Storage = {
+      get length() {
+        return 0;
+      },
+      clear: () => undefined,
+      getItem: () => null,
+      key: () => null,
+      removeItem: () => undefined,
+      setItem: () => {
+        throw new Error("quota exceeded");
+      },
+    };
+    const store = createCollapseStore({ storage: broken, viewportWidth: 1024 });
+    expect(() => store.toggle("side")).not.toThrow();
+    expect(store.isOpen("side")).toBe(false);
+  });
+
+  it("works without storage (session-only chrome state)", () => {
+    const store = createCollapseStore({ viewportWidth: 1024 });
+    store.toggle("side");
+    expect(store.isOpen("side")).toBe(false);
+  });
+});
diff --git a/src/features/layout/logic/collapse.ts b/src/features/layout/logic/collapse.ts
new file mode 100644
index 0000000..28e90b4
--- /dev/null
+++ b/src/features/layout/logic/collapse.ts
@@ -0,0 +1,95 @@
+/**
+ * Collapse chrome state — the open/closed state of the tree's collapsible
+ * split children (today: the sidebar). Renderer chrome, NOT tree data
+ * (layout-00 decision 3): tree nodes merely declare `collapsible`; this store
+ * owns the per-node state, persisted device-locally.
+ *
+ * Persistence is BYTE-COMPATIBLE with today: the same `dispatch.sidebar.open`
+ * key holding a JSON boolean, defaulting to open on wide screens (>= 1024px,
+ * Tailwind `lg`). Today's UI has exactly one collapsible node, and the
+ * persisted boolean tracks the toggled node's state — identical bytes and
+ * behavior. A future with several collapsible nodes migrates the format in
+ * plan 02, not here.
+ */
+
+import { type Readable, writable } from "svelte/store";
+
+/** The localStorage key — unchanged from today (no migration). */
+export const SIDEBAR_OPEN_KEY = "dispatch.sidebar.open";
+/** Tailwind `lg`: today's boot default is open on wide screens. */
+export const WIDE_BREAKPOINT = 1024;
+
+export interface CollapseState {
+  /** Explicit per-node open state (node id → open). Absent = the default. */
+  readonly openByNode: Readonly<Record<string, boolean>>;
+  /** The boot default (persisted boolean, else viewport width >= 1024). */
+  readonly defaultOpen: boolean;
+}
+
+export interface CollapseStore extends Readable<CollapseState> {
+  /** Is the named node open? (explicit state, else the default) */
+  isOpen(nodeId: string): boolean;
+  setOpen(nodeId: string, open: boolean): void;
+  toggle(nodeId: string): void;
+}
+
+export interface CollapseStoreOptions {
+  /** Injected storage (the app store's `Storage`; undefined → session-only). */
+  readonly storage?: Storage | undefined;
+  /** Viewport width at boot (today: `window.innerWidth`). Undefined → default open. */
+  readonly viewportWidth?: number | undefined;
+  /** Storage key override (tests). Defaults to `dispatch.sidebar.open`. */
+  readonly key?: string | undefined;
+}
+
+/** The boot default: open on wide screens (narrow screens start closed). */
+export function bootDefaultOpen(viewportWidth: number | undefined): boolean {
+  if (viewportWidth === undefined) return true;
+  return viewportWidth >= WIDE_BREAKPOINT;
+}
+
+/** Parse the persisted value. Today's format is a bare JSON boolean; anything else is ignored. */
+export function parsePersistedOpen(raw: string | null): boolean | null {
+  if (raw === null) return null;
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return typeof parsed === "boolean" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function createCollapseStore(options?: CollapseStoreOptions): CollapseStore {
+  const key = options?.key ?? SIDEBAR_OPEN_KEY;
+  const storage = options?.storage;
+  const persisted = parsePersistedOpen(storage === undefined ? null : storage.getItem(key));
+  const defaultOpen = persisted ?? bootDefaultOpen(options?.viewportWidth);
+
+  let openByNode: Record<string, boolean> = {};
+  const store = writable<CollapseState>({ openByNode, defaultOpen });
+
+  function set(nodeId: string, open: boolean): void {
+    openByNode = { ...openByNode, [nodeId]: open };
+    store.set({ openByNode, defaultOpen });
+    // Persist the toggled node's state as today's bare boolean. With one
+    // collapsible node (always, today) this is exactly today's behavior.
+    if (storage !== undefined) {
+      try {
+        storage.setItem(key, JSON.stringify(open));
+      } catch {
+        // Swallow quota / write errors — persistence is best-effort.
+      }
+    }
+  }
+
+  function isOpen(nodeId: string): boolean {
+    return openByNode[nodeId] ?? defaultOpen;
+  }
+
+  return {
+    subscribe: store.subscribe,
+    isOpen,
+    setOpen: (nodeId, open) => set(nodeId, open),
+    toggle: (nodeId) => set(nodeId, !isOpen(nodeId)),
+  };
+}
diff --git a/src/features/layout/logic/marker.test.ts b/src/features/layout/logic/marker.test.ts
new file mode 100644
index 0000000..53b91b0
--- /dev/null
+++ b/src/features/layout/logic/marker.test.ts
@@ -0,0 +1,29 @@
+import type { TileMarker } from "@dispatch/layout-contract";
+import { describe, expect, it } from "vitest";
+import { markerOutline, markerStyle } from "./marker";
+
+describe("markerOutline — the diagnostic tile-border mapping", () => {
+  it("main → a 4px solid red outline (the main tile's marker)", () => {
+    expect(markerOutline("main")).toBe("4px solid red");
+  });
+
+  it("side → a 4px solid green outline (the side tile's marker)", () => {
+    expect(markerOutline("side")).toBe("4px solid green");
+  });
+
+  it("no marker → no outline (existing trees render exactly as before)", () => {
+    expect(markerOutline(undefined)).toBeUndefined();
+  });
+});
+
+describe("markerStyle — the complete inline style (outline + inset offset)", () => {
+  it("insets the outline so it draws INSIDE the tile's box (never clipped at screen edges)", () => {
+    expect(markerStyle("main")).toBe("outline: 4px solid red; outline-offset: -4px");
+    expect(markerStyle("side")).toBe("outline: 4px solid green; outline-offset: -4px");
+  });
+
+  it("no/unknown marker → NO style at all (unmarked nodes carry zero outline CSS)", () => {
+    expect(markerStyle(undefined)).toBeUndefined();
+    expect(markerStyle("purple" as unknown as TileMarker)).toBeUndefined();
+  });
+});
diff --git a/src/features/layout/logic/marker.ts b/src/features/layout/logic/marker.ts
new file mode 100644
index 0000000..46259e0
--- /dev/null
+++ b/src/features/layout/logic/marker.ts
@@ -0,0 +1,46 @@
+/**
+ * Diagnostic tile-border markers (the contract's additive `TileMarker`
+ * presentation field) → the inline outline the renderer draws. Pure
+ * decision logic — the .svelte tile components just apply the returned
+ * style value.
+ *
+ * INLINE STYLES, deliberately: a marker value arrives in TREE DATA at
+ * runtime, and Tailwind only generates classes it sees in source files — a
+ * dynamic class from tree data would silently render nothing. An outline
+ * (not a border) is used so the diagnostic draws WITHOUT changing any
+ * tile's layout/size (4px solid, clearly visible).
+ *
+ * The outline is INSET (`outline-offset: -4px`) so it draws INSIDE the
+ * tile's box: tiles span their containers edge-to-edge, so the default
+ * (outside) outline overflows the visible area and is clipped away at the
+ * screen edges. The views inside the tiles have no opaque full-bleed
+ * background, so the inset ring stays on top of the tile's content.
+ *
+ * The marker is purely presentational: unknown/absent → no outline
+ * (existing trees render exactly as before), and no other behavior is
+ * attached to it anywhere in the renderer.
+ */
+
+import type { TileMarker } from "@dispatch/layout-contract";
+
+/** The diagnostic outline style for a marker — `undefined` = draw nothing. */
+export function markerOutline(marker: TileMarker | undefined): string | undefined {
+  if (marker === "main") return "4px solid red";
+  if (marker === "side") return "4px solid green";
+  return undefined;
+}
+
+/** The inset that keeps the outline INSIDE the tile's box (see the header note). */
+export const MARKER_OUTLINE_OFFSET = "-4px";
+
+/**
+ * The COMPLETE inline style for a marked element — outline + inset offset in
+ * one declaration — or `undefined` when unmarked/unknown, so unmarked nodes
+ * carry no outline CSS at all (existing trees render exactly as before).
+ */
+export function markerStyle(marker: TileMarker | undefined): string | undefined {
+  const outline = markerOutline(marker);
+  return outline === undefined
+    ? undefined
+    : `outline: ${outline}; outline-offset: ${MARKER_OUTLINE_OFFSET}`;
+}
diff --git a/src/features/layout/logic/migration.test.ts b/src/features/layout/logic/migration.test.ts
new file mode 100644
index 0000000..9eeeda0
--- /dev/null
+++ b/src/features/layout/logic/migration.test.ts
@@ -0,0 +1,68 @@
+import { DEFAULT_LAYOUT } from "@dispatch/layout-contract";
+import { describe, expect, it } from "vitest";
+import { migrationTree, sidePanelViews, storedPanelViews } from "./migration";
+import { overlaySidePanels } from "./seed";
+
+const KNOWN = new Set(["tabs", "model", "extensions", "vision", "tasks"]);
+
+describe("storedPanelViews", () => {
+  it("parses a stored array of view ids, filtered to known views, order kept", () => {
+    expect(storedPanelViews(["vision", "junk", "tasks"], KNOWN)).toEqual(["vision", "tasks"]);
+  });
+
+  it("returns null for absent/junk/non-array values", () => {
+    expect(storedPanelViews(null, KNOWN)).toBeNull();
+    expect(storedPanelViews(undefined, KNOWN)).toBeNull();
+    expect(storedPanelViews("extensions", KNOWN)).toBeNull();
+    expect(storedPanelViews({ 0: "tabs" }, KNOWN)).toBeNull();
+  });
+
+  it("returns null when nothing stored is a known view", () => {
+    expect(storedPanelViews(["deleted-view", "another-gone"], KNOWN)).toBeNull();
+    expect(storedPanelViews([], KNOWN)).toBeNull();
+  });
+});
+
+describe("sidePanelViews", () => {
+  it("reads the default tree's side panels", () => {
+    expect(sidePanelViews(DEFAULT_LAYOUT)).toEqual(["tabs", "model"]);
+  });
+
+  it("returns null for a tree without a 'side' panels node", () => {
+    expect(sidePanelViews({ version: 1, root: { kind: "leaf", view: "chat" } })).toBeNull();
+  });
+});
+
+describe("migrationTree (§2.7 — one-way, best-effort)", () => {
+  it("imports the stored selection when the fetched tree is the untouched default seed", () => {
+    const stored = JSON.stringify(["extensions", "tasks"]);
+    const migrated = migrationTree(JSON.parse(stored), KNOWN, DEFAULT_LAYOUT);
+    expect(migrated).toEqual(overlaySidePanels(DEFAULT_LAYOUT, ["extensions", "tasks"]));
+    // The rest of the tree is untouched — only the side panels changed.
+    expect(migrated?.root).toEqual(
+      overlaySidePanels(DEFAULT_LAYOUT, ["extensions", "tasks"])?.root,
+    );
+  });
+
+  it("returns null when the key is absent / junk / has no known views (nothing to import)", () => {
+    expect(migrationTree(null, KNOWN, DEFAULT_LAYOUT)).toBeNull();
+    expect(migrationTree("junk", KNOWN, DEFAULT_LAYOUT)).toBeNull();
+    expect(migrationTree(["gone-view"], KNOWN, DEFAULT_LAYOUT)).toBeNull();
+  });
+
+  it("returns null when the provider's tree is NOT the default seed (custom layout wins)", () => {
+    const custom = overlaySidePanels(DEFAULT_LAYOUT, ["vision"]);
+    expect(migrationTree(["extensions"], KNOWN, custom)).toBeNull();
+  });
+
+  it("returns null when the fetched tree has no side panels node at all", () => {
+    expect(
+      migrationTree(["extensions"], KNOWN, { version: 1, root: { kind: "leaf", view: "chat" } }),
+    ).toBeNull();
+  });
+
+  it("a stored selection identical to the default still migrates (a harmless idempotent PUT)", () => {
+    const migrated = migrationTree(["tabs", "model"], KNOWN, DEFAULT_LAYOUT);
+    expect(migrated).toEqual(DEFAULT_LAYOUT);
+  });
+});
diff --git a/src/features/layout/logic/migration.ts b/src/features/layout/logic/migration.ts
new file mode 100644
index 0000000..e0ed6fd
--- /dev/null
+++ b/src/features/layout/logic/migration.ts
@@ -0,0 +1,76 @@
+/**
+ * localStorage → provider migration (plan 02 §2.7, D-L4; one-way, best-effort).
+ *
+ * `dispatch.sidebar.views` is retired as a source of truth: on boot WITH a
+ * provider present, if the key exists AND the fetched tree's `side` panels
+ * equal DEFAULT_LAYOUT's (the workspace still has the untouched default
+ * seed), the stored panel selection is imported once via a PUT. When the
+ * provider's tree differs from the default (e.g. a calendar provider), the
+ * workspace already has a custom layout — importing the old sidebar override
+ * would be wrong. Regardless of outcome the key is never read again (the
+ * bytes stay, but nothing consumes them).
+ *
+ * Pure decision logic: the store owns the effects (the localStorage read +
+ * the PUT); this module decides IF and WHAT.
+ */
+
+import {
+  DEFAULT_LAYOUT,
+  findById,
+  type LayoutTree,
+  type PanelsNode,
+} from "@dispatch/layout-contract";
+import { overlaySidePanels } from "./seed";
+
+/**
+ * The stored selection's usable view ids: an array of strings filtered to the
+ * known (registered) views, in stored order. null when nothing usable is
+ * stored (absent key, junk, or no known ids) — nothing to import.
+ */
+export function storedPanelViews(
+  raw: unknown,
+  knownViews: ReadonlySet<string>,
+): readonly string[] | null {
+  if (!Array.isArray(raw)) return null;
+  const known = raw.filter((v): v is string => typeof v === "string" && knownViews.has(v));
+  return known.length > 0 ? known : null;
+}
+
+/**
+ * The view ids of a tree's `"side"` panels node (the default tree's swappable
+ * sidebar stack), or null when the tree has no such node.
+ */
+export function sidePanelViews(tree: LayoutTree): readonly string[] | null {
+  const found = findById(tree, "side");
+  if (found === null || found.node.kind !== "panels") return null;
+  return (found.node as PanelsNode).panels.map((p) => p.view);
+}
+
+function samePanels(a: readonly string[], b: readonly string[]): boolean {
+  return a.length === b.length && a.every((v, i) => v === b[i]);
+}
+
+/**
+ * The one-way migration decision (§2.7): given the RAW stored value, the
+ * known view ids, and the tree fetched from the provider, return the tree to
+ * PUT once — or null when there is nothing to migrate:
+ * - the stored key holds no usable selection, or
+ * - the provider's tree is NOT the untouched default seed (its side panels
+ *   differ from DEFAULT_LAYOUT's — the workspace already has a custom layout).
+ */
+export function migrationTree(
+  storedRaw: unknown,
+  knownViews: ReadonlySet<string>,
+  fetched: LayoutTree,
+): LayoutTree | null {
+  const stored = storedPanelViews(storedRaw, knownViews);
+  if (stored === null) return null;
+  const fetchedPanels = sidePanelViews(fetched);
+  const defaultPanels = sidePanelViews(DEFAULT_LAYOUT);
+  if (fetchedPanels === null || defaultPanels === null) return null;
+  if (!samePanels(fetchedPanels, defaultPanels)) return null;
+  // Overlay the stored selection onto the fetched tree (identical to the
+  // default here by the guard above — the seed overlay keeps the rest of the
+  // tree shared, not copied).
+  return overlaySidePanels(fetched, stored);
+}
diff --git a/src/features/layout/logic/panel-keys.test.ts b/src/features/layout/logic/panel-keys.test.ts
new file mode 100644
index 0000000..b45671a
--- /dev/null
+++ b/src/features/layout/logic/panel-keys.test.ts
@@ -0,0 +1,73 @@
+import { describe, expect, it } from "vitest";
+import { initialPanelKeys, reconcilePanelKeys, swappedPanels } from "./panel-keys";
+
+describe("initialPanelKeys", () => {
+  it("numbers the panels in order and seeds past them", () => {
+    expect(initialPanelKeys(["tabs", "model"])).toEqual({
+      views: ["tabs", "model"],
+      keys: [0, 1],
+      seed: 2,
+    });
+  });
+});
+
+describe("reconcilePanelKeys", () => {
+  const start = initialPanelKeys(["tabs", "model", "usage"]); // keys 0 1 2
+
+  it("closing the MIDDLE panel drops the middle key (not the last)", () => {
+    const next = reconcilePanelKeys(start, ["tabs", "usage"]);
+    expect(next.keys).toEqual([0, 2]);
+    expect(next.seed).toBe(3);
+  });
+
+  it("adding a panel gives only the new one a fresh key", () => {
+    const next = reconcilePanelKeys(start, ["tabs", "model", "usage", "lsp"]);
+    expect(next.keys).toEqual([0, 1, 2, 3]);
+    expect(next.seed).toBe(4);
+  });
+
+  it("a dropdown swap keeps every key positional", () => {
+    const next = reconcilePanelKeys(start, ["tabs", "lsp", "usage"]);
+    expect(next.keys).toEqual([0, 1, 2]);
+  });
+
+  it("handles duplicate views and never reuses a key", () => {
+    const dup = initialPanelKeys(["a", "b", "a"]); // 0 1 2
+    const removed = reconcilePanelKeys(dup, ["a", "a"]);
+    expect(removed.keys).toEqual([0, 2]);
+    const added = reconcilePanelKeys(removed, ["a", "a", "a"]);
+    expect(added.keys).toEqual([0, 2, 3]);
+    expect(new Set(added.keys).size).toBe(3);
+  });
+
+  it("a ✕ hint picks the exact panel when identical views make it ambiguous", () => {
+    const twins = initialPanelKeys(["model", "usage", "usage"]); // 0 1 2
+    expect(reconcilePanelKeys(twins, ["model", "usage"]).keys).toEqual([0, 1]); // no hint
+    expect(reconcilePanelKeys(twins, ["model", "usage"], 1).keys).toEqual([0, 2]);
+  });
+
+  it("ignores a stale hint that does not describe the change", () => {
+    // The tree changed some other way (e.g. a remote edit) — fall back to LCS.
+    expect(reconcilePanelKeys(start, ["tabs", "model"], 0).keys).toEqual([0, 1]);
+    expect(reconcilePanelKeys(start, ["tabs", "model", "usage"], 1).keys).toEqual([0, 1, 2]);
+  });
+
+  it("an unrelated replacement of different length gets all-fresh keys", () => {
+    const next = reconcilePanelKeys(start, ["x"]);
+    expect(next.keys).toEqual([3]);
+  });
+});
+
+describe("swappedPanels", () => {
+  it("reports a surviving panel whose view changed", () => {
+    const prev = initialPanelKeys(["tabs", "model"]);
+    const next = reconcilePanelKeys(prev, ["tabs", "usage"]);
+    expect([...swappedPanels(prev, next)]).toEqual([[1, { from: "model", to: "usage" }]]);
+  });
+
+  it("does not report adds or removes", () => {
+    const prev = initialPanelKeys(["tabs", "model", "usage"]);
+    expect(swappedPanels(prev, reconcilePanelKeys(prev, ["tabs", "usage"])).size).toBe(0);
+    expect(swappedPanels(prev, reconcilePanelKeys(prev, [...prev.views, "lsp"])).size).toBe(0);
+  });
+});
diff --git a/src/features/layout/logic/panel-keys.ts b/src/features/layout/logic/panel-keys.ts
new file mode 100644
index 0000000..76a053f
--- /dev/null
+++ b/src/features/layout/logic/panel-keys.ts
@@ -0,0 +1,118 @@
+/**
+ * Stable panel keys — the PURE identity scheme behind the panel height
+ * animation.
+ *
+ * Panel leaves carry no required id, so the panels list can't be keyed by the
+ * tree. Keying by INDEX is wrong for removal: closing the middle of three
+ * panels would re-use the middle DOM node for the third view and animate the
+ * LAST panel out. This reconciles a stable numeric key per panel across tree
+ * updates, from the view ids alone:
+ *
+ *  - same length → keys stay positional (a dropdown SWAP keeps its panel —
+ *    the panel morphs its height to the new view instead of leaving).
+ *  - length changed → the longest common subsequence of view ids keeps its
+ *    keys; every unmatched new panel gets a fresh key (an ADD), every
+ *    unmatched old key disappears (a REMOVE).
+ *
+ * Zero Svelte, zero DOM.
+ */
+
+export interface PanelKeys {
+  /** View id per panel, in order. */
+  readonly views: readonly string[];
+  /** Stable key per panel, aligned with `views`. */
+  readonly keys: readonly number[];
+  /** The next fresh key. */
+  readonly seed: number;
+}
+
+/** Keys for a freshly mounted panels list. */
+export function initialPanelKeys(views: readonly string[]): PanelKeys {
+  return { views: [...views], keys: views.map((_, i) => i), seed: views.length };
+}
+
+/**
+ * Reconcile `prev` against the next view list (see the module doc).
+ *
+ * `removedIndex` is an optional HINT from a local ✕ click: when the next list
+ * is exactly `prev` minus that index, that exact panel is the one removed.
+ * Without it, closing one of two identical adjacent views is ambiguous to the
+ * subsequence match (it would drop the later one).
+ */
+export function reconcilePanelKeys(
+  prev: PanelKeys,
+  nextViews: readonly string[],
+  removedIndex?: number,
+): PanelKeys {
+  if (removedIndex !== undefined && isRemovalAt(prev.views, nextViews, removedIndex)) {
+    return {
+      views: [...nextViews],
+      keys: prev.keys.filter((_, i) => i !== removedIndex),
+      seed: prev.seed,
+    };
+  }
+  if (nextViews.length === prev.views.length) {
+    return { views: [...nextViews], keys: [...prev.keys], seed: prev.seed };
+  }
+  const matched = lcsMatch(prev.views, nextViews);
+  let seed = prev.seed;
+  const keys = nextViews.map((_, j) => {
+    const i = matched.get(j);
+    if (i !== undefined) return prev.keys[i] ?? seed++;
+    return seed++;
+  });
+  return { views: [...nextViews], keys, seed };
+}
+
+/**
+ * The views whose panel SURVIVED but now mounts a different view (a swap):
+ * key → { from, to }. Adds/removes are not swaps.
+ */
+export function swappedPanels(
+  prev: PanelKeys,
+  next: PanelKeys,
+): Map<number, { from: string; to: string }> {
+  const before = new Map(prev.keys.map((k, i) => [k, prev.views[i] ?? ""]));
+  const out = new Map<number, { from: string; to: string }>();
+  next.keys.forEach((k, i) => {
+    const from = before.get(k);
+    const to = next.views[i] ?? "";
+    if (from !== undefined && from !== to) out.set(k, { from, to });
+  });
+  return out;
+}
+
+function isRemovalAt(prev: readonly string[], next: readonly string[], index: number): boolean {
+  if (index < 0 || index >= prev.length || next.length !== prev.length - 1) return false;
+  return next.every((v, j) => v === prev[j < index ? j : j + 1]);
+}
+
+/** LCS alignment: next index → prev index for every matched element. */
+function lcsMatch(a: readonly string[], b: readonly string[]): Map<number, number> {
+  const n = a.length;
+  const m = b.length;
+  // dp[i][j] = LCS length of a[i..] and b[j..]
+  const dp: number[][] = Array.from({ length: n + 1 }, () => new Array<number>(m + 1).fill(0));
+  for (let i = n - 1; i >= 0; i--) {
+    for (let j = m - 1; j >= 0; j--) {
+      const row = dp[i] as number[];
+      const below = dp[i + 1] as number[];
+      row[j] = a[i] === b[j] ? (below[j + 1] ?? 0) + 1 : Math.max(below[j] ?? 0, row[j + 1] ?? 0);
+    }
+  }
+  const out = new Map<number, number>();
+  let i = 0;
+  let j = 0;
+  while (i < n && j < m) {
+    if (a[i] === b[j]) {
+      out.set(j, i);
+      i++;
+      j++;
+    } else if ((dp[i + 1]?.[j] ?? 0) >= (dp[i]?.[j + 1] ?? 0)) {
+      i++;
+    } else {
+      j++;
+    }
+  }
+  return out;
+}
diff --git a/src/features/layout/logic/panels-edit.test.ts b/src/features/layout/logic/panels-edit.test.ts
new file mode 100644
index 0000000..b4c3099
--- /dev/null
+++ b/src/features/layout/logic/panels-edit.test.ts
@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { addPanelOp, firstPanelView, removePanelOp, swapPanelOp } from "./panels-edit";
+
+describe("panel edit → op mapping", () => {
+  it("maps a dropdown swap to a replaceView on the panel leaf's path", () => {
+    expect(swapPanelOp([1], 2, "model")).toEqual({
+      type: "replaceView",
+      target: [1, 2],
+      view: "model",
+    });
+  });
+
+  it("maps the + button to an append insertPanel", () => {
+    expect(addPanelOp(["titlebar"], "tasks")).toEqual({
+      type: "insertPanel",
+      panels: ["titlebar"],
+      view: "tasks",
+    });
+  });
+
+  it("maps the ✕ button to a removeNode on the panel leaf's path", () => {
+    expect(removePanelOp([1], 0)).toEqual({ type: "removeNode", target: [1, 0] });
+  });
+
+  it("the + button pre-selects the first eligible view (or null when none)", () => {
+    expect(firstPanelView([{ id: "tabs" }, { id: "model" }])).toBe("tabs");
+    expect(firstPanelView([])).toBeNull();
+  });
+});
diff --git a/src/features/layout/logic/panels-edit.ts b/src/features/layout/logic/panels-edit.ts
new file mode 100644
index 0000000..8a56859
--- /dev/null
+++ b/src/features/layout/logic/panels-edit.ts
@@ -0,0 +1,33 @@
+/**
+ * Panel-edit → tree-op mapping: the pure decision logic behind TilePanels'
+ * dropdown swap / add / remove buttons. The component builds the ops; the
+ * renderer's owner (TileRoot → onTreeChange) applies them. Zero Svelte, zero
+ * DOM.
+ */
+
+import type { LayoutOp, Path } from "@dispatch/layout-contract";
+
+/** Swap the view a panel leaf mounts (panel `index` of the panels node at `path`). */
+export function swapPanelOp(path: Path, index: number, view: string): LayoutOp {
+  return { type: "replaceView", target: [...path, index], view };
+}
+
+/** Add a panel mounting `view` (appended to the panels node at `path`). */
+export function addPanelOp(path: Path, view: string): LayoutOp {
+  return { type: "insertPanel", panels: path, view };
+}
+
+/** Remove the panel at `index` from the panels node at `path`. */
+export function removePanelOp(path: Path, index: number): LayoutOp {
+  return { type: "removeNode", target: [...path, index] };
+}
+
+/**
+ * The view a new panel starts with. The tree schema has no "empty panel"
+ * state (a leaf's `view` is required — today's "Select a view" placeholder has
+ * no tree representation), so the + button pre-selects the first panel-eligible
+ * view. Returns null when nothing is eligible (the + button hides).
+ */
+export function firstPanelView(views: readonly { readonly id: string }[]): string | null {
+  return views[0]?.id ?? null;
+}
diff --git a/src/features/layout/logic/registry.test.ts b/src/features/layout/logic/registry.test.ts
new file mode 100644
index 0000000..e5e947c
--- /dev/null
+++ b/src/features/layout/logic/registry.test.ts
@@ -0,0 +1,148 @@
+import type { Component } from "svelte";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  getView,
+  listPanelViews,
+  listViews,
+  registerPluginView,
+  registerView,
+  unregisterView,
+  unregisterViewsByPlugin,
+  type ViewRegistration,
+  viewRegistry,
+} from "./registry";
+
+const fakeComponent: Component = () => {
+  throw new Error("fixture component should never be constructed");
+};
+
+function registration(overrides?: Partial<ViewRegistration>): ViewRegistration {
+  return { id: "test-view", label: "Test View", component: fakeComponent, ...overrides };
+}
+
+const registeredIds = (): string[] => listViews().map((v) => v.id);
+
+afterEach(() => {
+  for (const id of registeredIds()) unregisterView(id);
+});
+
+describe("view registry", () => {
+  it("registers a view and exposes it via getView/listViews", () => {
+    registerView(registration());
+    expect(getView("test-view")?.label).toBe("Test View");
+    expect(registeredIds()).toContain("test-view");
+  });
+
+  it("throws loudly on a duplicate id", () => {
+    registerView(registration());
+    expect(() => registerView(registration({ label: "Other" }))).toThrow(/duplicate view id/);
+  });
+
+  it("normalizes panelEligible to true by default and respects false", () => {
+    registerView(registration({ id: "a" }));
+    registerView(registration({ id: "b", panelEligible: false }));
+    expect(getView("a")?.panelEligible).toBe(true);
+    expect(getView("b")?.panelEligible).toBe(false);
+    expect(listPanelViews().map((v) => v.id)).toContain("a");
+    expect(listPanelViews().map((v) => v.id)).not.toContain("b");
+  });
+
+  it("keeps pluginId when given", () => {
+    registerView(registration({ id: "plugin-view", pluginId: "my-plugin" }));
+    expect(getView("plugin-view")?.pluginId).toBe("my-plugin");
+  });
+
+  it("unregisterView removes the view (idempotent for unknown ids)", () => {
+    registerView(registration({ id: "gone" }));
+    unregisterView("gone");
+    expect(getView("gone")).toBeUndefined();
+    expect(() => unregisterView("never-registered")).not.toThrow();
+  });
+
+  it("is reactive: subscribers see registrations and unregistrations", () => {
+    const seen: string[][] = [];
+    const unsubscribe = viewRegistry.subscribe((views) => seen.push(views.map((v) => v.id)));
+    try {
+      registerView(registration({ id: "reactive-a" }));
+      registerView(registration({ id: "reactive-b" }));
+      unregisterView("reactive-a");
+    } finally {
+      unsubscribe();
+    }
+    expect(seen[0]).toEqual([]);
+    expect(seen.at(-1)).toEqual(["reactive-b"]);
+  });
+
+  it("preserves registration order in listViews", () => {
+    registerView(registration({ id: "z-first" }));
+    registerView(registration({ id: "a-second" }));
+    const ids = registeredIds();
+    expect(ids.indexOf("z-first")).toBeLessThan(ids.indexOf("a-second"));
+  });
+});
+
+// ── Plugin-view registration (plan 03) — forced attribution + the sweep ─────
+
+describe("registerPluginView / unregisterViewsByPlugin (plan 03)", () => {
+  it("forces the importing plugin's pluginId attribution", () => {
+    const dispose = registerPluginView(
+      { id: "abi-view", label: "ABI View", component: fakeComponent },
+      "my-plugin",
+    );
+    expect(getView("abi-view")?.pluginId).toBe("my-plugin");
+    dispose();
+    expect(getView("abi-view")).toBeUndefined();
+  });
+
+  it("returns a working per-view disposer (the plugin deactivate contract)", () => {
+    const dispose = registerPluginView(
+      { id: "abi-view-2", label: "ABI View", component: fakeComponent },
+      "my-plugin",
+    );
+    dispose();
+    dispose(); // idempotent
+    expect(getView("abi-view-2")).toBeUndefined();
+  });
+
+  it("the sweep removes exactly that plugin's views (registry attribution)", () => {
+    registerPluginView({ id: "p1-a", label: "A", component: fakeComponent }, "plugin-1");
+    registerPluginView({ id: "p1-b", label: "B", component: fakeComponent }, "plugin-1");
+    registerPluginView({ id: "p2-a", label: "C", component: fakeComponent }, "plugin-2");
+    registerView(registration({ id: "builtin" })); // no pluginId — never swept
+
+    unregisterViewsByPlugin("plugin-1");
+    expect(getView("p1-a")).toBeUndefined();
+    expect(getView("p1-b")).toBeUndefined();
+    expect(getView("p2-a")).not.toBeUndefined();
+    expect(getView("builtin")).not.toBeUndefined();
+
+    unregisterViewsByPlugin("plugin-2");
+    expect(getView("p2-a")).toBeUndefined();
+    expect(getView("builtin")).not.toBeUndefined();
+  });
+
+  it("the sweep is idempotent and a no-op for an unknown plugin", () => {
+    unregisterViewsByPlugin("nobody");
+    registerPluginView({ id: "p3-a", label: "A", component: fakeComponent }, "plugin-3");
+    unregisterViewsByPlugin("plugin-3");
+    expect(() => unregisterViewsByPlugin("plugin-3")).not.toThrow();
+  });
+
+  it("a duplicate id from a plugin throws LOUDLY (the driver marks it failed)", () => {
+    registerView(registration({ id: "taken" }));
+    expect(() =>
+      registerPluginView({ id: "taken", label: "Taken", component: fakeComponent }, "my-plugin"),
+    ).toThrow(/duplicate view id/);
+  });
+
+  it("sweep removals are visible to registry subscribers (reactive)", () => {
+    const seen: string[][] = [];
+    const unsubscribe = viewRegistry.subscribe((views) => {
+      seen.push(views.map((v) => v.id));
+    });
+    registerPluginView({ id: "reactive", label: "R", component: fakeComponent }, "p");
+    unregisterViewsByPlugin("p");
+    unsubscribe();
+    expect(seen.at(-1)).not.toContain("reactive");
+  });
+});
diff --git a/src/features/layout/logic/registry.ts b/src/features/layout/logic/registry.ts
new file mode 100644
index 0000000..bcd49e0
--- /dev/null
+++ b/src/features/layout/logic/registry.ts
@@ -0,0 +1,139 @@
+/**
+ * The view registry — the map from view id → component that tile leaves mount.
+ *
+ * Every view the renderer can place (the sidebar views + chat / composer /
+ * message-queue today; plugin views from plan 03 later) registers here. The
+ * registry is REACTIVE (a Svelte store): plan 03's late registrations re-render
+ * open dropdowns, and the tree renderer resolves leaves through it per render.
+ *
+ * An unknown view id in a leaf is NEVER a crash — backend-owned trees (plan 02)
+ * can name views a given client lacks; the renderer shows a fallback tile.
+ *
+ * This module holds a small amount of reactive state by design (the plan places
+ * the registry in `logic/` with Svelte-store reactivity). It is NOT decision
+ * logic — no DOM, no effects.
+ */
+
+import type { Component } from "svelte";
+import { type Readable, writable } from "svelte/store";
+
+/**
+ * The props type of a registered view component. The composition root hands
+ * every wrapper its `ports` through this bag (see `src/app/view-ports.ts`);
+ * fixture/generic components may ignore it.
+ *
+ * The registry is a HETEROGENEOUS component bag (the plan types it `Component`
+ * outright), so its props are opaque `Record<string, any>` — the wrappers
+ * re-narrow to their concrete props at the composition-root seam.
+ */
+export type ViewComponent =
+  // biome-ignore lint/suspicious/noExplicitAny: opaque props of a heterogeneous component bag
+  Component<Record<string, any>>;
+
+export interface ViewRegistration {
+  /** Registry id — the same id a leaf's `view` field names. */
+  readonly id: string;
+  /** Human label shown in panel dropdowns. */
+  readonly label: string;
+  /** Svelte 5 component, already props-wired (see `src/app/register-views.ts`). */
+  readonly component: ViewComponent;
+  /** Whether the view may appear in panel dropdowns (default true). */
+  readonly panelEligible?: boolean;
+  /** The plugin that contributed the view (plan 03 requires it for those). */
+  readonly pluginId?: string;
+}
+
+/** A registered view with `panelEligible` normalized (default true). */
+export interface RegisteredView {
+  readonly id: string;
+  readonly label: string;
+  readonly component: ViewComponent;
+  readonly panelEligible: boolean;
+  readonly pluginId: string | undefined;
+}
+
+const byId = new Map<string, RegisteredView>();
+const store = writable<readonly RegisteredView[]>([]);
+
+function publish(): void {
+  store.set([...byId.values()]);
+}
+
+/**
+ * Register a view. A duplicate id throws LOUDLY at dev time — two components
+ * claiming one id is a composition-root bug, never a runtime fallback case.
+ */
+export function registerView(registration: ViewRegistration): void {
+  if (byId.has(registration.id)) {
+    throw new Error(`registerView: duplicate view id "${registration.id}"`);
+  }
+  byId.set(registration.id, {
+    id: registration.id,
+    label: registration.label,
+    component: registration.component,
+    panelEligible: registration.panelEligible ?? true,
+    pluginId: registration.pluginId,
+  });
+  publish();
+}
+
+/** Remove a view. Idempotent (removing an unknown id is a no-op). */
+export function unregisterView(id: string): void {
+  if (byId.delete(id)) publish();
+}
+
+/**
+ * Register a PLUGIN view (plan 03) — the ABI-facing registration: the
+ * `pluginId` attribution is FORCED to the importing plugin (plugins cannot
+ * attribute views to another plugin or to no plugin), which is what makes
+ * `unregisterViewsByPlugin`'s unload sweep exact. Returns the per-view
+ * disposer (the plugin's deactivate contract). A duplicate id throws
+ * LOUDLY — the driver catches it and marks the plugin's FE half failed.
+ */
+export function registerPluginView(
+  registration: Omit<ViewRegistration, "pluginId">,
+  pluginId: string,
+): () => void {
+  registerView({ ...registration, pluginId });
+  return () => unregisterView(registration.id);
+}
+
+/**
+ * Remove every view attributed to one plugin (the plan-03 unload sweep).
+ * Idempotent; the reactive registry re-renders open dropdowns, and tiles
+ * holding removed views fall back to `FallbackTile` (never a crash).
+ */
+export function unregisterViewsByPlugin(pluginId: string): void {
+  let changed = false;
+  for (const [id, view] of byId) {
+    if (view.pluginId === pluginId) {
+      byId.delete(id);
+      changed = true;
+    }
+  }
+  if (changed) publish();
+}
+
+/** Look a view up by id (undefined → the renderer shows its fallback tile). */
+export function getView(id: string): RegisteredView | undefined {
+  return byId.get(id);
+}
+
+/** All registered views, in registration order (snapshot). */
+export function listViews(): readonly RegisteredView[] {
+  return [...byId.values()];
+}
+
+/** The panel-eligible subset (`panelEligible: true`) — panel dropdown options. */
+export function listPanelViews(): readonly RegisteredView[] {
+  return listViews().filter((v) => v.panelEligible);
+}
+
+/**
+ * Reactive registry contents (registration order). Subscribe in components —
+ * e.g. `$viewRegistry` in a panel dropdown — so late registrations (plan 03)
+ * re-render open dropdowns.
+ */
+export const viewRegistry: Readable<readonly RegisteredView[]> = {
+  subscribe: store.subscribe,
+};
diff --git a/src/features/layout/logic/seed.test.ts b/src/features/layout/logic/seed.test.ts
new file mode 100644
index 0000000..dfe166a
--- /dev/null
+++ b/src/features/layout/logic/seed.test.ts
@@ -0,0 +1,99 @@
+import { DEFAULT_LAYOUT, type LayoutTree, type SplitNode } from "@dispatch/layout-contract";
+import { describe, expect, it } from "vitest";
+import { DEFAULT_PANEL_VIEWS, overlaySidePanels, seedLayout } from "./seed";
+import { firstCollapsibleNodeId, firstPanelsNode } from "./tree-query";
+
+function sideViews(tree: LayoutTree): string[] {
+  const root = tree.root as SplitNode;
+  const side = root.children[1]?.node;
+  return side?.kind === "panels" ? side.panels.map((p) => p.view) : [];
+}
+
+describe("seedLayout", () => {
+  it("uses the default panels when nothing is stored", () => {
+    const tree = seedLayout(null, ["tabs", "model", "settings"]);
+    expect(sideViews(tree)).toEqual(DEFAULT_PANEL_VIEWS);
+  });
+
+  it("overlays the stored selection, dropping unknown/removed kinds", () => {
+    const tree = seedLayout(
+      ["extensions", "ghost-view", "model"],
+      ["tabs", "model", "extensions", "settings"],
+    );
+    expect(sideViews(tree)).toEqual(["extensions", "model"]);
+  });
+
+  it("falls back to the defaults when the stored selection is all-unknown or empty", () => {
+    expect(sideViews(seedLayout(["ghost"], ["tabs", "model"]))).toEqual(["tabs", "model"]);
+    expect(sideViews(seedLayout([], ["tabs", "model"]))).toEqual(["tabs", "model"]);
+  });
+
+  it("falls back to the defaults when the stored value is not a string array", () => {
+    expect(sideViews(seedLayout("junk", ["tabs", "model"]))).toEqual(["tabs", "model"]);
+    expect(sideViews(seedLayout([42], ["tabs", "model"]))).toEqual(["tabs", "model"]);
+    expect(sideViews(seedLayout({ a: 1 }, ["tabs", "model"]))).toEqual(["tabs", "model"]);
+  });
+
+  it("preserves the default tree's ids and the titlebar-unset invariant", () => {
+    const tree = seedLayout(["model"], ["tabs", "model"]);
+    expect((tree.root as SplitNode).id).toBe("root");
+    expect(tree.titlebar).toBeUndefined();
+  });
+});
+
+describe("overlaySidePanels", () => {
+  it("replaces only the side panels of the given base tree", () => {
+    const tree = overlaySidePanels(DEFAULT_LAYOUT, ["settings", "tasks"]);
+    expect(sideViews(tree)).toEqual(["settings", "tasks"]);
+    // The rest of the tree is untouched.
+    expect((tree.root as SplitNode).children[0]?.node).toEqual(
+      (DEFAULT_LAYOUT.root as SplitNode).children[0]?.node,
+    );
+  });
+});
+
+describe("tree queries", () => {
+  it("firstPanelsNode finds the side panels with its path", () => {
+    const tree = seedLayout(["model"], ["tabs", "model"]);
+    const found = firstPanelsNode(tree);
+    expect(found?.path).toEqual([1]);
+    expect(found?.node.panels.map((p) => p.view)).toEqual(["model"]);
+  });
+
+  it("firstCollapsibleNodeId returns the default tree's side node id", () => {
+    expect(firstCollapsibleNodeId(DEFAULT_LAYOUT)).toBe("side");
+  });
+
+  it("firstCollapsibleNodeId falls back to a path key when the node has no id", () => {
+    const tree: LayoutTree = {
+      version: 1,
+      root: {
+        kind: "split",
+        dir: "row",
+        children: [
+          { size: 1, node: { kind: "leaf", view: "chat" } },
+          {
+            size: 0,
+            basis: 320,
+            collapsible: true,
+            node: { kind: "panels", panels: [{ kind: "leaf", view: "tabs" }] },
+          },
+        ],
+      },
+    };
+    // The collapsible child sits at root path index 1 → key "1".
+    expect(firstCollapsibleNodeId(tree)).toBe("1");
+  });
+
+  it("firstCollapsibleNodeId returns null when nothing is collapsible", () => {
+    const tree: LayoutTree = {
+      version: 1,
+      root: {
+        kind: "split",
+        dir: "row",
+        children: [{ size: 1, node: { kind: "leaf", view: "chat" } }],
+      },
+    };
+    expect(firstCollapsibleNodeId(tree)).toBeNull();
+  });
+});
diff --git a/src/features/layout/logic/seed.ts b/src/features/layout/logic/seed.ts
new file mode 100644
index 0000000..7cd0ba3
--- /dev/null
+++ b/src/features/layout/logic/seed.ts
@@ -0,0 +1,78 @@
+/**
+ * Boot-time tree seeding: the default layout with today's sidebar selection
+ * overlaid from localStorage. Byte-compatible with today's boot behavior
+ * (`dispatch.sidebar.views` read; unknown/removed kinds dropped — the tree
+ * schema has no "unknown view" panel state, so a stale id is skipped exactly
+ * like a view that no longer exists).
+ */
+
+import {
+  DEFAULT_LAYOUT,
+  findById,
+  type LayoutNode,
+  type LayoutTree,
+  type LeafNode,
+  type PanelsNode,
+  type Path,
+} from "@dispatch/layout-contract";
+
+/**
+ * Today's default sidebar selection (the moved-from-top tab bar + the model
+ * controls) — the fallback when nothing (or nothing valid) is stored.
+ */
+export const DEFAULT_PANEL_VIEWS: readonly string[] = ["tabs", "model"];
+
+/**
+ * Seed a tree from DEFAULT_LAYOUT with `storedViews` (the parsed
+ * `dispatch.sidebar.views` value, or null when absent) overlaid onto the
+ * default tree's panels node.
+ *
+ * - null / non-array / array without any known view → the defaults.
+ * - Known views are kept in the stored order; unknown ids are dropped.
+ */
+export function seedLayout(storedViews: unknown, panelViewIds: readonly string[]): LayoutTree {
+  const known = new Set(panelViewIds);
+  const stored = Array.isArray(storedViews)
+    ? storedViews.filter((v): v is string => typeof v === "string")
+    : [];
+  const panels = stored.filter((v) => known.has(v));
+  const selected = panels.length > 0 ? panels : DEFAULT_PANEL_VIEWS.filter((v) => known.has(v));
+  return overlaySidePanels(DEFAULT_LAYOUT, selected);
+}
+
+/**
+ * A NEW tree: `base` with its `"side"` panels node replaced by leaves mounting
+ * `views` (in order). Targets the panels node by id (falls back to no-op when
+ * the base has none); the rest of the tree is shared, not copied.
+ */
+export function overlaySidePanels(base: LayoutTree, views: readonly string[]): LayoutTree {
+  const found = findById(base, "side");
+  if (found === null || found.node.kind !== "panels") return base;
+  const panels: readonly LeafNode[] = views.map((view) => ({ kind: "leaf", view }));
+  const next: PanelsNode = { ...found.node, panels };
+  return { version: 1, root: replaceChild(base.root, found.path, next) };
+}
+
+/** Rebuild the node at `path` (immutably); the replacement must be a panels node. */
+function replaceChild(node: LayoutNode, path: Path, replacement: PanelsNode): LayoutNode {
+  if (path.length === 0) return replacement;
+  const [head, ...rest] = path;
+  if (typeof head !== "number") return node;
+  if (node.kind === "split") {
+    return {
+      ...node,
+      children: node.children.map((child, i) =>
+        i === head ? { ...child, node: replaceChild(child.node, rest, replacement) } : child,
+      ),
+    };
+  }
+  if (node.kind === "stack") {
+    return {
+      ...node,
+      children: node.children.map((child, i) =>
+        i === head ? { ...child, node: replaceChild(child.node, rest, replacement) } : child,
+      ),
+    };
+  }
+  return node;
+}
diff --git a/src/features/layout/logic/tree-query.ts b/src/features/layout/logic/tree-query.ts
new file mode 100644
index 0000000..aa8dfe9
--- /dev/null
+++ b/src/features/layout/logic/tree-query.ts
@@ -0,0 +1,60 @@
+/**
+ * Tree queries the chrome needs — pure walks over the layout tree.
+ */
+
+import type { LayoutNode, LayoutTree, PanelsNode, Path } from "@dispatch/layout-contract";
+
+/** The first panels node in the tree (the panel-selection owner), if any. */
+export function firstPanelsNode(tree: LayoutTree): { node: PanelsNode; path: Path } | null {
+  const seen: { node: PanelsNode; path: Path }[] = [];
+  const visit = (node: LayoutNode, path: Path): void => {
+    if (seen.length > 0) return;
+    if (node.kind === "panels") {
+      seen.push({ node, path });
+      return;
+    }
+    const kids: readonly LayoutNode[] =
+      node.kind === "split"
+        ? node.children.map((c) => c.node)
+        : node.kind === "stack"
+          ? node.children.map((c) => c.node)
+          : [];
+    for (const [i, child] of kids.entries()) visit(child, [...path, i]);
+  };
+  visit(tree.root, []);
+  return seen[0] ?? null;
+}
+
+/**
+ * The node id of the tree's FIRST collapsible split child — the one the chrome
+ * top bar's toggle reads/writes (`findById("side")` on the default tree;
+ * generically the first collapsible child, root-first then titlebar). Falls
+ * back to a path-derived key when the child's node has no id. Null → the tree
+ * has nothing collapsible (the toggle button hides).
+ */
+export function firstCollapsibleNodeId(tree: LayoutTree): string | null {
+  const visit = (node: LayoutNode, path: Path): string | null => {
+    if (node.kind === "split") {
+      for (const [i, child] of node.children.entries()) {
+        if (!child.collapsible) continue;
+        if (child.node.id !== undefined) return child.node.id;
+        return [...path, i].map((s) => String(s)).join(":");
+      }
+    }
+    const kids: readonly LayoutNode[] =
+      node.kind === "split"
+        ? node.children.map((c) => c.node)
+        : node.kind === "stack"
+          ? node.children.map((c) => c.node)
+          : [];
+    for (const [i, child] of kids.entries()) {
+      const found = visit(child, [...path, i]);
+      if (found !== null) return found;
+    }
+    return null;
+  };
+  const inRoot = visit(tree.root, []);
+  if (inRoot !== null) return inRoot;
+  if (tree.titlebar !== undefined) return visit(tree.titlebar, ["titlebar"]);
+  return null;
+}