mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-05 17:30:50 +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.
48 lines
1.7 KiB
TypeScript
48 lines
1.7 KiB
TypeScript
import { initSandboxRuntimeModular } from "./init";
|
|
import { installAuthoredOpacityCapture } from "./colorGrading";
|
|
import { fitTextFontSize } from "../text/fitTextFontSize";
|
|
import { pretext } from "../text/pretext";
|
|
import { getVariables } from "./getVariables";
|
|
|
|
type HyperframeWindow = Window & {
|
|
__hyperframeRuntimeBootstrapped?: boolean;
|
|
__hyperframes?: {
|
|
fitTextFontSize: typeof fitTextFontSize;
|
|
getVariables: typeof getVariables;
|
|
pretext: typeof pretext;
|
|
};
|
|
};
|
|
|
|
// Inline composition scripts can run before DOMContentLoaded.
|
|
// Ensure timeline registry exists at script evaluation time.
|
|
(window as HyperframeWindow).__timelines = (window as HyperframeWindow).__timelines || {};
|
|
|
|
// Stamp color-graded elements with their authored inline opacity BEFORE the
|
|
// composition's animation scripts (and the grading hide) mutate it — must run
|
|
// at script evaluation time, while the document is still parsing.
|
|
installAuthoredOpacityCapture();
|
|
|
|
// Expose runtime helpers immediately so composition scripts can use them
|
|
// before DOMContentLoaded (font sizing runs during script evaluation, and
|
|
// getVariables is read by composition setup before the timeline is built).
|
|
(window as HyperframeWindow).__hyperframes = {
|
|
fitTextFontSize,
|
|
getVariables,
|
|
pretext,
|
|
};
|
|
|
|
function bootstrapHyperframeRuntime(): void {
|
|
const win = window as HyperframeWindow;
|
|
if (win.__hyperframeRuntimeBootstrapped) {
|
|
return;
|
|
}
|
|
win.__hyperframeRuntimeBootstrapped = true;
|
|
initSandboxRuntimeModular();
|
|
}
|
|
|
|
if (document.readyState === "loading") {
|
|
document.addEventListener("DOMContentLoaded", bootstrapHyperframeRuntime, { once: true });
|
|
} else {
|
|
bootstrapHyperframeRuntime();
|
|
}
|