@hienlh/ppm 0.22.10 → 0.23.0

package/src/web/components/design/canvas/design-issues-badge.tsx

@@ -0,0 +1,71 @@
+import { useState } from "react";
+import { AlertTriangle, X } from "@/lib/icons";
+import { cn } from "@/lib/utils";
+
+/**
+ * What went wrong in the design document on screen: script errors, failed loads, CSP
+ * blocks, links the canvas refused to follow, and layout problems the self-check found
+ * after the last turn. Everything here was reported by the page, so it is untrusted and
+ * rendered as plain text only.
+ */
+
+export type CanvasIssue =
+  | { kind: "error" | "rejection" | "resource" | "csp"; message: string; source?: string; line?: number }
+  | { kind: "navigate-blocked"; message: string; source: string }
+  /** Found by the canvas self-check after a turn; `source` names the element. */
+  | { kind: "layout"; message: string; source?: string };
+
+const KIND_LABEL: Record<CanvasIssue["kind"], string> = {
+  error: "Error",
+  rejection: "Unhandled rejection",
+  resource: "Failed to load",
+  csp: "Blocked by policy",
+  "navigate-blocked": "Link blocked",
+  layout: "Layout",
+};
+
+/** Kept per document load; the bridge itself stops at 20, and so does this list. */
+export const MAX_CANVAS_ISSUES = 20;
+
+export function DesignIssuesBadge({ issues, className }: { issues: CanvasIssue[]; className?: string }) {
+  const [open, setOpen] = useState(false);
+  if (issues.length === 0) return null;
+  return (
+    <div className={cn("pointer-events-auto", className)}>
+      <button
+        type="button"
+        onClick={() => setOpen((v) => !v)}
+        aria-expanded={open}
+        aria-label={`${issues.length} canvas ${issues.length === 1 ? "issue" : "issues"}`}
+        className="flex min-h-11 items-center gap-1.5 rounded-full border border-warning/40 bg-panel px-3 text-xs font-medium text-warning shadow-md md:min-h-8"
+      >
+        <AlertTriangle className="size-4" />
+        {issues.length}
+      </button>
+      {open && (
+        <div className="absolute right-0 top-full z-10 mt-1 w-[min(22rem,calc(100vw-2rem))] rounded-lg border border-border bg-popover text-popover-foreground shadow-lg">
+          <div className="flex items-center justify-between border-b border-border px-3 py-1.5">
+            <span className="text-xs font-semibold">Canvas issues</span>
+            <button type="button" onClick={() => setOpen(false)} aria-label="Close"
+              className="flex size-11 items-center justify-center rounded-md text-text-subtle hover:bg-surface-elevated md:size-7">
+              <X className="size-4" />
+            </button>
+          </div>
+          <ul className="max-h-72 overflow-y-auto p-2 text-xs">
+            {issues.map((issue, i) => (
+              <li key={i} className="border-b border-border/50 py-1.5 last:border-0">
+                <span className="font-medium text-warning">{KIND_LABEL[issue.kind]}</span>{" "}
+                <span className="break-words">{issue.message}</span>
+                {issue.source && (
+                  <span className="block truncate text-text-subtle" title={issue.source}>
+                    {issue.source}{"line" in issue && issue.line ? `:${issue.line}` : ""}
+                  </span>
+                )}
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/web/components/design/canvas/device-frame-presets.ts

@@ -0,0 +1,37 @@
+import type { DesignKind } from "../../../../shared/design-types";
+
+/**
+ * The sizes a design can be previewed at. `desktop` is the canvas itself (whatever room
+ * the pane has); every other frame is a fixed CSS size that is scaled down to fit, so a
+ * phone layout is laid out at 390px even on a narrow pane.
+ */
+export const DEVICE_FRAME_IDS = ["desktop", "tablet", "phone", "slide"] as const;
+export type DeviceFrameId = (typeof DEVICE_FRAME_IDS)[number];
+
+export interface DeviceFramePreset {
+  id: DeviceFrameId;
+  label: string;
+  /** CSS pixels, or null for "fill the pane". */
+  size: { width: number; height: number } | null;
+}
+
+export const DEVICE_FRAMES: readonly DeviceFramePreset[] = [
+  { id: "desktop", label: "Desktop", size: null },
+  { id: "tablet", label: "Tablet", size: { width: 820, height: 1180 } },
+  { id: "phone", label: "Phone", size: { width: 390, height: 844 } },
+  // The deck format the design instructions ask for, so a slide fills its frame exactly.
+  { id: "slide", label: "Slide", size: { width: 1280, height: 720 } },
+];
+
+export function isDeviceFrameId(value: unknown): value is DeviceFrameId {
+  return typeof value === "string" && (DEVICE_FRAME_IDS as readonly string[]).includes(value);
+}
+
+export function framePreset(id: DeviceFrameId): DeviceFramePreset {
+  return DEVICE_FRAMES.find((f) => f.id === id) ?? DEVICE_FRAMES[0]!;
+}
+
+/** A deck opens on its slide frame; everything else on the plain canvas. */
+export function defaultFrameFor(kind: DesignKind | undefined): DeviceFrameId {
+  return kind === "slides" ? "slide" : "desktop";
+}

package/src/web/components/design/canvas/use-design-bridge.ts

@@ -0,0 +1,169 @@
+import { useCallback, useEffect, useMemo, useRef, useState, type RefObject } from "react";
+import {
+  parentEnvelope, parseChildMessage, parseParentMessage,
+  type ChildMessage, type ChildMessageType, type ParentMessage,
+} from "../../../../shared/design-bridge-protocol";
+
+/**
+ * The parent side of the design bridge: which frame messages are believed, how to talk
+ * back, and what to redo every time the frame starts over.
+ *
+ * A message from the frame is accepted only when it comes from the iframe's current
+ * `contentWindow` AND carries the nonce minted for the current load. The source check alone
+ * is not enough: a frame that navigated itself to a foreign page is still the same
+ * `contentWindow`, but that page never saw the nonce — parent → frame messages never carry
+ * one (see `design-bridge-protocol.ts`), and none goes out at all while the frame looks dead
+ * (loaded but not yet proven itself with `ready`), which is the only window such a page could
+ * otherwise use to snoop one off the wire and echo it back to forge its own `ready`. A stale
+ * nonce (a message from the document before a reload) is dropped the same way.
+ *
+ * Every `ready` is a brand-new document — a live reload, a token rotation, or the tab pool
+ * moving the tab to another panel (which reloads any iframe it reparents). Features register
+ * a replay callback to restore their state (scroll, modes, pins) on each one.
+ */
+
+export type ReadyMessage = Extract<ChildMessage, { type: "ready" }>;
+type Handler<T extends ChildMessageType> = (message: Extract<ChildMessage, { type: T }>) => void;
+export type BridgeSend = (message: ParentMessage) => boolean;
+
+export interface BridgeExpectation {
+  contentWindow: unknown;
+  nonce: string | null;
+}
+
+/** The accept rule, pure so it can be tested without a frame: source, shape, then nonce. */
+export function acceptBridgeEvent(event: { source: unknown; data: unknown }, expected: BridgeExpectation): ChildMessage | null {
+  if (!expected.contentWindow || event.source !== expected.contentWindow) return null;
+  const message = parseChildMessage(event.data);
+  if (!message) return null;
+  if (!expected.nonce || message.nonce !== expected.nonce) return null;
+  return message;
+}
+
+/** 16 random bytes as base64url: 22 characters, inside the protocol's nonce shape. */
+export function newBridgeNonce(): string {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/** How long a document may take to say `ready` after its `load` before the canvas is dead. */
+export const BRIDGE_LIVENESS_MS = 3000;
+
+/**
+ * Whether the frame is showing a document that never said `ready`.
+ *
+ * Counted rather than flagged, because the two events race: `ready` is posted at
+ * DOMContentLoaded and usually lands *before* the iframe's `load`, but a slow parent can see
+ * them the other way round. Every genuine document produces one of each; a page the frame
+ * navigated to on its own (or an error page) produces a `load` and nothing else.
+ */
+export function frameLooksDead(loads: number, readies: number): boolean {
+  return loads > readies;
+}
+
+export interface DesignBridge {
+  send: BridgeSend;
+  on<T extends ChildMessageType>(type: T, handler: Handler<T>): () => void;
+  /** Runs on every `ready`, after the frame reports it; returns the unregister function. */
+  onReplay(replay: (send: BridgeSend, ready: ReadyMessage) => void): () => void;
+  /** The last `ready` of the current load, or null while the frame is (re)loading. */
+  ready: ReadyMessage | null;
+  /** Call from the iframe's `load` event: starts the liveness clock for this document. */
+  frameLoaded(): void;
+}
+
+export function useDesignBridge(
+  iframeRef: RefObject<HTMLIFrameElement | null>,
+  nonce: string | null,
+  onDead: () => void,
+): DesignBridge {
+  const [ready, setReady] = useState<ReadyMessage | null>(null);
+  const nonceRef = useRef(nonce);
+  const handlers = useRef(new Map<string, Set<(m: ChildMessage) => void>>());
+  const replays = useRef(new Set<(send: BridgeSend, ready: ReadyMessage) => void>());
+  const livenessTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const counts = useRef({ loads: 0, readies: 0 });
+  const onDeadRef = useRef(onDead);
+  onDeadRef.current = onDead;
+
+  const clearLiveness = useCallback(() => {
+    if (livenessTimer.current) clearTimeout(livenessTimer.current);
+    livenessTimer.current = null;
+  }, []);
+
+  // A new nonce means a new load is on its way: nothing from the old document counts now.
+  // Its liveness clock goes too, or it would judge the new document by the old one's load.
+  useEffect(() => {
+    nonceRef.current = nonce;
+    counts.current = { loads: 0, readies: 0 };
+    clearLiveness();
+    setReady(null);
+  }, [nonce, clearLiveness]);
+
+  const send = useCallback<BridgeSend>((message) => {
+    const win = iframeRef.current?.contentWindow;
+    if (!win || !nonceRef.current) return false;
+    // A load that fired `load` without a `ready` yet might already be showing a page the
+    // frame navigated itself to. Nothing goes out until the real document proves itself, or
+    // there would be a window where a parent message reaches that foreign page instead.
+    if (frameLooksDead(counts.current.loads, counts.current.readies)) return false;
+    const envelope = parentEnvelope(message);
+    // Validated before it leaves, so a feature cannot post a shape the bridge would reject.
+    if (!parseParentMessage(envelope)) return false;
+    // "*": the frame's origin is opaque, and nothing sensitive ever goes this way.
+    win.postMessage(envelope, "*");
+    return true;
+  }, [iframeRef]);
+
+  useEffect(() => {
+    const onMessage = (event: MessageEvent) => {
+      const message = acceptBridgeEvent(event, {
+        contentWindow: iframeRef.current?.contentWindow ?? null, nonce: nonceRef.current,
+      });
+      if (!message) return;
+      if (message.type === "ready") {
+        counts.current.readies++;
+        if (!frameLooksDead(counts.current.loads, counts.current.readies)) clearLiveness();
+        setReady(message);
+        for (const replay of replays.current) {
+          try { replay(send, message); } catch (e) { console.warn("[design] replay failed:", e); }
+        }
+      }
+      for (const handler of handlers.current.get(message.type) ?? []) {
+        try { handler(message); } catch (e) { console.warn(`[design] ${message.type} handler failed:`, e); }
+      }
+    };
+    window.addEventListener("message", onMessage);
+    return () => window.removeEventListener("message", onMessage);
+  }, [iframeRef, send, clearLiveness]);
+
+  useEffect(() => clearLiveness, [clearLiveness]);
+
+  const frameLoaded = useCallback(() => {
+    counts.current.loads++;
+    if (!frameLooksDead(counts.current.loads, counts.current.readies)) return;
+    clearLiveness();
+    livenessTimer.current = setTimeout(() => {
+      livenessTimer.current = null;
+      if (frameLooksDead(counts.current.loads, counts.current.readies)) onDeadRef.current();
+    }, BRIDGE_LIVENESS_MS);
+  }, [clearLiveness]);
+
+  const on = useCallback(<T extends ChildMessageType>(type: T, handler: Handler<T>) => {
+    const set = handlers.current.get(type) ?? new Set();
+    const wrapped = handler as (m: ChildMessage) => void;
+    set.add(wrapped);
+    handlers.current.set(type, set);
+    return () => { set.delete(wrapped); };
+  }, []);
+
+  const onReplay = useCallback((replay: (send: BridgeSend, ready: ReadyMessage) => void) => {
+    replays.current.add(replay);
+    return () => { replays.current.delete(replay); };
+  }, []);
+
+  return useMemo(() => ({ send, on, onReplay, ready, frameLoaded }), [send, on, onReplay, ready, frameLoaded]);
+}

package/src/web/components/design/canvas/use-design-canvas-check.ts

@@ -0,0 +1,110 @@
+import { useEffect, useRef } from "react";
+import { api, projectUrl } from "@/lib/api-client";
+import {
+  CHECK_REQUEST_ID_RE, withRuntimeIssues, type CanvasCheckReport, type LayoutCheckReport,
+} from "../../../../shared/design-canvas-check";
+import { newBridgeNonce, type DesignBridge, type ReadyMessage } from "./use-design-bridge";
+import type { CanvasIssue } from "./design-issues-badge";
+
+/**
+ * Running the canvas self-check from the parent, and answering the server when an agent's
+ * `design_check` tool asks for one.
+ *
+ * The frame measures itself (`check-run` → `check-result`); the parent adds what only it
+ * knows — the runtime issues it collected for this load and the device frame on screen. The
+ * screenshot library is fetched only when a screenshot is wanted, as its own lazy chunk,
+ * and handed to the frame as source because the frame can load nothing from PPM's origin.
+ */
+
+const CHECK_TIMEOUT_MS = 15_000;
+/** How long a canvas that is (re)loading gets to say `ready` before a request gives up. */
+const READY_WAIT_MS = 8_000;
+
+let libSource: Promise<string> | null = null;
+function screenshotLib(): Promise<string> {
+  libSource ??= import("modern-screenshot/dist/index.js?raw").then((m) => m.default).catch((e: unknown) => {
+    libSource = null;
+    throw e;
+  });
+  return libSource;
+}
+
+export interface CanvasCheckContext {
+  issues: readonly CanvasIssue[];
+  /** The device frame's label, e.g. "Desktop". */
+  frame: string;
+}
+
+/**
+ * The frame's current `ready`, or its next one if it is (re)loading; null if none comes in
+ * time. `bridge` may be a render old, so a load that completes meanwhile is taken from the
+ * event rather than from `bridge.ready`.
+ */
+function whenReady(bridge: DesignBridge): Promise<ReadyMessage | null> {
+  if (bridge.ready) return Promise.resolve(bridge.ready);
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => { off(); resolve(null); }, READY_WAIT_MS);
+    const off = bridge.on("ready", (m) => { clearTimeout(timer); off(); resolve(m); });
+  });
+}
+
+export async function runCanvasCheck(
+  bridge: DesignBridge,
+  ctx: CanvasCheckContext,
+  opts: { screenshot: boolean },
+): Promise<CanvasCheckReport> {
+  const lib = opts.screenshot ? await screenshotLib().catch(() => undefined) : undefined;
+  const ready = await whenReady(bridge);
+  if (!ready) throw new Error("The canvas is still loading");
+  const report = await new Promise<LayoutCheckReport>((resolve, reject) => {
+    const requestId = newBridgeNonce();
+    const cleanup = (): void => { offResult(); offError(); clearTimeout(timer); };
+    const offResult = bridge.on("check-result", (m) => { if (m.requestId === requestId) { cleanup(); resolve(m.report); } });
+    const offError = bridge.on("check-error", (m) => { if (m.requestId === requestId) { cleanup(); reject(new Error(m.message)); } });
+    const timer = setTimeout(() => { cleanup(); reject(new Error("The canvas did not answer in time")); }, CHECK_TIMEOUT_MS);
+    if (!bridge.send({ type: "check-run", requestId, screenshot: opts.screenshot, ...(lib ? { lib } : {}) })) {
+      cleanup();
+      reject(new Error("The canvas is not accepting messages"));
+    }
+  });
+  const runtime = ctx.issues.filter((i) => i.kind !== "navigate-blocked" && i.kind !== "layout");
+  const withIssues = withRuntimeIssues(report, runtime);
+  const note = opts.screenshot && !lib ? "The screenshot library could not be loaded." : withIssues.screenshotNote;
+  return { ...withIssues, ...(note ? { screenshotNote: note } : {}), file: ready.file, gen: ready.gen, frame: ctx.frame };
+}
+
+/**
+ * Answers `design:check_request` for this design: the server asks every browser showing it,
+ * and the first report posted back settles the agent's tool call. A tab that cannot check
+ * (still loading, frame dead) stays silent rather than answer with an error, so another
+ * device that can still wins.
+ */
+export function useDesignCanvasCheckResponder(opts: {
+  projectName: string;
+  slug: string;
+  bridge: DesignBridge;
+  context: () => CanvasCheckContext;
+}): void {
+  const ref = useRef(opts);
+  ref.current = opts;
+  const { projectName, slug } = opts;
+
+  useEffect(() => {
+    const onRequest = (e: Event) => {
+      const d = (e as CustomEvent<{ projectName?: unknown; slug?: unknown; requestId?: unknown; screenshot?: unknown }>).detail;
+      if (!d || d.projectName !== projectName || d.slug !== slug) return;
+      if (typeof d.requestId !== "string" || !CHECK_REQUEST_ID_RE.test(d.requestId)) return;
+      const requestId = d.requestId;
+      const { bridge, context } = ref.current;
+      runCanvasCheck(bridge, context(), { screenshot: d.screenshot === true })
+        .then((report) => api.post(`${projectUrl(projectName)}/designs/${encodeURIComponent(slug)}/check/${requestId}`, report))
+        .catch((err: unknown) => {
+          // A 404 means another client answered first; anything else is worth a line.
+          const message = (err as Error)?.message ?? String(err);
+          if (!/pending check/i.test(message)) console.warn(`[design] canvas check for ${slug} not sent: ${message}`);
+        });
+    };
+    window.addEventListener("design:check_request", onRequest);
+    return () => window.removeEventListener("design:check_request", onRequest);
+  }, [projectName, slug]);
+}

package/src/web/components/design/canvas/use-design-canvas.ts

@@ -0,0 +1,107 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useDesignPreviewUrl } from "./use-design-preview-url";
+import { newBridgeNonce, useDesignBridge } from "./use-design-bridge";
+import { useDesignLiveReload } from "./use-design-live-reload";
+import { MAX_CANVAS_ISSUES, type CanvasIssue } from "./design-issues-badge";
+import type { DesignTabContextValue } from "../design-tab-context";
+
+/**
+ * Everything that keeps the canvas iframe showing the right document.
+ *
+ * Each load gets a fresh nonce on its URL (`?n=`), and reloading means setting a new `src` —
+ * the frame's origin is opaque, so `location.reload()` is not available to the parent. The
+ * frame is recovered at most once per healthy document: an `expired` message or a load that
+ * never says `ready` re-mints the token and reloads; if that fails too the canvas says so
+ * instead of reloading forever.
+ *
+ * `expired` is only trusted before this load's `ready` arrives: the real expired stand-in
+ * (`expired-page.ts`) never sends one, but the actual design document could — its own script
+ * can read `?n=` off its URL — so a document that already proved itself must not be able to
+ * keep claiming its token died and loop the canvas through remints, each of which evicts
+ * another open canvas's token from the shared store.
+ */
+
+/** Whether an `expired` message for the current load should trigger a remint-and-reload. */
+export function acceptsExpired(readyForCurrentLoad: boolean): boolean {
+  return !readyForCurrentLoad;
+}
+
+export function useDesignCanvas(ctx: DesignTabContextValue) {
+  const { projectName, slug, design, isActive, refreshDesign } = ctx;
+  const iframeRef = useRef<HTMLIFrameElement | null>(null);
+  const preview = useDesignPreviewUrl(projectName, slug);
+  const [load, setLoad] = useState<{ url: string; nonce: string } | null>(null);
+  const [dead, setDead] = useState(false);
+  const [issues, setIssues] = useState<CanvasIssue[]>([]);
+  const recovering = useRef(false);
+  const lastScroll = useRef<{ x: number; y: number } | null>(null);
+
+  const reload = useCallback(async (opts?: { remint?: boolean }) => {
+    const url = opts?.remint ? await preview.remint() : preview.latestUrl();
+    if (!url) { setDead(true); return; }
+    setIssues([]);
+    setLoad({ url, nonce: newBridgeNonce() });
+  }, [preview]);
+
+  const recover = useCallback(() => {
+    if (recovering.current) { setDead(true); return; }
+    recovering.current = true;
+    void reload({ remint: true });
+  }, [reload]);
+
+  const bridge = useDesignBridge(iframeRef, load?.nonce ?? null, recover);
+  // Read inside the "expired" handler below instead of `bridge.ready` directly: that handler
+  // is registered in an effect that does not re-run on every render, so it would otherwise
+  // see whichever load was current the last time the effect ran.
+  const readyForLoad = useRef(false);
+  readyForLoad.current = bridge.ready !== null;
+
+  // First URL: load it.
+  useEffect(() => {
+    if (preview.initialUrl) setLoad({ url: preview.initialUrl, nonce: newBridgeNonce() });
+  }, [preview.initialUrl]);
+
+  // A manifest that names another entry page needs a URL for that page.
+  const entry = useRef(design.entry);
+  useEffect(() => {
+    if (entry.current === design.entry) return;
+    entry.current = design.entry;
+    void reload({ remint: true });
+  }, [design.entry, reload]);
+
+  useEffect(() => {
+    const offs = [
+      bridge.on("ready", () => { recovering.current = false; setDead(false); }),
+      bridge.on("expired", () => { if (acceptsExpired(readyForLoad.current)) recover(); }),
+      bridge.on("scroll", (m) => { lastScroll.current = { x: m.x, y: m.y }; }),
+      bridge.on("issue", (m) => setIssues((list) => list.length >= MAX_CANVAS_ISSUES ? list
+        : [...list, { kind: m.kind, message: m.message, source: m.source, line: m.line }])),
+      bridge.on("navigate-blocked", (m) => setIssues((list) => list.length >= MAX_CANVAS_ISSUES ? list
+        : [...list, { kind: "navigate-blocked", message: "The canvas does not follow links out of the design.", source: m.href }])),
+      // Every new document starts at the top; put the reader back where they were.
+      bridge.onReplay((send) => {
+        const at = lastScroll.current;
+        if (at && (at.x || at.y)) send({ type: "restore-scroll", x: at.x, y: at.y });
+      }),
+    ];
+    return () => { for (const off of offs) off(); };
+  }, [bridge.on, bridge.onReplay, recover]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const readyGen = useRef<string | null>(null);
+  readyGen.current = bridge.ready?.gen ?? null;
+  useDesignLiveReload({
+    projectName, slug, isActive,
+    reload: (opts) => { void reload(opts); },
+    onManifestChanged: refreshDesign,
+    currentUrl: () => load?.url ?? null,
+    readyGen: () => readyGen.current,
+  });
+
+  const src = load ? `${load.url}?n=${encodeURIComponent(load.nonce)}` : null;
+  return {
+    iframeRef, src, bridge, issues, dead, error: preview.error,
+    reload: () => { recovering.current = false; setDead(false); void reload(); },
+  };
+}
+
+export type DesignCanvasState = ReturnType<typeof useDesignCanvas>;

package/src/web/components/design/canvas/use-design-live-reload.ts

@@ -0,0 +1,86 @@
+import { useEffect, useRef } from "react";
+import { classifyDesignChange } from "@/lib/design/design-change-filter";
+
+/**
+ * Keep the canvas in step with the design's files.
+ *
+ * While the design's project is the active one, the file watcher reports every change and
+ * a burst of them (an agent writing three files) becomes one reload 300 ms after the last.
+ * The watcher follows the active project only, though, so a canvas that was hidden — another
+ * project, another tab, a backgrounded browser — asks the server when it comes back: a HEAD
+ * on its preview URL answers with the page's current `X-PPM-Gen`, and a gen other than the
+ * one the frame last reported means it is showing an old version.
+ */
+
+export const LIVE_RELOAD_DEBOUNCE_MS = 300;
+
+export interface LiveReloadOptions {
+  projectName: string;
+  slug: string;
+  /** True while the design tab is the visible tab of its panel. */
+  isActive: boolean;
+  reload: (opts?: { remint?: boolean }) => void;
+  onManifestChanged: () => void;
+  /** The URL the frame is showing now (for the gen check), or null while none is loaded. */
+  currentUrl: () => string | null;
+  /** The gen the frame last reported in `ready`, or null while none has. */
+  readyGen: () => string | null;
+}
+
+export function useDesignLiveReload(opts: LiveReloadOptions): void {
+  const optsRef = useRef(opts);
+  optsRef.current = opts;
+  const { projectName, slug, isActive } = opts;
+
+  useEffect(() => {
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    const onChange = (e: Event) => {
+      const detail = (e as CustomEvent<{ projectName?: string; path?: string }>).detail;
+      if (!detail || detail.projectName !== projectName || typeof detail.path !== "string") return;
+      const change = classifyDesignChange(detail.path, slug);
+      if (change === "manifest") optsRef.current.onManifestChanged();
+      if (change !== "reload") return;
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(() => {
+        timer = null;
+        optsRef.current.reload();
+      }, LIVE_RELOAD_DEBOUNCE_MS);
+    };
+    window.addEventListener("file:changed", onChange);
+    return () => {
+      window.removeEventListener("file:changed", onChange);
+      if (timer) clearTimeout(timer);
+    };
+  }, [projectName, slug]);
+
+  const wasActive = useRef(isActive);
+  useEffect(() => {
+    let cancelled = false;
+    const check = async () => {
+      const { currentUrl, readyGen, reload } = optsRef.current;
+      const url = currentUrl();
+      const gen = readyGen();
+      if (!url || !gen) return;
+      try {
+        const res = await fetch(url, { method: "HEAD", cache: "no-store", referrerPolicy: "no-referrer" });
+        if (cancelled) return;
+        if (res.status === 404) { reload({ remint: true }); return; }
+        const current = res.headers.get("X-PPM-Gen");
+        if (res.ok && current && current !== gen) reload();
+      } catch (e) {
+        // Offline or a server restart in progress: the frame's own liveness check covers it.
+        console.warn(`[design] gen check for ${slug} failed: ${(e as Error).message}`);
+      }
+    };
+    if (isActive && !wasActive.current) void check();
+    wasActive.current = isActive;
+    const onVisibility = () => {
+      if (document.visibilityState === "visible" && optsRef.current.isActive) void check();
+    };
+    document.addEventListener("visibilitychange", onVisibility);
+    return () => {
+      cancelled = true;
+      document.removeEventListener("visibilitychange", onVisibility);
+    };
+  }, [isActive, slug]);
+}

package/src/web/components/design/canvas/use-design-preview-url.ts

@@ -0,0 +1,74 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { requestCanvasPreview } from "@/lib/design/api-designs";
+
+/**
+ * The canvas's capability URL for one design.
+ *
+ * Minted once when the canvas mounts, then refreshed through the authenticated API every
+ * 10 minutes while it stays mounted — the iframe's own requests never extend a token. A
+ * refresh may rotate the token; the successor is kept for the *next* load and the document
+ * on screen is never reloaded for it (its old token stays valid until its own expiry).
+ *
+ * `remint` gets a fresh token outright: the recovery path when the frame reports its token
+ * expired, or stopped answering.
+ */
+
+export const PREVIEW_REFRESH_MS = 10 * 60 * 1000;
+
+export interface DesignPreviewUrl {
+  /** The URL the next load should use (the newest token), or null before the first mint. */
+  latestUrl: () => string | null;
+  /** Set once the first mint finished; a change asks the canvas to load it. */
+  initialUrl: string | null;
+  error: string | null;
+  remint: () => Promise<string | null>;
+}
+
+export function useDesignPreviewUrl(projectName: string, slug: string): DesignPreviewUrl {
+  const [initialUrl, setInitialUrl] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const latest = useRef<{ url: string; token: string } | null>(null);
+  const alive = useRef(true);
+
+  const remint = useCallback(async (): Promise<string | null> => {
+    try {
+      const cap = await requestCanvasPreview(projectName, slug);
+      if (!alive.current) return null;
+      latest.current = { url: cap.url, token: cap.token };
+      setError(null);
+      return cap.url;
+    } catch (e) {
+      if (alive.current) setError((e as Error).message || "Could not open the preview");
+      return null;
+    }
+  }, [projectName, slug]);
+
+  useEffect(() => {
+    alive.current = true;
+    latest.current = null;
+    setInitialUrl(null);
+    void remint().then((url) => { if (url) setInitialUrl(url); });
+    return () => { alive.current = false; };
+  }, [remint]);
+
+  useEffect(() => {
+    const timer = setInterval(() => {
+      const current = latest.current;
+      if (!current) return;
+      requestCanvasPreview(projectName, slug, current.token)
+        .then((cap) => {
+          // Only the token for the next load changes; the frame on screen keeps its own.
+          if (alive.current && cap.rotated) latest.current = { url: cap.url, token: cap.token };
+        })
+        .catch((e) => {
+          // An expired token cannot be refreshed; the frame posts `expired` on its next
+          // load and the canvas re-mints then. Anything else is worth a line in the console.
+          console.warn(`[design] preview refresh for ${slug} failed: ${(e as Error).message}`);
+        });
+    }, PREVIEW_REFRESH_MS);
+    return () => clearInterval(timer);
+  }, [projectName, slug]);
+
+  const latestUrl = useCallback(() => latest.current?.url ?? null, []);
+  return useMemo(() => ({ latestUrl, initialUrl, error, remint }), [latestUrl, initialUrl, error, remint]);
+}