reacthub-pixitweenjs 0.3.0-alpha.3 → 0.3.0-alpha.4

package/README.md

@@ -193,9 +193,9 @@ Display images with advanced transformations and filters.
     alpha: 1,
     scale: 1,
     colorCorrection: {
-      temperature: 6500,
-      contrast: 1,
-      saturation: 1,
+      temperature: 10,   // slider units: -100..100, 0 = no change
+      contrast: 0,
+      saturation: 0,
       blurRadius: 0,
     },
   }}
@@ -385,27 +385,36 @@ Create complex animations with precise timing:
 ### 🎨 Color Correction & Effects
 
 Driven by the shared `useSpriteFilters` hook (Pixi v8 + `pixi-filters` v6).
-Ordered filter chain: temperature → sharpness → HSL → adjustment →
-effect preset → blur → vignette → noise.
+Ordered filter chain: plateKey → exposure → temperature/tint → highlights/shadows →
+adjustment → vibrance → hue → sharpness → edge feather → effect preset → blur → vignette →
+noise → blend composite.
+
+`colorCorrection` uses **slider units** (neutral = `0`), the same as the Clippy editor:
 
 ```tsx
 transformation={{
   colorCorrection: {
-    temperature: 10,      // -100 to +100 (warm/cool)
-    contrast: 1.2,
-    saturation: 1.5,
-    brightness: 1.1,
-    hue: 0,               // degrees
-    sharpness: 0.3,       // 0–1
-    blurRadius: 0,        // Kawasaki blur strength
-    vignette: 0,          // 0–1
-    noise: 0,             // 0–1
-    red: 1, green: 1, blue: 1, alpha: 1, gamma: 1,
+    // -100..100, 0 = no change
+    brightness: 0, contrast: 20, saturation: 40,
+    red: 0, green: 0, blue: 0,
+    temperature: 10, tint: 0,
+    highlights: 0, shadows: 0, exposure: 0, vibrance: 0,
+    hue: 0,               // -180..180 degrees
+    // 0..100
+    sharpness: 0, blurRadius: 0, vignette: 0, noise: 0, edgeFeather: 0,
+    // 1 = no change
+    gamma: 1, alpha: 1,
   },
-  effect: "Sepia", // BlackAndWhite | Sepia | RetroVintage | NightVision | CYAN | Vignette | None
+  // Legacy string, or { name, intensity (0-100), params } for the ~60 presets
+  // (Warm, Cool, Cinematic, Neon, VHS, GlitchWave, ...). See Effects.
+  effects: { name: "Sepia", intensity: 100 },
+  blendMode: 4,           // numeric code; 4 = overlay (see BlendModes)
 }}
 ```
 
+Migrating from the old multiplier convention (`contrast: 1.2` = +20%)? Use
+`fromMultiplierColorCorrection({ contrast: 1.2 })` → `{ contrast: 20 }`.
+
 ### 🪟 Border + Mask
 
 Every uplifted sprite supports an optional border stroke and a mask

package/dist/components/AepComposition/AepAudioLayer.d.ts

@@ -10,6 +10,10 @@ export interface AepAudioLayerProps {
     pan?: AepAnimatable<number>;
     muted?: boolean;
     visible?: boolean;
+    /** Offset into the audio FILE the clip starts from, seconds. Default 0. */
+    trimStart?: number;
+    /** Playback rate. Default 1. */
+    speed?: number;
     transformation: {
         x: number;
         y: number;
@@ -25,4 +29,6 @@ export interface AepAudioLayerProps {
     };
     onContainerRefReady?: (uniqueId: string, ref: React.MutableRefObject<unknown>) => void;
 }
+/** Layer frame at master time `t`: keyframe `t === inPoint` sits at `offsetSec`. */
+export declare const layerFrameAt: (t: number, offsetSec: number, inPointFrames: number, fps: number) => number;
 export declare const AepAudioLayer: React.FC<AepAudioLayerProps>;

package/dist/components/AepComposition/AepComposition.d.ts

@@ -12,5 +12,7 @@ export interface AepCompositionProps {
     onError?: (err: unknown) => void;
     theme?: AepThemeMap;
     textOverrides?: AepTextOverrideMap;
+    onRenderReady?: () => void;
+    onLayerError?: (layerId: string, error: unknown) => void;
 }
 export declare const AepComposition: React.FC<AepCompositionProps>;

package/dist/components/AepComposition/AudioPlaybackManager.d.ts

@@ -0,0 +1,38 @@
+import { AudioRegistry } from '../../utils/audio/audioRegistry';
+import { AudioClipSpec } from '../../utils/audio/audioSync';
+import * as React from "react";
+export type AudioPlaybackElement = AudioClipSpec;
+export interface AudioPlaybackManagerProps {
+    audioElements: ReadonlyArray<AudioPlaybackElement>;
+    /** Defaults to the shared registry. Pass your own to isolate multiple players. */
+    registry?: AudioRegistry;
+    /**
+     * Stop and release EVERY element in the registry (and close its audio context) when this
+     * unmounts. Default true: right for the one editor-wide manager that owns the registry. Turn it
+     * off when the registry is shared with others and you only want to remove your own clips.
+     */
+    clearOnUnmount?: boolean;
+}
+/**
+ * AudioPlaybackManager — the single owner of audio playback. Renders nothing; mount it once,
+ * anywhere under the GSAP provider (it does not need to be inside the Pixi stage).
+ *
+ * Ported from the Clippy editor. The architecture is the point: ONE listener on the master
+ * timeline decides, for every clip, whether its element should be playing, where, and how loud.
+ * It replaces the old per-sprite GSAP tweens whose onStart/onUpdate hooks raced when clips were
+ * added dynamically, and it has no per-clip timing state to go stale.
+ *
+ * The decision itself is pure (`decideAudioSync`) and unit-tested; this component only owns the
+ * element lifecycle and the event wiring. Differences from Clippy:
+ *  - plain `HTMLAudioElement` instead of Howler (no dependency; same streaming behaviour as
+ *    Howler's html5 mode, which Clippy already uses)
+ *  - the playhead moving BACKWARDS or being scrubbed pauses the clips (Clippy kept playing
+ *    forward and re-seeked every 200 ms)
+ *  - the file position honours `speed` (Clippy's drifted at any speed other than 1)
+ *  - handles `play()` being blocked by the autoplay policy, and element load errors, instead of
+ *    silently stalling
+ *  - a RESUME event starts clips immediately rather than waiting for the next tick
+ */
+declare const AudioPlaybackManager: React.FC<AudioPlaybackManagerProps>;
+export default AudioPlaybackManager;
+export { AudioPlaybackManager };

package/dist/components/AepComposition/index.d.ts

@@ -37,3 +37,6 @@ export { AepTextOverrideProvider, useAepTextOverride, resolveTextSource, } from
 export type { AepTextOverrideMap } from './AepTextOverrideContext';
 export { resolvePostFxList } from './resolvePostFxList';
 export { shouldSplitText } from './shouldSplitText';
+export { AudioPlaybackManager } from './AudioPlaybackManager';
+export type { AudioPlaybackManagerProps, AudioPlaybackElement, } from './AudioPlaybackManager';
+export * from './model3d';

package/dist/components/AepComposition/model3d/Pixi3DModelLayer.d.ts

@@ -0,0 +1,9 @@
+import { ForwardedRefResponse, PixiBaseSpriteProps } from '../../../types/BaseProps';
+import { AepModel3DLayer } from '../../../types/aep';
+import * as React from "react";
+export interface Pixi3DModelLayerProps extends PixiBaseSpriteProps {
+    layer: AepModel3DLayer;
+}
+export declare const Pixi3DModelLayer: React.MemoExoticComponent<({ ref, layer, ...props }: Pixi3DModelLayerProps & {
+    ref?: React.Ref<ForwardedRefResponse | null>;
+}) => import("react/jsx-runtime").JSX.Element>;

package/dist/components/AepComposition/model3d/ThreeOffscreenRenderer.d.ts

@@ -0,0 +1,49 @@
+import * as THREE from "three";
+export interface OffscreenRenderRequest {
+    canvas: HTMLCanvasElement;
+    scene: THREE.Scene;
+    camera: THREE.PerspectiveCamera;
+    width: number;
+    height: number;
+}
+/** The slice of THREE.WebGLRenderer this service uses (lets tests inject a fake). */
+export interface OffscreenGlRenderer {
+    readonly domElement: HTMLCanvasElement;
+    setSize(width: number, height: number, updateStyle?: boolean): void;
+    setViewport(x: number, y: number, width: number, height: number): void;
+    render(scene: THREE.Scene, camera: THREE.Camera): void;
+    dispose(): void;
+    forceContextLoss(): void;
+}
+export declare class ThreeOffscreenRenderer {
+    readonly renderer: THREE.WebGLRenderer;
+    private readonly gl;
+    private width;
+    private height;
+    constructor(gl?: OffscreenGlRenderer);
+    render({ canvas, scene, camera, width, height }: OffscreenRenderRequest): void;
+    dispose(): void;
+}
+/**
+ * Reference-counted pool of shared things keyed by owner (a Pixi `Application`).
+ *
+ * The last release schedules disposal after a grace period, so a StrictMode double-mount or a
+ * stage remount reuses the same renderer instead of tearing down and recreating a WebGL context.
+ * Without this, every Application (each Storybook story switch, for example) leaked a context
+ * until the browser's ~16 context cap started dropping live ones.
+ */
+export declare function createRendererPool<T extends {
+    dispose(): void;
+}>(create: () => T, graceMs?: number): {
+    acquire(owner: unknown): T;
+    release(owner: unknown): void;
+    size: () => number;
+};
+/**
+ * Take a use of the shared renderer for a Pixi `Application` (or a process-wide fallback when no
+ * application is available, e.g. in tests/portals). Pair every call with `releaseOffscreenRenderer`.
+ */
+export declare function acquireOffscreenRenderer(app?: object | null): ThreeOffscreenRenderer;
+export declare function releaseOffscreenRenderer(app?: object | null): void;
+/** @deprecated Does not track ownership; use `acquireOffscreenRenderer` / `releaseOffscreenRenderer`. */
+export declare function getOffscreenRenderer(app?: object | null): ThreeOffscreenRenderer;

package/dist/components/AepComposition/model3d/framing.d.ts

@@ -0,0 +1,30 @@
+export interface CameraFraming {
+    position: [number, number, number];
+    target: [number, number, number];
+}
+/**
+ * Fixed camera for a model whose rest-pose bounds are `center` / `maxDim`.
+ *
+ * The camera frames the UNSCALED, UNTRANSLATED model and never follows it. Following `view.position`
+ * or compensating for `view.scale` would cancel the very motion those keyframes describe (the
+ * object would sit still in the viewport). Use `camera.fit` to leave room for growth or travel.
+ */
+export declare function frameCamera(center: readonly [number, number, number], maxDim: number, fovDeg: number, fit: number): CameraFraming;
+/** Seconds into a glTF clip: relative to the layer's in-point, never negative. */
+export declare function clipTimeSeconds(frame: number, inPointFrames: number, fps: number): number;
+/** Whether `frame` is inside the layer's half-open window [inPoint, outPoint). */
+export declare function isFrameInRange(frame: number, inPointFrames: number, outPointFrames: number): boolean;
+export interface FramingBounds {
+    center: [number, number, number];
+    /** Largest edge, in model units. */
+    maxDim: number;
+}
+/**
+ * Bounds used to frame the camera. An authored `bounds` override wins over what was measured from
+ * the loaded model; its `center` defaults to the measured centre. Measured bounds of a skinned
+ * glTF are cached at the first pose and do not follow the animation, hence the override.
+ */
+export declare function resolveFramingBounds(measured: FramingBounds, override?: {
+    center?: readonly [number, number, number];
+    size: readonly [number, number, number];
+}): FramingBounds;

package/dist/components/AepComposition/model3d/geometry.d.ts

@@ -0,0 +1,27 @@
+import { AepModel3DSource } from '../../../types/aep';
+import * as THREE from "three";
+export type PrimitiveShape = Extract<AepModel3DSource, {
+    type: "primitive";
+}>["shape"];
+export interface PrimitiveProportions {
+    width?: number;
+    height?: number;
+    depth?: number;
+}
+export declare function buildPrimitiveGeometry(shape: PrimitiveShape, proportions?: PrimitiveProportions): THREE.BufferGeometry;
+export interface ExtrudeGeometryResult {
+    geometry: THREE.ExtrudeGeometry;
+    /** Contour width/height in the same units as the input points. */
+    width: number;
+    height: number;
+}
+export declare function buildExtrudeGeometry(contour: ReadonlyArray<readonly [number, number]>, depth: number, bevel?: number): ExtrudeGeometryResult;
+export interface BuiltSourceGeometry {
+    geometry: THREE.BufferGeometry;
+    /**
+     * True when the geometry has two material groups: caps (0) and sides (1).
+     * Boxes have six groups (+X, -X, +Y, -Y, +Z, -Z).
+     */
+    materialGroups: "single" | "extrude" | "box";
+}
+export declare function buildSourceGeometry(source: AepModel3DSource, sampledDepth: number): BuiltSourceGeometry;

package/dist/components/AepComposition/model3d/index.d.ts

@@ -0,0 +1,14 @@
+export { Pixi3DModelLayer } from './Pixi3DModelLayer';
+export type { Pixi3DModelLayerProps } from './Pixi3DModelLayer';
+export { AepReadinessProvider, useAepCompositionReady, useAepReadiness, } from './readiness';
+export type { AepReadinessContextValue } from './readiness';
+export { ThreeOffscreenRenderer, acquireOffscreenRenderer, releaseOffscreenRenderer, createRendererPool, getOffscreenRenderer, } from './ThreeOffscreenRenderer';
+export type { OffscreenRenderRequest, OffscreenGlRenderer, } from './ThreeOffscreenRenderer';
+export { frameCamera, clipTimeSeconds, isFrameInRange } from './framing';
+export type { CameraFraming } from './framing';
+export { LIGHTING_PRESETS, DEFAULT_LIGHTING_PRESET, resolveLightingConfig, directionFromAzimuthElevation, } from './lighting';
+export type { LightingConfig, LightingOverrides, LightingPresetName, LightingRig, } from './lighting';
+export { buildPrimitiveGeometry, buildExtrudeGeometry, buildSourceGeometry, } from './geometry';
+export type { PrimitiveShape, PrimitiveProportions, ExtrudeGeometryResult, BuiltSourceGeometry, } from './geometry';
+export { sampleModel3DState, model3DStateKey, MODEL3D_DEFAULTS, } from './sampleModel3D';
+export type { SampledModel3DState } from './sampleModel3D';

package/dist/components/AepComposition/model3d/lighting.d.ts

@@ -0,0 +1,40 @@
+import { AepModel3DLighting } from '../../../types/aep';
+import * as THREE from "three";
+export type LightingPresetName = NonNullable<AepModel3DLighting["preset"]>;
+export interface LightingConfig {
+    preset: LightingPresetName;
+    keyAzimuth: number;
+    keyElevation: number;
+    keyIntensity: number;
+    keyColor: string;
+    fillIntensity: number;
+    rimIntensity: number;
+    ambientIntensity: number;
+    environmentIntensity: number;
+    environment: "room" | "none";
+}
+export declare const LIGHTING_PRESETS: Record<LightingPresetName, LightingConfig>;
+export declare const DEFAULT_LIGHTING_PRESET: LightingPresetName;
+export interface LightingOverrides {
+    keyAzimuth?: number;
+    keyElevation?: number;
+    keyIntensity?: number;
+    keyColor?: string;
+    fillIntensity?: number;
+    rimIntensity?: number;
+}
+export declare function resolveLightingConfig(presetName?: LightingPresetName, overrides?: LightingOverrides, environment?: AepModel3DLighting["environment"]): LightingConfig;
+/** Unit vector pointing from the light's target toward the light. */
+export declare function directionFromAzimuthElevation(azimuthDeg: number, elevationDeg: number): [number, number, number];
+export interface LightingRig {
+    group: THREE.Group;
+    ambient: THREE.AmbientLight;
+    key: THREE.DirectionalLight;
+    fill: THREE.DirectionalLight;
+    rim: THREE.DirectionalLight;
+}
+export declare function createLightingRig(config: LightingConfig): LightingRig;
+export declare function applyLightingRig(rig: LightingRig, config: LightingConfig): void;
+export declare function disposeLightingRig(rig: LightingRig): void;
+export declare function getRoomEnvironmentTexture(renderer: THREE.WebGLRenderer): THREE.Texture;
+export declare function applyEnvironment(scene: THREE.Scene, config: LightingConfig, renderer: THREE.WebGLRenderer): void;

package/dist/components/AepComposition/model3d/readiness.d.ts

@@ -0,0 +1,17 @@
+import * as React from "react";
+export interface AepReadinessContextValue {
+    ready: boolean;
+    readyCount: number;
+    total: number;
+    register: (id: string) => () => void;
+    markReady: (id: string) => void;
+    reset: (id: string) => void;
+    reportError: (id: string, error: unknown) => void;
+}
+export declare function useAepCompositionReady(): boolean;
+export declare function useAepReadiness(): AepReadinessContextValue;
+export interface AepReadinessProviderProps {
+    children: React.ReactNode;
+    onLayerError?: (layerId: string, error: unknown) => void;
+}
+export declare const AepReadinessProvider: React.FC<AepReadinessProviderProps>;

package/dist/components/AepComposition/model3d/sampleModel3D.d.ts

@@ -0,0 +1,40 @@
+import { AepModel3DLayer } from '../../../types/aep';
+import { LightingPresetName } from './lighting';
+export interface SampledModel3DState {
+    rotation: [number, number, number];
+    position: [number, number, number];
+    scale: number;
+    extrudeDepth: number;
+    roughness: number;
+    metalness: number;
+    clearcoat: number;
+    preset: LightingPresetName;
+    keyAzimuth: number;
+    keyElevation: number;
+    keyIntensity: number;
+    keyColor: string;
+    fillIntensity: number;
+    rimIntensity: number;
+    environment: "room" | "none";
+    shadowOpacity: number;
+    shadowSoftness: number;
+    shadowOffsetY: number;
+    fov: number;
+    fit: number;
+}
+export declare const MODEL3D_DEFAULTS: {
+    readonly rotation: [number, number, number];
+    readonly position: [number, number, number];
+    readonly scale: 1;
+    readonly roughness: 0.35;
+    readonly metalness: 0.05;
+    readonly clearcoat: 0;
+    readonly shadowOpacity: 0.35;
+    readonly shadowSoftness: 0.6;
+    readonly shadowOffsetY: 0;
+    readonly fov: 35;
+    readonly fit: 1.35;
+};
+export declare function sampleModel3DState(layer: AepModel3DLayer, frame: number): SampledModel3DState;
+/** Deterministic identity for the sampled state, used for dirty checks. */
+export declare function model3DStateKey(state: SampledModel3DState): string;

package/dist/components/PixiAudioSprite/HowlerAudioSprite.d.ts

@@ -14,5 +14,11 @@ interface IAudioPlayer {
     playFromTime: (time: number) => void;
 }
 type UseAudioPlayer = (props: AudioPlayerProps) => IAudioPlayer;
-declare const useHowlerAudioPlayer: UseAudioPlayer;
-export default useHowlerAudioPlayer;
+declare const useAudioElementPlayer: UseAudioPlayer;
+/**
+ * Plain-`HTMLAudioElement` player hook (no Howler involved; the old name was a leftover).
+ * `useHowlerAudioPlayer` stays exported as an alias so existing imports keep working.
+ */
+export { useAudioElementPlayer };
+export declare const useHowlerAudioPlayer: UseAudioPlayer;
+export default useAudioElementPlayer;

package/dist/components/PixiAudioSprite/PixiAudioSprite.d.ts

@@ -1,4 +1,6 @@
 import { PixiBaseSpriteProps, ForwardedRefResponse } from '../../types/BaseProps';
+import { AudioFade, DuckWindow } from '../../utils/audio/gainEnvelope';
+import { AudioRegistry } from '../../utils/audio/audioRegistry';
 import * as React from "react";
 import * as PIXI from "pixi.js";
 export interface PixiAudioSpriteProps extends PixiBaseSpriteProps {
@@ -6,15 +8,49 @@ export interface PixiAudioSpriteProps extends PixiBaseSpriteProps {
     src: string;
     startAt: number;
     endAt: number;
+    /** Offset into the audio FILE the clip starts from (seconds). */
     audioStartAt: number;
-    audioEndAt: number;
+    /** @deprecated Unused. The clip length on the timeline is `endAt - startAt`. */
+    audioEndAt?: number;
     mute: boolean;
     speed: number;
     visible: boolean;
+    /** 0..1. Default 1. */
+    volume?: number;
+    /**
+     * Volume as a function of timeline time in seconds (wins over `volume`). Lets an animation
+     * drive the base volume while fades / ducking / mute still apply on top.
+     */
+    getVolume?: (timelineTime: number) => number;
+    audioFade?: AudioFade;
+    duckWindows?: DuckWindow[];
+    duckTo?: number;
+    /**
+     * Mount a private AudioPlaybackManager for this one clip (default true), so the sprite works
+     * standalone. Set false when the app mounts ONE manager for the whole timeline and passes all
+     * clips to it.
+     */
+    managePlayback?: boolean;
+    /** Registry to use instead of the shared default (isolates multiple players). */
+    registry?: AudioRegistry;
     onContainerRefReady?: (uniqueId: string, ref: React.MutableRefObject<PIXI.Container | null>) => void;
     onSpriteRefReady?: (uniqueId: string, ref: React.MutableRefObject<PIXI.Container | null>) => void;
+    /** Fires once the clip's <audio> element exists (and again if it is replaced). */
     onAudioElementReady?: (uniqueId: string, el: HTMLAudioElement) => void;
 }
+/**
+ * PixiAudioSprite — an audio clip on the timeline, with an optional spectrum visualization.
+ *
+ * Playback is owned by `AudioPlaybackManager` (Clippy's architecture: one listener on the master
+ * timeline decides what plays, where and how loud). This component:
+ *   1. feeds its clip to a manager (its own by default; `managePlayback={false}` to opt out),
+ *   2. exposes the clip's `<audio>` element to callers via `onAudioElementReady`,
+ *   3. draws the waveform from that same element when `transformation.waveform` is set.
+ *
+ * Replaces the previous per-sprite GSAP tween driving a private `Audio`, whose onStart/onUpdate
+ * hooks raced when sprites were added dynamically, had no drift correction, ignored volume and
+ * fades, and re-created the element whenever any prop changed.
+ */
 declare const PixiAudioSprite: ({ ref, ...props }: PixiAudioSpriteProps & {
     ref?: React.Ref<ForwardedRefResponse | null>;
 }) => import("react/jsx-runtime").JSX.Element;

package/dist/components/PixiAudioSprite/index.d.ts

@@ -1 +1,4 @@
 export { default as PixiAudioSprite } from './PixiAudioSprite';
+export type { PixiAudioSpriteProps } from './PixiAudioSprite';
+export { default as useAudioElementPlayer, useHowlerAudioPlayer, } from './HowlerAudioSprite';
+export { default as useAudioVisualizer } from './useAudioVisualizer';

package/dist/components/PixiAudioSprite/useAudioVisualizer.d.ts

@@ -1,18 +1,33 @@
 import { default as AudioMotionAnalyzer } from 'audiomotion-analyzer';
-import { PixiBaseSpriteProps } from '../../types/BaseProps';
-import * as React from "react";
-export type AudioVisualizerProps = Partial<PixiBaseSpriteProps> & {
+import { Waveforms } from '../../types/Effects';
+import { AudioRegistry } from '../../utils/audio/audioRegistry';
+export interface UseAudioVisualizerOptions {
     uniqueId: string;
-    src: string;
-    muted?: boolean;
-    volume?: number;
-    loop?: boolean;
-    playbackRate?: number;
-    visible?: boolean;
-};
-declare const useAudioVisualizer: (audioProps: AudioVisualizerProps) => {
-    audioMotionRef: React.RefObject<AudioMotionAnalyzer | undefined>;
-    blobUrl: string;
-    canvasRef: React.RefObject<HTMLDivElement | null>;
-};
+    waveform: Waveforms;
+    width: number;
+    height: number;
+    /** Defaults to the shared registry the AudioPlaybackManager writes to. */
+    registry?: AudioRegistry;
+}
+export interface AudioVisualizer {
+    /** The analyzer canvas, once an element exists to tap. Wrap it in a Pixi CanvasSource. */
+    canvas: HTMLCanvasElement | null;
+    analyzer: AudioMotionAnalyzer | null;
+}
+/**
+ * Audio spectrum visualization for a clip, driven by the SAME `<audio>` element the
+ * AudioPlaybackManager plays.
+ *
+ * What changed from the previous version (and why):
+ *  - it no longer `fetch`es the whole audio file into a blob just to build an element; it taps
+ *    the element the manager already owns, so there is one download and one playback path
+ *  - the element is routed through Web Audio ONCE, via the registry's shared source node, so a
+ *    visualizer and stereo pan can coexist (previously they were mutually exclusive: a second
+ *    `createMediaElementSource` throws)
+ *  - the analyzer shares the registry's audio context; the manager resumes it on play
+ *  - the analyzer is built once per (clip, size). A waveform change updates its options in place,
+ *    because rebinding a new source node to the element is rejected by the browser
+ *  - the analyzer and its host element are destroyed on unmount (they leaked before)
+ */
+export declare function useAudioVisualizer({ uniqueId, waveform, width, height, registry, }: UseAudioVisualizerOptions): AudioVisualizer;
 export default useAudioVisualizer;

package/dist/components/PixiCaptionsTrack/PixiCaptionsTrack.d.ts

@@ -0,0 +1,86 @@
+import { CaptionSegment } from '../../utils/captions';
+import * as React from "react";
+import * as PIXI from "pixi.js";
+/** Style fields read from `transformation`. All optional; defaults suit a bottom caption. */
+export interface PixiCaptionsTransformation {
+    x?: number;
+    y?: number;
+    fontFamily?: string;
+    fontWeight?: string | number;
+    fontSize?: number;
+    fill?: string;
+    stroke?: string | number | null;
+    strokeWidth?: number;
+    dropShadow?: boolean;
+    dropShadowColor?: string | number;
+    dropShadowBlur?: number;
+    dropShadowAlpha?: number;
+    dropShadowAngle?: number;
+    dropShadowDistance?: number;
+    wordWrapWidth?: number;
+    align?: string;
+    padding?: number;
+    /** Active-word colour. */
+    highlightColor?: string;
+    /** Extra px between words, on top of the space. */
+    wordSpacing?: number;
+    /** Selects the render mode (see `captionModeFor`). */
+    captionStyleId?: string | null;
+    /** Background of the `boxed` modes: hex, rgb() or rgba(). */
+    captionBgColor?: string;
+    textTransform?: "none" | "uppercase" | "lowercase";
+    /** Pill behind the active word in `wordbox`. */
+    captionActiveWordBg?: string;
+}
+export interface PixiCaptionsTrackProps {
+    /** Cue list. Build one with `parseSubtitles`, `groupWordsIntoSegments` or `normalizeCaptionSegments`. */
+    segments: ReadonlyArray<CaptionSegment>;
+    uniqueId: string;
+    transformation?: PixiCaptionsTransformation;
+    /** Fallback render-mode id when `transformation.captionStyleId` is unset. */
+    style?: string | null;
+    visible?: boolean;
+    disabled?: boolean;
+    /** Caption item start/end on the timeline (s). Used to detect clip-local cue times. */
+    startAt?: number;
+    endAt?: number;
+    /**
+     * Pin the caption to this master-timeline time (seconds) instead of following the playhead.
+     * Makes the output a pure function of time: use it for frame-exact export.
+     */
+    currentTime?: number;
+    onContainerRefReady?: (uniqueId: string, ref: React.RefObject<PIXI.Container | null>) => void;
+    /** Click on the caption (the invisible hit area). */
+    onClick?: (uniqueId: string, event: unknown) => void;
+    mouseOverSpriteRef?: {
+        current?: unknown;
+    };
+}
+/**
+ * PixiCaptionsTrack — word-timed (karaoke) captions on the Pixi canvas.
+ *
+ * Ported from the Clippy editor. The frame is a PURE function of (style, words, t): the playhead
+ * picks the active word (`sampleCaptionAt`), the mode turns that into a look (`wordVisualFor`),
+ * and `layoutCaptionWords` places the words. No GSAP tweens per word, so scrub / seek / reverse
+ * need no tween state and the editor, a server render and an exported frame agree.
+ *
+ * Modes (by `captionStyleId`): pop, glow, boxed, vhs, wordbox, punch, slam, glowpop, springpop,
+ * and `none` (static line). See `captionModeFor`.
+ *
+ * All children use coordinates RELATIVE to the caption centre and the container is placed at
+ * (x, y). In Pixi v8 an empty Graphics contributes a (0,0) point to getLocalBounds(); with
+ * canvas-absolute children the bounds would span from the canvas origin and a transformer box
+ * would swallow the screen.
+ *
+ * Differences from the Clippy original: boxed backgrounds accept hex / rgb() / rgba() (it only
+ * read rgba()), the font/layout caches are flushed through the engine's font events, the blur
+ * filters are destroyed, an optional `currentTime` makes the output deterministic, and the
+ * `wordbox` branch no longer contains a stray unreachable statement.
+ */
+declare const PixiCaptionsTrackInner: {
+    (props: PixiCaptionsTrackProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+declare const PixiCaptionsTrack: typeof PixiCaptionsTrackInner;
+export default PixiCaptionsTrack;
+export { PixiCaptionsTrack };

package/dist/components/PixiCaptionsTrack/index.d.ts

@@ -0,0 +1,5 @@
+export { default as PixiCaptionsTrack } from './PixiCaptionsTrack';
+export type { PixiCaptionsTrackProps, PixiCaptionsTransformation, } from './PixiCaptionsTrack';
+export { useCaptionPlayhead } from './useCaptionPlayhead';
+export { useCaptionStyles } from './useCaptionStyles';
+export { useEmojiTextures } from './useEmojiTextures';

package/dist/components/PixiCaptionsTrack/useCaptionPlayhead.d.ts

@@ -0,0 +1,31 @@
+import { CaptionRenderMode, CaptionSample, CaptionSegment } from '../../utils/captions';
+import type * as PIXI from "pixi.js";
+export interface UseCaptionPlayheadOptions {
+    containerRef: React.RefObject<PIXI.Container | null>;
+    segments: ReadonlyArray<CaptionSegment>;
+    mode: CaptionRenderMode;
+    disabled?: boolean;
+    /** Caption item timeline start / end (seconds), to detect clip-local cue times. */
+    itemStartSec?: number;
+    itemEndSec?: number;
+    /**
+     * Master-timeline time in seconds. When given, the caption is a PURE function of this value,
+     * computed during render: no playhead subscription and no frame lag. Use it for deterministic
+     * export (Remotion frame / fps). When omitted, the master GSAP playhead is followed.
+     */
+    currentTime?: number;
+}
+/**
+ * What the caption shows right now: the active segment, active word and how long that word has
+ * been on / has left.
+ *
+ * Followed mode listens to Pixi's per-frame `onRender` (one callback per frame actually drawn,
+ * no second rAF loop), reads the playhead seconds from the master timeline, and only calls
+ * setState when something visible changed. The word's elapsed/remaining ms change every frame,
+ * but only matter to modes that animate within a word, so other modes do not re-render per frame.
+ *
+ * Controlled mode (`currentTime`) never subscribes. Clippy's loop sets React state from inside
+ * Pixi's render callback, so the committed frame lags the playhead by one; that is fine for live
+ * preview and wrong for an offline renderer that seeks frame by frame.
+ */
+export declare function useCaptionPlayhead({ containerRef, segments, mode, disabled, itemStartSec, itemEndSec, currentTime, }: UseCaptionPlayheadOptions): CaptionSample;