import type { PreviewPortalAsset, PreviewPortalIndexRenderOptions, PreviewPortalProject, PreviewPortalRenderOptions, PreviewPortalSurface, PreviewPortalTemplate } from './types.js';
import { PORTAL_CLIENT_JS, PORTAL_CSS, PORTAL_EDITOR_JS, PORTAL_JS, PORTAL_REVIEW_TABS_JS } from './shared-assets.js';
import { resolvePreviewPortalTemplate } from './templates.js';
// Phase 3d: the escape/aspect/date primitives, the scene contract, the run dashboard and the brand theming live in their own modules; render.ts keeps the surface router and the shared sections.
import { mediaAspectAttrs, slugify, aspectForProject, fmtDate, esc, escAttr } from './render-primitives.js';
import { renderSceneContract } from './render-scene-contract.js';
import { renderRunPortalHtml } from './render-run.js';
import { renderBrandTheme, renderBrandBar, renderHeroTagline, renderStatusChip, renderBrandBook } from './render-brand.js';

export function renderPreviewPortalHtml(options: PreviewPortalRenderOptions): string {
  if (options.surface === 'compare') {
    return renderComparePortalHtml(options);
  }
  if (options.surface === 'run') {
    return renderRunPortalHtml(options);
  }
  const mode = modeForSurface(options.surface);
  const { project } = options;
  const template = resolvePreviewPortalTemplate(project.template);
  // Size the media cards + hero to the project's aspect ratio (CSS keys off this
  // attribute) so vertical 9:16 clips render portrait, not letterboxed landscape.
  const aspect = aspectForProject(project);
  const final = project.assets.find((asset) => asset.section === 'final' && asset.kind === 'video');
  const stats = [
    [project.run.runId, 'run'],
    [template.name, 'template'],
    [String(project.assets.filter((asset) => asset.kind === 'video').length), 'videos'],
    [String(project.assets.filter((asset) => asset.kind === 'image').length), 'images'],
  ];
  const review = isReviewSurface(options.surface);
  const reviewModeAttr = review ? ` data-review-mode="${options.surface === 'client-review' ? 'client' : 'editor'}"` : '';
  const sections = `${final ? renderHeroVideo(final, template) : ''}${renderTemplateSections(project, template, options.surface)}${options.surface === 'preview' ? renderBrandBook(project) : ''}`;
  // Review surface = one feedback page with Decide|Compare tabs + an editor↔client
  // mode toggle. Preview stays a clean, controls-free deliverable.
  const content = review
    ? `${renderReviewBar(options.surface)}<div class="tab-panel" data-tab="decide">${sections}</div><div class="tab-panel" data-tab="compare" hidden>${renderCompareTab(project)}</div>`
    : sections;
  return `<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="icon" href="data:,">
<title>${esc(project.title)}</title>
<style>${PORTAL_CSS}</style>${renderBrandTheme(project, options.surface)}
</head>
<body data-mode="${mode}" data-aspect="${esc(aspect)}"${reviewModeAttr}${project.hasQcReview ? ' data-qc="1"' : ''}${project.hasSyncReview ? ' data-sync="1"' : ''}>
${options.surface === 'preview' ? '<div class="grain" aria-hidden="true"></div>' : ''}<nav class="toc" id="toc" aria-label="Sections"></nav>
<header class="hero">
  ${renderBrandBar(project, options.surface)}<div class="eyebrow">${labelForSurface(options.surface)} · ${esc(template.heroLabel)}${renderStatusChip(project, options.surface)}</div>
  <h1>${esc(project.title)}</h1>
  ${renderHeroTagline(project, options.surface)}${project.summary ? `<p class="sub">${esc(project.summary)}</p>` : ''}
  <div class="stats">${stats.map(([value, label]) => `<div class="stat"><div class="v">${esc(value)}</div><div class="l">${esc(label)}</div></div>`).join('')}</div>
  ${renderSoundtrackPlayer(options.surface, project)}
</header>
${options.surface === 'preview' ? renderFilterChips() : ''}${content}
${renderHud(options.surface)}
${renderShortcutsHelp()}
<footer>${project.brand ? `${esc(project.brand.brandName)} · produced with videoclaw · ` : 'Generated by videoclaw · '}${esc(project.slug)} · ${esc(fmtDate(project.run.updatedAt))}</footer>
<script>${PORTAL_JS}${scriptForSurface(options.surface)}</script>
</body>
</html>
`;
}

/** The feedback "family" — all render the single tabbed Review surface. */
function isReviewSurface(surface: PreviewPortalSurface): boolean {
  return surface === 'edit' || surface === 'review' || surface === 'client-review';
}

/** Tab bar (Decide | Compare) + editor↔client mode toggle for the Review surface. */
function renderReviewBar(surface: PreviewPortalSurface): string {
  const client = surface === 'client-review';
  return `<div class="review-bar">
  <button type="button" class="review-tab" data-tab="decide" aria-selected="true">Decide</button>
  <button type="button" class="review-tab" data-tab="compare" aria-selected="false">Compare</button>
  <div class="review-mode"><span>Feedback as</span>
    <button type="button" data-mode="editor" aria-pressed="${client ? 'false' : 'true'}">Me ↔ Claude</button>
    <button type="button" data-mode="client" aria-pressed="${client ? 'true' : 'false'}">Client</button>
  </div>
</div>`;
}

/** The Compare tab: run/version comparison for this project (empty-state friendly). */
function renderCompareTab(project: PreviewPortalProject): string {
  return `<section id="compare" data-toc="Compare">
  <div class="section-head"><h2>Compare</h2><div class="section-title">Run Comparison</div><div class="section-sub">Compare finals across this project's runs.</div></div>
  <div class="grid">${renderCompareCard(project.projectDir, project)}</div>
</section>`;
}

export function renderPreviewPortalIndexHtml(options: PreviewPortalIndexRenderOptions): string {
  const generatedAt = options.generatedAt ?? new Date().toISOString();
  const title = options.title ?? (options.client ? `${options.client} Review Index` : 'Videoclaw Review Index');
  const stats = [
    [String(options.projects.length), 'projects'],
    [String(options.projects.filter((project) => project.status === 'published').length), 'published'],
    [String(options.projects.filter((project) => project.status.includes('review')).length), 'in review'],
    [String(options.projects.reduce((sum, project) => sum + project.assets.length, 0)), 'assets'],
  ];
  return `<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="icon" href="data:,">
<title>${esc(title)}</title>
<style>${PORTAL_CSS}</style>
</head>
<body data-mode="preview">
<nav class="toc" id="toc" aria-label="Sections"></nav>
<header class="hero">
  <div class="eyebrow">client portal · ${options.client ? esc(options.client) : 'all clients'}</div>
  <h1>${esc(title)}</h1>
  <p class="sub">Review, compare, and deliver generated video projects from one consistent index.</p>
  <div class="stats">${stats.map(([value, label]) => `<div class="stat"><div class="v">${esc(value)}</div><div class="l">${esc(label)}</div></div>`).join('')}</div>
</header>
<section id="projects" data-toc="Projects">
  <div class="section-head"><h2>Projects</h2><div class="section-title">Project Library</div><div class="section-sub">${options.projects.length} project${options.projects.length === 1 ? '' : 's'} available.</div></div>
  <div class="grid">
    ${options.projects.map((project) => renderProjectIndexCard(project, {
      linkPrefix: options.linkPrefix ?? '',
      linkMode: options.linkMode ?? 'local',
      client: options.client ?? null,
    })).join('') || '<div class="card"><div class="meta"><div class="title">No projects found</div><div class="who">Generate a project portal first, then rebuild this index.</div></div></div>'}
  </div>
</section>
<footer>Generated by videoclaw · ${esc(generatedAt)}</footer>
<script>${PORTAL_JS}</script>
</body>
</html>
`;
}

function renderComparePortalHtml(options: PreviewPortalRenderOptions): string {
  const projects = options.compareProjects?.length ? options.compareProjects : [options.project];
  const title = `${options.project.title} Compare`;
  const stats = [
    [String(projects.length), 'versions'],
    [String(projects.filter((project) => project.assets.some((asset) => asset.section === 'final' && asset.kind === 'video')).length), 'finals'],
    [String(projects.reduce((sum, project) => sum + project.assets.filter((asset) => asset.kind === 'video').length, 0)), 'videos'],
    [String(projects.reduce((sum, project) => sum + project.assets.filter((asset) => asset.kind === 'image').length, 0)), 'images'],
  ];
  return `<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="icon" href="data:,">
<title>${esc(title)}</title>
<style>${PORTAL_CSS}</style>
</head>
<body data-mode="compare">
<nav class="toc" id="toc" aria-label="Sections"></nav>
<header class="hero">
  <div class="eyebrow">compare · ${esc(options.project.template)}</div>
  <h1>${esc(title)}</h1>
  ${options.project.summary ? `<p class="sub">${esc(options.project.summary)}</p>` : ''}
  <div class="stats">${stats.map(([value, label]) => `<div class="stat"><div class="v">${esc(value)}</div><div class="l">${esc(label)}</div></div>`).join('')}</div>
</header>
<section id="versions" data-toc="Versions">
  <div class="section-head"><h2>Versions</h2><div class="section-title">Run Comparison</div><div class="section-sub">Compare finals, run metadata, and links for each generated version.</div></div>
  <div class="grid">
    ${projects.map((project) => renderCompareCard(options.project.projectDir, project)).join('')}
  </div>
</section>
<footer>Generated by videoclaw · ${esc(options.project.slug)} · ${esc(fmtDate(options.project.run.updatedAt))}</footer>
<script>${PORTAL_JS}</script>
</body>
</html>
`;
}

function renderSoundtrackPlayer(surface: PreviewPortalSurface, project: PreviewPortalProject): string {
  // Soundtrack player is part of the polished final showcase only. When no
  // soundtrack was discovered, emit nothing (no broken/empty <audio> element).
  if (surface !== 'preview' || !project.soundtrack) return '';
  const { path, label, candidates } = project.soundtrack;

  // A/B candidates: render one labelled player per backend so a human can
  // compare/pick. The selected candidate is flagged as the headline.
  if (candidates && candidates.length > 1) {
    const rows = candidates
      .map(
        (c) =>
          `<div class="soundtrack-player">
  <span class="soundtrack-label">${esc(c.label)}${c.selected ? ' · selected' : ''}</span>
  <audio controls preload="none" data-downloadable src="${escAttr(c.path)}"></audio>
</div>`,
      )
      .join('\n');
    return rows;
  }

  return `<div class="soundtrack-player">
  <span class="soundtrack-label">${esc(label)}</span>
  <audio controls preload="none" data-downloadable src="${escAttr(path)}"></audio>
</div>`;
}

function renderHeroVideo(asset: PreviewPortalAsset, template: PreviewPortalTemplate): string {
  return `<div class="hero-video">
  <video${mediaAspectAttrs(asset)} controls preload="metadata" playsinline data-downloadable src="${escAttr(asset.path)}"></video>
  <div class="final-meta"><span class="num">${esc(template.primaryAssetLabel)}</span><span>${esc(asset.path)}</span></div>
</div>`;
}

function renderProjectIndexCard(
  project: PreviewPortalProject,
  options: { linkPrefix: string; linkMode: 'local' | 'published-run'; client?: string | null },
): string {
  const final = project.assets.find((asset) => asset.section === 'final' && asset.kind === 'video');
  const poster = project.assets.find((asset) => asset.kind === 'image');
  const base = projectIndexBase(project, options);
  const media = final
    ? `<video${mediaAspectAttrs(final)} controls preload="metadata" data-downloadable src="${escAttr(base)}/${escAttr(final.path)}"></video>`
    : poster
      ? `<img${mediaAspectAttrs(poster)} data-downloadable data-lightbox-group="projects" data-lb-caption="${escAttr(project.title)}" src="${escAttr(base)}/${escAttr(poster.path)}" alt="${escAttr(project.title)}">`
      : '';
  return `<div class="card" data-card-kind="project" data-card-id="${escAttr(project.slug)}">
    ${media}
    <div class="meta"><div class="num">${esc(project.status)}</div><div class="title">${esc(project.title)}</div><div class="who">${esc(project.slug)} · ${esc(project.template)} · ${esc(fmtDate(project.run.updatedAt))}</div>
      <div class="who"><a href="${escAttr(base)}/review.html">Review</a> · <a href="${escAttr(base)}/preview.html">Preview</a></div>
    </div>
  </div>`;
}

function projectIndexBase(
  project: PreviewPortalProject,
  options: { linkPrefix: string; linkMode: 'local' | 'published-run'; client?: string | null },
): string {
  if (options.linkMode === 'local') return `${options.linkPrefix}${project.slug}`;
  const runPath = `${project.slug}/runs/${project.run.runId}`;
  if (options.client) return `${options.linkPrefix}${runPath}`;
  return `${options.linkPrefix}clients/${slugify(project.client ?? 'unknown')}/${runPath}`;
}

function renderCompareCard(baseProjectDir: string, project: PreviewPortalProject): string {
  const final = project.assets.find((asset) => asset.section === 'final' && asset.kind === 'video');
  const prefix = relativePrefix(baseProjectDir, project.projectDir);
  const media = final
    ? `<video${mediaAspectAttrs(final)} controls preload="metadata" data-downloadable src="${escAttr(prefix)}${escAttr(final.path)}"></video>`
    : '<div class="meta"><code>No final video discovered</code></div>';
  return `<div class="card" data-card-kind="run" data-card-id="${escAttr(project.slug)}-${escAttr(project.run.runId)}">
    ${media}
    <div class="meta"><div class="num">${esc(project.run.status)}</div><div class="title">${esc(project.title)}</div><div class="who">${esc(project.slug)} · ${esc(project.run.runId)} · ${esc(project.template)}</div>
      <div class="who">Updated ${esc(fmtDate(project.run.updatedAt))}</div>
      <div class="who"><a href="${escAttr(prefix)}review.html">Review</a> · <a href="${escAttr(prefix)}preview.html">Preview</a></div>
    </div>
  </div>`;
}

function relativePrefix(baseProjectDir: string, targetProjectDir: string): string {
  if (baseProjectDir === targetProjectDir) return '';
  const base = baseProjectDir.split('/').filter(Boolean);
  const target = targetProjectDir.split('/').filter(Boolean);
  while (base.length && target.length && base[0] === target[0]) {
    base.shift();
    target.shift();
  }
  return `${base.map(() => '..').join('/')}/${target.join('/')}/`.replace(/^\//, '');
}

function renderCardsSection(
  id: string,
  title: string,
  assets: PreviewPortalAsset[],
  surface: PreviewPortalSurface,
): string {
  if (assets.length === 0) return '';
  return `<section id="${id}" data-toc="${escAttr(title)}">
  <div class="section-head"><h2>${esc(title)}</h2><div class="section-title">${esc(title)}</div><div class="section-sub">${assets.length} item${assets.length === 1 ? '' : 's'} discovered.</div></div>
  <div class="grid">
    ${assets.map((asset) => renderAssetCard(asset, surface)).join('')}
  </div>
</section>`;
}

/**
 * Production-sheet sections that every template should surface (Cast + the
 * scene/character/candidate/story sheet dirs). They are spliced in right after
 * the storyboard so they read as "what we built" before the raw clip/image
 * grids, without editing all six template section orders. Each renders only when
 * it has content, so a template that already lists one keeps a single copy.
 */
const PRODUCTION_SHEET_SECTIONS = ['cast', 'keyframes', 'reference-sheets', 'scene-candidates', 'story-sheets'];

function effectiveSectionOrder(template: PreviewPortalTemplate): string[] {
  const order = [...template.sectionOrder];
  const missing = PRODUCTION_SHEET_SECTIONS.filter((section) => !order.includes(section));
  if (missing.length === 0) return order;
  const afterStoryboard = order.indexOf('storyboard');
  const insertAt = afterStoryboard >= 0 ? afterStoryboard + 1 : Math.min(order.indexOf('brief') + 1 || 0, order.length);
  order.splice(insertAt, 0, ...missing);
  return order;
}

function renderTemplateSections(
  project: PreviewPortalProject,
  template: PreviewPortalTemplate,
  surface: PreviewPortalSurface,
): string {
  // When the storyboard section renders the scene keyframes, suppress those same
  // sceneIndex'd keyframes from the generic generation-inputs grid (no duplicates).
  const storyboardSceneIndexes = project.storyboard
    ? new Set(project.storyboard.scenes.map((scene) => scene.sceneIndex))
    : null;
  return effectiveSectionOrder(template)
    .map((section) => {
      if (section === 'brief') return renderBriefSection(project);
      if (section === 'storyboard') return renderStoryboardSection(project, surface);
      if (section === 'cast') return renderCastSection(project, surface);
      let assets = project.assets.filter((asset) => asset.section === section);
      if (section === 'generation-inputs' && storyboardSceneIndexes) {
        assets = assets.filter(
          (asset) => asset.sceneIndex === undefined || !storyboardSceneIndexes.has(asset.sceneIndex),
        );
      }
      return renderCardsSection(sectionId(section), template.sectionLabels[section] ?? titleFromSection(section), assets, surface);
    })
    .join('');
}

/**
 * The Cast section: one card per locked identity (Flow Character or reference
 * character), with a matched still or a monogram, a source/role badge, and the
 * stable id. Lets the client see who/what is identity-locked across the cut.
 * Renders nothing when no cast is registered.
 */
function renderCastSection(project: PreviewPortalProject, surface: PreviewPortalSurface): string {
  const cast = project.cast;
  if (!cast || cast.length === 0) return '';
  const cards = cast
    .map((member) => {
      const media = member.stillPath
        ? `<img data-downloadable data-lightbox-group="cast" data-lb-caption="${escAttr(member.name)}" src="${escAttr(member.stillPath)}" alt="${escAttr(member.name)}">`
        : `<div class="cast-mono" aria-hidden="true">${esc(member.name.slice(0, 1).toUpperCase())}</div>`;
      const badge = member.source === 'flow-character' ? 'Flow Character' : 'Reference';
      const num = member.role ? `${badge} · ${member.role}` : badge;
      return `<div class="card" data-card-kind="cast" data-card-id="cast-${escAttr(slugify(member.name))}" data-media-kind="image">
    ${media}
    <div class="meta"><div class="num">${esc(num)}</div><div class="title">${esc(member.name)}</div>${member.ref ? `<div class="who">${esc(member.ref)}</div>` : ''}</div>
    ${renderControls(surface)}
  </div>`;
    })
    .join('');
  return `<section id="cast" data-toc="Cast">
  <div class="section-head"><h2>Cast</h2><div class="section-title">Cast &amp; Identity Locks</div><div class="section-sub">${cast.length} locked ${cast.length === 1 ? 'identity' : 'identities'} carried across every shot.</div></div>
  <div class="grid">${cards}</div>
</section>`;
}

function renderBriefSection(project: PreviewPortalProject): string {
  const brief = project.brief;
  if (!brief) return '';
  const meta = brief.metadata ?? {};
  const profile = meta.executionProfile ?? {};
  const chips: string[] = [];
  if (typeof meta.platform === 'string') chips.push(meta.platform);
  if (typeof profile.aspectRatio === 'string') chips.push(profile.aspectRatio);
  if (typeof profile.resolution === 'string') chips.push(profile.resolution);
  if (typeof profile.quality === 'string') chips.push(profile.quality);
  if (profile.generateAudio === true) chips.push('audio on');
  else if (profile.generateAudio === false) chips.push('audio off');
  const chipHtml = chips.length ? `<div class="who">${chips.map((chip) => esc(chip)).join(' · ')}</div>` : '';
  return `<section id="brief" data-toc="Brief">
  <div class="section-head"><h2>Brief</h2><div class="section-title">${esc(brief.title)}</div>${chipHtml}</div>
  <div class="grid"><div class="card"><div class="meta"><div class="title">${esc(brief.intent)}</div></div></div></div>
</section>`;
}

function renderStoryboardSection(project: PreviewPortalProject, surface: PreviewPortalSurface): string {
  const storyboard = project.storyboard;
  if (!storyboard || storyboard.scenes.length === 0) return '';
  const scenes = [...storyboard.scenes].sort((a, b) => a.sceneIndex - b.sceneIndex);
  const cards = scenes
    .map((scene) => {
      const keyframe = project.assets.find(
        (asset) => asset.kind === 'image' && asset.sceneIndex === scene.sceneIndex,
      );
      const sceneLabel = `Scene ${scene.sceneIndex + 1}`;
      const image = keyframe
        ? `<img${mediaAspectAttrs(keyframe)} data-downloadable data-lightbox-group="storyboard" data-lb-caption="${escAttr(sceneLabel)}" src="${escAttr(keyframe.path)}" alt="${escAttr(sceneLabel)}">`
        : '<div class="meta"><code>No keyframe yet</code></div>';
      // When the scene has a rendered clip (`outputs/scene-<i>.mp4`), add an inline
      // <video> (hidden by default via the card's data-mode) and a two-button
      // Image/Video toggle. The clip src is project-relative — the same base the
      // keyframe <img> uses — so it resolves against the project-dir-relative HTML.
      const media = scene.clipPath
        ? `<div class="scene-media">${image}<video class="clip" src="${escAttr(scene.clipPath)}" controls preload="none" playsinline></video>${renderSceneToggle()}</div>`
        : image;
      const cardModeAttr = scene.clipPath ? ' data-mode="image"' : '';
      const chips: string[] = [];
      if (scene.characters?.length) chips.push(...scene.characters);
      if (scene.scenePrompt?.cameraMove) chips.push(scene.scenePrompt.cameraMove);
      if (typeof scene.durationSeconds === 'number') chips.push(`${scene.durationSeconds}s`);
      const chipHtml = chips.length ? `<div class="who">${chips.map((chip) => esc(chip)).join(' · ')}</div>` : '';
      const dialogue = scene.dialogue ? `<div class="who">“${esc(scene.dialogue)}”</div>` : '';
      return `<div class="card" data-card-kind="scene" data-card-id="storyboard-scene-${scene.sceneIndex}"${cardModeAttr} data-media-kind="image">
    ${media}
    <div class="meta"><div class="num">${esc(sceneLabel)}</div><div class="title">${esc(scene.description)}</div>${scene.colorState ? renderColorStateChip(scene.colorState) : ''}${chipHtml}${dialogue}${keyframe?.createdAt ? `<div class="who card-date">keyframe ${esc(fmtDate(keyframe.createdAt))}</div>` : ''}</div>
    ${renderSceneContract(scene, project)}
    ${renderControls(surface)}
  </div>`;
    })
    .join('');
  return `<section id="storyboard" data-toc="Storyboard">
  <div class="section-head"><h2>Storyboard</h2><div class="section-title">Storyboard</div><div class="section-sub">${scenes.length} scene${scenes.length === 1 ? '' : 's'}.</div></div>
  <div class="grid">
    ${cards}
  </div>
</section>`;
}

/**
 * The per-scene Image/Video toggle (rendered only when the scene has a rendered
 * clip). Two buttons drive the card's `data-mode`: "Image" (active by default)
 * shows the keyframe; "▶ Video" swaps in the inline `<video>`. The shared
 * `setPortalMode` handler in `PORTAL_JS` flips the mode and pauses/loads the clip;
 * the toggle CSS in `PORTAL_CSS` shows/hides image vs video. No per-card inline
 * scripts — buttons are wired by the shared JS via `data-portal-mode`.
 */
function renderSceneToggle(): string {
  return `<div class="scene-toggle" role="group" aria-label="Show keyframe or video">`
    + `<button type="button" class="scene-toggle-btn" data-portal-mode="image" aria-pressed="true">Image</button>`
    + `<button type="button" class="scene-toggle-btn" data-portal-mode="video" aria-pressed="false">▶ Video</button>`
    + `</div>`;
}

/**
 * Display metadata for the known narrative color states (the grade ids). The hex
 * is the on-screen swatch; the label is the human-readable beat name. Unknown
 * states render with a neutral swatch and the raw id, so the chip is always safe
 * (the inline style only ever uses a hardcoded hex, never the untrusted id).
 */
const COLOR_STATE_DISPLAY: Record<string, { label: string; hex: string }> = {
  'cool-steel': { label: 'Normal ops', hex: '#6A7A87' },
  'crimson-threat': { label: 'Breach', hex: '#CC0000' },
  'electric-blue': { label: 'Resolution', hex: '#00B4D8' },
  'kodak-500t': { label: 'Film base', hex: '#C9A36A' },
  'bleach-bypass': { label: 'Bleach bypass', hex: '#B8B8B0' },
  desaturated: { label: 'Desaturated', hex: '#8A8A8A' },
  'teal-orange': { label: 'Teal / orange', hex: '#1F7A7A' },
};

/** Render the per-scene color-state chip: a hex swatch + beat label + grade id. */
function renderColorStateChip(colorState: string): string {
  const display = COLOR_STATE_DISPLAY[colorState];
  const hex = display?.hex ?? '#888888';
  const label = display?.label ?? colorState;
  return `<div class="color-state"><span class="cs-swatch" style="background:${escAttr(hex)}"></span><span class="cs-label">${esc(label)}</span><span class="cs-id">${esc(colorState)}</span></div>`;
}

function sectionId(section: string): string {
  if (section === 'final') return 'finals';
  return section.replace(/[^a-z0-9]+/gi, '-').toLowerCase();
}

function titleFromSection(section: string): string {
  return section
    .split(/[-_\s]+/)
    .filter(Boolean)
    .map((part) => `${part[0]?.toUpperCase() ?? ''}${part.slice(1)}`)
    .join(' ');
}

function renderAssetCard(asset: PreviewPortalAsset, surface: PreviewPortalSurface): string {
  const kind = asset.section === 'final' ? 'final' : asset.section === 'videos' ? 'scene' : 'asset';
  const media = asset.kind === 'video'
    ? `<video${mediaAspectAttrs(asset)} controls preload="metadata" data-downloadable src="${escAttr(asset.path)}"></video>`
    : asset.kind === 'image'
      ? `<img${mediaAspectAttrs(asset)} data-downloadable data-lightbox-group="${escAttr(asset.section)}" data-lb-caption="${escAttr(asset.label)}" src="${escAttr(asset.path)}" alt="${escAttr(asset.label)}">`
      : asset.kind === 'audio'
        ? `<div class="meta"><audio controls data-downloadable src="${escAttr(asset.path)}"></audio></div>`
        : asset.kind === 'html'
          ? `<a class="doc-thumb" href="${escAttr(asset.path)}" target="_blank" rel="noopener"><span>⤢ Open ${esc(asset.label)}</span></a>`
          : `<div class="meta"><code>${esc(asset.path)}</code></div>`;
  return `<div class="card" data-card-kind="${kind}" data-card-id="${escAttr(asset.id)}" data-media-kind="${escAttr(asset.kind)}">
    ${media}
    <div class="meta"><div class="num">${esc(asset.section)}</div><div class="title">${esc(asset.label)}</div><div class="who">${esc(asset.path)}</div>${asset.createdAt ? `<div class="who card-date">added ${esc(fmtDate(asset.createdAt))}</div>` : ''}</div>
    ${renderControls(surface)}
  </div>`;
}

function renderControls(surface: PreviewPortalSurface): string {
  // The unified Review surface renders BOTH control sets per card; CSS shows only
  // the active mode's set (editor vs client). Preview renders none.
  if (!isReviewSurface(surface)) return '';
  return `<div class="review-controls">
      <button type="button" class="review-btn approve" data-review-action="approve" aria-pressed="false">Approve</button>
      <button type="button" class="review-btn regenerate" data-review-action="regenerate" aria-pressed="false">Regenerate</button>
      <input type="text" class="review-note" placeholder="why / what to change">
    </div>
    <div class="client-controls">
      <button type="button" class="client-btn approve" data-client-action="approve" aria-pressed="false">Approve</button>
      <button type="button" class="client-btn decline" data-client-action="decline" aria-pressed="false">Decline</button>
      <input type="text" class="client-note" placeholder="comment">
    </div>`;
}

/** Media filter chips (preview surface only): All / Videos / Images. The viewer
 * JS toggles `.card[data-media-kind]` visibility and hides emptied sections. */
function renderFilterChips(): string {
  return `<div class="media-filter" role="toolbar" aria-label="Filter media">
  <button type="button" data-filter-chip="all" aria-pressed="true">All</button>
  <button type="button" data-filter-chip="video" aria-pressed="false">Videos</button>
  <button type="button" data-filter-chip="image" aria-pressed="false">Images</button>
</div>`;
}

/** Keyboard-shortcuts help overlay, toggled with `?` by the viewer JS. Rendered
 * statically (hidden) so tests can assert its presence without executing JS. */
function renderShortcutsHelp(): string {
  const rows: Array<[string, string]> = [
    ['← → or [ ]', 'Select previous / next media (page) · previous / next asset (viewer)'],
    ['Enter', 'Open the selected media in the viewer'],
    ['Esc', 'Close the viewer or this help'],
    ['Space / K', 'Play / pause video'],
    ['J / L', 'Playback slower / faster (0.25–4×)'],
    [', / .', 'Frame step back / forward (Shift: 10 frames)'],
    ['F', 'Fullscreen video'],
    ['M / ↑ ↓', 'Mute · volume up / down'],
    ['G', 'Grab the current video frame as a PNG'],
    ['D', 'Download the current asset'],
    ['Z or click', 'Zoom image 2× (drag to pan)'],
    ['?', 'Toggle this help'],
  ];
  const grid = rows
    .map(([keys, what]) => `<kbd>${esc(keys)}</kbd><span>${esc(what)}</span>`)
    .join('');
  return `<div id="kb-help" role="dialog" aria-label="Keyboard shortcuts" hidden>
  <div class="kb-card"><h3>Keyboard shortcuts</h3><div class="kb-grid">${grid}</div></div>
</div>`;
}

function renderHud(surface: PreviewPortalSurface): string {
  // Both HUDs render; CSS shows the one matching the active mode.
  if (!isReviewSurface(surface)) return '';
  return `<div class="hud" id="review-hud" role="status"><span id="rs-approved">0 approved</span><span id="rs-regen">0 to regenerate</span><button type="button" id="copy-decisions-btn">Copy Review Decisions</button></div>
<div class="hud" id="client-hud" role="status"><span>Client feedback</span><button type="button" id="copy-client-feedback-btn">Copy Feedback</button></div>`;
}

function modeForSurface(surface: PreviewPortalSurface): 'editor' | 'client' | 'preview' | 'compare' | 'run' {
  if (surface === 'edit' || surface === 'review') return 'editor';
  if (surface === 'client-review') return 'client';
  if (surface === 'compare') return 'compare';
  if (surface === 'run') return 'run';
  return 'preview';
}

function labelForSurface(surface: PreviewPortalSurface): string {
  if (surface === 'edit') return 'editor edit';
  if (surface === 'review') return 'editor review';
  if (surface === 'client-review') return 'client review';
  if (surface === 'compare') return 'compare';
  if (surface === 'index') return 'index';
  if (surface === 'run') return 'run';
  return 'preview';
}

function scriptForSurface(surface: PreviewPortalSurface): string {
  // Review surface drives both control sets + the tab/mode toggle.
  if (isReviewSurface(surface)) return PORTAL_EDITOR_JS + PORTAL_CLIENT_JS + PORTAL_REVIEW_TABS_JS;
  return '';
}