feat: RFC — lightweight @hyperframes/validator package & browser-side pipeline for third-party integrations

[Breno-Oliveira10]

Problem

Summary

I'm developing AutoEdit, a browser-based non-linear editor (NLE) that uses HyperFrames for AI-driven motion graphics generation (Gemini). During integration, I ran into a tight coupling problem: to validate compositions and render them deterministically, I need to install @hyperframes/engine, @hyperframes/producer and @hyperframes/core as backend dependencies.

This creates a heavy dependency chain for any editor or third-party tool that wants to integrate HyperFrames motion graphics — they are forced to include the full rendering pipeline, even when they only need validation and a rendering endpoint.

Problem

Currently, integrating HyperFrames into a custom editor requires:

npm install @hyperframes/engine @hyperframes/producer @hyperframes/core
# + FFmpeg installed on the system
# + chrome-headless-shell (auto-downloaded by the engine)

This means every developer building HyperFrames-based solutions must:

1. Run their own Chrome headless instance
2. Manage FFmpeg as a system dependency
3. Implement their own linting/validation pipeline using @hyperframes/core
4. Keep all packages in sync

This RFC proposes discussing complementary approaches to reduce this friction and expand the HyperFrames ecosystem.

---

Use Cases

Use Case 1 — Browser-based NLE / video editor

A browser-based non-linear editor that uses a generative AI model (Gemini, GPT, Claude) to produce HyperFrames compositions from natural language prompts (my case). The editor needs to validate the generated HTML before showing a preview to the user. Today, this forces the full stack (engine + producer) onto the backend just to run the linter — even when the render itself happens later via the producer.

Use Case 2 — Template SaaS platform

A service that offers motion graphics templates to content creators. Users customize templates via a form (brand colors, text, logo, fonts...) and the platform renders the final MP4. Currently, the operator must provision and maintain Chrome headless and FFmpeg on every server instance. A lightweight validation step before dispatching to the render queue would significantly reduce failed renders — but installing the full producer just for pre-validation is overkill.

Use Case 3 — Automated AI content pipeline

A batch processing system that generates intros, faceless-explainer videos, lower-thirds, CTAs, etc. at scale using AI, producing multiple compositions per run. Each composition needs to be validated before entering the render queue, to avoid wasting compute on malformed HTML. The team needs to validate compositions in a lightweight step before they ever reach the render worker — something difficult today without pulling the entire render dependency tree.

---

Proposed solution

Proposed Alternatives — Not a Replacement, but a Complement

I am not proposing to replace the existing @hyperframes/producer pipeline. The FFmpeg + Chrome headless combination is the right choice for deterministic, pixel-perfect renders at production level, and it should remain as is.

Three alternatives, ordered by implementation complexity:

---

Alternative A — @hyperframes/validator (lightweight package)

Extract the lint/validate logic from @hyperframes/core into a standalone package with no heavy dependencies:

npm install @hyperframes/validator
# No FFmpeg. No Chrome. No engine. No producer.

import { validateComposition } from '@hyperframes/validator';

const result = await validateComposition(html);

if (!result.ok) {
  // Show errors to the user before even attempting to render
  console.error(result.findings);
} else {
  // Safe to dispatch to the render pipeline
  dispatchToProducer(html);
}

This solves the authoring-time validation problem for all the use cases mentioned above, without changing the rendering pipeline in any way. Small scope, high impact.

---

Alternative B — @hyperframes/validator-browser + browser-side rendering

A browser-compatible ESM build of the validator that runs entirely on the client, with no FFmpeg required:

import { validateComposition } from '@hyperframes/validator-browser';

const result = await validateComposition(html);
// Runs entirely in the browser — no server round-trip

This directly improves all three use cases described above:

• In Use Case 1, the editor catches errors in the AI-generated HTML before any network call, accelerating the feedback loop for the user;
• In Use Case 2, the SaaS platform validates on the client before even queuing the render job on the server;
• In Use Case 3, automated pipelines can run a lightweight validation step in CI without downloading the full producer dependency tree.

When combined with Mediabunny — already suggested by the community in #1661 — this alternative closes a 100% browser-side, zero system dependency pipeline:

validateComposition(html)     ← @hyperframes/validator-browser
        ↓ (if valid)
MediaBunny.render(html)       ← MP4/WebM rendering in the browser via WebCodecs
        ↓
download(output.mp4)          ← delivered directly to the user

The validator-browser + MediaBunny pair does not replace the official producer — it is a complementary path for contexts where running FFmpeg and Chrome headless on the server is not viable. The official producer remains the reference for deterministic, pixel-perfect production-level renders. The browser-side pipeline expands the ecosystem to a new class of lightweight integrations, without changing anything that already works.

Alternative C — Hosted public API (optional, HeyGen's call)

A minimal HTTP endpoint for validation and render job submission — similar in concept to AI image generation APIs:

POST https://api.hyperframes.dev/v1/validate
Content-Type: application/json

{ "html": "..." }

{
  "valid": true,
  "findings": [{ "severity": "warning", "message": "...", "elementId": "..." }]
}

I am not proposing that HeyGen implement or host this infrastructure. This is the highest-complexity alternative and it is entirely up to the maintainers to evaluate whether it fits the development roadmap. I include it to present the full solution space for discussion.

Alternatives considered

What I Am Actually Proposing

This RFC presents three concrete discussion points:

1. Does a public API endpoint fit the HyperFrames roadmap?
If yes, what shape would it take? If no, that is a valid answer too.

2. Does a lightweight @hyperframes/validator package (Alternative A)
make sense as a complement to the existing stack?

3. Does a complementary 100% browser-side pipeline using @hyperframes/validator-browser (Alternative B) — where the browser-side pipeline expands the ecosystem to a new class of lightweight integrations without changing anything that already works — make sense?

Alternative A has a small scope and does not alter any existing API or behavior — it is a pure addition. It would significantly lower the adoption barrier for editors, SaaS tools and AI pipelines that want to integrate HyperFrames without committing to the full rendering infrastructure.

Alternative B has an equally small scope and also does not alter any existing API or behavior — it is a pure addition, independent of Alternative A. It opens HyperFrames to a new class of integrations where running Node.js, FFmpeg or Chrome headless on the server is not viable: browser-based editors, SaaS tools with minimal infrastructure and AI pipelines that need instant client-side validation.

When combined with MediaBunny, this alternative delivers a complete 100% browser-side creation and export cycle — no system dependencies, no dedicated server — expanding the HyperFrames ecosystem reach to developers and contexts that today cannot adopt the stack due to infrastructure constraints.

I am happy to discuss any of the alternatives if the maintainers find this direction worth pursuing.

---

Related

• Feature request: Support browser-side video export with Mediabunny #1661 — Feature request: Support browser-side video export with Mediabunny
  (related in spirit — both address reducing infrastructure requirements for lightweight or browser-based integrations)

Additional context

No response

[miguel-heygen]

hi @Breno-Oliveira10, I extracted the linter into a new package called @hyperframes/lint, take a look to the docs! it should have same behaviour than in core: https://hyperframes.heygen.com/packages/lint

[Breno-Oliveira10]

Thank you @miguel-heygen for the swift action on this — the extraction of @hyperframes/lint
as a standalone package (v0.7.15, #1756) is exactly the direction I was hoping
for. Being able to run lintHyperframeHtml and shouldBlockRender without
pulling in the full engine + producer chain removes the main coupling friction
I described. This already unblocks the validation layer in my editor completely.

@hyperframes/parsers (#1755) was a welcome surprise as well — the GSAP AST
mutation API (/gsap-writer-acorn) gives a much safer path for modifying
composition timelines programmatically than working with raw string patching.
That will be useful for the property editing layer too.

One question for the maintainers, as a natural follow-up to what was just shipped:

Does a browser-compatible ESM build — something like @hyperframes/validator-browser
— make sense as a next step? The idea would be a zero-dependency build of the
lint/validate logic that runs entirely in the client (no Node.js, no server
round-trip), enabling editors and tools that operate fully in the browser to
catch composition errors before any network call.

Combined with a browser-side render solution (as also discussed in #1661), this
would close a complete authoring-to-export pipeline for browser-only contexts —
complementary to the existing producer, not a replacement.

Totally understand if this is out of scope or if there are technical constraints
that make a browser ESM build impractical. Just wanted to raise it while the
refactor momentum is there.

Thanks again for the fast turnaround and for keeping the packages modular —
this makes HyperFrames significantly easier to integrate into third-party tools.

[miguel-heygen]

@Breno-Oliveira10 — shipped! A browser ESM build of the validator just landed in v0.7.17 as the @hyperframes/lint/browser entry (#1773).

It runs the rule engine fully client-side — no Node.js, no fs, no server round-trip:

import { lintHyperframeHtml, shouldBlockRender } from "@hyperframes/lint/browser";

const result = await lintHyperframeHtml(htmlString, { filePath: "index.html" });
// result.ok, result.findings — validate before any preview/network call

A few details:

• Node-free by construction. The browser entry exposes lintHyperframeHtml, lintMediaUrls, and shouldBlockRender — everything that operates on an HTML string. It's built with a platform: "browser" pass, so the build fails if any node: builtin sneaks in; a full esbuild bundle (deps inlined) comes out to ~558 KB with zero node builtins.
• lintProject stays Node-only. The directory-walking project linter still lives on the main @hyperframes/lint entry (it needs the filesystem) — only the HTML-string path is exposed to the browser.
• Leaner install too. @hyperframes/lint now depends only on @hyperframes/parsers (we dropped @hyperframes/core), so it no longer transitively pulls studio-server/hono or other unrelated packages — just the validator.

That should close the authoring-side of the loop you described for browser-only contexts. The browser-side render piece (#1661) is still its own track. Thanks for the detailed write-up — it made the scope easy to land cleanly.

[Breno-Oliveira10]

This is exactly what I needed on the authoring side — having lintHyperframeHtml
and shouldBlockRender run fully in the browser before any network call closes
the validation loop cleanly. The leaner install (parsers + postcss only) is a
nice bonus too.

Understood on #1661 being its own track. Will keep an eye on it.

Thanks @miguel-heygen again for the fast turnaround on this — really appreciated.