hyperframes lint
Static analysis for HyperFrames compositions. Catches determinism, asset, and codec issues before the encoder ever starts.
hyperframes lint reads your composition without rendering it and reports anything that would either break determinism or waste encoder time. Run it in pre-commit, in CI, and as a save hook in your editor.
Synopsis
bash
hyperframes lint <file> [flags]<file> may be a single HTML file or a glob.
Flags
| Flag | Default | Meaning |
|---|---|---|
--fix | off | Auto-correct safe issues (formatting, missing data-fps). |
--rule <name> | all | Run only the named rule. Repeatable. |
--max-warnings <n> | -1 | Exit non-zero if warnings exceed n. -1 disables. |
--format <pretty|json> | pretty | Reporter. --json is shorthand for --format json. |
--ignore <glob> | — | Skip files matching the glob. Repeatable. |
Rules
| Rule | Default | What it catches |
|---|---|---|
missing-duration | error | No data-duration on the composition root. |
oversize-asset | warn | Image, video, or font larger than 5 MB. |
non-deterministic-time | error | Use of Date.now(), performance.now(), or Math.random() without the seeded shim. |
missing-data-attrs | warn | An element animates in CSS but has no data-start / data-fade. |
unsupported-codec | error | The composition declares a codec the current FFmpeg build cannot produce. |
unused-asset | warn | Asset on disk is referenced by no track. |
font-not-preloaded | warn | @font-face source loaded over the network (will fail in offline render). |
Rules can be turned off or escalated in hyperframes.config.ts:
ts
export default defineConfig({
lint: {
rules: {
"oversize-asset": "off",
"missing-data-attrs": "error"
}
}
});Common invocations
$ hyperframes lint comp.html
warn comp.html:12 oversize-asset hero.png is 7.4 MB
ok 1 file, 0 errors, 1 warningJSON output
json
{
"command": "lint",
"status": "fail",
"exit_code": 2,
"files": 3,
"errors": [
{
"rule": "non-deterministic-time",
"file": "home.html",
"line": 34,
"column": 17,
"message": "Math.random() called without seed",
"severity": "error"
}
],
"warnings": [
{
"rule": "oversize-asset",
"file": "comp.html",
"line": 12,
"message": "hero.png is 7.4 MB",
"severity": "warn"
}
]
}Exit codes
0— clean (or only warnings, when--max-warningsallows).1— invalid input or unknown rule.2— lint errors present.
Tips
- Wire
hyperframes lint --jsoninto your editor's diagnostics protocol. The shape is stable. --fixonly touches safe edits. It will never rewrite your animation logic.- The
non-deterministic-timerule has zero false positives: the seeded shim is the only legitimate timer in a HyperFrames composition. - In monorepos, run lint per-package with
--cwdto scope error paths nicely in CI logs.
Next
- HyperFrames CLI — full command index.
hyperframes render— what runs after a clean lint.