@jxsuite/studio 5.3.0 → 5.4.0

package/src/panels/jump-bar.ts

@@ -1,16 +1,16 @@
 /// <reference lib="dom" />
 /**
- * ⑥ The jump bar — the pane's address, and every place you can go from it.
+ * The jump bar — the pane's address, and every place you can go from it.
  *
  * **The two half-breadcrumbs this replaces.** Studio grew two trails, neither of which could say
  * where you were:
  *
- * 1. `panels/pane-context.ts`'s `navTpl()` (the old `#tab-bar` breadcrumb, plan §3.2 ⑥ names it as
- *    `tab-bar.ts:129-185`) — a `Back` button plus one span per `session.documentStack` frame. It
- *    appeared ONLY while you were inside a sub-document, printed the frame's file basename (which
- *    is the SAME basename for a `$map` template, so it read `index.json › index.json`), and knew
- *    nothing about the project above it or the selection below it. It is deleted, and so is the
- *    stack it walked: nothing ever pushed a frame, so it could only ever draw its empty branch.
+ * 1. `panels/pane-context.ts`'s `navTpl()` (the old `#tab-bar` breadcrumb, `tab-bar.ts:129-185`) — a
+ *    `Back` button plus one span per `session.documentStack` frame. It appeared ONLY while you were
+ *    inside a sub-document, printed the frame's file basename (which is the SAME basename for a
+ *    `$map` template, so it read `index.json › index.json`), and knew nothing about the project
+ *    above it or the selection below it. It is deleted, and so is the stack it walked: nothing ever
+ *    pushed a frame, so it could only ever draw its empty branch.
  * 2. `surfaces/statusbar.ts`'s selection field — a clickable ancestor trail, `selection.set` per
  *    crumb. It appeared ONLY while something was selected, and knew nothing about the document it
  *    was inside.
@@ -23,12 +23,12 @@
  *   project        file              selection ancestors
  * ```
  *
- * **The status bar keeps only what an address cannot say.** Plan §3.2 ⑫ and `studio.md` §16.2 give
- * the bar AMBIENT STATE, and an ancestor trail in a second place is exactly the duplication the
- * shell redesign exists to remove — three breadcrumbs would be worse than the two we started with.
- * So the trail moves here whole, and `statusbar/selection` keeps the two facts this bar cannot
- * state: HOW MANY things are selected (a count is not a path) and which Stylebook rule the Style
- * panel is editing (a selector is not a node).
+ * **The status bar keeps only what an address cannot say.** `studio.md` §16.2 gives the bar AMBIENT
+ * STATE, and an ancestor trail in a second place is exactly the duplication the shell redesign
+ * exists to remove — three breadcrumbs would be worse than the two we started with. So the trail
+ * moves here whole, and `statusbar/selection` keeps the two facts this bar cannot state: HOW MANY
+ * things are selected (a count is not a path) and which Stylebook rule the Style panel is editing
+ * (a selector is not a node).
  *
  * **Every interactive item is a command, resolved from the registry.** There is no click handler in
  * this file that names behaviour: a segment names a command id and its args, and the registry
@@ -47,7 +47,7 @@
  * (studio-ui-guidelines.md §6, §9.3). What stays here is the part that is a decision: which pane
  * this bar is about, what its address is, which of its steps the registry can run, and what a
  * chevron opens — and the chevron opens the KIT MENU, `surfaces/menu.ts`, because a list of
- * commands is what that surface already is (§12.5).
+ * commands is what that surface already is (studio-ui-guidelines.md §12.5).
  */
 
 import { displayTagName } from "@jxsuite/schema/guards";
@@ -81,7 +81,8 @@ const JUMP_BAR_HEIGHT = 24;
 
 /**
  * What a segment addresses. The kind is stamped on the element so a test — and a shot — can name a
- * step of the address without matching its rendered text, which is derived (§13 R1).
+ * step of the address without matching its rendered text, which is derived (the shot contract's R1,
+ * `scripts/screenshots/README.md`).
  */
 export type JumpSegmentKind = "project" | "file" | "editor" | "node";
 
@@ -301,7 +302,7 @@ export function jumpSegments(
 function editorSegment(sigil: string, def: FunctionEditDef | FormulaEditDef): JumpSegment {
   return {
     choices: [],
-    // No command, and none is missing: the Logic tab's own header carries the Close (P8.5), which
+    // No command, and none is missing: the Logic tab's own header carries the Close (§16.3), which
     // Is where a reader looking at the editor already is. A second exit up here would be a button
     // Beside the address that means "stop being at this address" — and the pane context bar drew
     // Exactly that, a Back of its own, until this excision removed it.
@@ -350,7 +351,7 @@ function segmentTitle(registry: CommandRegistry, segment: JumpSegment, id: strin
  *
  * An unregistered or invisible command makes the step a READOUT rather than removing it, and more
  * than one alternative is what earns a chevron: one is not a choice, and a control that cannot move
- * is chrome (§2 principle 9).
+ * is chrome (studio-ui-guidelines.md §12.2).
  */
 function projectStep(
   registry: CommandRegistry | null,
@@ -411,7 +412,8 @@ export function dismissJumpMenu(): void {
  * The rows are built from the segment's choices, and every row runs a command — the same command
  * the segment itself names, with a different path. Nothing here decides what selecting means, and
  * nothing here draws a panel: `surfaces/menu.ts` owns the roving caret, typeahead, Escape and light
- * dismissal, because a list of commands is what that surface already is (§12.5).
+ * dismissal, because a list of commands is what that surface already is: a second one is the defect
+ * studio-ui-guidelines.md §12.5 names.
  */
 function openChoices(segment: JumpSegment, anchor: HTMLElement | null): void {
   const registry = activeRegistry();

package/src/panels/layers-panel.ts

@@ -16,13 +16,13 @@
  *
  * **Rows are `registry.forPlacement("outline/row")`.** Every row used to carry five hand-built
  * action buttons, always visible, on every row. They collapse to the selected row plus the hovered
- * one, which is Gutenberg's rule and the one plan §3.2 ⑩ codifies: the floating bar owns
- * selection-scoped verbs, the inspector owns values. The verbs, their names, their chords and their
- * disabled reasons all come from the records in `block-action-bar.ts` — the surface renders, it
- * does not decide. A row that is neither selected nor hovered is projected with an EMPTY command
- * list, so the cluster costs nothing rather than being hidden by a rule: a `display: none` kit
- * element is still an upgraded custom element, which is the whole cost the collapse exists to
- * remove.
+ * one, which is Gutenberg's rule and the one studio-ui-guidelines.md §12.1 codifies: the floating
+ * bar owns selection-scoped verbs, the inspector owns values. The verbs, their names, their chords
+ * and their disabled reasons all come from the records in `block-action-bar.ts` — the surface
+ * renders, it does not decide. A row that is neither selected nor hovered is projected with an
+ * EMPTY command list, so the cluster costs nothing rather than being hidden by a rule: a `display:
+ * none` kit element is still an upgraded custom element, which is the whole cost the collapse
+ * exists to remove.
  *
  * **A row says something.** On a real page the tree was a wall of rows all reading "div": only
  * text-bearing nodes got a preview and containers got the tag they already wear as a coloured
@@ -504,7 +504,8 @@ function selectModelRow(index: number, gesture: { range?: boolean } = {}): void
 }
 
 /**
- * Apply one row activation to the selection, honouring the two accumulate gestures (§6.5).
+ * Apply one row activation to the selection, honouring the two accumulate gestures
+ * (studio-ui-guidelines.md §8.1).
  *
  * - Plain: replace the selection with this path. **This is the only branch a keyboard walk or an
  *   unmodified click can reach, and it is byte-identical to what the Outline always did.**
@@ -1254,9 +1255,10 @@ export function mountOutlinePanel(
         editInput,
         editReady: (element) => {
           /* On a microtask, because `onNodeCreated` fires as the node is BUILT and one tick before
-             it is in the document — which is exactly why it is the seam (guidelines §9.4): it
-             hands over the element earlier than awaiting the mount would, and the host decides
-             when it is worth anything. An unconnected input cannot take focus. */
+             it is in the document — which is exactly why it is the seam
+             (studio-ui-guidelines.md §9.4): it hands over the element earlier than awaiting the
+             mount would, and the host decides when it is worth anything. An unconnected input
+             cannot take focus. */
           queueMicrotask(() => {
             const input = element as HTMLInputElement;
             if (input.isConnected) {
@@ -1267,10 +1269,10 @@ export function mountOutlinePanel(
         },
         expand: expandOutlineRow,
         emptyAction: () => {
-          /* `"insert"`, not `"blocks"`. The panel was renamed in P3.1 and this call kept the old id
-             for three phases, so the one action an empty page offers landed the Navigator on "No
-             Navigator panel is registered as blocks". `setActivityTab` takes a `NavigatorPanelId`
-             now, so this cannot recur. */
+          /* `"insert"`, not `"blocks"`. The panel was renamed with the registry-driven rail (§5.1),
+             and this call kept the old id for three phases, so the one action an empty page offers
+             landed the Navigator on "No Navigator panel is registered as blocks". `setActivityTab`
+             takes a `NavigatorPanelId` now, so this cannot recur. */
           setActivityTab("insert");
         },
         hover: hoverRow,
@@ -1350,8 +1352,8 @@ export function detachOutline(): void {
  * Contribute the Outline panel.
  *
  * `level: "document"` — it writes the open document's tree (reorder, rename, delete, duplicate).
- * "Outline" rather than "Layers" is §3.2 ③'s name for it; the id stays `layers` because that is
- * what `view.setActivity` and 26 screenshot steps address it by, and an id is not a label.
+ * "Outline" rather than "Layers" is §5.1's name for it; the id stays `layers` because that is what
+ * `view.setActivity` and 26 screenshot steps address it by, and an id is not a label.
  */
 export function registerLayersPanel(): void {
   registerPanel({

package/src/panels/left-panel.ts

@@ -6,8 +6,8 @@
  * no-document copy table and the two post-render special cases are gone: this file resolves ONE
  * record from the panel registry, hands the document its name and its level, renders its `render`
  * into the content island, and calls its `afterRender`. Everything a panel is — its name, its
- * level, its empty state, its drag registrations — is declared beside the state it writes (plan §2
- * principle 1).
+ * level, its empty state, its drag registrations — is declared beside the state it writes (one
+ * definition site per action, studio.md §13).
  *
  * **The box is `surfaces/navigator-dock.json` now, and the body is still lit.** A `PanelRecord`'s
  * `render` returns a lit template, so the panel body cannot be a document; the dock draws the
@@ -108,7 +108,7 @@ export function mount(deps: NavigatorPanelDeps) {
         void tab.doc.document;
         void tab.doc.mode;
         // 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("|");
       }
       render();

package/src/panels/navigator-panels.ts

@@ -16,11 +16,11 @@
  * advertisement, in the shell's own furniture, for a place to find things wrong with the product.
  * The count reaches the user from the status bar the moment there is one.
  *
- * **Search is declared and hidden.** It is a surface a later phase builds (P3.3's palette index),
- * and it holds a rail slot §3.2 has already spent. A `when: () => false` record is the honest way
- * to say "this exists in the design and not yet in the app": the id is reserved, the budget already
- * counts it, and the day it ships the only edit is deleting one predicate — as opposed to a stub
- * button that lies to whoever clicks it.
+ * **Search is declared and hidden.** It is a surface a later phase builds (the palette's project
+ * index), and it holds a slot in the rail's four-tab budget (`studio-ui-guidelines.md` §12.2). A
+ * `when: () => false` record is the honest way to say "this exists in the design and not yet in the
+ * app": the id is reserved, the budget already counts it, and the day it ships the only edit is
+ * deleting one predicate — as opposed to a stub button that lies to whoever clicks it.
  */
 
 import { registerFilesPanel } from "../files/files";
@@ -79,11 +79,11 @@ export function registerNavigatorPanels(): void {
   // ── Off-rail: reachable by command and palette, no rail button ──────────────
   registerInsertPanel();
 
-  // ── The Bottom dock's tabs (§3.2 ⑪): Problems · Logic · Activity ────────────
+  // ── The Bottom dock's tabs (§16.3): Problems · Logic · Activity ──────────────
   // Composed here, in the one place panel records are gathered, so the shell has ONE composition
   // Site rather than one per dock. Importing the module is also what attaches the dock to the
-  // Shell's mount lifecycle — see its `registerShellSurface` call. Problems arrives with them and
-  // Still takes the rail's fourth PROJECT slot, because the rail groups by level, not by dock.
+  // Shell's mount lifecycle — see its `registerShellSurface` call. Problems arrives with them and,
+  // Like every Bottom-dock tab, has no rail button (§16.3).
   registerBottomPanels();
 }
 

package/src/panels/overlays.ts

@@ -42,7 +42,7 @@ export function mount(ctx: OverlaysCtx) {
       // Track selection, hover, mode, and the active panel (a hit in another breakpoint panel — or
       // A header click — re-anchors the block action bar even when the selection path is unchanged).
       // 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.hover;
       void tab.doc.mode;

package/src/panels/pane-context.ts

@@ -1,12 +1,12 @@
 /// <reference lib="dom" />
 /**
- * The pane's own chrome — region ⑦ (context bar) and region ⑩ (the floating zoom pod).
+ * The pane's own chrome — the pane context bar and the floating zoom pod.
  *
  * This replaces `#tab-bar`, which was a 28px band styled identically to the tab strip above it,
  * holding **five unrelated axes** with no labels on any of them: a document-stack breadcrumb
  * (navigation), a zoom widget (viewport), route params and component test props (document data), a
- * colour-scheme switch and feature toggles (rendering state), and Export (a mode action). Plan §3.2
- * ⑦ replaces them with three axes that each say what they are:
+ * colour-scheme switch and feature toggles (rendering state), and Export (a mode action). The pane
+ * context bar replaces them with three axes that each say what they are:
  *
  * - **Editor kind** — `Canvas ⌄`, offering only the kinds this document declares. A document with one
  *   kind renders the name as text rather than as a dropdown that cannot go anywhere.
@@ -15,10 +15,10 @@
  *   Canvas. The two are drawn apart because they are two axes: preview is a flag over an edit or
  *   design base, so the radio marks the base throughout and the toggle says whether it is on.
  * - **Rendering context** — `md ⌄ Light ⌄`, folding the size breakpoint, the colour scheme, the
- *   feature queries and the layout show/hide switch into one popover. Per §2 principle 5 this
- *   control **only selects**; its footer is "Manage contexts…", which routes to the definition site
- *   — Project Settings › Contexts (`settings/contexts-section.ts`), the one place a breakpoint, a
- *   colour scheme or a feature query is defined.
+ *   feature queries and the layout show/hide switch into one popover. Per §6.2 ("The breakpoint and
+ *   scheme axes") this control **only selects**; its footer is "Manage contexts…", which routes to
+ *   the definition site — Project Settings › Contexts (`settings/contexts-section.ts`), the one
+ *   place a breakpoint, a colour scheme or a feature query is defined.
  * - **Resolving with** — the document DATA a render resolves against: a page's route params, a
  *   component's test props. Its own popover beside the context one, headed "resolving with", with
  *   the fields in a vertical stack. A SECOND popover rather than a fourth group in the first,
@@ -34,12 +34,13 @@
  * **The bar is not a grid row.** It renders inside the pane's own cell (`#pane-chrome`, stacked
  * over `#canvas-wrap`), because a per-pane surface cannot be a row of the application grid — the
  * second pane would have no way to have one. The stage is offset by {@link PANE_CONTEXT_VAR} rather
- * than by a track, and the zoom pod floats bottom-right over the canvas exactly as §3.2 ⑩ asks.
+ * than by a track, and the zoom pod floats bottom-right over the canvas, as
+ * `docs/studio/interface/tabs.md` ("The pane context bar") describes it.
  *
  * **The read-only banner rides with the bar.** `collab/collab-state.ts` says whether a guest may
- * write (§7.4); the surface that owes them the sentence is this one, because it is the per-pane,
- * per-document chrome that sits directly above the editing surface. It is stacked under the bar
- * inside the document's `[part="band"]` and the offset is MEASURED from that band
+ * write (`collab.md` §4); the surface that owes them the sentence is this one, because it is the
+ * per-pane, per-document chrome that sits directly above the editing surface. It is stacked under
+ * the bar inside the document's `[part="band"]` and the offset is MEASURED from that band
  * ({@link applyPaneContextOffset}), so a two-line banner pushes the stage down instead of covering
  * the document it is warning you about.
  */
@@ -66,6 +67,9 @@ import {
 import { openMenu } from "../surfaces/menu";
 import { emptyPaneContextView, mountPaneContextSurface } from "../surfaces/pane-context";
 import { PANE_SELECTOR } from "../surfaces/pane-grid";
+import { diffShowsCode } from "../canvas/diff-view";
+import { canRenderComparison } from "./git-diff-open";
+import { shell } from "../shell";
 import { paneRegion } from "../ui/regions";
 import {
   fitToScreen,
@@ -268,9 +272,9 @@ export function mount(host: HTMLElement, ctx: PaneContextCtx) {
         void tab.session.ui.previewProps;
         void tab.session.ui.showLayout;
         void tab.session.ui.zoom;
-        // The read-only banner (§7.4) is part of this chrome, so its two facts are tracked here
-        // Too: a peer downgrading you mid-session must make the sentence appear, not wait for the
-        // Next zoom.
+        // The read-only banner (`collab.md` §4) is part of this chrome, so its two facts are
+        // Tracked here too: a peer downgrading you mid-session must make the sentence appear, not
+        // Wait for the next zoom.
         void collabState(tab).active;
         void collabState(tab).readOnly;
       }
@@ -322,7 +326,7 @@ export function applyPaneContextOffset(height: number, host?: HTMLElement | null
  *
  * The band is the DOCUMENT's, handed back by the mount rather than found by selector — a surface
  * that re-queries its own markup is holding a node that the next render may already have replaced
- * (guidelines §9.4).
+ * (`studio-ui-guidelines.md` §9.4).
  */
 function topBandHeight(surface: PaneContextSurfaceHandle): number {
   return Math.max(surface.band()?.offsetHeight ?? 0, PANE_CONTEXT_HEIGHT);
@@ -416,7 +420,7 @@ export function dismissPresetMenu(): void {
  *
  * **It is the kit menu, not a second one.** `surfaces/menu.ts` already owns roving focus,
  * typeahead, light dismissal, the disabled row's `requires` sentence and the Escape that closes it
- * (guidelines §12.5); this hands it rows.
+ * (`studio-ui-guidelines.md` §12.5); this hands it rows.
  */
 function openPresetMenu(paneId: string, anchor: HTMLElement): void {
   dismissPresetMenu();
@@ -617,13 +621,13 @@ export function presetRows(paneId: string): PresetRow[] {
  * Everything one pane's chrome draws, as words and keyed rows.
  *
  * There is no takeover branch. Opening a function body or a formula reveals the dock's Logic tab
- * (P8) and leaves the canvas standing underneath it, so the axes still describe the document on the
- * stage and the zoom pod still has something to zoom. Suppressing them while the dock was open
+ * (§16.3) and leaves the canvas standing underneath it, so the axes still describe the document on
+ * the stage and the zoom pod still has something to zoom. Suppressing them while the dock was open
  * removed the controls for the very document the reader could still see.
  *
- * **There is no breadcrumb either.** The address is ⑥'s job — `panels/jump-bar.ts`, one row above —
- * and the Logic tab's own header carries the Close. This bar drew a second Back and a second trail
- * beside both of them.
+ * **There is no breadcrumb either.** The address is the jump bar's job — `panels/jump-bar.ts`, one
+ * row above — and the Logic tab's own header carries the Close. This bar drew a second Back and a
+ * second trail beside both of them.
  */
 function viewFor(tab: Tab, paneId: string, ctx: PaneContextCtx): PaneContextView {
   /* A LENS suppresses the two axes that WRITE. Editor kind and Canvas view both land in
@@ -802,9 +806,9 @@ interface PaneLocale {
  * and "groups a document declares nothing for are absent" is the rule the whole popover follows.
  *
  * The fallback chain is what makes the control honest about a file it has not been told about:
- * `previewLocale` is the author's explicit choice, the path is the file's own language (§13.3 puts
- * a translation in its own directory), and the default locale is what an unprefixed page renders
- * as.
+ * `previewLocale` is the author's explicit choice, the path is the file's own language
+ * (`site-architecture.md` §13.3 puts a translation in its own directory), and the default locale is
+ * what an unprefixed page renders as.
  */
 function localeOf(tab: Tab | null): PaneLocale | null {
   const i18n = getEffectiveLocales();
@@ -949,7 +953,7 @@ function localeGroup(locale: PaneLocale | null): Partial<PaneContextView> {
   };
 }
 
-// ─── ⑩ The floating zoom pod ─────────────────────────────────────────────────
+// ─── The floating zoom pod ───────────────────────────────────────────────────
 
 /** The fit entries the pod offers, in menu order. `1` is "actual size", a numeric fit. */
 const FIT_CHOICES: readonly { value: string; fit: FitMode; label: string }[] = [
@@ -970,13 +974,28 @@ function fitChoiceValue(fit: FitMode): string {
 /** The modes whose stage is the panzoom surface — the only ones with a fit to state. */
 const STAGE_ZOOM_MODES = new Set(["design", "stylebook", "git-diff"]);
 
+/**
+ * The path this pane is comparing, or "" before it has a comparison.
+ *
+ * Resolved exactly as `canvas-render.ts`'s git-diff branch resolves the comparison it draws: a Diff
+ * lens carries its own, and every other pane draws the Source Control panel's one app-level slot.
+ * Both halves are reactive, so the pod repaints when either one lands or retargets.
+ */
+function comparisonPathOf(paneId: string): string {
+  const derived = derivationOfPane(paneId);
+  const state =
+    derived?.kind === "lens" && derived.preset === "diff" ? derived.diff : shell.git.diffState;
+  return state?.filePath ?? "";
+}
+
 /**
  * Zoom and fit, floating over the canvas bottom-right.
  *
  * Two surfaces, one control: `edit` drives the content-reflow `editZoom`, while design / Stylebook
  * / git-diff render on the panzoom surface and drive `ui.zoom` — and only the panzoom surface has a
  * fit, because a fit is a statement about an artboard. Preview is deliberately absent: its frame is
- * a real viewport that scrolls its own document, so there is nothing to zoom.
+ * a real viewport that scrolls its own document, so there is nothing to zoom. So is a comparison's
+ * CODE half, for the same reason: see below.
  */
 function podFor(tab: Tab, paneId: string): Partial<PaneContextView> {
   /* THIS pane's mode. `ctx.getCanvasMode()` answers for the focused pane, so the unfocused pod
@@ -993,6 +1012,15 @@ function podFor(tab: Tab, paneId: string): Partial<PaneContextView> {
   if (!STAGE_ZOOM_MODES.has(mode)) {
     return { podState: "hidden" };
   }
+  /* NO POD OVER A COMPARISON'S CODE HALF. That half is one Monaco diff editor filling the stage,
+     with no panzoom surface under it, so `applyTransform` and `resetZoom` return early and + / − /
+     100% / Fit moved nothing but their own label. And it sat on Monaco's own scrollbar and diff
+     overview ruler at the stage's right edge, which no native measurement can see. The predicate is
+     the one the renderer chose the half with, so the two cannot disagree; `diff-view.ts` is not
+     reactive, so the Visual/Code switch repaints this chrome itself (`diff-toolbar.ts`). */
+  if (mode === "git-diff" && diffShowsCode(paneId, canRenderComparison(comparisonPathOf(paneId)))) {
+    return { podState: "hidden" };
+  }
   const zoom = stageZoom(surface);
   return {
     fitOptions: FIT_CHOICES.map(({ label, value }) => ({ label, value })),
@@ -1011,7 +1039,7 @@ function podFor(tab: Tab, paneId: string): Partial<PaneContextView> {
  * These four controls wrote `session.ui` directly through `updateUi`, which is why none of the
  * three axes was a command: the popover WAS the capability, and the palette, the assistant and
  * `__jxAutomation` had no name for it. Going through the registry makes the control and the verb
- * one thing (§2, principle 1) and gets the breakpoint refusal for free.
+ * one thing (one definition site per action, §13) and gets the breakpoint refusal for free.
  */
 function runContextCommand(paneId: string, id: string, args: Record<string, unknown>): void {
   // THIS pane, named. The bar is drawn once per pane and the side bar's controls write the side
@@ -1161,7 +1189,7 @@ export function isResolvingOpen(paneId: string): boolean {
  * Open or close it.
  *
  * A named end state rather than a toggle, so `canvas.setResolvingOpen { open: false }` means the
- * same thing twice and a screenshot can photograph it (§13's R1).
+ * same thing twice and a screenshot can photograph it (R1, `scripts/screenshots/README.md`).
  *
  * It writes the panel and does NOT re-project the bar. A popover moves into the top layer while it
  * is open; nothing about the bar changes when it does, and the only thing the bar redraws for is

package/src/panels/pane-grid.ts

@@ -2,13 +2,14 @@
 /**
  * The pane grid — `workspace.panes`, given a visual counterpart.
  *
- * `workspace.panes` has been a real data model since P3: an ordered list, a focused id, a split, an
- * unsplit. Nothing drew it. `index.html` declared ONE each of `#tab-strip`, `#jump-bar`,
- * `#pane-chrome` and `#canvas-wrap` as flat siblings in `#app`'s grid — four surfaces that belong
- * to a PANE, laid out as rows and columns of the APPLICATION — so the shell could model two panes
- * and had somewhere to put exactly one. §18.3's stage handover was the workaround: one stage, taken
- * by whichever pane had focus, releasing the loser's artboards on the way past. This module is what
- * that scaffolding was standing in for, and the handover is deleted with it.
+ * `workspace.panes` has been a real data model since the shell redesign's chrome phase: an ordered
+ * list, a focused id, a split, an unsplit. Nothing drew it. `index.html` declared ONE each of
+ * `#tab-strip`, `#jump-bar`, `#pane-chrome` and `#canvas-wrap` as flat siblings in `#app`'s grid —
+ * four surfaces that belong to a PANE, laid out as rows and columns of the APPLICATION — so the
+ * shell could model two panes and had somewhere to put exactly one. §18.3's stage handover was the
+ * workaround: one stage, taken by whichever pane had focus, releasing the loser's artboards on the
+ * way past. This module is what that scaffolding was standing in for, and the handover is deleted
+ * with it.
  *
  * **The document owns the frame; this module owns the decisions.** `surfaces/pane-grid.json` is the
  * cells, the five boxes inside each one, the splitter between two of them and every rule that lays
@@ -50,7 +51,7 @@
  * `scale`, `min` and `max` closures that read `clientWidth` on every `pointermove` are gone, along
  * with the window-resize staleness they were paying for.
  *
- * The fourth rule of §18.1 — _a pane with nothing in it is a hole in the grid_ — is enforced in
+ * The third rule of §18.1 — _a pane with nothing in it is a hole in the grid_ — is enforced in
  * `workspace/workspace.ts`, where the tabs are. This module never repairs: repairing inside a
  * reactive effect that writes `workspace.panes` is an effect that triggers itself.
  */

package/src/panels/panel-registry.ts

@@ -5,17 +5,18 @@
  * A {@link PanelRecord} is to a surface what a `Command` is to an action: its name, the containment
  * level of the state it WRITES, the dock that hosts it, the predicate that decides whether it
  * exists at all, and the function that draws it. The rail, the panel header and the dock budget
- * become RENDERINGS of these records — plan §2 principle 1, applied to regions rather than verbs.
+ * become RENDERINGS of these records — one definition site per action (§13), applied to regions
+ * rather than verbs.
  *
  * It mirrors the shipped `settings/settings-modal.ts` contribution point
  * (`registerSettingsSection`) deliberately: a module-level `Map`, keyed by id, written by the
  * module that OWNS the surface. The one thing it adds is the field that makes the rail derivable —
  *
  * **`level` is required, and it is the level of the state the panel WRITES, not the state it
- * reads** (plan §2 principle 3). Insert reads the project's component registry and writes the
- * document tree, so it is `document`. Files reads documents and writes project files, so it is
- * `project`. That rule, and not intuition, is what settles every contested placement and what stops
- * the rail re-accreting: the two rail groups are two rows of
+ * reads** (§13.2). Insert reads the project's component registry and writes the document tree, so
+ * it is `document`. Files reads documents and writes project files, so it is `project`. That rule,
+ * and not intuition, is what settles every contested placement and what stops the rail
+ * re-accreting: the two rail groups are two rows of
  * {@link
  * import("../commands/levels").PANEL_PLACEMENT_MATRIX}, checked at registration exactly the
  * way a command's `menus` are.
@@ -99,15 +100,16 @@ export interface NavigatorPanelDeps {
 /**
  * The focused document, as a document-level panel reads it. `null` when no tab is open.
  *
- * A `level: "project"` panel must not read this — that is principle 3's corollary, and the reason
- * the Source Control badge used to vanish when the last tab closed. {@link registerPanel} cannot
- * enforce it (a closure's imports are not inspectable), so the contract is stated here and asserted
- * by `tests/panel-registry.test.ts`, which renders every project-level panel with `doc: null`.
+ * A `level: "project"` panel must not read this — that is `studio-ui-guidelines.md` §12.1's closing
+ * rule, and the reason the Source Control badge used to vanish when the last tab closed.
+ * {@link registerPanel} cannot enforce it (a closure's imports are not inspectable), so the contract
+ * is stated here and asserted by `tests/panel-registry.test.ts`, which renders every project-level
+ * panel with `doc: null`.
  */
 export interface NavigatorDocument {
   document: JxMutableNode;
   mode: string;
-  /** The whole selection SET the navigator/inspector panels render against (§6.5). */
+  /** The whole selection SET the navigator/inspector panels render against (§6.7). */
   selection: JxPath[];
   canvas: Record<string, unknown> | null;
   content?: { frontmatter?: Record<string, unknown> } | undefined;
@@ -131,8 +133,23 @@ export type PanelBody = TemplateResult | typeof nothing;
 export interface PanelRecord {
   /** Lowercase, stable, and the value `view.setActivity` accepts — renaming one is a shot break. */
   id: string;
-  /** The human name. The rail label AND the panel header, so there is one place it is spelled. */
+  /**
+   * The human name, spelled once: the panel header, the rail button's accessible name and tooltip,
+   * the `Show …` command and the chrome-budget row. The rail prints it under the glyph too, unless
+   * {@link PanelRecord.railLabel} says otherwise.
+   */
   title: string;
+  /**
+   * The rail button's visible text, for a title too long to sit under the glyph.
+   *
+   * The stacked label box is 48px at `--jx-text-xs` (10px), and "Source Control" is 71px, so the
+   * kit's ellipsis drew it as "Source …". Absent: the rail prints `title`. It must be a LEADING
+   * part of `title`, because the button's accessible name stays the title and the words on screen
+   * must be inside it (WCAG 2.5.3 Label in Name; best practice is that they lead it).
+   * {@link registerPanel} throws otherwise. Not derived from the title's first word, which would
+   * turn "Project Styles" into "Project": a record that needs a short name says which one.
+   */
+  railLabel?: string;
   /** REQUIRED. The level of the state this panel WRITES. Checked against the panel matrix. */
   level: Level;
   dock: PanelDock;
@@ -146,9 +163,9 @@ export interface PanelRecord {
    *
    * Not a hiding mechanism — a rail-less panel is still reachable by `view.setActivity`, by the
    * palette and by another surface linking to it. It is how a record survives the interval between
-   * losing its rail slot and gaining its real home (Insert becomes an overlay in P3.5; State folds
-   * into Data). Declaring it `false` also removes the panel's `rail/<level>` placement, which is
-   * what keeps the rail inside its four-per-group budget.
+   * losing its rail slot and gaining its real home (Insert, reachable from the canvas and palette;
+   * State, folded into Data — §5.1). Declaring it `false` also removes the panel's `rail/<level>`
+   * placement, which is what keeps the rail inside its four-per-group budget.
    */
   rail?: boolean;
   /**
@@ -209,7 +226,8 @@ const PANEL_ID_PATTERN = /^[a-z][\w-]*$/;
 const panelRegistry = new Map<string, PanelRecord>();
 
 /**
- * Define a panel. Throws on a duplicate id, a malformed id, or a matrix violation.
+ * Define a panel. Throws on a duplicate id, a malformed id, a matrix violation, or a `railLabel`
+ * that is not a leading part of the title.
  *
  * Failing at registration is the same bet `createCommandRegistry.register` makes: a misplaced
  * surface is a design error, and a design error that only shows up as a wrong-looking rail is a
@@ -240,6 +258,16 @@ export function registerPanel(panel: PanelRecord): void {
     const detail = violations.map((violation) => `  ✗ ${panel.id} ${violation.message}`).join("\n");
     throw new Error(`Panel "${panel.id}" violates the level × placement matrix:\n${detail}`);
   }
+  if (
+    panel.railLabel !== undefined &&
+    (panel.railLabel.trim() === "" || !panel.title.startsWith(panel.railLabel))
+  ) {
+    throw new Error(
+      `Panel "${panel.id}" declares railLabel "${panel.railLabel}", which is not a leading part ` +
+        `of its title "${panel.title}": the rail button's accessible name is the title, and the ` +
+        `words on screen must be inside it (WCAG 2.5.3, Label in Name).`,
+    );
+  }
   panelRegistry.set(panel.id, panel);
 }
 
@@ -287,10 +315,10 @@ const RAIL_GROUP_LEVELS: readonly { level: Level; label: string }[] = [
  * Every panel that has a rail button, whatever dock draws its body.
  *
  * The rail is NOT the Navigator's tab strip. `panelPlacements()` has always awarded `rail/<level>`
- * on `rail !== false` alone — the dock is a separate placement — and Problems is the panel that
- * proves it: its body is the Bottom dock's first tab (plan §7.2), and it still owns a rail slot and
- * a badge, because "how many things need fixing" is a question you ask without opening anything.
- * Filtering this by `dock === "navigator"` is what would put the same list in two hosts at once.
+ * on `rail !== false` alone — the dock is a separate placement. Problems proved it for a release:
+ * its body is the Bottom dock's first tab, and it owned a rail slot and a badge until §16.3 took
+ * every Bottom-dock tab off the rail and put its count in the status bar. Filtering this by `dock
+ * === "navigator"` is what would put the same list in two hosts at once.
  */
 function railablePanels(): readonly PanelRecord[] {
   return listPanels().filter((panel) => panel.rail !== false);

package/src/panels/problems-panel.ts

@@ -1,8 +1,8 @@
 /// <reference lib="dom" />
 /**
- * Problems — everything that must be fixed, listed until it is (plan §7.1, §7.2).
+ * Problems — everything that must be fixed, listed until it is (§16.1, §16.3).
  *
- * `services/notify.ts` landed the RECORD in P4 wave A: a failure is a `Notification` with `tier:
+ * `services/notify.ts` landed the RECORD first: a failure is a `Notification` with `tier:
  * "problem"`, which means the app promises to keep it until somebody fixes it. This is the surface
  * that keeps the promise. Until it existed, `problems` was a reactive array with a count (the rail
  * badge, the status bar) and no way to read what was in it.
@@ -41,11 +41,10 @@
  * it mounts, so it answers with the call the dock already made: `render` runs for the active tab
  * only, and `afterRender` consumes what it left.
  *
- * **One record, one host.** Problems lives in the BOTTOM DOCK — plan §7.2's table says so outright
- * ("Problems | Bottom dock ⑪, badge on the rail") and §3.2 ⑪ makes it the dock's first tab. §3.2 ③
- * also lists it among the Navigator's panels; that line loses, because a list open in two docks at
- * once is two hosts for one record, and hosting it in the Navigator spends left-dock width on
- * something that belongs under the pane grid.
+ * **One record, one host.** Problems lives in the BOTTOM DOCK, as its first tab (§16.3). The shell
+ * redesign also listed it among the Navigator's panels; that line lost, because a list open in two
+ * docks at once is two hosts for one record, and hosting it in the Navigator spends left-dock width
+ * on something that belongs under the pane grid.
  *
  * **And no rail button.** It had one, in the PROJECT group, which meant a control on the far left
  * that opened a dock along the bottom — the rail carried a per-dock branch in three places to keep
@@ -272,12 +271,12 @@ export function syncProblemsSurface(host: HTMLElement): void {
 }
 
 /**
- * Define the Problems panel — the P3 placeholder, built.
+ * Define the Problems panel — the chrome phase's placeholder, built.
  *
- * P3 registered this id with `when: () => false` and a `render` that threw: "declared in the design
- * and not yet in the app", holding the rail slot §3.2 ② had already spent so the budget counted it
- * from the day it was named. This is the edit that phase described — the predicate is gone, the
- * body is real, and the badge is live.
+ * The shell redesign's chrome phase registered this id with `when: () => false` and a `render` that
+ * threw: "declared in the design and not yet in the app", holding a Navigator rail slot so the
+ * budget counted it from the day it was named. This is the edit that phase described — the
+ * predicate is gone, the body is real, and the badge is live.
  *
  * One caller: `panels/bottom-dock.ts`'s {@link import("./bottom-dock").registerBottomPanels}, which
  * is the module that owns the dock this record is drawn in. `registerPanel` throws on a duplicate