@drawnagency/primitives 0.1.79 → 0.1.81

package/src/components/primitives/gridDrop.ts

@@ -0,0 +1,26 @@
+/**
+ * Convert a drop target (the cell being dropped onto + the closest edge) into
+ * the destination index for the moved item.
+ *
+ * Same-collection reorder: the dragged item is spliced OUT of the array before
+ * being re-inserted, so a destination past its original position shifts down by
+ * one — hence the `fromIndex < toIndex` decrement.
+ *
+ * Cross-collection insert: nothing is removed from the destination array, so no
+ * shift adjustment applies.
+ */
+export function resolveDropIndex({
+  fromIndex,
+  targetIndex,
+  edge,
+  sameCollection,
+}: {
+  fromIndex: number;
+  targetIndex: number;
+  edge: "left" | "right" | null;
+  sameCollection: boolean;
+}): number {
+  let toIndex = targetIndex + (edge === "right" ? 1 : 0);
+  if (sameCollection && fromIndex < toIndex) toIndex--;
+  return toIndex;
+}

package/src/components/primitives/useEditableCollection.ts

@@ -16,6 +16,7 @@ interface UseEditableCollectionReturn<T> {
   onReorder: (fromIndex: number, toIndex: number) => void;
   onAdd: () => void;
   onInsert: (index: number) => void;
+  onInsertItem: (index: number, data: T) => void;
   onRemove: (id: string) => void;
 }
 
@@ -89,6 +90,20 @@ export function useEditableCollection<T>({
     [createItem, onChange],
   );
 
+  // Insert an externally-provided item (e.g. one dragged in from another grid)
+  // at a specific index. Distinct from onInsert, which creates a blank item.
+  const onInsertItem = useCallback(
+    (index: number, data: T) => {
+      setWrappedItems((prev) => {
+        const next = [...prev];
+        next.splice(index, 0, { id: uid(), data });
+        onChange(next.map((w) => w.data));
+        return next;
+      });
+    },
+    [onChange]
+  );
+
   const onRemove = useCallback(
     (id: string) => {
       setWrappedItems((prev) => {
@@ -100,5 +115,5 @@ export function useEditableCollection<T>({
     [onChange]
   );
 
-  return { wrappedItems, onReorder, onAdd, onInsert, onRemove };
+  return { wrappedItems, onReorder, onAdd, onInsert, onInsertItem, onRemove };
 }

package/src/components/sections/Colors/index.tsx

@@ -30,7 +30,7 @@ export default defineSection({
   schema,
   authoringNote:
     "A brand color palette. Each color may carry hex/rgb/cmyk/pantone values. Use to document brand colors with swatches.",
-  component: ({ content, options, onChange, openModal }) => (
+  component: ({ content, options, onChange, openModal, onDelete }) => (
     <Colors
       colors={content.content.colors}
       columns={options?.columns as number}
@@ -39,6 +39,7 @@ export default defineSection({
       showLabel={options?.showLabel as boolean}
       onChange={onChange ? (c) => onChange(c as typeof content) : undefined}
       openModal={openModal}
+      onDelete={onDelete}
     />
   ),
   defaults: () => ({

package/src/components/shell/DocInspector.tsx

@@ -0,0 +1,278 @@
+import { settingsFor, type DocumentOptions } from "../../document";
+import { Input } from "../shared/Input";
+import { Select } from "../shared/Select";
+import { Checkbox } from "../shared/Checkbox";
+import { RadioGroup } from "../shared/RadioGroup";
+import { ColorPicker } from "../shared/ColorPicker";
+import { FormLabel } from "../shared/FormLabel";
+import { useMediaLibrary } from "./MediaLibraryContext";
+import { Button } from "../shared/Button";
+import type { MediaItem } from "../../media/types";
+
+// Smallest generated variant for the inspector thumbnail (same file naming as
+// docImagesFrom in lib/document-input.ts); null when the item can't render.
+function thumbSrc(imageId: string, item: MediaItem | undefined): string | null {
+  if (!item || item.kind !== "image") return null;
+  if (item.mimeType === "image/svg+xml") return `/api/media/${imageId}/original.svg`;
+  const widths = item.variants.map((v) => v.width).sort((a, b) => a - b);
+  if (widths.length === 0) return null;
+  return `/api/media/${imageId}/${widths[0]}.webp`;
+}
+
+export interface DocInspectorProps {
+  document: DocumentOptions;
+  selection: { kind: "cover" } | { kind: "chunk"; chunkId: string; title: string };
+  warnings: string[]; // warningsByChunk for the selected chunk
+  onUpdateCover: (patch: Partial<DocumentOptions["cover"]>) => void;
+  onUpdateMeta: (patch: Partial<DocumentOptions["meta"]>) => void;
+  // Caller merges the patch via sectionSettingsSchema.parse.
+  onUpdateSection: (chunkId: string, patch: Record<string, unknown>) => void;
+}
+
+// Drawn palette — mirrors the swatch row in the harness inspector.
+const SWATCHES = [
+  "#FFFFFF", "#EBEBEB", "#999999", "#333333", "#1F1F1F", // neutrals: white → near-black
+  "#009FAD", // teal (brand primary)
+  "#3D7F7F", // forest
+  "#099A6F", // green
+  "#5F81AB", // blue
+  "#7C97BB", // sky
+  "#6864A0", // violet
+  "#D3A978", // beige
+  "#EB9500", // gold
+  "#F07C00", // orange
+  "#A24E16", // brown / rust
+  "#A65982", // indigo
+  "#E64165", // pink
+];
+
+function ColorControl({ label, value, onPick }: { label: string; value: string; onPick: (v: string) => void }) {
+  return (
+    <div className="mb-4">
+      <FormLabel>{label}</FormLabel>
+      <div className="flex flex-wrap items-center gap-1">
+        {SWATCHES.map((s) => (
+          <button
+            key={s}
+            type="button"
+            aria-label={s}
+            onClick={() => onPick(s)}
+            style={{ background: s }}
+            className={`h-6 w-6 rounded border ${s === value ? "border-primary ring-1 ring-primary" : "border-base-200"}`}
+          />
+        ))}
+        <ColorPicker value={value} onChange={onPick} label="Custom color" className="h-6 w-6" />
+      </div>
+    </div>
+  );
+}
+
+export function DocInspector({
+  document: doc,
+  selection,
+  warnings,
+  onUpdateCover,
+  onUpdateMeta,
+  onUpdateSection,
+}: DocInspectorProps) {
+  return (
+    <aside data-testid="doc-inspector" className="w-64 shrink-0 overflow-y-auto border-l border-base-200 bg-base p-4">
+      {selection.kind === "cover" ? (
+        <CoverPanel doc={doc} onUpdateCover={onUpdateCover} onUpdateMeta={onUpdateMeta} />
+      ) : (
+        <ChunkPanel
+          key={selection.chunkId}
+          chunkId={selection.chunkId}
+          title={selection.title}
+          doc={doc}
+          warnings={warnings}
+          onUpdateSection={onUpdateSection}
+        />
+      )}
+    </aside>
+  );
+}
+
+function CoverPanel({
+  doc,
+  onUpdateCover,
+  onUpdateMeta,
+}: {
+  doc: DocumentOptions;
+  onUpdateCover: (patch: Partial<DocumentOptions["cover"]>) => void;
+  onUpdateMeta: (patch: Partial<DocumentOptions["meta"]>) => void;
+}) {
+  const { cover, meta } = doc;
+  const media = useMediaLibrary();
+  return (
+    <>
+      <h2 className="mb-2 text-xs font-semibold uppercase tracking-wide text-base-contrast-light">Cover</h2>
+      <Input label="Title" value={cover.title} onChange={(title) => onUpdateCover({ title })} className="mb-2" />
+      <Input label="Label" value={cover.label} onChange={(label) => onUpdateCover({ label })} className="mb-2" />
+      <Input label="Date" value={cover.date} onChange={(date) => onUpdateCover({ date })} className="mb-2" />
+
+      {media ? (
+        <div className="mb-4">
+          <FormLabel>Cover image</FormLabel>
+          {cover.imageId ? (
+            (() => {
+              const src = thumbSrc(cover.imageId, media.manifest.images[cover.imageId]);
+              return src ? (
+                <img src={src} alt="Cover image preview" className="mb-2 max-h-24 rounded border border-base-200" />
+              ) : null;
+            })()
+          ) : null}
+          <div className="flex gap-2">
+            <Button
+              variant="secondary"
+              size="sm"
+              onClick={() => media.openSelectModal((imageId) => onUpdateCover({ imageId }))}
+            >
+              {cover.imageId ? "Replace image" : "Choose image"}
+            </Button>
+            {cover.imageId ? (
+              <Button variant="ghost" size="sm" onClick={() => onUpdateCover({ imageId: null })}>
+                Remove image
+              </Button>
+            ) : null}
+          </div>
+        </div>
+      ) : null}
+
+      <ColorControl label="Background" value={cover.bgColor} onPick={(bgColor) => onUpdateCover({ bgColor })} />
+      <ColorControl label="Accent" value={cover.accentColor} onPick={(accentColor) => onUpdateCover({ accentColor })} />
+
+      <h2 className="mb-2 mt-6 text-xs font-semibold uppercase tracking-wide text-base-contrast-light">Document</h2>
+      <Input label="Client" value={meta.client} onChange={(client) => onUpdateMeta({ client })} className="mb-2" />
+      <Input label="Project" value={meta.project} onChange={(project) => onUpdateMeta({ project })} className="mb-2" />
+      <Input label="Date label" value={meta.dateLabel} onChange={(dateLabel) => onUpdateMeta({ dateLabel })} className="mb-2" />
+    </>
+  );
+}
+
+function ChunkPanel({
+  chunkId,
+  title,
+  doc,
+  warnings,
+  onUpdateSection,
+}: {
+  chunkId: string;
+  title: string;
+  doc: DocumentOptions;
+  warnings: string[];
+  onUpdateSection: (chunkId: string, patch: Record<string, unknown>) => void;
+}) {
+  const settings = settingsFor(doc.sections, chunkId);
+  const layout = settings.imageLayout;
+
+  return (
+    <>
+      <h2 className="mb-3 text-xs font-semibold uppercase tracking-wide text-base-contrast-light">{title}</h2>
+
+      <Checkbox
+        className="mb-4"
+        checked={!settings.excluded}
+        onChange={(checked) => onUpdateSection(chunkId, { excluded: !checked })}
+        label="Include in document"
+      />
+
+      {/* Image placement is linked, not independent (Drew, 2026-07-19): text
+          left → images right of the column, text top → images below full
+          width. One control drives both fields. */}
+      <RadioGroup
+        className="mb-4"
+        label="Text placement"
+        value={settings.textPlacement}
+        options={[
+          { label: "Top", value: "top" },
+          { label: "Left column", value: "leftColumn" },
+        ]}
+        onChange={(textPlacement) =>
+          onUpdateSection(chunkId, {
+            textPlacement,
+            imagePlacement: textPlacement === "leftColumn" ? "right" : "fullWidth",
+          })
+        }
+      />
+
+      <Checkbox
+        className="mb-4"
+        checked={settings.dropTextOverflow}
+        onChange={(dropTextOverflow) => onUpdateSection(chunkId, { dropTextOverflow })}
+        label="Drop text overflow"
+      />
+
+      <Select
+        className="mb-4"
+        label="Image layout"
+        value={layout.mode}
+        options={[
+          { value: "grid", label: "Grid" },
+          { value: "masonry", label: "Masonry" },
+        ]}
+        onChange={(v) =>
+          onUpdateSection(
+            chunkId,
+            v === "grid"
+              ? { imageLayout: { mode: "grid", rows: 2, columns: 4 } }
+              : { imageLayout: { mode: "masonry", flow: "rows", columns: 3 } },
+          )
+        }
+      />
+
+      {layout.mode === "grid" ? (
+        <>
+          <Select
+            className="mb-4"
+            label="Rows"
+            value={String(layout.rows)}
+            options={[1, 2, 3].map((n) => ({ value: String(n), label: String(n) }))}
+            onChange={(v) => onUpdateSection(chunkId, { imageLayout: { ...layout, rows: Number(v) } })}
+          />
+          <Select
+            className="mb-4"
+            label="Columns"
+            value={String(layout.columns)}
+            options={[2, 3, 4].map((n) => ({ value: String(n), label: String(n) }))}
+            onChange={(v) => onUpdateSection(chunkId, { imageLayout: { ...layout, columns: Number(v) } })}
+          />
+        </>
+      ) : (
+        <>
+          <Select
+            className="mb-4"
+            label="Flow"
+            value={layout.flow}
+            options={[
+              { value: "rows", label: "Rows" },
+              { value: "columns", label: "Columns" },
+            ]}
+            onChange={(v) => onUpdateSection(chunkId, { imageLayout: { ...layout, flow: v } })}
+          />
+          {/* Column count only drives the columns flow (layoutRows never reads
+              it) — hide it when irrelevant. */}
+          {layout.flow === "columns" ? (
+            <Select
+              className="mb-4"
+              label="Columns"
+              value={String(layout.columns)}
+              options={[2, 3, 4, 5, 6].map((n) => ({ value: String(n), label: String(n) }))}
+              onChange={(v) => onUpdateSection(chunkId, { imageLayout: { ...layout, columns: Number(v) } })}
+            />
+          ) : null}
+        </>
+      )}
+
+      {warnings.length > 0 ? (
+        <div className="mt-2">
+          {warnings.map((w, i) => (
+            <p key={i} className="mb-1 rounded border border-amber-300 bg-amber-50 px-2 py-1 text-xs text-amber-800">
+              {w}
+            </p>
+          ))}
+        </div>
+      ) : null}
+    </>
+  );
+}

package/src/components/shell/DocumentEditorOverlay.tsx

@@ -0,0 +1,169 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import type { Page } from "../../schemas/site-config";
+import type { MediaManifest } from "../../media/types";
+import type { LoadedSection } from "../../lib/loader";
+import {
+  DocViewer,
+  documentOptionsSchema,
+  sectionSettingsSchema,
+  settingsFor,
+  type Chunk,
+  type DocHost,
+  type DocumentOptions,
+} from "../../document";
+import { DocInspector, type DocInspectorProps } from "./DocInspector";
+import { buildDraftDocumentInput } from "../../lib/document-input";
+import { Button } from "../shared/Button";
+// The sealed document stylesheet ships with its editor consumer (Task 6 decided
+// the present route imports it from its island; this is the editor's island).
+// Vitest stubs CSS imports, so it stays out of the jsdom test graph regardless.
+import "../../document/styles/document.css";
+
+export interface DocumentEditorOverlayProps {
+  /** The active page — its `document` block must be enabled for the FAB to mount. */
+  page: Page;
+  /**
+   * The page's draft sections, in `page.order` order. The overlay drops
+   * archived ones itself — /present renders only live sections, so a chunk the
+   * published document will never show must not influence the proofed layout.
+   */
+  sections: LoadedSection[];
+  manifest: MediaManifest;
+  /** Wired by the shell to `setPageDocument` + the local-changes dirty flag. */
+  onUpdateDocument: (patch: Partial<DocumentOptions>) => void;
+  onClose: () => void;
+}
+
+/**
+ * Full-viewport editing surface: DocViewer (edit mode, ghosts + selection) on
+ * the left, DocInspector (settings for the current selection) on the right.
+ *
+ * The engine input is rebuilt from the live draft (page + in-memory sections +
+ * manifest) on every prop change, so unsaved edits repaginate immediately —
+ * the pagination hook's stale-heights guard absorbs the shape changes.
+ */
+export function DocumentEditorOverlay({
+  page,
+  sections,
+  manifest,
+  onUpdateDocument,
+  onClose,
+}: DocumentEditorOverlayProps) {
+  // page.document is optional on the type; the caller only mounts this when it
+  // is enabled, but parse-with-defaults keeps us total either way.
+  const doc = useMemo(() => documentOptionsSchema.parse(page.document ?? {}), [page.document]);
+
+  const source = useMemo(
+    () =>
+      buildDraftDocumentInput({
+        page,
+        sections: sections.filter((s) => s.meta.status !== "archived"),
+        manifest,
+      }),
+    [page, sections, manifest],
+  );
+
+  // Titles (for the inspector header) + per-chunk warnings come straight from
+  // DocViewer's single pagination pass via onDocState — no second useDocPages.
+  const [docState, setDocState] = useState<{ chunks: Chunk[]; warningsByChunk: Record<string, string[]> }>({
+    chunks: [],
+    warningsByChunk: {},
+  });
+  const { chunks, warningsByChunk } = docState;
+
+  // null = cover selected.
+  const [selectedChunkId, setSelectedChunkId] = useState<string | null>(null);
+
+  // All media bytes come from /api/media (draft branch bytes are served to
+  // editor sessions) — the same host shape the present route uses.
+  const host: DocHost = useMemo(
+    () => ({
+      variant: "preview",
+      imageSrc: (image, variant) =>
+        `/api/media/${image.imageId}/${variant === "print" ? image.printFile : image.previewFile}`,
+    }),
+    [],
+  );
+
+  // Escape closes (the close button is the other exit). DocViewer owns arrow
+  // paging on its own window listener; Escape doesn't collide with it. An
+  // Escape aimed at an inspector control is the cancel-the-field gesture, not
+  // "leave the editor": text fields blur (so the next Escape closes), and a
+  // select is left alone entirely — the browser uses Escape to dismiss its
+  // popup and there's no way to tell whether one is open.
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key !== "Escape") return;
+      const t = e.target as HTMLElement | null;
+      if (t && (t.tagName === "INPUT" || t.tagName === "TEXTAREA" || t.isContentEditable)) {
+        t.blur();
+        return;
+      }
+      if (t && t.tagName === "SELECT") return;
+      e.preventDefault();
+      onClose();
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [onClose]);
+
+  const selection: DocInspectorProps["selection"] = useMemo(() => {
+    if (selectedChunkId === null) return { kind: "cover" };
+    const chunk = chunks.find((c) => c.id === selectedChunkId);
+    return { kind: "chunk", chunkId: selectedChunkId, title: chunk?.title ?? selectedChunkId };
+  }, [selectedChunkId, chunks]);
+
+  const warnings = selectedChunkId ? warningsByChunk[selectedChunkId] ?? [] : [];
+
+  // Merge the inspector's partial patch onto the chunk's CURRENT settings and
+  // ship the whole validated block — setPageDocument merges sections shallowly
+  // by key, so we must hand it a complete SectionSettings, not a fragment.
+  const handleUpdateSection = useCallback(
+    (chunkId: string, patch: Record<string, unknown>) => {
+      const merged = sectionSettingsSchema.parse({ ...settingsFor(doc.sections, chunkId), ...patch });
+      onUpdateDocument({ sections: { [chunkId]: merged } });
+    },
+    [doc.sections, onUpdateDocument],
+  );
+
+  // Cover/meta are single objects on the document; merge onto the current value
+  // so a one-field edit doesn't blank the siblings before setPageDocument runs.
+  const handleUpdateCover = useCallback(
+    (patch: Partial<DocumentOptions["cover"]>) => onUpdateDocument({ cover: { ...doc.cover, ...patch } }),
+    [doc.cover, onUpdateDocument],
+  );
+  const handleUpdateMeta = useCallback(
+    (patch: Partial<DocumentOptions["meta"]>) => onUpdateDocument({ meta: { ...doc.meta, ...patch } }),
+    [doc.meta, onUpdateDocument],
+  );
+
+  return (
+    <div className="fixed inset-0 z-50 flex flex-col bg-base" role="dialog" aria-modal="true" aria-label="Document editor">
+      <div className="flex items-center justify-between border-b border-base-200 bg-base px-4 py-2">
+        <span className="text-sm font-medium text-base-contrast">Document · {page.title}</span>
+        <Button variant="secondary" size="sm" aria-label="Close document editor" onClick={onClose}>
+          Close
+        </Button>
+      </div>
+      <div className="flex min-h-0 flex-1">
+        <DocViewer
+          source={source}
+          document={doc}
+          host={host}
+          mode="edit"
+          selectedChunkId={selectedChunkId}
+          onSelectChunk={setSelectedChunkId}
+          onDocState={setDocState}
+        />
+        <DocInspector
+          document={doc}
+          selection={selection}
+          warnings={warnings}
+          onUpdateCover={handleUpdateCover}
+          onUpdateMeta={handleUpdateMeta}
+          onUpdateSection={handleUpdateSection}
+        />
+      </div>
+    </div>
+  );
+}

package/src/components/shell/DocumentPresentOverlay.tsx

@@ -0,0 +1,87 @@
+import { useEffect, useMemo } from "react";
+import type { Page } from "../../schemas/site-config";
+import type { MediaManifest } from "../../media/types";
+import type { LoadedSection } from "../../lib/loader";
+import { DocViewer, documentOptionsSchema, type DocHost } from "../../document";
+import { buildDraftDocumentInput } from "../../lib/document-input";
+// Same sealed document stylesheet the editor overlay ships (see
+// DocumentEditorOverlay). Vitest stubs CSS imports, so it stays out of the jsdom
+// test graph regardless.
+import "../../document/styles/document.css";
+
+export interface DocumentPresentOverlayProps {
+  /** The active page — its `document` block supplies cover/meta/section settings. */
+  page: Page;
+  /**
+   * The sections currently on the canvas (already page-ordered and filtered to
+   * the branch being previewed). The shell derives these from the same
+   * `computeDisplaySections` call the history/branch canvas renders.
+   */
+  sections: LoadedSection[];
+  manifest: MediaManifest;
+  onClose: () => void;
+}
+
+/**
+ * Read-only, full-viewport document PRESENTATION of the content currently being
+ * viewed — used when the shell is previewing a non-draft version (the published
+ * branch). It is `DocViewer` in `present` mode: no inspector, no update path.
+ *
+ * Product decision (Drew): history/branch views are the record — we present them
+ * but never open the editor over them. Document SETTINGS come from the current
+ * draft's `page.document`; the previewed branch's own document index is not
+ * carried in the shell's `viewSections`, so cover/meta/exclusions here reflect
+ * the draft, not the historical commit. This is an accepted approximation: we
+ * are rendering historical *content* with the draft's presentation settings.
+ */
+export function DocumentPresentOverlay({
+  page,
+  sections,
+  manifest,
+  onClose,
+}: DocumentPresentOverlayProps) {
+  // page.document is optional on the type; the caller only mounts this when it
+  // is enabled, but parse-with-defaults keeps us total either way.
+  const doc = useMemo(() => documentOptionsSchema.parse(page.document ?? {}), [page.document]);
+
+  const source = useMemo(
+    () => buildDraftDocumentInput({ page, sections, manifest }),
+    [page, sections, manifest],
+  );
+
+  // All media bytes come from /api/media — the same host shape the present route
+  // and the editor overlay use.
+  const host: DocHost = useMemo(
+    () => ({
+      variant: "preview",
+      imageSrc: (image, variant) =>
+        `/api/media/${image.imageId}/${variant === "print" ? image.printFile : image.previewFile}`,
+    }),
+    [],
+  );
+
+  // Escape closes, matching the editor overlay. DocViewer owns arrow paging on
+  // its own window listener; Escape doesn't collide with it.
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key !== "Escape") return;
+      e.preventDefault();
+      onClose();
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [onClose]);
+
+  return (
+    <div
+      className="fixed inset-0 z-50 flex flex-col bg-base"
+      role="dialog"
+      aria-modal="true"
+      aria-label="Document presentation"
+    >
+      <div className="flex min-h-0 flex-1">
+        <DocViewer source={source} document={doc} host={host} mode="present" onClose={onClose} />
+      </div>
+    </div>
+  );
+}

package/src/components/shell/EditorContext.tsx

@@ -16,10 +16,12 @@ interface EditorContextValue {
   showAllChrome: boolean;
   viewBranch: "saved" | "live";
   historyState: HistoryState;
+  historyPageId: string | null;
   toggleEditMode: () => void;
   toggleShowAllChrome: () => void;
   setViewBranch: (branch: "saved" | "live") => void;
   setHistoryState: (state: HistoryState) => void;
+  setHistoryPageId: (pageId: string | null) => void;
 }
 
 const EditorContext = createContext<EditorContextValue | null>(null);
@@ -33,7 +35,10 @@ export function EditorProvider({ children }: EditorProviderProps) {
   const [showAllChrome, setShowAllChrome] = useState(false);
   const [viewBranch, setViewBranchState] = useState<"saved" | "live">("saved");
   const [historyState, setHistoryStateRaw] = useState<HistoryState>(null);
+  const [historyPageId, setHistoryPageId] = useState<string | null>(null);
   const setHistoryState = useCallback((state: HistoryState) => {
+    // null = "auto": resolved to the current page (or home) at render time
+    setHistoryPageId(null);
     setHistoryStateRaw(state);
   }, []);
 
@@ -49,7 +54,7 @@ export function EditorProvider({ children }: EditorProviderProps) {
   const setViewBranch = useCallback((b: "saved" | "live") => setViewBranchState(b), []);
 
   return (
-    <EditorContext.Provider value={{ isEditMode, showAllChrome, viewBranch, historyState, toggleEditMode, toggleShowAllChrome, setViewBranch, setHistoryState }}>
+    <EditorContext.Provider value={{ isEditMode, showAllChrome, viewBranch, historyState, historyPageId, toggleEditMode, toggleShowAllChrome, setViewBranch, setHistoryState, setHistoryPageId }}>
       {children}
     </EditorContext.Provider>
   );