@jxsuite/studio 5.3.0 → 5.4.0

package/src/surfaces/block-action-bar.json

@@ -1,14 +1,14 @@
 {
   "$schema": "https://jxsuite.com/schema/v1",
   "$id": "StudioBlockActionBar",
-  "$description": "The floating action bar over the canvas selection (plan §3.2 region ⑩, studio-ui-guidelines.md §8.6), as a Jx document over the kit. ONE SHAPE is the whole rule this markup exists to keep: the parent selector, the element badge, the drag handle and every verb are drawn on every selection, and a control that cannot act is DISABLED rather than removed — a toolbar whose buttons move under the cursor is worse than one with a greyed button. Nothing here decides what a verb is called, whether it can act or what its chord reads: `panels/block-action-bar.ts` projects the command registry into `verbs` and `formats`, already resolved to a glyph, a name, a tooltip and a refusal, and this document draws them. The toolbar role, the roving caret and the arrow keys are `jx-action-group`'s, so no keyboard code rides along; Escape is the one key this document claims, because leaving the bar means going back to the canvas and only the host knows where that is. The drag handle is an ISLAND (§9.4): the document draws the node and `surfaces/block-action-bar.ts` attaches the pragmatic-dnd registration to it through `onNodeCreated`. Position is a DECISION measured against the selection rect, so it arrives as two numbers the flow projects — `barX` and `barY` — rather than as a layout this document could compute; the `style` object below binds them, because a style declaration may read state like any other value (spec §9.1).",
+  "$description": "The floating action bar over the canvas selection (studio.md §4.4, studio-ui-guidelines.md §8.6), as a Jx document over the kit. ONE SHAPE is the whole rule this markup exists to keep: the parent selector, the element badge, the drag handle and every verb are drawn on every selection, and a control that cannot act is DISABLED rather than removed — a toolbar whose buttons move under the cursor is worse than one with a greyed button. Nothing here decides what a verb is called, whether it can act or what its chord reads: `panels/block-action-bar.ts` projects the command registry into `verbs` and `formats`, already resolved to a glyph, a name, a tooltip and a refusal, and this document draws them. The toolbar role, the roving caret and the arrow keys are `jx-action-group`'s, so no keyboard code rides along; Escape is the one key this document claims, because leaving the bar means going back to the canvas and only the host knows where that is. The drag handle is an ISLAND (studio-ui-guidelines.md §9.4): the document draws the node and `surfaces/block-action-bar.ts` attaches the pragmatic-dnd registration to it through `onNodeCreated`. Position is a DECISION measured against the selection rect, so it arrives as two numbers the flow projects — `barX` and `barY` — rather than as a layout this document could compute; the `style` object below binds them, because a style declaration may read state like any other value (spec.md §9.1).",
   "tagName": "div",
   "attributes": {
     "part": "root",
     "role": "none"
   },
   "style": {
-    "$description": "The `.block-action-bar` rules that used to live in `styles/canvas.css`, re-valued onto the kit's tokens. The bar is `position: fixed` because its anchor is a rect in viewport space that crossed the iframe bridge; the layer it sits in has no clipping, which is why the host clamps it rather than letting overflow do it.\n\nThe two placement properties are declared HERE, bound to the flow's measured numbers. They used to travel as a `style` ATTRIBUTE the flow assembled into one string, on the belief that a document cannot bind a style declaration to state. It can, and always could: a reactive value on a custom property in a rule targeting the element itself is written inline under the author's own name (spec §9.1), which is precisely the attribute that string was hand-writing. The bar reads them by name through the ordinary cascade — the root is `display: contents`, so a custom property set on it inherits down — and `panels/block-action-bar.ts` overrides `--jx-bar-x` on the bar itself when it clamps, because a value set on an element beats one it inherits — which is also why that clamp releases its own previous write before it measures, or the bar would be pinned at the right edge for the rest of the session.",
+    "$description": "The `.block-action-bar` rules that used to live in `styles/canvas.css`, re-valued onto the kit's tokens. The bar is `position: fixed` because its anchor is a rect in viewport space that crossed the iframe bridge; the layer it sits in has no clipping, which is why the host clamps it rather than letting overflow do it.\n\nThe two placement properties are declared HERE, bound to the flow's measured numbers. They used to travel as a `style` ATTRIBUTE the flow assembled into one string, on the belief that a document cannot bind a style declaration to state. It can, and always could: a reactive value on a custom property in a rule targeting the element itself is written inline under the author's own name (spec.md §9.1), which is precisely the attribute that string was hand-writing. The bar reads them by name through the ordinary cascade — the root is `display: contents`, so a custom property set on it inherits down — and `panels/block-action-bar.ts` overrides `--jx-bar-x` on the bar itself when it clamps, because a value set on an element beats one it inherits — which is also why that clamp releases its own previous write before it measures, or the bar would be pinned at the right edge for the rest of the session.",
     "display": "contents",
     "--jx-bar-x": "${state.barX}px",
     "--jx-bar-y": "${state.barY}px",
@@ -39,7 +39,7 @@
       "gap": "2px"
     },
     "& [part=\"tag\"] > [part=\"control\"]": {
-      "$description": "The element badge. It is a button on every selection and disabled where the tag cannot be changed — a component instance, a repeater — which is §8.6's rule applied to the one control that used to change shape.",
+      "$description": "The element badge. It is a button on every selection and disabled where the tag cannot be changed — a component instance, a repeater — which is studio-ui-guidelines.md §8.6's rule applied to the one control that used to change shape.",
       "minWidth": "0",
       "minHeight": "0",
       "maxWidth": "140px",
@@ -84,7 +84,7 @@
       }
     },
     "& [part=\"drag-handle\"][aria-disabled=\"true\"]": {
-      "$description": "ONE shape (§8.6): the handle is greyed on the document root, never removed — a toolbar whose controls move under the cursor is worse than one with a dead affordance.",
+      "$description": "ONE shape (studio-ui-guidelines.md §8.6): the handle is greyed on the document root, never removed — a toolbar whose controls move under the cursor is worse than one with a dead affordance.",
       "cursor": "default",
       "opacity": "0.3"
     },

package/src/surfaces/block-action-bar.ts

@@ -19,7 +19,7 @@
  * takes its pragmatic-dnd registration as it is created — `canDrag` and the dragged path are the
  * flow's, so the registration outlives every selection change and the bar never carries two. The
  * link panel is the kit's `jx-popover`, and an element's own `showPopover()` is the one overlay
- * call §9.4 leaves on this side of the seam.
+ * call `studio-ui-guidelines.md` §9.4 leaves on this side of the seam.
  *
  * **Every control the flow has to reach again is announced, never queried.** `format.link`'s button
  * is the link panel's anchor and ⌥↑ needs the toolbar itself; both are recorded here as the runtime
@@ -332,8 +332,8 @@ export function mountBlockActionBar(host: HTMLElement, actions: BlockBarActions)
       }
       /*
        * Placing is by measured coordinate — the anchor's box, read here rather than bound in the
-       * document, which is the one measurement §9.4 leaves on this side of the seam — and showing
-       * is the element's own `showPopover`.
+       * document, which is the one measurement `studio-ui-guidelines.md` §9.4 leaves on this side
+       * of the seam — and showing is the element's own `showPopover`.
        *
        * A custom element connects asynchronously, so the panel may not yet carry the `popover`
        * attribute that makes it showable: `jx-ready` is the element saying it does. The same

package/src/surfaces/boot-failure.json

@@ -0,0 +1,228 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioBootFailure",
+  "$description": "What Studio draws INSTEAD of the application frame when a launcher was supposed to register a platform adapter and did not (`platforms/default-platform.ts`'s `bootRefusal`). It replaces a failure that drew everything: desktop 5.0.0 to 5.1.3 fell back to the dev-server adapter inside a `views://` window, so every panel rendered and the first click said \"Failed to fetch\". This says so up front instead: what failed, the error the launcher recorded, and the facts a support thread needs, with a Reload for a transient failure and a Copy for everything else. The adapter decides every sentence; the document only draws them. It is the whole page, so it carries a window drag strip of its own — the desktop window hides its title bar, and with no Command Bar mounted there is otherwise nothing to move the window by.",
+  "tagName": "div",
+  "attributes": {
+    "part": "screen",
+    "role": "alert"
+  },
+  "style": {
+    "$description": "Tokens throughout: the screen is mounted before anything but the kit's theme has run, so it can lean on nothing the frame's stylesheets declare. The top padding clears the macOS traffic lights, which sit over the page because the window's title bar is hidden.",
+    "position": "fixed",
+    "inset": "0",
+    "display": "flex",
+    "alignItems": "flex-start",
+    "justifyContent": "center",
+    "paddingTop": "max(10vh, calc(var(--jx-control-h) * 2))",
+    "overflowY": "auto",
+    "boxSizing": "border-box",
+    "background": "var(--jx-bg)",
+    "fontFamily": "var(--jx-font-sans)",
+    "color": "var(--jx-fg)",
+    "& > [part=\"drag-strip\"]": {
+      "$description": "The window's handle. Electrobun's preload recognises the class and supplies the drag behaviour itself, so the rule here only sizes the strip: as tall as the hidden title bar would have been.",
+      "position": "absolute",
+      "top": "0",
+      "left": "0",
+      "right": "0",
+      "height": "calc(var(--jx-control-h) + var(--jx-space-3))"
+    },
+    "& > [part=\"content\"]": {
+      "position": "relative",
+      "maxWidth": "40rem",
+      "width": "100%",
+      "padding": "0 var(--jx-space-6) var(--jx-space-7)",
+      "boxSizing": "border-box",
+      "display": "flex",
+      "flexDirection": "column",
+      "gap": "var(--jx-space-4)"
+    },
+    "& > [part=\"content\"] > [part=\"icon\"]": {
+      "$description": "The child, not any descendant: `jx-button` renders its own `<span part=\"icon\">` into light DOM unconditionally, so a bare `[part=\"icon\"]` reached the Reload and Copy buttons too. `--jx-icon-size` is a custom property and `color` inherits, so both passed through that span's `display: contents` and drew the Copy button's clipboard glyph at 32px in warning amber, stretching the actions row with it. This is the collision `[part=\"error\"]` taught: a part name is shared with the kit unless a selector says otherwise.",
+      "--jx-icon-size": "2rem",
+      "color": "var(--jx-warning)"
+    },
+    "& [part=\"title\"]": {
+      "margin": "0",
+      "fontSize": "1.5rem",
+      "fontWeight": "400",
+      "color": "var(--jx-fg)"
+    },
+    "& [part=\"lead\"]": {
+      "margin": "0",
+      "fontSize": "var(--jx-text-lg)",
+      "lineHeight": "1.5",
+      "color": "var(--jx-fg)"
+    },
+    "& [part=\"detail\"]": {
+      "$description": "The launcher's own error, verbatim. Selectable, because the point of printing it is that someone pastes it into an issue, and wrapped, because a stack line is wider than any window it is likely to be read in.",
+      "margin": "0",
+      "padding": "var(--jx-space-3) var(--jx-space-4)",
+      "maxHeight": "40vh",
+      "overflow": "auto",
+      "background": "var(--jx-bg-panel)",
+      "border": "1px solid var(--jx-border)",
+      "borderRadius": "var(--jx-radius-sm)",
+      "fontFamily": "var(--jx-font-mono)",
+      "fontSize": "var(--jx-text-sm)",
+      "whiteSpace": "pre-wrap",
+      "wordBreak": "break-word",
+      "userSelect": "text"
+    },
+    "& [part=\"facts\"]": {
+      "margin": "0",
+      "fontSize": "var(--jx-text-sm)",
+      "color": "var(--jx-fg-dim)",
+      "wordBreak": "break-all",
+      "userSelect": "text"
+    },
+    "& [part=\"actions\"]": {
+      "display": "flex",
+      "flexWrap": "wrap",
+      "gap": "var(--jx-space-3)"
+    }
+  },
+  "children": [
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "drag-strip",
+        "class": "electrobun-webkit-app-region-drag",
+        "aria-hidden": "true"
+      }
+    },
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "content"
+      },
+      "children": [
+        {
+          "tagName": "jx-icon",
+          "attributes": {
+            "part": "icon"
+          },
+          "$props": {
+            "name": "warning",
+            "weight": "fill"
+          }
+        },
+        {
+          "tagName": "h1",
+          "attributes": {
+            "part": "title"
+          },
+          "textContent": "${state.title}"
+        },
+        {
+          "tagName": "p",
+          "attributes": {
+            "part": "lead"
+          },
+          "textContent": "${state.lead}"
+        },
+        {
+          "tagName": "div",
+          "attributes": {
+            "part": "detail-slot",
+            "role": "none"
+          },
+          "style": {
+            "display": "contents"
+          },
+          "$switch": {
+            "$ref": "#/state/hasDetail"
+          },
+          "cases": {
+            "true": {
+              "tagName": "pre",
+              "attributes": {
+                "part": "detail"
+              },
+              "textContent": "${state.detail}"
+            }
+          }
+        },
+        {
+          "tagName": "p",
+          "attributes": {
+            "part": "facts"
+          },
+          "textContent": "${state.facts}"
+        },
+        {
+          "tagName": "div",
+          "attributes": {
+            "part": "actions"
+          },
+          "children": [
+            {
+              "tagName": "jx-button",
+              "attributes": {
+                "part": "reload"
+              },
+              "$props": {
+                "variant": "accent"
+              },
+              "onclick": {
+                "$prototype": "Function",
+                "body": [
+                  {
+                    "operator": "call",
+                    "target": {
+                      "$ref": "#/state/reload"
+                    },
+                    "value": []
+                  }
+                ]
+              },
+              "children": [
+                {
+                  "tagName": "span",
+                  "textContent": "Reload"
+                }
+              ]
+            },
+            {
+              "tagName": "jx-button",
+              "attributes": {
+                "part": "copy"
+              },
+              "$props": {
+                "quiet": true
+              },
+              "onclick": {
+                "$prototype": "Function",
+                "body": [
+                  {
+                    "operator": "call",
+                    "target": {
+                      "$ref": "#/state/copy"
+                    },
+                    "value": []
+                  }
+                ]
+              },
+              "children": [
+                {
+                  "tagName": "jx-icon",
+                  "attributes": {
+                    "slot": "icon"
+                  },
+                  "$props": {
+                    "name": "copy"
+                  }
+                },
+                {
+                  "tagName": "span",
+                  "textContent": "${state.copied ? 'Copied' : 'Copy details'}"
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/src/surfaces/boot-failure.ts

@@ -0,0 +1,156 @@
+/// <reference lib="dom" />
+/**
+ * The boot-failure surface: what Studio draws instead of its frame when the platform adapter a
+ * launcher was supposed to register never arrived.
+ *
+ * `platforms/default-platform.ts` decides WHETHER to refuse the dev-server fallback; this decides
+ * what to SAY about it. The difference matters because the reader is a customer, not a developer
+ * with a console open: desktop 5.0.0 to 5.1.3 failed this way silently for months, and the only
+ * report that reached anyone was "Create Project says Failed to fetch". So the screen names the
+ * failure in one sentence, prints the error the launcher recorded, and carries the facts a support
+ * thread asks for first — which bundle, which launcher, which page — behind a Copy button, so the
+ * next report arrives with them attached.
+ *
+ * The error is read LAZILY, from `launcherSignal()` at the moment the view is built, and not from
+ * the refusal. The launcher's boot module records the first page error it sees; reading it late
+ * costs nothing and cannot miss one that landed after the refusal was decided.
+ *
+ * The page's query string is never printed. The Chromium launcher authenticates its window with a
+ * `?token=` in the URL, and "copy details" is an invitation to paste the result somewhere public.
+ *
+ * @docs studio/desktop
+ */
+
+import { reactive } from "../reactivity";
+import { launcherSignal } from "../platform";
+import { mountSurface, registerSurface } from "../ui/surface";
+import { APP_NAME, GIT_COMMIT, VERSION } from "../version";
+import bootFailureDoc from "./boot-failure.json";
+import type { BootRefusal } from "../platforms/default-platform";
+import type { SurfaceHandle } from "../ui/surface";
+import type { JxDocument } from "@jxsuite/schema/types";
+
+registerSurface("boot-failure", bootFailureDoc as unknown as JxDocument);
+
+/** The page the failure happened on — `location`, or a stand-in with the one field read. */
+export interface BootFailurePage {
+  href: string;
+}
+
+/** What the document draws, with every sentence already decided. */
+export interface BootFailureView {
+  title: string;
+  lead: string;
+  /** The launcher's recorded error: its message, then its stack when it has one. */
+  detail: string;
+  hasDetail: boolean;
+  /** One line of support facts: bundle version and commit, launcher, page (no query string). */
+  facts: string;
+}
+
+/** The scope `boot-failure.json` reads. */
+interface BootFailureScope extends Record<string, unknown>, BootFailureView {
+  /** The last Copy landed on the clipboard; the button says so. */
+  copied: boolean;
+  reload: () => void;
+  copy: () => Promise<void>;
+}
+
+/** One sentence per refusal: what failed, in the words of someone who only saw the window. */
+function leadFor(refusal: BootRefusal): string {
+  if (refusal.kind === "launcher") {
+    return "The desktop app's bridge to its backend failed to start, so nothing can be opened, saved or created; reinstalling the latest release from the download page fixes this.";
+  }
+  if (refusal.kind === "declared") {
+    return "This page's startup script never ran, so Studio has no backend to open, save or create projects with.";
+  }
+  return `This page was opened from a ${refusal.protocol} URL, which has no Studio backend behind it; open Studio through the desktop app or a Jx dev server instead.`;
+}
+
+/**
+ * The error text, message first.
+ *
+ * A V8 stack already begins with the message, so printing both would say it twice; a stack that
+ * does not contain it (a non-Error throw, a WebKit stack of bare frames) gets the message above
+ * it.
+ */
+function detailFor(): string {
+  const error = launcherSignal()?.error;
+  if (!error) {
+    return "";
+  }
+  const { message, stack } = error;
+  if (!stack) {
+    return message;
+  }
+  return stack.includes(message) ? stack : `${message}\n${stack}`;
+}
+
+/**
+ * Everything the screen says, decided from the refusal and the live launcher signal.
+ *
+ * Pure apart from reading that signal, which is the point: see the header on why it is read here.
+ *
+ * @param refusal Why the dev-server fallback was refused.
+ * @param page The page to name in the facts line. Only its path survives; see the header.
+ */
+export function bootFailureView(
+  refusal: BootRefusal,
+  page: BootFailurePage = location,
+): BootFailureView {
+  const detail = detailFor();
+  const launcher =
+    (refusal.kind === "launcher" ? refusal.launcher : undefined) ??
+    launcherSignal()?.launcher ??
+    "none";
+  // Cut at the first `?` or `#`: the query is where the Chromium launcher's token lives.
+  const [where] = page.href.split(/[?#]/u);
+  return {
+    detail,
+    // Labelled as the STUDIO bundle's version, not the app's: the desktop app wraps a Studio bundle
+    // Whose version moves on its own schedule, and a support thread that reads "5.3.0" as the
+    // Desktop release is chasing a build that does not exist.
+    facts: `${APP_NAME} bundle ${VERSION} (${GIT_COMMIT}) · launcher ${launcher} · ${where}`,
+    hasDetail: detail !== "",
+    lead: leadFor(refusal),
+    title: "Jx Studio couldn't connect to its backend",
+  };
+}
+
+/** The plain-text report Copy puts on the clipboard: everything the screen says, in order. */
+export function bootFailureReport(view: BootFailureView): string {
+  return [view.title, view.lead, view.detail, view.facts].filter(Boolean).join("\n\n");
+}
+
+/**
+ * Mount the boot-failure screen into `host`.
+ *
+ * @param host The container it owns — `#shell-root`, via `shell/tree.ts`'s `mountBootFailureTree`.
+ * @param refusal Why the dev-server fallback was refused.
+ * @param page The page to name in the facts line; `location` by default.
+ */
+export function mountBootFailureSurface(
+  host: HTMLElement,
+  refusal: BootRefusal,
+  page: BootFailurePage = location,
+): Promise<SurfaceHandle> {
+  const view = bootFailureView(refusal, page);
+  const scope = reactive<BootFailureScope>({
+    ...view,
+    copied: false,
+    async copy() {
+      try {
+        await navigator.clipboard.writeText(bootFailureReport(view));
+        scope.copied = true;
+      } catch {
+        /* No clipboard: an insecure context, a denied permission, or a webview without the API.
+           The button stays "Copy details", and the text it would have copied is on the screen,
+           selectable, directly above it — so the failure costs one drag rather than the report. */
+      }
+    },
+    reload() {
+      location.reload();
+    },
+  }) as BootFailureScope;
+  return mountSurface("boot-failure", scope, host);
+}

package/src/surfaces/bottom-dock.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://jxsuite.com/schema/v1",
   "$id": "StudioBottomDock",
-  "$description": "⑪ The Bottom dock's chrome as a Jx document over the kit: a real `tablist` of the dock's tabs, the button that shuts it, and ONE `tabpanel` for whichever tab is showing. Every tab names that one panel — the dock draws the selected tab's body and no other, so there is exactly one panel element and its `aria-labelledby` follows the selection, which is the same shape `surfaces/git-panel.json` uses for its two sub-tabs. It draws no tab BODY: `panels/bottom-dock.ts` keeps the panel registry, the `when` filter, the badge in each tab's label, the Logic reveal and every tab's `afterRender`, and renders the active record into the one empty `[part=\"dock-body\"]` island this document leaves for it (studio-ui-guidelines.md §9.4).",
+  "$description": "The Bottom dock's chrome (studio.md §16.3) as a Jx document over the kit: a real `tablist` of the dock's tabs, the button that shuts it, and ONE `tabpanel` for whichever tab is showing. Every tab names that one panel — the dock draws the selected tab's body and no other, so there is exactly one panel element and its `aria-labelledby` follows the selection, which is the same shape `surfaces/git-panel.json` uses for its two sub-tabs. It draws no tab BODY: `panels/bottom-dock.ts` keeps the panel registry, the `when` filter, the badge in each tab's label, the Logic reveal and every tab's `afterRender`, and renders the active record into the one empty `[part=\"dock-body\"]` island this document leaves for it (studio-ui-guidelines.md §9.4).",
   "tagName": "div",
   "attributes": {
     "part": "bottom-dock"

package/src/surfaces/canvas-stage.json

@@ -7,7 +7,7 @@
     "part": "stage"
   },
   "style": {
-    "$description": "`styles/canvas.css`'s `.panzoom-wrap`, `.canvas-panel*`, `.source-*`, `.doc-header-host`, `.content-edit-*`, `.edit-width-handle`, `.preview-stage` and `.diff-code-*` rules, keyed on `part`. Two selectors reach FOREIGN DOM and say so where they stand: `.doc-header` is the card's own root inside its host, and `.is-resizing` is written by `canvas/edit-width-drag.ts` onto the column this document draws — the same shape `grid-panel.json` uses for Tabulator's theme. The width handles are `jx-split` elements, which paint their own hover, drag and focus states; this sheet says only where they stand and how wide they are.",
+    "$description": "`styles/canvas.css`'s `.panzoom-wrap`, `.canvas-panel*`, `.source-*`, `.content-edit-*`, `.edit-width-handle`, `.preview-stage` and `.diff-code-*` rules, keyed on `part`, plus the Document Header card's host. One selector reaches FOREIGN DOM and says so where it stands: `.is-resizing` is written by `canvas/edit-width-drag.ts` onto the column this document draws — the same shape `grid-panel.json` uses for Tabulator's theme. The width handles are `jx-split` elements, which paint their own hover, drag and focus states; this sheet says only where they stand and how wide they are.",
     "display": "contents",
     "& [part=\"panzoom\"]": {
       "$description": "The transformed surface. `applyTransform` writes `transform` on it imperatively, so only the origin is declared here. `--boards-inset` is the Project Styles bar's clearance: that bar floats over the stage, so the boards start below it.",
@@ -97,21 +97,12 @@
       "left": "50%",
       "transform": "translateX(-50%)"
     },
-    "& [part=\"doc-header\"][data-placement=\"in-column\"]": {
-      "$description": "Edit: the card is a block of the artefact's own column and scrolls with it, so it is part of the document rather than a strip above it.",
-      "display": "block",
-      "paddingBottom": "16px"
-    },
-    "& [part=\"doc-header\"][data-placement=\"pinned\"]": {
-      "$description": "Design: the artboards are drawn under a pan/zoom transform, and a form drawn at 40% is a picture of a form — so the card sits above the surface at 1:1 and keeps its own scroll. This is the one placement that still needs a cap.",
+    "& [part=\"doc-header\"]": {
+      "$description": "Edit only: the card is docked above the page's scroller as a band across the pane at 1:1, so its width is the pane's rather than the breakpoint's, and the page scrolls under it rather than taking it along. It used to be a block of Edit's column, which made it exactly as wide as the column's breakpoint or dragged width and scrolled it off with the first screen of the page. `canvas-render.ts` stacks the stage cell when it draws one — and closes its gap, so the band's own bottom border is where the scroller clips; `flex-shrink: 0` keeps the band whole while the scroller below takes the squeeze. THE CAP IS TWO CAPS, because the band has two ways to eat the page: `40vh` is the tall-pane answer, and `50%` is the short-pane one — a percentage `max-height` resolves against this flex container, the stage cell, whose height is definite (row 2 of the pane's `auto minmax(0, 1fr)` grid), so the page always keeps half the pane however little of it the dock and the bars have left. `40vh` alone is a share of the WINDOW: with the bottom dock open in a 650px window it is most of a 280px stage, and the page was a sliver. No `z-index`: the one it had was for Design, where the band's sibling was a pan/zoom surface whose boards could paint over it. Edit's sibling is the scroller, which clips its own content, and Design draws no card at all. The shadow is the same one-edge idiom as `panel-outline.json`'s verb cluster — it reaches over the scroller's top padding, so the page reads as passing under a docked band rather than ending at a rule. No `display`, so `hidden` on the host still hides it.",
       "flexShrink": "0",
-      "maxHeight": "40vh",
-      "overflowY": "auto"
-    },
-    "& [part=\"doc-header\"][data-placement=\"pinned\"] .doc-header": {
-      "$description": "FOREIGN DOM: `.doc-header` is the frontmatter card's own root, mounted into this host by `panels/frontmatter-panel.ts`. Pinned, the card is a band across the stage rather than a card on it, so it loses its own rounding and keeps only the edge that separates it from the boards.",
-      "borderWidth": "0 0 1px",
-      "borderRadius": "0"
+      "maxHeight": "min(40vh, 50%)",
+      "overflowY": "auto",
+      "boxShadow": "0 8px 8px -8px rgb(0 0 0 / 0.35)"
     },
     "& [part=\"edit-canvas\"]": {
       "$description": "The side gutter is LOAD-BEARING, not breathing room: the resize handles hang outside the column's own box — flex siblings with a negative margin, so they take no width from it — and this container clips horizontally, so without it the handles would be unreachable at exactly the width where dragging inward matters most. It must stay at least as wide as `EDIT_CANVAS_GUTTER` in `canvas/edit-width.ts`, which is what the drag's own ceiling subtracts. This box is also the TRACK the two `jx-split`s measure: the first ancestor of a handle that generates a box, which is why the handles are drawn here beside the column rather than inside it — inside, the column would have been the track, and the track cannot be the thing being resized.",
@@ -198,7 +189,7 @@
   },
   "children": [
     {
-      "$description": "What stands over the frame, and only ever one of the three: the Document Header card above a pan/zoom surface, the Compare bar over a comparison, or the Project Styles bar over the catalogue. Each is an empty host — the surface that fills it is mounted by the module that owns it.",
+      "$description": "What stands over the frame, and only ever one of the three: the Document Header card docked above Edit's scrolling column, the Compare bar over a comparison, or the Project Styles bar over the catalogue. Each is an empty host — the surface that fills it is mounted by the module that owns it.",
       "tagName": "div",
       "attributes": {
         "part": "lead-slot"
@@ -211,10 +202,10 @@
       },
       "cases": {
         "header": {
+          "$description": "The card has ONE place, so the host says nothing about where it is. It used to carry `data-placement`, one of two, and the card read it back as the host was announced — which is before the runtime writes a node's attributes, so the card read no attribute at all and drew `in-column` even where the host said `pinned`.",
           "tagName": "div",
           "attributes": {
-            "part": "doc-header",
-            "data-placement": "pinned"
+            "part": "doc-header"
           }
         },
         "toolbar": {
@@ -295,28 +286,6 @@
                 }
               },
               "children": [
-                {
-                  "$description": "Edit draws the Document Header card INSIDE the document's column, as its first block — the column's first child by contract. The width handles are not in the column at all (they stand beside it, see the frame), so nothing here can get in front of it.",
-                  "tagName": "div",
-                  "attributes": {
-                    "part": "column-header-slot"
-                  },
-                  "style": {
-                    "display": "contents"
-                  },
-                  "$switch": {
-                    "$ref": "#/state/columnHeader"
-                  },
-                  "cases": {
-                    "shown": {
-                      "tagName": "div",
-                      "attributes": {
-                        "part": "doc-header",
-                        "data-placement": "in-column"
-                      }
-                    }
-                  }
-                },
                 {
                   "$prototype": "Array",
                   "items": { "$ref": "#/state/panels" },

package/src/surfaces/canvas-stage.ts

@@ -64,10 +64,12 @@ export interface CanvasStageView {
   frameVars: string;
   /** Whether Edit's column hugs its content — a component definition rather than a page. */
   hug: boolean;
-  /** What stands over the frame, and only ever one of the three. */
+  /**
+   * What stands over the frame, and only ever one of the three: the Document Header card docked
+   * above Edit's scrolling column, the Compare bar over a comparison, or the Project Styles bar
+   * over the catalogue.
+   */
   lead: "none" | "header" | "toolbar" | "chrome";
-  /** Whether Edit draws the Document Header card inside its column. */
-  columnHeader: "hidden" | "shown";
   /** Whether the column has its two width handles. */
   handles: "hidden" | "shown";
   panels: CanvasStagePanelItem[];
@@ -81,8 +83,8 @@ export interface CanvasStageActions {
    * A host the document drew, announced as it is BUILT — one reconcile step before it is in the
    * page, which is what lets an editor be handed a node before the frame paints.
    *
-   * `detail` is the handle's side for `edit-handle` and the card's placement for `doc-header`; the
-   * artboard's own three parts are not announced here at all, because a record is filled from
+   * `detail` is the handle's side for `edit-handle` and "" for every other part; the artboard's own
+   * three parts are not announced here at all, because a record is filled from
    * {@link CanvasStageHandle.panelNode} once the reconcile has settled.
    */
   host: (part: string, element: HTMLElement, detail: string) => void;
@@ -112,7 +114,7 @@ interface CanvasStageScope extends Record<string, unknown>, CanvasStageView {
  * Static is the whole point. A node is announced as it is BUILT, one reconcile step before its
  * attributes are settled, so nothing here may read the element: `part` is what the node is,
  * `data-slot` says which of the two bound parts it is (see {@link CanvasStageView.framePart}), and
- * `data-side` / `data-placement` tell two nodes of one part apart.
+ * `data-side` tells the two width handles apart — the one part the document draws twice.
  */
 function attrOf(def: JxElement | string, name: string): string {
   const value = typeof def === "string" ? undefined : def.attributes?.[name];
@@ -153,7 +155,6 @@ function project(scope: CanvasStageScope, view: CanvasStageView): void {
   scope.frameVars = view.frameVars;
   scope.hug = view.hug;
   scope.lead = view.lead;
-  scope.columnHeader = view.columnHeader;
   scope.handles = view.handles;
   scope.panels = view.panels;
 }
@@ -180,7 +181,6 @@ export function mountCanvasStage(
      than from a callback that will not fire again. */
   const boards = new Map<string, Map<string, HTMLElement>>();
   const scope = reactive<CanvasStageScope>({
-    columnHeader: "hidden",
     frame: "boards",
     framePart: "panzoom",
     frameVars: "",
@@ -206,7 +206,7 @@ export function mountCanvasStage(
         const slot = attrOf(def, "data-slot");
         const named =
           slot === "frame" ? scope.framePart : slot === "inner" ? scope.innerPart : part;
-        actions.host(named, element, attrOf(def, "data-side") || attrOf(def, "data-placement"));
+        actions.host(named, element, attrOf(def, "data-side"));
       }
     },
   }).then((surface) => {