hyper-animator-codex 0.8.0 → 0.8.1

package/README.md

@@ -3,9 +3,9 @@
 Install the `hyper-animator-codex` Codex skill from npm.
 
 The skill guides Codex through a contract-first HyperFrames animation workflow:
-natural-language brief, outline/narration detection, dual-catalog shot planning
-(HyperFrames + ShotCraft), MiniMax mainland China audio, HTML animation
-authoring, validation, user approval, and render handoff.
+natural-language brief, outline/narration detection, visual-first dual-catalog
+shot planning (HyperFrames + ShotCraft), HTML animation authoring, MiniMax
+mainland China audio after visual approval, validation, and render handoff.
 
 ## Install
 
@@ -124,6 +124,11 @@ When rendering video, hide preview controls with any one of:
 
 ## Narration And Subtitles
 
+The workflow detects narration needs early, but generated narration and
+subtitles are deferred until the user approves the page, transitions, and
+animation. Visual drafts use `audio.narration.mode: "deferred"` in the shot
+plan.
+
 Detect outline and narration files in a project directory:
 
 ```bash
@@ -180,7 +185,14 @@ node skills/hyper-animator-codex/scripts/query_shotcraft.mjs \
 ```
 
 HyperFrames entries remain the renderable catalog; ShotCraft supplies shot
-grammar and motion references that are translated into HyperFrames/GSAP HTML.
+grammar and motion references that are translated into `motion_contract`
+commitments and then into HyperFrames/GSAP HTML.
+
+For high-impact ShotCraft refs, the validator requires an explicit
+`motion_contract.motion_preset`. The bundled
+`references/shotcraft/motion-pack/` directory contains small GSAP helpers to
+copy before freehanding the animation.
+
 Validate a dual-catalog plan before authoring:
 
 ```bash
@@ -209,7 +221,8 @@ packaging use a faster cost-efficient model.
 
 The skill can analyze background music and guide Codex to align HyperFrames/GSAP transitions to beats, bars, energy peaks, and detected music segments.
 
-Install optional Python dependencies:
+Install optional Python dependencies yourself if you want automatic beat
+analysis. The skill will not install them during a run:
 
 ```bash
 python3 -m pip install librosa pydub numpy click
@@ -236,6 +249,8 @@ Then analyze the generated audio with `analyze_music_beats.py` and align animati
 ## Development
 
 ```bash
+npm run preflight
 npm test
+npm run check
 npm run pack:check
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyper-animator-codex",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Install the Hyper Animator skill for Codex and Claude Code.",
   "type": "module",
   "bin": {
@@ -8,7 +8,10 @@
   },
   "scripts": {
     "postinstall": "node bin/postinstall.mjs",
+    "preflight": "node tools/verify-governance.mjs",
     "test": "node --test",
+    "test:contracts": "node --test test/shot-plan-contract.test.mjs test/workflow-policy.test.mjs test/provider-policy.test.mjs",
+    "check": "npm run preflight && npm test && npm run pack:check",
     "pack:check": "npm pack --dry-run"
   },
   "files": [

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

@@ -11,32 +11,32 @@ Turn a natural-language animation or video brief into a validated HyperFrames HT
 
 ## Required Flow
 
-1. Read `contracts/workflow-policy.json` before doing any orchestration. Treat it as an executable product contract, not optional guidance. Generated narration and generated BGM must use `minimax_cn` at the declared `minimaxi.com` endpoints.
-2. Enforce the provider boundary. Never run `hyperframes auth login` or `hyperframes tts`. Do not use HeyGen, Kokoro, or MusicGen. Do not install a fallback audio runtime or fallback model. If MiniMax is unavailable or fails, stop that audio stage and ask the user to choose: retry MiniMax CN, provide a local audio file, or skip the track.
+1. Read `contracts/workflow-policy.json` before doing any orchestration. Treat it as an executable product contract, not optional guidance. Generated narration and generated BGM must use `minimax_cn` at the declared `minimaxi.com` endpoints; generated narration is gated until visual confirmation.
+2. Enforce the provider boundary. Never run `hyperframes auth login` or `hyperframes tts`. Do not use HeyGen, Kokoro, or MusicGen. Do not install a fallback audio runtime, fallback model, or beat-analysis dependency. If MiniMax or optional beat analysis is unavailable, stop that stage and ask the user to choose: retry MiniMax CN, provide a local audio file/beat map, or skip the track.
 3. Read `references/git-checkpoint-workflow.md` and run `scripts/git_checkpoint.mjs --phase init --message "chore: initialize hyper animator workspace" --allow-empty` before requirement capture. If the helper reports an existing dirty repository or linked worktree, stop and ask the user to resolve it.
-4. When starting in a new directory, restarting, or handling outline/narration/voiceover/subtitle/full-mix work, read `references/narration-audio-workflow.md` and run `scripts/detect_project_files.mjs --dir . --pretty` before visual planning.
+4. When starting in a new directory, restarting, or handling outline/narration/voiceover/subtitle/full-mix work, read `references/narration-audio-workflow.md` and run `scripts/detect_project_files.mjs --dir . --pretty` before visual planning. Detect outline/narration inputs only; do not process narration yet.
 5. Capture the raw request and extract an initial intent profile: purpose, format, duration, content inputs, style tags, motion tags, and needed roles.
 6. If purpose, format, or core content is unclear, ask the first clarification round before choosing catalog items.
 7. Query both catalogs:
    - Read `references/hyperframes-catalog-map.json` and score renderable HyperFrames candidates.
    - Run `scripts/query_shotcraft.mjs --query "<purpose style motion>" --limit 8 --json` against `references/shotcraft/catalog.json` for shot grammar, pacing, transition, and camera references.
-8. Pick candidate HyperFrames blocks/components plus ShotCraft references for each main scene, caption, effect, transition, and outro. ShotCraft TSX is a design reference; do not introduce Remotion or copy it as the final renderer.
+8. Pick candidate HyperFrames blocks/components plus ShotCraft references for each main scene, caption, effect, transition, and outro. Open the selected ShotCraft card READMEs and translate their timing, camera, transition, and known pitfalls into explicit `motion_contract.shotcraft_commitments`; ShotCraft TSX is a design reference, not the renderer. If a selected card is covered by `references/shotcraft/motion-pack/README.md`, use its `motion_contract.motion_preset` and GSAP helper before freehanding motion.
 9. 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.
 10. Apply model routing when model selection is available: use `gpt-5.6-sol` for page and animation authoring only; use `gpt-5.6-terra` or another fast cost-efficient model for requirements, discovery, catalog queries, shot planning, audio prompting, validation, and packaging. Do not create an extra agent/entity only to implement this routing.
-11. Write a shot plan that follows `contracts/shot-plan.schema.json`, uses `catalog_strategy: "dual_catalog"`, and gives every shot explicit start/end timing and both catalog reference lists. Run `scripts/validate_shot_plan.mjs shot-plan.json`; fix every error before audio generation or HTML authoring.
-12. Clarify audio: ask whether to use narration, subtitles, animation/transition sound effects, and background music.
-13. If generated narration is used, first run `scripts/validate_provider_policy.mjs --kind narration --provider minimax_cn --endpoint https://api.minimaxi.com/v1/t2a_v2`. Use `scripts/generate_minimax_tts.mjs` for voice listing and TTS; do not construct MiniMax HTTP calls directly. For multi-scene narration, use `--split-scenes` and treat `narration-manifest.json` actual durations as the scene-timing source. Reconcile shot boundaries with those durations and run `scripts/validate_shot_plan.mjs` again. If subtitles are requested, run `scripts/generate_subtitles.mjs --timing-manifest <voice-output>/narration-manifest.json`.
-14. If generated BGM is requested, read `references/minimax-music-workflow.md`, run `scripts/validate_provider_policy.mjs --kind bgm --provider minimax_cn --endpoint https://api.minimaxi.com/v1/music_generation`, and use `scripts/generate_minimax_music.mjs`. Do not construct MiniMax HTTP calls directly.
-15. If background music is used, read `references/beat-sync-workflow.md`, generate or obtain the audio, and run `scripts/analyze_music_beats.py` when the file is available.
-16. Ask the second clarification round with dual-catalog candidate context: visual direction, motion rhythm, generation mode, narration/subtitle/audio choices, music prompt/model when MiniMax is used, and beat-sync assumptions when background music is present.
-17. Write or assemble HTML using `references/HyperFrames-AI-Generation-Patterns-codex.md`. When beat-sync is enabled, align major reveals, cuts, transitions, camera moves, narration beats, subtitle cues, and visual accents to the beat map instead of arbitrary timestamps.
-18. After each file-writing stage, run `scripts/git_checkpoint.mjs` with the phase-specific allowlist from `references/git-checkpoint-workflow.md`. Do not create, switch, or recommend Git branches or worktrees.
-19. Run pre-render quality gates on the base HTML.
-20. Read `references/preview-controls-workflow.md`, run `scripts/inject_preview_controls.mjs` to create a preview HTML copy, and run `scripts/validate_hyperframes_html.py preview.html --preview-controls`.
-21. Show a concise plan summary and preview path or HTML file to the user. Ask for confirmation before video render.
-22. Render only after user confirmation. Prefer rendering the base HTML; if rendering the preview copy, use `?render=1`, `?preview=0`, or `<html data-render-mode="video">` so preview controls are hidden. Then report output path and any caveats.
+11. Write a visual-first shot plan that follows `contracts/shot-plan.schema.json`, sets workflow_stage: `visual_draft`, `catalog_strategy: "dual_catalog"`, `audio.narration.mode: "deferred"` when narration is requested, explicit start/end timing, both catalog reference lists, and one `motion_contract` per shot including `motion_preset`. Run `scripts/validate_shot_plan.mjs shot-plan.json`; fix every error before HTML authoring.
+12. Clarify audio intent only: ask whether the final piece should use narration, subtitles, transition sound effects, and background music. Do not generate narration audio or subtitles before the user confirms the page, transition, and animation. If BGM is the rhythm source, it may be generated or imported before HTML; otherwise defer it with narration.
+13. If generated BGM is needed as the rhythm source, read `references/minimax-music-workflow.md`, run `scripts/validate_provider_policy.mjs --kind bgm --provider minimax_cn --endpoint https://api.minimaxi.com/v1/music_generation`, and use `scripts/generate_minimax_music.mjs`. Then read `references/beat-sync-workflow.md` and run `scripts/analyze_music_beats.py` when dependencies and the file are already available. Do not install beat-analysis dependencies during the run.
+14. Ask the second clarification round with dual-catalog candidate context: visual direction, motion rhythm, selected ShotCraft commitments, generation mode, BGM/beat-sync assumptions when present, and the fact that narration is deferred until visual approval.
+15. Write or assemble the visual HTML using `references/HyperFrames-AI-Generation-Patterns-codex.md`. When beat-sync is enabled, align major reveals, cuts, transitions, camera moves, subtitle placeholders, and visual accents to the beat map instead of arbitrary timestamps.
+16. After each file-writing stage, run `scripts/git_checkpoint.mjs` with the phase-specific allowlist from `references/git-checkpoint-workflow.md`. Do not create, switch, or recommend Git branches or worktrees.
+17. Run pre-render quality gates on the base HTML.
+18. Read `references/preview-controls-workflow.md`, run `scripts/inject_preview_controls.mjs` to create a preview HTML copy, and run `scripts/validate_hyperframes_html.py preview.html --preview-controls`.
+19. Show a concise visual plan summary and preview path. Ask the user to confirm or revise the page, transition, and animation before any generated narration or subtitle work.
+20. After visual confirmation, handle narration. If generated narration is used, first run `scripts/validate_provider_policy.mjs --kind narration --provider minimax_cn --endpoint https://api.minimaxi.com/v1/t2a_v2`. Use `scripts/generate_minimax_tts.mjs` for voice listing and TTS; do not construct MiniMax HTTP calls directly. For multi-scene narration, use `--split-scenes` and treat `narration-manifest.json` actual durations as the scene-timing source. Generate subtitles only after this with `scripts/generate_subtitles.mjs --timing-manifest <voice-output>/narration-manifest.json`.
+21. Reconcile shot boundaries with actual narration durations, update the shot plan to `workflow_stage: "audio_integrated"`, re-run `scripts/validate_shot_plan.mjs`, update the HTML/audio preview, and ask for final render confirmation.
+22. Render only after final user confirmation. Prefer rendering the base HTML; if rendering the preview copy, use `?render=1`, `?preview=0`, or `<html data-render-mode="video">` so preview controls are hidden. Then report output path and any caveats.
 
 ## Interactive Questions
 
@@ -44,8 +44,8 @@ Prefer Codex interactive question tools such as `AskUserQuestion` or `request_us
 
 Use two rounds:
 
-- Round 1: purpose, format, duration, platform, required content, outline/narration status, narration/subtitles, brand assets, sound effects, background music, and whether video render is expected in this turn.
-- Round 2: after catalog scoring, ask about style, motion, candidate selection, generation mode, voice/emotion/subtitle style, and beat-sync assumptions when background music is present.
+- Round 1: purpose, format, duration, platform, required content, outline/narration status, desired final narration/subtitles, brand assets, sound effects, background music, and whether video render is expected in this turn.
+- Round 2: after catalog scoring, ask about style, motion, candidate selection, generation mode, selected ShotCraft commitments, and beat-sync assumptions when background music is present. Defer voice/emotion/subtitle generation choices until page, transition, and animation approval.
 
 Do not ask everything upfront when the brief is already specific. Ask only for missing or decision-changing information.
 
@@ -57,6 +57,7 @@ Do not ask everything upfront when the brief is already specific. Ask only for m
 - Read `references/hyperframes-catalog-map.json` whenever selecting catalog candidates or determining visual references.
 - Read `references/shotcraft/catalog.json` and use `scripts/query_shotcraft.mjs` whenever building or revising a shot plan. Open only the selected cards and source references, not the entire bundle.
 - Read selected `references/shotcraft/cards/<name>/README.md` files for intent, timing, parameters, and known failure modes. Treat selected `references/shotcraft/source/**/*.tsx` as motion references that must be translated into the HyperFrames/GSAP contract.
+- Read `references/shotcraft/motion-pack/README.md` before HTML authoring when selected ShotCraft refs include a supported preset. Copy only needed helpers from `references/shotcraft/motion-pack/shotcraft-motion-pack.js`.
 - Read `contracts/shot-plan.schema.json` before writing a shot plan and validate the result with `scripts/validate_shot_plan.mjs`.
 - Read `references/HyperFrames-AI-Generation-Patterns-codex.md` before generating new HyperFrames HTML.
 - Read `references/hyperframes-agent-pseudocode.ts` when implementing the end-to-end loop or when the correct sequence is ambiguous.
@@ -71,6 +72,8 @@ Hard constraints beat score:
 
 - Use the HyperFrames map and ShotCraft together. HyperFrames answers “what can be rendered”; ShotCraft answers “how the shot should communicate and move.”
 - Query ShotCraft first, then open only the top relevant cards. By default exclude `reference-only` styles.
+- Every selected ShotCraft reference must become a concrete `motion_contract.shotcraft_commitments` item in the shot plan before HTML authoring.
+- Supported ShotCraft refs must also select the matching `motion_contract.motion_preset`; use the motion pack helper before inventing a new GSAP pattern.
 - Do not install React, Remotion, or ShotCraft dependencies merely to use a ShotCraft reference.
 - Portrait requests prioritize portrait items such as `instagram-follow`, `tiktok-follow`, `spotify-card`, and `flowchart-vertical`.
 - Caption requests prioritize `caption-*` components.
@@ -113,7 +116,10 @@ Before approval, inspect the preview against the selected ShotCraft cards:
 
 - every required product capability has a distinct, readable shot;
 - every shot adds new information and preserves the selected card's motion
-  grammar, critical timing, and documented known pitfalls;
+  grammar, critical timing, documented known pitfalls, and written
+  `motion_contract.shotcraft_commitments`;
+- supported ShotCraft refs use their declared `motion_contract.motion_preset`
+  and corresponding motion-pack helper;
 - real product states/assets are used when supplied, with no invented product
   claims;
 - text, masks, media, fonts, and async resources are fully loaded at render

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

@@ -1,4 +1,4 @@
 interface:
   display_name: "Hyper Animator Codex"
-  short_description: "Plan dual-catalog HyperFrames videos with MiniMax CN audio"
-  default_prompt: "Use $hyper-animator-codex to plan my shots with HyperFrames and ShotCraft, create validated HyperFrames HTML, and use MiniMax CN for generated narration or BGM."
+  short_description: "Plan visual-first HyperFrames videos with ShotCraft"
+  default_prompt: "Use $hyper-animator-codex to plan visual-first shots with HyperFrames and ShotCraft, create validated HyperFrames HTML, and add MiniMax CN narration or BGM only at the approved stage."

package/skills/hyper-animator-codex/contracts/shot-plan.schema.json

@@ -6,6 +6,7 @@
   "additionalProperties": false,
   "required": [
     "schema_version",
+    "workflow_stage",
     "generation_mode",
     "catalog_strategy",
     "dimensions",
@@ -18,6 +19,13 @@
     "schema_version": {
       "const": "1.0.0"
     },
+    "workflow_stage": {
+      "enum": [
+        "visual_draft",
+        "audio_integrated",
+        "render_ready"
+      ]
+    },
     "generation_mode": {
       "enum": [
         "assemble_existing_catalog_items",
@@ -109,7 +117,8 @@
           "enum": [
             "generated",
             "user_local_file",
-            "none"
+            "none",
+            "deferred"
           ]
         },
         "provider": {
@@ -167,7 +176,8 @@
         "end_seconds",
         "purpose",
         "hyperframes_refs",
-        "shotcraft_refs"
+        "shotcraft_refs",
+        "motion_contract"
       ],
       "properties": {
         "id": {
@@ -188,6 +198,7 @@
         },
         "hyperframes_refs": {
           "type": "array",
+          "minItems": 1,
           "items": {
             "type": "string",
             "minLength": 1
@@ -196,6 +207,7 @@
         },
         "shotcraft_refs": {
           "type": "array",
+          "minItems": 1,
           "items": {
             "type": "string",
             "minLength": 1
@@ -207,6 +219,60 @@
             "string",
             "null"
           ]
+        },
+        "motion_contract": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "motion_preset",
+            "energy",
+            "camera",
+            "transition",
+            "shotcraft_commitments",
+            "readable_rest_seconds"
+          ],
+          "properties": {
+            "motion_preset": {
+              "enum": [
+                "none",
+                "slam-entrance",
+                "whip-transition",
+                "crash-zoom",
+                "push-stack-wipe",
+                "dataviz-landscape-open",
+                "panel-grid-reflow",
+                "brand-resolve"
+              ]
+            },
+            "energy": {
+              "enum": [
+                "quiet",
+                "balanced",
+                "high",
+                "cinematic"
+              ]
+            },
+            "camera": {
+              "type": "string",
+              "minLength": 1
+            },
+            "transition": {
+              "type": "string",
+              "minLength": 1
+            },
+            "shotcraft_commitments": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "readable_rest_seconds": {
+              "type": "number",
+              "minimum": 0
+            }
+          }
         }
       }
     }

package/skills/hyper-animator-codex/contracts/workflow-policy.json

@@ -5,6 +5,7 @@
     "generated_narration": {
       "provider": "minimax_cn",
       "endpoint": "https://api.minimaxi.com/v1/t2a_v2",
+      "stage_after": "visual_confirmation",
       "backup_endpoints": [
         "https://api-bj.minimaxi.com/v1/t2a_v2"
       ],
@@ -26,10 +27,14 @@
     ],
     "forbidden_commands": [
       "hyperframes auth login",
-      "hyperframes tts"
+      "hyperframes tts",
+      "python3 -m pip install librosa",
+      "pip3 install librosa",
+      "pip install librosa"
     ],
     "automatic_fallback": false,
     "automatic_runtime_install": false,
+    "automatic_dependency_install": false,
     "failure_choices": [
       "retry_minimax_cn",
       "use_user_local_file",
@@ -69,6 +74,13 @@
     "default_statuses": [
       "implemented"
     ],
+    "motion_pack_path": "references/shotcraft/motion-pack/README.md",
+    "motion_pack_snippet": "references/shotcraft/motion-pack/shotcraft-motion-pack.js",
+    "prefer_motion_pack_before_freehand": true,
+    "motion_pack_required_for_supported_refs": true,
+    "motion_contract_required": true,
+    "minimum_commitments_per_shot": 1,
+    "read_selected_cards_before_html": true,
     "excluded_asset_extensions": [
       ".mp4",
       ".mov",

package/skills/hyper-animator-codex/references/examples/shot-plan-dual-catalog.json

@@ -1,5 +1,6 @@
 {
   "schema_version": "1.0.0",
+  "workflow_stage": "visual_draft",
   "generation_mode": "generate_new_hyperframes_html",
   "catalog_strategy": "dual_catalog",
   "dimensions": {
@@ -9,8 +10,7 @@
   "duration_seconds": 12,
   "audio": {
     "narration": {
-      "mode": "generated",
-      "provider": "minimax_cn"
+      "mode": "deferred"
     },
     "bgm": {
       "mode": "generated",
@@ -33,6 +33,16 @@
       "shotcraft_refs": [
         "scene-locked-title"
       ],
+      "motion_contract": {
+        "motion_preset": "none",
+        "energy": "cinematic",
+        "camera": "slow crane rise from a title detail to the full product stage",
+        "transition": "full-frame light wipe into the proof shot",
+        "shotcraft_commitments": [
+          "keep the title locked and readable before the camera travel opens the scene"
+        ],
+        "readable_rest_seconds": 0.6
+      },
       "narration_scene": "1"
     },
     {
@@ -46,6 +56,16 @@
       "shotcraft_refs": [
         "ai-stream-response"
       ],
+      "motion_contract": {
+        "motion_preset": "none",
+        "energy": "high",
+        "camera": "locked readable screen with short punch-ins on key rows",
+        "transition": "snap to the final proof state on a clear beat",
+        "shotcraft_commitments": [
+          "stream response rows progressively instead of fading static copy"
+        ],
+        "readable_rest_seconds": 0.5
+      },
       "narration_scene": "2"
     },
     {
@@ -59,6 +79,16 @@
       "shotcraft_refs": [
         "ui-strip-away-outro"
       ],
+      "motion_contract": {
+        "motion_preset": "none",
+        "energy": "cinematic",
+        "camera": "wide resolve with a final centered brand hold",
+        "transition": "strip away interface fragments into the outro mark",
+        "shotcraft_commitments": [
+          "resolve dense motion into a clean brand hold for at least one second"
+        ],
+        "readable_rest_seconds": 1
+      },
       "narration_scene": "3"
     }
   ],

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

@@ -19,23 +19,28 @@
    Transition、可选 Outro，以及每个镜头的 ShotCraft 参考。
 6. 判断 generation mode：组装现有 catalog，还是生成新 HTML。
 7. 调用 `AskUserQuestion` 第二轮澄清样式、动效、候选取舍，以及 generation mode。
-8. 若选择 `assemble_existing_catalog_items`，生成 wrapper composition，并解析 component paste 指令为真实 snippet。
-9. 若选择 `generate_new_hyperframes_html`，按
+8. 写出 `workflow_stage: visual_draft` 的 shot plan。每个镜头必须包含
+   `motion_contract.motion_preset` 和 `motion_contract.shotcraft_commitments`，
+   把 ShotCraft 卡片的镜头、转场、节奏和避坑要求变成可验证条目。若最终需要
+   旁白，此阶段使用 `audio.narration.mode: deferred`。
+9. 运行 `scripts/validate_shot_plan.mjs shot-plan.json`。
+10. 若选择 `assemble_existing_catalog_items`，生成 wrapper composition，并解析 component paste 指令为真实 snippet。
+11. 若选择 `generate_new_hyperframes_html`，按
    `references/HyperFrames-AI-Generation-Patterns-codex.md` 生成完整
    block/component HTML；ShotCraft TSX 只作为动效参考，不引入 Remotion
    运行时。
-10. 按 `contracts/shot-plan.schema.json` 写出镜头计划，并运行
-    `scripts/validate_shot_plan.mjs shot-plan.json`。
-11. 运行 pre-render quality gates。
-12. 展示方案摘要和 HTML preview，让用户验证/确认。
-13. 根据反馈修订。
-14. 渲染视频。
+12. 运行 pre-render quality gates。
+13. 展示方案摘要和 HTML preview，让用户确认页面、转场和动画。
+14. 视觉确认后再生成旁白、字幕并按实际时长更新 shot plan。
+15. 根据反馈修订。
+16. 渲染视频。
 
 ## Intent Profile
 
 ```json
 {
   "rawRequest": "",
+  "workflowStage": "visual_draft",
   "purpose": "product_launch",
   "format": "landscape_16_9",
   "generationMode": "generate_new_hyperframes_html",
@@ -136,6 +141,8 @@ score =
 }
 ```
 
+Round 2 不选择 voice/emotion，也不生成字幕。旁白选择放到视觉确认后。
+
 ## HTML Generation Plan
 
 生成 HTML 前输出 plan：
@@ -149,6 +156,7 @@ score =
     {"id": "logo-outro", "role": "outro_reference"}
   ],
   "patternsRequired": true,
+  "audio": {"narration": {"mode": "deferred"}},
   "assumptions": ["用户未提供 logo，先使用文字 logo 占位"],
   "nextValidation": "请确认风格、文案、时长和画幅。"
 }

package/skills/hyper-animator-codex/references/narration-audio-workflow.md

@@ -15,19 +15,24 @@ Rules:
 - scan only the current directory top level;
 - trust fixed names first: `outline.*` and `narration.*`;
 - if multiple candidates are returned, ask the user to choose;
-- if only outline exists, ask whether to generate narration from it;
-- if only narration exists, ask whether to generate an outline from it;
+- if only outline exists, record narration as deferred until visual approval;
+- if only narration exists, use it as content context but do not generate audio or subtitles yet;
 - if narration is not used, do not generate voice audio or subtitles.
 
 Codex writes or edits outline/narration content. Scripts only validate, convert, call MiniMax, and write artifacts.
 
+Narration is a post-visual-confirmation stage. Do not generate MiniMax TTS,
+voice lists, or subtitles until the user has approved the page, transition,
+and animation direction. A visual draft shot plan should use
+`audio.narration.mode: "deferred"` when narration is requested.
+
 ## Provider Boundary
 
 Generated narration and BGM use MiniMax mainland China (`minimax_cn`) only.
 Never run `hyperframes auth login` or `hyperframes tts`; never invoke HeyGen,
-Kokoro, or MusicGen; and never install a fallback runtime/model. Kokoro is a
-local open-weight TTS engine, but it is outside this product contract and is
-not needed.
+Kokoro, or MusicGen; and never install a fallback runtime/model or beat
+analysis dependency during a run. Kokoro is a local open-weight TTS engine,
+but it is outside this product contract and is not needed.
 
 Before a generated-audio call, validate the route:
 
@@ -121,15 +126,17 @@ Subtitle rules:
 
 ## BGM, Beat, And Schedule
 
-BGM is the timing source when present:
+BGM is the timing source when present, but narration still waits for visual
+approval:
 
 1. decide BGM generation, local import, or skip;
-2. if configured, generate BGM with `scripts/generate_minimax_music.mjs`;
-3. analyze the music with `scripts/analyze_music_beats.py`;
-4. schedule transitions, animation, narration, and subtitles against the beat map;
-5. generate HTML;
-6. preview and get user confirmation;
-7. render and mix final video/audio.
+2. if BGM is needed for beat-sync, generate BGM with `scripts/generate_minimax_music.mjs`;
+3. analyze the music with `scripts/analyze_music_beats.py` only when its dependencies are already available;
+4. if beat analysis dependencies are missing, do not run `pip install`; ask for a beat map, continue with explicit manual cues, or skip beat sync;
+5. schedule transitions and animation against the beat map or manual cues;
+6. generate the visual HTML preview and get page/transition/animation confirmation;
+7. generate narration and subtitles, then reconcile timing;
+8. render and mix final video/audio after final approval.
 
 Default mix:
 

package/skills/hyper-animator-codex/references/shotcraft/motion-pack/README.md

@@ -0,0 +1,32 @@
+# ShotCraft motion pack
+
+Use this pack before freehanding animation for the supported ShotCraft cards.
+The goal is to copy the card's actual motion grammar into GSAP/HyperFrames
+instead of merely describing it in prose.
+
+| ShotCraft reference | `motion_contract.motion_preset` | Helper |
+| --- | --- | --- |
+| `slam-entrance-moves` | `slam-entrance` | `slamEntrance` |
+| `shot-transitions` | `whip-transition` | `whipTransition` |
+| `crash-zoom-punch` | `crash-zoom` | `crashZoom` |
+| `bottom-push-stack-wipe` | `push-stack-wipe` | `pushStackWipe` |
+| `dataviz-landscape-open` | `dataviz-landscape-open` | `datavizLandscapeOpen` |
+| `panel-grid-moves` | `panel-grid-reflow` | `panelGridReflow` |
+| `ui-to-brand-morph` | `brand-resolve` | `brandResolve` |
+
+Usage:
+
+1. Read the selected ShotCraft card README first.
+2. Set the matching `motion_contract.motion_preset` in the shot plan.
+3. Copy only the needed helper from `shotcraft-motion-pack.js` into the
+   generated HTML, or include the file as a local reference when the project
+   allows that.
+4. Keep the helper on the main paused GSAP timeline; do not run wall-clock
+   timers, React, Remotion, or ShotCraft runtime code.
+
+Quality bar:
+
+- motion starts with a visible camera/geometry event, not a fade;
+- transition covers the cut with a real mask, whip, impact, or spatial travel;
+- dense motion resolves into at least `readable_rest_seconds` of rest;
+- every helper call is tied to a named shot boundary or beat cue.

package/skills/hyper-animator-codex/references/shotcraft/motion-pack/shotcraft-motion-pack.js

@@ -0,0 +1,178 @@
+// Copy the needed helpers into a generated HyperFrames HTML file.
+// Requires GSAP and a paused main timeline.
+(function registerShotCraftMotion(global) {
+  function gsapRef() {
+    if (!global.gsap) throw new Error("GSAP is required for ShotCraft motion helpers");
+    return global.gsap;
+  }
+
+  function slamEntrance(tl, target, cue = 0, opts = {}) {
+    const gsap = gsapRef();
+    const duration = opts.duration ?? 0.72;
+    tl.set(target, { transformPerspective: 900, transformOrigin: "50% 55%" }, cue)
+      .fromTo(target, {
+        autoAlpha: 0,
+        scale: 2.4,
+        z: 420,
+        rotateX: -18,
+        filter: "blur(14px) brightness(1.8)",
+      }, {
+        autoAlpha: 1,
+        scale: 0.92,
+        z: 0,
+        rotateX: 0,
+        filter: "blur(0px) brightness(1)",
+        duration: duration * 0.58,
+        ease: "expo.out",
+      }, cue)
+      .to(target, { scale: 1.04, duration: duration * 0.16, ease: "power2.out" }, cue + duration * 0.42)
+      .to(target, { scale: 1, duration: duration * 0.26, ease: "back.out(2.4)" }, cue + duration * 0.56);
+    if (opts.ring) {
+      tl.fromTo(opts.ring, { autoAlpha: 0.9, scale: 0.12 }, {
+        autoAlpha: 0,
+        scale: 2.8,
+        duration: duration * 0.72,
+        ease: "expo.out",
+      }, cue + 0.04);
+    }
+    return tl;
+  }
+
+  function whipTransition(tl, fromTarget, toTarget, cue = 0, opts = {}) {
+    const distance = opts.distance ?? 260;
+    const blur = opts.blur ?? 18;
+    tl.to(fromTarget, {
+      x: -distance,
+      rotateZ: -3,
+      filter: `blur(${blur}px)`,
+      autoAlpha: 0,
+      duration: 0.2,
+      ease: "power4.in",
+    }, cue)
+      .fromTo(toTarget, {
+        x: distance,
+        rotateZ: 3,
+        filter: `blur(${blur}px)`,
+        autoAlpha: 0,
+      }, {
+        x: 0,
+        rotateZ: 0,
+        filter: "blur(0px)",
+        autoAlpha: 1,
+        duration: 0.34,
+        ease: "expo.out",
+      }, cue + 0.16);
+    if (opts.flash) tl.fromTo(opts.flash, { autoAlpha: 0 }, { autoAlpha: 1, yoyo: true, repeat: 1, duration: 0.05 }, cue + 0.14);
+    return tl;
+  }
+
+  function crashZoom(tl, target, cue = 0, opts = {}) {
+    tl.fromTo(target, {
+      scale: opts.fromScale ?? 0.72,
+      filter: "contrast(1.3) saturate(1.25)",
+    }, {
+      scale: opts.overshoot ?? 1.18,
+      duration: 0.16,
+      ease: "power4.in",
+    }, cue)
+      .to(target, { scale: 0.98, duration: 0.12, ease: "power2.out" }, cue + 0.16)
+      .to(target, { scale: 1, filter: "contrast(1) saturate(1)", duration: 0.28, ease: "expo.out" }, cue + 0.28);
+    if (opts.shock) tl.fromTo(opts.shock, { autoAlpha: 0.85, scale: 0.2 }, { autoAlpha: 0, scale: 2.2, duration: 0.34, ease: "expo.out" }, cue + 0.12);
+    return tl;
+  }
+
+  function pushStackWipe(tl, fromTarget, toTarget, cue = 0, opts = {}) {
+    const height = opts.height ?? "112%";
+    tl.fromTo(toTarget, { y: height, autoAlpha: 1 }, {
+      y: "0%",
+      duration: 0.48,
+      ease: "power3.inOut",
+    }, cue)
+      .to(fromTarget, {
+        y: "-18%",
+        scale: 0.94,
+        filter: "blur(8px)",
+        autoAlpha: 0,
+        duration: 0.42,
+        ease: "power3.inOut",
+      }, cue + 0.04)
+      .fromTo(opts.shadow ?? toTarget, { boxShadow: "0 -40px 80px rgba(0,0,0,0.35)" }, {
+        boxShadow: "0 0 0 rgba(0,0,0,0)",
+        duration: 0.36,
+        ease: "power2.out",
+      }, cue + 0.28);
+    return tl;
+  }
+
+  function datavizLandscapeOpen(tl, bars, labels, cue = 0, opts = {}) {
+    tl.fromTo(bars, {
+      scaleY: 0,
+      transformOrigin: "50% 100%",
+    }, {
+      scaleY: 1,
+      duration: opts.duration ?? 0.86,
+      stagger: opts.stagger ?? 0.035,
+      ease: "expo.out",
+    }, cue)
+      .fromTo(labels, { y: 18, autoAlpha: 0 }, {
+        y: 0,
+        autoAlpha: 1,
+        duration: 0.34,
+        stagger: opts.stagger ?? 0.035,
+        ease: "power2.out",
+      }, cue + 0.24);
+    return tl;
+  }
+
+  function panelGridReflow(tl, panels, cue = 0, opts = {}) {
+    const gsap = gsapRef();
+    const panelList = gsap.utils.toArray(panels);
+    panelList.forEach((panel, index) => {
+      tl.fromTo(panel, {
+        xPercent: index % 2 === 0 ? -18 : 18,
+        yPercent: index % 3 === 0 ? -12 : 12,
+        rotateZ: index % 2 === 0 ? -3 : 3,
+        autoAlpha: 0,
+      }, {
+        xPercent: 0,
+        yPercent: 0,
+        rotateZ: 0,
+        autoAlpha: 1,
+        duration: opts.duration ?? 0.58,
+        ease: "expo.out",
+      }, cue + index * (opts.stagger ?? 0.045));
+    });
+    return tl;
+  }
+
+  function brandResolve(tl, tiles, wordmark, cue = 0, opts = {}) {
+    tl.to(tiles, {
+      x: 0,
+      y: 0,
+      rotateZ: 0,
+      scale: 0.78,
+      duration: opts.gatherDuration ?? 0.54,
+      stagger: opts.stagger ?? 0.025,
+      ease: "power3.inOut",
+    }, cue)
+      .to(tiles, { autoAlpha: 0, scale: 0.48, duration: 0.2, ease: "power2.in" }, cue + 0.48)
+      .fromTo(wordmark, { autoAlpha: 0, scale: 0.86, filter: "blur(10px)" }, {
+        autoAlpha: 1,
+        scale: 1,
+        filter: "blur(0px)",
+        duration: 0.42,
+        ease: "expo.out",
+      }, cue + 0.54);
+    return tl;
+  }
+
+  global.HyperAnimatorShotCraftMotion = {
+    slamEntrance,
+    whipTransition,
+    crashZoom,
+    pushStackWipe,
+    datavizLandscapeOpen,
+    panelGridReflow,
+    brandResolve,
+  };
+})(window);

package/skills/hyper-animator-codex/scripts/git_checkpoint.mjs

@@ -193,7 +193,7 @@ function parsePorcelainLine(line) {
 }
 
 function porcelainLines(pathspecs = []) {
-  const args = ["status", "--porcelain=v1", "--untracked-files=all"];
+  const args = ["-c", "core.quotePath=false", "status", "--porcelain=v1", "--untracked-files=all"];
 
   if (pathspecs.length > 0) {
     args.push("--", ...pathspecs);
@@ -230,7 +230,7 @@ function trackedOrUntrackedMatching(pathspecs) {
 }
 
 function stagedFiles() {
-  return git(["diff", "--cached", "--name-only", "--diff-filter=ACDMR"], { check: true }).stdout
+  return git(["-c", "core.quotePath=false", "diff", "--cached", "--name-only", "--diff-filter=ACDMR"], { check: true }).stdout
     .split("\n")
     .map((line) => line.trim())
     .filter(Boolean)

package/skills/hyper-animator-codex/scripts/validate_shot_plan.mjs

@@ -5,6 +5,28 @@ import { fileURLToPath } from "node:url";
 
 const scriptDir = dirname(fileURLToPath(import.meta.url));
 const skillRoot = dirname(scriptDir);
+const WORKFLOW_STAGES = new Set(["visual_draft", "audio_integrated", "render_ready"]);
+const AUDIO_MODES = new Set(["generated", "user_local_file", "none", "deferred"]);
+const ENERGY_LEVELS = new Set(["quiet", "balanced", "high", "cinematic"]);
+const MOTION_PRESETS = new Set([
+  "none",
+  "slam-entrance",
+  "whip-transition",
+  "crash-zoom",
+  "push-stack-wipe",
+  "dataviz-landscape-open",
+  "panel-grid-reflow",
+  "brand-resolve",
+]);
+const SHOTCRAFT_MOTION_PRESETS = new Map([
+  ["slam-entrance-moves", "slam-entrance"],
+  ["shot-transitions", "whip-transition"],
+  ["crash-zoom-punch", "crash-zoom"],
+  ["bottom-push-stack-wipe", "push-stack-wipe"],
+  ["dataviz-landscape-open", "dataviz-landscape-open"],
+  ["panel-grid-moves", "panel-grid-reflow"],
+  ["ui-to-brand-morph", "brand-resolve"],
+]);
 
 function isObject(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -16,8 +38,8 @@ function validateAudioTrack(track, label, errors) {
     return;
   }
 
-  if (!["generated", "user_local_file", "none"].includes(track.mode)) {
-    errors.push(`audio.${label}.mode must be generated, user_local_file, or none`);
+  if (!AUDIO_MODES.has(track.mode)) {
+    errors.push(`audio.${label}.mode must be generated, user_local_file, none, or deferred`);
   }
   if (track.mode === "generated" && track.provider !== "minimax_cn") {
     errors.push(`audio.${label}.provider must be minimax_cn when mode is generated`);
@@ -25,8 +47,48 @@ function validateAudioTrack(track, label, errors) {
   if (track.mode === "user_local_file" && (typeof track.path !== "string" || !track.path.trim())) {
     errors.push(`audio.${label}.path is required when mode is user_local_file`);
   }
-  if (track.mode === "none" && track.provider !== undefined) {
-    errors.push(`audio.${label}.provider must be omitted when mode is none`);
+  if ((track.mode === "none" || track.mode === "deferred") && track.provider !== undefined) {
+    errors.push(`audio.${label}.provider must be omitted when mode is ${track.mode}`);
+  }
+  if ((track.mode === "none" || track.mode === "deferred") && track.path !== undefined) {
+    errors.push(`audio.${label}.path must be omitted when mode is ${track.mode}`);
+  }
+}
+
+function validateMotionContract(contract, label, shotcraftRefs, errors) {
+  if (!isObject(contract)) {
+    errors.push(`${label}.motion_contract is required`);
+    return;
+  }
+
+  if (!MOTION_PRESETS.has(contract.motion_preset)) {
+    errors.push(`${label}.motion_contract.motion_preset must be one of ${[...MOTION_PRESETS].join(", ")}`);
+  }
+  const expectedPresets = shotcraftRefs
+    .map((reference) => SHOTCRAFT_MOTION_PRESETS.get(reference))
+    .filter(Boolean);
+  if (expectedPresets.length > 0 && !expectedPresets.includes(contract.motion_preset)) {
+    errors.push(`${label}.motion_contract.motion_preset must use ${expectedPresets.join(" or ")} for selected ShotCraft refs`);
+  }
+  if (!ENERGY_LEVELS.has(contract.energy)) {
+    errors.push(`${label}.motion_contract.energy must be quiet, balanced, high, or cinematic`);
+  }
+  for (const field of ["camera", "transition"]) {
+    if (typeof contract[field] !== "string" || !contract[field].trim()) {
+      errors.push(`${label}.motion_contract.${field} is required`);
+    }
+  }
+  if (!Array.isArray(contract.shotcraft_commitments) || contract.shotcraft_commitments.length === 0) {
+    errors.push(`${label}.motion_contract.shotcraft_commitments must contain at least one item`);
+  } else {
+    contract.shotcraft_commitments.forEach((commitment, index) => {
+      if (typeof commitment !== "string" || !commitment.trim()) {
+        errors.push(`${label}.motion_contract.shotcraft_commitments[${index}] must be a non-empty string`);
+      }
+    });
+  }
+  if (!Number.isFinite(contract.readable_rest_seconds) || contract.readable_rest_seconds < 0) {
+    errors.push(`${label}.motion_contract.readable_rest_seconds must be zero or greater`);
   }
 }
 
@@ -35,6 +97,9 @@ function validateShotPlan(plan, catalogs) {
 
   if (!isObject(plan)) return ["plan must be a JSON object"];
   if (plan.schema_version !== "1.0.0") errors.push("schema_version must be 1.0.0");
+  if (!WORKFLOW_STAGES.has(plan.workflow_stage)) {
+    errors.push("workflow_stage must be visual_draft, audio_integrated, or render_ready");
+  }
   if (!["assemble_existing_catalog_items", "generate_new_hyperframes_html"].includes(plan.generation_mode)) {
     errors.push("generation_mode is invalid");
   }
@@ -56,6 +121,12 @@ function validateShotPlan(plan, catalogs) {
   } else {
     validateAudioTrack(plan.audio.narration, "narration", errors);
     validateAudioTrack(plan.audio.bgm, "bgm", errors);
+    if (plan.workflow_stage === "visual_draft" && plan.audio.narration?.mode === "generated") {
+      errors.push("audio.narration must not be generated before visual confirmation");
+    }
+    if (plan.workflow_stage !== "visual_draft" && plan.audio.narration?.mode === "deferred") {
+      errors.push("audio.narration.mode cannot stay deferred after visual confirmation");
+    }
   }
 
   if (!isObject(plan.model_routing)) {
@@ -102,6 +173,9 @@ function validateShotPlan(plan, catalogs) {
     if (!Array.isArray(shot.hyperframes_refs)) {
       errors.push(`${label}.hyperframes_refs must be an array`);
     } else {
+      if (shot.hyperframes_refs.length === 0) {
+        errors.push(`${label}.hyperframes_refs must contain at least one HyperFrames reference`);
+      }
       for (const reference of shot.hyperframes_refs) {
         if (!catalogs.hyperframes.has(reference)) {
           errors.push(`${label} has unknown HyperFrames reference: ${reference}`);
@@ -111,17 +185,16 @@ function validateShotPlan(plan, catalogs) {
     if (!Array.isArray(shot.shotcraft_refs)) {
       errors.push(`${label}.shotcraft_refs must be an array`);
     } else {
+      if (shot.shotcraft_refs.length === 0) {
+        errors.push(`${label}.shotcraft_refs must contain at least one ShotCraft reference`);
+      }
       for (const reference of shot.shotcraft_refs) {
         if (!catalogs.shotcraft.has(reference)) {
           errors.push(`${label} has unknown ShotCraft reference: ${reference}`);
         }
       }
     }
-    if (Array.isArray(shot.hyperframes_refs)
-      && Array.isArray(shot.shotcraft_refs)
-      && shot.hyperframes_refs.length + shot.shotcraft_refs.length === 0) {
-      errors.push(`${label} must reference at least one catalog`);
-    }
+    validateMotionContract(shot.motion_contract, label, Array.isArray(shot.shotcraft_refs) ? shot.shotcraft_refs : [], errors);
 
     if (index === 0 && shot.start_seconds !== 0) {
       errors.push("shots must start at 0 seconds");