@tokenoftrust/storefront-runner 1.4.2-rc.0 → 2.0.0

package/apps/storefront/src/lib/publish/reviewReleaseWorkspace/controller.ts

@@ -0,0 +1,325 @@
+/**
+ * Client controller for the merchant Review-and-Release workspace (`review-release.astro`).
+ *
+ * Reads server-stamped context from the root element, polls `GET /api/changes`,
+ * derives the two-decision view model with the pure `@/lib/publish/reviewRelease`
+ * seam, renders it with the pure `render.ts`, and wires the ONLY two actions —
+ * "Add to next release" and "Publish now". It owns the browser-only concerns the
+ * pure modules can't: poll cadence, the `shipInFlight` "Publishing…" transient, the
+ * publish confirmation dialog (focus trap + Esc + focus return), and ARIA-live
+ * discipline (one announcement per REAL state transition, never per poll tick).
+ *
+ * Not unit-tested (the storefront test env is `node`, no DOM) — the render + action
+ * logic it composes IS tested; this glue is verified on a live preview.
+ */
+import {
+  buildReviewReleaseViewModel,
+  formatReleaseDate,
+  READ_ONLY_NOTE,
+  UNDO_TOAST_COPY,
+  type ReviewReleaseViewModel,
+  type ReviewReleaseContext,
+  type ChangesPayload,
+} from "@/lib/publish/reviewRelease";
+import { renderWorkspace, type LiveReleaseView } from "./render.js";
+import { addChangeToRelease, publishNextRelease } from "./actions.js";
+
+interface WorkspaceContext {
+  changesEndpoint: string;
+  acceptEndpoint: string;
+  shipEndpoint: string;
+  buildEndpoint: string;
+  liveHref: string;
+  canShip: boolean;
+  internalTestStore: boolean;
+  storeName: string;
+  pollMs: number;
+  slowThresholdMs: number;
+}
+
+const DEFAULT_POLL_MS = 8000;
+
+export function initReviewReleaseWorkspace(): void {
+  const root = document.querySelector<HTMLElement>("[data-rr-root]");
+  if (!root) return;
+  const workspace = root.querySelector<HTMLElement>("[data-rr-workspace]");
+  const announcer = root.querySelector<HTMLElement>("[data-rr-announce]");
+  const toast = root.querySelector<HTMLElement>("[data-rr-toast]");
+  if (!workspace) return;
+
+  const ctx: WorkspaceContext = {
+    changesEndpoint: root.dataset.changesEndpoint ?? "/api/changes",
+    acceptEndpoint: root.dataset.acceptEndpoint ?? "/api/changes/accept",
+    shipEndpoint: root.dataset.shipEndpoint ?? "/api/changes/ship",
+    buildEndpoint: root.dataset.buildEndpoint ?? "/api/preview/build",
+    liveHref: root.dataset.liveHref ?? "/",
+    canShip: root.dataset.canShip === "true",
+    internalTestStore: root.dataset.internalTestStore === "true",
+    storeName: root.dataset.storeName ?? "your store",
+    pollMs: Number(root.dataset.pollMs) || DEFAULT_POLL_MS,
+    slowThresholdMs: Number(root.dataset.slowThresholdMs) || 120_000,
+  };
+
+  let shipInFlight = false;
+  let publishSucceeded = false;
+  let prevVm: ReviewReleaseViewModel | null = null;
+  let lastPayload: ChangesPayload | null = null;
+  let busy = false; // an action POST is in flight — suppress a racing re-render
+
+  // ── Rendering ──────────────────────────────────────────────────────────────
+  function render(payload: ChangesPayload): void {
+    lastPayload = payload;
+    const modelCtx: ReviewReleaseContext = {
+      canShip: ctx.canShip,
+      internalTestStore: ctx.internalTestStore,
+      storeName: ctx.storeName,
+      shipInFlight,
+      preparingSlowThresholdMs: ctx.slowThresholdMs,
+    };
+    const vm = buildReviewReleaseViewModel(payload, modelCtx);
+    const current = payload.current ?? {};
+    const live: LiveReleaseView = {
+      versionId: current.versionId ?? null,
+      publishedDate: formatReleaseDate(current.createdAt ?? null),
+      liveHref: ctx.liveHref,
+    };
+    workspace!.innerHTML = renderWorkspace(vm, { liveHref: ctx.liveHref, live, publishSucceeded });
+    announceTransitions(prevVm, vm);
+    prevVm = vm;
+    triggerPreparingWork(vm);
+  }
+
+  // ── "Preparing" must mean something real is happening, not just a claim ────────
+  // A change sits in "preparing" (queued/reconciling/not-built) until something
+  // actually invokes the build/reconcile pipeline — no standing background job
+  // does that on its own. Kick it off automatically, once per change per page
+  // load, so the merchant's "we're working on this" copy is true rather than a
+  // dead label waiting on an external webhook that may never arrive.
+  const triggeredPreparing = new Set<string>();
+  function triggerPreparingWork(vm: ReviewReleaseViewModel): void {
+    if (!ctx.canShip) return;
+    for (const c of vm.changes) {
+      if (c.state !== "preparing") continue;
+      const key = c.changeId ?? (c.prNumber != null ? `pr:${c.prNumber}` : null);
+      if (!key || triggeredPreparing.has(key)) continue;
+      triggeredPreparing.add(key);
+      const body: Record<string, unknown> = {};
+      if (c.prNumber != null) body.pr = c.prNumber;
+      if (c.changeId) body.changeId = c.changeId;
+      fetch(ctx.buildEndpoint, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+      }).catch(() => {}); // best-effort; the next poll just still shows "Preparing" if it failed
+    }
+  }
+
+  function renderReadOnlyFallback(): void {
+    workspace!.innerHTML =
+      `<section class="rr-section"><p class="rr-note">${escapeText(READ_ONLY_NOTE)}</p></section>`;
+  }
+
+  // ── Data ─────────────────────────────────────────────────────────────────────
+  async function load(): Promise<void> {
+    if (busy) return;
+    try {
+      const res = await fetch(ctx.changesEndpoint, { headers: { accept: "application/json" } });
+      if (res.status === 401 || res.status === 403) {
+        renderReadOnlyFallback();
+        return;
+      }
+      if (!res.ok) return; // transient; the next poll retries silently (no merchant error)
+      const payload = (await res.json()) as ChangesPayload;
+      // A completed ship clears the client transient once the server confirms live.
+      if (shipInFlight && payload.aggregate?.queueState === "shipped") shipInFlight = false;
+      render(payload);
+    } catch {
+      // Network blip — leave the last render in place; the poll loop retries.
+    }
+  }
+
+  // ── ARIA-live: one announcement per REAL transition ───────────────────────────
+  function announceTransitions(prev: ReviewReleaseViewModel | null, next: ReviewReleaseViewModel): void {
+    if (!announcer) return;
+    const msgs: string[] = [];
+    if (!prev || prev.nextRelease.state !== next.nextRelease.state) {
+      msgs.push(next.nextRelease.heading);
+    }
+    if (prev) {
+      const before = new Map(prev.changes.map((c) => [c.changeId ?? `pr:${c.prNumber}`, c.state]));
+      for (const c of next.changes) {
+        const key = c.changeId ?? `pr:${c.prNumber}`;
+        const wasState = before.get(key);
+        if (wasState && wasState !== c.state) {
+          const title = c.title?.trim() || (c.prNumber != null ? `Change #${c.prNumber}` : "A change");
+          msgs.push(`${title} is now ${c.label}.`);
+        }
+      }
+    }
+    if (msgs.length) setAnnouncement(msgs.join(" "));
+  }
+
+  function setAnnouncement(text: string): void {
+    if (!announcer) return;
+    announcer.textContent = "";
+    // Force SR pickup of a possibly-repeated message on the next frame.
+    window.requestAnimationFrame(() => {
+      announcer.textContent = text;
+    });
+  }
+
+  function showToast(text: string): void {
+    if (!toast) return;
+    toast.textContent = text;
+    toast.hidden = false;
+    window.setTimeout(() => {
+      toast.hidden = true;
+    }, 5000);
+  }
+
+  // ── Action wiring (event delegation; survives innerHTML re-renders) ────────────
+  workspace.addEventListener("click", (ev) => {
+    const target = ev.target as HTMLElement;
+    const addBtn = target.closest<HTMLButtonElement>("[data-rr-add]");
+    if (addBtn && !addBtn.disabled) {
+      void handleAdd(addBtn);
+      return;
+    }
+    if (target.closest("[data-rr-publish]")) {
+      openConfirm();
+    }
+  });
+
+  async function handleAdd(btn: HTMLButtonElement): Promise<void> {
+    const changeId = btn.dataset.changeId || null;
+    const prRaw = btn.dataset.prNumber;
+    const prNumber = prRaw && Number.isFinite(Number(prRaw)) ? Number(prRaw) : null;
+    btn.disabled = true;
+    btn.setAttribute("aria-busy", "true");
+    busy = true;
+    const result = await addChangeToRelease(
+      { fetch: fetchLike, endpoint: ctx.acceptEndpoint },
+      { changeId, prNumber },
+    );
+    busy = false;
+    if (result.kind === "added") {
+      setAnnouncement("Added to your next release.");
+      showToast(UNDO_TOAST_COPY);
+    } else if (result.kind === "needs-attention") {
+      setAnnouncement("That change needs a developer before it can go live. We've let them know.");
+    } else {
+      setAnnouncement("We couldn't add that just now — it will reappear here if it's still ready.");
+    }
+    await load();
+  }
+
+  // ── Publish confirmation dialog (focus-trapped) ───────────────────────────────
+  const confirmEl = root.querySelector<HTMLElement>("[data-rr-confirm]");
+  const dialogEl = root.querySelector<HTMLElement>("[data-rr-confirm-dialog]");
+  const confirmHeadingEl = root.querySelector<HTMLElement>("[data-rr-confirm-heading]");
+  const confirmBodyEl = root.querySelector<HTMLElement>("[data-rr-confirm-body]");
+  const confirmOkEl = root.querySelector<HTMLButtonElement>("[data-rr-confirm-ok]");
+  const confirmCancelEl = root.querySelector<HTMLButtonElement>("[data-rr-confirm-cancel]");
+  let invokingButton: HTMLElement | null = null;
+
+  function openConfirm(): void {
+    if (!confirmEl || !prevVm?.nextRelease.confirm) return;
+    const confirm = prevVm.nextRelease.confirm;
+    if (confirmHeadingEl) confirmHeadingEl.textContent = confirm.heading;
+    if (confirmBodyEl) confirmBodyEl.textContent = confirm.body;
+    if (confirmOkEl) confirmOkEl.textContent = confirm.confirm;
+    if (confirmCancelEl) confirmCancelEl.textContent = confirm.cancel;
+    invokingButton = document.activeElement as HTMLElement;
+    confirmEl.hidden = false;
+    (confirmOkEl ?? dialogEl)?.focus();
+    document.addEventListener("keydown", onDialogKeydown, true);
+  }
+
+  function closeConfirm(): void {
+    if (!confirmEl) return;
+    confirmEl.hidden = true;
+    document.removeEventListener("keydown", onDialogKeydown, true);
+    invokingButton?.focus();
+    invokingButton = null;
+  }
+
+  function onDialogKeydown(ev: KeyboardEvent): void {
+    if (ev.key === "Escape") {
+      ev.preventDefault();
+      closeConfirm();
+      return;
+    }
+    if (ev.key === "Tab" && dialogEl) {
+      const focusable = dialogEl.querySelectorAll<HTMLElement>(
+        'button, [href], input, [tabindex]:not([tabindex="-1"])',
+      );
+      const first = focusable[0];
+      const last = focusable[focusable.length - 1];
+      if (!first || !last) return;
+      const active = document.activeElement;
+      if (ev.shiftKey && active === first) {
+        ev.preventDefault();
+        last.focus();
+      } else if (!ev.shiftKey && active === last) {
+        ev.preventDefault();
+        first.focus();
+      }
+    }
+  }
+
+  confirmCancelEl?.addEventListener("click", closeConfirm);
+  confirmEl?.addEventListener("click", (ev) => {
+    if (ev.target === confirmEl) closeConfirm(); // backdrop click
+  });
+  confirmOkEl?.addEventListener("click", () => {
+    closeConfirm();
+    void handlePublish();
+  });
+
+  async function handlePublish(): Promise<void> {
+    shipInFlight = true;
+    publishSucceeded = false;
+    // Re-render immediately from the last payload so the release shows "Publishing…"
+    // while the go-live POST is in flight (the client-owned transient, contract §3).
+    if (lastPayload) render(lastPayload);
+    busy = true;
+    const result = await publishNextRelease({ fetch: fetchLike, endpoint: ctx.shipEndpoint });
+    busy = false;
+    if (result.kind === "published") {
+      shipInFlight = false;
+      publishSucceeded = true;
+      setAnnouncement("Your release is live.");
+    } else if (result.kind === "paywall") {
+      shipInFlight = false;
+      setAnnouncement("Publishing to your live store is part of the paid plan.");
+    } else if (result.kind === "not-ready") {
+      shipInFlight = false;
+      setAnnouncement("We're getting your next release ready. Nothing you need to do.");
+    } else if (result.kind === "publish-failed") {
+      shipInFlight = false;
+      setAnnouncement("We couldn't finish publishing. We're retrying — nothing you need to do.");
+    } else {
+      shipInFlight = false;
+      setAnnouncement("We couldn't finish publishing just now. We're retrying automatically.");
+    }
+    await load();
+  }
+
+  // ── Kickoff ───────────────────────────────────────────────────────────────────
+  void load();
+  window.setInterval(() => {
+    if (!confirmEl || confirmEl.hidden) void load();
+  }, ctx.pollMs);
+}
+
+/** Adapt the global `fetch` to the actions' minimal `FetchLike` shape. */
+function fetchLike(
+  input: string,
+  init?: { method?: string; headers?: Record<string, string>; body?: string },
+): Promise<{ ok: boolean; status: number; json: () => Promise<unknown> }> {
+  return fetch(input, init);
+}
+
+function escapeText(value: string): string {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}

package/apps/storefront/src/lib/publish/reviewReleaseWorkspace/render.ts

@@ -0,0 +1,241 @@
+/**
+ * Pure HTML rendering for the merchant Review-and-Release workspace.
+ *
+ * Consumes the already-decided `ReviewReleaseViewModel` (from the
+ * `@/lib/publish/reviewRelease` seam) and returns serializable HTML strings — no
+ * DOM, no I/O — so it is exhaustively node-testable (the storefront test env is
+ * `node`, not jsdom; interaction/focus is verified on a live preview). The client
+ * controller injects these strings and wires events; this module invents NO copy
+ * (the seam's view model is the single source of truth) and adds NO merchant
+ * action beyond the two the model carries.
+ */
+import type {
+  ReviewReleaseViewModel,
+  ChangeCardView,
+  NextReleaseView,
+  MerchantPermissions,
+} from "@/lib/publish/reviewRelease";
+import { NO_CHANGES_COPY, PUBLISH_SUCCESS_COPY } from "@/lib/publish/reviewRelease";
+
+/** Best-effort "what's live now" pointer (contract §9.7 history gap: no full history yet). */
+export interface LiveReleaseView {
+  /** The live version id (short-rendered), or null when nothing is live. */
+  versionId: string | null;
+  /** Deterministic "Mon D, YYYY" published date, or "" when unknown. */
+  publishedDate: string;
+  /** basePath-aware href to the live store root. */
+  liveHref: string;
+}
+
+export interface WorkspaceRenderOptions {
+  /** basePath-aware href to the live store root (for the release "View your live store"). */
+  liveHref: string;
+  /** The current live release pointer, rendered as a persistent "Live" section. */
+  live: LiveReleaseView;
+  /** The post-publish success line + link is shown only right after a publish. */
+  publishSucceeded?: boolean;
+}
+
+/** HTML-escape an interpolated dynamic value (titles come from PR titles; store name from config). */
+export function esc(value: string): string {
+  return value
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+const READONLY_NOTE_ID = "rr-readonly-note";
+const TESTSTORE_NOTE_ID = "rr-teststore-note";
+const PAYWALL_NOTE_ID = "rr-paywall-note";
+
+// ── Change cards ───────────────────────────────────────────────────────────────
+
+/** The display title for a change: its human title, else a PR/change reference. */
+function changeTitle(c: ChangeCardView): string {
+  if (c.title && c.title.trim()) return c.title.trim();
+  if (typeof c.prNumber === "number") return `Change #${c.prNumber}`;
+  if (c.changeId) return c.changeId;
+  return "Change";
+}
+
+/**
+ * One change row. The status chip always carries its state WORD (color-independent,
+ * a11y §8). The "Add to next release" button appears only on `ready-to-add`; when the
+ * viewer is read-only it is rendered `disabled` with an `aria-describedby` pointing at
+ * the read-only note (never hidden — contract §6). `needs-attention` carries no
+ * action at all — its subline already states the developer was notified.
+ */
+export function renderChangeCard(c: ChangeCardView, perms: MerchantPermissions): string {
+  const title = esc(changeTitle(c));
+  const chip = `<span class="rr-chip rr-chip-${c.state}">${esc(c.label)}</span>`;
+  const subline = `<p class="rr-subline">${esc(c.subline)}</p>`;
+
+  let actions = "";
+  if (c.action && c.action.id === "add-to-next-release") {
+    const accessibleName = c.title ? `${c.action.label}: ${title}` : c.action.label;
+    if (perms.canAddAndPublish) {
+      actions += `<button type="button" class="rr-btn rr-btn-primary" data-rr-add`
+        + ` data-change-id="${esc(c.changeId ?? "")}" data-pr-number="${c.prNumber ?? ""}"`
+        + ` aria-label="${esc(accessibleName)}">${esc(c.action.label)}</button>`;
+    } else {
+      // Read-only: never hide the action — show it disabled with a programmatic reason.
+      actions += `<button type="button" class="rr-btn rr-btn-primary" disabled`
+        + ` aria-describedby="${READONLY_NOTE_ID}"`
+        + ` aria-label="${esc(accessibleName)}">${esc(c.action.label)}</button>`;
+    }
+  }
+  return (
+    `<li class="rr-change" data-rr-change data-state="${c.state}"`
+    + ` data-change-id="${esc(c.changeId ?? "")}" data-pr-number="${c.prNumber ?? ""}">`
+    + `<div class="rr-change-main"><div class="rr-change-head">`
+    + `<span class="rr-change-title">${title}</span>${chip}</div>${subline}</div>`
+    + `<div class="rr-change-actions">${actions}</div>`
+    + `</li>`
+  );
+}
+
+/** The "Changes to review" section. Honest zero-state when the queue is empty. */
+export function renderChangesSection(vm: ReviewReleaseViewModel): string {
+  const items = vm.changes.map((c) => renderChangeCard(c, vm.permissions)).join("");
+  const body = vm.changes.length
+    ? `<ul class="rr-change-list" data-rr-change-list>${items}</ul>`
+    : `<p class="rr-empty" data-rr-changes-empty>${esc(NO_CHANGES_COPY)}</p>`;
+  const readOnlyNote = vm.permissions.readOnly
+    ? `<p class="rr-note" id="${READONLY_NOTE_ID}">${esc(vm.permissions.readOnlyNote ?? "")}</p>`
+    : "";
+  return (
+    `<section class="rr-section rr-changes" aria-labelledby="rr-changes-title">`
+    + `<h2 id="rr-changes-title" class="rr-section-title">Changes to review</h2>`
+    + readOnlyNote
+    + body
+    + `</section>`
+  );
+}
+
+// ── Next release ─────────────────────────────────────────────────────────────────
+
+/** The "What's in this release" plain-title list (Ready to publish) — no sha/digest/counts. */
+function renderContents(next: NextReleaseView): string {
+  if (next.state !== "ready-to-publish") return "";
+  const items = next.contents.items.length
+    ? `<ul class="rr-contents-list">${next.contents.items.map((t) => `<li>${esc(t)}</li>`).join("")}</ul>`
+    : `<p class="rr-note">${esc(next.contents.fallback)}</p>`;
+  return (
+    `<div class="rr-contents">`
+    + `<h3 class="rr-contents-title">${esc(next.contents.heading)}</h3>${items}</div>`
+  );
+}
+
+/**
+ * The next-release action row. `Publish now` appears ONLY in `ready-to-publish` and
+ * ONLY when the model resolved the publish action (owner/admin/ship, entitled,
+ * not a test store). In `ready-to-publish` WITHOUT the action, the button is replaced
+ * — never hidden — by the internal-test-store notice, the paywall upgrade prompt, or
+ * the read-only note, in that precedence. `live` offers only "View your live store".
+ */
+function renderReleaseAction(
+  next: NextReleaseView,
+  perms: MerchantPermissions,
+  liveHref: string,
+): string {
+  if (next.action && next.action.id === "publish-now") {
+    return (
+      `<div class="rr-release-action">`
+      + `<button type="button" class="rr-btn rr-btn-primary rr-publish" data-rr-publish>`
+      + `${esc(next.action.label)}</button></div>`
+    );
+  }
+  if (next.action && next.action.id === "view-live-store") {
+    return (
+      `<div class="rr-release-action">`
+      + `<a class="rr-btn rr-btn-primary" href="${esc(liveHref)}" data-rr-view-live>`
+      + `${esc(next.action.label)}</a></div>`
+    );
+  }
+  // Ready-to-publish but the action was withheld — show WHY (never a bare hidden button).
+  if (next.state === "ready-to-publish") {
+    if (perms.internalTestStore) {
+      return (
+        `<div class="rr-release-action rr-blocked">`
+        + `<p class="rr-note" id="${TESTSTORE_NOTE_ID}" role="note">`
+        + `${esc(perms.internalTestStoreNote ?? "")}</p></div>`
+      );
+    }
+    if (perms.paywall.active) {
+      return (
+        `<div class="rr-release-action rr-paywall" data-rr-paywall>`
+        + `<p class="rr-note" id="${PAYWALL_NOTE_ID}">Publishing to your live store is part of the paid plan. `
+        + `Previewing and reviewing stays free.</p>`
+        + `<a class="rr-btn rr-btn-primary" href="mailto:success@tokenoftrust.com?subject=Upgrade%20store%20publishing"`
+        + ` data-rr-upgrade>Upgrade to publish</a></div>`
+      );
+    }
+    if (perms.readOnly) {
+      return (
+        `<div class="rr-release-action">`
+        + `<button type="button" class="rr-btn rr-btn-primary" disabled aria-describedby="${READONLY_NOTE_ID}">`
+        + `Publish now</button>`
+        + `<p class="rr-note" id="${READONLY_NOTE_ID}">${esc(perms.readOnlyNote ?? "")}</p></div>`
+      );
+    }
+  }
+  return "";
+}
+
+/** The next-release panel: heading + body (the state), the contents list, and the action. */
+export function renderNextRelease(
+  next: NextReleaseView,
+  perms: MerchantPermissions,
+  liveHref: string,
+  publishSucceeded = false,
+): string {
+  const success = publishSucceeded
+    ? `<p class="rr-success" data-rr-publish-success>${esc(PUBLISH_SUCCESS_COPY.message)} `
+      + `<a href="${esc(liveHref)}">${esc(PUBLISH_SUCCESS_COPY.link)}</a></p>`
+    : "";
+  return (
+    `<section class="rr-section rr-release" data-rr-release data-state="${next.state}"`
+    + ` aria-labelledby="rr-release-title">`
+    + `<div class="rr-release-status">`
+    + `<h2 id="rr-release-title" class="rr-section-title">${esc(next.heading)}</h2>`
+    + `<p class="rr-release-body">${esc(next.body)}</p></div>`
+    + renderContents(next)
+    + success
+    + renderReleaseAction(next, perms, liveHref)
+    + `</section>`
+  );
+}
+
+// ── Live (best-effort "what's live now") ─────────────────────────────────────────
+
+/**
+ * The "Live" section — the current live release. Best-effort: the open-queue
+ * `/api/changes` payload carries only the live-version pointer (no published
+ * history yet, contract §9.7), so this shows the live version + date + a link, not a
+ * historical list. Omitted entirely when nothing is live.
+ */
+export function renderLiveSection(live: LiveReleaseView): string {
+  if (!live.versionId) return "";
+  const shortId = esc(live.versionId.slice(0, 12));
+  const when = live.publishedDate ? ` · Published ${esc(live.publishedDate)}` : "";
+  return (
+    `<section class="rr-section rr-live" aria-labelledby="rr-live-title">`
+    + `<h2 id="rr-live-title" class="rr-section-title">Live</h2>`
+    + `<p class="rr-live-body">Your store is serving <code class="rr-mono">${shortId}</code>${when}.</p>`
+    + `<a class="rr-btn rr-btn-ghost" href="${esc(live.liveHref)}">View your live store</a>`
+    + `</section>`
+  );
+}
+
+// ── Whole workspace ──────────────────────────────────────────────────────────────
+
+/** Compose the three sections the controller injects into the workspace container. */
+export function renderWorkspace(vm: ReviewReleaseViewModel, opts: WorkspaceRenderOptions): string {
+  return (
+    renderChangesSection(vm)
+    + renderNextRelease(vm.nextRelease, vm.permissions, opts.liveHref, opts.publishSucceeded)
+    + renderLiveSection(opts.live)
+  );
+}

package/apps/storefront/src/lib/publish/shipWorkspace.ts

@@ -46,6 +46,7 @@
  * digest column (surfaced for a static tenant) differs.
  */
 import { reviewDashboardRevisionHref } from "@/lib/preview/reviewDashboard";
+import { assignVersionNumbers } from "@/lib/publish/versionNumber";
 import {
   candidateEvidenceAuthority,
   classifyCandidateForRender,
@@ -57,8 +58,10 @@ import type { ReviewEnvironment, PromotionEvent } from "@tot/public-runtime";
 // ── Versions / promotion history ───────────────────────────────────────────
 
 /** The plain-language "what shipped in this version" model (same shape the staged
- *  release summary uses — a lead sentence + one highlight per included change). */
+ *  release summary uses — a name + a lead sentence + one highlight per included change). */
 export interface VersionReleaseSummary {
+  /** The human-readable release name (see `deriveReleaseName`), or null. */
+  name: string | null;
   lead: string;
   highlights: { title: string; detail: string }[];
 }
@@ -87,6 +90,12 @@ export interface VersionReleaseInfo {
 export interface WorkspaceVersion {
   /** The tenant Gitea SHA the version serves — the content identity. */
   versionId: string;
+  /**
+   * The merchant-facing monotonic version number ("v42") — derived from first
+   * promotion order (see `versionNumber.ts`), shared with the "Live version"
+   * metric. The human label; the SHA is demoted to a technical disclosure.
+   */
+  number: number | null;
   /** How the version was published (a Gitea commit, or a content hash). */
   source: "commit" | "hash" | null;
   /** ISO time the version was PROMOTED onto `live` (the promotion event). */
@@ -133,7 +142,7 @@ export type RollbackMode = "control-plane" | "pointer";
 /** The versions-panel view model. */
 export interface VersionsView {
   /** The current live version + (static) the digest `live/` actually serves. */
-  current: { versionId: string | null; digest: string | null };
+  current: { versionId: string | null; number: number | null; digest: string | null };
   /** Promotion history, newest first, current marked. */
   versions: WorkspaceVersion[];
   /** Whether the tenant publishes its public site to an external static target. */
@@ -189,12 +198,18 @@ export function buildVersionsView(input: BuildVersionsViewInput): VersionsView {
     staticPublish,
   } = input;
 
+  // The merchant-facing "v42" counter, derived from first-promotion order — the
+  // SAME derivation `resolveLiveVersion` feeds the "Live version" metric, so the
+  // panel and the metric always agree on a version's number.
+  const numbers = assignVersionNumbers(promotions);
+
   const versions: WorkspaceVersion[] = promotions.map((p) => {
     const facts = manifests.get(p.versionId);
     const release = releases?.get(p.versionId);
     const isCurrent = currentVersionId != null && p.versionId === currentVersionId;
     return {
       versionId: p.versionId,
+      number: numbers.get(p.versionId) ?? null,
       source: facts?.source ?? null,
       promotedAt: p.at,
       createdAt: facts?.createdAt ?? null,
@@ -210,7 +225,11 @@ export function buildVersionsView(input: BuildVersionsViewInput): VersionsView {
   });
 
   return {
-    current: { versionId: currentVersionId, digest: staticPublish ? currentDigest : null },
+    current: {
+      versionId: currentVersionId,
+      number: currentVersionId != null ? numbers.get(currentVersionId) ?? null : null,
+      digest: staticPublish ? currentDigest : null,
+    },
     versions,
     staticPublish,
     rollbackMode: staticPublish ? "pointer" : "control-plane",