npm - hyper-animator-codex - Versions diffs - 0.3.0 → 0.5.0 - Mend

hyper-animator-codex 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md CHANGED Viewed

@@ -37,6 +37,21 @@ Use a custom Codex skills directory:
 npx hyper-animator-codex install --target /path/to/codex/skills
 ```
+## Git Checkpoints
+During `/hyper-animator` runs, the installed skill initializes a normal Git repository in a new output directory and creates rollback-friendly stage commits. It does not create branches or worktrees.
+The bundled helper can be run from an installed skill directory or repository checkout:
+```bash
+node skills/hyper-animator-codex/scripts/git_checkpoint.mjs \
+  --phase init \
+  --message "chore: initialize hyper animator workspace" \
+  --allow-empty
+```
+Existing Git repositories with uncommitted changes are protected: the helper stops instead of mixing user edits into automatic commits. Large video and audio files above 10 MB are skipped by default and recorded in a manifest under `hyper-animator-output/git-checkpoints/`.
 ## MiniMax Music Configuration
 MiniMax is the preferred generated-background-music provider. Configure it during install so the copied Codex skill can generate music without asking for credentials later:
@@ -68,10 +83,32 @@ ${CODEX_HOME:-$HOME/.codex}/skills/hyper-animator-codex/config/minimax.json
 Do not commit that installed config file. The npm package does not include local MiniMax credentials.
+## HTML Preview Controls
+Preview HTML can include a bottom page indicator and thin draggable progress bar:
+```bash
+node skills/hyper-animator-codex/scripts/inject_preview_controls.mjs composition.html -o composition.preview.html --force
+python3 skills/hyper-animator-codex/scripts/validate_hyperframes_html.py composition.preview.html --preview-controls
+```
+The injected controls support dragging the progress bar and using ArrowLeft or ArrowRight to move between pages.
+Use `data-preview-pages="0,3,6,9"` for explicit page starts, or `data-preview-page-count="4"` to divide the duration evenly.
+When rendering video, hide preview controls with any one of:
+```text
+?render=1
+?preview=0
+<html data-render-mode="video">
+```
 ## Contents
 - `skills/hyper-animator-codex/SKILL.md`: Codex skill instructions.
 - `skills/hyper-animator-codex/references/`: HyperFrames catalog map, workflow guide, pseudocode, and request examples.
+- `skills/hyper-animator-codex/scripts/git_checkpoint.mjs`: Git initialization and stage-commit helper for `/hyper-animator` runs.
 - `skills/hyper-animator-codex/scripts/validate_hyperframes_html.py`: static pre-render HTML quality gate.
 ## Optional Beat Detection

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "hyper-animator-codex",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Install the Hyper Animator Codex skill for Codex.",
   "type": "module",
   "bin": {

package/skills/hyper-animator-codex/SKILL.md CHANGED Viewed

@@ -11,21 +11,24 @@ Turn a natural-language animation or video brief into a validated HyperFrames HT
 ## Required Flow
-1. Capture the raw request and extract an initial intent profile: purpose, format, duration, content inputs, style tags, motion tags, and needed roles.
-2. If purpose, format, or core content is unclear, ask the first clarification round before choosing catalog items.
-3. Read `references/hyperframes-catalog-map.json` and score candidates by keyword, intent domain, format, role, style, motion, and constraints.
-4. Pick candidate blocks/components for main scene, caption, effects, transitions, and outro.
-5. Decide generation mode:
+1. Read `references/git-checkpoint-workflow.md` and run `scripts/git_checkpoint.mjs --phase init --message "chore: initialize hyper animator workspace" --allow-empty` before requirement capture. If the helper reports an existing dirty repository or linked worktree, stop and ask the user to resolve it.
+2. Capture the raw request and extract an initial intent profile: purpose, format, duration, content inputs, style tags, motion tags, and needed roles.
+3. If purpose, format, or core content is unclear, ask the first clarification round before choosing catalog items.
+4. Read `references/hyperframes-catalog-map.json` and score candidates by keyword, intent domain, format, role, style, motion, and constraints.
+5. Pick candidate blocks/components for main scene, caption, effects, transitions, and outro.
+6. Decide generation mode:
    - `generate_new_hyperframes_html` when the user asks to write HTML, create a new effect, customize style, match a brand, use complex animation, or when component snippets are only paste placeholders.
    - `assemble_existing_catalog_items` only when the user asks to use existing catalog items or quickly compose installed blocks/components.
-6. Clarify audio: ask whether to add animation/transition sound effects and whether to add background music.
-7. If background music is requested or undecided, read `references/minimax-music-workflow.md` and prefer MiniMax generation when configured. If MiniMax is unavailable or declined, ask for a local audio path or continue without BGM.
-8. If background music is used, read `references/beat-sync-workflow.md`, generate or obtain the audio, and run `scripts/analyze_music_beats.py` when the file is available.
-9. Ask the second clarification round with candidate context: visual direction, motion rhythm, generation mode, audio choices, music prompt/model when MiniMax is used, and beat-sync assumptions when background music is present.
-10. Write or assemble HTML. When beat-sync is enabled, align major reveals, cuts, transitions, camera moves, and visual accents to the beat map instead of arbitrary timestamps.
-11. Run pre-render quality gates.
-12. Show a concise plan summary and preview path or HTML file to the user. Ask for confirmation before video render.
-13. Render only after user confirmation, then report output path and any caveats.
+7. Clarify audio: ask whether to add animation/transition sound effects and whether to add background music.
+8. If background music is requested or undecided, read `references/minimax-music-workflow.md` and prefer MiniMax generation when configured. If MiniMax is unavailable or declined, ask for a local audio path or continue without BGM.
+9. If background music is used, read `references/beat-sync-workflow.md`, generate or obtain the audio, and run `scripts/analyze_music_beats.py` when the file is available.
+10. Ask the second clarification round with candidate context: visual direction, motion rhythm, generation mode, audio choices, music prompt/model when MiniMax is used, and beat-sync assumptions when background music is present.
+11. Write or assemble HTML. When beat-sync is enabled, align major reveals, cuts, transitions, camera moves, and visual accents to the beat map instead of arbitrary timestamps.
+12. After each file-writing stage, run `scripts/git_checkpoint.mjs` with the phase-specific allowlist from `references/git-checkpoint-workflow.md`. Do not create, switch, or recommend Git branches or worktrees.
+13. Run pre-render quality gates on the base HTML.
+14. Read `references/preview-controls-workflow.md`, run `scripts/inject_preview_controls.mjs` to create a preview HTML copy, and run `scripts/validate_hyperframes_html.py preview.html --preview-controls`.
+15. Show a concise plan summary and preview path or HTML file to the user. Ask for confirmation before video render.
+16. Render only after user confirmation. Prefer rendering the base HTML; if rendering the preview copy, use `?render=1`, `?preview=0`, or `<html data-render-mode="video">` so preview controls are hidden. Then report output path and any caveats.
 ## Interactive Questions
@@ -40,11 +43,13 @@ Do not ask everything upfront when the brief is already specific. Ask only for m
 ## References
+- Read `references/git-checkpoint-workflow.md` before any `/hyper-animator` run writes files or initializes output.
 - Read `references/hyperframes-intent-workflow.md` for the full AskUserQuestion workflow, generation-mode rules, scoring model, and render confirmation requirements.
 - Read `references/hyperframes-catalog-map.json` whenever selecting catalog candidates or determining visual references.
 - Read `references/hyperframes-agent-pseudocode.ts` when implementing the end-to-end loop or when the correct sequence is ambiguous.
 - Read `references/minimax-music-workflow.md` when generated background music, MiniMax, music prompt, instrumental/vocal choice, or provider fallback is mentioned.
 - Read `references/beat-sync-workflow.md` when sound effects, background music, soundtrack, beat sync, rhythm, BPM, audio-reactive animation, or transition timing to music is mentioned.
+- Read `references/preview-controls-workflow.md` before showing HTML previews or rendering after preview approval.
 - Use `references/examples/*.json` for sanity checks against common request shapes.
 ## Catalog Rules
@@ -76,6 +81,12 @@ Generated block HTML must include:
 - no wall-clock `Date.now()` or `setInterval()` driving primary timeline progress;
 - readable text at the target video dimensions.
+Preview HTML must pass:
+```bash
+python3 scripts/validate_hyperframes_html.py path/to/composition.preview.html --preview-controls
+```
 If the validator fails, fix the HTML before asking the user to approve render.
 ## Render Handoff
@@ -87,9 +98,13 @@ Before rendering, summarize:
 - sound effects and background music choices;
 - MiniMax provider status, model, generated audio path, metadata path, and redacted config source when MiniMax is used;
 - beat map path, BPM, duration, and timing assumptions when beat-sync is enabled;
+- base HTML path and preview HTML path;
+- preview controls injection status and page count source;
+- render-hidden signal used to hide preview controls during video render;
 - dimensions and duration;
 - content assumptions;
 - preview location;
 - validator result.
+- Git checkpoint status, latest commit hash, skipped large media manifest path, and any dirty-worktree caveats;
 Ask the user whether to render or revise. If rendering tools or project-specific commands are unavailable, stop at validated HTML and report the exact missing render command or dependency.

package/skills/hyper-animator-codex/references/git-checkpoint-workflow.md ADDED Viewed

@@ -0,0 +1,87 @@
+# Git Checkpoint Workflow
+Use this workflow whenever `/hyper-animator` writes files. The goal is rollback-friendly stage commits without creating branches or worktrees.
+## Start Of Run
+Run this before requirement capture or file generation:
+```bash
+node scripts/git_checkpoint.mjs \
+  --phase init \
+  --message "chore: initialize hyper animator workspace" \
+  --allow-empty
+```
+If the helper reports an existing repository with uncommitted changes, stop and ask the user to resolve those files before continuing.
+## Phase Commits
+Use explicit allowlists for every checkpoint:
+```bash
+node scripts/git_checkpoint.mjs \
+  --phase brief \
+  --message "feat: capture animation brief" \
+  --allow "hyper-animator-output/brief/**" \
+  --allow "hyper-animator-output/catalog/**"
+```
+```bash
+node scripts/git_checkpoint.mjs \
+  --phase base-html \
+  --message "feat: create base animation html" \
+  --allow "*.html" \
+  --allow "hyper-animator-output/html/**" \
+  --allow "hyper-animator-output/assets/**"
+```
+```bash
+node scripts/git_checkpoint.mjs \
+  --phase audio \
+  --message "feat: add audio assets" \
+  --allow "hyper-animator-output/music/**" \
+  --allow "hyper-animator-output/beat-maps/**"
+```
+```bash
+node scripts/git_checkpoint.mjs \
+  --phase preview \
+  --message "feat: add preview controls" \
+  --allow "*.preview.html" \
+  --allow "hyper-animator-output/preview/**"
+```
+```bash
+node scripts/git_checkpoint.mjs \
+  --phase render \
+  --message "chore: render animation video" \
+  --allow "hyper-animator-output/render/**" \
+  --allow "*.mp4" \
+  --allow "*.webm"
+```
+For preview feedback revisions:
+```bash
+node scripts/git_checkpoint.mjs \
+  --phase refine \
+  --message "refine: update animation from preview feedback" \
+  --allow "*.html" \
+  --allow "hyper-animator-output/**"
+```
+## Media Policy
+The default large media threshold is 10 MB. Large audio/video files are skipped unless `--include-large-media` is passed. When a file is skipped, the helper commits a manifest under:
+```text
+hyper-animator-output/git-checkpoints/<phase>-skipped-media.json
+```
+## Hard Rules
+- Do not run `git switch`, `git checkout -b`, `git branch`, or `git worktree add`.
+- Do not create or recommend branches or worktrees for `/hyper-animator` output.
+- Do not commit MiniMax credentials, `.firecrawl/`, `node_modules/`, or render caches.
+- If unrelated dirty files are reported, stop and ask the user before continuing.

package/skills/hyper-animator-codex/references/preview-controls-workflow.md ADDED Viewed

@@ -0,0 +1,54 @@
+# Preview Controls Workflow
+Use this whenever a generated or assembled HyperFrames HTML animation will be shown to the user for preview before video render.
+## Required Behavior
+HTML previews should include a bottom page indicator and thin progress bar. Users can drag the progress bar to seek, or press ArrowLeft and ArrowRight to move between pages.
+Video renders must hide those controls. Use one of these render-hidden signals:
+- `?render=1`
+- `?preview=0`
+- `<html data-render-mode="video">`
+## Page Model
+Prefer explicit page starts:
+```html
+data-preview-pages="0,3,6,9"
+```
+If exact page starts are not known, use:
+```html
+data-preview-page-count="4"
+```
+If neither attribute exists, the injector falls back to one page.
+## Generate Preview HTML
+After the base HTML passes normal quality gates, create a preview copy:
+```bash
+node scripts/inject_preview_controls.mjs composition.html -o composition.preview.html --force
+python3 scripts/validate_hyperframes_html.py composition.preview.html --preview-controls
+```
+Show the preview copy to the user for validation.
+## Render HTML
+Prefer rendering the base `composition.html` without preview controls. If the renderer must use the preview copy, render it with `?render=1`, `?preview=0`, or `<html data-render-mode="video">` so controls are hidden.
+## Handoff Summary
+Before rendering, report:
+- base HTML path;
+- preview HTML path;
+- whether preview controls were injected;
+- page count source: `data-preview-pages`, `data-preview-page-count`, or one-page fallback;
+- render-hidden signal to be used.

package/skills/hyper-animator-codex/scripts/git_checkpoint.mjs ADDED Viewed

@@ -0,0 +1,524 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+const FALLBACK_USER_NAME = "Hyper Animator Codex";
+const FALLBACK_USER_EMAIL = "hyper-animator-codex@local";
+const DEFAULT_MAX_BINARY_MB = 10;
+const SKIPPED_MANIFEST_DIR = join("hyper-animator-output", "git-checkpoints");
+const MEDIA_EXTENSIONS = new Set([
+  ".mp4",
+  ".mov",
+  ".webm",
+  ".mkv",
+  ".avi",
+  ".m4v",
+  ".mp3",
+  ".wav",
+  ".m4a",
+  ".aac",
+  ".flac",
+  ".ogg",
+  ".wma",
+]);
+const DEFAULT_EXCLUDES = [
+  ".firecrawl/",
+  ".gitconfig-global",
+  ".git/",
+  "node_modules/",
+  "config/minimax.json",
+  "skills/hyper-animator-codex/config/minimax.json",
+  "tmp/",
+  ".tmp/",
+];
+let repositoryRootCache = null;
+let gitPrefixCache = null;
+function requireValue(argv, index, flag) {
+  const value = argv[index + 1];
+  if (!value || value.startsWith("--")) {
+    throw new Error(`${flag} requires a value`);
+  }
+  return value;
+}
+function parseArgs(argv) {
+  const options = {
+    phase: "",
+    message: "",
+    allow: [],
+    exclude: [],
+    maxBinaryMb: DEFAULT_MAX_BINARY_MB,
+    includeLargeMedia: false,
+    allowEmpty: false,
+    dryRun: false,
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--phase") {
+      options.phase = requireValue(argv, index, arg);
+      index += 1;
+    } else if (arg === "--message") {
+      options.message = requireValue(argv, index, arg);
+      index += 1;
+    } else if (arg === "--allow") {
+      options.allow.push(requireValue(argv, index, arg));
+      index += 1;
+    } else if (arg === "--exclude") {
+      options.exclude.push(requireValue(argv, index, arg));
+      index += 1;
+    } else if (arg === "--max-binary-mb") {
+      options.maxBinaryMb = Number(requireValue(argv, index, arg));
+      index += 1;
+    } else if (arg === "--include-large-media") {
+      options.includeLargeMedia = true;
+    } else if (arg === "--allow-empty") {
+      options.allowEmpty = true;
+    } else if (arg === "--dry-run") {
+      options.dryRun = true;
+    } else {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+  if (!options.phase) {
+    throw new Error("--phase is required");
+  }
+  if (!options.message) {
+    throw new Error("--message is required");
+  }
+  if (!Number.isFinite(options.maxBinaryMb) || options.maxBinaryMb < 0) {
+    throw new Error("--max-binary-mb must be a non-negative number");
+  }
+  return options;
+}
+function git(args, { check = true } = {}) {
+  const result = spawnSync("git", args, {
+    cwd: process.cwd(),
+    encoding: "utf8",
+  });
+  if (check && result.status !== 0) {
+    const detail = result.stderr.trim() || result.stdout.trim() || `git ${args.join(" ")}`;
+    throw new Error(detail);
+  }
+  return result;
+}
+function normalizeGitPath(value) {
+  return value.trim().replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function repositoryRoot() {
+  if (repositoryRootCache !== null) {
+    return repositoryRootCache;
+  }
+  const result = git(["rev-parse", "--show-toplevel"], { check: false });
+  repositoryRootCache = result.status === 0 && result.stdout.trim() ? result.stdout.trim() : process.cwd();
+  return repositoryRootCache;
+}
+function gitPrefix() {
+  if (gitPrefixCache !== null) {
+    return gitPrefixCache;
+  }
+  const result = git(["rev-parse", "--show-prefix"], { check: false });
+  gitPrefixCache = result.status === 0 ? normalizeGitPath(result.stdout) : "";
+  return gitPrefixCache;
+}
+function cwdRelativeToGitPath(path) {
+  const prefix = gitPrefix();
+  return normalizeGitPath(prefix ? join(prefix, path) : path);
+}
+function resolveGitDirPath(value) {
+  const trimmed = value.trim();
+  const absolute = isAbsolute(trimmed) ? trimmed : resolve(process.cwd(), trimmed);
+  try {
+    return normalizeGitPath(realpathSync(absolute));
+  } catch {
+    return normalizeGitPath(absolute);
+  }
+}
+function isDefaultExcluded(path) {
+  const normalized = normalizeGitPath(path);
+  return DEFAULT_EXCLUDES.some((entry) => {
+    const cleaned = entry.endsWith("/") ? entry.slice(0, -1) : entry;
+    return normalized === cleaned || normalized.startsWith(`${cleaned}/`);
+  });
+}
+function isInsideGitRepo() {
+  const result = git(["rev-parse", "--is-inside-work-tree"], { check: false });
+  return result.status === 0 && result.stdout.trim() === "true";
+}
+function isLinkedWorktree() {
+  const gitDir = resolveGitDirPath(git(["rev-parse", "--git-dir"]).stdout);
+  const commonDir = resolveGitDirPath(git(["rev-parse", "--git-common-dir"]).stdout);
+  return gitDir !== commonDir;
+}
+function hasAnyCommit() {
+  return git(["rev-parse", "--verify", "HEAD"], { check: false }).status === 0;
+}
+function parsePorcelainLine(line) {
+  const path = line.slice(3).replace(/^"|"$/g, "");
+  const target = path.includes(" -> ") ? path.split(" -> ").pop() : path;
+  return normalizeGitPath(target);
+}
+function porcelainLines(pathspecs = []) {
+  const args = ["status", "--porcelain=v1", "--untracked-files=all"];
+  if (pathspecs.length > 0) {
+    args.push("--", ...pathspecs);
+  }
+  return git(args, { check: true }).stdout
+    .split("\n")
+    .map((line) => line.trimEnd())
+    .filter(Boolean);
+}
+function dirtyLines() {
+  return porcelainLines().filter((line) => !isDefaultExcluded(parsePorcelainLine(line)));
+}
+function allDirtyFiles(pathspecs = []) {
+  const seen = new Set();
+  return porcelainLines(pathspecs)
+    .map(parsePorcelainLine)
+    .filter((path) => !isDefaultExcluded(path))
+    .filter((path) => {
+      if (seen.has(path)) {
+        return false;
+      }
+      seen.add(path);
+      return true;
+    });
+}
+function trackedOrUntrackedMatching(pathspecs) {
+  return allDirtyFiles(pathspecs);
+}
+function stagedFiles() {
+  return git(["diff", "--cached", "--name-only", "--diff-filter=ACDMR"], { check: true }).stdout
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map(normalizeGitPath);
+}
+function patternToRegExp(pattern) {
+  let escaped = "";
+  for (let index = 0; index < pattern.length; index += 1) {
+    const char = pattern[index];
+    if (char === "*") {
+      if (pattern[index + 1] === "*") {
+        escaped += ".*";
+        index += 1;
+      } else {
+        escaped += "[^/]*";
+      }
+    } else if (/[.+^${}()|[\]\\]/.test(char)) {
+      escaped += `\\${char}`;
+    } else {
+      escaped += char;
+    }
+  }
+  return new RegExp(`^${escaped}$`);
+}
+function isExplicitlyExcluded(path, patterns) {
+  return patterns.some((pattern) => {
+    const normalized = normalizeGitPath(pattern);
+    if (normalized.endsWith("/")) {
+      return path.startsWith(normalized);
+    }
+    if (normalized.includes("*")) {
+      return patternToRegExp(normalized).test(path);
+    }
+    return path === normalized;
+  });
+}
+function ensureIdentity() {
+  const name = git(["config", "--get", "user.name"], { check: false }).stdout.trim();
+  const email = git(["config", "--get", "user.email"], { check: false }).stdout.trim();
+  if (!name) {
+    git(["config", "--local", "user.name", FALLBACK_USER_NAME]);
+  }
+  if (!email) {
+    git(["config", "--local", "user.email", FALLBACK_USER_EMAIL]);
+  }
+}
+function extensionOf(path) {
+  const index = path.lastIndexOf(".");
+  return index === -1 ? "" : path.slice(index).toLowerCase();
+}
+function fileSizeBytes(path) {
+  const fsPath = isAbsolute(path) ? path : join(repositoryRoot(), path);
+  try {
+    return statSync(fsPath).size;
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return 0;
+    }
+    throw error;
+  }
+}
+function isLargeMedia(path, maxBinaryMb) {
+  return MEDIA_EXTENSIONS.has(extensionOf(path)) && fileSizeBytes(path) > maxBinaryMb * 1024 * 1024;
+}
+function writeSkippedMediaManifest(phase, skipped) {
+  if (skipped.length === 0) {
+    return null;
+  }
+  mkdirSync(SKIPPED_MANIFEST_DIR, { recursive: true });
+  const manifestPath = join(SKIPPED_MANIFEST_DIR, `${phase}-skipped-media.json`);
+  const manifest = {
+    phase,
+    skipped: skipped.map((path) => ({
+      path,
+      size_bytes: fileSizeBytes(path),
+      reason: "larger than max-binary-mb",
+    })),
+  };
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+  return cwdRelativeToGitPath(manifestPath);
+}
+function readKnownSkippedMedia() {
+  const known = new Set();
+  if (!existsSync(SKIPPED_MANIFEST_DIR)) {
+    return known;
+  }
+  for (const entry of readdirSync(SKIPPED_MANIFEST_DIR, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith("-skipped-media.json")) {
+      continue;
+    }
+    const manifestPath = join(SKIPPED_MANIFEST_DIR, entry.name);
+    let manifest;
+    try {
+      manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+    } catch {
+      continue;
+    }
+    if (!Array.isArray(manifest?.skipped)) {
+      continue;
+    }
+    for (const item of manifest.skipped) {
+      const path = typeof item === "string" ? item : item?.path;
+      if (typeof path === "string" && path.trim()) {
+        known.add(normalizeGitPath(path));
+      }
+    }
+  }
+  return known;
+}
+function stageFiles(paths) {
+  if (paths.length > 0) {
+    git(["add", "--", ...paths.map((path) => `:(top)${normalizeGitPath(path)}`)]);
+  }
+}
+function planStageFiles(options) {
+  const dirty = allDirtyFiles();
+  const selected = trackedOrUntrackedMatching(options.allow);
+  const selectedSet = new Set(selected);
+  const knownSkippedMedia = readKnownSkippedMedia();
+  const explicitExcluded = new Set();
+  const stageable = [];
+  const skippedMedia = [];
+  for (const path of dirty) {
+    if (isExplicitlyExcluded(path, options.exclude)) {
+      explicitExcluded.add(path);
+    }
+  }
+  for (const path of selected) {
+    if (isDefaultExcluded(path) || isExplicitlyExcluded(path, options.exclude)) {
+      continue;
+    }
+    if (!options.includeLargeMedia && isLargeMedia(path, options.maxBinaryMb)) {
+      skippedMedia.push(path);
+      continue;
+    }
+    stageable.push(path);
+  }
+  const skippedSet = new Set(skippedMedia);
+  const unrelated = dirty.filter((path) => {
+    if (selectedSet.has(path) || explicitExcluded.has(path) || skippedSet.has(path)) {
+      return false;
+    }
+    return options.includeLargeMedia || !knownSkippedMedia.has(path) || !isLargeMedia(path, options.maxBinaryMb);
+  });
+  return { stageable, skippedMedia, unrelated };
+}
+function ensureOnlyPlannedFilesStaged(expectedPaths) {
+  const expected = new Set(expectedPaths.map(normalizeGitPath));
+  const unexpected = stagedFiles().filter((path) => !expected.has(path));
+  if (unexpected.length > 0) {
+    throw new Error(`Existing repository has staged files outside the planned set:\n${unexpected.join("\n")}`);
+  }
+}
+function createCommit(message, allowEmpty) {
+  const args = ["commit"];
+  if (allowEmpty) {
+    args.push("--allow-empty");
+  }
+  args.push("-m", message);
+  const result = git(args, { check: false });
+  const output = `${result.stdout}\n${result.stderr}`;
+  if (result.status !== 0 && /nothing to commit|no changes added/i.test(output)) {
+    return false;
+  }
+  if (result.status !== 0) {
+    throw new Error(output.trim() || `git ${args.join(" ")}`);
+  }
+  return true;
+}
+function main(argv = process.argv.slice(2)) {
+  const options = parseArgs(argv);
+  if (options.phase !== "init" && options.allow.length === 0) {
+    throw new Error("--allow is required for non-init phases");
+  }
+  if (options.dryRun) {
+    console.log(`dry run: phase=${options.phase} message=${options.message}`);
+    console.log(isInsideGitRepo() ? "dry run: existing Git repository detected" : "dry run: would initialize Git repository");
+    return;
+  }
+  const startedInsideRepo = isInsideGitRepo();
+  if (startedInsideRepo && isLinkedWorktree()) {
+    throw new Error("Refusing to run in a linked worktree. Use a normal repository directory for /hyper-animator.");
+  }
+  if (startedInsideRepo) {
+    if (options.phase === "init" && hasAnyCommit()) {
+      const dirty = dirtyLines();
+      if (dirty.length > 0) {
+        throw new Error(`Existing repository has uncommitted changes:\n${dirty.join("\n")}`);
+      }
+      ensureIdentity();
+      console.log(`checkpoint ${options.phase}: ${git(["rev-parse", "--short", "HEAD"]).stdout.trim()}`);
+      return;
+    }
+  } else {
+    git(["init"]);
+  }
+  ensureIdentity();
+  if (!hasAnyCommit()) {
+    const plan = planStageFiles({ ...options, allow: [] });
+    ensureOnlyPlannedFilesStaged(plan.stageable);
+    const manifestPath = writeSkippedMediaManifest(options.phase, plan.skippedMedia);
+    const stageable = manifestPath ? [...plan.stageable, manifestPath] : plan.stageable;
+    stageFiles(stageable);
+    ensureOnlyPlannedFilesStaged(stageable);
+    if (!createCommit(options.message, options.allowEmpty)) {
+      throw new Error("nothing to commit");
+    }
+  } else {
+    const plan = planStageFiles(options);
+    if (plan.unrelated.length > 0) {
+      throw new Error(`Existing repository has unrelated dirty files outside allowlist:\n${plan.unrelated.join("\n")}`);
+    }
+    ensureOnlyPlannedFilesStaged(plan.stageable);
+    const manifestPath = writeSkippedMediaManifest(options.phase, plan.skippedMedia);
+    const stageable = manifestPath ? [...plan.stageable, manifestPath] : plan.stageable;
+    stageFiles(stageable);
+    ensureOnlyPlannedFilesStaged(stageable);
+    if (!createCommit(options.message, options.allowEmpty)) {
+      throw new Error("nothing to commit");
+    }
+  }
+  console.log(`checkpoint ${options.phase}: ${git(["rev-parse", "--short", "HEAD"]).stdout.trim()}`);
+}
+try {
+  main();
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+  process.exitCode = 1;
+}

package/skills/hyper-animator-codex/scripts/inject_preview_controls.mjs ADDED Viewed

@@ -0,0 +1,338 @@
+#!/usr/bin/env node
+import { readFile, stat, writeFile } from "node:fs/promises";
+const MARKER = "<!-- hyper-animator-preview-controls:start -->";
+const PREVIEW_UI_MARKER = /<[A-Za-z][A-Za-z0-9:-]*(?:\s[^<>]*?)?\sdata-hyper-preview-ui(?:\s|=|\/?>)/i;
+function parseArgs(args) {
+  const parsed = { input: undefined, output: undefined, force: false, componentId: undefined };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "-o" || arg === "--output") {
+      parsed.output = requireValue(args, index, arg);
+      index += 1;
+    } else if (arg === "--force") {
+      parsed.force = true;
+    } else if (arg === "--component-id") {
+      parsed.componentId = requireValue(args, index, arg);
+      index += 1;
+    } else if (arg === "--help" || arg === "-h") {
+      parsed.help = true;
+    } else if (!parsed.input) {
+      parsed.input = arg;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  return parsed;
+}
+function requireValue(args, index, flag) {
+  const value = args[index + 1];
+  if (!value || value.startsWith("-")) {
+    throw new Error(`${flag} requires a value`);
+  }
+  return value;
+}
+function printHelp() {
+  console.log(`Usage:
+  node scripts/inject_preview_controls.mjs input.html [-o preview.html] [--force] [--component-id <id>]
+Options:
+  -o, --output <file>      Write preview HTML to a separate file
+  --force                 Allow overwriting the output file
+  --component-id <id>     Use a specific data-composition-id for timeline seeking
+`);
+}
+async function pathExists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch (error) {
+    if (error && error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+function findCompositionId(html, explicitId) {
+  if (explicitId) return explicitId;
+  const match = html.match(/data-composition-id\s*=\s*["']([^"']+)["']/i);
+  if (!match) {
+    throw new Error("Cannot inject preview controls: missing data-composition-id. Pass --component-id to override.");
+  }
+  return match[1];
+}
+function serializeJsString(value) {
+  return JSON.stringify(value)
+    .replace(/</g, "\\u003C")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+}
+function findTagEnd(html, startIndex) {
+  let quote = null;
+  for (let index = startIndex + 1; index < html.length; index += 1) {
+    const char = html[index];
+    if (quote) {
+      if (char === quote) {
+        quote = null;
+      }
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (char === ">") {
+      return index;
+    }
+  }
+  return -1;
+}
+function scanLastClosingBodyTagIndex(html) {
+  const lower = html.toLowerCase();
+  let index = 0;
+  let lastClosingBodyTagIndex = -1;
+  let rawTextTag = "";
+  while (index < html.length) {
+    if (rawTextTag) {
+      const closingTag = `</${rawTextTag}`;
+      const closingTagIndex = lower.indexOf(closingTag, index);
+      if (closingTagIndex === -1) {
+        return lastClosingBodyTagIndex;
+      }
+      const closingTagEndIndex = findTagEnd(html, closingTagIndex);
+      if (closingTagEndIndex === -1) {
+        return lastClosingBodyTagIndex;
+      }
+      index = closingTagEndIndex + 1;
+      rawTextTag = "";
+      continue;
+    }
+    const nextTagIndex = html.indexOf("<", index);
+    if (nextTagIndex === -1) {
+      return lastClosingBodyTagIndex;
+    }
+    if (lower.startsWith("<!--", nextTagIndex)) {
+      const commentEndIndex = lower.indexOf("-->", nextTagIndex + 4);
+      if (commentEndIndex === -1) {
+        return lastClosingBodyTagIndex;
+      }
+      index = commentEndIndex + 3;
+      continue;
+    }
+    const tagEndIndex = findTagEnd(html, nextTagIndex);
+    if (tagEndIndex === -1) {
+      return lastClosingBodyTagIndex;
+    }
+    const tagContent = lower.slice(nextTagIndex + 1, tagEndIndex).trimStart();
+    if (/^\/\s*body\b/.test(tagContent)) {
+      lastClosingBodyTagIndex = nextTagIndex;
+    } else if (/^(script|style|textarea|title)\b/.test(tagContent)) {
+      rawTextTag = tagContent.match(/^(script|style|textarea|title)\b/)[1];
+    }
+    index = tagEndIndex + 1;
+  }
+  return lastClosingBodyTagIndex;
+}
+function findLastClosingBodyTagIndex(html) {
+  return scanLastClosingBodyTagIndex(html);
+}
+function injectPreviewControls(html, componentId) {
+  if (PREVIEW_UI_MARKER.test(html)) {
+    return html;
+  }
+  const escapedId = serializeJsString(componentId);
+  const controls = `<!-- hyper-animator-preview-controls:start -->
+<style data-hyper-preview-style>
+.hyper-preview-ui {
+  position: fixed;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  z-index: 2147483647;
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr);
+  align-items: center;
+  gap: 10px;
+  padding: 6px 10px 8px;
+  color: rgba(255, 255, 255, 0.86);
+  font: 12px/1.2 system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  pointer-events: none;
+  background: linear-gradient(to top, rgba(0, 0, 0, 0.34), rgba(0, 0, 0, 0));
+}
+.hyper-preview-ui[hidden] {
+  display: none !important;
+}
+.hyper-preview-page {
+  min-width: 42px;
+  text-align: center;
+  font-variant-numeric: tabular-nums lining-nums;
+  text-shadow: 0 1px 2px rgba(0, 0, 0, 0.45);
+}
+.hyper-preview-progress {
+  width: 100%;
+  height: 3px;
+  accent-color: rgba(255, 255, 255, 0.92);
+  cursor: pointer;
+  pointer-events: auto;
+}
+</style>
+<div class="hyper-preview-ui" data-hyper-preview-ui hidden aria-label="Animation preview controls">
+  <div class="hyper-preview-page" data-hyper-preview-page aria-live="polite">1 / 1</div>
+  <input class="hyper-preview-progress" data-hyper-preview-progress type="range" min="0" max="1000" step="1" value="0" aria-label="Preview progress" />
+</div>
+<script data-hyper-preview-script>
+(function () {
+  const componentId = ${escapedId};
+  const params = new URLSearchParams(window.location.search);
+  const renderMode = params.get("render") === "1" || params.get("preview") === "0" || document.documentElement.dataset.renderMode === "video";
+  const root = document.querySelector("[data-hyper-preview-ui]");
+  if (!root) return;
+  if (renderMode) {
+    root.hidden = true;
+    root.style.display = "none";
+    return;
+  }
+  const pageLabel = root.querySelector("[data-hyper-preview-page]");
+  const progress = root.querySelector("[data-hyper-preview-progress]");
+  const composition = findComposition();
+  const duration = readDuration(composition);
+  const pages = readPages(composition, duration);
+  let pageIndex = 0;
+  root.hidden = false;
+  root.style.display = "";
+  updateForTime(0);
+  progress.addEventListener("input", function () {
+    const seconds = (Number(progress.value) / Number(progress.max)) * duration;
+    seek(seconds);
+    updateForTime(seconds);
+  });
+  document.addEventListener("keydown", function (event) {
+    if (event.defaultPrevented || event.metaKey || event.ctrlKey || event.altKey || renderMode) return;
+    if (event.key === "ArrowLeft") {
+      event.preventDefault();
+      goToPage(Math.max(0, pageIndex - 1));
+    } else if (event.key === "ArrowRight") {
+      event.preventDefault();
+      goToPage(Math.min(pages.length - 1, pageIndex + 1));
+    }
+  });
+  function readDuration(element) {
+    const raw = element ? Number(element.dataset.duration) : NaN;
+    const timelineDuration = getTimeline() && typeof getTimeline().duration === "function" ? Number(getTimeline().duration()) : NaN;
+    const value = Number.isFinite(raw) && raw > 0 ? raw : timelineDuration;
+    return Number.isFinite(value) && value > 0 ? value : 1;
+  }
+  function readPages(element, totalDuration) {
+    if (element && element.dataset.previewPages) {
+      const parsed = element.dataset.previewPages.split(",").map((value) => Number(value.trim())).filter((value) => Number.isFinite(value) && value >= 0 && value <= totalDuration);
+      if (parsed.length > 0) return parsed;
+    }
+    const count = element && Number.parseInt(element.dataset.previewPageCount || "", 10);
+    if (Number.isFinite(count) && count > 1) {
+      return Array.from({ length: count }, (_, index) => (totalDuration / count) * index);
+    }
+    return [0];
+  }
+  function getTimeline() {
+    return window.__timelines && window.__timelines[componentId];
+  }
+  function findComposition() {
+    const compositions = document.querySelectorAll("[data-composition-id]");
+    for (const element of compositions) {
+      if (element.dataset.compositionId === componentId) {
+        return element;
+      }
+    }
+    return null;
+  }
+  function seek(seconds) {
+    const timeline = getTimeline();
+    if (!timeline) return;
+    if (typeof timeline.time === "function") {
+      timeline.time(Math.max(0, Math.min(duration, seconds)));
+    } else if (typeof timeline.progress === "function") {
+      timeline.progress(Math.max(0, Math.min(1, seconds / duration)));
+    }
+  }
+  function goToPage(nextIndex) {
+    pageIndex = nextIndex;
+    const seconds = pages[pageIndex] || 0;
+    seek(seconds);
+    updateForTime(seconds);
+  }
+  function updateForTime(seconds) {
+    pageIndex = activePageIndex(seconds);
+    pageLabel.textContent = String(pageIndex + 1) + " / " + String(pages.length);
+    progress.value = String(Math.round((Math.max(0, Math.min(duration, seconds)) / duration) * Number(progress.max)));
+  }
+  function activePageIndex(seconds) {
+    let active = 0;
+    for (let index = 0; index < pages.length; index += 1) {
+      if (seconds + 0.0001 >= pages[index]) active = index;
+    }
+    return active;
+  }
+})();
+</script>
+<!-- hyper-animator-preview-controls:end -->`;
+  const closingBodyTagIndex = findLastClosingBodyTagIndex(html);
+  if (closingBodyTagIndex !== -1) {
+    return `${html.slice(0, closingBodyTagIndex)}${controls}\n${html.slice(closingBodyTagIndex)}`;
+  }
+  return `${html}\n${controls}\n`;
+}
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.help) {
+    printHelp();
+    return;
+  }
+  if (!options.input) {
+    throw new Error("input.html is required");
+  }
+  const output = options.output || options.input;
+  if (options.output && !options.force && await pathExists(output)) {
+    throw new Error(`Output already exists: ${output}. Re-run with --force to overwrite.`);
+  }
+  const html = await readFile(options.input, "utf8");
+  const componentId = findCompositionId(html, options.componentId);
+  await writeFile(output, injectPreviewControls(html, componentId), "utf8");
+  console.log(`Preview controls written to: ${output}`);
+}
+main().catch((error) => {
+  console.error(`Error: ${error.message}`);
+  process.exitCode = 1;
+});

package/skills/hyper-animator-codex/scripts/validate_hyperframes_html.py CHANGED Viewed

@@ -13,7 +13,12 @@ def has_attr(html: str, name: str) -> bool:
     return re.search(rf"\b{name}\s*=\s*['\"]?[^'\"\s>]+", html, re.IGNORECASE) is not None
-def check_html(html: str, *, component: bool = False) -> tuple[list[str], list[str]]:
+def check_html(
+    html: str,
+    *,
+    component: bool = False,
+    preview_controls: bool = False,
+) -> tuple[list[str], list[str]]:
     failures: list[str] = []
     warnings: list[str] = []
@@ -51,6 +56,24 @@ def check_html(html: str, *, component: bool = False) -> tuple[list[str], list[s
     if len(re.findall(r"data-duration\s*=\s*['\"]?(\d+(?:\.\d+)?)", html)) > 1:
         warnings.append("multiple data-duration values found; verify the intended render duration")
+    if preview_controls:
+        if "data-hyper-preview-ui" not in html:
+            failures.append("missing preview controls: data-hyper-preview-ui")
+        if "data-hyper-preview-page" not in html:
+            failures.append("missing preview controls: page indicator")
+        if "data-hyper-preview-progress" not in html:
+            failures.append("missing preview controls: progress input")
+        if not re.search(r"<input[^>]+type=[\"']range[\"']", html, re.IGNORECASE | re.DOTALL):
+            failures.append("missing preview controls: range input")
+        if "ArrowLeft" not in html or "ArrowRight" not in html:
+            failures.append("missing preview controls: left/right keyboard handlers")
+        if 'params.get("render") === "1"' not in html:
+            failures.append("missing preview controls: ?render=1 hidden-mode check")
+        if 'params.get("preview") === "0"' not in html:
+            failures.append("missing preview controls: ?preview=0 hidden-mode check")
+        if 'dataset.renderMode === "video"' not in html:
+            failures.append("missing preview controls: data-render-mode video hidden-mode check")
     return failures, warnings
@@ -62,6 +85,11 @@ def main() -> int:
         action="store_true",
         help="Validate a component snippet instead of a full block composition",
     )
+    parser.add_argument(
+        "--preview-controls",
+        action="store_true",
+        help="Require injected Hyper Animator preview controls",
+    )
     args = parser.parse_args()
     path = Path(args.html_file)
@@ -70,7 +98,11 @@ def main() -> int:
         return 2
     html = path.read_text(encoding="utf-8")
-    failures, warnings = check_html(html, component=args.component)
+    failures, warnings = check_html(
+        html,
+        component=args.component,
+        preview_controls=args.preview_controls,
+    )
     for warning in warnings:
         print(f"WARN: {warning}", file=sys.stderr)