@jxsuite/studio 2.0.0 → 2.1.0

package/src/tabs/selection.ts

@@ -0,0 +1,323 @@
+/**
+ * The selection SET — one vocabulary for `session.selection`, now that it is `JxPath[]` (§6.5).
+ *
+ * ## The invariant this module exists to hold
+ *
+ * **A selection of one behaves exactly as a selection did before it was a list.** Every surface
+ * that addresses a single node — the Inspector's three tabs, the block action bar, the status bar,
+ * the canvas overlay box, the context menu — reads {@link primarySelection} and nothing else. When
+ * `length === 1` that function returns the sole path, so those surfaces receive byte-identically
+ * what `session.selection` used to hand them. Nothing downstream of `primarySelection` can tell the
+ * difference, and that is what makes the widening shippable: the multi cases are additions beside
+ * the single case, never a rewrite of it.
+ *
+ * The corollary is a rule about writes: **replace the array, never mutate it in place.** Several
+ * render effects track the selection with a bare `void tab.session.selection` read, which
+ * subscribes to the property and not to the array's indices; an in-place `push` would move the
+ * selection without repainting the panel that draws it. Every helper here returns a NEW array.
+ *
+ * ## Ordering, and why two ends of the list have names
+ *
+ * The list is kept in the order the user built it.
+ *
+ * - {@link selectionAnchor} is `selection[0]` — where a shift-range extends FROM. It survives every
+ *   range extension, so shift-clicking A then D then B gives A..D then A..B, which is what every
+ *   list in every file manager does.
+ * - {@link primarySelection} is the LAST element — the most recently added path, and therefore the
+ *   one the user just pointed at. Single-target surfaces address it.
+ *
+ * ## Structural batches
+ *
+ * A multi-node structural edit is one decision and must be one undo step, which `transactDoc`
+ * already gives for free — everything mutated inside one call is one history entry. What it does
+ * NOT give is index safety: removing `children/0` renumbers `children/1`, so a naive loop over the
+ * selection deletes the wrong nodes. {@link structuralBatch} answers that once — descendants
+ * dropped, then descending document order, so every splice happens below coordinates nothing later
+ * in the batch depends on.
+ *
+ * It also answers a second question the single-path world never had to ask: whether a selected path
+ * is a splice coordinate AT ALL. The Outline gives the document element, a repeater's map template
+ * and a `$switch` case rows of their own, and any of them can be ctrl-clicked into a selection
+ * beside an ordinary element. {@link isSpliceablePath} is the test, and it is the one thing
+ * standing between a mixed selection and a half-applied, unrecorded delete.
+ */
+
+import type { JxPath } from "../state";
+import { isAncestor, pathsEqual } from "../state";
+
+/**
+ * The path single-target surfaces address — the most recently added, or `null` when empty.
+ *
+ * @param {readonly JxPath[] | null | undefined} selection
+ * @returns {JxPath | null}
+ */
+export function primarySelection(selection: readonly JxPath[] | null | undefined): JxPath | null {
+  return selection && selection.length > 0 ? (selection.at(-1) as JxPath) : null;
+}
+
+/**
+ * The path a shift-range extends from — the first in the list, or `null` when empty.
+ *
+ * @param {readonly JxPath[] | null | undefined} selection
+ * @returns {JxPath | null}
+ */
+export function selectionAnchor(selection: readonly JxPath[] | null | undefined): JxPath | null {
+  return selection && selection.length > 0 ? (selection[0] as JxPath) : null;
+}
+
+/**
+ * Whether `path` is one of the selected paths.
+ *
+ * @param {readonly JxPath[] | null | undefined} selection
+ * @param {JxPath | null} path
+ * @returns {boolean}
+ */
+export function isSelected(
+  selection: readonly JxPath[] | null | undefined,
+  path: JxPath | null,
+): boolean {
+  if (!path || !selection) {
+    return false;
+  }
+  return selection.some((p) => pathsEqual(p, path));
+}
+
+/**
+ * Copy a selection, so nothing can mutate one through the array it was handed.
+ *
+ * History entries and the collab awareness payload both take a copy for the same reason they always
+ * did: `session.selection` is a reactive proxy, and a stored reference to it would follow the live
+ * selection instead of recording where it was. (A third caller, the sub-document stack's frames,
+ * went with the stack — nothing pushes one any more.)
+ *
+ * @param {readonly JxPath[]} paths
+ * @returns {JxPath[]}
+ */
+export function cloneSelection(paths: readonly JxPath[]): JxPath[] {
+  return clonePaths(paths);
+}
+
+/** Copy a list of paths, so no caller can mutate a selection through the array it was handed. */
+function clonePaths(paths: readonly JxPath[]): JxPath[] {
+  const out: JxPath[] = [];
+  for (const path of paths) {
+    out.push([...path]);
+  }
+  return out;
+}
+
+/**
+ * Ctrl/Cmd-click: add the path when it is absent, remove it when it is present.
+ *
+ * Adding appends, so the newly clicked path becomes the primary and the anchor is untouched.
+ * Removing preserves the order of the survivors — including the anchor, unless the anchor is what
+ * was removed.
+ *
+ * @param {readonly JxPath[]} selection
+ * @param {JxPath} path
+ * @returns {JxPath[]}
+ */
+export function toggleSelected(selection: readonly JxPath[], path: JxPath): JxPath[] {
+  if (isSelected(selection, path)) {
+    return clonePaths(selection.filter((p) => !pathsEqual(p, path)));
+  }
+  return [...clonePaths(selection), [...path]];
+}
+
+/**
+ * Shift-click: the contiguous run of `rows` between the anchor and `target`, inclusive.
+ *
+ * `rows` is the surface's own visible order — the Outline's flattened, expansion-aware row list —
+ * because "the range between these two" is a question only the surface that draws them can answer.
+ * When the anchor is absent from `rows` (it was collapsed away, or nothing was selected) the range
+ * degenerates to `[target]`, which is a plain click.
+ *
+ * The returned list starts at the anchor end, so the anchor stays `selection[0]` and the target
+ * becomes the primary — a further shift-click re-extends from the same anchor.
+ *
+ * @param {readonly JxPath[]} rows Visible rows in display order.
+ * @param {JxPath | null} anchor
+ * @param {JxPath} target
+ * @returns {JxPath[]}
+ */
+export function rangeSelection(
+  rows: readonly JxPath[],
+  anchor: JxPath | null,
+  target: JxPath,
+): JxPath[] {
+  const to = rows.findIndex((p) => pathsEqual(p, target));
+  const from = anchor ? rows.findIndex((p) => pathsEqual(p, anchor)) : -1;
+  if (to === -1 || from === -1) {
+    return [[...target]];
+  }
+  const slice = from <= to ? rows.slice(from, to + 1) : rows.slice(to, from + 1).toReversed();
+  return clonePaths(slice);
+}
+
+/**
+ * Drop every selected path that `removed` addresses or contains.
+ *
+ * This is `mutateRemoveNode`'s selection repair, widened: deleting a node used to clear the
+ * selection outright, and with a list it clears only the entries the deletion actually invalidated.
+ * A one-path selection therefore still ends up empty exactly when it used to.
+ *
+ * @param {readonly JxPath[]} selection
+ * @param {JxPath} removed
+ * @returns {JxPath[]}
+ */
+export function pruneSelection(selection: readonly JxPath[], removed: JxPath): JxPath[] {
+  return clonePaths(selection.filter((p) => !isAncestor(removed, p)));
+}
+
+/**
+ * Order two paths the way the document reads: parents before children, siblings by index.
+ *
+ * Segments are compared pairwise; numbers numerically (so `children/10` follows `children/9`), and
+ * anything else by string order. A prefix sorts before what extends it.
+ *
+ * @param {JxPath} a
+ * @param {JxPath} b
+ * @returns {number}
+ */
+export function comparePaths(a: JxPath, b: JxPath): number {
+  const len = Math.min(a.length, b.length);
+  for (let i = 0; i < len; i++) {
+    const x = a[i]!;
+    const y = b[i]!;
+    if (x === y) {
+      continue;
+    }
+    if (typeof x === "number" && typeof y === "number") {
+      return x - y;
+    }
+    return String(x) < String(y) ? -1 : 1;
+  }
+  return a.length - b.length;
+}
+
+/**
+ * Drop any path whose ancestor is also selected.
+ *
+ * Deleting a `<section>` and one of its own paragraphs is one deletion, not two: the paragraph goes
+ * with its parent, and a second splice into coordinates that no longer exist is how a batch
+ * corrupts a document.
+ *
+ * @param {readonly JxPath[]} selection
+ * @returns {JxPath[]}
+ */
+export function topLevelSelection(selection: readonly JxPath[]): JxPath[] {
+  return clonePaths(
+    selection.filter((p) => !selection.some((q) => !pathsEqual(q, p) && isAncestor(q, p))),
+  );
+}
+
+/**
+ * Whether `path` names a position a structural verb can splice — a tail of `"children"` + index.
+ *
+ * Every structural mutator (`mutateRemoveNode`, `mutateDuplicateNode`, `mutateWrapNode`) reaches
+ * its parent with `parentElementPath` — drop the last two segments — and its position with
+ * `childIndex` — take the last. That produces a splice coordinate for exactly one path shape, and
+ * the Outline emits three others as first-class rows: the document element (`[]`), a repeater's map
+ * template (`[…, "children", 1, "map"]`) and a `$switch` case (`[…, "cases", "warn"]`). For the
+ * template, `parentElementPath` resolves to the enclosing children ARRAY, whose `.children` is
+ * `undefined`, so the splice throws mid-transaction; for a case it splices at `NaN` and takes the
+ * wrong child.
+ *
+ * Selecting one of those beside an ordinary element is a single ctrl-click, so this is the
+ * invariant that keeps a batch from mutating the document and then throwing before anything is
+ * recorded.
+ *
+ * @param {JxPath} path
+ * @returns {boolean}
+ */
+export function isSpliceablePath(path: JxPath): boolean {
+  return path.at(-2) === "children" && typeof path.at(-1) === "number";
+}
+
+/**
+ * The order a structural batch must run in: contained paths dropped, unspliceable paths dropped,
+ * then LAST node first.
+ *
+ * Descending document order is what makes a loop of splices safe. Removing or duplicating at index
+ * `n` renumbers every sibling after `n`, so a batch that starts at the end never touches a
+ * coordinate a later step still needs. It is also why duplicating a multi-selection inserts each
+ * clone directly after its own original instead of walking the whole run forward.
+ *
+ * Containment is decided BEFORE spliceability, on the selection the user actually made: a selected
+ * repeater template still shadows its own descendants, so selecting the template and something
+ * inside it yields nothing rather than quietly deleting the child the user never pointed at.
+ *
+ * @param {readonly JxPath[]} selection
+ * @returns {JxPath[]} Deepest/last first, every entry a splice coordinate.
+ */
+export function structuralBatch(selection: readonly JxPath[]): JxPath[] {
+  return topLevelSelection(selection)
+    .filter((path) => isSpliceablePath(path))
+    .toSorted((a, b) => comparePaths(b, a));
+}
+
+/**
+ * Deduplicate a list of paths, keeping the FIRST occurrence of each.
+ *
+ * Keeping the first is what makes `selection.setPaths` idempotent: passing the same list twice — or
+ * a list that names one node twice — always lands on the same selection, in the same order, with
+ * the same anchor and the same primary.
+ *
+ * @param {readonly JxPath[]} paths
+ * @returns {JxPath[]}
+ */
+export function uniquePaths(paths: readonly JxPath[]): JxPath[] {
+  const out: JxPath[] = [];
+  for (const path of paths) {
+    if (!out.some((p) => pathsEqual(p, path))) {
+      out.push([...path]);
+    }
+  }
+  return out;
+}
+
+/**
+ * Whether two selections name the same paths in the same order.
+ *
+ * @param {readonly JxPath[] | null | undefined} a
+ * @param {readonly JxPath[] | null | undefined} b
+ * @returns {boolean}
+ */
+export function selectionsEqual(
+  a: readonly JxPath[] | null | undefined,
+  b: readonly JxPath[] | null | undefined,
+): boolean {
+  const x = a ?? [];
+  const y = b ?? [];
+  return x.length === y.length && x.every((p, i) => pathsEqual(p, y[i] as JxPath));
+}
+
+/**
+ * Collapse one field's value across the selection into a single reading.
+ *
+ * `{ mixed: true }` is the answer the three inspector tabs render as the **Mixed** provenance
+ * state: the selected nodes disagree, so there is no one value to show and typing one would
+ * overwrite several different ones. `{ mixed: false, value }` is the answer when they agree — and
+ * when the selection is a single node it is ALWAYS that answer, which is why a single selection
+ * renders no Mixed state anywhere.
+ *
+ * Comparison is by JSON shape rather than reference: two nodes that both carry `{ $ref: "#/state/x"
+ * }` hold equal values written at different times.
+ *
+ * @template T
+ * @param {readonly T[]} values One per selected node, in selection order.
+ * @returns {{ mixed: boolean; value: T | undefined }}
+ */
+export function unifyValues<T>(values: readonly T[]): { mixed: boolean; value: T | undefined } {
+  if (values.length === 0) {
+    return { mixed: false, value: undefined };
+  }
+  const first = values[0] as T;
+  const key = JSON.stringify(first ?? null);
+  for (let i = 1; i < values.length; i++) {
+    if (JSON.stringify(values[i] ?? null) !== key) {
+      return { mixed: true, value: undefined };
+    }
+  }
+  return { mixed: false, value: first };
+}

package/src/tabs/tab.ts

@@ -2,19 +2,21 @@
 import { effectScope, reactive } from "../reactivity";
 import { formatByName, formatForPath } from "../format/format-host";
 import { normalizeArrayChildren } from "../state";
-import type {
-  DocumentStackEntry,
-  FormulaEditDef,
-  FunctionEditDef,
-  GitBranchesResult,
-  GitDiffState,
-  GitStatusResult,
-  InlineEditDef,
-  JsonValue,
-} from "../types";
+import type { FormulaEditDef, FunctionEditDef, InlineEditDef, JsonValue } from "../types";
+import { editorKindForMode } from "../commands/context";
+import type { EditorKind } from "../commands/context";
 import type { JxMutableNode } from "@jxsuite/schema/types";
 import type { JxDocOp, JxFmOp } from "./patch-ops";
 
+/**
+ * The project's configuration file, project-relative.
+ *
+ * Named here rather than at the four places that used to spell it, because it is a DOCUMENT PATH —
+ * `inferModes` answers `["stylebook", "source"]` for it (editor kind `config`), and
+ * `tabs/project-config.ts` binds the tab at this path as the configuration document.
+ */
+export const PROJECT_CONFIG_PATH = "project.json";
+
 export interface TabUi {
   rightTab: string;
   canvasMode: string;
@@ -22,8 +24,6 @@ export interface TabUi {
   preview: boolean;
   /** Show elements inherited from the page's layout (pages with an effective layout only). */
   showLayout: boolean;
-  /** Above-canvas frontmatter Properties accordion expanded (content-collection docs, edit mode). */
-  frontmatterOpen: boolean;
   /** Chosen literal values for dynamic route params (e.g. { sku: "mini-trencher" }). */
   previewParams: Record<string, string>;
   /**
@@ -40,7 +40,7 @@ export interface TabUi {
   activeMedia: string | null;
   activeSelector: string | null;
   editingFunction: FunctionEditDef | null;
-  /** Full-screen formula workspace target ($expression editing); editingFunction wins if both set. */
+  /** Logic-tab formula target ($expression editing); editingFunction wins if both are set. */
   editingFormula: FormulaEditDef | null;
   featureToggles: Record<string, boolean>;
   /**
@@ -49,22 +49,40 @@ export interface TabUi {
    * which scheme layer edits target.
    */
   previewColorScheme: "auto" | "light" | "dark";
+  /**
+   * The locale this pane renders AS — the artboard's `lang` and `dir` (§13.4), never which file is
+   * open.
+   *
+   * Jx has no message catalogue: a translation is a different file in a different directory, so
+   * "show this page in French" is a navigation and belongs to the locale preset. This axis is the
+   * other half — the rendering context a document is _drawn_ under, which is how an author sees
+   * their layout mirror under an RTL locale without leaving the document they are editing.
+   *
+   * `null` is "the document's own language", resolved from its path at render time rather than
+   * baked in here: a file moved into `pages/fr/` must change what the pane draws, and a stored tag
+   * would go on claiming the language the file used to be in.
+   */
+  previewLocale: string | null;
   styleSections: Record<string, boolean>;
+  /**
+   * Which Data rows have their editor and value open, by state-entry name.
+   *
+   * PER TAB, and a set rather than a single name: comparing two entries means seeing both at once,
+   * and coming back to a tab means finding it as you left it. It was one module-global string
+   * (`expandedSignal`) plus one module-global Set (`expandedDataKeys`) — two answers to one
+   * question, both shared across every open document.
+   */
+  dataRows: Record<string, boolean>;
+  /**
+   * How far each truncation marker in a Data row's value tree has been opened, keyed by tree path.
+   *
+   * PER TAB, for the reason `dataRows` is: the paths are entry names, and a module-global record
+   * would have applied "show 50 more of `listings`" to a different document's `listings`.
+   */
+  dataLimits: Record<string, number>;
   inspectorSections: Record<string, boolean>;
   styleShorthands: Record<string, boolean>;
   styleFilter: string;
-  styleFilterActive: boolean;
-  stylebookSelection: string | null;
-  stylebookTab: string;
-  stylebookFilter: string;
-  stylebookCustomizedOnly: boolean;
-  settingsTab: string;
-  gitStatus: GitStatusResult | null;
-  gitBranches: GitBranchesResult | null;
-  gitCommitMessage: string;
-  gitLoading: boolean;
-  gitError: string | null;
-  gitDiffState: GitDiffState | null;
   pendingInlineEdit: InlineEditDef | null;
 }
 
@@ -83,10 +101,10 @@ export interface StoredLivePreview {
 interface HistorySnapshot {
   /** Full document at this state (checkpoint), or null when the ops describe the transition. */
   document: Record<string, unknown> | null;
-  /** Selection after this state's transaction. */
-  selection: (string | number)[] | null;
+  /** Selection after this state's transaction — the whole set, so a batch undoes back to it. */
+  selection: (string | number)[][];
   /** Selection before this state's transaction (restored on surgical undo). */
-  selectionBefore?: (string | number)[] | null;
+  selectionBefore?: (string | number)[][];
   /** Replayable ops transforming the previous state into this one. */
   forwardOps?: JxDocOp[] | null;
   /** Replayable ops transforming this state back into the previous one. */
@@ -103,11 +121,34 @@ interface HistorySnapshot {
   coalesceKey?: string | null;
 }
 
+/**
+ * Where a tab was drilled in FROM — a relationship, not a navigation stack.
+ *
+ * Drilling into a component opens a real tab of its own (see `workspace/workspace.ts`), so the old
+ * "swap the document under the same tab id" breadcrumb is gone. What survives is this: the tab
+ * remembers which document sent the author here, and the tab strip prints it. Nothing restores from
+ * it, nothing pops it — closing the parent leaves the child perfectly usable.
+ */
+export interface TabOrigin {
+  /** Id of the tab the author drilled in from. */
+  tabId: string;
+  /** That tab's document path at the moment of the drill-in — what the strip prints. */
+  documentPath: string | null;
+}
+
 export interface Tab {
   id: string;
   documentPath: string | null;
   fileHandle: FileSystemFileHandle | null;
   capabilities: { modes: string[] };
+  /** Pinned tabs hold the head of their pane's strip, and a preview open never takes their slot. */
+  pinned: boolean;
+  /**
+   * A PREVIEW tab is disposable: the next preview open in the same pane replaces it, and it renders
+   * italic to say so. It stops being one the moment the author commits to it — an edit, a pin, a
+   * double-click. The palette's `@`/`#` modes make browsing cheap, and browsing must not litter.
+   */
+  preview: boolean;
   scope: {
     stop: () => void;
     run: <T>(fn: () => T) => T | undefined;
@@ -122,13 +163,33 @@ export interface Tab {
     dirty: boolean;
   };
   session: {
-    selection: (string | number)[] | null;
+    /**
+     * The selected document paths, in the order the user built them (§6.5).
+     *
+     * `[]` is "nothing selected" — there is no `null` state, because "no selection" and "a
+     * selection of nothing" were never two different things. `selection[0]` is the anchor a
+     * shift-range extends from; the LAST entry is the primary, which every single-target surface
+     * reads through `tabs/selection.ts`'s `primarySelection`. **Always assign a fresh array**:
+     * several render effects track this with a bare property read and would miss an in-place push.
+     */
+    selection: (string | number)[][];
     hover: (string | number)[] | null;
     clipboard: JxMutableNode | null;
-    documentStack: DocumentStackEntry[];
+    /** The document this tab was drilled in from, if any. Rendered by the tab strip. */
+    openedFrom: TabOrigin | null;
     ui: TabUi;
     canvas: {
       status: string;
+      /**
+       * A Refresh is out and the snapshot below has not come back yet.
+       *
+       * The button used to guess: fire the re-render, then `setTimeout(…, 200)` and repaint,
+       * because nothing told the panel when the values had actually changed. A fetch slower than
+       * 200ms repainted the OLD values and looked like a Refresh that did nothing. The iframe posts
+       * `dataScope` when the render resolves, so the honest answer is to say "refreshing" until it
+       * arrives and let the arrival be the repaint.
+       */
+      refreshing: boolean;
       // A serializable snapshot of the iframe's resolved `$defs` (data-source values), posted over
       // The bridge as a `dataScope` message and read by the data-explorer panel. Plain data now —
       // The old live `EffectScope` (with `.stop()`) moved into the iframe realm with buildScope.
@@ -160,30 +221,20 @@ function createDefaultUi(canvasMode: string, preview = false) {
     editingFormula: null,
     editingFunction: null,
     featureToggles: {},
-    frontmatterOpen: true,
-    gitBranches: null,
-    gitCommitMessage: "",
-    gitDiffState: null,
-    gitError: null,
-    gitLoading: false,
-    gitStatus: null,
     inspectorSections: {},
     pendingInlineEdit: null,
     preview,
     previewColorScheme: "auto" as const,
+    previewLocale: null as string | null,
     previewParams: {},
     previewProps: null,
     rightTab: "properties",
-    settingsTab: "stylebook",
     showLayout: true,
     styleFilter: "",
-    styleFilterActive: false,
     styleSections: {},
+    dataRows: {},
+    dataLimits: {},
     styleShorthands: {},
-    stylebookCustomizedOnly: false,
-    stylebookFilter: "",
-    stylebookSelection: null,
-    stylebookTab: "elements",
     zoom: 1,
   };
 }
@@ -201,6 +252,8 @@ const ALL_MODES = ["edit", "design", "preview", "source", "stylebook"];
  *   frontmatter?: Record<string, unknown>;
  *   sourceFormat?: string | null;
  *   capabilities?: { modes?: string[] };
+ *   openedFrom?: TabOrigin | null;
+ *   preview?: boolean;
  * }} opts
  * @returns {Tab}
  */
@@ -212,6 +265,8 @@ export function createTab({
   frontmatter,
   sourceFormat = null,
   capabilities,
+  openedFrom = null,
+  preview: previewTab = false,
 }: {
   id: string;
   documentPath?: string | null;
@@ -220,6 +275,8 @@ export function createTab({
   frontmatter?: Record<string, unknown>;
   sourceFormat?: string | null;
   capabilities?: { modes?: string[] };
+  openedFrom?: TabOrigin | null;
+  preview?: boolean;
 }) {
   const scope = effectScope();
 
@@ -249,12 +306,15 @@ export function createTab({
     fileHandle,
     history: reactive({
       index: 0,
-      snapshots: [{ document: structuredClone(document), selection: null }],
+      snapshots: [{ document: structuredClone(document), selection: [] }],
     }),
     id,
+    pinned: false,
+    preview: previewTab,
     scope,
     session: reactive({
       canvas: {
+        refreshing: false,
         error: null,
         livePreviews: null,
         pendingInlineEdit: null,
@@ -262,9 +322,9 @@ export function createTab({
         status: "idle",
       },
       clipboard: null,
-      documentStack: [],
       hover: null,
-      selection: null,
+      openedFrom,
+      selection: [],
       ui: createDefaultUi(initialCanvasMode, initialPreview),
     }),
   })) as unknown as Tab;
@@ -281,7 +341,7 @@ export function createTab({
  * @returns {string[]}
  */
 function inferModes(documentPath: string | null | undefined, sourceFormat: string | null) {
-  if (documentPath === "project.json") {
+  if (documentPath === PROJECT_CONFIG_PATH) {
     return ["stylebook", "source"];
   }
   const format = formatByName(sourceFormat) ?? formatForPath(documentPath);
@@ -307,6 +367,81 @@ function inferDocumentMode(documentPath: string | null | undefined, sourceFormat
   return "component";
 }
 
+// ─── Editor kinds ─────────────────────────────────────────────────────────────
+// §4.2's first axis. `canvasMode` conflates two orthogonal questions — WHICH EDITOR is open, and
+// (for the Canvas editor only) WHICH VIEW of it. The pane context bar labels them separately, and
+// The pane model needs the first one on its own: the second pane is capped to non-Canvas kinds
+// Until P8's `canvas-patcher` fan-out lands, because a second live `@jxsuite/runtime` host is the
+// Expensive part.
+//
+// The mode → kind map itself is `commands/context.ts`'s `editorKindForMode`. It was duplicated
+// Here, and the copy that drifted is what let a settings document resolve into the canvas key
+// Scope; the pane model and the command context now read the same table.
+
+/**
+ * The editor kind a tab is currently showing. Reads the BASE mode: the preview toggle is a value on
+ * the Canvas view axis, not a different editor.
+ *
+ * @param {Tab} tab
+ * @returns {EditorKind}
+ */
+export function editorKindOf(tab: Tab): EditorKind {
+  return editorKindForMode(tab.session.ui.canvasMode);
+}
+
+/**
+ * Every editor kind this document supports, in the format's own mode order and deduplicated — the
+ * dropdown's entries, so it can never contain a permanently dead one (§4.2).
+ *
+ * `preview` contributes nothing: it is a Canvas VIEW, and the kind it would add is already there.
+ *
+ * @param {Tab} tab
+ * @returns {EditorKind[]}
+ */
+export function editorKindsOf(tab: Tab): EditorKind[] {
+  const kinds: EditorKind[] = [];
+  for (const mode of tab.capabilities.modes) {
+    if (mode === "preview") {
+      continue;
+    }
+    const kind = editorKindForMode(mode);
+    if (!kinds.includes(kind)) {
+      kinds.push(kind);
+    }
+  }
+  return kinds;
+}
+
+/**
+ * The first mode this tab supports that renders `kind`, or `undefined` when it supports none.
+ *
+ * The inverse of {@link editorKindOf}: choosing an editor kind has to land on a real `canvasMode`,
+ * because that string is what the canvas render message carries.
+ *
+ * @param {Tab} tab
+ * @param {EditorKind} kind
+ * @returns {string | undefined}
+ */
+export function modeForEditorKind(tab: Tab, kind: EditorKind): string | undefined {
+  return tab.capabilities.modes.find(
+    (mode) => mode !== "preview" && editorKindForMode(mode) === kind,
+  );
+}
+
+// ─── There is no sub-document stack ───────────────────────────────────────────
+// A tab held one, and it was scaffolding for a navigation model the tab model replaced. `studio.md`
+// §14.3 justified it for exactly two cases and both moved: a function body opens in the Bottom
+// Dock's Logic tab (P8), and a `$map` template is a subtree of its parent document, selected in
+// Place on the canvas rather than loaded as a document of its own. Everything with a file of its
+// Own — a component, a layout — opens a REAL TAB with an `openedFrom` relationship (§14.1–2):
+// {@link TabOrigin}, above, which nothing pops and nothing restores from.
+//
+// So `pushSubDocument` had no caller in `src/`, the stack was permanently `[]`, and every reader
+// Below it — `popSubDocument`, `popToSubDocument`, the UI capture/restore pair, the pane-context
+// Breadcrumb, the jump bar's `subdocument` segment, `document.setStackLevel`, collab's `drilled`
+// Guard — was live code that could only ever take its empty branch. They are gone together: a
+// Stack with no way in is not an unfinished feature, it is a shape the design moved past.
+
 /**
  * Dispose a tab — stops its effectScope, killing all effects created within it.
  *