@jxsuite/studio 5.2.0 → 5.4.0

package/src/panels/bottom-dock.ts

@@ -1,11 +1,11 @@
 /// <reference lib="dom" />
 /**
- * ⑪ The Bottom dock — where long operations and lists of things-to-fix live (plan §3.2 ⑪).
+ * The Bottom dock — where long operations and lists of things-to-fix live (§16.3).
  *
  * Studio had no bottom dock and at least five surfaces wanted one, so each of them took over the
  * canvas: Code mode, the git diff, the formula workspace and the Monaco function editor all replace
- * the stage, and the progress modal covers the whole app. The canvas is the one region §3 says must
- * never disappear, so this is where those surfaces go instead.
+ * the stage, and the progress modal covers the whole app. The canvas is the one region §16.3 says
+ * must never disappear, so this is where those surfaces go instead.
  *
  * **Under the pane grid, not under the window.** The dock occupies the pane's grid column only, so
  * opening it never narrows the Navigator or the Inspector — which is the difference between a dock
@@ -13,16 +13,17 @@
  *
  * **Three tabs, under a cap of four.** `scripts/check-chrome-budget.ts` caps a dock at four, and
  * this spends three: **Problems · Logic · Activity**, with Deploy folded into Activity because a
- * deploy is a long operation with a log. Diff was the fourth until P8 gave it a pane to open into
- * instead — see {@link registerBottomPanels}. `shell.ts` declares the ids ({@link BOTTOM_TAB_IDS})
- * so a bare Bun process can read `view.setBottomTab`'s enum; this module turns them into records.
+ * deploy is a long operation with a log. Diff was the fourth until a second pane gave it somewhere
+ * to open into instead — see {@link registerBottomPanels}. `shell.ts` declares the ids
+ * ({@link BOTTOM_TAB_IDS}) so a bare Bun process can read `view.setBottomTab`'s enum; this module
+ * turns them into records.
  *
  * **The tabs are panel records, so they inherit everything.** `dock: "bottom"` was already admitted
  * by `registerPanel()` and by the level × placement matrix, and `ui/regions.ts` has parsed
- * `dock.bottom` since P3 — it simply resolved to nothing, because there was no host. This is the
- * host. Every tab gets `dock.bottom/panel:<id>` for free and its title comes from the record.
+ * `dock.bottom` from the start — it simply resolved to nothing, because there was no host. This is
+ * the host. Every tab gets `dock.bottom/panel:<id>` for free and its title comes from the record.
  *
- * **Logic is built, and it is why this dock exists.** P8.5 moves the formula workspace and the
+ * **Logic is built, and it is why this dock exists.** §16.3 moves the formula workspace and the
  * Monaco function editor out of their canvas takeovers and into this tab, so the page whose values
  * they compute stays on screen beside them. Its record is defined beside the surface
  * (`panels/formula-workspace.ts`) and registered from here, like Problems and Activity. Because a
@@ -30,11 +31,10 @@
  * for a Logic target appearing and opens the dock on it — once per target, so closing the dock over
  * an open formula keeps it closed until you open another.
  *
- * **Problems is one of them.** §7.2's table places it here ("Problems | Bottom dock ⑪, badge on the
- * rail") and this dock is its only host. It keeps a rail button and a badge — the rail groups by
- * LEVEL, not by dock — and that button reveals it HERE, which is what `panels/activity-bar.ts`
- * branches on. Its record is defined beside the notification store it renders
- * (`panels/problems-panel.ts`) and registered from here, like every other tab of this dock.
+ * **Problems is one of them.** §16.3 places it here, and this dock is its only host. It has no rail
+ * button: its count sits in the status bar, and clicking the count runs `view.setBottomTab`. Its
+ * record is defined beside the notification store it renders (`panels/problems-panel.ts`) and
+ * registered from here, like every other tab of this dock.
  */
 
 import { render as litRender, nothing } from "lit-html";
@@ -72,10 +72,10 @@ export const BOTTOM_DOCK_SELECTOR = "#bottom-dock";
  *
  * Problems first, because it is the tab the dock opens itself for.
  *
- * **Diff is not among them, and its reserved id is gone.** It was held here through P4–P7 with a
+ * **Diff is not among them, and its reserved id is gone.** It was held here for four phases with a
  * `when: () => false`, and the comment that held it said why it should not be here: `git-diff` is
  * the `diff` EDITOR KIND (`commands/context.ts`), a pane hosts it at pane size, and folding it into
- * a 240px dock would be a downgrade. What it owed was a pane to open into — and P8 shipped that
+ * a 240px dock would be a downgrade. What it owed was a pane to open into — and §18 shipped that
  * (`pane.splitRight`, `canOpenInSecondPane`), so Source Control opens a changed file as a Diff
  * editor in the side pane. A reservation whose capability shipped elsewhere is not a reservation;
  * it is an id in `view.setBottomTab`'s enum that can only ever select a hidden tab. The dock spends
@@ -94,7 +94,7 @@ export function registerBottomPanels(): void {
  * The dock's tabs, in strip order.
  *
  * Ordered by {@link BOTTOM_TAB_IDS} rather than by registration order, because the strip's order is
- * a design decision (§3.2 ⑪ names it) and `shell.ts` is where a bare Bun process can read it. An id
+ * a design decision (§16.3 names it) and `shell.ts` is where a bare Bun process can read it. An id
  * with no record is skipped rather than throwing: the list is also the `args` enum, and a command
  * enum naming a surface that has not registered yet must be inert, not fatal.
  */
@@ -147,7 +147,7 @@ function bottomContext(): NavigatorPanelContext {
   };
 }
 
-/** One tab's label — the record's title, with its badge appended as §3.1 draws it ("Problems 2"). */
+/** One tab's label — the record's title, with its badge appended ("Problems 2"). */
 export function bottomTabLabel(panel: PanelRecord, ctx: CommandContext): string {
   const badge = panel.badge?.(ctx) ?? null;
   return badge === null || badge === 0 || badge === "" ? panel.title : `${panel.title} ${badge}`;
@@ -219,10 +219,10 @@ function logicKey(): string | null {
  * Paint the dock, and stamp the region iff it is on screen.
  *
  * The stamp is conditional on purpose. `REGION_FOR_FOCUS.dock` has pointed at `dock.bottom` since
- * P3, so F6 and `regions.resolve()` will find whatever carries it — and a COLLAPSED dock is a
- * `display: none` box that focus must not land in and a shot must not crop. A closed dock therefore
- * resolves to nothing, and `view.setBottomDock { open: true }` is what makes it addressable, which
- * is exactly what an idempotent setter is for.
+ * before the dock existed, so F6 and `regions.resolve()` will find whatever carries it — and a
+ * COLLAPSED dock is a `display: none` box that focus must not land in and a shot must not crop. A
+ * closed dock therefore resolves to nothing, and `view.setBottomDock { open: true }` is what makes
+ * it addressable, which is exactly what an idempotent setter is for.
  */
 export function renderBottomDock(): void {
   if (!_host) {

package/src/panels/chat-panel.ts

@@ -12,10 +12,19 @@
  * in `ui/regions.ts`'s shell table — the assistant no longer has a shell host to name. Three
  * screenshot shots address that id and none of them changed.
  *
- * Hosts the assistant UI from ai-panel.ts unconditionally: with no project (welcome screen), with a
- * project but no open document, and with a document open. The panel is mounted once at studio boot
- * and never tears down on tab switches — the assistant's module state and DOM (composer draft,
- * scroll position) persist.
+ * Hosts the assistant machinery from ai-panel.ts unconditionally: with no project (welcome screen),
+ * with a project but no open document, and with a document open. The machinery is mounted once at
+ * studio boot and never tears down on tab switches — the assistant's module state (composer draft,
+ * scroll position, transcript) persists.
+ *
+ * **The assistant's SURFACE document is what this module defers.** Mounting `surfaces/ai-chat.ts`
+ * costs a traced 100–290 ms of connectedCallback at boot (its island projections; see
+ * `scripts/perf/REPORT.md`), paid on every window open although the document is invisible until
+ * the tab is picked. Binding is the same seam (`bindAiPanelHost`) and it is now deferred to the
+ * first time the Assistant tab is actually shown or revealed: `renderAiPanel` no-ops while the
+ * surface is null, and the surface's own watcher projects whatever the machinery wrote before that
+ * point, so a prompt seeded into a boot the reader never spends in the tab is not lost — it is one
+ * more message waiting when the body first appears.
  *
  * **This module is the SEAM, and it has no markup of its own.** The assistant is a Jx document
  * (`surfaces/ai-chat.json`), and a document CLEARS the host it is given — so it needs a container
@@ -32,6 +41,7 @@ import { effect, effectScope } from "../reactivity";
 import { workspace } from "../workspace/workspace";
 import { consumePendingAgentPrompt, hasPendingAgentPrompt } from "../services/agent-seed";
 import { REGION_ATTR } from "../ui/regions";
+import { inspectorTab } from "./right-panel";
 import {
   bindAiPanelHost,
   mountAiPanel,
@@ -48,6 +58,23 @@ const ASSISTANT_REGION = "inspector.assistant";
 let _host: HTMLElement | null = null;
 let _container: HTMLElement | null = null;
 let _scope: EffectScope | null = null;
+/** Whether the surface document has been bound. One bind per host; a remount resets it. */
+let _surfaceBound = false;
+
+/**
+ * Bind the assistant's surface document the first time its tab is shown or revealed.
+ *
+ * The container, the region attribute and every prompt path are ready before this; the surface is
+ * the expensive part and is invisible until the tab is picked, so this is the earliest moment its
+ * cost is worth paying. A restore that lands on the Assistant tab binds on the same tick.
+ */
+function ensureAssistantSurface(): void {
+  if (_surfaceBound || !_container) {
+    return;
+  }
+  _surfaceBound = true;
+  bindAiPanelHost(_container);
+}
 
 /**
  * Mount the assistant into the host the Inspector hands it. Idempotent per host: the persistent
@@ -68,11 +95,18 @@ export function mount(host: HTMLElement | null) {
   host.append(_container);
 
   mountAiPanel();
-  bindAiPanelHost(_container);
+  _surfaceBound = false;
 
   _scope?.stop();
   _scope = effectScope();
   _scope.run(() => {
+    effect(() => {
+      // The surface's bind follows the TAB: a session restored onto the Assistant is bound by
+      // One re-run of this effect, not by anyone remembering to call the seam directly.
+      if (inspectorTab() === "assistant") {
+        ensureAssistantSurface();
+      }
+    });
     effect(() => {
       // A pending agent prompt (stored by the New Project flow, possibly from another window) is
       // Keyed by the absolute project root — consume it as soon as this window adopts that root.
@@ -98,6 +132,7 @@ export function mount(host: HTMLElement | null) {
 export function unmount() {
   _scope?.stop();
   _scope = null;
+  _surfaceBound = false;
   // `null` unbinds the surface: the document is disposed and the chat-state watcher stopped.
   bindAiPanelHost(null);
   if (_host) {

package/src/panels/data-explorer.ts

@@ -30,8 +30,8 @@ function rowsUi(): Record<string, boolean> | null {
  *
  * The tree caps arrays at 20, objects at 30 and depth at 5, and printed "… 5 more" as inert text.
  * That is the panel telling you it has the answer and will not show it — the exact case a user
- * opens this panel for is the fetch that returned something unexpected at item 40. Plan §11.2:
- * "truncation markers gain real expand actions."
+ * opens this panel for is the fetch that returned something unexpected at item 40. §5.6: every
+ * truncation marker in the tree is a control.
  *
  * Raising a limit is remembered per marker rather than globally, so opening one long array does not
  * re-render every other one at full length, and it never lowers: a step is a step.
@@ -136,7 +136,7 @@ export function dataTypeLabel(value: unknown) {
 /* THE VALUE LIST IS GONE, AND ITS ROWS ARE THE DEFINITION ROWS — `panels/signals-panel.ts`.
    It listed every state entry with its badge and what it resolved to, one rail tab away from a
    panel listing every state entry with its badge and how it is defined: the same names twice, and
-   you read one to understand the other. Plan §11.2 asks for "definitions + live values in one row",
+   you read one to understand the other. §5.6 asks for definitions and live values in one row,
    so the definition row now carries the resolved type and expands to the value tree, and what is
    left here is the tree WALK, the type label and the row-expansion record the merged rows read. */
 
@@ -369,12 +369,12 @@ export function registerDataExplorerCommands(
  *
  * `level: "document"`, because both belong to the open document.
  *
- * **This is where the State editor lives now.** Plan §11.2 always said so ("State panel + inline
- * editor → Navigator › Data"), but the two halves shipped apart: the rail button was taken away to
- * keep the DOCUMENT group at four, the merge was deferred, and the editor was left reachable only
- * by typing its name into the palette. So the one surface for declaring a state variable — or a
- * component property, which is a state entry with a default — became unfindable, which is a
- * capability lost rather than a control moved.
+ * **This is where the State editor lives now.** §5.6 says so (expanding a row opens the entry's
+ * editor), but the two halves shipped apart: the rail button was taken away to keep the DOCUMENT
+ * group at four, the merge was deferred, and the editor was left reachable only by typing its name
+ * into the palette. So the one surface for declaring a state variable — or a component property,
+ * which is a state entry with a default — became unfindable, which is a capability lost rather than
+ * a control moved.
  *
  * Defining and watching are the same task interrupted: you add an entry, then look at what it
  * resolved to. Two panels made that two panels.

package/src/panels/data-grid.ts

@@ -205,7 +205,7 @@ let actionsState: ActionsState = { pushing: false, testResult: null, testing: nu
 /**
  * The row mounted in each host the settings machinery has handed us.
  *
- * Keyed by the host node, because one settings pane per stage means one host per stage (§4.1) and a
+ * Keyed by the host node, because one settings pane per stage means one host per stage (§18) and a
  * module-level single would make the second pane's row replace the first's.
  */
 const mounted = new Map<HTMLElement, DataActionsSurfaceHandle>();

package/src/panels/editors.ts

@@ -5,13 +5,13 @@
  * It used to take over the canvas: `renderFunctionEditor` cleared `canvasWrap`, dropped every
  * canvas panel and mounted Monaco over the stage, so the page whose handler you were writing was
  * the one thing you could not see while writing it. It is a surface of the Bottom dock's **Logic**
- * tab now (plan §12 P8.5); `panels/formula-workspace.ts` owns that tab's record and calls the two
- * exports below — {@link syncFunctionEditor} from the panel's `afterRender`, and
+ * tab now (§16.3); `panels/formula-workspace.ts` owns that tab's record and calls the two exports
+ * below — {@link syncFunctionEditor} from the panel's `afterRender`, and
  * {@link closeFunctionEditor} for its Close. The container is no longer one of them: the Logic tab
  * is a Jx document (`surfaces/logic-workspace.json`) and it draws the empty
- * {@link CODE_HOST_SELECTOR} node itself, which is what an island is (studio-ui-guidelines.md
- * §9.4). The canvas keeps rendering the page underneath the dock; `canvas/canvas-render.ts` no
- * longer knows this surface exists.
+ * {@link CODE_HOST_SELECTOR} node itself: an island, as studio-ui-guidelines.md §9.4 defines one.
+ * The canvas keeps rendering the page underneath the dock; `canvas/canvas-render.ts` no longer
+ * knows this surface exists.
  *
  * **The mount is driven by the DOM, not by a render call.** A dock tab's body is re-rendered
  * whenever anything it reads changes, and a repaint will happily replace the container element out
@@ -178,9 +178,9 @@ export function syncFunctionEditor(host: HTMLElement): void {
  *   work was the one that destroyed it.
  *
  * The takeover never saw this because it was torn down by exactly one thing (closing it, which
- * happened to be slower than the debounce). A dock tab is torn down by five, four of them new in
- * P8. Handling it here rather than guarding inside each callback is deliberate: a guard on "is this
- * still the current editor?" is passed by a timer that fires after a REMOUNT.
+ * happened to be slower than the debounce). A dock tab is torn down by five, four of them new with
+ * the pane grid (§18). Handling it here rather than guarding inside each callback is deliberate: a
+ * guard on "is this still the current editor?" is passed by a timer that fires after a REMOUNT.
  *
  * **But cancelling alone is the same loss with the alarm switched off.** The armed commit IS the
  * last half-second of typing; dropping it means the pre-typing body survives instead of an empty

package/src/panels/elements-panel.ts

@@ -265,15 +265,14 @@ export function mountElementsPanel(ctx: NavigatorPanelContext, host: HTMLElement
 /**
  * Contribute the Insert panel — **off the rail** (`rail: false`).
  *
- * §3.2 ② removes Elements from the Navigator rail because it is not a view of anything: it is an
- * insert palette, and a palette belongs at the caret (slash menu), on the canvas (`+`) and behind
- * ⌘⇧A, all of which are P3.5's Insert command family. The record survives that interval so the
- * surface stays reachable — `view.setActivity {tab:"insert"}`, the palette, and the screenshot
- * pipeline all still address it — and giving up its rail slot is what keeps the DOCUMENT group at
- * four.
+ * §5.1 keeps Insert off the Navigator rail because it is not a view of anything: it is an insert
+ * palette, and a palette belongs at the caret (slash menu), on the canvas (`+`) and behind ⌘⇧A, all
+ * of which are the Insert command family. The record survives so the surface stays reachable —
+ * `view.setActivity {tab:"insert"}`, the palette, and the screenshot pipeline all still address it
+ * — and giving up its rail slot is what keeps the DOCUMENT group at four.
  *
- * `level: "document"`, per principle 3's own worked example: it READS the project's component
- * registry and WRITES the document tree.
+ * `level: "document"`, per §13.2's own worked example: it READS the project's component registry
+ * and WRITES the document tree.
  */
 export function registerInsertPanel(): void {
   registerPanel({

package/src/panels/empty-state.ts

@@ -68,7 +68,7 @@ export function staleSelectionMessage(): string {
  *
  * Quick Access is reached through a lazy import on purpose: this module is imported by every panel
  * in the shell, and a static edge would drag the file browser, the format host and the recents
- * store into all of them. P2 replaces the closure with a command id.
+ * store into all of them. A command id would replace the closure.
  */
 export function openPageAction(label = "Open a page…"): EmptyStateAction {
   return {

package/src/panels/events-panel.ts

@@ -3,11 +3,11 @@
  * The Logic tab — everything about how this element BEHAVES. The FLOW behind the `logic-panel`
  * surface.
  *
- * Plan §6.5 re-split the inspector by task rather than by data type, and this is the tab that
- * gained by it. Wiring a `$switch`, wiring a repeater to a collection and wiring a click handler
- * are one job; they were three, split across two tabs, because a `$switch` is stored as a property
- * and a click handler is stored as a property-shaped function, and the old split followed the
- * storage. So Logic is now:
+ * The inspector is split by task rather than by data type (§6), and this is the tab that gained by
+ * it. Wiring a `$switch`, wiring a repeater to a collection and wiring a click handler are one job;
+ * they were three, split across two tabs, because a `$switch` is stored as a property and a click
+ * handler is stored as a property-shaped function, and the old split followed the storage. So Logic
+ * is now:
  *
  * - **Repeating list** — the `$prototype: "Array"` node's items / filter / sort, and its template.
  * - **Condition** — the `$switch` expression and its cases.
@@ -28,8 +28,9 @@
  * Three things the conversion settled, and each was a defect rather than a translation:
  *
  * - **A binding had two controls that did the same thing.** The provenance chip cleared the key and
- *   the trash button beside it cleared the same key. §12.5 calls a second list of actions a defect;
- *   there is one control now, and it carries the dot that says whether the selection agrees.
+ *   the trash button beside it cleared the same key. studio-ui-guidelines.md §12.5 calls a second
+ *   list of actions a defect; there is one control now, and it carries the dot that says whether
+ *   the selection agrees.
  * - **The sections would not stay shut.** Repeating list, Condition and Events were rendered with a
  *   hard-coded `open`, so collapsing one lasted until the next repaint. They persist through
  *   `inspectorSections` like every other section in the dock.
@@ -114,9 +115,9 @@ import type {
  * The events worth SUGGESTING — not the events an element may have.
  *
  * These ten were a closed `sp-picker`, so `ondragover`, `onpointerdown`, `onwheel`, `onpaste` and
- * every custom event a component emits were unbindable from the Inspector: the plan's §6.5 asks for
- * "a free-form combobox instead of a hard-coded list of ten". The list is still ten, and it is a
- * list of SUGGESTIONS now — the menu's last row asks for any other name.
+ * every custom event a component emits were unbindable from the Inspector. An event name is typed,
+ * not picked (§6.1): the list is still ten, and it is a list of SUGGESTIONS now — the menu's last
+ * row asks for any other name.
  */
 export const EVENT_NAMES = [
   "onclick",
@@ -159,7 +160,7 @@ function seedForHandlerMode(mode: SlotMode, functionDefs: [string, unknown][]):
 // ─── The Mixed contract ──────────────────────────────────────────────────────
 
 /**
- * The Logic tab's Mixed contract (§6.5), stated once because it is a judgement, not a mechanism.
+ * The Logic tab's Mixed contract (§6.7), stated once because it is a judgement, not a mechanism.
  *
  * Wiring splits in two, and a multi-selection treats the halves differently:
  *
@@ -917,7 +918,7 @@ function watch(): void {
 
 // ─── The menus ───────────────────────────────────────────────────────────────
 
-/** The rung picker for a bindable row: every source this position permits, one action away (§6.3). */
+/** The rung picker for a bindable row: every source this position permits, one action away (§6.6). */
 function openSourceMenu(key: string, anchor: HTMLElement): void {
   const plan = plans.fields.get(key);
   if (!plan || !canMove(plan.mode, plan.offered)) {

package/src/panels/formula-workspace.ts

@@ -1,15 +1,15 @@
 /// <reference lib="dom" />
 /**
- * ⑪ · Logic — the flow behind the Bottom dock's Logic tab.
+ * Logic — the flow behind the Bottom dock's Logic tab.
  *
  * **What changed, and why it is the whole point.** Both of these surfaces used to TAKE OVER the
  * canvas: `TabUi.editingFormula` (this file) and `TabUi.editingFunction` (`panels/editors.ts`) each
  * cleared `canvasWrap`, dropped every canvas panel and drew themselves over the stage. So the one
  * artefact whose values you are authoring — the page — was the one thing you could not see while
  * authoring them, and the workspace's own data rail existed to paper over it: a frozen snapshot of
- * a scope, shown because the live thing had just been unmounted. Plan §12 P8.5: "no editor hides
- * the page it computes." They are a **tab of the Bottom dock** now (§3.2 ⑪), which sits under the
- * pane grid, so the page renders beside the formula and keeps rendering while you edit it.
+ * a scope, shown because the live thing had just been unmounted. No editor may hide the page it
+ * computes (§16.3). They are a **tab of the Bottom dock** now, which sits under the pane grid, so
+ * the page renders beside the formula and keeps rendering while you edit it.
  *
  * **A dock tab is not a reparented takeover.** The surface has to work at dock height, so the
  * header is one row, the chip pipeline and the result are single lines, and the data rail is a
@@ -93,7 +93,10 @@ export type LogicTarget =
   | { surface: "function"; editing: FunctionEditDef }
   | { surface: "formula"; editing: FormulaEditDef };
 
-/** The sentence the tab shows with nothing open in it — what the region is FOR (§11.1). */
+/**
+ * The sentence the tab shows with nothing open in it — what the region is FOR
+ * (studio-ui-guidelines.md §11.1).
+ */
 const NOTHING_OPEN = "Open a formula or a function to edit it here, beside the page it computes.";
 
 /** The target names a document position that holds no expression: say so, keep the header. */

package/src/panels/frontmatter-fields.ts

@@ -128,7 +128,10 @@ export interface FmRowView {
   label: string;
   /** Which control the row draws. */
   kind: "text" | "number" | "boolean" | "select" | "media";
-  /** Whether the value is set on this document — §4.2's dot, and the row's only clear affordance. */
+  /**
+   * Whether the value is set on this document — studio-ui-guidelines.md §4.2's dot, and the row's
+   * only clear affordance.
+   */
   isSet: boolean;
   /** The text, number or chosen value, always as a string. Empty for a boolean row. */
   value: string;

package/src/panels/frontmatter-panel.ts

@@ -1,25 +1,30 @@
 /// <reference lib="dom" />
 /**
- * The Document Header card (§3.2 ⑧) — the artefact's own header, drawn IN the stage.
+ * The Document Header card — the artefact's own header, drawn IN the stage.
  *
  * It replaces the old "Properties" bar, which was a fourth full-width band that **appeared and
  * vanished as a side effect of the canvas mode** with no control to summon it, and which showed
  * nothing at all unless `findContentTypeSchema` matched the document to a content collection — so
  * it never appeared on the default home page, the one document every new author opens first.
  *
- * Three gates are gone, and each was a lie about what the card is for:
+ * Two gates are gone, and each was a lie about what the card is for:
  *
  * - The **collection gate** (`if (!fieldSet?.collection)`) — a page's `title` is frontmatter whether
  *   or not a collection schema describes it;
- * - The **mode gate** (`getCanvasMode() === "edit"`) — the header is part of the document, not a view
- *   of it, so switching to Design must not delete it;
  * - The **document-mode gate** (`doc.mode === "content"`) — a JSON page carries `title` and `$head`
  *   directly on the root node, and it has a header for exactly the same reason.
  *
- * What it renders instead: **any** document with frontmatter or `$head`, in every named layout and
- * in both authoring views of the stage — Title, Route, the layout picker, the
- * schema-and-frontmatter field list, the door to Search appearance and a "Raw head tags"
- * disclosure. `hasDocumentHeader` is the whole predicate, and it is a fact about the DOCUMENT.
+ * What it renders instead: **any** document with frontmatter or `$head`, in every named layout —
+ * Title, Route, the layout picker, the schema-and-frontmatter field list, the door to Search
+ * appearance and a "Raw head tags" disclosure. `hasDocumentHeader` is this module's whole
+ * predicate, and it is a fact about the DOCUMENT.
+ *
+ * **The canvas mode is the STAGE's question, and this module still takes none.** The stage draws a
+ * host for the card in Edit only (`wantsDocHeader` in `canvas/canvas-render.ts`): Design gives its
+ * artboards the whole pane, and the Navigator's Page panel carries the same fields in every mode,
+ * so nothing is out of reach in either. The old mode gate lived HERE, as a `getCanvasMode()` check
+ * the card ran to decide whether to exist; the decision now has one owner, the frame that draws the
+ * page, and this module draws into whatever host it is handed.
  *
  * **One reserved-key policy, one `collectFmFields` call.** The two field sets this card merges used
  * to disagree: this module passed an empty reserved set and `head-panel.ts` passed `{title}`, so
@@ -29,7 +34,8 @@
  * **The card has no host of its own.** `#frontmatter-panel` — the grid row, the `hidden` div, the
  * `frontmatterPanelEl` ref and the 40vh cap that came with them — is deleted. The STAGE renders the
  * host now ({@link attachDocumentHeaderHost}, called from the stage document's `onNodeCreated` in
- * `canvas/canvas-render.ts`), so the card sits inside the artefact rather than in a band above it.
+ * `canvas/canvas-render.ts`), so the card is docked above the page, as wide as the pane, rather
+ * than in a band the shell drew above every stage.
  *
  * **The card is a Jx document now** (`src/surfaces/doc-header.json`), and this module is the flow
  * behind it: it decides which document a pane's card is drawn for, which rows that document has,
@@ -55,7 +61,7 @@
  * ids behind a `#/content/<type>` reference are a read (`ui/form-controls.ts`), so the card draws
  * its own control for each and calls the owner for the part that is not markup. Neither module's
  * lit template is interpolated here — a document and a lit template cannot share a container, and
- * §9.4 forbids the mix outright.
+ * studio-ui-guidelines.md §9.4 forbids the mix outright.
  *
  * @docs studio/editing/frontmatter
  */
@@ -170,8 +176,8 @@ export function attachDocumentHeaderHost(paneId: string, el: HTMLElement | null)
 /* There is no `documentHeaderHost` getter any more, and its absence is the point.
    It existed for ONE caller: the stage's lit `ref`, which was told about a removal WITHOUT being
    told which node had gone, so it had to read the host back and ask whether it was still connected
-   before deciding the report was about the host it held. `surfaces/canvas-stage.json` states both
-   placements as a view, so a frame that draws no card simply announces none and `renderCanvasImpl`
+   before deciding the report was about the host it held. `surfaces/canvas-stage.json` states the
+   card's slot as a view, so a frame that draws no card simply announces none and `renderCanvasImpl`
    releases the slot in one place — there is nothing left to settle after the fact, and a getter
    whose only reader is gone is a fact about the module nobody is entitled to. */
 
@@ -360,12 +366,6 @@ function viewFor(tab: Tab, paneId: string, card: HeaderCard): DocHeaderView {
   return {
     collection: collection ? collection.name : "Document",
     hasRoute: route !== null,
-    /* The stage's two placements, read off the host it handed over. In Edit the card is a block of
-       the document's own column; in Design it is pinned above a pan/zoom surface at 1:1, and only
-       that one wants the band's edge rather than the card's. `surfaces/canvas-stage.json` says the
-       same thing from the STAGE's side, which a document's own scoped style block cannot answer —
-       and it says it on `data-placement` rather than on a class, because the stage emits none. */
-    placement: card.el.dataset["placement"] === "pinned" ? "pinned" : "in-column",
     rawEntries: raw,
     rawOpen: _rawOpen.has(tab.id),
     rawState: raw.length === 0 ? "empty" : "list",

package/src/panels/git-panel.ts

@@ -23,8 +23,8 @@
  * light dismissal and Escape, so both the markup and the flag go.
  *
  * The third is the empty states. A document cannot call a lit helper, so the three this panel used
- * to render are drawn in the document — under the same §11 copy rules, and, for the two that offer
- * buttons, with the buttons still real. This was the last caller that passed
+ * to render are drawn in the document — under the same studio-ui-guidelines.md §11 copy rules, and,
+ * for the two that offer buttons, with the buttons still real. This was the last caller that passed
  * `EmptyStateAction.icon`, a `TemplateResult` of `sp-icon-*`, and the field went with it.
  *
  * @docs studio/publish/source-control
@@ -412,9 +412,9 @@ let _deps: GitPanelDeps = {};
  *
  * A `<select>` always holds one of its options, and picking "New branch…" must put the control back
  * on the current branch when the dialog is dismissed. A document's binding only writes when the
- * SCOPE MOVES (guidelines §9.3), so writing the current branch over a scope that already said it
- * would be a no-op and the control would keep saying "New branch…". Announcing what the reader
- * actually chose first is what makes putting it back a change.
+ * SCOPE MOVES (studio-ui-guidelines.md §9.3), so writing the current branch over a scope that
+ * already said it would be a no-op and the control would keep saying "New branch…". Announcing what
+ * the reader actually chose first is what makes putting it back a change.
  */
 let _branchOverride: string | null = null;
 
@@ -700,8 +700,9 @@ async function discardFile(path: string): Promise<void> {
  * The split button's second half.
  *
  * The kit menu, not a `<div>` of this panel's own: `openMenu()` owns the popover, the roving focus,
- * the light dismissal and Escape, and it is the answer this shell already settled on (§8.4). One
- * row, because there is one thing "Commit and sync" can do differently.
+ * the light dismissal and Escape, and it is the answer this shell already settled on
+ * (studio-ui-guidelines.md §8.4). One row, because there is one thing "Commit and sync" can do
+ * differently.
  */
 function openCommitMenu(anchor: HTMLElement): void {
   /* Lazily imported for the reason `panels/problems-panel.ts` and `panels/empty-state.ts` already
@@ -978,9 +979,10 @@ export function sourceControlCommands(): AnyCommand[] {
       // `when` already asked about the project; an `enablement` that re-asks is the same rule
       // Written twice, and the two places drift.
       enablement: (ctx) => !ctx.project.isRepo,
-      /* No `aiTool`, by §12.4's third deletion rule: outside the tree, irreversible, and the model
-         has no read to judge by. The git family is reconsidered together when `git.commit` becomes
-         a record — without it the agent could not ship its own edits anyway. */
+      /* No `aiTool`, by studio-ui-guidelines.md §12.4's third deletion rule: outside the tree,
+         irreversible, and the model has no read to judge by. The git family is reconsidered
+         together when `git.commit` becomes a record — without it the agent could not ship its own
+         edits anyway. */
       run: async () => {
         await initRepository();
       },
@@ -1003,8 +1005,8 @@ export function sourceControlCommands(): AnyCommand[] {
       requires: "a project tracked by git",
       when: (ctx) => ctx.project.open,
       enablement: (ctx) => ctx.project.isRepo,
-      /* No `aiTool`, by §12.4's third deletion rule: it creates a repository on the person's
-         account. Same family as `git.init`. */
+      /* No `aiTool`, by studio-ui-guidelines.md §12.4's third deletion rule: it creates a
+         repository on the person's account. Same family as `git.init`. */
       run: async () => {
         await createGithubRepository({ projectName: projectState?.name || "my-project" });
       },
@@ -1019,7 +1021,8 @@ export function sourceControlCommands(): AnyCommand[] {
       requires: "a project tracked by git",
       when: (ctx) => ctx.project.open,
       enablement: (ctx) => ctx.project.isRepo,
-      /* No `aiTool`, by §12.4's third deletion rule. Same family as `git.init`. */
+      /* No `aiTool`, by studio-ui-guidelines.md §12.4's third deletion rule. Same family as
+         `git.init`. */
       run: async () => {
         await pushCurrentBranch();
       },
@@ -1073,6 +1076,9 @@ export function registerGitPanel(): void {
   registerPanel({
     id: "git",
     title: "Source Control",
+    /* The full title is 71px against the rail's 48px label box. The header, the tooltip and the
+       accessible name keep it; only the words under the glyph shorten. */
+    railLabel: "Source",
     level: "project",
     dock: "navigator",
     // A KEY into the kit's icon manifest, not a tag: this one resolves to

package/src/panels/head-panel.ts

@@ -480,8 +480,8 @@ export interface SeoField extends ResolvedHeadField {
  * Character budgets, in the only role a number is allowed here: a counter's reference line.
  *
  * There is deliberately no score. A single figure out of a hundred aggregates unrelated facts into
- * a verdict, and the verdict is what gets optimised (plan §14). A count beside a limit says the
- * same thing without pretending to rank it.
+ * a verdict, and the verdict is what gets optimised (§16.6). A count beside a limit says the same
+ * thing without pretending to rank it.
  */
 export const SEO_LIMITS: Readonly<Record<string, number>> = {
   description: 160,
@@ -589,7 +589,7 @@ function hasTitleEntry(layers: HeadLayers): boolean {
  *
  * Every one of them states a consequence rather than a grade, and every one is checkable against
  * `head-merger.ts`. "Missing" is decided on the MERGED value, so a page that inherits a description
- * from the site is never told it has none — the defect §9.2 names by name.
+ * from the site is never told it has none — the defect site-architecture.md §8.6 names by name.
  *
  * @param {SeoPreview} preview — `warnings` is ignored; this computes it.
  * @param {HeadLayers} layers
@@ -875,8 +875,8 @@ export function buildHeadDoc(doc: JxMutableNode, fm: Record<string, unknown>): J
  * mutation it makes — Title, Clear title, the Layout picker — as does Search appearance, which is
  * where the head fields went and which takes its tab the same way. The card is drawn per pane, so
  * on a markdown page the card in one pane retitled the document in the other. The comment beside
- * the card's JSON branch has claimed since P8 that this was fixed; the fix reached the JSON branch
- * only, and this is the half that was left.
+ * the card's JSON branch has claimed since the pane grid landed that this was fixed; the fix
+ * reached the JSON branch only, and this is the half that was left.
  *
  * @param {Tab | null} tab The document to commit into.
  * @param {() => void} rerender
@@ -1174,8 +1174,8 @@ function customEntries(head: JxHeadEntry[]): PageTagRow[] {
  * Everything the panel says about one document, and the commit table behind it.
  *
  * `activeTab.value` is read HERE and nowhere below it: the Navigator's Page panel is an app-level
- * surface that shows the focused document by definition (§3.2), and spelling that out once at the
- * top is what lets every helper under it take a tab instead of asking for one.
+ * surface that shows the focused document by definition, and spelling that out once at the top is
+ * what lets every helper under it take a tab instead of asking for one.
  */
 function view(ctx: PagePanelContext): PagePanelView {
   _commits.clear();
@@ -1454,9 +1454,8 @@ export function renderHeadTemplate(_against: PagePanelContext): typeof nothing {
  * Contribute the Page panel.
  *
  * `level: "document"` — title, description, social card and custom `$head` entries are the open
- * document's. The id is `page` now: "head" named an HTML element, and §3.2's DOCUMENT group calls
- * the surface Page. P3.10 moves these fields into the in-stage Document Header card; until then the
- * record is what keeps the surface addressable under one name.
+ * document's. The id is `page` now: "head" named an HTML element, and §5.1's Document group calls
+ * the surface Page. The record is what keeps the surface addressable under one name.
  */
 export function registerPagePanel(): void {
   registerPanel({