@jxsuite/studio 5.2.0 → 5.4.0

package/src/ui/panel-resize.ts

@@ -43,8 +43,7 @@ import {
 } from "../shell";
 import type { DockId } from "../shell";
 import { effect } from "../reactivity";
-import { rectOf } from "../utils/geometry";
-import { splitModifiersOf } from "@jxsuite/ui/behaviors/split";
+import { splitModifiersOf, trackOf } from "@jxsuite/ui/behaviors/split";
 import type { SplitModifiers } from "@jxsuite/ui/behaviors/split";
 
 /**
@@ -59,11 +58,11 @@ import type { SplitModifiers } from "@jxsuite/ui/behaviors/split";
  *
  * **There is no pointer path left in this module**, and it is worth recording why rather than
  * quietly dropping it: a handle driven by pointer events alone is unreachable from a keyboard,
- * which is an SC 2.1.1 failure however it is drawn. The pane split moved to `jx-split` first (ui.md
- * §5.5), the three docks followed, and the Edit column was last because its handle SNAPS — and the
- * element had no way to tell a host which modifiers a step carried. It has now: every `input`
- * carries them, so a snap lives in {@link bindSplit} rather than in a pointer handler of this
- * module's own.
+ * which is an SC 2.1.1 failure however it is drawn. The pane split moved to `jx-split` first
+ * (`ui.md` §5.5), the three docks followed, and the Edit column was last because its handle SNAPS —
+ * and the element had no way to tell a host which modifiers a step carried. It has now: every
+ * `input` carries them, so a snap lives in {@link bindSplit} rather than in a pointer handler of
+ * this module's own.
  */
 export interface ResizeTarget {
   /** Which coordinate the drag reads. */
@@ -160,25 +159,6 @@ export interface SplitElement extends HTMLElement {
   collapse: number;
 }
 
-/**
- * The length of the box a handle divides, along its axis — the same box `jx-split` measures at
- * pointerdown, read here so the share this adapter writes and the one the element drags against are
- * two readings of one number.
- */
-function trackOf(handle: HTMLElement, axis: "x" | "y"): number {
-  for (let node = handle.parentElement; node; node = node.parentElement) {
-    if (globalThis.getComputedStyle(node).display === "contents") {
-      continue;
-    }
-    const box = rectOf(node);
-    const length = axis === "x" ? box.width : box.height;
-    if (length > 0) {
-      return length;
-    }
-  }
-  return 0;
-}
-
 /**
  * A target's pixel size as the leading side's share of the track, and back.
  *
@@ -231,7 +211,7 @@ function sizeOf(target: ResizeTarget, share: number, track: number): number {
  */
 export function bindSplit(handle: SplitElement, target: ResizeTarget): () => void {
   const sync = (): void => {
-    const track = trackOf(handle, target.axis);
+    const track = trackOf(handle, target.axis === "x");
     if (track <= 0) {
       return;
     }
@@ -243,7 +223,7 @@ export function bindSplit(handle: SplitElement, target: ResizeTarget): () => voi
     handle.value = shareOf(target, target.read(), track);
   };
   const onInput = (event: Event): void => {
-    const track = trackOf(handle, target.axis);
+    const track = trackOf(handle, target.axis === "x");
     if (track <= 0) {
       return;
     }

package/src/ui/popover-surface.ts

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

package/src/ui/progress-modal.ts

@@ -1,11 +1,11 @@
 /// <reference lib="dom" />
 /**
- * The one surface in Studio that still BLOCKS while it works — and now the only one (plan §7.3).
+ * The one surface in Studio that still BLOCKS while it works — and now the only one (§16.4).
  *
  * What changed. This modal used to be four things at once: the running state, the error view, the
  * log and the operation's entire memory. It blocked the whole app, offered no way out, and took all
  * four with it when it closed — so a failed `bun install` could be read exactly once, and a hung
- * one could not be escaped at all. §7.3 splits those apart:
+ * one could not be escaped at all. §16.4 splits those apart:
  *
  * - The **record** moves to `panels/activity-panel.ts`, which keeps the entry, its steps and its log
  *   after the modal is gone;
@@ -15,7 +15,7 @@
  * - And the **exit** arrives twice: `Run in the background` hands the app back while the operation
  *   keeps going in Activity, and an operation that passed a `cancel` gets a real Cancel button.
  *
- * What did NOT change is which operations block. §7.3 keeps blocking for dependency install and
+ * What did NOT change is which operations block. §16.4 keeps blocking for dependency install and
  * nothing else, and this module's four call sites are exactly that — `packages/ensure-deps.ts`,
  * `packages/pull-package-sync.ts`, `packages/jxsuite-update.ts` and
  * `settings/dependencies-editor.ts`. Every other long operation calls `beginActivity` directly and

package/src/ui/regions.ts

@@ -9,7 +9,8 @@
  * restoration after a toast or a Problems jump, and the screenshot pipeline, which today addresses
  * the shell through sixteen CSS selectors, seven of which name nodes the shell redesign deletes.
  *
- * **The grammar** (UX-REDESIGN-PLAN §13.2) is `<surface>[.<instance>][/<part>]`:
+ * **The grammar** (scripts/screenshots/README.md, "The region grammar") is
+ * `<surface>[.<instance>][/<part>]`:
  *
  * ```text
  * navigator                     the Navigator dock
@@ -38,7 +39,10 @@ import type { FocusRegion } from "../shell";
 /** The attribute every region carries. One attribute, one grammar, one resolver. */
 export const REGION_ATTR = "data-jx-region";
 
-/** The eight surfaces §13.2 declares. A region id always begins with one of these. */
+/**
+ * The eight surfaces the region grammar declares (`scripts/screenshots/README.md`). A region id
+ * always begins with one of these.
+ */
 export const REGION_SURFACES = [
   "rail",
   "navigator",
@@ -377,12 +381,12 @@ export function inspectorStatementsRegion(eventKey: string): string {
  * Region id for a Bottom dock tab, derived from the panel's own id.
  *
  * The third member of the derived-region family, and the one that shows the grammar was worth
- * specifying before the surface existed: `dock.bottom` has parsed since P3 (it is the only surface
- * whose NAME contains the instance separator, which is why {@link DOTTED_SURFACES} exists) and
- * resolved to nothing, because nothing hosted it. `panels/bottom-dock.ts` stamps this once, from
- * the same id `view.setBottomTab` accepts, so the dock's four tabs are addressable without anyone
- * authoring an id — and the host itself carries the bare `dock.bottom` only while it is open, so a
- * closed dock resolves to nothing rather than to an invisible box.
+ * specifying before the surface existed: `dock.bottom` parsed before the dock was built (it is the
+ * only surface whose NAME contains the instance separator, which is why {@link DOTTED_SURFACES}
+ * exists) and resolved to nothing, because nothing hosted it. `panels/bottom-dock.ts` stamps this
+ * once, from the same id `view.setBottomTab` accepts, so every tab the dock hosts is addressable
+ * without anyone authoring an id — and the host itself carries the bare `dock.bottom` only while it
+ * is open, so a closed dock resolves to nothing rather than to an invisible box.
  */
 export function bottomPanelRegion(panelId: string): string {
   return `dock.bottom/panel:${panelId}`;
@@ -419,7 +423,8 @@ export function overlayRegion(
 }
 
 /**
- * `regions` — the namespace §13.3 names, gathered so a consumer imports one thing.
+ * `regions` — the resolver behind the region grammar (`scripts/screenshots/README.md`), gathered so
+ * a consumer imports one thing.
  *
  * `probe.regions` is a projection of this; nothing here knows the camera exists.
  */

package/src/ui/schema-form.ts

@@ -162,7 +162,7 @@ export interface RenderFormOptions {
   ui?: Record<string, { control?: string; enum?: unknown }> | undefined;
   rerender?: (() => void) | undefined;
   /**
-   * Externally-produced diagnostics, keyed by property name — §7.1's inline tier, sourced.
+   * Externally-produced diagnostics, keyed by property name — §16.1's inline tier, sourced.
    *
    * This is how a validator that runs over the WHOLE document reaches the one field it is about:
    * `jx-validate`'s `project.json` errors, Monaco's markers for the same file open in the code
@@ -177,7 +177,7 @@ export interface RenderFormOptions {
   /** How many times each field has been refused in a row; drives the row's repeat counter. */
   errorCounts?: Record<string, number> | undefined;
   /**
-   * Report required-but-empty fields inline. Off by default, and that default is §7.1's rule
+   * Report required-but-empty fields inline. Off by default, and that default is §16.5's rule
    * literally applied: a form the user has not touched yet has not committed anything, so painting
    * every required field red the moment it renders is telling them they got something wrong before
    * they did anything. Required-ness is already shown — the row carries the required mark. A host
@@ -313,7 +313,7 @@ function asText(value: unknown): string {
   return typeof value === "object" ? JSON.stringify(value, null, 2) : String(value);
 }
 
-// ─── Field validation (§7.1, inline tier) ────────────────────────────────────
+// ─── Field validation (§16.1, inline tier) ───────────────────────────────────
 
 /**
  * Why this value is not acceptable for this property schema, or `""` when it is.
@@ -670,7 +670,7 @@ function createController(): FormController {
     return raw;
   }
 
-  /** 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 plan = plans.get(key);
     if (!plan?.ladder) {
@@ -985,11 +985,12 @@ function deriveField(prop: string, ps: JsonSchema, args: DeriveArgs): SchemaForm
   }
 
   /* A relationship to another collection (`$ref: "#/content/<type>"`) is the registered `reference`
-     control, wherever the form is drawn — §9.2's "one picker" is this dispatch plus the single
-     `registerFormControl("reference", …)` in `ui/form-controls.ts`. It is deliberately NOT an enum:
-     the choices are entry files on disk, so they are read asynchronously and can be stale, and a
-     schema `enum` is a closed set the document itself declares. When the control is not registered
-     (a bare-Bun import of this engine), the field falls through to the plain text control below. */
+     control, wherever the form is drawn — site-architecture.md §7.4's one entry picker is this
+     dispatch plus the single `registerFormControl("reference", …)` in `ui/form-controls.ts`. It is
+     deliberately NOT an enum: the choices are entry files on disk, so they are read asynchronously
+     and can be stale, and a schema `enum` is a closed set the document itself declares. When the
+     control is not registered (a bare-Bun import of this engine), the field falls through to the
+     plain text control below. */
   if (referenceTarget(ps) !== null) {
     const reference = controlRegistry.get("reference");
     if (reference) {

package/src/ui/timing.ts

@@ -13,16 +13,17 @@
  */
 
 /**
- * Text/style input debounce — the §4.4 standard. Long enough that a normal typing cadence produces
- * one commit per pause rather than one per keystroke, short enough that the canvas still feels
- * live.
+ * Text/style input debounce — the studio-ui-guidelines.md §4.4 standard. Long enough that a normal
+ * typing cadence produces one commit per pause rather than one per keystroke, short enough that the
+ * canvas still feels live.
  */
 export const INPUT_DEBOUNCE = 400;
 
 /**
- * Code and expression textareas — the §4.4 standard. Longer than {@link INPUT_DEBOUNCE} because
- * each commit re-parses source (or re-lints), and because half-typed code is usually invalid, so
- * committing eagerly just burns work on states the user is about to leave.
+ * Code and expression textareas — the studio-ui-guidelines.md §4.4 standard. Longer than
+ * {@link INPUT_DEBOUNCE} because each commit re-parses source (or re-lints), and because half-typed
+ * code is usually invalid, so committing eagerly just burns work on states the user is about to
+ * leave.
  */
 export const CODE_DEBOUNCE = 500;
 
@@ -38,7 +39,8 @@ export const LIVE_PREVIEW = 350;
  * `STATUS_MESSAGE = 3000` used to live here: how long a transient message stayed in the status bar
  * before it erased itself. It had one reader, `statusMessage`, which is deleted — the bar carries
  * ambient state now and outcomes go to `services/notify.ts`, whose `TOAST_LIFETIME_MS` is per
- * SEVERITY (§7.1 caps the band at 4–8s) rather than one number for a failure and a save alike.
+ * SEVERITY (4s, or 8s for a warning or an error: studio-ui-guidelines.md §13.2) rather than one
+ * number for a failure and a save alike.
  */
 
 /**

package/src/ui/value-source.ts

@@ -1,11 +1,11 @@
 /**
  * Value Source — the one vocabulary for "how is this value produced", and the derivation that says
- * which productions a given document position actually permits (plan §6.3).
+ * which productions a given document position actually permits (§6.6).
  *
  * Six controls used to answer that question in six dialects: `abc / $ref / ${} / fx` on the dynamic
  * slot, `inline / $expression / ref` on the Events tab, `lit / $ref / expr` on every expression
  * operand, and `Static value / route param / Custom…` in the schema-driven forms. They are the same
- * four rungs of the Rule of Least Power ladder (spec §2.2) wearing four costumes, and a user who
+ * four rungs of the Rule of Least Power ladder (spec.md §2.2) wearing four costumes, and a user who
  * learned one learned none of the others. {@link VALUE_SOURCE_LABELS} is the single vocabulary;
  * every surface that offers the choice spells it the same way.
  *
@@ -48,11 +48,11 @@ import { isFunctionDef, isRef, isTemplateString } from "@jxsuite/schema/guards";
 /** A rung of the value ladder — one way a document position can produce its value. */
 export type SlotMode = "literal" | "ref" | "template" | "expression" | "function";
 
-/** Ladder order, least powerful first (spec §2.2). Every rung list is sorted by this. */
+/** Ladder order, least powerful first (spec.md §2.2). Every rung list is sorted by this. */
 export const SLOT_MODE_ORDER: SlotMode[] = ["literal", "ref", "template", "expression", "function"];
 
 /**
- * The user-facing name of each rung — the whole point of §6.3. `ref` keeps its ellipsis because
+ * The user-facing name of each rung — the whole point of §6.6. `ref` keeps its ellipsis because
  * choosing it opens a picker rather than committing a value.
  */
 export const VALUE_SOURCE_LABELS: Record<SlotMode, string> = {

package/src/ui/virtual-window.ts

@@ -9,7 +9,7 @@
  * project. The two trees pay a smaller version of the same bill — a 5 000-node page drew 5 000
  * rows, each an `sp-icon` custom element — and they now pay it through this file.
  *
- * **It lives in `ui/`, not in `browse/`.** P3 workstream 11 promised "one virtual-list primitive
+ * **It lives in `ui/`, not in `browse/`.** The shell redesign promised "one virtual-list primitive
  * behind the Files tree and the Outline tree, reused by the Library grid", and what shipped sat
  * inside the Library and was imported by the Library alone. A primitive two surfaces share cannot
  * live inside one of them: the next surface that needs it either reaches across a feature boundary
@@ -300,6 +300,44 @@ export function nearestScroller(el: HTMLElement | null): HTMLElement | null {
   return null;
 }
 
+/**
+ * The scroller that resolved for `list` last time, memoized while the tree still holds it.
+ *
+ * Every render pass asks {@link nearestScroller} the same question about the same list, and each
+ * ask is a walk whose reads (scrollHeight, clientHeight, computed overflow) land on a tree that is
+ * mid-paint — they force the flush the DevTools timeline charges to whatever function happened to
+ * read first. Profiling the program boot put 400 ms of style recalculation behind a handful of
+ * these walks (`trackOf` and this one together), and the answer did not change between any two
+ * repaints.
+ *
+ * Only a POSITIVE resolution is cached, and negative answers are never: a list that has not grown
+ * its rows yet has nothing to scroll (the first paint of every session), and a null answer memoized
+ * at that instant would never be revisited. Once a scroller is found it is kept while
+ * `cached.contains(list)` and both are connected — containment and connectivity are plain node
+ * walks that never read layout, so the cache invalidates itself on reparenting or teardown without
+ * paying for it.
+ *
+ * **The one semantic residue is deliberate**: the original walk additionally required the scroller
+ * to HAVE something to scroll right then (the "declares overflow but never scrolls" guard above). A
+ * memoized scroller that has since stopped scrolling stays answered — which is harmless for the
+ * window: `computeWindow` then yields the whole list (a list that fits has no window to cut), and
+ * the watch's own ResizeObserver drives a measure when the box moves so the empty answer of the
+ * next moment arrives without a walk.
+ */
+export function scrollerFor(list: HTMLElement): HTMLElement | null {
+  const cached = scrollerCache.get(list);
+  if (cached && cached.isConnected && list.isConnected && cached.contains(list)) {
+    return cached;
+  }
+  const found = nearestScroller(list);
+  if (found) {
+    scrollerCache.set(list, found);
+  } else {
+    scrollerCache.delete(list);
+  }
+  return found;
+}
+
 /**
  * How far `list`'s first row has scrolled above the top of `scroller`'s viewport.
  *
@@ -327,7 +365,7 @@ export function listWindow(
   list: HTMLElement | null,
   spec: { count: number; rowHeight: number; columns?: number; overscanRows?: number },
 ): WindowRange {
-  const scroller = list?.isConnected === true ? nearestScroller(list) : null;
+  const scroller = list?.isConnected === true ? scrollerFor(list) : null;
   if (!scroller || !list) {
     const count = Math.max(0, Math.trunc(spec.count));
     return { end: count, padBottom: 0, padTop: 0, start: 0, totalRows: count };
@@ -377,7 +415,7 @@ export function scrollTopToReveal(spec: {
  * would paint twice for one keystroke.
  */
 export function revealListRow(list: HTMLElement | null, index: number, rowHeight: number): boolean {
-  const scroller = list?.isConnected === true ? nearestScroller(list) : null;
+  const scroller = list?.isConnected === true ? scrollerFor(list) : null;
   if (!scroller || !list || index < 0 || !(rowHeight > 0)) {
     return false;
   }
@@ -437,9 +475,24 @@ export interface ListWindowWatch {
   window: VirtualWindow;
 }
 
+const scrollerCache = new WeakMap<HTMLElement, HTMLElement>();
+
 /**
  * Bind — or keep — the scroll watch that repaints a windowed list.
  *
+ * Runs synchronously, on purpose. Deferring the resolve-and-bind to the next animation frame was
+ * tried and measured (`scripts/perf/REPORT.md`, "deferring the first measure a frame"): it moved
+ * the boot trace's forced-flush cost rather than removing it, since the layout work still runs on
+ * the frame's own pass either way, and it cost eight test-semantics changes in this file's test
+ * suite for the same totals — so it was reverted. What actually removed the repeated flush is
+ * `scrollerFor`'s identity memoization (alongside `trackOf`'s, in `split.ts`): once a scroller is
+ * resolved for a list, later calls skip the ancestor walk entirely instead of re-reading
+ * `scrollHeight`/`clientHeight` on a dirty tree every render.
+ *
+ * A steady state where the SAME list and scroller are bound hands back `previous` unchanged — no
+ * work happens when nothing changed. Only a rebind (new list, changed scroller, first bind) creates
+ * a new watch.
+ *
  * Called from the surface's `afterRender`, where the rows exist and the scroller can be resolved,
  * and handed back its own previous handle so re-binding is the exception rather than the rule: the
  * tree element survives every re-render (lit reuses it), so the steady state is "same list, same
@@ -450,14 +503,14 @@ export interface ListWindowWatch {
  * the element whose box moves when the ROWS change height, so it is what the window observes to
  * learn that `rowHeight()` now answers differently ({@link createVirtualWindow}).
  *
- * Returns the handle to keep, or null when nothing scrolls this list.
+ * @returns The handle to keep, or null when nothing scrolls this list.
  */
 export function watchListWindow(
   previous: ListWindowWatch | null,
   list: HTMLElement,
   spec: { count: () => number; rowHeight: () => number; onChange: () => void },
 ): ListWindowWatch | null {
-  const scroller = nearestScroller(list);
+  const scroller = scrollerFor(list);
   if (previous && previous.list === list && previous.scroller === scroller) {
     return previous;
   }

package/src/utils/base64.ts

@@ -1,11 +1,14 @@
 /// <reference lib="dom" />
 /**
- * Base64 encoding for binary upload payloads.
+ * Base64 encoding for binary payloads that cross an RPC boundary.
  *
  * `StudioPlatform.uploadFile` accepts `string | File | Blob | ArrayBuffer`, but the RPC platforms
  * (electrobun, chromium) JSON-serialize their params — a `File`/`Blob` becomes `{}` on the wire.
  * Those platforms encode here before the call; the HTTP platforms (dev server, cloud) post the
  * binary body directly and must NOT use this.
+ *
+ * {@link base64ToBytes} is the same boundary in the other direction, for `readFileBytes`: the RPC
+ * backends answer a base64 string for the same reason they accept one, and the caller wants bytes.
  */
 
 /** Bytes per `String.fromCodePoint` call — spreading a whole large file blows the call stack. */
@@ -31,3 +34,19 @@ export async function toBase64(data: string | File | Blob | ArrayBuffer): Promis
   const buffer = data instanceof ArrayBuffer ? data : await data.arrayBuffer();
   return bytesToBase64(new Uint8Array(buffer));
 }
+
+/**
+ * Decode a base64 string to raw bytes — the inverse of {@link bytesToBase64}.
+ *
+ * The RPC platforms' `readFileBytes` answers base64 because their params and results are JSON, so
+ * this is where a JPEG becomes a JPEG again. `atob` yields one character per byte, and reading the
+ * code point back out is what keeps a byte above 0x7F from being re-encoded as UTF-8 — the exact
+ * corruption that makes `readFile` useless for an image.
+ *
+ * `Uint8Array.from` with a mapper rather than an index loop, because `atob`'s output is latin1: one
+ * code unit per byte, none of them a surrogate, so iterating characters and iterating bytes are the
+ * same walk and the index never has to be reasoned about.
+ */
+export function base64ToBytes(base64: string): Uint8Array {
+  return Uint8Array.from(atob(base64), (char) => char.codePointAt(0) ?? 0);
+}

package/src/utils/canvas-media.ts

@@ -5,7 +5,7 @@
 import { pureSchemeOf } from "@jxsuite/runtime";
 
 /**
- * True when a feature query participates in the forced-scheme contract (spec §9.5) — a pure
+ * True when a feature query participates in the forced-scheme contract (spec.md §9.5) — a pure
  * prefers-color-scheme query. These surface as the Auto/Light/Dark control, not generic toggles.
  *
  * @param {string} query

package/src/utils/studio-utils.ts

@@ -76,37 +76,6 @@ export function attrLabel(
   return camelToLabel(attr);
 }
 
-/**
- * Abbreviate a CSS value for button-group display
- *
- * @param {string} val
- * @returns {string}
- */
-export function abbreviateValue(val: string) {
-  const map: Record<string, string> = {
-    baseline: "base",
-    column: "col",
-    "column-reverse": "col-r",
-    contents: "cnt",
-    "flex-end": "end",
-    "flex-start": "start",
-    "flow-root": "flow",
-    inline: "inl",
-    "inline-block": "i-blk",
-    "inline-flex": "i-flx",
-    "inline-grid": "i-grd",
-    normal: "norm",
-    nowrap: "no-wr",
-    "row-reverse": "row-r",
-    "space-around": "arnd",
-    "space-between": "betw",
-    "space-evenly": "even",
-    stretch: "str",
-    "wrap-reverse": "wr-rev",
-  };
-  return map[val] || val;
-}
-
 /**
  * True when a schema `format` names a MEDIA reference.
  *

package/src/view.ts

@@ -23,9 +23,10 @@ import type { Tab } from "./tabs/tab";
  * different modules, torn down by different events and written into by different continuations —
  * and each of those differences used to justify its own spelling of the same two ideas ("ignore the
  * change my own `setValue` is about to fire" and "cancel the work armed over this buffer"). The
- * function editor got a canceller in P8 and the source view did not, which is exactly how a 600ms
- * timer survived three disposal sites and stayed able to replace a page with an empty parse.
- * `services/monaco-buffer.ts` owns the rule; this is the storage it needs.
+ * function editor got a canceller in the shell redesign's panes phase and the source view did not,
+ * which is exactly how a 600ms timer survived three disposal sites and stayed able to replace a
+ * page with an empty parse. `services/monaco-buffer.ts` owns the rule; this is the storage it
+ * needs.
  */
 /**
  * A comparison's Monaco diff editor.

package/src/workspace/pane-derive.ts

@@ -171,10 +171,10 @@ export const PRESET_LABELS: Readonly<Record<DerivePreset, string>> = {
   diff: "Diff vs HEAD",
   layout: "Layout",
   /* An UNFINISHED sentence, like `breakpoint`'s, because the row and the chip both finish it with
-     the locale's own autonym — "Same page in français". Jx has no message catalogue (§13.3): a
-     translation is a different file in a different directory, so this preset opens that file
-     rather than re-rendering this one, and the label says "the same page" about the document
-     rather than about the text on screen. */
+     the locale's own autonym — "Same page in français". Jx has no message catalogue
+     (site-architecture.md §13.3): a translation is a different file in a different directory, so
+     this preset opens that file rather than re-rendering this one, and the label says "the same
+     page" about the document rather than about the text on screen. */
   locale: "Same page in",
 };
 
@@ -1029,9 +1029,9 @@ export function presetRefusal(
     if (i18n === null || i18n.locales.length < 2) {
       return "a project that declares more than one locale — see Project Settings › Locales";
     }
-    /* A PATH, because a translation is a FILE (§13.3) rather than a rendering: an unsaved document
-       has nowhere for its sibling to be, and `translationPathFor` would answer null for it one
-       frame later with a sentence about locales instead of about saving. */
+    /* A PATH, because a translation is a FILE (site-architecture.md §13.3) rather than a rendering:
+       an unsaved document has nowhere for its sibling to be, and `translationPathFor` would answer
+       null for it one frame later with a sentence about locales instead of about saving. */
     if (source.documentPath === null) {
       return "a document that has been saved";
     }
@@ -1082,10 +1082,11 @@ function derivationFor(
   media: string | null,
   locale: string | null = null,
 ): PaneDerivation {
-  /* A COMPANION, because the French copy of this page is a different FILE — §13.3 has no message
-     catalogue, so there is no rendering of this document that is the French one. A lens here would
-     be a second copy of the same page under a chip naming another language, which is the defect
-     this module's own header warns about: a projection that changes only the chip. */
+  /* A COMPANION, because the French copy of this page is a different FILE — Jx has no message
+     catalogue (site-architecture.md §13.3), so there is no rendering of this document that is the
+     French one. A lens here would be a second copy of the same page under a chip naming another
+     language, which is the defect this module's own header warns about: a projection that changes
+     only the chip. */
   if (preset === "locale") {
     return {
       kind: "companion",
@@ -1213,8 +1214,8 @@ export function derivationCommands(deps: DerivationDeps): AnyCommand[] {
       enablement: () => deriveRefusal(activePane().id) === null,
       requires: DERIVE_REQUIRES,
       undo: "none",
-      /* No `aiTool`, by §12.4's first deletion rule: chrome — it arranges what the person is
-         looking at. */
+      /* No `aiTool`, by studio-ui-guidelines.md §12.4's first deletion rule: chrome — it arranges
+         what the person is looking at. */
       run: (_ctx, args) => {
         const preset = enumArg("pane.derive", args, "preset", DERIVE_PRESETS);
         /* `??`, not `||`. `optionalStringArg` answers `undefined` or a non-empty string — it is

package/src/workspace/session.ts

@@ -1,12 +1,13 @@
 /**
  * Session.ts — what a project looked like when you left it, and how it looks that way again.
  *
- * Plan §4.4: "Session state persists **per project root** … open tabs and order per pane, active
- * tab, per-tab editor kind / view / zoom / rendering context." P3's "Newly possible" states the
- * consequence plainly: **the session survives a relaunch.** Neither shipped. The per-project record
- * held `layouts` and `activeLayout` and nothing else, its interface said "Session state (§4.4)
- * grows into this shape", and reopening a project landed on the home page with an empty strip — so
- * nine open documents, a split, and the breakpoint you were checking were lost every time.
+ * The shell redesign promised that session state persists **per project root** — open tabs and
+ * order per pane, active tab, per-tab editor kind / view / zoom / rendering context — and stated
+ * the consequence plainly: **the session survives a relaunch** (§14.8). Neither shipped. The
+ * per-project record held `layouts` and `activeLayout` and nothing else, its interface said session
+ * state would "grow into this shape", and reopening a project landed on the home page with an empty
+ * strip — so nine open documents, a split, and the breakpoint you were checking were lost every
+ * time.
  *
  * **Paths, not tab ids.** A tab id is minted per open and means nothing across a reload; the
  * document's path is the identity the workspace already dedupes on (`openFileInTab` scans