dsh-hyperframes 0.9.1 → 0.9.3

package/skills/hyperframes/references/types/vertical.md

@@ -0,0 +1,23 @@
+# Vertical and social clips (9:16)
+
+Made at 1080×1920 when the request or the platform says vertical; a landscape film is not squeezed into it but recomposed.
+
+## The platform's own UI
+
+The app draws over the frame. On 1080×1920: nothing in the top 168 px (status and search bar); every word and the product inside the band from 168 to 1330 px; below 1330 px (caption, handle, buttons) only texture or decoration; no text under the right-hand action rail. Ads and some apps reserve more at the bottom; check the platform the clip is for. Burned-in captions sit at the bottom of the band (`../captions.md`).
+
+## The first second
+
+- Frame 0 is the thumbnail and the hook: a face, the result, or one bold line already on screen. Never black, never a logo.
+- The viewer decides in about a second whether to stay: the change or the question arrives in the first beat.
+- Many viewers watch muted: speech is captioned, and the picture carries the hook without sound.
+
+## Layout
+
+- One subject, centred, stacked vertically; landscape layouts (side-by-side panels, wide charts) are rebuilt as a vertical sequence.
+- Type is larger than in landscape (titles about ×1.35, `../overlays.md`); nothing meant to be read under 28 px, and a fixed word limit per line (about 8 Chinese characters or 5 English words for a claim): cut words, never shrink.
+- Talking heads: punch-ins on emphasis, B-roll cut on the sentence, the face never under a card (`../overlays.md`).
+
+## Pacing
+
+Faster than landscape: shots of 1–2 s, a new beat every 2–4 s, the payoff before the swipe. A loop that cuts from the last frame back to the first is a choice, not a default.

package/skills/{motion-graphics/categories/maps → hyperframes/scripts}/bake-basemap.mjs

@@ -1,10 +1,10 @@
-// bake-basemap.mjs — canonical basemap-lane helper for the `maps` skill.
+// bake-basemap.mjs — bake a real-imagery map camera move for a composition (references/film.md, "Maps").
 //
 // WHAT IT DOES (and why baking at all): drives MapLibre in headless Chrome to record ONLY the
 // real-imagery basemap as an MP4 (camera zoom→hold), and projects each requested country's border
 // to SCREEN coordinates at the held view. The HF composition then plays the MP4 on track 0 and
 // animates a *live* SVG overlay (border draw-on, colour-block / flag fills, labels, pins) from the
-// exported `coords.json`. Borders/fills are NOT baked into the video — they stay editable in HF.
+// exported `<NAME>-coords.json`. Borders/fills are NOT baked into the video — they stay editable in HF.
 //
 // Why bake the imagery at all (this is the real reason, not "smoothness"): HF forbids render-time
 // network and requires deterministic output. Live raster tiles re-fetch every render and can change
@@ -15,16 +15,32 @@
 // PARAMETRIC — drive everything by env. Example (Brazil + Argentina on satellite):
 //   NAME=br-ar STYLE=satellite COUNTRIES="Brazil:#22d3ee,Argentina:#f59e0b" \
 //   CENTER="-60,-25" ZSTART=2.4 ZEND=3.4 FPS=30 DUR=5 node bake-basemap.mjs
-// Then encode frames-<NAME>/f%04d.png → <NAME>.mp4 (all-intra: -g 1) and feed <NAME>-coords.json
-// to the HF composition.
-import puppeteer from "puppeteer-core";
-import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
+// From space down to a street (globe, starfield, a turn from FROM to CENTER, then the dive):
+//   NAME=mbs PROJECTION=globe FROM="18,16" CENTER="103.8607,1.2834" ZSTART=1.85 ZEND=16.2 \
+//   PITCH=40 DUR=10 HOLD=0.8 node bake-basemap.mjs
+// It encodes frames-<NAME>/f%04d.png → <NAME>.mp4 (all-intra: -g 1) and writes <NAME>-coords.json
+// for the HF composition. One bake at a time: several headless Chromes on a small machine stall.
+import { join } from "node:path";
 import { mkdirSync, writeFileSync, readdirSync, existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { spawnSync } from "node:child_process";
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
+if (process.argv.includes("--help") || process.argv.includes("-h")) {
+  console.log(`usage: [NAME=..] [STYLE=satellite|dark|light|<{z}/{x}/{y} url>] [CENTER="lng,lat"]
+       [PROJECTION=mercator|globe] [FROM="lng,lat"] [PAN=0.35] [ZSTART=..] [ZEND=..] [PITCH=..]
+       [BEARING=..] [FPS=30] [DUR=5] [HOLD=0.5] [COUNTRIES="Name:#hex,Name:#hex"] [OUT=dir]
+       [CHROME=path] node bake-basemap.mjs
+PROJECTION=globe starts from Earth in space (starfield, atmosphere) and flattens as it zooms in.
+FROM pans the camera from that point to CENTER over the first PAN of the move, while the zoom
+runs from PAN/2 to HOLD; ZSTART about 1.8 frames the whole globe, ZEND 16 is a building.
+Writes <OUT>/<NAME>.mp4 (all-intra basemap) and <OUT>/<NAME>-coords.json (projected borders).
+Needs puppeteer-core, ffmpeg, a Chrome or chrome-headless-shell, and network for the tiles.
+Run one bake at a time; it prints its pace and an estimate as it goes.`);
+  process.exit(0);
+}
+
+// Loaded after the --help check so usage prints without puppeteer-core installed.
+const { default: puppeteer } = await import("puppeteer-core");
 
 // --- resolve Chrome dynamically (no hardcoded machine path) ---
 function resolveChrome() {
@@ -69,6 +85,9 @@ const FPS = +(process.env.FPS || 30),
   DUR = +(process.env.DUR || 5),
   N = Math.max(1, Math.round(FPS * DUR));
 const HOLD = +(process.env.HOLD || 0.5); // p∈[0,1] at which the zoom finishes; camera holds after
+const PROJECTION = process.env.PROJECTION === "globe" ? "globe" : "mercator";
+const FROM = process.env.FROM ? process.env.FROM.split(",").map(Number) : null; // pan start; null = no pan
+const PAN = +(process.env.PAN || 0.35); // p at which the pan from FROM reaches CENTER
 const MARGIN = (process.env.KEEPMARGIN || "16,13").split(",").map(Number); // [lon°,lat°] keep-box around each country's mainland
 // COUNTRIES="Name:#hex,Name:#hex" — borders to project (optional; omit for a pure zoom-to / pin shot)
 const COUNTRIES = (process.env.COUNTRIES || "")
@@ -91,6 +110,8 @@ for (const [k, v] of Object.entries({
   FPS,
   DUR,
   HOLD,
+  PAN,
+  ...(FROM ? { "FROM.lng": FROM[0], "FROM.lat": FROM[1] } : {}),
 }))
   if (!Number.isFinite(v))
     throw new Error(
@@ -112,21 +133,43 @@ const OUT = process.env.OUT || process.cwd(); // artifacts → workspace (cwd),
 const framesDir = join(OUT, "frames-" + NAME);
 mkdirSync(framesDir, { recursive: true });
 
+// A seeded star field behind the globe, so every bake of the same move is identical.
+let seed = 7;
+const rnd = () => (seed = (seed * 16807) % 2147483647) / 2147483647;
+const STARS = `<svg id="stars" width="1920" height="1080">${Array.from({ length: 260 }, () => {
+  const x = (rnd() * 1920).toFixed(0),
+    y = (rnd() * 1080).toFixed(0);
+  const r = (rnd() * 1.3 + 0.3).toFixed(2),
+    a = (rnd() * 0.6 + 0.2).toFixed(2);
+  return `<circle cx="${x}" cy="${y}" r="${r}" fill="#fff" opacity="${a}"/>`;
+}).join("")}</svg>`;
+
 // Deps PINNED exact (mutable @5/@2 majors would drift the bake over time).
 const PAGE = `<!doctype html><html><head>
 <link href="https://cdn.jsdelivr.net/npm/maplibre-gl@5.24.0/dist/maplibre-gl.css" rel="stylesheet">
 <script src="https://cdn.jsdelivr.net/npm/maplibre-gl@5.24.0/dist/maplibre-gl.js"></script>
 <script src="https://cdn.jsdelivr.net/npm/topojson-client@3.1.0/dist/topojson-client.min.js"></script>
-<style>*{margin:0}html,body{width:1920px;height:1080px;overflow:hidden;background:#05070d}#map{width:1920px;height:1080px}.maplibregl-control-container{display:none!important}</style>
-</head><body><div id="map"></div><script>
+<style>*{margin:0}html,body{width:1920px;height:1080px;overflow:hidden;background:radial-gradient(ellipse at 50% 55%,#0b1630 0%,#050812 55%,#020308 100%)}#stars{position:absolute;inset:0}#map{position:absolute;inset:0;width:1920px;height:1080px}.maplibregl-control-container{display:none!important}</style>
+</head><body>${PROJECTION === "globe" ? STARS : ""}<div id="map"></div><script>
 var CENTER=${JSON.stringify(CENTER)}, ZSTART=${ZSTART}, ZEND=${ZEND}, PITCH=${PITCH}, BEARING=${BEARING}, HOLD=${HOLD};
+var FROM=${JSON.stringify(FROM)}, PAN=${PAN};
 var MARGIN=${JSON.stringify(MARGIN)}, WANT=${JSON.stringify(COUNTRIES)};
-var map=new maplibregl.Map({container:"map",style:{version:8,projection:{type:"mercator"},
+var GLOBE=${PROJECTION === "globe"};
+// On the globe the page behind the map shows through (stars), and the atmosphere fades out as the camera nears the ground.
+var map=new maplibregl.Map({container:"map",style:{version:8,projection:{type:GLOBE?"globe":"mercator"},
+  sky:GLOBE?{"atmosphere-blend":["interpolate",["linear"],["zoom"],0,1,5,1,7,0]}:undefined,
   sources:{s:{type:"raster",tiles:[${JSON.stringify(TILES)}],tileSize:256,maxzoom:19}},
-  layers:[{id:"bg",type:"background",paint:{"background-color":"#05070d"}},{id:"s",type:"raster",source:"s"}]},
-  center:CENTER,zoom:ZSTART,pitch:0,bearing:0,interactive:false,attributionControl:false,fadeDuration:0,preserveDrawingBuffer:true,maxTileCacheSize:6000});
+  layers:(GLOBE?[]:[{id:"bg",type:"background",paint:{"background-color":"#05070d"}}]).concat([{id:"s",type:"raster",source:"s"}])},
+  center:FROM||CENTER,zoom:ZSTART,pitch:0,bearing:0,interactive:false,attributionControl:false,fadeDuration:0,preserveDrawingBuffer:true,maxTileCacheSize:6000,
+  canvasContextAttributes:{alpha:GLOBE,preserveDrawingBuffer:true}});
 function ease(x){return x<0.5?4*x*x*x:1-Math.pow(-2*x+2,3)/2;} // easeInOutCubic (= Remotion interpolate+Easing)
-function camAt(p){ var t=ease(Math.min(1,p/HOLD)); return {center:CENTER, zoom:ZSTART+(ZEND-ZSTART)*t, pitch:PITCH*t, bearing:BEARING*t}; }
+function sine(x){return -(Math.cos(Math.PI*x)-1)/2;}
+function seg(p,a,b){return b<=a?1:Math.min(1,Math.max(0,(p-a)/(b-a)));}
+// With FROM, the camera turns to CENTER over [0,PAN] while the zoom runs over [PAN/2,HOLD]; without it, the zoom runs over [0,HOLD].
+function camAt(p){
+  var s=FROM?sine(seg(p,0,PAN)):1, t=ease(seg(p,FROM?PAN/2:0,HOLD));
+  var c=FROM?[FROM[0]+(CENTER[0]-FROM[0])*s, FROM[1]+(CENTER[1]-FROM[1])*s]:CENTER;
+  return {center:c, zoom:ZSTART+(ZEND-ZSTART)*t, pitch:PITCH*t, bearing:BEARING*t}; }
 function ringCentroid(r){ var sx=0,sy=0; for(var k=0;k<r.length;k++){sx+=r[k][0];sy+=r[k][1];} return [sx/r.length, sy/r.length]; }
 // Keep the polygons in a lon/lat box around the country's MAINLAND (the vertex-richest polygon),
 // dropping far-flung overseas territories that would blow up the bbox. Generalizes per subject —
@@ -164,10 +207,12 @@ window.__ready=new Promise(function(res){ map.on("load", function(){
   });
 });});
 window.__setCam=function(p){ map.jumpTo(camAt(p)); };
-// returns true if the idle event did NOT fire within ms (i.e. tiles may be incomplete)
-// returns true only if tiles are GENUINELY not loaded at timeout — CARTO/Esri idle is flaky and
-// often never fires even when every tile is painted, so check areTilesLoaded() before crying timeout.
-window.__waitIdle=function(ms){ return new Promise(function(res){ var done=false; function fin(t){if(done)return;done=true;res(t);} map.once("idle",function(){fin(false);}); setTimeout(function(){ fin(!map.areTilesLoaded()); }, ms||9000); }); };
+// Resolves false once every tile for this camera is loaded and painted, true if ms passed first.
+// Polls rather than waiting for "idle": that event can fire before a listener is attached, which
+// left every cached frame sitting out the whole timeout.
+window.__waitIdle=function(ms){ return new Promise(function(res){ var t0=performance.now();
+  (function poll(){ if(map.loaded()&&map.areTilesLoaded()){ map.triggerRepaint(); requestAnimationFrame(function(){requestAnimationFrame(function(){res(false);});}); return; }
+    if(performance.now()-t0>(ms||9000)){ res(!map.areTilesLoaded()); return; } setTimeout(poll,40); })(); }); };
 function featurePath(f){ function ring(r){ return r.map(function(c,i){ var p=map.project(c); return (i?"L":"M")+p.x.toFixed(1)+" "+p.y.toFixed(1); }).join(" ")+"Z"; }
   var g=f.geometry,d=""; if(g.type==="Polygon") g.coordinates.forEach(function(r){d+=ring(r);}); else g.coordinates.forEach(function(poly){poly.forEach(function(r){d+=ring(r);});}); return d; }
 function bboxOf(f){ var mnx=1e9,mny=1e9,mxx=-1e9,mxy=-1e9;
@@ -202,8 +247,9 @@ try {
   await page.evaluate(() => window.__ready);
   for (const w of await page.evaluate(() => window.__warn)) console.warn(`[${NAME}] WARN: ${w}`);
   console.log(
-    `[${NAME}] ready (${STYLE}); baking ${N} frames, zoom ${ZSTART}→${ZEND} hold@p=${HOLD}, ${COUNTRIES.length} border(s)`,
+    `[${NAME}] ready (${STYLE}, ${PROJECTION}); baking ${N} frames, zoom ${ZSTART}→${ZEND} hold@p=${HOLD}, ${COUNTRIES.length} border(s)`,
   );
+  const t0 = Date.now();
   let coords = null;
   const timeouts = [];
   for (let i = 0; i < N; i++) {
@@ -221,7 +267,12 @@ try {
     });
     if (p >= HOLD && !coords && COUNTRIES.length)
       coords = await page.evaluate(() => window.__project()); // capture at first hold frame
-    if (i % 20 === 0 || i === N - 1) console.log(`  [${NAME}] ${i + 1}/${N}`);
+    if (i % 20 === 0 || i === N - 1) {
+      const per = (Date.now() - t0) / 1000 / (i + 1);
+      console.log(
+        `  [${NAME}] ${i + 1}/${N} · ${per.toFixed(2)} s/frame · about ${Math.ceil((per * (N - i - 1)) / 60)} min left`,
+      );
+    }
   }
   // encode frames → all-intra MP4 (every frame seekable for HF); fall back to printing the command if ffmpeg is absent
   const mp4 = join(OUT, NAME + ".mp4"),

package/skills/hyperframes/scripts/lib/main-module.mjs

@@ -0,0 +1,13 @@
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+
+// Node resolves symlinks in the main module's import.meta.url but argv[1] keeps the invoked
+// spelling (a symlinked skills dir, or /tmp vs /private/tmp on macOS), so compare real paths.
+export function isMainModule(importMetaUrl) {
+  if (!process.argv[1]) return false;
+  try {
+    return pathToFileURL(realpathSync(process.argv[1])).href === importMetaUrl;
+  } catch {
+    return false;
+  }
+}

package/skills/hyperframes/scripts/lib/main-module.test.mjs

@@ -0,0 +1,46 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import { mkdtempSync, readFileSync, readdirSync, rmSync, symlinkSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { dirname, join, relative, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+const SKILLS = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
+const CLI_MEDIA_USE = resolve(SKILLS, "../packages/cli/src/media-use");
+
+// Agents install skills by symlinking the skills dir, so each script must still run its CLI.
+test("skill CLIs run when invoked through a symlinked skills dir", () => {
+  const dir = mkdtempSync(join(tmpdir(), "skills-link-"));
+  try {
+    symlinkSync(SKILLS, join(dir, "skills"), "dir");
+    for (const script of ["media-use/audio/scripts/heygen-voice.mjs"]) {
+      const run = spawnSync(process.execPath, [join(dir, "skills", script), "not-a-command"], {
+        encoding: "utf8",
+      });
+      assert.notEqual(run.status, 0, `${script} exited ${run.status} without running its CLI`);
+      assert.match(run.stderr, /usage/, script);
+    }
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+function skillScripts(dir) {
+  return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) return entry.name === "node_modules" ? [] : skillScripts(path);
+    return /\.(mjs|js)$/.test(entry.name) && !/\.test\.mjs$/.test(entry.name) ? [path] : [];
+  });
+}
+
+test("skill scripts detect their CLI entry through lib/main-module.mjs only", () => {
+  const handRolled = [...skillScripts(SKILLS), ...skillScripts(CLI_MEDIA_USE)].filter(
+    (path) =>
+      !path.endsWith("main-module.mjs") && readFileSync(path, "utf8").includes("process.argv[1]"),
+  );
+  assert.deepEqual(
+    handRolled.map((path) => relative(SKILLS, path)),
+    [],
+  );
+});

package/skills/{motion-graphics/grounding → hyperframes/scripts}/locate.mjs

@@ -5,7 +5,7 @@
  * "which numbered strip is the target in?" — so localization = RSVP grid-index
  * (ACL 2025 long.715): pick strips on a numbered grid, reconstruct the box
  * geometrically. Zero npm deps — node + ffmpeg (both already required by
- * hyperframes). Full protocol: grounding/PROTOCOL.md.
+ * hyperframes). Accuracy notes: references/film.md.
  *
  * THE LOOP (you read images between steps):
  *   1) node locate.mjs overlay <img> --out DIR

package/skills/hyperframes/scripts/plugin-cli.mjs

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 // Run from the user's project; locate the release from this installed file.
 import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join, win32 } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { fileURLToPath } from "node:url";
+import { isMainModule } from "./lib/main-module.mjs";
 
 const root = fileURLToPath(new URL("../../../", import.meta.url));
 const manifests = [
@@ -71,7 +72,7 @@ export function invocation(
   return { command: node, args: [npx, ...cliArgs], env: childEnv };
 }
 
-if (process.argv[1] && pathToFileURL(realpathSync(process.argv[1])).href === import.meta.url) {
+if (isMainModule(import.meta.url)) {
   try {
     const command = invocation(process.argv.slice(2));
     const result = spawnSync(command.command, command.args, {

package/skills/hyperframes/scripts/plugin-cli.test.mjs

@@ -17,11 +17,15 @@ import { invocation, pluginVersion } from "./plugin-cli.mjs";
 function fixture(t, manifest = "plugin.json", version = "1.2.3") {
   const root = mkdtempSync(join(tmpdir(), "hf-plugin-"));
   t.after(() => rmSync(root, { recursive: true, force: true }));
-  mkdirSync(join(root, "skills/hyperframes/scripts"), { recursive: true });
+  mkdirSync(join(root, "skills/hyperframes/scripts/lib"), { recursive: true });
   mkdirSync(join(root, manifest, ".."), { recursive: true });
   writeFileSync(join(root, manifest), JSON.stringify({ name: "hyperframes", version }));
   const launcher = join(root, "skills/hyperframes/scripts/plugin-cli.mjs");
   copyFileSync(new URL("./plugin-cli.mjs", import.meta.url), launcher);
+  copyFileSync(
+    new URL("./lib/main-module.mjs", import.meta.url),
+    join(root, "skills/hyperframes/scripts/lib/main-module.mjs"),
+  );
   return { root, launcher };
 }
 

package/skills/hyperframes-animation/SKILL.md

@@ -1,88 +1,10 @@
 ---
 name: hyperframes-animation
-description: "All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic."
+description: Compatibility entry for the retired hyperframes-animation skill; routes to the current official hyperframes skill.
 ---
 
-**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.
+# hyperframes-animation: compatibility entry
 
-# HyperFrames Animation
+The current official HyperFrames release merged this workflow into the `hyperframes` skill. Load `hyperframes` from the DSH skill registry and follow its current instructions for the user's task. Use its bundled resources; do not reconstruct the retired workflow or download standalone skills.
 
-All motion knowledge in one skill: **rules** (atomic recipes), **blueprints** (multi-phase scene templates), **transitions** (scene-to-scene), **techniques** (broader motion-design patterns), and **adapters** (per-runtime APIs).
-
-For the composition contract (data attributes, sub-compositions, determinism) see `hyperframes-core`.
-
-## Default: compose atomic rules
-
-Pick 2-4 rules from `rules-index.md`, glue them together with a single paused GSAP timeline, done. This is faster and produces less code than starting from a blueprint.
-
-## Load a blueprint when
-
-- The scene matches an existing pre-designed multi-phase template (brand-reveal, social-proof, etc.) and reusing its phase pipeline saves real authoring time
-- You want runnable ground-truth code for a complex 4-5 phase choreography
-
-Blueprints live in `blueprints-index.md`. Each entry points to `blueprints/<id>.md` (recipe). Do not read it speculatively; load it when you've already decided you need scene-level orchestration.
-
-## Routing
-
-| Want to…                                                                       | Read                                                |
-| ------------------------------------------------------------------------------ | --------------------------------------------------- |
-| Pick an atomic motion pattern by trigger / tag                                 | `rules-index.md`                                    |
-| Read one rule's full HTML / CSS / GSAP recipe                                  | `rules/<name>.md`                                   |
-| Pick a multi-phase scene template                                              | `blueprints-index.md`                               |
-| Read one blueprint's full recipe                                               | `blueprints/<id>.md`                                |
-| Author a scene transition (CSS-driven, between two clips)                      | `transitions/overview.md`, `transitions/catalog.md` |
-| Look up a broader motion-design technique                                      | `techniques.md`                                     |
-| Motion blur — shutter smear on an element, and when not to use it              | `references/motion-blur.md`                         |
-| Analyze an existing composition's animation map                                | `scripts/animation-map.mjs`                         |
-| GSAP API — timeline / tweens / position parameters                             | `adapters/gsap.md`                                  |
-| GSAP — drop-in effect recipes                                                  | `rules/gsap-effects.md`                             |
-| GSAP — transforms / perf                                                       | `adapters/gsap-transforms-and-perf.md`              |
-| GSAP — eases / stagger                                                         | `adapters/gsap-easing-and-stagger.md`               |
-| GSAP — timeline / labels                                                       | `adapters/gsap-timeline-and-labels.md`              |
-| Lottie / dotLottie (After Effects exports, `window.__hfLottie`)                | `adapters/lottie.md`                                |
-| Character animation (walk cycle, mascot, jointed puppet, gestures)             | `adapters/lottie.md` → Characters                   |
-| Three.js / WebGL (3D scenes, `AnimationMixer`, `hf-seek`)                      | `adapters/three.md`                                 |
-| Anime.js (`window.__hfAnime`)                                                  | `adapters/animejs.md`                               |
-| CSS keyframes (`animation-delay` / `play-state` / `fill-mode`)                 | `adapters/css-animations.md`                        |
-| Web Animations API (`element.animate()`, `currentTime` seek)                   | `adapters/waapi.md`                                 |
-| TypeGPU / WebGPU (`navigator.gpu`, WGSL, compute pipelines)                    | `adapters/typegpu.md`                               |
-| HTML-as-texture + WebGL/GLSL post-fx (capture live DOM via `drawElementImage`) | `adapters/html-in-canvas-patterns.md`               |
-| Named text-animation effects (24 IDs via external `animate-text` skill)        | `adapters/animate-text.md`                          |
-
-## Picking a runtime
-
-- **GSAP** is the default for 95% of motion work — covers timeline orchestration, transforms, easing, stagger. All atomic rules in this skill are GSAP-based.
-- **Lottie** when an asset has its own pre-baked timeline (typically After Effects exports), including characters that walk, gesture or react.
-- **Three.js** for 3D scenes, camera motion, shader-driven visuals.
-- **Anime.js** for lightweight tweening when GSAP is overkill.
-- **CSS** for simple repeated motifs, decoration, shimmer — no JavaScript animation cost.
-- **WAAPI** for native browser keyframes without a GSAP dependency.
-- **TypeGPU / WebGPU** for GPU-rendered canvases (particles, liquid glass, custom shaders).
-
-Multiple runtimes can coexist in one composition. Each registers its instances on the runtime-specific global so HyperFrames can seek all of them in one pass.
-
-## Critical Constraints
-
-**Prerequisite: `hyperframes-core` → Non-Negotiable Rules** (single paused timeline, `data-duration` governs length, no `Math.random` / `Date.now` / `performance.now`, no `repeat: -1`, no page-load `gsap.set` on later-scene clips, no `display` or raw `visibility` tweens, and no timeline construction inside `async` / `setTimeout` / `Promise`). GSAP `autoAlpha` and zero-duration visibility sets at explicit timeline boundaries remain allowed by core. Use those exceptions only on non-clip elements or wrappers inside a clip; the framework owns `.clip` lifecycle. Don't restate the full contract here.
-
-Animation-craft additions on top of core's contract:
-
-- **Pre-calculated layout constants** — never derive positions from `getBoundingClientRect()` at tween time. Tween-time DOM measurements desync because the renderer samples in parallel; compute coordinates once at composition setup and reuse.
-- **Spatial motion uses GSAP transform aliases only** (`x`, `y`, `scale`, `rotation`). Core's allowlist also permits `opacity` / `color` / `backgroundColor` / `borderRadius` for non-spatial property tweens — but never `width` / `height` / `top` / `left` for layout changes.
-
-## Scripts
-
-```bash
-node skills/hyperframes-animation/scripts/animation-map.mjs <composition-dir> \
-  --out <composition-dir>/.hyperframes/anim-map
-```
-
-Reads every GSAP timeline registered on `window.__timelines`, enumerates tweens, samples bboxes, computes flags, outputs `animation-map.json`. Use it to audit choreography (dead zones, stagger consistency, lifecycle warnings) after authoring.
-
-`animation-map.mjs` resolves helper packages from the current project first, then can bootstrap the bundled HyperFrames package version. Set `HYPERFRAMES_SKILL_PKG_VERSION=<version>` only when running the skill outside the bundled CLI/skill install and you need to pin that bootstrap version explicitly.
-
-## See Also
-
-- `hyperframes-core` — composition structure, data attributes, sub-compositions, deterministic render contract
-- `hyperframes-creative` — palettes, typography, narration, beat planning (non-animation creative direction)
-- `hyperframes-cli` — `npx hyperframes lint / check / snapshot / preview / render`
+For an existing project, preserve its files and dependencies. DSH plugin management owns this installed skill bundle. The upstream plugin launcher pins HyperFrames 0.8.207 and suppresses standalone skill installation; run it in the user's project directory. This entry preserves the previous DSH skill name while using the current workflow.