@jxsuite/studio 4.1.0 → 5.1.0

package/src/panels/frontmatter-panel.ts

@@ -28,23 +28,46 @@
  *
  * **The card has no host of its own.** `#frontmatter-panel` — the grid row, the `hidden` div, the
  * `frontmatterPanelEl` ref and the 40vh cap that came with them — is deleted. The STAGE renders the
- * host now ({@link attachDocumentHeaderHost}, called from a `ref` in `canvas/canvas-render.ts`), so
- * the card sits inside the artefact rather than in a band above it. This module keeps only the
- * focus-aware scheduler and the reactive effect, because a field commit must still repaint the card
- * WITHOUT repainting the canvas — a full canvas render remounts the document iframe.
+ * host now ({@link attachDocumentHeaderHost}, called from the stage document's `onNodeCreated` in
+ * `canvas/canvas-render.ts`), so the card sits inside the artefact rather than in a band above it.
+ *
+ * **The card is a Jx document now** (`src/surfaces/doc-header.json`), and this module is the flow
+ * behind it: it decides which document a pane's card is drawn for, which rows that document has,
+ * what each row commits into and where a media or reference row gets its choices, then hands the
+ * surface a projection whose every field is already a string. Three things follow.
+ *
+ * **The focus-aware scheduler is gone, and nothing replaced it.** `panels/panel-scheduler.ts`
+ * existed to withhold a repaint while a text input in the card had focus, because a lit re-render
+ * rebuilt every control and truncated whatever was being typed into one. A document binds each
+ * value on its own runtime effect and skips a write equal to what the control already holds
+ * (specs/studio-ui-guidelines.md §9.3), so a projection that changed one field repaints one field
+ * and a projection that changed nothing repaints nothing. There is no window left to withhold.
+ *
+ * **ONE row vocabulary.** Title, the Layout picker and every schema-driven frontmatter field are
+ * the same row, told apart by which control they draw; what makes them different is what they
+ * WRITE, and that is this module's business rather than the document's. {@link RowCommit} is that
+ * table, rebuilt with each projection and reached by the row's `key` — which is why a row's key and
+ * its `data-prop` are two different strings: a collection whose schema declares a `layout` property
+ * would otherwise collide with the Layout picker.
+ *
+ * **Two widgets are borrowed as BEHAVIOUR rather than as markup.** The media browser
+ * (`ui/media-picker.ts`) renders into the popover layer rather than into the field, and the entry
+ * ids behind a `#/content/<type>` reference are a read (`ui/form-controls.ts`), so the card draws
+ * its own control for each and calls the owner for the part that is not markup. Neither module's
+ * lit template is interpolated here — a document and a lit template cannot share a container, and
+ * §9.4 forbids the mix outright.
+ *
+ * @docs studio/editing/frontmatter
  */
 
-import { html, nothing, render as litRender } from "lit-html";
 import { projectState } from "../store";
 import { workspace } from "../workspace/workspace";
 import { tabOfPane } from "../canvas/canvas-surface";
 import { paneRegion } from "../ui/regions";
 import { effect, effectScope } from "../reactivity";
-import { createPanelScheduler } from "./panel-scheduler";
-import { collectFmFields, renderFmField } from "./frontmatter-fields";
-import { renderFieldRow } from "../ui/field-row";
-import { spTextField } from "../ui/field-input";
-import { transact } from "../tabs/transact";
+import { collectFmFields, projectFmField } from "./frontmatter-fields";
+import { LIVE_PREVIEW } from "../ui/timing";
+import { mutateUpdateFrontmatter, transact, transactDoc } from "../tabs/transact";
 import { pageRoute } from "./tab-strip";
 import {
   RESERVED_FM_KEYS,
@@ -54,25 +77,58 @@ import {
   entryValue,
   isPageDocument,
   isManagedEntry,
-  renderLayoutPickerRow,
+  layoutPickerEntries,
 } from "./head-panel";
 import { isGoogleFontEntry, isGoogleFontPreconnect } from "../utils/google-fonts";
 import { activeRegistry } from "../commands/active-registry";
+import { invalidateLayoutCache } from "../site-context";
+import { mountDocHeaderSurface } from "../surfaces/doc-header";
 
 import type { JxHeadEntry, JxMutableNode } from "@jxsuite/schema/types";
 import type { Tab } from "../tabs/tab";
-import type { PanelScheduler } from "./panel-scheduler";
-import type { TemplateResult } from "lit-html";
+import type { FmSchemaEntry } from "./frontmatter-fields";
+import type * as MediaPickerModule from "../ui/media-picker";
+import type {
+  DocHeaderActions,
+  DocHeaderChoice,
+  DocHeaderRawEntry,
+  DocHeaderRow,
+  DocHeaderSurface,
+  DocHeaderView,
+} from "../surfaces/doc-header";
+
+/** What one row of the card writes. The document knows the control; this knows the document. */
+interface RowCommit {
+  /** Remove the value this row shows. */
+  clear: () => void;
+  /** Commit what the control settled on — a string from every kind but the checkbox. */
+  commit: (raw: string | boolean) => void;
+}
 
 /**
- * The card's host and scheduler, per PANE.
+ * One pane's card: the node the stage gave it, the mounted surface, its commit table and the
+ * actions the surface was handed.
  *
  * A single `_host` was the same singleton every other stage-content module had, and it produced a
  * subtler failure than most: the stage hands the host over from a lit `ref`, so with two stages
  * drawing a header the second `ref` to fire silently took the card away from the first, leaving one
  * pane's Document Header frozen on the frontmatter of the moment it lost the handle.
  */
-const _hosts = new Map<string, { el: HTMLElement; scheduler: PanelScheduler }>();
+interface HeaderCard {
+  /** The pane this card is drawn for. Held rather than looked up: an action has to answer it. */
+  paneId: string;
+  el: HTMLElement;
+  /** `null` until the pane's document first has a header to draw. */
+  surface: DocHeaderSurface | null;
+  /** This pane's rows, by key. Rebuilt with each projection. */
+  commits: Map<string, RowCommit>;
+  /** Handed to the surface once, when it is mounted; every one of them reads `commits`. */
+  actions: DocHeaderActions;
+  /** Text edits waiting out {@link LIVE_PREVIEW}, one per row key. */
+  pending: Map<string, { commit: () => void; timer: ReturnType<typeof setTimeout> }>;
+}
+
+const _hosts = new Map<string, HeaderCard>();
 let _scope: { stop: () => void; run: <T>(fn: () => T) => T | undefined } | null = null;
 
 /** Per-document disclosure state, keyed by tab id — not stored on the document. */
@@ -82,9 +138,7 @@ const _rawOpen = new Set<string>();
  * The element the stage has made available for the card, or `null` while no stage hosts it.
  *
  * Called from a lit `ref` in `canvas/canvas-render.ts`, so the host's lifetime is the stage's: the
- * canvas creates it when it draws a document that has a header and drops it otherwise. The
- * scheduler is re-created per host because it binds `focusin`/`focusout` to that exact node, and
- * the focus guard is the whole reason this module still owns a render path of its own.
+ * canvas creates it when it draws a document that has a header and drops it otherwise.
  *
  * @param {HTMLElement | null} el
  */
@@ -93,24 +147,33 @@ export function attachDocumentHeaderHost(paneId: string, el: HTMLElement | null)
   if (held?.el === el) {
     return;
   }
-  held?.scheduler.unbind();
-  _hosts.delete(paneId);
+  if (held) {
+    takeDown(held);
+    _hosts.delete(paneId);
+  }
   if (!el) {
     return;
   }
-  const scheduler = createPanelScheduler({ render: () => _doRender(paneId), root: el });
-  _hosts.set(paneId, { el, scheduler });
-  scheduler.bindFocus();
-  scheduler.schedule();
+  const card: HeaderCard = {
+    actions: {} as DocHeaderActions,
+    commits: new Map(),
+    el,
+    paneId,
+    pending: new Map(),
+    surface: null,
+  };
+  card.actions = makeActions(card);
+  _hosts.set(paneId, card);
+  paint(paneId, card);
 }
 
-/**
- * The host the stage last handed over, or `null`. The stage reads it back to settle Lit's
- * order-independent detach report; nothing else needs to know where the card lives.
- */
-export function documentHeaderHost(paneId: string): HTMLElement | null {
-  return _hosts.get(paneId)?.el ?? null;
-}
+/* There is no `documentHeaderHost` getter any more, and its absence is the point.
+   It existed for ONE caller: the stage's lit `ref`, which was told about a removal WITHOUT being
+   told which node had gone, so it had to read the host back and ask whether it was still connected
+   before deciding the report was about the host it held. `surfaces/canvas-stage.json` states both
+   placements as a view, so a frame that draws no card simply announces none and `renderCanvasImpl`
+   releases the slot in one place — there is nothing left to settle after the fact, and a getter
+   whose only reader is gone is a fact about the module nobody is entitled to. */
 
 /**
  * Mount the Document Header card: subscribe to the tab / document / frontmatter reads it renders
@@ -151,13 +214,24 @@ export function mount() {
 export function unmount() {
   _scope?.stop();
   _scope = null;
-  for (const { scheduler } of _hosts.values()) {
-    scheduler.unbind();
+  for (const card of _hosts.values()) {
+    takeDown(card);
   }
   _hosts.clear();
   _rawOpen.clear();
 }
 
+/** Take one pane's card down: cancel its waiting edits and dispose the document it mounted. */
+function takeDown(card: HeaderCard): void {
+  for (const { timer } of card.pending.values()) {
+    clearTimeout(timer);
+  }
+  card.pending.clear();
+  card.surface?.dispose();
+  card.surface = null;
+  card.commits.clear();
+}
+
 /** Each pane's tab, deduplicated — the set of documents a header could be drawn for. */
 function paneTabs(): Tab[] {
   const tabs: Tab[] = [];
@@ -171,12 +245,15 @@ function paneTabs(): Tab[] {
 }
 
 /**
- * Request a render. Coalesced and deferred while a text input in the card is focused, so re-renders
- * never clobber a field mid-edit.
+ * Repaint every card.
+ *
+ * Coalescing is the runtime's now: a projection assigns to a standing scope and each binding
+ * re-runs only where the value it reads has changed, so calling this twice in one tick costs one
+ * comparison per binding rather than two renders.
  */
 export function render() {
-  for (const { scheduler } of _hosts.values()) {
-    scheduler.schedule();
+  for (const [paneId, card] of _hosts) {
+    paint(paneId, card);
   }
 }
 
@@ -207,204 +284,351 @@ export function hasDocumentHeader(tab: Tab): boolean {
   return isPageDocument(tab);
 }
 
-function _doRender(paneId: string) {
-  const host = _hosts.get(paneId)?.el;
-  if (!host) {
-    return;
-  }
+/**
+ * Draw (or take down) one pane's card.
+ *
+ * The surface is only ever mounted ONCE per host and assigned to afterwards. Rebuilding it on a
+ * repaint would take a field out from under a reader mid-edit, which is the failure the scheduler
+ * this conversion deletes was built to prevent; `connected()` answers the one case assignment
+ * cannot, a stage that redrew and took the card's root away.
+ */
+function paint(paneId: string, card: HeaderCard): void {
   const tab = tabOfPane(paneId);
   if (!tab || !hasDocumentHeader(tab)) {
-    // The stage decides whether the host exists; this only covers the window between a document
-    // Losing its header and the canvas noticing. Lit leaves comment markers, so `:empty` cannot be
-    // The signal and the host is hidden explicitly.
-    litRender(nothing, host);
-    host.hidden = true;
+    /* The stage decides whether the host exists; this only covers the window between a document
+       losing its header and the canvas noticing. */
+    takeDown(card);
+    card.el.replaceChildren();
+    card.el.hidden = true;
+    return;
+  }
+  const view = viewFor(tab, paneId, card);
+  card.el.hidden = false;
+  if (card.surface?.connected()) {
+    card.surface.update(view);
     return;
   }
-  litRender(documentHeaderTemplate(tab, paneId), host);
-  host.hidden = false;
+  card.surface?.dispose();
+  card.surface = mountDocHeaderSurface(card.el, view, card.actions);
 }
 
+// ─── The projection ──────────────────────────────────────────────────────────
+
 /**
- * The card.
+ * Everything the card says about one document, and the commit table behind it.
  *
- * Exported as a template because the STAGE hosts it: `canvas-render.ts` emits the host div and this
- * module paints into it. The region id (`pane.primary/frontmatter`) rides on the `<section>` rather
- * than on a shell host, which is what made the move a layout change instead of a rename — the id
- * names the card's PLACE in the pane, and the pane still has one.
+ * `tab`, not `activeTab` — the card is drawn for the pane that mounted it. Both branches of the
+ * commit path resolved through FOCUS once, so with two panes the visible card's controls edited
+ * whichever document happened to be focused: click "Clear title" on the card in the left pane and
+ * the field disappeared from the right pane's document instead.
  *
  * @param {Tab} tab
- * @returns {TemplateResult}
+ * @returns {DocHeaderView}
  */
-export function documentHeaderTemplate(tab: Tab, paneId: string): TemplateResult {
+function viewFor(tab: Tab, paneId: string, card: HeaderCard): DocHeaderView {
   const isContent = tab.doc.mode === "content";
   const fm = (tab.doc.content?.frontmatter ?? {}) as Record<string, unknown>;
   // ONE view of the document's head material, whichever realm it lives in: frontmatter keys for a
   // Markdown page, root properties for a JSON one.
   const headDoc = isContent ? buildHeadDoc(tab.doc.document, fm) : tab.doc.document;
-  /*
-   * `tab`, not `activeTab` — the card is drawn for the pane that mounted it, and every other line
-   * in this template already reads that. Both branches resolved through FOCUS, so with two panes
-   * the visible card's controls edited whichever document happened to be focused: click "Clear
-   * title" on the card in the left pane and the field disappears from the right pane's document
-   * instead. Invisible with one stage, which is why it survived the pane keying.
-   *
-   * **The first fix reached the JSON branch only, and the comment here said it was done.** A
-   * markdown page takes the CONTENT branch, where `applyContentMutation` resolved the focus for
-   * itself one call deeper — and `renderFmField` below did the same at each of its seven widgets.
-   * Both take their tab now, so the whole card commits into one document: the one it is showing.
-   */
   const applyMutation = isContent
     ? (fn: (doc: JxMutableNode) => void) => applyContentMutation(tab, render, fn)
     : (fn: (doc: JxMutableNode) => void) => {
         transact(tab, fn);
       };
 
+  const commits = new Map<string, RowCommit>();
+  const rows: DocHeaderRow[] = [titleRow(headDoc, applyMutation, commits)];
+  const layout = layoutRow(tab, headDoc, applyMutation, commits);
+  if (layout) {
+    rows.push(layout);
+  }
+
   // ONE call. The old pair of surfaces made two, with two different reserved-key policies.
   const { collection, fields, requiredFields } = collectFmFields(
     tab,
     projectState?.projectConfig,
     RESERVED_FM_KEYS,
   );
+  for (const f of fields) {
+    rows.push(fieldRow(tab, f.field, f.entry, f.value, requiredFields, commits));
+  }
+  card.commits = commits;
 
   const route = tab.documentPath ? pageRoute(tab.documentPath) : null;
-  const title = typeof headDoc.title === "string" ? headDoc.title : "";
-  const head = headDoc.$head ?? [];
+  const raw = rawEntries(headDoc.$head ?? []);
+  return {
+    collection: collection ? collection.name : "Document",
+    hasRoute: route !== null,
+    /* The stage's two placements, read off the host it handed over. In Edit the card is a block of
+       the document's own column; in Design it is pinned above a pan/zoom surface at 1:1, and only
+       that one wants the band's edge rather than the card's. `surfaces/canvas-stage.json` says the
+       same thing from the STAGE's side, which a document's own scoped style block cannot answer —
+       and it says it on `data-placement` rather than on a class, because the stage emits none. */
+    placement: card.el.dataset["placement"] === "pinned" ? "pinned" : "in-column",
+    rawEntries: raw,
+    rawOpen: _rawOpen.has(tab.id),
+    rawState: raw.length === 0 ? "empty" : "list",
+    region: paneRegion(paneId, "frontmatter"),
+    route: route ?? "",
+    rows,
+  };
+}
+
+/** A blank row, so every kind carries every field the document's bindings read. */
+function blankRow(key: string, prop: string, label: string): DocHeaderRow {
+  return {
+    checked: false,
+    clearLabel: `Clear ${prop}`,
+    hasNote: false,
+    hasThumb: false,
+    isSet: false,
+    key,
+    kind: "text",
+    label,
+    note: "",
+    options: [],
+    placeholder: "",
+    prop,
+    thumb: "",
+    value: "",
+  };
+}
 
-  return html`
-    <section
-      class="doc-header"
-      aria-label="Document header"
-      data-jx-region=${paneRegion(paneId, "frontmatter")}
-    >
-      <header class="doc-header-bar">
-        <span class="doc-header-title">${collection ? collection.name : "Document"}</span>
-        ${
-          route === null
-            ? nothing
-            : html`<code class="doc-header-route" title="This page's route">${route}</code>`
+/** The one head value you type while writing, in both realms. */
+function titleRow(
+  headDoc: JxMutableNode,
+  applyMutation: (fn: (doc: JxMutableNode) => void) => void,
+  commits: Map<string, RowCommit>,
+): DocHeaderRow {
+  const title = typeof headDoc.title === "string" ? headDoc.title : "";
+  commits.set("title", {
+    clear: () =>
+      applyMutation((d) => {
+        delete d.title;
+      }),
+    commit: (raw) =>
+      applyMutation((d) => {
+        const val = String(raw).trim();
+        if (val) {
+          d.title = val;
+        } else {
+          delete d.title;
         }
-      </header>
-      <div class="doc-header-body">
-        ${renderFieldRow({
-          hasValue: Boolean(title),
-          label: "Title",
-          onClear: () =>
-            applyMutation((d) => {
-              delete d.title;
-            }),
-          prop: "title",
-          widget: spTextField(
-            "doc-header:title",
-            title,
-            (v: string) =>
-              applyMutation((d) => {
-                const val = v.trim();
-                if (val) {
-                  d.title = val;
-                } else {
-                  delete d.title;
-                }
-              }),
-            { placeholder: "Untitled" },
-          ),
-        })}
-        ${isPageDocument(tab) ? renderLayoutPickerRow(headDoc, applyMutation) : nothing}
-        ${fields.map((f) => renderFmField(tab, f.field, f.entry, f.value, requiredFields))}
-      </div>
-      ${seoButtonRow()} ${disclosure(tab.id, _rawOpen, "Raw head tags", rawHeadBody(head))}
-    </section>
-  `;
+      }),
+  });
+  return {
+    ...blankRow("title", "title", "Title"),
+    clearLabel: "Clear title",
+    isSet: Boolean(title),
+    placeholder: "Untitled",
+    value: title,
+  };
 }
 
 /**
- * The door to Search appearance (`panels/seo-modal.ts`).
+ * The layout picker, or `null` when this document takes none — a component has no layout, and a
+ * page whose layouts directory is still being listed has nothing to offer yet.
  *
- * A row rather than a disclosure, because what is behind it is a surface and not more of this card.
- * It runs the COMMAND rather than calling `openSeoModal` — the Page panel offers the same door and
- * neither of them should own it.
+ * The listing is `head-panel.ts`'s, asked for as data: the Page panel draws the same choices from
+ * the same cache, so creating a layout invalidates one thing rather than two.
  */
-function seoButtonRow(): TemplateResult {
-  return html`
-    <div class="doc-header-seo">
-      <sp-action-button
-        quiet
-        size="s"
-        class="doc-header-seo-btn"
-        @click=${() => {
-          void activeRegistry()?.run("document.openSeo");
-        }}
-      >
-        <sp-icon-search slot="icon"></sp-icon-search>
-        Search appearance…
-      </sp-action-button>
-    </div>
-  `;
+function layoutRow(
+  tab: Tab,
+  headDoc: JxMutableNode,
+  applyMutation: (fn: (doc: JxMutableNode) => void) => void,
+  commits: Map<string, RowCommit>,
+): DocHeaderRow | null {
+  if (!isPageDocument(tab)) {
+    return null;
+  }
+  const entries = layoutPickerEntries();
+  if (entries === null) {
+    return null;
+  }
+  const current = headDoc.$layout;
+  const defaultPath = projectState?.projectConfig?.defaults?.layout;
+  const defaultLabel = defaultPath ? layoutName(defaultPath) : "";
+  const options: DocHeaderChoice[] = [
+    { label: defaultLabel ? `Default (${defaultLabel})` : "Default", value: "__default__" },
+    { label: "None", value: "__none__" },
+    ...entries.map((l) => ({ label: l.name, value: l.path })),
+  ];
+  commits.set("__layout", {
+    clear: () =>
+      applyMutation((d) => {
+        delete d.$layout;
+      }),
+    commit: (raw) => {
+      const val = String(raw);
+      applyMutation((d) => {
+        if (val === "__default__") {
+          delete d.$layout;
+        } else if (val === "__none__") {
+          d.$layout = false;
+        } else {
+          d.$layout = val;
+        }
+      });
+      invalidateLayoutCache();
+    },
+  });
+  return {
+    ...blankRow("__layout", "layout", "Layout"),
+    isSet: current !== undefined,
+    kind: "select",
+    options,
+    value: current === false ? "__none__" : current || "__default__",
+  };
+}
+
+/** `./layouts/blog-post.json` → `Blog Post`. */
+function layoutName(path: string): string {
+  return path
+    .replace(/^\.\/layouts\//, "")
+    .replace(/\.json$/, "")
+    .replaceAll(/[-_]+/g, " ")
+    .replaceAll(/\b\w/g, (c: string) => c.toUpperCase());
 }
 
 /**
- * A collapsible block whose open state is per tab and lives in this module.
+ * One schema-driven frontmatter field, as the row that draws it and the write that commits it.
  *
- * Deliberately NOT on `tab.session.ui`: P3's first workstream is hoisting view flags OUT of the tab
- * record, and adding two more would be moving in the wrong direction for a disclosure nobody needs
- * restored across a relaunch.
+ * **What the row LOOKS like is `panels/frontmatter-fields.ts`'s answer, not this module's.** The
+ * Navigator's Page panel draws the same field set from the same schemas, and the two surfaces
+ * deciding independently that a `$ref` is a picker, that `"uri-reference"` is a media format or
+ * that an array is a comma-separated line is exactly how they came to disagree about `title`. What
+ * stays here is what the card COMMITS INTO — this tab's frontmatter, through its transaction log.
+ *
+ * `tab` is a parameter because this used to commit to `activeTab.value` at each of seven widgets,
+ * which is right for the Navigator's Document panel and wrong for a card drawn once per pane: a
+ * collection field edited on the card in one pane wrote into whichever document had the keyboard.
  */
-function disclosure(
-  tabId: string,
-  open: Set<string>,
-  label: string,
-  body: TemplateResult,
-): TemplateResult {
-  const isOpen = open.has(tabId);
-  return html`
-    <details
-      class="doc-header-disclosure"
-      ?open=${isOpen}
-      @toggle=${(e: Event) => {
-        const el = e.target as HTMLDetailsElement;
-        if (el.open) {
-          open.add(tabId);
-        } else {
-          open.delete(tabId);
-        }
-      }}
-    >
-      <summary>${label}</summary>
-      <div class="doc-header-body">${body}</div>
-    </details>
-  `;
+function fieldRow(
+  tab: Tab,
+  field: string,
+  entry: FmSchemaEntry,
+  value: unknown,
+  requiredFields: Set<string>,
+  commits: Map<string, RowCommit>,
+): DocHeaderRow {
+  const key = `fm:${field}`;
+  const { parse, row } = projectFmField(field, entry, value, requiredFields, { rerender: render });
+  commits.set(key, {
+    clear: () => transactDoc(tab, (t) => mutateUpdateFrontmatter(t, field)),
+    commit: (raw) => transactDoc(tab, (t) => mutateUpdateFrontmatter(t, field, parse(raw))),
+  });
+  return { ...blankRow(key, field, row.label), ...row, clearLabel: `Clear ${field}` };
 }
 
-/* THE SEO BLOCK IS A MODAL — `panels/seo-modal.ts`.
-   Two rendered previews, a resolved-field list, a warning list, the page and Open Graph meta rows
-   and an icon picker, all disclosed inside a card whose job is the four or five fields you fill in
-   while writing. A previewed SERP result is not a field; it is a picture you study, and studying it
-   in a strip above the canvas made the card taller than the document it describes. The card keeps
-   Title — the one head value you type while writing — and offers the door. */
-
 /**
  * The `$head` entries no structured control owns, listed read-only.
  *
  * Read-only on purpose: the card discloses what is there so the author is never surprised by a tag
  * they cannot see, and the Page panel remains the surface that adds and removes them.
  */
-function rawHeadBody(head: JxHeadEntry[]): TemplateResult {
-  const custom = head.filter(
-    (e: JxHeadEntry) => !isManagedEntry(e) && !isGoogleFontEntry(e) && !isGoogleFontPreconnect(e),
-  );
-  if (custom.length === 0) {
-    return html`<p class="doc-header-empty">No custom head tags on this document.</p>`;
-  }
-  return html`
-    <ul class="doc-header-raw">
-      ${custom.map(
-        (entry) => html`
-          <li>
-            <code>${entryLabel(entry)}</code>
-            <span title=${entryValue(entry)}>${entryValue(entry)}</span>
-          </li>
-        `,
-      )}
-    </ul>
-  `;
+function rawEntries(head: JxHeadEntry[]): DocHeaderRawEntry[] {
+  return head
+    .filter(
+      (e: JxHeadEntry) => !isManagedEntry(e) && !isGoogleFontEntry(e) && !isGoogleFontPreconnect(e),
+    )
+    .map((entry, index) => ({
+      key: `raw:${index}`,
+      label: entryLabel(entry),
+      value: entryValue(entry),
+    }));
+}
+
+// ─── The actions ─────────────────────────────────────────────────────────────
+
+/**
+ * What the reader can do on one pane's card.
+ *
+ * Made once per host and handed to the surface at mount, so every one of them reads the CURRENT
+ * commit table rather than closing over the projection that was standing when the card was drawn.
+ */
+function makeActions(card: HeaderCard): DocHeaderActions {
+  const flush = (key: string): void => {
+    const waiting = card.pending.get(key);
+    if (waiting) {
+      clearTimeout(waiting.timer);
+      card.pending.delete(key);
+    }
+  };
+  const now = (key: string, raw: string | boolean): void => {
+    flush(key);
+    card.commits.get(key)?.commit(raw);
+  };
+  return {
+    browse: (key, anchor) => {
+      flush(key);
+      void mediaPicker().then((m) => {
+        if (anchor instanceof HTMLElement) {
+          m.showMediaPickerPopover(anchor, (val: string) => {
+            card.commits.get(key)?.commit(val);
+          });
+        }
+      });
+    },
+    clear: (key) => {
+      flush(key);
+      card.commits.get(key)?.clear();
+    },
+    commitText: (key, value) => now(key, value),
+    /* Debounced, so the canvas follows the typing without a document write per keystroke. The
+       control is NOT reset in the meantime: the projection this commit causes resolves to the text
+       already in the field, and a document binding skips a write equal to what the element holds. */
+    editText: (key, value) => {
+      flush(key);
+      const commit = () => {
+        card.pending.delete(key);
+        card.commits.get(key)?.commit(value);
+      };
+      card.pending.set(key, { commit, timer: setTimeout(commit, LIVE_PREVIEW) });
+    },
+    openSeo: () => {
+      // The COMMAND, not a local open() — the Page panel offers the same door and neither of them
+      // Owns it.
+      void activeRegistry()?.run("document.openSeo");
+    },
+    setBoolean: (key, checked) => now(key, checked),
+    setChoice: (key, value) => now(key, value),
+    setNumber: (key, value) => now(key, value),
+    setRawOpen: (open) => {
+      // Per DOCUMENT rather than per pane: the same file open in two stages discloses the same
+      // Tags, and a flag on the pane would make the two cards disagree about one document.
+      const tab = tabOfPane(card.paneId);
+      if (!tab) {
+        return;
+      }
+      if (open) {
+        _rawOpen.add(tab.id);
+      } else {
+        _rawOpen.delete(tab.id);
+      }
+    },
+    upload: (key) => {
+      flush(key);
+      void mediaPicker().then((m) => {
+        m.pickAndUpload((val: string) => {
+          card.commits.get(key)?.commit(val);
+        });
+      });
+    },
+  };
+}
+
+/**
+ * The media picker's two behaviours, imported on the first press.
+ *
+ * ONE cached promise, deliberately: two dynamic imports of a module in flight at once is the shape
+ * that loses its coverage record (see the note in the repository's agent guide), and the file also
+ * pulls in the upload pipeline and the media metadata cache — neither of which a card that draws no
+ * media field should ever load.
+ */
+let _mediaPicker: Promise<typeof MediaPickerModule> | null = null;
+
+function mediaPicker(): Promise<typeof MediaPickerModule> {
+  _mediaPicker ??= import("../ui/media-picker");
+  return _mediaPicker;
 }