mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-17 15:24:19 +00:00
* fix(player): stop re-encoding the composition query Every src the player sets goes through withShaderQueryParams, which parsed the author's whole query with URLSearchParams and re-serialised it with toString(). That is a form encoder: it writes a space as +, while callers percent-encode and read back with decodeURIComponent. Those two codecs are not inverses, so any space in any query value arrived corrupted. It ran even when there was nothing to inject. With no shader attributes both params are deleted, so the round-trip was pure loss, on every src, for every consumer. Append the two params to the raw query instead of re-serialising it. The player now hands a composition its query back byte-identical. Empirically space was the only casualty: plus, ampersand, equals, hash, percent, question mark, quotes and non-ASCII all survived a URLSearchParams round-trip. That is narrow, but a space in a headline or in SVG path data is the common case, and invalid path data renders nothing at all. Latent until now: no shipped consumer depended on query preservation, so this surfaced only once compositions began carrying variable payloads. * fix(cli): serve the runtime ahead of every author script injectRuntime appended its script before </body>, so it landed after any inline script the composition carried. At the moment a composition's own script ran, window.__hyperframes was undefined and getVariables() was unreachable: our documented API did not exist at the point authors are told to call it. Served order was gsap at line 6, the composition's init script at 20, the runtime at 37. A probe inside the composition's IIFE recorded hfTypeAtInit undefined with no variable keys, and the element rendered its hardcoded fallback rather than the declared value. The runtime is designed to load early. Its entry assigns __timelines, installs the authored-opacity capture (whose own comment says it must run while the document is still parsing), and exposes __hyperframes synchronously, deferring real work to DOMContentLoaded. End-of-body injection defeated all three, and nothing in it needs a parsed DOM, so no defer is wanted. Injects at head start instead, reusing the placement cascade injectScriptsAtHeadStart already implemented rather than adding a fourth copy of it. Head start rather than the closing tag so the runtime also precedes author scripts inside head. injectRuntime has exactly one consumer, the play server's composition route. Every other surface reaches the runtime through the bundler, which already injects into head, or deliberately serves raw. Two registry blocks had independently worked around this by parsing the authored attribute themselves. Those stay, but the workaround is no longer the only way to read a variable at init.
150 lines
5.3 KiB
TypeScript
150 lines
5.3 KiB
TypeScript
/**
|
|
* Shader transition option types, constants, and pure helper functions for
|
|
* injecting shader capture scale and loading mode parameters into composition
|
|
* URLs and srcdoc HTML.
|
|
*/
|
|
|
|
export const SHADER_CAPTURE_SCALE_ATTR = "shader-capture-scale";
|
|
export const SHADER_LOADING_ATTR = "shader-loading";
|
|
const SHADER_CAPTURE_SCALE_PARAM = "__hf_shader_capture_scale";
|
|
const SHADER_LOADING_PARAM = "__hf_shader_loading";
|
|
|
|
export const SHADER_LOADING_PHRASES = [
|
|
"Preparing scene transitions",
|
|
"Sampling outgoing scene motion",
|
|
"Sampling incoming scene motion",
|
|
"Caching transition frames",
|
|
"Finalizing transition preview",
|
|
];
|
|
|
|
export type ShaderLoadingMode = "composition" | "player" | "none";
|
|
|
|
export interface ShaderTransitionState {
|
|
ready?: boolean;
|
|
progress?: number;
|
|
total?: number;
|
|
currentTransition?: number;
|
|
transitionTotal?: number;
|
|
transitionFrame?: number;
|
|
transitionFrames?: number;
|
|
phase?: "cached" | "capturing" | "finalizing";
|
|
loading?: boolean;
|
|
}
|
|
|
|
function normalizeShaderCaptureScale(value: string | null): string | null {
|
|
if (value === null) return null;
|
|
const parsed = Number(value);
|
|
if (!Number.isFinite(parsed) || parsed <= 0) return null;
|
|
return String(Math.min(1, Math.max(0.25, parsed)));
|
|
}
|
|
|
|
function normalizeShaderLoadingMode(value: string | null): ShaderLoadingMode {
|
|
if (value === null || value.trim() === "") return "composition";
|
|
const normalized = value.trim().toLowerCase();
|
|
if (
|
|
normalized === "none" ||
|
|
normalized === "false" ||
|
|
normalized === "0" ||
|
|
normalized === "off"
|
|
) {
|
|
return "none";
|
|
}
|
|
if (
|
|
normalized === "player" ||
|
|
normalized === "true" ||
|
|
normalized === "1" ||
|
|
normalized === "on"
|
|
) {
|
|
return "player";
|
|
}
|
|
return "composition";
|
|
}
|
|
|
|
/** Drop one of our own keys from raw `a=1&b=2` pairs, matched by name so that
|
|
* nothing around it has to be decoded. */
|
|
function withoutParam(pairs: string[], key: string): string[] {
|
|
return pairs.filter((pair) => pair !== "" && pair.split("=")[0] !== key);
|
|
}
|
|
|
|
/**
|
|
* The player's own params, appended to the query the composition author wrote
|
|
* rather than merged into a re-serialized copy of it.
|
|
*
|
|
* `new URLSearchParams(query).toString()` is a form-encoding round trip: it
|
|
* re-encodes the *whole* query as application/x-www-form-urlencoded, which
|
|
* writes every space as `+`. A composition reading its own query with
|
|
* `decodeURIComponent` — percent-decoding, which leaves `+` alone — cannot undo
|
|
* that, so a value of "Ship it today" arrived on the page as "Ship+it+today".
|
|
* The two codecs are not inverses, and the player has no business picking one
|
|
* for a query it is only passing along. The author's bytes now travel through
|
|
* byte-identical; only our two keys are rewritten.
|
|
*/
|
|
function withShaderQueryParams(
|
|
src: string,
|
|
scale: string | null,
|
|
loadingMode: ShaderLoadingMode,
|
|
): string {
|
|
const hashIndex = src.indexOf("#");
|
|
const beforeHash = hashIndex >= 0 ? src.slice(0, hashIndex) : src;
|
|
const hash = hashIndex >= 0 ? src.slice(hashIndex) : "";
|
|
const queryIndex = beforeHash.indexOf("?");
|
|
const path = queryIndex >= 0 ? beforeHash.slice(0, queryIndex) : beforeHash;
|
|
const query = queryIndex >= 0 ? beforeHash.slice(queryIndex + 1) : "";
|
|
let pairs = withoutParam(query.split("&"), SHADER_CAPTURE_SCALE_PARAM);
|
|
pairs = withoutParam(pairs, SHADER_LOADING_PARAM);
|
|
if (scale !== null) pairs.push(`${SHADER_CAPTURE_SCALE_PARAM}=${encodeURIComponent(scale)}`);
|
|
if (loadingMode !== "composition") {
|
|
pairs.push(`${SHADER_LOADING_PARAM}=${encodeURIComponent(loadingMode)}`);
|
|
}
|
|
const nextQuery = pairs.join("&");
|
|
return `${path}${nextQuery ? `?${nextQuery}` : ""}${hash}`;
|
|
}
|
|
|
|
function injectShaderOptionsIntoSrcdoc(
|
|
html: string,
|
|
scale: string | null,
|
|
loadingMode: ShaderLoadingMode,
|
|
): string {
|
|
if (scale === null && loadingMode === "composition") return html;
|
|
const lines: string[] = [];
|
|
if (scale !== null) lines.push(`window.__HF_SHADER_CAPTURE_SCALE=${JSON.stringify(scale)};`);
|
|
if (loadingMode !== "composition") {
|
|
lines.push(`window.__HF_SHADER_LOADING=${JSON.stringify(loadingMode)};`);
|
|
}
|
|
const script = `<script data-hyperframes-player-shader-options>${lines.join("")}</script>`;
|
|
if (/<head\b[^>]*>/i.test(html))
|
|
return html.replace(/<head\b[^>]*>/i, (match) => `${match}${script}`);
|
|
if (/<html\b[^>]*>/i.test(html))
|
|
return html.replace(/<html\b[^>]*>/i, (match) => `${match}${script}`);
|
|
return `${script}${html}`;
|
|
}
|
|
|
|
/**
|
|
* Convenience wrappers that read shader attributes directly from an element,
|
|
* avoiding boilerplate in the web component class body.
|
|
*/
|
|
|
|
export function getShaderModeFromElement(el: Element): ShaderLoadingMode {
|
|
return normalizeShaderLoadingMode(el.getAttribute(SHADER_LOADING_ATTR));
|
|
}
|
|
|
|
export function getShaderCaptureScaleFromElement(el: Element): number {
|
|
return Number(normalizeShaderCaptureScale(el.getAttribute(SHADER_CAPTURE_SCALE_ATTR)) ?? "1");
|
|
}
|
|
|
|
export function prepareSrcForElement(el: Element, src: string): string {
|
|
return withShaderQueryParams(
|
|
src,
|
|
normalizeShaderCaptureScale(el.getAttribute(SHADER_CAPTURE_SCALE_ATTR)),
|
|
getShaderModeFromElement(el),
|
|
);
|
|
}
|
|
|
|
export function prepareSrcdocForElement(el: Element, srcdoc: string): string {
|
|
return injectShaderOptionsIntoSrcdoc(
|
|
srcdoc,
|
|
normalizeShaderCaptureScale(el.getAttribute(SHADER_CAPTURE_SCALE_ATTR)),
|
|
getShaderModeFromElement(el),
|
|
);
|
|
}
|