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

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

@@ -96,73 +96,73 @@ export declare const aepTransform3DSchema: z.ZodObject<{
         hold?: boolean | undefined;
     }>, "many">]>;
 }, "strict", z.ZodTypeAny, {
-    anchor: [number, number, number] | {
+    scale: [number, number] | {
         t: number;
-        v: [number, number, number];
+        v: [number, number];
         easeIn?: [number, number, number, number] | undefined;
         easeOut?: [number, number, number, number] | undefined;
         hold?: boolean | undefined;
     }[];
-    rotation: [number, number, number] | {
+    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;
     }[];
-    scale: [number, number] | {
+    anchor: [number, number, number] | {
         t: number;
-        v: [number, number];
+        v: [number, number, number];
         easeIn?: [number, number, number, number] | undefined;
         easeOut?: [number, number, number, number] | undefined;
         hold?: boolean | undefined;
     }[];
-    opacity: number | {
+    rotation: [number, number, number] | {
         t: number;
-        v: number;
+        v: [number, number, number];
         easeIn?: [number, number, number, number] | undefined;
         easeOut?: [number, number, number, number] | undefined;
         hold?: boolean | undefined;
     }[];
-    position: [number, number, number] | {
+    opacity: number | {
         t: number;
-        v: [number, number, number];
+        v: number;
         easeIn?: [number, number, number, number] | undefined;
         easeOut?: [number, number, number, number] | undefined;
         hold?: boolean | undefined;
     }[];
 }, {
-    anchor: [number, number, number] | {
+    scale: [number, number] | {
         t: number;
-        v: [number, number, number];
+        v: [number, number];
         easeIn?: [number, number, number, number] | undefined;
         easeOut?: [number, number, number, number] | undefined;
         hold?: boolean | undefined;
     }[];
-    rotation: [number, number, number] | {
+    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;
     }[];
-    scale: [number, number] | {
+    anchor: [number, number, number] | {
         t: number;
-        v: [number, number];
+        v: [number, number, number];
         easeIn?: [number, number, number, number] | undefined;
         easeOut?: [number, number, number, number] | undefined;
         hold?: boolean | undefined;
     }[];
-    opacity: number | {
+    rotation: [number, number, number] | {
         t: number;
-        v: number;
+        v: [number, number, number];
         easeIn?: [number, number, number, number] | undefined;
         easeOut?: [number, number, number, number] | undefined;
         hold?: boolean | undefined;
     }[];
-    position: [number, number, number] | {
+    opacity: number | {
         t: number;
-        v: [number, number, number];
+        v: number;
         easeIn?: [number, number, number, number] | undefined;
         easeOut?: [number, number, number, number] | undefined;
         hold?: boolean | undefined;

package/dist/types/index.d.ts

@@ -4,4 +4,5 @@ export * from './BlendModes';
 export * from './OverlayTypes';
 export * from './transformation';
 export * from './MaskTypes';
+export * from './CropTypes';
 export * from './aep';

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/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;

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

@@ -0,0 +1,57 @@
+import { CaptionRenderMode } from './captionPose';
+/** The words to draw, and the index of `words[0]` of that list within the full segment. */
+export declare function displayedWordsFor<T>(mode: CaptionRenderMode, words: ReadonlyArray<T>, activeIndex: number): {
+    words: T[];
+    offset: number;
+};
+export interface ParsedColor {
+    /** 0xRRGGBB */
+    color: number;
+    /** 0..1 */
+    alpha: number;
+}
+/**
+ * Parse `#rgb`, `#rrggbb`, `#rrggbbaa`, `rgb()`, `rgba()` (comma or space separated, % alpha) and
+ * `transparent`. Returns null for anything else (named colours: let the caller fall back to Pixi).
+ *
+ * Fix vs Clippy: its boxed-caption background only understood `rgba(...)` strings; a hex or
+ * `rgb()` background was silently ignored and the default black box drawn instead.
+ */
+export declare function parseCaptionColor(input: string | null | undefined): ParsedColor | null;
+export interface BoxedBackground {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    radius: number;
+    color: number;
+    alpha: number;
+}
+export declare const BOXED_PADDING = 12;
+export declare const DEFAULT_BOXED_COLOR: ParsedColor;
+/** Corner radius per boxed preset. */
+export declare const boxedRadiusFor: (captionStyleId: string | null | undefined) => number;
+/**
+ * The rounded box behind the whole caption in `boxed` mode, in coordinates relative to the
+ * caption centre. `captionBgColor` unset / `transparent` / unparseable falls back to the
+ * default 75% black (Clippy's behaviour).
+ */
+export declare function boxedBackgroundSpec(contentWidth: number, contentHeight: number, captionBgColor: string | null | undefined, captionStyleId: string | null | undefined): BoxedBackground;
+export interface WordboxPill {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    radius: number;
+}
+export declare const WORDBOX_GROW_MS = 120;
+/**
+ * The rounded pill behind the active word in `wordbox` mode: grows from the word's centre over
+ * 120 ms (ease-out-cubic). Relative to the caption centre.
+ */
+export declare function wordboxPillSpec(pos: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, totalWidth: number, totalHeight: number, elapsedMs: number, fontSize: number): WordboxPill;