@rmdes/indiekit-endpoint-site-config 1.0.0-beta.13 → 1.0.0-beta.15

package/README.md

@@ -220,6 +220,25 @@ Phase 4 makes the composition editor the homepage source of truth (the v3 homepa
 
 **Phase 6 surfaces** — the hub already lists `listing`, `posttype`, and `pages` as disabled cards; their composition surfaces (and the blog sidebars' cutover off the v3 doc) land in Phase 6.
 
+### Phase 5: True preview + build status
+
+Phase 5 adds a true preview (the draft rendered through the **production** theme renderer, zero drift) and a post-publish build-status surface.
+
+**Routes** (both on the session-protected design router):
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| POST | `/design/homepage/preview` | Write the preview-draft artifact on demand (never per keystroke) |
+| GET | `/design/api/build-status` | Build-status API polled by the publish strip (`Cache-Control: no-store`) |
+
+**Preview-draft artifact** — the Update-preview POST writes `content/_data/compositions/preview-draft.json` (`{schemaVersion: 4, kind: "preview", tree, revision, token, generatedAt}`, atomic tmp + rename) from the draft tree (or the published tree when no draft exists). The theme renders it at `/preview/<token>/` — an unguessable 16-byte token stored on the `siteConfig` doc. Each preview write bumps a monotonic revision; the editor's preview pane polls the same-origin iframe until the new revision appears. **Publish rotates the token** (previously shared preview URLs expire) and rewrites a fresh preview-draft from the now-published tree — warn-only, a preview refresh failure never masks a successful publish.
+
+**Custom-tree scope (deliberate)** — the preview POST accepts custom (hand-built) trees, since they render through the same production renderer. But the editor view stays read-only for custom trees and offers **no preview pane affordance**; previewing a hand-built tree is its author's out-of-band concern.
+
+**Build-status API** — `GET /design/api/build-status` reads `/app/data/build-status.json` (written by the theme's build hooks as `{state: "building"|"ok", buildId, startedAt, finishedAt, durationSeconds, incremental, lastOkDurationSeconds}` and by start.sh's crash wrapper as a minimal `{state: "failed", error, finishedAt}`) and responds with the raw fields plus a computed `stuck` flag: a `building` state that has overrun `max(2 × lastOkDurationSeconds, 120)` seconds (the 120s floor absorbs full post-boot builds; 60 is the default when the duration is absent). The endpoint is tolerant by contract — an absent or corrupt file responds `{state: "unknown"}`, never a 500, and a `building` object missing `startedAt` is never stuck.
+
+**Publish-flow strip** — after a publish (`?published=1`) the draft bar's "Live" row gains a build-status strip. With JS, `editor.js` polls the API every 5s while a sessionStorage watch (stamped with the publish time) is active: `building` shows "Rebuilding — usually ~Xs on this site. Your current site stays online."; `ok` with `finishedAt` after the publish shows "Live · <time>" (terminal); `failed` shows the error excerpt plus a republish hint (terminal — the live site is unchanged); `stuck` explains that publishing again rewrites the homepage artifact (which also heals a missed watcher event). Without JS, the strip renders the last-known status server-side with a reload-to-update note (no meta-refresh).
+
 ## Theme integration
 
 The companion Eleventy theme [`indiekit-eleventy-theme`](https://github.com/rmdes/indiekit-eleventy-theme) reads:

package/assets/editor.css

@@ -419,6 +419,26 @@
   flex-wrap: wrap;
 }
 
+/* Publish-flow build-status strip (Phase 5 S2) — rides in the draft bar's
+   "Live" state after a publish. */
+.sc-build-status {
+  flex-basis: 100%;
+  border-top: 1px solid var(--color-outline-variant, #ddd);
+  padding-top: var(--space-2xs, 0.375rem);
+}
+
+.sc-build-status__text {
+  margin: 0;
+  font: var(--font-caption, 0.875rem/1.4 sans-serif);
+  color: var(--color-on-offset, #666);
+}
+
+.sc-build-status__note {
+  margin: var(--space-3xs, 0.25rem) 0 0;
+  font: var(--font-caption, 0.75rem/1.4 sans-serif);
+  color: var(--color-on-offset, #666);
+}
+
 /* ---- Focus visibility (WCAG 2.4.7) ----
    Cards themselves aren't focusable; every interactive element inside the
    editor, hub, and add dialog gets a visible focus ring. Same accent as the
@@ -441,3 +461,80 @@
   flex-direction: column;
   gap: var(--space-s, 0.75rem);
 }
+
+/* ---- Right-pane mode toggle + true preview (Phase 5) ----
+   The pane wrapper takes over the sticky behavior the bare structural
+   preview had as a direct grid child (a sticky element inside a
+   content-height wrapper has no room to stick). */
+
+.sc-design__pane {
+  position: sticky;
+  top: var(--space-s, 0.75rem);
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-xs, 0.5rem);
+}
+
+.sc-design__pane .sc-design__preview {
+  position: static; /* sticky moved to the wrapper */
+}
+
+@media (max-width: 1100px) {
+  .sc-design__pane {
+    position: static;
+  }
+}
+
+.sc-pane-toggle {
+  display: flex;
+  gap: var(--space-2xs, 0.375rem);
+}
+
+.sc-pane-toggle__link {
+  font: var(--font-caption, 0.8125rem/1.4 sans-serif);
+  font-weight: 700;
+  text-decoration: none;
+  color: var(--color-on-offset, #666);
+  padding: var(--space-2xs, 0.25rem) var(--space-xs, 0.5rem);
+  border: 1px solid var(--color-outline-variant, #ddd);
+  border-radius: var(--border-radius-small, 0.25rem);
+}
+
+.sc-pane-toggle__link[aria-current="true"] {
+  color: var(--color-on-primary, #fff);
+  background: var(--color-primary, #0066cc);
+  border-color: var(--color-primary, #0066cc);
+}
+
+.sc-design__preview--live {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-xs, 0.5rem);
+}
+
+.sc-preview-bar {
+  display: flex;
+  gap: var(--space-xs, 0.5rem);
+  flex-wrap: wrap;
+}
+
+.sc-preview-status {
+  font: var(--font-caption, 0.8125rem/1.4 sans-serif);
+  color: var(--color-on-offset, #666);
+  min-height: 1.2em; /* no layout shift when status text appears */
+  margin: 0;
+}
+
+.sc-preview-frame {
+  width: 100%;
+  height: min(70vh, 48rem);
+  border: 1px solid var(--color-outline-variant, #ddd);
+  border-radius: var(--border-radius-small, 0.25rem);
+  background: var(--color-background, #fff);
+}
+
+.sc-preview-empty {
+  font: var(--font-caption, 0.8125rem/1.4 sans-serif);
+  color: var(--color-on-offset, #666);
+}

package/assets/editor.js

@@ -147,8 +147,282 @@ function initUndoFlash(i18n) {
   flash.append(dismiss);
 }
 
+/** (5) True-preview pane (Phase 5). Enhancement over the plain
+ * Update-preview POST: fetch with `Accept: application/json`, then poll the
+ * same-origin iframe every 3s — reload it and read the theme page's
+ * `[data-preview-revision]` — until the just-written revision shows up.
+ * Status copy quotes the site's measured build time (expectedSeconds from
+ * build-status.json); polling caps at 3× that — with a 30s floor so a
+ * 2s-build site doesn't flip to "taking longer than usual" after one poll
+ * (90s when the expected time is unknown) — then shows "taking longer than
+ * usual" and leaves the manual reload button as the recovery affordance.
+ * The no-JS path (plain POST + full page reloads) works without any of
+ * this. */
+const PREVIEW_POLL_MS = 3000;
+const PREVIEW_DEFAULT_CAP_MS = 90_000;
+const PREVIEW_MIN_CAP_MS = 30_000;
+
+function initPreviewPane(i18n) {
+  const form = document.querySelector("[data-sc-preview-form]");
+  if (!form) return; // structural pane (or no editor) — nothing to enhance
+  const pane = form.closest(".sc-design__preview");
+  const status = pane.querySelector("[data-sc-preview-status]");
+  const reload = pane.querySelector("[data-sc-preview-reload]");
+  let timer = null;
+
+  const getFrame = () => pane.querySelector("[data-sc-preview-frame]");
+
+  const setStatus = (text) => {
+    if (status) status.textContent = text;
+  };
+
+  const reloadFrame = (iframe) => {
+    // Same-origin reload; re-assigning src is the fallback (also covers a
+    // frame that never finished its first load).
+    try {
+      iframe.contentWindow.location.reload();
+    } catch {
+      iframe.src = iframe.src;
+    }
+  };
+
+  /** First Update-preview on a fresh site: no token existed at render time,
+   * so the iframe wasn't server-rendered — create it from the response. */
+  const ensureFrame = (token) => {
+    let iframe = getFrame();
+    if (iframe) return iframe;
+    pane.querySelector("[data-sc-preview-empty]")?.remove();
+    iframe = document.createElement("iframe");
+    iframe.className = "sc-preview-frame";
+    iframe.setAttribute("data-sc-preview-frame", "");
+    iframe.title = i18n.previewFrameTitle || "";
+    iframe.src = `/preview/${encodeURIComponent(token)}/`;
+    pane.append(iframe);
+    return iframe;
+  };
+
+  const frameRevision = (iframe) => {
+    try {
+      return (
+        iframe.contentDocument
+          ?.querySelector("[data-preview-revision]")
+          ?.getAttribute("data-preview-revision") ?? null
+      );
+    } catch {
+      return null; // mid-load or cross-origin — keep polling
+    }
+  };
+
+  const stopPolling = () => {
+    if (timer) {
+      clearInterval(timer);
+      timer = null;
+    }
+  };
+
+  const startPolling = ({ token, revision, expectedSeconds }) => {
+    stopPolling();
+    const iframe = ensureFrame(token);
+    const expected =
+      typeof expectedSeconds === "number" && expectedSeconds > 0 ? expectedSeconds : null;
+    const capMs = expected
+      ? Math.max(expected * 3 * 1000, PREVIEW_MIN_CAP_MS)
+      : PREVIEW_DEFAULT_CAP_MS;
+    const startedAt = Date.now();
+    setStatus(
+      expected
+        ? (i18n.previewBuilding || "").replace("{{seconds}}", String(Math.round(expected)))
+        : i18n.previewBuildingUnknown || "",
+    );
+    timer = setInterval(() => {
+      if (frameRevision(iframe) === String(revision)) {
+        stopPolling();
+        setStatus(i18n.previewReady || "");
+        return;
+      }
+      if (Date.now() - startedAt > capMs) {
+        stopPolling();
+        setStatus(i18n.previewSlow || "");
+        return;
+      }
+      reloadFrame(iframe);
+    }, PREVIEW_POLL_MS);
+  };
+
+  if (reload) {
+    reload.hidden = false;
+    reload.addEventListener("click", () => {
+      const iframe = getFrame();
+      if (iframe) reloadFrame(iframe);
+    });
+  }
+
+  form.addEventListener("submit", async (event) => {
+    event.preventDefault();
+    try {
+      const response = await fetch(form.action, {
+        method: "POST",
+        headers: { Accept: "application/json" },
+      });
+      if (!response.ok) throw new Error(`HTTP ${response.status}`);
+      startPolling(await response.json());
+    } catch {
+      // Fall back to the plain POST (full reload) — the no-JS path.
+      stopPolling();
+      form.submit();
+    }
+  });
+}
+
+/** (6) Publish-flow build-status strip (Phase 5 S2). After a publish
+ * (?published=1) the draft bar — now "Live" — gains a strip tracking the
+ * Eleventy rebuild. The strip element only renders on the publish flash;
+ * sessionStorage carries the watch across reloads of that page, stamped
+ * with the publish time so "finishedAt after the publish" is checkable.
+ * Polling is a passive 5s GET of the authed build-status API (a cheap fs
+ * read server-side); the watch ends on terminal states (post-publish ok,
+ * or failed) and when the user navigates off the flash page. A stale "ok"
+ * from BEFORE the publish keeps the rebuilding copy — the new build just
+ * hasn't been observed yet.
+ *
+ * No stamp + a terminal status = a reload AFTER the watch already ended
+ * (endWatch cleared the stamp; the URL still says ?published=1). The probe
+ * branch handles it: fetch once FIRST and, if the status is already
+ * terminal (ok with a finishedAt, or failed), render it as-is and never
+ * (re)start the watch — re-stamping with the reload time would compare
+ * finishedAt against the WRONG moment and replace a correct "Live · time"
+ * with an eternal "Rebuilding…". Only a non-terminal probe (building,
+ * unknown, fetch failure) stamps and starts polling.
+ *
+ * The no-JS path renders the last-known status server-side with a
+ * reload-to-update note. */
+const BUILD_STATUS_POLL_MS = 5000;
+const BUILD_STATUS_URL = "/site-config/design/api/build-status";
+const PUBLISH_WATCH_KEY = "scPublishWatch";
+const BUILD_ERROR_EXCERPT_CHARS = 140;
+
+function initBuildStatus(i18n) {
+  const strip = document.querySelector("[data-sc-build-status]");
+  if (!strip) {
+    // The watch lives only on the page showing the publish flash —
+    // navigating away ends it (a lingering stamp would poison the
+    // "finishedAt after publish" check on the NEXT publish).
+    sessionStorage.removeItem(PUBLISH_WATCH_KEY);
+    return;
+  }
+  const text = strip.querySelector("[data-sc-build-text]");
+  if (!text) return;
+
+  const setText = (value) => {
+    text.textContent = value;
+  };
+
+  // The moment finishedAt must beat for an "ok" to count as terminal.
+  // Stamp path: the publish time. Probe path: 0 — any finished build is
+  // terminal there (see the docblock above).
+  let publishedAt = 0;
+  let timer = null;
+  let ended = false;
+  const endWatch = () => {
+    ended = true;
+    sessionStorage.removeItem(PUBLISH_WATCH_KEY);
+    if (timer) {
+      clearInterval(timer);
+      timer = null;
+    }
+  };
+
+  const render = (status) => {
+    const state = status?.state;
+    if (state === "building") {
+      if (status.stuck) return setText(i18n.buildStuck || "");
+      const seconds =
+        typeof status.lastOkDurationSeconds === "number" && status.lastOkDurationSeconds > 0
+          ? Math.round(status.lastOkDurationSeconds)
+          : null;
+      return setText(
+        seconds
+          ? (i18n.buildBuilding || "").replace("{{seconds}}", String(seconds))
+          : i18n.buildBuildingUnknown || "",
+      );
+    }
+    if (state === "ok") {
+      const finishedAt =
+        typeof status.finishedAt === "string" ? Date.parse(status.finishedAt) : Number.NaN;
+      if (!Number.isNaN(finishedAt) && finishedAt > publishedAt) {
+        // Terminal: the build landed. (Client-side display only —
+        // templates never see this Date.)
+        setText(
+          (i18n.buildLive || "").replace(
+            "{{time}}",
+            new Date(finishedAt).toLocaleTimeString(),
+          ),
+        );
+        endWatch();
+        return;
+      }
+      // Stale ok from before the publish (or finishedAt dropped): the
+      // rebuild hasn't been observed yet — keep waiting.
+      return setText(i18n.buildBuildingUnknown || "");
+    }
+    if (state === "failed") {
+      const parts = [i18n.buildFailed || ""];
+      if (typeof status.error === "string" && status.error !== "") {
+        parts.push(status.error.slice(0, BUILD_ERROR_EXCERPT_CHARS));
+      }
+      parts.push(i18n.buildRetryHint || "");
+      setText(parts.filter(Boolean).join(" "));
+      endWatch(); // terminal: failed (the live site is unchanged)
+      return;
+    }
+    // unknown — or any unrecognized/garbage state — renders neutral copy
+    // and keeps polling (the writer may catch up).
+    setText(i18n.buildUnknown || "");
+  };
+
+  const fetchStatus = async () => {
+    try {
+      const response = await fetch(BUILD_STATUS_URL, {
+        headers: { Accept: "application/json" },
+      });
+      if (!response.ok) return null; // transient — caller keeps polling
+      return await response.json();
+    } catch {
+      return null; // network blip — the last rendered copy stands
+    }
+  };
+
+  const tick = async () => {
+    const status = await fetchStatus();
+    if (status) render(status);
+  };
+
+  const stamp = Number(sessionStorage.getItem(PUBLISH_WATCH_KEY));
+  if (Number.isFinite(stamp) && stamp > 0) {
+    // Mid-watch reload of the flash page: keep the original publish stamp.
+    publishedAt = stamp;
+    timer = setInterval(tick, BUILD_STATUS_POLL_MS);
+    tick();
+    return;
+  }
+
+  // No stamp: a fresh publish flash, or a reload after the watch ended.
+  // Probe FIRST — in probe mode (publishedAt 0) render() treats any ok
+  // with a finishedAt, and any failed, as terminal: show it, never watch.
+  (async () => {
+    const status = await fetchStatus();
+    if (status) render(status);
+    if (ended) return; // already terminal — the rendered copy is final
+    publishedAt = Date.now();
+    sessionStorage.setItem(PUBLISH_WATCH_KEY, String(publishedAt));
+    timer = setInterval(tick, BUILD_STATUS_POLL_MS);
+  })();
+}
+
 const i18n = readI18n();
 initSortable();
 initAddDialog();
 initSearchFilter(i18n);
 initUndoFlash(i18n);
+initPreviewPane(i18n);
+initBuildStatus(i18n);

package/lib/controllers/design.js

@@ -49,6 +49,14 @@ import {
   createDraftFromTree,
 } from "../storage/composition-draft.js";
 import { buildHomepageTree } from "../storage/migrate-v3-to-v4.js";
+import {
+  getPreviewState,
+  ensureToken,
+  bumpRevision,
+  rotateToken,
+} from "../storage/preview-state.js";
+import { readBuildStatus } from "../storage/read-build-status.js";
+import { writePreviewDraft } from "../render/write-preview-draft.js";
 import { treeToZones, zonesToTree } from "../editor/zones.js";
 import {
   addBlock,
@@ -162,6 +170,91 @@ export function parseUndoPayload(raw) {
   }
 }
 
+// Stuck-build detection (spec §5.3): a "building" state that has overrun
+// max(2 × lastOkDurationSeconds, 120) seconds. The 120s floor matters — the
+// first post-boot build is FULL (~2min on the big site) while
+// lastOkDurationSeconds usually reflects a fast incremental, so without the
+// floor every reboot would flag a false stuck. 60 is the formula's default
+// when the duration is absent or garbage (2 × 60 = the floor).
+const STUCK_FLOOR_SECONDS = 120;
+const STUCK_DEFAULT_OK_SECONDS = 60;
+
+/**
+ * Is this build-status object an overdue ("stuck") build?
+ *
+ * Tolerant by contract: start.sh's crash wrapper drops fields, so a
+ * "building" object missing (or garbling) `startedAt` is NEVER stuck — we
+ * can't measure how long it has run, and a false "stuck" banner is worse
+ * than a quiet one.
+ *
+ * @param {object | null | undefined} status Parsed build-status content
+ * @param {number} nowMs Current epoch ms (injected for tests)
+ * @returns {boolean}
+ */
+export function isStuckBuild(status, nowMs) {
+  if (status?.state !== "building") return false;
+  const startedAt =
+    typeof status.startedAt === "string" ? Date.parse(status.startedAt) : Number.NaN;
+  if (Number.isNaN(startedAt)) return false;
+  const lastOk =
+    typeof status.lastOkDurationSeconds === "number" && status.lastOkDurationSeconds > 0
+      ? status.lastOkDurationSeconds
+      : STUCK_DEFAULT_OK_SECONDS;
+  const thresholdMs = Math.max(2 * lastOk, STUCK_FLOOR_SECONDS) * 1000;
+  return nowMs - startedAt > thresholdMs;
+}
+
+/**
+ * The build-status API/locals shape: the raw file fields + computed `stuck`;
+ * absent/corrupt file (reader returned null) → a neutral unknown. An
+ * unrecognized `state` passes through untouched — the UI owns rendering
+ * anything unrecognized as unknown.
+ *
+ * `finishedAt` is the one field the view DATE-FORMATS (`| date` → date-fns
+ * parseISO, which crashes/garbles on non-ISO values), so an unparseable
+ * value is stripped here at the single shared merge point (API + GET
+ * locals): the view's ok branch is gated on the field and falls through to
+ * the neutral no-time copy instead of crashing the no-JS GET.
+ *
+ * @param {object | null} status Result of readBuildStatus
+ * @param {number} [nowMs=Date.now()]
+ * @returns {object} `{ ...status, stuck }` or `{ state: "unknown", stuck: false }`
+ */
+export function mergeBuildStatus(status, nowMs = Date.now()) {
+  if (!status) return { state: "unknown", stuck: false };
+  const merged = { ...status, stuck: isStuckBuild(status, nowMs) };
+  if (
+    merged.finishedAt !== undefined &&
+    (typeof merged.finishedAt !== "string" || Number.isNaN(Date.parse(merged.finishedAt)))
+  ) {
+    delete merged.finishedAt; // merged is our own copy — the input stays untouched
+  }
+  return merged;
+}
+
+/**
+ * GET /design/api/build-status handler factory (Phase 5 S2). A passive fs
+ * read of /app/data/build-status.json — cheap enough for the publish strip's
+ * 5s polling. Cache-Control: no-store (a build status is stale the moment
+ * it's cached). NEVER 500s on an absent/corrupt file — the tolerant reader
+ * maps both to unknown.
+ *
+ * @param {object} [options] Test seams
+ * @param {() => Promise<object | null>} [options.readStatus]
+ * @param {() => number} [options.now]
+ * @returns {import("express").RequestHandler}
+ */
+export function buildStatusHandler({ readStatus = readBuildStatus, now = Date.now } = {}) {
+  return async (request, response, next) => {
+    try {
+      response.set("Cache-Control", "no-store");
+      response.json(mergeBuildStatus(await readStatus(), now()));
+    } catch (error) {
+      next(error);
+    }
+  };
+}
+
 /**
  * Surface redirect query params as flash template vars.
  * @param {object} [query]
@@ -305,10 +398,21 @@ function findNode(zones, blockId) {
  * @param {(prefix: string) => string} [overrides.idFactory]
  * @param {(doc: object) => Promise<unknown>} [overrides.writeArtifact]
  *   Forwarded to publishDraft (defaults to the real artifact writer there)
+ * @param {(input: object) => Promise<unknown>} [overrides.writePreviewArtifact]
+ *   Preview-draft writer (defaults to writePreviewDraft)
+ * @param {() => Promise<object | null>} [overrides.readStatus]
+ *   build-status.json reader (defaults to readBuildStatus)
+ * @param {() => number} [overrides.now] Clock (stuck math test seam)
  * @returns {import("express").Router}
  */
 export function designRouter(Indiekit, overrides = {}) {
-  const { idFactory = defaultIdFactory, writeArtifact } = overrides;
+  const {
+    idFactory = defaultIdFactory,
+    writeArtifact,
+    writePreviewArtifact = writePreviewDraft,
+    readStatus = readBuildStatus,
+    now = Date.now,
+  } = overrides;
   const router = express.Router();
 
   const catalogOf = () => Indiekit.config?.application?.blockCatalog || [];
@@ -361,9 +465,20 @@ export function designRouter(Indiekit, overrides = {}) {
     };
     if (!state) return { ...base, noComposition: true };
     const zones = treeToZones(state.tree);
+    // Custom-tree preview scope (deliberate, Phase 5): the preview POST
+    // accepts custom trees (they render fine through the production
+    // renderer), but this read-only view offers NO preview pane affordance —
+    // the editor is read-only for custom trees, full stop. Hand-built trees
+    // are previewed by their authors out-of-band.
     if (zones.custom) return { ...base, customTree: true, isDraft: state.isDraft };
     const token = typeof query.u === "string" ? query.u : null;
     const undo = token ? parseUndoPayload(token) : null;
+    // Right-pane mode is server state (?pane=preview) so the toggle works
+    // without JS by full reload; structural stays the default.
+    const pane = query.pane === "preview" ? "preview" : "structural";
+    const preview = Indiekit.database
+      ? await getPreviewState(Indiekit.database)
+      : { token: null, revision: 0 };
     return {
       ...base,
       zones,
@@ -372,6 +487,9 @@ export function designRouter(Indiekit, overrides = {}) {
       isDraft: state.isDraft,
       draftUpdatedAt: state.doc.draftUpdatedAt ?? null,
       undo: undo ? { ...undo, token } : null,
+      pane,
+      preview,
+      previewing: typeof query.previewing === "string" ? query.previewing : null,
       ...extra,
     };
   }
@@ -410,12 +528,24 @@ export function designRouter(Indiekit, overrides = {}) {
       const db = requireDb(response);
       if (!db) return;
       const state = await getEditorState(db, SURFACE_ID);
-      response.render(EDITOR_VIEW, await editorLocals(state, request.query ?? {}));
+      const query = request.query ?? {};
+      // No-JS publish flow: ?published=1 renders the LAST-KNOWN build status
+      // server-side (same tolerant reader as the API) with a reload-to-update
+      // note; editor.js replaces it with 5s polling.
+      const extra = query.published
+        ? { buildStatus: mergeBuildStatus(await readStatus(), now()) }
+        : {};
+      response.render(EDITOR_VIEW, await editorLocals(state, query, extra));
     } catch (error) {
       next(error);
     }
   });
 
+  // -- build-status API (Phase 5 S2) --
+  // Authed (the whole design router mounts behind the session gate);
+  // polled every 5s by the publish strip in editor.js.
+  router.get("/api/build-status", buildStatusHandler({ readStatus, now }));
+
   router.post("/homepage/blocks/add", async (request, response, next) => {
     try {
       const db = requireDb(response);
@@ -665,6 +795,40 @@ export function designRouter(Indiekit, overrides = {}) {
     }
   });
 
+  // On-demand preview-draft write (Phase 5). NOTE: custom trees ARE allowed
+  // here — a custom tree renders through the same PRODUCTION renderer at
+  // /preview/<token>/; only the EDITOR (block ops) is read-only for custom
+  // trees. The artifact is written ONLY on this explicit POST and on publish
+  // (every write triggers an incremental Eleventy rebuild — ~25s on large
+  // sites), never per keystroke.
+  router.post("/homepage/preview", async (request, response, next) => {
+    try {
+      const db = requireDb(response);
+      if (!db) return;
+      const state = await getEditorState(db, SURFACE_ID);
+      // state.tree = draftTree ?? published tree; a doc with neither (never
+      // seeded, draft discarded) has nothing to preview.
+      if (!state?.tree) return flashError(response, "no-composition");
+      const token = await ensureToken(db);
+      const revision = await bumpRevision(db);
+      await writePreviewArtifact({ tree: state.tree, revision, token });
+      // Dual response (plain-POST-first): editor.js fetches with
+      // Accept: application/json; the no-JS form post gets the standard
+      // redirect and the GET locals carry token/revision.
+      if ((request.headers?.accept ?? "").includes("application/json")) {
+        const status = await readStatus();
+        const expectedSeconds =
+          typeof status?.lastOkDurationSeconds === "number"
+            ? status.lastOkDurationSeconds
+            : null;
+        return response.json({ token, revision, expectedSeconds });
+      }
+      return response.redirect(303, `${HOME}?pane=preview&previewing=${revision}`);
+    } catch (error) {
+      next(error);
+    }
+  });
+
   router.post("/homepage/publish", async (request, response, next) => {
     try {
       const db = requireDb(response);
@@ -673,7 +837,29 @@ export function designRouter(Indiekit, overrides = {}) {
         ...(writeArtifact ? { writeArtifact } : {}),
         updatedBy: userIdent(),
       });
-      if (result.ok) return response.redirect(303, `${HOME}?published=1`);
+      if (result.ok) {
+        // Per-publish token rotation (spec §5.3): previously shared preview
+        // URLs expire — the old /preview/<token>/ page dies on the next
+        // rebuild, intentionally. A FRESH preview-draft is written from the
+        // now-published tree so the preview pane tracks the NEW token
+        // immediately. The publish itself already succeeded (db promotion +
+        // artifact) — a preview refresh failure must never turn it into an
+        // error page, so this block only warns.
+        try {
+          const token = await rotateToken(db);
+          const revision = await bumpRevision(db);
+          const published = await db.collection("compositions").findOne({ _id: SURFACE_ID });
+          if (published?.tree) {
+            await writePreviewArtifact({ tree: published.tree, revision, token });
+          }
+        } catch (error) {
+          console.warn(
+            "[site-config] preview rotation after publish failed:",
+            error?.message ?? String(error),
+          );
+        }
+        return response.redirect(303, `${HOME}?published=1`);
+      }
       if (result.error === "not-found") return flashError(response, "no-composition");
       if (result.error === "conflict") return flashError(response, "conflict");
       // The flash only says "failed validation" — log the actual validator

package/lib/render/write-preview-draft.js

@@ -0,0 +1,74 @@
+/**
+ * Preview-draft artifact writer (site-builder Phase 5, spec §2.4/§5.3).
+ *
+ * The theme's `/preview/<token>/` page renders this artifact through the
+ * PRODUCTION composition renderer (zero drift from the live homepage).
+ * Written ON DEMAND only — the editor's explicit "Update preview" POST and
+ * the post-publish refresh — NEVER per keystroke: every artifact write
+ * triggers an incremental Eleventy rebuild (~25s on large sites).
+ *
+ * The artifact is BUILT from explicit arguments (never picked off a MongoDB
+ * doc), so editor-internal fields can't leak by construction — the same
+ * deliberate-contract posture as write-composition-json.js's whitelist.
+ *
+ * Uses tmp-file + rename so the Eleventy watcher never reads a partial file
+ * (a direct writeFile races the watcher and can crash the build on
+ * JSON.parse). Mirrors the atomic pattern in write-composition-json.js.
+ *
+ * The token is an unguessable-path token (defense in depth, rotated on
+ * publish) — it ends up in this public-ish artifact and the preview URL by
+ * design, but must never be logged.
+ * @module render/write-preview-draft
+ */
+
+import { writeFile, rename, mkdir, unlink } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { join } from "node:path";
+
+export const PREVIEW_DRAFT_FILE = "preview-draft.json";
+
+const isoNow = () => new Date().toISOString();
+
+/**
+ * Write the preview-draft artifact to disk atomically (tmp file → rename).
+ * Creates the output directory if it does not exist.
+ *
+ * @param {object} input
+ * @param {object} input.tree - Composition tree to preview (draft or published)
+ * @param {number} input.revision - Monotonic preview revision (preview-state.js)
+ * @param {string} input.token - Unguessable preview path token (preview-state.js)
+ * @param {string} [outputDir="/app/data/content/_data/compositions"] - Destination directory
+ * @param {object} [options]
+ * @param {() => string} [options.now] ISO timestamp factory (workspace rule:
+ *   dates are ISO 8601 strings, never Date objects)
+ * @returns {Promise<string>} The output path written
+ */
+export async function writePreviewDraft(
+  { tree, revision, token },
+  outputDir = "/app/data/content/_data/compositions",
+  options = {},
+) {
+  const { now = isoNow } = options;
+  // Explicit construction — exactly the spec §2.4 shape, nothing else.
+  const artifact = {
+    schemaVersion: 4,
+    kind: "preview",
+    tree,
+    revision,
+    token,
+    generatedAt: now(),
+  };
+
+  const outputPath = join(outputDir, PREVIEW_DRAFT_FILE);
+  await mkdir(outputDir, { recursive: true });
+  const tmp = `${outputPath}.${randomBytes(6).toString("hex")}.tmp`;
+  try {
+    await writeFile(tmp, JSON.stringify(artifact, undefined, 2), "utf8");
+    await rename(tmp, outputPath);
+  } catch (error) {
+    // Best-effort cleanup — don't leak tmp files into the watched _data dir.
+    await unlink(tmp).catch(() => {});
+    throw error;
+  }
+  return outputPath;
+}

package/lib/storage/preview-state.js

@@ -0,0 +1,118 @@
+/**
+ * Preview token + revision lifecycle (site-builder Phase 5, spec §5.3) —
+ * stored as sibling fields on the siteConfig doc (`previewToken`,
+ * `previewRevision`), the same same-doc posture as composition-draft.js.
+ *
+ * THE TOKEN: 16 random bytes, base64url (≈22 chars) — an unguessable-path
+ * token for `/preview/<token>/`, ephemeral defense-in-depth. It is NEVER an
+ * IndieAuth token and must never be logged. Rotated unconditionally on every
+ * publish so previously shared preview URLs expire (the old URL dies on the
+ * next rebuild — intentional, per-publish rotation policy).
+ *
+ * THE REVISION: a monotonic integer bumped on every preview-draft write. The
+ * theme's preview page embeds it (`data-preview-revision`); the editor polls
+ * the iframe until the just-written revision shows up.
+ *
+ * ATOMICITY: field-level updates only ($set / $setOnInsert / $inc — never a
+ * whole-doc replace), matching the composition-draft.js convention.
+ * ensureToken is read-back-after-atomic-write so concurrent boots/requests
+ * always converge on the single persisted token, never two.
+ *
+ * @module storage/preview-state
+ */
+
+import { randomBytes } from "node:crypto";
+
+const SITE_CONFIG_ID = "primary";
+
+const defaultRandom = () => randomBytes(16).toString("base64url");
+
+/**
+ * Read the current preview state from the siteConfig doc.
+ *
+ * @param {object} db MongoDB database handle (`collection(name)`)
+ * @returns {Promise<{ token: string | null, revision: number }>}
+ */
+export async function getPreviewState(db) {
+  const doc = await db.collection("siteConfig").findOne({ _id: SITE_CONFIG_ID });
+  return {
+    token: doc?.previewToken ?? null,
+    revision: doc?.previewRevision ?? 0,
+  };
+}
+
+/**
+ * Return the persisted preview token, generating one atomically when absent.
+ *
+ * Two atomic field-level writes + a read-back: (1) $setOnInsert via upsert
+ * covers the no-doc case (a concurrent upsert race surfaces as a duplicate
+ * _id error — swallowed, the doc now exists either way); (2) a
+ * $exists-filtered $set covers a pre-existing doc that lacks the field
+ * (exactly one concurrent caller matches). The read-back is authoritative,
+ * so every concurrent caller returns the SAME persisted token — never two.
+ *
+ * @param {object} db
+ * @param {object} [options]
+ * @param {() => string} [options.random] Token factory (test seam)
+ * @returns {Promise<string>} The persisted token
+ */
+export async function ensureToken(db, options = {}) {
+  const { random = defaultRandom } = options;
+  const candidate = random();
+  const siteConfig = db.collection("siteConfig");
+  try {
+    await siteConfig.updateOne(
+      { _id: SITE_CONFIG_ID },
+      { $setOnInsert: { previewToken: candidate } },
+      { upsert: true },
+    );
+  } catch (error) {
+    // E11000: a concurrent upsert inserted the doc first — fine, it exists.
+    if (error?.code !== 11_000) throw error;
+  }
+  await siteConfig.updateOne(
+    { _id: SITE_CONFIG_ID, previewToken: { $exists: false } },
+    { $set: { previewToken: candidate } },
+  );
+  const doc = await siteConfig.findOne({ _id: SITE_CONFIG_ID });
+  return doc.previewToken;
+}
+
+/**
+ * Atomically increment the preview revision and return the NEW value
+ * (findOneAndUpdate, not update-then-read — a racing bump can never make two
+ * callers see the same number).
+ *
+ * @param {object} db
+ * @returns {Promise<number>} The post-increment revision
+ */
+export async function bumpRevision(db) {
+  const result = await db.collection("siteConfig").findOneAndUpdate(
+    { _id: SITE_CONFIG_ID },
+    { $inc: { previewRevision: 1 } },
+    { upsert: true, returnDocument: "after" },
+  );
+  // Driver v4/v5 wraps the doc in { value }; v6 returns it directly.
+  const doc = result?.value ?? result;
+  return doc.previewRevision;
+}
+
+/**
+ * Unconditionally replace the preview token (the publish path — every
+ * publish expires previously shared preview URLs).
+ *
+ * @param {object} db
+ * @param {object} [options]
+ * @param {() => string} [options.random] Token factory (test seam)
+ * @returns {Promise<string>} The new token
+ */
+export async function rotateToken(db, options = {}) {
+  const { random = defaultRandom } = options;
+  const token = random();
+  await db.collection("siteConfig").updateOne(
+    { _id: SITE_CONFIG_ID },
+    { $set: { previewToken: token } },
+    { upsert: true },
+  );
+  return token;
+}

package/lib/storage/read-build-status.js

@@ -0,0 +1,35 @@
+/**
+ * Tolerant reader for the Eleventy build-status file (site-builder Phase 5,
+ * spec §2.4/§5.3). The file lives OUTSIDE the site output at
+ * `/app/data/build-status.json` — written by the theme's build hooks
+ * (building/ok) and start.sh's crash wrapper (failed); read here by the
+ * preview flow (S1: `lastOkDurationSeconds` → "~Xs on this site" copy) and
+ * the authed build-status API (S2).
+ *
+ * TOLERANT BY CONTRACT: absent, unreadable, corrupt, or non-object content
+ * all return null — the status file is an observability aid and must never
+ * take a request down. Callers own the "unknown" presentation.
+ *
+ * @module storage/read-build-status
+ */
+
+import { readFile } from "node:fs/promises";
+
+export const BUILD_STATUS_PATH = "/app/data/build-status.json";
+
+/**
+ * Read and parse the build-status file.
+ *
+ * @param {string} [path=BUILD_STATUS_PATH] File path (test seam)
+ * @returns {Promise<object | null>} The parsed status object, or null when
+ *   the file is absent/corrupt/not a plain object
+ */
+export async function readBuildStatus(path = BUILD_STATUS_PATH) {
+  try {
+    const parsed = JSON.parse(await readFile(path, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}

package/locales/en.json

@@ -269,6 +269,30 @@
       },
       "preview": {
         "title": "Layout preview"
+      },
+      "previewPane": {
+        "toggleLabel": "Preview mode",
+        "structural": "Structural",
+        "live": "Preview",
+        "update": "Update preview",
+        "reload": "Reload preview",
+        "frameTitle": "Homepage preview",
+        "empty": "No preview yet — choose “Update preview” to build one.",
+        "requested": "Preview update requested — the site is rebuilding. Reload this page in a moment to refresh the preview.",
+        "building": "Building preview… (~{{seconds}}s on this site)",
+        "buildingUnknown": "Building preview…",
+        "ready": "Preview is up to date.",
+        "slow": "This is taking longer than usual — the preview will appear once the build finishes. Use “Reload preview” to check again."
+      },
+      "buildStatus": {
+        "building": "Rebuilding — usually ~{{seconds}}s on this site. Your current site stays online.",
+        "buildingUnknown": "Rebuilding — your current site stays online.",
+        "live": "Live · {{time}}",
+        "failed": "Build failed — your live site is unchanged.",
+        "retryHint": "Republish to retry.",
+        "stuck": "This is taking longer than usual. Publishing again rewrites the homepage and usually unblocks a stalled build.",
+        "unknown": "Build status unavailable — your live site is unchanged.",
+        "reloadNote": "Reload this page to update the build status."
       }
     },
     "homepage": {

package/locales/fr.json

@@ -269,6 +269,30 @@
       },
       "preview": {
         "title": "Aperçu de la mise en page"
+      },
+      "previewPane": {
+        "toggleLabel": "Mode d'aperçu",
+        "structural": "Structure",
+        "live": "Aperçu",
+        "update": "Mettre à jour l'aperçu",
+        "reload": "Recharger l'aperçu",
+        "frameTitle": "Aperçu de la page d'accueil",
+        "empty": "Pas encore d'aperçu — choisissez « Mettre à jour l'aperçu » pour le générer.",
+        "requested": "Mise à jour de l'aperçu demandée — le site se reconstruit. Rechargez cette page dans un instant pour actualiser l'aperçu.",
+        "building": "Construction de l'aperçu… (~{{seconds}} s sur ce site)",
+        "buildingUnknown": "Construction de l'aperçu…",
+        "ready": "L'aperçu est à jour.",
+        "slow": "C'est plus long que d'habitude — l'aperçu apparaîtra à la fin de la construction. Utilisez « Recharger l'aperçu » pour vérifier."
+      },
+      "buildStatus": {
+        "building": "Reconstruction en cours — environ {{seconds}} s sur ce site. Votre site actuel reste en ligne.",
+        "buildingUnknown": "Reconstruction en cours — votre site actuel reste en ligne.",
+        "live": "En ligne · {{time}}",
+        "failed": "La construction a échoué — votre site en ligne est inchangé.",
+        "retryHint": "Republiez pour réessayer.",
+        "stuck": "C'est plus long que d'habitude. Republier réécrit la page d'accueil et débloque généralement une construction bloquée.",
+        "unknown": "Statut de construction indisponible — votre site en ligne est inchangé.",
+        "reloadNote": "Rechargez cette page pour actualiser le statut de construction."
       }
     },
     "homepage": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rmdes/indiekit-endpoint-site-config",
-  "version": "1.0.0-beta.13",
+  "version": "1.0.0-beta.15",
   "type": "module",
   "description": "Site identity, branding, and navigation configuration for Indiekit",
   "main": "index.js",

package/views/partials/design-preview-live.njk

@@ -0,0 +1,34 @@
+{# True preview pane (Phase 5, right pane when ?pane=preview). The iframe is
+   the theme's /preview/<token>/ page — the preview-draft.json artifact
+   rendered through the PRODUCTION composition renderer (zero drift), same
+   origin as the admin. The artifact is written ONLY by the Update-preview
+   POST (and on publish) — never per keystroke (every write triggers an
+   incremental Eleventy rebuild).
+
+   No-JS path: the form POST redirects back with
+   ?pane=preview&previewing=<revision>; the status line says the site is
+   rebuilding and a full page reload refreshes the iframe. editor.js
+   enhances with fetch (Accept: application/json) + same-origin revision
+   polling. Context: preview {token, revision}, previewing. #}
+<div class="sc-design__preview sc-design__preview--live">
+  <div class="sc-preview-bar">
+    <form method="post" action="/site-config/design/homepage/preview" class="sc-mini-form" data-sc-preview-form>
+      <button class="button button--small">{{ __("siteConfig.design.previewPane.update") }}</button>
+    </form>
+    {# JS-only manual reload affordance — editor.js reveals it. #}
+    <button type="button" class="button button--small button--secondary" hidden data-sc-preview-reload>
+      {{ __("siteConfig.design.previewPane.reload") }}
+    </button>
+  </div>
+  <p class="sc-preview-status" data-sc-preview-status aria-live="polite">
+    {%- if previewing %}{{ __("siteConfig.design.previewPane.requested") }}{% endif -%}
+  </p>
+  {% if preview.token %}
+  <iframe class="sc-preview-frame" data-sc-preview-frame
+    src="/preview/{{ preview.token }}/"
+    data-sc-revision="{{ preview.revision }}"
+    title="{{ __('siteConfig.design.previewPane.frameTitle') }}"></iframe>
+  {% else %}
+  <p class="sc-preview-empty" data-sc-preview-empty>{{ __("siteConfig.design.previewPane.empty") }}</p>
+  {% endif %}
+</div>

package/views/site-config-design-homepage.njk

@@ -30,9 +30,25 @@
    deferred classic scripts and modules both execute in document order. #}
 <script src="/assets/@rmdes-indiekit-endpoint-site-config/vendor/Sortable.min.js" defer></script>
 <script type="module" src="/assets/@rmdes-indiekit-endpoint-site-config/editor.js"></script>
+{# i18n's __() interpolates {{var}} at RENDER time (mustache: a missing
+   variable becomes an empty string). Strings whose placeholders are replaced
+   CLIENT-side by editor.js must be passed through as themselves
+   (e.g. { seconds: "{{seconds}}" }) so the literal placeholder survives. #}
 {% set editorI18n = {
   searchEmpty: __("siteConfig.design.addBlock.searchEmpty"),
-  dismiss: __("siteConfig.design.flash.dismiss")
+  dismiss: __("siteConfig.design.flash.dismiss"),
+  previewBuilding: __("siteConfig.design.previewPane.building", { seconds: "{{seconds}}" }),
+  previewBuildingUnknown: __("siteConfig.design.previewPane.buildingUnknown"),
+  previewReady: __("siteConfig.design.previewPane.ready"),
+  previewSlow: __("siteConfig.design.previewPane.slow"),
+  previewFrameTitle: __("siteConfig.design.previewPane.frameTitle"),
+  buildBuilding: __("siteConfig.design.buildStatus.building", { seconds: "{{seconds}}" }),
+  buildBuildingUnknown: __("siteConfig.design.buildStatus.buildingUnknown"),
+  buildLive: __("siteConfig.design.buildStatus.live", { time: "{{time}}" }),
+  buildFailed: __("siteConfig.design.buildStatus.failed"),
+  buildRetryHint: __("siteConfig.design.buildStatus.retryHint"),
+  buildStuck: __("siteConfig.design.buildStatus.stuck"),
+  buildUnknown: __("siteConfig.design.buildStatus.unknown")
 } %}
 <script type="application/json" id="sc-editor-i18n">{{ editorI18n | dump | replace("</", "<\\/") | safe }}</script>
 
@@ -229,12 +245,56 @@
       </form>
       {% else %}
       <p class="sc-draft-bar__status">{{ __("siteConfig.design.draftBar.live") }}</p>
+      {# Publish-flow build-status strip (Phase 5 S2): renders ONLY on the
+         publish flash (?published=1) with the LAST-KNOWN status server-side
+         (no-JS path; the noscript note says reload to update — no
+         meta-refresh). editor.js takes over with 5s polling of the
+         build-status API. Unrecognized states render the neutral copy. #}
+      {% if success == "published" %}
+      <div class="sc-build-status" data-sc-build-status aria-live="polite">
+        <p class="sc-build-status__text" data-sc-build-text>
+          {%- if buildStatus.state == "building" and buildStatus.stuck %}
+          {{ __("siteConfig.design.buildStatus.stuck") }}
+          {%- elif buildStatus.state == "building" %}
+          {%- if buildStatus.lastOkDurationSeconds is number and buildStatus.lastOkDurationSeconds > 0 %}
+          {{ __("siteConfig.design.buildStatus.building", { seconds: buildStatus.lastOkDurationSeconds | round }) }}
+          {%- else %}
+          {{ __("siteConfig.design.buildStatus.buildingUnknown") }}
+          {%- endif %}
+          {%- elif buildStatus.state == "ok" and buildStatus.finishedAt %}
+          <time datetime="{{ buildStatus.finishedAt }}">{{ __("siteConfig.design.buildStatus.live", { time: buildStatus.finishedAt | date("PPp") }) }}</time>
+          {%- elif buildStatus.state == "failed" %}
+          {{ __("siteConfig.design.buildStatus.failed") }}
+          {%- if buildStatus.error %} {{ buildStatus.error | truncate(140) }}{% endif %}
+          {{ __("siteConfig.design.buildStatus.retryHint") }}
+          {%- else %}
+          {{ __("siteConfig.design.buildStatus.unknown") }}
+          {%- endif %}
+        </p>
+        <noscript><p class="sc-build-status__note">{{ __("siteConfig.design.buildStatus.reloadNote") }}</p></noscript>
+      </div>
+      {% endif %}
       {% endif %}
     </div>
   </div>
 
-  {# Right pane: structural preview #}
-  {% include "partials/design-preview.njk" %}
+  {# Right pane: Structural (Phase 4 skeleton, default) | Preview (Phase 5
+     true preview — the theme renders preview-draft.json through the
+     PRODUCTION renderer at /preview/<token>/). Pane choice is server state
+     (?pane=preview) via plain links, so no-JS toggles by full reload. #}
+  <div class="sc-design__pane">
+    <nav class="sc-pane-toggle" aria-label="{{ __('siteConfig.design.previewPane.toggleLabel') }}">
+      <a class="sc-pane-toggle__link" href="/site-config/design/homepage"
+        {%- if pane != "preview" %} aria-current="true"{% endif %}>{{ __("siteConfig.design.previewPane.structural") }}</a>
+      <a class="sc-pane-toggle__link" href="/site-config/design/homepage?pane=preview"
+        {%- if pane == "preview" %} aria-current="true"{% endif %}>{{ __("siteConfig.design.previewPane.live") }}</a>
+    </nav>
+    {% if pane == "preview" %}
+    {% include "partials/design-preview-live.njk" %}
+    {% else %}
+    {% include "partials/design-preview.njk" %}
+    {% endif %}
+  </div>
 </div>
 
 {# The shared add-block dialog (one per page; zone preset by editor.js) #}