@jxsuite/studio 5.3.0 → 5.4.0

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

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

package/src/workspace/workspace.ts

@@ -1,5 +1,6 @@
 import { computed, reactive, toRaw } from "../reactivity";
 import { commitTabBuffers } from "../services/monaco-buffer";
+import { resetAiWrites } from "../services/ai-writes";
 import { ensureCollab, rekeyCollab } from "../collab/collab-session";
 import { createTab, disposeTab } from "../tabs/tab";
 import { projectState } from "../state";
@@ -12,7 +13,7 @@ import {
 } from "../commands/command-args";
 import { EDITOR_KIND_LABELS } from "../commands/context";
 import type { Tab, TabOrigin } from "../tabs/tab";
-import type { JsonLayout } from "../files/json-layout";
+import type { JsonLayout } from "@jxsuite/schema/json-layout";
 
 import type { ComponentEntry } from "../files/components";
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
@@ -35,11 +36,11 @@ export interface ClosedTabRecord {
 const CLOSED_TAB_LIMIT = 20;
 
 /**
- * One editor pane — the unit of split, focus and zoom (§4.1).
+ * One editor pane — the unit of split, focus and zoom (§18.1).
  *
  * A tab BELONGS to a pane, and the pane is what splits; the tab strip is per-pane for the same
- * reason. This is the minimal model P3 asks for: an ordered list and an active id, with no rules
- * for derived panes and no follow behaviour (those are P8).
+ * reason. The model is deliberately minimal, an ordered list and an active id; derived panes and
+ * their follow behaviour (§18.4) sit beside it in `derived` rather than in either.
  */
 export interface Pane {
   id: string;
@@ -357,10 +358,10 @@ export function focusOtherPane() {
  * `session.ui.canvasMode`), one picked the replacement kind, and two narrowed what the controls
  * offered so no dropdown could contain an entry the app would refuse.
  *
- * The cap existed because a second LIVE canvas host was unaffordable, and it is gone because
- * workstream 1 made it affordable — see {@link MAX_PANES}. Its LAST act was a bug: `capToPaneKind`
- * flipped a splitting Design tab to `source` before focus moved, so `⌘\` on a page you were
- * designing silently became "open this as Code somewhere else".
+ * The cap existed because a second LIVE canvas host was unaffordable, and it is gone because render
+ * fan-out (§18.2) made it affordable — see {@link MAX_PANES}. Its LAST act was a bug:
+ * `capToPaneKind` flipped a splitting Design tab to `source` before focus moved, so `⌘\` on a page
+ * you were designing silently became "open this as Code somewhere else".
  *
  * What replaces them is `tabs/tab.ts`'s `editorKindsOf` — the kinds a DOCUMENT declares — which is
  * the only narrowing left and the only one that was ever about the document rather than about what
@@ -371,7 +372,7 @@ export function focusOtherPane() {
  * Split the grid and move a tab into the new pane, which becomes focused.
  *
  * Moves rather than duplicates: one tab is one document with one undo history and one collab
- * session, and two strips claiming the same id is the duplicate-`repeat`-key bug §4.3 describes.
+ * session, and two strips claiming the same id is the duplicate-`repeat`-key bug §14.1 describes.
  *
  * The subject is `tabId` when given, else the focused pane's active tab. The drag resolver names
  * the tab it is carrying — the gesture points at a chip, not at whatever the keyboard is in — and
@@ -607,11 +608,11 @@ export function paneIsEmpty(pane: Pane): boolean {
   return pane.tabOrder.length === 0 && pane.derived === null;
 }
 
-/* No `togglePaneZoom`. Zoom is a view of a GRID, and there is no grid: §18.3 hands the one stage
-   between panes, so the focused pane already fills the shell and the other one is not on screen to
-   be zoomed away from. The state existed, both commands wrote it, and nothing that draws ever read
-   it — a control whose only observable effect is on itself. It comes back with the second live
-   host, and not one release earlier. */
+/* No `togglePaneZoom`. It was removed when the shell still handed one stage between panes: the
+   focused pane already filled the shell, so the state existed, both commands wrote it, and nothing
+   that draws ever read it — a control whose only observable effect is on itself. There is a grid of
+   live panes now (§18.3), so a zoom is buildable, but no section of studio.md asks for one; it
+   comes back with the section that does, and not one release earlier. */
 
 /**
  * Remove a tab id from whichever pane holds it, without touching the tab itself.
@@ -696,6 +697,13 @@ function defaultSlot(pane: Pane, tabId: string): number {
  * @param {object | null} [config]
  */
 export function setWorkspaceProject(root: string | null, config: object | null = null) {
+  /* Leaving a project drops the assistant's record of what each turn changed (ai.md §3.2). It
+     names project-relative paths, and its Restore undoes the active tab, so carried into another
+     project it would list files that are not there and undo a document the turn never touched.
+     Adopting a project from none keeps it: a bootstrap conversation follows the project it made. */
+  if (workspace.projectRoot && root !== workspace.projectRoot) {
+    resetAiWrites();
+  }
   workspace.projectRoot = root;
   workspace.projectConfig = config;
 }
@@ -820,12 +828,12 @@ function setActiveTab(tabId: string, opts: { cycling?: boolean; focus?: boolean
  * keys. Callers that mean "show me this file" should use `files/files.ts`'s `openFileInTab`, which
  * activates the existing tab instead.
  *
- * `preview: true` opens a DISPOSABLE tab (§4.3): single-clicking through the tree or the palette is
- * browsing, and browsing must not litter, so the next preview open in the same pane takes its slot.
- * It is opt-in rather than the default because only the CALLER knows whether the author was
- * browsing or committing — an author who typed a new file name has committed, and silently
- * discarding that tab on their next click is the one failure a preview tab must never have.
- * {@link promoteTab} records a commitment made after the fact.
+ * `preview: true` opens a DISPOSABLE tab (docs/studio/interface/tabs.md): single-clicking through
+ * the tree or the palette is browsing, and browsing must not litter, so the next preview open in
+ * the same pane takes its slot. It is opt-in rather than the default because only the CALLER knows
+ * whether the author was browsing or committing — an author who typed a new file name has
+ * committed, and silently discarding that tab on their next click is the one failure a preview tab
+ * must never have. {@link promoteTab} records a commitment made after the fact.
  *
  * `paneId` says WHERE, and `focus` says whether the keyboard goes with it. Both default to today's
  * answer — the focused pane, and yes — because "open this document" has always meant "in front of
@@ -1383,12 +1391,12 @@ export function tabCommands(deps: TabCommandDeps): AnyCommand[] {
           "Use it when the user should SEE the page, or for iterative visual refinement after " +
           "creating a page or component.",
         name: "open_document",
-        /* The person's own read: `activeTab` is what the tab strip highlights, and `editor.kind`
-           is the fact the document-tree tier is gated on. Both are named so the model learns in one
+        /* The person's own read: `activeTab` is what the tab strip highlights, and `editor.kind` is
+           the fact the document-tree tier is gated on. Both are named so the model learns in one
            round whether the tree tools reach the file it opened — a `.csv` lands in the Grid, a
            `.png` in the Media viewer, and neither is an element tree. The `.value` read is module
-           state, which a projected `report` may close over (§12.4); `after` alone cannot say WHICH
-           document is active. */
+           state, which a projected `report` may close over (studio-ui-guidelines.md §12.4); `after`
+           alone cannot say WHICH document is active. */
         report: ({ after, args }) => {
           const path = stringArg("document.open", args, "path");
           const active = activeTab.value?.documentPath ?? null;
@@ -1402,11 +1410,12 @@ export function tabCommands(deps: TabCommandDeps): AnyCommand[] {
           return `"${path}" is the active document, ${where}.`;
         },
       },
-      /* Refuses by THROWING (§12.4's first review rule). `openFileInTab` reports a file it cannot
-         open as a Problem and returns normally — the right answer for a click in the Files tree,
-         where the toast is in front of the person — so the record has to look for the tab itself.
-         The hand tool this replaced read `getTab()` after the open and called whatever it found a
-         success, so a missing file left the PREVIOUS document active and reported "Switched to". */
+      /* Refuses by THROWING (studio-ui-guidelines.md §12.4's first review rule). `openFileInTab`
+         reports a file it cannot open as a Problem and returns normally — the right answer for a
+         click in the Files tree, where the toast is in front of the person — so the record has to
+         look for the tab itself. The hand tool this replaced read `getTab()` after the open and
+         called whatever it found a success, so a missing file left the PREVIOUS document active and
+         reported "Switched to". */
       run: async (_ctx, args) => {
         const path = stringArg("document.open", args, "path");
         await deps.openFile(path);
@@ -1435,8 +1444,9 @@ export function tabCommands(deps: TabCommandDeps): AnyCommand[] {
       group: "1_file",
       when: (ctx) => ctx.project.open,
       requires: "an open project",
-      /* No `aiTool`, by §12.4's first deletion rule: chrome — it arranges what the person is
-         looking at. No `undo`: opening a tab is not a state the undo stack owns. */
+      /* No `aiTool`, by studio-ui-guidelines.md §12.4's first deletion rule: chrome — it arranges
+         what the person is looking at. No `undo`: opening a tab is not a state the undo stack
+         owns. */
       undo: "none",
       /* The non-drag equivalent of dragging a file row onto the other pane's strip (SC 2.5.7): the
          same `receivingPane` the drag resolver uses, so a file tree row and this command can never
@@ -1550,12 +1560,12 @@ export function tabCommands(deps: TabCommandDeps): AnyCommand[] {
  * The pane commands.
  *
  * They live beside the pane model for the same reason the tab commands do, and they are the whole
- * user-facing surface of §4.1's Pane transport: split, focus, unsplit, zoom.
+ * user-facing surface of the pane transport (§18.1): split, focus, unsplit, zoom.
  *
  * `⌘0` and `⌘⌥0` are a PAIR, and they are both bound. `⌘0` was `canvas.zoomReset`, which held it
- * for the one verb of the zoom cluster that also has a button in the floating zoom pod (§3.2 ⑩) —
- * so the chord was the second way to reach a control that is already on screen, while focusing a
- * pane had no way at all. The zoom keeps its pod button and gives up the key.
+ * for the one verb of the zoom cluster that also has a button in the floating zoom pod — so the
+ * chord was the second way to reach a control that is already on screen, while focusing a pane had
+ * no way at all. The zoom keeps its pod button and gives up the key.
  *
  * @param {TabCommandDeps} deps
  * @returns {AnyCommand[]}
@@ -1604,13 +1614,13 @@ export function paneCommands(deps: TabCommandDeps): AnyCommand[] {
       /* This is NOT `pane.derive`, and the distinction is the whole reason both exist. `derive`
          shows a projection OF THIS PANE — its Code, its diff, the same page at another breakpoint —
          and follows it. `compareWith` puts THAT DOCUMENT beside this one and then leaves it alone.
-         Collapsing them would give "open a second document in the other pane" two definition
-         sites, which is how the two names in §4.1 came to disagree in the first place. */
+         Collapsing them would give "open a second document in the other pane" two definition sites,
+         which is how the shell redesign's two names for it came to disagree in the first place. */
       enablement: () => workspace.activeTabId !== null,
       requires: "an open document",
       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: async (_ctx, args) => {
         const path = stringArg("pane.compareWith", args, "path");
         const here = activePane();

package/styles/canvas.css

@@ -18,32 +18,6 @@
   min-height: 0;
 }
 
-/* ─── Document Header card ─────────────────────
-   Region ⑧: the artefact's own header, drawn IN the stage. `#frontmatter-panel` — a fourth
-   full-width band up to 40vh that appeared and vanished as a side effect of the canvas mode — is
-   gone, grid row and all.
-
-   Two placements, because the stage draws a page two ways. In Edit the card is `in-column`: a block
-   of the document's own centered column that scrolls with it, so it is part of the artefact rather
-   than a strip above it. In Design the artboards are under a pan/zoom transform, and a form drawn
-   at 40% is a picture of a form — so the card is `pinned` above the surface at 1:1, and that is the
-   one placement that still needs a cap. */
-.doc-header-host[hidden] {
-  display: none;
-}
-.doc-header-host.in-column {
-  display: block;
-  padding-bottom: 16px;
-}
-.doc-header-host.pinned {
-  flex-shrink: 0;
-  max-height: 40vh;
-  overflow-y: auto;
-}
-.doc-header-host.pinned .doc-header {
-  border-width: 0 0 1px;
-  border-radius: 0;
-}
 /* ─── Content edit mode canvas ─────────────── */
 .content-edit-canvas {
   width: 100%;
@@ -201,7 +175,7 @@
 .overlay-coselection-group {
   display: contents;
 }
-/* The other members of a multi-selection (§6.5). Same accent, thinner: one box is the primary —
+/* The other members of a multi-selection (§6.7). Same accent, thinner: one box is the primary —
    what the Inspector, the block action bar and the status bar address — and the rest are along for
    the batch. A selection of one draws no co-selection boxes at all. */
 .overlay-coselection {