Skip to content

Write HTML. Render video. Built for agents.

10.6 KB
Raw Blame
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>;
    __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 {};