@jxsuite/studio 6.1.1 → 8.0.0

package/src/surfaces/ai-managed-connect.ts

@@ -27,9 +27,8 @@ import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import connectDoc from "./ai-managed-connect.json";
 import type { SurfaceHandle } from "../ui/surface";
-import type { JxDocument } from "@jxsuite/schema/types";
 
-registerSurface("ai-managed-connect", connectDoc as unknown as JxDocument);
+registerSurface("ai-managed-connect", connectDoc);
 
 /** What the offer says right now. Every field is the flow's wording, never a state it derives. */
 export interface ManagedConnectView {
@@ -63,7 +62,7 @@ interface ManagedConnectFlags {
 }
 
 interface ManagedConnectScope
-  extends Record<string, unknown>, ManagedConnectView, ManagedConnectActions, ManagedConnectFlags {}
+  extends ManagedConnectView, ManagedConnectActions, ManagedConnectFlags {}
 
 /** The view plus the flag the document switches on. */
 function derive(view: ManagedConnectView): ManagedConnectView & ManagedConnectFlags {
@@ -87,7 +86,7 @@ export function createManagedConnectSurface(
 ): ManagedConnectSurface {
   const host = document.createElement("div");
   host.style.display = "contents";
-  const scope = reactive({ ...derive(view), ...actions }) as ManagedConnectScope;
+  const scope: ManagedConnectScope = reactive<ManagedConnectScope>({ ...derive(view), ...actions });
 
   /** `null` while a mount is in flight — which is a standing surface, not a missing one. */
   let handle: SurfaceHandle | null = null;

package/src/surfaces/ai-model-picker.ts

@@ -25,9 +25,8 @@ import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import pickerDoc from "./ai-model-picker.json";
 import type { SurfaceHandle } from "../ui/surface";
-import type { JxDocument } from "@jxsuite/schema/types";
 
-registerSurface("ai-model-picker", pickerDoc as unknown as JxDocument);
+registerSurface("ai-model-picker", pickerDoc);
 
 /** One row the control offers. Already a label — the flow decides what a row is called. */
 export interface ModelPickerRow {
@@ -79,8 +78,7 @@ interface ModelPickerFlags {
   hasFailure: boolean;
 }
 
-interface ModelPickerScope
-  extends Record<string, unknown>, ModelPickerView, ModelPickerActions, ModelPickerFlags {}
+interface ModelPickerScope extends ModelPickerView, ModelPickerActions, ModelPickerFlags {}
 
 /** The view plus the flag the document switches on. */
 function derive(view: ModelPickerView): ModelPickerView & ModelPickerFlags {
@@ -103,7 +101,7 @@ export function createModelPickerSurface(
 ): ModelPickerSurface {
   const host = document.createElement("div");
   host.style.display = "contents";
-  const scope = reactive({ ...derive(view), ...actions }) as ModelPickerScope;
+  const scope: ModelPickerScope = reactive<ModelPickerScope>({ ...derive(view), ...actions });
 
   /** `null` while a mount is in flight — which is a standing surface, not a missing one. */
   let handle: SurfaceHandle | null = null;

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

@@ -29,15 +29,16 @@
  * @docs studio/editing/writing
  */
 
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import blockActionBarDoc from "./block-action-bar.json";
 
 import type { JxScope } from "@jxsuite/runtime/types";
-import type { JxDocument, JxElement } from "@jxsuite/schema/types";
+import type { JxElement } from "@jxsuite/schema/types";
 import { rectOf } from "../utils/geometry";
 
-registerSurface("block-action-bar", blockActionBarDoc as unknown as JxDocument);
+registerSurface("block-action-bar", blockActionBarDoc);
 
 /** One button, already decided: what it is called, what it draws, and why it cannot act. */
 export interface BlockBarTool {
@@ -116,7 +117,7 @@ export interface BlockBarActions {
 }
 
 /** The scope `block-action-bar.json` reads. */
-interface BlockBarScope extends BlockBarView, Record<string, unknown> {
+interface BlockBarScope extends BlockBarView {
   linkValue: string;
   linkExisting: boolean;
   linkApplyLabel: string;
@@ -167,8 +168,8 @@ export function emptyBlockBarView(): BlockBarView {
 
 /** A node definition's `part`, as written in the document. */
 function partOf(def: JxElement | string): string {
-  const part = typeof def === "string" ? undefined : def.attributes?.["part"];
-  return typeof part === "string" ? part : "";
+  const part = isString(def) ? undefined : def.attributes?.["part"];
+  return isString(part) ? part : "";
 }
 
 /**
@@ -180,9 +181,10 @@ function partOf(def: JxElement | string): string {
  * same shape `surfaces/schema-form.ts` and `surfaces/properties-panel.ts` use.
  */
 function commandIdOf(state: JxScope | undefined): string {
-  const item = (state?.["$map"] as { item?: Record<string, unknown> } | undefined)?.item;
-  const id = item?.["id"];
-  return typeof id === "string" ? id : "";
+  const map = state?.["$map"];
+  const item = isJsonObject(map) ? map["item"] : undefined;
+  const id = isJsonObject(item) ? item["id"] : undefined;
+  return isString(id) ? id : "";
 }
 
 /** The bar's mounted surface, and every handle the flow is allowed to reach back through. */
@@ -250,22 +252,29 @@ export function mountBlockActionBar(host: HTMLElement, actions: BlockBarActions)
     linkApplyLabel: "Apply",
     linkExisting: false,
     linkInput: (_scope: JxScope, event: Event) => {
-      const value = (event.target as { value?: unknown } | null)?.value;
-      scope.linkValue = typeof value === "string" ? value : "";
+      const { target } = event;
+      const value = target !== null && "value" in target ? target.value : undefined;
+      scope.linkValue = isString(value) ? value : "";
     },
     linkValue: "",
     linkX: 0,
     linkY: 0,
     openMergeTags: (_scope: JxScope, event: Event) => {
       event.stopPropagation();
+      // SAFETY: Only the merge-tags `jx-action-button`'s `onclick` binds this handler, and during
+      // Dispatch `currentTarget` is the element the listener sits on.
       actions.openMergeTags(event.currentTarget as HTMLElement);
     },
     openOverflow: (_scope: JxScope, event: Event) => {
       event.stopPropagation();
+      // SAFETY: Only the overflow `jx-action-button`'s `onclick` binds this handler, and during
+      // Dispatch `currentTarget` is the element the listener sits on.
       actions.openOverflow(event.currentTarget as HTMLElement);
     },
     openTagMenu: (_scope: JxScope, event: Event) => {
       event.stopPropagation();
+      // SAFETY: Only the tag `jx-action-button`'s `onclick` binds this handler, and during
+      // Dispatch `currentTarget` is the element the listener sits on.
       actions.openTagMenu(event.currentTarget as HTMLElement);
     },
     removeLink: () => {
@@ -274,7 +283,7 @@ export function mountBlockActionBar(host: HTMLElement, actions: BlockBarActions)
     },
     run: (id: string) => actions.run(id),
     selectParent: () => actions.selectParent(),
-  }) as BlockBarScope;
+  });
 
   /* One mount for the life of the window, and no teardown to write. The bar is chrome the app
      never takes down: `dismissBlockActionBar` hides it through `visible`, and its layer slot is
@@ -295,6 +304,8 @@ export function mountBlockActionBar(host: HTMLElement, actions: BlockBarActions)
         return;
       }
       if (part === "link") {
+        // SAFETY: `part: "link"` is the document's `jx-popover`, whose class carries `open` and the
+        // `showPopover({ source })` overload that PopoverElement names.
         linkEl = element as PopoverElement;
         return;
       }

package/src/surfaces/boot-failure.json

@@ -21,12 +21,13 @@
     "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.",
+      "$description": "The window's handle. The `app-region-drag` class (shell-frame) makes the strip drag the frameless window, so the rule here sizes it, as tall as the hidden title bar would have been, and repeats the drag region so the strip works even before the shell stylesheet loads.",
       "position": "absolute",
       "top": "0",
       "left": "0",
       "right": "0",
-      "height": "calc(var(--jx-control-h) + var(--jx-space-3))"
+      "height": "calc(var(--jx-control-h) + var(--jx-space-3))",
+      "-webkit-app-region": "drag"
     },
     "& > [part=\"content\"]": {
       "position": "relative",
@@ -88,7 +89,7 @@
       "tagName": "div",
       "attributes": {
         "part": "drag-strip",
-        "class": "electrobun-webkit-app-region-drag",
+        "class": "app-region-drag",
         "aria-hidden": "true"
       }
     },

package/src/surfaces/boot-failure.ts

@@ -28,9 +28,8 @@ 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);
+registerSurface("boot-failure", bootFailureDoc);
 
 /** The page the failure happened on — `location`, or a stand-in with the one field read. */
 export interface BootFailurePage {
@@ -49,7 +48,7 @@ export interface BootFailureView {
 }
 
 /** The scope `boot-failure.json` reads. */
-interface BootFailureScope extends Record<string, unknown>, BootFailureView {
+interface BootFailureScope extends BootFailureView {
   /** The last Copy landed on the clipboard; the button says so. */
   copied: boolean;
   reload: () => void;
@@ -135,7 +134,7 @@ export function mountBootFailureSurface(
   page: BootFailurePage = location,
 ): Promise<SurfaceHandle> {
   const view = bootFailureView(refusal, page);
-  const scope = reactive<BootFailureScope>({
+  const scope: BootFailureScope = reactive<BootFailureScope>({
     ...view,
     copied: false,
     async copy() {
@@ -151,6 +150,6 @@ export function mountBootFailureSurface(
     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 (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).",
+  "$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/publish-workspace.json` uses for its four 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/bottom-dock.ts

@@ -15,23 +15,14 @@
  * @docs studio/interface
  */
 
+import { isString } from "@jxsuite/schema/guards";
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import bottomDockDoc from "./bottom-dock.json";
-import type { JxDocument, JxElement } from "@jxsuite/schema/types";
-import type { SurfaceHandle } from "../ui/surface";
+import type { JxElement } from "@jxsuite/schema/types";
+import type { SurfaceHandle, SurfaceTab } from "../ui/surface";
 
-registerSurface("bottom-dock", bottomDockDoc as unknown as JxDocument);
-
-/** One tab of the strip, as the document draws it. */
-export interface BottomTabView {
-  /** The panel id — the row's identity, the strip's `selected` value, and `data-tab`. */
-  key: string;
-  /** The record's title with its badge already appended ("Problems 2"). */
-  label: string;
-  /** The tab element's own id, which the one panel names as its `aria-labelledby`. */
-  tabId: string;
-}
+registerSurface("bottom-dock", bottomDockDoc);
 
 /** What the dock says right now. */
 export interface BottomDockValues {
@@ -41,7 +32,7 @@ export interface BottomDockValues {
   tabId: string;
   /** `dock.bottom/panel:<id>`, or empty when no tab is showing and the body has no identity. */
   bodyRegion: string;
-  tabs: BottomTabView[];
+  tabs: SurfaceTab[];
 }
 
 export interface BottomDockActions {
@@ -62,7 +53,7 @@ export interface BottomDockHandle {
   dispose: () => void;
 }
 
-interface BottomDockScope extends Record<string, unknown>, BottomDockValues, BottomDockActions {}
+interface BottomDockScope extends BottomDockValues, BottomDockActions {}
 
 function project(scope: BottomDockScope, values: BottomDockValues): void {
   scope.tab = values.tab;
@@ -73,8 +64,8 @@ function project(scope: BottomDockScope, values: BottomDockValues): void {
 
 /** The `part` a node was declared with, or the empty string. */
 function partOf(def: JxElement | string): string {
-  const part = typeof def === "string" ? undefined : def.attributes?.["part"];
-  return typeof part === "string" ? part : "";
+  const part = isString(def) ? undefined : def.attributes?.["part"];
+  return isString(part) ? part : "";
 }
 
 /**
@@ -90,7 +81,7 @@ export function mountBottomDockSurface(
   actions: BottomDockActions,
   options: BottomDockOptions,
 ): BottomDockHandle {
-  const scope = reactive<BottomDockScope>({ ...values, ...actions }) as BottomDockScope;
+  const scope: BottomDockScope = reactive<BottomDockScope>({ ...values, ...actions });
 
   container.textContent = "";
   // @ts-expect-error -- _$litPart$ is lit's private render-part marker, not in the DOM types

package/src/surfaces/canvas-stage.json

@@ -1,22 +1,26 @@
 {
   "$schema": "https://jxsuite.com/schema/v1",
   "$id": "StudioCanvasStage",
-  "$description": "The canvas's own chrome: the artboards, the boxes around them, and the empty hosts the islands attach to. `canvas/canvas-render.ts` keeps every decision — which mode this pane is in, which breakpoints the document declares, how wide Edit's column is, whether a comparison has a visual half — and `canvas/canvas-utils.ts` keeps the geometry; this document owns the markup and the style, and it draws NOTHING it decides for itself.\n\n**Every island stays an island** (studio-ui-guidelines.md §9.4). Monaco gets `[part=\"source-editor\"]` or `[part=\"diff-code-editor\"]`, the artboard's iframe gets `[part=\"panel-canvas\"]`, the Document Header card gets `[part=\"doc-header\"]`, the Compare bar gets `[part=\"diff-toolbar\"]` and the Project Styles bar gets `[part=\"chrome-host\"]` — each drawn empty and announced through `onNodeCreated`, one reconcile step before it is in the page.\n\n**Three of the five frames share one artboard vocabulary**, which is why `framePart` and `innerPart` are bound rather than written: Preview, the pan/zoom surface and Edit's column are all \"a box holding N artboards\", differing only in what the box is and what else stands in it. Writing the artboard three times would be three places for a breakpoint's viewport to drift.\n\n**The stage draws no box of its own.** Its root is `display: contents`, so the frame and whatever leads it are the flex items of the pane's own stage cell — the axis `canvas-render.ts` sets on that cell still reaches them, and no depth was added between the stage and the artboards for the pan maths to have to account for.",
+  "$description": "The canvas's own chrome: the artboards, the boxes around them, and the empty hosts the islands attach to. `canvas/canvas-render.ts` keeps every decision — which mode this pane is in, which breakpoints the document declares, how wide Edit's column is, whether a comparison has a visual half — and `canvas/canvas-utils.ts` keeps the geometry; this document owns the markup and the style, and it draws NOTHING it decides for itself.\n\n**Every island stays an island** (studio-ui-guidelines.md §9.4). Monaco gets `[part=\"source-editor\"]` or `[part=\"diff-code-editor\"]`, the artboard's iframe gets `[part=\"panel-canvas\"]`, the writing-mode banner gets `[part=\"writing-banner\"]`, the Compare bar gets `[part=\"diff-toolbar\"]` and the Project Styles bar gets `[part=\"chrome-host\"]` — each drawn empty and announced through `onNodeCreated`, one reconcile step before it is in the page.\n\n**Three of the five frames share one artboard vocabulary**, which is why `framePart` and `innerPart` are bound rather than written: Preview, the pan/zoom surface and Edit's column are all \"a box holding N artboards\", differing only in what the box is and what else stands in it. Writing the artboard three times would be three places for a breakpoint's viewport to drift.\n\n**The stage draws no box of its own.** Its root is `display: contents`, so the frame and whatever leads it are the flex items of the pane's own stage cell — the axis `canvas-render.ts` sets on that cell still reaches them, and no depth was added between the stage and the artboards for the pan maths to have to account for.",
   "tagName": "div",
   "attributes": {
     "part": "stage"
   },
   "style": {
-    "$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.",
+    "$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 writing-mode banner'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.",
+      "$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. It is a MARGIN, not padding: padding sits inside the box the transform scales, so at a 25% fit a 40px clearance drew as 10px and the bar covered the first specimen. A margin is outside the transform and stays 40 screen pixels at every zoom, and `applyGeometricFit` subtracts the same length from the height it fits into.",
       "display": "inline-flex",
       "gap": "24px",
       "alignItems": "flex-start",
       "transformOrigin": "0 0",
       "marginBlock": "auto",
-      "paddingTop": "var(--boards-inset, 0)"
+      "marginTop": "var(--boards-inset, auto)"
+    },
+    "& [part=\"chrome-host\"]": {
+      "$description": "The Project Styles bar's host generates no box. The bar inside it is absolutely positioned over the stage, but an empty host in flow is a flex item of the stage cell, whose `gap` then pushed the artboards 24px right of where the fit arithmetic put them, so the last board ran off the pane's edge.",
+      "display": "contents"
     },
     "& [part=\"panel\"]": {
       "flexShrink": "0"
@@ -97,13 +101,6 @@
       "left": "50%",
       "transform": "translateX(-50%)"
     },
-    "& [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": "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.",
       "width": "100%",
@@ -185,11 +182,15 @@
     },
     "& [part=\"preview-stage\"] [part=\"panel-canvas\"]": {
       "height": "100%"
+    },
+    "& [part=\"writing-banner\"]": {
+      "$description": "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. It never shrinks: it is one line.",
+      "flexShrink": "0"
     }
   },
   "children": [
     {
-      "$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.",
+      "$description": "What stands over the frame: the writing-mode banner above Edit's scrolling column for a collection entry (whose fields are the Inspector's), 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"
@@ -201,11 +202,11 @@
         "$ref": "#/state/lead"
       },
       "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`.",
+        "banner": {
+          "$description": "The writing-mode banner over a collection entry written on the canvas (studio.md §22.5): an empty host the banner surface is mounted into by `content/writing-banner.ts`. An entry's fields are edited in the Inspector's Entry tab; the banner only says the layout is locked and where to edit it.",
           "tagName": "div",
           "attributes": {
-            "part": "doc-header"
+            "part": "writing-banner"
           }
         },
         "toolbar": {
@@ -288,8 +289,12 @@
               "children": [
                 {
                   "$prototype": "Array",
-                  "items": { "$ref": "#/state/panels" },
-                  "key": { "$ref": "$map/item/key" },
+                  "items": {
+                    "$ref": "#/state/panels"
+                  },
+                  "key": {
+                    "$ref": "$map/item/key"
+                  },
                   "map": {
                     "$description": "One artboard: its breakpoint's name, the white page under it, and the empty box the iframe mounts into. Keyed on the breakpoint, because each board owns a live iframe and the declared set changes with the document's `$media` — position-based reuse would hand one breakpoint's frame to another's width, which is a live document rendered at the wrong viewport rather than a cosmetic diff.",
                     "tagName": "div",
@@ -323,8 +328,14 @@
                               "body": [
                                 {
                                   "operator": "call",
-                                  "target": { "$ref": "#/state/pickPanel" },
-                                  "value": [{ "$ref": "$map/item/key" }]
+                                  "target": {
+                                    "$ref": "#/state/pickPanel"
+                                  },
+                                  "value": [
+                                    {
+                                      "$ref": "$map/item/key"
+                                    }
+                                  ]
                                 }
                               ]
                             },

package/src/surfaces/canvas-stage.ts

@@ -23,20 +23,21 @@
  *
  * **Every island stays an island** (specs/studio-ui-guidelines.md §9.4). The document draws each
  * host empty and this module announces it the moment it is CREATED, one reconcile step before it is
- * in the page; Monaco, the artboard iframes, the Document Header card, the Compare bar and the
+ * in the page; Monaco, the artboard iframes, the writing-mode banner, the Compare bar and the
  * Project Styles bar are all attached by the modules that own them.
  *
  * @docs studio/interface/canvas
  */
 
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import canvasStageDoc from "./canvas-stage.json";
-import type { JxDocument, JxElement } from "@jxsuite/schema/types";
+import type { JxElement } from "@jxsuite/schema/types";
 import type { JxScope } from "@jxsuite/runtime/types";
 import type { SurfaceHandle } from "../ui/surface";
 
-registerSurface("canvas-stage", canvasStageDoc as unknown as JxDocument);
+registerSurface("canvas-stage", canvasStageDoc);
 
 /** One artboard, as the document reads it. Every field is already a string or a boolean. */
 export interface CanvasStagePanelItem {
@@ -65,11 +66,11 @@ export interface CanvasStageView {
   /** 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: the Document Header card docked
-   * above Edit's scrolling column, the Compare bar over a comparison, or the Project Styles bar
-   * over the catalogue.
+   * What stands over the frame: the writing-mode banner above Edit's scrolling column for a
+   * collection entry (`banner`), the Compare bar over a comparison, or the Project Styles bar over
+   * the catalogue. Edit draws nothing over an ordinary page (studio.md §4.2).
    */
-  lead: "none" | "header" | "toolbar" | "chrome";
+  lead: "none" | "banner" | "toolbar" | "chrome";
   /** Whether the column has its two width handles. */
   handles: "hidden" | "shown";
   panels: CanvasStagePanelItem[];
@@ -104,7 +105,7 @@ export interface CanvasStageHandle {
 }
 
 /** The scope the document reads: {@link CanvasStageView} plus the one control it draws. */
-interface CanvasStageScope extends Record<string, unknown>, CanvasStageView {
+interface CanvasStageScope extends CanvasStageView {
   pickPanel: (key: string) => void;
 }
 
@@ -117,16 +118,16 @@ interface CanvasStageScope extends Record<string, unknown>, CanvasStageView {
  * `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];
-  return typeof value === "string" ? value : "";
+  const value = isString(def) ? undefined : def.attributes?.[name];
+  return isString(value) ? value : "";
 }
 
 /** The `key` of the `$map` item a node was rendered inside, or "". */
 function itemKey(state: JxScope | undefined): string {
-  const item = (state?.["$map"] as { item?: unknown } | undefined)?.item;
-  const key =
-    item !== null && typeof item === "object" ? (item as Record<string, unknown>).key : "";
-  return typeof key === "string" ? key : "";
+  const map = state?.["$map"];
+  const item = isJsonObject(map) ? map["item"] : undefined;
+  const key = isJsonObject(item) ? item["key"] : "";
+  return isString(key) ? key : "";
 }
 
 /** The three parts an artboard is made of; everything else is a singleton host. */
@@ -180,7 +181,7 @@ export function mountCanvasStage(
      "the iframe survives" means — so the record a fresh render builds is filled from here rather
      than from a callback that will not fire again. */
   const boards = new Map<string, Map<string, HTMLElement>>();
-  const scope = reactive<CanvasStageScope>({
+  const scope: CanvasStageScope = reactive<CanvasStageScope>({
     frame: "boards",
     framePart: "panzoom",
     frameVars: "",
@@ -190,7 +191,7 @@ export function mountCanvasStage(
     lead: "none",
     panels: [],
     pickPanel: actions.pickPanel,
-  }) as CanvasStageScope;
+  });
   project(scope, view);
 
   let mounted: SurfaceHandle | null = null;

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

@@ -25,25 +25,19 @@
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import { overlayRegion, REGION_ATTR } from "../ui/regions";
-import { close as closeDialog, showModal } from "@jxsuite/ui/behaviors/dialog";
+import { close, showModal } from "@jxsuite/ui/behaviors/dialog";
 import { whenReady } from "./dialog";
 import pickerDoc from "./cf-account-picker.json";
 import type { SurfaceHandle } from "../ui/surface";
-import type { JxDocument } from "@jxsuite/schema/types";
+import type { CfAccount } from "../publish/pages-service";
 
-registerSurface("cf-account-picker", pickerDoc as unknown as JxDocument);
-
-/** One account the grant reaches, as the list draws it. */
-export interface CfAccountPickerRow {
-  id: string;
-  name: string;
-}
+registerSurface("cf-account-picker", pickerDoc);
 
 /** What the flow knows. Every one of these may change while the dialog is up. */
 export interface CfAccountPickerView {
   /** The listing is in flight. Its own state, because "not yet asked" is not "reaches nothing". */
   loading: boolean;
-  accounts: CfAccountPickerRow[];
+  accounts: CfAccount[];
   /** The last refusal — a listing that failed, or an account the broker would not accept. */
   failure: string;
   /** The id being committed, so its own row can say so rather than the whole list going grey. */
@@ -88,15 +82,14 @@ interface CfAccountPickerFlags {
 }
 
 /** One row, as the document reads it: what it says, and whether it may be pressed. */
-interface CfAccountPickerScopeRow extends CfAccountPickerRow {
+interface CfAccountPickerScopeRow extends CfAccount {
   /** This row's own button text — "Selecting…" while it is the one being committed. */
   label: string;
   /** Every row is disabled while any commit is in flight: one answer at a time. */
   busy: boolean;
 }
 
-interface CfAccountPickerScope
-  extends Record<string, unknown>, CfAccountPickerView, CfAccountPickerFlags {
+interface CfAccountPickerScope extends CfAccountPickerView, CfAccountPickerFlags {
   choose: (id: string) => void;
   retry: () => void;
   closed: () => void;
@@ -150,8 +143,12 @@ export function openCfAccountPickerSurface(options: CfAccountPickerOptions): CfA
     closed = true;
     options.onClosed();
   };
+  /* Read through a call, not the bare binding: `close()` can run while the mount is awaiting the
+     element, and a direct `closed` test after that `await` would be narrowed to the value the test
+     before it saw. */
+  const isClosed = (): boolean => closed;
 
-  const scope = reactive({
+  const scope: CfAccountPickerScope = reactive<CfAccountPickerScope>({
     ...derive({ accounts: [], choosing: "", failure: "", loading: true }),
     choose: (id: string) => {
       options.onChoose(id);
@@ -160,18 +157,20 @@ export function openCfAccountPickerSurface(options: CfAccountPickerOptions): CfA
     retry: () => {
       options.onRetry();
     },
-  }) as CfAccountPickerScope;
+  });
 
   let mounted: SurfaceHandle | null = null;
   const ready = mountSurface("cf-account-picker", scope, slot).then(async (surface) => {
     mounted = surface;
+    /* SAFETY: `cf-account-picker.json`'s root definition is a `jx-dialog` element, so the runtime
+       mounts an HTMLElement; a `Text` root only comes from a document whose root is a bare string. */
     const element = surface.root as HTMLElement;
-    if (closed) {
+    if (isClosed()) {
       surface.dispose();
       return element;
     }
     await whenReady(element);
-    if (closed) {
+    if (isClosed()) {
       return element;
     }
     showModal(element);
@@ -186,7 +185,7 @@ export function openCfAccountPickerSurface(options: CfAccountPickerOptions): CfA
       const element = mounted?.root;
       if (element instanceof HTMLElement) {
         // The platform's close first, so focus goes back where it came from; then the document.
-        closeDialog(element);
+        close(element);
       }
       mounted?.dispose();
       mounted = null;