@jxsuite/studio 5.3.0 → 5.4.0

package/src/panels/properties-panel.ts

@@ -2,15 +2,15 @@
 /**
  * The Content tab — everything about WHAT this element is and says.
  *
- * Plan §6.5 re-split the inspector by task. Content is the element itself (tag, id, class, text),
- * its HTML attributes, its link target, its custom attributes, its component props and its media.
- * Three things left, and each left for a place that already had a better claim on it:
+ * The Inspector is split by task (§6). Content is the element itself (tag, id, class, text), its
+ * HTML attributes, its link target, its custom attributes, its component props and its media. Three
+ * things left, and each left for a place that already had a better claim on it:
  *
  * - **Repeater · Switch · Observed Attributes · CSS Properties · CSS Parts → the Logic tab.** Wiring
  *   a `$switch` and wiring a click handler are the same task (`panels/events-panel.ts`).
  * - **The Page section → the Document Header card.** `panels/head-panel.ts` owns the one layout
  *   picker; this panel drew a second one that could disagree with it.
- * - **Media breakpoint DEFINITIONS → Project Settings › Contexts** (P4). Nothing remains here: the
+ * - **Media breakpoint DEFINITIONS → Project Settings › Contexts** (§17.1). Nothing remains here: the
  *   only reason adding a breakpoint used to cost you your element selection.
  *
  * **This module decides; `surfaces/properties-panel.json` draws.** Every question with an answer —
@@ -27,7 +27,7 @@
  * untouched, and there is nothing to guard against. What survives is the DRAFT layer
  * (`ui/field-input.ts`), which is a different promise — it is what keeps a half-typed value from
  * being replaced by the last committed one, and what keys that half-typed value to the NODE rather
- * than to the field's name (§11.4).
+ * than to the field's name (§6.1).
  *
  * **Two leaves are drawn elsewhere**, and each is its own surface with readers outside this tab:
  * the media picker and the expression editor. The document draws an empty `[part="control-host"]`
@@ -220,11 +220,12 @@ function bindingDonor(value: unknown): string {
 /**
  * The state entry a bound value reads, when the chip can name one — a `$ref` or a `${…}` template.
  *
- * §6.2's table says a bound chip "click opens the source", and on the Content tab it did not: both
+ * §6.7's table says clicking a bound chip opens its source, and on the Content tab it did not: both
  * bound branches returned a `donor` and a `title` and no `onClick`, so the chip was drawn as a
- * handler-less span. The Style tab's chip has jumped to the Data panel since P5; the same promise
- * on the other tab was a label. Same regex as `style-panel.ts`'s `templateSignalOf`, because both
- * spellings of a template (`${x}` and `${state.x}`) name the same entry.
+ * handler-less span. The Style tab's chip has jumped to the Data panel since the shell redesign's
+ * inspector phase; the same promise on the other tab was a label. Same regex as `style-panel.ts`'s
+ * `templateSignalOf`, because both spellings of a template (`${x}` and `${state.x}`) name the same
+ * entry.
  */
 function boundSignalOf(value: unknown): string | null {
   if (isRef(value)) {
@@ -285,7 +286,7 @@ export function isComponentDefinitionOpen(node: JxMutableNode): boolean {
 }
 
 /**
- * Which of §6.2's four states a component-prop row is in.
+ * Which of §6.7's four states a component-prop row is in.
  *
  * Bound beats set (a `$ref` IS a value, but "bound to `title`" is the more useful sentence); set
  * beats inherited; a prop with no declared default and no value is plain Default and draws
@@ -322,7 +323,7 @@ function componentPropProvenance(
   return { state: "default" };
 }
 
-/** Which of §6.2's states an HTML-attribute row is in. Attributes have no third cascade layer. */
+/** Which of §6.7's states an HTML-attribute row is in. Attributes have no third cascade layer. */
 function attributeProvenance(
   attr: string,
   value: unknown,
@@ -453,9 +454,9 @@ export function invalidatePageRouteCache() {
  * refuse a section the user is looking at; no validation at all would accept the label the old
  * `inspector.toggleSection` step passed ("Element", not `__element`) and silently do nothing.
  *
- * `__media` left with the breakpoint definitions, which are Project Settings › Contexts now (P4).
- * `__observed`, `__cssprops` and `__cssparts` are drawn by the Logic tab; the key space is the
- * INSPECTOR's, not one tab's, so `inspector.setSection` keeps addressing all of them.
+ * `__media` left with the breakpoint definitions, which are Project Settings › Contexts now
+ * (§17.1). `__observed`, `__cssprops` and `__cssparts` are drawn by the Logic tab; the key space is
+ * the INSPECTOR's, not one tab's, so `inspector.setSection` keeps addressing all of them.
  */
 export const INSPECTOR_SECTION_KEYS = [
   "__element",
@@ -881,7 +882,7 @@ function commitKvPair(key: string): void {
   write(name, value);
 }
 
-/** The rung picker: every source this position permits, one action away (§6.3). */
+/** The rung picker: every source this position permits, one action away (§6.6). */
 function openSourceMenu(key: string, anchor: HTMLElement): void {
   const ladder = plans.get(key)?.ladder;
   if (!ladder) {
@@ -1143,7 +1144,7 @@ function projectPanel(): ContentPanelView {
   }
 
   // A repeating list has no content of its own — it has a source and a template, and both are
-  // Wiring. Content says where the answer lives rather than drawing an empty accordion (§6.5).
+  // Wiring. Content says where the answer lives rather than drawing an empty accordion (§6).
   if (node.$prototype === "Array") {
     return emptyView(
       "A repeating list has no content of its own.",
@@ -1286,7 +1287,7 @@ function sectionsFor(node: JxMutableNode, path: JxPath): ContentSectionView[] {
 }
 
 /**
- * One accordion section, with §6.2's collapsed-header tally.
+ * One accordion section, with §6.7's collapsed-header tally.
  *
  * The dot is an INDICATOR and not a control: it used to inherit `.set-dot`'s pointer cursor and its
  * danger hover, which together say "click me to clear this", and nothing happened because it never
@@ -1464,7 +1465,7 @@ function elementRows(
 // ─── Component settings ──────────────────────────────────────────────────────
 
 /**
- * Component props, each row carrying §6.2's provenance chip — the SECOND cascade.
+ * Component props, each row carrying §6.7's provenance chip — the SECOND cascade.
  *
  * A component instance's value for a prop either overrides the component's declared default or does
  * not exist, and until the chip landed the two were the same blank field. The chip states which,
@@ -1646,7 +1647,7 @@ function attributeRow(
   const hasVal = value !== undefined && value !== "";
   const key = `attr|${attr}`;
   const label = attrLabel(entry, attr);
-  // One write per selected element, inside ONE transaction (§6.5). `targets` is `[path]` for a
+  // One write per selected element, inside ONE transaction (§6.7). `targets` is `[path]` for a
   // Single selection, so this is the same single mutation it has always been.
   const commitAttr = (v?: JsonValue) =>
     transactDoc(activeTab.value!, (t) => {
@@ -1887,7 +1888,7 @@ function customRows(path: JxPath, customAttrs: [string, unknown][]): ContentRowV
   return rows;
 }
 
-// ─── Usage (§9.6) ────────────────────────────────────────────────────────────
+// ─── Usage (§9.1.1) ──────────────────────────────────────────────────────────
 
 /**
  * The component instance's usage line — "Used on 7 pages →", expanding to the files.

package/src/panels/provenance.ts

@@ -1,5 +1,5 @@
 /**
- * Provenance — where the value in a field came from, as one chip (plan §6.2).
+ * Provenance — where the value in a field came from, as one chip (§6.7).
  *
  * Four states, and the two that carry information NAME THEIR SOURCE:
  *
@@ -12,7 +12,7 @@
  * | mixed     | neutral, "mixed (3)" — see below  | clear across all  |
  *
  * **Mixed** is what a multi-selection says when the selected elements disagree about a field
- * (§6.5). It is a fifth state of THIS chip rather than a fifth widget, because it answers the same
+ * (§6.7). It is a fifth state of THIS chip rather than a fifth widget, because it answers the same
  * question the other four answer — _where did the value in this box come from?_ — and the honest
  * answer is "from several places, and they differ". It names how many elements are involved, so
  * "mixed" never has to mean "some unknown number of things". Typing into a Mixed field commits the
@@ -38,7 +38,7 @@
  * looks. That is the split the header above always described; it is now the whole file.
  */
 
-/** The states of §6.2 (four) plus §6.5's `mixed`, in the order the table lists them. */
+/** §6.7's four chip states plus its multi-selection `mixed`, in the order the table lists them. */
 export type ProvenanceState = "set" | "inherited" | "default" | "bound" | "mixed";
 
 /** Where one field's value came from, and what clicking the chip does about it. */

package/src/panels/quick-search.ts

@@ -1,19 +1,20 @@
 /// <reference lib="dom" />
 /**
- * The Palette — one omnibox, several modes (UX-REDESIGN-PLAN §5.4).
+ * The Palette — one omnibox, several modes (specs/studio.md §13; its rendering rules are
+ * specs/studio-ui-guidelines.md §12).
  *
  * This file used to be a filename-substring finder with one hidden domain swap in it: with no
  * project open the same trigger, the same chrome and the same placeholder silently listed recent
  * PROJECTS instead. It is now the surface the whole shell shrinks into — the place a capability
- * goes when it is retired from the chrome (§2 principle 9), which only works if everything is
- * reachable here by name, with its chord printed beside it.
+ * goes when it is retired from the chrome (the chrome budget, specs/studio-ui-guidelines.md §12.2),
+ * which only works if everything is reachable here by name, with its chord printed beside it.
  *
  * Four properties earn that:
  *
  * 1. **Modes are named, prefixed and enumerable.** `>` commands, `@` document nodes, plain text files,
  *    and `?` lists them. The mode is echoed as a REMOVABLE CHIP, so the no-project case is a stated
  *    `Recent Projects` mode rather than a swap you have to infer. `PALETTE_MODES` is the namespace:
- *    P4's Problems and P7's content search are new members, not a new widget.
+ *    a Problems mode or a content search is a new member, not a new widget.
  * 2. **Files are matched by fuzzy subsequence over the FULL PATH.** `pgblog` finds
  *    `pages/blog/index.md`. The backend glob (`**\/*q*.{json,md}`) can only do a basename
  *    substring, so the palette asks it once for the document set and ranks locally — which is also
@@ -22,11 +23,11 @@
  * 3. **Every row prints its binding.** That is how a large surface stays discoverable without adding
  *    chrome, and it is the mechanism by which the palette teaches the keyboard it replaced.
  * 4. **An unavailable command is GREYED, not hidden**, with its `requires` sentence as the subtitle
- *    (§2 principle 4). "Why can't I" is the question a palette is uniquely good at answering, and a
- *    row that vanishes answers it with silence.
+ *    (`studio-ui-guidelines.md` §12.3). "Why can't I" is the question a palette is uniquely good at
+ *    answering, and a row that vanishes answers it with silence.
  *
  * The exported names still read `…QuickSearch` because `src/studio.ts` and `src/panels/empty-state.
- * ts` import them and neither is this workstream's file. They are the palette's; the rename is one
+ * ts` import them and neither was this change's file. They are the palette's; the rename is one
  * find-replace in those two call sites.
  */
 
@@ -60,7 +61,10 @@ export interface PaletteModeSpec {
   /** The removable chip's text, and the row label in `?`. */
   chip: string;
   placeholder: string;
-  /** What `?` prints under the mode's name. One sentence, no noun phrases (§2 principle 6). */
+  /**
+   * What `?` prints under the mode's name. One sentence, no noun phrases (`studio-ui-guidelines.md`
+   * §11.1).
+   */
   description: string;
 }
 
@@ -341,7 +345,7 @@ interface ProjectRow {
 interface CommandRow {
   kind: "command";
   id: string;
-  /** `"View: Zen Mode"` — the palette's own naming convention (§5.1). */
+  /** `"View: Zen Mode"` — the palette's own naming convention (§13.1). */
   name: string;
   /** The `requires` sentence when disabled; otherwise empty. */
   detail: string;
@@ -519,8 +523,8 @@ function projectRows(query: string): ProjectRow[] {
 /**
  * Every command the registry holds, ranked — including the ones that cannot run right now.
  *
- * Visibility (`when`) still hides; enablement does not. That split is the whole of §2 principle 4:
- * a command that does not apply to this app at all is absent, and one that does not apply to this
+ * Visibility (`when`) still hides; enablement does not. That split is the whole of §13.1's pair: a
+ * command that does not apply to this app at all is absent, and one that does not apply to this
  * MOMENT is greyed and says why.
  */
 function commandRows(registry: CommandRegistry, query: string): CommandRow[] {

package/src/panels/right-panel.ts

@@ -4,8 +4,9 @@
  *
  * **Content · Style · Logic · Assistant**, text-labelled. Three of those are renames of what was
  * here (Properties→Content, Events→Logic) and the fourth is the assistant, folded in from the fifth
- * grid column it used to own — which is the point of plan §3.2 ⑨: an inspector tab costs zero
- * additional width, so the canvas gets the ~300px back and the assistant is still one key away.
+ * grid column it used to own — which is the point of §3.1's "no assistant column": an inspector tab
+ * costs zero additional width, so the canvas gets the ~300px back and the assistant is still one
+ * key away.
  *
  * **This file no longer draws anything.** The dock's markup, its ARIA and its style are
  * `surfaces/inspector-dock.json`, mounted through `surfaces/inspector-dock.ts`; what is left here
@@ -176,7 +177,7 @@ export function mount(ctx: RightPanelCtx) {
         // Track properties the right panel reads
         void tab.doc.document;
         // The whole SET, joined — a bare property read would not re-trigger when the selection
-        // Changes WITHIN the array, and §6.5's helpers always replace it but nothing enforces that.
+        // Changes WITHIN the array, and §6.7's helpers always replace it but nothing enforces that.
         void tab.session.selection.map((path) => path.join("/")).join("|");
         void tab.session.ui.rightTab;
       }

package/src/panels/seo-modal.ts

@@ -11,7 +11,7 @@
  * So it opens as a modal, from two places — the Document Header card and the Navigator's Page
  * panel. Two doors because the two are different moments: one while writing the page, one while
  * working on its head material. Both run `document.openSeo`, so there is a third door in the
- * palette and no surface owns the capability (§2 principle 1).
+ * palette and no surface owns the capability (one definition site per action, §13).
  *
  * **The card keeps the fields; the modal keeps the picture.** Title still lives on the card,
  * because it is the one head value you type while writing. Everything the modal holds is either a
@@ -72,7 +72,7 @@ import type { AnyCommand, CommandRegistry } from "../commands/registry";
  * Two rendered previews, a resolved-field list and a warning list, over the MERGED head — and no
  * score. A number out of a hundred aggregates unrelated facts into a verdict, and a verdict is
  * what gets optimised; a count beside a limit and a named consequence say the same thing without
- * ranking anything (plan §9.2, §14).
+ * ranking anything (§16.6).
  *
  * The previews are pictures of what the build emits, so a value the page did not author is marked
  * as inherited with the donor NAMED — the third cascade to use `panels/provenance.ts`'s vocabulary
@@ -87,7 +87,7 @@ import type { AnyCommand, CommandRegistry } from "../commands/registry";
  * The two chips that can go somewhere do: a value from the site's own `$head` opens Project
  * Settings › Site head, and one from the site `name` opens Overview. The layout and build donors
  * get no handler, because the card has no verb for "open that layout" and a control that looks
- * pressable and does nothing is the defect §6.2 exists to remove — the document draws those two as
+ * pressable and does nothing is the defect §6.7 exists to remove — the document draws those two as
  * a `<span>` and the two below as a `<button>`, on exactly this answer.
  *
  * @param {SeoField} field
@@ -550,7 +550,8 @@ export function seoCommands(): AnyCommand[] {
       group: "2_document",
       requires: "an open document",
       when: (ctx) => ctx.document.open,
-      /* No `aiTool`, by §12.4's first deletion rule: this opens a modal for a person. */
+      /* No `aiTool`, by `studio-ui-guidelines.md` §12.4's first rule: this opens a modal for a
+         person. */
       run: () => {
         const tab = activeTab.value;
         if (!tab) {

package/src/panels/settings-menu.ts

@@ -7,15 +7,15 @@
  * `app.preferences` (the application, ⌘,) and `settings.open` (this project, ⌘⇧,) — plus a third
  * editor over the same project document, `styles.open`. A slot can hold one of those and must lie
  * about the rest by omission. A menu can hold all three and say what each one is, because it prints
- * every row's own name, chord and gate beside it (§12.3). That is the whole argument for the matrix
- * row `settings/menu` admitting two levels, and for the divider this file draws where the level
- * changes.
+ * every row's own name, chord and gate beside it (`studio-ui-guidelines.md` §12.3). That is the
+ * whole argument for the matrix row `settings/menu` admitting two levels, and for the divider this
+ * file draws where the level changes.
  *
  * **Nothing here is a list of actions.** The rows are `registry.forPlacement("settings/menu")`, so
  * a record joins the menu by declaring the placement and leaves by not declaring it. The submenus
  * are the enumeration of each parent command's own `section` ARGUMENT, read from that argument's
  * own definition site — which is state the command already validates, not a second vocabulary
- * (§12.5).
+ * (`studio-ui-guidelines.md` §12.5).
  *
  * **A parent row runs its own command AND owns a submenu.** The APG menu pattern does not describe
  * that and Spectrum's stock submenu forbade it outright; the kit's `jx-menu-item` makes it the rule
@@ -67,11 +67,11 @@ let _rerender: (() => void) | null = null;
 /**
  * A command's `section` argument, enumerated from that argument's OWN definition site.
  *
- * NOT the second list of actions §12.5 forbids: it holds no titles, no handlers and no ordering of
- * its own. Each entry points at the array the command's validation already reads —
- * `app.preferences` refuses anything `isPreferencesSection` rejects, `settings.open` refuses
- * anything absent from `settingsSectionKeys()` — so a submenu row can never name a value its own
- * command would refuse.
+ * NOT the second list of actions `studio-ui-guidelines.md` §12.5 forbids: it holds no titles, no
+ * handlers and no ordering of its own. Each entry points at the array the command's validation
+ * already reads — `app.preferences` refuses anything `isPreferencesSection` rejects,
+ * `settings.open` refuses anything absent from `settingsSectionKeys()` — so a submenu row can never
+ * name a value its own command would refuse.
  */
 const SECTION_SOURCES: Readonly<Record<string, () => readonly MenuSection[]>> = {
   "app.preferences": () =>

package/src/panels/settings-pane.ts

@@ -6,7 +6,7 @@
  * two-column shape the modal had, because the modal's IA was never the problem — its MODALITY was.
  * Moving the identical layout into `#canvas-wrap` is what makes the seven screenshot crops change
  * frame (`overlay.dialog:settings` → `pane.primary`) without one manifest STEP changing, which is
- * §13.7's proof that the command boundary was drawn in the right place.
+ * the proof that the command boundary was drawn in the right place.
  *
  * **This file is the FLOW; the markup is a document.** `surfaces/settings-pane.json` owns the two
  * columns, the list's ARIA and keyboard, and every value in their style;
@@ -74,8 +74,8 @@ interface ActiveSettingsPane {
    * section rendering into that same element throws on a part whose markers have left the document.
    * It fails the other way too: lit renders BESIDE foreign nodes rather than replacing them, so a
    * lit section drawn after a document one left both on screen at once. A fresh host per section is
-   * what makes the two kinds coexist, which is the whole of §9.3's surface-level rule applied to
-   * one dispatcher.
+   * what makes the two kinds coexist, which is the whole of `studio-ui-guidelines.md` §9.3's
+   * surface-level rule applied to one dispatcher.
    */
   sectionHost: HTMLElement | null;
   /** The section the body currently holds, so an idle re-render does not rebuild it. */

package/src/panels/signals-panel.ts

@@ -147,8 +147,8 @@ export interface SignalDef {
  * The rename that was refused, and why — cleared by the next accepted one.
  *
  * A collision used to be a silent no-op: the field kept the typed name, the document kept the old
- * one, and nothing said which had won. Plan §11.2 asks for "collision-checked rename with a visible
- * error", and half of that had shipped.
+ * one, and nothing said which had won. The shell redesign asked for "collision-checked rename with
+ * a visible error", and half of that had shipped.
  */
 let renameError: { name: string; message: string } | null = null;
 
@@ -1139,7 +1139,7 @@ function emitsField(name: string, def: SignalDef): SignalFieldView {
 /**
  * A function: what it is for, what it takes, what it emits, and its body.
  *
- * Structured bodies (spec §20) are a body MODE rather than a new entity: "Statements" is the
+ * Structured bodies (`spec.md` §20) are a body MODE rather than a new entity: "Statements" is the
  * statement-card editor over `body: JxStatement[]`, "Code" is the text path over `body: string`.
  * Switching modes replaces the body with the other representation's empty seed — an explicit mode
  * change, nothing is converted.
@@ -1189,13 +1189,19 @@ function functionFields(S: SignalsPanelState, name: string, def: SignalDef): Sig
         prop: "Body",
         segments: [
           {
+            checked: statements ? "true" : "false",
             field: "body",
             key: "statements",
             label: "Statements",
-            selected: statements,
             signal: name,
           },
-          { field: "body", key: "code", label: "Code", selected: !statements, signal: name },
+          {
+            checked: statements ? "false" : "true",
+            field: "body",
+            key: "code",
+            label: "Code",
+            signal: name,
+          },
         ],
         signal: name,
       },
@@ -1850,9 +1856,10 @@ function definedSignalNames(): string[] {
 /**
  * Open a state entry's formula in the Bottom dock.
  *
- * It used to be an XPath press matching the row's RENDERED NAME, which plan §13's R1 forbids
- * outright: a panel that starts eliding long names, or grouping differently, breaks a shot by
- * improving the app. The document defines these names, so the document is what validates them.
+ * It used to be an XPath press matching the row's RENDERED NAME, which R1
+ * (`scripts/screenshots/README.md`) forbids outright: a panel that starts eliding long names, or
+ * grouping differently, breaks a shot by improving the app. The document defines these names, so
+ * the document is what validates them.
  *
  * It defaults its target to the one open Data row — the button it replaces is rendered inside that
  * entry's own editor, so "the one that is open" is what a reader means, and with several open it
@@ -1943,7 +1950,7 @@ export function registerSignalsCommands(registry: CommandRegistry): void {
 }
 
 /* THE STATE PANEL IS GONE, AND ITS EDITOR IS IN DATA — `panels/data-explorer.ts`.
-   It was registered here `rail: false`, waiting for plan §11.2's merge into Data, and the merge did
+   It was registered here `rail: false`, waiting for its merge into Data (§5.6), and the merge did
    not follow: the button was removed and the editor was left reachable only by typing "State" into
    the palette. Declaring a state variable — or a component property, which is a state entry with a
    default — is not an advanced move to hide behind a search box, so the entry list is now the Data

package/src/panels/statement-editor.ts

@@ -1,7 +1,7 @@
 /// <reference lib="dom" />
-// oxlint-disable unicorn/no-thenable -- `then` is the JSON Schema conditional keyword (spec §20), not a promise
+// oxlint-disable unicorn/no-thenable -- `then` is the JSON Schema conditional keyword (spec.md §20), not a promise
 /**
- * Statement editor (spec §20) — the FLOW behind the `statements` surface.
+ * Statement editor (`spec.md` §20) — the FLOW behind the `statements` surface.
  *
  * A Function entry's `body: JxStatement[]` is edited here as structure rather than as text: bare
  * expression nodes (mutation or `call`), `if`/`then`/`else` branches, `$switch`/`cases` multiway
@@ -27,8 +27,8 @@
  *   paints them.
  * - **The add-statement control is a menu, not a picker.** It was an `sp-picker` that had to reset
  *   its own value to `""` inside its change handler so the placeholder came back. A document's
- *   binding skips an equal write, so that trick cannot work here — and it should not have to: §12.5
- *   asks for one list of actions, and the kit's menu is it.
+ *   binding skips an equal write, so that trick cannot work here — and it should not have to:
+ *   `studio-ui-guidelines.md` §12.5 asks for one list of actions, and the kit's menu is it.
  *
  * @docs studio/logic/statements
  */
@@ -91,7 +91,7 @@ type LanePath = (string | number)[];
 
 // ─── Statement Kind Detection ────────────────────────────────────────────────
 
-/** Discriminate a statement's kind, mirroring the runtime's detection order (spec §20.2). */
+/** Discriminate a statement's kind, mirroring the runtime's detection order (`spec.md` §20.2). */
 export function statementKind(stmt: unknown): "expression" | "if" | "switch" | "dispatch" {
   if (isJsonObject(stmt)) {
     if ("operator" in stmt) {
@@ -112,7 +112,7 @@ export function statementKind(stmt: unknown): "expression" | "if" | "switch" | "
 
 const ASSIGN_OPS = new Set(["=", "+=", "-=", "*=", "/="]);
 
-/** Card header label — ECMA/WHATWG naming (spec §20.2). */
+/** Card header label — ECMA/WHATWG naming (`spec.md` §20.2). */
 function kindLabel(stmt: unknown): string {
   switch (statementKind(stmt)) {
     case "if": {
@@ -137,7 +137,7 @@ function kindLabel(stmt: unknown): string {
   }
 }
 
-// ─── Add-statement Seeds (spec §20 shapes) ───────────────────────────────────
+// ─── Add-statement Seeds (spec.md §20 shapes) ────────────────────────────────
 
 const STATEMENT_SEEDS: Record<string, () => JxStatement> = {
   call: () => ({ operator: "call", target: { $ref: "" }, value: [] }),
@@ -150,7 +150,10 @@ const STATEMENT_SEEDS: Record<string, () => JxStatement> = {
   switch: () => ({ $switch: { $ref: "" }, cases: {} }),
 };
 
-/** The add-statement menu, in the order the rows read. One list, and this is it (§12.5). */
+/**
+ * The add-statement menu, in the order the rows read. One list, and this is it
+ * (`studio-ui-guidelines.md` §12.5).
+ */
 const STATEMENT_CHOICES: readonly StatementOption[] = [
   { label: "Set state", value: "set" },
   { label: "Call function", value: "call" },
@@ -753,7 +756,7 @@ function markDrop(row: HTMLElement, type?: string): void {
 const islandHosts = new WeakMap<HTMLElement, Map<string, HTMLElement>>();
 
 /**
- * Draw a structured function body (spec §20) into `host`, or bring the one already there up to
+ * Draw a structured function body (`spec.md` §20) into `host`, or bring the one already there up to
  * date. `onChange` receives a fresh statement array on every edit; the input array is never
  * mutated.
  *