dsh-hyperframes 0.3.2 → 0.4.1

package/README.en.md

@@ -6,11 +6,11 @@
 
 [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
 
-DSH (DeepSeek Harness) video-creation skill plugin: installing it registers the twenty official HyperFrames by HeyGen skills into DSH (video from HTML: core workflow, animation, audio, captions, keyframes, creative templates, CLI, registry, website-to-video; synced with official v0.8.20).
+DSH (DeepSeek Harness) video-creation skill plugin: installing it registers the twenty-one official HyperFrames by HeyGen skills into DSH (video from HTML: core workflow, animation, audio, captions, keyframes, creative templates, CLI, registry, website-to-video; synced with official v0.8.82).
 
 ## Compatibility
 
-Verified with official `@deepseek-ai/dsh@0.1.5-rc.1` and Node `24.16.0` on 2026-09-11: all 18 components load alongside Modlens, with passing tool-schema, skill-registration and offline read-only invocation checks. Uses the `cordis.patch.yml` + `dsh.bundle.patch` bundle model. Node requirements match this Harness release: 22.19 or later within 22.x, or 24 or later. Live external-service workflows require separate configuration and validation.
+Validation host: Harness `0.2.0-rc.1` built from official sources (commit `407e65c8`) with Node `24.16.0` on 2026-09-28. All 23 plugin tests pass in an isolated environment; all 18 plugins mount together in one host registering 21 skills and 1 tools, with tool schemas and health-check contracts passing. No live ports or external services were exercised in this round.
 
 ## Installation
 
@@ -39,8 +39,9 @@ Then restart the web service. To clean up fully, also remove the plugin entry fr
 | `hyperframes-audio` | Audio: voiceovers, audio-reactive visuals |
 | `hyperframes-keyframes` | Keyframe animation |
 | `hyperframes-creative` | Creative templates and styles |
-| `hyperframes-cli` | `npx hyperframes` CLI (init/lint/inspect/preview/render/transcribe/tts/doctor) |
+| `hyperframes-cli` | `npx hyperframes` CLI (init/check/preview/render/timeline/publish/cloud/transcribe/tts/doctor, ...) |
 | `hyperframes-registry` | `hyperframes add` registry block installation and wiring |
+| `hyperframes-studio` | Studio timeline conventions: track layering, caption track, safe zones |
 | `embedded-captions` | Embedded captions |
 | `faceless-explainer` | Faceless explainer videos |
 | `figma` | Figma asset integration |
@@ -60,7 +61,7 @@ Node.js 22.19+ (22.x) / 24+ + FFmpeg (`npx hyperframes`).
 
 ## Porting notes
 
-Ported from the official OpenAI Codex HyperFrames by HeyGen plugin cache: frontmatter converted to the DSH format, Codex-only `agents/` stripped, and all internal references verified.
+Synced from the official `heygen-com/hyperframes` repository at v0.8.82 (2026-09-28): the complete packaged `skills/` tree, 21 skills, copied as-is with no frontmatter changes. Since v0.8.20, `hyperframes-studio` (Studio timeline conventions) is new, the brief/storyboard/script docs moved from `hyperframes-core` to the `hyperframes` skill, `media-use` and `music-to-video` were substantially reworked (built-in motion primitives), and the `embedded-captions` scripts were upgraded upstream.
 
 ## Multi-harness
 

package/README.md

@@ -2,18 +2,18 @@
 
 # dsh-hyperframes
 
-> **在 20+ 个 agent 里写视频**：HyperFrames by HeyGen 官方 20 技能，HTML 即视频。
+> **在 20+ 个 agent 里写视频**：HyperFrames by HeyGen 官方 21 技能，HTML 即视频。
 
 ![npm version](https://img.shields.io/npm/v/dsh-hyperframes?label=npm&color=blue) ![npm downloads](https://img.shields.io/npm/dm/dsh-hyperframes) ![license](https://img.shields.io/npm/l/dsh-hyperframes) ![stars](https://img.shields.io/github/stars/STARDUSTLC666/dsh-hyperframes?style=social)
 
 [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
 
 
-DSH（DeepSeek Harness）视频创作技能插件：**安装即把 HyperFrames by HeyGen 官方 20 个技能注册进 DSH**（HTML 写视频：核心工作流、动画、音频、字幕、关键帧、创意模板、CLI、注册表、网站转视频等，同步官方 v0.8.20）。
+DSH（DeepSeek Harness）视频创作技能插件：**安装即把 HyperFrames by HeyGen 官方 21 个技能注册进 DSH**（HTML 写视频：核心工作流、动画、音频、字幕、关键帧、创意模板、CLI、注册表、网站转视频等，同步官方 v0.8.82）。
 
 ## 兼容性
 
-已在官方 `@deepseek-ai/dsh@0.1.5-rc.1`、Node `24.16.0` 上验证（2026-09-11）：18 个组件与 Modlens 同载，工具 schema、技能注册及离线只读调用检查通过。采用 `cordis.patch.yml` + `dsh.bundle.patch` 组合包模型。Node 要求与该版本 Harness 一致：22.19 及以上的 22.x，或 24 及以上。外部服务的实际业务操作需按各组件配置单独验证。
+验证宿主：官方源码构建的 Harness `0.2.0-rc.1`（commit `407e65c8`）+ Node `24.16.0`（2026-09-28）。23 项插件测试在隔离环境全部通过；同一个宿主里 18 个插件共同加载，注册 21 个技能、1 个工具，工具 schema 与健康检查契约通过。本轮未启用真实端口与外部服务。
 
 ## 安装
 
@@ -42,8 +42,9 @@ dsh plugin --profile web remove dsh-hyperframes
 | `hyperframes-audio` | 音频：配音、音频响应视觉 |
 | `hyperframes-keyframes` | 关键帧动画 |
 | `hyperframes-creative` | 创意模板与风格 |
-| `hyperframes-cli` | `npx hyperframes` 命令行（init/lint/inspect/preview/render/transcribe/tts/doctor）|
+| `hyperframes-cli` | `npx hyperframes` 命令行（init/check/preview/render/timeline/publish/cloud/transcribe/tts/doctor…）|
 | `hyperframes-registry` | `hyperframes add` 注册表组件安装与接线 |
+| `hyperframes-studio` | Studio 时间轴规范：轨道分层、字幕轨、安全区 |
 | `embedded-captions` | 内嵌字幕 |
 | `faceless-explainer` | 无脸讲解视频 |
 | `figma` | Figma 素材接入 |
@@ -63,7 +64,7 @@ Node.js 22.19+ (22.x) / 24+ + FFmpeg（`npx hyperframes`）。
 
 ## 移植说明
 
-技能同步自官方仓库 `heygen-com/hyperframes` v0.8.20（2026-08-31）：官方 codex 插件打包的完整 `skills/` 目录；旧版五件套中的 `gsap`、`website-to-hyperframes` 已被上游合并进新技能体系。
+技能同步自官方仓库 `heygen-com/hyperframes` v0.8.82（2026-09-28）：官方打包的完整 `skills/` 目录，共 21 个技能。相较 v0.8.20，新增 `hyperframes-studio`（Studio 时间轴规范），`hyperframes-core` 的 brief/storyboard/script 等文档改由 `hyperframes` 技能承载，`media-use` 与 `music-to-video` 大幅重构（新增内置动态原语），`embedded-captions` 等脚本随官方升级。旧版五件套中的 `gsap`、`website-to-hyperframes` 已被上游合并进新技能体系。
 
 ## 跨平台使用
 

package/lib/index.d.ts

@@ -3,7 +3,7 @@ export { parseSkillFile } from './skill-bundle.js';
 export type { SkillRegistration, SkillsPluginContext } from './skill-bundle.js';
 export declare const name = "hyperframes-skills";
 export declare const inject: string[];
-export declare const SKILL_NAMES: readonly ["embedded-captions", "faceless-explainer", "figma", "general-video", "hyperframes", "hyperframes-animation", "hyperframes-audio", "hyperframes-cli", "hyperframes-core", "hyperframes-creative", "hyperframes-keyframes", "hyperframes-registry", "media-use", "motion-graphics", "music-to-video", "pr-to-video", "product-launch-video", "remotion-to-hyperframes", "slideshow", "talking-head-recut"];
+export declare const SKILL_NAMES: readonly ["embedded-captions", "faceless-explainer", "figma", "general-video", "hyperframes", "hyperframes-animation", "hyperframes-audio", "hyperframes-cli", "hyperframes-core", "hyperframes-creative", "hyperframes-keyframes", "hyperframes-registry", "hyperframes-studio", "media-use", "motion-graphics", "music-to-video", "pr-to-video", "product-launch-video", "remotion-to-hyperframes", "slideshow", "talking-head-recut"];
 /** Absolute resource root shipped in this independently installable package. */
 export declare function bundledSkillsDir(): string;
 /** Re-read and validate disk resources; runtime state is checked by the health tool. */

package/lib/index.js

@@ -21,6 +21,7 @@ export const SKILL_NAMES = [
     "hyperframes-creative",
     "hyperframes-keyframes",
     "hyperframes-registry",
+    "hyperframes-studio",
     "media-use",
     "motion-graphics",
     "music-to-video",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-hyperframes",
-  "version": "0.3.2",
-  "description": "DSH 视频创作技能插件：注册 HyperFrames by HeyGen 官方移植技能五件套（hyperframes / hyperframes-cli / hyperframes-registry / website-to-hyperframes / gsap），安装即用。",
+  "version": "0.4.1",
+  "description": "DSH 视频创作技能插件：注册 HyperFrames by HeyGen 官方移植技能（含 CLI 与官网转视频），安装即用。",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/skills/embedded-captions/SKILL.md

@@ -9,6 +9,8 @@ description: >
   including transcription and subject matting; split multi-shot footage before applying it.
 ---
 
+**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin. Standalone installs keep the update instructions below.
+
 > **First, keep this skill fresh — confirm with the user before running:** `npx hyperframes skills update embedded-captions`. A fast no-op when everything is current; otherwise it refreshes this skill plus the core domain skills it depends on before you rely on them.
 
 # Embedded Captions
@@ -17,6 +19,27 @@ description: >
 
 ---
 
+## Runtime prerequisites
+
+Plugin installs use the bundled, manifest-pinned CLI for matting, transcription,
+and rendering; no source checkout is required. The local preview and caption
+measurement helpers also need Sharp, Puppeteer (with its Chromium browser), and
+GSAP. Install these in the **caption project**, not inside the read-only plugin:
+
+```bash
+npm install --prefix <project> --save-dev --save-exact sharp@0.35.3 puppeteer@25.8.0 gsap@3.15.0
+```
+
+Keep the project's lockfile. If these dependencies already exist, use its locked
+versions instead of overwriting them. Bash and FFmpeg/ffprobe must be on PATH.
+Matting and transcription may download their own models on first use.
+
+Rendering waits for the CLI to exit successfully before compositing. The old
+`HF_TIMEOUT_S` shell watchdog is no longer used: a large partial file is not proof
+that rendering finished. An explicit built-checkout argument or `HYPERFRAMES_ROOT`
+selects the contributor CLI instead of the plugin pin. Cancel a stalled render normally through the CLI/terminal;
+the caption helper does not force-kill or recover a render from a process snapshot.
+
 ## Operational flow (TL;DR)
 
 Routed through `/hyperframes`, the intent layer confirms only the input (which clip) and **announces** the identity pick as a deferred ask — the shortlist needs the probed clip, so it stays at step 1 below; the layer's run-shape questions don't apply (the footage is untouched, there is no storyboard to review). A `BRIEF.md`, when present, carries the confirmed input and any user notes — read it first.
@@ -57,7 +80,7 @@ Rail-surface identities build exactly this (rail = `rail.html`, embed = the clim
 
 **One front-end, three engines behind.** The user picks an IDENTITY from [CATALOG.md](CATALOG.md) (35 entries: 10 classic + 25 themed); the engine, compiler and authoring file are derived by lookup from the catalog row. **Never surface "Standard vs Cinematic vs Theme" as a question** — those are backend names (a product has one UX even with several engines). The catalog encodes everything routing needs: reading surface, voice, recommend-for, scene needs, adjacency notes for the genuinely-close pairs (loud↔ordnance, neon↔neonsign, cream↔stardust).
 
-The identity pick is a **preference gate** (`../hyperframes-core/references/brief-contract.md` § 1): in autonomous mode ("surprise me" / "decide for me"), pick from your shortlist yourself and state the one-line why instead of asking.
+The identity pick is a **preference gate** (`../hyperframes/references/brief-contract.md` § 1): in autonomous mode ("surprise me" / "decide for me"), pick from your shortlist yourself and state the one-line why instead of asking.
 
 Procedure: probe the clip → shortlist 2–3 identities from the catalog → recommend ONE with a one-line why → **the user picks** (autonomous mode: you pick, stating the why) → author that identity's file. Identities are engine-locked (no cross combos; opening one is a validation event — see dna/README.md).
 
@@ -65,6 +88,8 @@ Procedure: probe the clip → shortlist 2–3 identities from the catalog → re
 
 (The full identity table lives in [CATALOG.md](CATALOG.md) — single source of truth for routing. The engine docs below describe each backend's authoring contract.)
 
+**CATALOG.md is the whole answer space here: this workflow does not search the HyperFrames component registry.** The composition workflows run `npx hyperframes catalog` before authoring a named look; this one must not. Its engines are locked compilers that consume `cinematic.json` / `theme.json` and emit the composition themselves, so a registry item — the `caption-*` blocks included — has nothing to mount into. A registry block styles text on a designed canvas; this skill burns captions into somebody's footage through a matte. When no identity fits the ask, say so and pick the nearest, rather than reaching outside the catalog.
+
 **Recommendation heuristic**: use the "Shortlisting heuristics" in [CATALOG.md](CATALOG.md) — they are identity-level (e.g. "炸" shortlists ordnance/stomp/terminal/loud and picks by WHAT should explode), never category-level. Unsure → `anchor`.
 
 - **Cinematic** → write `plan.json` for a locked template, compiled by `make-composition.cjs`.
@@ -248,8 +273,8 @@ The full **embed-track** playbook lives in **[references/composition-craft.md](r
 
 ## Dependencies
 
-- **hyperframes**, built (`packages/cli/dist/cli.js`). Scripts auto-resolve the checkout: `HYPERFRAMES_ROOT` env → repo root if this skill ships _inside_ hyperframes → `~/Downloads/hyperframes`. Build with `bun install && bun run build`.
-- **Node-first; two Python touchpoints via `uvx` (no manual installs):** transcription runs WhisperX through `uvx` (word-level timings; falls back per SKILL §transcription), and Theme's `drawon` setpiece shells `python3 scripts/gen-stroke-path.py` at compile time. Everything else runs on the toolchain hyperframes already ships: matting via the hyperframes CLI's **`remove-background`** (u2net_human_seg; weights auto-download once, ~168 MB, to `~/.cache/hyperframes/`), image/alpha math via **`sharp`**, layout/occlusion/overflow via **`puppeteer`**, plus **`ffmpeg`**. The scripts auto-resolve these from the hyperframes checkout — nothing extra to install.
+- **HyperFrames CLI:** plugin installs use the bundled manifest-pinned launcher. Source contributors can use a built checkout (`packages/cli/dist/cli.js`) via `HYPERFRAMES_ROOT`, the skill’s source tree, or `~/Downloads/hyperframes`.
+- **Node-first; two Python touchpoints via `uvx` (no manual installs):** transcription runs WhisperX through `uvx` (word-level timings; falls back per SKILL §transcription), and Theme's `drawon` setpiece shells `python3 scripts/gen-stroke-path.py` at compile time. Everything else runs on the toolchain hyperframes already ships: matting via the hyperframes CLI's **`remove-background`** (u2net_human_seg; weights auto-download once, ~168 MB, to `~/.cache/hyperframes/`), image/alpha math via **`sharp`**, layout/occlusion/overflow via **`puppeteer`**, plus **`ffmpeg`**. Install Sharp, Puppeteer, and GSAP in the caption project as described in **Runtime prerequisites** above. The helpers check that project first and retain checkout dependency lookup for source contributors.
 - **Transcription = WhisperX via `uvx`** (word-level timings + alignment; no manual install — `transcribe.cjs` drives `uvx whisperx`). Falls back to an existing word-level `transcript.json` if present.
 - **Source video** — `matte.cjs` / `transcribe.cjs` auto-resolve `source.mp4` (or glob the clip / read `hyperframes.json`), so `hyperframes init --video X.mp4` needs no manual rename.
 - **fps** — `matte.cjs` extracts at the source's native rate and records `matte.fps`; `render-and-composite.sh` uses that so the matte stays frame-aligned.

package/skills/embedded-captions/references/aesthetic-principles.md

@@ -121,9 +121,8 @@ Chunk at natural pauses ≥ 250ms. A caption spanning a breath-break feels wrong
 
 ### 17. Safe zones per platform, always
 
-- 9:16 TikTok/IG/Shorts: caption zone `y ∈ [12%, 78%]` (bottom 22% is UI)
-- 16:9 broadcast: title-safe = center 80%
-- TV export: 5% margin on all sides
+- Use the safe boxes in `/hyperframes-studio` (Safe zones) for wide and vertical
+  framings; that skill owns the values.
 
 Bake into the layout solver. Never eyeball.
 

package/skills/embedded-captions/references/rail.md

@@ -17,7 +17,7 @@ with only the climax(es) promoted to embed. Rail is not a fallback — it's the
 
 - **Lower third, horizontally centered.** Landscape (16:9): baseline ~80–120px above the
   bottom edge. Portrait (9:16): lower-middle, ~ 600–700px from the bottom (clear of platform UI).
-- **Title-safe margins:** keep text within ~90% width / inside any letterbox-pillarbox bars
+- **Title-safe margins:** keep text within the title-safe box (80% of the frame, `/hyperframes-studio` Safe zones) / inside any letterbox-pillarbox bars
   (see the letterbox probe). Never flush to the frame edge.
 - **One caption group on screen at a time.** No accumulation, no cascade — that's embed-track behaviour.
 - It rides above the subject; the matte does **not** occlude it (rail = in front).

package/skills/embedded-captions/scripts/check-occlusion.cjs

@@ -11,6 +11,7 @@ const cp = require("child_process");
 
 function hfResolve(pkg) {
   const roots = [
+    process.argv[2] && path.resolve(process.argv[2]), // project-owned helper dependencies
     process.env.HYPERFRAMES_ROOT,
     path.resolve(__dirname, "..", "..", ".."),
     path.join(os.homedir(), "Downloads", "hyperframes"),
@@ -29,7 +30,9 @@ function hfResolve(pkg) {
       } catch {}
     }
   }
-  console.error(`[v2] cannot find ${pkg} — set HYPERFRAMES_ROOT`);
+  console.error(
+    `[v2] cannot find ${pkg} — install project dependencies per embedded-captions SKILL.md Runtime prerequisites`,
+  );
   process.exit(3);
 }
 const sharp = hfResolve("sharp");

package/skills/embedded-captions/scripts/check-overflow.cjs

@@ -18,6 +18,7 @@ const fs = require("fs");
 const os = require("os");
 
 const HF_ROOTS = [
+  process.argv[2] && path.resolve(process.argv[2]), // project-owned helper dependencies
   process.env.HYPERFRAMES_ROOT,
   path.resolve(__dirname, "../../.."),
   path.join(os.homedir(), "Downloads", "hyperframes"),

package/skills/embedded-captions/scripts/check-rail-climax.cjs

@@ -20,6 +20,7 @@ const fs = require("fs");
 const os = require("os");
 
 const HF_ROOTS = [
+  process.argv[2] && path.resolve(process.argv[2]), // project-owned helper dependencies
   process.env.HYPERFRAMES_ROOT,
   path.resolve(__dirname, "../../.."),
   path.join(os.homedir(), "Downloads", "hyperframes"),
@@ -154,7 +155,10 @@ async function main() {
   const railPath = path.join(project, "rail.html");
   if (!fs.existsSync(railPath) || !fs.existsSync(indexPath))
     ok("[rail-climax] no rail.html+index.html — not Standard, skipping");
-  if (!puppeteer) ok("[rail-climax] puppeteer unavailable — skipping (set HYPERFRAMES_ROOT)");
+  if (!puppeteer)
+    ok(
+      "[rail-climax] puppeteer unavailable — skipping (install project dependencies per embedded-captions SKILL.md Runtime prerequisites)",
+    );
 
   const exe =
     process.platform === "darwin"

package/skills/embedded-captions/scripts/fixtures/heroless/theme.json

@@ -0,0 +1,11 @@
+{
+  "width": 1280,
+  "height": 720,
+  "fps": 24,
+  "duration": 6,
+  "lines": [
+    ["quiet", "captions"],
+    ["continue", "without"],
+    ["a", "hero"]
+  ]
+}

package/skills/embedded-captions/scripts/hf-cli.cjs

@@ -0,0 +1,33 @@
+// Resolve CLI ownership once for matting, transcription, and shell rendering.
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+function hfCli(checkout) {
+  const root = path.resolve(__dirname, "../../..");
+  for (const dir of [checkout, process.env.HYPERFRAMES_ROOT].filter(Boolean)) {
+    const cli = path.join(dir, "packages/cli/dist/cli.js");
+    if (fs.existsSync(cli)) return cli;
+  }
+  const manifests = [
+    "plugin.json",
+    ".claude-plugin/plugin.json",
+    ".codex-plugin/plugin.json",
+    ".cursor-plugin/plugin.json",
+    "gemini-extension.json",
+  ];
+  if (
+    !fs.existsSync(path.join(root, "packages/cli/dist/cli.js")) &&
+    manifests.some((p) => fs.existsSync(path.join(root, p)))
+  ) {
+    return path.join(root, "skills/hyperframes/scripts/plugin-cli.mjs");
+  }
+  for (const dir of [root, path.join(os.homedir(), "Downloads/hyperframes")].filter(Boolean)) {
+    const cli = path.join(dir, "packages/cli/dist/cli.js");
+    if (fs.existsSync(cli)) return cli;
+  }
+  throw new Error(
+    "HyperFrames CLI unavailable: install the full plugin or set HYPERFRAMES_ROOT to a built checkout.",
+  );
+}
+module.exports = { hfCli };
+if (require.main === module) console.log(hfCli(process.argv[2]));