hyper-animator-codex 0.8.1 → 0.8.3

package/README.md

@@ -77,14 +77,13 @@ generate music and voiceover without asking for credentials later:
 ```bash
 npx hyper-animator-codex install --force \
   --minimax-api-key "$MINIMAX_API_KEY" \
-  --minimax-group-id "$MINIMAX_GROUP_ID" \
-  --minimax-model music-2.6-free
+  --minimax-model music-3.0-free
 ```
 
 Environment fallback is also supported:
 
 ```bash
-MINIMAX_API_KEY=... MINIMAX_GROUP_ID=... npx hyper-animator-codex install --force
+MINIMAX_API_KEY=... npx hyper-animator-codex install --force
 ```
 
 Or load a JSON config file:
@@ -107,7 +106,8 @@ Preview HTML can include a bottom page indicator and thin draggable progress bar
 
 ```bash
 node skills/hyper-animator-codex/scripts/inject_preview_controls.mjs composition.html -o composition.preview.html --force
-python3 skills/hyper-animator-codex/scripts/validate_hyperframes_html.py composition.preview.html --preview-controls
+python3 skills/hyper-animator-codex/scripts/validate_hyperframes_html.py composition.preview.html \
+  --preview-controls --shot-plan shot-plan.json
 ```
 
 The injected controls support dragging the progress bar and using ArrowLeft or ArrowRight to move between pages.
@@ -197,15 +197,17 @@ Validate a dual-catalog plan before authoring:
 
 ```bash
 node skills/hyper-animator-codex/scripts/validate_shot_plan.mjs shot-plan.json
+python3 skills/hyper-animator-codex/scripts/validate_hyperframes_html.py composition.html --shot-plan shot-plan.json
 ```
 
-When model routing is available, `gpt-5.6-sol` is reserved for page generation
-and animation authoring. Planning, discovery, audio prompting, validation, and
-packaging use a faster cost-efficient model.
+When model routing is available, the client's `high_quality` tier is reserved
+for page generation and animation authoring. Planning, discovery, audio
+prompting, validation, and packaging use its `fast` tier; the shot plan records
+the actual model names.
 
 ## Contents
 
-- `skills/hyper-animator-codex/SKILL.md`: Codex skill instructions.
+- `skills/hyper-animator-codex/SKILL.md`: Codex and Claude Code skill instructions.
 - `skills/hyper-animator-codex/contracts/`: provider/model policy and shot-plan schema.
 - `skills/hyper-animator-codex/references/`: HyperFrames catalog, ShotCraft knowledge bundle, authoring patterns, workflows, and examples.
 - `skills/hyper-animator-codex/scripts/query_shotcraft.mjs`: ShotCraft intent/reference search.

package/bin/hyper-animator-codex.mjs

@@ -25,12 +25,12 @@ Options:
   --quiet                         Suppress successful install output
   --target <dir>                  Install into one specific skills directory
   --minimax-api-key <key>         Save MiniMax API key into installed skill config
-  --minimax-group-id <group_id>   Save MiniMax group_id into installed skill config
-  --minimax-model <model>         MiniMax text music model: music-3.0, music-2.6, or music-2.6-free
-  --minimax-config <file>         Load MiniMax JSON config with api_key, group_id, and model
+  --minimax-group-id <group_id>   Optional legacy account metadata
+  --minimax-model <model>         MiniMax text music model; default music-3.0
+  --minimax-config <file>         Load MiniMax JSON config with api_key and optional model
 
 Environment fallback:
-  MINIMAX_API_KEY, MINIMAX_GROUP_ID, MINIMAX_MODEL
+  MINIMAX_API_KEY, MINIMAX_MODEL (MINIMAX_GROUP_ID remains optional)
 `);
 }
 

package/lib/install-skill.mjs

@@ -1,6 +1,6 @@
-import { chmod, cp, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { chmod, cp, mkdir, mkdtemp, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import {
@@ -84,46 +84,75 @@ async function restoreExistingMinimaxConfig(installedPath, existingConfig) {
 
 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 sourcePath = resolve(options.sourcePath || join(packageRoot, "skills", SKILL_NAME));
+  const installedPath = resolve(targetRoot, SKILL_NAME);
   const force = Boolean(options.force);
 
+  if (sourcePath === installedPath
+    || sourcePath.startsWith(`${installedPath}${sep}`)
+    || installedPath.startsWith(`${sourcePath}${sep}`)) {
+    throw new Error(`Source and install paths overlap: ${sourcePath} -> ${installedPath}`);
+  }
   if (!(await pathExists(sourcePath))) {
     throw new Error(`Packaged skill not found at ${sourcePath}`);
   }
 
   await mkdir(targetRoot, { recursive: true });
-
-  const existingMinimaxConfig = force ? await readExistingMinimaxConfig(installedPath) : null;
-
-  if (await pathExists(installedPath)) {
+  const installExists = await pathExists(installedPath);
+  if (installExists) {
     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,
-  });
-
   const resolvedMinimaxConfig = await resolveInstallMinimaxConfig({
     cliConfig: options.minimaxConfig || {},
     env: options.env || process.env,
   });
-  const minimaxWrite = resolvedMinimaxConfig
-    ? await writeMinimaxConfig(installedPath, resolvedMinimaxConfig)
-    : null;
-  const restoredMinimaxConfigPath = minimaxWrite ? null : await restoreExistingMinimaxConfig(installedPath, existingMinimaxConfig);
+  const existingMinimaxConfig = force ? await readExistingMinimaxConfig(installedPath) : null;
+  const stagingRoot = await mkdtemp(join(resolve(targetRoot), `.${SKILL_NAME}-install-`));
+  const stagingPath = join(stagingRoot, SKILL_NAME);
+  let backupRoot = null;
+  let backupPath = null;
+
+  try {
+    await cp(sourcePath, stagingPath, {
+      recursive: true,
+      filter: shouldCopy,
+    });
+    if (resolvedMinimaxConfig) {
+      await writeMinimaxConfig(stagingPath, resolvedMinimaxConfig);
+    } else {
+      await restoreExistingMinimaxConfig(stagingPath, existingMinimaxConfig);
+    }
+
+    if (installExists) {
+      backupRoot = await mkdtemp(join(resolve(targetRoot), `.${SKILL_NAME}-backup-`));
+      backupPath = join(backupRoot, SKILL_NAME);
+      await rename(installedPath, backupPath);
+    }
+    try {
+      await rename(stagingPath, installedPath);
+    } catch (error) {
+      if (backupPath && await pathExists(backupPath)) {
+        await rename(backupPath, installedPath);
+      }
+      throw error;
+    }
+  } finally {
+    await rm(stagingRoot, { recursive: true, force: true });
+    if (backupRoot) await rm(backupRoot, { recursive: true, force: true });
+  }
 
   return {
     skillName: SKILL_NAME,
     tool: options.tool || "codex",
     sourcePath,
     installedPath,
-    minimaxConfigPath: minimaxWrite ? minimaxWrite.configPath : restoredMinimaxConfigPath,
-    minimaxConfig: minimaxWrite ? redactMinimaxConfig(minimaxWrite.config) : null,
+    minimaxConfigPath: resolvedMinimaxConfig || existingMinimaxConfig
+      ? join(installedPath, MINIMAX_CONFIG_RELATIVE_PATH)
+      : null,
+    minimaxConfig: resolvedMinimaxConfig ? redactMinimaxConfig(resolvedMinimaxConfig) : null,
   };
 }
 

package/lib/minimax-config.mjs

@@ -1,8 +1,8 @@
 import { chmod, mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
-export const DEFAULT_MINIMAX_MODEL = "music-2.6";
-export const TEXT_MUSIC_MODELS = new Set(["music-3.0", "music-2.6", "music-2.6-free"]);
+export const DEFAULT_MINIMAX_MODEL = "music-3.0";
+export const TEXT_MUSIC_MODELS = new Set(["music-3.0", "music-3.0-free", "music-2.6", "music-2.6-free"]);
 export const MINIMAX_CONFIG_RELATIVE_PATH = join("config", "minimax.json");
 
 async function pathExists(path) {
@@ -62,19 +62,15 @@ export function validateMinimaxConfig(config = {}) {
     throw new Error("MiniMax api_key is required when MiniMax config is provided");
   }
 
-  if (!normalized.group_id) {
-    throw new Error("MiniMax group_id is required when MiniMax config is provided");
-  }
-
   const model = normalized.model || DEFAULT_MINIMAX_MODEL;
 
   if (!TEXT_MUSIC_MODELS.has(model)) {
-    throw new Error(`Unsupported MiniMax text music model: ${model}. Use music-3.0, music-2.6, or music-2.6-free.`);
+    throw new Error(`Unsupported MiniMax text music model: ${model}. Use music-3.0, music-3.0-free, music-2.6, or music-2.6-free.`);
   }
 
   return {
     api_key: normalized.api_key,
-    group_id: normalized.group_id,
+    ...(normalized.group_id ? { group_id: normalized.group_id } : {}),
     model,
   };
 }
@@ -156,7 +152,7 @@ export function redactMinimaxConfig(config = {}) {
 
   return {
     api_key: normalized.api_key ? "[redacted]" : undefined,
-    group_id: normalized.group_id,
+    ...(normalized.group_id ? { group_id: normalized.group_id } : {}),
     model: normalized.model || DEFAULT_MINIMAX_MODEL,
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyper-animator-codex",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "Install the Hyper Animator skill for Codex and Claude Code.",
   "type": "module",
   "bin": {
@@ -8,11 +8,13 @@
   },
   "scripts": {
     "postinstall": "node bin/postinstall.mjs",
+    "build:contracts": "node tools/build-shot-plan-validator.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"
+    "pack:check": "npm pack --dry-run",
+    "prepublishOnly": "npm run check"
   },
   "files": [
     "bin/",
@@ -39,5 +41,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "devDependencies": {
+    "ajv": "^8.17.1"
   }
 }

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

@@ -1,6 +1,6 @@
 ---
 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 assembly, new HyperFrames HTML, outline/narration detection, voiceover, subtitles, sound effects, background music, rhythm, BPM, final mixing, or beat-synced transitions.
+description: Use when a user asks a coding agent 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 assembly, new HyperFrames HTML, outline/narration detection, voiceover, subtitles, sound effects, background music, rhythm, BPM, final mixing, or beat-synced transitions.
 ---
 
 # Hyper Animator Codex
@@ -24,15 +24,15 @@ Turn a natural-language animation or video brief into a validated HyperFrames HT
 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 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.
+10. Apply capability-based model routing when model selection is available: use the client's `high_quality` model for page and animation authoring only, and a `fast` cost-efficient model for requirements, discovery, catalog queries, shot planning, audio prompting, validation, and packaging. On Codex, prefer `gpt-5.6-sol` and `gpt-5.6-terra` respectively; on Claude Code, record the actual Claude models selected. Do not create an extra agent/entity only to implement this routing.
+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, provider-neutral model routing tiers plus actual model names, 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`.
+17. Mark every shot root with `data-shot-id` and `data-motion-preset`, then run `scripts/validate_hyperframes_html.py composition.html --shot-plan shot-plan.json` so planned ShotCraft motion is proven in executable HTML.
+18. Read `references/preview-controls-workflow.md`, run `scripts/inject_preview_controls.mjs` to create a preview HTML copy (with play/pause and interactive autoplay), and run `scripts/validate_hyperframes_html.py preview.html --preview-controls --shot-plan shot-plan.json`.
 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.
@@ -40,7 +40,7 @@ Turn a natural-language animation or video brief into a validated HyperFrames HT
 
 ## 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.
+Prefer the current client's interactive question tool when available. If unavailable, ask the same questions as ordinary concise text and continue after the user answers.
 
 Use two rounds:
 
@@ -86,7 +86,7 @@ Hard constraints beat score:
 Before render, run:
 
 ```bash
-python3 scripts/validate_hyperframes_html.py path/to/composition.html
+python3 scripts/validate_hyperframes_html.py path/to/composition.html --shot-plan path/to/shot-plan.json
 ```
 
 Generated block HTML must include:
@@ -96,6 +96,8 @@ Generated block HTML must include:
 - scoped CSS under `[data-composition-id="..."]` or another unique composition selector;
 - `gsap.timeline({ paused: true })`;
 - `window.__timelines[id]` registration;
+- one `data-shot-id` and matching `data-motion-preset` per planned shot;
+- a real motion-pack helper call for every supported non-`none` preset;
 - no unresolved `<!-- paste from ... -->` placeholders;
 - no wall-clock `Date.now()` or `setInterval()` driving primary timeline progress;
 - no `Math.random()` for visual generation; use a fixed-seed deterministic PRNG;
@@ -105,7 +107,7 @@ Generated block HTML must include:
 Preview HTML must pass:
 
 ```bash
-python3 scripts/validate_hyperframes_html.py path/to/composition.preview.html --preview-controls
+python3 scripts/validate_hyperframes_html.py path/to/composition.preview.html --preview-controls --shot-plan path/to/shot-plan.json
 ```
 
 If the validator fails, fix the HTML before asking the user to approve render.
@@ -140,7 +142,7 @@ Before rendering, summarize:
 
 - generation mode;
 - shot-plan validator result and selected HyperFrames/ShotCraft references per shot;
-- model routing used, including confirmation that Sol was limited to page/animation authoring;
+- model routing used, including confirmation that the high-quality tier was limited to page/animation authoring;
 - detected outline/narration paths, ambiguity status, and any outline/narration generation assumptions;
 - selected or referenced catalog items;
 - narration usage, selected voice, emotion, voice audio path, subtitle style, subtitle JSON/SRT paths, and voice/BGM/SFX volume values when applicable;

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

@@ -17,7 +17,7 @@
   ],
   "properties": {
     "schema_version": {
-      "const": "1.0.0"
+      "const": "1.1.0"
     },
     "workflow_stage": {
       "enum": [
@@ -82,12 +82,32 @@
       ],
       "properties": {
         "page_animation_authoring": {
-          "const": "gpt-5.6-sol"
+          "allOf": [
+            {
+              "$ref": "#/$defs/modelRoute"
+            },
+            {
+              "properties": {
+                "tier": {
+                  "const": "high_quality"
+                }
+              }
+            }
+          ]
         },
         "planning_and_validation": {
-          "not": {
-            "const": "gpt-5.6-sol"
-          }
+          "allOf": [
+            {
+              "$ref": "#/$defs/modelRoute"
+            },
+            {
+              "properties": {
+                "tier": {
+                  "const": "fast"
+                }
+              }
+            }
+          ]
         }
       }
     },
@@ -106,6 +126,26 @@
     }
   },
   "$defs": {
+    "modelRoute": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "tier",
+        "actual_model"
+      ],
+      "properties": {
+        "tier": {
+          "enum": [
+            "high_quality",
+            "fast"
+          ]
+        },
+        "actual_model": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
     "audioTrack": {
       "type": "object",
       "additionalProperties": false,

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

@@ -47,14 +47,20 @@
   },
   "model_routing": {
     "page_animation_authoring": {
-      "model": "gpt-5.6-sol",
+      "tier": "high_quality",
+      "preferred_models": {
+        "codex": "gpt-5.6-sol"
+      },
       "use_for": [
         "page_generation",
         "animation_authoring"
       ]
     },
     "planning_and_validation": {
-      "model": "gpt-5.6-terra",
+      "tier": "fast",
+      "preferred_models": {
+        "codex": "gpt-5.6-terra"
+      },
       "use_for": [
         "requirements",
         "file_detection",

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

@@ -1,5 +1,5 @@
 {
-  "schema_version": "1.0.0",
+  "schema_version": "1.1.0",
   "workflow_stage": "visual_draft",
   "generation_mode": "generate_new_hyperframes_html",
   "catalog_strategy": "dual_catalog",
@@ -18,8 +18,14 @@
     }
   },
   "model_routing": {
-    "page_animation_authoring": "gpt-5.6-sol",
-    "planning_and_validation": "gpt-5.6-terra"
+    "page_animation_authoring": {
+      "tier": "high_quality",
+      "actual_model": "gpt-5.6-sol"
+    },
+    "planning_and_validation": {
+      "tier": "fast",
+      "actual_model": "gpt-5.6-terra"
+    }
   },
   "shots": [
     {

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

@@ -184,9 +184,11 @@ Round 2 不选择 voice/emotion，也不生成字幕。旁白选择放到视觉
 
 ## Model Routing
 
-- `gpt-5.6-sol` 仅用于页面生成和动画编写。
+- 页面生成和动画编写使用当前客户端的 `high_quality` 层级模型；
+  Codex 优先 `gpt-5.6-sol`。
 - 需求抽取、文件检测、catalog 查询、镜头计划、音频提示词、校验和打包
-  使用 `gpt-5.6-terra` 或同级快速经济模型。
+  使用当前客户端的 `fast` 层级模型；Codex 优先 `gpt-5.6-terra`。
+- 在 shot plan 中记录层级和实际模型名；Claude Code 不要伪填 GPT 型号。
 - 不为模型路由自动新增 Agent 或其他实体；在运行环境支持模型选择时才
   应用路由。
 

package/skills/hyper-animator-codex/references/minimax-music-workflow.md

@@ -26,17 +26,15 @@ The installed config shape is:
 ```json
 {
   "api_key": "[redacted]",
-  "group_id": "group_id",
-  "model": "music-2.6-free"
+  "model": "music-3.0"
 }
 ```
 
-Do not print or echo the raw API key. `group_id` is stored because the installer collects it, but the current `/v1/music_generation` API call uses only `Authorization: Bearer <API_key>` and the documented JSON request body.
+Do not print or echo the raw API key. `group_id` is optional legacy account
+metadata and is not required by the current `/v1/music_generation` call.
 
-The wrapper accepts `music-3.0`, `music-2.6`, and `music-2.6-free`. The stable
-installer default remains `music-2.6` for backward compatibility; choose
-`music-3.0` explicitly when the account has access and the user wants the
-current model.
+The wrapper accepts `music-3.0`, `music-3.0-free`, `music-2.6`, and
+`music-2.6-free`. The installer default is `music-3.0`.
 
 ## Clarify Music
 

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

@@ -19,7 +19,7 @@ Rules:
 - 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.
+The coding agent 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,
@@ -31,8 +31,7 @@ and animation direction. A visual draft shot plan should use
 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 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.
+analysis dependency during a run. Do not add a Kokoro runtime or component.
 
 Before a generated-audio call, validate the route:
 
@@ -53,7 +52,7 @@ Use this shape:
 
 ```json
 {
-  "voice": "XiaoR_001",
+  "voice": "male-qn-qingse",
   "emotion": "calm",
   "language": "zh",
   "style": "casual",

package/skills/hyper-animator-codex/references/preview-controls-workflow.md

@@ -4,7 +4,7 @@ Use this whenever a generated or assembled HyperFrames HTML animation will be sh
 
 ## Required Behavior
 
-HTML previews should include a bottom page indicator and thin progress bar. Users can drag the progress bar to seek, or press ArrowLeft and ArrowRight to move between pages.
+HTML previews should include a bottom page indicator, play/pause button, and thin progress bar. The preview copy must start the registered timeline in interactive mode; users can pause/resume, drag the progress bar to seek, or press ArrowLeft and ArrowRight to move between pages. Never show the paused base composition as the interactive preview.
 
 Video renders must hide those controls. Use one of these render-hidden signals:
 
@@ -12,6 +12,8 @@ Video renders must hide those controls. Use one of these render-hidden signals:
 - `?preview=0`
 - `<html data-render-mode="video">`
 
+The main render timeline should remain `paused: true` for deterministic frame capture. Preview controls are responsible for calling `timeline.play()`/`timeline.pause()` and must skip autoplay when any render-hidden signal is active.
+
 ## Page Model
 
 Prefer explicit page starts:
@@ -34,7 +36,7 @@ After the base HTML passes normal quality gates, create a preview copy:
 
 ```bash
 node scripts/inject_preview_controls.mjs composition.html -o composition.preview.html --force
-python3 scripts/validate_hyperframes_html.py composition.preview.html --preview-controls
+python3 scripts/validate_hyperframes_html.py composition.preview.html --preview-controls --shot-plan shot-plan.json
 ```
 
 Show the preview copy to the user for validation.

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

@@ -108,7 +108,7 @@ Options:
   --format <mp3|wav|pcm>       Audio encoding format, default mp3
   --sample-rate <rate>         16000, 24000, 32000, or 44100; default 44100
   --bitrate <bits>             32000, 64000, 128000, or 256000; default 256000
-  --model <model>              music-3.0, music-2.6, or music-2.6-free
+  --model <model>              music-3.0, music-3.0-free, music-2.6, or music-2.6-free
   --config <file>              Explicit MiniMax config JSON
   --request-json <file>        Read request options from a JSON file
   --dry-run                    Print redacted request without contacting MiniMax
@@ -270,8 +270,12 @@ function safeFileStem(prompt) {
   return stem || "minimax-music";
 }
 
-async function downloadUrl(url) {
-  const response = await fetch(url);
+async function downloadUrl(url, timeoutMs) {
+  const parsed = URL.canParse(url) ? new URL(url) : null;
+  if (!parsed || !["http:", "https:"].includes(parsed.protocol)) {
+    throw minimaxError("MiniMax audio URL must use HTTP or HTTPS", { kind: "response" });
+  }
+  const response = await fetchWithTimeout(url, {}, timeoutMs);
 
   if (!response.ok) {
     throw new Error(`MiniMax audio URL download failed with HTTP ${response.status}`);
@@ -429,7 +433,7 @@ async function callMiniMaxWithRetries(config, request, { endpoint, timeoutMs, ma
   throw minimaxError("MiniMax request failed", { kind: "network", retryable: true, attempts });
 }
 
-async function writeAudioOutput({ responseJson, request, outputDir, prompt, endpoint }) {
+async function writeAudioOutput({ responseJson, request, outputDir, prompt, endpoint, timeoutMs }) {
   await mkdir(outputDir, { recursive: true });
 
   const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
@@ -439,7 +443,7 @@ async function writeAudioOutput({ responseJson, request, outputDir, prompt, endp
   const metadataPath = join(outputDir, `${stem}.minimax.json`);
   const audioValue = responseJson.data.audio;
   const audioBuffer = request.output_format === "url"
-    ? await downloadUrl(audioValue)
+    ? await downloadUrl(audioValue, timeoutMs)
     : decodeHexAudio(audioValue);
 
   await writeFile(audioPath, audioBuffer);
@@ -496,7 +500,7 @@ async function main() {
     }
 
     if (!runtime) {
-      throw Object.assign(new Error("MiniMax config not found. Run hyper-animator-codex install with --minimax-api-key and --minimax-group-id, or set MINIMAX_API_KEY and MINIMAX_GROUP_ID."), {
+      throw Object.assign(new Error("MiniMax config not found. Run hyper-animator-codex install with --minimax-api-key, or set MINIMAX_API_KEY."), {
         kind: "config",
         retryable: false,
       });
@@ -539,6 +543,7 @@ async function main() {
       outputDir: options.output_dir,
       prompt: options.prompt,
       endpoint,
+      timeoutMs,
     });
 
     printJson({