@jxsuite/studio 5.2.0 → 5.4.0

package/src/collab/collab-session.ts

@@ -37,7 +37,7 @@ import { PROJECT_CONFIG_PATH } from "../tabs/tab";
 import type { TransactOrigin } from "../tabs/transact";
 import type { TransactionRecord } from "../tabs/patch-ops";
 import type { Tab } from "../tabs/tab";
-import type { JxDocOp } from "@jxsuite/collab/ops";
+import type { JxDocOp } from "@jxsuite/schema/doc-ops";
 import type { CollabHandle } from "@jxsuite/collab/provider";
 import type { JxMutableNode } from "@jxsuite/schema/types";
 import type * as CollabNS from "@jxsuite/collab";
@@ -664,7 +664,7 @@ export function ensureCollab(tab: Tab): void {
 
 /**
  * Join or leave this document's collaboration session — the idempotent setter behind `Collaborate:
- * Share this document` and `Collaborate: Stop sharing` (§7.4).
+ * Share this document` and `Collaborate: Stop sharing` (collab.md §4).
  *
  * Leaving sets a flag the watcher effect reads rather than calling `detachSession` directly, so the
  * effect remains the one owner of the session lifecycle and re-joining is the same call with the
@@ -709,7 +709,7 @@ async function attachSession(tab: Tab): Promise<void> {
   const platform = maybePlatform();
   if (!path || !platform?.collab) {
     /* Not a failure and not a session: this build/platform has no collaboration to offer. Saying
-       so is the difference between "nobody else is here" and "something broke" (§7.4). */
+       so is the difference between "nobody else is here" and "something broke" (collab.md §4). */
     collabState(tab).status = "unavailable";
     return;
   }
@@ -753,7 +753,7 @@ async function attachSession(tab: Tab): Promise<void> {
     } catch (error) {
       /* An attach that threw is a FAILURE, and it used to be reported as "detached" — the same
          value a solo document carries. A relay that is down, a token that expired and a document
-         nobody shared were one indistinguishable state (§7.4). */
+         nobody shared were one indistinguishable state (collab.md §4). */
       state.status = "failed";
       state.active = false;
       state.attachError = error instanceof Error ? error.message : String(error);

package/src/collab/collab-state.ts

@@ -13,9 +13,9 @@ import type { CollabAwarenessState } from "@jxsuite/collab/awareness-types";
  *
  * `"detached"` used to mean three different things at once and say none of them: this build has no
  * collaboration at all, this project has collaboration but this tab is solo, and the attach was
- * tried and it FAILED. §7.4: a freeze is currently indistinguishable from a bug, and so was a
- * broken connection. `"unavailable"` and `"failed"` split the third and first cases out, so the
- * chip can say which one it is.
+ * tried and it FAILED. A freeze was indistinguishable from a bug, and so was a broken connection
+ * (collab.md §4). `"unavailable"` and `"failed"` split the third and first cases out, so the chip
+ * can say which one it is.
  */
 export type CollabTabStatus =
   | "unavailable"
@@ -42,7 +42,7 @@ export interface TabCollabState {
    * surfaces soft-freeze and the canvas previews the source reconciler's parses.
    *
    * The freeze is real and it is brief, and until now its only rendering was a grey line for three
-   * seconds — which is exactly what a bug looks like. It gets an indicator (§7.4).
+   * seconds — which is exactly what a bug looks like. It gets an indicator (collab.md §4).
    */
   sourceCanonical: boolean;
   /**

package/src/collab/presence-chips.ts

@@ -1,6 +1,6 @@
 /**
  * Presence chips — who else is in this co-editing session, the sync-status pill that replaces the
- * dirty dot for collab tabs, and the two states co-editing had no way to announce (§7.4).
+ * dirty dot for collab tabs, and the two states co-editing had no way to announce (collab.md §4).
  *
  * Pure projections of `collabState(tab)`: the Command Bar surface draws the cluster and the pane's
  * own chrome draws the banner, and both are documents, so nothing here renders.
@@ -22,8 +22,8 @@
  *
  * **Undo says what it does.** The Y.UndoManager is constructed with `trackedOrigins:
  * {LOCAL_ORIGIN}`, so ⌘Z reaches your own actions and never a peer's. That is the correct behaviour
- * and it is also surprising, so the status pill's title states it — §13 lists this as adopted
- * precisely because silently undoing someone else's work is worse than not undoing.
+ * and it is also surprising, so the status pill's title states it (collab.md §4). The scoping is
+ * deliberate: silently undoing someone else's work is worse than not undoing.
  */
 
 import { collabState } from "./collab-state";

package/src/commands/app-commands.ts

@@ -8,12 +8,12 @@
  * process with no DOM and no bootstrap, and each looks for one export — `defaultCommandSet()`.
  *
  * Without this module those three checks see only `commands/defaults.ts`'s sixteen records, which
- * is why plan §13.5's headline promise was not yet true: a manifest step naming `view.setActivity`
- * with a panel id the registry does not declare sailed through Lane 1, because Lane 1 could not
- * load the record that declares the enum. Every module gathered below imports cleanly with no
- * `document` and no `localStorage` write, which is the ONLY property this file requires of them —
- * and the test beside it asserts exactly that, so a future DOM read at module scope fails here
- * rather than in CI.
+ * is why the screenshot gate's headline promise (`scripts/screenshots/README.md`, "The gate") was
+ * not yet true: a manifest step naming `view.setActivity` with a panel id the registry does not
+ * declare sailed through Lane 1, because Lane 1 could not load the record that declares the enum.
+ * Every module gathered below imports cleanly with no `document` and no `localStorage` write, which
+ * is the ONLY property this file requires of them — and the test beside it asserts exactly that, so
+ * a future DOM read at module scope fails here rather than in CI.
  *
  * **Deps are the no-op set.** Nothing here runs a command; the checks read `id`, `level`, `menus`
  * and `args`. Passing real implementations would mean importing the app.
@@ -136,7 +136,7 @@ export function appCommandSet(): AnyCommand[] {
     // And none reached the palette, because they were registered ONLY into the private registry
     // `editor/context-menu.ts` builds for its popover — a registry whose own docstring said it
     // Existed "until a bootstrap composes every contribution point into a single app-wide
-    // Registry". This is that bootstrap; it has existed since P2.
+    // Registry". This is that bootstrap; it has existed since the command registry landed.
     ...liveElementCommands(),
     ...dataExplorerCommands({ renderLeftPanel: NO_OP }),
     ...signalsCommands(),

package/src/commands/budget.ts

@@ -1,26 +1,27 @@
 /**
  * Budget.ts — chrome is earned by frequency and capped by a build check.
  *
- * Plan §2, principle 9: at most five commands may declare `menus: ["commandbar/primary"]`, and at
- * most four tabs per dock. `scripts/check-chrome-budget.ts` fails CI otherwise, which is what turns
- * "we should keep the toolbar small" from a code-review opinion into a build error.
+ * The chrome budget, studio-ui-guidelines.md §12.2: at most five commands may declare `menus:
+ * ["commandbar/primary"]`, and at most four tabs per dock. `scripts/check-chrome-budget.ts` fails
+ * CI otherwise, which is what turns "we should keep the toolbar small" from a code-review opinion
+ * into a build error.
  *
  * The cap is not arbitrary. The toolbar's own CSS already admits it is over budget — a container
  * query at 1140px strips every `.tb-label` rather than conceding there are too many controls — and
  * an unlabelled icon is a control the user has to hover to identify. A hard number is what makes
  * "retire this control, keep its name and its chord" the cheap option.
  *
- * The dock/tab sets used to be a flat declaration — written out from §3.2 because `registerPanel()`
- * did not exist. It does now, so the two `rail/*` rows are a QUERY over `railDeclarations()`
- * ({@link dockTabs}) and adding a ninth rail panel fails this check without anyone remembering to
- * update a list. The two rows that remain declared are the two docks whose tab sets this module
- * cannot see from a bare Bun process: the Inspector's four come from `commands/defaults.ts`'s
- * `INSPECTOR_TABS` (a query in all but name), and the Bottom dock's four are records in
- * `panels/bottom-dock.ts`, which renders lit templates and therefore cannot be imported here.
- * `tests/bottom-dock.test.ts` asserts the declared row and the registered set are the same four
- * titles, so the copy cannot drift — the same bargain `tests/right-panel.test.ts` strikes for the
- * Inspector. Both become real queries the day `scripts/check-chrome-budget.ts` joins them the way
- * it already joins the rail.
+ * The dock/tab sets used to be a flat declaration — written out by hand from the shell redesign's
+ * region table, because `registerPanel()` did not exist. It does now, so the two `rail/*` rows are
+ * a QUERY over `railDeclarations()` ({@link dockTabs}) and adding a ninth rail panel fails this
+ * check without anyone remembering to update a list. The two rows that remain declared are the two
+ * docks whose tab sets this module cannot see from a bare Bun process: the Inspector's four come
+ * from `commands/defaults.ts`'s `INSPECTOR_TABS` (a query in all but name), and the Bottom dock's
+ * four are records in `panels/bottom-dock.ts`, which renders lit templates and therefore cannot be
+ * imported here. `tests/bottom-dock.test.ts` asserts the declared row and the registered set are
+ * the same four titles, so the copy cannot drift — the same bargain `tests/right-panel.test.ts`
+ * strikes for the Inspector. Both become real queries the day `scripts/check-chrome-budget.ts`
+ * joins them the way it already joins the rail.
  */
 
 import { INSPECTOR_TABS } from "./defaults";
@@ -46,7 +47,7 @@ export const CHROME_BUDGET = {
    *
    * A prompt is chrome for a model: every tool costs attention, and issue 273's finding was that a
    * naive projection of every declaration would have taken the list from 22 to 67. Thirty is
-   * headroom over today's 28 (19 hand + 9 projected), not a target. Asserted in
+   * headroom over today's 29 (18 hand + 11 projected), not a target. Asserted in
    * `tests/ai-command-tools.test.ts` rather than `scripts/check-chrome-budget.ts`, because the hand
    * table lives in `ai-system-prompt.ts`, which imports `../store.js` and is not bare-Bun loadable;
    * the number lives here either way, and raising it is a design decision.
@@ -56,7 +57,7 @@ export const CHROME_BUDGET = {
 
 /** One tabbed region and what it currently hosts. */
 export interface DockDeclaration {
-  /** Region key as §3.2 names it. Rail groups count separately — they are separate placements. */
+  /** Region key. Rail groups count separately — they are separate placements. */
   dock: string;
   tabs: readonly string[];
 }

package/src/commands/command-args.ts

@@ -1,9 +1,9 @@
 /**
  * Command-args.ts — loud coercion for the arguments a command record declares.
  *
- * Every scriptable command carries an `args` JSON Schema (spec §13.1, plan §13.3): the palette
- * prompts from it, the AI tool's parameters are it, and `scripts/check-shot-contract.ts` validates
- * every manifest step against it in the `checks` job. This module is the RUNTIME half of that same
+ * Every scriptable command carries an `args` JSON Schema (studio.md §13.1): the palette prompts
+ * from it, the AI tool's parameters are it, and `scripts/check-shot-contract.ts` validates every
+ * manifest step against it in the `checks` job. This module is the RUNTIME half of that same
  * declaration, twice over: the typed readers a `run` body calls (`stringArg(...)` and its family),
  * and {@link coerceArgs}, which `registry.run` applies to the received record BEFORE `run` for
  * every caller — the palette, `__jxAutomation`, the assistant and a chord alike. The coercion
@@ -16,11 +16,12 @@
  * 1. **Reject loudly, never clamp.** An unknown panel id, a mode the tab cannot enter, a selection
  *    path that is not in the document — each throws. A no-op would photograph the previous state
  *    and a docs build would accept it; a clamp would photograph a state the caller did not ask for.
- *    Plan §13.4 makes this a tested property.
+ *    The shot contract (`scripts/screenshots/README.md`, `steps`) makes this a tested property.
  * 2. **The failure names the fix.** `{@link enumArg}` prints the declared values, which is what makes
- *    §13.5's headline failure — _manifest shot "properties-bar" names panel "head"; the registry
- *    declares "page"_ — a sentence a reader can act on rather than a stack trace. Nothing else in
- *    this file matters as much as that message.
+ *    the screenshot gate's headline failure (`scripts/screenshots/README.md`, "The gate") —
+ *    _manifest shot "properties-bar" names panel "head"; the registry declares "page"_ — a sentence
+ *    a reader can act on rather than a stack trace. Nothing else in this file matters as much as
+ *    that message.
  *
  * `RangeError` (not a bespoke class) because `services/profile.ts` already throws it for exactly
  * this — an id outside a declared set — and one refusal shape is easier to catch than two.
@@ -185,7 +186,7 @@ export function nullablePathArg(
 }
 
 /**
- * A LIST of document paths — the whole selection set (§6.5).
+ * A LIST of document paths — the whole selection set (§6.7).
  *
  * Every element is validated as a path, so a caller that passes one bare path by mistake
  * (`["children", 0]` rather than `[["children", 0]]`) is refused by name instead of selecting two
@@ -218,7 +219,7 @@ export function pathListArg(
 
 // ─── Schema fragments ─────────────────────────────────────────────────────────
 // The readers above are what a `run` body calls; these are the same facts in the form the palette
-// Prompt, the AI tool's parameter list and Lane 1's static check read. The pair used to be kept
+// Prompt, the AI tool's parameter list and the shot-contract check read. The pair used to be kept
 // Adjacent so a reviewer could see that a schema agreed with its coercion; `coerceArgs` below made
 // Them ONE call site, so a schema that disagrees with its coercion is now a refusal rather than a
 // Defect a reviewer has to spot — which is what this module exists to prevent.

package/src/commands/context.ts

@@ -1,11 +1,11 @@
 /**
  * Context.ts — the record every `when` / `enablement` predicate closes over.
  *
- * One flat-ish record of the facts a command can be gated on (UX-REDESIGN-PLAN §5.2). Predicates
+ * One flat-ish record of the facts a command can be gated on (specs/studio.md §13.4). Predicates
  * are plain closures over this record — the shape `services/gated-registry.ts` already ships for
- * the AI's tools — not a serialisable string DSL. §13 rejects the DSL explicitly: a `"project.open
- * && editor.kind == 'canvas'"` grammar needs a tokenizer, a parser and a reactive evaluator to buy
- * serialisability nothing in Studio consumes.
+ * the AI's tools — not a serialisable string DSL, which the shell redesign rejected explicitly: a
+ * `"project.open && editor.kind == 'canvas'"` grammar needs a tokenizer, a parser and a reactive
+ * evaluator to buy serialisability nothing in Studio consumes.
  *
  * This module owns the SHAPE and a pure builder. It deliberately imports nothing from the state
  * modules: the registry takes a `getContext()` thunk, so wiring the live sources (the reactive
@@ -32,6 +32,9 @@ export const CAPABILITIES = [
   "dataRows",
   "windowControls",
   "findReferences",
+  /* The image editor's gate. A backend that cannot hand Studio a project file's raw bytes cannot
+     decode one, so the Image mode is not offered at all rather than offered and then failing. */
+  "readFileBytes",
 ] as const;
 
 export type Capability = (typeof CAPABILITIES)[number];
@@ -182,7 +185,7 @@ export interface CommandContext {
   selection: {
     count: number;
     /**
-     * The selected document paths, in selection order — `[]` when nothing is selected (§6.5).
+     * The selected document paths, in selection order — `[]` when nothing is selected (§6.7).
      *
      * The context is what `probe.state()` answers with, so this is how a script, a screenshot step
      * or the assistant READS a multi-selection back. `count` is its length; the last entry is the
@@ -237,13 +240,19 @@ export interface CommandContext {
   };
   ai: {
     configured: boolean;
+    /**
+     * A turn is in flight: from an accepted send until its loop ends, with its tools, its questions
+     * and its imports included (specs/ai.md §3.0). Not the token stream, which the chat's own
+     * status reports and which reads idle whenever the turn's tools are running.
+     */
     streaming: boolean;
     /**
      * A turn is suspended on an `ask_user` question.
      *
-     * Distinct from `streaming` rather than folded into it: no tokens are moving, so a surface that
-     * paints a spinner on `streaming` must not paint one here — but the turn is alive and holding a
-     * tool open, so Stop is enabled on the union of the two.
+     * Always inside a turn, so `streaming` holds too. Kept as its own fact for `when` predicates
+     * and the live-context probe: while a question waits, a send is its answer rather than a new
+     * turn (the composer reads the same fact straight from `panels/ai-panel.ts`). Stop's union with
+     * it is the same thing as `streaming`.
      */
     waiting: boolean;
   };
@@ -309,6 +318,7 @@ export function emptyContext(): CommandContext {
       dataRows: false,
       windowControls: false,
       findReferences: false,
+      readFileBytes: false,
     },
   };
 }
@@ -358,8 +368,8 @@ const GLOBAL_STACK: readonly KeyScope[] = ["global"];
 /**
  * The scope stack for the current context, narrowest scope first.
  *
- * The ladder is `caret > grid/code engine > focused dock > global` (plan §5.3), and the whole point
- * is that a scope which is not on the stack cannot fire AT ALL. Three hand-written guards collapse
+ * The ladder is `caret > grid/code engine > focused dock > global` (§13.3), and the whole point is
+ * that a scope which is not on the stack cannot fire AT ALL. Three hand-written guards collapse
  * into it:
  *
  * - The blanket modal return → the `palette`-only stack;

package/src/commands/defaults.ts

@@ -21,7 +21,8 @@
  *   print — one sentence, three consumers.
  *
  * The primary Command Bar cluster is capped at five by `scripts/check-chrome-budget.ts`; four are
- * spent here (Save, Undo, Redo, Open in Browser) exactly as plan §3.2 region ① specifies.
+ * spent here (Save, Undo, Redo, Open in Browser), exactly the four studio-ui-guidelines.md §12.1
+ * admits to `commandbar/primary` at document level.
  */
 
 import { isSpliceablePath } from "../tabs/selection";
@@ -41,10 +42,10 @@ import type { CommandContext } from "./context";
 export type DockId = "navigator" | "inspector" | "bottom";
 
 /**
- * Palette modes, echoed as a removable chip in the input (plan §5.4).
+ * Palette modes, echoed as a removable chip in the input.
  *
  * The value space is the palette's namespace, declared once here so a new mode is a new member
- * rather than a new widget: P4's Problems and P7's content search slot in beside these.
+ * rather than a new widget: a Problems mode or a content search slots in beside these.
  */
 export type PaletteMode = "picker" | "files" | "commands" | "nodes" | "projects";
 
@@ -68,15 +69,14 @@ export interface RailPanel {
   when?: (ctx: CommandContext) => boolean;
 }
 
-/** How many rail panels get a ⌘N. §3.2 ② spends exactly this many slots, four per level group. */
+/** How many rail panels get a ⌘N: the Navigator rail (§5.1) spends four per level group. */
 export const RAIL_CHORD_LIMIT = 8;
 
 /**
- * The Inspector's four tabs, in the order §3.2 ⑨ names them — which is the order ⌘⇧1–4 follow.
+ * The Inspector's four tabs, in the order §6 names them — which is the order ⌘⇧1–4 follow.
  *
- * `"assistant"` is a different dock (it is the Inspector's second instance until P3.6 folds the
- * column in), so it is not one of `shell.ts`'s `INSPECTOR_TAB_IDS`; the chord still belongs in the
- * same run of four, because a user counting tabs does not know that.
+ * `"assistant"` is the fourth tab, not a dock of its own (there is no assistant column, §3.1), so
+ * it is one of `shell.ts`'s `INSPECTOR_TAB_IDS` like the other three.
  */
 export interface InspectorTab {
   /** The stored `session.ui.rightTab` value, or `"assistant"` for the assistant dock. */
@@ -130,9 +130,9 @@ export interface CommandDeps {
    */
   panelRoster: readonly RailPanel[];
   /**
-   * Toggle-FOCUS a panel (plan §5.3): reveal it and take focus, or — when it already has focus —
-   * collapse the dock hosting it and hand focus back to the pane. Deliberately not toggle-visible:
-   * ⌘1 pressed from the canvas must land you in Files, not close it.
+   * Toggle-FOCUS a panel: reveal it and take focus, or — when it already has focus — collapse the
+   * dock hosting it and hand focus back to the pane. Deliberately not toggle-visible: ⌘1 pressed
+   * from the canvas must land you in Files, not close it.
    */
   focusPanel: (panelId: string) => void;
   /** Show an Inspector tab and focus the dock. `"assistant"` addresses the assistant dock. */
@@ -202,11 +202,11 @@ const structurallyEditable = (ctx: CommandContext) =>
 /**
  * The one sentence for {@link structurallyEditable}, read by Delete and Duplicate both.
  *
- * It names the gate the predicate actually has (§12.4's corollary): the old sentences said "not the
- * document root" and "has a sibling position" for a gate that also refuses a repeater's template
- * and a `$switch` case, which sent a reader who had selected a template looking for a root. Two
- * records with one predicate carry one sentence, because the tooltip, the palette subtitle and the
- * assistant's refusal are all this string.
+ * It names the gate the predicate actually has (studio-ui-guidelines.md §12.4's corollary): the old
+ * sentences said "not the document root" and "has a sibling position" for a gate that also refuses
+ * a repeater's template and a `$switch` case, which sent a reader who had selected a template
+ * looking for a root. Two records with one predicate carry one sentence, because the tooltip, the
+ * palette subtitle and the assistant's refusal are all this string.
  */
 const SPLICEABLE_SELECTION =
   "an element selected on the canvas that has a sibling position: not the document root, a " +
@@ -278,7 +278,7 @@ export function defaultCommands(deps: CommandDeps): AnyCommand[] {
        * the build keeps a command of its own rather than disappearing with the coupling.
        *
        * `commandbar/overflow` rather than `commandbar/primary`: the primary row is budgeted at five
-       * and is document-level by frequency (studio-ui-guidelines §12), and a build is neither
+       * and is document-level by frequency (studio-ui-guidelines.md §12), and a build is neither
        * frequent nor about the document in front of you. No default chord for the same reason.
        */
       id: "project.buildSite",
@@ -373,10 +373,11 @@ export function defaultCommands(deps: CommandDeps): AnyCommand[] {
       enablement: (ctx) => structurallyEditable(ctx) && !ctx.selection.isRepeater,
       requires: "an element with a sibling position that is not already a repeater",
       /*
-       * No `aiTool`, by §12.4's second deletion rule: `run` waits on a person. The dialog picks the
-       * collection, and a projected call would suspend the agent's turn on it while the loop counts
-       * the round as work; a cancel returns nothing a report could describe. A record with a
-       * `collection` argument that skips the dialog would be the way back in, and is a UX call.
+       * No `aiTool`, by studio-ui-guidelines.md §12.4's second deletion rule: `run` waits on a
+       * person. The dialog picks the collection, and a projected call would suspend the agent's
+       * turn on it while the loop counts the round as work; a cancel returns nothing a report could
+       * describe. A record with a `collection` argument that skips the dialog would be the way back
+       * in, and is a UX call.
        *
        * The one record here whose implementation is not injected, and the reason is a property of
        * the implementation rather than of this record: `convertToRepeater()` is self-contained —
@@ -540,11 +541,11 @@ export function defaultCommands(deps: CommandDeps): AnyCommand[] {
       /*
        * The other half of multi-window, and the half that had no door.
        *
-       * "Open a project ELSEWHERE" is reachable from Open Project and from Recents (§4.2a); "open
-       * an EMPTY window" was reachable only from the ElectroBun launcher's native application menu
-       * — so on a launcher whose window has no menu bar, `newWindow` existed on the platform and
-       * could not be run. Gated on the same capability every other multi-window verb is, so a host
-       * with one window does not offer it.
+       * "Open a project ELSEWHERE" is reachable from Open Project and from Recents
+       * (desktop.md §4.2a); "open an EMPTY window" was reachable only from the ElectroBun
+       * launcher's native application menu — so on a launcher whose window has no menu bar,
+       * `newWindow` existed on the platform and could not be run. Gated on the same capability
+       * every other multi-window verb is, so a host with one window does not offer it.
        */
       id: "view.newWindow",
       title: "New Window",
@@ -559,7 +560,7 @@ export function defaultCommands(deps: CommandDeps): AnyCommand[] {
     },
     {
       // The no-project palette stops being a hidden domain swap on `!projectState` and becomes a
-      // NAMED mode that works either way (plan §5.4) — same trigger, same chrome, stated feature.
+      // NAMED mode that works either way — same trigger, same chrome, stated feature.
       id: "project.openRecent",
       title: "Open Recent…",
       category: "Project",
@@ -569,7 +570,7 @@ export function defaultCommands(deps: CommandDeps): AnyCommand[] {
       run: () => deps.openPalette("projects"),
     },
 
-    // ── Direct keys (plan §5.3) ──
+    // ── Direct keys ──
     ...panelFocusCommands(deps),
     ...inspectorFocusCommands(deps),
     {
@@ -602,7 +603,7 @@ export function defaultCommands(deps: CommandDeps): AnyCommand[] {
  * Generated rather than written out eight times for the reason the whole registry exists: the rail,
  * the chord, the palette row and the generated shortcut sheet are then four renderings of one list.
  * Only the first eight get a chord; a ninth panel keeps its name and its palette row, which is the
- * cost §2 principle 9 puts on chrome.
+ * cost studio-ui-guidelines.md §12.2 puts on chrome.
  */
 export function panelFocusCommands(deps: CommandDeps): AnyCommand[] {
   let chordsSpent = 0;

package/src/commands/levels.ts

@@ -1,7 +1,8 @@
 /**
  * Levels.ts — the containment taxonomy and the level × placement matrix.
  *
- * Two vocabularies live here, and keeping them apart is the whole point (UX-REDESIGN-PLAN §5.1):
+ * Two vocabularies live here, and keeping them apart is the whole point (specs/studio.md
+ * §13.2–§13.3):
  *
  * - {@link Level} answers WHAT a record acts on. It governs placement and is CI-checked.
  * - {@link KeyScope} answers WHERE a chord is live. It governs keyboard dispatch only.
@@ -150,9 +151,10 @@ export const PLACEMENT_MATRIX: Readonly<Record<Placement, PlacementRule>> = {
 /**
  * Every surface a Panel record may occupy.
  *
- * The rail's two level groups are SEPARATE placements, not one "mixed" region — principle 2's whole
- * point. `navigator` is the dock body below them, which hosts whichever panel the rail selected and
- * prints that panel's level in its header, so it is the one panel placement admitting two levels.
+ * The rail's two level groups are SEPARATE placements, not one "mixed" region — the whole point of
+ * the level × placement matrix (studio-ui-guidelines.md §12.1). `navigator` is the dock body below
+ * them, which hosts whichever panel the rail selected and prints that panel's level in its header,
+ * so it is the one panel placement admitting two levels.
  */
 export const PANEL_PLACEMENTS = [
   "rail/project",
@@ -169,7 +171,7 @@ export type PanelPlacement = (typeof PANEL_PLACEMENTS)[number];
  * `studio-ui-guidelines.md` §12 beside {@link PLACEMENT_MATRIX}.
  *
  * The rail rows are what stop it re-accreting: a panel cannot be filed in the PROJECT group because
- * "it feels project-ish", only because the state it WRITES is the project's (principle 3).
+ * "it feels project-ish", only because the state it WRITES is the project's (§13.2).
  */
 export const PANEL_PLACEMENT_MATRIX: Readonly<Record<PanelPlacement, PlacementRule>> = {
   "rail/project": {
@@ -215,7 +217,7 @@ function dockPlacement(dock: PlaceablePanel["dock"]): PanelPlacement {
  * Every placement a Panel record occupies: its dock body, plus its rail group when it has a button.
  *
  * The rail group is DERIVED from the level rather than declared, which is what makes "grouped by
- * level with a divider" (§3.2 ②) a property of the data instead of an ordering convention in the
+ * level with a divider" (§5.1) a property of the data instead of an ordering convention in the
  * rail's template. A rail panel whose level has no group (`application`, `selection`) therefore
  * names a placement the matrix does not contain, and is rejected below.
  */

package/src/commands/live-context.ts

@@ -65,7 +65,7 @@ export function isTextEntryFocused(doc: Document = document): boolean {
 export interface LiveContextSources {
   /** `studio.ts`'s `getCanvasMode()` — the per-tab preview toggle already composed in. */
   canvasMode: () => string;
-  /** `canvas/iframe-host.ts`'s bridge-derived caret flag (P1). */
+  /** `canvas/iframe-host.ts`'s bridge-derived caret flag (§10). */
   isCaretActive: () => boolean;
   /** `ui/layers.ts`'s `isModalOpen()`. */
   isModalOpen: () => boolean;
@@ -74,8 +74,9 @@ export interface LiveContextSources {
   /** Whether the assistant has usable credentials (`services/ai-models`). */
   aiConfigured: () => boolean;
   /**
-   * Whether the assistant is mid-stream. `panels/ai-panel.ts` keeps its `DocumentAssistant` module-
-   * private, so there is nothing to read yet; the caller passes a probe when one exists.
+   * Whether an assistant turn is in flight, tools and questions included. `panels/ai-panel.ts`
+   * keeps its `DocumentAssistant` module-private, so the caller passes its probe
+   * (`isAssistantStreaming`).
    */
   aiStreaming?: () => boolean;
   /** Whether a turn is suspended on an `ask_user` question (`panels/ai-panel.ts`). */
@@ -93,6 +94,7 @@ function capabilities(platform: StudioPlatform | null): CommandContext["capabili
     gitClone: has("gitClone"),
     importSite: has("importSite"),
     openProjectInNewWindow: has("openProjectInNewWindow"),
+    readFileBytes: has("readFileBytes"),
     // Multi-window is a desktop-only family; `newWindow` is the one every member implies.
     windowControls: has("newWindow"),
   };
@@ -138,13 +140,13 @@ export function createLiveContext(sources: LiveContextSources): () => CommandCon
 
     ctx.editor.kind = tab ? editorKindForMode(mode) : "none";
     ctx.canvas.view = canvasViewForMode(mode);
-    /* The grid, counted from the grid. This read spent two phases saying "panes land in P3; until
-       then the grid is one pane showing the focused tab" — through P3, which built the pane model,
-       and through P8, which gave every pane a live stage. It counted `workspace.tabOrder`, the
-       FOCUSED pane's strip, so it could never answer 2 and answered 0 whenever no tab was open,
-       while a pane with no tab is still a pane. `derived` was declared and never assigned at all.
-       `services/automation.ts` publishes this whole record as `probe.state()`, so the screenshot
-       pipeline and the assistant were both reading it.
+    /* The grid, counted from the grid. This read spent two phases saying that until panes landed
+       the grid was one pane showing the focused tab — through the shell redesign's chrome phase,
+       which built the pane model, and through its panes phase, which gave every pane a live stage.
+       It counted `workspace.tabOrder`, the FOCUSED pane's strip, so it could never answer 2 and
+       answered 0 whenever no tab was open, while a pane with no tab is still a pane. `derived` was
+       declared and never assigned at all. `services/automation.ts` publishes this whole record as
+       `probe.state()`, so the screenshot pipeline and the assistant were both reading it.
 
        `derived` is ASSIGNED now, and it means "the grid contains a derived pane" — the fact the two
        predicates that need it actually ask. A third phase of a declared-never-assigned context key

package/src/commands/reference.ts

@@ -1,11 +1,11 @@
 /**
  * Reference.ts — the registry, projected into the two generated documentation pages.
  *
- * Plan §12 P3 lists `docs/studio/interface/shortcuts.md` and a new
- * `docs/studio/interface/commands.md` as **generated from the registry at build time**, which is
- * the last of §5.5's seven derivations: with the chrome, the keymap, the palette, the menus and the
- * automation surface all rendering the same records, a hand-maintained shortcut sheet is the only
- * place left for the app's keyboard and its documentation to disagree.
+ * `docs/studio/interface/shortcuts.md` and `docs/studio/interface/commands.md` are **generated from
+ * the registry at build time**, the last of the renderings §13 derives from it: with the chrome,
+ * the keymap, the palette, the menus and the automation surface all rendering the same records, a
+ * hand-maintained shortcut sheet is the only place left for the app's keyboard and its
+ * documentation to disagree.
  *
  * This module is the projection, not the generator. It takes a command set — `appCommandSet()`, the
  * one bare-Bun-importable export the three CI checks already load — and returns ROWS plus the

package/src/commands/registry.ts

@@ -6,7 +6,7 @@
  * default chord, and the surfaces it belongs in. Every surface — Command Bar, palette, rail,
  * context menus, the block action bar, the keymap, `__jxAutomation` and the assistant's tools —
  * becomes a RENDERING of these records. A surface may choose whether to show a command; it may
- * never decide what it is called, when it is available, or what it does (plan §2, principle 1).
+ * never decide what it is called, when it is available, or what it does (§13).
  *
  * Four things fail loudly at registration rather than degrading into a surface disagreement:
  *
@@ -23,7 +23,7 @@
  * `when` / `enablement` are `(ctx) => boolean` closures, modelled on the shipped
  * `services/gated-registry.ts` `ToolAvailability`, and `requires` is ONE string with three
  * consumers: the disabled control's tooltip, the palette row's grey subtitle and the agent's
- * refusal message. Plan §13 rejects a serialisable string DSL; do not add one.
+ * refusal message. §13.1 rejects a serialisable string DSL; do not add one.
  *
  * The registry takes its context by injection (`getContext`), so nothing here imports a state
  * module. That is what lets the CI checks import the command set in a bare Bun process and lets

package/src/content/draft-state.ts

@@ -1,5 +1,6 @@
 /**
- * The draft axis (§7.6) — what a draft IS, and whether drafts are listed. One place, every list.
+ * The draft axis (site-architecture.md §7.6) — what a draft IS, and whether drafts are listed. One
+ * place, every list.
  *
  * It is deliberately its own module rather than a field on a pane's state and rather than a section
  * of `entry-model.ts`. Two reasons, and the second is why the definitions live here beside the
@@ -20,17 +21,17 @@
 import { reactive } from "../reactivity";
 import type { ContentTypeSchema } from "@jxsuite/schema/types";
 
-/** The conventional boolean frontmatter field that marks an entry a draft (§7.6). */
+/** The conventional frontmatter boolean that marks an entry a draft (site-architecture.md §7.6). */
 export const DRAFT_FIELD = "draft";
 
 /**
  * What a draft IS, in one sentence, for every surface that shows the pill.
  *
- * Deliberately does not say "excluded from production builds" — the spec's §7.6 bullet describes an
- * intent the build does not implement yet (`packages/compiler`'s `site/site-build.ts` says so
- * beside `$sitemap`), and a badge that promises a file will not ship when it will is the exact
- * class of confident-wrong statement §16 exists to end. When the compiler learns to drop drafts,
- * this constant changes and every surface changes with it.
+ * Deliberately does not say "excluded from production builds" — site-architecture.md §7.6's bullet
+ * describes an intent the build does not implement yet (`packages/compiler`'s `site/site-build.ts`
+ * says so beside `$sitemap`), and a badge that promises a file will not ship when it will is the
+ * exact class of confident-wrong statement §16 exists to end. When the compiler learns to drop
+ * drafts, this constant changes and every surface changes with it.
  */
 export const DRAFT_MEANING =
   "Marked a draft. Studio filters drafts out of its own lists; the build does not exclude them yet.";
@@ -82,7 +83,7 @@ export function includingDrafts(): boolean {
  *
  * A setter, never a toggle: `content.setIncludeDrafts` names the STATE it reaches, so a manifest
  * step, an assistant call and a checkbox all land on the same value however many times they run
- * (plan §13.1, and the rule `tests/app-commands.test.ts` enforces).
+ * (§13.5's idempotence rule, which `tests/app-commands.test.ts` enforces).
  *
  * Setting the flag is all this does. Repainting the lists that read it belongs to the command — see
  * `content/entry-commands.ts` — because a data module may not reach into the workspace.