dsh-hyperframes 0.1.0

package/README.en.md

@@ -0,0 +1,35 @@
+[中文](README.md)
+
+# dsh-hyperframes
+
+DSH (DeepSeek Harness) video-creation skill plugin: installing it registers the five official HyperFrames by HeyGen skills into DSH (video from HTML: compositions, GSAP animation, captions, voiceovers, audio-reactive visuals, website-to-video).
+
+## Installation
+
+```bash
+dsh plugin --profile web add dsh-hyperframes
+```
+
+After restarting, say "turn this website into a HyperFrames video" to trigger it.
+
+## Skills
+
+| Skill | Purpose |
+| :-- | :-- |
+| `hyperframes` | HTML video compositions: visual styles/palettes/captions/audio-reactive/transitions |
+| `hyperframes-cli` | `npx hyperframes` CLI (init/lint/inspect/preview/render/transcribe/tts/doctor) |
+| `hyperframes-registry` | `hyperframes add` registry block installation and wiring |
+| `website-to-hyperframes` | Seven-step website-to-video pipeline |
+| `gsap` | GSAP animation API reference (tweens/timelines/easing/performance) |
+
+## Requirements
+
+Node.js ≥ 22 + 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.
+
+## License
+
+MIT for the porting arrangement; skill content copyright remains with HeyGen.

package/README.md

@@ -0,0 +1,35 @@
+[English](README.en.md)
+
+# dsh-hyperframes
+
+DSH（DeepSeek Harness）视频创作技能插件：**安装即把 HyperFrames by HeyGen 官方移植技能五件套注册进 DSH**（HTML 写视频：合成、GSAP 动画、字幕、配音、音频响应、网址转视频）。
+
+## 安装
+
+```bash
+dsh plugin --profile web add dsh-hyperframes
+```
+
+重启后说「把这个网址做成 HyperFrames 视频」即可触发。
+
+## 技能清单
+
+| 技能 | 用途 |
+| :-- | :-- |
+| `hyperframes` | HTML 视频合成：视觉风格/调色板/字幕/音频响应/转场 |
+| `hyperframes-cli` | `npx hyperframes` 命令行（init/lint/inspect/preview/render/transcribe/tts/doctor）|
+| `hyperframes-registry` | `hyperframes add` 注册表组件安装与接线 |
+| `website-to-hyperframes` | 网址转视频七步流水线 |
+| `gsap` | GSAP 动画 API 参考（tween/timeline/缓动/性能）|
+
+## 依赖
+
+Node.js ≥ 22 + FFmpeg（`npx hyperframes`）。
+
+## 移植说明
+
+技能移植自 OpenAI Codex 官方 HyperFrames by HeyGen 插件缓存：frontmatter 已转换为 DSH 格式，codex 专属 `agents/` 已剔除，全部内部引用校验。
+
+## License
+
+MIT（移植编排）；技能内容版权归 HeyGen。

package/cordis.patch.yml

@@ -0,0 +1,7 @@
+# dsh-hyperframes 组合包补丁：把HyperFrames 技能插件行插入 profile。
+# 插件加载即把技能注册进 ctx.skills（技能目录实时可见），无需配置。
+#
+- insert:
+    - id: hyperframes-skills
+      name: 'dsh-hyperframes'
+      config: {}

package/lib/index.d.ts

@@ -0,0 +1,35 @@
+/** cordis 服务注入：apply 里要用 ctx.skills，必须显式声明。 */
+export declare const inject: string[];
+/** 技能注册定义（最小面）。 */
+export interface SkillRegistration {
+    name: string;
+    description: string;
+    content: string;
+    resourceBase: {
+        kind: 'directory';
+        path: string;
+    };
+    source?: string;
+}
+/** 插件所需的最小 ctx 面。 */
+export interface SkillsPluginContext {
+    skills: {
+        register(definition: SkillRegistration): () => void;
+    };
+    on?(event: string, listener: () => void): () => void;
+}
+/** 随包分发的技能清单。 */
+export declare const SKILL_NAMES: readonly ["hyperframes", "hyperframes-cli", "hyperframes-registry", "website-to-hyperframes", "gsap"];
+/** 打包技能目录的绝对路径。 */
+export declare function bundledSkillsDir(): string;
+/** 拆分 SKILL.md 的 frontmatter 与正文。 */
+export declare function parseSkillFile(text: string): {
+    name: string;
+    description: string;
+    content: string;
+};
+/**
+ * 插件入口：把技能注册进技能注册表。
+ * 单个技能文件缺失只告警，不影响其余技能与宿主启动。
+ */
+export declare function apply(ctx: SkillsPluginContext): void;

package/lib/index.js

@@ -0,0 +1,74 @@
+/**
+ * dsh-hyperframes —— HyperFrames by HeyGen 视频创作技能插件：加载即把技能注册进 ctx.skills。
+ *
+ * 技能正文与资源随包分发（skills/ 目录），resourceBase 指向打包目录，
+ * 技能正文里的相对引用（rules/、references/ 等）由技能加载器解析。
+ *
+ * @module dsh-hyperframes
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+import YAML from 'yaml';
+/** cordis 服务注入：apply 里要用 ctx.skills，必须显式声明。 */
+export const inject = ['skills'];
+/** 随包分发的技能清单。 */
+export const SKILL_NAMES = ["hyperframes", "hyperframes-cli", "hyperframes-registry", "website-to-hyperframes", "gsap"];
+/** 打包技能目录的绝对路径。 */
+export function bundledSkillsDir() {
+    return fileURLToPath(new URL('../skills/', import.meta.url));
+}
+/** 拆分 SKILL.md 的 frontmatter 与正文。 */
+export function parseSkillFile(text) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(text);
+    if (!match)
+        return { name: '', description: '', content: text };
+    let name = '';
+    let description = '';
+    try {
+        const parsed = YAML.parse(match[1]);
+        if (typeof parsed === 'object' && parsed !== null) {
+            const record = parsed;
+            if (typeof record.name === 'string')
+                name = record.name;
+            if (typeof record.description === 'string')
+                description = record.description;
+        }
+    }
+    catch { /* 保留空值，由调用方处理 */ }
+    return { name, description, content: text.slice(match[0].length).trimStart() };
+}
+/**
+ * 插件入口：把技能注册进技能注册表。
+ * 单个技能文件缺失只告警，不影响其余技能与宿主启动。
+ */
+export function apply(ctx) {
+    const disposers = [];
+    for (const skillName of SKILL_NAMES) {
+        try {
+            const dir = join(bundledSkillsDir(), skillName);
+            const text = readFileSync(join(dir, 'SKILL.md'), 'utf8');
+            const parsed = parseSkillFile(text);
+            if (parsed.name === '' || parsed.description === '' || parsed.content === '') {
+                console.warn('[dsh-hyperframes] 技能 ' + skillName + ' 的 frontmatter 不完整，已跳过。');
+                continue;
+            }
+            disposers.push(ctx.skills.register({
+                name: parsed.name,
+                description: parsed.description,
+                content: parsed.content,
+                resourceBase: { kind: 'directory', path: dir },
+                source: 'runtime',
+            }));
+        }
+        catch (error) {
+            console.warn('[dsh-hyperframes] 技能 ' + skillName + ' 加载失败：' + (error instanceof Error ? error.message : String(error)));
+        }
+    }
+    if (typeof ctx.on === 'function') {
+        ctx.on('dispose', () => {
+            for (const dispose of disposers)
+                dispose();
+        });
+    }
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "dsh-hyperframes",
+  "version": "0.1.0",
+  "description": "DSH 视频创作技能插件：注册 HyperFrames by HeyGen 官方移植技能五件套（hyperframes / hyperframes-cli / hyperframes-registry / website-to-hyperframes / gsap），安装即用。",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "skills",
+    "cordis.patch.yml",
+    "README.md",
+    "README.en.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepare": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "pnpm run build && node --test \"test/*.test.mjs\"",
+    "prepublishOnly": "pnpm run build"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "skills",
+    "video"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.6.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/STARDUSTLC666/dsh-hyperframes"
+  },
+  "bugs": {
+    "url": "https://github.com/STARDUSTLC666/dsh-hyperframes/issues"
+  },
+  "homepage": "https://github.com/STARDUSTLC666/dsh-hyperframes#readme",
+  "author": "stardustlc",
+  "packageManager": "pnpm@11.7.0"
+}

package/skills/gsap/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: gsap
+description: "GSAP animation reference for HyperFrames. Covers gsap.to(), from(), fromTo(), easing, stagger, defaults, timelines (gsap.timeline(), position parameter, labels, nesting, playback), and performance (transforms, will-change, quickTo). Use when writing GSAP animations in HyperFrames compositions. 中文：在 HyperFrames 合成里写 GSAP 动画时使用。"
+compatibility: Pure reference; GSAP ships inside HyperFrames compositions, no local install needed.
+allowed-tools: Bash
+---
+
+# GSAP
+
+## Core Tween Methods
+
+- **gsap.to(targets, vars)** — animate from current state to `vars`. Most common.
+- **gsap.from(targets, vars)** — animate from `vars` to current state (entrances).
+- **gsap.fromTo(targets, fromVars, toVars)** — explicit start and end.
+- **gsap.set(targets, vars)** — apply immediately (duration 0).
+
+Always use **camelCase** property names (e.g. `backgroundColor`, `rotationX`).
+
+## Common vars
+
+- **duration** — seconds (default 0.5).
+- **delay** — seconds before start.
+- **ease** — `"power1.out"` (default), `"power3.inOut"`, `"back.out(1.7)"`, `"elastic.out(1, 0.3)"`, `"none"`.
+- **stagger** — number `0.1` or object: `{ amount: 0.3, from: "center" }`, `{ each: 0.1, from: "random" }`.
+- **overwrite** — `false` (default), `true`, or `"auto"`.
+- **repeat** — number or `-1` for infinite. **yoyo** — alternates direction with repeat.
+- **onComplete**, **onStart**, **onUpdate** — callbacks.
+- **immediateRender** — default `true` for from()/fromTo(). Set `false` on later tweens targeting the same property+element to avoid overwrite.
+
+## Transforms and CSS
+
+Prefer GSAP's **transform aliases** over raw `transform` string:
+
+| GSAP property               | Equivalent          |
+| --------------------------- | ------------------- |
+| `x`, `y`, `z`               | translateX/Y/Z (px) |
+| `xPercent`, `yPercent`      | translateX/Y in %   |
+| `scale`, `scaleX`, `scaleY` | scale               |
+| `rotation`                  | rotate (deg)        |
+| `rotationX`, `rotationY`    | 3D rotate           |
+| `skewX`, `skewY`            | skew                |
+| `transformOrigin`           | transform-origin    |
+
+- **autoAlpha** — prefer over `opacity`. At 0: also sets `visibility: hidden`.
+- **CSS variables** — `"--hue": 180`.
+- **svgOrigin** _(SVG only)_ — global SVG coordinate space origin. Don't combine with `transformOrigin`.
+- **Directional rotation** — `"360_cw"`, `"-170_short"`, `"90_ccw"`.
+- **clearProps** — `"all"` or comma-separated; removes inline styles on complete.
+- **Relative values** — `"+=20"`, `"-=10"`, `"*=2"`.
+
+## Function-Based Values
+
+```javascript
+gsap.to(".item", {
+  x: (i, target, targets) => i * 50,
+  stagger: 0.1,
+});
+```
+
+## Easing
+
+Built-in eases: `power1`–`power4`, `back`, `bounce`, `circ`, `elastic`, `expo`, `sine`. Each has `.in`, `.out`, `.inOut`.
+
+## Defaults
+
+```javascript
+gsap.defaults({ duration: 0.6, ease: "power2.out" });
+```
+
+## Controlling Tweens
+
+```javascript
+const tween = gsap.to(".box", { x: 100 });
+tween.pause();
+tween.play();
+tween.reverse();
+tween.kill();
+tween.progress(0.5);
+tween.time(0.2);
+```
+
+## gsap.matchMedia() (Responsive + Accessibility)
+
+Runs setup only when a media query matches; auto-reverts when it stops matching.
+
+```javascript
+let mm = gsap.matchMedia();
+mm.add(
+  {
+    isDesktop: "(min-width: 800px)",
+    reduceMotion: "(prefers-reduced-motion: reduce)",
+  },
+  (context) => {
+    const { isDesktop, reduceMotion } = context.conditions;
+    gsap.to(".box", {
+      rotation: isDesktop ? 360 : 180,
+      duration: reduceMotion ? 0 : 2,
+    });
+  },
+);
+```
+
+---
+
+## Timelines
+
+### Creating a Timeline
+
+```javascript
+const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } });
+tl.to(".a", { x: 100 }).to(".b", { y: 50 }).to(".c", { opacity: 0 });
+```
+
+### Position Parameter
+
+Third argument controls placement:
+
+- **Absolute**: `1` — at 1s
+- **Relative**: `"+=0.5"` — after end; `"-=0.2"` — before end
+- **Label**: `"intro"`, `"intro+=0.3"`
+- **Alignment**: `"<"` — same start as previous; `">"` — after previous ends; `"<0.2"` — 0.2s after previous starts
+
+```javascript
+tl.to(".a", { x: 100 }, 0);
+tl.to(".b", { y: 50 }, "<"); // same start as .a
+tl.to(".c", { opacity: 0 }, "<0.2"); // 0.2s after .b starts
+```
+
+### Labels
+
+```javascript
+tl.addLabel("intro", 0);
+tl.to(".a", { x: 100 }, "intro");
+tl.addLabel("outro", "+=0.5");
+tl.play("outro");
+tl.tweenFromTo("intro", "outro");
+```
+
+### Timeline Options
+
+- **paused: true** — create paused; call `.play()` to start.
+- **repeat**, **yoyo** — apply to whole timeline.
+- **defaults** — vars merged into every child tween.
+
+### Nesting Timelines
+
+```javascript
+const master = gsap.timeline();
+const child = gsap.timeline();
+child.to(".a", { x: 100 }).to(".b", { y: 50 });
+master.add(child, 0);
+```
+
+### Playback Control
+
+`tl.play()`, `tl.pause()`, `tl.reverse()`, `tl.restart()`, `tl.time(2)`, `tl.progress(0.5)`, `tl.kill()`.
+
+---
+
+## Performance
+
+### Prefer Transform and Opacity
+
+Animating `x`, `y`, `scale`, `rotation`, `opacity` stays on the compositor. Avoid `width`, `height`, `top`, `left` when transforms achieve the same effect.
+
+### will-change
+
+```css
+will-change: transform;
+```
+
+Only on elements that actually animate.
+
+### gsap.quickTo() for Frequent Updates
+
+```javascript
+let xTo = gsap.quickTo("#id", "x", { duration: 0.4, ease: "power3" }),
+  yTo = gsap.quickTo("#id", "y", { duration: 0.4, ease: "power3" });
+container.addEventListener("mousemove", (e) => {
+  xTo(e.pageX);
+  yTo(e.pageY);
+});
+```
+
+### Stagger > Many Tweens
+
+Use `stagger` instead of separate tweens with manual delays.
+
+### Cleanup
+
+Pause or kill off-screen animations.
+
+---
+
+## References (loaded on demand)
+
+- **[references/effects.md](references/effects.md)** — Drop-in effects: typewriter text, audio visualizer. Read when needing ready-made effect patterns for HyperFrames.
+
+## Best Practices
+
+- Use camelCase property names; prefer transform aliases and autoAlpha.
+- Prefer timelines over chaining with delay; use the position parameter.
+- Add labels with `addLabel()` for readable sequencing.
+- Pass defaults into timeline constructor.
+- Store tween/timeline return value when controlling playback.
+
+## Do Not
+
+- Animate layout properties (width/height/top/left) when transforms suffice.
+- Use both svgOrigin and transformOrigin on the same SVG element.
+- Chain animations with delay when a timeline can sequence them.
+- Create tweens before the DOM exists.
+- Skip cleanup — always kill tweens when no longer needed.