Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
docs: clarify async font measurement and timeline registration (#5203)
Abdullah M. Nazif9e69821b8b18
diff --git a/docs/guides/gsap-animation.mdx b/docs/guides/gsap-animation.mdxindex 0e555b00d2..2442c77dec 100644--- a/docs/guides/gsap-animation.mdx+++ b/docs/guides/gsap-animation.mdx@@ -73,6 +73,37 @@ The registry key must match `data-composition-id`.The normal timeline methods are `to()`, `from()`, `fromTo()`, and `set()`. GSAP supports many CSS properties, but the [HyperFrames animation skill](https://github.com/heygen-com/hyperframes/tree/main/skills/hyperframes-animation) contains the render-safe patterns used by agents.+## Load fonts before measuring text++An underline or a position calculated from text width needs the final font metrics. HyperFrames waits for fonts used by existing markup before starting composition scripts, but a face used only by script-created text may still be unloaded.++Request that face with `document.fonts.load()` before measuring. Match the text's font family, weight, and size, and pass the text so the browser can load the required character ranges. `document.fonts.ready` waits for fonts already requested; it does not request an unused face.++This example uses the `intro` composition, an inline-block `#title` styled with `font: 700 64px "LocalFace"` from a local `@font-face`, and a block-level `#underline`:++```js+const title = document.getElementById("title");+const underline = document.getElementById("underline");+title.textContent = "Build with HyperFrames";++document.fonts.load('700 64px "LocalFace"', title.textContent).then(() => {+ underline.style.width = `${title.getBoundingClientRect().width}px`;++ const timeline = gsap.timeline({ paused: true });+ timeline.fromTo(+ ["#title", "#underline"],+ { opacity: 0, y: 32 },+ { opacity: 1, y: 0, duration: 0.6, ease: "power3.out" },+ 0,+ );++ window.__timelines = window.__timelines || {};+ window.__timelines.intro = timeline;+});+```++The underline now matches the loaded text width. Build all tweens before registering the timeline at the end of the callback. Registering an empty timeline before the asynchronous build finishes can make a nested composition appear ready before its animation exists.+## DurationAn explicit root `data-duration` is the composition's render length:diff --git a/docs/reference/html-schema.mdx b/docs/reference/html-schema.mdxindex b51e5fafb0..21e43a99a0 100644--- a/docs/reference/html-schema.mdx+++ b/docs/reference/html-schema.mdx@@ -298,13 +298,15 @@ bindings. Use `getVariables()` when the value affects logic.A composition using GSAP must:- create one finite timeline with `{ paused: true }`;-- register it synchronously on `window.__timelines`;+- register it on `window.__timelines` after adding its tweens;- use the same key as `data-composition-id`;- avoid wall-clock state, unseeded randomness, and infinite repeats.HyperFrames controls seeking. Composition code describes how the visual statelooks at a given time.+Asynchronous setup, such as [loading a font before measuring text](/guides/gsap-animation#load-fonts-before-measuring-text), is supported. Register the completed timeline at the end of the callback, after its tweens are added. Do not register an empty timeline before the asynchronous build finishes.+Every element with `data-composition-id` participates in timeline readiness.For a static nested section, use an ordinary `id` instead, or add`data-no-timeline` to declare that no timeline will be registered. Otherwise,diff --git a/skills-manifest.json b/skills-manifest.jsonindex 49ddfb2a1e..868bc89db1 100644--- a/skills-manifest.json+++ b/skills-manifest.json@@ -22,7 +22,7 @@"files": 29},"hyperframes-animation": {- "hash": "3bd80388da91c689",+ "hash": "9370b856259f4586","files": 122},"hyperframes-audio": {diff --git a/skills/hyperframes-animation/adapters/gsap.md b/skills/hyperframes-animation/adapters/gsap.mdindex c7824de33e..ebe7565609 100644--- a/skills/hyperframes-animation/adapters/gsap.md+++ b/skills/hyperframes-animation/adapters/gsap.md@@ -9,7 +9,7 @@ GSAP usage scoped to HyperFrames' seek-driven render model. This skill is the GS## HyperFrames Contract-HyperFrames controls GSAP through its `gsap` runtime adapter. Create a paused timeline synchronously, register it on `window.__timelines` with the exact `data-composition-id`, and let HyperFrames seek it.+HyperFrames controls GSAP through its `gsap` runtime adapter. Create a paused timeline, register it on `window.__timelines` with the exact `data-composition-id` after adding its tweens, and let HyperFrames seek it. Setup may run inside an async callback; register the completed timeline at the end of that callback.```html<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>