@hienlh/ppm 0.23.10 → 0.23.11

package/src/types/system-services.ts

@@ -1,9 +1,14 @@
-/** Service-manager contract shared by the systemd collector, the routes and the web
- *  client — Mission Center's Services page. Types + constants only, no imports, so
- *  both bundles can take it. Import RELATIVELY — the "@" alias points at src/web. */
+/** Service-manager contract shared by the systemd and launchd collectors, the routes
+ *  and the web client — Mission Center's Services page. Types + constants only, no
+ *  imports, so both bundles can take it. Import RELATIVELY — the "@" alias points at
+ *  src/web. */
 
 export type ServiceScope = "system" | "user";
 
+/** systemd on Linux, launchd on macOS. It decides what the page calls a row (a unit or
+ *  a job) and how a few fields read; every field below says what it holds under each. */
+export type ServiceManager = "systemd" | "launchd";
+
 /** Start/Stop/Restart are Mission Center's menu; Enable/Disable its details switch. */
 export type ServiceAction = "start" | "stop" | "restart" | "enable" | "disable";
 
@@ -12,20 +17,30 @@ export const SERVICE_ACTIONS: readonly ServiceAction[] = ["start", "stop", "rest
 /** One unit. Mission Center lists `.service`, `.socket` and `.mount` units and drops
  *  the ones systemd reports as `not-found`; masked units stay in the list. */
 export interface ServiceInfo {
-  /** Full unit name, suffix included: "sshd.service", "docker.socket", "home.mount". */
+  /** Full unit name, suffix included: "sshd.service", "docker.socket", "home.mount".
+   *  Under launchd, the job's label: "com.apple.Finder", "homebrew.mxcl.postgresql@16". */
   unit: string;
   scope: ServiceScope;
   description: string;
-  /** systemd ActiveState verbatim: "active", "inactive", "failed", "activating", … */
+  /** systemd ActiveState verbatim: "active", "inactive", "failed", "activating", …
+   *  Under launchd, "running" or "not running": launchd has no failed state. */
   activeState: string;
-  /** systemd SubState verbatim: "running", "exited", "dead", "listening", … */
+  /** systemd SubState verbatim: "running", "exited", "dead", "listening", …
+   *  Under launchd, how the last run ended ("exit code 1", "killed by SIGKILL", "idle
+   *  exit"), or "" while the job is running. */
   subState: string;
   /** Unit-file state verbatim ("enabled", "disabled", "static", "masked", "indirect", …);
-   *  null for a unit with no unit file (transient, generated without one). */
+   *  null for a unit with no unit file (transient, generated without one). Under launchd,
+   *  the override launchd holds for the label ("enabled" or "disabled"), null for the
+   *  many jobs that have none. */
   unitFileState: string | null;
   /** Mission Center's three booleans, derived exactly as it does: ActiveState "active",
    *  ActiveState "failed", and unit-file state exactly "enabled" (static/indirect/alias
-   *  count as not enabled). `activating`/`reloading` are neither running nor failed. */
+   *  count as not enabled). `activating`/`reloading` are neither running nor failed.
+   *
+   *  Under launchd: the job has a process; it has none and its last run ended in an
+   *  error (an exit code, a crash signal, a jetsam kill); and it is not disabled —
+   *  every job is enabled until something disables it. */
   running: boolean;
   failed: boolean;
   enabled: boolean;
@@ -38,36 +53,68 @@ export interface ServiceInfo {
 }
 
 export interface ServicesSnapshot {
-  /** False when the host has no supported service manager (no systemd). The UI hides
-   *  the Services page, as Mission Center does when both lists stay empty. */
+  /** False when the host has no service manager PPM can read (the one it asked did not
+   *  answer). The UI hides the Services page, as Mission Center does when both lists
+   *  stay empty. */
   supported: boolean;
+  /** The manager PPM asked: launchd on macOS, systemd everywhere else. */
+  manager: ServiceManager;
   services: ServiceInfo[];
   /** Non-fatal failures, human readable (e.g. the user manager is unreachable). */
   warnings: string[];
 }
 
 export interface ServiceLogLine {
-  /** Epoch ms UTC. */
-  ts: number;
+  /** Epoch ms UTC; null for a line read from a job's own log file, which has none. */
+  ts: number | null;
   message: string;
 }
 
+/** Where a launchd job's log lines came from. systemd's are always this boot's journal. */
+export type ServiceLogSource =
+  /** The tail of the files the job sends its stdout and stderr to. */
+  | { kind: "files"; paths: string[] }
+  /** The unified log, for a job that declares no readable file: everything since the
+   *  running process started, or since boot for a job that is not running. */
+  | { kind: "unified"; since: "start" | "boot" }
+  /** The same cut to a recent window, because the whole of it could not be read in time. */
+  | { kind: "unified"; minutes: number };
+
 export interface ServiceDetails extends ServiceInfo {
-  /** Configured `User=` / `Group=`; null when unset (runs as the manager's user). */
+  /** Configured `User=` / `Group=`; null when unset (runs as the manager's user). Under
+   *  launchd, the user the job runs as and its `group`, when launchd reports one. */
   user: string | null;
   group: string | null;
-  /** Unit file location (`FragmentPath`), null when unknown. */
+  /** Unit file location (`FragmentPath`), null when unknown. Under launchd, the job's
+   *  property list, or launchd's note for a job submitted without one
+   *  ("(submitted by smd.95)"). */
   fragmentPath: string | null;
-  /** This boot's journal for the unit, oldest first, bounded. */
+  /** The unit's log, oldest first, bounded: this boot's journal under systemd, and
+   *  under launchd whatever `logSource` says. */
   logs: ServiceLogLine[];
+  /** launchd only, from here down. */
+  logSource?: ServiceLogSource;
+  /** The executable launchd runs, and the argument vector it passes (argv[0] first). */
+  program?: string | null;
+  arguments?: string[];
+  stdoutPath?: string | null;
+  stderrPath?: string | null;
+  /** How the last run ended, in words: "exit code 1", "Killed: 9", "never exited". */
+  lastExit?: string | null;
+  /** launchd starts the job again whenever it stops, which is why Stop does not last. */
+  keepAlive?: boolean;
 }
 
 export interface ServiceActionResult {
   unit: string;
   scope: ServiceScope;
   action: ServiceAction;
+  /** What the user should know about how it landed: a job launchd keeps alive has
+   *  already started again by the time a stop returns. */
+  note?: string;
 }
 
 /** Client poll cadence while the Services page is visible. The list costs a handful of
- *  `systemctl` spawns, so it is fetched on demand rather than riding the metrics tick. */
+ *  `systemctl` / `launchctl` spawns, so it is fetched on demand rather than riding the
+ *  metrics tick. */
 export const SERVICES_POLL_INTERVAL_MS = 3000;

package/src/web/components/chat/chat-tab.tsx

@@ -493,6 +493,26 @@ function ChatTabContent({ metadata, tabId, onNewSession, onFork, historyFilter }
 
   // Pending fork message — show in input for user to edit, not auto-send
   const [forkDraft, setForkDraft] = useState<string | undefined>(metadata?.pendingMessage as string | undefined);
+
+  // "Build in new chat" hands a design screenshot over as a data URL on the tab's own
+  // metadata (never a live event: there is no mounted composer yet for a brand new tab). It
+  // is fed through `externalFiles`, the same drop path a screenshot dragged in by hand would
+  // take, so the upload, thumbnail and inline-image handling are exactly the drop code path's
+  // rather than a second copy of it. Cleared right away: attaching it needs no session.
+  useEffect(() => {
+    const dataUrl = metadata?.pendingAttachmentDataUrl as string | undefined;
+    if (!dataUrl || !tabId) return;
+    patchTabMetadata(tabId, { pendingAttachmentDataUrl: undefined, pendingAttachmentName: undefined });
+    const name = (metadata?.pendingAttachmentName as string | undefined) || "screenshot.jpg";
+    fetch(dataUrl)
+      .then((r) => r.blob())
+      .then((blob) => {
+        setExternalFiles([new File([blob], name, { type: blob.type || "image/jpeg" })]);
+        setTimeout(() => setExternalFiles(null), 100);
+      })
+      .catch(() => { /* best effort: the draft still opens, just without the screenshot attached */ });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
   // True from the moment an edit is submitted until the forked session starts
   // responding. Drives a "working" indicator so the ~10s fork + codex connect
   // doesn't leave the user staring at a frozen screen. (No optimistic message
@@ -867,7 +887,10 @@ function ChatTabContent({ metadata, tabId, onNewSession, onFork, historyFilter }
           setProviderId(selectedProvider);
           setPermissionMode(selectedPermission);
           if (tabId) patchTabMetadata(tabId, { permissionMode: selectedPermission });
-          const picked = await ensureAccountClaim(selectedProvider);
+          // The claim is advisory, and so is the server's use of it: a pick that fails
+          // starts the session on whichever account the server chooses, rather than
+          // refusing the first message.
+          const picked = await ensureAccountClaim(selectedProvider).catch(() => null);
           if (attempt !== firstSendAttempt.current) return;
           const latest = metadataRef.current;
           const accountId = latest?.pickedAccountProvider === selectedProvider

package/src/web/components/chat/message-input.tsx

@@ -20,6 +20,7 @@ import { ProviderSelector } from "./provider-selector";
 import { ModelThinkingSelector } from "./model-thinking-selector";
 import type { SlashItem } from "./slash-command-picker";
 import { fetchSlashItems, getCachedSlashItems, subscribeSlashItems, SLASH_ITEMS_TTL_MS } from "@/lib/slash-items-cache";
+import { replaceSlashQuery, slashQueryBefore, stripSlashQuery } from "@/lib/slash-trigger";
 import type { FileNode } from "../../../types/project";
 import { useFileStore } from "@/stores/file-store";
 import { PromptCacheChip } from "./prompt-cache-chip";
@@ -495,13 +496,11 @@ export const MessageInput = memo(function MessageInput({
     const cursorPos = el.selectionStart;
     const textBefore = text.slice(0, cursorPos);
     const textAfter = text.slice(cursorPos);
-    // Strip the /query trigger before the cursor, preserving leading whitespace.
-    const stripTrigger = (match: string) => (match.startsWith("/") ? "" : match[0]!);
 
     // Agents render as a removable chip (not inline text) so the composed
     // "Use the X agent to …" prompt is only assembled at send time.
     if (slashSelected.type === "agent") {
-      const stripped = textBefore.replace(/(?:^|\s)\/\S*$/, stripTrigger);
+      const stripped = stripSlashQuery(textBefore);
       setAgentTag(slashSelected.name);
       writeTextareas(stripped + textAfter);
       onSlashStateChange?.(false, "");
@@ -515,10 +514,7 @@ export const MessageInput = memo(function MessageInput({
     // The item's own sigil is used, not a hardcoded `/`: a codex skill is invoked
     // as `$imagegen`, so the composer must show the text that will actually be
     // sent rather than leaving the server to silently rewrite it.
-    const replaced = textBefore.replace(/(?:^|\s)\/\S*$/, (match) => {
-      const prefix = stripTrigger(match);
-      return `${prefix}${slashSelected.invokeSigil ?? "/"}${slashSelected.name} `;
-    });
+    const replaced = replaceSlashQuery(textBefore, `${slashSelected.invokeSigil ?? "/"}${slashSelected.name}`);
     writeTextareas(replaced + textAfter);
     onSlashStateChange?.(false, "");
     slashPickerOpenRef.current = false;
@@ -816,10 +812,9 @@ export const MessageInput = memo(function MessageInput({
 
       // Check for slash anywhere in text (after whitespace or at start)
       if (hasSlash) {
-        const slashMatch = textBefore.match(/(?:^|\s)\/(\S*)$/);
-        if (slashMatch) {
+        const filter = slashQueryBefore(textBefore);
+        if (filter !== null) {
           if (!slashPickerOpenRef.current) loadSlashItems();
-          const filter = slashMatch[1] ?? "";
           onSlashStateChange?.(true, filter);
           slashPickerOpenRef.current = true;
           if (filePickerOpenRef.current) { onFileStateChange?.(false, ""); filePickerOpenRef.current = false; }

package/src/web/components/design/canvas/design-canvas-pane.tsx

@@ -1,18 +1,16 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useMemo, useRef, useState } from "react";
 import { Loader2, Minimize2, RefreshCw } from "@/lib/icons";
 import { BottomSheet } from "@/components/ui/mobile-bottom-sheet";
 import { cn } from "@/lib/utils";
-import {
-  designFrameKey, loadDesignViewPrefs, saveDesignViewPrefs, withFrame,
-} from "@/lib/design/design-view-prefs";
 import { useDesignTab } from "../design-tab-context";
 import { DesignToolbar, type DesignToolbarContext } from "../design-toolbar";
 import { DesignToolbarList } from "../design-toolbar-list";
 import { DesignHistoryPanel } from "../history/design-history-panel";
 import { useDesignCanvas } from "./use-design-canvas";
-import { defaultFrameFor, framePreset, type DeviceFrameId } from "./device-frame-presets";
-import { fitFrame, type Size } from "./canvas-geometry";
-import { DesignIssuesBadge } from "./design-issues-badge";
+import { useDesignFrame } from "./use-design-frame";
+import { framePreset } from "./device-frame-presets";
+import { DesignIssuesBadge, type CanvasIssue } from "./design-issues-badge";
+import { useDesignVariants, useShownVariant } from "../variants/use-design-variants";
 import { useDesignCommentsFeature } from "../comments/use-design-comments-feature";
 import { DesignCommentsOverlay, DesignCommentsSidePanel } from "../comments/design-comments-layer";
 import { useDesignTweaks } from "../tweaks/use-design-tweaks";
@@ -28,8 +26,9 @@ import { useDesignAutoCheck } from "../use-design-auto-check";
 import { useExpandedCanvasEscape } from "./use-expanded-canvas-escape";
 
 /**
- * The live canvas: the design's entry page in a sandboxed iframe, sized to the chosen
- * device frame, with the toolbar above it (desktop) or behind the More sheet (phone).
+ * The live canvas: the variant on screen (the entry page unless another was chosen) in a
+ * sandboxed iframe, sized to the chosen device frame, with the toolbar above it (desktop) or
+ * behind the More sheet (phone).
  *
  * `sandbox="allow-scripts"` without `allow-same-origin` gives the page an opaque origin, so
  * it can read nothing of PPM's; `no-referrer` keeps its capability URL out of any request
@@ -37,30 +36,11 @@ import { useExpandedCanvasEscape } from "./use-expanded-canvas-escape";
  */
 export function DesignCanvasPane({ moreOpen = false, onMoreClose }: { moreOpen?: boolean; onMoreClose?: () => void }) {
   const tab = useDesignTab();
-  const canvas = useDesignCanvas(tab);
+  const shownVariant = useShownVariant(tab);
+  const canvas = useDesignCanvas(tab, shownVariant.file);
+  const variants = useDesignVariants(shownVariant);
   const [historyOpen, setHistoryOpen] = useState(false);
-  const frameKey = designFrameKey(tab.projectName, tab.slug);
-  const [frame, setFrameState] = useState<DeviceFrameId>(
-    () => loadDesignViewPrefs().frames[frameKey] ?? defaultFrameFor(tab.design.kind),
-  );
-  const setFrame = useCallback((next: DeviceFrameId) => {
-    setFrameState(next);
-    saveDesignViewPrefs(withFrame(loadDesignViewPrefs(), frameKey, next));
-  }, [frameKey]);
-
-  const stageRef = useRef<HTMLDivElement>(null);
-  const [stage, setStage] = useState<Size>({ width: 0, height: 0 });
-  useEffect(() => {
-    const el = stageRef.current;
-    if (!el) return;
-    const observer = new ResizeObserver(([entry]) => {
-      if (entry) setStage({ width: entry.contentRect.width, height: entry.contentRect.height });
-    });
-    observer.observe(el);
-    return () => observer.disconnect();
-  }, []);
-  const fit = fitFrame(framePreset(frame).size, stage);
-  const framed = frame !== "desktop";
+  const { frame, setFrame, stageRef, stage, fit, framed } = useDesignFrame(tab);
 
   // Comments, tweaks and the history share the side column, so opening one closes the others.
   const closeTweaksRef = useRef<() => void>(() => {});
@@ -85,19 +65,23 @@ export function DesignCanvasPane({ moreOpen = false, onMoreClose }: { moreOpen?:
     setHistoryOpen(true);
   }, [closeComments, closeTweaks]);
   const undo = useDesignUndo(tab, { openHistory });
-  const exports = useDesignExport(tab, canvas.bridge);
-  // The self-check: on demand for the agent's design_check tool, and by itself after a turn.
+  // The self-check: on demand for the agent's design_check tool, by itself after a turn, and
+  // for the screenshot "Build in new chat" attaches.
   const checkContext = () => ({ issues: canvas.issues, frame: framePreset(frame).label });
+  const exports = useDesignExport(tab, canvas.bridge, variants.file, checkContext);
   useDesignCanvasCheckResponder({ projectName: tab.projectName, slug: tab.slug, bridge: canvas.bridge, context: checkContext });
   const layoutIssues = useDesignAutoCheck({ tab, bridge: canvas.bridge, context: checkContext });
-  const allIssues = useMemo(() => [...canvas.issues, ...layoutIssues], [canvas.issues, layoutIssues]);
+  const { variantWarnings } = tab.design;
+  const allIssues = useMemo<CanvasIssue[]>(() => [
+    ...canvas.issues, ...layoutIssues, ...(variantWarnings ?? []).map((message) => ({ kind: "manifest" as const, message })),
+  ], [canvas.issues, layoutIssues, variantWarnings]);
 
   const { expanded, setExpanded } = tab.layout;
   useExpandedCanvasEscape(expanded, () => setExpanded(false), () => comments.picker.on);
 
   const toolbarCtx = useMemo<DesignToolbarContext>(() => ({
-    ...tab, canvas, frame, setFrame, historyOpen, toggleHistory, comments, tweaks, transform, undo, exports,
-  }), [tab, canvas, frame, setFrame, historyOpen, toggleHistory, comments, tweaks, transform, undo, exports]);
+    ...tab, canvas, frame, setFrame, historyOpen, toggleHistory, comments, tweaks, transform, undo, exports, variants,
+  }), [tab, canvas, frame, setFrame, historyOpen, toggleHistory, comments, tweaks, transform, undo, exports, variants]);
   const tweaksPanel = tweaks.panelOpen && <TweaksPanel feature={tweaks} tabId={tab.tabId} slug={tab.slug} />;
 
   const history = historyOpen && (

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

@@ -4,16 +4,18 @@ 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.
+ * blocks, links the canvas refused to follow, layout problems the self-check found after the
+ * last turn, and entries of `design.json` the server skipped. Everything here was written by
+ * the page or the agent, 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 };
+  | { kind: "layout"; message: string; source?: string }
+  /** Something in `design.json` the server skipped, such as a variant it could not use. */
+  | { kind: "manifest"; message: string; source?: undefined };
 
 const KIND_LABEL: Record<CanvasIssue["kind"], string> = {
   error: "Error",
@@ -22,6 +24,7 @@ const KIND_LABEL: Record<CanvasIssue["kind"], string> = {
   csp: "Blocked by policy",
   "navigate-blocked": "Link blocked",
   layout: "Layout",
+  manifest: "design.json",
 };
 
 /** Kept per document load; the bridge itself stops at 20, and so does this list. */

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

@@ -26,10 +26,11 @@ export function acceptsExpired(readyForCurrentLoad: boolean): boolean {
   return !readyForCurrentLoad;
 }
 
-export function useDesignCanvas(ctx: DesignTabContextValue) {
-  const { projectName, slug, design, isActive, refreshDesign } = ctx;
+/** `file` is the variant to show: the entry page, or one of the other variants. */
+export function useDesignCanvas(ctx: DesignTabContextValue, file: string) {
+  const { projectName, slug, isActive, refreshDesign } = ctx;
   const iframeRef = useRef<HTMLIFrameElement | null>(null);
-  const preview = useDesignPreviewUrl(projectName, slug);
+  const preview = useDesignPreviewUrl(projectName, slug, file);
   const [load, setLoad] = useState<{ url: string; nonce: string } | null>(null);
   const [dead, setDead] = useState(false);
   const [issues, setIssues] = useState<CanvasIssue[]>([]);
@@ -61,13 +62,17 @@ export function useDesignCanvas(ctx: DesignTabContextValue) {
     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);
+  // Another variant, or a manifest naming another entry page, needs a URL for that page.
+  const shown = useRef(file);
   useEffect(() => {
-    if (entry.current === design.entry) return;
-    entry.current = design.entry;
-    void reload({ remint: true });
-  }, [design.entry, reload]);
+    if (shown.current === file) return;
+    shown.current = file;
+    void preview.retarget(file).then((url) => {
+      if (!url || shown.current !== file) return;
+      setIssues([]);
+      setLoad({ url, nonce: newBridgeNonce() });
+    });
+  }, [file, preview]);
 
   useEffect(() => {
     const offs = [
@@ -93,6 +98,7 @@ export function useDesignCanvas(ctx: DesignTabContextValue) {
     projectName, slug, isActive,
     reload: (opts) => { void reload(opts); },
     onManifestChanged: refreshDesign,
+    entry: ctx.design.entry,
     currentUrl: () => load?.url ?? null,
     readyGen: () => readyGen.current,
   });

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

@@ -0,0 +1,36 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import {
+  designFrameKey, loadDesignViewPrefs, saveDesignViewPrefs, withFrame,
+} from "@/lib/design/design-view-prefs";
+import type { DesignTabContextValue } from "../design-tab-context";
+import { defaultFrameFor, framePreset, type DeviceFrameId } from "./device-frame-presets";
+import { fitFrame, type Size } from "./canvas-geometry";
+
+/**
+ * The device frame the canvas is shown in (remembered per design on this device) and how it
+ * fits the stage it sits on, re-measured whenever the stage is resized.
+ */
+export function useDesignFrame(tab: DesignTabContextValue) {
+  const frameKey = designFrameKey(tab.projectName, tab.slug);
+  const [frame, setFrameState] = useState<DeviceFrameId>(
+    () => loadDesignViewPrefs().frames[frameKey] ?? defaultFrameFor(tab.design.kind),
+  );
+  const setFrame = useCallback((next: DeviceFrameId) => {
+    setFrameState(next);
+    saveDesignViewPrefs(withFrame(loadDesignViewPrefs(), frameKey, next));
+  }, [frameKey]);
+
+  const stageRef = useRef<HTMLDivElement>(null);
+  const [stage, setStage] = useState<Size>({ width: 0, height: 0 });
+  useEffect(() => {
+    const el = stageRef.current;
+    if (!el) return;
+    const observer = new ResizeObserver(([entry]) => {
+      if (entry) setStage({ width: entry.contentRect.width, height: entry.contentRect.height });
+    });
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, []);
+  const fit = fitFrame(framePreset(frame).size, stage);
+  return { frame, setFrame, stageRef, stage, fit, framed: frame !== "desktop" };
+}

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

@@ -1,5 +1,5 @@
 import { useEffect, useRef } from "react";
-import { classifyDesignChange } from "@/lib/design/design-change-filter";
+import { classifyDesignChange, mayChangeVariants } from "@/lib/design/design-change-filter";
 
 /**
  * Keep the canvas in step with the design's files.
@@ -20,7 +20,10 @@ export interface LiveReloadOptions {
   /** True while the design tab is the visible tab of its panel. */
   isActive: boolean;
   reload: (opts?: { remint?: boolean }) => void;
+  /** Also called when a page that may be a variant appears or goes (see `mayChangeVariants`). */
   onManifestChanged: () => void;
+  /** The design's entry page, which is never a variant that can come or go. */
+  entry: string;
   /** 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. */
@@ -34,11 +37,20 @@ export function useDesignLiveReload(opts: LiveReloadOptions): void {
 
   useEffect(() => {
     let timer: ReturnType<typeof setTimeout> | null = null;
+    // Same debounce for re-reading the design: an agent writing three variants and the
+    // manifest is one refetch, not one per file.
+    let manifestTimer: 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 === "manifest" || mayChangeVariants(detail.path, slug, optsRef.current.entry)) {
+        if (manifestTimer) clearTimeout(manifestTimer);
+        manifestTimer = setTimeout(() => {
+          manifestTimer = null;
+          optsRef.current.onManifestChanged();
+        }, LIVE_RELOAD_DEBOUNCE_MS);
+      }
       if (change !== "reload") return;
       if (timer) clearTimeout(timer);
       timer = setTimeout(() => {
@@ -50,6 +62,7 @@ export function useDesignLiveReload(opts: LiveReloadOptions): void {
     return () => {
       window.removeEventListener("file:changed", onChange);
       if (timer) clearTimeout(timer);
+      if (manifestTimer) clearTimeout(manifestTimer);
     };
   }, [projectName, slug]);
 
@@ -64,7 +77,14 @@ export function useDesignLiveReload(opts: LiveReloadOptions): void {
       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; }
+        if (res.status === 404) {
+          // Gone while hidden: an expired token, or a variant another device's pick deleted.
+          // The design is re-read too, so a vanished variant falls back to the entry page
+          // instead of re-minting a URL for a file the server no longer lists.
+          optsRef.current.onManifestChanged();
+          reload({ remint: true });
+          return;
+        }
         const current = res.headers.get("X-PPM-Gen");
         if (res.ok && current && current !== gen) reload();
       } catch (e) {

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

@@ -2,7 +2,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { requestCanvasPreview } from "@/lib/design/api-designs";
 
 /**
- * The canvas's capability URL for one design.
+ * The canvas's capability URL for one design, pointing at the variant on screen.
  *
  * 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
@@ -10,7 +10,11 @@ import { requestCanvasPreview } from "@/lib/design/api-designs";
  * 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.
+ * expired, or stopped answering. `retarget` points the URL at another variant through the
+ * refresh call, keeping the token — every switch minting a new one would fill the shared
+ * token store and push out other canvases' tokens. Every answer is for the file that was
+ * asked for, and one that arrives after the user switched again is dropped, so the next
+ * load never shows a variant that is no longer the chosen one.
  */
 
 export const PREVIEW_REFRESH_MS = 10 * 60 * 1000;
@@ -22,18 +26,22 @@ export interface DesignPreviewUrl {
   initialUrl: string | null;
   error: string | null;
   remint: () => Promise<string | null>;
+  /** The URL for variant `file`, keeping the token when it is still alive. */
+  retarget: (file: string) => Promise<string | null>;
 }
 
-export function useDesignPreviewUrl(projectName: string, slug: string): DesignPreviewUrl {
+export function useDesignPreviewUrl(projectName: string, slug: string, file: 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 fileRef = useRef(file);
 
   const remint = useCallback(async (): Promise<string | null> => {
+    const asked = fileRef.current;
     try {
-      const cap = await requestCanvasPreview(projectName, slug);
-      if (!alive.current) return null;
+      const cap = await requestCanvasPreview(projectName, slug, undefined, asked);
+      if (!alive.current || asked !== fileRef.current) return null;
       latest.current = { url: cap.url, token: cap.token };
       setError(null);
       return cap.url;
@@ -43,6 +51,22 @@ export function useDesignPreviewUrl(projectName: string, slug: string): DesignPr
     }
   }, [projectName, slug]);
 
+  const retarget = useCallback(async (next: string): Promise<string | null> => {
+    fileRef.current = next;
+    const token = latest.current?.token;
+    if (!token) return remint();
+    try {
+      const cap = await requestCanvasPreview(projectName, slug, token, next);
+      if (!alive.current || next !== fileRef.current) return null;
+      latest.current = { url: cap.url, token: cap.token };
+      setError(null);
+      return cap.url;
+    } catch {
+      // The token died (a restart, the idle timeout): a new one is the only way on.
+      return next === fileRef.current ? remint() : null;
+    }
+  }, [projectName, slug, remint]);
+
   useEffect(() => {
     alive.current = true;
     latest.current = null;
@@ -55,10 +79,11 @@ export function useDesignPreviewUrl(projectName: string, slug: string): DesignPr
     const timer = setInterval(() => {
       const current = latest.current;
       if (!current) return;
-      requestCanvasPreview(projectName, slug, current.token)
+      const asked = fileRef.current;
+      requestCanvasPreview(projectName, slug, current.token, asked)
         .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 };
+          if (alive.current && cap.rotated && asked === fileRef.current) latest.current = { url: cap.url, token: cap.token };
         })
         .catch((e) => {
           // An expired token cannot be refreshed; the frame posts `expired` on its next
@@ -70,5 +95,5 @@ export function useDesignPreviewUrl(projectName: string, slug: string): DesignPr
   }, [projectName, slug]);
 
   const latestUrl = useCallback(() => latest.current?.url ?? null, []);
-  return useMemo(() => ({ latestUrl, initialUrl, error, remint }), [latestUrl, initialUrl, error, remint]);
+  return useMemo(() => ({ latestUrl, initialUrl, error, remint, retarget }), [latestUrl, initialUrl, error, remint, retarget]);
 }