@jxsuite/studio 5.2.0 → 5.4.0

package/src/surfaces/logic-panel.ts

@@ -42,9 +42,8 @@ export type LogicFieldKind = "control" | "text" | "select";
 /**
  * A bindable value as a first-class field row: a collection, a filter, a sort key, a `$switch`.
  *
- * These were the last second-class rows in the inspector (§12 P5 item 6) — a bare label and a
- * widget, with no set dot, no clear affordance and no error slot. Every field the tab has is one of
- * these now.
+ * These were the last second-class rows in the inspector — a bare label and a widget, with no set
+ * dot, no clear affordance and no error slot. Every field the tab has is one of these now.
  */
 export interface LogicFieldView {
   /** The slot's field key: the repeater's key, and what every callback names. */
@@ -161,7 +160,10 @@ export interface LogicView {
   /** `empty` or `ready` — no document, no selection and a stale one are all the first. */
   state: string;
   emptyMessage: string;
-  /** What the reader can do about it. An empty state that teaches nothing offers none (§11.1). */
+  /**
+   * What the reader can do about it. An empty state that teaches nothing offers none
+   * (studio-ui-guidelines.md §11.1).
+   */
   emptyActions: LogicEmptyAction[];
   hasEmptyActions: boolean;
 

package/src/surfaces/logic-workspace.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://jxsuite.com/schema/v1",
   "$id": "StudioLogicWorkspace",
-  "$description": "⑪ · Logic — the Bottom dock tab where a formula and a function body are edited BESIDE the page they compute. One tab, two surfaces, one header: `panels/formula-workspace.ts` decides which of them is open (a `$expression` or a Monaco body), what it is called and what its verbs are, and this draws both. The chip pipeline is a projection of `ui/formula-chips.ts`'s model — the expression tree read left to right — and a chip click reports its key back; nothing here unrolls a tree, reads a document or evaluates anything. Three ISLANDS, each an empty host this document draws and the flow fills (studio-ui-guidelines.md §9.4): `[part=\"code-host\"]` takes Monaco, `[part=\"editor-host\"]` takes the expression editor, which is a lit surface of its own and another conversion's to move, and one `[part=\"tree-host\"]` per data-rail entry takes the value tree, which is a mounted document of its own (`surfaces/panel-data.json`). The rail's trees had been empty since that tree became a document, because the lit takeover rendered a host nothing ever filled; announcing them is what fills them.",
+  "$description": "Logic — the Bottom dock tab where a formula and a function body are edited BESIDE the page they compute. One tab, two surfaces, one header: `panels/formula-workspace.ts` decides which of them is open (a `$expression` or a Monaco body), what it is called and what its verbs are, and this draws both. The chip pipeline is a projection of `ui/formula-chips.ts`'s model — the expression tree read left to right — and a chip click reports its key back; nothing here unrolls a tree, reads a document or evaluates anything. Three ISLANDS, each an empty host this document draws and the flow fills (studio-ui-guidelines.md §9.4): `[part=\"code-host\"]` takes Monaco, `[part=\"editor-host\"]` takes the expression editor, which is a lit surface of its own and another conversion's to move, and one `[part=\"tree-host\"]` per data-rail entry takes the value tree, which is a mounted document of its own (`surfaces/panel-data.json`). The rail's trees had been empty since that tree became a document, because the lit takeover rendered a host nothing ever filled; announcing them is what fills them.",
   "tagName": "div",
   "attributes": {
     "part": "workspace"
@@ -94,7 +94,7 @@
       "textOverflow": "ellipsis"
     },
     "& [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 chip it annotates and never sets the chip'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 chip it annotates and never sets the chip's width.",
       "flex": "0 1 auto",
       "minWidth": "0",
       "maxWidth": "120px",

package/src/surfaces/logic-workspace.ts

@@ -1,6 +1,6 @@
 /// <reference lib="dom" />
 /**
- * ⑪ · Logic — the Bottom dock tab, as a mounted document.
+ * Logic — the Bottom dock tab, as a mounted document.
  *
  * This is the adapter. `panels/formula-workspace.ts` is the flow — it reads which of the two
  * surfaces is open, resolves the expression at that document position, keeps the chip selection,
@@ -63,7 +63,7 @@ export interface LogicScopeEntryView {
 export interface LogicWorkspaceView {
   /** `empty` (nothing open in the tab) or `ready`. */
   state: string;
-  /** What the tab is for, said when nothing is open in it (§11.1). */
+  /** What the tab is for, said when nothing is open in it (studio-ui-guidelines.md §11.1). */
   emptyMessage: string;
   /** Which body the ready state draws: `formula`, `code`, or `missing`. */
   surface: string;

package/src/surfaces/media-browser.ts

@@ -10,9 +10,9 @@
  * **The platform owns dismissal.** The root is a `jx-popover`, so Escape, light dismissal, the top
  * layer and focus back to the invoker are its contract rather than three document listeners and a
  * `z-index` chosen from the layer the anchor happened to be in. That is not only tidier: an overlay
- * drawn into a layer div paints UNDERNEATH a modal `<dialog>` and is inert besides (`specs/ui.md`
- * §7), which is the whole reason `panels/seo-modal.ts` had to fork its own Browse onto the kit
- * menu, and a top-layer popover has no such problem.
+ * drawn into a layer div paints UNDERNEATH a modal `<dialog>` and is inert besides (ui.md §6),
+ * which is the whole reason `panels/seo-modal.ts` had to fork its own Browse onto the kit menu, and
+ * a top-layer popover has no such problem.
  *
  * **The filter takes the caret, and the adapter is what puts it there.** A `jx-popover` moves focus
  * into itself but has no opinion about which control; the panel is a search box over a list, so the

package/src/surfaces/media-pane.ts

@@ -166,7 +166,8 @@ export function mountMediaSurface(
   let disposed = false;
   /* Nothing is called on an element here, so the mount is all there is to wait for: the DOCUMENT is
      what this surface renders, and the kit's Copy button settles its own template one
-     `connectedCallback` later without anybody asking it to (§1.1, "await the element"). */
+     `connectedCallback` later without anybody asking it to (studio-ui-guidelines.md §1.1, "await
+     the element"). */
   const ready = mountSurface("media-pane", scope, host).then((surface) => {
     if (disposed) {
       surface.dispose();

package/src/surfaces/menu.ts

@@ -1,11 +1,11 @@
 /**
  * The menu surface: a `jx-menu` of command-record projections, mounted into a popover layer slot.
  *
- * This is the first Studio surface rendered as a Jx document (specs/studio-ui-guidelines.md §6,
- * §9.3): `menu.json` is the markup, ARIA and style, and this adapter is the decisions — which
- * records, what they print, where the panel opens, what runs on select. The kit owns the menu
- * contract (roving focus, typeahead, submenus, light dismissal, Escape) through the platform's own
- * popover, so nothing here binds a key or a document listener.
+ * This is the first Studio surface rendered as a Jx document (studio-ui-guidelines.md §6, §9.3):
+ * `menu.json` is the markup, ARIA and style, and this adapter is the decisions — which records,
+ * what they print, where the panel opens, what runs on select. The kit owns the menu contract
+ * (roving focus, typeahead, submenus, light dismissal, Escape) through the platform's own popover,
+ * so nothing here binds a key or a document listener.
  *
  * Every menu opens in a `getLayerSlot("popover", id)` slot, which is what carries the
  * `overlay.menu:<id>` region the screenshot pipeline addresses, and is torn down when the popover

package/src/surfaces/new-project.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://jxsuite.com/schema/v1",
   "$id": "StudioNewProject",
-  "$description": "The New Project wizard: two steps in one dialog. Step 1 asks where the site comes from — a starter gallery that ends with one Start from scratch card, an Import of a site that already exists, or an Agent brief — and step 2 asks what it is called and where it is written. A `jx-dialog`, so the platform owns modality, Escape, focus restoration and the backdrop, which is what retired the fixed `.new-project-modal` card, the `<sp-underlay>` beside it, the `z-index: 1000` that card needed to climb back out from under its own scrim, and the hand-drawn header with its own close button. The footer is the dialog's too: Cancel, Back and the primary are `cancelLabel`, `secondaryLabel` and `confirmLabel`, so the wizard says which answers exist by naming them rather than by drawing three buttons per step. Nothing here knows what a starter is, which platform writes to a repository rather than a folder, what makes an AI gate open, or how a breakpoint policy is spelled — `new-project/new-project-modal.ts` keeps the flow, `new-project/import-tab.ts` the brief and `new-project/location-fields.ts` the destination, and all three hand over strings, flags and one discriminant per branch. The three AI controllers are islands: their own mounted documents, placed by the adapter into boxes this document renders empty (§9.4).",
+  "$description": "The New Project wizard: two steps in one dialog. Step 1 asks where the site comes from — a starter gallery that ends with one Start from scratch card, an Import of a site that already exists, or an Agent brief — and step 2 asks what it is called and where it is written. A `jx-dialog`, so the platform owns modality, Escape, focus restoration and the backdrop, which is what retired the fixed `.new-project-modal` card, the `<sp-underlay>` beside it, the `z-index: 1000` that card needed to climb back out from under its own scrim, and the hand-drawn header with its own close button. The footer is the dialog's too: Cancel, Back and the primary are `cancelLabel`, `secondaryLabel` and `confirmLabel`, so the wizard says which answers exist by naming them rather than by drawing three buttons per step. Nothing here knows what a starter is, which platform writes to a repository rather than a folder, what makes an AI gate open, or how a breakpoint policy is spelled — `new-project/new-project-modal.ts` keeps the flow, `new-project/import-tab.ts` the brief and `new-project/location-fields.ts` the destination, and all three hand over strings, flags and one discriminant per branch. The three AI controllers are islands: their own mounted documents, placed by the adapter into boxes this document renders empty (studio-ui-guidelines.md §9.4).",
   "tagName": "jx-dialog",
   "$props": {
     "headline": {

package/src/surfaces/palette.json

@@ -17,6 +17,9 @@
       "paddingTop": "60px",
       "background": "rgba(0, 0, 0, 0.4)"
     },
+    "& [part=\"overlay\"][hidden]": {
+      "display": "none"
+    },
     "& [part=\"panel\"]": {
       "width": "560px",
       "maxWidth": "calc(100vw - 32px)",
@@ -133,14 +136,12 @@
       "color": "var(--jx-fg-dim)"
     }
   },
-  "$switch": {
-    "$ref": "#/state/open"
-  },
-  "cases": {
-    "true": {
+  "children": [
+    {
       "tagName": "div",
       "attributes": {
-        "part": "overlay"
+        "part": "overlay",
+        "hidden": "${state.open ? null : ''}"
       },
       "onclick": {
         "$prototype": "Function",
@@ -531,5 +532,5 @@
         }
       ]
     }
-  }
+  ]
 }

package/src/surfaces/pane-context.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://jxsuite.com/schema/v1",
   "$id": "StudioPaneContext",
-  "$description": "The pane's own chrome — region ⑦ (the context bar) and region ⑩ (the floating zoom pod), one mount per pane. It replaces `#tab-bar`, a 28px band styled identically to the tab strip above it that held five unrelated axes with no labels on any of them; the three axes here each say what they are, and the label is what stops the band re-accreting into an anonymous strip of chips. `panels/pane-context.ts` keeps every decision — which editor kinds a document declares, which canvas views it has, whether preview is a flag over them, what a lens may not write, which pane's stage a zoom verb lands on, and what a route param's candidate values are — and hands this document one projection of words, booleans and keyed rows. The bar and the banner share `[part=\"band\"]` so the adapter can MEASURE what the stage must clear: a banner's height is its wrapped text, and only layout knows how many lines that is.",
+  "$description": "The pane's own chrome — the pane context bar and the floating zoom pod, one mount per pane. It replaces `#tab-bar`, a 28px band styled identically to the tab strip above it that held five unrelated axes with no labels on any of them; the three axes here each say what they are, and the label is what stops the band re-accreting into an anonymous strip of chips. `panels/pane-context.ts` keeps every decision — which editor kinds a document declares, which canvas views it has, whether preview is a flag over them, what a lens may not write, which pane's stage a zoom verb lands on, and what a route param's candidate values are — and hands this document one projection of words, booleans and keyed rows. The bar and the banner share `[part=\"band\"]` so the adapter can MEASURE what the stage must clear: a banner's height is its wrapped text, and only layout knows how many lines that is.",
   "tagName": "div",
   "attributes": {
     "part": "chrome"
@@ -59,10 +59,14 @@
       "flexShrink": "0"
     },
     "& [part=\"preview-toggle\"]": {
-      "$description": "Not a third radio, and it must not read as one: it says the canvas is inert. The margin separates the two axes the eye is being asked to read as separate; the accent fill is the kit's `emphasized`, which is what deleted the four Spectrum custom properties this rule used to carry.",
+      "$description": "Not a third radio, and it must not read as one: it says the canvas is inert. The margin separates the two axes the eye is being asked to read as separate; the accent fill is the kit's `emphasized`, which is what deleted the four Spectrum custom properties this rule used to carry. The toggle is `quiet: false`, so it rests as a framed button of its own beside the framed View switch, as the Spectrum button did; quiet, it read as a fourth loose word once the switch beside it drew its frame.",
       "flexShrink": "0",
       "marginInlineStart": "6px"
     },
+    "& jx-action-button[part=\"preview-toggle\"] > [part=\"control\"]": {
+      "$description": "The text padding the View switch's segments get from their group, which this toggle stands outside: the small size's 2px is for a glyph, and 6px is what the group gives a text segment. (0,3,1) outranks the kit's small padding at (0,3,0).",
+      "paddingInline": "6px"
+    },
     "& [part=\"context-trigger\"]": {
       "fontVariantNumeric": "tabular-nums"
     },
@@ -88,29 +92,47 @@
       "fontSize": "var(--jx-text-md)"
     },
     "& [part=\"pod\"]": {
-      "$description": "Bottom-right of the pane, over the stage — a viewport control, which is not a document axis and so never belonged in a band beside one.",
+      "$description": "Bottom-right of the pane, over the stage — a viewport control, which is not a document axis and so never belonged in a band beside one. It is a ROW of two controls and draws no box of its own: a 1px border and a 6px radius round 2px/4px of padding framed the zoom group's own frame and the Fit select's own frame, a frame inside a frame and busier than any other group in the chrome. Each control draws itself and takes `--pod-lift` to stand off the document under it, which is what the pod's fill and border used to do for both at once, and the gap between them says they are two controls rather than one strip with a seam. The right inset ADDS `--stage-scrollbar-w` because the chrome layer spans the whole cell, scrollbar gutter included: a fixed 12px put the pod 3px into Edit's 15px track, painting over it and swallowing its clicks. CSS cannot measure a scrollbar and this document cannot see the scroller, so `canvas/stage-scrollbar.ts` measures the stage's own and writes the width on the cell, where this reads it by cascade. It is 0 wherever the stage does not scroll or the scrollbar is an overlay. Physical right on purpose: Studio's chrome is never mirrored.",
+      "--pod-lift": "0 2px 8px rgb(0 0 0 / 25%)",
       "alignSelf": "flex-end",
+      "display": "flex",
+      "alignItems": "center",
+      "gap": "var(--jx-space-2)",
       "pointerEvents": "auto",
-      "margin": "0 var(--jx-space-4) var(--jx-space-4) 0",
-      "padding": "var(--jx-space-1) var(--jx-space-2)",
-      "border": "1px solid var(--border)",
-      "borderRadius": "var(--jx-radius-md)",
-      "background": "var(--bg)",
-      "boxShadow": "0 2px 8px rgb(0 0 0 / 25%)"
+      "margin": "0 calc(var(--jx-space-4) + var(--stage-scrollbar-w, 0px)) var(--jx-space-4) 0"
+    },
+    "& [part=\"zoom-group\"]": {
+      "$description": "The segmented frame floats on its own now that the pod draws no box around it. The radius is the one the first and last segments already draw, so the shadow follows the shape of the strip instead of a rectangle around it — the host's box IS that strip, since the group has no padding and each member's -1px pulls its own host in by a pixel.",
+      "borderRadius": "var(--jx-radius-sm)",
+      "boxShadow": "var(--pod-lift)"
+    },
+    "& [part=\"pod\"] > [part=\"zoom-group\"][data-compact] > jx-action-button > [part=\"control\"]": {
+      "$description": "One resting ink across the pod. A compact group rests its unselected members on `--jx-fg-dim` and brightens the chosen one, which is how a segmented control says which segment is on — and nothing in this pod is ever chosen: the three are a viewport verb, a readout and a verb. So the dim ink said nothing here and made `100%` read as disabled beside the Fit select's value, which is the same kind of readout at `--jx-fg`. (0,5,1) over the group's own resting rule at (0,4,1); the group's hover is (0,6,1) and still wins, which now leaves it only the wash.",
+      "color": "var(--fg)"
     },
     "& [part=\"zoom-label\"]": {
-      "minWidth": "48px",
-      "fontFamily": "var(--font-mono)"
+      "$description": "A floor under the percentage, so the pod does not shift as the value changes length. The width is the host's and the face is the control's, below: the control sets its own font and sits inside the host at its content width, so this rule used to carry a mono face nothing inherited and to open a 6px hole in the segmented frame before the `+` segment (measured: a 48px host round a 41.8px control, drawn in Inter).",
+      "minWidth": "48px"
+    },
+    "& [part=\"zoom-label\"] > [part=\"control\"]": {
+      "$description": "The control fills its 48px host, closing the frame, and draws the percentage in the mono face with tabular digits so a changing value does not jitter. (0,3,0) outranks the kit control's own face at (0,2,0).",
+      "flex": "1",
+      "fontFamily": "var(--font-mono)",
+      "fontVariantNumeric": "tabular-nums"
     },
     "& [part=\"fit\"]": {
       "maxWidth": "120px"
     },
+    "& [part=\"fit\"] > [part=\"control\"]": {
+      "$description": "The pod's second control lifts off the document the way the first does, on the frame the kit's select already draws. On the control rather than the host, because the host is a column whose error region and help slot are the select's neighbours: the shadow has to follow the box that is painted.",
+      "boxShadow": "var(--pod-lift)"
+    },
     "& [part=\"popover\"]": {
       "$description": "Both panels take the pointer that `.pane-chrome` withholds. A popover is in the top layer while it shows, which changes where it PAINTS and not where it is in the tree, so it inherits `pointer-events: none` from the chrome layer exactly as the band does.",
       "pointerEvents": "auto"
     },
     "& [part=\"ctx\"]": {
-      "$description": "One column of labelled groups over a footer that leaves for the definition site. This control only SELECTS (§2 principle 5) — nothing in it defines a breakpoint, a scheme or a feature query.",
+      "$description": "One column of labelled groups over a footer that leaves for the definition site. This control only SELECTS; the definitions live in Project Settings › Contexts (§6.2), and nothing in it defines a breakpoint, a scheme or a feature query.",
       "display": "flex",
       "flexDirection": "column",
       "gap": "10px",
@@ -129,11 +151,15 @@
       "letterSpacing": "0.04em",
       "color": "var(--fg-dim)"
     },
-    "& [part=\"sizes\"]": {
-      "flexWrap": "wrap"
+    "& [part=\"sizes\"], & [part=\"features\"]": {
+      "$description": "The two groups that WRAP, and the reason neither is a segmented control. A breakpoint or feature list is as long as the project makes it and this popover is a 240–340px column, so both fold onto a second line in any project with more than a few; a compact group cannot draw that — its seam is written in tree order, no selector can find the ends of a flex line, and it therefore refuses to wrap and would overflow the column instead (ui.md §5.4). Chips instead: each member draws its own rounded frame (`quiet: false`, since the group no longer frames it) and the chosen one takes the accent edge below. The gap is --jx-space-2 rather than the group's own 2px, which puts every small chip's hit area at the 24px floor on both axes instead of the 22px two overlapping extensions leave (§4.3).",
+      "flexWrap": "wrap",
+      "gap": "var(--jx-space-2)"
     },
-    "& [part=\"features\"]": {
-      "flexWrap": "wrap"
+    "& [part=\"sizes-item\"][data-selected] > [part=\"control\"], & [part=\"features-item\"][data-selected] > [part=\"control\"]": {
+      "$description": "A chosen chip reads the way a chosen segment does: the accent tint with an accent EDGE. A member's own selected state is a 15% tint over its neutral border, which among framed neighbours reads as a faint wash rather than as the one that is on — the measurement that gave the compact group its selected rule, restated here at the one place the group does not draw it. (0,4,0) over the member's own (0,3,0).",
+      "borderColor": "var(--jx-accent)",
+      "background": "var(--jx-accent-20)"
     },
     "& [part=\"fields\"]": {
       "$description": "The fields, stacked. They were a row on the bar capped at 140px; in the popover each takes the full column so a route value or a JSON test prop is readable while you type it.",
@@ -461,6 +487,7 @@
                                   },
                                   "$props": {
                                     "size": "sm",
+                                    "quiet": false,
                                     "toggles": true,
                                     "emphasized": true,
                                     "selected": {
@@ -799,55 +826,55 @@
                       }
                     ]
                   }
-                },
-                {
-                  "tagName": "div",
+                }
+              ]
+            },
+            {
+              "tagName": "div",
+              "attributes": {
+                "part": "fit-slot",
+                "role": "none"
+              },
+              "style": {
+                "display": "contents"
+              },
+              "$switch": {
+                "$ref": "#/state/fitState"
+              },
+              "cases": {
+                "shown": {
+                  "tagName": "jx-select",
                   "attributes": {
-                    "part": "fit-slot",
-                    "role": "none"
-                  },
-                  "style": {
-                    "display": "contents"
+                    "part": "fit"
                   },
-                  "$switch": {
-                    "$ref": "#/state/fitState"
+                  "$props": {
+                    "label": "Fit",
+                    "size": "sm",
+                    "options": {
+                      "$ref": "#/state/fitOptions"
+                    },
+                    "value": {
+                      "$ref": "#/state/fitValue"
+                    }
                   },
-                  "cases": {
-                    "shown": {
-                      "tagName": "jx-select",
-                      "attributes": {
-                        "part": "fit"
-                      },
-                      "$props": {
-                        "label": "Fit",
-                        "size": "sm",
-                        "options": {
-                          "$ref": "#/state/fitOptions"
+                  "onchange": {
+                    "$prototype": "Function",
+                    "body": [
+                      {
+                        "operator": "call",
+                        "target": {
+                          "$ref": "#/state/chooseFit"
                         },
-                        "value": {
-                          "$ref": "#/state/fitValue"
-                        }
-                      },
-                      "onchange": {
-                        "$prototype": "Function",
-                        "body": [
+                        "value": [
                           {
-                            "operator": "call",
-                            "target": {
-                              "$ref": "#/state/chooseFit"
-                            },
-                            "value": [
-                              {
-                                "$ref": "event#/target/value"
-                              }
-                            ]
+                            "$ref": "event#/target/value"
                           }
                         ]
                       }
-                    }
+                    ]
                   }
                 }
-              ]
+              }
             }
           ]
         }
@@ -898,7 +925,7 @@
                   },
                   "$props": {
                     "selects": "single",
-                    "compact": true,
+                    "compact": false,
                     "label": "Size"
                   },
                   "children": [
@@ -918,6 +945,7 @@
                         },
                         "$props": {
                           "size": "sm",
+                          "quiet": false,
                           "checked": {
                             "$ref": "$map/item/checked"
                           },
@@ -1170,7 +1198,7 @@
                       },
                       "$props": {
                         "selects": "multiple",
-                        "compact": true,
+                        "compact": false,
                         "label": "Features"
                       },
                       "children": [
@@ -1190,6 +1218,7 @@
                             },
                             "$props": {
                               "size": "sm",
+                              "quiet": false,
                               "toggles": true,
                               "selected": {
                                 "$ref": "$map/item/selected"

package/src/surfaces/pane-context.ts

@@ -1,6 +1,7 @@
 /// <reference lib="dom" />
 /**
- * The pane's chrome as a mounted document — regions ⑦ and ⑩, one mount per pane.
+ * The pane's chrome as a mounted document — the pane context bar and the floating zoom pod, one
+ * mount per pane.
  *
  * `panels/pane-context.ts` is the flow: which editor kinds a document declares, which canvas views
  * it has, whether preview is a flag over one of them, what a lens may never write, which pane's

package/src/surfaces/pane-grid.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://jxsuite.com/schema/v1",
   "$id": "StudioPaneGrid",
-  "$description": "The pane grid (studio.md §18.1): one cell per pane, with a splitter before every cell but the first. Every box here is EMPTY by design — the FIVE inside a cell are hosts other modules fill (`panels/tab-strip.ts` the strip, `panels/jump-bar.ts` the jump bar, `panels/pane-context.ts` the chrome layer, `canvas/canvas-render.ts` the stage, `panels/pane-grid.ts` itself the right-edge drop zone), and the stage is an ISLAND in the §9.4 sense: the canvas host mounts a cross-origin `<iframe>` into it, so nothing this document draws may ever go inside it. What the document owns is the STRUCTURE and the STYLE — the cell's own two-row grid, the three row-2 children that share its lower cell, and the splitter — which is `styles/shell.css`'s `.pane*` block and `styles/canvas.css`'s `.pane-stage` rule, carried here and keyed on `part`. Two things are load-bearing and easy to undo. (1) **A row that moves reloads an iframe**, so the keyed `$map` is not an optimisation: `workspace.panes[0]` is always the primary and `MAX_PANES` is 2, the key is the pane id, and the runtime's forward-cursor pass therefore never moves a kept row — gaining or losing the side pane leaves the primary's node, and the frame inside it, untouched. (2) **The splitter must sit BETWEEN two cells and inside neither**, so each row is a `display: contents` wrapper holding its own leading splitter and its cell: the wrapper generates no box, so the splitter and the two cells are the grid items of `#pane-grid` in DOM order, and a pointer landing on the splitter is in no cell at all. Every selector below is a `>` chain from the root, because a pane's stage hosts other surface documents and a bare `[part=\"row\"]` descendant rule would reach into them.",
+  "$description": "The pane grid (studio.md §18.1): one cell per pane, with a splitter before every cell but the first. Every box here is EMPTY by design — the FIVE inside a cell are hosts other modules fill (`panels/tab-strip.ts` the strip, `panels/jump-bar.ts` the jump bar, `panels/pane-context.ts` the chrome layer, `canvas/canvas-render.ts` the stage, `panels/pane-grid.ts` itself the right-edge drop zone), and the stage is an ISLAND in the studio-ui-guidelines.md §9.4 sense: the canvas host mounts a cross-origin `<iframe>` into it, so nothing this document draws may ever go inside it. What the document owns is the STRUCTURE and the STYLE — the cell's own two-row grid, the three row-2 children that share its lower cell, and the splitter — which is `styles/shell.css`'s `.pane*` block and `styles/canvas.css`'s `.pane-stage` rule, carried here and keyed on `part`. Two things are load-bearing and easy to undo. (1) **A row that moves reloads an iframe**, so the keyed `$map` is not an optimisation: `workspace.panes[0]` is always the primary and `MAX_PANES` is 2, the key is the pane id, and the runtime's forward-cursor pass therefore never moves a kept row — gaining or losing the side pane leaves the primary's node, and the frame inside it, untouched. (2) **The splitter must sit BETWEEN two cells and inside neither**, so each row is a `display: contents` wrapper holding its own leading splitter and its cell: the wrapper generates no box, so the splitter and the two cells are the grid items of `#pane-grid` in DOM order, and a pointer landing on the splitter is in no cell at all. Every selector below is a `>` chain from the root, because a pane's stage hosts other surface documents and a bare `[part=\"row\"]` descendant rule would reach into them.",
   "tagName": "div",
   "attributes": {
     "part": "grid",
@@ -45,7 +45,7 @@
       "display": "none"
     },
     "& > [part=\"row\"] > [part=\"pane\"] > [part=\"jump\"]": {
-      "$description": "Region ⑥. Like the chrome layer below it this shares the pane's lower cell rather than owning a row, so the two bars stack OVER the stage instead of pushing it down. `align-self: start` is what keeps it the height of its own content instead of the height of the cell, so the bar never covers the stage it sits above.",
+      "$description": "The jump bar. Like the chrome layer below it this shares the pane's lower cell rather than owning a row, so the two bars stack OVER the stage instead of pushing it down. `align-self: start` is what keeps it the height of its own content instead of the height of the cell, so the bar never covers the stage it sits above.",
       "gridRow": "2",
       "gridColumn": "1",
       "alignSelf": "start",
@@ -55,7 +55,7 @@
       "maxWidth": "100%"
     },
     "& > [part=\"row\"] > [part=\"pane\"] > [part=\"chrome\"]": {
-      "$description": "Regions ⑦ and ⑩. The layer itself is inert and only its children take the pointer; `surfaces/pane-context.json` owns what they look like. Offset by `--jump-bar-h` for the same reason the stage is: the jump bar is stacked over this same cell, and one projection per bar is what keeps \"no tab open\" costing no dead band.",
+      "$description": "The pane context bar and the floating zoom pod. The layer itself is inert and only its children take the pointer; `surfaces/pane-context.json` owns what they look like. Offset by `--jump-bar-h` for the same reason the stage is: the jump bar is stacked over this same cell, and one projection per bar is what keeps \"no tab open\" costing no dead band.",
       "gridRow": "2",
       "gridColumn": "1",
       "marginTop": "var(--jump-bar-h, 0px)",

package/src/surfaces/panel-activity.json

@@ -154,7 +154,8 @@
       }
     },
     "& [part=\"log\"]": {
-      "$description": "The captured output the progress modal used to show once and then lose. It scrolls inside the row rather than growing it, so one 400-line `bun install` failure does not become the whole panel.",
+      "$description": "The captured output the progress modal used to show once and then lose. It scrolls inside the row rather than growing it, so one 400-line `bun install` failure does not become the whole panel. It is selectable against the root's `user-select: none`, the one part of an activity row that is: the output is what a reader pastes into a bug report, and the row offers no copy action.",
+      "userSelect": "text",
       "maxHeight": "180px",
       "margin": "2px 0 0",
       "padding": "6px",

package/src/surfaces/panel-deploy-checklist.json

@@ -239,7 +239,7 @@
                       "cases": {
                         "true": {
                           "tagName": "jx-button",
-                          "$description": "The recovery button wears the command's own title, so it reads as a verb rather than as a decoration, and a refused command is dimmed with the reason it names in its tooltip. A command the registry does not have, or whose `when` is false, draws NOTHING rather than a dead label — a surface may choose whether to show a command, never whether it exists (§12.4).",
+                          "$description": "The recovery button wears the command's own title, so it reads as a verb rather than as a decoration, and a refused command is dimmed with the reason it names in its tooltip. A command the registry does not have, or whose `when` is false, draws NOTHING rather than a dead label — a surface may choose whether to show a command, never whether it exists (§13).",
                           "$props": {
                             "size": "sm",
                             "disabled": {

package/src/surfaces/panel-elements.ts

@@ -148,7 +148,8 @@ export function mountElementsSurface(
   let disposed = false;
   /* Nothing is called on an element here, so the mount is all there is 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 asking them to (§1.1, "await the element"). */
+     `connectedCallback` later without anybody asking them to (studio-ui-guidelines.md §1.1,
+     "await the element"). */
   const ready = mountSurface("panel-elements", scope, container).then((surface) => {
     if (disposed) {
       surface.dispose();

package/src/surfaces/panel-i18n.ts

@@ -187,7 +187,8 @@ export function mountI18nSurface(
   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("panel-i18n", scope, container).then((surface) => {
     if (disposed) {
       surface.dispose();

package/src/surfaces/panel-outline.json

@@ -684,7 +684,7 @@
               ]
             },
             "empty": {
-              "$description": "Drawn here rather than borrowed from `panels/empty-state.ts`, which is a lit template a document cannot call. What is kept is the pattern's rules (guidelines §11): one sentence saying what the region is for, then the one action that fills it.",
+              "$description": "Drawn here rather than borrowed from `panels/empty-state.ts`, which is a lit template a document cannot call. What is kept is the pattern's rules (studio-ui-guidelines.md §11): one sentence saying what the region is for, then the one action that fills it.",
               "tagName": "div",
               "attributes": {
                 "part": "empty"

package/src/surfaces/panel-outline.ts

@@ -21,8 +21,8 @@
  * `role`, no `aria-*` and no key names — those were written out here and written out again in
  * `files-panel.ts`, one contract in two copies with nothing keeping them in agreement.
  *
- * **Three things reach the host through `onNodeCreated`** (guidelines §9.4), because each is a fact
- * about a node that only exists once it has been created:
+ * **Three things reach the host through `onNodeCreated`** (studio-ui-guidelines.md §9.4), because
+ * each is a fact about a node that only exists once it has been created:
  *
  * - The tree element, which is what the virtual window is measured against and what the scroll watch
  *   binds to. Nothing about the window can be computed before it.
@@ -285,7 +285,8 @@ export function mountOutlineSurface(
   let disposed = false;
   /* Nothing is called on an element here, so the mount is all there is to wait for: the two islands
      announce themselves through `onNodeCreated` as they 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). */
   const ready = mountSurface("panel-outline", scope, container, {
     onNodeCreated: (element, _path, def) => {
       /* A text node carries no `part`, so narrowing and asking are the same question — asked once,

package/src/surfaces/panel-page.json

@@ -42,7 +42,7 @@
       "padding": "0 var(--jx-space-2)"
     },
     "& [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 in a 240px dock (§4.6) — a field refuses to shrink below its own min-content without it.",
+      "$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 in a 240px dock (studio-ui-guidelines.md §4.6) — a field refuses to shrink below its own min-content without it.",
       "display": "flex",
       "flexDirection": "column",
       "alignItems": "stretch",
@@ -58,7 +58,7 @@
       "color": "var(--fg-dim)"
     },
     "& [part=\"chip\"]": {
-      "$description": "§4.2's set dot: a 6px accent dot, drawn only where the value is set on this document, that clears it when pressed. A real `button` — it is pressable, and it is the row's only keyboard route to clearing — stripped of the chrome a button brings 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 on this document, that clears it when pressed. A real `button` — it is pressable, and it is the row's only keyboard route to clearing — stripped of the chrome a button brings so the row still reads as a label with a dot beside it.",
       "width": "6px",
       "height": "6px",
       "padding": "0",

package/src/surfaces/panel-page.ts

@@ -58,7 +58,10 @@ export interface PageRow extends Record<string, unknown> {
   label: string;
   /** Which control the row draws. `textarea` is a multiline text field, not a second element. */
   kind: "text" | "textarea" | "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;

package/src/surfaces/panel-problems.json

@@ -113,7 +113,7 @@
       "overflowWrap": "anywhere"
     },
     "& [part=\"file-path\"]": {
-      "$description": "The path is a control, not a label: it opens the file the problem is about, which is the click-through §7.1 asks for. Underlined on hover only — a permanently underlined path in a dense list reads as a paragraph of links. A plain button rather than a `jx-button`, for the reason the status bar's items are: what it has to look like is a line of text, and every fill, border and control height the kit draws would have to be taken back off again. Named `file-path` and not `path` because `jx-icon` puts `part=\"path\"` on the `<path>` of every glyph it draws, so `[part=\"path\"]` inside a row selects this button and both SVG paths beside it — a styling rule that reaches into the kit's own drawing, and a test or a devtools query that cannot tell them apart.",
+      "$description": "The path is a control, not a label: it opens the file the problem is about, which is the click-through §16.1 asks for. Underlined on hover only — a permanently underlined path in a dense list reads as a paragraph of links. A plain button rather than a `jx-button`, for the reason the status bar's items are: what it has to look like is a line of text, and every fill, border and control height the kit draws would have to be taken back off again. Named `file-path` and not `path` because `jx-icon` puts `part=\"path\"` on the `<path>` of every glyph it draws, so `[part=\"path\"]` inside a row selects this button and both SVG paths beside it — a styling rule that reaches into the kit's own drawing, and a test or a devtools query that cannot tell them apart.",
       "alignSelf": "flex-start",
       "maxWidth": "100%",
       "overflow": "hidden",
@@ -139,7 +139,8 @@
       }
     },
     "& [part=\"detail\"]": {
-      "$description": "The captured log the progress modal used to own. It scrolls inside the row rather than growing it, so one 400-line `bun install` failure does not become the whole panel.",
+      "$description": "The captured log the progress modal used to own. It scrolls inside the row rather than growing it, so one 400-line `bun install` failure does not become the whole panel. It is the one part of a problem row that is selectable against the root's `user-select: none`: the log is what a reader pastes into a bug report, and the row offers no copy action.",
+      "userSelect": "text",
       "maxHeight": "180px",
       "margin": "var(--jx-space-1) 0 0",
       "padding": "6px",
@@ -171,7 +172,7 @@
       "flex": "none"
     },
     "& [part=\"empty\"]": {
-      "$description": "The teaching empty state, drawn here rather than borrowed from `panels/empty-state.ts`: that helper is a lit template, and a document cannot call one. What is kept is the pattern's rules (§11) — one sentence saying what the region is FOR, then where its content comes from. It offers no action, because the action that fills this region is a failure and nothing here should invite one.",
+      "$description": "The teaching empty state, drawn here rather than borrowed from `panels/empty-state.ts`: that helper is a lit template, and a document cannot call one. What is kept is the pattern's rules (studio-ui-guidelines.md §11) — one sentence saying what the region is FOR, then where its content comes from. It offers no action, because the action that fills this region is a failure and nothing here should invite one.",
       "display": "flex",
       "flexDirection": "column",
       "alignItems": "center",

package/src/surfaces/panel-problems.ts

@@ -109,8 +109,8 @@ function project(scope: ProblemsScope, values: ProblemsValues): void {
  *
  * Nothing is called on the elements, 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 (guidelines §1.1, "await the
- * element").
+ * `connectedCallback` later without anybody here asking them to (studio-ui-guidelines.md §1.1,
+ * "await the element").
  */
 export function mountProblemsSurface(
   container: HTMLElement,