cineview 1.0.0

package/dist/components/Animate/AnimateVideo.d.ts

@@ -0,0 +1,59 @@
+import { CSSProperties, VideoHTMLAttributes } from 'react';
+import { AnimationType } from '../../types';
+type NativeVideoEventProps = Pick<VideoHTMLAttributes<HTMLVideoElement>, 'onEnded' | 'onPlay' | 'onPause' | 'onTimeUpdate' | 'onError'>;
+export interface AnimateVideoProps extends NativeVideoEventProps {
+    /**
+     * Video resource URL. Videos authored for scrubbing should use dense keyframes;
+     * all-keyframe encoding provides the most predictable reverse-seek performance.
+     */
+    src: string;
+    'aria-label'?: string;
+    width?: number | string;
+    height?: number | string;
+    style?: CSSProperties;
+    /** Whether this component eagerly fills the shared video preload cache. */
+    preload?: boolean;
+    poster?: string;
+    playbackRate?: number;
+    /** Optional video-time interval driven by progress, including reverse intervals. */
+    scrubRange?: readonly [fromSeconds: number, toSeconds: number];
+    animateId?: string;
+    duration?: {
+        enter?: number;
+        exit?: number;
+    };
+    /** Defaults to a neutral variant so frame scrubbing remains the visible animation. */
+    enterAnimation?: AnimationType;
+    exitAnimation?: AnimationType;
+    timeline?: {
+        delay?: number;
+        after?: string;
+    };
+    visibility?: {
+        replay?: boolean;
+        enterMargin?: number;
+        exitMargin?: number;
+    };
+    /**
+     * Scroll mode, takeover zones only (default `false`). When `true`, the
+     * decoded-frame residency of the scrub video follows the zone's approach
+     * band (task-flow 2026-08-14, Plan A "release when far / preload when near"):
+     *
+     * - Leaving the zone beyond 1.5 viewports (band `'far'`) drops the decoded
+     *   frames/textures via `pause + removeAttribute('src') + load()` — probe
+     *   evidence shows those frames otherwise cost real compositor time in the
+     *   scenes the viewer scrolls to next.
+     * - Returning within 1 viewport of the zone (band `'near'`) re-attaches the
+     *   source (blob already in memory, zero network) and catches the seek up to
+     *   the current timeline position once metadata is back.
+     *
+     * The release threshold sits deliberately outside the preload threshold
+     * (Schmitt ordering) so hovering between them cannot flap. Ignored outside
+     * scroll takeover zones and in drag mode. Releasing only happens after the
+     * timeline has actually been scrubbed/played once (an un-watched video has
+     * nothing resident to free).
+     */
+    releaseOnLeave?: boolean;
+}
+export declare const AnimateVideo: import('react').ForwardRefExoticComponent<AnimateVideoProps & import('react').RefAttributes<HTMLVideoElement>>;
+export {};

package/dist/components/Animate/StaggerContainer.d.ts

@@ -0,0 +1,35 @@
+import { ReactElement } from 'react';
+import { MotionValue } from 'framer-motion';
+import { AnimatePhase, ParsedAnimationVariant } from '../../types';
+import { DragVisualState } from './useAnimateDrag';
+type StaggerFrom = 'first' | 'last' | 'center';
+type StaggerPhase = 'initial' | 'animate' | 'exit';
+export interface StaggerTiming {
+    itemDurationMs: number;
+    tailDurationMs: number;
+    effectiveDurationMs: number;
+}
+export declare function countStaggerItems(container: ReactElement): number;
+export declare function resolveStaggerTiming(variant: ParsedAnimationVariant, authoredDurationMs: number, each: number, from: StaggerFrom, itemCount: number, target?: 'animate' | 'exit'): StaggerTiming;
+export declare function renderStaggerTree(container: ReactElement, variant: ParsedAnimationVariant, each: number, from: StaggerFrom, phase: boolean | StaggerPhase, itemDurationMs?: number, exitVariant?: ParsedAnimationVariant | null, exitItemDurationMs?: number, instant?: boolean): ReactElement;
+interface CommonProps {
+    container: ReactElement;
+    variant: ParsedAnimationVariant;
+    each: number;
+    from: StaggerFrom;
+    itemDurationMs?: number;
+    effectiveDurationMs?: number;
+    exitVariant?: ParsedAnimationVariant | null;
+    exitItemDurationMs?: number;
+}
+export declare function ScrollStagger({ container, variant, each, from, itemDurationMs, effectiveDurationMs, exitVariant, exitItemDurationMs, signedVisual, }: CommonProps & {
+    signedVisual: MotionValue<number>;
+}): ReactElement;
+export declare function ArrivalStagger({ container, variant, each, from, itemDurationMs, effectiveDurationMs, phaseMotion, staticReveal, }: CommonProps & {
+    phaseMotion: MotionValue<AnimatePhase>;
+    staticReveal: boolean;
+}): ReactElement;
+export declare function DragStagger({ container, variant, each, from, itemDurationMs, effectiveDurationMs, exitVariant, exitItemDurationMs, visualState, }: CommonProps & {
+    visualState: MotionValue<DragVisualState | null>;
+}): ReactElement;
+export {};

package/dist/components/Animate/__fixtures__/animate-media-public-path.fixture.d.ts

@@ -0,0 +1 @@
+export declare function AnimateMediaPublicPathFixture(): React.JSX.Element;

package/dist/components/Animate/animateInterpolation.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared interpolation/variant helpers for the Animate hooks.
+ *
+ * `useAnimateDrag` and `useAnimateScroll` are two independent driver
+ * implementations (follow-finger element clock vs. scroll-budget / visibility
+ * gate), but the leaf math that turns a variant record + progress into a CSS
+ * value is identical. These pure helpers were duplicated verbatim in both hooks;
+ * keeping one copy here removes the drift risk.
+ *
+ * `lerpTransformValue` is the superset string interpolator (drag's former
+ * `lerpStringValue`): it handles number, unit-suffixed strings (`100%`, `12px`,
+ * `45deg`), AND single-arg transform functions (`translateY(100%)`). Scroll's
+ * former `lerpValue` lacked the function branch; adopting the superset is purely
+ * additive — non-function values resolve identically.
+ */
+export type AnimatableProperty = 'opacity' | 'x' | 'y' | 'scale' | 'rotate' | 'rotateX' | 'rotateY' | 'skewX' | 'skewY' | 'filter';
+export type TransformValue = number | string;
+export type VariantRecord = Record<string, unknown>;
+/**
+ * Compiled variant records shared by the drag and scroll drivers (both have
+ * full enter/exit semantics). The arrival driver intentionally keeps its own
+ * two-field shape { initial, animate } — it has no exit concept, and faking an
+ * empty exitTarget here would be a semantic lie.
+ */
+export interface SceneVariantRecords {
+    enterInitial: VariantRecord;
+    enterAnimate: VariantRecord;
+    exitTarget: VariantRecord;
+}
+export declare function clamp(value: number, min: number, max: number): number;
+export declare function lerp(start: number, end: number, progress: number): number;
+export declare function lerpTransformValue(start: TransformValue, end: TransformValue, progress: number): TransformValue;
+/**
+ * Resolve one property from a Framer Motion variant record at a scrubbed local progress.
+ * Array targets are full keyframe sequences; scalar targets retain the existing from-to lerp.
+ */
+export declare function interpolateVariantValue(from: TransformValue, record: VariantRecord, property: AnimatableProperty, fallback: TransformValue, progress: number): TransformValue;
+export declare function getVariantTerminalValue(record: VariantRecord, property: AnimatableProperty, fallback: TransformValue): TransformValue;
+export declare function parseNumericValue(value: unknown, fallback: number): number;
+export declare function getDefaultValue(property: AnimatableProperty, phase: 'initial' | 'animate' | 'exit'): TransformValue;
+export declare function getVariantValue<T extends TransformValue>(record: VariantRecord, property: AnimatableProperty, fallback: T): T;

package/dist/components/Animate/animateRenderState.d.ts

@@ -0,0 +1,23 @@
+import { AnimateRenderState } from '../../types';
+/**
+ * Render-prop state normalization (pure functions, exported for testing).
+ *
+ * Scroll and drag use different phase vocabularies:
+ *   - scroll: `GatePhase`('idle'|'waiting'|'entering'|'entered'|'exiting'|'exited'), passed through directly.
+ *   - drag:  `DragVisualState.mode`('rest'|'outgoing'|'enter'|'hidden') + `localProgress`(0..1),
+ *            normalized to unified `AnimateRenderState.phase` vocabulary.
+ *
+ * Both sides converge `enterProgress` to 0..1 (0=initial frame, 1=fully entered).
+ */
+export type ScrollGatePhase = 'idle' | 'waiting' | 'entering' | 'entered' | 'exiting' | 'exited';
+export type DragVisualMode = 'rest' | 'outgoing' | 'enter' | 'hidden';
+/** Drag side: mode + localProgress → unified phase vocabulary. */
+export declare function normalizeDragPhase(mode: DragVisualMode, localProgress: number): AnimateRenderState['phase'];
+/** Scroll side: `visualMotion` convention 0=initial, 1=enter, -1=exit; enterProgress takes positive segment. */
+export declare function resolveScrollEnterProgress(signedVisual: number): number;
+/** Scroll side: assemble complete render state. */
+export declare function resolveScrollRenderState(phase: ScrollGatePhase, signedVisual: number): AnimateRenderState;
+/** Drag side: assemble complete render state. localProgress is already unsigned 0..1. */
+export declare function resolveDragRenderState(mode: DragVisualMode, localProgress: number): AnimateRenderState;
+/** No-animation early-exit branch: always initial state (progress 0, phase idle), still supports function children. */
+export declare const IDLE_RENDER_STATE: AnimateRenderState;

package/dist/components/Animate/animateSemantics.d.ts

@@ -0,0 +1,39 @@
+import { AnimateProps, AnimationType } from '../../types';
+type WidenAnimationRequirements<T> = T extends unknown ? Omit<T, 'enterAnimation' | 'loopAnimation'> & {
+    enterAnimation?: AnimationType;
+    loopAnimation?: AnimationType;
+} : never;
+/**
+ * Runtime implementation shape. The public union requires enter or loop,
+ * while this internal view remains defensive against JavaScript/`as any`
+ * callers so invalid configurations can fail open and report INVALID_ANIMATION.
+ */
+export type AnimateInternalProps = WidenAnimationRequirements<AnimateProps>;
+export interface NormalizedAnimateTimeline {
+    driver: 'scene' | 'clock';
+    delay: number;
+    after?: string;
+    zoneId?: string;
+    phase?: {
+        start?: number;
+        end?: number;
+    };
+}
+export type ResolvedAnimateTimeline = Omit<NormalizedAnimateTimeline, 'driver'> & {
+    lane: 'scroll' | 'visibility';
+};
+export interface NormalizedAnimateVisibility {
+    replay: boolean;
+    enterMargin?: number;
+    exitMargin?: number;
+}
+export interface NormalizedAnimateSemantics {
+    duration: {
+        enter: number;
+        exit: number;
+    };
+    timeline: NormalizedAnimateTimeline;
+    visibility: NormalizedAnimateVisibility;
+}
+export declare function normalizeAnimateSemantics({ duration, timeline, visibility, }: Pick<AnimateInternalProps, 'duration' | 'timeline' | 'visibility'>): NormalizedAnimateSemantics;
+export {};

package/dist/components/Animate/animateTimeline.d.ts

@@ -0,0 +1,14 @@
+import { ReactNode } from 'react';
+import { AnimateTimeline } from '../../types';
+interface AnimateTimelineProviderProps {
+    value: AnimateTimeline;
+    children: ReactNode;
+}
+export declare function AnimateTimelineProvider({ value, children, }: AnimateTimelineProviderProps): React.JSX.Element;
+/**
+ * Read the nearest Animate timeline without subscribing React to frame updates.
+ * Consumers attach MotionValues directly to motion styles or subscribe with
+ * useMotionValueEvent; CineView remains the only timeline writer.
+ */
+export declare function useAnimateTimeline(): AnimateTimeline;
+export {};

package/dist/components/Animate/dragVisualState.d.ts

@@ -0,0 +1,26 @@
+import { SceneContextType } from './Animate';
+import { AnimatableProperty, SceneVariantRecords, TransformValue } from './animateInterpolation';
+import { DragSceneTransaction, PreparedSceneSnapshot } from '../Scene/dragPreparedState';
+export interface DragVisualState {
+    mode: 'rest' | 'outgoing' | 'enter' | 'hidden';
+    direction: 'forward' | 'backward';
+    transitionProgress: number;
+    sharedElapsedMs: number;
+    projectedSceneElapsedMs: number;
+    sharedTimelineDurationMs: number;
+    sceneTimelineDurationMs: number;
+    localProgress: number;
+    sceneOffset: number;
+}
+export declare function resolveDirection(sceneContext: SceneContextType): 'forward' | 'backward';
+export declare function resolveElementElapsed(sceneContext: SceneContextType): number;
+export declare function resolveRenderProgress(sceneContext: SceneContextType): number;
+export declare function resolvePlaybackSnapshot(sceneContext: SceneContextType): DragSceneTransaction | PreparedSceneSnapshot | null;
+export declare function resolveSceneTimelineDuration(sceneContext: SceneContextType): number;
+export declare function resolveTransitionProgress(sceneContext: SceneContextType): number;
+export declare function resolveSharedTimelineDuration(sceneContext: SceneContextType): number;
+export declare function resolveEnterLocalProgress(sceneElapsedMs: number, calculatedDelay: number, enterDuration: number): number;
+export declare function resolveVisualState(sceneContext: SceneContextType, calculatedDelay: number, enterDuration: number, exitDuration: number): DragVisualState;
+export declare function resolvePlaybackVisualState(sceneContext: SceneContextType, calculatedDelay: number, enterDuration: number, exitDuration: number, excludedFromPlayback: boolean, variantsPending: boolean): DragVisualState;
+export declare function resolvePropertyValue(state: DragVisualState, variants: SceneVariantRecords, property: AnimatableProperty): TransformValue;
+export declare function resolveDragPropertyValue(state: DragVisualState | null, variants: SceneVariantRecords, property: AnimatableProperty): TransformValue;

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

@@ -0,0 +1,6 @@
+export { Animate } from './Animate';
+export { useAnimateTimeline } from './animateTimeline';
+export { SceneContext } from './Animate';
+export type { SceneAnimationRegistryContext, SceneBaseRuntimeContext, SceneContextType, SceneDragRuntimeContext, SceneScrollRuntimeBridgeContext, } from './Animate';
+export type { AnimateInternalProps, NormalizedAnimateSemantics, NormalizedAnimateTimeline, NormalizedAnimateVisibility, } from './animateSemantics';
+export type { AnimateRegistrationInfo } from '../../animations/registry';

package/dist/components/Animate/useAnimateArrival.d.ts

@@ -0,0 +1,35 @@
+import { MutableRefObject } from 'react';
+import { MotionValue } from 'framer-motion';
+import { AnimatePhase, ParsedAnimationVariant } from '../../types';
+import { SceneContextType } from './Animate';
+interface UseAnimateArrivalParams {
+    enabled: boolean;
+    sceneContext: SceneContextType | null;
+    enterVariant: ParsedAnimationVariant | null;
+    hasAuthoredEnterAnimation: boolean;
+    parseReady: boolean;
+    delay: number;
+    enterDuration: number;
+    /** Manual enter trigger (see `AnimateProps.enterRef`). `delay` is this lane's
+     *  fallback switch: with a delay authored the pass still self-starts after it,
+     *  with none the element holds at its initial frame until the consumer calls.
+     *  (`after` is ignored on this lane by design, so it is not a fallback here.) */
+    enterRef?: MutableRefObject<(() => void) | null>;
+}
+interface UseAnimateArrivalReturn {
+    style: Record<string, MotionValue<number> | MotionValue<string> | MotionValue<number | string>>;
+    visualMotion: MotionValue<number>;
+    phaseMotion: MotionValue<AnimatePhase>;
+    shouldRunInfinite: boolean;
+    /** Existing content revealed by the first-screen timeout must not tween stagger children. */
+    staticReveal: boolean;
+}
+/**
+ * * Real-time post-arrival driver for drag + timeline driver 'clock'.
+ *
+ * It never reads drag progress and never registers with the Scene element track.
+ * The sole start signal is Scene.activationToken. A Scene departure resets the
+ * element; returning mints a new token and therefore replays exactly once.
+ */
+export declare function useAnimateArrival({ enabled, sceneContext, enterVariant, hasAuthoredEnterAnimation, parseReady, delay, enterDuration, enterRef, }: UseAnimateArrivalParams): UseAnimateArrivalReturn;
+export {};

package/dist/components/Animate/useAnimateDrag.d.ts

@@ -0,0 +1,34 @@
+import { MotionValue } from 'framer-motion';
+import { ParsedAnimationVariant } from '../../types';
+import { SceneContextType } from './Animate';
+import { resolveEnterLocalProgress, DragVisualState } from './dragVisualState';
+export { resolveEnterLocalProgress };
+export type { DragVisualState };
+interface UseAnimateDragParams {
+    sceneContext: SceneContextType | null;
+    enterVariant: ParsedAnimationVariant | null;
+    exitVariant: ParsedAnimationVariant | null;
+    componentId: string;
+    delay: number;
+    enterDuration: number;
+    exitDuration: number;
+    after?: string;
+    /** An enter/infinite animation was authored but its variants have not parsed
+     *  yet (async preset import). Hold the initial frame instead of resolving to
+     *  the rest frame, which would paint the element fully visible for a frame and
+     *  then snap it back — the refresh flash. */
+    variantsPending?: boolean;
+}
+interface UseAnimateDragReturn {
+    style: Record<string, DragMotionValue>;
+    opacity: MotionValue<number>;
+    x: MotionValue<number | string>;
+    y: MotionValue<number | string>;
+    scale: MotionValue<number>;
+    rotate: MotionValue<number | string>;
+    useInteractiveStyles: boolean;
+    shouldRunInfinite: boolean;
+    visualState: MotionValue<DragVisualState | null>;
+}
+type DragMotionValue = MotionValue<number> | MotionValue<string> | MotionValue<number | string>;
+export declare function useAnimateDrag({ sceneContext, enterVariant, exitVariant, componentId, delay, enterDuration, exitDuration, after, variantsPending, }: UseAnimateDragParams): UseAnimateDragReturn;

package/dist/components/Animate/useAnimatePublicTimeline.d.ts

@@ -0,0 +1,16 @@
+import { MotionValue } from 'framer-motion';
+import { AnimatePhase, AnimateTimeline, ScrollMode } from '../../types';
+import { SceneContextType } from './Animate';
+import { DragVisualState } from './dragVisualState';
+export interface UseAnimatePublicTimelineParams {
+    mode: ScrollMode;
+    isDragArrival: boolean;
+    timelineLane: AnimateTimeline['lane'];
+    sceneContext: SceneContextType | null;
+    arrivalVisualMotion: MotionValue<number>;
+    arrivalPhaseMotion: MotionValue<AnimatePhase>;
+    scrollVisualMotion: MotionValue<number>;
+    scrollPhaseMotion: MotionValue<AnimatePhase>;
+    dragVisualState: MotionValue<DragVisualState | null>;
+}
+export declare function useAnimatePublicTimeline({ mode, isDragArrival, timelineLane, sceneContext, arrivalVisualMotion, arrivalPhaseMotion, scrollVisualMotion, scrollPhaseMotion, dragVisualState, }: UseAnimatePublicTimelineParams): AnimateTimeline;

package/dist/components/Animate/useAnimateScroll.d.ts

@@ -0,0 +1,83 @@
+import { MutableRefObject } from 'react';
+import { MotionValue } from 'framer-motion';
+import { ParsedAnimationVariant } from '../../types';
+import { SceneContextType } from './Animate';
+import { ResolvedAnimateTimeline, NormalizedAnimateVisibility } from './animateSemantics';
+import { SceneScrollZoneRuntime } from '../Scene/sceneScrollRuntime';
+interface UseAnimateScrollParams {
+    sceneContext: SceneContextType | null;
+    zoneRuntime: SceneScrollZoneRuntime | null;
+    zoneId: string | null;
+    enterVariant: ParsedAnimationVariant | null;
+    exitVariant: ParsedAnimationVariant | null;
+    hasAuthoredEnterAnimation?: boolean;
+    hasAuthoredExitAnimation?: boolean;
+    /** Whether this Animate has a parsed infinite variant to gate. Without one,
+     *  the zone's visual subscription is the only per-frame consumer required. */
+    hasInfiniteAnimation?: boolean;
+    componentId: string;
+    duration: {
+        enter: number;
+        exit: number;
+    };
+    timeline: ResolvedAnimateTimeline;
+    visibility: NormalizedAnimateVisibility;
+    /** CineView-level default enter/exit gate margins (design px). Per-Animate
+     *  visibility margins override these; both undefined → fall back to 50. */
+    globalEnterMargin?: number;
+    globalExitMargin?: number;
+    /** Manual enter/exit triggers (see `AnimateProps.enterRef` / `exitRef`).
+     *  Honoured on the visibility lane only — the scroll-takeover lane's progress
+     *  is a pure function of scrollTop and has no tween to trigger. */
+    enterRef?: MutableRefObject<(() => void) | null>;
+    exitRef?: MutableRefObject<(() => void) | null>;
+    /** An animation was authored but its variants have not parsed yet. The gate
+     *  must not start an enter attempt against the empty variant records — it
+     *  would tween through the DEFAULT frames and then swap mid-flight once the
+     *  real ones land. Hold the initial frame until the parse settles. */
+    variantsPending?: boolean;
+}
+interface UseAnimateScrollReturn {
+    style: Record<string, MotionValue<number> | MotionValue<string> | MotionValue<number | string>>;
+    shouldRunInfinite: boolean;
+    visualMotion: MotionValue<number>;
+    phaseMotion: MotionValue<GatePhase>;
+}
+export type GatePhase = 'idle' | 'waiting' | 'entering' | 'entered' | 'exiting' | 'exited';
+export type GateAction = 'enter' | 'exit' | null;
+/**
+ * Pure phase-transition decision for the visibility gate state machine.
+ *
+ * Enter and exit gates overlap in relTop ∈ [0, exitMargin] (both true). Without
+ * a mutex, reverse re-entry drives the element down through that band and the
+ * machine flips enter→exit→enter within one update batch — the exit snap to
+ * -epsilon flashes a near-animate frame ("element appears then replays from 0").
+ * The overlap band is therefore a hysteresis dead zone: when BOTH gates are
+ * true, hold the current phase (return null). Enter only fires strictly above
+ * the band (enterGate && !exitGate); exit only strictly below it
+ * (exitGate && !enterGate). Geometry (gate definitions) is unchanged — this only
+ * governs which transition the band resolves to.
+ *
+ * Returns the tween to launch, or null to hold the current phase.
+ */
+export declare function resolveGatePhaseAction(phase: GatePhase, enterGate: boolean, exitGate: boolean, opts: {
+    hasExplicitExit: boolean;
+    replay: boolean;
+}): GateAction;
+/**
+ * Pure decision for whether a visibility-driven element's loopAnimation
+ * should be running.
+ *
+ * The infinite (e.g. pulse) loop must only run while the element is BOTH in its
+ * entered phase AND currently intersecting the viewport. An element with no
+ * authored exitAnimation (hasExplicitExit === false) never exits — its phase
+ * stays 'entered' indefinitely even after it scrolls fully off-screen in either
+ * direction. Without an explicit on-screen check the infinite loop then keeps
+ * spinning off-screen forever (wasted work, and the element silently pulses
+ * where nobody can see it). Tying it to live viewport intersection pauses the
+ * loop the moment the element leaves the viewport in EITHER direction and
+ * resumes it on return.
+ */
+export declare function resolveInfiniteActive(phase: GatePhase, onScreen: boolean): boolean;
+export declare function useAnimateScroll({ sceneContext, zoneRuntime, zoneId, enterVariant, exitVariant, hasAuthoredEnterAnimation, hasAuthoredExitAnimation, hasInfiniteAnimation, componentId, duration, timeline, visibility, globalEnterMargin, globalExitMargin, enterRef, exitRef, variantsPending, }: UseAnimateScrollParams): UseAnimateScrollReturn;
+export {};

package/dist/components/Animate/useAnimatedPropertyLanes.d.ts

@@ -0,0 +1,30 @@
+import { MotionValue } from 'framer-motion';
+import { MutableRefObject } from 'react';
+import { AnimatableProperty, TransformValue } from './animateInterpolation';
+/** Per-driver leaf resolution: (source value, variants, property) → raw value. */
+export type PropertyValueResolver<T, V> = (input: T, variants: V, property: AnimatableProperty) => TransformValue;
+export interface AnimatedPropertyLanes {
+    style: {
+        opacity: MotionValue<number>;
+        x: MotionValue<TransformValue>;
+        y: MotionValue<TransformValue>;
+        scale: MotionValue<number>;
+        rotate: MotionValue<TransformValue>;
+        rotateX: MotionValue<TransformValue>;
+        rotateY: MotionValue<TransformValue>;
+        skewX: MotionValue<TransformValue>;
+        skewY: MotionValue<TransformValue>;
+        filter: MotionValue<TransformValue>;
+    };
+    opacity: MotionValue<number>;
+    x: MotionValue<TransformValue>;
+    y: MotionValue<TransformValue>;
+    scale: MotionValue<number>;
+    rotate: MotionValue<TransformValue>;
+    rotateX: MotionValue<TransformValue>;
+    rotateY: MotionValue<TransformValue>;
+    skewX: MotionValue<TransformValue>;
+    skewY: MotionValue<TransformValue>;
+    filter: MotionValue<TransformValue>;
+}
+export declare function useAnimatedPropertyLanes<T, V>(source: MotionValue<T>, variantsRef: MutableRefObject<V>, resolveValue: PropertyValueResolver<T, V>, resolveNumericValue?: PropertyValueResolver<T, V>): AnimatedPropertyLanes;

package/dist/components/Animate/visibilityScheduler.d.ts

@@ -0,0 +1,12 @@
+export interface VisibilityRootMeasurement {
+    top: number;
+    height: number;
+}
+type VisibilitySubscriber = (measurement: VisibilityRootMeasurement) => void;
+type VisibilityRoot = Window | HTMLElement;
+export declare function subscribeVisibilityMeasurement(root: VisibilityRoot, subscriber: VisibilitySubscriber): () => void;
+/** Queue one targeted visibility re-measurement on the next frame. Dependency
+ * completion and delay timers use this instead of launching a tween from a stale
+ * gate snapshot. Multiple wakeups for the same callback coalesce into one frame. */
+export declare function scheduleVisibilityRecheck(ownerWindow: Window, callback: () => void): () => void;
+export {};

package/dist/components/CineView/CineView.d.ts

@@ -0,0 +1,48 @@
+import { default as React } from 'react';
+import { AnimationType, CineViewRef, DragModeConfig, SceneProps, ScrollMode } from '../../types';
+type SceneAuthoringCompatProps = SceneProps & {
+    mode?: ScrollMode;
+    slideDirection?: 'x' | 'y';
+    slideDuration?: number;
+    sceneTransitionDuration?: number;
+    enterAnimation?: AnimationType;
+    exitAnimation?: AnimationType;
+    exitDuration?: number;
+    sceneWidth?: number | string;
+    sceneHeight?: number | string;
+    sceneZIndex?: number;
+    sceneStackMode?: 'replace' | 'cover';
+    scrollEnterLength?: number;
+    scrollExitLength?: number;
+};
+export declare function resolveRootMode(mode: ScrollMode | undefined): ScrollMode;
+export declare function resolveRootSceneStackMode(sceneProps: Pick<SceneAuthoringCompatProps, 'layout' | 'sceneStackMode'>, rootMode: ScrollMode): 'replace' | 'cover';
+/**
+ * Drag engine root component. Exported so UMD can split into single-engine builds by mode
+ * (see task-flow `2026-08-04-umd-mode-split.md`: scroll engine accounts for 20.3% of UMD bundle;
+ * script-tag consumers using only drag shouldn't carry it).
+ * Not re-exported from barrel: public API remains only `CineView` + `mode` prop.
+ */
+export declare const CineViewDragEngine: React.ForwardRefExoticComponent<import('../..').CineViewBaseProps & DragModeConfig & {
+    mode?: "drag";
+    callbacks?: import('../..').DragModeCallbacks;
+} & {
+    zoneTrigger?: undefined;
+    sceneSizing?: undefined;
+    enterMargin?: undefined;
+    exitMargin?: undefined;
+    debug?: undefined;
+} & React.RefAttributes<CineViewRef>>;
+export {};
+/**
+ * ⚠️ Mode dispatcher is NOT in this file, see `CineViewDispatch.tsx`.
+ *
+ * Originally there was a 5-line dispatcher here that statically imported both engines, causing
+ * ANY path reaching this file to pull in BOTH engines. UMD must be single-file (Rollup refuses
+ * UMD code splitting), so script-tag consumers using only drag carried the scroll engine's
+ * gzip 10437 bytes (20.3% of total bundle), pushing the package over 50 KB.
+ * After moving the dispatcher out, this file contains only the drag engine, allowing
+ * `entry-drag.ts` to truly exclude scroll. Real-world lesson: merely adding entry files
+ * without moving the dispatcher resulted in a drag build of 51937 bytes (larger than full bundle).
+ * See task-flow `2026-08-04-umd-mode-split.md` for details.
+ */

package/dist/components/CineView/CineViewDispatch.d.ts

@@ -0,0 +1,2 @@
+import { CineViewProps, CineViewRef } from '../../types';
+export declare const CineView: import('react').ForwardRefExoticComponent<CineViewProps & import('react').RefAttributes<CineViewRef>>;

package/dist/components/CineView/DirectScrollCineView.d.ts

@@ -0,0 +1,5 @@
+import { default as React } from 'react';
+import { CineViewRef, CineViewScrollModeProps } from '../../types';
+export declare const DirectScrollCineView: React.ForwardRefExoticComponent<Omit<CineViewScrollModeProps, "mode"> & {
+    mode?: "scroll";
+} & React.RefAttributes<CineViewRef>>;

package/dist/components/CineView/DragSceneStack.d.ts

@@ -0,0 +1,55 @@
+import { default as React, MutableRefObject } from 'react';
+import { MotionValue } from 'framer-motion';
+import { DragModeConfig, ScrollMode } from '../../types';
+import { DragRelease, DragReleaseInput, SceneManagerActions } from '../../hooks/useSceneManager';
+import { DragRenderLane, DragTakeoverSnapshot, SceneActivationRecord } from '../Scene/types';
+import { DragSceneTransaction, PreparedSceneInvalidation, PreparedSceneSnapshot } from '../Scene/dragPreparedState';
+interface DragSceneStackProps {
+    scenes: React.ReactElement[];
+    visibleSceneIndices: Set<number>;
+    currentScene: number;
+    totalScenes: number;
+    mode: ScrollMode;
+    dragConfig?: DragModeConfig;
+    dragProgress: number;
+    dragTimelineProgress: number;
+    renderProgress: number;
+    renderProgressMotion: MotionValue<number>;
+    timelineProgressMotion: MotionValue<number>;
+    isDragging: boolean;
+    sharedTimelineDurationMs: number;
+    dragRelease: DragRelease | null;
+    sceneActivations: ReadonlyMap<number, SceneActivationRecord>;
+    firstSceneEnterActive: boolean;
+    firstSceneEnterReady: boolean;
+    direction: 'forward' | 'backward' | null;
+    isAnimating: boolean;
+    viewportWidth: number;
+    viewportHeight: number;
+    sceneActions: SceneManagerActions;
+    sceneWrapperRefs: MutableRefObject<Array<HTMLDivElement | null>>;
+    /** CineView-owned shared render-lane slot (D-F1); stable ref. */
+    renderLaneRef: MutableRefObject<DragRenderLane | null>;
+    /** Synchronous baseline shared by the render and element lanes during takeover. */
+    takeoverSnapshot: MutableRefObject<DragTakeoverSnapshot | null>;
+    candidateSuspended: boolean;
+    onCandidateSuspensionChange: (suspended: boolean) => boolean;
+    onElementContinuationChange: (sceneIndex: number, active: boolean) => void;
+    onPointerSessionStart: () => void;
+    dragTransaction: DragSceneTransaction | null;
+    onPrepared: (snapshot: PreparedSceneSnapshot) => void;
+    onPreparedInvalidated: (invalidation: PreparedSceneInvalidation) => void;
+    onOwnershipRequest: (direction: 'forward' | 'backward') => boolean;
+    onSceneChange: (direction: 'forward' | 'backward', progressRatio?: number, committedElapsedMs?: number, timelineDuration?: number) => void;
+    onDragProgressChange: (progress: number) => void;
+    onRenderProgressChange?: (progress: number) => void;
+    onDragTimelineProgressChange: (progress: number) => void;
+    onDraggingChange: (dragging: boolean) => void;
+    onSharedTimelineDurationChange: (duration: number) => void;
+    onDragRelease: (release: DragReleaseInput | null) => void;
+    onDragReset: () => void;
+    onTransactionComplete: (transactionId: symbol) => void;
+    onFirstSceneEnterComplete: () => void;
+}
+export declare function DragSceneStack({ scenes, visibleSceneIndices, currentScene, totalScenes, mode, dragConfig, dragProgress, dragTimelineProgress, renderProgress, renderProgressMotion, timelineProgressMotion, isDragging, sharedTimelineDurationMs, dragRelease, sceneActivations, firstSceneEnterActive, firstSceneEnterReady, direction, isAnimating, viewportWidth, viewportHeight, sceneActions, sceneWrapperRefs, renderLaneRef, takeoverSnapshot, candidateSuspended, onCandidateSuspensionChange, onElementContinuationChange, onPointerSessionStart, dragTransaction, onPrepared, onPreparedInvalidated, onOwnershipRequest, onSceneChange, onDragProgressChange, onRenderProgressChange, onDragTimelineProgressChange, onDraggingChange, onSharedTimelineDurationChange, onDragRelease, onDragReset, onTransactionComplete, onFirstSceneEnterComplete, }: DragSceneStackProps): React.ReactElement;
+export {};

package/dist/components/CineView/ScrollSceneSlot.d.ts

@@ -0,0 +1,42 @@
+import { default as React } from 'react';
+import { buildSceneTimelineState, SceneAuthoringCompatProps, SceneLayoutInfo, ScrollInputDirection } from './directScrollHelpers';
+import { ScrollModeConfig } from '../../types';
+import { GroupedCallbacks } from './regroupCallbacks';
+import { SceneScrollTimelineState } from '../Scene/sceneScrollRuntime';
+import { KeyedScrollExternalStore } from '../runtime/scrollExternalStore';
+import { ScrollSceneFrameStore } from '../runtime/scrollSceneFrameStore';
+export interface ScrollSceneRenderSnapshot {
+    sceneLayout: SceneLayoutInfo | null;
+    sceneZoneState: SceneScrollTimelineState | null;
+    sceneTimelineState: ReturnType<typeof buildSceneTimelineState> | null;
+    isCurrent: boolean;
+    isBackdropActive: boolean;
+    visualViewportOffset: number;
+    isScrolling: boolean;
+    scrollDirection: ScrollInputDirection | null;
+    activeSceneIndex: number;
+    viewportWidth: number;
+    viewportHeight: number;
+    firstSceneEnterGateKnown: boolean;
+    firstSceneEnterActive: boolean;
+    firstSceneEnterReady: boolean;
+    direction: 'x' | 'y';
+    sceneCount: number;
+    sceneSizing: ScrollModeConfig['sceneSizing'];
+    exposeTakeoverDebugData: boolean;
+    takeoverSceneSpan: number | null;
+}
+export declare const EMPTY_SCROLL_SCENE_SNAPSHOT: ScrollSceneRenderSnapshot;
+export type ScrollSceneSnapshotList = readonly (ScrollSceneRenderSnapshot | undefined)[];
+export type ScrollSceneSnapshotStore = KeyedScrollExternalStore<ScrollSceneSnapshotList, number, ScrollSceneRenderSnapshot>;
+interface ScrollSceneSlotProps {
+    child: React.ReactElement<SceneAuthoringCompatProps>;
+    store: ScrollSceneSnapshotStore;
+    frameStore?: ScrollSceneFrameStore;
+    sceneIndex: number;
+    setWrapperRef: (sceneIndex: number, node: HTMLDivElement | null) => void;
+    scrollCallbacks?: GroupedCallbacks['scroll'];
+}
+export declare function areScrollSceneRenderSnapshotsEqual(previous: ScrollSceneRenderSnapshot, next: ScrollSceneRenderSnapshot): boolean;
+export declare const ScrollSceneSlot: React.NamedExoticComponent<ScrollSceneSlotProps>;
+export {};