Add --data flag to render for parametrized renders (à la getRenderData)

[bigadamknight]

Why

Editframe shipped this same week as a key agent-facing feature: a single composition can be rendered with arbitrary JSON injected at render time, so a render farm or upstream agent can produce N variations of a video without forking the composition file.

npx editframe render --data '{"title":"Q4 Report","theme":"dark"}' -o output.mp4

…and inside the composition:

import { getRenderData } from "@editframe/elements";
const data = getRenderData();
document.querySelector('ef-text').textContent = data.title;

This is exactly what we want for HyperFrames. Right now the only way to template a composition is by writing the values into the source HTML before render — which means duplicating the entire project per variation.

Proposed API

CLI:

hyperframes render --data '{"title":"Q4 Report"}' -o out.mp4
hyperframes render --data-file render-data.json -o out.mp4   # convenience

Composition reads it via a tiny helper from @hyperframes/runtime (or wherever the existing browser-side helpers live):

<script type="module">
  import { getRenderData } from "@hyperframes/runtime";
  const { title } = getRenderData() ?? { title: "Default" };
  document.getElementById("hero").textContent = title;
</script>

Outside a render context, getRenderData() returns null (or whatever the studio injects in dev), so compositions are safe to author with sensible defaults.

Implementation sketch

1. packages/cli/src/commands/render.ts — add args:

   data: { type: "string", description: "JSON string injected at render time, readable via getRenderData()" },
   "data-file": { type: "string", description: "Path to a JSON file injected at render time" },

2. packages/cli/src/capture/... — when launching the Playwright page, before the page script runs, inject:

   await page.addInitScript((payload) => {
     window.__hyperframesRenderData = payload;
   }, parsedData);

3. packages/engine (or core) — export getRenderData():

   export function getRenderData<T = unknown>(): T | null {
     return (typeof window !== "undefined" && (window as any).__hyperframesRenderData) ?? null;
   }

4. Studio / preview — same addInitScript path, but wired off a --render-data query param or a studio control, so dev iteration matches render behaviour.
5. Docs — extend render.ts --help examples and add a "parametrized renders" section to docs/.

Why this matters now

Agents are the target user. Both Editframe and HyperFrames pitch as "agent-native". Without parametrized renders, an agent that wants to produce 50 personalised videos has to either (a) emit 50 forked compositions, or (b) pre-write the values into the HTML before each render. (a) is wasteful and breaks the "edit the source surgically" promise; (b) is fine but not great. --data collapses both into one render call per variation.

Bonus: this is the missing primitive for artefact-editor to sit above HyperFrames for parametrized exports — pass per-row data from a sheet, render N MP4s.

[jrusso1020]

@bigadamknight I have a series of PRs related to this would be curious to see if you have any feedback on them!