@motion.page/sdk 1.1.3 → 1.2.0

package/dist/registries/SDKRegistry.d.ts

@@ -63,6 +63,15 @@ interface TextFlapperFunctions {
     flap: (charElements: HTMLElement[], config: FlapConfig, staggerDelays?: number[], continuous?: boolean) => FlapController;
     revert: (charElements: HTMLElement[]) => void;
 }
+/**
+ * Factory slot for the optional reactive responsive runtime. The
+ * ResponsiveManager module self-registers `create` here when loaded, so
+ * core/Motion can instantiate a manager without a static import — keeping the
+ * module tree-shaken out of bundles that have no responsive timelines.
+ */
+interface ResponsiveFactory {
+    create: () => import('../responsive/ResponsiveManager').ResponsiveManager;
+}
 /**
  * Unified registry for all optional SDK features.
  * Each slot is null until the corresponding module loads and self-registers.
@@ -82,5 +91,6 @@ export declare const SDKRegistry: {
     } | null;
     styleReset: StyleResetFunctions | null;
     fit: FitResolverFunctions | null;
+    responsive: ResponsiveFactory | null;
 };
 export {};

package/dist/responsive/ResponsiveManager.d.ts

@@ -0,0 +1,86 @@
+/**
+ * ResponsiveManager (Responsive Editing — Stage 2, reactive SDK runtime)
+ *
+ * Registers a set of per-breakpoint timeline variants and live-swaps between
+ * them as the viewport crosses a breakpoint boundary. This upgrades the Stage 1
+ * compile-time output (N mutually-exclusive `if(matchMedia(...).matches)` blocks
+ * evaluated once at load) to a single `Motion.responsive(...)` call whose active
+ * variant follows the viewport in real time.
+ *
+ * The breakpoint queries are byte-for-byte the SAME strict, non-overlapping
+ * mutual-exclusion ranges used by Stage 1 `buildResponsiveBlocks` (RD-2):
+ *
+ *   desktop  screen and (min-width: L+1)
+ *   laptop   screen and (min-width: T+1) and (max-width: L)
+ *   tablet   screen and (min-width: P+1) and (max-width: T)
+ *   phone    screen and (max-width: P)
+ *
+ * Exactly one query matches any given width, so the active tier is unambiguous.
+ *
+ * On activation the manager KILLS the previously-active variant's timeline
+ * (cleaning up its triggers + restoring element state) and then invokes the new
+ * tier's factory, which rebuilds and (re)registers the timeline. A variant
+ * factory returns the `Timeline` it builds so the manager can kill it on the
+ * next swap.
+ *
+ * Tree-shaking: this module self-registers a factory on `SDKRegistry.responsive`
+ * and is referenced by `Motion.responsive` only through that registry — never via
+ * a static import. It is therefore only bundled when a project actually has a
+ * responsive timeline (see `feature:responsive` in the sdk-generator bundler).
+ */
+/** The four tiers in cascade order (widest → narrowest). */
+export type ResponsiveTier = 'desktop' | 'laptop' | 'tablet' | 'phone';
+/**
+ * A variant factory: builds + registers the tier's timeline and returns it.
+ * Returning the timeline lets the manager kill it precisely on the next swap.
+ * A factory MAY return nothing (e.g. a tier whose nodes are all disabled);
+ * in that case the manager simply has no active timeline for that tier.
+ */
+export type ResponsiveVariant = () => {
+    kill: (clearProps?: boolean) => void;
+} | void;
+/** Map of tier → variant factory. Tiers may be sparse; missing tiers cascade up. */
+export type ResponsiveVariants = Partial<Record<ResponsiveTier, ResponsiveVariant>>;
+/** Global breakpoint pixel boundaries (same values the builder stores). */
+export interface ResponsiveBreakpointConfig {
+    laptops: number;
+    tablets: number;
+    phones: number;
+}
+export declare class ResponsiveManager {
+    private variants;
+    private queries;
+    private activeTier;
+    private activeTimeline;
+    private destroyed;
+    /**
+     * Register the variants and wire up matchMedia listeners. Immediately
+     * activates whichever tier currently matches the viewport.
+     *
+     * Re-entrant: calling register() again (or after destroy()) first tears down
+     * any previously-wired listeners and active timeline via destroy(), then
+     * re-arms from a clean slate. This prevents matchMedia 'change' listeners from
+     * accumulating across re-registrations (which would otherwise leak listeners
+     * and trigger duplicate rebuilds on every breakpoint crossing).
+     *
+     * In non-DOM / no-matchMedia environments it falls back to building the
+     * desktop variant a single time (no live swapping).
+     */
+    register(variants: ResponsiveVariants, config: ResponsiveBreakpointConfig): void;
+    /** Re-evaluate which tier matches and swap if it changed. */
+    private handleChange;
+    /**
+     * Kill the current timeline and build the variant for `tier`. When the tier
+     * has no own variant, cascade UP to the nearest wider tier that does (so a
+     * sparse variant map still covers every width).
+     */
+    private activateTier;
+    /** Kill the active timeline if any, swallowing teardown errors. */
+    private killActive;
+    /** The tier currently driving the preview (for tests / debugging). */
+    getActiveTier(): ResponsiveTier | null;
+    /**
+     * Tear down all listeners and kill the active timeline. Idempotent.
+     */
+    destroy(): void;
+}

package/dist/utils/PropertyParser/constants.d.ts

@@ -0,0 +1,15 @@
+/**
+ * PropertyParser constants — property-name sets used to classify and default
+ * animation properties.
+ */
+export declare const TRANSFORM_PROPS: Set<string>;
+export declare const PX_PROPS: Set<string>;
+export declare const DEG_PROPS: Set<string>;
+export declare const UNITLESS_PROPS: Set<string>;
+export declare const COLOR_PROPS: Set<string>;
+export declare const NAMED_COLORS: Set<string>;
+/**
+ * Properties that support "auto" value resolution.
+ * Only layout properties where the browser can compute a natural value make sense.
+ */
+export declare const AUTO_PROPS: Set<string>;

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

@@ -0,0 +1,23 @@
+/**
+ * PropertyParser barrel — preserves the public import path `../utils/PropertyParser`.
+ *
+ * Re-exports the exact public surface the original single-file module had:
+ *   - types `PropertyValue`, `ParsedProperty`
+ *   - predicates `isTransformProp`, `isColorProp`, `isFilterProp`, `isDrawSVGProp`,
+ *     `isPathProp`, `isClipPathProp`, `isCSSVariable`, `looksLikeColor`
+ *   - unit helpers `parseValue`, `getDefaultUnit`, `getCurrentValue`,
+ *     `convertPxToUnit`, `getCurrentValueInUnit`, `getOriginalCSSValueWithUnit`,
+ *     `camelToKebab`
+ *   - relative-value helpers `isRelativeValue`, `getRelativeOperator`,
+ *     `calculateRelativeValue`
+ *   - the main `parseProperty` entry point
+ *
+ * Unlike TextSplitter/TextFlapper, this module has NO module-load side effect:
+ * it only READS from SDKRegistry, it never registers itself. So there is no
+ * `./register` import here.
+ */
+export type { PropertyValue, ParsedProperty } from './types';
+export { isTransformProp, isColorProp, isFilterProp, isDrawSVGProp, isPathProp, isClipPathProp, isCSSVariable, looksLikeColor, } from './predicates';
+export { parseValue, getDefaultUnit, getCurrentValue, convertPxToUnit, getCurrentValueInUnit, getOriginalCSSValueWithUnit, camelToKebab, } from './units';
+export { isRelativeValue, getRelativeOperator, calculateRelativeValue, } from './relative';
+export { parseProperty } from './parsers';

package/dist/utils/PropertyParser/parsers.d.ts

@@ -0,0 +1,13 @@
+/**
+ * PropertyParser parsers — the main `parseProperty` entry point and the
+ * per-type parsers it delegates to (color, filter, CSS variable, drawSVG,
+ * clip-path, path). The optional parsers read their implementations from
+ * SDKRegistry and gracefully no-op when a parser is not loaded.
+ */
+import type { AnimationTarget } from '../../types';
+import type { PropertyValue, ParsedProperty } from './types';
+/**
+ * Parse a property for animation
+ * Handles both DOM Elements and plain objects
+ */
+export declare function parseProperty(target: AnimationTarget, prop: string, targetValue: PropertyValue, fromValue?: PropertyValue): ParsedProperty;

package/dist/utils/PropertyParser/predicates.d.ts

@@ -0,0 +1,37 @@
+/**
+ * PropertyParser predicates — classify a property by name and detect
+ * color-like values.
+ */
+import type { PropertyValue } from './types';
+/**
+ * Check if a property is a transform property
+ */
+export declare function isTransformProp(prop: string): boolean;
+/**
+ * Check if a property is a color property
+ */
+export declare function isColorProp(prop: string): boolean;
+/**
+ * Check if a property is the filter property
+ */
+export declare function isFilterProp(prop: string): boolean;
+/**
+ * Check if a property is the drawSVG property
+ */
+export declare function isDrawSVGProp(prop: string): boolean;
+/**
+ * Check if a property is the path property (motion path)
+ */
+export declare function isPathProp(prop: string): boolean;
+/**
+ * Check if a property is the clip-path property (accepts both kebab and camel case)
+ */
+export declare function isClipPathProp(prop: string): boolean;
+/**
+ * Check if a property is a CSS variable (custom property)
+ */
+export declare function isCSSVariable(prop: string): boolean;
+/**
+ * Check if a value looks like a color (for CSS variable type detection)
+ */
+export declare function looksLikeColor(value: PropertyValue): boolean;

package/dist/utils/PropertyParser/relative.d.ts

@@ -0,0 +1,17 @@
+/**
+ * PropertyParser relative values — detect and compute relative operators
+ * (`+=`, `-=`, `*=`, `/=`).
+ */
+import type { PropertyValue } from './types';
+/**
+ * Check if a value is relative (+=, -=, *=, /=)
+ */
+export declare function isRelativeValue(value: PropertyValue): boolean;
+/**
+ * Get relative operator from value string
+ */
+export declare function getRelativeOperator(value: string): '+=' | '-=' | '*=' | '/=' | null;
+/**
+ * Calculate relative end value
+ */
+export declare function calculateRelativeValue(startValue: number, relativeValue: number, operator: '+=' | '-=' | '*=' | '/='): number;

package/dist/utils/PropertyParser/types.d.ts

@@ -0,0 +1,83 @@
+/**
+ * PropertyParser types — the property-value union and the discriminated union
+ * of all parsed property shapes.
+ */
+import type { ParsedFilterFunction } from '../FilterParser';
+import type { ParsedDrawSVG } from '../DrawSVGParser';
+import type { ParsedClipPath } from '../ClipPathParser';
+/**
+ * Valid property value types for animation
+ */
+export type PropertyValue = number | string;
+/**
+ * Base fields shared by all parsed property types
+ */
+export interface ParsedPropertyBase {
+    property: string;
+    isTransform: boolean;
+}
+/**
+ * Scalar property (numbers with units)
+ */
+export interface ParsedScalarProperty extends ParsedPropertyBase {
+    type: 'scalar';
+    startValue: number;
+    endValue: number;
+    unit: string;
+}
+/**
+ * Color property (RGBA values)
+ */
+export interface ParsedColorProperty extends ParsedPropertyBase {
+    type: 'color';
+    startColor: Float32Array;
+    endColor: Float32Array;
+}
+/**
+ * Filter property (CSS filters)
+ */
+export interface ParsedFilterProperty extends ParsedPropertyBase {
+    type: 'filter';
+    startFilters: ParsedFilterFunction[];
+    endFilters: ParsedFilterFunction[];
+}
+/**
+ * DrawSVG property (SVG stroke animation)
+ */
+export interface ParsedDrawSVGProperty extends ParsedPropertyBase {
+    type: 'drawSVG';
+    startDraw: ParsedDrawSVG;
+    endDraw: ParsedDrawSVG;
+    length: number;
+}
+/**
+ * Clip-path property (CSS clip-path shape function interpolation)
+ */
+export interface ParsedClipPathProperty extends ParsedPropertyBase {
+    type: 'clipPath';
+    startClipPath: ParsedClipPath;
+    endClipPath: ParsedClipPath;
+}
+/**
+ * Path property (motion along SVG path)
+ */
+export interface ParsedPathProperty extends ParsedPropertyBase {
+    type: 'path';
+    pathData: string;
+    pathLength: number;
+    startProgress: number;
+    endProgress: number;
+    rotate: boolean;
+    alignOffset: {
+        x: number;
+        y: number;
+    };
+    pathOffset: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Discriminated union of all parsed property types
+ */
+export type ParsedProperty = ParsedScalarProperty | ParsedColorProperty | ParsedFilterProperty | ParsedDrawSVGProperty | ParsedPathProperty | ParsedClipPathProperty;

package/dist/utils/PropertyParser/units.d.ts

@@ -0,0 +1,53 @@
+/**
+ * PropertyParser units — numeric/unit parsing, defaulting, and reading current
+ * values off a target (with px↔unit conversion via the browser layout engine).
+ */
+import type { AnimationTarget } from '../../types';
+import type { PropertyValue } from './types';
+/**
+ * Parse a property value and extract numeric value and unit
+ */
+export declare function parseValue(value: PropertyValue): {
+    value: number;
+    unit: string;
+};
+/**
+ * Get the default unit for a property
+ */
+export declare function getDefaultUnit(prop: string): string;
+/**
+ * Get the current computed value of a property from a target
+ * Handles both DOM Elements and plain objects
+ */
+export declare function getCurrentValue(target: AnimationTarget, prop: string): number;
+/**
+ * Convert a pixel value to a target CSS unit by measuring the element in the DOM.
+ *
+ * Uses the browser's layout engine: temporarily sets `100{targetUnit}` on the
+ * element, reads the computed pixel equivalent, then derives the conversion ratio.
+ * This handles %, em, rem, vw, vh, vmin, vmax, ch, ex — any unit the browser supports.
+ *
+ * When the target unit is 'px' or empty, returns the value unchanged (no conversion).
+ * Falls back to the raw pixel value if measurement fails (e.g. detached element).
+ */
+export declare function convertPxToUnit(element: Element, prop: string, pxValue: number, targetUnit: string): number;
+/**
+ * Get the current computed value of a property, converted to the specified unit.
+ *
+ * Combines getCurrentValue (which always returns px for layout properties)
+ * with convertPxToUnit to return the value in the desired CSS unit.
+ * Only performs conversion for DOM Element targets with non-px units.
+ */
+export declare function getCurrentValueInUnit(target: AnimationTarget, prop: string, targetUnit: string): number;
+/**
+ * Get the original CSS value AND unit of a property (excluding inline styles)
+ * Returns both value and unit to preserve the original CSS unit (%, rem, em, vh, etc.)
+ */
+export declare function getOriginalCSSValueWithUnit(target: Element, prop: string): {
+    value: number;
+    unit: string;
+};
+/**
+ * Convert camelCase to kebab-case
+ */
+export declare function camelToKebab(str: string): string;

package/dist/utils/{TextFlapper.d.ts → TextFlapper/TextFlapper.d.ts}

@@ -27,43 +27,8 @@
  * Revert:
  *   TextFlapper.revert(charEls);
  */
-import type { FlapConfig } from '../types';
-/**
- * A single numeric property to interpolate per flap cycle.
- * AnimationBuilder populates these from user-provided from/to vars so that
- * CSS properties animate once per character-swap cycle instead of once over
- * the full animation duration.
- */
-export interface UserPropEntry {
-    /** CSS property name or transform shorthand (e.g. 'y', 'opacity', 'rotateX') */
-    prop: string;
-    /** Start value (from) */
-    from: number;
-    /** End value (to) */
-    to: number;
-    /** CSS unit string: 'px', 'deg', '%', or '' for unitless */
-    unit: string;
-    /** True when prop is a TransformCache property (routes through setTransformValue) */
-    isTransform: boolean;
-}
-/** Lightweight controller for standalone flap() usage (ConnectAI, etc.) */
-export interface FlapController {
-    kill(): void;
-    readonly finished: Promise<void>;
-    readonly isComplete: boolean;
-}
-/**
- * Per-character render driver returned by `prepare()`.
- * AnimationBuilder uses these to create real Animation objects via Engine.
- */
-export interface FlapCharDriver {
-    /** The character element */
-    readonly el: HTMLElement;
-    /** Called each frame with progress (0-1). Drives text swaps + visual effects. */
-    readonly render: (progress: number) => void;
-    /** Snap to resolved final state. Called on animation complete. */
-    readonly finalize: () => void;
-}
+import type { FlapConfig } from '../../types';
+import type { UserPropEntry, FlapController, FlapCharDriver } from './types';
 export declare class TextFlapper {
     /**
      * Prepare per-character animation drivers for the split-flap effect.

package/dist/utils/TextFlapper/charRender.d.ts

@@ -0,0 +1,21 @@
+/**
+ * TextFlapper per-char render function builders.
+ *
+ * buildCharRender maps linear progress (0-1) to the current visual state and
+ * applies the corresponding CSS/text swap; buildCharFinalize snaps to the
+ * resolved final state on completion.
+ */
+import type { FlapConfig } from '../../types';
+import type { UserPropEntry } from './types';
+/**
+ * Build the render callback for a single character.
+ *
+ * The render function maps a linear progress (0-1) to the current visual state:
+ * which cycle, which phase within the cycle, and applies the corresponding
+ * CSS properties + text swap.
+ *
+ * Pre-generates random characters so the animation is deterministic when
+ * scrubbed (seek forward/backward produces consistent results).
+ */
+export declare function buildCharRender(el: HTMLElement, target: string, cycles: number, charset: string, type: NonNullable<FlapConfig['type']>, perspectivePx: number, continuous: boolean, userProps?: UserPropEntry[]): (progress: number) => void;
+export declare function buildCharFinalize(el: HTMLElement, target: string, type: NonNullable<FlapConfig['type']>, userProps?: UserPropEntry[]): () => void;

package/dist/utils/TextFlapper/constants.d.ts

@@ -0,0 +1,20 @@
+/**
+ * TextFlapper constants — charsets, defaults, and the module-level WeakMaps
+ * that track per-element state across prepare/render/revert.
+ */
+import type { BoardParts } from './types';
+export declare const CHARSETS: Record<string, string>;
+export declare const DEFAULT_SPEED = 80;
+export declare const DEFAULT_PERSPECTIVE = 400;
+export declare const DEFAULT_CYCLES: [number, number];
+export declare const originalContentMap: WeakMap<HTMLElement, string>;
+export declare const boardPartsMap: WeakMap<HTMLElement, BoardParts>;
+/**
+ * Tracks elements pinned by `stableWidth: 'container'` so revert() can
+ * restore their original `display` and `width` inline styles without
+ * clobbering unrelated user-set inline styles.
+ */
+export declare const containerPinnedMap: WeakMap<HTMLElement, {
+    display: string;
+    width: string;
+}>;

package/dist/utils/TextFlapper/helpers.d.ts

@@ -0,0 +1,50 @@
+/**
+ * TextFlapper helpers — charset resolution, cycle counting, measurement, and
+ * the one-time per-type DOM/style setup that prepare() applies before driving.
+ */
+import type { FlapConfig } from '../../types';
+import type { StableWidthMode } from './types';
+/**
+ * Walk upward from a character span past any implicit word-wrap spans
+ * inserted by TextSplitter ([data-split-word-wrap]). The returned element
+ * is the split ROOT — the user-facing container that was passed to split()
+ * (e.g. the <a>, <h1>, etc.). This is the element we want to pin in
+ * `stableWidth: 'container'` mode, not the intermediate per-word wrappers.
+ */
+export declare function findSplitRootContainer(charEl: HTMLElement): HTMLElement | null;
+export declare function resolveCharset(charset: string | undefined): string;
+export declare function getRandomChar(charset: string): string;
+export declare function resolveCycleCount(cycles: FlapConfig['cycles']): number;
+export declare function isWhitespaceChar(char: string): boolean;
+/**
+ * Record original textContent for revert, return normalised target char.
+ */
+export declare function recordAndNormalise(el: HTMLElement): string;
+/**
+ * One-time setup styles required by each animation type.
+ */
+/**
+ * Measure the widest glyph in `chars` using the same rendering context as
+ * `referenceEl` (font, size, weight, letter-spacing etc. all inherit).
+ *
+ * Used by `stableWidth` to size each char cell (or container) wide enough
+ * for BOTH the target text AND the random charset pool. Without this,
+ * cycling from a narrow Latin target ("Getting started") through a wider
+ * charset (katakana, blocks, CJK) causes per-cycle width jumps since the
+ * measurement was only sized for the narrow target.
+ *
+ * Returns the widest measured width AND the character that produced it —
+ * the character is used by `stableWidth: 'container'` to simulate the
+ * widest flap state in-place for a precise (subpixel-aware) measurement
+ * of the ROOT container's full flap width.
+ *
+ * Measurement strategy: one absolutely-positioned invisible wrapper holds
+ * one inline-block child per unique char. Appended once, all widths are
+ * read with getBoundingClientRect() after a single reflow, then the
+ * wrapper is removed.
+ */
+export declare function measureMaxCharsetWidth(referenceEl: HTMLElement, chars: string): {
+    width: number;
+    char: string;
+};
+export declare function applyTypeSetup(charElements: HTMLElement[], type: FlapConfig['type'], perspectivePx?: number, styledBoard?: boolean, stableWidth?: StableWidthMode, preserveWhitespaceCells?: boolean, charset?: string): void;

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

@@ -0,0 +1,16 @@
+/**
+ * TextFlapper barrel — preserves the public import path `../utils/TextFlapper`.
+ *
+ * Re-exports the exact public surface the original single-file module had:
+ *   - class `TextFlapper`
+ *   - types `UserPropEntry`, `FlapController`, `FlapCharDriver`
+ *
+ * The SDKRegistry self-registration side effect lives in `./TextFlapper`
+ * (co-located with the class), so importing this barrel still registers the
+ * implementation on SDKRegistry at module load — the behaviour the SDK entry
+ * relies on. It is intentionally NOT a separate bare `import './register'`:
+ * the chunked SDK bundler does not inline bare side-effect imports and would
+ * leak a raw `import` statement into the standalone bundle.
+ */
+export { TextFlapper } from './TextFlapper';
+export type { UserPropEntry, FlapController, FlapCharDriver } from './types';

package/dist/utils/TextFlapper/types.d.ts

@@ -0,0 +1,89 @@
+/**
+ * TextFlapper types — public driver/controller interfaces plus internal
+ * structural types shared across the TextFlapper parts.
+ */
+/**
+ * A single numeric property to interpolate per flap cycle.
+ * AnimationBuilder populates these from user-provided from/to vars so that
+ * CSS properties animate once per character-swap cycle instead of once over
+ * the full animation duration.
+ */
+export interface UserPropEntry {
+    /** CSS property name or transform shorthand (e.g. 'y', 'opacity', 'rotateX') */
+    prop: string;
+    /** Start value (from) */
+    from: number;
+    /** End value (to) */
+    to: number;
+    /** CSS unit string: 'px', 'deg', '%', or '' for unitless */
+    unit: string;
+    /** True when prop is a TransformCache property (routes through setTransformValue) */
+    isTransform: boolean;
+}
+/** Lightweight controller for standalone flap() usage (ConnectAI, etc.) */
+export interface FlapController {
+    kill(): void;
+    readonly finished: Promise<void>;
+    readonly isComplete: boolean;
+}
+/**
+ * Per-character render driver returned by `prepare()`.
+ * AnimationBuilder uses these to create real Animation objects via Engine.
+ */
+export interface FlapCharDriver {
+    /** The character element */
+    readonly el: HTMLElement;
+    /** Called each frame with progress (0-1). Drives text swaps + visual effects. */
+    readonly render: (progress: number) => void;
+    /** Snap to resolved final state. Called on animation complete. */
+    readonly finalize: () => void;
+}
+/**
+ * Board type DOM structure — real Solari departure board effect.
+ *
+ * A single two-sided flap rotates 0° → -180° around the split line:
+ *   FRONT = OLD char's top half   (visible 0° to ~-90°)
+ *   BACK  = NEW char's bottom half (visible ~-90° to -180°, lands at bottom)
+ *
+ * Two static halves sit behind the flap:
+ *   staticTop    = NEW char's top    (revealed as flap falls away)
+ *   staticBottom = OLD char's bottom (covered by flapBack when it lands)
+ *
+ * The flap uses a wrapper with transform-style: preserve-3d (no overflow).
+ * Front and back children each have overflow:hidden + backface-visibility:hidden.
+ *
+ * A persistent split line sits at z:3 above everything for realism.
+ * A dynamic shadow overlay on the bottom half adds depth during rotation.
+ *
+ * Layout:
+ *   container (el, perspective)
+ *   ├─ staticTop    (top:0,   h:50%, overflow:hidden, z:1) → text (NEW top)
+ *   ├─ staticBottom (top:50%, h:50%, overflow:hidden, z:1) → text (OLD→NEW bottom)
+ *   ├─ flapWrap     (top:0,   h:50%, transformOrigin:center bottom, preserve-3d, z:2)
+ *   │   ├─ flapFront (h:100%, overflow:hidden, backface:hidden)      → text (OLD top)
+ *   │   └─ flapBack  (h:100%, overflow:hidden, backface:hidden, rotateX:180°) → text (NEW bottom)
+ *   └─ splitLine    (top:50%, h:1px, z:3) — persistent center divider
+ */
+export interface BoardParts {
+    /** Static NEW char top half (background, revealed as flap falls) */
+    staticTop: HTMLElement;
+    /** Static bottom half (OLD char initially, switches to NEW at midpoint) */
+    staticBottom: HTMLElement;
+    /** Flap wrapper — rotates 0°→-180°, holds front/back faces */
+    flapWrap: HTMLElement;
+    /** Front face — OLD char top (visible 0° to -90°) */
+    flapFront: HTMLElement;
+    /** Back face — NEW char bottom (visible -90° to -180°) */
+    flapBack: HTMLElement;
+    /** Persistent split line across the center */
+    splitLine: HTMLElement;
+    /** Dynamic shadow overlay on the bottom half — opacity driven by flap angle */
+    shadow: HTMLElement;
+    /** Inner text spans */
+    staticTopText: HTMLElement;
+    staticBottomText: HTMLElement;
+    flapFrontText: HTMLElement;
+    flapBackText: HTMLElement;
+}
+/** Normalised internal form of FlapConfig.stableWidth */
+export type StableWidthMode = 'none' | 'cells' | 'container';

package/dist/utils/TextSplitter/TextSplitter.d.ts

@@ -0,0 +1,55 @@
+/**
+ * TextSplitter - Split text into animatable elements
+ *
+ * Splits text content into chars, words, or lines wrapped in spans.
+ * Supports nested splitting (e.g., 'chars,words' = words containing char spans).
+ *
+ * Preserves existing element structure — inline elements like
+ * `<span class="accent">word</span>` keep their wrapper and styling.
+ * Only text nodes are replaced with split spans.
+ *
+ * Usage:
+ *   const elements = TextSplitter.split(element, 'chars');
+ *   const elements = TextSplitter.split(element, 'words');
+ *   const elements = TextSplitter.split(element, 'chars,words');
+ *
+ * Revert:
+ *   TextSplitter.revert(element);
+ *   TextSplitter.revert(element, consumer); // reference-counted
+ */
+import type { SplitType, SplitOptions, SplitResult } from './types';
+export declare class TextSplitter {
+    /**
+     * Split text content into animatable elements.
+     *
+     * When `options.consumer` is provided the split is reference-counted.
+     * A second consumer on the same element will have the DOM upgraded
+     * (chars nested inside existing word spans, or word-wraps promoted to
+     * word spans) rather than reverted and rebuilt, so the first consumer's
+     * DOM references remain valid.
+     *
+     * Without a consumer token the function behaves exactly like before:
+     * any existing split is reverted and a fresh split is performed.
+     */
+    static split(element: Element, type: SplitType, options?: SplitOptions): HTMLElement[];
+    /**
+     * Revert element to original content.
+     *
+     * When `consumer` is provided the revert is reference-counted: the DOM is
+     * only restored once all registered consumers have released via this method.
+     * If the consumer is the last one (or no consumer tracking is active), the
+     * element's innerHTML is restored to the pre-split original immediately.
+     *
+     * Without `consumer` (legacy / forced revert), the DOM is restored regardless
+     * of how many consumers are still registered. All consumer refs are cleared.
+     */
+    static revert(element: Element, consumer?: object): boolean;
+    /**
+     * Check if element has been split
+     */
+    static isSplit(element: Element): boolean;
+    /**
+     * Get split result for an element
+     */
+    static getResult(element: Element): SplitResult | undefined;
+}