mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-03 04:38:33 +00:00
Miguel Ángel
0285a711e9
## What
Exposes the `pretext` text-measurement API on `window.__hyperframes`, so the API our agent-facing docs already describe actually exists.
Adds `pretext.prepare`, `.layout`, `.prepareWithSegments`, `.measureLineStats`, `.measureNaturalWidth`.
## Why
`skills/hyperframes-core/references/determinism-rules.md` is required reading for any agent authoring a composition. Line 59 tells them to call `window.__hyperframes.pretext.prepare(text, font)` then `pretext.layout(prepared, maxWidth, lineHeight)` for text measurement without a DOM reflow.
That object did not exist. The runtime exposed exactly `fitTextFontSize` and `getVariables`. Any composition following the documented recipe threw at runtime.
Deleting the doc line was the smaller change, but reflow-free measurement is genuinely the right tool for sizing text per frame, and `fitTextFontSize` is already built on it. Making the docs true is the better fix.
## How
- New `packages/core/src/text/pretext.ts` assembles the exposed surface in one place, with the include/exclude rationale next to it.
- `entry.ts` attaches it alongside the existing helpers. Sub-compositions inherit it for free: the scoping shim builds its scoped variant with `Object.assign({}, base, { getVariables })`, so anything added to the base object is carried through.
Two deliberate decisions:
**Wider than the doc named.** `layout()` returns only `{ lineCount, height }`. The doc's own "shrinkwrap containers" use case needs a width, which is impossible with just `prepare` + `layout`. `measureNaturalWidth` and `measureLineStats` make that claim achievable; `prepareWithSegments` is their required input.
**`clearCache` and `setLocale` withheld.** Both mutate state shared across compositions. Exposing them would let one composition change how a later one measures, making a render depend on what ran before it.
**Doc correction.** The reference called this "pure arithmetic, ~0.0002 ms per call". Not quite: `prepare` measures fonts through a canvas and throws outside a browser. Only the steps after a prepared string are arithmetic. Reworded, and documented the width helpers and the omissions.
## Trade-off
The runtime bundle grows **4,903 bytes (+1.30%)**, from 377,865 to 382,768. That ships inline in every composition. Measured by building the artifact with and without the change.
## Test plan
- [x] Unit tests added/updated
- [x] Manual testing performed
- [x] Documentation updated (if applicable)
`packages/core/src/text/pretext.test.ts` guards the shape of the published surface: the two documented names exist, the width helpers exist, and the two stateful functions are absent. Behaviour is deliberately not asserted there. `prepare` needs a canvas, and mocking it (as `fitTextFontSize.test.ts` must) would assert nothing real.
Real behaviour was verified by rendering a composition that calls the documented API:
```
lines=2 height=216 naturalWidth=1785
```
Self-consistent: natural width 1785 exceeds the 1600 container so it wraps to 2 lines, and 2 x 108 line-height is exactly the reported 216. The frame was inspected visually.
Also run:
- `packages/core` full suite from the package root: **903 passed, 46 files**
- `tsc --noEmit` and `tsc --noEmit -p tsconfig.runtime.json`: clean
- `oxlint` / `oxfmt`: clean
## Follow-ups (not in this PR)
An audit of the wider attribute surface found several more doc/runtime mismatches, including `data-gpu-mode` documented as an HTML attribute when it is a config field, and `data-no-timeline` being real, load-bearing, and absent from the table agents read. Those are separate changes.
86 lines
1.7 KiB
JSON
86 lines
1.7 KiB
JSON
{
|
|
"source": "heygen-com/hyperframes",
|
|
"skills": {
|
|
"embedded-captions": {
|
|
"hash": "14e79d53c24e3945",
|
|
"files": 138
|
|
},
|
|
"faceless-explainer": {
|
|
"hash": "c70b904aa68cf7e5",
|
|
"files": 24
|
|
},
|
|
"figma": {
|
|
"hash": "4f524b4962bd8d7c",
|
|
"files": 2
|
|
},
|
|
"general-video": {
|
|
"hash": "49f5216832cb8e91",
|
|
"files": 4
|
|
},
|
|
"hyperframes": {
|
|
"hash": "756a72f58fa3739b",
|
|
"files": 17
|
|
},
|
|
"hyperframes-animation": {
|
|
"hash": "2ce5ca7dbf361e27",
|
|
"files": 121
|
|
},
|
|
"hyperframes-audio": {
|
|
"hash": "534cea75fe0f2bc6",
|
|
"files": 6
|
|
},
|
|
"hyperframes-cli": {
|
|
"hash": "7f61f9a970a94cc1",
|
|
"files": 11
|
|
},
|
|
"hyperframes-core": {
|
|
"hash": "4ca81d4092effc62",
|
|
"files": 19
|
|
},
|
|
"hyperframes-creative": {
|
|
"hash": "bacb5205ea5eb3d8",
|
|
"files": 78
|
|
},
|
|
"hyperframes-keyframes": {
|
|
"hash": "d00744ff0e669624",
|
|
"files": 3
|
|
},
|
|
"hyperframes-registry": {
|
|
"hash": "549017b6d436aaf8",
|
|
"files": 12
|
|
},
|
|
"media-use": {
|
|
"hash": "7e329ade41b1c1ba",
|
|
"files": 152
|
|
},
|
|
"motion-graphics": {
|
|
"hash": "1434e22bb0259bbb",
|
|
"files": 23
|
|
},
|
|
"music-to-video": {
|
|
"hash": "55a2b5fdcd6f892c",
|
|
"files": 132
|
|
},
|
|
"pr-to-video": {
|
|
"hash": "7769801640dca521",
|
|
"files": 30
|
|
},
|
|
"product-launch-video": {
|
|
"hash": "81953f054fcb9d91",
|
|
"files": 28
|
|
},
|
|
"remotion-to-hyperframes": {
|
|
"hash": "3ecc684432b298dd",
|
|
"files": 70
|
|
},
|
|
"slideshow": {
|
|
"hash": "6a24a84b0c1a75f9",
|
|
"files": 2
|
|
},
|
|
"talking-head-recut": {
|
|
"hash": "2f5d99f823c48e75",
|
|
"files": 28
|
|
}
|
|
}
|
|
}
|