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,
  PreviewPortalVoiceClone,
} 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;
  /**
   * Also discover the live-run state (per-generation status + diff-vs-contract
   * alarm + event log + show-bible nav + spend) onto `project.runState`. Off by
   * default because it is the heavier path (cost estimate, telemetry, contract
   * diff) — only the `run` surface reads it; review/preview/compare skip it.
   */
  withRunState?: boolean;
}

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);
  const voiceClones = await discoverVoiceClones(projectDir);
  const project: PreviewPortalProject = {
    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 } : {}),
    ...(voiceClones && voiceClones.length ? { voiceClones } : {}),
  };
  if (options.withRunState) {
    const { discoverRunState } = await import('./run-discovery.js');
    project.runState = await discoverRunState(options.root, options.projectSlug, projectDir, project);
  }
  return project;
}

/**
 * Read `artifacts/voice-clones.json` (the cloned-voice references — the
 * black-frame-with-audio trick) into the per-character voice map the per-scene
 * review contract renders. Mirrors `discoverSoundtrack`'s graceful absence
 * handling: returns undefined when the artifact is absent or unparseable, so a
 * project without it renders byte-identically to today. The playable `src` is
 * the durable hosted URL when present, else the local clip path; the label is
 * built from name/character/description.
 */
async function discoverVoiceClones(
  projectDir: string,
): Promise<PreviewPortalVoiceClone[] | undefined> {
  const path = join(projectDir, 'artifacts', 'voice-clones.json');
  if (!existsSync(path)) return undefined;
  let parsed: {
    voices?: Array<{
      name?: unknown;
      character?: unknown;
      clipPath?: unknown;
      hostedUrl?: unknown;
      description?: unknown;
      durationMs?: unknown;
    }>;
  };
  try {
    parsed = JSON.parse(await readFile(path, 'utf-8'));
  } catch {
    return undefined;
  }
  if (!Array.isArray(parsed.voices)) return undefined;
  const out: PreviewPortalVoiceClone[] = [];
  for (const voice of parsed.voices) {
    const character = stringValue(voice?.character);
    const src = stringValue(voice?.hostedUrl) ?? stringValue(voice?.clipPath);
    if (!character || !src) continue; // a voice with no cast character can't bind to a scene
    const name = stringValue(voice?.name);
    const description = stringValue(voice?.description);
    const labelParts = [name ?? character];
    if (name && name.toLowerCase() !== character.toLowerCase()) labelParts.push(character);
    if (description) labelParts.push(description);
    out.push({
      character,
      label: labelParts.join(' · '),
      src,
      ...(typeof voice?.durationMs === 'number' && voice.durationMs > 0
        ? { durationSeconds: Math.round(voice.durationMs / 100) / 10 }
        : {}),
    });
  }
  return out.length ? out : undefined;
}

/**
 * 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);
        // The rendered per-scene clip lives at `outputs/scene-<sceneIndex>.mp4`
        // (0-based). Carry a project-relative `clipPath` so the storyboard card
        // can offer an inline Image/Video toggle; absent when not yet rendered.
        const clipRel = `outputs/scene-${sceneIndex}.mp4`;
        const clipExists = existsSync(join(projectDir, clipRel));
        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 } : {}),
          ...(clipExists ? { clipPath: clipRel } : {}),
        };
      });
    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;
}