@jxsuite/studio 5.3.0 → 5.4.0

package/src/tabs/transact.ts

@@ -9,7 +9,7 @@ import {
   pruneSelection,
   structuralBatch,
 } from "./selection";
-import { applyDocOpToDoc, childArray, cloneValue } from "./doc-op-apply";
+import { applyDocOpToDoc, childArray, cloneValue, inverseOf } from "./doc-op-apply";
 import {
   beginRecording,
   endRecording,
@@ -773,7 +773,7 @@ export function mutateDuplicateNode(tab: Tab, path: JxPath) {
 }
 
 /**
- * Remove every selected node, in ONE transaction and therefore ONE undo step (§6.5).
+ * Remove every selected node, in ONE transaction and therefore ONE undo step (§6.7).
  *
  * Three things make a batch different from a loop. `structuralBatch` drops paths contained by
  * another selected path — deleting a `<section>` and a paragraph inside it is one deletion — drops
@@ -878,35 +878,29 @@ export function mutateMoveNode(tab: Tab, fromPath: JxPath, toParentPath: JxPath,
   if (!fromParent || !Array.isArray(fromParent.children) || !toParent) {
     return;
   }
-  const [node] = fromParent.children.splice(fromIdx, 1);
-  if (node === undefined) {
+  if (fromParent.children[fromIdx] === undefined) {
     return;
   }
   let adjustedIndex = toIndex;
   if (fromParent === toParent && fromIdx < toIndex) {
     adjustedIndex -= 1;
   }
-  childArray(toParent).splice(adjustedIndex, 0, node);
+  const forward: JxDocOp = {
+    fromIndex: fromIdx,
+    fromParentPath,
+    op: "move-child",
+    toIndex: adjustedIndex,
+    toParentPath,
+  };
+  /* Computed BEFORE the splice, against the document the move applies to. The inverse runs against
+     the post-move document, so `inverseOf` writes both of its parent paths in post-move
+     coordinates: the removal shifted paths under the source parent, the insertion paths under the
+     target. One implementation of that rule, shared with every other host that moves a node. */
+  const inverse = inverseOf(doc, forward);
+  const [node] = fromParent.children.splice(fromIdx, 1);
+  childArray(toParent).splice(adjustedIndex, 0, node!);
   recordPatch({ fromPath, op: "move", toIndex: adjustedIndex, toParentPath });
-  recordDocOp({
-    forward: {
-      fromIndex: fromIdx,
-      fromParentPath,
-      op: "move-child",
-      toIndex: adjustedIndex,
-      toParentPath,
-    },
-    inverse: {
-      fromIndex: adjustedIndex,
-      // The inverse runs against the post-move document, so both parent paths are translated
-      // Into post-move coordinates: the removal shifted paths under fromParent, the insertion
-      // Shifted paths under toParent.
-      fromParentPath: shiftPrefixedIndex(fromParentPath, toParentPath, fromIdx, -1, false),
-      op: "move-child",
-      toIndex: fromIdx,
-      toParentPath: shiftPrefixedIndex(toParentPath, fromParentPath, adjustedIndex, 1, true),
-    },
-  });
+  recordDocOp({ forward, inverse });
 
   if (pathsEqual(primarySelection(tab.session.selection), fromPath)) {
     let idx = toIndex;

package/src/types.ts

@@ -298,6 +298,26 @@ export interface StudioPlatform {
   } | null>;
   listDirectory: (dir: string) => Promise<DirEntry[]>;
   readFile: (path: string) => Promise<string>;
+  /**
+   * A project file's raw bytes — what {@link readFile} cannot answer.
+   *
+   * `readFile` decodes as UTF-8, and every byte sequence that is not valid UTF-8 becomes U+FFFD on
+   * the way through. That is invisible and irreversible: a JPEG read this way is not a corrupted
+   * JPEG, it is a string of replacement characters that no decoder will ever turn back into an
+   * image. So a caller that must DECODE a project file — the image editor — needs this instead.
+   *
+   * **The `<img>` route is not an alternative, on the one platform that matters most.** A preview
+   * `src` from `files/media-paths.ts` is a cross-origin loopback URL on the electrobun desktop
+   * while the shell sits on `views://`, so drawing it into a canvas taints the canvas and
+   * `toBlob()` throws; and `server.md` §4.2 bans CORS outright, because the whole loopback security
+   * model rests on the browser refusing cross-origin reads. Bytes through the PAL become a
+   * same-origin `Blob`, so tainting stops being a thing that can happen rather than a thing that is
+   * worked around.
+   *
+   * Optional, and feature-detected like every optional member: a backend without it simply does not
+   * offer the image editor, which is the honest degradation `specs/desktop.md` §3.1 asks for.
+   */
+  readFileBytes?: (path: string) => Promise<ArrayBuffer>;
   writeFile: (path: string, content: string) => Promise<void>;
   /**
    * Store bytes at a project path, and report where they really landed.
@@ -547,9 +567,13 @@ export interface StudioPlatform {
     onReady?: (evt: ImportReadyEvent) => void,
   ) => Promise<{ root: string; config: ProjectConfig; result?: ImportSiteSummary }>;
   /**
-   * Open a native directory picker and return the chosen absolute path (null when cancelled). Backs
-   * the New Project modal's **Browse…** button on `createDestination: "path"` platforms. Desktop
-   * only — the dev server has no native dialog, so its Location field is typed by hand.
+   * Open a native directory picker and return the chosen absolute path. Backs the New Project
+   * modal's **Browse…** button on `createDestination: "path"` platforms: desktop (the system
+   * dialog), and the dev server in a browser that has `showDirectoryPicker` (Chromium-based).
+   *
+   * Resolves `null` only when the user cancels; rejects with a displayable Error otherwise. The
+   * modal shows that message under the Location field, and typing a path clears it. A picker that
+   * resolves `null` for a failure is a dead button: the click visibly does nothing.
    */
   pickDirectory?: () => Promise<string | null>;
   /** Stack B AI assistant: URL of the OpenAI-compatible SSE chat proxy (`/__studio/ai/chat`). */

package/src/ui/ai-credentials-form.ts

@@ -8,14 +8,14 @@
  *
  * The interim `Assistant: Settings…` dialog that used to host it is deleted: a provider key is an
  * application setting, and the surface that owns application settings is also the one that can list
- * it and revoke it (plan §9.3). Nothing about this form changed for the move, which is the argument
+ * it and revoke it (§15). Nothing about this form changed for the move, which is the argument
  * for it having been a reusable form rather than a section of a dialog.
  *
  * This module is the FLOW; `surfaces/ai-credentials-form.json` is what it draws. It keeps the three
  * drafts, decides which credentials a listing is sent with, what Save persists and re-reads, and
- * whether Cancel is on offer; the surface renders those and reports what the reader did. `render()`
- * hands back the surface's own host element rather than a template, because every gate is still a
- * lit template that interpolates the form beside the keyless offer — see
+ * whether there is anything to Save or Cancel; the surface renders those and reports what the
+ * reader did. `render()` hands back the surface's own host element rather than a template, because
+ * every gate is still a lit template that interpolates the form beside the keyless offer — see
  * `surfaces/ai-credentials-form.ts` for why that element is the mount point and why re-rendering
  * the gate cannot disturb it.
  *
@@ -25,12 +25,15 @@
 
 import { fetchAvailableModels, proxyModelsErrorMessage } from "../services/ai-models";
 import {
+  aiProviderDiffers,
   getBaseUrl,
   getOpenAiKey,
-  hasOpenAiKey,
   saveAiProvider,
+  storedEquals,
   storedModel,
 } from "../services/ai-settings";
+import { SETTINGS } from "../services/settings/definitions";
+import type { AiProvider } from "../services/ai-settings";
 import { createAiCredentialsSurface } from "../surfaces/ai-credentials-form";
 import type {
   AiCredentialsSurface,
@@ -47,7 +50,10 @@ export interface AiCredentialsFormOptions {
   requestRender: () => void;
   /** Called after Save persists the credentials. */
   onSaved?: () => void;
-  /** Called when Cancel dismisses the form (Cancel is only offered when a key already exists). */
+  /**
+   * Called when Cancel puts the drafts back to what is stored (Cancel is only offered while they
+   * differ from it).
+   */
   onCancel?: () => void;
   /**
    * Optional context line replacing the default blurb.
@@ -85,21 +91,65 @@ export function createAiCredentialsForm(opts: AiCredentialsFormOptions): AiCrede
   let modelsLoading = false;
   let modelsError = "";
 
+  /**
+   * What the store held when the drafts last agreed with it — the answer to "has the reader touched
+   * this field?". A draft still equal to its basis is a VIEW of the store, not an edit, so
+   * {@link followStore} may move it; one that differs is the reader's and nothing but a Save or a
+   * Cancel replaces it. Starts blank because the drafts do, which is what lets a host that never
+   * calls `startEdit` still open on what is stored.
+   */
+  let basis: AiProvider = { apiKey: "", baseUrl: "", model: "" };
+
   /** Made on the first render, and kept for the life of the controller. */
   let surface: AiCredentialsSurface | null = null;
 
   /**
-   * Load the drafts from what is stored.
+   * What is stored, in the shape the drafts take.
    *
    * The model comes from {@link storedModel} rather than `getModel()`, so a user who has never
    * picked one drafts an empty field instead of the `"gpt-4o"` default. Saving a prefilled default
    * writes a choice nobody made, and `jx.ai.model: "gpt-4o"` is exactly what a broken install was
    * left holding.
    */
+  function stored(): AiProvider {
+    return { apiKey: getOpenAiKey(), baseUrl: getBaseUrl(), model: storedModel() };
+  }
+
+  /** Load the drafts from what is stored, discarding any edit, and take that as the new basis. */
   function loadDrafts() {
-    keyDraft = getOpenAiKey();
-    baseUrlDraft = getBaseUrl();
-    modelDraft = storedModel();
+    basis = stored();
+    keyDraft = basis.apiKey;
+    baseUrlDraft = basis.baseUrl;
+    modelDraft = basis.model;
+  }
+
+  /**
+   * Bring every untouched draft up to what is stored now, and keep every edited one.
+   *
+   * Without this a draft could drift from the store with nobody having typed, and a form that
+   * offers Save and Cancel only while it differs would offer them for an edit nobody made. Two
+   * hosts did exactly that: the New Project gates never call `startEdit`, so their drafts began
+   * blank over a stored endpoint or model — and Save then overwrote both with nothing — and a
+   * Disconnect in Preferences › Accounts left the Assistant form holding the key it had just
+   * revoked, which its Save would have stored again. Run from {@link render}, the host's repaint,
+   * and never from a setter, so a keystroke is never rebased onto the store under the reader.
+   *
+   * **"Untouched" is judged by the same rule as `dirty`**, through the store's own normalisation,
+   * because the two questions have to agree. Raw string equality made a draft that differed only by
+   * whitespace, or by an endpoint's trailing slash, TOUCHED here and not-dirty there: no Save and
+   * no Cancel were drawn, so nothing could reset it, and yet this function refused to move it — so
+   * a Disconnect in Accounts left the revoked key sitting in the field, and once the store was
+   * empty the form turned dirty and offered to store it back. A draft Save would not move is a view
+   * of the store, whatever it was typed as.
+   */
+  function followStore() {
+    const now = stored();
+    keyDraft = storedEquals(SETTINGS.aiOpenAiKey, keyDraft, basis.apiKey) ? now.apiKey : keyDraft;
+    baseUrlDraft = storedEquals(SETTINGS.aiBaseUrl, baseUrlDraft, basis.baseUrl)
+      ? now.baseUrl
+      : baseUrlDraft;
+    modelDraft = storedEquals(SETTINGS.aiModel, modelDraft, basis.model) ? now.model : modelDraft;
+    basis = now;
   }
 
   /** Open the form pre-filled with the current settings, and load the model list. */
@@ -122,7 +172,8 @@ export function createAiCredentialsForm(opts: AiCredentialsFormOptions): AiCrede
    * `setOpenAiKey`/`setBaseUrl` treat as _clear_, so pressing Save a second time on the emptied
    * form deleted the key and endpoint that the first press had just stored. Reading back through
    * the getters also shows what was actually kept — trimmed, and with the endpoint's trailing slash
-   * stripped — rather than what was typed.
+   * stripped — rather than what was typed. And because the drafts then equal the store, the form is
+   * no longer `dirty`: Save and Cancel go away, so a second press has nothing to land on.
    */
   function save() {
     saveAiProvider({ apiKey: keyDraft, baseUrl: baseUrlDraft, model: modelDraft });
@@ -135,7 +186,10 @@ export function createAiCredentialsForm(opts: AiCredentialsFormOptions): AiCrede
     opts.requestRender();
   }
 
-  /** Dismiss the form without saving (only offered when a key already exists). */
+  /**
+   * Put the drafts back to what is stored. Only offered while they differ from it, so it always
+   * abandons something — which is also why it takes itself away.
+   */
   function cancel() {
     loadDrafts();
     modelsError = "";
@@ -196,12 +250,14 @@ export function createAiCredentialsForm(opts: AiCredentialsFormOptions): AiCrede
   function view(): AiCredentialsView {
     return {
       baseUrlDraft,
+      /* Compared as the store would hold each value, so what Save would erase — whitespace, an
+         endpoint's trailing slash — is not an edit. See `aiProviderDiffers`. */
+      dirty: aiProviderDiffers({ apiKey: keyDraft, baseUrl: baseUrlDraft, model: modelDraft }),
       fetchLabel: modelsLoading
         ? "Fetching…"
         : availableModels.length > 0
           ? "Refresh models"
           : "Fetch models",
-      haveKey: hasOpenAiKey(),
       intro: opts.intro ?? DEFAULT_INTRO,
       keyDraft,
       modelDraft,
@@ -214,9 +270,10 @@ export function createAiCredentialsForm(opts: AiCredentialsFormOptions): AiCrede
   /**
    * What the reader typed, announced on the scope before anything else reads it.
    *
-   * A document's binding writes only when the value it reads CHANGES (§9.3), so a draft the flow
-   * decided without the raw text passing through would leave the field holding something the flow
-   * does not have. Nothing rewrites a draft today; the echo is what makes a rewrite possible.
+   * A document's binding writes only when the value it reads CHANGES (the controlled-input rule of
+   * studio-ui-guidelines.md §9.3), so a draft the flow decided without the raw text passing through
+   * would leave the field holding something the flow does not have. Nothing rewrites a draft today;
+   * the echo is what makes a rewrite possible.
    */
   function setKey(value: string) {
     keyDraft = value;
@@ -238,6 +295,7 @@ export function createAiCredentialsForm(opts: AiCredentialsFormOptions): AiCrede
   }
 
   function render(): HTMLElement {
+    followStore();
     if (surface) {
       surface.update(view());
     } else {

package/src/ui/ai-managed-connect.ts

@@ -66,6 +66,13 @@ const LEDE_FRESH =
   "Recommended — run the assistant on Workers AI in your own Cloudflare account. No API key to create, copy or rotate.";
 const LEDE_LAPSED =
   "Your Cloudflare connection has expired. Reconnect to keep using the assistant.";
+/**
+ * A live grant that reaches more than one account and has none chosen (`cf_account_required`).
+ * Re-authorizing lands back in exactly this state, so the button opens the account picker instead
+ * of the OAuth flow, and the words say which of the two is missing.
+ */
+const LEDE_ACCOUNT =
+  "Cloudflare is connected, but no account is chosen yet. Pick the account the assistant should run on.";
 
 /**
  * Create a managed-connect controller bound to a host's render scheduler.
@@ -98,6 +105,51 @@ export function createManagedConnect(opts: ManagedConnectOptions): ManagedConnec
     return !isProxyConfigured() || proxyStateCode() === "cf_reconnect_required";
   }
 
+  /**
+   * The grant is live but names no account — the one state a connect flow cannot fix. Read from the
+   * shared probe alone, so it can never outlive the state it describes: a disconnect, or an account
+   * picked in Preferences, changes what the probe answers and this answer with it.
+   */
+  const needsAccount = () => proxyStateCode() === "cf_account_required";
+
+  /**
+   * Re-probe after the connection changed, and CHECK the answer, because a change the backend does
+   * not honour must not look like one that worked. This is the only place that can tell.
+   */
+  async function verifyConnection(): Promise<void> {
+    // Re-probe: /models flips to configured once the connection lands, opening the gate.
+    resetModelCache();
+    await fetchAvailableModels({ force: true });
+    /* Each refusal gets the advice that can fix it: reconnecting cannot choose an account, and a
+       pick cannot revive a lapsed grant. */
+    if (proxyStateCode() === "cf_account_required") {
+      connectError =
+        "Cloudflare still reports no account chosen for the assistant. Pick one again, or use your own API key below.";
+    } else if (!isProxyConfigured() || proxyStateCode() === "cf_reconnect_required") {
+      connectError =
+        "Cloudflare connected, but the assistant backend still reports the connection as unusable. " +
+        "Try reconnecting, or use your own API key below.";
+    }
+  }
+
+  /** Open the account picker, and verify the connection once an account is chosen. */
+  async function chooseAccount(): Promise<void> {
+    /* Lazily, because the picker pulls the dialog layer in and this module is imported by every
+       credentials gate — including ones that render before layers are bound. */
+    const { openCfAccountPicker } = await import("./cf-account-picker");
+    if (!(await openCfAccountPicker())) {
+      /* Re-probe, because the probe still answers from before the connect. The backend reports a
+         live grant with no account as `cf_account_required`, so after this the button offers the
+         picker again rather than an OAuth round trip that would land right back here. */
+      resetModelCache();
+      await fetchAvailableModels({ force: true });
+      connectError =
+        "Cloudflare is connected, but no account is chosen yet — pick one to finish setting up the assistant.";
+      return;
+    }
+    await verifyConnection();
+  }
+
   function ensureProbe() {
     ensureProxyProbe(opts.requestRender);
   }
@@ -126,25 +178,10 @@ export function createManagedConnect(opts: ManagedConnectOptions): ManagedConnec
       return;
     }
     if (!outcome.connection.accountId) {
-      /* Lazily, because the picker pulls the dialog layer in and this module is imported by every
-         credentials gate — including ones that render before layers are bound. */
-      const { openCfAccountPicker } = await import("./cf-account-picker");
-      if (!(await openCfAccountPicker())) {
-        connectError =
-          "Cloudflare is connected, but no account is chosen yet — pick one to finish setting up the assistant.";
-        return;
-      }
-    }
-    // Re-probe: /models flips to configured once the connection lands, opening the gate.
-    resetModelCache();
-    await fetchAvailableModels({ force: true });
-    /* And then CHECK, because a connect the backend does not honour must not look like one that
-       worked. This is the only place that can tell the difference. */
-    if (!isProxyConfigured() || proxyStateCode() === "cf_reconnect_required") {
-      connectError =
-        "Cloudflare connected, but the assistant backend still reports the connection as unusable. " +
-        "Try reconnecting, or use your own API key below.";
+      await chooseAccount();
+      return;
     }
+    await verifyConnection();
   }
 
   async function connect() {
@@ -155,7 +192,11 @@ export function createManagedConnect(opts: ManagedConnectOptions): ManagedConnec
     connectError = "";
     opts.requestRender();
     try {
-      await settle((await getPlatform().cfConnect?.()) ?? null);
+      /* `cf_account_required` is a grant that already works for authorization and names no
+         account; the OAuth flow would land straight back here (ai.md §2.1). */
+      await (needsAccount()
+        ? chooseAccount()
+        : settle((await getPlatform().cfConnect?.()) ?? null));
     } catch (error) {
       connectError = error instanceof Error ? error.message : String(error);
     }
@@ -165,6 +206,14 @@ export function createManagedConnect(opts: ManagedConnectOptions): ManagedConnec
 
   /** What the offer says right now — the whole of what the surface is told. */
   function view(): ManagedConnectView {
+    if (needsAccount()) {
+      return {
+        buttonLabel: busy ? "Choosing…" : "Choose Cloudflare account",
+        busy,
+        error: connectError,
+        intro: LEDE_ACCOUNT,
+      };
+    }
     const lapsed = proxyStateCode() === "cf_reconnect_required";
     const idleLabel = lapsed ? "Reconnect Cloudflare" : "Connect Cloudflare";
     return {

package/src/ui/color-selector.ts

@@ -7,7 +7,7 @@
  * Spectrum surface in Studio, and the island `studio-ui-guidelines.md` §9.4 describes: the Style
  * tab and the Content tab each drew an empty `[part="control-host"]` and this filled it with lit.
  *
- * §5.6 landed, so the control is `jx-color-field` and both tabs draw it inline in their own
+ * `ui.md` §5.6 landed, so the control is `jx-color-field` and both tabs draw it inline in their own
  * documents. What no kit element can answer is what is LEFT here: which colours this project has
  * given a name to. That is a question about the document being edited — the `--color-*` custom
  * properties of the effective style, site and document together — and it is Studio's to answer.

package/src/ui/expression-editor.ts

@@ -185,7 +185,7 @@ function restrictGroups(operators: readonly string[]): ExprSelectGroup[] {
   })).filter((group) => group.rows.length > 0);
 }
 
-/** The three rungs of the value ladder, spelled the way `ui/value-source.ts` spells them (§6.3). */
+/** The three rungs of the value ladder, spelled the way `ui/value-source.ts` spells them (§6.6). */
 const SOURCE_OPTIONS: ExprOption[] = [
   { label: VALUE_SOURCE_LABELS.literal, value: "literal" },
   { label: VALUE_SOURCE_LABELS.ref, value: "ref" },
@@ -298,7 +298,7 @@ function operatorInfo(op: string): OperatorInfo {
 /**
  * Which rung of the value ladder an operand occupies. The three answers are the same three the
  * Properties, Style and Logic tabs give, and they are spelled the same way — `ui/value-source.ts`
- * owns the words, so `lit / $ref / expr` is gone from the operand picker (plan §6.3).
+ * owns the words, so `lit / $ref / expr` is gone from the operand picker (§6.6).
  *
  * @param {unknown} operand
  * @returns {"ref" | "expression" | "literal"}
@@ -1058,7 +1058,7 @@ export function flattenExpression(
 
 /**
  * The projection ONE operand slot reads as — a statement's `if` test, a `$switch` discriminant, a
- * `dispatchEvent` detail (spec §20). The same rows, with no operator row above them.
+ * `dispatchEvent` detail (spec.md §20). The same rows, with no operator row above them.
  */
 export function flattenOperand(
   operand: unknown,

package/src/ui/form-controls.ts

@@ -4,8 +4,8 @@
  * JSON-Schema field editor), "secret" (value committed via the host's secret store, never
  * project.json) and "reference" (an entry of another content collection).
  *
- * Three, not the four the spec still lists: `"binding"` was the signal/route-param picker, and P5
- * replaced it with the value-source ladder every scalar field now carries (`ui/dynamic-slot.ts`,
+ * Three, not the four the spec still lists: `"binding"` was the signal/route-param picker, and the
+ * value-source ladder every scalar field now carries replaced it (§6.6; `ui/dynamic-slot.ts`,
  * `ui/value-source.ts`). Nothing has registered it since, so a descriptor naming it falls through
  * to the control its type would have had anyway.
  *
@@ -705,13 +705,14 @@ registerFormControl("secret", secretControl);
 
 /**
  * An entry of another content collection — site-architecture.md §6.1's `{ "$ref": "#/content/x" }`
- * and §7.4's "entry picker (dropdown of collection entries)".
+ * and site-architecture.md §7.4's "entry picker (dropdown of collection entries)".
  *
  * **Registered once, consulted by everything.** `ui/schema-form.ts` dispatches to it for any
  * property whose `$ref` names a collection, so the settings forms, the entry editor and the
  * frontmatter card all draw the same picker without any of them knowing it exists. That is the
- * whole point: P5 collapsed six value-source vocabularies into one and three call sites still spoke
- * their own, so this one arrives as a registration rather than as a fourth renderer.
+ * whole point: the value-source ladder (§6.6) collapsed six vocabularies into one and three call
+ * sites still spoke their own, so this one arrives as a registration rather than as a fourth
+ * renderer.
  *
  * Three states, and none of them lies:
  *

package/src/ui/formula-catalog.ts

@@ -1,6 +1,6 @@
 /**
  * Formula catalog — the metadata registry behind the formula palette, chip labels, and Monaco
- * completions (spec §19). Merges three sources into one uniform entry shape:
+ * completions (spec.md §19). Merges three sources into one uniform entry shape:
  *
  * 1. Blessed operators (hand-authored metadata for every member of `BLESSED_OPERATORS`),
  * 2. Blessed pure globals (derived programmatically from `BLESSED_GLOBALS`),
@@ -314,7 +314,7 @@ export function operatorEntries(): FormulaCatalogEntry[] {
   return out;
 }
 
-// ─── Pure standard-library methods (derived, spec §19.4d) ───────────────────
+// ─── Pure standard-library methods (derived, spec.md §19.4d) ────────────────
 
 /** Prototype owner per pure method — drives grouping and the derived description. */
 const PURE_METHOD_PROTO: Record<string, string> = {
@@ -367,7 +367,7 @@ export const ZERO_ARG_METHODS = new Set([
   "trimStart",
 ]);
 
-/** The derived catalog entry for one pure method operator (spec §19.4d). */
+/** The derived catalog entry for one pure method operator (spec.md §19.4d). */
 function pureMethodEntry(op: string): FormulaCatalogEntry {
   const proto = PURE_METHOD_PROTO[op] ?? "Standard library";
   return {
@@ -387,7 +387,7 @@ function pureMethodEntry(op: string): FormulaCatalogEntry {
 // ─── Blessed globals (derived) ──────────────────────────────────────────────
 
 /**
- * Synthetic blessed helpers wrap constructor-shaped standard-library APIs (spec §19.4c); their
+ * Synthetic blessed helpers wrap constructor-shaped standard-library APIs (spec.md §19.4c); their
  * catalog descriptions name the wrapped API rather than claiming a literal global exists.
  */
 const HELPER_DESCRIPTIONS: Record<string, string> = {

package/src/ui/formula-chips.ts

@@ -1,6 +1,6 @@
 /**
- * Formula chips — the MODEL behind the chip pipeline (spec §19.9): an expression tree read as a row
- * of chips, left to right. The `target` chain unrolls deepest-first, so the head chip is the
+ * Formula chips — the MODEL behind the chip pipeline (spec.md §19.9): an expression tree read as a
+ * row of chips, left to right. The `target` chain unrolls deepest-first, so the head chip is the
  * innermost target operand (a ref or a literal) and each operator follows it out to the root;
  * nested non-target operands (`value`, `initial`, a `switch` case, a positional arg) become
  * parenthesized group chips beside the link they belong to.

package/src/ui/layers.ts

@@ -4,13 +4,13 @@
  *
  * Everything renders into one of the four fixed hosts declared in index.html (#layer-popover,
  * #layer-modal, #layer-dialog, #layer-toast), bound once at boot by initLayers(). Native browser
- * dialogs (`prompt`, `confirm`, `alert`) are not permitted anywhere in Studio — use
- * `showPromptDialog`, `showConfirmDialog`, or `showSaveDiscardDialog`. See studio-ui-guidelines.md
- * §8.7.
+ * dialogs (`prompt`, `confirm`, `alert`) are not permitted anywhere in Studio
+ * (studio-ui-guidelines.md §8.7) — use `showPromptDialog`, `showConfirmDialog`, or
+ * `showSaveDiscardDialog`.
  *
- * The toast host is the fourth layer (plan §3.2 ④, §7.1). It is a rendering of
- * `services/notify.ts`'s `toasts` array and owns exactly two things that array does not: the timer
- * that retires a resting toast, and the transition account {@link overlayIdleBlockers} publishes.
+ * The toast host is the fourth layer (§16.1). It is a rendering of `services/notify.ts`'s `toasts`
+ * array and owns exactly two things that array does not: the timer that retires a resting toast,
+ * and the transition account {@link overlayIdleBlockers} publishes.
  */
 import { render as litRender, nothing } from "lit-html";
 import { overlayRegion, REGION_ATTR } from "./regions";
@@ -117,7 +117,8 @@ export function isModalOpen(): boolean {
  * `showPromptDialog` below are the three named questions, and they go through the same document.
  *
  * A body that is genuinely richer than a sentence is an ISLAND, not a new dialog: `message` accepts
- * a lit template and `messageOptions` renders it into the document's `[part="island"]` (§9.4).
+ * a lit template and `messageOptions` renders it into the document's `[part="island"]`
+ * (studio-ui-guidelines.md §9.4).
  */
 
 /**
@@ -208,7 +209,7 @@ export function showSaveDiscardDialog(
 
 /**
  * A message as the surface takes it: a sentence, or a lit template rendered into the document's
- * island once the element is ready — the island rule of studio-ui-guidelines §9.4.
+ * island once the element is ready — the island rule of studio-ui-guidelines.md §9.4.
  */
 function messageOptions(
   message: string | TemplateResult,
@@ -485,19 +486,20 @@ const _toastEntering = new Set<string>();
 /**
  * Whether the reader has asked for less movement.
  *
- * Read per call rather than cached: §13.3 clause 6 says the app must HONOUR this rather than have
- * the runner inject a freeze stylesheet, which means the answer has to be able to change.
+ * Read per call rather than cached: motion is not among the three things §13.5 lets `?automation=1`
+ * change, so the app must HONOUR this rather than have the runner inject a freeze stylesheet, which
+ * means the answer has to be able to change.
  */
 function reducedMotion(): boolean {
   return globalThis.matchMedia?.("(prefers-reduced-motion: reduce)").matches === true;
 }
 
 /**
- * **One of the three listed exceptions to §13.3 clause 6** — behaviour that differs under
- * `?automation=1` beyond installing the hook, pinning the clock and selecting a profile. The other
- * Two are both refusals to touch the project on disk: `packages/ensure-deps.ts` declines to run
- * `bun install`, and `packages/jxsuite-update.ts` declines to prompt for a dependency update. This
- * One is the only exception that changes what a picture SHOWS rather than what it avoids doing.
+ * **One of the three exceptions §13.5 lists** — behaviour that differs under `?automation=1` beyond
+ * installing the hook, pinning the clock and selecting a profile. The other two are both refusals
+ * to touch the project on disk: `packages/ensure-deps.ts` declines to run `bun install`, and
+ * `packages/jxsuite-update.ts` declines to prompt for a dependency update. This one is the only
+ * exception that changes what a picture SHOWS rather than what it avoids doing.
  *
  * A toast is the single surface in the app whose lifetime is a TIMER rather than a state. Every
  * other surface a shot can photograph is there because the app is in a state, and it stays there
@@ -507,9 +509,9 @@ function reducedMotion(): boolean {
  * as long as they cared to look, instead of showing the toast that happened to still be there.
  *
  * The gate is re-derived from `location.search` rather than imported from `services/automation.ts`
- * deliberately: §13.3 requires the scripting surface to be absent from the desktop and cloud
- * bundles (`check-bundle-budget.ts`'s next assertion), and importing it from a module every layer
- * pulls in would ship it everywhere. One line of duplication, on purpose.
+ * deliberately: the scripting surface must stay out of the desktop and cloud bundles (no spec
+ * states it and `check-bundle-budget.ts` does not assert it yet), and importing it from a module
+ * every layer pulls in would ship it everywhere. One line of duplication, on purpose.
  */
 export function toastsAreHeld(): boolean {
   try {

package/src/ui/panel-resize.ts

@@ -58,11 +58,11 @@ import type { SplitModifiers } from "@jxsuite/ui/behaviors/split";
  *
  * **There is no pointer path left in this module**, and it is worth recording why rather than
  * quietly dropping it: a handle driven by pointer events alone is unreachable from a keyboard,
- * which is an SC 2.1.1 failure however it is drawn. The pane split moved to `jx-split` first (ui.md
- * §5.5), the three docks followed, and the Edit column was last because its handle SNAPS — and the
- * element had no way to tell a host which modifiers a step carried. It has now: every `input`
- * carries them, so a snap lives in {@link bindSplit} rather than in a pointer handler of this
- * module's own.
+ * which is an SC 2.1.1 failure however it is drawn. The pane split moved to `jx-split` first
+ * (`ui.md` §5.5), the three docks followed, and the Edit column was last because its handle SNAPS —
+ * and the element had no way to tell a host which modifiers a step carried. It has now: every
+ * `input` carries them, so a snap lives in {@link bindSplit} rather than in a pointer handler of
+ * this module's own.
  */
 export interface ResizeTarget {
   /** Which coordinate the drag reads. */

package/src/ui/popover-surface.ts

@@ -66,8 +66,8 @@ export interface OpenPopoverSurfaceOptions {
   /** The platform closed it — clicked outside, Escape, or a second press on the invoker. */
   onDismissed?: () => void;
   /**
-   * A node the document made exists. The one seam an island reaches its host through (§9.4), passed
-   * straight to the runtime.
+   * A node the document made exists. The one seam an island reaches its host through
+   * (studio-ui-guidelines.md §9.4), passed straight to the runtime.
    */
   onNodeCreated?: JxMountOptions["onNodeCreated"];
 }