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

hyper-animator-codex 0.3.0 → 0.4.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 (6) hide show

package/README.md CHANGED Viewed

@@ -68,6 +68,27 @@ ${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.

package/package.json CHANGED Viewed

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

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

@@ -23,9 +23,10 @@ Turn a natural-language animation or video brief into a validated HyperFrames HT
 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.
+11. Run pre-render quality gates on the base HTML.
+12. 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`.
+13. Show a concise plan summary and preview path or HTML file to the user. Ask for confirmation before video render.
+14. 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
@@ -45,6 +46,7 @@ Do not ask everything upfront when the brief is already specific. Ask only for m
 - 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 +78,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,6 +95,9 @@ 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;

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/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)