mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-14 18:01:20 +08:00
Ular Kimsanov
edfe66a953
* docs: add the shared page components Adds the six React snippets the rebuilt documentation pages compose against, plus the styles they need. Nothing imports them yet, so this lands with no user-visible change and no navigation churn. - DocsVideo / ShowcaseWall — the film player and the Showcase grid - LiveReferenceProject — embeds the Reference Project via <hyperframes-player> - WorkflowChooser, AgentAction, and the two grid snippets The scrub indicator is a timecode bubble rather than a thumbnail. Mounting a second <video> with the same src to drive a preview frame made every page carrying a film download the whole file twice, which is not worth a thumbnail. * docs: add the Reference Project example One real 10-second project the documentation can point at instead of describing a hypothetical one: a live capture of example.com, synthesised narration, and caption timings measured from that narration. It passes its own gates — `hyperframes lint` clean, `hyperframes check` passed, 28/28 text checks WCAG AA. No page imports it yet, so this lands without touching navigation. Only the two WAV masters exceed the repository's 500 KB non-LFS limit, so only those go through LFS. The MP3 stings and the capture PNG stay plain, which keeps the example usable after a clone without `git lfs pull`. `bun run docs:bundle-reference` regenerates the single-file embed the Introduction page loads from the CDN. * docs: keep the Reference Project verification report The Examples page links this file twice — as "What changed after review" and as "The real verification report" — in the section that makes the project's brief, source, revision notes, and checks public end to end. It is a published artifact, not leftover scaffolding. * docs: state the Reference Project embed's isolation contract The composition is fetched from the CDN and handed to the player as a blob: URL, which inherits the docs origin, and <hyperframes-player> sandboxes its iframe with allow-scripts + allow-same-origin. So the embedded composition runs with script access to this origin. That is a consequence of how the player works — it drives seeking through the iframe's document, which a cross-origin frame does not expose — not something this component can fix. Serving the CDN URL directly would isolate the frame and break playback. The guard is therefore the source, so the comment says so out loud: src must stay a first-party path we publish, never user- or community-supplied HTML. * fix(docs): resolve reduced-motion on the first render, and the embed's dep gap Both defects from Rames Jusso's review on #2977. Neither is visible today because nothing imports these files yet, which is what makes them cheap now. **Reduced motion resolved one paint too late, in all three grids.** `useState(false)` plus a `matchMedia` read in an effect meant the first committed render always emitted `<video src autoPlay loop>`; a reduce-motion visitor had 6 + 8 + 4 tiles already fetching before the attributes came off. `autoPlay` also overrides `preload="metadata"`, so those were the files, not metadata probes — and dropping `src` with no following `load()` is not a reliable abort. A lazy initializer knows the answer on the first render. **LiveReferenceProject never sent the initial variables.** The sending effect read `playerRef.current`, assigned by the effect above it on the commit where `compositionSrc` lands — a commit with nothing in the sending effect's dep array. So it ran once against a null ref and never again. It looked correct only because the three defaults match what the composition already renders. Also from the same review: - The object URL could outlive its revoke: once the body resolves, `abort()` no longer stops the chain, so the blob could be minted after cleanup ran with `objectUrl` still undefined. Same `cancelled` guard the effect above uses. - `postMessage` targeted `"*"` while the isolation comment argues the frame is same-origin. Naming `window.location.origin` turns that prose guard into an enforced one. - Nothing reached a terminal state when the player script never arrived: `whenDefined()` does not reject, and a later mount reuses the tag without its error listener. A CSP rule or content blocker never fires `error` at all. A deadline covers every path instead of sitting on "Loading…" forever. - `loadFailed` was never cleared, so one transient failure stuck. - The README claimed a clone works without `git lfs pull`. It does for the visuals; both WAVs are pointers and they are the bed and the voiceover, so the captions would play over silence. Says so now. - The bundler stripped trailing whitespace document-wide while inlining the runtime, which reaches inside script template literals where those spaces are data. It also assumed a literal `<head>` and would silently ship an embed with no `<base>`. Strip removed, anchor asserted. Copilot's five "missing hook imports" comments are wrong — Mintlify pre-injects the hooks, and `TemplateCard.jsx`, cited as the counter-example, uses the `export function` form the same page says is unsupported. * fix(docs): stop preview loops when Reduce Motion is turned on mid-session Miguel's changes-requested on #2977. He is right about the mechanism: dropping `src` and `autoPlay` through React props neither pauses a playing element nor aborts its selected resource, so a visitor who turned Reduce Motion on with the page already open kept every tile running. Measured in a browser rather than argued from the spec, same clip, same sequence: playing paused=false t=2.90 readyState=4 networkState=1 React props only paused=false t=3.90 readyState=4 networkState=1 + pause/removeAttr/load paused=true t=0 readyState=0 networkState=0 The middle row is the bug: time still advancing, resource still held. Rames' follow-up asked for a remount-to-poster instead, because a video that ends with `src` removed holds its last frame and `poster` only paints before playback begins. `load()` covers that too — it drops readyState to HAVE_NOTHING, which is precisely the state that paints the poster. Confirmed side by side on screen: the React-props-only tile sits on an arbitrary mid-clip frame, the pause/load tile shows the poster again. So no remount is needed. The guard cannot be shared as code — Mintlify compiles each snippet in isolation and forbids one importing another — so it is copy-pasted into all three grids. A duplicated invariant is the kind that rots, and a rendering test would mean adding React to a repo that only carries it inside packages/studio, plus mocking Mintlify's hook-injection contract with a mock that can stay green while the page breaks. `scripts/check-docs-snippet-motion.mjs` asserts the source instead, wired into `bun run lint`, with unit tests covering both edges. That gate immediately found `docs/snippets/TemplateCard.jsx`: autoplays with no reduced-motion handling at all. It is imported by zero pages, and it uses the `export function` form Mintlify's constraints page says is unsupported, so it would not work if it were. Deleted rather than fixed. * refactor(scripts): split the motion guard into named predicates fallow flagged findMotionGuardViolations at CRAP 42 — a finding this branch introduced, so it gets fixed rather than suppressed, same as the catalog generator earlier in the stack. The two conditions are now their own predicates behind a small requirements table, which drops the branch count under the threshold and makes each rule readable on its own line. Same output, same tests. * fix(docs): move the stop effect above ShowcaseWall's early return Rames' changes-requested on `e1a03c63`. The effect I added in the previous commit landed below `if (open) return`, so `ShowcaseWall` called five hooks on the grid render and four once a tile was open. That is a conditional hook: clicking a tile — the component's primary interaction — threw "Rendered fewer hooks than expected". Worth naming why it landed in one of three. `workflow-chooser` and `advanced-path-grid` have no early return, so the same paste position was fine there. `ShowcaseWall` is the only one with a conditional return and it got the same copy. That is the duplication cost this script's own header warns about, showing up in the commit that added the script. **The bespoke gate could not have caught it, and now the generic one does.** `.oxlintrc.json` already loaded the `react` plugin and never excluded `docs/` — only `.prettierignore` does, which is why formatting is not a finding here but linting reaches these files. Naming the two hook rules in an override scoped to `docs/snippets/**` reports this bug directly, and also reports the `compositionSrc` dependency gap from round one that was found by reading. Verified both ways: reintroducing the conditional hook produces `react-hooks(rules-of-hooks)`, and `bunx oxlint .` is clean repo-wide, so nothing lit up in `packages/studio`. **Two holes in the script itself, both from the same review.** It matched whole files while the invariant is per component, so a second unguarded grid in `docs-video.jsx` would have ridden in on `ShowcaseWall`'s guard. It now splits by component. That immediately surfaced the distinction between a component that decides to autoplay and one that forwards its caller's `autoPlay` prop — `DocsVideo` only ever plays because a reader clicked, so it does not owe a preference check. And `readsPreferenceLazily` never tied its halves: any lazy initializer plus the media-query string anywhere in the file passed, which is the original bug satisfying the check written to prevent it. The query now has to sit inside the initializer's own expression. Both holes have tests. fallow is clean at 0 introduced. * fix(scripts): close the two silent gaps in the motion gate Both from Rames' approval pass on #2977, and both found by running these functions rather than reading them. Both fail the same quiet way: a component `autoplays` misses is filtered out before any requirement runs, so the gate reports zero problems instead of a violation. `autoplays` had become narrower than the version it replaced. Excluding the `autoPlay={autoPlay}` passthrough was right, but the replacement only matched `autoPlay={` or `autoPlay` alone on a line, so `<video autoPlay muted />` on one line slipped through. Restored the old breadth. Two things are stripped first rather than one — the passthrough, and the prop's own default in the signature, which is a declaration and not a use. Without the second strip, `DocsVideo` is asked to own a decision it only forwards. `splitComponents` anchored on `^export`, so anything not exported folded into the previous exported component and inherited its guard. Same hole as the whole-file match, narrowed from file scope to non-export scope. The anchor no longer requires `export`. Ten tests now, including his exact examples for both. * docs: remove the live-composition embed and its build apparatus The Introduction no longer carries the embed (removed in #2979), and nothing else used any of this: the 200-line snippet, 26 CSS rules, the bundler that built the single-file HTML for the CDN, its npm script, and the README section explaining how to regenerate it. The Reference Project itself stays — Examples, Developers, and Go further all link to it as the worked example; only the interactive embed of it is gone. This also retires the isolation contract I documented two rounds ago. That comment existed because the embed handed CDN HTML to a same-origin blob; with the embed gone there is no such surface to reason about, which is a better outcome than a comment explaining why it was acceptable. * docs: remove the AgentAction snippet Its only consumer is gone. The Quickstart now shows the agent instruction in a plain fence instead, because this component rendered a Copy button and never displayed the request — a reader copied text they could not read, which is the wrong shape for the one affordance a non-technical visitor depends on. Mintlify fences already carry a copy button and show their contents.
242 lines
8.9 KiB
HTML
242 lines
8.9 KiB
HTML
<!doctype html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="UTF-8" />
|
||
<title>captions — example.com intro</title>
|
||
<!-- This head is metadata for the source file only. The runtime clones ONLY
|
||
the <template> contents, so every style, node and script that has to
|
||
exist at render time lives inside it. GSAP is deliberately not
|
||
re-imported here: the host page already provides the global, and a
|
||
second <script src> would be a render-time network fetch. -->
|
||
</head>
|
||
<body>
|
||
<template>
|
||
<style>
|
||
/* Root is styled by #root, never by a class: the compiler scopes each
|
||
sub-composition's CSS to its data-composition-id, which would turn a
|
||
root class selector into a descendant selector that cannot match. */
|
||
#root {
|
||
position: absolute;
|
||
inset: 0;
|
||
width: 1920px;
|
||
height: 1080px;
|
||
pointer-events: none;
|
||
}
|
||
|
||
/* Fixed lower band. Full-width absolute + text-align, NOT
|
||
left:50% + translateX(-50%) — the latter clips at canvas edges.
|
||
bottom:64px puts the pill at y 934–1016, inside the 184px band the
|
||
main composition reserves, so a caption can never cover the artwork. */
|
||
.group {
|
||
position: absolute;
|
||
left: 0;
|
||
right: 0;
|
||
bottom: 64px;
|
||
text-align: center;
|
||
/* the root is click-through so the artwork underneath stays
|
||
selectable in Studio; the pills themselves are not */
|
||
pointer-events: auto;
|
||
opacity: 0;
|
||
visibility: hidden;
|
||
}
|
||
.pill {
|
||
display: inline-block;
|
||
max-width: 1304px;
|
||
padding: 16px 32px;
|
||
border-radius: 12px;
|
||
background: #1b1b1b;
|
||
font-family: "Inter", sans-serif;
|
||
font-weight: 700; /* bundled weight */
|
||
font-size: 42px;
|
||
line-height: 1.2;
|
||
letter-spacing: -0.005em;
|
||
text-align: center;
|
||
}
|
||
/* Emphasis by luminance only. A word starts read-pending and stays lit
|
||
once spoken — no scale pop, no colour flash, no scatter exit. Both
|
||
states clear WCAG AA against #1b1b1b (6.1:1 idle, 17.2:1 lit). */
|
||
.w {
|
||
color: #9a9a9a;
|
||
}
|
||
</style>
|
||
|
||
<div
|
||
id="root"
|
||
data-composition-id="captions"
|
||
data-start="0"
|
||
data-duration="10"
|
||
data-width="1920"
|
||
data-height="1080"
|
||
data-layout-allow-caption-zone
|
||
></div>
|
||
|
||
<script>
|
||
(function () {
|
||
// Phrase groups. start/end/s/e are absolute composition seconds, taken
|
||
// from `npx hyperframes transcribe assets/narration.wav --model small.en`
|
||
// plus the narration clip's data-start of 1.00s. Three groups for three
|
||
// spoken sentences: stable, one visible at a time, never re-grouped.
|
||
var GROUPS = [
|
||
{
|
||
start: 1.1,
|
||
end: 2.81,
|
||
words: [
|
||
{ t: "This", s: 1.1, e: 1.36 },
|
||
{ t: "is", s: 1.36, e: 1.54 },
|
||
// spoken "example dot com"; written as the string it is
|
||
{ t: "example.com.", s: 1.54, e: 2.81 },
|
||
],
|
||
},
|
||
{
|
||
start: 2.81,
|
||
end: 5.48,
|
||
words: [
|
||
{ t: "The", s: 2.81, e: 2.95 },
|
||
{ t: "domain", s: 2.95, e: 3.24 },
|
||
{ t: "reserved", s: 3.24, e: 3.56 },
|
||
{ t: "for", s: 3.74, e: 3.81 },
|
||
{ t: "documentation", s: 3.88, e: 4.62 },
|
||
{ t: "examples.", s: 4.74, e: 5.38 },
|
||
],
|
||
},
|
||
{
|
||
start: 5.48,
|
||
end: 8.03,
|
||
words: [
|
||
{ t: "Use", s: 5.48, e: 5.55 },
|
||
{ t: "it", s: 5.62, e: 5.68 },
|
||
{ t: "in", s: 5.68, e: 5.8 },
|
||
{ t: "your", s: 5.8, e: 6.03 },
|
||
{ t: "docs —", s: 6.09, e: 6.36 },
|
||
{ t: "no", s: 6.48, e: 6.54 },
|
||
{ t: "permission", s: 6.54, e: 6.77 },
|
||
{ t: "needed.", s: 7.17, e: 7.68 },
|
||
],
|
||
},
|
||
];
|
||
|
||
var IDLE = "#9a9a9a";
|
||
var LIT = "#ffffff";
|
||
// Back-to-back phrases: the narration has no pause between sentences
|
||
// (group 0 ends the exact instant group 1 begins), so the handoff is a
|
||
// quick fade-down / fade-up rather than a crossfade. Keeping them
|
||
// short holds the dip at a sentence boundary under ~0.2s while still
|
||
// guaranteeing only one group is ever drawn on a given frame.
|
||
var ENTER = 0.18;
|
||
var EXIT = 0.1;
|
||
|
||
var root = document.getElementById("root");
|
||
var api = window.__hyperframes;
|
||
|
||
// Build the DOM synchronously — one group element, one span per word.
|
||
GROUPS.forEach(function (group, gi) {
|
||
var groupEl = document.createElement("div");
|
||
groupEl.id = "cg-" + gi;
|
||
groupEl.className = "group";
|
||
|
||
var pill = document.createElement("div");
|
||
pill.className = "pill";
|
||
|
||
var text = group.words
|
||
.map(function (w) {
|
||
return w.t;
|
||
})
|
||
.join(" ");
|
||
|
||
// Overflow guard: shrink the phrase until it fits one line rather
|
||
// than letting it wrap up out of the caption band.
|
||
if (api && typeof api.fitTextFontSize === "function") {
|
||
var fit = api.fitTextFontSize(text, {
|
||
fontFamily: "Inter",
|
||
fontWeight: 700,
|
||
maxWidth: 1240,
|
||
baseFontSize: 42,
|
||
minFontSize: 30,
|
||
step: 2,
|
||
});
|
||
if (fit && fit.fontSize) pill.style.fontSize = fit.fontSize + "px";
|
||
}
|
||
|
||
group.words.forEach(function (w, wi) {
|
||
if (wi > 0) pill.appendChild(document.createTextNode(" "));
|
||
var span = document.createElement("span");
|
||
span.id = "cw-" + gi + "-" + wi;
|
||
span.className = "w";
|
||
span.textContent = w.t;
|
||
pill.appendChild(span);
|
||
});
|
||
|
||
groupEl.appendChild(pill);
|
||
root.appendChild(groupEl);
|
||
});
|
||
|
||
window.__timelines = window.__timelines || {};
|
||
var tl = gsap.timeline({ paused: true });
|
||
|
||
GROUPS.forEach(function (group, gi) {
|
||
var groupEl = document.getElementById("cg-" + gi);
|
||
|
||
// enter — fromTo, not from: the host re-seeks this sub-composition
|
||
// every time its slot becomes visible, and from() can desync.
|
||
tl.fromTo(
|
||
groupEl,
|
||
{ autoAlpha: 0, y: 14 },
|
||
{ autoAlpha: 1, y: 0, duration: ENTER, ease: "power3.out" },
|
||
group.start,
|
||
);
|
||
|
||
// progressive fill — each word lights on its own measured onset and
|
||
// stays lit, so the phrase completes with the voice.
|
||
group.words.forEach(function (w, wi) {
|
||
tl.fromTo(
|
||
"#cw-" + gi + "-" + wi,
|
||
{ color: IDLE },
|
||
{ color: LIT, duration: 0.14, ease: "none" },
|
||
w.s,
|
||
);
|
||
});
|
||
|
||
// exit, then the mandatory hard kill exactly at group.end so no group
|
||
// can bleed into the next one or into the end card.
|
||
tl.to(
|
||
groupEl,
|
||
{ autoAlpha: 0, y: -8, duration: EXIT, ease: "power2.in" },
|
||
group.end - EXIT,
|
||
);
|
||
tl.set(groupEl, { opacity: 0, visibility: "hidden" }, group.end);
|
||
});
|
||
|
||
// Self-lint: prove every group is really gone after its own end.
|
||
//
|
||
// Call getComputedStyle BARE, not as window.getComputedStyle(el).
|
||
// Inside a sub-composition the runtime evaluates this script with a
|
||
// `window` wrapper object (window !== globalThis, though property
|
||
// reads/writes proxy through to the real window). Retrieving the
|
||
// native function through the wrapper and calling it as a method
|
||
// makes the wrapper the receiver, so it throws
|
||
// `TypeError: Illegal invocation`, the timeline is never registered,
|
||
// and the render ships whatever DOM state the throw left behind.
|
||
GROUPS.forEach(function (group, gi) {
|
||
var el = document.getElementById("cg-" + gi);
|
||
if (!el) return;
|
||
tl.seek(group.end + 0.01);
|
||
var computed = getComputedStyle(el);
|
||
if (computed.opacity !== "0" && computed.visibility !== "hidden") {
|
||
console.warn(
|
||
"[caption-lint] group " +
|
||
gi +
|
||
" still visible at t=" +
|
||
(group.end + 0.01).toFixed(2) +
|
||
"s",
|
||
);
|
||
}
|
||
});
|
||
tl.seek(0);
|
||
|
||
window.__timelines["captions"] = tl;
|
||
})();
|
||
</script>
|
||
</template>
|
||
</body>
|
||
</html>
|