hyper-animator-codex 0.1.0

package/README.md

@@ -0,0 +1,51 @@
+# hyper-animator-codex
+
+Install the `hyper-animator-codex` Codex skill from npm.
+
+The skill guides Codex through a HyperFrames animation workflow: natural-language brief, clarification questions, catalog-map intent matching, style and motion selection, HTML animation authoring, validation, user approval, and render handoff.
+
+## Install
+
+Use it directly with `npx`:
+
+```bash
+npx hyper-animator-codex install
+```
+
+To replace an existing installed copy:
+
+```bash
+npx hyper-animator-codex install --force
+```
+
+Or install the CLI globally:
+
+```bash
+npm install -g hyper-animator-codex
+hyper-animator-codex install --force
+```
+
+By default the installer copies the skill to:
+
+```text
+${CODEX_HOME:-$HOME/.codex}/skills/hyper-animator-codex
+```
+
+Use a custom Codex skills directory:
+
+```bash
+npx hyper-animator-codex install --target /path/to/codex/skills
+```
+
+## Contents
+
+- `skills/hyper-animator-codex/SKILL.md`: Codex skill instructions.
+- `skills/hyper-animator-codex/references/`: HyperFrames catalog map, workflow guide, pseudocode, and request examples.
+- `skills/hyper-animator-codex/scripts/validate_hyperframes_html.py`: static pre-render HTML quality gate.
+
+## Development
+
+```bash
+npm test
+npm run pack:check
+```

package/bin/hyper-animator-codex.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+import { installSkill, resolveCodexSkillsRoot, SKILL_NAME } from "../lib/install-skill.mjs";
+
+function printHelp() {
+  console.log(`Usage:
+  hyper-animator-codex install [--force] [--target <skills-dir>]
+  hyper-animator-codex path
+  hyper-animator-codex help
+
+Commands:
+  install  Install the packaged ${SKILL_NAME} skill into Codex
+  path     Print the default Codex skills directory
+  help     Show this help
+
+Options:
+  --force            Replace an existing installed skill
+  --target <dir>     Install into a specific Codex skills directory
+`);
+}
+
+function parseInstallArgs(args) {
+  const parsed = {
+    force: false,
+    targetRoot: undefined,
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--force") {
+      parsed.force = true;
+    } else if (arg === "--target") {
+      const value = args[index + 1];
+      if (!value) {
+        throw new Error("--target requires a directory");
+      }
+      parsed.targetRoot = value;
+      index += 1;
+    } else {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+
+  return parsed;
+}
+
+async function main() {
+  const [command = "install", ...args] = process.argv.slice(2);
+
+  if (command === "help" || command === "--help" || command === "-h") {
+    printHelp();
+    return;
+  }
+
+  if (command === "path") {
+    console.log(resolveCodexSkillsRoot());
+    return;
+  }
+
+  if (command !== "install") {
+    throw new Error(`Unknown command: ${command}`);
+  }
+
+  const options = parseInstallArgs(args);
+  const result = await installSkill(options);
+
+  console.log(`Installed ${result.skillName}`);
+  console.log(`Source: ${result.sourcePath}`);
+  console.log(`Target: ${result.installedPath}`);
+}
+
+main().catch((error) => {
+  console.error(`Error: ${error.message}`);
+  process.exitCode = 1;
+});

package/lib/install-skill.mjs

@@ -0,0 +1,69 @@
+import { cp, mkdir, rm, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const SKILL_NAME = "hyper-animator-codex";
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+
+async function pathExists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch (error) {
+    if (error && error.code === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+}
+
+function shouldCopy(src) {
+  const name = basename(src);
+  return name !== ".DS_Store" && name !== "__pycache__" && !name.endsWith(".pyc");
+}
+
+export function resolveCodexSkillsRoot(env = process.env) {
+  if (env.CODEX_HOME) {
+    return join(env.CODEX_HOME, "skills");
+  }
+
+  const home = env.HOME || homedir();
+  if (!home) {
+    throw new Error("Cannot resolve Codex skills directory: HOME is not set");
+  }
+
+  return join(home, ".codex", "skills");
+}
+
+export async function installSkill(options = {}) {
+  const targetRoot = options.targetRoot || resolveCodexSkillsRoot(options.env);
+  const sourcePath = options.sourcePath || join(packageRoot, "skills", SKILL_NAME);
+  const installedPath = join(targetRoot, SKILL_NAME);
+  const force = Boolean(options.force);
+
+  if (!(await pathExists(sourcePath))) {
+    throw new Error(`Packaged skill not found at ${sourcePath}`);
+  }
+
+  await mkdir(targetRoot, { recursive: true });
+
+  if (await pathExists(installedPath)) {
+    if (!force) {
+      throw new Error(`${SKILL_NAME} already exists at ${installedPath}; rerun with --force to replace it`);
+    }
+    await rm(installedPath, { recursive: true, force: true });
+  }
+
+  await cp(sourcePath, installedPath, {
+    recursive: true,
+    filter: shouldCopy,
+  });
+
+  return {
+    skillName: SKILL_NAME,
+    sourcePath,
+    installedPath,
+  };
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "hyper-animator-codex",
+  "version": "0.1.0",
+  "description": "Install the Hyper Animator Codex skill for Codex.",
+  "type": "module",
+  "bin": {
+    "hyper-animator-codex": "bin/hyper-animator-codex.mjs"
+  },
+  "scripts": {
+    "test": "node --test",
+    "pack:check": "npm pack --dry-run"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "skills/hyper-animator-codex/",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/realpkuasule/hyper-animator-codex.git"
+  },
+  "keywords": [
+    "codex",
+    "codex-skill",
+    "hyperframes",
+    "animation",
+    "video",
+    "gsap"
+  ],
+  "author": "",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=18.17"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/hyper-animator-codex/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: hyper-animator-codex
+description: Use when a user asks Codex to create, plan, author, customize, validate, preview, or render a HyperFrames, HTML, or GSAP animation/video from natural-language requirements, including product demos, code demos, data videos, podcast captions, social shorts, catalog block/component assembly, or new HyperFrames HTML.
+---
+
+# Hyper Animator Codex
+
+## Overview
+
+Turn a natural-language animation or video brief into a validated HyperFrames HTML composition and render handoff. Use catalog items for intent matching and visual references, but keep user confirmation before render.
+
+## Required Flow
+
+1. Capture the raw request and extract an initial intent profile: purpose, format, duration, content inputs, style tags, motion tags, and needed roles.
+2. If purpose, format, or core content is unclear, ask the first clarification round before choosing catalog items.
+3. Read `references/hyperframes-catalog-map.json` and score candidates by keyword, intent domain, format, role, style, motion, and constraints.
+4. Pick candidate blocks/components for main scene, caption, effects, transitions, and outro.
+5. Decide generation mode:
+   - `generate_new_hyperframes_html` when the user asks to write HTML, create a new effect, customize style, match a brand, use complex animation, or when component snippets are only paste placeholders.
+   - `assemble_existing_catalog_items` only when the user asks to use existing catalog items or quickly compose installed blocks/components.
+6. Ask the second clarification round with candidate context: visual direction, motion rhythm, generation mode, and any candidate tradeoffs.
+7. Write or assemble HTML.
+8. Run pre-render quality gates.
+9. Show a concise plan summary and preview path or HTML file to the user. Ask for confirmation before video render.
+10. Render only after user confirmation, then report output path and any caveats.
+
+## Interactive Questions
+
+Prefer Codex interactive question tools such as `AskUserQuestion` or `request_user_input` when available. If they are unavailable, ask the same questions as ordinary concise text and continue after the user answers.
+
+Use two rounds:
+
+- Round 1: purpose, format, duration, platform, required content, brand assets, and whether video render is expected in this turn.
+- Round 2: after catalog scoring, ask about style, motion, candidate selection, and generation mode.
+
+Do not ask everything upfront when the brief is already specific. Ask only for missing or decision-changing information.
+
+## References
+
+- Read `references/hyperframes-intent-workflow.md` for the full AskUserQuestion workflow, generation-mode rules, scoring model, and render confirmation requirements.
+- Read `references/hyperframes-catalog-map.json` whenever selecting catalog candidates or determining visual references.
+- Read `references/hyperframes-agent-pseudocode.ts` when implementing the end-to-end loop or when the correct sequence is ambiguous.
+- Use `references/examples/*.json` for sanity checks against common request shapes.
+
+## Catalog Rules
+
+Hard constraints beat score:
+
+- Portrait requests prioritize portrait items such as `instagram-follow`, `tiktok-follow`, `spotify-card`, and `flowchart-vertical`.
+- Caption requests prioritize `caption-*` components.
+- Complete scene requests prioritize block items with `main_scene`.
+- Exclude `code-morph` by default because it appears in failed items.
+- Component `install.includeSnippet` values that only say `<!-- paste from ... -->` are not renderable HTML. Resolve the real snippet or switch to `generate_new_hyperframes_html`.
+
+## HTML Quality Gates
+
+Before render, run:
+
+```bash
+python3 scripts/validate_hyperframes_html.py path/to/composition.html
+```
+
+Generated block HTML must include:
+
+- fixed `data-width`, `data-height`, and `data-duration`;
+- `data-composition-id`;
+- scoped CSS under `[data-composition-id="..."]` or another unique composition selector;
+- `gsap.timeline({ paused: true })`;
+- `window.__timelines[id]` registration;
+- no unresolved `<!-- paste from ... -->` placeholders;
+- no wall-clock `Date.now()` or `setInterval()` driving primary timeline progress;
+- readable text at the target video dimensions.
+
+If the validator fails, fix the HTML before asking the user to approve render.
+
+## Render Handoff
+
+Before rendering, summarize:
+
+- generation mode;
+- selected or referenced catalog items;
+- dimensions and duration;
+- content assumptions;
+- preview location;
+- validator result.
+
+Ask the user whether to render or revise. If rendering tools or project-specific commands are unavailable, stop at validated HTML and report the exact missing render command or dependency.

package/skills/hyper-animator-codex/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Hyper Animator Codex"
+  short_description: "Turn animation briefs into HyperFrames videos"
+  default_prompt: "Use $hyper-animator-codex to turn my animation brief into HyperFrames HTML and a rendered video."

package/skills/hyper-animator-codex/references/examples/request-code_demo.json

@@ -0,0 +1,18 @@
+{
+  "rawRequest": "做一个开发者工具 CLI 安装演示，黑色终端风，展示命令输入和安装成功。",
+  "expectedIntent": {
+    "purpose": "developer_demo",
+    "format": "landscape_16_9",
+    "styleTags": [
+      "dark"
+    ],
+    "neededRoles": [
+      "main_scene"
+    ]
+  },
+  "likelyItems": [
+    "code-snippet-apple-terminal-pro",
+    "code-snippet-apple-terminal-homebrew",
+    "grain-overlay"
+  ]
+}

package/skills/hyper-animator-codex/references/examples/request-podcast_caption.json

@@ -0,0 +1,22 @@
+{
+  "rawRequest": "给播客采访加一个嘉宾名牌，再加口播字幕，风格简洁高级。",
+  "expectedIntent": {
+    "purpose": "podcast_interview",
+    "format": "landscape_16_9",
+    "styleTags": [
+      "minimal",
+      "premium"
+    ],
+    "neededRoles": [
+      "main_scene",
+      "caption",
+      "effect"
+    ]
+  },
+  "likelyItems": [
+    "lt-clean-bar",
+    "lt-soft-pill",
+    "caption-editorial-emphasis",
+    "grain-overlay"
+  ]
+}

package/skills/hyper-animator-codex/references/examples/request-product_launch.json

@@ -0,0 +1,23 @@
+{
+  "rawRequest": "做一个 AI 产品发布视频，展示 App 界面，Apple 风，横屏，最后有 logo 收尾。",
+  "expectedIntent": {
+    "purpose": "product_launch",
+    "format": "landscape_16_9",
+    "styleTags": [
+      "apple_like",
+      "premium"
+    ],
+    "neededRoles": [
+      "main_scene",
+      "device_showcase",
+      "outro"
+    ]
+  },
+  "likelyItems": [
+    "app-showcase",
+    "vfx-iphone-device",
+    "logo-outro",
+    "vignette",
+    "shimmer-sweep"
+  ]
+}

package/skills/hyper-animator-codex/references/hyperframes-agent-pseudocode.ts

@@ -0,0 +1,266 @@
+type Format = "landscape_16_9" | "portrait_9_16" | "square" | "custom" | "flexible" | "unknown";
+type GenerationMode = "assemble_existing_catalog_items" | "generate_new_hyperframes_html";
+
+type IntentProfile = {
+  rawRequest: string;
+  purpose?: string;
+  format?: Format;
+  generationMode?: GenerationMode;
+  styleTags: string[];
+  motionTags: string[];
+  neededRoles: string[];
+  durationTarget?: number;
+  contentInputs: Record<string, unknown>;
+};
+
+type CatalogItem = {
+  id: string;
+  title: string;
+  type: "block" | "component";
+  intentDomains: string[];
+  naturalLanguageTriggers: string[];
+  styleTags: string[];
+  motionTags: string[];
+  assetRoles: string[];
+  format: { width?: number; height?: number; aspect: Format; durationSeconds?: number };
+  install: { command?: string; path?: string; includeSnippet?: string };
+  generationHints?: {
+    htmlStrategy?: {
+      assembleExisting?: string;
+      generateNew?: string;
+    };
+    patternsRequiredForGenerateNew?: boolean;
+    componentSnippetWarning?: string;
+  };
+};
+
+type ScoredItem = CatalogItem & { score: number; reasons: string[] };
+type FinalPlan = {
+  generationMode: GenerationMode;
+  selectedItems: ScoredItem[];
+  width: number;
+  height: number;
+  duration: number;
+  assumptions: string[];
+};
+
+declare function AskUserQuestion(input: unknown): Promise<Record<string, unknown>>;
+declare function renderVideo(input: { html: string; width: number; height: number; duration: number }): Promise<string>;
+declare function readInstalledSnippet(path: string): Promise<string>;
+declare function generateWithLLM(input: unknown): Promise<string>;
+
+export async function runHyperFramesAgent(userRequest: string, catalogMap: { items: CatalogItem[] }) {
+  let profile = extractInitialIntent(userRequest);
+
+  if (!profile.purpose || !profile.format || profile.format === "unknown") {
+    const answers = await AskUserQuestion({
+      purpose: "clarify_intent_and_format",
+      questions: buildFirstRoundQuestions(),
+    });
+    profile = mergeAnswers(profile, answers);
+  }
+
+  let candidates = scoreCatalogItems(profile, catalogMap.items).filter((item) => item.id !== "code-morph");
+  const draftPlan = selectBlocksAndComponents(profile, candidates);
+
+  if (!profile.generationMode || generationModeNeedsConfirmation(profile, draftPlan)) {
+    const answer = await AskUserQuestion({
+      purpose: "clarify_generation_mode",
+      question: "你希望这次是快速组合现有 HyperFrames catalog 条目，还是生成一个新的完整 HTML 动画？",
+      choices: ["assemble_existing_catalog_items", "generate_new_hyperframes_html"],
+      recommendation: recommendGenerationMode(profile, draftPlan),
+    });
+    profile = mergeAnswers(profile, answer);
+  }
+
+  const styleAnswers = await AskUserQuestion({
+    purpose: "clarify_style_motion",
+    candidateContext: draftPlan.selectedItems.map((item) => item.id),
+    questions: buildStyleQuestions(),
+  });
+  profile = mergeAnswers(profile, styleAnswers);
+
+  candidates = scoreCatalogItems(profile, catalogMap.items).filter((item) => item.id !== "code-morph");
+  const finalPlan = selectBlocksAndComponents(profile, candidates);
+  finalPlan.generationMode = profile.generationMode ?? recommendGenerationMode(profile, finalPlan);
+
+  const html = finalPlan.generationMode === "assemble_existing_catalog_items"
+    ? await assembleExistingCatalogHtml(finalPlan, profile)
+    : await generateNewHyperFramesHtml(finalPlan, profile);
+
+  const quality = runPreRenderQualityGates(html, finalPlan);
+  if (!quality.ok) {
+    return { status: "quality_gate_failed", finalPlan, html, failures: quality.failures };
+  }
+
+  const approval = await AskUserQuestion({
+    purpose: "user_validation_before_render",
+    summary: summarizePlan(finalPlan),
+    previewHtml: html,
+    questions: [
+      { id: "approved", question: "这个方案可以进入渲染吗？", choices: ["可以", "需要修改"] },
+      { id: "feedback", question: "如果需要修改，请说明要改的地方。", optional: true },
+    ],
+  });
+
+  if (approval.approved !== "可以") {
+    return { status: "needs_revision", html, finalPlan, feedback: approval.feedback };
+  }
+
+  return renderVideo({ html, width: finalPlan.width, height: finalPlan.height, duration: finalPlan.duration });
+}
+
+function recommendGenerationMode(profile: IntentProfile, plan: FinalPlan): GenerationMode {
+  if (/写|生成|自定义|新的|html|动画/i.test(profile.rawRequest)) return "generate_new_hyperframes_html";
+  const hasComponentPasteOnly = plan.selectedItems.some((item) => item.type === "component" && item.install.includeSnippet?.startsWith("<!-- paste from"));
+  if (hasComponentPasteOnly) return "generate_new_hyperframes_html";
+  return "assemble_existing_catalog_items";
+}
+
+function generationModeNeedsConfirmation(profile: IntentProfile, plan: FinalPlan): boolean {
+  if (/用现有|catalog|调用|组合/i.test(profile.rawRequest)) return false;
+  if (/写|生成|自定义|新的|html|动画/i.test(profile.rawRequest)) return false;
+  return plan.selectedItems.some((item) => item.type === "component" && item.install.includeSnippet?.startsWith("<!-- paste from"));
+}
+
+async function assembleExistingCatalogHtml(plan: FinalPlan, profile: IntentProfile): Promise<string> {
+  const bodyParts: string[] = [];
+  for (const item of plan.selectedItems) {
+    if (item.type === "block" && item.install.includeSnippet?.startsWith("<div")) {
+      bodyParts.push(item.install.includeSnippet);
+      continue;
+    }
+    if (item.type === "component" && item.install.path) {
+      bodyParts.push(await readInstalledSnippet(item.install.path));
+      continue;
+    }
+    bodyParts.push(`<!-- Missing snippet for ${item.id}; resolve before render. -->`);
+  }
+
+  return `<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=${plan.width}, height=${plan.height}" />
+  <style>html,body{margin:0;width:${plan.width}px;height:${plan.height}px;overflow:hidden;}</style>
+</head>
+<body>
+${bodyParts.join("\n")}
+</body>
+</html>`;
+}
+
+async function generateNewHyperFramesHtml(plan: FinalPlan, profile: IntentProfile): Promise<string> {
+  return generateWithLLM({
+    mode: "generate_new_hyperframes_html",
+    patternsReference: "/Users/zhichao/claude/hf-projects/HyperFrames-AI-Generation-Patterns-codex.md",
+    requirements: [
+      "Generate complete HyperFrames HTML, not just data-composition-src wrapper.",
+      "Use fixed data-composition-id, data-width, data-height, data-duration.",
+      "Use gsap.timeline({ paused: true }) and register window.__timelines[id].",
+      "Scope CSS under [data-composition-id] or unique component id.",
+      "Pad timeline to declared duration.",
+      "Avoid Date.now(), hover-only animation, and unbounded RAF for primary progress.",
+      "Handle fonts/assets/WebGL readiness before timeline registration; provide fallback for WebGL.",
+    ],
+    selectedReferences: plan.selectedItems.map((item) => ({ id: item.id, title: item.title, reasons: item.reasons })),
+    profile,
+    dimensions: { width: plan.width, height: plan.height, duration: plan.duration },
+  });
+}
+
+function runPreRenderQualityGates(html: string, plan: FinalPlan): { ok: boolean; failures: string[] } {
+  const failures: string[] = [];
+  if (plan.generationMode === "generate_new_hyperframes_html") {
+    if (!/data-composition-id=/.test(html)) failures.push("missing data-composition-id");
+    if (!/data-duration=/.test(html)) failures.push("missing data-duration");
+    if (!/data-width=/.test(html) || !/data-height=/.test(html)) failures.push("missing data-width/data-height");
+    if (!/gsap\.timeline\(\{\s*paused:\s*true/.test(html)) failures.push("missing paused GSAP timeline");
+    if (!/window\.__timelines/.test(html)) failures.push("missing window.__timelines registration");
+  }
+  if (/<!-- paste from /.test(html)) failures.push("component paste instruction was not resolved to real snippet");
+  if (/Date\.now\(/.test(html)) failures.push("uses Date.now for timing");
+  if (/setInterval\(/.test(html)) failures.push("uses setInterval for primary timing");
+  return { ok: failures.length === 0, failures };
+}
+
+function extractInitialIntent(rawRequest: string): IntentProfile {
+  const profile: IntentProfile = { rawRequest, styleTags: [], motionTags: [], neededRoles: [], contentInputs: {} };
+  if (/产品|app|发布|功能/.test(rawRequest)) profile.purpose = "product_launch";
+  if (/代码|编程|cli|终端|vscode/i.test(rawRequest)) profile.purpose = "developer_demo";
+  if (/数据|图表|地图|增长|复盘/.test(rawRequest)) profile.purpose = "data_visualization";
+  if (/播客|采访|嘉宾|lower third/i.test(rawRequest)) profile.purpose = "podcast_interview";
+  if (/字幕|口播|caption|shorts|tiktok|reels/i.test(rawRequest)) profile.neededRoles.push("caption");
+  if (/转场|切换|transition/i.test(rawRequest)) profile.neededRoles.push("transition");
+  if (/logo|片尾|outro/i.test(rawRequest)) profile.neededRoles.push("outro");
+  if (/竖屏|9:16|tiktok|shorts|reels/i.test(rawRequest)) profile.format = "portrait_9_16";
+  else if (/横屏|16:9|youtube|b站|bilibili/i.test(rawRequest)) profile.format = "landscape_16_9";
+  else profile.format = "unknown";
+  if (/用现有|catalog|调用|组合/i.test(rawRequest)) profile.generationMode = "assemble_existing_catalog_items";
+  if (/写|生成|自定义|新的|html|动画/i.test(rawRequest)) profile.generationMode = "generate_new_hyperframes_html";
+  if (/apple|苹果|高级|premium/i.test(rawRequest)) profile.styleTags.push("apple_like", "premium");
+  if (/电影|cinematic|暗调/i.test(rawRequest)) profile.styleTags.push("cinematic", "dark");
+  if (/极简|clean|minimal/i.test(rawRequest)) profile.styleTags.push("minimal");
+  if (/故障|赛博|glitch|cyber/i.test(rawRequest)) profile.styleTags.push("cyberpunk");
+  return profile;
+}
+
+function scoreCatalogItems(profile: IntentProfile, items: CatalogItem[]): ScoredItem[] {
+  return items.map((item) => {
+    let score = 0;
+    const reasons: string[] = [];
+    const request = profile.rawRequest.toLowerCase();
+    const keywordHits = item.naturalLanguageTriggers.filter((k) => request.includes(k.toLowerCase()));
+    if (keywordHits.length) { score += Math.min(0.30, keywordHits.length * 0.05); reasons.push(`keyword: ${keywordHits.slice(0, 4).join(", ")}`); }
+    if (profile.purpose && item.intentDomains.includes(profile.purpose)) { score += 0.25; reasons.push(`intent: ${profile.purpose}`); }
+    if (profile.format && item.format.aspect === profile.format) { score += 0.15; reasons.push(`format: ${profile.format}`); }
+    const roleHits = profile.neededRoles.filter((role) => item.assetRoles.includes(role));
+    if (roleHits.length) { score += Math.min(0.10, roleHits.length * 0.05); reasons.push(`role: ${roleHits.join(", ")}`); }
+    const styleHits = profile.styleTags.filter((tag) => item.styleTags.includes(tag));
+    if (styleHits.length) { score += Math.min(0.10, styleHits.length * 0.04); reasons.push(`style: ${styleHits.join(", ")}`); }
+    const motionHits = profile.motionTags.filter((tag) => item.motionTags.includes(tag));
+    if (motionHits.length) { score += Math.min(0.05, motionHits.length * 0.025); reasons.push(`motion: ${motionHits.join(", ")}`); }
+    return { ...item, score: Number(score.toFixed(3)), reasons };
+  }).sort((a, b) => b.score - a.score);
+}
+
+function buildFirstRoundQuestions() {
+  return [
+    { id: "purpose", question: "你这次视频/动画主要用于什么场景？", choices: ["product_launch", "developer_demo", "data_visualization", "podcast_interview", "social_media"] },
+    { id: "format", question: "目标画幅是什么？", choices: ["landscape_16_9", "portrait_9_16", "square", "unknown"] },
+  ];
+}
+
+function buildStyleQuestions() {
+  return [
+    { id: "style", question: "这次更想要哪种视觉方向？", choices: ["apple_like", "cinematic", "minimal", "social_dynamic", "cyberpunk", "editorial"] },
+    { id: "motion", question: "动效更偏哪种节奏？", choices: ["steady_premium", "fast_impact", "soft_fluid", "glitch_cyber"] },
+  ];
+}
+
+function selectBlocksAndComponents(profile: IntentProfile, candidates: ScoredItem[]): FinalPlan {
+  const main = candidates.find((item) => item.type === "block" && item.assetRoles.includes("main_scene"));
+  const captions = candidates.filter((item) => item.assetRoles.includes("caption") && item.type === "component").slice(0, 1);
+  const effects = candidates.filter((item) => item.assetRoles.includes("effect") && item.type === "component").slice(0, 2);
+  const outro = profile.neededRoles.includes("outro") ? candidates.find((item) => item.assetRoles.includes("outro")) : undefined;
+  const selectedItems = [main, ...captions, ...effects, outro].filter(Boolean) as ScoredItem[];
+  const width = main?.format.width ?? (profile.format === "portrait_9_16" ? 1080 : 1920);
+  const height = main?.format.height ?? (profile.format === "portrait_9_16" ? 1920 : 1080);
+  const duration = selectedItems.reduce((sum, item) => sum + (item.format.durationSeconds ?? 0), 0) || profile.durationTarget || 10;
+  const generationMode = profile.generationMode ?? "generate_new_hyperframes_html";
+  return { generationMode, selectedItems, width, height, duration, assumptions: [] };
+}
+
+function mergeAnswers(profile: IntentProfile, answers: Record<string, unknown>): IntentProfile {
+  return { ...profile, ...answers } as IntentProfile;
+}
+
+function summarizePlan(plan: FinalPlan) {
+  return {
+    generationMode: plan.generationMode,
+    selectedItems: plan.selectedItems.map((item) => ({ id: item.id, title: item.title, score: item.score, reasons: item.reasons })),
+    width: plan.width,
+    height: plan.height,
+    duration: plan.duration,
+  };
+}