dsh-hyperframes 0.9.1 → 0.9.2

package/skills/hyperframes/scripts/lib/frame-packets-core.mjs

@@ -1,194 +0,0 @@
-// Frame packets inline the storyboard frame, blueprint and cited recipes.
-// Workflow wrappers supply resource paths and workflow-specific sections.
-// The role combines the shared worker contract with the workflow delta.
-
-import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  readdirSync,
-  realpathSync,
-  writeFileSync,
-} from "node:fs";
-import { basename, join, resolve } from "node:path";
-import { pathToFileURL } from "node:url";
-
-export function field(block, name) {
-  const match = block.match(new RegExp(`^-\\s+${name}:\\s*(.+)$`, "im"));
-  return match?.[1]?.trim() ?? null;
-}
-
-export function splitFrames(storyboard) {
-  const matches = [...storyboard.matchAll(/^## Frame\s+([^\n]+)$/gm)];
-  return matches.map((match, index) => {
-    const start = match.index;
-    const end = matches[index + 1]?.index ?? storyboard.length;
-    return {
-      heading: match[1].trim(),
-      block: storyboard.slice(start, end).trim(),
-    };
-  });
-}
-
-export function frameId(frame) {
-  const src = field(frame.block, "src");
-  if (!src) throw new Error(`${frame.heading}: missing src`);
-  return basename(src).replace(/\.html?$/i, "");
-}
-
-export function selectedFile(path, heading) {
-  if (!path || !existsSync(path)) return "";
-  return `\n## ${heading}\n\n${readFileSync(path, "utf8").trim()}\n`;
-}
-
-function escapeRegExp(id) {
-  return id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-export function knownRuleIds(animationDir) {
-  const rulesDir = join(animationDir, "rules");
-  if (!existsSync(rulesDir)) {
-    console.warn(
-      `frame-packets: no rules dir at ${rulesDir} — packets will inline no motion recipes`,
-    );
-    return [];
-  }
-  return readdirSync(rulesDir)
-    .filter((name) => name.endsWith(".md"))
-    .map((name) => name.replace(/\.md$/, ""));
-}
-
-export function citedRules(block, ruleIds) {
-  const explicit = (field(block, "rules") ?? "")
-    .split(/[,\s]+/)
-    .map((rule) => rule.trim())
-    .filter(Boolean);
-  const mentioned = ruleIds.filter((id) =>
-    new RegExp(`(?<![\\w-])${escapeRegExp(id)}(?![\\w-])`, "i").test(block),
-  );
-  return [...new Set([...explicit, ...mentioned])].filter((id) => ruleIds.includes(id));
-}
-
-// visual-design.md tells the author to write the blueprint as `<id> (Reproduce)`
-// or `<id> (Adapt)` — the qualifier is direction for the frame worker, not part of
-// the filename. Parse the field into the id it names (or null for `compose`), so
-// no caller ever resolves a raw field value against the blueprints directory.
-export function blueprintId(block) {
-  const raw = field(block, "blueprint");
-  if (!raw) return null;
-  const id = raw.replace(/\s*\([^)]*\)\s*$/, "").trim();
-  return id && id.toLowerCase() !== "compose" ? id : null;
-}
-
-export function resourceSections(block, { animationDir, ruleIds, frameId }) {
-  let sections = "";
-  const blueprint = blueprintId(block);
-  if (blueprint) {
-    const blueprintsDir = join(animationDir, "blueprints");
-    const path = join(blueprintsDir, `${blueprint}.md`);
-    // An installed library must contain the named blueprint.
-    // An absent on-demand library warns, like missing motion rules.
-    if (!existsSync(blueprintsDir)) {
-      console.warn(
-        `frame-packets: no blueprints dir at ${blueprintsDir} — packets will inline no blueprint`,
-      );
-    } else if (!existsSync(path)) {
-      throw new Error(`${frameId ?? "frame"}: blueprint "${blueprint}" has no file at ${path}`);
-    } else {
-      sections += selectedFile(path, `Selected blueprint: ${blueprint}`);
-    }
-  }
-  for (const rule of citedRules(block, ruleIds)) {
-    sections += selectedFile(
-      join(animationDir, "rules", `${rule}.md`),
-      `Selected motion rule: ${rule}`,
-    );
-  }
-  return sections;
-}
-
-export function buildRolePayload({ corePath, deltaPath, outDir }) {
-  const core = readFileSync(corePath, "utf8").trim();
-  const delta = readFileSync(deltaPath, "utf8").trim();
-  const role = `${core}\n\n---\n\n${delta}\n`;
-  mkdirSync(outDir, { recursive: true });
-  const path = join(outDir, "_role.md");
-  writeFileSync(path, role);
-  return { path, bytes: Buffer.byteLength(role) };
-}
-
-export function buildFramePackets({
-  projectDir,
-  storyboardPath = join(projectDir, "STORYBOARD.md"),
-  outDir = join(projectDir, ".hyperframes", "frame-packets"),
-  maxPacketBytes = 48_000,
-  animationDir,
-  corePath,
-  deltaPath,
-  // Per-workflow hooks (all optional):
-  // designTruthLine(projectDir) -> the packet's design-truth input line
-  // validateFrame(frame, id)   -> throw to reject a frame before packing
-  // extraSections(block)       -> extra packet sections appended after the rule recipes
-  designTruthLine = (dir) => `- Design tokens: ${join(resolve(dir), "frame.md")}`,
-  validateFrame,
-  extraSections,
-}) {
-  const storyboard = readFileSync(storyboardPath, "utf8");
-  const frames = splitFrames(storyboard);
-  if (frames.length === 0) throw new Error("STORYBOARD.md has no frame blocks");
-  const ruleIds = knownRuleIds(animationDir);
-
-  const packets = frames.map((frame) => {
-    const id = frameId(frame);
-    if (validateFrame) validateFrame(frame, id);
-    const packet = `# Frame packet: ${id}\n\n## Project inputs\n\n- Project: ${resolve(projectDir)}\n${designTruthLine(projectDir)}\n- RULES_DIR: ${join(animationDir, "rules")}\n\n## Assigned storyboard block\n\n${frame.block}\n${resourceSections(frame.block, { animationDir, ruleIds, frameId: id })}${extraSections ? extraSections(frame.block) : ""}`;
-    const bytes = Buffer.byteLength(packet);
-    if (bytes > maxPacketBytes) {
-      throw new Error(`${id}: frame packet is ${bytes} bytes (limit ${maxPacketBytes})`);
-    }
-    return { frameId: id, path: join(outDir, `${id}.md`), bytes, packet };
-  });
-
-  mkdirSync(outDir, { recursive: true });
-  for (const { path, packet } of packets) writeFileSync(path, packet);
-  buildRolePayload({ corePath, deltaPath, outDir });
-  return packets.map(({ packet: _packet, ...result }) => result);
-}
-
-export function flag(argv, name, fallback) {
-  const index = argv.indexOf(`--${name}`);
-  return index >= 0 && argv[index + 1] ? argv[index + 1] : fallback;
-}
-
-// realpath both sides: on macOS /tmp → /private/tmp, and node resolves the main
-// module's symlinks in import.meta.url while argv[1] keeps the invoked spelling —
-// a raw compare silently skips main() when invoked through any symlinked path.
-export function isMainModule(importMetaUrl) {
-  if (!process.argv[1]) return false;
-  try {
-    return pathToFileURL(realpathSync(process.argv[1])).href === importMetaUrl;
-  } catch {
-    return false;
-  }
-}
-
-export function runCli({ buildFramePackets: build, buildRolePayload: buildRole }) {
-  const argv = process.argv.slice(2);
-  const projectDir = resolve(flag(argv, "project", "."));
-  const outDir = resolve(flag(argv, "out-dir", join(projectDir, ".hyperframes", "frame-packets")));
-  try {
-    const packets = build({
-      projectDir,
-      storyboardPath: resolve(flag(argv, "storyboard", join(projectDir, "STORYBOARD.md"))),
-      outDir,
-    });
-    const role = buildRole({ outDir });
-    console.log(`✓ frame packets: ${packets.length} bounded packet(s)`);
-    for (const packet of packets)
-      console.log(`  ${packet.frameId}: ${packet.bytes} bytes → ${packet.path}`);
-    console.log(`  worker role: ${role.bytes} bytes → ${role.path}`);
-  } catch (error) {
-    console.error(`✗ frame packets: ${error.message}`);
-    process.exit(1);
-  }
-}

package/skills/hyperframes-animation/adapters/animate-text.md

@@ -1,64 +0,0 @@
-# Text Effects — Reference
-
-For deterministic text-animation specs (e.g., `typewriter` at exact `240ms / 46ms stagger / steps(1, end) easing`), this skill defers to the separate **`animate-text`** skill maintained by Pixel Point at [github.com/pixel-point/animate-text](https://github.com/pixel-point/animate-text). It provides a catalog of 24 named text effects with portable contracts and per-library implementation recipes (GSAP, Anime.js, WAAPI).
-
-**We do NOT ship the catalog inside this repo.** Pixel Point's `animate-text` is the source of truth; vendoring its files here would violate the upstream's licensing (no explicit license declared upstream as of this writing). Loading the skill separately keeps the legal picture clean while giving you the same catalog.
-
-## How to use it
-
-When a beat needs a deterministic text animation, load the upstream skill alongside this one:
-
-```bash
-# In your project root, install the upstream skill into .agents/skills/
-npx skills add pixel-point/animate-text
-```
-
-Or in a skill-aware agent runtime, the skill is invoked by name:
-
-```
-/animate-text
-```
-
-Once installed, the specs live at:
-
-```
-.agents/skills/animate-text/assets/effects/<id>.json   # per-library implementation recipe
-.agents/skills/animate-text/assets/specs/<id>.json     # portable motion contract
-```
-
-Sub-agents reading those files get exact GSAP timings, easing strings, DOM split rules, and stagger algorithms — no creative invention needed.
-
-## When you don't need the upstream skill
-
-If a beat's text animation is simple enough to describe in prose ("headline fades up word-by-word, 80ms stagger"), implement it inline using the GSAP knowledge already in these skills (`hyperframes-creative` → `references/motion-principles.md` and `references/beat-direction.md`; `hyperframes-animation` → `techniques.md`, entry #4 "Per-Word Kinetic Typography"). The upstream catalog is most valuable when:
-
-- You want a specific NAMED effect across multiple beats (so they feel like one design system, not one-offs)
-- You're choosing between several similar effects (typewriter vs per-character-rise vs bottom-up-letters) and want to see all 24 in one place
-- You need layout-aware effects (`kinetic-center-build`, `short-slide-right`, `short-slide-down`) where parameters alone aren't enough — those ship with custom layout algorithms
-
-## Effect names — vocabulary (do NOT use this as the implementation source)
-
-For convenience while writing storyboards: the upstream skill provides 24 effects. Their IDs are listed here so you can name them in `STORYBOARD.md` even before loading the upstream skill. **The implementation specs are in the upstream skill, not here.**
-
-- **Per-character (7):** soft-blur-in, per-character-rise, typewriter, bottom-up-letters, top-down-letters, stagger-from-center, stagger-from-edges
-- **Per-word (8):** per-word-crossfade, spring-scale-in, shared-axis-y, blur-out-up, kinetic-center-build, short-slide-right, short-slide-down, depth-parallax-words
-- **Per-line (2):** mask-reveal-up, line-by-line-slide
-- **Whole element (7):** micro-scale-fade, shimmer-sweep, fade-through, shared-axis-z, scale-down-fade, focus-blur-resolve, shared-axis-x
-
-For descriptions, durations, easing curves, and the per-library recipes: load `/animate-text` and read its own catalog page.
-
-## In the storyboard
-
-Every text element in every beat can name an effect by ID, e.g.:
-
-```markdown
-**Text Animations:**
-
-- Main headline: `kinetic-center-build`
-- Eyebrow label: `soft-blur-in`
-- Body copy 3 lines: `mask-reveal-up`
-```
-
-Sub-agents implementing the beat will load `/animate-text` if it's not already loaded, then read the spec for each named effect from the upstream skill's files.
-
-If the upstream skill isn't available (offline build, network restrictions, agent runtime that doesn't support skill loading), sub-agents fall back to implementing the effect from the description alone — using GSAP knowledge plus the effect ID as a description of intent (e.g., "typewriter" = per-character stepped reveal with no interpolation).

package/skills/hyperframes-animation/adapters/animejs.md

@@ -1,130 +0,0 @@
----
-name: hyperframes-animejs
-description: Anime.js adapter patterns for HyperFrames. Use when writing Anime.js animations or timelines inside HyperFrames compositions, registering animations on window.__hfAnime, making Anime.js seek-driven and deterministic, or translating Anime.js examples into render-safe HyperFrames HTML.
----
-
-# Anime.js for HyperFrames
-
-HyperFrames can seek Anime.js instances through its `animejs` runtime adapter. The composition owns the animation objects; HyperFrames owns the clock.
-
-**This page targets v4 (examples pinned to 4.5.0, MIT).** v4 is a hard break from v3 — there is no callable `anime()`, `easing:` is now `ease:`, and ease names lost their `ease` prefix. Writing v3 from memory produces a composition that throws or silently animates nothing.
-
-The repo's own producer fixtures pin `animejs@4.0.2/lib/anime.iife.min.js`, which still resolves — but that build predates `splitText` / `scrambleText` / `createSeededRandom` / `createLayout` used below, and 4.1+ moved the bundles to `dist/bundles/`, so a version bump needs the path changed too.
-
-## Contract
-
-- Create animations or timelines synchronously during composition initialization.
-- Set `autoplay: false` so Anime.js does not advance on its own clock.
-- Register every returned animation or timeline on `window.__hfAnime` — **explicitly. There is no working auto-discovery on v4** (see Avoid).
-- Use finite durations and loop counts.
-- Avoid callbacks that mutate DOM based on wall-clock time, network state, or unseeded randomness.
-
-The adapter seeks every registered instance with `instance.seek(timeMs)`, where `timeMs` is HyperFrames time **in milliseconds** (`ctx.time` seconds × 1000). It also calls `pause()` and `play()` on each instance; anything exposing those three methods works, whatever created it.
-
-## Loading v4
-
-```html
-<!-- UMD: the global `anime` is a NAMESPACE OBJECT, not a function -->
-<script src="https://cdn.jsdelivr.net/npm/animejs@4.5.0/dist/bundles/anime.umd.min.js"></script>
-```
-
-`anime.animate(...)`, `anime.createTimeline(...)`, `anime.utils.*`, `anime.svg.*`, `anime.stagger(...)`. **Calling `anime(...)` is a TypeError** — every v4 build (UMD and IIFE alike) assigns a namespace object to the global, so v3's `anime({ targets })` form cannot work no matter which v4 file you load.
-
-## Basic Pattern
-
-```html
-<script>
-  const anim = anime.animate(".mark", {
-    x: 280, // v4 shorthand for translateX
-    rotate: "1turn",
-    opacity: [0, 1],
-    duration: 1200,
-    ease: "outExpo", // NOT easing: "easeOutExpo"
-    autoplay: false,
-  });
-
-  window.__hfAnime = window.__hfAnime || [];
-  window.__hfAnime.push(anim);
-</script>
-```
-
-## Timeline Pattern
-
-`createTimeline` replaces `anime.timeline`, and `add()` takes **targets as its first argument** — `add(targets, parameters, position)`:
-
-```html
-<script>
-  const tl = anime.createTimeline({
-    autoplay: false,
-    defaults: { ease: "outCubic" }, // per-timeline defaults, not a bare `easing`
-  });
-
-  tl.add(".title", { y: [40, 0], opacity: [0, 1], duration: 650 });
-  tl.add(".accent", { scaleX: [0, 1], duration: 450 }, 250); // 250 = time position
-
-  window.__hfAnime = window.__hfAnime || [];
-  window.__hfAnime.push(tl);
-</script>
-```
-
-Position accepts a number, a label, `"+=250"` / `"-=100"`, `"<"` (previous **end**) and `"<<"` (previous **start**).
-
-## Module Builds
-
-The adapter does not care how the instance was created — only that it exposes `seek()`, `pause()`, and `play()`:
-
-```html
-<script type="module">
-  import { animate } from "https://cdn.jsdelivr.net/npm/animejs@4.5.0/+esm";
-
-  const anim = animate(".chip", { x: "18rem", duration: 900, autoplay: false });
-
-  window.__hfAnime = window.__hfAnime || [];
-  window.__hfAnime.push(anim);
-</script>
-```
-
-## Determinism
-
-v4 ships `createSeededRandom(seed)` — use it instead of `Math.random()` when a composition needs scatter/jitter, so the same frame renders the same on every pass:
-
-```js
-const rnd = anime.createSeededRandom(1337);
-anime.animate(".dot", { y: () => -40 * rnd(), duration: 800, autoplay: false });
-```
-
-`anime.utils.random()` / `randomPick()` / `shuffle()` are **not** seeded — they break frame-to-frame reproducibility.
-
-## Good Uses
-
-- Small SVG and DOM flourishes where Anime.js syntax is compact.
-- Free `splitText` / `scrambleText` (Motion puts these behind Motion+; GSAP SplitText is the other free option).
-- `svg.createDrawable` / `svg.morphTo` / `svg.createMotionPath` line-draw and path work.
-- Multiple independent micro-animations pushed into the same registry.
-
-Use GSAP for complex scene sequencing unless the user specifically asks for Anime.js. GSAP is still the primary HyperFrames authoring path.
-
-## Avoid
-
-- Leaving `autoplay` at the Anime.js default.
-- **Relying on the adapter's `anime.running` auto-discovery — it cannot work on v4.** `running` is not among v4.5.0's exports (verified against the published bundle), so `discover()` returns immediately and any instance you did not `push()` is never seeked. Explicit registration is mandatory, not a nicety.
-- `autoplay: onScroll(...)` — there is no scroll in a headless seek render, so the animation would never advance. Drive it off composition time instead.
-- `waapi.animate()` for anything the adapter must seek — the adapter seeks via `.seek()`, and whether WAAPI-backed instances honor it is **unverified**. Use the JS engine (`animate`) for rendered compositions; `waapi` is an off-main-thread optimization for live pages.
-- `createDraggable`, and any pointer-driven `createAnimatable` loop — input does not exist at render time.
-- Infinite loops. Compute a finite repeat count from the composition duration (v4 `loop` counts **repeats**: `loop: 1` plays twice).
-- Building animations in timers, promises, event handlers, or after async asset loads.
-
-## Validation
-
-After editing a composition that uses Anime.js:
-
-```bash
-npx hyperframes lint
-npx hyperframes validate
-```
-
-## Credits And References
-
-- HyperFrames adapter source: `packages/core/src/runtime/adapters/animejs.ts`.
-- Anime.js v4 docs: https://animejs.com/documentation/
-- v3 → v4 migration (not on animejs.com): https://github.com/juliangarnier/anime/wiki/Migrating-from-v3-to-v4

package/skills/hyperframes-animation/adapters/css-animations.md

@@ -1,143 +0,0 @@
----
-name: hyperframes-css-animations
-description: CSS animation adapter patterns for HyperFrames. Use when authoring CSS keyframes, animation-delay based timing, animation-fill-mode, animation-play-state, or CSS-only motion that HyperFrames must seek deterministically during preview and rendering.
----
-
-# CSS Animations for HyperFrames
-
-HyperFrames can seek CSS keyframe animations through its `css` runtime adapter. Use this for simple repeated motifs, background motion, shimmer, glow, masks, and non-sequenced decoration.
-
-For scene choreography, GSAP is usually clearer. CSS animations work best when the motion belongs to one element and has a fixed duration.
-
-## Contract
-
-- Put the animated element in the DOM before runtime initialization finishes.
-- Give timed elements a `data-start` value so local animation time matches the clip.
-- Use finite `animation-duration` and `animation-iteration-count` because the negative-delay fallback cannot represent unbounded duration in environments without WAAPI-backed CSS animations.
-- Prefer `animation-fill-mode: both` so seeked states hold before and after active motion.
-- Avoid wall-clock JavaScript, hover-triggered state, and class toggles that depend on user events.
-
-The adapter discovers elements with computed `animation-name`, seeks their browser `Animation` handles when available, and falls back to pausing with negative `animation-delay`.
-
-## Basic Pattern
-
-```html
-<div
-  id="pulse-ring"
-  class="clip pulse-ring"
-  data-start="0"
-  data-duration="4"
-  data-track-index="2"
-></div>
-
-<style>
-  .pulse-ring {
-    width: 280px;
-    height: 280px;
-    border: 4px solid rgba(255, 255, 255, 0.7);
-    border-radius: 50%;
-    animation-name: pulse-ring;
-    animation-duration: 1200ms;
-    animation-timing-function: cubic-bezier(0.2, 0, 0, 1);
-    animation-iteration-count: 3;
-    animation-fill-mode: both;
-  }
-
-  @keyframes pulse-ring {
-    from {
-      opacity: 0;
-      transform: scale(0.82);
-    }
-    35% {
-      opacity: 1;
-    }
-    to {
-      opacity: 0;
-      transform: scale(1.18);
-    }
-  }
-</style>
-```
-
-## Stagger Pattern
-
-Use CSS custom properties to avoid duplicating keyframes:
-
-```html
-<div class="clip dots" data-start="1" data-duration="3" data-track-index="3">
-  <span style="--i: 0"></span>
-  <span style="--i: 1"></span>
-  <span style="--i: 2"></span>
-</div>
-
-<style>
-  .dots span {
-    display: inline-block;
-    width: 18px;
-    height: 18px;
-    margin-right: 10px;
-    border-radius: 50%;
-    background: currentColor;
-    animation: dot-pop 900ms ease-out both;
-    animation-delay: calc(var(--i) * 120ms);
-  }
-
-  @keyframes dot-pop {
-    from {
-      opacity: 0;
-      transform: translateY(18px) scale(0.75);
-    }
-    to {
-      opacity: 1;
-      transform: translateY(0) scale(1);
-    }
-  }
-</style>
-```
-
-## Good Uses
-
-- Decorative loops with a known repeat count.
-- Mask, glow, shimmer, grain, and subtle parallax layers.
-- Simple one-element entrances where a full JS timeline would be excessive.
-
-## Avoid
-
-- Infinite CSS animations unless you have verified the browser exposes seekable WAAPI-backed CSS animation handles. Prefer a finite iteration count covering the visible duration. If you do use `infinite`, add `data-duration` to the root element — see Composition Duration below.
-- Animating layout properties like `top`, `left`, `width`, or `height` when transforms work.
-- Relying on hover, focus, scroll, or media queries to trigger render-critical motion.
-- Changing animation classes after startup unless another deterministic timeline controls that change.
-
-## Composition Duration
-
-The render engine needs to know the composition's total length. GSAP timelines report this automatically; CSS-only compositions have no timeline object, so the runtime infers duration from the longest running animation's computed end time (`animation-delay` + `animation-duration` × finite `animation-iteration-count`, per element with `data-start` added as an offset). `data-duration` on the root element is optional whenever every CSS animation on the page is finite — you don't need to add it just because the composition is CSS-driven.
-
-`animation-iteration-count: infinite` (or any unresolved/unbounded animation) has no finite end time, so it cannot be auto-inferred. If the composition's only animation is infinite, you **must** add `data-duration="<seconds>"` to the root `[data-composition-id]` element with your intended total length — `npx hyperframes lint` errors on this case (`root_composition_missing_duration_source`) precisely because there is nothing for the runtime to infer.
-
-```html
-<div
-  data-composition-id="root"
-  data-start="0"
-  data-duration="6"
-  data-width="1920"
-  data-height="1080"
->
-  <div class="clip spinner" data-start="0" style="animation: spin 1s linear infinite"></div>
-</div>
-```
-
-## Validation
-
-After editing CSS animation compositions:
-
-```bash
-npx hyperframes lint
-npx hyperframes check
-```
-
-## Credits And References
-
-- HyperFrames adapter source: `packages/core/src/runtime/adapters/css.ts`.
-- Duration auto-inference: `packages/core/src/runtime/init.ts` (`resolveAdapterDurationFloorSeconds`), `getInferredDurationSeconds` in the adapter above.
-- MDN CSS animation documentation: https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/animation
-- MDN `animation-fill-mode`: https://developer.mozilla.org/en-US/docs/Web/CSS/animation-fill-mode