hyper-animator-codex 0.1.0

package/skills/hyper-animator-codex/references/hyperframes-intent-workflow.md

@@ -0,0 +1,191 @@
+# HyperFrames Intent Workflow
+
+目标：把自然语言视频/动画需求稳定地转成 HyperFrames HTML composition，并在关键节点用 `AskUserQuestion` 澄清。
+
+本 workflow 采用双模式架构：
+
+- `assemble_existing_catalog_items`：复用已安装的 HyperFrames catalog block/component，适合快速组装和调用现有视觉资产。
+- `generate_new_hyperframes_html`：根据 catalog 候选作为参考，按 `HyperFrames-AI-Generation-Patterns-codex.md` 生成新的完整 HyperFrames HTML，适合用户要求“写 HTML 动画”或现有 catalog 不完全匹配的场景。
+
+## Pipeline
+
+1. 接收自然语言需求。
+2. 抽取初始 `intent_profile`：用途、平台、画幅、内容类型、风格、动效、时长、是否需要字幕/转场/片尾。
+3. 若用途或画幅缺失，调用 `AskUserQuestion` 第一轮澄清。
+4. 用 `hyperframes-catalog-map.json` 对 catalog items 打分。
+5. 选出候选 plan：主场景 Block、可选 Component、可选 Transition、可选 Outro。
+6. 判断 generation mode：组装现有 catalog，还是生成新 HTML。
+7. 调用 `AskUserQuestion` 第二轮澄清样式、动效、候选取舍，以及 generation mode。
+8. 若选择 `assemble_existing_catalog_items`，生成 wrapper composition，并解析 component paste 指令为真实 snippet。
+9. 若选择 `generate_new_hyperframes_html`，按 patterns 文档生成完整 block/component HTML。
+10. 运行 pre-render quality gates。
+11. 展示方案摘要和 HTML preview，让用户验证/确认。
+12. 根据反馈修订。
+13. 渲染视频。
+
+## Intent Profile
+
+```json
+{
+  "rawRequest": "",
+  "purpose": "product_launch",
+  "format": "landscape_16_9",
+  "generationMode": "generate_new_hyperframes_html",
+  "styleTags": ["apple_like", "premium"],
+  "motionTags": ["reveal", "zoom"],
+  "neededRoles": ["main_scene", "device_showcase", "caption", "outro"],
+  "durationTarget": 30,
+  "contentInputs": {
+    "productName": "",
+    "script": "",
+    "code": "",
+    "data": []
+  }
+}
+```
+
+## AskUserQuestion Round 1: 用途和场景
+
+当 `purpose` 或 `format` 不明确时先问，不要直接选 block。
+
+```json
+{
+  "purpose": "clarify_intent_and_format",
+  "questions": [
+    {
+      "id": "purpose",
+      "question": "你这次视频/动画主要用于什么场景？",
+      "choices": ["产品发布/功能展示", "技术教程/代码演示", "数据报告/市场复盘", "播客/采访/字幕包装", "社交媒体短视频"]
+    },
+    {
+      "id": "format",
+      "question": "目标画幅是什么？",
+      "choices": ["横屏 16:9", "竖屏 9:16", "方形", "还不确定"]
+    }
+  ]
+}
+```
+
+## Catalog Scoring
+
+```text
+score =
+  keywordMatch * 0.30
++ intentDomainMatch * 0.25
++ formatMatch * 0.15
++ assetRoleMatch * 0.10
++ styleMatch * 0.10
++ motionMatch * 0.05
++ constraintsMatch * 0.05
+```
+
+硬约束优先于分数：
+
+- 竖屏需求优先 portrait 条目，如 `instagram-follow`, `tiktok-follow`, `spotify-card`, `flowchart-vertical`。
+- 需要叠加字幕时优先 component：`caption-*`。
+- 需要完整镜头时优先 block。
+- `code-morph` 在 failedItems 中，默认不可选。
+
+## Generation Mode Decision
+
+默认规则：
+
+- 用户说“用现有 catalog / 快速拼一个 / 调用 block / 组合这些条目”：选择 `assemble_existing_catalog_items`。
+- 用户说“写 HTML 动画 / 生成一个新效果 / 自定义样式 / 按我的品牌做”：选择 `generate_new_hyperframes_html`。
+- 如果 component 的 `install.includeSnippet` 只是 `<!-- paste from ... -->` 注释，不能直接作为最终 HTML；必须读取/粘贴真实 snippet，或者切到 `generate_new_hyperframes_html`。
+- 如果需要原创 caption、shader、WebGL、3D 或复杂时间线，优先 `generate_new_hyperframes_html` 并遵循 patterns 文档。
+
+必要时追问：
+
+```json
+{
+  "purpose": "clarify_generation_mode",
+  "question": "你希望这次是快速组合现有 HyperFrames catalog 条目，还是生成一个新的完整 HTML 动画？",
+  "choices": ["快速组合现有条目", "生成新的完整 HTML 动画"]
+}
+```
+
+## AskUserQuestion Round 2: 样式和动效
+
+在候选 items 出来后再问，问题要带候选上下文。
+
+```json
+{
+  "purpose": "clarify_style_motion",
+  "candidateContext": ["app-showcase", "vfx-iphone-device", "logo-outro"],
+  "questions": [
+    {
+      "id": "style",
+      "question": "这次更想要哪种视觉方向？",
+      "choices": ["Apple 风高级产品感", "电影感/暗调科技", "极简清爽", "社媒高能/动感"]
+    },
+    {
+      "id": "motion",
+      "question": "动效更偏哪种节奏？",
+      "choices": ["稳重高级", "快节奏冲击", "柔和流动", "故障/赛博"]
+    }
+  ]
+}
+```
+
+## HTML Generation Plan
+
+生成 HTML 前输出 plan：
+
+```json
+{
+  "generationMode": "generate_new_hyperframes_html",
+  "selectedItems": [
+    {"id": "app-showcase", "role": "visual_reference"},
+    {"id": "caption-pill-karaoke", "role": "caption_reference"},
+    {"id": "logo-outro", "role": "outro_reference"}
+  ],
+  "patternsRequired": true,
+  "assumptions": ["用户未提供 logo，先使用文字 logo 占位"],
+  "nextValidation": "请确认风格、文案、时长和画幅。"
+}
+```
+
+## HTML Generation Rules
+
+### assemble_existing_catalog_items
+
+- Block 可用 `data-composition-src` include。
+- Component 的 paste comment 不是最终视觉；必须解析为真实 snippet 后粘贴。
+- Wrapper composition 仍应有固定画幅和总时长。
+
+### generate_new_hyperframes_html
+
+必须遵循 `HyperFrames-AI-Generation-Patterns-codex.md`：
+
+- 完整 block 使用 `data-composition-id`, `data-width`, `data-height`, `data-duration`。
+- 主动画使用 `gsap.timeline({ paused: true })`。
+- 注册到 `window.__timelines[id]`。
+- CSS scoped 到 `[data-composition-id="..."]` 或唯一 component id。
+- timeline 覆盖 declared duration，并 padding 到完整 duration。
+- 字体、图片、GLTF、WebGL 等 async 资源 ready 后再注册 timeline。
+- WebGL/Three/shader 必须有 fallback timeline。
+
+## Pre-Render Quality Gates
+
+渲染前必须检查：
+
+- HTML 有固定 width/height/duration。
+- Block 有 `data-composition-id`。
+- 有 paused GSAP timeline 并注册 `window.__timelines[id]`。
+- Timeline 覆盖 declared duration。
+- 没有用 `Date.now()`、hover 或无限 RAF 驱动主进度。
+- Async 资源处理不会导致空白 render。
+- Component 是真实 snippet 或 attach 函数，不是 paste 注释。
+- CSS selector scoped 或唯一。
+- 文本在目标视频尺寸可读。
+
+## User Validation
+
+渲染前必须让用户确认：
+
+- generation mode 是否符合预期。
+- 选用/参考的 block/component 是否符合需求。
+- 画幅和时长是否正确。
+- 文案、代码、数据、logo 是否正确。
+- 是否需要替换风格或动效。

package/skills/hyper-animator-codex/scripts/validate_hyperframes_html.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""Static pre-render checks for HyperFrames HTML compositions."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+
+def has_attr(html: str, name: str) -> bool:
+    return re.search(rf"\b{name}\s*=\s*['\"]?[^'\"\s>]+", html, re.IGNORECASE) is not None
+
+
+def check_html(html: str, *, component: bool = False) -> tuple[list[str], list[str]]:
+    failures: list[str] = []
+    warnings: list[str] = []
+
+    if not component:
+        for attr in ("data-width", "data-height", "data-duration", "data-composition-id"):
+            if not has_attr(html, attr):
+                failures.append(f"missing {attr}")
+
+    if "<!-- paste from " in html:
+        failures.append("unresolved component paste placeholder")
+
+    paused_timeline = re.search(
+        r"gsap\s*\.\s*timeline\s*\(\s*\{[^}]*paused\s*:\s*true",
+        html,
+        re.IGNORECASE | re.DOTALL,
+    )
+    if not paused_timeline:
+        failures.append("missing gsap.timeline({ paused: true })")
+
+    if "window.__timelines" not in html:
+        failures.append("missing window.__timelines registration")
+
+    if re.search(r"\bDate\s*\.\s*now\s*\(", html):
+        failures.append("uses Date.now(); render progress must be timeline-driven")
+
+    if re.search(r"\bsetInterval\s*\(", html):
+        failures.append("uses setInterval(); primary render progress must be timeline-driven")
+
+    if re.search(r"\brequestAnimationFrame\s*\(", html) and "fallback" not in html.lower():
+        warnings.append("requestAnimationFrame found; ensure it is not the primary render clock and has render fallback")
+
+    if "<style" in html.lower() and "[data-composition-id" not in html:
+        warnings.append("style block found without [data-composition-id] scoped selector")
+
+    if len(re.findall(r"data-duration\s*=\s*['\"]?(\d+(?:\.\d+)?)", html)) > 1:
+        warnings.append("multiple data-duration values found; verify the intended render duration")
+
+    return failures, warnings
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Validate HyperFrames HTML before render.")
+    parser.add_argument("html_file", help="Path to a HyperFrames HTML file")
+    parser.add_argument(
+        "--component",
+        action="store_true",
+        help="Validate a component snippet instead of a full block composition",
+    )
+    args = parser.parse_args()
+
+    path = Path(args.html_file)
+    if not path.exists():
+        print(f"FAIL: file does not exist: {path}", file=sys.stderr)
+        return 2
+
+    html = path.read_text(encoding="utf-8")
+    failures, warnings = check_html(html, component=args.component)
+
+    for warning in warnings:
+        print(f"WARN: {warning}", file=sys.stderr)
+
+    if failures:
+        for failure in failures:
+            print(f"FAIL: {failure}", file=sys.stderr)
+        return 1
+
+    print("OK: HyperFrames HTML passed static pre-render checks")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())