Files
hyperframes/packages/core/src/runtime/window.d.ts
T
Miguel Ángel 70187a13b5 perf(core): the preview mounts and draws only the scenes near the playhead (#6189)
* 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
2026-10-25 19:39:14 +00:00

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 {};