@jxsuite/studio 6.1.1 → 8.0.0

package/src/canvas/canvas-render.ts

@@ -1,16 +1,20 @@
 /// <reference lib="dom" />
 /**
  * Canvas render — extracted from studio.js (Phase 4o). Multi-mode canvas rendering orchestrator:
- * dispatches to manage/settings/source/edit/design/preview rendering paths.
+ * dispatches to source/edit/design/preview rendering paths.
  */
 
-import { render as litRender, nothing } from "lit-html";
+import { render, nothing } from "lit-html";
 import type * as monaco from "monaco-editor";
 import type { WireDiffMarks } from "./iframe-protocol";
 import type * as Y from "yjs";
 import { loadedMonaco, loadMonaco, mountStillWanted } from "../services/monaco-lazy";
 
-import { getNodeAtPath, updateCanvas } from "../store";
+import { getNodeAtPath } from "@jxsuite/schema/doc-ops";
+import { isString } from "@jxsuite/schema/guards";
+import { errorMessage } from "@jxsuite/schema/parse";
+import { stageOf } from "./surface-registry";
+import { updateCanvas } from "../store";
 import { activeTab, tabIsLive, workspace } from "../workspace/workspace";
 import {
   activeMediaOfPane,
@@ -40,21 +44,25 @@ import { canRenderComparison } from "../panels/git-diff-open";
 import { releaseStageScrollbar, trackStageScrollbar } from "./stage-scrollbar";
 import { renderDiffToolbar, setDiffRepaint, setDiffToolbarHost } from "./diff-toolbar";
 import { attachCursorStyles } from "../collab/monaco-cursors";
-import type { AwarenessLike } from "../collab/monaco-cursors";
-import type { BindingAwareness } from "../collab/monaco-binding";
 import { monacoTheme, shell } from "../shell";
 import { parseSourceForPath } from "../files/file-ops";
 import { serializeDocument } from "../files/serialize-document";
 import { parseJsonDocument, serializeJson } from "@jxsuite/schema/json-layout";
 import { detachGridPanel, gridPanelMounted, renderGridMode } from "../grid/grid-panel";
-import { detachLibraryPane, libraryPaneMounted, renderLibraryMode } from "../browse/library-pane";
 import { detachEntryPane, entryPaneMounted, renderEntryMode } from "../content/entry-editor";
 import { detachMediaPane, mediaPaneMounted, renderMediaMode } from "../media/media-pane";
 import {
-  detachSettingsPane,
-  renderSettingsPane,
-  settingsPaneMounted,
-} from "../panels/settings-pane";
+  detachVariablesView,
+  renderVariablesMode,
+  variablesViewMounted,
+} from "../style/variables-view";
+import { PROJECT_VARIABLES_VIEW } from "../style/project-styles";
+import {
+  detachWorkspaceHome,
+  isWorkspaceHomeMode,
+  renderWorkspaceHome,
+  workspaceHomeMounted,
+} from "../workspace/workspace-home";
 import { formatByName, formatForPath } from "../format/format-host";
 import {
   BUFFER_COMMIT,
@@ -64,10 +72,16 @@ import {
   commitBufferWrites,
 } from "../services/monaco-buffer";
 import { noteTyping } from "../tabs/typing";
+import { normalizeDocument } from "../tabs/bare-repeaters";
 import { diffModelUrisFor, modelUriFor, monacoLangForPath } from "../services/model-uri";
 import { renderWelcome } from "../surfaces/welcome";
 import { emptyState } from "../surfaces/empty-state";
-import { attachDocumentHeaderHost, hasDocumentHeader } from "../panels/frontmatter-panel";
+import {
+  attachWritingBanner,
+  detachWritingBanner,
+  renderWritingBanner,
+} from "../content/writing-banner";
+import { writesEntryOnCanvas } from "../content/content-collections";
 import { mountCanvasStage } from "../surfaces/canvas-stage";
 import type {
   CanvasStageActions,
@@ -236,7 +250,7 @@ function hardClearCanvasWrap(canvasWrap: HTMLElement) {
  * the two width handles apart: `data-side`, the one part the stage document draws twice).
  *
  * Per STAGE rather than per module, for the reason every other field on `CanvasSurface` is: two
- * panes each have a Monaco host and a card slot, and one slot would hand the second pane's stage
+ * panes each have a Monaco host and a banner slot, and one slot would hand the second pane's stage
  * the first pane's editor.
  */
 const _stageHosts = new WeakMap<CanvasSurface, Map<string, HTMLElement>>();
@@ -280,8 +294,8 @@ function stageActions(surface: CanvasSurface): CanvasStageActions {
       stageHosts(surface).set(detail ? `${part}:${detail}` : part, element);
       if (part === "panzoom") {
         surface.panzoomWrap = element;
-      } else if (part === "doc-header") {
-        attachDocumentHeaderHost(surface.paneId, element);
+      } else if (part === "writing-banner") {
+        attachWritingBanner(surface.paneId, element);
       } else if (part === "diff-toolbar") {
         setDiffToolbarHost(surface.paneId, element);
       }
@@ -317,10 +331,10 @@ function drawStage(
   entries: CanvasPanelEntry[],
 ): Promise<CanvasStageHandle | null> {
   _stageEntries.set(surface, entries);
-  /* There is no card-host release here, and there must not be one: `renderCanvasImpl` already
-     releases it for EVERY mode that draws no header, one branch above this one. A second answer to
+  /* There is no banner-host release here, and there must not be one: `renderCanvasImpl` already
+     releases it for EVERY mode that draws no banner, one branch above this one. A second answer to
      the same question is how the two drift — and this one would answer only for the frames that
-     reach a stage, leaving grid, library, entry, media and settings to the first. */
+     reach a stage, leaving grid, the homes, entry and media to the first. */
   const standing = surface.stage;
   const stage = standing ?? mountCanvasStage(surface.wrap, view, stageActions(surface));
   surface.stage = stage;
@@ -362,9 +376,8 @@ function editorStageView(frame: "source" | "code"): CanvasStageView {
  * Release this pane's stage document.
  *
  * Called on a real mode transition and on a full reset — the two moments the structure standing on
- * the stage stops being the stage's. The two hosts that are handed to another module go WITH it: a
- * card slot or a Compare bar pointing at a detached node is a surface that draws into nothing and
- * never says so.
+ * the stage stops being the stage's. The host handed to another module goes WITH it: a Compare bar
+ * pointing at a detached node is a surface that draws into nothing and never says so.
  *
  * @param {CanvasSurface} surface
  */
@@ -376,7 +389,6 @@ function detachCanvasStage(surface: CanvasSurface): void {
   surface.stage = null;
   _stageHosts.delete(surface);
   _stageEntries.delete(surface);
-  attachDocumentHeaderHost(surface.paneId, null);
   setDiffToolbarHost(surface.paneId, null);
 }
 
@@ -412,13 +424,15 @@ async function createSourceCollabBinding(
 ): Promise<() => void> {
   const { bindMonacoToYText } = await import("../collab/monaco-binding");
   const unbind = bindMonacoToYText({
-    awareness: ctx.awareness as unknown as BindingAwareness,
+    awareness: ctx.awareness,
     editors: [editor],
     model,
     origin: ctx.localOrigin,
+    /* SAFETY: collabSourceContext's `text` is `collab.sourceText(handle.doc)`, the session's shared
+       source Y.Text, attached to the handle's Y.Doc as the binding requires. */
     text: ctx.text as Y.Text,
   });
-  const detachStyles = attachCursorStyles(ctx.awareness as unknown as AwarenessLike, document);
+  const detachStyles = attachCursorStyles(ctx.awareness, document);
   return () => {
     detachStyles();
     unbind();
@@ -558,7 +572,7 @@ function sideMarks(
  */
 async function mountDiffEditor(
   surface: CanvasSurface,
-  container: Element,
+  container: HTMLElement,
   state: GitDiffState,
 ): Promise<void> {
   const { paneId } = surface;
@@ -589,17 +603,20 @@ async function mountDiffEditor(
     lang,
     monaco.Uri.parse(uris.work),
   );
-  const editor = monaco.editor.createDiffEditor(container as HTMLElement, {
-    automaticLayout: true,
-    fontFamily: "'JetBrains Mono', 'SF Mono', 'Fira Code', 'Consolas', monospace",
-    fontSize: 12,
-    minimap: { enabled: false },
-    originalEditable: false,
-    readOnly: true,
-    renderSideBySide: true,
-    scrollBeyondLastLine: false,
-    theme: monacoTheme(),
-  }) as NonNullable<CanvasSurface["monacoDiffEditor"]>;
+  const editor: NonNullable<CanvasSurface["monacoDiffEditor"]> = monaco.editor.createDiffEditor(
+    container,
+    {
+      automaticLayout: true,
+      fontFamily: "'JetBrains Mono', 'SF Mono', 'Fira Code', 'Consolas', monospace",
+      fontSize: 12,
+      minimap: { enabled: false },
+      originalEditable: false,
+      readOnly: true,
+      renderSideBySide: true,
+      scrollBeyondLastLine: false,
+      theme: monacoTheme(),
+    },
+  );
   editor.setModel({ modified, original });
   editor._diffKey = key;
   surface.monacoDiffEditor = editor;
@@ -609,10 +626,11 @@ function resetCanvasView(surface: CanvasSurface) {
   const canvasWrap = surface.wrap;
   const { paneId } = surface;
   detachGridPanel(paneId);
-  detachLibraryPane(paneId);
   detachEntryPane(paneId);
+  detachWritingBanner(paneId);
   detachMediaPane(paneId);
-  detachSettingsPane(paneId);
+  detachVariablesView(paneId);
+  detachWorkspaceHome(paneId);
   disposeSourceCollab(surface);
   disposeSourceEditor(surface);
   disposeDiffEditor(surface);
@@ -663,7 +681,7 @@ function resetCanvasView(surface: CanvasSurface) {
 async function mountSourceEditor(
   tab: Tab,
   surface: CanvasSurface,
-  editorContainer: Element,
+  editorContainer: HTMLElement,
   filePath: string,
   lang: string,
 ): Promise<void> {
@@ -757,7 +775,7 @@ async function mountSourceEditor(
   // Typed as the surface `view` declares (the editor plus `_ignoreNextChange` / `_writes`), because
   // The instance is HELD here now rather than re-read off `view.monacoEditor` in every callback.
   const sourceEditor: NonNullable<typeof surface.monacoEditor> = monaco.editor.create(
-    editorContainer as unknown as HTMLElement,
+    editorContainer,
     {
       automaticLayout: true,
       fontFamily: "'JetBrains Mono', 'SF Mono', 'Fira Code', 'Consolas', monospace",
@@ -832,8 +850,10 @@ async function mountSourceEditor(
           if (!tabIsLive(tab)) {
             return;
           }
-          tab.doc.document = document as JxMutableNode;
+          tab.doc.document = document;
           tab.doc.content.frontmatter = frontmatter;
+          // The buffer is the author's own spelling now, so it is what the next save keeps.
+          tab.doc.source = sourceEditor.getValue();
           tab.doc.dirty = true;
           writes.markSettled();
         } catch {
@@ -845,7 +865,12 @@ async function mountSourceEditor(
           // The buffer's text is the author's own layout now — the objects they opened up or
           // Closed, the blank lines they left — so it is what the next save preserves.
           const parsed = parseJsonDocument(sourceEditor.getValue());
-          tab.doc.document = parsed.document as JxMutableNode;
+          /* SAFETY: a JSON source tab holds a Jx document, whose schema makes the top-level object
+             parseJsonDocument returns a node; text that does not parse throws into the catch. */
+          const document = parsed.document as JxMutableNode;
+          // The member form every edit assumes, and the record of the bare repeaters the text wrote.
+          tab.doc.bareRepeaters = normalizeDocument(document);
+          tab.doc.document = document;
           tab.doc.layout = parsed.layout;
           tab.doc.dirty = true;
           writes.markSettled();
@@ -930,7 +955,7 @@ function renderDerivationNotice(
   surface.wrap.style.display = "block";
   const registry = activeRegistry();
   const pin = registry?.get("pane.pin");
-  litRender(
+  render(
     emptyState(surface.wrap, {
       message,
       ...(held && { detail: `${tabLabel(held)} is still open here.` }),
@@ -954,7 +979,7 @@ function renderCanvasImpl(surface: CanvasSurface) {
   /* Every read below is scoped to ONE pane. The stage, the panels it mounted and the mode it draws
      are the surface's; the document is whatever tab that pane is showing, which is `activeTab` only
      when the pane is the focused one. */
-  const canvasWrap = surface.wrap;
+  const canvasWrap = stageOf(surface);
   /* A pane with no stage renders nothing — it is not an error and it is not a fallback to some
      other pane's stage. Two schedulers can name a stage-less pane: a frame queued for a pane that
      lost the shell's single stage between the schedule and the rAF, and `escalateToFullRender` on
@@ -970,7 +995,6 @@ function renderCanvasImpl(surface: CanvasSurface) {
     // No active tab — reset every piece of canvas view state so reopening a file can never inherit
     // A stale Lit part, a dead Monaco editor, or a mismatched prevCanvasMode (the toxic states that
     // Previously left the canvas unrenderable until a full reload).
-    attachDocumentHeaderHost(surface.paneId, null);
     resetCanvasView(surface);
     /* A DERIVED pane with nothing to draw explains itself. It is not the welcome screen and it is
        not a blank stage: it is a standing rule that has not resolved — "Select an element inside a
@@ -1000,7 +1024,6 @@ function renderCanvasImpl(surface: CanvasSurface) {
      follow has run and a stage that blanked on that would flicker on every retarget. */
   const staleDerivation = derivationOfPane(surface.paneId);
   if (staleDerivation?.status === "unavailable" && staleDerivation.reason) {
-    attachDocumentHeaderHost(surface.paneId, null);
     resetCanvasView(surface);
     /* …and for a COMPANION, what it is still holding. `tab` here is the pane's OWN document for a
        companion and the SOURCE pane's for a lens — the hop `tabOfPane` takes — so the kind decides
@@ -1012,6 +1035,8 @@ function renderCanvasImpl(surface: CanvasSurface) {
     );
     return;
   }
+  /* SAFETY: `initCanvasRender` runs at studio boot (studio.ts), before the shell schedules the first
+     pane render, and nothing resets `_ctx` afterwards. */
   const ctx = _ctx as CanvasRenderCtx;
   const S = {
     document: tab.doc.document,
@@ -1024,28 +1049,19 @@ function renderCanvasImpl(surface: CanvasSurface) {
   // Re-rendering the previous mode's panels in place.
   const canvasMode = canvasModeOfPane(surface.paneId);
 
-  /* The Document Header card is drawn by the STAGE, and only by Edit's. It is docked
-     above the page's scroller, a band across the pane at 1:1: 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 go
-     INSIDE Edit's column, where it was exactly as wide as whatever breakpoint or dragged width the
-     column had and scrolled off with the first screen of the page, and it was pinned above Design's
-     artboards as well. Design omits it now, so the artboards get the whole pane, and nothing is
-     lost by that: the Navigator's Page panel carries the same fields in every mode.
-     `hasDocumentHeader` is the other predicate, and it is a fact about the DOCUMENT. It used to
-     carry two more clauses, suppressing the card while a function body or a formula was open on
-     the grounds that those sub-editors took the whole stage. They open in the dock's Logic tab now
-     (§16.3) and the page is still on screen behind it, so those clauses only DETACHED the visible
-     card: it stopped re-rendering and quietly showed frontmatter from before the edit. */
-  /* …and NOT in a lens. The Document Header is an editing surface — Title, Route, SEO, the raw
-     frontmatter — over a document this pane does not own, and two cards editing one document's
-     frontmatter side by side is two writers for one field. A lens is a view; the card belongs to
-     the pane that owns the tab. */
-  const wantsDocHeader =
+  /* Edit draws the page and nothing above it (§4.2): a document's settings — title, URL, layout,
+     frontmatter, description, Search appearance — are the Inspector's Page tab's (§6), in every
+     mode, so the stage carries no card of its own and the page starts at the top of the pane.
+     A collection entry written in Edit carries the writing-mode banner (§22.5): the canvas wraps it
+     in its template's layout, and the banner says the layout is locked. Not in a lens: the
+     banner's door belongs to the pane that owns the tab, and a lens is a view. */
+  const wantsWritingBanner =
     canvasMode === "edit" &&
     derivationOfPane(surface.paneId)?.kind !== "lens" &&
-    hasDocumentHeader(tab);
-  if (!wantsDocHeader) {
-    attachDocumentHeaderHost(surface.paneId, null);
+    Boolean(projectState?.isSiteProject) &&
+    writesEntryOnCanvas(tab.documentPath);
+  if (!wantsWritingBanner) {
+    detachWritingBanner(surface.paneId);
   }
 
   /* Advance THIS stage's render generation so stale async renders from its previous pass bail out.
@@ -1154,12 +1170,6 @@ function renderCanvasImpl(surface: CanvasSurface) {
     return;
   }
 
-  // Library fast-path, same shape: the Library pane owns its own reactivity (view state, scan,
-  // Window), so a same-tab re-render while it is mounted needs nothing from the canvas pipeline.
-  if (canvasMode === "manage" && libraryPaneMounted(surface.paneId, tab) && !modeChanged) {
-    return;
-  }
-
   // Entry fast-path, same shape: the entry form owns its own effect over the tab's frontmatter, so
   // A field commit repaints the form and nothing reaches the canvas pipeline.
   if (canvasMode === "entry" && entryPaneMounted(surface.paneId, tab) && !modeChanged) {
@@ -1172,9 +1182,21 @@ function renderCanvasImpl(surface: CanvasSurface) {
     return;
   }
 
-  // Settings fast-path, same shape: the Project Settings editor subscribes to the section registry
-  // And to its own chosen section, so a mounted editor needs nothing from the canvas pipeline.
-  if (canvasMode === "settings" && settingsPaneMounted(surface) && !modeChanged) {
+  // Variables fast-path, same shape: the view follows the document through its own effect.
+  if (
+    canvasMode === PROJECT_VARIABLES_VIEW &&
+    variablesViewMounted(surface.paneId, tab) &&
+    !modeChanged
+  ) {
+    return;
+  }
+
+  // Workspace-home fast-path, same shape: a home is a standing document with nothing to re-render.
+  if (
+    isWorkspaceHomeMode(canvasMode) &&
+    workspaceHomeMounted(surface.paneId, tab) &&
+    !modeChanged
+  ) {
     return;
   }
 
@@ -1191,10 +1213,11 @@ function renderCanvasImpl(surface: CanvasSurface) {
     const curCustomized = shell.stylebook.customizedOnly;
     const filterChanged =
       curFilter !== surface.prevStylebookFilter ||
-      curCustomized !== surface.prevStylebookCustomizedOnly;
+      curCustomized !== surface.prevStylebookCustomizedOnly ||
+      activeMediaOfPane(surface.paneId) !== surface.prevStylebookMedia;
     if (!filterChanged) {
-      const style = transposeStylebookStyle(getEffectiveStyle(tab.doc.document?.style));
-      if (postStyleUpdateToStylebookHosts(style as Record<string, unknown>) > 0) {
+      const style = transposeStylebookStyle(getEffectiveStyle(tab.doc.document.style));
+      if (postStyleUpdateToStylebookHosts(style) > 0) {
         return;
       }
     }
@@ -1238,18 +1261,18 @@ function renderCanvasImpl(surface: CanvasSurface) {
     // Destroy the grid panel if switching away from grid mode
     detachGridPanel(surface.paneId);
 
-    // The Library holds an IntersectionObserver and an LRU of live runtime subtrees; leaving the
-    // Mode without releasing them is exactly the unbounded retention its LRU cap exists to remove.
-    detachLibraryPane(surface.paneId);
-
-    // Same for the entry form, whose effect scope subscribes to the document's frontmatter
+    // The entry form's effect scope subscribes to the document's frontmatter
     detachEntryPane(surface.paneId);
 
     // And for the media viewer, whose effect scope subscribes to the tab's path
     detachMediaPane(surface.paneId);
 
-    // Same for the Project Settings editor, which holds a registry subscription
-    detachSettingsPane(surface.paneId);
+    // And for the Variables view, whose effect scope subscribes to the document's style
+    detachVariablesView(surface.paneId);
+
+    // And for a workspace home, whose surface holds a mounted document (the Content home's
+    // IntersectionObserver and preview LRU among them)
+    detachWorkspaceHome(surface.paneId);
 
     // Dispose Monaco editor if switching away from source mode
     disposeSourceCollab(surface);
@@ -1261,7 +1284,7 @@ function renderCanvasImpl(surface: CanvasSurface) {
        leaving, and lit's part, which the empty-state and welcome paths own. */
     releaseCanvasHosts(canvasWrap);
     detachCanvasStage(surface);
-    litRender(nothing, canvasWrap);
+    render(nothing, canvasWrap);
     surface.panzoomWrap = null;
     // Reset inline style overrides from other modes
     canvasWrap.style.padding = "";
@@ -1282,6 +1305,7 @@ function renderCanvasImpl(surface: CanvasSurface) {
   if (canvasMode === "stylebook") {
     surface.prevStylebookFilter = shell.stylebook.filter;
     surface.prevStylebookCustomizedOnly = shell.stylebook.customizedOnly;
+    surface.prevStylebookMedia = activeMediaOfPane(surface.paneId);
     void renderStylebookMode(surface, {
       applyTransform,
       canvasPanelEntry,
@@ -1360,29 +1384,8 @@ function renderCanvasImpl(surface: CanvasSurface) {
     return;
   }
 
-  /* Settings mode: the Project Settings document (§17.1). Same non-iframe-editor pattern as
-     grid and stylebook — the panel owns its own reactivity from here — and the reason the seven
-     settings screenshots now crop `pane.primary` instead of `overlay.dialog:settings` without one
-     manifest step changing. */
-  if (canvasMode === "settings") {
-    canvasWrap.style.padding = "0";
-    canvasWrap.style.display = "block";
-    renderSettingsPane(surface);
-    return;
-  }
-
-  /* Library mode: the project's own contents, over a GridSource, in one of five layouts
-     (`browse/library-pane.ts`). `commands/context.ts` already mapped `manage` to the `library`
-     editor kind — this is the surface that map was pointing at. */
-  if (canvasMode === "manage") {
-    canvasWrap.style.padding = "0";
-    canvasWrap.style.display = "block";
-    renderLibraryMode(surface, tab);
-    return;
-  }
-
   /* Entry mode: one content entry's fields, typed by its collection's schema
-     (`content/entry-editor.ts`). Same non-iframe-editor pattern as the Library and Settings — and
+     (`content/entry-editor.ts`). Same non-iframe-editor pattern as the grid and the homes — and
      the reason `entry` is in `commands/context.ts`'s mode map, without which a form over a
      frontmatter record would have resolved into the CANVAS key scope. */
   if (canvasMode === "entry") {
@@ -1401,6 +1404,22 @@ function renderCanvasImpl(surface: CanvasSurface) {
     return;
   }
 
+  /* The Styles workspace's Variables view: `project.json`'s CSS custom properties, edited in a
+     form (`style/variables-view.ts`). Like a home, it writes nothing onto the stage: its own style
+     block fills it (`surfaces/styles-variables.json`). */
+  if (canvasMode === PROJECT_VARIABLES_VIEW) {
+    renderVariablesMode(surface, tab);
+    return;
+  }
+
+  /* A workspace's home: the surface a workspace opens on when none of its own tabs is open
+     (`workspace/workspace-home.ts`). Unlike the five above it writes nothing onto the stage: the
+     home's own style block fills it (`surfaces/publish-workspace.json`, for one). */
+  if (isWorkspaceHomeMode(canvasMode)) {
+    renderWorkspaceHome(surface, tab);
+    return;
+  }
+
   // Grid mode: spreadsheet editor over the tab's grid source (mirrors the Monaco/stylebook
   // Non-iframe-editor pattern; the panel owns its own reactivity from here).
   if (canvasMode === "grid") {
@@ -1465,7 +1484,7 @@ function renderCanvasImpl(surface: CanvasSurface) {
        decided rather than the opener: a comparison reaches this branch from three doors (the panel,
        a Diff lens, the Editor axis) and only this one sees every arrival. Forcing it here also
        leaves `diffView` alone, so a document opened after a `.css` still comes up Visual. */
-    const renderable = canRenderComparison(gitDiffState.filePath ?? "");
+    const renderable = canRenderComparison(gitDiffState.filePath);
     if (diffShowsCode(surface.paneId, renderable)) {
       /* A null map is how the toolbar learns there is no visual half to offer: it draws Code as a
          static label rather than as half of a choice, and reports the line marks instead of a node
@@ -1518,12 +1537,15 @@ function renderCanvasImpl(surface: CanvasSurface) {
 
     /** @param {string} content */
     const parseContent = (content: string): Promise<JxMutableNode> => {
-      const fmtPath = gitDiffState.filePath ?? "";
+      const fmtPath = gitDiffState.filePath;
       if (formatForPath(fmtPath)) {
         return parseSourceForPath(fmtPath, content).then((r) => r.document);
       }
       return Promise.resolve().then(() => {
         try {
+          /* SAFETY: a side of a VISUAL comparison is a revision of a document the canvas renders
+             (canRenderComparison chose this half), a JSON Jx document; unparseable text throws into
+             the catch, which draws the failure instead. */
           return JSON.parse(content) as JxMutableNode;
         } catch {
           return {
@@ -1636,31 +1658,26 @@ function renderCanvasImpl(surface: CanvasSurface) {
     const entry = canvasPanelEntry(null, null, true);
     // A component-definition doc (root tag is a custom element) is a fragment, not a page: it should
     // Hug its content rather than have the column fill+stretch to the viewport (dead scroll space).
-    const rootTag = (S.document as { tagName?: unknown }).tagName;
-    const isComponentDoc = typeof rootTag === "string" && rootTag.includes("-");
+    const rootTag = S.document.tagName;
+    const isComponentDoc = isString(rootTag) && rootTag.includes("-");
     const { featureToggles: editToggles } = S.ui;
-    /* The stage stacks when it carries the card: the band first, the page's scroller below it.
-       Set on every render rather than on the transition, because whether a document HAS a header
-       changes with the tab and not with the mode. `editors.ts` and `formula-workspace.ts` already
-       claim the column this way — `#canvas-wrap` is a row by default and each surface states its
-       own axis. Stretched, because the band is as wide as the PANE: that is the whole difference
-       between docking the card here and drawing it in the column, whose width is the breakpoint's
-       or the drag's.
-       And FLUSH: the cell's own 24px gap (`pane-grid.json`) between two side-by-side surfaces is
-       dead space between a docked band and the box below it. The scroller clips its content at its
-       top edge, so the gap put that edge 24px below the band's border with nothing drawn in
-       between — the page ended at an invisible line and the band read as a hairline over one
-       continuous surface. At 0 the clip happens AT the border, which is what makes the border read
-       as the band's edge; the scroller's own 32px of top padding is the breathing room. */
-    canvasWrap.style.flexDirection = wantsDocHeader ? "column" : "";
-    canvasWrap.style.alignItems = wantsDocHeader ? "stretch" : "";
-    canvasWrap.style.gap = wantsDocHeader ? "0px" : "";
+    /* The stage stacks when it carries the writing banner: the band first, the page's scroller
+       below it. Set on every render rather than on the transition, because whether a document is
+       a collection entry changes with the tab and not with the mode. `editors.ts` and
+       `formula-workspace.ts` already claim the column this way — `#canvas-wrap` is a row by
+       default and each surface states its own axis. Stretched, because the band is as wide as the
+       PANE rather than the breakpoint's column. And FLUSH: the cell's own 24px gap
+       (`pane-grid.json`) between two side-by-side surfaces would be dead space between the band and
+       the scroller below it, whose own 32px of top padding is the breathing room. */
+    const stacks = wantsWritingBanner;
+    canvasWrap.style.flexDirection = stacks ? "column" : "";
+    canvasWrap.style.alignItems = stacks ? "stretch" : "";
+    canvasWrap.style.gap = stacks ? "0px" : "";
     void drawStage(
       surface,
       {
-        /* The card LEADS the frame (`tests/canvas-render.test.ts`, "Edit docks it above the page's
-           scroller"): a sibling of the scroller rather than a block of the column, so the page
-           scrolls under it and the breakpoint does not size it. The two handles are not in the
+        /* The banner LEADS the frame: a sibling of the scroller rather than a block of the column,
+           so the page scrolls under it and the breakpoint does not size it. The two handles are not in the
            column either: they are `jx-split`s standing beside it in the canvas's row, because the
            canvas is the track a splitter has to measure and the column is the thing being
            resized. */
@@ -1670,7 +1687,7 @@ function renderCanvasImpl(surface: CanvasSurface) {
         handles: "shown",
         hug: isComponentDoc,
         innerPart: "edit-column",
-        lead: wantsDocHeader ? "header" : "none",
+        lead: wantsWritingBanner ? "banner" : "none",
         panels: [entry.item],
       },
       [entry],
@@ -1678,8 +1695,13 @@ function renderCanvasImpl(surface: CanvasSurface) {
       if (!stage) {
         return;
       }
+      if (wantsWritingBanner) {
+        renderWritingBanner(surface.paneId, tab);
+      }
       const editColumn = stageHost(surface, "edit-column");
       const scroller = stageHost(surface, "edit-canvas");
+      /* SAFETY: the edit stage view always draws its `edit-canvas` part, and this runs only once
+         drawStage settled with that stage (the `!stage` return above). */
       entry.panel.scrollContainer = scroller as HTMLElement;
       /* The one mode whose stage SCROLLS under the zoom pod, so the one that tells the pane how
          wide its scrollbar is. The pod floats in the pane's chrome layer, which spans the gutter
@@ -1717,9 +1739,9 @@ function renderCanvasImpl(surface: CanvasSurface) {
     canvasWrap.style.padding = "0";
     canvasWrap.style.overflow = "hidden";
   }
-  /* No Document Header here, so the stage cell stays the row it is by default: the card is Edit's
-     alone (see `wantsDocHeader`), and the transition into this mode has already cleared the two
-     inline writes Edit makes to stack it. */
+  /* Nothing leads Design's frame, so the stage cell stays the row it is by default: the writing
+     banner is Edit's alone (see `wantsWritingBanner`), and the transition into this mode has
+     already cleared the inline writes Edit makes to stack it. */
 
   const {
     sizeBreakpoints,
@@ -1733,7 +1755,7 @@ function renderCanvasImpl(surface: CanvasSurface) {
   if (!hasMedia) {
     // Single panel — use baseWidth if a custom one is defined, otherwise full-width
     const effectiveMedia = getEffectiveMedia(S.document.$media);
-    const hasBaseWidth = effectiveMedia && effectiveMedia["--"];
+    const hasBaseWidth = effectiveMedia["--"];
     const label = hasBaseWidth ? `${mediaDisplayName("--")} (${baseWidth}px)` : null;
     const entry = canvasPanelEntry(
       hasBaseWidth ? "base" : null,
@@ -1900,8 +1922,11 @@ function renderCanvasIntoPanel(
 ) {
   const gen = passGen ?? surface.renderGeneration;
   const tab = tabOfPane(surface.paneId);
+  /* SAFETY: every caller is a renderCanvasImpl pass, which returns before drawing any panel when its
+     pane has no tab, so without an override `tab` was non-null when this pass began; the git-diff
+     callers always pass their override. */
   const docToRender = docOverride || (tab?.doc.document as JxMutableNode);
-  const canvas = panel.canvas as HTMLElement;
+  const { canvas } = panel;
 
   canvasPerf.panelRenders += 1;
   panel.ready = false;
@@ -1947,14 +1972,16 @@ function renderCanvasIntoPanel(
         // The canvas you are looking at; it says so itself.
       }
     })
-    .catch((error: unknown) => {
-      const detail = error instanceof Error ? error.message : String(error);
-      notify.error("The canvas could not be mounted.", {
-        detail,
-        key: "canvas.mount",
-        source: "Canvas",
-      });
-    });
+    .catch(reportMountFailure);
+}
+
+/** A canvas mount that rejected, reported as a Problem with the failure's own message. */
+function reportMountFailure(cause: unknown): void {
+  notify.error("The canvas could not be mounted.", {
+    detail: errorMessage(cause),
+    key: "canvas.mount",
+    source: "Canvas",
+  });
 }
 
 /*
@@ -1974,11 +2001,11 @@ setSurfaceTeardown((surface) => {
   clearDiffView(surface.paneId);
   setDiffToolbarHost(surface.paneId, null);
   detachGridPanel(surface.paneId);
-  detachLibraryPane(surface.paneId);
   detachEntryPane(surface.paneId);
   detachMediaPane(surface.paneId);
-  detachSettingsPane(surface.paneId);
-  attachDocumentHeaderHost(surface.paneId, null);
+  detachVariablesView(surface.paneId);
+  detachWorkspaceHome(surface.paneId);
+  detachWritingBanner(surface.paneId);
   disposeSourceCollab(surface);
   disposeSourceEditor(surface);
   surface.centerObserver?.disconnect();
@@ -2012,7 +2039,7 @@ function refuseUnresolvableToken(token: string): void {
     throw new RangeError(`command "insert.data" needs an open document; no tab is active`);
   }
   const root = tokenRoot(token);
-  const state = (tab.doc.document.state ?? {}) as Record<string, unknown>;
+  const state = tab.doc.document.state ?? {};
   if (root === "state") {
     const name = token.split(".")[1] ?? "";
     if (!(name in state)) {