Skip to content

Commit 6895d32

Browse files
committed
test(core): assert the pretext attachment by running the runtime
Review correctly pointed out that nothing here fails if the attachment is removed again. pretext.test.ts asserts the shape of the module export, which passes whether or not entry.ts ever attaches it, and a snippet check over the bundle would be decorative: fitTextFontSize.ts imports prepare/layout from @chenglou/pretext directly, so the name is already in the output through an unrelated path. Evaluate the built runtime in a jsdom window and read window.__hyperframes back instead. That is the assertion that actually breaks. Verified by deleting the attachment line: the check exits 1 with "window.__hyperframes.pretext is not attached", and passes again once restored. Covers fitTextFontSize and getVariables the same way, and asserts clearCache and setLocale stay off the surface so the determinism choice is enforced rather than just documented. requestAnimationFrame is stubbed rather than enabling jsdom's pretendToBeVisual, which starts a frame loop that keeps the process alive. Also answers the open question raised in review about the withheld clearCache. The upstream cache is keyed by (segment, font), with segments coming from Intl.Segmenter at word granularity, so it grows with the number of distinct words a composition renders, not with frames. A per-frame counter or typewriter reuses existing entries; only new words allocate. Recorded next to the omission.
1 parent 58c20ae commit 6895d32

2 files changed

Lines changed: 66 additions & 0 deletions

File tree

‎packages/core/scripts/test-hyperframe-runtime-contract.ts‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,66 @@ for (const snippet of requiredSnippets) {
2727
assert(runtimeSource.includes(snippet), `Runtime contract snippet missing: ${snippet}`);
2828
}
2929

30+
// Snippet checks cannot prove what `window.__hyperframes` ends up carrying.
31+
// A name can reach the bundle through an unrelated import: `fitTextFontSize.ts`
32+
// imports `prepare`/`layout` from `@chenglou/pretext`, so grepping for
33+
// "pretext" stays green even if the attachment in entry.ts is deleted. Run the
34+
// runtime and read the object back instead.
35+
const { JSDOM } = await import("jsdom");
36+
const dom = new JSDOM("<!doctype html><html><body></body></html>", {
37+
runScripts: "outside-only",
38+
});
39+
// The runtime's DOMContentLoaded path calls requestAnimationFrame. jsdom only
40+
// provides it under `pretendToBeVisual`, which also starts a frame loop that
41+
// keeps the process alive, so stub it instead. The stub never fires: we are
42+
// asserting what the runtime attaches at evaluation time, not what it animates.
43+
Object.defineProperty(dom.window, "requestAnimationFrame", {
44+
value: () => 0,
45+
configurable: true,
46+
});
47+
Object.defineProperty(dom.window, "cancelAnimationFrame", {
48+
value: () => {},
49+
configurable: true,
50+
});
51+
dom.window.eval(runtimeSource);
52+
53+
const hyperframes = (dom.window as unknown as { __hyperframes?: Record<string, unknown> })
54+
.__hyperframes;
55+
assert(hyperframes, "Runtime did not attach window.__hyperframes");
56+
57+
// Each of these is an API the agent-facing docs tell composition authors to
58+
// call. If one stops being attached, every composition written against the
59+
// docs throws at render time, which no other check would catch.
60+
const requiredHelpers = ["fitTextFontSize", "getVariables"];
61+
for (const helper of requiredHelpers) {
62+
assert(
63+
typeof hyperframes[helper] === "function",
64+
`window.__hyperframes.${helper} is not attached`,
65+
);
66+
}
67+
68+
const pretext = hyperframes.pretext as Record<string, unknown> | undefined;
69+
assert(pretext, "window.__hyperframes.pretext is not attached");
70+
const requiredPretextFns = [
71+
"prepare",
72+
"layout",
73+
"prepareWithSegments",
74+
"measureLineStats",
75+
"measureNaturalWidth",
76+
];
77+
for (const fn of requiredPretextFns) {
78+
assert(typeof pretext[fn] === "function", `window.__hyperframes.pretext.${fn} is not attached`);
79+
}
80+
81+
// clearCache/setLocale mutate state shared across compositions. Keeping them
82+
// off the surface is a deliberate determinism choice, so assert it holds.
83+
for (const forbidden of ["clearCache", "setLocale"]) {
84+
assert(
85+
!(forbidden in pretext),
86+
`window.__hyperframes.pretext.${forbidden} must not be exposed (mutates shared state)`,
87+
);
88+
}
89+
3090
const scriptDir = resolve(fileURLToPath(new URL(".", import.meta.url)));
3191
const manifestPath = resolve(scriptDir, "../dist/hyperframe.manifest.json");
3292
try {

‎packages/core/src/text/pretext.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,12 @@ import {
2626
* - `clearCache` and `setLocale` mutate process-global state. A composition
2727
* calling either would change how *other* compositions measure, which breaks
2828
* the guarantee that the same file renders the same video every time.
29+
* Withholding `clearCache` does not strand memory: the cache is keyed by
30+
* (segment, font) where segments come from `Intl.Segmenter` at word
31+
* granularity, so it grows with the number of distinct *words* a composition
32+
* renders, not with frames. A counter or typewriter re-measuring every frame
33+
* reuses the same entries. Only genuinely new words allocate, which bounds it
34+
* at a composition's vocabulary.
2935
* - The incremental cursor API (`layoutNextLine`, `walkLineRanges`, and
3036
* friends) has no caller yet. Add it when something needs it.
3137
*

0 commit comments

Comments
 (0)