plotlink-ows 1.0.32 → 1.2.94

package/app/web/components/TerminalPanel.tsx

@@ -3,6 +3,17 @@ import { Terminal } from "@xterm/xterm";
 import { FitAddon } from "@xterm/addon-fit";
 import { SerializeAddon } from "@xterm/addon-serialize";
 import "@xterm/xterm/css/xterm.css";
+import { isCodexAuthUnclear, CODEX_AUTH_UNCLEAR_MESSAGE, type AgentReadiness } from "@app-lib/agent-readiness";
+import { FRESH_SPAWN_SIGNAL } from "@app-lib/terminal-protocol";
+import { redactTerminalSecrets } from "@app-lib/terminal-redact";
+
+/** Story metadata persisted with a `_new_*` → real-folder rename (#295). */
+export interface RenameMeta {
+  contentType?: "fiction" | "cartoon";
+  language?: string;
+  agentMode?: "normal" | "bypass";
+  agentProvider?: "claude" | "codex";
+}
 
 interface TerminalPanelProps {
   token: string;
@@ -12,7 +23,49 @@ interface TerminalPanelProps {
   onDestroySession?: (storyName: string) => void;
   onArchiveStory?: (storyName: string) => void;
   confirmedStories?: Set<string>;
-  renameRef?: React.RefObject<((oldName: string, newName: string) => Promise<boolean>) | null>;
+  // The optional `meta` is persisted to the confirmed story's .story.json
+  // atomically with the rename so a fresh story's provider/contentType survive (#295).
+  renameRef?: React.RefObject<((oldName: string, newName: string, meta?: RenameMeta) => Promise<boolean>) | null>;
+  bypassStories?: Record<string, boolean>;
+  agentProviders?: Record<string, "claude" | "codex">;
+  /** Local agent (Codex) readiness. null/undefined = not yet loaded (fail-open). */
+  readiness?: AgentReadiness | null;
+  /** Content type of the currently-selected story (undefined = unknown). */
+  contentType?: "fiction" | "cartoon";
+  /**
+   * True only for the selected real (non-`_new_*`) cartoon story whose
+   * `.story.json` has no `agentProvider` recorded (legacy). When true, show the
+   * explicit provider-repair CTA instead of auto-spawning, so the writer sets
+   * the provider to Codex before launching. Never true for fiction or a cartoon
+   * that already has a provider.
+   */
+  needsProviderRepair?: boolean;
+  /** Set this story's provider to Codex (scoped, non-destructive repair). */
+  onRepairProvider?: () => void | Promise<void>;
+}
+
+const CODEX_ENABLE_CMD = "codex features enable image_generation";
+
+/**
+ * Pure predicate: should the cartoon agent LAUNCH be blocked?
+ *
+ * Blocked ONLY when ALL of:
+ *  - the selected story is a cartoon, AND
+ *  - readiness has loaded (non-null), AND
+ *  - Codex is NOT ready (not installed OR image generation not enabled).
+ *
+ * Fail-open: readiness null/undefined => NOT blocked (a probe failure must never
+ * brick terminals). Fiction / undefined contentType => NEVER blocked.
+ */
+export function isCartoonLaunchBlocked(
+  contentType: "fiction" | "cartoon" | undefined,
+  readiness: AgentReadiness | null | undefined,
+): boolean {
+  if (contentType !== "cartoon") return false;
+  if (!readiness) return false; // fail-open until readiness resolves
+  const codexReady =
+    readiness.codex.installed && readiness.codex.imageGeneration === "enabled";
+  return !codexReady;
 }
 
 interface TerminalSession {
@@ -106,13 +159,21 @@ async function deleteScrollback(storyName: string): Promise<void> {
 // Sessions live outside React state to avoid ref-in-effect lint issues
 const sessions = new Map<string, TerminalSession>();
 
-export function TerminalPanel({ token, storyName, authFetch, onSelectStory, onDestroySession, onArchiveStory, confirmedStories, renameRef }: TerminalPanelProps) {
+export function TerminalPanel({ token, storyName, authFetch, onSelectStory, onDestroySession, onArchiveStory, confirmedStories, renameRef, bypassStories, agentProviders, readiness, contentType, needsProviderRepair, onRepairProvider }: TerminalPanelProps) {
   const wrapperRef = useRef<HTMLDivElement>(null);
   const authFetchRef = useRef(authFetch);
   const [sessionList, setSessionList] = useState<string[]>([]);
   const [disconnected, setDisconnected] = useState<Set<string>>(new Set());
   const [confirmingDiscard, setConfirmingDiscard] = useState<string | null>(null);
   const [confirmingArchive, setConfirmingArchive] = useState<string | null>(null);
+  const [copiedEnableCmd, setCopiedEnableCmd] = useState(false);
+  const [repairing, setRepairing] = useState(false);
+
+  // Gate the cartoon agent launch for the currently-selected story.
+  const cartoonLaunchBlocked = isCartoonLaunchBlocked(contentType, readiness);
+  // Legacy cartoon (no provider recorded) ⇒ require explicit provider repair
+  // before auto-spawning a terminal. Scoped to the selected story only.
+  const showProviderRepair = !!needsProviderRepair;
 
   const connectWsRef = useRef<(name: string, session: TerminalSession, resume: boolean) => void>(() => {});
 
@@ -142,10 +203,19 @@ export function TerminalPanel({ token, storyName, authFetch, onSelectStory, onDe
     }
   }, [safeFit]);
 
+  const bypassRef = useRef<Record<string, boolean>>({});
+  useEffect(() => { bypassRef.current = bypassStories || {}; }, [bypassStories]);
+
+  const providerRef = useRef<Record<string, "claude" | "codex">>({});
+  useEffect(() => { providerRef.current = agentProviders || {}; }, [agentProviders]);
+
   const connectWs = useCallback((name: string, session: TerminalSession, resume: boolean) => {
     const wsProto = window.location.protocol === "https:" ? "wss:" : "ws:";
+    const bypass = bypassRef.current[name] ? "&bypass=true" : "";
+    const provider = providerRef.current[name];
+    const providerParam = provider ? `&provider=${encodeURIComponent(provider)}` : "";
     const ws = new WebSocket(
-      `${wsProto}//${window.location.host}/ws/terminal?story=${encodeURIComponent(name)}&token=${token}&resume=${resume}`
+      `${wsProto}//${window.location.host}/ws/terminal?story=${encodeURIComponent(name)}&token=${token}&resume=${resume}${bypass}${providerParam}`
     );
 
     ws.onopen = () => {
@@ -155,8 +225,22 @@ export function TerminalPanel({ token, storyName, authFetch, onSelectStory, onDe
       ws.send(JSON.stringify({ type: "resize", cols: session.term.cols, rows: session.term.rows }));
     };
 
+    // The very first frame may be a control signal (#453). A fresh server spawn
+    // (the agent process reprints its banner/history) sends FRESH_SPAWN_SIGNAL —
+    // drop the restored scrollback so the banner isn't duplicated. Any other
+    // first frame (a live-PTY reconnect) is normal PTY output and is kept.
+    let firstFrame = true;
     ws.onmessage = (e) => {
-      session.term.write(e.data);
+      if (firstFrame) {
+        firstFrame = false;
+        if (typeof e.data === "string" && e.data === FRESH_SPAWN_SIGNAL) {
+          session.term.reset();
+          deleteScrollback(name).catch(() => {});
+          return;
+        }
+      }
+      // Mask obvious auth secrets before they reach the terminal / scrollback (#454).
+      session.term.write(typeof e.data === "string" ? redactTerminalSecrets(e.data) : e.data);
     };
 
     ws.onclose = (event) => {
@@ -242,11 +326,16 @@ export function TerminalPanel({ token, storyName, authFetch, onSelectStory, onDe
     sessions.set(name, session);
     setSessionList((prev) => [...prev, name]);
 
-    // Restore scrollback from IndexedDB
+    // Restore scrollback from IndexedDB, masking any auth secrets first so an OLD
+    // transcript can't re-display previously-persisted tokens/passphrases (#454).
+    // If redaction changed it, re-save the masked copy so the raw value is gone
+    // from storage and never re-persisted later.
     try {
       const saved = await loadScrollback(name);
       if (saved) {
-        term.write(saved);
+        const redacted = redactTerminalSecrets(saved);
+        term.write(redacted);
+        if (redacted !== saved) saveScrollback(name, redacted).catch(() => {});
       }
     } catch { /* ignore */ }
 
@@ -330,15 +419,16 @@ export function TerminalPanel({ token, storyName, authFetch, onSelectStory, onDe
 
   /** Rename a session key (e.g. _new_123 → paper-chair) without killing the PTY.
    *  Returns true on success, false on failure. */
-  const renameSession = useCallback(async (oldName: string, newName: string): Promise<boolean> => {
+  const renameSession = useCallback(async (oldName: string, newName: string, meta?: RenameMeta): Promise<boolean> => {
     const session = sessions.get(oldName);
     if (!session || sessions.has(newName)) return false;
 
-    // Rename on the server first
+    // Rename on the server first. Forward the confirmed story's metadata so the
+    // server persists contentType/provider atomically with the rename (#295).
     const res = await authFetchRef.current("/api/terminal/rename", {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ oldName, newName }),
+      body: JSON.stringify({ oldName, newName, ...(meta ?? {}) }),
     });
     if (!res.ok) return false;
 
@@ -363,6 +453,24 @@ export function TerminalPanel({ token, storyName, authFetch, onSelectStory, onDe
       return next;
     });
 
+    // #377: the renamed session's live PTY keeps the cwd it was SPAWNED in, so
+    // after the story folder moves (e.g. _new_* → final, or a partial slug →
+    // full title) the agent's trust prompt / working directory still points at
+    // the old (now-renamed) folder — confusing, and the old folder may no longer
+    // exist. If this session is live, move the terminal into the FINAL folder:
+    // kill the stale-cwd PTY and reconnect WITH RESUME, so the new spawn runs in
+    // stories/<newName> (correct cwd/trust prompt) while the conversation is
+    // preserved (claude --resume / codex resume). The server reads the provider
+    // from the .story.json it just persisted, so the respawn stays provider-aware.
+    // If resume can't recover, the existing code-4000 path reconnects fresh in
+    // the same (correct) folder. A never-connected session needs no respawn — its
+    // first connect already uses the final name.
+    if (session.connected || session.ws) {
+      await authFetchRef.current(`/api/terminal/${encodeURIComponent(newName)}`, { method: "DELETE" }).catch(() => {});
+      if (session.ws) { session.ws.close(); session.ws = null; }
+      connectWsRef.current(newName, session, true);
+    }
+
     return true;
   }, []);
 
@@ -375,6 +483,20 @@ export function TerminalPanel({ token, storyName, authFetch, onSelectStory, onDe
   // Auto-spawn + show/hide when story changes
   useEffect(() => {
     if (!storyName) return;
+    // Cartoon readiness gate: never spawn/connect a terminal for a cartoon
+    // story whose Codex/image_generation is known-not-ready. Show guidance
+    // instead (rendered below). Fail-open when readiness is null/undefined.
+    if (cartoonLaunchBlocked) {
+      showSession(null);
+      return;
+    }
+    // Legacy cartoon with no recorded provider: do NOT auto-spawn. Show the
+    // explicit repair CTA so the writer sets the provider to Codex first. After
+    // repair, `needsProviderRepair` flips false and normal gating/launch applies.
+    if (showProviderRepair) {
+      showSession(null);
+      return;
+    }
     if (!sessions.has(storyName)) {
       // Check if a previous session exists — if so, show overlay instead of auto-connecting
       authFetchRef.current(`/api/terminal/session/${encodeURIComponent(storyName)}`)
@@ -395,7 +517,7 @@ export function TerminalPanel({ token, storyName, authFetch, onSelectStory, onDe
     } else {
       showSession(storyName);
     }
-  }, [storyName, createSession, showSession]);
+  }, [storyName, createSession, showSession, cartoonLaunchBlocked, showProviderRepair]);
 
   // Periodic scrollback save (every 30s for active session)
   useEffect(() => {
@@ -496,7 +618,7 @@ export function TerminalPanel({ token, storyName, authFetch, onSelectStory, onDe
         <div ref={wrapperRef} className="h-full" />
 
         {/* Empty state overlay */}
-        {isEmpty && (
+        {isEmpty && !cartoonLaunchBlocked && !showProviderRepair && (
           <div className="absolute inset-0 flex items-center justify-center text-muted">
             <div className="text-center">
               <p className="text-lg font-serif">Select a story on the left menu</p>
@@ -505,6 +627,106 @@ export function TerminalPanel({ token, storyName, authFetch, onSelectStory, onDe
           </div>
         )}
 
+        {/* Cartoon launch gated: Codex / image generation not ready */}
+        {cartoonLaunchBlocked && (
+          <div
+            data-testid="cartoon-launch-blocked"
+            className="absolute inset-0 flex items-center justify-center"
+            style={{ background: "rgba(240, 235, 225, 0.9)" }}
+          >
+            <div className="space-y-3 p-6 bg-surface border border-border rounded-lg shadow-lg max-w-md">
+              <p className="text-sm font-serif text-foreground font-medium">
+                Cartoon agent can&apos;t launch yet
+              </p>
+              <p className="text-xs text-muted">
+                This is a cartoon story. The writing agent needs Codex with image
+                generation enabled before it can start, because the clean-image
+                step relies on image generation support.
+              </p>
+              {readiness && !readiness.codex.installed ? (
+                <p className="text-xs text-amber-700">
+                  Codex was not detected. Install the Codex CLI and sign in
+                  (e.g. <span className="font-mono">npm i -g @openai/codex</span> then{" "}
+                  <span className="font-mono">codex login</span>), then reopen this story.
+                </p>
+              ) : isCodexAuthUnclear(readiness) ? (
+                <p className="text-xs text-amber-700" data-testid="codex-auth-unknown-launch">
+                  {CODEX_AUTH_UNCLEAR_MESSAGE} Then reopen this story.
+                </p>
+              ) : (
+                <div className="space-y-1">
+                  <p className="text-xs text-amber-700">
+                    Codex is installed but image generation isn&apos;t enabled. Enable
+                    it, then reopen this story:
+                  </p>
+                  <div className="flex items-center gap-1">
+                    <code className="flex-1 truncate rounded border border-border bg-surface px-1.5 py-1 text-left text-[10px] font-mono text-foreground">
+                      {CODEX_ENABLE_CMD}
+                    </code>
+                    <button
+                      type="button"
+                      data-testid="copy-codex-enable-launch"
+                      onClick={async () => {
+                        try {
+                          await navigator.clipboard.writeText(CODEX_ENABLE_CMD);
+                          setCopiedEnableCmd(true);
+                          setTimeout(() => setCopiedEnableCmd(false), 2000);
+                        } catch { /* clipboard unavailable */ }
+                      }}
+                      className="rounded border border-border px-2 py-1 text-[10px] text-muted hover:border-accent hover:text-accent transition-colors"
+                    >
+                      {copiedEnableCmd ? "Copied!" : "Copy"}
+                    </button>
+                  </div>
+                </div>
+              )}
+            </div>
+          </div>
+        )}
+
+        {/* Legacy cartoon: no provider recorded — explicit, scoped repair CTA.
+            Separate from readiness gating; about a MISSING provider on this one
+            story. Setting it to Codex never touches other stories or fiction. */}
+        {showProviderRepair && !cartoonLaunchBlocked && (
+          <div
+            data-testid="legacy-cartoon-provider-repair"
+            className="absolute inset-0 flex items-center justify-center"
+            style={{ background: "rgba(240, 235, 225, 0.9)" }}
+          >
+            <div className="space-y-3 p-6 bg-surface border border-border rounded-lg shadow-lg max-w-md">
+              <p className="text-sm font-serif text-foreground font-medium">
+                Set this cartoon story&apos;s provider
+              </p>
+              <p className="text-xs text-muted">
+                This cartoon story was created before provider tracking, so it has
+                no provider recorded and would launch with Claude — which can&apos;t
+                generate the clean images cartoons need. Set this story&apos;s
+                provider to Codex to continue.
+              </p>
+              <p className="text-[11px] text-muted">
+                Only this story is changed. Other stories and fiction are not affected.
+              </p>
+              <button
+                type="button"
+                data-testid="repair-provider-codex"
+                disabled={repairing}
+                onClick={async () => {
+                  if (repairing) return;
+                  setRepairing(true);
+                  try {
+                    await onRepairProvider?.();
+                  } finally {
+                    setRepairing(false);
+                  }
+                }}
+                className="px-4 py-1.5 bg-accent text-white text-sm rounded hover:bg-accent-dim disabled:opacity-50 disabled:cursor-not-allowed"
+              >
+                {repairing ? "Setting…" : "Set this story's provider to Codex"}
+              </button>
+            </div>
+          </div>
+        )}
+
         {/* Discard confirmation overlay */}
         {confirmingDiscard && (
           <div className="absolute inset-0 flex items-center justify-center z-10" style={{ background: "rgba(240, 235, 225, 0.9)" }}>

package/app/web/components/WorkflowCoach.tsx

@@ -0,0 +1,128 @@
+import { useEffect, useState } from "react";
+import type { CartoonCoach, CoachUiAction } from "@app-lib/cartoon-coach";
+import type { StoryProgress } from "@app-lib/story-progress";
+
+/**
+ * Persistent cartoon workflow coach (#429). Converts the current story/episode
+ * state into one stage label + one primary next action — an agent copy-paste
+ * prompt or a direct in-app UI action — so a normal writer always knows the next
+ * step without reading terminal logs or technical warnings. It never blocks the
+ * terminal or advanced controls; it just makes the normal path obvious.
+ *
+ * Two pieces:
+ *  - `WorkflowCoachView` is presentational (takes an already-loaded coach) so the
+ *    progress overview, which already fetches the progress payload, can render it
+ *    with no extra request.
+ *  - `WorkflowCoach` is the self-loading container the file views use.
+ *
+ * Fiction is unaffected: the coach is null for fiction, so the view renders
+ * nothing.
+ */
+
+interface WorkflowCoachViewProps {
+  coach: CartoonCoach | null | undefined;
+  /** Run an app-driven step (the agent steps copy a prompt instead). */
+  onAction: (action: CoachUiAction, episodeFile: string | null) => void;
+  className?: string;
+}
+
+export function WorkflowCoachView({ coach, onAction, className = "" }: WorkflowCoachViewProps) {
+  // Track the prompt that was copied rather than a bare boolean, so the "Copied!"
+  // confirmation derives to false the moment the coach (and its prompt) changes —
+  // no reset effect, no stale confirmation under a new stage.
+  const [copiedPrompt, setCopiedPrompt] = useState<string | null>(null);
+  const copied = copiedPrompt !== null && copiedPrompt === coach?.prompt;
+
+  if (!coach) return null;
+
+  return (
+    <div
+      className={`flex items-center gap-2 px-3 py-2 bg-accent/5 border-b border-accent/30 text-xs ${className}`}
+      data-testid="workflow-coach"
+      data-stage={coach.stageLabel}
+      data-action-kind={coach.actionKind}
+      data-ui-action={coach.uiAction ?? ""}
+    >
+      <span className="rounded-full bg-background px-2 py-0.5 text-[10px] font-medium uppercase tracking-[0.14em] text-accent flex-shrink-0" data-testid="workflow-coach-stage">
+        {coach.stageLabel}
+      </span>
+      <span className="min-w-0 flex-1 text-foreground" data-testid="workflow-coach-action">
+        <span className="text-muted">Next: </span>
+        <span className="font-medium">{coach.action}</span>
+      </span>
+      {coach.actionKind === "agent" && coach.prompt ? (
+        <button
+          onClick={() => {
+            if (!coach.prompt) return;
+            const prompt = coach.prompt;
+            navigator.clipboard?.writeText(prompt).then(() => setCopiedPrompt(prompt)).catch(() => {});
+          }}
+          data-testid="workflow-coach-copy"
+          className="flex-shrink-0 rounded bg-accent px-2.5 py-1 text-[11px] font-medium text-white hover:bg-accent-dim transition-colors"
+        >
+          {copied ? "Copied!" : "Copy prompt"}
+        </button>
+      ) : coach.actionKind === "ui" && coach.uiAction ? (
+        <button
+          onClick={() => onAction(coach.uiAction!, coach.episodeFile)}
+          data-testid="workflow-coach-do"
+          className="flex-shrink-0 rounded bg-accent px-2.5 py-1 text-[11px] font-medium text-white hover:bg-accent-dim transition-colors"
+        >
+          {coach.action}
+        </button>
+      ) : null}
+    </div>
+  );
+}
+
+interface WorkflowCoachProps {
+  storyName: string;
+  /** The file currently in focus, so the coach speaks about that episode (#429). */
+  fileName?: string | null;
+  authFetch: (url: string, opts?: RequestInit) => Promise<Response>;
+  /** Bumped by the parent to reload after a state change (cut edit / publish). */
+  refreshKey?: number;
+  onAction: (action: CoachUiAction, episodeFile: string | null) => void;
+}
+
+/**
+ * Self-loading coach for the file views. Fetches the story progress (scoped to
+ * the focused file) and renders the coach bar. The coach is cleared in EVERY
+ * load exit path — at the start, on a non-OK response, and on error — so a
+ * previous file's coach can never linger under a different file when the new
+ * request fails or 404s (the stale-state-on-error class flagged on #420/#427).
+ */
+export function WorkflowCoach({ storyName, fileName, authFetch, refreshKey = 0, onAction }: WorkflowCoachProps) {
+  const [coach, setCoach] = useState<CartoonCoach | null>(null);
+
+  // Reset the coach the instant the target changes (file switch / refresh),
+  // during render — React's recommended way to reset state on a changing input.
+  // This clears the prior file's coach BEFORE the new load resolves; and because
+  // the effect below sets the coach to null on a non-OK response and never sets
+  // it on error, it also STAYS cleared when the new load fails or 404s (the
+  // stale-state-on-error class flagged on #420/#427).
+  //
+  // JSON.stringify keeps the key printable and source-safe (#437): it changes
+  // whenever any input changes — identical reset semantics — and it escapes the
+  // parts so a separator can never collide with the values' own content.
+  const targetKey = JSON.stringify([storyName, fileName ?? "", refreshKey]);
+  const [loadedKey, setLoadedKey] = useState<string | null>(null);
+  if (loadedKey !== targetKey) {
+    setCoach(null);
+    setLoadedKey(targetKey);
+  }
+
+  useEffect(() => {
+    let cancelled = false;
+    const focus = fileName ? `?focus=${encodeURIComponent(fileName)}` : "";
+    authFetch(`/api/stories/${storyName}/progress${focus}`)
+      .then((res) => (res.ok ? res.json() : null))
+      .then((data: (StoryProgress & { coach?: CartoonCoach | null }) | null) => {
+        if (!cancelled) setCoach(data?.coach ?? null);
+      })
+      .catch(() => { /* leave it cleared — the coach is best-effort */ });
+    return () => { cancelled = true; };
+  }, [storyName, fileName, authFetch, refreshKey]);
+
+  return <WorkflowCoachView coach={coach} onAction={onAction} />;
+}

package/app/web/components/asset-image.tsx

@@ -0,0 +1,114 @@
+import { useState, useEffect } from "react";
+
+type AuthFetch = (url: string, opts?: RequestInit) => Promise<Response>;
+
+/** Resolve a story-relative asset path to its auth-protected API URL. */
+export function assetUrl(storyName: string, assetPath: string): string {
+  const relative = assetPath.startsWith("assets/") ? assetPath.slice(7) : assetPath;
+  return `/api/stories/${storyName}/asset/${relative}`;
+}
+
+interface AssetState {
+  /** Same-origin blob object URL safe to use as an <img src>, or null. */
+  url: string | null;
+  loading: boolean;
+  error: boolean;
+}
+
+/**
+ * Load an auth-protected story asset as a blob object URL.
+ *
+ * Story asset routes sit behind `requireAuth`, but a browser `<img src>`
+ * request never carries the `Authorization: Bearer` header that `authFetch`
+ * adds, so the raw URL 401s and the image breaks. Instead we fetch the asset
+ * via `authFetch`, turn the response into a blob, and hand back an object URL.
+ * The object URL is revoked when the asset path changes or the component
+ * unmounts so we don't leak blobs across cut selections.
+ */
+export function useAuthedAsset(
+  storyName: string,
+  assetPath: string | null | undefined,
+  authFetch: AuthFetch,
+): AssetState {
+  const [state, setState] = useState<AssetState>({
+    url: null,
+    loading: !!assetPath,
+    error: false,
+  });
+
+  useEffect(() => {
+    if (!assetPath) {
+      setState({ url: null, loading: false, error: false });
+      return;
+    }
+
+    let objectUrl: string | null = null;
+    let cancelled = false;
+    setState({ url: null, loading: true, error: false });
+
+    (async () => {
+      try {
+        const res = await authFetch(assetUrl(storyName, assetPath));
+        if (!res.ok) throw new Error(`asset request failed (${res.status})`);
+        const blob = await res.blob();
+        if (cancelled) return;
+        objectUrl = URL.createObjectURL(blob);
+        setState({ url: objectUrl, loading: false, error: false });
+      } catch {
+        if (!cancelled) setState({ url: null, loading: false, error: true });
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+      if (objectUrl) URL.revokeObjectURL(objectUrl);
+    };
+  }, [storyName, assetPath, authFetch]);
+
+  return state;
+}
+
+interface AssetImageProps {
+  storyName: string;
+  assetPath: string;
+  authFetch: AuthFetch;
+  alt: string;
+  className?: string;
+}
+
+/**
+ * Render an auth-protected story asset as an image, loading it through
+ * `useAuthedAsset`. Shows a neutral placeholder while loading and a clear
+ * "Image not available" state on failure so a broken auth boundary surfaces
+ * instead of a broken-image glyph.
+ */
+export function AssetImage({ storyName, assetPath, authFetch, alt, className }: AssetImageProps) {
+  const { url, loading, error } = useAuthedAsset(storyName, assetPath, authFetch);
+
+  if (error || (!loading && !url)) {
+    return (
+      <div className="w-full aspect-video bg-surface border border-border rounded flex items-center justify-center">
+        <span className="text-xs text-muted">Image not available</span>
+      </div>
+    );
+  }
+
+  if (!url) {
+    return (
+      <div
+        className="w-full aspect-video bg-surface border border-border rounded flex items-center justify-center"
+        data-testid="asset-loading"
+      >
+        <span className="text-xs text-muted">Loading image…</span>
+      </div>
+    );
+  }
+
+  return (
+    <img
+      src={url}
+      alt={alt}
+      className={className ?? "w-full rounded border border-border"}
+    />
+  );
+}

package/app/web/components/asset-test-utils.ts

@@ -0,0 +1,44 @@
+import { vi } from "vitest";
+
+/** Object URL returned by the stubbed `URL.createObjectURL` in jsdom tests. */
+export const MOCK_BLOB_URL = "blob:mock-asset-url";
+
+/**
+ * jsdom doesn't implement the object-URL APIs that `useAuthedAsset` relies on.
+ * Stub them so blob-backed asset loading works in component tests, and so a
+ * test can assert that an `<img>` points at the object URL rather than the
+ * raw auth-protected API route.
+ */
+export function installObjectUrlStub(): void {
+  const u = URL as unknown as {
+    createObjectURL: (b: Blob) => string;
+    revokeObjectURL: (s: string) => void;
+  };
+  u.createObjectURL = vi.fn(() => MOCK_BLOB_URL);
+  u.revokeObjectURL = vi.fn();
+}
+
+/**
+ * `authFetch` double for tests that render asset-loading components. Asset
+ * routes (`/asset/`) resolve to an image blob the way the real authenticated
+ * route does; every other route resolves to `jsonData`. This mirrors the real
+ * world where the Bearer header reaches both the data route and the image —
+ * the bug being fixed was a raw `<img src>` that never sent that header.
+ */
+export function makeAssetAuthFetch(jsonData: unknown = {}) {
+  return vi.fn((url: string) =>
+    Promise.resolve(
+      url.includes("/asset/")
+        ? {
+            ok: true,
+            status: 200,
+            blob: () => Promise.resolve(new Blob(["img-bytes"], { type: "image/webp" })),
+          }
+        : {
+            ok: true,
+            status: 200,
+            json: () => Promise.resolve(jsonData),
+          },
+    ),
+  );
+}