@jxsuite/studio 5.3.0 → 5.4.0

package/src/surfaces/cf-account-picker.json

@@ -49,8 +49,8 @@
       "fontSize": "var(--jx-text-md)",
       "color": "var(--fg-dim)"
     },
-    "& [part=\"error\"]": {
-      "$description": "A commit the broker refused, said above the list the reader is still looking at. It is not an announcement of the same thing twice: the list survives a refusal, because listing again is not what would fix an account Cloudflare will not accept, so the reason has to sit beside the rows that are still on offer.",
+    "& [part=\"failure\"]": {
+      "$description": "A commit the broker refused, said above the list the reader is still looking at. It is not an announcement of the same thing twice: the list survives a refusal, because listing again is not what would fix an account Cloudflare will not accept, so the reason has to sit beside the rows that are still on offer. It is `failure` rather than `error` because every kit field draws a permanent, empty `[part=\"error\"]` of its own, and the kit is light DOM: a rule on that name here would reach any field this dialog ever holds.",
       "margin": "0",
       "fontSize": "var(--jx-text-md)",
       "color": "var(--danger)"
@@ -77,19 +77,22 @@
       "borderRadius": "var(--radius)"
     },
     "& [part=\"text\"]": {
-      "$description": "`min-width: 0` so a long account name ellipses inside the row instead of pushing its own button off the end of it.",
+      "$description": "`min-width: 0` lets the column shrink below its content, so the name and id reflow inside the row instead of pushing its own button off the end of it; what lets them reflow is their own `overflow-wrap`. Nothing here ellipsizes. Unlike Preferences › Accounts, the row does not wrap its button onto a line of its own: in an `sm` dialog the arithmetic (a 120px basis, the gap and a 105px button against a 236px row) would wrap every row at rest.",
       "display": "flex",
       "flexDirection": "column",
       "gap": "var(--jx-space-1)",
       "minWidth": "0"
     },
     "& [part=\"name\"]": {
-      "color": "var(--fg)"
+      "$description": "`overflow-wrap: anywhere` because Cloudflare names a new account after the email that opened it (`name@example.com's Account`), and an address has no break opportunity in it.",
+      "color": "var(--fg)",
+      "overflowWrap": "anywhere"
     },
     "& [part=\"detail\"]": {
-      "$description": "The account id under the name. Two Cloudflare accounts may carry the same name and the id is what is stored, so the row shows both rather than the half a reader would have to guess from.",
+      "$description": "The account id under the name. Two Cloudflare accounts may carry the same name and the id is what is stored, so the row shows both rather than the half a reader would have to guess from. `overflow-wrap: anywhere` because the id is 32 hex digits with no break opportunity: it measured 203px in a 119px column and ran under the row's own button. It reflows rather than ellipsizing, because the id is the half that tells two same-named accounts apart.",
       "fontSize": "var(--jx-text-sm)",
-      "color": "var(--fg-dim)"
+      "color": "var(--fg-dim)",
+      "overflowWrap": "anywhere"
     }
   },
   "children": [
@@ -188,7 +191,7 @@
                 {
                   "tagName": "div",
                   "attributes": {
-                    "part": "error-slot",
+                    "part": "failure-slot",
                     "role": "none"
                   },
                   "style": {
@@ -201,7 +204,7 @@
                     "true": {
                       "tagName": "p",
                       "attributes": {
-                        "part": "error"
+                        "part": "failure"
                       },
                       "textContent": "${state.failure}"
                     }

package/src/surfaces/commandbar.ts

@@ -1,6 +1,7 @@
 /// <reference lib="dom" />
 /**
- * The Command Bar — region ① of studio-ui-guidelines §6, rendered FROM the registry, as a document.
+ * The Command Bar — the `commandbar/*` placements of `studio-ui-guidelines.md` §12.1, rendered FROM
+ * the registry, as a document.
  *
  * `surfaces/commandbar.json` is the band; this module is its adapter. Every control in the band is
  * a command, so what the document is handed is a PROJECTION of the registry rather than a list of
@@ -8,24 +9,24 @@
  * `scripts/check-chrome-budget.ts`), `docks` is the three dock records with the shell's state
  * beside them, `layouts` is the project's own layout record, and the ⬢ Studio menu is
  * `forPlacement("commandbar/overflow")` opened on the `menu` surface. With no project open the same
- * document renders; the records' own `when` clauses empty it (§2 principle 4: enablement is a
- * predicate with a sentence, never a second template).
+ * document renders; the records' own `when` clauses empty it (§13.1: enablement is a predicate with
+ * a sentence, never a second template).
  *
  * What is decided here, and nowhere in the document:
  *
  * - {@link commandTooltip}: the title, plus its chord formatted for THIS platform by `keymap.format`,
  *   or plus the `requires` sentence when the record is off — so no control is ever permanently dead
  *   with no explanation.
- * - The **Command Center pill** (①a) is the app's address bar: `◈ project › document › selection`,
+ * - The **Command Center pill** is the app's address bar: `◈ project › document › selection`,
  *   right-aligned ⌘K, each segment opening the palette pre-scoped. It gives Studio a persistent
  *   project name — the desktop titlebar is `titleBarStyle:"hidden"`.
  * - The window controls, which are the one thing in the band that is not an action, and whose ORDER
  *   is the platform's.
  *
- * **Retired, with a name, a chord and a residue** (§2 principle 9): Open Project + New Project +
- * recents → the pill and `Project: Open Recent…`; `Manage` → `File: Browse Library`; `Publish` →
- * the `Publish:` family; `Sync Project` → Source Control. The five-mode switcher lives in the pane
- * context bar and is reachable as `View: Set Canvas Mode` in the palette.
+ * **Retired, with a name, a chord and a residue** (`studio-ui-guidelines.md` §12.2): Open Project +
+ * New Project + recents → the pill and `Project: Open Recent…`; `Manage` → `File: Browse Library`;
+ * `Publish` → the `Publish:` family; `Sync Project` → Source Control. The five-mode switcher lives
+ * in the pane context bar and is reachable as `View: Set Canvas Mode` in the palette.
  *
  * @docs studio/interface
  */
@@ -553,7 +554,7 @@ function windowControls(): WindowControls | undefined {
 
 /**
  * `◈ project › document › selection`: four facts about where you are, in non-collapsible chrome
- * (§4.4).
+ * (the Command Center pill, `docs/studio/interface.md`).
  */
 function projectSegments(tab: Tab | null): SegmentProjection[] {
   const segments: SegmentProjection[] = [
@@ -837,7 +838,7 @@ export function mount(rootEl: HTMLElement, _ctx: ToolbarCtx = {}): void {
         void tab.doc.dirty;
         void tab.doc.mode;
         // The whole SET, joined — a bare property read would not re-trigger when the selection
-        // Changes WITHIN the array, and §6.5's helpers always replace it but nothing enforces that.
+        // Changes WITHIN the array, and §6.7's helpers always replace it but nothing enforces that.
         void tab.session.selection.map((path) => path.join("/")).join("|");
         void tab.session.ui.canvasMode;
         // Open in Browser needs a value for every route param before it can resolve a page.

package/src/surfaces/convert-repeater.ts

@@ -185,8 +185,9 @@ export function openConvertRepeaterSurface(
     setName: (value: string) => {
       /* What the control holds, first and unconditionally. A binding only writes when the scope
          CHANGES, so a surface that refused a value without announcing the raw one would leave the
-         field showing text the scope does not have (§9.3). The refusal here is a sentence UNDER the
-         field rather than a rewrite of it, but the echo is what keeps that true of the next one. */
+         field showing text the scope does not have (`studio-ui-guidelines.md` §9.3). The refusal
+         here is a sentence UNDER the field rather than a rewrite of it, but the echo is what keeps
+         that true of the next one. */
       scope.newName = value;
       options.onName(value);
     },

package/src/surfaces/dialog.json

@@ -80,11 +80,17 @@
   },
   "style": {
     "& [part=\"message\"]": {
-      "margin": "0 0 var(--jx-space-3)"
+      "$description": "The one part of a dialog that is text rather than interface, so it opts back in to selection. The root sets `user-select: none` and `styles/tokens.json` restates it on every `dialog`, so the headline, the labels and the buttons around this sentence stay unselectable; a message is often the thing a reader copies into a search or a bug report.",
+      "margin": "0 0 var(--jx-space-3)",
+      "userSelect": "text"
     },
     "& [part=\"message\"]:last-child": {
       "margin": "0"
     },
+    "& [part=\"island\"] > p, & [part=\"island\"] > span, & [part=\"island\"] > strong, & [part=\"island\"] > em, & [part=\"island\"] > code": {
+      "$description": "The island's own prose is the message's other form — a body richer than a sentence, written straight into the island from a lit template (studio-ui-guidelines.md §9.4) — so it is selectable for the same reason `[part=\"message\"]` is. The opt-in stops at those children because the island is ALSO the mount point for a whole document: the Open Grid picker and Push Schema's plan put their surfaces here, and `user-select` inherits, so a rule on the island itself would hand selection to every heading, source row and button they draw, which is the interface the policy exists to keep unselectable. A mounted surface roots a `div`; a message writes paragraphs and text-level spans, so the two forms are told apart by the child that arrives.",
+      "userSelect": "text"
+    },
     "& [part=\"island\"]:empty": {
       "display": "none"
     },

package/src/surfaces/dialog.ts

@@ -16,8 +16,8 @@
  *
  * A message that is a lit template (three callers still pass one) is rendered by the caller into
  * the document's `[part="island"]` through {@link DialogSurfaceOptions.island}, which is the island
- * rule of studio-ui-guidelines §9.4: the decision stays with the host, the markup around it is the
- * document's.
+ * rule of `studio-ui-guidelines.md` §9.4: the decision stays with the host, the markup around it is
+ * the document's.
  *
  * @docs studio/interface
  */

package/src/surfaces/doc-header.json

@@ -1,28 +1,21 @@
 {
   "$schema": "https://jxsuite.com/schema/v1",
   "$id": "StudioDocHeader",
-  "$description": "The Document Header card (§3.2 ⑧) — the artefact's own header, drawn IN the stage, once per pane. A bar naming the collection and the page's route, a column of rows, the door to Search appearance and a disclosure listing the raw head tags. ONE row vocabulary: Title, the Layout picker and every schema-driven frontmatter field are the same `row`, discriminated by `kind`, because they differ in what they COMMIT rather than in what they look like — and what they commit is `panels/frontmatter-panel.ts`'s decision, reached by the row's `key`. Nothing here knows what a content collection is, which document it is drawing, or that a page has a route: the flow hands over rows whose every field is already a string and this draws them.",
+  "$description": "The Document Header card (`docs/studio/editing/frontmatter.md`) — the artefact's own header, drawn IN the stage, docked above Edit's page, once per pane. A bar naming the collection and the page's route, a column of rows, the door to Search appearance and a disclosure listing the raw head tags. ONE row vocabulary: Title, the Layout picker and every schema-driven frontmatter field are the same `row`, discriminated by `kind`, because they differ in what they COMMIT rather than in what they look like — and what they commit is `panels/frontmatter-panel.ts`'s decision, reached by the row's `key`. Nothing here knows what a content collection is, which document it is drawing, or that a page has a route: the flow hands over rows whose every field is already a string and this draws them.",
   "tagName": "section",
   "attributes": {
     "part": "card",
     "aria-label": "Document header",
-    "data-jx-region": "${state.region}",
-    "data-placement": "${state.placement}"
+    "data-jx-region": "${state.region}"
   },
   "style": {
-    "$description": "The twelve `.doc-header*` rules from `styles/canvas.css` plus the row vocabulary the card used to borrow from `styles/inspector.css` (`.style-row`, `.style-row-label`, `.set-dot`) and `styles/overlays.css` (`.media-picker`, `.media-picker-thumb`). The borrowed ones are TRANSCRIBED rather than shared: the card is a document now and a class it does not emit cannot style it, and the three lit panels that still draw a `.style-row` go on owning those rules until they convert. Every `--spectrum-font-size-*` reference is re-pointed at the kit's scale — a document mounted in a pane's stage is outside `<sp-theme>`, so each of them would silently have taken its hard-coded fallback and stopped following the theme. And the PLACEMENT is an attribute rather than an ancestor class: `.doc-header-host.pinned .doc-header` reached in from the stage's own host, which a scoped style block cannot answer, so the stage's two placements arrive as `data-placement` and the card keys on itself.",
+    "$description": "The twelve `.doc-header*` rules from `styles/canvas.css` plus the row vocabulary the card used to borrow from `styles/inspector.css` (`.style-row`, `.style-row-label`, `.set-dot`) and `styles/overlays.css` (`.media-picker`, `.media-picker-thumb`). The borrowed ones are TRANSCRIBED rather than shared: the card is a document now and a class it does not emit cannot style it, and the three lit panels that still draw a `.style-row` go on owning those rules until they convert. Every `--spectrum-font-size-*` reference is re-pointed at the kit's scale — a document mounted in a pane's stage is outside `<sp-theme>`, so each of them would silently have taken its hard-coded fallback and stopped following the theme. And the card has ONE shape, because it has one place: Edit docks it above the page's scroller as a band across the pane, so it is a band rather than a box. It keeps only the bottom edge that separates it from the page, because a box's border and radius would draw a card edge across a full-width strip. It used to have two placements, arriving as a `data-placement` the card keyed on, and the band look was the Design one; the attribute was read before the runtime had written it, so the band never drew.",
     "display": "flex",
     "flexDirection": "column",
     "padding": "8px 12px 10px",
     "background": "var(--bg-panel)",
-    "border": "1px solid var(--border)",
-    "borderRadius": "var(--radius)",
+    "borderBottom": "1px solid var(--border)",
     "fontFamily": "var(--jx-font-sans)",
-    "&[data-placement=\"pinned\"]": {
-      "$description": "Design draws the artboards under a pan/zoom transform, so the card is pinned above the surface at 1:1 rather than sitting in the document's own column. Pinned it is a band, not a box: it spans the stage, so the box's border and radius would draw a card edge across a full-width strip.",
-      "borderWidth": "0 0 1px",
-      "borderRadius": "0"
-    },
     "& [part=\"bar\"]": {
       "display": "flex",
       "alignItems": "baseline",
@@ -48,7 +41,7 @@
       "gap": "2px"
     },
     "& [part=\"row\"]": {
-      "$description": "§4.1's standard form row, stacked: the label sits above a control that takes the whole width. `min-width: 0` is what keeps it honest at a narrow stage (§4.6) — a field refuses to shrink below its own min-content without it, and the card is drawn inside a pane that can be half a window wide.",
+      "$description": "studio-ui-guidelines.md §4.1's standard form row, stacked: the label sits above a control that takes the whole width. `min-width: 0` is what keeps it honest at a narrow stage (studio-ui-guidelines.md §4.6) — a field refuses to shrink below its own min-content without it, and the card is drawn inside a pane that can be half a window wide.",
       "display": "flex",
       "flexDirection": "column",
       "alignItems": "stretch",
@@ -64,7 +57,7 @@
       "color": "var(--fg-dim)"
     },
     "& [part=\"chip\"]": {
-      "$description": "§4.2's set dot: a 6px accent dot, drawn only where the value is set here, that clears the value when it is pressed. It is a real `button` — it is pressable, and it is the row's only keyboard route to clearing — stripped of the chrome a button brings with it so the row still reads as a label with a dot beside it.",
+      "$description": "studio-ui-guidelines.md §4.2's set dot: a 6px accent dot, drawn only where the value is set here, that clears the value when it is pressed. It is a real `button` — it is pressable, and it is the row's only keyboard route to clearing — stripped of the chrome a button brings with it so the row still reads as a label with a dot beside it.",
       "width": "6px",
       "height": "6px",
       "padding": "0",

package/src/surfaces/doc-header.ts

@@ -54,7 +54,10 @@ export interface DocHeaderRow extends Record<string, unknown> {
   label: string;
   /** Which control the row draws. */
   kind: "text" | "number" | "boolean" | "select" | "media";
-  /** Whether the value is set on this document — §4.2's dot, and the row's only clear affordance. */
+  /**
+   * Whether the value is set on this document — studio-ui-guidelines.md §4.2's dot, and the row's
+   * only clear affordance.
+   */
   isSet: boolean;
   /** The dot's accessible name and tooltip, e.g. `Clear title`. */
   clearLabel: string;
@@ -90,8 +93,6 @@ export interface DocHeaderRawEntry extends Record<string, unknown> {
 export interface DocHeaderView {
   /** The region id the card stamps on itself — `pane.<id>/frontmatter`. */
   region: string;
-  /** `in-column` in Edit, `pinned` in Design. The stage decides; the card only draws it. */
-  placement: "in-column" | "pinned";
   /** The matched collection's name, or the word `Document` when it belongs to none. */
   collection: string;
   /** This page's route. */
@@ -150,7 +151,6 @@ interface DocHeaderScope extends Record<string, unknown>, DocHeaderView, DocHead
 /** Write a whole view into the scope. Assignment only — the mount is never rebuilt for a repaint. */
 function project(scope: DocHeaderScope, view: DocHeaderView): void {
   scope.region = view.region;
-  scope.placement = view.placement;
   scope.collection = view.collection;
   scope.route = view.route;
   scope.hasRoute = view.hasRoute;
@@ -180,7 +180,6 @@ export function mountDocHeaderSurface(
     ...actions,
     collection: "Document",
     hasRoute: false,
-    placement: "in-column",
     rawEntries: [],
     rawOpen: false,
     rawState: "empty",

package/src/surfaces/entry-editor.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://jxsuite.com/schema/v1",
   "$id": "StudioEntryEditor",
-  "$description": "The Entry editor (§7.4) — one content entry's fields, in a pane, as a Jx document over the kit. The adapter (`surfaces/entry-editor.ts`) hands in a projection; `content/entry-editor.ts` decides everything in it — which collection the file belongs to, which record its fields live in, which required keys are absent and what a draft flag commits into. The FORM is an island: a schema is `ui/schema-form.ts`'s subject, so this document renders an empty `fields` node and the flow places the element that engine hands back (studio-ui-guidelines.md §9.3, §9.4). That is the whole of the difference between this and the card the lit version drew, and it is why the engine converting in batch 7 is what unblocked this one.",
+  "$description": "The Entry editor (site-architecture.md §7.4) — one content entry's fields, in a pane, as a Jx document over the kit. The adapter (`surfaces/entry-editor.ts`) hands in a projection; `content/entry-editor.ts` decides everything in it — which collection the file belongs to, which record its fields live in, which required keys are absent and what a draft flag commits into. The FORM is an island: a schema is `ui/schema-form.ts`'s subject, so this document renders an empty `fields` node and the flow places the element that engine hands back (studio-ui-guidelines.md §9.3, §9.4). That is the whole of the difference between this and the card the lit version drew, and it is why the engine converting in batch 7 is what unblocked this one.",
   "tagName": "div",
   "attributes": {
     "part": "entry",

package/src/surfaces/entry-editor.ts

@@ -154,7 +154,8 @@ export function mountEntryEditorSurface(
   let disposed = false;
   /* Nothing is called on an element here, so the mount is all there is to wait for: the island
      announces itself through `onNodeCreated` as it is created, which is one `connectedCallback`
-     earlier than awaiting the element would be (§1.1, "await the element"). */
+     earlier than awaiting the element would be (studio-ui-guidelines.md §1.1, "await the
+     element"). */
   const ready = mountSurface("entry-editor", scope, host, {
     onNodeCreated: (element, _path, def) => {
       if (element instanceof HTMLElement && partOf(def) === "fields") {

package/src/surfaces/expression-editor.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://jxsuite.com/schema/v1",
   "$id": "StudioExpressionEditor",
-  "$description": "The expression editor (spec §19.9): a `$expression` node edited as STRUCTURE — an operator, the operands that operator needs, and the live value of each. The rows arrive FLAT. An expression nests to any depth (an operand may be another expression, an aggregate's per-item body is one, and either may hold more of both) while a document's one repeater is `$prototype: \"Array\"` over a list, so `ui/expression-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 statement tree and the Data panel's value tree. Six kinds of row come out of that walk: the CHIP strip that summarises the whole pipeline, the preview's ERROR line, the OPERATOR row, an OPERAND row (the workhorse, which carries the value ladder and every literal control), a section LABEL, and an ACTION that grows the node. Five surfaces draw this — the Inspector's Content and Logic tabs, the Navigator's State panel, the statement editor and the Logic dock — and none of them is named here: each host has already said where it is, so this document stamps no region of its own.",
+  "$description": "The expression editor (spec.md §19.9): a `$expression` node edited as STRUCTURE — an operator, the operands that operator needs, and the live value of each. The rows arrive FLAT. An expression nests to any depth (an operand may be another expression, an aggregate's per-item body is one, and either may hold more of both) while a document's one repeater is `$prototype: \"Array\"` over a list, so `ui/expression-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 statement tree and the Data panel's value tree. Six kinds of row come out of that walk: the CHIP strip that summarises the whole pipeline, the preview's ERROR line, the OPERATOR row, an OPERAND row (the workhorse, which carries the value ladder and every literal control), a section LABEL, and an ACTION that grows the node. Five surfaces draw this — the Inspector's Content and Logic tabs, the Navigator's State panel, the statement editor and the Logic dock — and none of them is named here: each host has already said where it is, so this document stamps no region of its own.",
   "tagName": "div",
   "attributes": {
     "part": "expression"
@@ -58,7 +58,7 @@
       "textOverflow": "ellipsis"
     },
     "& [part=\"row\"]": {
-      "$description": "§4.1's standard form row, stacked, with its own indent. `display: flex` rather than `block` because an operand row carries a leading cell (an argument's name, a case's key) beside the field.",
+      "$description": "studio-ui-guidelines.md §4.1's standard form row, stacked, with its own indent. `display: flex` rather than `block` because an operand row carries a leading cell (an argument's name, a case's key) beside the field.",
       "boxSizing": "border-box",
       "display": "flex",
       "alignItems": "flex-start",
@@ -107,7 +107,7 @@
       "fontSize": "var(--jx-text-xs)"
     },
     "& [part=\"badge\"]": {
-      "$description": "The live value (spec §19.9). A resolved formula is arbitrary text — an object, a URL, a paragraph — so it ellipsizes inside the line it annotates and never sets that line's width.",
+      "$description": "The live value (spec.md §19.9). A resolved formula is arbitrary text — an object, a URL, a paragraph — so it ellipsizes inside the line it annotates and never sets that line's width.",
       "flex": "0 1 auto",
       "minWidth": "0",
       "maxWidth": "120px",
@@ -123,7 +123,7 @@
       "textOverflow": "ellipsis"
     },
     "& [part=\"preview-error\"]": {
-      "$description": "§7.1's inline tier: not a toast and not a problem record, because it is a property of the value currently in the editor and lives exactly as long as that value does.",
+      "$description": "§16.1's inline tier: not a toast and not a problem record, because it is a property of the value currently in the editor and lives exactly as long as that value does.",
       "margin": "0",
       "padding": "2px 0",
       "minWidth": "0",
@@ -529,7 +529,7 @@
                     },
                     "children": [
                       {
-                        "$description": "The value ladder (§6.3), in the one vocabulary `ui/value-source.ts` owns. It is absent where the position admits a single shape — an assignment target, a `call`'s callee — because a picker with one entry is a control that asks a question with one answer.",
+                        "$description": "The value ladder (§6.6), in the one vocabulary `ui/value-source.ts` owns. It is absent where the position admits a single shape — an assignment target, a `call`'s callee — because a picker with one entry is a control that asks a question with one answer.",
                         "tagName": "span",
                         "attributes": {
                           "part": "source-slot",

package/src/surfaces/files-panel.json

@@ -17,7 +17,7 @@
     "fontSize": "var(--jx-text-md)",
     "color": "var(--fg)",
     "& [part=\"empty\"]": {
-      "$description": "The two states that are not a tree. They are two states and not one sentence: a window with no project at all and a monorepo root that has not been pointed at a site are different situations, and only the second has anything to offer (§11).",
+      "$description": "The two states that are not a tree. They are two states and not one sentence: a window with no project at all and a monorepo root that has not been pointed at a site are different situations, and only the second has anything to offer (studio-ui-guidelines.md §11).",
       "padding": "var(--jx-space-6)",
       "textAlign": "center",
       "color": "var(--fg-dim)",
@@ -166,7 +166,7 @@
                     "value": []
                   }
                 ],
-                "description": "The declared `project.open` command, run through the registry — not a second opener of this surface's own. It is the one the chord, the palette and the status bar's PROJECT field already run, so a window that opens a project from here reports the outcome the same way they do (§12.5)."
+                "description": "The declared `project.open` command, run through the registry — not a second opener of this surface's own. It is the one the chord, the palette and the status bar's PROJECT field already run, so a window that opens a project from here reports the outcome the same way they do (studio-ui-guidelines.md §12.5)."
               },
               "children": [
                 {
@@ -218,12 +218,13 @@
               },
               "children": [
                 {
+                  "$description": "A row of quiet tools, so NOT compact. A compact group draws every member's frame and fill whatever its quiet says, which is the segmented look a choice wants and not the borderless one a toolbar wants; Spectrum's group here was `compact quiet`, a combination the kit spells as compact=false with its members' default quiet.",
                   "tagName": "jx-action-group",
                   "attributes": {
                     "part": "toolbar-actions"
                   },
                   "$props": {
-                    "compact": true,
+                    "compact": false,
                     "label": "File tree actions"
                   },
                   "children": [

package/src/surfaces/files-panel.ts

@@ -230,7 +230,7 @@ function mappedRow(state: JxScope | undefined): FileRowView | null {
  *
  * Nothing is called on the elements, so the mount is all this has to wait for: the two islands
  * announce themselves through `onNodeCreated` as their nodes are created, which is one
- * `connectedCallback` EARLIER than awaiting the element would be (guidelines §1.1).
+ * `connectedCallback` EARLIER than awaiting the element would be (studio-ui-guidelines.md §1.1).
  */
 export function mountFilesPanelSurface(
   container: HTMLElement,

package/src/surfaces/formula-palette.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://jxsuite.com/schema/v1",
   "$id": "StudioFormulaPalette",
-  "$description": "The formula palette (spec §19.9): a search field over the formula catalog, its results grouped by the catalog's own group order, and one pick that hands an entry back to whoever opened it. The same shape as `palette.json` — a scrim, a framed panel, a borderless field, a listbox — because it is the same gesture over a different corpus, and the two used to share a stylesheet by sharing its class names. `groups` is the filtered catalog already grouped; `activeId` is the highlight, and it is ONE string — the id the field points `aria-activedescendant` at and the id the listbox is handed as `active` — kept apart from the rows so a key moves it without the list reconciling, which is why every row carries the FLAT index it would otherwise have to be asked for. Panel position is the caller's: centred under the top edge by default, and pinned under an anchor control when one was named, which is the only thing about this surface a document cannot decide for itself — it arrives as `anchorLeft`/`anchorTop`, two numbers the `style` object below binds, because a style declaration may read state like any other value (spec §9.1).",
+  "$description": "The formula palette (spec.md §19.9): a search field over the formula catalog, its results grouped by the catalog's own group order, and one pick that hands an entry back to whoever opened it. The same shape as `palette.json` — a scrim, a framed panel, a borderless field, a listbox — because it is the same gesture over a different corpus, and the two used to share a stylesheet by sharing its class names. `groups` is the filtered catalog already grouped; `activeId` is the highlight, and it is ONE string — the id the field points `aria-activedescendant` at and the id the listbox is handed as `active` — kept apart from the rows so a key moves it without the list reconciling, which is why every row carries the FLAT index it would otherwise have to be asked for. Panel position is the caller's: centred under the top edge by default, and pinned under an anchor control when one was named, which is the only thing about this surface a document cannot decide for itself — it arrives as `anchorLeft`/`anchorTop`, two numbers the `style` object below binds, because a style declaration may read state like any other value (spec.md §9.1).",
   "tagName": "div",
   "attributes": {
     "part": "palette"
@@ -39,7 +39,7 @@
       "overflow": "hidden"
     },
     "& [part=\"panel\"][data-anchored]": {
-      "$description": "Opened from a control rather than from a chord: the panel hangs under that control instead of sitting under the top edge. The two custom properties are the only measured numbers in the surface — a rect belongs to the moment it was taken, so the adapter measures it once per open and this document binds the result. They used to travel as a `style` ATTRIBUTE the adapter assembled into one string, on the belief that a document cannot bind a style declaration to state; it can, and always could. They are declared at the top of this object rather than here because a reactive custom property in a rule targeting the element ITSELF is written inline under the author's own name (spec §9.1), and the panel then reads them by inheritance — the root is `display: contents`, so nothing sits between the two.",
+      "$description": "Opened from a control rather than from a chord: the panel hangs under that control instead of sitting under the top edge. The two custom properties are the only measured numbers in the surface — a rect belongs to the moment it was taken, so the adapter measures it once per open and this document binds the result. They used to travel as a `style` ATTRIBUTE the adapter assembled into one string, on the belief that a document cannot bind a style declaration to state; it can, and always could. They are declared at the top of this object rather than here because a reactive custom property in a rule targeting the element ITSELF is written inline under the author's own name (spec.md §9.1), and the panel then reads them by inheritance — the root is `display: contents`, so nothing sits between the two.",
       "position": "fixed",
       "left": "var(--formula-palette-left)",
       "top": "var(--formula-palette-top)",

package/src/surfaces/formula-palette.ts

@@ -1,6 +1,6 @@
 /// <reference lib="dom" />
 /**
- * The formula palette (spec §19.9): a search over the formula catalog, mounted into the popover
+ * The formula palette (spec.md §19.9): a search over the formula catalog, mounted into the popover
  * layer as a Jx document.
  *
  * `formula-palette.json` is the markup, the ARIA and the style; this is the decisions — which