videoclaw 3.0.0-alpha.1

package/src/video/preview-portal/discovery.ts

@@ -0,0 +1,787 @@
+import { existsSync } from 'node:fs';
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { basename, isAbsolute, join, relative, resolve } from 'node:path';
+import { readBrandDefinition } from '../brand-definition.js';
+import { probeMedia } from '../final-media.js';
+import { readImageDimensions } from '../image-dimensions.js';
+import { PREVIEW_PORTAL_TEMPLATE_REGISTRY } from './templates.js';
+import type {
+  PreviewPortalAsset,
+  PreviewPortalBrand,
+  PreviewPortalCastMember,
+  PreviewPortalBrief,
+  PreviewPortalCard,
+  PreviewPortalProject,
+  PreviewPortalReferenceSlot,
+  PreviewPortalSoundtrack,
+  PreviewPortalSoundtrackCandidate,
+  PreviewPortalStatus,
+  PreviewPortalStoryboard,
+  PreviewPortalTemplateId,
+} from './types.js';
+
+interface ScenePacketInfo {
+  renderPrompt?: string;
+  referenceSlots: PreviewPortalReferenceSlot[];
+}
+
+export interface DiscoverPreviewPortalProjectOptions {
+  root: string;
+  projectSlug: string;
+  runId?: string;
+  client?: string | null;
+  template?: PreviewPortalTemplateId;
+  status?: PreviewPortalStatus;
+}
+
+export interface DiscoverPreviewPortalPortfolioOptions {
+  root: string;
+  client?: string | null;
+  limit?: number;
+}
+
+export async function discoverPreviewPortalProject(
+  options: DiscoverPreviewPortalProjectOptions,
+): Promise<PreviewPortalProject> {
+  const projectDir = join(options.root, 'projects', options.projectSlug);
+  const manifest = await readProjectJson(projectDir);
+  const template = options.template ?? templateFromManifest(manifest) ?? 'generic-video';
+  const now = new Date().toISOString();
+  const assets = await discoverAssets(projectDir);
+  const status = options.status ?? 'draft';
+  const summary = stringValue(manifest?.summary) ?? stringValue(manifest?.intent);
+  const client = options.client ?? clientFromManifest(manifest);
+  const soundtrack = await discoverSoundtrack(projectDir, manifest, assets);
+  const brief = await discoverBrief(projectDir);
+  const storyboard = await discoverStoryboard(projectDir);
+  const brand = await discoverBrand(options.root, options.projectSlug, projectDir);
+  const cast = await discoverCast(projectDir, assets);
+  return {
+    client,
+    slug: options.projectSlug,
+    title: stringValue(manifest?.title) ?? titleFromSlug(options.projectSlug),
+    template,
+    status,
+    projectDir,
+    run: {
+      runId: options.runId ?? 'run-001',
+      label: options.runId ?? 'run-001',
+      status,
+      createdAt: now,
+      updatedAt: now,
+      publishedAt: null,
+      approvedAt: null,
+      declinedAt: null,
+    },
+    ...(summary ? { summary } : {}),
+    ...(brand ? { brand } : {}),
+    ...(cast ? { cast } : {}),
+    ...(brief ? { brief } : {}),
+    ...(storyboard ? { storyboard } : {}),
+    assets,
+    cards: buildCards(assets),
+    ...(soundtrack ? { soundtrack } : {}),
+  };
+}
+
+/**
+ * Surface the production's locked cast — registered Flow Characters
+ * (`artifacts/flow-characters.json`) and reference characters
+ * (`characters/characters.json`) — so the portal can show "who is identity-locked
+ * across every shot". Each member is matched, best-effort, to a still already
+ * discovered in the project (by name slug) so a face renders where one exists;
+ * otherwise the Cast card falls back to a monogram. Returns undefined when no
+ * cast is registered (the section then does not render).
+ */
+async function discoverCast(
+  projectDir: string,
+  assets: PreviewPortalAsset[],
+): Promise<PreviewPortalCastMember[] | undefined> {
+  const members: PreviewPortalCastMember[] = [];
+  const seen = new Set<string>();
+  const add = (name: string, source: PreviewPortalCastMember['source'], ref?: string) => {
+    const trimmed = name.trim();
+    if (!trimmed || seen.has(trimmed.toLowerCase())) return;
+    seen.add(trimmed.toLowerCase());
+    const stillPath = matchCastStill(trimmed, assets);
+    members.push({
+      name: trimmed,
+      source,
+      ...(ref ? { ref } : {}),
+      ...(stillPath ? { stillPath } : {}),
+      ...(/master/i.test(trimmed) ? { role: 'product master' } : {}),
+    });
+  };
+
+  const flowPath = join(projectDir, 'artifacts', 'flow-characters.json');
+  if (existsSync(flowPath)) {
+    try {
+      const parsed = JSON.parse(await readFile(flowPath, 'utf-8')) as {
+        characters?: Array<{ name?: unknown; entityId?: unknown }>;
+      };
+      for (const c of parsed.characters ?? []) {
+        if (typeof c?.name === 'string') {
+          add(c.name, 'flow-character', typeof c.entityId === 'string' ? c.entityId : undefined);
+        }
+      }
+    } catch {
+      // malformed flow-characters.json — skip the Flow cast, still try characters.json
+    }
+  }
+
+  const charPath = join(projectDir, 'characters', 'characters.json');
+  if (existsSync(charPath)) {
+    try {
+      const parsed = JSON.parse(await readFile(charPath, 'utf-8')) as {
+        characters?: Array<{ name?: unknown }>;
+      };
+      for (const c of parsed.characters ?? []) {
+        if (typeof c?.name === 'string') add(c.name, 'character');
+      }
+    } catch {
+      // doctor reports malformed characters.json separately
+    }
+  }
+
+  return members.length ? members : undefined;
+}
+
+/** Best-effort still match: a discovered image whose path slug contains the
+ * character's name slug. Searches the cast-likely sections only (characters,
+ * images, keyframes). Returns undefined when nothing matches (monogram card). */
+function matchCastStill(name: string, assets: PreviewPortalAsset[]): string | undefined {
+  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '');
+  if (!slug) return undefined;
+  const hit = assets.find(
+    (asset) =>
+      asset.kind === 'image' &&
+      (asset.section === 'characters' || asset.section === 'images' || asset.section === 'keyframes') &&
+      asset.path.toLowerCase().replace(/[^a-z0-9]+/g, '').includes(slug),
+  );
+  return hit?.path;
+}
+
+/**
+ * Surface the client's locked brand system for portal theming: the
+ * brand-definition artifact (via the canonical reader) plus a probed logo at
+ * assets/brand/logo.*. Returns undefined when the artifact is absent or
+ * malformed — the portal then renders its stock theme, visually unchanged.
+ */
+async function discoverBrand(
+  root: string,
+  projectSlug: string,
+  projectDir: string,
+): Promise<PreviewPortalBrand | undefined> {
+  let artifact;
+  try {
+    artifact = await readBrandDefinition(root, projectSlug);
+  } catch {
+    return undefined;
+  }
+  if (!artifact || typeof artifact.brandName !== 'string' || !artifact.brandName.trim()) return undefined;
+  const palette = Object.entries(artifact.palette ?? {})
+    .filter(([, color]) => color && typeof color.hex === 'string' && /^#[0-9a-fA-F]{6}$/.test(color.hex))
+    .map(([role, color]) => ({ role, hex: color.hex, ...(color.name ? { name: color.name } : {}) }));
+  const typography = (Array.isArray(artifact.typography) ? artifact.typography : [])
+    .filter((t) => t && typeof t.level === 'string' && typeof t.font === 'string')
+    .map((t) => ({ level: t.level, font: t.font, weight: typeof t.weight === 'string' ? t.weight : '' }));
+  let logoPath: string | undefined;
+  for (const ext of ['svg', 'png', 'webp', 'jpg', 'jpeg']) {
+    const candidate = join(projectDir, 'assets', 'brand', `logo.${ext}`);
+    if (existsSync(candidate)) {
+      logoPath = `assets/brand/logo.${ext}`;
+      break;
+    }
+  }
+  const taglines = artifact.taglines && typeof artifact.taglines === 'object'
+    ? {
+        ...(artifact.taglines.functional ? { functional: artifact.taglines.functional } : {}),
+        ...(artifact.taglines.emotional ? { emotional: artifact.taglines.emotional } : {}),
+        ...(artifact.taglines.community ? { community: artifact.taglines.community } : {}),
+      }
+    : undefined;
+  return {
+    brandName: artifact.brandName.trim(),
+    ...(typeof artifact.positioning === 'string' && artifact.positioning.trim()
+      ? { positioning: artifact.positioning.trim() }
+      : {}),
+    ...(taglines && Object.keys(taglines).length ? { taglines } : {}),
+    palette,
+    typography,
+    ...(logoPath ? { logoPath } : {}),
+  };
+}
+
+/** Read the brief artifact subset rendered in the preview header. Returns
+ * undefined when absent or malformed (the portal index skips broken projects). */
+async function discoverBrief(projectDir: string): Promise<PreviewPortalBrief | undefined> {
+  const path = join(projectDir, 'artifacts', 'brief.json');
+  if (!existsSync(path)) return undefined;
+  try {
+    const brief = JSON.parse(await readFile(path, 'utf-8')) as { title?: unknown; intent?: unknown; metadata?: unknown };
+    if (typeof brief.title !== 'string' || typeof brief.intent !== 'string') return undefined;
+    return {
+      title: brief.title,
+      intent: brief.intent,
+      ...(brief.metadata && typeof brief.metadata === 'object'
+        ? { metadata: brief.metadata as PreviewPortalBrief['metadata'] }
+        : {}),
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+/** Read the storyboard scenes rendered as scene cards. Returns undefined when
+ * absent or malformed. */
+async function discoverStoryboard(projectDir: string): Promise<PreviewPortalStoryboard | undefined> {
+  const path = join(projectDir, 'artifacts', 'storyboard.json');
+  if (!existsSync(path)) return undefined;
+  // The resolved per-scene submit text and reference slots live in
+  // filmmaking-prompts.json (seedancePackets[].promptText / .references). Pair
+  // them onto each scene by sceneIndex so the preview can paint the exact
+  // provider input and the identity-lock status before any render spend.
+  const packets = await discoverScenePackets(projectDir);
+  try {
+    const parsed = JSON.parse(await readFile(path, 'utf-8')) as { scenes?: unknown };
+    if (!Array.isArray(parsed.scenes)) return undefined;
+    const scenes = parsed.scenes
+      .filter((scene): scene is Record<string, unknown> => !!scene && typeof scene === 'object')
+      .map((scene, index) => {
+        const sceneIndex = typeof scene.sceneIndex === 'number' ? scene.sceneIndex : index;
+        const packet = packets.get(sceneIndex);
+        return {
+          sceneIndex,
+          description: typeof scene.description === 'string' ? scene.description : '',
+          ...(Array.isArray(scene.characters)
+            ? { characters: scene.characters.filter((c): c is string => typeof c === 'string') }
+            : {}),
+          ...(scene.scenePrompt && typeof scene.scenePrompt === 'object'
+            ? { scenePrompt: scene.scenePrompt as PreviewPortalStoryboard['scenes'][number]['scenePrompt'] }
+            : {}),
+          ...(packet?.renderPrompt ? { renderPrompt: packet.renderPrompt } : {}),
+          ...(packet && packet.referenceSlots.length ? { referenceSlots: packet.referenceSlots } : {}),
+          ...(typeof scene.colorState === 'string' && scene.colorState ? { colorState: scene.colorState } : {}),
+          ...(typeof scene.dialogue === 'string' ? { dialogue: scene.dialogue } : {}),
+          ...(typeof scene.durationSeconds === 'number' ? { durationSeconds: scene.durationSeconds } : {}),
+        };
+      });
+    return { scenes };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Read `artifacts/filmmaking-prompts.json` and return a sceneIndex → packet-info
+ * map carrying the resolved 10-block submit prompt (`seedancePackets[].promptText`)
+ * and the scene's reference slots (`seedancePackets[].references`). The submit
+ * prompt is the convergence point where the multi-shot plan, the Joey
+ * cinematography registers, and the story-bible continuity all land; the
+ * reference slots are the identity-lock contract (which avatar locks which scene,
+ * ready vs pending). Character-sheet slots are enriched with the bound `Asset://`
+ * URI from `seedance-assets.json` when registered. Returns an empty map when the
+ * artifact is absent or malformed (the contract block falls back gracefully). */
+async function discoverScenePackets(projectDir: string): Promise<Map<number, ScenePacketInfo>> {
+  const out = new Map<number, ScenePacketInfo>();
+  const path = join(projectDir, 'artifacts', 'filmmaking-prompts.json');
+  if (!existsSync(path)) return out;
+  const assetUris = await loadSeedanceAssetMap(projectDir);
+  try {
+    const parsed = JSON.parse(await readFile(path, 'utf-8')) as {
+      seedancePackets?: Array<{ sceneIndex?: unknown; promptText?: unknown; references?: unknown }>;
+    };
+    for (const packet of parsed.seedancePackets ?? []) {
+      if (typeof packet?.sceneIndex !== 'number' || out.has(packet.sceneIndex)) continue;
+      const renderPrompt = typeof packet.promptText === 'string' && packet.promptText.trim()
+        ? packet.promptText
+        : undefined;
+      const referenceSlots: PreviewPortalReferenceSlot[] = [];
+      for (const ref of Array.isArray(packet.references) ? packet.references : []) {
+        if (!ref || typeof ref !== 'object') continue;
+        const slot = ref as Record<string, unknown>;
+        if (typeof slot.slot !== 'string' || typeof slot.role !== 'string') continue;
+        const characterName = typeof slot.characterName === 'string' ? slot.characterName : undefined;
+        const assetUri = characterName ? assetUris.get(characterName) : undefined;
+        referenceSlots.push({
+          slot: slot.slot,
+          role: slot.role,
+          label: typeof slot.label === 'string' ? slot.label : slot.slot,
+          status: slot.status === 'ready' ? 'ready' : 'pending',
+          ...(typeof slot.path === 'string' ? { path: slot.path } : {}),
+          ...(characterName ? { characterName } : {}),
+          ...(assetUri ? { assetUri } : {}),
+        });
+      }
+      out.set(packet.sceneIndex, { ...(renderPrompt ? { renderPrompt } : {}), referenceSlots });
+    }
+  } catch {
+    return out;
+  }
+  return out;
+}
+
+/**
+ * Read `artifacts/seedance-assets.json` (the registered Asset Library avatars)
+ * into a character-name → `Asset://` URI map. Prefers the international-profile
+ * URI when present (the one Seedance moderation accepts globally). Returns an
+ * empty map when the artifact is absent — identity slots then render as a bound
+ * character name without an Asset URI (i.e. "pending registration"). */
+async function loadSeedanceAssetMap(projectDir: string): Promise<Map<string, string>> {
+  const out = new Map<string, string>();
+  const path = join(projectDir, 'artifacts', 'seedance-assets.json');
+  if (!existsSync(path)) return out;
+  try {
+    const parsed = JSON.parse(await readFile(path, 'utf-8')) as {
+      assets?: Array<{ name?: unknown; assetUri?: unknown; intlAssetUri?: unknown }>;
+    };
+    for (const asset of parsed.assets ?? []) {
+      if (typeof asset?.name !== 'string') continue;
+      const uri = typeof asset.intlAssetUri === 'string' && asset.intlAssetUri.trim()
+        ? asset.intlAssetUri
+        : typeof asset.assetUri === 'string' && asset.assetUri.trim()
+          ? asset.assetUri
+          : undefined;
+      if (uri) out.set(asset.name, uri);
+    }
+  } catch {
+    return out;
+  }
+  return out;
+}
+
+/**
+ * Discover the project soundtrack/score for the polished preview showcase.
+ * Preference order: an explicit `soundtrack`/`audio` manifest field that points
+ * at an existing project-local audio file, otherwise the first discovered audio
+ * asset. Returns undefined when no soundtrack exists (so the preview renders no
+ * `<audio>` element).
+ */
+async function discoverSoundtrack(
+  projectDir: string,
+  manifest: Record<string, unknown> | null,
+  assets: PreviewPortalAsset[],
+): Promise<PreviewPortalSoundtrack | undefined> {
+  const projectRoot = resolve(projectDir);
+
+  // 1. soundtrack.json A/B candidates (the music A/B layer). Renders one player
+  //    per candidate; the `selected` (or manifest-soundtrack-matching, or first)
+  //    candidate becomes the headline.
+  const fromArtifact = await discoverSoundtrackCandidates(projectRoot, manifest);
+  if (fromArtifact) return fromArtifact;
+
+  // 2. Legacy single soundtrack: explicit `soundtrack`/`audio` manifest field.
+  const manifestPath = stringValue(manifest?.soundtrack) ?? stringValue(manifest?.audio);
+  if (manifestPath && isAudioPath(manifestPath)) {
+    const localPath = resolveAssetPath(projectRoot, manifestPath);
+    if (localPath && existsSync(localPath)) {
+      const rel = relative(projectRoot, localPath).replaceAll('\\', '/');
+      return { path: rel, label: labelFromPath(rel) };
+    }
+  }
+
+  // 3. Fallback: first discovered audio asset.
+  const audioAsset = assets.find((asset) => asset.kind === 'audio' && isAudioPath(asset.path));
+  if (audioAsset) {
+    return { path: audioAsset.path, label: audioAsset.label };
+  }
+  return undefined;
+}
+
+/**
+ * Read `artifacts/soundtrack.json` (the A/B candidate artifact) and surface every
+ * candidate so a human can compare/pick in the preview. The headline is the
+ * `selected` candidate; absent a selection, the candidate whose path matches the
+ * manifest `soundtrack` field; else the first candidate. Returns undefined when
+ * the artifact is missing, malformed, or yields no on-disk audio candidate.
+ */
+async function discoverSoundtrackCandidates(
+  projectRoot: string,
+  manifest: Record<string, unknown> | null,
+): Promise<PreviewPortalSoundtrack | undefined> {
+  const path = join(projectRoot, 'artifacts', 'soundtrack.json');
+  if (!existsSync(path)) return undefined;
+  let parsed: {
+    candidates?: Array<{ backendId?: unknown; path?: unknown }>;
+    selected?: unknown;
+  };
+  try {
+    parsed = JSON.parse(await readFile(path, 'utf-8'));
+  } catch {
+    return undefined;
+  }
+  if (!Array.isArray(parsed.candidates)) return undefined;
+
+  const selectedId = stringValue(parsed.selected);
+  const manifestPath = stringValue(manifest?.soundtrack);
+  const candidates: PreviewPortalSoundtrackCandidate[] = [];
+  for (const raw of parsed.candidates) {
+    const backendId = stringValue(raw?.backendId);
+    const candPath = stringValue(raw?.path);
+    if (!backendId || !candPath || !isAudioPath(candPath)) continue;
+    const localPath = resolveAssetPath(projectRoot, candPath);
+    if (!localPath || !existsSync(localPath)) continue;
+    const rel = relative(projectRoot, localPath).replaceAll('\\', '/');
+    candidates.push({
+      backendId,
+      path: rel,
+      label: `${labelFromPath(rel)} · ${backendId}`,
+      selected: false,
+    });
+  }
+  if (candidates.length === 0) return undefined;
+
+  // Pick the headline: selected backend, else manifest-matching path, else first.
+  let headline =
+    (selectedId ? candidates.find((c) => c.backendId === selectedId) : undefined) ??
+    (manifestPath
+      ? (() => {
+          const abs = resolveAssetPath(projectRoot, manifestPath);
+          if (!abs) return undefined;
+          const rel = relative(projectRoot, abs).replaceAll('\\', '/');
+          return candidates.find((c) => c.path === rel);
+        })()
+      : undefined) ??
+    candidates[0];
+  headline = { ...headline, selected: true };
+  const withSelection = candidates.map((c) =>
+    c.backendId === headline.backendId && c.path === headline.path ? headline : c,
+  );
+
+  return {
+    path: headline.path,
+    label: headline.label,
+    candidates: withSelection,
+  };
+}
+
+function isAudioPath(path: string): boolean {
+  return /\.(mp3|m4a|wav|aac)$/i.test(path);
+}
+
+export async function discoverPreviewPortalPortfolio(
+  options: DiscoverPreviewPortalPortfolioOptions,
+): Promise<PreviewPortalProject[]> {
+  const projectsDir = join(options.root, 'projects');
+  if (!existsSync(projectsDir)) return [];
+  const entries = await readdir(projectsDir, { withFileTypes: true });
+  const projects: PreviewPortalProject[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name === 'clients') continue;
+    try {
+      const project = await discoverPreviewPortalProject({
+        root: options.root,
+        projectSlug: entry.name,
+      });
+      if (options.client && normalizeClient(project.client) !== normalizeClient(options.client)) continue;
+      projects.push(project);
+    } catch {
+      // A portfolio index should skip broken folders instead of blocking every other project.
+    }
+  }
+  return projects
+    .sort((a, b) => b.run.updatedAt.localeCompare(a.run.updatedAt) || a.title.localeCompare(b.title))
+    .slice(0, options.limit ?? Number.POSITIVE_INFINITY);
+}
+
+async function readProjectJson(projectDir: string): Promise<Record<string, unknown> | null> {
+  const path = join(projectDir, 'project.json');
+  if (!existsSync(path)) return null;
+  return JSON.parse(await readFile(path, 'utf-8')) as Record<string, unknown>;
+}
+
+async function discoverAssets(projectDir: string): Promise<PreviewPortalAsset[]> {
+  const dirs = [
+    'final', 'videos', 'images', 'characters', 'audio', 'prompts', 'variants',
+    // Production-sheet dirs: per-scene stills, character reference sheets, scene
+    // candidate sheets, and the story-sheet grid — all canonical output dirs the
+    // portal previously ignored.
+    'keyframes', 'reference-sheets', 'scene-candidates', 'story-sheets',
+  ];
+  const out: PreviewPortalAsset[] = [];
+  // Tracks the resolved absolute path of every emitted asset so the
+  // characters.json appender does not re-list a file already found on disk.
+  const seen = new Set<string>();
+  for (const dir of dirs) {
+    const absoluteDir = join(projectDir, dir);
+    if (!existsSync(absoluteDir)) continue;
+    for (const path of await listFiles(absoluteDir)) {
+      const info = await stat(path);
+      const rel = relative(projectDir, path).replaceAll('\\', '/');
+      out.push({
+        id: rel.replace(/[^a-zA-Z0-9]+/g, '-').replace(/^-|-$/g, ''),
+        path: rel,
+        kind: kindFromPath(rel),
+        label: labelFromPath(rel),
+        section: dir,
+        sizeBytes: info.size,
+        createdAt: info.mtime.toISOString(),
+        exists: true,
+      });
+      seen.add(resolve(path));
+    }
+  }
+  const generationInputs = await discoverGenerationInputAssets(projectDir);
+  for (const asset of generationInputs) seen.add(resolve(projectDir, asset.path));
+  out.push(...generationInputs);
+  out.push(...await discoverPromptPacketAssets(projectDir));
+  out.push(...await discoverCharacterReferenceAssets(projectDir, seen));
+  const sorted = out.sort((a, b) => a.path.localeCompare(b.path));
+  await annotateAssetOrientations(projectDir, sorted);
+  return sorted;
+}
+
+/**
+ * Bucket real pixel dimensions into a card orientation. Cards must follow the
+ * ASSET's aspect, not the project's: a 9:16 social deliverable inside a 16:9
+ * project still gets a portrait card (never letterboxed in a landscape box).
+ */
+export function classifyOrientation(
+  width?: number,
+  height?: number,
+): 'portrait' | 'square' | 'landscape' | undefined {
+  if (!width || !height || width <= 0 || height <= 0) return undefined;
+  const ratio = width / height;
+  if (ratio < 0.98) return 'portrait';
+  if (ratio <= 1.02) return 'square';
+  return 'landscape';
+}
+
+/**
+ * Best-effort per-asset dimension probe: header parse for stills, ffprobe for
+ * video (env-overridable via VCLAW_FFPROBE_BIN inside probeMedia). Failures
+ * (missing ffprobe, truncated files) leave the fields unset so the card falls
+ * back to the project-level default shape.
+ */
+async function annotateAssetOrientations(projectDir: string, assets: PreviewPortalAsset[]): Promise<void> {
+  await Promise.all(assets.map(async (asset) => {
+    if (asset.kind !== 'video' && asset.kind !== 'image') return;
+    const absolute = isAbsolute(asset.path) ? asset.path : join(projectDir, asset.path);
+    if (!existsSync(absolute)) return;
+    try {
+      const dims = asset.kind === 'image'
+        ? await readImageDimensions(absolute)
+        : await probeMedia(absolute);
+      const orientation = classifyOrientation(dims?.width, dims?.height);
+      if (!orientation) return;
+      asset.width = dims?.width;
+      asset.height = dims?.height;
+      asset.orientation = orientation;
+    } catch {
+      // best-effort only — unprobed assets keep the default card shape
+    }
+  }));
+}
+
+/**
+ * Surface character reference images registered in characters/characters.json
+ * (via `vclaw video character-add --ref`) that were not already found by the
+ * directory scan. Deduped against `seenAbsolutePaths` so a ref physically
+ * inside characters/ is listed once. URI refs (gobananas://) and refs that
+ * escape the project or are missing are skipped (not portably renderable);
+ * the doctor surfaces those separately.
+ */
+async function discoverCharacterReferenceAssets(
+  projectDir: string,
+  seenAbsolutePaths: Set<string>,
+): Promise<PreviewPortalAsset[]> {
+  const charactersPath = join(projectDir, 'characters', 'characters.json');
+  if (!existsSync(charactersPath)) return [];
+  let store: { characters?: Array<{ name?: unknown; referenceAssets?: unknown }> };
+  try {
+    store = JSON.parse(await readFile(charactersPath, 'utf-8'));
+  } catch {
+    return []; // doctor reports malformed characters.json separately
+  }
+  const projectRoot = resolve(projectDir);
+  const out: PreviewPortalAsset[] = [];
+  for (const character of store.characters ?? []) {
+    const name = typeof character?.name === 'string' ? character.name : undefined;
+    const refs = Array.isArray(character?.referenceAssets) ? character.referenceAssets : [];
+    for (const ref of refs) {
+      if (typeof ref !== 'string' || !ref.trim()) continue;
+      if (/^[a-z][a-z0-9+.-]*:\/\//i.test(ref)) continue; // gobananas://, http(s):// — not renderable
+      const localPath = resolveAssetPath(projectRoot, ref);
+      if (!localPath || !existsSync(localPath)) continue;
+      if (seenAbsolutePaths.has(localPath)) continue;
+      const rel = relative(projectRoot, localPath).replaceAll('\\', '/');
+      if (kindFromPath(rel) !== 'image') continue;
+      const info = await stat(localPath);
+      out.push({
+        id: `character-ref-${rel.replace(/[^a-zA-Z0-9]+/g, '-').replace(/^-|-$/g, '')}`,
+        path: rel,
+        kind: 'image',
+        label: name ? `${name} reference` : labelFromPath(rel),
+        section: 'characters',
+        sizeBytes: info.size,
+        createdAt: info.mtime.toISOString(),
+        exists: true,
+      });
+      seenAbsolutePaths.add(localPath);
+    }
+  }
+  return out;
+}
+
+async function discoverPromptPacketAssets(projectDir: string): Promise<PreviewPortalAsset[]> {
+  const path = join(projectDir, 'artifacts', 'filmmaking-prompts.json');
+  if (!existsSync(path)) return [];
+  const info = await stat(path);
+  return [{
+    id: 'filmmaking-prompts',
+    path: 'artifacts/filmmaking-prompts.json',
+    kind: 'json',
+    label: 'Filmmaking Prompt Packet',
+    section: 'prompt-packets',
+    sizeBytes: info.size,
+    createdAt: info.mtime.toISOString(),
+    exists: true,
+  }];
+}
+
+async function discoverGenerationInputAssets(projectDir: string): Promise<PreviewPortalAsset[]> {
+  const manifestPath = join(projectDir, 'artifacts', 'asset-manifest.json');
+  if (!existsSync(manifestPath)) return [];
+  const manifest = JSON.parse(await readFile(manifestPath, 'utf-8')) as {
+    assets?: Array<{
+      id?: unknown;
+      kind?: unknown;
+      path?: unknown;
+      sceneIndex?: unknown;
+      backend?: unknown;
+    }>;
+  };
+  const projectRoot = resolve(projectDir);
+  const out: PreviewPortalAsset[] = [];
+  for (const asset of manifest.assets ?? []) {
+    if (asset.kind !== 'image' || typeof asset.path !== 'string' || !asset.path.trim()) continue;
+    const localPath = resolveAssetPath(projectRoot, asset.path);
+    if (!localPath || !existsSync(localPath)) continue;
+    const rel = relative(projectRoot, localPath).replaceAll('\\', '/');
+    const info = await stat(localPath);
+    const sceneLabel = typeof asset.sceneIndex === 'number' ? `Scene ${asset.sceneIndex}` : 'Scene input';
+    const backend = typeof asset.backend === 'string' && asset.backend.trim() ? asset.backend.trim() : null;
+    out.push({
+      id: `generation-inputs-${String(asset.id ?? rel).replace(/[^a-zA-Z0-9]+/g, '-').replace(/^-|-$/g, '')}`,
+      path: rel,
+      kind: 'image',
+      label: backend?.includes('seedance')
+        ? `${sceneLabel} · Seedance input`
+        : `${sceneLabel} · Generation input`,
+      section: 'generation-inputs',
+      sizeBytes: info.size,
+      createdAt: info.mtime.toISOString(),
+      exists: true,
+      ...(typeof asset.sceneIndex === 'number' ? { sceneIndex: asset.sceneIndex } : {}),
+    });
+  }
+  return out;
+}
+
+function resolveAssetPath(projectRoot: string, value: string): string | null {
+  const projectSlug = basename(projectRoot);
+  const normalized = value.replaceAll('\\', '/');
+  const projectScopedPrefix = `projects/${projectSlug}/`;
+  const localValue = normalized.startsWith(projectScopedPrefix)
+    ? normalized.slice(projectScopedPrefix.length)
+    : normalized;
+  const path = isAbsolute(localValue) ? resolve(localValue) : resolve(projectRoot, localValue);
+  const rel = relative(projectRoot, path);
+  if (rel.startsWith('..') || rel === '' || rel.startsWith('/')) return null;
+  return path;
+}
+
+async function listFiles(dir: string): Promise<string[]> {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const out: string[] = [];
+  for (const entry of entries) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...await listFiles(path));
+    if (entry.isFile()) out.push(path);
+  }
+  return out;
+}
+
+function buildCards(assets: PreviewPortalAsset[]): PreviewPortalCard[] {
+  const finals = assets.filter((asset) => asset.section === 'final' && asset.kind === 'video');
+  const scenes = assets.filter((asset) => asset.section === 'videos' && asset.kind === 'video');
+  const images = assets.filter((asset) => asset.section === 'images' && asset.kind === 'image');
+  return [
+    ...finals.map((asset, index) => ({
+      id: asset.id,
+      kind: 'final' as const,
+      title: index === 0 ? 'Final cut' : labelFromPath(asset.path),
+      subtitle: asset.path,
+      assetIds: [asset.id],
+      reviewable: true,
+    })),
+    ...scenes.map((asset) => ({
+      id: asset.id,
+      kind: 'scene' as const,
+      title: labelFromPath(asset.path),
+      subtitle: asset.path,
+      assetIds: [asset.id],
+      reviewable: true,
+    })),
+    ...images.map((asset) => ({
+      id: asset.id,
+      kind: 'asset' as const,
+      title: labelFromPath(asset.path),
+      subtitle: asset.path,
+      assetIds: [asset.id],
+      reviewable: false,
+    })),
+  ];
+}
+
+function kindFromPath(path: string): PreviewPortalAsset['kind'] {
+  const lower = path.toLowerCase();
+  if (/\.(jpg|jpeg|png|webp|gif|avif)$/.test(lower)) return 'image';
+  if (/\.(mp4|mov|webm)$/.test(lower)) return 'video';
+  if (/\.(mp3|wav|m4a|aac)$/.test(lower)) return 'audio';
+  if (/\.html$/.test(lower)) return 'html';
+  if (/\.json$/.test(lower)) return 'json';
+  if (/\.(txt|md)$/.test(lower)) return 'text';
+  return 'other';
+}
+
+function templateFromManifest(manifest: Record<string, unknown> | null): PreviewPortalTemplateId | null {
+  const raw = stringValue(manifest?.template) ?? stringValue(manifest?.previewTemplate);
+  if (!raw) return null;
+  // Validate against the template registry (single source of truth) so a newly
+  // added template is recognized here automatically instead of being silently
+  // downgraded to 'generic-video' by a stale hardcoded allowlist.
+  if (Object.prototype.hasOwnProperty.call(PREVIEW_PORTAL_TEMPLATE_REGISTRY, raw)) {
+    return raw as PreviewPortalTemplateId;
+  }
+  return null;
+}
+
+function clientFromManifest(manifest: Record<string, unknown> | null): string | null {
+  return stringValue(manifest?.client)
+    ?? stringValue(manifest?.clientName)
+    ?? stringValue(manifest?.owner)
+    ?? null;
+}
+
+function normalizeClient(value: string | null | undefined): string {
+  return (value ?? '').trim().toLowerCase();
+}
+
+function titleFromSlug(slug: string): string {
+  return slug
+    .split('-')
+    .filter(Boolean)
+    .map((part) => `${part[0]?.toUpperCase() ?? ''}${part.slice(1)}`)
+    .join(' ');
+}
+
+function labelFromPath(path: string): string {
+  const name = path.split('/').pop() ?? path;
+  return name.replace(/\.[^.]+$/, '').replace(/[_-]+/g, ' ');
+}
+
+function stringValue(value: unknown): string | null {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}