Skip to content

Diogenesoftoronto/keating / video/keating-surface-tour/.agents/skills/hyperframes-animation

hyperframes-animation

Verified

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.

FileKindSize
SKILL.mdskill md7.6 KB
adapters/animate-text.mdmarkdown4.0 KB
adapters/animejs.mdmarkdown6.1 KB
adapters/css-animations.mdmarkdown5.3 KB
adapters/gsap-easing-and-stagger.mdmarkdown13.0 KB
adapters/gsap-timeline-and-labels.mdmarkdown3.6 KB
adapters/gsap-transforms-and-perf.mdmarkdown8.4 KB
adapters/gsap.mdmarkdown6.9 KB
adapters/html-in-canvas-patterns.mdmarkdown16.8 KB
adapters/lottie.mdmarkdown4.0 KB
adapters/three.mdmarkdown5.1 KB
adapters/typegpu.mdmarkdown7.9 KB
adapters/waapi.mdmarkdown4.1 KB
blueprints-index.mdmarkdown25.9 KB
blueprints/agent-progress-theater.mdmarkdown15.7 KB
blueprints/camera-journey.mdmarkdown13.3 KB
blueprints/comparison-split.mdmarkdown3.2 KB
blueprints/constellation-hub.mdmarkdown7.0 KB
blueprints/cta-morph-press.mdmarkdown6.3 KB
blueprints/cursor-ui-demo.mdmarkdown19.8 KB
blueprints/dataviz-countup.mdmarkdown14.3 KB
blueprints/device-surface-showcase.mdmarkdown16.7 KB
blueprints/fixed-anchor-cycle.mdmarkdown8.9 KB
blueprints/grid-card-assemble.mdmarkdown15.2 KB
blueprints/kinetic-type-beats.mdmarkdown28.5 KB
blueprints/logo-assemble-lockup.mdmarkdown26.0 KB
blueprints/overwhelm-surround.mdmarkdown6.0 KB
blueprints/panel-edit-live-sync.mdmarkdown13.1 KB
blueprints/prompt-type-submit-generate.mdmarkdown18.2 KB
blueprints/spatial-pan-stations.mdmarkdown4.8 KB
blueprints/ticker-takeover.mdmarkdown3.0 KB
blueprints/titlecard-reveal.mdmarkdown7.3 KB
blueprints/transcript-scroll-artifact-reveal.mdmarkdown11.4 KB
blueprints/typewriter-reveal.mdmarkdown6.1 KB
blueprints/video-text-pivot.mdmarkdown3.2 KB
blueprints/zoom-out-workspace-reveal.mdmarkdown14.4 KB
examples/brand-reveal-assemble-zoom.htmlother12.0 KB
examples/comparison-split-cards.htmlother21.2 KB
examples/concept-demo-decode-pan.htmlother18.0 KB
examples/cta-morph-press.htmlother14.8 KB
examples/cta-orbit-collapse.htmlother49.5 KB
examples/demo-page-scroll-spotlight.htmlother24.4 KB
examples/hook-counter-burst.htmlother22.5 KB
examples/messaging-multi-phrase.htmlother11.9 KB
examples/metric-video-text-pivot.htmlother25.0 KB
examples/problem-mockup-overwhelm.htmlother43.4 KB
examples/proof-logo-chain.htmlother28.2 KB
examples/takeover-ticker-displace.htmlother10.7 KB
examples/workflow-approve-press.htmlother20.2 KB
rules-index.mdmarkdown20.7 KB
rules/3d-camera-flight.mdmarkdown17.7 KB
rules/3d-page-scroll.mdmarkdown7.2 KB
rules/3d-text-depth-layers.mdmarkdown6.6 KB
rules/ai-tracking-box.mdmarkdown6.4 KB
rules/ambient-glow-bloom.mdmarkdown9.6 KB
rules/anchored-layout-expand.mdmarkdown10.1 KB
rules/asr-keyword-glow.mdmarkdown6.6 KB
rules/avatar-cloud-network.mdmarkdown6.4 KB
rules/camera-cursor-tracking.mdmarkdown7.7 KB
rules/card-morph-anchor.mdmarkdown7.2 KB
rules/center-outward-expansion.mdmarkdown4.2 KB
rules/chart-scrub-readout.mdmarkdown10.1 KB
rules/chromatic-glitch.mdmarkdown10.1 KB
rules/context-sensitive-cursor.mdmarkdown6.8 KB
rules/control-target-sync.mdmarkdown10.0 KB
rules/coordinate-target-zoom.mdmarkdown7.4 KB
rules/counting-dynamic-scale.mdmarkdown5.8 KB
rules/css-marker-patterns.mdmarkdown5.6 KB
rules/cursor-click-ripple.mdmarkdown6.3 KB
rules/cursor-drag.mdmarkdown10.0 KB
rules/depth-of-field-blur.mdmarkdown8.7 KB
rules/depth-scatter-assemble.mdmarkdown6.9 KB
rules/discrete-text-sequence.mdmarkdown6.3 KB
rules/dynamic-content-sequencing.mdmarkdown8.4 KB
rules/gradient-text-sweep.mdmarkdown8.5 KB
rules/gsap-effects.mdmarkdown6.8 KB
rules/hacker-flip-3d.mdmarkdown5.5 KB
rules/kinetic-beat-slam.mdmarkdown6.3 KB
rules/motion-blur-streak.mdmarkdown10.4 KB
rules/multi-cursor-choreography.mdmarkdown10.3 KB
rules/multi-phase-camera.mdmarkdown7.6 KB
rules/nudge-curve.mdmarkdown2.6 KB
rules/orbit-3d-entry.mdmarkdown6.5 KB
rules/particle-burst.mdmarkdown9.7 KB
rules/physics-press-reaction.mdmarkdown6.5 KB
rules/press-release-spring.mdmarkdown6.9 KB
rules/reactive-displacement.mdmarkdown6.4 KB
rules/scale-swap-transition.mdmarkdown5.4 KB
rules/sine-wave-loop.mdmarkdown6.0 KB
rules/split-tilt-cards.mdmarkdown5.5 KB
rules/spring-pop-entrance.mdmarkdown6.4 KB
rules/stat-bars-and-fills.mdmarkdown5.4 KB
rules/svg-icon-enrichment.mdmarkdown7.4 KB
rules/svg-path-draw.mdmarkdown5.2 KB
rules/theme-crossfade-morph.mdmarkdown9.2 KB
rules/vertical-spring-ticker.mdmarkdown5.4 KB
rules/viewport-change.mdmarkdown8.8 KB
rules/waterfall-entry.mdmarkdown4.5 KB
scripts/animation-map-sampling.mjsscript1.4 KB
scripts/animation-map-sampling.test.mjsscript1.6 KB
scripts/animation-map.mjsscript19.8 KB
scripts/animation-map.test.mjsscript12.1 KB
scripts/package-loader.mjsscript13.2 KB
scripts/package-loader.test.mjsscript2.5 KB
techniques.mdmarkdown15.4 KB
transitions/TRANSITION-REGISTRY.mdmarkdown7.9 KB
transitions/catalog.mdmarkdown6.5 KB
transitions/css-3d.mdmarkdown421 B
transitions/css-blur.mdmarkdown1.7 KB
transitions/css-cover.mdmarkdown1.4 KB
transitions/css-destruction.mdmarkdown4.4 KB
transitions/css-dissolve.mdmarkdown2.4 KB
transitions/css-distortion.mdmarkdown1.8 KB
transitions/css-grid.mdmarkdown370 B
transitions/css-light.mdmarkdown2.3 KB
transitions/css-mechanical.mdmarkdown1.6 KB
transitions/css-other.mdmarkdown838 B
transitions/css-push.mdmarkdown1.2 KB
transitions/css-radial.mdmarkdown1.0 KB
transitions/css-scale.mdmarkdown715 B
transitions/overview.mdmarkdown13.5 KB

scripts/animation-map.test.mjs

View on GitHub
import assert from "node:assert/strict";
import { spawnSync } from "node:child_process";
import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { describe, it } from "node:test";

const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
const HELPERS = [
  join(REPO_ROOT, "skills", "hyperframes-animation", "scripts", "animation-map.mjs"),
  join(REPO_ROOT, "skills", "hyperframes-creative", "scripts", "contrast-report.mjs"),
];

describe("HyperFrames skill helpers", () => {
  for (const helper of HELPERS)
    it(`${helper.split("/").at(-1)} bundles modular input and uses rational fps`, () => {
      const root = mkdtempSync(join(tmpdir(), "hyperframes-skill-helper-test-"));
      const packageDir = join(root, "node_modules", "@hyperframes", "producer");
      const corePackageDir = join(root, "node_modules", "@hyperframes", "core");
      const sharpPackageDir = join(root, "node_modules", "sharp");
      const compositionDir = join(root, "composition");
      mkdirSync(packageDir, { recursive: true });
      mkdirSync(corePackageDir, { recursive: true });
      mkdirSync(sharpPackageDir, { recursive: true });
      mkdirSync(compositionDir, { recursive: true });
      writeFileSync(
        join(packageDir, "package.json"),
        JSON.stringify({ name: "@hyperframes/producer", type: "module", exports: "./index.mjs" }),
      );
      writeFileSync(
        join(packageDir, "index.mjs"),
        [
          'import { readFileSync } from "node:fs";',
          'import { join } from "node:path";',
          "export async function createFileServer(options) {",
          '  const bundled = readFileSync(join(options.compiledDir, "index.html"), "utf8");',
          '  if (bundled !== "<!doctype html><main>bundled modular composition</main>") {',
          "    throw new Error(`UNEXPECTED_BUNDLE=${bundled}`);",
          "  }",
          '  return { url: "http://test", close() {} };',
          "}",
          "export async function createCaptureSession(_url, _out, options) {",
          "  throw new Error(`CAPTURE_OPTIONS=${JSON.stringify(options)}`);",
          "}",
          "export async function initializeSession() {}",
          "export async function closeCaptureSession() {}",
          "export async function getCompositionDuration() { return 0; }",
        ].join("\n"),
      );
      writeFileSync(
        join(corePackageDir, "package.json"),
        JSON.stringify({
          name: "@hyperframes/core",
          type: "module",
          exports: { ".": "./index.mjs", "./compiler": "./compiler.mjs" },
        }),
      );
      writeFileSync(
        join(corePackageDir, "index.mjs"),
        [
          "export function parseFps(input) {",
          "  if (input === '30000/1001') return { ok: true, value: { num: 30000, den: 1001 } };",
          "  if (input === '29.97') return { ok: false, reason: 'ambiguous-decimal' };",
          "  return { ok: true, value: { num: Number(input), den: 1 } };",
          "}",
        ].join("\n"),
      );
      writeFileSync(
        join(corePackageDir, "compiler.mjs"),
        [
          "export async function bundleToSingleHtml() {",
          '  return "<!doctype html><main>bundled modular composition</main>";',
          "}",
        ].join("\n"),
      );
      writeFileSync(
        join(sharpPackageDir, "package.json"),
        JSON.stringify({ name: "sharp", type: "module", exports: "./index.mjs" }),
      );
      writeFileSync(join(sharpPackageDir, "index.mjs"), "export default function sharp() {}\n");

      try {
        const result = spawnSync(
          process.execPath,
          [helper, compositionDir, "--fps", "30000/1001", "--out", join(root, "output")],
          {
            encoding: "utf8",
            env: {
              ...process.env,
              HYPERFRAMES_SKILL_NODE_MODULES: join(root, "node_modules"),
            },
          },
        );
        const output = `${result.stdout}\n${result.stderr}`;
        assert.notEqual(result.status, 0);
        assert.match(output, /CAPTURE_OPTIONS=.*"fps":\{"num":30000,"den":1001\}/);

        const invalid = spawnSync(
          process.execPath,
          [helper, compositionDir, "--fps", "29.97", "--out", join(root, "invalid-output")],
          {
            encoding: "utf8",
            env: {
              ...process.env,
              HYPERFRAMES_SKILL_NODE_MODULES: join(root, "node_modules"),
            },
          },
        );
        const invalidOutput = `${invalid.stdout}\n${invalid.stderr}`;
        assert.notEqual(invalid.status, 0);
        assert.match(invalidOutput, /Invalid --fps "29\.97": ambiguous-decimal/);
        assert.doesNotMatch(invalidOutput, /CAPTURE_OPTIONS=/);
      } finally {
        rmSync(root, { recursive: true, force: true });
      }
    });
});

// The two package-loader.mjs copies are intentionally byte-identical (each
// skill ships standalone, so neither can import the other's) and now carry
// shared logic (initializeSessionWithRetry + FALLBACK_TRANSIENT_PATTERNS)
// that a future fix could land in one copy and silently miss in the other —
// the exact drift class the audio.mjs identity pin was born to catch.
describe("package-loader parity", () => {
  it("package-loader.mjs is byte-identical to hyperframes-creative's copy (the stated contract)", () => {
    const here = readFileSync(
      join(REPO_ROOT, "skills", "hyperframes-animation", "scripts", "package-loader.mjs"),
      "utf8",
    );
    const sibling = readFileSync(
      join(REPO_ROOT, "skills", "hyperframes-creative", "scripts", "package-loader.mjs"),
      "utf8",
    );
    assert.equal(here, sibling);
  });
});

// ── Transient-init retry (the zero-duration false-fail fix) ─────────────────
// A valid modular project's sub-composition timelines register asynchronously;
// the first initializeSession can time out with the transient "zero duration /
// Runtime ready: false" diagnostic. The render pipeline closes the crashed
// session and retries once with a fresh browser (probeStage) — the standalone
// helpers must do the same instead of reporting the project as zero-duration.

/** Write a fake node_modules with the given producer index.mjs source. */
function writeFakeEnv(root, producerIndexSource) {
  const packageDir = join(root, "node_modules", "@hyperframes", "producer");
  const corePackageDir = join(root, "node_modules", "@hyperframes", "core");
  const sharpPackageDir = join(root, "node_modules", "sharp");
  const compositionDir = join(root, "composition");
  mkdirSync(packageDir, { recursive: true });
  mkdirSync(corePackageDir, { recursive: true });
  mkdirSync(sharpPackageDir, { recursive: true });
  mkdirSync(compositionDir, { recursive: true });
  writeFileSync(
    join(packageDir, "package.json"),
    JSON.stringify({ name: "@hyperframes/producer", type: "module", exports: "./index.mjs" }),
  );
  writeFileSync(join(packageDir, "index.mjs"), producerIndexSource);
  writeFileSync(
    join(corePackageDir, "package.json"),
    JSON.stringify({
      name: "@hyperframes/core",
      type: "module",
      exports: { ".": "./index.mjs", "./compiler": "./compiler.mjs" },
    }),
  );
  writeFileSync(
    join(corePackageDir, "index.mjs"),
    "export function parseFps(input) { return { ok: true, value: { num: Number(input), den: 1 } }; }",
  );
  writeFileSync(
    join(corePackageDir, "compiler.mjs"),
    'export async function bundleToSingleHtml() { return "<!doctype html><main>x</main>"; }',
  );
  writeFileSync(
    join(sharpPackageDir, "package.json"),
    JSON.stringify({ name: "sharp", type: "module", exports: "./index.mjs" }),
  );
  writeFileSync(join(sharpPackageDir, "index.mjs"), "export default function sharp() {}\n");
  return compositionDir;
}

function runHelper(helper, root, compositionDir) {
  const result = spawnSync(process.execPath, [helper, compositionDir, "--out", join(root, "out")], {
    encoding: "utf8",
    env: { ...process.env, HYPERFRAMES_SKILL_NODE_MODULES: join(root, "node_modules") },
  });
  return `${result.stdout}\n${result.stderr}`;
}

const FAKE_PRODUCER_COMMON = [
  'export async function createFileServer() { return { url: "http://test", close() {} }; }',
  'export async function createCaptureSession() { console.error("SESSION_CREATED"); return {}; }',
  'export async function closeCaptureSession() { console.error("SESSION_CLOSED"); }',
  "export async function getCompositionDuration() { return 0; }",
].join("\n");

describe("transient-init retry", () => {
  for (const helper of HELPERS) {
    it(`${helper.split("/").at(-1)} retries a transient zero-duration init once with a fresh session`, () => {
      const root = mkdtempSync(join(tmpdir(), "hyperframes-skill-retry-test-"));
      try {
        const compositionDir = writeFakeEnv(
          root,
          [
            FAKE_PRODUCER_COMMON,
            "let initCalls = 0;",
            "export async function initializeSession() {",
            "  initCalls++;",
            "  if (initCalls === 1) {",
            // The transient shape: readiness deadline hit before async
            // sub-composition timelines landed (Runtime ready: false).
            '    throw new Error("Composition has zero duration after initialization.\\nRuntime ready: false");',
            "  }",
            '  throw new Error("INIT_ATTEMPT_2_REACHED");',
            "}",
          ].join("\n"),
        );

        const output = runHelper(helper, root, compositionDir);

        // Retried: fresh session created for attempt 2, crashed one closed.
        assert.match(output, /retrying with a fresh browser session/);
        assert.equal((output.match(/SESSION_CREATED/g) ?? []).length, 2);
        assert.equal((output.match(/SESSION_CLOSED/g) ?? []).length, 2);
        // ...and the retry genuinely re-ran init (bounded: no third attempt).
        assert.match(output, /INIT_ATTEMPT_2_REACHED/);
      } finally {
        rmSync(root, { recursive: true, force: true });
      }
    });

    it(`${helper.split("/").at(-1)} does NOT retry a genuine authoring failure (Runtime ready: true)`, () => {
      const root = mkdtempSync(join(tmpdir(), "hyperframes-skill-retry-test-"));
      try {
        const compositionDir = writeFakeEnv(
          root,
          [
            FAKE_PRODUCER_COMMON,
            "export async function initializeSession() {",
            // The fast-fail shape: runtime IS ready, there is genuinely no
            // timeline/duration — an authoring bug retries can't fix.
            '  throw new Error("Composition has zero duration after initialization.\\nRuntime ready: true");',
            "}",
          ].join("\n"),
        );

        const output = runHelper(helper, root, compositionDir);

        assert.doesNotMatch(output, /retrying with a fresh browser session/);
        assert.equal((output.match(/SESSION_CREATED/g) ?? []).length, 1);
        assert.match(output, /Composition has zero duration/);
      } finally {
        rmSync(root, { recursive: true, force: true });
      }
    });
  }

  it("prefers the producer's own isTransientBrowserError classifier when exported", () => {
    const root = mkdtempSync(join(tmpdir(), "hyperframes-skill-retry-test-"));
    try {
      const compositionDir = writeFakeEnv(
        root,
        [
          FAKE_PRODUCER_COMMON,
          // A message the frozen fallback patterns would NOT match — only the
          // producer-provided classifier can mark it transient.
          "export function isTransientBrowserError(err) { return String(err && err.message).includes('CUSTOM_TRANSIENT'); }",
          "let initCalls = 0;",
          "export async function initializeSession() {",
          "  initCalls++;",
          '  if (initCalls === 1) throw new Error("CUSTOM_TRANSIENT flake");',
          '  throw new Error("INIT_ATTEMPT_2_REACHED");',
          "}",
        ].join("\n"),
      );

      const output = runHelper(HELPERS[0], root, compositionDir);

      assert.match(output, /retrying with a fresh browser session/);
      assert.match(output, /INIT_ATTEMPT_2_REACHED/);
    } finally {
      rmSync(root, { recursive: true, force: true });
    }
  });
});
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 193kUpdated Claude CodeCodexVerifiedInstall