Hyperframes engine ignores project variables — `project-set-var` + `project-render` produces template demo text instead of stored content

[Billthorpe522]

Summary

The project-set-var + project-render flow stores variables on the project, but the Hyperframes engine never substitutes them into the template HTML. Every render against a template with hardcoded copy produces a video with the template's demo text — inspect-template's inputs.schema is honoured by the CLI but ignored by the adapter.

Reproduction

git clone https://github.com/nexu-io/html-video.git
cd html-video && pnpm install && pnpm -r build && npx playwright install chromium

node packages/cli/dist/bin.js project-create --name "var-test" --intent "Test" --aspect 16:9
# returns: proj_<id>

node packages/cli/dist/bin.js project-set-template proj_<id> --template frame-light-leak-cinema

node packages/cli/dist/bin.js project-set-var proj_<id> --key title --value "Real relics."
node packages/cli/dist/bin.js project-set-var proj_<id> --key subtitle --value "Brass Boot Relics"
node packages/cli/dist/bin.js project-set-var proj_<id> --key duration_sec --value 6

node packages/cli/dist/bin.js project-render proj_<id> --output out.mp4

project-show confirms the vars are stored:

"variables":{"title":"Real relics.","subtitle":"Brass Boot Relics","duration_sec":6}

But the rendered MP4 shows the template's hardcoded demo text: REEL 03 · CH I · MMXXVI, A Quiet Year in Berlin, 52.5200° N · 13.4050° E.

Root cause

packages/adapter-hyperframes/dist/render.js, renderToHtml() injects the variables onto window.__HV_VARS__ but does not substitute them into the HTML body:

// ~line 513
const augmented = sourceHtml.replace('</body>', `<script>
window.__HV_VARS__ = ${JSON.stringify(input.variables)};
window.__HV_DURATION__ = ${...};
</script></body>`);

The source HTML (e.g. templates/frame-light-leak-cinema/source/index.html) has hardcoded text in <header>, <main>, <footer> — no {{title}} placeholders, no DOM-level substitution before render.

The README advertises "your agent writes plain HTML and the framework renders it to MP4" and every template's inputs.schema implies fillable slots — so the gap between "schema exists, vars stored, render ignores them" is the user-facing break.

Suggested fix

One of:

1. Template-side placeholders + engine-side substitution. Update template sources to use {{title}} / {{subtitle}} / {{duration_sec}} markers; have renderToHtml do a String.replace against input.variables before writing the preview HTML.
2. data-html-video-var attribute protocol. Templates mark fillable nodes with data-html-video-var="title"; the engine walks the DOM and sets textContent before recording.
3. Hide the inputs.schema on stock frame-* templates until they're upgraded, so the CLI rejects var-set calls instead of silently dropping them.

The README's Roadmap lists "Agent skill packages" and Remotion adapter work; var injection belongs on the same list — without it, every render is a stock template showcase, not a content-driven video.

Environment

• html-video v0.1.0 (cloned Jun 26 2026)
• Node v24.14.0
• Playwright chromium-1228
• Windows 11 / git-bash

[lefarcen]

Hi @Billthorpe522! Really helpful report — the repro steps and code pointer made this straightforward to verify.

I checked the Hyperframes path in packages/adapter-hyperframes/src/render.ts: renderToHtml() currently only appends window.__HV_VARS__ / window.__HV_DURATION__ before </body>, while templates/frame-light-leak-cinema/template.html-video.yaml advertises title, subtitle, and duration_sec in inputs.schema and the template HTML still contains hardcoded copy. So this looks like a real user-facing bug, not just a docs mismatch.

I’ve tagged it as a bug and we’ll track it that way. I don’t want to lock in a fix contract yet because the adapter/template boundary still needs a maintainer decision, but the core break is clear: project variables are being stored and surfaced to the renderer without ever being applied to the template DOM. If you want to take a crack at a PR once that direction is settled, happy to review it.

[walliai666]

/claim

[lefarcen]

Hey @walliai666 — thanks for picking this up.

Roughly how long do you think it'll take: a few hours, 1–3 days, about a week, or longer?

[lefarcen]

Heads-up: PR #77 is now open to carry this through the renderer path. It parameterises the affected stock templates with {{key}} placeholders, updates the Hyperframes adapter to substitute variables before injecting window.__HV_VARS__, and makes Studio previews render the first example values instead of raw tokens.

Keeping this issue open until that PR lands and the fix is in main.

[lefarcen]

Hey @walliai666 — gentle check: are you still planning to take this one, or is anything blocking you?

[lefarcen]

Hey @walliai666, gentle check — still on this one, or is anything blocking you?

[lefarcen]

Hey @walliai666 — quick check-in: are you still planning to take this one, or is anything blocking you?

[lefarcen]

Hey @walliai666 — gentle check: are you still on this one? Anything blocking?

[lefarcen]

Hey @walliai666 — gentle check: are you still on this one? Anything blocking?

[lefarcen]

Hey @walliai666, gentle check — still on this one? Anything blocking?

[lefarcen]

Hey @walliai666, last nudge — if there’s no signal by tomorrow, we’ll reopen this for the community. Any quick update is enough to keep the claim.