reacthub-pixitweenjs 0.2.109-alpha.7 → 0.3.0-alpha.4

package/dist/types/aep/transform3D.d.ts

@@ -0,0 +1,171 @@
+import { z } from 'zod';
+export declare const aepTransform3DSchema: z.ZodObject<{
+    position: z.ZodUnion<[z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>, z.ZodArray<z.ZodObject<{
+        t: z.ZodNumber;
+        v: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+        easeIn: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+        easeOut: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+        hold: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        t: number;
+        v: [number, number, number];
+        easeIn?: [number, number, number, number] | undefined;
+        easeOut?: [number, number, number, number] | undefined;
+        hold?: boolean | undefined;
+    }, {
+        t: number;
+        v: [number, number, number];
+        easeIn?: [number, number, number, number] | undefined;
+        easeOut?: [number, number, number, number] | undefined;
+        hold?: boolean | undefined;
+    }>, "many">]>;
+    anchor: z.ZodUnion<[z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>, z.ZodArray<z.ZodObject<{
+        t: z.ZodNumber;
+        v: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+        easeIn: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+        easeOut: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+        hold: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        t: number;
+        v: [number, number, number];
+        easeIn?: [number, number, number, number] | undefined;
+        easeOut?: [number, number, number, number] | undefined;
+        hold?: boolean | undefined;
+    }, {
+        t: number;
+        v: [number, number, number];
+        easeIn?: [number, number, number, number] | undefined;
+        easeOut?: [number, number, number, number] | undefined;
+        hold?: boolean | undefined;
+    }>, "many">]>;
+    scale: z.ZodUnion<[z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, z.ZodArray<z.ZodObject<{
+        t: z.ZodNumber;
+        v: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+        easeIn: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+        easeOut: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+        hold: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        t: number;
+        v: [number, number];
+        easeIn?: [number, number, number, number] | undefined;
+        easeOut?: [number, number, number, number] | undefined;
+        hold?: boolean | undefined;
+    }, {
+        t: number;
+        v: [number, number];
+        easeIn?: [number, number, number, number] | undefined;
+        easeOut?: [number, number, number, number] | undefined;
+        hold?: boolean | undefined;
+    }>, "many">]>;
+    rotation: z.ZodUnion<[z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>, z.ZodArray<z.ZodObject<{
+        t: z.ZodNumber;
+        v: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+        easeIn: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+        easeOut: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+        hold: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        t: number;
+        v: [number, number, number];
+        easeIn?: [number, number, number, number] | undefined;
+        easeOut?: [number, number, number, number] | undefined;
+        hold?: boolean | undefined;
+    }, {
+        t: number;
+        v: [number, number, number];
+        easeIn?: [number, number, number, number] | undefined;
+        easeOut?: [number, number, number, number] | undefined;
+        hold?: boolean | undefined;
+    }>, "many">]>;
+    opacity: z.ZodUnion<[z.ZodNumber, z.ZodArray<z.ZodObject<{
+        t: z.ZodNumber;
+        v: z.ZodNumber;
+        easeIn: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+        easeOut: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+        hold: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        t: number;
+        v: number;
+        easeIn?: [number, number, number, number] | undefined;
+        easeOut?: [number, number, number, number] | undefined;
+        hold?: boolean | undefined;
+    }, {
+        t: number;
+        v: number;
+        easeIn?: [number, number, number, number] | undefined;
+        easeOut?: [number, number, number, number] | undefined;
+        hold?: boolean | undefined;
+    }>, "many">]>;
+}, "strict", z.ZodTypeAny, {
+    scale: [number, number] | {
+        t: number;
+        v: [number, number];
+        easeIn?: [number, number, number, number] | undefined;
+        easeOut?: [number, number, number, number] | undefined;
+        hold?: boolean | undefined;
+    }[];
+    position: [number, number, number] | {
+        t: number;
+        v: [number, number, number];
+        easeIn?: [number, number, number, number] | undefined;
+        easeOut?: [number, number, number, number] | undefined;
+        hold?: boolean | undefined;
+    }[];
+    anchor: [number, number, number] | {
+        t: number;
+        v: [number, number, number];
+        easeIn?: [number, number, number, number] | undefined;
+        easeOut?: [number, number, number, number] | undefined;
+        hold?: boolean | undefined;
+    }[];
+    rotation: [number, number, number] | {
+        t: number;
+        v: [number, number, number];
+        easeIn?: [number, number, number, number] | undefined;
+        easeOut?: [number, number, number, number] | undefined;
+        hold?: boolean | undefined;
+    }[];
+    opacity: number | {
+        t: number;
+        v: number;
+        easeIn?: [number, number, number, number] | undefined;
+        easeOut?: [number, number, number, number] | undefined;
+        hold?: boolean | undefined;
+    }[];
+}, {
+    scale: [number, number] | {
+        t: number;
+        v: [number, number];
+        easeIn?: [number, number, number, number] | undefined;
+        easeOut?: [number, number, number, number] | undefined;
+        hold?: boolean | undefined;
+    }[];
+    position: [number, number, number] | {
+        t: number;
+        v: [number, number, number];
+        easeIn?: [number, number, number, number] | undefined;
+        easeOut?: [number, number, number, number] | undefined;
+        hold?: boolean | undefined;
+    }[];
+    anchor: [number, number, number] | {
+        t: number;
+        v: [number, number, number];
+        easeIn?: [number, number, number, number] | undefined;
+        easeOut?: [number, number, number, number] | undefined;
+        hold?: boolean | undefined;
+    }[];
+    rotation: [number, number, number] | {
+        t: number;
+        v: [number, number, number];
+        easeIn?: [number, number, number, number] | undefined;
+        easeOut?: [number, number, number, number] | undefined;
+        hold?: boolean | undefined;
+    }[];
+    opacity: number | {
+        t: number;
+        v: number;
+        easeIn?: [number, number, number, number] | undefined;
+        easeOut?: [number, number, number, number] | undefined;
+        hold?: boolean | undefined;
+    }[];
+}>;
+export type AepTransform3D = z.infer<typeof aepTransform3DSchema>;

package/dist/types/index.d.ts

@@ -1,4 +1,8 @@
 export * from './Animations';
 export * from './BaseProps';
 export * from './BlendModes';
+export * from './OverlayTypes';
 export * from './transformation';
+export * from './MaskTypes';
+export * from './CropTypes';
+export * from './aep';

package/dist/utils/AppStateProvider.d.ts

@@ -3,6 +3,7 @@ interface AppState {
     transformation: {
         [key: string]: unknown;
     };
+    [key: string]: unknown;
 }
 interface AppStateContextProviderProps extends AppState {
     children: React.ReactNode;

package/dist/utils/AppWrapper.d.ts

@@ -2,6 +2,9 @@ import * as React from "react";
 interface AppProps {
     children: React.ReactNode;
     backgroundColor?: string;
+    backgroundAlpha?: number;
+    width?: number;
+    height?: number;
 }
 export declare const AppWrapper: React.FC<AppProps>;
 export {};

package/dist/utils/ContextBridge.d.ts

@@ -2,6 +2,6 @@ import * as React from "react";
 declare const ContextBridge: <T>({ children, Context, render, }: {
     children: React.ReactNode;
     Context: React.Context<T>;
-    render: (children: React.ReactNode) => JSX.Element;
+    render: (children: React.ReactNode) => React.JSX.Element;
 }) => import("react/jsx-runtime").JSX.Element;
 export default ContextBridge;

package/dist/utils/GsapAnims.d.ts

@@ -1,3 +1,2 @@
 import { IGsapAnimInterface, Animations } from '../types/Animations';
-
 export declare const getAnimByName: (animate: Animations) => IGsapAnimInterface;

package/dist/utils/InteractionManager.d.ts

@@ -4,14 +4,5 @@ type PixiInteractionManagerProps = {
         [key: string]: unknown;
     };
 };
-/**
- * Initialize Pixi Interaction Manager
- * @param param0
- * @returns
- * @see https://pixijs.download/dev/docs/PIXI.InteractionManager.html
- * @see https://pixijs.download/dev/docs/PIXI.InteractionManager.html#moveWhenInside
- * @see https://pixijs.download/dev/docs/PIXI.InteractionManager.html#on
- *
- * */
-declare const InteractionManager: ({ children, options, }: PixiInteractionManagerProps) => import('react').ReactNode;
+declare const InteractionManager: ({ children }: PixiInteractionManagerProps) => import('react').ReactNode;
 export default InteractionManager;

package/dist/utils/PixiSelector.d.ts

@@ -0,0 +1,17 @@
+import * as PIXI from "pixi.js";
+/** Stable element label from a uniqueId. */
+export declare const getElementName: (uniqueId: string) => string;
+/** Inverse of `getElementName`; null when the label is not an element label. */
+export declare const getUniqueIdFromName: (name: string | null | undefined) => string | null;
+/** Find a descendant by exact label (recursive). */
+export declare const findByName: (container: PIXI.Container | null | undefined, name: string | null | undefined) => PIXI.Container | null;
+/** Find every descendant whose label matches a `*` glob, e.g. `image-*`. */
+export declare const findAllByPattern: (container: PIXI.Container | null | undefined, pattern: string) => PIXI.Container[];
+export interface PixiSelector {
+    (name: string): PIXI.Container | null;
+    all: (pattern: string) => PIXI.Container[];
+    byId: (uniqueId: string) => PIXI.Container | null;
+    byType: (type: string) => PIXI.Container[];
+}
+/** A selector scoped to `container`, like `gsap.utils.selector` for Pixi. */
+export declare const createPixiSelector: (container: PIXI.Container) => PixiSelector;

package/dist/utils/aeMath/zoomToFov.d.ts

@@ -0,0 +1 @@
+export declare function zoomToFov(zoomPx: number, compHeight: number): number;

package/dist/utils/areSpritePropsEqual.d.ts

@@ -0,0 +1,8 @@
+export declare const SPRITE_REF_PROP_NAMES: readonly ["mouseOverSpriteRef", "mouseOverTransformerRef", "spriteHelperRef", "canvasImageRef", "textEditorRef", "onContainerRefReady", "onSpriteRefReady"];
+/**
+ * `React.memo` comparator for sprite components. Skips re-render while
+ * the transformer is actively dragging, and otherwise compares props
+ * after omitting ref-typed entries.
+ */
+export declare function areSpritePropsEqual<P extends object>(prev: Readonly<P>, next: Readonly<P>, extraIgnore?: readonly string[]): boolean;
+export default areSpritePropsEqual;

package/dist/utils/assetRefCount.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared ownership of `PIXI.Assets`-cached resources.
+ *
+ * `PIXI.Assets` caches one texture per URL, so every sprite showing that URL gets the SAME
+ * texture. Unloading on one sprite's unmount destroys it under any other sprite still using
+ * it, and a remount (a stage swapping canvases with the same assets) runs the old cleanup's
+ * unload right as the new mount resolves to the cached texture, leaving a destroyed texture
+ * on screen. So: count users per key and unload only once nobody has used it for a grace
+ * period, which also lets an immediate remount reuse the loaded texture.
+ *
+ * Extracted from Clippy's video asset cache so images/SVGs can use it too.
+ */
+export declare const DEFAULT_UNLOAD_GRACE_MS = 3000;
+export interface AssetRefCounter {
+    /** Mark `key` in use; cancels a pending unload so a remount keeps the texture. */
+    acquire: (key: string) => void;
+    /** Release one use; the asset is unloaded after the grace period if still unused. */
+    release: (key: string) => void;
+}
+export declare function createAssetRefCounter(graceMs?: number): AssetRefCounter;

package/dist/utils/audio/audioRegistry.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Registry of the <audio> elements the AudioPlaybackManager owns, keyed by clip uniqueId, plus the
+ * Web Audio graph nodes built on top of them.
+ *
+ * Ported from the Clippy editor's `audioRegistry`, with `Howl` replaced by `HTMLAudioElement`
+ * (this engine plays through plain elements; see AudioPlaybackManager for why).
+ *
+ * It lives outside React so the manager (outside the Pixi stage) and the waveform / pan code
+ * (inside it) reach the SAME element without bridging a context through the Pixi tree.
+ *
+ * Why the source-node cache matters: `createMediaElementSource(el)` can be called ONCE per
+ * element, ever. Pan and a visualizer both want it, so whoever asks first creates the node and
+ * everyone else reuses it via `getOrCreateSourceNode`. That removes the old "pan and waveform
+ * are mutually exclusive" limitation.
+ *
+ * The registry is an instance (`createAudioRegistry`) so two players on one page do not share
+ * state; `audioRegistry` is the default shared one, which is what one editor player wants.
+ */
+export interface AudioRegistry {
+    get(id: string): HTMLAudioElement | undefined;
+    set(id: string, el: HTMLAudioElement, src: string): void;
+    srcFor(id: string): string | undefined;
+    has(id: string): boolean;
+    /** Stop and release the element. Keeps the source node (it cannot be recreated for the element). */
+    delete(id: string): void;
+    forEach(fn: (el: HTMLAudioElement, id: string) => void): void;
+    readonly size: number;
+    /** Called whenever an element is added, replaced or removed. Returns the unsubscribe. */
+    subscribe(fn: () => void): () => void;
+    /**
+     * Increments on every change. Read it with `useSyncExternalStore(registry.subscribe, () =>
+     * registry.version)` so a component can never miss a change that happens between its render
+     * and its subscription (a child's effect runs before its parent's).
+     */
+    readonly version: number;
+    /** The shared Web Audio context, created on first use. */
+    getContext(): AudioContext | null;
+    /** The context only if it already exists (resume it without creating one). */
+    getContextIfExists(): AudioContext | null;
+    /** The element's one-and-only MediaElementAudioSourceNode, created on first request. */
+    getOrCreateSourceNode(id: string): MediaElementAudioSourceNode | null;
+    getSourceNode(id: string): MediaElementAudioSourceNode | undefined;
+    /** Register a node created elsewhere (e.g. by AudioMotion) so others can reuse it. */
+    setSourceNode(id: string, node: MediaElementAudioSourceNode): void;
+    hasSourceNode(id: string): boolean;
+    /** Stop + release every element, drop the source nodes, close the context. */
+    clear(): void;
+}
+export declare function createAudioRegistry(): AudioRegistry;
+/** The default registry: one editor player on screen at a time. */
+export declare const audioRegistry: AudioRegistry;

package/dist/utils/audio/audioSync.d.ts

@@ -0,0 +1,98 @@
+import { AudioFade, DuckWindow } from './gainEnvelope';
+/** Seek only when the element has drifted this far from where the timeline says it should be. */
+export declare const DRIFT_TOLERANCE_SEC = 0.2;
+/** Stay this far inside the end of the media so a seek never lands on / past EOF. */
+export declare const END_GUARD_SEC = 0.05;
+export interface AudioClipSpec {
+    uniqueId: string;
+    src: string;
+    /** Timeline position where the clip starts (seconds). */
+    start: number;
+    /** Timeline position where the clip ends (seconds). */
+    end: number;
+    /** Offset into the audio FILE the clip starts from (seconds). */
+    frameStartAt: number;
+    /** Clip volume 0..1. Default 1. */
+    volume?: number;
+    /**
+     * Volume as a function of timeline time (seconds); wins over `volume`. Lets another system
+     * (e.g. an animated AEP `level`) drive the base volume while fades/ducking/mute still apply on
+     * top. Being a function of `t`, not of mutable state, it is correct under scrub and seek.
+     */
+    getVolume?: (timelineTime: number) => number;
+    mute?: boolean;
+    /** Playback rate. Default 1. */
+    speed?: number;
+    audioFade?: AudioFade;
+    /** Clip-relative windows (seconds) during which the clip ducks. */
+    duckWindows?: DuckWindow[];
+    /** Linear multiplier applied inside those windows. */
+    duckTo?: number;
+}
+/** Master-player state at the moment of a tick. */
+export interface PlayerState {
+    playing: boolean;
+    /** The playhead just moved backwards. */
+    reverse?: boolean;
+    /** The user is dragging the scrubber. */
+    seeking?: boolean;
+}
+/** What the media element is doing right now. */
+export interface ElementSnapshot {
+    paused: boolean;
+    currentTime: number;
+    /** NaN / Infinity until metadata loads. */
+    duration: number;
+}
+export type SyncDecision = {
+    kind: "pause";
+} | {
+    kind: "play";
+    /** Seek here before (or while) playing; null = leave the element where it is. */
+    seekTo: number | null;
+    volume: number;
+    rate: number;
+    /** The element is paused and must be started. */
+    start: boolean;
+};
+/** Is the playhead inside the clip? Start inclusive, end exclusive. */
+export declare const isClipActive: (spec: Pick<AudioClipSpec, "start" | "end">, t: number) => boolean;
+/**
+ * File position that should be playing at timeline time `t`.
+ *
+ * Fix vs Clippy: it used `frameStartAt + (t - start)`, which is right only at speed 1. At speed
+ * s the file advances s seconds per timeline second, so a 2x clip drifted by a full second per
+ * second and the drift check seeked on every tick. Clamped inside the media so it never seeks
+ * past the end.
+ */
+export declare function clipFileTime(spec: Pick<AudioClipSpec, "start" | "frameStartAt" | "speed">, t: number, mediaDuration?: number): number;
+/** Final 0..1 volume for the clip at timeline time `t` (base x fade x duck, or 0 when muted). */
+export declare function clipVolumeAt(spec: AudioClipSpec, t: number): number;
+/**
+ * Decide what to do with a clip's element on this tick.
+ *
+ *  - not in range, not playing, playing backwards, or being scrubbed  -> pause (silent)
+ *  - in range and playing, element paused                              -> seek + start
+ *  - in range and playing, element running                             -> follow the volume
+ *    envelope, and re-seek only if it has drifted more than DRIFT_TOLERANCE_SEC
+ *
+ * Reverse audio is not supported, so the clip is paused while the playhead runs backwards
+ * (Clippy kept playing forward and drift-seeked every 200 ms, which sounds like a stutter).
+ */
+export declare function decideAudioSync(spec: AudioClipSpec, t: number, state: PlayerState, el: ElementSnapshot): SyncDecision;
+/** Minimal slice of HTMLAudioElement we drive (also what tests fake). */
+export interface PlayableAudio {
+    paused: boolean;
+    currentTime: number;
+    volume: number;
+    playbackRate: number;
+    duration: number;
+    play(): Promise<void> | void;
+    pause(): void;
+}
+export declare const snapshotOf: (el: PlayableAudio) => ElementSnapshot;
+/**
+ * Apply a decision to the element. `onPlayBlocked` fires when the browser rejects `play()`
+ * (autoplay policy, no user gesture yet); the sync loop simply tries again on the next tick.
+ */
+export declare function applyAudioDecision(el: PlayableAudio, decision: SyncDecision, onPlayBlocked?: (error: unknown) => void): void;

package/dist/utils/audio/gainEnvelope.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Shared audio gain model.
+ *
+ * Single source of truth for "how loud is this audio clip at time T".
+ * Both playback paths consume it so preview and export cannot diverge:
+ *
+ *   - preview: AudioPlaybackManager (HTMLAudioElement, per GSAP tick)
+ *   - export:  any offline renderer can call `gainAt` per frame with the same spec
+ *
+ * Gain is composed multiplicatively:
+ *
+ *   gain(t) = baseVolume x fade(t) x duck(t)
+ *
+ * `fade` is authored per-clip by the user (transformation.audioFade).
+ * `duck` is derived from other items on the timeline — a music bed ducks
+ * under voiceover. It mirrors the backend envelope built by
+ * agent-orchestrator-service/src/services/duck-envelope.ts so a project
+ * assembled by the agent sounds the same in the editor as it does on render.
+ *
+ * Pure and dependency-free. Ported verbatim from the Clippy editor (utils/audio/gain-envelope.ts).
+ */
+/** One side of a user-authored fade. `volume` is a 0–100 percentage. */
+export interface AudioFadeSide {
+    enabled?: boolean;
+    /** seconds */
+    duration?: number;
+    /** 0–100 — the volume the fade starts from (in) or ends at (out) */
+    volume?: number;
+}
+export interface AudioFade {
+    fadeIn?: AudioFadeSide;
+    fadeOut?: AudioFadeSide;
+}
+/** A window, in seconds relative to the ducked clip's start, during which to attenuate. */
+export interface DuckWindow {
+    startSec: number;
+    endSec: number;
+}
+/** Backend envelope shape from duck-envelope.ts — times in ms, gain in dB. */
+export interface DuckEnvelopePoint {
+    tMs: number;
+    gainDb: number;
+}
+export interface GainSpec {
+    /** 0–1 clip volume from the item */
+    baseVolume: number;
+    muted?: boolean;
+    /** clip length on the timeline, in seconds */
+    clipDuration: number;
+    fade?: AudioFade;
+    /** Linear multiplier applied inside duck windows. 0.15 ~= -16 dB. */
+    duckTo?: number;
+    /** Clip-relative windows to duck under. */
+    duckWindows?: DuckWindow[];
+    /** Ramp length in/out of a duck window, seconds. */
+    duckFade?: number;
+}
+/** Matches MUSIC_DUCK_FADE_MS (150ms) in duck-envelope.ts. */
+export declare const DEFAULT_DUCK_FADE_SEC = 0.15;
+/**
+ * Matches the `duckTo` emitted by clhq-ai-video-cascade/editor-project-builder.
+ * Note the backend's MUSIC_DUCK_DB default of -8 dB is a *different*, shallower
+ * duck (~0.4 linear); `duckTo` on the item always wins when present.
+ */
+export declare const DEFAULT_DUCK_TO = 0.15;
+/**
+ * Default clip volume for a music bed.
+ *
+ * Agent-generated music has always arrived at 0.4–0.6 while user-inserted
+ * stock music defaulted to 1.0 — roughly 8 dB louder for the same job. Both
+ * paths now start from this value so a bed sounds the same however it got
+ * onto the timeline.
+ */
+export declare const MUSIC_BED_DEFAULT_VOLUME = 0.6;
+/** trackRole values that count as speech for the purposes of `duckDuring: 'voiceover'`. */
+export declare const VOICE_TRACK_ROLES: readonly ["voiceover", "narration", "dialogue"];
+export declare function dbToLinear(db: number): number;
+export declare function linearToDb(linear: number): number;
+/**
+ * Volume at `clipTime` seconds into the clip, applying fade-in / fade-out
+ * around `baseVolume`. Returns `baseVolume` when no fade is configured.
+ *
+ * Fades are linear in amplitude (matching the previous preview behaviour).
+ */
+export declare function fadeGainAt(clipTime: number, clipDuration: number, baseVolume: number, fade?: AudioFade): number;
+/**
+ * Duck multiplier (0–1) at `clipTime` seconds into the clip.
+ *
+ * Each window ramps 1 -> duckTo over `duckFade` seconds *before* the window
+ * opens, holds through it, then ramps back over `duckFade` seconds after it
+ * closes. Overlapping windows take the deepest (minimum) multiplier, so
+ * back-to-back narration lines do not let the bed swell in the gap.
+ */
+export declare function duckGainAt(clipTime: number, duckWindows?: DuckWindow[], duckTo?: number, duckFade?: number): number;
+/**
+ * Final gain (0–1) for a clip at `clipTime` seconds past its start.
+ *
+ * `clipTime` is measured from the start of the clip *on the timeline*, not
+ * from the start of the source file — trimming (frameStartAt) shifts which
+ * audio plays, not where the fade sits.
+ */
+export declare function gainAt(clipTime: number, spec: GainSpec): number;
+/** Minimal shape needed off a timeline item to decide whether it ducks others. */
+export interface DuckSourceItem {
+    type?: string;
+    trackRole?: string;
+    start?: number;
+    end?: number;
+    mute?: boolean;
+    muted?: boolean;
+    volume?: number;
+    uniqueId?: string;
+}
+/** Minimal shape of the clip being ducked. */
+export interface DuckTargetItem {
+    uniqueId?: string;
+    start?: number;
+    end?: number;
+    trackRole?: string;
+    duckTo?: number;
+    duckDuring?: string;
+}
+/**
+ * Convert the backend's dB envelope (duck-envelope.ts) into clip-relative
+ * windows. Any run of points at a negative gain becomes one window.
+ *
+ * Used when the agent has already computed `musicDuckEnvelope`; we prefer its
+ * voice timings over anything we re-derive from the timeline.
+ */
+export declare function duckWindowsFromEnvelope(points: DuckEnvelopePoint[], clipStartSec?: number): DuckWindow[];
+/**
+ * Derive duck windows for `target` from the other items on the timeline.
+ *
+ * Only runs when the target opts in via `duckDuring`. Today the only value
+ * the backend emits is `'voiceover'`, which matches any audible item whose
+ * trackRole is in VOICE_TRACK_ROLES.
+ *
+ * Returned windows are clip-relative seconds and merged so overlapping or
+ * near-touching speech becomes one sustained duck rather than a pumping bed.
+ */
+export declare function deriveDuckWindows(target: DuckTargetItem, allItems: DuckSourceItem[], options?: {
+    mergeGapSec?: number;
+}): DuckWindow[];
+/**
+ * Build the full GainSpec for an audio item given the rest of the timeline.
+ * Convenience wrapper so both players construct the spec identically.
+ */
+export declare function buildGainSpec(item: {
+    start?: number;
+    end?: number;
+    volume?: number;
+    mute?: boolean;
+    muted?: boolean;
+    uniqueId?: string;
+    trackRole?: string;
+    duckTo?: number;
+    duckDuring?: string;
+    transformation?: {
+        audioFade?: AudioFade;
+        musicDuckEnvelope?: DuckEnvelopePoint[];
+    };
+}, allItems: DuckSourceItem[]): GainSpec;

package/dist/utils/audio/useAudioRegistry.d.ts

@@ -0,0 +1,10 @@
+import { AudioRegistry } from './audioRegistry';
+/**
+ * Re-render when the registry's set of elements changes; returns its version.
+ *
+ * `useSyncExternalStore` re-reads the version after subscribing, so a change made between render
+ * and subscription is not lost. A plain `useEffect(() => registry.subscribe(bump))` misses it
+ * whenever a CHILD's effect (the AudioPlaybackManager creating the element) runs before the
+ * parent's subscription effect.
+ */
+export declare function useAudioRegistryVersion(registry: AudioRegistry): number;

package/dist/utils/blendMode.d.ts

@@ -0,0 +1,21 @@
+export declare const BLEND_NORMAL = 0;
+export declare const BLEND_ADD = 1;
+export declare const BLEND_MULTIPLY = 2;
+export declare const BLEND_SCREEN = 3;
+export type BlendStrategy = 'none' | 'native';
+/**
+ * Decide how a numeric PIXI blend mode should be realised in the render path.
+ *
+ * - `'none'`   → no filter, default normal blend (or unsupported code → safe degrade).
+ * - `'native'` → resolved to a PIXI v8 BLEND_MODES string and set directly.
+ */
+export declare const resolveBlendStrategy: (blendMode: number | undefined | null) => BlendStrategy;
+/** True if the renderer can realise this blend code (was: @pixi/picture set). */
+export declare const isPictureSupported: (blendMode: number) => boolean;
+export type PixiBlendModeString = 'normal' | 'add' | 'multiply' | 'screen' | 'overlay' | 'darken' | 'lighten' | 'color-dodge' | 'color-burn' | 'hard-light' | 'soft-light';
+/**
+ * Translate the editor's numeric blend-mode code (dropdown/state value) into
+ * the PIXI v8 string value expected by `DisplayObject.blendMode` / `Filter.blendMode`.
+ * Unknown/unsupported codes safely degrade to 'normal'.
+ */
+export declare const resolveBlendModeString: (blendMode: number | undefined | null) => PixiBlendModeString;

package/dist/utils/captions/captionClock.d.ts

@@ -0,0 +1,17 @@
+import { CaptionSegment } from './types';
+/**
+ * True when cue times are CLIP-LOCAL (0 = the caption item's own start) rather than on the
+ * master timeline. This is Clippy's rule, kept identical so both engines agree:
+ *
+ *  - no segments                      -> false
+ *  - no usable item end               -> clip-local iff the item starts after 0
+ *  - otherwise                        -> every cue fits inside the item duration (+0.5 s)
+ *
+ * Agent-built captions (viral shorts, polish) store clip-local times; editor auto-captions on
+ * an untrimmed full-length video store source-absolute times and compare to the playhead.
+ *
+ * (`timeBase.isClipLocal` differs in the no-end case: it returns false. Use this one to render.)
+ */
+export declare function usesClipLocalTime(segments: ReadonlyArray<Pick<CaptionSegment, "end">>, itemStartSec?: number, itemEndSec?: number): boolean;
+/** Master playhead -> the time the cues are expressed in. */
+export declare const captionTimeAt: (playheadSec: number, clipLocal: boolean, itemStartSec?: number) => number;