@jxsuite/studio 5.3.0 → 5.4.0

package/src/surfaces/settings-locales.json

@@ -20,8 +20,8 @@
       "fontSize": "var(--jx-text-md)",
       "color": "var(--fg-dim)"
     },
-    "& [part=\"error\"]": {
-      "$description": "A write that failed, said under the section title rather than pinned to a control: settings save on change, so a silent rejection would read as \"my edit just vanished\", and the whole file failed rather than one field.",
+    "& [part=\"section-error\"]": {
+      "$description": "A write that failed, said under the section title rather than pinned to a control: settings save on change, so a silent rejection would read as \"my edit just vanished\", and the whole file failed rather than one field. It is `section-error` rather than `error` because the tag field's refusal IS the kit's own `[part=\"error\"]` sentence, in this same light-DOM tree: a rule on that name gave the tag field's refusal this margin and size, and reached the two pickers' empty regions as well.",
       "margin": "6px 0 0",
       "fontSize": "var(--jx-text-md)",
       "color": "var(--danger)"
@@ -95,7 +95,7 @@
     {
       "tagName": "div",
       "attributes": {
-        "part": "error-slot",
+        "part": "section-error-slot",
         "role": "none"
       },
       "$switch": {
@@ -105,7 +105,7 @@
         "true": {
           "tagName": "p",
           "attributes": {
-            "part": "error",
+            "part": "section-error",
             "role": "alert"
           },
           "textContent": "${state.error}"

package/src/surfaces/settings-overview.ts

@@ -188,7 +188,8 @@ export function mountOverviewSurface(
   let disposed = false;
   /* Nothing is called on the element, so the mount is all this has to wait for: the DOCUMENT is
      what this surface renders, and the kit elements inside it settle their own templates one
-     `connectedCallback` later without anybody here asking them to (§1.1, "await the element"). */
+     `connectedCallback` later without anybody here asking them to (studio-ui-guidelines.md §1.1,
+     "await the element"). */
   void mountSurface("settings-overview", scope, container).then((surface) => {
     if (disposed) {
       surface.dispose();

package/src/surfaces/settings-pane.ts

@@ -8,8 +8,9 @@
  * **One island, and the sections are why.** A settings section is handed a container and renders
  * into it — some of them still with lit, some by mounting a document of their own — so the body
  * cannot be part of this document's subtree. It draws an empty `[part="body"]`, announces it
- * through `onNodeCreated` as it is created, and the flow renders into it (studio-ui-guidelines.md
- * §9.4). Nothing here queries for it by a selector this package also renders.
+ * through `onNodeCreated` as it is created, and the flow renders into it: the island seam of
+ * studio-ui-guidelines.md §9.4. Nothing here queries for it by a selector this package also
+ * renders.
  *
  * @docs studio/projects/settings
  */

package/src/surfaces/settings-rawjson.ts

@@ -77,7 +77,7 @@ export function mountRawJsonSurface(
   let disposed = false;
   /* Nothing is called on the element, so the mount is all this has to wait for: the DOCUMENT is
      what this surface renders, and `jx-button` settles its own template one `connectedCallback`
-     later without anybody here asking it to (§1.1, "await the element"). */
+     later without anybody here asking it to (studio-ui-guidelines.md §1.1, "await the element"). */
   void mountSurface("settings-rawjson", scope, container).then((surface) => {
     if (disposed) {
       surface.dispose();

package/src/surfaces/slash-menu.ts

@@ -6,10 +6,10 @@
  * which commands are on offer, what the filter matches, which row is active and what a pick does.
  *
  * **It is a listbox, and it is deliberately not `surfaces/menu.json`.** Every other Studio menu is
- * that surface, and the rule is that a second list of actions is a defect (§12.5) — but the two
- * differ on the one thing a menu cannot give up. `jx-menu` owns the keyboard: showing it moves the
- * caret onto its first row, which is the whole point of a roving-focus menu. This panel filters a
- * caret that is somewhere else — inside the canvas's `contenteditable`, and usually inside the
+ * that surface, and studio-ui-guidelines.md §12.5 makes a second list of actions a defect — but the
+ * two differ on the one thing a menu cannot give up. `jx-menu` owns the keyboard: showing it moves
+ * the caret onto its first row, which is the whole point of a roving-focus menu. This panel filters
+ * a caret that is somewhere else — inside the canvas's `contenteditable`, and usually inside the
  * canvas IFRAME — and every character typed after the `/` has to keep landing there, so the panel
  * that takes the keyboard is the panel that ends the interaction it exists to serve. What is left
  * once focus is off the table is a combobox popup: `role="listbox"`, an active row marked with

package/src/surfaces/statements.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://jxsuite.com/schema/v1",
   "$id": "StudioStatements",
-  "$description": "The statement editor (spec §20): a Function entry's `body: JxStatement[]` edited as STRUCTURE rather than as text. The rows arrive FLAT. A statement tree nests to any depth — an `if` holds two lanes, a `$switch` holds one per case plus a default, and either may hold another of both — while a document's one repeater is `$prototype: \"Array\"` over a list, so `panels/statement-editor.ts` walks the tree once and hands over rows that already carry their own indent; recursion is a property of the walk, exactly as it is for the Data panel's value tree. Four kinds of row come out of that walk: a statement CARD (its header, and the fields that statement is made of), a LANE header naming a branch, the ADD control that ends every lane, and an ACTION that grows the statement itself (`+ Add else`, `+ Add case`). Two hosts draw this — the Navigator's State panel and the Inspector's Logic tab — and neither is named here: the region is stamped on the host, because a shared control cannot know where it is. An operand is an ISLAND: the document renders `[part=\"control-host\"]` and nothing inside it, and the flow fills it with the expression editor (studio-ui-guidelines.md §9.4).",
+  "$description": "The statement editor (spec.md §20): a Function entry's `body: JxStatement[]` edited as STRUCTURE rather than as text. The rows arrive FLAT. A statement tree nests to any depth — an `if` holds two lanes, a `$switch` holds one per case plus a default, and either may hold another of both — while a document's one repeater is `$prototype: \"Array\"` over a list, so `panels/statement-editor.ts` walks the tree once and hands over rows that already carry their own indent; recursion is a property of the walk, exactly as it is for the Data panel's value tree. Four kinds of row come out of that walk: a statement CARD (its header, and the fields that statement is made of), a LANE header naming a branch, the ADD control that ends every lane, and an ACTION that grows the statement itself (`+ Add else`, `+ Add case`). Two hosts draw this — the Navigator's State panel and the Inspector's Logic tab — and neither is named here: the region is stamped on the host, because a shared control cannot know where it is. An operand is an ISLAND: the document renders `[part=\"control-host\"]` and nothing inside it, and the flow fills it with the expression editor (studio-ui-guidelines.md §9.4).",
   "tagName": "div",
   "attributes": {
     "part": "statements"
@@ -218,7 +218,7 @@
                       "$ref": "$map/item/key"
                     },
                     "map": {
-                      "$description": "One operand of the statement. Every field is `span` — the Inspector is 280px and the guidelines' standard row is vertically stacked (§4.1) — and every field carries `data-prop`, which is what `inspector/field:<prop>` addresses. The key is `<row>::<prop>`, self-contained because this `$map` shadows the row's own `$map.item`.",
+                      "$description": "One operand of the statement. Every field is `span` — the Inspector is 280px and the standard row is vertically stacked (studio-ui-guidelines.md §4.1) — and every field carries `data-prop`, which is what `inspector/field:<prop>` addresses. The key is `<row>::<prop>`, self-contained because this `$map` shadows the row's own `$map.item`.",
                       "tagName": "jx-field",
                       "attributes": {
                         "part": "field",
@@ -500,7 +500,7 @@
             ]
           },
           "add": {
-            "$description": "The end of every lane. It opens the kit's menu rather than being a picker of its own: a select that has to snap back to its placeholder after each pick is a control fighting the runtime's skip-an-equal-write, and §12.5 asks for one list of actions rather than a second.",
+            "$description": "The end of every lane. It opens the kit's menu rather than being a picker of its own: a select that has to snap back to its placeholder after each pick is a control fighting the runtime's skip-an-equal-write, and studio-ui-guidelines.md §12.5 asks for one list of actions rather than a second.",
             "tagName": "div",
             "attributes": {
               "part": "add",

package/src/surfaces/statusbar.ts

@@ -1,24 +1,24 @@
 /// <reference lib="dom" />
 /**
- * ⑫ The status bar — ambient state, in scope order, and nothing else.
+ * The status bar — ambient state, in scope order, and nothing else.
  *
  * What this replaces: a bar built by `innerHTML` string concatenation with a three-character
  * escaper, carrying whatever the last of 78 `statusMessage()` calls had said, for three seconds.
  * Transient messages have left entirely for the toast host (`ui/layers.ts`) and the Problems list
  * (`services/notify.ts`); what remains here is state that is TRUE for as long as it is shown.
  *
- * **Three fixed fields, in the shell's own left-to-right level order** (plan §3.2 ⑫), so the bar
- * restates the containment model on every glance:
+ * **Three fixed fields, in the shell's own left-to-right level order** (§16.2), so the bar restates
+ * the containment model on every glance:
  *
  * ```text
  * PROJECT                        ‖ DOCUMENT                       ‖ SELECTION
  * name · branch ↑n↓n · problems  ‖ path · view · save state       ‖ count · style rule
  * ```
  *
- * The SELECTION field held an ancestor breadcrumb until region ⑥ landed. The trail is an ADDRESS,
- * not ambient state, and it now lives once — in the jump bar (`panels/jump-bar.ts`), which merged
- * it with the pane context bar's document-stack chain. What is left here is the count and the
- * Stylebook's rule, neither of which is a path.
+ * The SELECTION field held an ancestor breadcrumb until the jump bar landed. The trail is an
+ * ADDRESS, not ambient state, and it now lives once — in the jump bar (`panels/jump-bar.ts`), which
+ * merged it with the pane context bar's document-stack chain. What is left here is the count and
+ * the Stylebook's rule, neither of which is a path.
  *
  * `statusbar/project`, `statusbar/document` and `statusbar/selection` are three placements the
  * level × placement matrix already declares, each admitting exactly one level — so the bar's
@@ -31,12 +31,12 @@
  *
  * **Every interactive item is a command.** There are no click handlers in this file: an item names
  * a command id, and renders as a button only when the registry has that command and its `when`
- * holds. That is what lets an item that has no command yet — the peers count, whose `Collaborate:`
- * family lands with P4.8 — sit in the template today and start rendering the day it is registered,
- * with no edit here. The three readouts that are NOT buttons are marked: the view name (its control
- * is the pane context bar ⑦; a second mode picker in 24px would be the chrome duplication §2
- * principle 9 exists to prevent), the save wording once a document IS saved, and the stylebook
- * selector.
+ * holds. That is what let an item with no command yet — the peers count, before the `Collaborate:`
+ * family was registered — sit in the template and start rendering the day its command arrived, with
+ * no edit here. The three readouts that are NOT buttons are marked: the view name (its control is
+ * the pane context bar; a second mode picker in 24px would be the chrome duplication
+ * studio-ui-guidelines.md §12.2's budget exists to prevent), the save wording once a document IS
+ * saved, and the stylebook selector.
  *
  * The bar is the `statusbar` surface (`surfaces/statusbar.json`): this module is the projection —
  * three fields of items, each item a button with a command or a readout without — and the surface
@@ -186,7 +186,7 @@ function projectField(
   return { id, items: live, region };
 }
 
-// ─── ⑫a PROJECT ──────────────────────────────────────────────────────────────
+// ─── PROJECT ─────────────────────────────────────────────────────────────────
 
 /** `↑2↓1`, or "" when the branch is level with its upstream. */
 export function aheadBehindLabel(ahead: number, behind: number): string {
@@ -203,15 +203,15 @@ function projectField_(registry: CommandRegistry | null): ProjectedField | null
     project
       ? { command: "project.openRecent", label: project.name }
       : { command: "project.open", label: "No project" },
-    /* WHICH branch, when there is one — and deliberately no "not tracked" twin, though plan §12 P1
-       workstream 9's "repo state becomes a persistent status-bar field" reads like a request for
-       one. An untracked project already states itself in this field, one item along:
+    /* WHICH branch, when there is one — and deliberately no "not tracked" twin, though the shell
+       redesign's "repo state becomes a persistent status-bar field" reads like a request for one.
+       An untracked project already states itself in this field, one item along:
        `deployStatusItem()`'s first link is `repo`, whose label is "Track this project with git" and
        whose command is `git.init`. A second item beside it would carry no fact the first does not
        — "Not tracked" and "Track this project with git" answer the same question with the same verb
-       — and adjacent duplicate chrome is what §2 principle 9 forbids. `tests/statusbar.test.ts`
-       pins the pairing from both ends, so deleting the checklist's repo step fails there rather
-       than quietly taking the state off the bar. */
+       — and adjacent duplicate chrome is what the chrome budget (studio-ui-guidelines.md §12.2)
+       forbids. `tests/statusbar.test.ts` pins the pairing from both ends, so deleting the
+       checklist's repo step fails there rather than quietly taking the state off the bar. */
     status?.isRepo === true && status.branch
       ? {
           command: "panel.focus.git",
@@ -248,7 +248,7 @@ function projectField_(registry: CommandRegistry | null): ProjectedField | null
   ]);
 }
 
-// ─── ⑫b DOCUMENT ─────────────────────────────────────────────────────────────
+// ─── DOCUMENT ────────────────────────────────────────────────────────────────
 
 /**
  * What the pane is showing, in the words the pane context bar uses.
@@ -307,13 +307,13 @@ function documentField(registry: CommandRegistry | null): ProjectedField | null
   ]);
 }
 
-// ─── ⑫c SELECTION ────────────────────────────────────────────────────────────
+// ─── SELECTION ───────────────────────────────────────────────────────────────
 
 /**
  * What is selected — the COUNT, and nothing that is an address.
  *
  * This field used to carry a clickable ancestor trail, one `selection.set` per crumb. That trail
- * has moved whole to the jump bar (⑥, `panels/jump-bar.ts`), which is region ⑥'s entire reason to
+ * has moved whole to the jump bar (`panels/jump-bar.ts`), which is the jump bar's entire reason to
  * exist: Studio had two half-breadcrumbs — that one, and the pane context bar's document-stack
  * chain — and neither ever rendered the whole address. Leaving a copy here would have made three.
  *

package/src/surfaces/style-panel.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://jxsuite.com/schema/v1",
   "$id": "StudioStylePanel",
-  "$description": "The Inspector's Style tab: the Target Line's host, one filter, then the CSS property accordion — every row saying where its value came from (§6.2), every section heading tallying what is set inside it. Nothing here knows what CSS is. `panels/style-panel.ts` resolves the compound coordinate (selection, breakpoint, scheme layer, nested selector), reads css-meta, decides which of seven controls a property gets, works out its provenance and what a commit writes; this document draws the answer and decides nothing. That split is what lets the tab stop going through `panels/panel-scheduler.ts`: the focus guard existed because a lit repaint of the whole panel could take the field a reader was typing into, and a document is one runtime effect per bound property with an equal write skipped.",
+  "$description": "The Inspector's Style tab: the Target Line's host, one filter, then the CSS property accordion — every row saying where its value came from (§6.7), every section heading tallying what is set inside it. Nothing here knows what CSS is. `panels/style-panel.ts` resolves the compound coordinate (selection, breakpoint, scheme layer, nested selector), reads css-meta, decides which of seven controls a property gets, works out its provenance and what a commit writes; this document draws the answer and decides nothing. That split is what lets the tab stop going through `panels/panel-scheduler.ts`: the focus guard existed because a lit repaint of the whole panel could take the field a reader was typing into, and a document is one runtime effect per bound property with an equal write skipped.",
   "tagName": "div",
   "attributes": {
     "part": "panel"
@@ -14,7 +14,7 @@
     "fontFamily": "var(--jx-font-sans)",
     "color": "var(--jx-fg)",
     "& [part=\"empty\"]": {
-      "$description": "The one empty-state pattern (`panels/empty-state.ts`), drawn here because a document cannot render a lit helper. Its rules are what is kept (§11): one sentence saying what the region is FOR, then the action that fills it.",
+      "$description": "The one empty-state pattern (`panels/empty-state.ts`), drawn here because a document cannot render a lit helper. Its rules are what is kept (studio-ui-guidelines.md §11): one sentence saying what the region is FOR, then the action that fills it.",
       "display": "flex",
       "flexDirection": "column",
       "alignItems": "center",
@@ -106,7 +106,7 @@
       "minInlineSize": "0"
     },
     "& [part=\"chip-slot\"] > [part=\"chip\"]": {
-      "$description": "One vocabulary, five states (§6.2). `default` draws nothing at all — absence IS the ghost — which is why there is no rule for it: the document never makes the node. `set` is the 6px accent disc `.set-dot` has always been; the two that carry information wear their donor's name in a bordered pill, and `mixed` is neutral on purpose because it says nothing about WHERE a value came from, only that the selection disagrees.",
+      "$description": "One vocabulary, five states (§6.7). `default` draws nothing at all — absence IS the ghost — which is why there is no rule for it: the document never makes the node. `set` is the 6px accent disc `.set-dot` has always been; the two that carry information wear their donor's name in a bordered pill, and `mixed` is neutral on purpose because it says nothing about WHERE a value came from, only that the selection disagrees.",
       "display": "inline-flex",
       "alignItems": "center",
       "flexShrink": "0",
@@ -190,7 +190,7 @@
       "background": "var(--jx-handler)"
     },
     "& [part=\"source\"]": {
-      "$description": "The Value Source chip (§6.3): quiet while the value is a literal, accent-tinted the moment it is produced from something else. A CSS declaration has exactly two rungs — `JxStyle` admits no `$ref` — so the picker it opens is two rows, and that is derived from the schema rather than written here.",
+      "$description": "The Value Source chip (§6.6): quiet while the value is a literal, accent-tinted the moment it is produced from something else. A CSS declaration has exactly two rungs — `JxStyle` admits no `$ref` — so the picker it opens is two rows, and that is derived from the schema rather than written here.",
       "flex": "none",
       "color": "var(--jx-fg-dim)"
     },
@@ -881,7 +881,7 @@
                                       }
                                     },
                                     "group": {
-                                      "$description": "The dual-mode control: a number beside its unit. Type what you mean, or take a unit from the list — and the list is the kit MENU rather than a second popup of this document's own (§12.5), because every row of it is a verb: a unit re-attaches to the number the field holds. A keyword row, whose list commits a value, is the `keywords` case instead — and so is the font row now, because a font is chosen by looking and a menu row cannot draw itself in its own face.",
+                                      "$description": "The dual-mode control: a number beside its unit. Type what you mean, or take a unit from the list — and the list is the kit MENU rather than a second popup of this document's own (studio-ui-guidelines.md §12.5), because every row of it is a verb: a unit re-attaches to the number the field holds. A keyword row, whose list commits a value, is the `keywords` case instead — and so is the font row now, because a font is chosen by looking and a menu row cannot draw itself in its own face.",
                                       "tagName": "div",
                                       "attributes": {
                                         "part": "group"
@@ -1070,7 +1070,11 @@
                                                 },
                                                 "children": [
                                                   {
+                                                    "$description": "The abbreviation, for a value with no glyph, and HIDDEN rather than empty on a button that has one. The kit's `[part=\"label\"]` is `display: contents`, so an empty span is still a flex item in the control, and the control's 4px gap sits between the glyph and nothing: every icon button in the tab drew 26px wide with its glyph pushed 2px off centre, instead of 22px and centred. Hidden, it takes no box, and the button's name and tooltip are the value either way.",
                                                     "tagName": "span",
+                                                    "attributes": {
+                                                      "hidden": "${$map.item.text ? null : ''}"
+                                                    },
                                                     "textContent": "${$map.item.text}"
                                                   }
                                                 ]

package/src/surfaces/style-panel.ts

@@ -104,9 +104,9 @@ export interface StyleButtonView extends Record<string, unknown> {
   value: string;
   /** The accessible name and tooltip. */
   title: string;
-  /** A kit glyph name, or the empty string where the kit has none for this value. */
+  /** A kit manifest name, css-meta's `$icons` entry verbatim, or `""` where the value has none. */
   icon: string;
-  /** The abbreviation drawn when there is no glyph. Empty when there is one. */
+  /** The abbreviation drawn when there is no glyph. Empty when there is one, and its span hidden. */
   text: string;
   selected: boolean;
 }
@@ -138,7 +138,7 @@ export interface StyleRowView extends Record<string, unknown> {
   chipState: string;
   chipText: string;
   chipTitle: string;
-  /** The Value Source chip (§6.3). Absent on a child, a custom pair and a nested rule. */
+  /** The Value Source chip (§6.6). Absent on a child, a custom pair and a nested rule. */
   hasSource: boolean;
   sourceState: string;
   sourceLabel: string;

package/src/surfaces/tab-strip.json

@@ -101,7 +101,7 @@
       "lineHeight": "1"
     },
     "& [part=\"pill\"]": {
-      "$description": "`.entry-pill` — the draft pill (§7.6), in `jx-tab`'s status slot. It is ON THE CHIP and not only inside the entry editor because the mistake it prevents, publishing something you believed was private, is made while glancing at a row of tabs. \"Published\" is deliberately as visible as \"Draft\": a state you can only see one half of is a state you cannot check. The two Spectrum colours it used to name are `--jx-signal` against `--jx-bg`, which flips with the theme where a fixed yellow and a fixed black did not.",
+      "$description": "`.entry-pill` — the draft pill (site-architecture.md §7.6), in `jx-tab`'s status slot. It is ON THE CHIP and not only inside the entry editor because the mistake it prevents, publishing something you believed was private, is made while glancing at a row of tabs. \"Published\" is deliberately as visible as \"Draft\": a state you can only see one half of is a state you cannot check. The two Spectrum colours it used to name are `--jx-signal` against `--jx-bg`, which flips with the theme where a fixed yellow and a fixed black did not.",
       "padding": "0 5px",
       "borderRadius": "var(--radius)",
       "background": "var(--bg)",
@@ -334,7 +334,7 @@
                     "textContent": "${$map.item.pill}"
                   },
                   {
-                    "$description": "The pin, in the actions slot. `title` is the whole accessible name (§10): the glyph is hidden, so a matching `aria-label` would announce it twice. `tabindex` follows the tab's own selectedness, exactly as the close button's does — the strip is ONE stop in the tab order, and a control inside every chip that took the platform's default would make fifteen.",
+                    "$description": "The pin, in the actions slot. `title` is the whole accessible name (studio-ui-guidelines.md §10): the glyph is hidden, so a matching `aria-label` would announce it twice. `tabindex` follows the tab's own selectedness, exactly as the close button's does — the strip is ONE stop in the tab order, and a control inside every chip that took the platform's default would make fifteen.",
                     "tagName": "button",
                     "attributes": {
                       "slot": "actions",

package/src/surfaces/target-line.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://jxsuite.com/schema/v1",
   "$id": "StudioTargetLine",
-  "$description": "The Style tab's edit target, as one sentence (plan §6.1): element · breakpoint · scheme variant · selector, then the chip that states how wide the blast radius is. Every word of the sentence is a control, because a sentence you cannot act on is a caption and the panel already had one of those. The breakpoint and scheme segments ROUTE to where those axes are defined rather than offering a third list to pick from — the Style tab owns the selector axis and nothing else — so the selector is the one segment with a menu, and that menu is the kit's. The project-scope warning band is not decoration: entering Stylebook converts every edit from `this element` to `every element of this tag`, and the band states that before the first keystroke.",
+  "$description": "The Style tab's edit target, as one sentence (§6.2): element · breakpoint · scheme variant · selector, then the chip that states how wide the blast radius is. Every word of the sentence is a control, because a sentence you cannot act on is a caption and the panel already had one of those. The breakpoint and scheme segments ROUTE to where those axes are defined rather than offering a third list to pick from — the Style tab owns the selector axis and nothing else — so the selector is the one segment with a menu, and that menu is the kit's. The project-scope warning band is not decoration: entering Stylebook converts every edit from `this element` to `every element of this tag`, and the band states that before the first keystroke.",
   "tagName": "div",
   "attributes": {
     "part": "target"

package/src/surfaces/target-line.ts

@@ -1,9 +1,9 @@
 /// <reference lib="dom" />
 /**
- * The Target Line — the Style tab's compound edit target, as one sentence (plan §6.1).
+ * The Target Line — the Style tab's compound edit target, as one sentence (§6.2).
  *
  * ```text
- * ⌖  h1 · @md · :hover · dark variant                    [ all <h1> in this document ]
+ * ⌖  h1 · Base · dark variant · :hover                   [ all <h1> in this document ]
  * ```
  *
  * `style-panel.ts` has always computed this tuple exactly: it is the per-field key
@@ -18,10 +18,10 @@
  * 1. **Every segment is a control.** A sentence you cannot act on is a caption, and the panel already
  *    had one of those.
  * 2. **The Style tab does not own the breakpoint or the scheme.** Those axes are SELECTED on the pane
- *    context bar (region ⑦) and DEFINED in Project Settings › Contexts — §2 principle 5. The
- *    breakpoint and scheme segments therefore state the resolved value and route to the definition
- *    site; they do not offer a third list to pick from. The selector segment is the one axis this
- *    tab owns, so it is the one segment with a menu.
+ *    context bar and DEFINED in Project Settings › Contexts (§6.2). The breakpoint and scheme
+ *    segments therefore state the resolved value and route to the definition site; they do not
+ *    offer a third list to pick from. The selector segment is the one axis this tab owns, so it is
+ *    the one segment with a menu.
  * 3. **The scope chip is what makes Stylebook safe.** Entering Stylebook silently discards the element
  *    selection and converts every subsequent edit from "this element" to "every element of this
  *    tag" — with one line of text, after the fact, as the only signal. The chip states the blast
@@ -35,8 +35,9 @@
  * panel renders an EMPTY host for it and hands this module the model; the document owns the markup,
  * the ARIA and every value in the style, and this module owns the decisions — what each word says,
  * what pressing one does, and what the selector menu offers. That menu is the KIT's
- * (`surfaces/menu.ts`), because a list of choices is what that surface already is (§12.5), which is
- * also how the roving caret, typeahead and Escape arrive here without a line of keyboard code.
+ * (`surfaces/menu.ts`), because a list of choices is what that surface already is
+ * (studio-ui-guidelines.md §12.5), which is also how the roving caret, typeahead and Escape arrive
+ * here without a line of keyboard code.
  *
  * @docs studio/design/states-and-selectors
  */
@@ -78,7 +79,7 @@ export interface TargetSelector {
   /** Which options the element already declares — marked in the menu. */
   declared: Set<string>;
   onSelect: (selector: string | null) => void;
-  /** Opens the Add Nested Selector dialog (`showPromptDialog`, ui-guidelines §8.7). */
+  /** Opens the Add Nested Selector dialog (`showPromptDialog`, studio-ui-guidelines.md §8.7). */
   onAddCustom: () => void;
 }
 
@@ -277,7 +278,8 @@ const ADD_SELECTOR_VALUE = "__add_custom__";
  *
  * The one command in this file, and it addresses a CONTROL rather than a state — which is why it
  * refuses out loud instead of doing nothing: a manifest that hands a CSS selector to a synthetic
- * mouse would silently photograph the wrong panel (§13).
+ * mouse would silently photograph the wrong panel (the shot contract,
+ * `scripts/screenshots/README.md`).
  *
  * @throws {RangeError} When the Style tab is not rendered.
  */

package/src/surfaces/welcome.json

@@ -47,10 +47,15 @@
       "letterSpacing": "0.3px"
     },
     "& [part=\"section-header\"]": {
+      "$description": "`center`, not `baseline`: `Clear all` is a small kit button, and a small kit control is layout-contained so its outset hit area adds nothing to a scrolling ancestor's overflow, which leaves it with no baseline to export. A baseline row synthesised one from the button's bottom edge, which stood the header 33px tall with the title 10px under the button's label. The gap under the header is the HEADER's, because centring aligns MARGIN boxes: while the h2 kept its own 8px block-end margin its margin box was 26px, exactly the header's height, so `center` had nothing to move and left the h2 flush at the top with the button centred 3.6px below its baseline — a fix that measured right and still looked wrong. With the margin moved out, the two boxes are the only things in the line and they centre on each other.",
       "display": "flex",
-      "alignItems": "baseline",
+      "alignItems": "center",
       "justifyContent": "space-between",
-      "gap": "var(--jx-space-4)"
+      "gap": "var(--jx-space-4)",
+      "marginBottom": "var(--jx-space-3)"
+    },
+    "& [part=\"section-header\"] [part=\"section-title\"]": {
+      "marginBlockEnd": "0"
     },
     "& [part=\"actions\"]": {
       "display": "flex",

package/src/tabs/doc-op-apply.ts

@@ -4,10 +4,10 @@
  * from live editing: history replay in the parent ({@link file://./transact.ts}) and the iframe
  * canvas's non-reactive shadow doc (the patch source-of-truth across the cross-origin bridge).
  *
- * The implementation is the canonical one in `@jxsuite/collab/ops` (yjs-free, so the slim
- * canvas-iframe bundle imports it without dragging yjs in); this module re-exports it so both sides
- * of the frame boundary — and the collab bridge — replay ops through one code path.
+ * The implementation is the canonical one in `@jxsuite/schema/doc-ops` (it imports types only, so
+ * the slim canvas-iframe bundle takes it without dragging yjs in); this module re-exports it so
+ * both sides of the frame boundary and the collab bridge replay ops through one code path.
  */
 
-export { applyDocOpToDoc, childArray, cloneValue } from "@jxsuite/collab/ops";
-export type { JxDocOp } from "@jxsuite/collab/ops";
+export { applyDocOpToDoc, childArray, cloneValue, inverseOf } from "@jxsuite/schema/doc-ops";
+export type { JxDocOp } from "@jxsuite/schema/doc-ops";

package/src/tabs/patch-ops.ts

@@ -6,7 +6,7 @@
  */
 
 // oxlint-disable-next-line unicorn/prefer-export-from -- JxDocOpPair is also used locally (TransactionRecord)
-import type { JxDocOpPair } from "@jxsuite/collab/ops";
+import type { JxDocOpPair } from "@jxsuite/schema/doc-ops";
 import type { JxPath } from "../state";
 import type { Tab } from "./tab.js";
 
@@ -34,10 +34,10 @@ export type JxPatchOp =
  * Value-carrying document mutation, replayable in either direction. Mutators record a
  * forward/inverse pair per change; history applies them for surgical undo/redo and for
  * materializing states from checkpoints — without whole-document snapshots per edit. The definition
- * is canonical in `@jxsuite/collab/ops` (the collab bridge mirrors the same ops into a shared
+ * is canonical in `@jxsuite/schema/doc-ops` (the collab bridge mirrors the same ops into a shared
  * Y.Doc); re-exported here so studio call sites keep their import path.
  */
-export type { JxDocOp } from "@jxsuite/collab/ops";
+export type { JxDocOp } from "@jxsuite/schema/doc-ops";
 export type { JxDocOpPair };
 
 /**

package/src/tabs/project-config.ts

@@ -33,14 +33,14 @@
  * from the other side: a config that reached disk without passing through here (the assistant's
  * `write_file`) is put INTO the document rather than left beside it as a rival.
  *
- * **One serialisation.** {@link serializeProjectConfig} is `files/json-layout.ts`'s serializer over
- * the layout the file was read in — byte-for-byte what `files/serialize-document.ts`'s native-JSON
- * branch writes, so a ⌘S on the open tab and a settings edit produce the same file. The predecessor
- * had `null, 2` in `site-context.ts` and `"\t"` in both `settings/contributed-section.ts` and
- * `settings/defs-editor.ts`, so a settings edit re-indented the entire file — every `project.json`
- * in this repository is on disk with two spaces. It was then `JSON.stringify(config, null, 2)`,
- * which agreed with the tab's save and disagreed with the formatter: a one-field edit re-laid every
- * short array in the file (issue 308).
+ * **One serialisation.** {@link serializeProjectConfig} is `@jxsuite/schema/json-layout`'s
+ * serializer over the layout the file was read in — byte-for-byte what
+ * `files/serialize-document.ts`'s native-JSON branch writes, so a ⌘S on the open tab and a settings
+ * edit produce the same file. The predecessor had `null, 2` in `site-context.ts` and `"\t"` in both
+ * `settings/contributed-section.ts` and `settings/defs-editor.ts`, so a settings edit re-indented
+ * the entire file — every `project.json` in this repository is on disk with two spaces. It was then
+ * `JSON.stringify(config, null, 2)`, which agreed with the tab's save and disagreed with the
+ * formatter: a one-field edit re-laid every short array in the file (issue 308).
  *
  * **A no-op edit writes nothing.** A form that re-commits the value it already holds — and every
  * one of these surfaces has such a path — used to rewrite the whole file. A commit now compares the
@@ -67,8 +67,8 @@ import { requireProjectState, setProjectState } from "../state";
 import { setWorkspaceProject, workspace } from "../workspace/workspace";
 import { PROJECT_CONFIG_PATH, createTab, disposeTab } from "./tab";
 import { transactDoc } from "./transact";
-import { deriveJsonLayout, parseJsonDocument, serializeJson } from "../files/json-layout";
-import type { JsonLayout } from "../files/json-layout";
+import { deriveJsonLayout, parseJsonDocument, serializeJson } from "@jxsuite/schema/json-layout";
+import type { JsonLayout } from "@jxsuite/schema/json-layout";
 
 import type { Tab } from "./tab";
 import type { ProjectConfig } from "@jxsuite/schema/types";

package/src/tabs/selection.ts

@@ -1,5 +1,5 @@
 /**
- * The selection SET — one vocabulary for `session.selection`, now that it is `JxPath[]` (§6.5).
+ * The selection SET — one vocabulary for `session.selection`, now that it is `JxPath[]` (§6.7).
  *
  * ## The invariant this module exists to hold
  *

package/src/tabs/tab.ts

@@ -8,7 +8,7 @@ import { editorKindForMode } from "../commands/context";
 import type { EditorKind } from "../commands/context";
 import type { JxMutableNode } from "@jxsuite/schema/types";
 import type { JxDocOp, JxFmOp } from "./patch-ops";
-import type { JsonLayout } from "../files/json-layout";
+import type { JsonLayout } from "@jxsuite/schema/json-layout";
 
 /**
  * The project's configuration file, project-relative.
@@ -70,13 +70,13 @@ export interface TabUi {
   featureToggles: Record<string, boolean>;
   /**
    * Canvas color-scheme preview: follow the OS ("auto") or force a scheme. Drives the
-   * data-color-scheme attribute on the canvas iframe root (spec §9.5) and, in the style sidebar,
+   * data-color-scheme attribute on the canvas iframe root (spec.md §9.5) and, in the style sidebar,
    * which scheme layer edits target.
    */
   previewColorScheme: "auto" | "light" | "dark";
   /**
-   * The locale this pane renders AS — the artboard's `lang` and `dir` (§13.4), never which file is
-   * open.
+   * The locale this pane renders AS — the artboard's `lang` and `dir` (site-architecture.md §13.4),
+   * never which file is open.
    *
    * Jx has no message catalogue: a translation is a different file in a different directory, so
    * "show this page in French" is a navigation and belongs to the locale preset. This axis is the
@@ -187,8 +187,8 @@ export interface Tab {
     handlersSource: string | null;
     dirty: boolean;
     /**
-     * The layout the document's JSON file was written in (`files/json-layout.ts`), or null for a
-     * document with no JSON source — a format-class file, a new document, a stub.
+     * The layout the document's JSON file was written in (`@jxsuite/schema/json-layout`), or null
+     * for a document with no JSON source — a format-class file, a new document, a stub.
      *
      * On the document record because it is a fact about the FILE the document came from, and it
      * lives exactly as long as that fact does: every edit leaves it alone (the pointers it is keyed
@@ -201,7 +201,7 @@ export interface Tab {
   };
   session: {
     /**
-     * The selected document paths, in the order the user built them (§6.5).
+     * The selected document paths, in the order the user built them (§6.7).
      *
      * `[]` is "nothing selected" — there is no `null` state, because "no selection" and "a
      * selection of nothing" were never two different things. `selection[0]` is the anchor a
@@ -419,11 +419,9 @@ function inferDocumentMode(documentPath: string | null | undefined, sourceFormat
 }
 
 // ─── Editor kinds ─────────────────────────────────────────────────────────────
-// §4.2's first axis. `canvasMode` conflates two orthogonal questions — WHICH EDITOR is open, and
-// (for the Canvas editor only) WHICH VIEW of it. The pane context bar labels them separately, and
-// The pane model needs the first one on its own: the second pane is capped to non-Canvas kinds
-// Until P8's `canvas-patcher` fan-out lands, because a second live `@jxsuite/runtime` host is the
-// Expensive part.
+// The pane context bar's Editor axis (docs/studio/interface/tabs.md). `canvasMode` conflates two
+// Orthogonal questions — WHICH EDITOR is open, and (for the Canvas editor only) WHICH VIEW of it.
+// The pane context bar labels them separately, so the first is answered here on its own.
 //
 // The mode → kind map itself is `commands/context.ts`'s `editorKindForMode`. It was duplicated
 // Here, and the copy that drifted is what let a settings document resolve into the canvas key
@@ -442,7 +440,8 @@ export function editorKindOf(tab: Tab): EditorKind {
 
 /**
  * Every editor kind this document supports, in the format's own mode order and deduplicated — the
- * dropdown's entries, so it can never contain a permanently dead one (§4.2).
+ * dropdown's entries, so it can never contain a permanently dead one
+ * (docs/studio/interface/tabs.md, "The pane context bar").
  *
  * `preview` contributes nothing: it is a Canvas VIEW, and the kind it would add is already there.
  *
@@ -482,7 +481,7 @@ export function modeForEditorKind(tab: Tab, kind: EditorKind): string | undefine
 // ─── There is no sub-document stack ───────────────────────────────────────────
 // A tab held one, and it was scaffolding for a navigation model the tab model replaced. `studio.md`
 // §14.3 justified it for exactly two cases and both moved: a function body opens in the Bottom
-// Dock's Logic tab (P8), and a `$map` template is a subtree of its parent document, selected in
+// Dock's Logic tab (§16.3), and a `$map` template is a subtree of its parent document, selected in
 // Place on the canvas rather than loaded as a document of its own. Everything with a file of its
 // Own — a component, a layout — opens a REAL TAB with an `openedFrom` relationship (§14.1–2):
 // {@link TabOrigin}, above, which nothing pops and nothing restores from.