@jxsuite/studio 6.1.2 → 8.0.0

package/src/surfaces/add-new.ts

@@ -0,0 +1,325 @@
+/// <reference lib="dom" />
+/**
+ * Add new as a mounted document.
+ *
+ * `create/add-new-flow.ts` is the flow — it holds the kind, the name and the options, reads the
+ * project into a `CreationContext`, lists the directories the result would write into, asks
+ * `deriveCreation` what that is and `creationProblem` whether it may, and performs the write — and
+ * this is the surface it draws into: the reactive scope the document reads, the few flags it
+ * branches on, and the mount that lives in the dialog layer until the flow takes it down.
+ *
+ * **The flow states facts; the surface derives the flags.** Whether the name field is drawn,
+ * whether the field is refused and whether the primary button can answer are each one comparison
+ * over the view, so they are made here rather than handed in beside the facts they restate.
+ *
+ * **Await the ELEMENT, not just the mount.** `mountSurface` resolving means the DOCUMENT rendered;
+ * a `jx-dialog`'s own template is one `connectedCallback` later, and `showModal` in between finds
+ * no `<dialog>` to open. `whenReady` is shared with `surfaces/dialog.ts` rather than
+ * reimplemented.
+ *
+ * @docs studio/projects/pages-layouts-components
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import { overlayRegion, REGION_ATTR } from "../ui/regions";
+import { close, showModal } from "@jxsuite/ui/behaviors/dialog";
+import { selectValue } from "@jxsuite/ui/behaviors/textfield";
+import { whenReady } from "./dialog";
+import addNewDoc from "./add-new.json";
+import type { CreationKind } from "../create/add-new";
+import type { SurfaceHandle, SurfaceOption } from "../ui/surface";
+
+registerSurface("add-new", addNewDoc);
+
+/** One kind in the left-hand list. */
+export interface AddNewKindRow {
+  id: CreationKind;
+  label: string;
+  hint: string;
+  icon: string;
+  /** `"true"` for the chosen kind: the row is one radio of a radiogroup. */
+  checked: "true" | "false";
+}
+
+/** One card in a Start from / Wrap it in radiogroup. */
+export interface AddNewChoiceRow {
+  value: string;
+  label: string;
+  /** The muted second line: "header + footer", "mostly writing", "2 elements". */
+  note: string;
+  checked: "true" | "false";
+  /** A choice that cannot be made now stays in the group, disabled, with `reason` as its tip. */
+  disabled: boolean;
+  reason: string;
+}
+
+/** One field preset chip. */
+export interface AddNewPresetRow {
+  id: string;
+  label: string;
+  selected: boolean;
+  icon: string;
+}
+
+/** What the flow knows. Every one of these may change while the dialog is up. */
+export interface AddNewView {
+  kind: CreationKind;
+  kinds: AddNewKindRow[];
+  /** The chosen kind's label, which names the detail region. */
+  kindLabel: string;
+  /** The sentence that introduces the chosen kind. */
+  kindHint: string;
+  /** Where the dialog can be opened from, said once at the foot of the list. */
+  chordNote: string;
+  nameLabel: string;
+  name: string;
+  placeholder: string;
+  /** The refusal under the name field; `""` until the reader has typed, and when there is none. */
+  error: string;
+  /** The derived result: "Saved as pages/pricing.json · opens at /pricing". */
+  saved: string;
+  /** The primary button's words. */
+  cta: string;
+  /** Whether the primary button can answer now. */
+  canConfirm: boolean;
+
+  // ── language (page, entry, collection) ────────────────────────────────────
+  /** Whether the Language picker is drawn: a page, or an entry of a localized collection. */
+  localeShown: boolean;
+  localeOptions: SurfaceOption[];
+  /** The chosen language, a declared tag. */
+  locale: string;
+  /** Whether the project declares languages, which is when a collection can be localized. */
+  localizable: boolean;
+  /** Collection: one folder per language. */
+  localized: boolean;
+  /** The declared tags, said on the collection's checkbox: "en, fr-CA, ar". */
+  localeSummary: string;
+
+  // ── page ──────────────────────────────────────────────────────────────────
+  route: string;
+  editingUrl: boolean;
+  url: string;
+  startChoices: AddNewChoiceRow[];
+
+  // ── collection ────────────────────────────────────────────────────────────
+  itemNoun: string;
+  presets: AddNewPresetRow[];
+  ownPage: boolean;
+  pattern: string;
+  templateOptions: SurfaceOption[];
+  pageTemplate: string;
+
+  // ── template ──────────────────────────────────────────────────────────────
+  wrapChoices: AddNewChoiceRow[];
+
+  // ── component ─────────────────────────────────────────────────────────────
+  componentChoices: AddNewChoiceRow[];
+  copying: boolean;
+  copyOptions: SurfaceOption[];
+  copyOf: string;
+
+  // ── entry ─────────────────────────────────────────────────────────────────
+  collectionOptions: SurfaceOption[];
+  collection: string;
+
+  // ── media ─────────────────────────────────────────────────────────────────
+  dropActive: "true" | "false";
+  uploadAccept: string;
+  fileSummary: string;
+}
+
+/** What the document can tell the flow. */
+export interface AddNewActions {
+  pickKind: (kind: CreationKind) => void;
+  setName: (value: string) => void;
+  /** The primary button, or Enter in a field. The flow decides whether that creates anything. */
+  confirm: () => void;
+  toggleUrl: () => void;
+  setUrl: (value: string) => void;
+  pickStart: (value: string) => void;
+  togglePreset: (id: string) => void;
+  setOwnPage: (checked: boolean) => void;
+  pickPageTemplate: (value: string) => void;
+  pickWrap: (value: string) => void;
+  pickComponentStart: (value: string) => void;
+  pickCopy: (value: string) => void;
+  pickCollection: (value: string) => void;
+  pickLocale: (value: string) => void;
+  setLocalized: (checked: boolean) => void;
+  /**
+   * The file picker settled. The ELEMENT rather than its list, because a file input that is not
+   * cleared refuses the same file twice, and the input is this document's own control.
+   */
+  choose: (input: HTMLInputElement) => void;
+  drop: (files: FileList | null) => void;
+  dragOver: () => void;
+  dragOut: () => void;
+  /** The dialog closed, for any reason the platform owns as well as the flow's own `close`. */
+  closed: () => void;
+}
+
+export interface AddNewSurfaceOptions {
+  /** Where the dialog is mounted — the dialog layer, handed in so this module never reaches back. */
+  layer: HTMLElement;
+  view: AddNewView;
+  actions: AddNewActions;
+}
+
+export interface AddNewSurfaceHandle {
+  host: HTMLElement;
+  /** Resolves with the `jx-dialog` element once it has rendered and been opened. */
+  ready: Promise<HTMLElement>;
+  /** Redraw from the flow's current view. */
+  update: (view: AddNewView) => void;
+  /** Close the dialog (the platform restores focus) and dispose the document. Idempotent. */
+  close: () => void;
+}
+
+/** What the document branches on. Derived, never handed in. */
+interface AddNewFlags {
+  /** Every kind but Media has a name. */
+  named: boolean;
+  invalid: boolean;
+  blocked: boolean;
+}
+
+type AddNewScope = AddNewView &
+  AddNewFlags &
+  Omit<AddNewActions, "setName" | "closed"> & {
+    setName: (value: string) => void;
+    closed: () => void;
+  };
+
+/** The view plus the flags the document renders from. */
+function derive(view: AddNewView): AddNewView & AddNewFlags {
+  return {
+    ...view,
+    blocked: !view.canConfirm,
+    invalid: view.error !== "",
+    named: view.kind !== "media",
+  };
+}
+
+/** Open the dialog. The handle's `ready` resolves once it is showing. */
+export function openAddNewSurface(options: AddNewSurfaceOptions): AddNewSurfaceHandle {
+  const slot = document.createElement("div");
+  /* The layer is `pointer-events: none` so a click passes through it when nothing is up, and every
+     slot in it turns them back on for its own content. `pointer-events` INHERITS, and the top layer
+     changes paint order rather than inheritance, so a modal `<dialog>` in a slot that skipped this
+     is painted above everything and hit-tests to nothing. */
+  slot.style.pointerEvents = "auto";
+  slot.setAttribute(REGION_ATTR, overlayRegion("dialog", "add-new"));
+  options.layer.append(slot);
+
+  let closed = false;
+  /** Say it is over, once: the platform's own `close` and `close()` may each be first. */
+  const finish = (): void => {
+    if (closed) {
+      return;
+    }
+    closed = true;
+    options.actions.closed();
+  };
+  const isClosed = (): boolean => closed;
+
+  const { actions } = options;
+  const scope: AddNewScope = reactive<AddNewScope>({
+    ...derive(options.view),
+    choose: actions.choose,
+    closed: finish,
+    confirm: actions.confirm,
+    dragOut: actions.dragOut,
+    dragOver: actions.dragOver,
+    drop: actions.drop,
+    pickCollection: actions.pickCollection,
+    pickComponentStart: actions.pickComponentStart,
+    pickCopy: actions.pickCopy,
+    pickKind: actions.pickKind,
+    pickLocale: actions.pickLocale,
+    pickPageTemplate: actions.pickPageTemplate,
+    pickStart: actions.pickStart,
+    pickWrap: actions.pickWrap,
+    setName: (value: string) => {
+      /* What the control holds, first and unconditionally. A binding only writes when the scope
+         CHANGES, so a surface that did not echo the raw value would leave the field showing text
+         the scope does not have (`studio-ui-guidelines.md` §9.3). */
+      scope.name = value;
+      actions.setName(value);
+    },
+    setLocalized: actions.setLocalized,
+    setOwnPage: actions.setOwnPage,
+    setUrl: (value: string) => {
+      scope.url = value;
+      actions.setUrl(value);
+    },
+    toggleUrl: actions.toggleUrl,
+    togglePreset: actions.togglePreset,
+  });
+
+  let mounted: SurfaceHandle | null = null;
+
+  /**
+   * Put the caret in the name field, selected.
+   *
+   * On open only: the name is the only thing the dialog requires, so it is where the reader is
+   * about to type. A focus move is the one thing a surface may reach into its document for (`ui.md`
+   * §2 rule 5).
+   */
+  const focusName = (): void => {
+    setTimeout(() => {
+      const root = mounted?.root;
+      if (closed || !(root instanceof HTMLElement)) {
+        return;
+      }
+      const control = root.querySelector<HTMLElement>('jx-textfield[part="name"]');
+      if (control) {
+        selectValue(control, "all");
+      }
+    }, 0);
+  };
+
+  const ready = mountSurface("add-new", scope, slot).then(async (surface) => {
+    mounted = surface;
+    /* SAFETY: `add-new.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 (isClosed()) {
+      surface.dispose();
+      return element;
+    }
+    await whenReady(element);
+    if (isClosed()) {
+      return element;
+    }
+    showModal(element);
+    if (scope.named) {
+      focusName();
+    }
+    return element;
+  });
+
+  return {
+    close() {
+      /* Idempotent line by line rather than guarded on `closed`: the platform's own `close` runs
+         `finish()` first, and a guard would leave this slot behind in the layer. */
+      const element = mounted?.root;
+      if (element instanceof HTMLElement) {
+        close(element);
+      }
+      mounted?.dispose();
+      mounted = null;
+      slot.remove();
+      finish();
+    },
+    host: slot,
+    ready,
+    update(view) {
+      /* Never a focus move here. A kind switch from the keyboard is an arrow key inside the kinds
+         radiogroup, and pulling the caret into the name field would end the walk after one step;
+         the name keeps its value across kinds and Tab reaches it next. */
+      Object.assign(scope, derive(view));
+    },
+  };
+}

package/src/surfaces/ai-chat.ts

@@ -514,8 +514,8 @@ export function mountAiChatSurface(
     }
   }
 
-  /* There is no `connected()` here, where `doc-header.ts` and `panel-stylebook-layers.ts` both
-     have one. Those two mount into a node LIT repaints, so "is my root still where I put it" is a
+  /* There is no `connected()` here, where `panel-stylebook-layers.ts` has one. That one mounts
+     into a node LIT repaints, so "is my root still where I put it" is a
      live question. The assistant's container is built once for the life of the window
      (`right-panel.ts`'s `_ensureContainers`) and nothing else ever writes into it, so the answer
      would be a constant — and a constant nobody reads is a second thing to keep in step. */

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/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/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,7 +23,7 @@
  *
  * **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
@@ -66,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[];