@mosetta/content 0.0.0-stage → 0.0.10

package/src/editing.ts

@@ -0,0 +1,1304 @@
+// The client-side EDITING SESSION (stage 5): shared state of "which page draft is
+// open, what's selected, what changed" for the workbench's smart widgets. Lives HERE because it
+// operates purely on content-model documents — zero react, plain listeners; widgets subscribe via
+// useSyncExternalStore. The session never touches the content API: it is the single source of the
+// draft being edited, and WRITING that draft out belongs to a service alongside it (the editor's
+// EditingAutosave) — not to this class, and not to whichever panel happens to be open.
+import { DiContainer, SingleDiToken } from '@mosetta/di';
+import {
+  ContentKind,
+  DEFAULT_SLOT,
+  IBlueprintNodeDoc,
+  IPageAction,
+  IPageDoc,
+  PAGE_HISTORY_LIMIT,
+  IPageMeta,
+  IPageMetaWords,
+  IPrefabField,
+} from './model';
+import { unitOwnerOf } from './units';
+
+/**
+ * Where the next block goes, as picked in the preview: a place inside a parent's slot, at a
+ * position among that slot's children. Only slots the preview actually RENDERS can be picked —
+ * the editor learns them from the running page, not from a manifest.
+ */
+export interface IInsertionPoint {
+  readonly parentId: string;
+  readonly slot: string;
+  /** position among the children of THIS slot (children of other slots are not counted) */
+  readonly index: number;
+  /** what the place calls itself, in the preview's own relative words ("add before heading") —
+   * whoever shows the pending insert repeats these words instead of naming raw node ids */
+  readonly label?: string;
+}
+
+/** a SLOT as the selection: not a node — copy/cut act on its children, a paste lands inside it */
+export interface ISelectedSlot {
+  readonly parentId: string;
+  readonly slot: string;
+}
+
+export interface IEditingState {
+  /** what is open: a page, or a prefab — edited in a page's shape (prefabAsPage) */
+  readonly kind: ContentKind;
+  /** the open entity's name — a page's or a prefab's */
+  readonly pageName: string | null;
+  /** the DRAFT being edited (saves target it); null while a published revision is inspected */
+  readonly draftId: string | null;
+  /**
+   * The PUBLISHED (or archived) revision being INSPECTED — read-only by the content model
+   * (versions are immutable). Non-null puts the whole session in the read-only mode: the one
+   * mutation doorway refuses, so nothing dirties, nothing autosaves, and every compose affordance
+   * downstream can simply ask this field. Exclusive with `draftId` by construction.
+   */
+  readonly revision: number | null;
+  /**
+   * The draft's last PERSISTED write sequence — the optimistic-concurrency token. The working doc
+   * is not the authority on it (its own `seq` goes stale the moment editing starts): the autosave
+   * stamps `seq + 1` on what it sends, and only a landed save advances it (markSaved). A save
+   * refused with CONFLICT means someone else advanced the chain — fork or roll back.
+   */
+  readonly seq: number;
+  readonly doc: IPageDoc | null;
+  readonly selectedNodeId: string | null;
+  /**
+   * The node under the pointer in THIS session's canvas — ephemeral, never a mode: the tree wears
+   * a pale highlight for it (paler than the selection), and nothing else reacts. Hover is also
+   * what ACTIVATES a session (focus follows the pointer across canvases) — which is exactly why
+   * consumers that care about the last deliberate CHOICE (the settings panel) follow the hub's
+   * `selection` facade instead of the active one.
+   */
+  readonly hoveredNodeId: string | null;
+  /**
+   * Bumped by every deliberate selection ACT (selectNode, selectSlot, openPage) — the hub's
+   * selection anchor follows acts, not diffs: re-picking the very node already selected here
+   * must still pull the anchor back from wherever it wandered, and the ids alone cannot say so.
+   */
+  readonly selectionStamp: number;
+  /** the blue selection's OTHER shape: a slot instead of a node — exclusive with everything else */
+  readonly selectedSlot: ISelectedSlot | null;
+  /**
+   * Slots the RUNNING page declares, reported by the preview (the canvas feeds them in): the one
+   * way the tree can show EMPTY slots — the document only knows slots that hold children.
+   */
+  readonly declaredSlots: readonly ISelectedSlot[];
+  /**
+   * The node being MOVED (the tree's move mode) — its own exclusive mode, isolated from the rest
+   * by construction: entering it dissolves every selection, and any selection dissolves it. The
+   * isolation is the point — mixed modes breed emergent bugs.
+   */
+  readonly movingNodeId: string | null;
+  /**
+   * The nodes picked with Ctrl (multi-selection, the substrate of copy/paste) — a FLAT set of
+   * ids: pickedness belongs to each element, not to its place in the hierarchy. A Ctrl-click
+   * puts an element in (or takes it out) TOGETHER with its subtree, and touches nothing else —
+   * so a parent stays picked when one of its children is excluded, and a copy of "the card
+   * without this text" is expressible. Non-empty means the yellow mode, which excludes the
+   * ordinary selection and the insertion point — and they exclude it back.
+   */
+  readonly multiSelectedIds: readonly string[];
+  /** picked in the preview; absent → an insert lands at the end of the selected node */
+  readonly insertionPoint: IInsertionPoint | null;
+  /**
+   * Whether the preview is being INSPECTED: outlines drawn, clicks taken as selection. Turned off,
+   * the preview behaves like the live page — which is the only way to try a menu or a form inside
+   * it — and nothing can be composed until it is back on.
+   */
+  readonly inspecting: boolean;
+  readonly dirty: boolean;
+  /**
+   * Why the draft is not on disk, when a write was tried and refused — a code for the widget that
+   * shows it. The session carries it because "is my work saved" is a question about the session,
+   * not about whichever panel happens to be open.
+   */
+  readonly saveFailure: string | null;
+  /** bumped on every successful save — the canvas keys its preview iframe on it (refresh signal) */
+  readonly savedCount: number;
+  /**
+   * The VIEWS the author chose for reference providers, by provider name — i18n: `{ lang }`, the
+   * language being edited. Editor state, never document: forms read and write references through
+   * it, the canvas previews it. Workbench-wide by the hub (one switch for every canvas).
+   */
+  readonly views: Readonly<Record<string, unknown>>;
+}
+
+const IDLE: IEditingState = {
+  kind: 'pages', pageName: null, draftId: null, revision: null, seq: 1, doc: null, selectedNodeId: null, hoveredNodeId: null,
+  selectionStamp: 0, selectedSlot: null, declaredSlots: [], multiSelectedIds: [], insertionPoint: null,
+  movingNodeId: null, inspecting: true, dirty: false, saveFailure: null, savedCount: 0, views: {},
+};
+
+// ---- pure immutable tree ops (unit-testable without a session) ----
+
+export function findNodeDoc(root: IBlueprintNodeDoc, id: string): IBlueprintNodeDoc | null {
+  if (root.id === id) return root;
+  for (const child of root.children ?? []) {
+    const hit = findNodeDoc(child, id);
+    if (hit) return hit;
+  }
+  return null;
+}
+
+/** every id in the branch under `node`, the node itself included */
+function subtreeIds(node: IBlueprintNodeDoc): string[] {
+  return [node.id, ...(node.children ?? []).flatMap(subtreeIds)];
+}
+
+/** the picked nodes that START a region (their parent is not picked), in document order */
+function pickedRegionStarts(doc: IBlueprintNodeDoc, picked: readonly string[]): string[] {
+  const starts: string[] = [];
+  const walk = (node: IBlueprintNodeDoc, parentPicked: boolean): void => {
+    const isPicked = picked.includes(node.id);
+    if (isPicked && !parentPicked) starts.push(node.id);
+    for (const child of node.children ?? []) walk(child, isPicked);
+  };
+  for (const child of doc.children ?? []) walk(child, false);
+  return starts;
+}
+
+/** the node holding `id` among its children — null for the root itself and for unknown ids */
+function findParentNode(root: IBlueprintNodeDoc, id: string): IBlueprintNodeDoc | null {
+  for (const child of root.children ?? []) {
+    if (child.id === id) return root;
+    const deeper = findParentNode(child, id);
+    if (deeper) return deeper;
+  }
+  return null;
+}
+
+/**
+ * What a copy takes from a flat multi-selection: the PICKED FOREST. A picked node keeps only its
+ * picked children (the holes stay holes — "the card without this text"), and a picked node whose
+ * parent is NOT picked starts a top-level block of its own, however deep it sits. The document
+ * root is a page, not a block — it never enters a copy; picking it copies its picked children.
+ */
+export function pickedForest(doc: IBlueprintNodeDoc, picked: readonly string[]): IBlueprintNodeDoc[] {
+  const prune = (node: IBlueprintNodeDoc): IBlueprintNodeDoc => ({
+    ...node,
+    children: (node.children ?? []).filter((child) => picked.includes(child.id)).map(prune),
+  });
+  const roots: IBlueprintNodeDoc[] = [];
+  const walk = (node: IBlueprintNodeDoc, parentPicked: boolean): void => {
+    const isPicked = picked.includes(node.id);
+    if (isPicked && !parentPicked) roots.push(prune(node));
+    for (const child of node.children ?? []) walk(child, isPicked);
+  };
+  for (const child of doc.children ?? []) walk(child, false);
+  return roots;
+}
+
+/**
+ * Fresh identities for arriving blocks: every node gets the next `node-<n>` the document does not
+ * hold — a copy may come from this very page (ids would collide) or from another one (ids mean
+ * nothing here). Top-level blocks also shed their `slot`: the slot they were copied out of belongs
+ * to the OLD parent, and the insert stamps the new one's. Children keep theirs — their parents
+ * came along.
+ */
+export function renumberBlocks(doc: IBlueprintNodeDoc, blocks: readonly IBlueprintNodeDoc[]): IBlueprintNodeDoc[] {
+  let max = 0;
+  (function scan(node: IBlueprintNodeDoc) {
+    const match = /^node-(\d+)$/.exec(node.id);
+    if (match) max = Math.max(max, Number(match[1]));
+    for (const child of node.children ?? []) scan(child);
+  })(doc);
+  const fresh = (node: IBlueprintNodeDoc, topLevel: boolean): IBlueprintNodeDoc => {
+    max += 1;
+    const { slot, ...rest } = node;
+    return {
+      ...rest,
+      id: `node-${max}`,
+      ...(topLevel || slot === undefined ? {} : { slot }),
+      children: (node.children ?? []).map((child) => fresh(child, false)),
+    };
+  };
+  return blocks.map((block) => fresh(block, true));
+}
+
+/** replace/remove (fn → null) the node with `id`; untouched subtrees keep identity */
+function transformNode(
+  node: IBlueprintNodeDoc,
+  id: string,
+  fn: (n: IBlueprintNodeDoc) => IBlueprintNodeDoc | null,
+): IBlueprintNodeDoc | null {
+  if (node.id === id) return fn(node);
+  let changed = false;
+  const children: IBlueprintNodeDoc[] = [];
+  for (const child of node.children ?? []) {
+    const next = transformNode(child, id, fn);
+    if (next !== child) changed = true;
+    if (next) children.push(next);
+  }
+  return changed ? { ...node, children } : node;
+}
+
+/** the meta with the patch merged; an emptied field (or a flag turned off) leaves the doc */
+function mergeMeta(meta: IPageMeta, patch: Partial<IPageMeta>): IPageMeta {
+  const merged: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries({ ...meta, ...patch })) {
+    if (key === 'i18n') {
+      if (value && typeof value === 'object' && Object.keys(value).length) merged[key] = value;
+    } else if ((typeof value === 'string' && value !== '') || value === true) merged[key] = value;
+  }
+  return merged;
+}
+
+/** the meta with `lang`'s words merged in; an emptied word, then an empty language, leaves the doc */
+function mergeMetaWords(meta: IPageMeta, byLang: Readonly<Record<string, IPageMetaWords>>): IPageMeta {
+  const i18n: Record<string, IPageMetaWords> = { ...meta.i18n };
+  for (const [lang, patch] of Object.entries(byLang)) {
+    const words: Record<string, string> = {};
+    for (const [key, value] of Object.entries({ ...i18n[lang], ...patch })) {
+      if ((key === 'title' || key === 'description') && typeof value === 'string' && value !== '') words[key] = value;
+    }
+    if (Object.keys(words).length) i18n[lang] = words;
+    else delete i18n[lang];
+  }
+  return mergeMeta(meta, { i18n });
+}
+
+/** the doc with this meta; an empty meta leaves the doc */
+function withMeta(doc: IPageDoc, meta: IPageMeta): IPageDoc {
+  const { meta: old, ...rest } = doc;
+  void old;
+  return Object.keys(meta).length ? { ...rest, meta } : rest;
+}
+
+export function updateNodeSettingsInDoc(doc: IPageDoc, id: string, patch: Record<string, unknown>): IPageDoc {
+  return transformNode(doc, id, (n) => ({ ...n, settings: { ...n.settings, ...patch } })) as IPageDoc;
+}
+
+const slotOf = (node: IBlueprintNodeDoc): string => node.slot ?? DEFAULT_SLOT;
+
+/**
+ * Insert under `parentId`. Without `at` the child lands at the very end (the old behaviour, used
+ * when nothing was picked in the preview). With `at` it lands at that position WITHIN ITS SLOT:
+ * children of one slot are scattered through the array, so the index is resolved against the
+ * slot's own sequence and the array position is derived from it.
+ */
+export function insertChildInDoc(
+  doc: IPageDoc,
+  parentId: string,
+  child: IBlueprintNodeDoc,
+  at?: { slot: string; index: number },
+): IPageDoc {
+  return transformNode(doc, parentId, (n) => {
+    const children = [...(n.children ?? [])];
+    if (!at) return { ...n, children: [...children, child] };
+    const placed = at.slot === DEFAULT_SLOT ? child : { ...child, slot: at.slot };
+    const sameSlot = children.map((c, i) => ({ c, i })).filter(({ c }) => slotOf(c) === at.slot);
+    // past the last child of the slot → right after it; the slot being empty → the very end
+    const position = sameSlot[at.index]?.i
+      ?? (sameSlot.length ? sameSlot[sameSlot.length - 1].i + 1 : children.length);
+    children.splice(position, 0, placed);
+    return { ...n, children };
+  }) as IPageDoc;
+}
+
+// node-level `ssr` flag (SSR epic stage 4): true on the ROOT enables server rendering of the
+// page; false on any node opts its whole branch out (cannot be re-enabled deeper — no islands).
+// undefined removes the field (keeps stored docs free of noise).
+export function setNodeSsrInDoc(doc: IPageDoc, id: string, ssr: boolean | undefined): IPageDoc {
+  return transformNode(doc, id, (n) => {
+    const next = { ...n } as IBlueprintNodeDoc & { ssr?: boolean };
+    if (ssr === undefined) delete next.ssr;
+    else next.ssr = ssr;
+    return next;
+  }) as IPageDoc;
+}
+
+/** node-level `autoBind` flag: a provider linking new blocks' fields at once; false removes the field */
+export function setNodeAutoBindInDoc(doc: IPageDoc, id: string, on: boolean): IPageDoc {
+  return transformNode(doc, id, (n) => {
+    const next = { ...n };
+    if (on) (next as { autoBind?: boolean }).autoBind = true;
+    else delete (next as { autoBind?: boolean }).autoBind;
+    return next;
+  }) as IPageDoc;
+}
+
+export function removeNodeFromDoc(doc: IPageDoc, id: string): IPageDoc {
+  if (doc.id === id) return doc; // the root is the page itself — not removable
+  return transformNode(doc, id, () => null) as IPageDoc;
+}
+
+/**
+ * Move a node (with its whole subtree) to `index` in `parentId`'s `slot`, or refuse with null.
+ * Two traps live here. The INDEX SHIFT: the index describes the document with the moving node
+ * still in it, so it is converted to an ANCHOR (the child currently at that position) before the
+ * removal, and the anchor is re-found afterwards. The CYCLE: a target inside the moving branch
+ * disappears together with it — the parent lookup after removal is the guard, for free.
+ */
+export function moveNodeInDoc(
+  doc: IPageDoc,
+  id: string,
+  parentId: string,
+  slot: string,
+  index: number,
+): IPageDoc | null {
+  if (id === doc.id) return null; // the root is the page — it does not move
+  const moving = findNodeDoc(doc, id);
+  const parentBefore = findNodeDoc(doc, parentId);
+  if (!moving || !parentBefore) return null;
+  const anchor = (parentBefore.children ?? []).filter((child) => (child.slot ?? DEFAULT_SLOT) === slot)[index] ?? null;
+  if (anchor?.id === id) return null; // right before itself — the same place
+  const without = removeNodeFromDoc(doc, id);
+  const parentAfter = findNodeDoc(without, parentId);
+  if (!parentAfter) return null; // the target lived inside the moving branch — a cycle
+  const siblings = (parentAfter.children ?? []).filter((child) => (child.slot ?? DEFAULT_SLOT) === slot);
+  const at = anchor ? siblings.findIndex((child) => child.id === anchor.id) : siblings.length;
+  // the moving node adopts the TARGET's slot; its children keep theirs — they came along
+  const { slot: _old, ...bare } = moving;
+  return insertChildInDoc(without, parentId, bare, { slot, index: at === -1 ? siblings.length : at });
+}
+
+
+/**
+ * Record a mutation in the draft itself: `next` gets a history entry holding the action and the
+ * page as it was before, capped at PAGE_HISTORY_LIMIT (the oldest step falls off). The snapshot
+ * goes in with both stacks stripped — entries never nest. A fresh edit is the fork where the
+ * undone future becomes unreachable, so the redo list is cleared.
+ */
+export function recordAction(prev: IPageDoc, action: IPageAction, next: IPageDoc): IPageDoc {
+  const { history: _prior, redo: _undone, ...before } = prev;
+  const history = [...(prev.history ?? []), { action, before }].slice(-PAGE_HISTORY_LIMIT);
+  const { redo: _stale, ...cleanNext } = next;
+  return { ...cleanNext, history };
+}
+
+/** next `node-<n>` id not colliding with ANY existing id in the doc */
+export function nextNodeId(doc: IBlueprintNodeDoc): string {
+  let max = 0;
+  (function walk(n: IBlueprintNodeDoc) {
+    const m = /^node-(\d+)$/.exec(n.id);
+    if (m) max = Math.max(max, Number(m[1]));
+    for (const c of n.children ?? []) walk(c);
+  })(doc);
+  return `node-${max + 1}`;
+}
+
+// ---- the session ----
+
+export class EditingSession {
+  private state: IEditingState = IDLE;
+
+  private readonly listeners = new Set<() => void>();
+
+  readonly subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+
+  readonly snapshot = (): IEditingState => this.state;
+
+  private set(next: IEditingState): void {
+    this.state = next;
+    for (const listener of this.listeners) listener();
+  }
+
+  /** open a DRAFT for editing; the root starts selected (= default insertion target) */
+  openPage(pageName: string, draftId: string, doc: IPageDoc, kind: ContentKind = 'pages'): void {
+    this.set({
+      ...this.state,
+      kind,
+      pageName,
+      draftId,
+      revision: null,
+      seq: doc.seq ?? 1,
+      doc,
+      selectedNodeId: doc.id,
+      hoveredNodeId: null,
+      selectionStamp: this.state.selectionStamp + 1,
+      selectedSlot: null,
+      declaredSlots: [],
+      multiSelectedIds: [],
+      insertionPoint: null,
+      movingNodeId: null,
+      dirty: false,
+      saveFailure: null,
+      savedCount: 0,
+    });
+  }
+
+  /**
+   * Open a PUBLISHED (or archived) revision for read-only inspection. Same session, same panels —
+   * selection, hover and the preview all work — but the mutation doorway is shut (`revision`
+   * non-null), so the tree cannot change and nothing ever dirties or autosaves.
+   */
+  openRevision(pageName: string, revision: number, doc: IPageDoc, kind: ContentKind = 'pages'): void {
+    this.set({
+      ...this.state,
+      kind,
+      pageName,
+      draftId: null,
+      revision,
+      seq: 1,
+      doc,
+      selectedNodeId: doc.id,
+      hoveredNodeId: null,
+      selectionStamp: this.state.selectionStamp + 1,
+      selectedSlot: null,
+      declaredSlots: [],
+      multiSelectedIds: [],
+      insertionPoint: null,
+      movingNodeId: null,
+      dirty: false,
+      saveFailure: null,
+      savedCount: 0,
+    });
+  }
+
+  closePage(): void {
+    this.set(IDLE);
+  }
+
+  /** the ORDINARY selection — one blue node; taking it dissolves every other mode (exclusive) */
+  selectNode(id: string | null): void {
+    if (!this.state.doc) return;
+    this.set({
+      ...this.state,
+      selectedNodeId: id,
+      selectedSlot: null,
+      multiSelectedIds: [],
+      movingNodeId: null,
+      selectionStamp: this.state.selectionStamp + 1,
+    });
+  }
+
+  /** the pointer moved over a node (or off every node) — ephemeral, disturbs no mode */
+  hoverNode(id: string | null): void {
+    const { doc, hoveredNodeId } = this.state;
+    // ids the draft no longer knows (an edit landed after the frame rendered) read as "nothing";
+    // a prefab's block (`<prefabNode>/<block>`) is known while its prefab node is
+    const next = id && doc && findNodeDoc(doc, unitOwnerOf(id) ?? id) ? id : null;
+    if (next === hoveredNodeId) return;
+    this.set({ ...this.state, hoveredNodeId: next });
+  }
+
+  /**
+   * The blue selection leaves QUIETLY — no act, no stamp: a canvas surrenders its own selection
+   * when it sees the workspace's selection anchor living elsewhere (ONE blue block per
+   * workspace), and that surrender must never read as a new pick — a stamp bump here would have
+   * the anchor stolen right back by the very canvas that was told to let go.
+   */
+  retireSelection(): void {
+    const { selectedNodeId, selectedSlot } = this.state;
+    if (selectedNodeId === null && selectedSlot === null) return;
+    this.set({ ...this.state, selectedNodeId: null, selectedSlot: null });
+  }
+
+  /**
+   * The blue selection's OTHER shape: a SLOT. Not a node — what it means is its children: a copy
+   * takes them, a cut removes them (the slot itself is structure and stays), a paste lands INSIDE
+   * it, at the end. Exclusive with every other mode, like any selection.
+   */
+  selectSlot(parentId: string, slot: string): void {
+    const { doc } = this.state;
+    if (!doc || !findNodeDoc(doc, parentId)) return;
+    this.set({
+      ...this.state,
+      selectedSlot: { parentId, slot },
+      selectedNodeId: null,
+      multiSelectedIds: [],
+      insertionPoint: null,
+      movingNodeId: null,
+      selectionStamp: this.state.selectionStamp + 1,
+    });
+  }
+
+  /**
+   * A Ctrl-click: an UNPICKED element joins the set with its whole subtree; a PICKED one leaves
+   * with its subtree — and NOTHING ELSE moves. Deselecting a child does not touch its parent:
+   * pickedness is per element, and the hole left behind is exactly what a copy wants to express.
+   * The three modes are exclusive BY THE SESSION, not by the widgets: the yellow pick clears the
+   * blue selection and the pending insertion point, whoever sent it.
+   */
+  toggleMultiSelect(id: string): void {
+    const { doc, multiSelectedIds } = this.state;
+    if (!doc) return;
+    const branch = findNodeDoc(doc, id);
+    if (!branch) return;
+    const family = subtreeIds(branch);
+    const picked = multiSelectedIds.includes(id)
+      ? multiSelectedIds.filter((node) => !family.includes(node))
+      : [...multiSelectedIds, ...family.filter((node) => !multiSelectedIds.includes(node))];
+    this.set({ ...this.state, multiSelectedIds: picked, selectedNodeId: null, selectedSlot: null, insertionPoint: null, movingNodeId: null });
+  }
+
+  /**
+   * A Ctrl-click on a SLOT ROW: the slot is not a node, it is a DOOR to its children — the
+   * gesture passes through. Any child missing → all of them join (subtrees included); all of
+   * them already in → all of them leave.
+   */
+  toggleMultiSelectSlot(parentId: string, slot: string): void {
+    const { doc, multiSelectedIds } = this.state;
+    if (!doc) return;
+    const parent = findNodeDoc(doc, parentId);
+    if (!parent) return;
+    const kids = (parent.children ?? []).filter((child) => (child.slot ?? DEFAULT_SLOT) === slot);
+    if (!kids.length) return;
+    const families = kids.flatMap(subtreeIds);
+    const picked = kids.every((kid) => multiSelectedIds.includes(kid.id))
+      ? multiSelectedIds.filter((id) => !families.includes(id))
+      : [...multiSelectedIds, ...families.filter((id) => !multiSelectedIds.includes(id))];
+    this.set({ ...this.state, multiSelectedIds: picked, selectedNodeId: null, selectedSlot: null, insertionPoint: null, movingNodeId: null });
+  }
+
+  /**
+   * The preview reported what slots the running page declares. Geometry arrives on every
+   * measurement, so an unchanged list is dropped here — without waking a single subscriber.
+   */
+  setDeclaredSlots(slots: readonly ISelectedSlot[]): void {
+    const current = this.state.declaredSlots;
+    const same = slots.length === current.length
+      && slots.every((slot, i) => current[i].parentId === slot.parentId && current[i].slot === slot.slot);
+    if (same) return;
+    this.set({ ...this.state, declaredSlots: slots });
+  }
+
+  /**
+   * Enter the MOVE mode for one node (the tree's per-row button): its own exclusive mode —
+   * the isolation from every selection is deliberate, mixed modes breed emergent bugs. The
+   * root does not move; picking a place is commitMove, leaving is cancelMove (or Escape).
+   */
+  startMove(id: string): void {
+    const { doc } = this.state;
+    if (!doc || id === doc.id || !findNodeDoc(doc, id)) return;
+    if (this.state.revision !== null) return; // a read-only view offers no mode that edits
+    this.set({
+      ...this.state,
+      movingNodeId: id,
+      selectedNodeId: null,
+      selectedSlot: null,
+      multiSelectedIds: [],
+      insertionPoint: null,
+    });
+  }
+
+  cancelMove(): void {
+    if (this.state.movingNodeId === null) return;
+    this.set({ ...this.state, movingNodeId: null });
+  }
+
+  /**
+   * The purple tip was clicked: the moving node lands at `index` of `parentId`'s `slot` — one
+   * action through the one channel. A refused move (a cycle, the same place) just leaves the
+   * mode; the moved node comes out blue-selected.
+   */
+  commitMove(parentId: string, slot: string, index: number): void {
+    const { doc, movingNodeId } = this.state;
+    if (!doc || !movingNodeId) return;
+    const next = moveNodeInDoc(doc, movingNodeId, parentId, slot, index);
+    if (!next) {
+      this.set({ ...this.state, movingNodeId: null });
+      return;
+    }
+    this.mutate({ type: 'move', nodeId: movingNodeId }, next, {
+      movingNodeId: null,
+      selectedNodeId: movingNodeId,
+    });
+  }
+
+  /** the preview is handed back to the visitor, or taken back for editing */
+  setInspecting(inspecting: boolean): void {
+    this.set({ ...this.state, inspecting, ...(inspecting ? {} : { insertionPoint: null }) });
+  }
+
+  /** a "+" in the preview was pressed (or dismissed) — the next insert targets exactly this place */
+  setInsertionPoint(point: IInsertionPoint | null): void {
+    if (!this.state.doc) return;
+    if (point && this.state.revision !== null) return; // nothing can be inserted into a revision
+    // naming a place is another mode — it dissolves the others (dismissing names nothing)
+    this.set({
+      ...this.state,
+      insertionPoint: point,
+      ...(point ? { multiSelectedIds: [], selectedSlot: null, movingNodeId: null } : {}),
+    });
+  }
+
+  /**
+   * THE mutation channel: every change to the page tree passes through here, and here alone the
+   * draft learns its history — the action plus the page as it was before (recordAction). One
+   * doorway is what lets copy/paste and undo/redo manipulate edits instead of growing their own.
+   */
+  private mutate(action: IPageAction, next: IPageDoc, rest: Partial<IEditingState> = {}): void {
+    const { doc } = this.state;
+    if (!doc) return;
+    if (this.state.revision !== null) return; // an inspected revision is immutable — refuse quietly
+    const recorded = recordAction(doc, action, next);
+    this.set({
+      ...this.state,
+      ...rest,
+      doc: recorded,
+      // a node the edit removed cannot stay picked; rest may hand the set over (a paste clears it)
+      multiSelectedIds: (rest.multiSelectedIds ?? this.state.multiSelectedIds)
+        .filter((node) => findNodeDoc(recorded, node) !== null),
+      hoveredNodeId: this.state.hoveredNodeId && findNodeDoc(recorded, this.state.hoveredNodeId)
+        ? this.state.hoveredNodeId
+        : null,
+      selectedSlot: (() => {
+        const kept = rest.selectedSlot !== undefined ? rest.selectedSlot : this.state.selectedSlot;
+        return kept && findNodeDoc(recorded, kept.parentId) ? kept : null;
+      })(),
+      movingNodeId: (() => {
+        const kept = rest.movingNodeId !== undefined ? rest.movingNodeId : this.state.movingNodeId;
+        return kept && findNodeDoc(recorded, kept) ? kept : null;
+      })(),
+      dirty: true,
+    });
+  }
+
+  updateNodeSettings(id: string, patch: Record<string, unknown>): void {
+    if (!this.state.doc) return;
+    this.mutate({ type: 'settings', nodeId: id }, updateNodeSettingsInDoc(this.state.doc, id, patch));
+  }
+
+  /**
+   * Several nodes' settings in ONE undoable step — a write through a reference touches the
+   * provider, binding a field touches the provider and the consumer, and the author made one edit.
+   */
+  updateNodesSettings(patches: readonly { readonly nodeId: string; readonly patch: Record<string, unknown> }[]): void {
+    const { doc } = this.state;
+    if (!doc || !patches.length) return;
+    const next = patches.reduce((acc, { nodeId, patch }) => updateNodeSettingsInDoc(acc, nodeId, patch), doc);
+    this.mutate({ type: 'settings', nodeId: patches[0].nodeId }, next);
+  }
+
+  /** the page's own words about itself (title, description, cover, date) — one undoable step per patch */
+  setPageMeta(patch: Partial<IPageMeta>): void {
+    const { doc } = this.state;
+    if (!doc) return;
+    this.mutate({ type: 'settings', nodeId: doc.id }, withMeta(doc, mergeMeta(doc.meta ?? {}, patch)));
+  }
+
+  /**
+   * The page's title and description in other languages, by language code — one undoable step for
+   * all of them (a translation fills several at once). An emptied word reads the original again.
+   */
+  setPageMetaWords(byLang: Readonly<Record<string, IPageMetaWords>>): void {
+    const { doc } = this.state;
+    if (!doc || !Object.keys(byLang).length) return;
+    this.mutate({ type: 'settings', nodeId: doc.id }, withMeta(doc, mergeMetaWords(doc.meta ?? {}, byLang)));
+  }
+
+  /**
+   * A PREFAB's open fields — the settings each page placing it sets for itself. One undoable step;
+   * an empty list leaves the document. Meaningful only while a prefab is open.
+   */
+  setPrefabFields(fields: readonly IPrefabField[]): void {
+    const { doc } = this.state;
+    if (!doc) return;
+    const { fields: _old, ...rest } = doc;
+    this.mutate({ type: 'settings', nodeId: doc.id }, fields.length ? { ...rest, fields } : rest);
+  }
+
+  /** the author's view of a reference provider (i18n: the language being edited); null clears it */
+  setView(name: string, view: unknown): void {
+    if (Object.is(this.state.views[name] ?? null, view ?? null)) return;
+    const { [name]: old, ...rest } = this.state.views;
+    void old;
+    this.set({ ...this.state, views: view == null ? rest : { ...rest, [name]: view } });
+  }
+
+  /**
+   * The root's block — the page's root component (a prefab's preview frame): swapped for another,
+   * the children stay where they are. Chosen in the editor, not at creation: what a root
+   * component is needs the page in front of one to make sense.
+   */
+  setRootReference(reference: string): void {
+    const { doc } = this.state;
+    if (!doc || doc.reference === reference) return;
+    this.mutate({ type: 'settings', nodeId: doc.id }, { ...doc, reference });
+  }
+
+  /**
+   * Blocks moved to another version of themselves (ADR-0061) in ONE undoable step: each node takes
+   * its new reference and its settings as the new version reads them (migrated by the caller — the
+   * block's own `upgrade`, its new defaults). Children, slot and every other field stay.
+   */
+  upgradeNodes(changes: readonly { readonly nodeId: string; readonly reference: string; readonly settings: Record<string, unknown> }[]): void {
+    const { doc } = this.state;
+    if (!doc || !changes.length || this.state.revision !== null) return;
+    const next = changes.reduce(
+      (acc, { nodeId, reference, settings }) => transformNode(acc, nodeId, (n) => ({ ...n, reference, settings })) as IPageDoc,
+      doc,
+    );
+    this.mutate({ type: 'settings', nodeId: changes[0].nodeId }, next);
+  }
+
+  /** a provider takes new blocks under its wing — or stops (node-level `autoBind`) */
+  setNodeAutoBind(id: string, on: boolean): void {
+    if (!this.state.doc) return;
+    this.mutate({ type: 'settings', nodeId: id }, setNodeAutoBindInDoc(this.state.doc, id, on));
+  }
+
+  /**
+   * Settings changes that FOLLOW the step just made, folded into it — an insert and the links its
+   * block gets from a provider are one edit, one Ctrl+Z. Folded only while that step is still the
+   * last one (`action`, as recorded); otherwise — the author did something meanwhile — they become
+   * a step of their own. Answers whether they were folded in.
+   */
+  amendStep(action: IPageAction, patches: readonly { readonly nodeId: string; readonly patch: Record<string, unknown> }[]): boolean {
+    const { doc } = this.state;
+    if (!doc || !patches.length || this.state.revision !== null) return false;
+    const last = doc.history?.[doc.history.length - 1]?.action;
+    if (!last || last.type !== action.type || last.nodeId !== action.nodeId) {
+      this.updateNodesSettings(patches);
+      return false;
+    }
+    const next = patches.reduce((acc, { nodeId, patch }) => updateNodeSettingsInDoc(acc, nodeId, patch), doc);
+    this.set({ ...this.state, doc: next, dirty: true });
+    return true;
+  }
+
+  /** toggle the node-level ssr flag (root: enable page SSR; deeper: opt the branch out) */
+  setNodeSsr(id: string, ssr: boolean | undefined): void {
+    if (!this.state.doc) return;
+    this.mutate({ type: 'ssr', nodeId: id }, setNodeSsrInDoc(this.state.doc, id, ssr));
+  }
+
+  /**
+   * Insert into the place picked in the preview; with nothing picked — at the end of the selected
+   * node (the root when nothing is selected). The new node gets selected, and the picked place is
+   * consumed: its index describes a tree that no longer exists.
+   */
+  insertNode(reference: string, settings: Record<string, unknown>): void {
+    const { doc, selectedNodeId, insertionPoint } = this.state;
+    if (!doc) return;
+    const node: IBlueprintNodeDoc = { id: nextNodeId(doc), reference, settings, children: [] };
+    const parentId = insertionPoint?.parentId ?? selectedNodeId ?? doc.id;
+    // a prefab's block selected (seen, not edited) holds no children of the page's
+    if (!findNodeDoc(doc, parentId)) return;
+    const at = insertionPoint ? { slot: insertionPoint.slot, index: insertionPoint.index } : undefined;
+    this.mutate({ type: 'insert', nodeId: node.id, reference }, insertChildInDoc(doc, parentId, node, at), {
+      selectedNodeId: node.id,
+      insertionPoint: null,
+    });
+  }
+
+  /**
+   * The blocks a copy takes, in document order: the picked forest (the yellow mode), or the blue
+   * branch whole. The page root is not a block — a blue selection on it copies nothing (picking
+   * it YELLOW copies its picked children, see pickedForest).
+   */
+  copySelection(): IBlueprintNodeDoc[] {
+    const { doc, multiSelectedIds, selectedNodeId, selectedSlot } = this.state;
+    if (!doc) return [];
+    if (selectedSlot) {
+      // a selected slot MEANS its children: each one a top-level block, subtrees whole
+      const parent = findNodeDoc(doc, selectedSlot.parentId);
+      return (parent?.children ?? []).filter((child) => (child.slot ?? DEFAULT_SLOT) === selectedSlot.slot);
+    }
+    if (multiSelectedIds.length) return pickedForest(doc, multiSelectedIds);
+    if (selectedNodeId && selectedNodeId !== doc.id) {
+      const branch = findNodeDoc(doc, selectedNodeId);
+      return branch ? [branch] : [];
+    }
+    return [];
+  }
+
+  /**
+   * Insert arriving blocks — freshly renumbered — into the place picked in the preview; with no
+   * place, NEXT TO the selection, never inside it: whether a block can host children is the
+   * PREVIEW's knowledge (slots are learned from the running page, not from a manifest), so the
+   * paste takes the one spot the document itself vouches for — the selected node's own slot,
+   * right after it. The root is the exception: it demonstrably hosts, blocks land at its end.
+   * The WHOLE paste is one action through the one channel, so one Ctrl+Z takes all of it back.
+   * The first pasted block gets selected, the picked place is consumed.
+   */
+  pasteNodes(blocks: readonly IBlueprintNodeDoc[]): void {
+    const { doc, selectedNodeId, multiSelectedIds, insertionPoint } = this.state;
+    if (!doc || !blocks.length) return;
+    const arriving = renumberBlocks(doc, blocks);
+    // right AFTER the anchor node, in its own slot — the one spot the document vouches for
+    const allAfter = (anchorId: string): IPageDoc | null => {
+      const anchor = findNodeDoc(doc, anchorId);
+      const parent = anchor ? findParentNode(doc, anchorId) : null;
+      if (!anchor || !parent) return null;
+      const slotName = anchor.slot ?? DEFAULT_SLOT;
+      const siblings = (parent.children ?? []).filter((child) => (child.slot ?? DEFAULT_SLOT) === slotName);
+      const position = siblings.findIndex((child) => child.id === anchorId) + 1;
+      let acc: IPageDoc = doc;
+      arriving.forEach((block, index) => {
+        acc = insertChildInDoc(acc, parent.id, block, { slot: slotName, index: position + index });
+      });
+      return acc;
+    };
+    const { selectedSlot } = this.state;
+    let next: IPageDoc | null = null;
+    if (selectedSlot && findNodeDoc(doc, selectedSlot.parentId)) {
+      // INTO the selected slot, at the end of its children
+      const host = findNodeDoc(doc, selectedSlot.parentId)!;
+      const already = (host.children ?? []).filter((child) => (child.slot ?? DEFAULT_SLOT) === selectedSlot.slot).length;
+      next = doc;
+      arriving.forEach((block, index) => {
+        next = insertChildInDoc(next!, selectedSlot.parentId, block, {
+          slot: selectedSlot.slot,
+          index: already + index,
+        });
+      });
+    } else if (insertionPoint && findNodeDoc(doc, insertionPoint.parentId)) {
+      next = doc;
+      arriving.forEach((block, index) => {
+        next = insertChildInDoc(next!, insertionPoint.parentId, block, {
+          slot: insertionPoint.slot,
+          index: insertionPoint.index + index,
+        });
+      });
+    } else if (multiSelectedIds.length) {
+      // the yellow mode has no blue anchor: the paste follows the LAST picked region — so
+      // picking a slot's children and pasting lands into that very slot, after them
+      const starts = pickedRegionStarts(doc, multiSelectedIds);
+      next = starts.length ? allAfter(starts[starts.length - 1]) : null;
+    } else if (selectedNodeId && selectedNodeId !== doc.id) {
+      // a prefab's block selected: the paste lands after its prefab, the page's own block
+      next = allAfter(unitOwnerOf(selectedNodeId) ?? selectedNodeId);
+    }
+    if (next === null) {
+      next = doc;
+      for (const block of arriving) next = insertChildInDoc(next, doc.id, block);
+    }
+    this.mutate({ type: 'paste', nodeId: arriving[0].id }, next, {
+      selectedNodeId: arriving[0].id,
+      selectedSlot: null,
+      multiSelectedIds: [],
+      insertionPoint: null,
+    });
+  }
+
+  /**
+   * The removing half of a CUT (the copy is copySelection — the two are one gesture, split so
+   * the clipboard can be written before the tree changes). What leaves the page are the picked
+   * REGION STARTS whole: an unpicked child of a picked parent has nowhere to stay and goes with
+   * it — deliberately, while the clipboard copy still carries only what was picked. One action,
+   * one undo. The blue selection cuts its branch; the root cannot be cut.
+   */
+  removeSelection(): void {
+    const { doc, multiSelectedIds, selectedNodeId, insertionPoint } = this.state;
+    if (!doc) return;
+    const { selectedSlot } = this.state;
+    // a selected slot cuts its CHILDREN; the slot is structure, it stays selected for the paste back
+    const slotParent = selectedSlot ? findNodeDoc(doc, selectedSlot.parentId) : null;
+    const starts: string[] = selectedSlot
+      ? (slotParent?.children ?? [])
+        .filter((child) => (child.slot ?? DEFAULT_SLOT) === selectedSlot.slot)
+        .map((child) => child.id)
+      : multiSelectedIds.length
+        ? pickedRegionStarts(doc, multiSelectedIds)
+        : (selectedNodeId && selectedNodeId !== doc.id && findNodeDoc(doc, selectedNodeId) ? [selectedNodeId] : []);
+    if (!starts.length) return;
+    let next: IPageDoc = doc;
+    for (const id of starts) next = removeNodeFromDoc(next, id);
+    this.mutate({ type: 'cut', nodeId: starts[0] }, next, {
+      selectedNodeId: selectedNodeId && !findNodeDoc(next, selectedNodeId) ? doc.id : selectedNodeId,
+      insertionPoint: insertionPoint && findNodeDoc(next, insertionPoint.parentId) ? insertionPoint : null,
+    });
+  }
+
+  removeNode(id: string): void {
+    const { doc, selectedNodeId, insertionPoint } = this.state;
+    // the root stays; a prefab's block is the prefab's — not the page's to remove
+    if (!doc || doc.id === id || !findNodeDoc(doc, id)) return;
+    const next = removeNodeFromDoc(doc, id);
+    this.mutate({ type: 'remove', nodeId: id }, next, {
+      selectedNodeId: selectedNodeId === id ? doc.id : selectedNodeId,
+      // the picked place lived inside what just left
+      insertionPoint: insertionPoint && findNodeDoc(next, insertionPoint.parentId) ? insertionPoint : null,
+    });
+  }
+
+  /**
+   * Step back: the top history entry leaves the stack, its snapshot becomes the page, and the
+   * step waits on the redo list — inside the document, like the history itself, so both
+   * directions survive a reload together. No entry is ever RECORDED by this: undo and redo move
+   * steps between the stacks, only real edits (mutate) create them.
+   */
+  undo(): void {
+    const { doc } = this.state;
+    if (!doc?.history?.length) return;
+    const entry = doc.history[doc.history.length - 1];
+    const { history: _h, redo: _r, ...after } = doc;
+    const remaining = doc.history.slice(0, -1);
+    this.restore({
+      ...entry.before,
+      ...(remaining.length ? { history: remaining } : {}),
+      redo: [...(doc.redo ?? []), { action: entry.action, after }].slice(-PAGE_HISTORY_LIMIT),
+    });
+  }
+
+  /** step forward again: the mirror of undo — the top redo entry goes back onto the history */
+  redo(): void {
+    const { doc } = this.state;
+    if (!doc?.redo?.length) return;
+    const entry = doc.redo[doc.redo.length - 1];
+    const { history: _h, redo: _r, ...before } = doc;
+    const remaining = doc.redo.slice(0, -1);
+    this.restore({
+      ...entry.after,
+      history: [...(doc.history ?? []), { action: entry.action, before }].slice(-PAGE_HISTORY_LIMIT),
+      ...(remaining.length ? { redo: remaining } : {}),
+    });
+  }
+
+  /**
+   * Swap the document wholesale and keep the pointers honest: a selection whose node is gone
+   * falls back to the root, a picked place dies with its parent. Dirty like any edit — the
+   * autosave writes the restored page out by the same rule.
+   */
+  private restore(next: IPageDoc): void {
+    if (this.state.revision !== null) return; // undo/redo have nothing to do in a read-only view
+    const { selectedNodeId, multiSelectedIds, insertionPoint } = this.state;
+    this.set({
+      ...this.state,
+      doc: next,
+      // a selection whose node is gone falls back to the root; NO selection stays none — grabbing
+      // the root here would drag the blue mode over an active yellow one. A prefab's block stays
+      // while its prefab node does
+      selectedNodeId: selectedNodeId ? (findNodeDoc(next, unitOwnerOf(selectedNodeId) ?? selectedNodeId) ? selectedNodeId : next.id) : null,
+      hoveredNodeId: this.state.hoveredNodeId && findNodeDoc(next, unitOwnerOf(this.state.hoveredNodeId) ?? this.state.hoveredNodeId)
+        ? this.state.hoveredNodeId
+        : null,
+      multiSelectedIds: multiSelectedIds.filter((node) => findNodeDoc(next, node) !== null),
+      selectedSlot: this.state.selectedSlot && findNodeDoc(next, this.state.selectedSlot.parentId)
+        ? this.state.selectedSlot
+        : null,
+      movingNodeId: this.state.movingNodeId && findNodeDoc(next, this.state.movingNodeId)
+        ? this.state.movingNodeId
+        : null,
+      insertionPoint: insertionPoint && findNodeDoc(next, insertionPoint.parentId) ? insertionPoint : null,
+      dirty: true,
+    });
+  }
+
+  /**
+   * A savePageDraft mutation landed ok. `saved` is the document that was SENT, and the flag is
+   * cleared only if the session still holds it: an edit made while the request was in flight is
+   * NOT on disk, and clearing the flag for it would leave the last change unsaved with nothing
+   * saying so — the dot goes out, no further save is scheduled, and the next thing to touch the
+   * draft decides whether it survives.
+   */
+  markSaved(saved: IPageDoc, seq: number): void {
+    if (!this.state.doc) return;
+    this.set({
+      ...this.state,
+      dirty: saved !== this.state.doc,
+      seq,
+      saveFailure: null,
+      savedCount: this.state.savedCount + 1,
+    });
+  }
+
+  /** a write was refused — the draft stays dirty, and now says why */
+  markSaveFailed(code: string): void {
+    this.set({ ...this.state, saveFailure: code });
+  }
+}
+
+export const EDITING_SESSION_TOKEN = new SingleDiToken<EditingSession>('EDITING_SESSION_TOKEN');
+
+// ---- many sessions, one ACTIVE: the hub behind a multi-canvas workbench ------------------------
+
+/** the key of the session work starts in before any canvas has bound itself */
+export const DEFAULT_EDITING_SESSION_KEY = 'default';
+
+/**
+ * The HUB of editing sessions: every canvas owns a session under its own key, and the hub's
+ * `active` facade is what the rest of the workbench holds — a session-shaped view that routes
+ * every call to the CURRENT session and re-emits its changes, so the tree and the hotkeys follow
+ * whichever canvas the user last touched (a hover included) without knowing sessions switched.
+ *
+ * The SECOND facade, `selection`, follows the last deliberate CHOICE instead: it routes to the
+ * session where a selection last CHANGED, whichever canvas is active now. Hover activates
+ * sessions (focus follows the pointer), and a panel that shows "the element you picked" (the
+ * settings) must not lose its subject to a pointer passing over another canvas — it keeps
+ * showing the picked element until a pick happens elsewhere.
+ *
+ * Ownership starts loose: work begun before any canvas exists (a fresh draft opened from the
+ * pages panel) lives in the DEFAULT session, and the first canvas to bind ADOPTS that very
+ * instance — the open draft included — instead of starting empty.
+ */
+export class EditingSessionHub {
+  private readonly sessions = new Map<string, EditingSession>();
+
+  private readonly activeListeners = new Set<() => void>();
+
+  private readonly selectionListeners = new Set<() => void>();
+
+  /** each session's selectionStamp when last seen — the act detector */
+  private readonly seenStamps = new Map<EditingSession, number>();
+
+  /** the permanent per-session subscriptions, so a retired session can be let go of */
+  private readonly watchers = new Map<EditingSession, () => void>();
+
+  private currentKey = DEFAULT_EDITING_SESSION_KEY;
+
+  private selectionKey = DEFAULT_EDITING_SESSION_KEY;
+
+  /** the session-shaped view of whichever session is ACTIVE — what EDITING_SESSION_TOKEN holds */
+  readonly active: EditingSession;
+
+  /** the session-shaped view of wherever the last SELECTION happened — the settings' anchor */
+  readonly selection: EditingSession;
+
+  constructor() {
+    const first = new EditingSession();
+    this.sessions.set(this.currentKey, first);
+    this.watch(first);
+    // A Proxy rather than a hand-written delegator: the facade must follow the session's WHOLE
+    // surface forever, and a forgotten method here would be a silent no-op there. TWO members are
+    // intercepted with STABLE, late-binding functions: `subscribe` (subscribers belong to the
+    // facade and survive switches) and `snapshot` — react's useSyncExternalStore CACHES the
+    // getSnapshot it was rendered with, so a snapshot bound at property-ACCESS time would keep
+    // reading the pre-switch session forever, and every post-switch notify would look like
+    // "nothing changed" (a silent bailout instead of following the active canvas).
+    this.active = this.facadeOver(() => this.currentSession(), this.subscribeActive, this.snapshotActive);
+    this.selection = this.facadeOver(() => this.selectionSession(), this.subscribeSelection, this.snapshotSelection);
+  }
+
+  /** the session bound to `key`, if one exists — a LOOK, never a creation (nor an adoption) */
+  peek(key: string): EditingSession | null {
+    return this.sessions.get(key) ?? null;
+  }
+
+  /** the workbench's provider views — every session shows them, a new session inherits them */
+  private views: Readonly<Record<string, unknown>> = {};
+
+  private readonly viewListeners = new Set<() => void>();
+
+  /** one provider's view for the whole workbench (null clears it) */
+  setView(name: string, view: unknown): void {
+    const { [name]: old, ...rest } = this.views;
+    void old;
+    this.views = view == null ? rest : { ...this.views, [name]: view };
+    for (const session of this.sessions.values()) session.setView(name, view);
+    for (const listener of [...this.viewListeners]) listener();
+  }
+
+  readonly viewsSnapshot = (): Readonly<Record<string, unknown>> => this.views;
+
+  readonly subscribeViews = (listener: () => void): (() => void) => {
+    this.viewListeners.add(listener);
+    return () => {
+      this.viewListeners.delete(listener);
+    };
+  };
+
+  /** the session bound to `key` — created on first ask, or ADOPTED from the default pool */
+  sessionFor(key: string): EditingSession {
+    const existing = this.sessions.get(key);
+    if (existing) return existing;
+    const unowned = this.sessions.get(DEFAULT_EDITING_SESSION_KEY);
+    if (unowned && key !== DEFAULT_EDITING_SESSION_KEY) {
+      this.sessions.delete(DEFAULT_EDITING_SESSION_KEY);
+      this.sessions.set(key, unowned);
+      if (this.currentKey === DEFAULT_EDITING_SESSION_KEY) this.currentKey = key;
+      if (this.selectionKey === DEFAULT_EDITING_SESSION_KEY) this.selectionKey = key;
+      return unowned;
+    }
+    const fresh = new EditingSession();
+    for (const [name, view] of Object.entries(this.views)) fresh.setView(name, view);
+    this.sessions.set(key, fresh);
+    this.watch(fresh);
+    return fresh;
+  }
+
+  /** the key hover-borrowed the focus for; null whenever the activation was deliberate */
+  private borrowedKey: string | null = null;
+
+  /** make `key`'s session the ACTIVE one — the facade switches and tells every subscriber */
+  activate(key: string): void {
+    this.borrowedKey = null;
+    const before = this.currentSession();
+    const target = this.sessionFor(key);
+    this.currentKey = key;
+    if (target !== before) this.notifyActive();
+  }
+
+  /**
+   * Make `key` the active session AND the selection anchor — the canvas in front after a reload:
+   * the documents restored behind it were opened too, and the last of them to arrive must not
+   * keep the anchor (the settings would show a canvas nobody sees).
+   */
+  focus(key: string): void {
+    this.activate(key);
+    if (this.selectionKey === key) return;
+    this.selectionKey = key;
+    this.notifySelection();
+  }
+
+  /**
+   * Hover BORROWS the focus rather than taking it: the session activates like any other, but
+   * the activation is marked a LOAN — when the pointer leaves the canvas without a deliberate
+   * act having happened (release), the focus goes home to the selection anchor. The invariant
+   * this buys: at rest, the tree shows the canvas of the selected node.
+   */
+  borrow(key: string): void {
+    // the pointer over the canvas that already HAS the focus (its tab picked, a click inside)
+    // borrows nothing: its leave must keep it — the anchor may live in a canvas hidden behind it
+    if (key === this.currentKey && this.borrowedKey === null) return;
+    this.activate(key);
+    this.borrowedKey = key;
+  }
+
+  /** the pointer left `key`'s canvas: a focus still on loan for it returns to the anchor */
+  release(key: string): void {
+    if (this.borrowedKey !== key) return;
+    this.activate(this.selectionKey);
+  }
+
+  activeKey(): string {
+    return this.currentKey;
+  }
+
+  /** where the selection anchor lives — a canvas checks it to keep ONE blue block per workspace */
+  anchorKey(): string {
+    return this.selectionKey;
+  }
+
+  /** every key a session lives under right now */
+  keys(): string[] {
+    return [...this.sessions.keys()];
+  }
+
+  /**
+   * A canvas tab CLOSED: its session leaves the hub for good. Whoever pointed at it falls back —
+   * the active facade to a remaining session (dockview activates a neighbour tab anyway, and a
+   * neighbouring CANVAS re-activates its own session right after; this fallback covers the
+   * neighbour being no canvas at all), the selection anchor to wherever the active one landed.
+   * The last session leaving re-seeds an empty default — the tree and the settings show their
+   * placeholders instead of a dead canvas's world.
+   */
+  retire(key: string): void {
+    const session = this.sessions.get(key);
+    if (!session) return;
+    this.sessions.delete(key);
+    this.seenStamps.delete(session);
+    this.watchers.get(session)?.();
+    this.watchers.delete(session);
+    if (this.borrowedKey === key) this.borrowedKey = null;
+    if (this.sessions.size === 0) {
+      const fresh = new EditingSession();
+      this.sessions.set(DEFAULT_EDITING_SESSION_KEY, fresh);
+      this.watch(fresh);
+    }
+    if (this.currentKey === key) {
+      // a remaining canvas with an open draft beats an empty one — «the tree switches to the
+      // canvas that is left», and only with nothing left does it show its placeholder
+      const remaining = [...this.sessions.entries()];
+      const withDoc = remaining.find(([, held]) => held.snapshot().doc !== null);
+      this.currentKey = (withDoc ?? remaining[0])[0];
+      this.notifyActive();
+    }
+    if (this.selectionKey === key) {
+      this.selectionKey = this.currentKey;
+      this.notifySelection();
+    }
+  }
+
+  private currentSession(): EditingSession {
+    return this.sessions.get(this.currentKey)!;
+  }
+
+  private selectionSession(): EditingSession {
+    return this.sessions.get(this.selectionKey) ?? this.currentSession();
+  }
+
+  /**
+   * The hub listens to EVERY session it holds, permanently — that is what lets it see a
+   * selection change in a canvas that is not active, and what feeds both facades from one wire.
+   */
+  private watch(session: EditingSession): void {
+    this.seenStamps.set(session, session.snapshot().selectionStamp);
+    this.watchers.set(session, session.subscribe(() => this.onSessionChanged(session)));
+  }
+
+  private onSessionChanged(session: EditingSession): void {
+    const now = session.snapshot();
+    // ONLY an act moves the anchor (the stamp): a diff without one is somebody's programmatic
+    // housekeeping — a canvas surrendering its blue selection (retireSelection), an edit pruning
+    // a dead id — and mistaking it for a pick would drag the anchor around behind the janitor
+    const selectionChanged = this.seenStamps.get(session) !== now.selectionStamp;
+    this.seenStamps.set(session, now.selectionStamp);
+    // the key is looked up at NOTIFY time: an adoption re-keys the session, the instance stays
+    const key = this.keyOf(session);
+    if (selectionChanged && key !== null && key !== this.selectionKey) {
+      this.selectionKey = key;
+      this.notifySelection();
+    } else if (key === this.selectionKey) {
+      this.notifySelection();
+    }
+    if (key === this.currentKey) this.notifyActive();
+  }
+
+  private keyOf(session: EditingSession): string | null {
+    for (const [key, held] of this.sessions) {
+      if (held === session) return key;
+    }
+    return null;
+  }
+
+  private facadeOver(
+    current: () => EditingSession,
+    subscribe: EditingSession['subscribe'],
+    snapshot: EditingSession['snapshot'],
+  ): EditingSession {
+    return new Proxy(current(), {
+      get: (_target, prop) => {
+        if (prop === 'subscribe') return subscribe;
+        if (prop === 'snapshot') return snapshot;
+        const target = current();
+        const value = Reflect.get(target, prop, target) as unknown;
+        return typeof value === 'function'
+          ? (value as (...args: unknown[]) => unknown).bind(target)
+          : value;
+      },
+    });
+  }
+
+  private notifyActive(): void {
+    for (const listener of this.activeListeners) listener();
+  }
+
+  private notifySelection(): void {
+    for (const listener of this.selectionListeners) listener();
+  }
+
+  private readonly snapshotActive = (): IEditingState => this.currentSession().snapshot();
+
+  private readonly subscribeActive = (listener: () => void): (() => void) => {
+    this.activeListeners.add(listener);
+    return () => this.activeListeners.delete(listener);
+  };
+
+  private readonly snapshotSelection = (): IEditingState => this.selectionSession().snapshot();
+
+  private readonly subscribeSelection = (listener: () => void): (() => void) => {
+    this.selectionListeners.add(listener);
+    return () => this.selectionListeners.delete(listener);
+  };
+}
+
+export const EDITING_SESSION_HUB_TOKEN = new SingleDiToken<EditingSessionHub>('EDITING_SESSION_HUB_TOKEN');
+
+/**
+ * Lazily register the session on first use: the workbench's ROOT app belongs to the TARGET app
+ * (the editor is injected into its devOnly page) and must not know editor services —
+ * whichever widget renders first creates the shared instance. What the token holds is the HUB's
+ * `active` facade; a container that already resolves the token (a preview environment seeding
+ * its own specimen session) keeps what it has — no hub appears there.
+ */
+export function ensureEditingSession(di: DiContainer): EditingSession {
+  try {
+    return di.getByToken(EDITING_SESSION_TOKEN);
+  } catch {
+    const hub = new EditingSessionHub();
+    di.registerValueOfToken(EDITING_SESSION_HUB_TOKEN, hub);
+    di.registerValueOfToken(EDITING_SESSION_TOKEN, hub.active);
+    return hub.active;
+  }
+}
+
+/** the hub, where one exists — null in preview environments and anywhere pre-hub */
+export function editingSessionHubOf(di: DiContainer): EditingSessionHub | null {
+  return di.hasByToken(EDITING_SESSION_HUB_TOKEN) ? di.getByToken(EDITING_SESSION_HUB_TOKEN) : null;
+}