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

package/dist/utils/gsapEffects/backEffects.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/gsapEffects/bounceEffects.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/gsapEffects/effectGenerator.d.ts

@@ -0,0 +1,3 @@
+export declare function createEffectFromConfig(name: any): void;
+export declare function registerEffectsFromConfig(names: any): void;
+export declare function registerAllStandardEffects(): void;

package/dist/utils/gsapEffects/effectTarget.d.ts

@@ -0,0 +1,11 @@
+import * as PIXI from 'pixi.js';
+/**
+ * GSAP hands a registered effect its targets as an ARRAY — it runs
+ * gsap.utils.toArray() on whatever was passed to gsap.effects.NAME(...).
+ *
+ * Tween-only effects never notice, since gsap.to/from/set all accept arrays.
+ * Effects that touch the scene graph (addChild, getLocalBounds, mask) must
+ * unwrap first, or they fail on the Array — loudly with "addChild is not a
+ * function", or silently via `array.children ?? []` reading as empty.
+ */
+export declare function resolveEffectNode(target: PIXI.Container | PIXI.Container[]): PIXI.Container | null;

package/dist/utils/gsapEffects/fadeEffects.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/gsapEffects/flipEffects.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/gsapEffects/generalEffects.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/gsapEffects/lightSpeedEffect.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/gsapEffects/logoRevealEffects.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/gsapEffects/registerEffects.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/gsapEffects/riseEffect.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/gsapEffects/rollEffects.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/gsapEffects/rotateEffects.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/gsapEffects/slideEffects.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/gsapEffects/staggerTextEffects.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/gsapEffects/textUnitEffects.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/gsapEffects/textUnitMask.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/gsapEffects/textUnits.d.ts

@@ -0,0 +1,172 @@
+import * as PIXI from 'pixi.js';
+/** Normalised anchor, 0–1. `0,0` is top-left, `1,1` bottom-right. */
+export type UnitAnchor = number | {
+    x: number;
+    y: number;
+};
+export type TextEffectVars = {
+    duration?: number;
+    ease?: string;
+    immediateRender?: boolean;
+    overwrite?: boolean | 'auto';
+    x?: number;
+    y?: number;
+    alpha?: number;
+    scaleX?: number;
+    scaleY?: number;
+    revealUnit?: 'letter' | 'word';
+    /** Seconds between each unit's start. Maps to gsap's stagger `each`. */
+    stagger?: number;
+    /** Where the stagger emanates from: start | center | edges | random | end. */
+    staggerFrom?: 'start' | 'center' | 'edges' | 'random' | 'end';
+    /** Ease that distributes the start times (not the per-unit ease). */
+    staggerEase?: string;
+    /** Vertical travel for fade-y (px). */
+    yOffset?: number;
+};
+/**
+ * Transform origins for the split, passed straight to SplitText.
+ *
+ * These are the ONLY correct way to set a unit's transform origin — `pivot`
+ * relocates the unit as well as re-centring it, which displaces it from the
+ * laid-out position captured in `baseX`/`baseY`.
+ */
+export type UnitAnchors = {
+    charAnchor?: UnitAnchor;
+    wordAnchor?: UnitAnchor;
+    lineAnchor?: UnitAnchor;
+};
+export type TextUnits = {
+    /** The effect's container — already normalised from GSAP's target array. */
+    node: PIXI.Container;
+    /** Words or chars, in reading order. */
+    units: PIXI.Container[];
+    /** Resting x of a unit, captured before any tween moved it. */
+    baseX: (unit: PIXI.Container) => number;
+    /** Resting y of a unit, captured before any tween moved it. */
+    baseY: (unit: PIXI.Container) => number;
+    /** Source text's font size, for deriving travel distances that scale. */
+    fontSize: number;
+};
+/** Depth-first search for the element's text node. */
+export declare function findTextNode(root: PIXI.Container): PIXI.Text | null;
+/** Normalise GSAP's target (always an array) to a Container, or null. */
+export declare function resolveTextTarget(target: PIXI.Container | PIXI.Container[], label: string): PIXI.Container | null;
+/**
+ * Lock the container to its authored transform before the units animate.
+ * Per-unit effects move the units, never the container, so it must sit at its
+ * resting state for the whole reveal.
+ */
+export declare function applyContainerBaseState(node: PIXI.Container, vars: TextEffectVars): void;
+/**
+ * Cached split + resting positions, or null when the target has no PIXI.Text.
+ *
+ * A null return is a normal case, not an error: it is reached from project JSON
+ * and when an element's type changes under a saved animation. Callers should
+ * fall back to `containerFadeEffect`.
+ */
+export declare function resolveTextUnits(node: PIXI.Container, revealUnit: 'letter' | 'word', anchors?: UnitAnchors): TextUnits | null;
+/**
+ * Turn the authored `stagger` into GSAP's config.
+ *
+ * `amount` is the total time spread across all units, so the LAST unit still
+ * lands on `duration` — the documented way to express what these effects used to
+ * hand-roll by offsetting N separate tweens. `each` would instead make the total
+ * grow with the word count, so a long title would overrun its own animation.
+ */
+export declare function resolveStagger(vars: TextEffectVars, unitCount: number, duration: number): {
+    amount: number;
+    unitDuration: number;
+};
+/**
+ * The `stagger` object shared by every per-unit effect.
+ *
+ * `defaultFrom` lets an effect (e.g. TEXT_SPOTLIGHT → 'center') pick its own
+ * look when the user hasn't overridden it. Do NOT implement that by spreading
+ * `{ staggerFrom: defaultFrom, ...vars }` at the call site — `vars` always
+ * carries an explicit `staggerFrom` key (usePixiAnimation's `animInExtra` sets
+ * it even when the author never set one, so its value is `undefined`), and
+ * object spread copies that key regardless of value, silently clobbering the
+ * default. This shipped once already: every TEXT_* effect defaulted to
+ * 'start' instead of its intended origin until this comment was added.
+ */
+export declare function staggerConfig(vars: TextEffectVars, amount: number, defaultFrom?: NonNullable<TextEffectVars['staggerFrom']>): {
+    ease?: string | undefined;
+    amount: number;
+    from: NonNullable<"start" | "center" | "edges" | "random" | "end" | undefined>;
+};
+export declare function ensureUnitMask(unit: PIXI.Container, signature: string): PIXI.Graphics | null;
+/**
+ * Public record of each per-unit effect's own defaults, keyed by name.
+ *
+ * Exists so `src/components/edit-menu/constants.ts` (`TEXT_ANIMATION_DEFAULT_FROM`)
+ * can be cross-checked against the real values rather than drifting silently —
+ * see `textUnitEffectsBehavior.test.ts`. Pure data; importing it does not
+ * invoke PIXI or run any effect.
+ */
+export declare const TEXT_UNIT_EFFECT_DEFAULTS: Readonly<Record<string, {
+    from: NonNullable<TextEffectVars['staggerFrom']>;
+    unit: 'letter' | 'word';
+}>>;
+export type UnitEffectContext = {
+    baseX: (unit: PIXI.Container) => number;
+    baseY: (unit: PIXI.Container) => number;
+    /**
+     * Resting box height per unit. Measured once per effect run and ONLY when
+     * the effect is masked — unmasked effects never pay for getLocalBounds.
+     * Falls back to fontSize (design-space units, NFR4).
+     */
+    unitH: (unit: PIXI.Container) => number;
+    /** Source text's font size, for deriving travel distances that scale. */
+    fontSize: number;
+};
+export type UnitEffectSpec = {
+    /** GSAP effect name / ANIMATION id. */
+    name: string;
+    /** Default per-unit ease. */
+    ease: string;
+    /** Default stagger origin for this look. */
+    from?: TextEffectVars['staggerFrom'];
+    /** Default split granularity. `revealUnit` in the project JSON overrides it. */
+    unit?: 'letter' | 'word';
+    /** Transform origins — applied to the split, never as pivot. */
+    anchors?: UnitAnchors;
+    /**
+     * Clip every unit to its own resting box (FR8 masked reveals). The unit
+     * still animates through the same single fromTo — the mask only adds the
+     * hard edge, and pads past it so the resting frame is unclipped.
+     */
+    masked?: boolean;
+    /** Per-unit start state. */
+    from_: (ctx: UnitEffectContext) => gsap.TweenVars;
+    /** Per-unit end state. Must land every unit exactly on its resting position. */
+    to: (ctx: UnitEffectContext) => gsap.TweenVars;
+};
+/**
+ * The single registration path for every SplitText per-unit effect (phase 2
+ * catalogue in `textUnitEffects.ts`, masked FR8 catalogue in
+ * `textUnitMask.ts`). One `gsap.fromTo` over the split units with a native
+ * `stagger` config; splitting, caching, resting-position capture and stagger
+ * maths all live above in this module.
+ *
+ * Three rules shape every effect registered here:
+ *
+ * - Positions are ABSOLUTE. A recipe's `y: 50` means "50px from where it
+ *   sits"; on a Pixi unit the same literal means "y = 50 in parent space",
+ *   which stacks every word in one spot. Always tween relative to baseX/baseY.
+ * - Transform origin comes from `charAnchor`/`wordAnchor`, never `pivot` —
+ *   `pivot` relocates the unit away from its captured resting position.
+ * - Randomness must be DETERMINISTIC per unit. usePixiAnimation rebuilds the
+ *   timeline every frame, so `gsap.utils.random()` would re-roll ~30x a
+ *   second and the text would jitter instead of animating.
+ */
+export declare function registerTextUnitEffect(spec: UnitEffectSpec): void;
+/**
+ * Whole-element fade — the non-text form.
+ *
+ * A sprite has no sub-units to stagger, so this is a fade (plus an optional
+ * rise) over the container itself. It backs the generic STAGGER_FADE family for
+ * images, video and shapes, and is the safety net whenever a text effect is
+ * pointed at something with no PIXI.Text inside.
+ */
+export declare function containerFadeEffect(node: PIXI.Container, vars: TextEffectVars, withYOffset: boolean, defaultEase: string): gsap.core.Tween;

package/dist/utils/gsapEffects/typewriterEffect.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/gsapEffects/wipeEffect.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/gsapEffects/zoomEffects.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/index.d.ts

@@ -4,3 +4,28 @@ export { areSpritePropsEqual, SPRITE_REF_PROP_NAMES, } from './areSpritePropsEqu
 export { resolveTextRuns, resolveTextRunsWithWarnings, } from './text/resolveTextRuns';
 export { layoutText, createCanvasMetricsProvider, MetricsCache, metricsCacheKey, splitGraphemes, isWhitespaceChar, type AepTextAlign as AepTextLayoutAlign, type AepGlyphMetrics, type AepTextLayoutGlyph, type AepTextLayoutInput, type AepTextLayoutLine, type AepTextLayoutResult, type AepTextLayoutRun, type AepTextMetricsProvider, } from './textLayout';
 export { loadMsdfAtlas, hydrateMsdfAtlas, MSDF_VERTEX_SHADER, MSDF_FRAGMENT_SHADER, computeInstanceMatrix, writeInstanceColor, hexToRgba, type MsdfAtlas, type MsdfAtlasJson, type MsdfGlyph, type AnimatorOffset as MsdfAnimatorOffset, } from './msdf';
+export * from './captions';
+export { applyEntranceOverlaps } from './entranceOverlap';
+export { ANIMATION, ANIMATION_TIMING, CANVAS_DEFAULTS, ANIMATIONS_WITHOUT_ALPHA, SPECIAL_ANIMATIONS, LOOP_ANIMATIONS, isLoopAnimation, camelToUpperSnake, normalizeAnimation, normalizeLoopAnimation, animationAffectsAlpha, isSpecialAnimation, isValidAnimation, } from '../constants/animation';
+export { ANIMATION_CONFIGS } from './gsapEffects/animationConfigs';
+export { useAllVideosReady, registerVideo, markVideoReady, unregisterVideo, resetVideoReadiness, } from './videoReadiness';
+export { acquireVideoAsset, releaseVideoAsset } from './videoAssetCache';
+export { getElementName, getUniqueIdFromName, findByName, findAllByPattern, createPixiSelector, type PixiSelector, } from './PixiSelector';
+export { mapV7DropShadow, mapV7Stroke, buildV8FillGradient, normalizeFontWeight, normalizeLetterSpacing, } from './textStyleV8';
+export { PIXITEXT_HITAREA_PREFIX, PIXITEXT_TEXT_LABEL, getPixiTextHitAreaName, } from '../constants/elementNames';
+export { useBlendFilter } from '../hooks/useBlendFilter';
+export { resolveBlendModeString, resolveBlendStrategy } from './blendMode';
+export { sanitizeImageSrc } from './sanitizeImageSrc';
+export { loadSpriteTextureSync, type SpriteTextureHandle, } from './loadSpriteTexture';
+export { createAssetRefCounter, type AssetRefCounter } from './assetRefCount';
+export { gifFrameAt, type GifFrameTiming } from './gifTiming';
+export { buildRasterSvg, rewriteSvg, readOriginalSize, detectOutlineIcon, isSvgSource, } from './svgRaster';
+export { loadGoogleFonts, getLoadedFonts, FONT_LOAD_TIMEOUT_MS, type FontsLoadedDetail, } from './fonts/fontLoader';
+export { fontFamilyKey, formatGoogleFamily, fontWeightsOf, isFontSpecCovered, googleFontsHref, } from './fonts/fontSpec';
+export { GOOGLE_FONTS, ALL_GOOGLE_FONTS, PRELOAD_FONTS } from './fonts/googleFonts';
+export { sanitizeCanvasText, CANVAS_TEXT_MAX_LENGTH } from './sanitizeCanvasText';
+export { buildTextStyleOptions, type TextStyleInput } from './textStyle';
+export { gainAt, fadeGainAt, duckGainAt, buildGainSpec, deriveDuckWindows, duckWindowsFromEnvelope, dbToLinear, linearToDb, DEFAULT_DUCK_TO, DEFAULT_DUCK_FADE_SEC, MUSIC_BED_DEFAULT_VOLUME, VOICE_TRACK_ROLES, type AudioFade, type AudioFadeSide, type DuckWindow, type GainSpec, } from './audio/gainEnvelope';
+export { decideAudioSync, applyAudioDecision, clipFileTime, clipVolumeAt, DRIFT_TOLERANCE_SEC, type AudioClipSpec, type SyncDecision, } from './audio/audioSync';
+export { audioRegistry, createAudioRegistry, type AudioRegistry, } from './audio/audioRegistry';
+export * from './threeModel';

package/dist/utils/loadSpriteTexture.d.ts

@@ -1,10 +1,39 @@
-import * as PIXI from 'pixi.js';
+import * as PIXI from "pixi.js";
 export interface LoadSpriteTextureOptions {
-    scaleMode?: 'linear' | 'nearest';
+    scaleMode?: "linear" | "nearest";
     enableMipmap?: boolean;
+    /**
+     * Force Pixi's texture loader. Default true.
+     *
+     * Extensionless image URLs (Unsplash/imgix: `/photo-xxx?fm=jpg&w=1080`) give Pixi's
+     * resolver nothing to infer a loader from, so `Assets.load(url)` silently never resolves
+     * and the canvas stays blank. Pass `false` for GIF/video/SVG URLs that must go through
+     * their own parser.
+     */
+    forceTextureParser?: boolean;
 }
-export declare function loadSpriteTexture(src: string, opts?: LoadSpriteTextureOptions): Promise<{
+export interface SpriteTextureHandle {
     promise: Promise<PIXI.Texture | null>;
+    /** Stop caring about the result (resolves the promise with null if still pending). */
     cancel: () => void;
+    /**
+     * Release this handle's use of the texture. The texture belongs to `PIXI.Assets` (every URL,
+     * relative or absolute, is cached there), so it is never `destroy`ed: `Assets.unload` runs
+     * once no sprite has used the URL for a grace period.
+     */
     dispose: () => void;
-}>;
+}
+/**
+ * Load a texture and return a handle SYNCHRONOUSLY.
+ *
+ * The old version was `async` and returned `Promise<handle>`, so a component that unmounted
+ * before that promise settled ran its cleanup with no handle to cancel: the load completed
+ * later and called `setTexture` on an unmounted component. Returning the handle directly
+ * removes the race. `loadSpriteTexture(src).then(handle => ...)` still works (see below).
+ */
+export declare function loadSpriteTextureSync(rawSrc: string, opts?: LoadSpriteTextureOptions): SpriteTextureHandle;
+/**
+ * Backward-compatible wrapper: resolves to the same handle. Prefer
+ * `loadSpriteTextureSync`, which has no cancel race.
+ */
+export declare function loadSpriteTexture(src: string, opts?: LoadSpriteTextureOptions): Promise<SpriteTextureHandle>;

package/dist/utils/sanitizeCanvasText.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Sanitize plain text for in-canvas title / TipTap editing.
+ *
+ * Guards against paste of HTML, control chars, zero-width/bidi tricks,
+ * and unbounded length that would blow up Pixi Text layout or project JSON.
+ */
+/** Soft cap for a single title element — enough for multi-line copy, not novels. */
+export declare const CANVAS_TEXT_MAX_LENGTH = 2000;
+/**
+ * Normalize and harden plain text before it hits TipTap / Pixi / editor store.
+ */
+export declare const sanitizeCanvasText: (input: unknown, maxLen?: number) => string;

package/dist/utils/sanitizeImageSrc.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Repairs a `data:` URI that had a CDN origin wrongly prepended, e.g.
+ *   https://x.cloudfront.net/data:image/png;base64,AAAA?Expires=...  ->  data:image/png;base64,AAAA
+ * and drops the signed-URL query params appended after the payload. Anything else is
+ * returned unchanged. Ported from the Clippy editor.
+ */
+export declare function sanitizeImageSrc(src: string | undefined | null): string | undefined | null;

package/dist/utils/svgRaster.d.ts

@@ -0,0 +1,47 @@
+export declare const BASE_STROKE_WIDTH_SVG = 2;
+/** Longest side of the SVG's own coordinate system (viewBox, else width/height, else 512). */
+export declare const readOriginalSize: (svgEl: Element) => number;
+/** Outline (stroke-based) icons need `meet` scaling and stroke handling; filled ones stretch. */
+export declare const detectOutlineIcon: (svgEl: Element) => boolean;
+export declare const computeStrokeWidth: ({ shouldApply, strokeWidth, resolution, renderWidth, renderHeight, originalSize, isOutline, }: {
+    shouldApply: boolean;
+    strokeWidth: number;
+    resolution: number;
+    renderWidth: number;
+    renderHeight: number;
+    originalSize: number;
+    isOutline: boolean;
+}) => number;
+export declare const applyStrokeToShapes: (svgEl: Element, stroke: string, strokeWidth: number) => void;
+export declare const scaleExistingStrokes: (svgEl: Element, scale: number, minStroke: number, resolution: number, originalSize: number, renderSize: number) => void;
+export interface BuildRasterSvgOptions {
+    /** Target size in CSS px (before `resolution`). Falls back to the SVG's own size. */
+    width?: number;
+    height?: number;
+    resolution: number;
+    stroke?: string;
+    strokeWidth?: number;
+}
+/**
+ * Re-write an SVG so that drawing it onto a `width*res x height*res` canvas is crisp and
+ * its strokes scale sensibly. Returns the serialized SVG. Non-SVG documents are returned as is.
+ */
+export declare function buildRasterSvg(svgText: string, opts: BuildRasterSvgOptions): string;
+export interface RewriteSvgOptions {
+    width: number;
+    height: number;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+}
+/**
+ * Size an SVG for baking through `Graphics.svg()` and optionally override fill/stroke on the
+ * root element (paths that inherit pick it up; per-path fills and gradients are left alone).
+ *
+ * Fix vs Clippy: it forced `viewBox="0 0 w h"`, discarding the artwork's real viewBox and
+ * distorting non-square art. The original viewBox is kept; one is only synthesised when the
+ * document has none.
+ */
+export declare function rewriteSvg(svgText: string, opts: RewriteSvgOptions): string;
+/** True for `.svg` URLs and inline `data:image/svg+xml` sources. */
+export declare const isSvgSource: (src: string) => boolean;

package/dist/utils/textLayout/index.d.ts

@@ -1,5 +1,5 @@
 export type { AepTextAlign, AepGlyphMetrics, AepTextLayoutGlyph, AepTextLayoutInput, AepTextLayoutLine, AepTextLayoutResult, AepTextLayoutRun, AepTextMetricsProvider, } from './types';
-export { layoutText } from './layoutText';
+export { layoutText, resetDefaultTextMetrics } from './layoutText';
 export { createCanvasMetricsProvider, type CanvasMetricsProviderOptions, } from './canvasMetricsProvider';
 export { createPixiCanvasMetricsProvider, type PixiCanvasMetricsProviderOptions, } from './pixiCanvasMetricsProvider';
 export { createTypefaceMetricsProvider, type ThreeTypefaceJson, } from './typefaceMetricsProvider';

package/dist/utils/textLayout/layoutText.d.ts

@@ -1,2 +1,7 @@
 import { AepTextLayoutInput, AepTextLayoutResult } from './types';
+/**
+ * Drop the default provider and its glyph-metrics cache. Call after webfonts finish loading:
+ * glyphs measured against the fallback font are otherwise cached and stay wrong.
+ */
+export declare function resetDefaultTextMetrics(): void;
 export declare function layoutText(input: AepTextLayoutInput): AepTextLayoutResult;

package/dist/utils/textStyle.d.ts

@@ -0,0 +1,81 @@
+import type * as PIXI from "pixi.js";
+/** Everything the flat text sprite reads from `transformation` that shapes the TextStyle. */
+export interface TextStyleInput {
+    fontFamily?: string;
+    fontSize?: number;
+    fontWeight?: string | number;
+    fontStyle?: string;
+    /** `"small-caps"`, or (legacy) a boolean. */
+    fontVariant?: string | boolean;
+    fill?: string | number;
+    /** Two or more colours -> a linear FillGradient (overrides `fill`). */
+    gradientColors?: (string | number)[];
+    gradientStops?: number[];
+    /** 0 = vertical (default), 1 = horizontal. */
+    gradientType?: 0 | 1;
+    stroke?: string | number | object | null;
+    /** v8 name. */
+    strokeWidth?: number;
+    /** v7 name; both are accepted. */
+    strokeThickness?: number;
+    dropShadow?: boolean | object;
+    dropShadowColor?: string | number | null;
+    dropShadowBlur?: number;
+    dropShadowAlpha?: number;
+    /** Radians. */
+    dropShadowAngle?: number;
+    dropShadowDistance?: number;
+    /** Soft-glow preset: a zero-offset shadow of `blurRadius`. Wins over `dropShadow`. */
+    blurEnabled?: boolean;
+    blurRadius?: number;
+    align?: string;
+    padding?: number;
+    letterSpacing?: number | string;
+    leading?: number;
+    /**
+     * Wrap width in px. When unset the text does NOT wrap (a very large width), which is the
+     * sprite's long-standing default; set it (or call `setWordWrap`) to wrap.
+     */
+    wordWrapWidth?: number;
+    /** Pixi v8.16+ tagged text. */
+    tagStyles?: Record<string, Partial<PIXI.TextStyleOptions>>;
+}
+export declare const NO_WRAP_WIDTH = 50000000;
+/**
+ * Build Pixi v8 `TextStyleOptions` from the sprite's transformation fields. Pure (the only Pixi
+ * thing it may construct is a FillGradient), so it is unit-testable.
+ *
+ * Fixes over the previous inline builder:
+ *  - font weights 400-900 were silently dropped (only bold/bolder/lighter/100-300 passed)
+ *  - stroke/shadow went through the v7 flat props, which Pixi converts with a deprecation
+ *    warning on every `new TextStyle`; v8 objects are emitted directly
+ *  - a numeric black stroke (0x000000) was treated as "no stroke"
+ *  - shadow alpha/angle/distance were hard-coded (alpha ignored, angle 30deg, distance 5)
+ *  - negative letterSpacing was dropped
+ *  - `fontVariant` was passed as a boolean
+ *  - `align` and `padding` were never applied
+ *  - gradient fills and `'transparent'` fills were unsupported
+ */
+export declare function buildTextStyleOptions(input: TextStyleInput): PIXI.TextStyleOptions;
+/**
+ * Where a background box sits so it hugs text of size `textW x textH` placed with `anchor` at
+ * (x, y), padded by `pad` on every side. Returns the box size and its position for a sprite
+ * that uses the SAME anchor as the text.
+ */
+export declare function hugBox(x: number, y: number, anchor: {
+    x: number;
+    y: number;
+}, textW: number, textH: number, pad: number): {
+    width: number;
+    height: number;
+    x: number;
+    y: number;
+};
+/** Normalise the scalar-or-point anchor. */
+export declare const toAnchorPoint: (a: number | {
+    x: number;
+    y: number;
+} | undefined) => {
+    x: number;
+    y: number;
+};

package/dist/utils/textStyleV8.d.ts

@@ -0,0 +1,62 @@
+import * as PIXI from "pixi.js";
+/**
+ * Pixi v8 TextStyle helpers. v7 accepted flat `dropShadow*` / `strokeThickness`
+ * props; v8 expects `dropShadow: {…}`, `stroke: {color, width}` and a
+ * `FillGradient`. Pixi 8.18 still converts the flat v7 props in the constructor,
+ * but logs a deprecation warning on every `new TextStyle` — these helpers emit
+ * the v8 shapes directly. Ported from the Clippy editor, with fixes noted below.
+ */
+export interface V7DropShadowFields {
+    dropShadow?: boolean | object;
+    dropShadowColor?: string | number;
+    dropShadowBlur?: number;
+    dropShadowAlpha?: number;
+    dropShadowAngle?: number;
+    dropShadowDistance?: number;
+}
+export type V8DropShadowPatch = {
+    dropShadow?: {
+        color: string | number;
+        alpha: number;
+        angle: number;
+        blur: number;
+        distance: number;
+    };
+};
+export declare const mapV7DropShadow: (s: V7DropShadowFields) => V8DropShadowPatch;
+export interface V7StrokeFields {
+    stroke?: string | number | object | null;
+    strokeThickness?: number;
+}
+/**
+ * Pack v7 `stroke` (colour) + `strokeThickness` (width) into the v8 object.
+ *
+ * Fix vs Clippy: a numeric black stroke (`0x000000`) is a valid colour but falsy,
+ * so test for null/undefined rather than truthiness.
+ */
+export declare const mapV7Stroke: (s: V7StrokeFields) => {
+    stroke?: object;
+};
+export interface V7GradientFields {
+    fillGradientStops?: number[];
+    fillGradientType?: 0 | 1;
+}
+/**
+ * Build a v8 `FillGradient` from colours + stops. `type` 0 = vertical, 1 = horizontal.
+ * Returns undefined when fewer than two colours are given.
+ *
+ * Fix vs Clippy: uses the options form (`{type, start, end, textureSpace, colorStops}`);
+ * the positional `new FillGradient(x0, y0, x1, y1)` is deprecated since Pixi 8.5.2.
+ */
+export declare const buildV8FillGradient: (colorsHex: (string | number)[] | null | undefined, stops: number[] | undefined, type: 0 | 1 | undefined) => PIXI.FillGradient | undefined;
+/**
+ * Normalise a CSS font weight. Accepts the named weights and 100..900 as a number
+ * or numeric string. Returns undefined for anything else, so the caller can leave
+ * the TextStyle default alone.
+ *
+ * Fix: the previous flat sprite only let `bold|bolder|lighter|100|200|300` through,
+ * silently dropping 400-900 (so Montserrat 800 rendered at 400).
+ */
+export declare const normalizeFontWeight: (weight: string | number | null | undefined) => PIXI.TextStyleFontWeight | undefined;
+/** Letter spacing: any finite number, including negative (tight tracking). 0/invalid -> undefined. */
+export declare const normalizeLetterSpacing: (value: number | string | null | undefined) => number | undefined;

package/dist/utils/threeModel.d.ts

@@ -0,0 +1,55 @@
+import * as THREE from "three";
+export interface ThreeDParams {
+    positionX?: number;
+    positionY?: number;
+    positionZ?: number;
+    rotationX?: number;
+    rotationY?: number;
+    rotationZ?: number;
+    /** Continuous Y spin in rad/s, added on top of rotationY. Default 0.5. */
+    spinSpeed?: number;
+    scale?: number;
+    flipX?: 1 | -1;
+    flipY?: 1 | -1;
+    materialColor?: string;
+    roughness?: number;
+    metalness?: number;
+    emissiveIntensity?: number;
+    ambientIntensity?: number;
+    directionalIntensity?: number;
+    fillIntensity?: number;
+    clipIndex?: number;
+    playbackSpeed?: number;
+}
+export interface ModelPose {
+    position: [number, number, number];
+    rotation: [number, number, number];
+    scale: [number, number, number];
+}
+export declare const THREE_DEFAULTS: {
+    readonly ambientIntensity: 0.6;
+    readonly directionalIntensity: 1.2;
+    readonly fillIntensity: 0.8;
+    readonly spinSpeed: 0.5;
+    readonly playbackSpeed: 1;
+};
+/** Pure pose at local clip time `t` (seconds). Same input -> same output, so scrub/export are stable. */
+export declare function computeModelPose(td: ThreeDParams, t: number): ModelPose;
+/** Animation clock position for clip playback: speed-scaled, looped. */
+export declare function clipTimeAt(t: number, duration: number, speed?: number, loop?: boolean): number;
+export type MaterialOverrides = Pick<ThreeDParams, "materialColor" | "roughness" | "metalness" | "emissiveIntensity">;
+export declare function hasMaterialOverrides(o: MaterialOverrides): boolean;
+export declare function applyMaterialOverrides(root: THREE.Object3D, o: MaterialOverrides): void;
+/** Stable key so overrides are re-applied only when they actually change. */
+export declare function materialOverrideKey(o: MaterialOverrides): string;
+/** Camera distance so a bounding box of `maxDim` fits the vertical FOV (degrees), with margin. */
+export declare function fitDistance(maxDim: number, fovDeg: number, margin?: number): number;
+export declare function fitCameraToObject(camera: THREE.PerspectiveCamera, root: THREE.Object3D, margin?: number): void;
+/**
+ * GLTFLoader resolves relative texture/buffer paths against the model's own directory. For hosts
+ * (e.g. Poly Haven) whose CDN layout doesn't mirror those paths, `resources` maps each relative
+ * path to its real absolute URL. Returns a URL modifier for THREE.LoadingManager, or undefined.
+ */
+export declare function buildResourceUrlModifier(modelSrc: string, resources?: Record<string, string>): ((url: string) => string) | undefined;
+/** Recursively dispose geometries, materials and their textures. */
+export declare function disposeObject(root: THREE.Object3D): void;

package/dist/utils/videoAssetCache.d.ts

@@ -0,0 +1,4 @@
+/** Mark the URL in use; cancels a pending unload so a remount keeps the texture. */
+export declare const acquireVideoAsset: (key: string) => void;
+/** Release one use; the texture is unloaded after the grace period if still unused. */
+export declare const releaseVideoAsset: (key: string) => void;

package/dist/utils/videoReadiness.d.ts

@@ -0,0 +1,13 @@
+/** Failsafe: never block the play button longer than 5s on a hung load. */
+export declare const VIDEO_READY_TIMEOUT_MS = 5000;
+/**
+ * Register a video sprite as pending. Always re-pends on (re)mount so a remount
+ * after an earlier markVideoReady still waits for a fresh load signal.
+ */
+export declare function registerVideo(uniqueId: string): void;
+export declare function markVideoReady(uniqueId: string): void;
+export declare function unregisterVideo(uniqueId: string): void;
+/** Clear all readiness state (project switch / editor reset). */
+export declare function resetVideoReadiness(): void;
+/** true when no registered video is still loading. */
+export declare function useAllVideosReady(): boolean;