mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 16:08:56 +00:00
* perf(core): skip rendering preview scenes far from the playhead * refactor(core): split the far-scene pass into small helpers * perf(core): a first render reveals only the clips it reaches * fix(core): reveal the clips holding first-rendered tweens, wherever their window is * feat(core): a scene may load a project helper and wait for fonts and still swap * perf(core): the preview mounts only the scenes near the playhead * perf(core): a seek waits only for the scene it lands in; neighbours mount one per turn * feat(studio): selecting a clip in an unmounted scene mounts that scene first * fix(core): a source a play and a seek both need is fetched and decoded once * fix(core): a scene mounting during play joins the mix without restarting what plays * fix(studio): selecting a clip waits on a scene mount only in a preview that unmounts scenes * fix(core): far scenes still mount after an edit, and an edit to a parked scene keeps its styles * perf(core): web audio schedules a clip only as the playhead comes near it * chore(studio): trim the scene hold helper's comments to its package's share * fix(core): a scene the preview unmounts is freed, not kept by audio, caches or old roots * fix(studio): an unmounted scene's rows and their state come from the markup it mounts with * perf(core): the preview mounts scenes ahead of play and keeps recent ones mounted * refactor(core): keep the far-scene neighbour rule private to its module * style(core): format the far-scene neighbour rule * perf(core): the preview unmounts scenes the playhead leaves, as kept ones slowed each mount * fix(core): scenes that measure text, call their own animate or wait on font loads can unmount * fix(core): each preview scene carries the helpers it loads, so it mounts on its own * fix(core): a mounted scene shows though its stand-in was hidden by display * fix(core): a helper scenes share runs once for the film, and a remounted scene keeps showing * fix(core): a scene that also publishes its timeline under another id stays mounted * feat(core): scenes that draw in 2D or chain the timeline they register can unmount * perf(core): a play frame that draws nothing new skips the hidden-clip lookup * fix(core): a GSAP file copied into a project counts as the library for scene unmounting * style(core): drop an unneeded escape in the registered-chain pattern * chore: core and producer size budgets make room for the preview scene window * fix(core): a scene that draws on a 2D canvas stays mounted * fix(core): a scene the preview unmounts lets go of timelines it built after a font wait * perf(core): a scene leaving the playhead keeps its last rendered size, no forced layout at the cut * refactor(core): the far-scene skip keeps last-render boxes in their own helper * fix(core): a mounting scene never records the runtime's root timeline as its own * chore(producer): raise the size budget to the measured size with the preview runtime inlined * docs(core): keep the far-scene and scene-memory comments within the comment limits * perf(core): style each hidden clip visible once ahead of its cut, so the cut frame does not * fix(core): a seek into a scene still mounting as a neighbour waits for that mount * chore(core): keep comment share and size budgets to main plus the measured core growth
267 lines
11 KiB
TypeScript
267 lines
11 KiB
TypeScript
import type {
|
|
RuntimeSeekOptions,
|
|
RuntimeTimelineChildLike,
|
|
RuntimeTimelineMessage,
|
|
RuntimeTimelineLike,
|
|
SceneAnimation,
|
|
} from "./types";
|
|
import type { RuntimeColorGradingApi } from "./colorGrading";
|
|
import type { HyperframePickerApi } from "../inline-scripts/pickerApi";
|
|
import type { PlayerAPI } from "../core.types";
|
|
import type { ClipTree } from "./clipTree";
|
|
import type { SvgSelectorAliases } from "../compiler/svgSelectorAliases";
|
|
|
|
type ThreeClockLike = {
|
|
elapsedTime: number;
|
|
oldTime: number;
|
|
startTime: number;
|
|
getElapsedTime: () => number;
|
|
getDelta: () => number;
|
|
};
|
|
|
|
type ThreeAnimationMixerLike = {
|
|
setTime?: (time: number) => void;
|
|
update: (deltaTime: number) => ThreeAnimationMixerLike;
|
|
};
|
|
|
|
type ThreeLike = {
|
|
Clock?: {
|
|
prototype: ThreeClockLike;
|
|
};
|
|
AnimationMixer?: {
|
|
prototype: ThreeAnimationMixerLike;
|
|
};
|
|
};
|
|
|
|
declare global {
|
|
interface Window {
|
|
__hfHasFrameSources?: () => boolean;
|
|
__timelines: Record<string, RuntimeTimelineLike>;
|
|
__player?: PlayerAPI;
|
|
__hyperframes?: {
|
|
registerFrameSource: typeof import("./frameSources").registerFrameSource;
|
|
createFilmBridge: typeof import("./filmBridge").createFilmBridge;
|
|
/** A path the calling composition wrote relative to its own file, as a URL the page can load. */
|
|
assetUrl?: (path: string) => string;
|
|
registerRuntimeDataHandler?: (
|
|
channel: string,
|
|
handler: (payload: unknown) => void,
|
|
) => () => void;
|
|
setRuntimeData?: (channel: string, payload: unknown, requestId?: number) => void;
|
|
clearRuntimeData?: (channel: string) => void;
|
|
[key: string]: unknown;
|
|
};
|
|
__clipManifest?: RuntimeTimelineMessage;
|
|
__clipTree?: ClipTree;
|
|
__hfSvgSelectorAliases?: SvgSelectorAliases;
|
|
__hf?: {
|
|
colorGrading?: RuntimeColorGradingApi;
|
|
onSwallowed?: (label: string, err: unknown) => void;
|
|
seek?: (timeSeconds: number, options?: RuntimeSeekOptions) => void;
|
|
duration?: number;
|
|
/** How a length that no timeline supplied was found: the render telemetry reads this. */
|
|
durationSource?: {
|
|
source: "authored" | "derived" | "unresolved";
|
|
seconds: number | null;
|
|
pendingClips: number;
|
|
};
|
|
/** Where each animation's FIRST cycle ends, latest wins, in seconds (root timeline, CSS and
|
|
* Lottie; never script-created WAAPI, media or the declared length); repeats may run past it.
|
|
* Null when unknown. Studio reads it. */
|
|
animationEnd?: () => number | null;
|
|
/** Borrow an element's playback while the transport clock is paused, so the
|
|
* runtime's paused-side enforcement leaves it alone. Always release. */
|
|
leasePausedMedia?: (el: HTMLMediaElement) => void;
|
|
releasePausedMedia?: (el: HTMLMediaElement) => void;
|
|
/** Where Studio's loop wraps to while it plays, or null: the clips due there stay loaded. */
|
|
setLoopStart?: (seconds: number | null) => void;
|
|
/** Read-only level taps for the Studio meters: nothing exists until
|
|
* `start()`, and `stop()` removes every tap. Peaks are linear per channel. */
|
|
audioMeter?: {
|
|
start(): void;
|
|
stop(): void;
|
|
read(): {
|
|
master: { l: number; r: number };
|
|
groups: Record<string, { l: number; r: number }>;
|
|
};
|
|
};
|
|
/** Declared-compute hold for setup no adapter can see (mesh building,
|
|
* shader compiles). Runtime and player hold until every promise
|
|
* registered here, under any key unique to your piece, resolves. */
|
|
buildReady?: Record<string, PromiseLike<unknown>>;
|
|
};
|
|
__playerReady?: boolean;
|
|
__renderReady?: boolean;
|
|
/** Set when start-up or the render-ready publish threw; readiness waits fail with it instead of seeking. */
|
|
__hfStartupError?: string;
|
|
__hfRuntimeTeardown?: (() => void) | null;
|
|
/** What each composition's scripts started on gsap's global timeline, by composition id. */
|
|
__hfSceneAnimations?: Record<string, SceneAnimation[]> | null;
|
|
/** Swap edited scenes from a rebuilt preview document; refuses before changing anything when it cannot. */
|
|
__hfSwapScenes?: (html: string, signal?: AbortSignal) => Promise<void>;
|
|
__hfHoldScenes?: (names: string[]) => Promise<void>;
|
|
__hfParkedSceneMarkup?: (placeholder: Element) => Element | null;
|
|
__HF_EXPORT_RENDER_SEEK_CONFIG?: {
|
|
mode?: string;
|
|
diagnostics?: boolean;
|
|
step?: number;
|
|
offsetFraction?: number;
|
|
fps?: number;
|
|
fpsSource?: "render-options" | "default";
|
|
fpsFallbackReason?: "missing" | "invalid";
|
|
owner?: string;
|
|
};
|
|
__HF_PARITY_MODE?: boolean;
|
|
/** Legacy debug-only fps hint. Render-mode runtime fps uses __HF_EXPORT_RENDER_SEEK_CONFIG.fps. */
|
|
__HF_FPS?: number;
|
|
__HF_MAX_DURATION_SEC?: number;
|
|
__hfThreeTime?: number;
|
|
/**
|
|
* Current seek position in seconds, set by the TypeGPU/WebGPU adapter.
|
|
* Poll this from your WebGPU render loop instead of `performance.now()`
|
|
* to get the deterministic seek position.
|
|
*
|
|
* Also listen for the `"hf-seek"` CustomEvent on `window` for an
|
|
* imperative push signal: `window.addEventListener("hf-seek", e => render(e.detail.time))`.
|
|
*/
|
|
__hfTypegpuTime?: number;
|
|
/**
|
|
* Re-render GPU adapters (Three.js / WebGPU) at the given time, bypassing
|
|
* the `"hf-seek"` dedup. Called by the engine after injecting decoded
|
|
* video frames so GPU compositions re-upload their video textures from the
|
|
* freshly-injected `__render_frame__` images. See `forceDispatchSeekEvent`.
|
|
*/
|
|
__hfReseekGpu?: (time: number) => void;
|
|
/**
|
|
* Await GPU work registered synchronously by `hf-seek` listeners through
|
|
* `event.detail.waitUntil(...)`; `videoFrames: false` skips the video-frame holds.
|
|
*/
|
|
__hfWaitForSeekCompletion?: (options?: { videoFrames?: boolean }) => Promise<void>;
|
|
/**
|
|
* Canonical root-timeline start for a media element. Snapshot capture uses
|
|
* this runtime-owned resolver so reference expressions, authored timing
|
|
* restoration, and arbitrary composition nesting cannot drift.
|
|
*/
|
|
__hfResolveMediaStartSeconds?: (element: Element) => number;
|
|
__HF_PICKER_API?: HyperframePickerApi;
|
|
gsap?: {
|
|
timeline: (params?: { paused?: boolean }) => RuntimeTimelineLike;
|
|
set?: (target: Element, vars: Record<string, unknown>) => unknown;
|
|
config?: (vars: Record<string, unknown>) => unknown;
|
|
parseEase?: (
|
|
ease: string | ((progress: number) => number),
|
|
...args: unknown[]
|
|
) => ((progress: number) => number) | null;
|
|
registerPlugin?: (plugin: unknown) => void;
|
|
globalTimeline?: {
|
|
getChildren?: (
|
|
nested?: boolean,
|
|
tweens?: boolean,
|
|
timelines?: boolean,
|
|
) => RuntimeTimelineChildLike[];
|
|
};
|
|
ticker?: {
|
|
tick: () => void;
|
|
};
|
|
};
|
|
THREE?: ThreeLike;
|
|
/**
|
|
* Global Anime.js v4 namespace (set by the UMD or IIFE bundle).
|
|
* Register returned instances on `window.__hfAnime`; v4 has no
|
|
* `anime.running` auto-discovery registry.
|
|
*/
|
|
anime?: {
|
|
animate?: (targets: unknown, params?: unknown) => unknown;
|
|
createTimeline?: (params?: unknown) => unknown;
|
|
/** Legacy v3 registry retained for backward-compatible discovery. */
|
|
running?: unknown[];
|
|
};
|
|
/**
|
|
* anime.js instances registered by compositions.
|
|
* The adapter seeks all instances when the player is seeked.
|
|
*
|
|
* Push your animation or timeline instance here:
|
|
* window.__hfAnime = window.__hfAnime || [];
|
|
* window.__hfAnime.push(anim);
|
|
*/
|
|
__hfAnime?: unknown[];
|
|
/**
|
|
* Global lottie-web instance (set by including the lottie.min.js script).
|
|
* The adapter uses `lottie.getRegisteredAnimations()` for auto-discovery.
|
|
*/
|
|
lottie?: {
|
|
loadAnimation: (params: unknown) => unknown;
|
|
getRegisteredAnimations: () => unknown[];
|
|
};
|
|
/**
|
|
* Lottie animation instances registered by compositions.
|
|
* The adapter seeks all instances when the player is seeked.
|
|
*
|
|
* Push your animation instance here after calling `lottie.loadAnimation()`:
|
|
* window.__hfLottie = window.__hfLottie || [];
|
|
* window.__hfLottie.push(anim);
|
|
*/
|
|
__hfLottie?: unknown[];
|
|
/**
|
|
* Mapbox GL JS map instances. Push your map here after creating it:
|
|
* window.__hfMapbox = window.__hfMapbox || [];
|
|
* window.__hfMapbox.push(map);
|
|
*/
|
|
__hfMapbox?: unknown[];
|
|
/**
|
|
* Leaflet map instances. Push your map here after creating it:
|
|
* window.__hfLeaflet = window.__hfLeaflet || [];
|
|
* window.__hfLeaflet.push(map);
|
|
*/
|
|
__hfLeaflet?: unknown[];
|
|
/**
|
|
* Google Maps instances. Push your map here after creating it:
|
|
* window.__hfGoogleMaps = window.__hfGoogleMaps || [];
|
|
* window.__hfGoogleMaps.push(map);
|
|
*/
|
|
__hfGoogleMaps?: unknown[];
|
|
/**
|
|
* MapLibre GL JS map instances. Push your map here after creating it:
|
|
* window.__hfMaplibre = window.__hfMaplibre || [];
|
|
* window.__hfMaplibre.push(map);
|
|
*/
|
|
__hfMaplibre?: unknown[];
|
|
/**
|
|
* D3 transition instances. Push your transition here after creating it:
|
|
* window.__hfD3 = window.__hfD3 || [];
|
|
* window.__hfD3.push(transition);
|
|
*/
|
|
__hfD3?: unknown[];
|
|
/**
|
|
* Render-time variable overrides injected by the engine when the user
|
|
* passes `hyperframes render --variables '<json>'`. Read indirectly via
|
|
* `window.__hyperframes.getVariables()` (or the named `getVariables`
|
|
* export from `@hyperframes/core`), which merges these over the
|
|
* declared defaults from `<html data-composition-variables="...">`.
|
|
*/
|
|
__hfVariables?: Record<string, unknown>;
|
|
/**
|
|
* Per-instance, pre-merged variables for sub-compositions. Keyed by the
|
|
* sub-composition's `data-composition-id`. Populated by the runtime
|
|
* composition loader at mount time: layers the host element's
|
|
* `data-variable-values` over the sub-comp's declared defaults so the
|
|
* scoped `getVariables()` exposed by `compositionScoping.ts` returns the
|
|
* resolved values for the instance currently executing.
|
|
*/
|
|
__hfVariablesByComp?: Record<string, Record<string, unknown>>;
|
|
/**
|
|
* Set to `true` while the GSAP tween-batching interceptor (injected via
|
|
* HF_EARLY_STUB in fileServer.ts) is still draining queued tween calls
|
|
* through requestAnimationFrame batches. Cleared and the "hf-timelines-built"
|
|
* CustomEvent is dispatched when all queues are empty.
|
|
*
|
|
* init.ts uses this to decide whether to defer `bindRootTimelineIfAvailable`:
|
|
* if true at DOMContentLoaded time, it adds a one-shot event listener and
|
|
* rebinds after the event fires.
|
|
*/
|
|
__hfTimelinesBuilding?: boolean;
|
|
}
|
|
}
|
|
|
|
export {};
|