cineview 0.0.1-beta

package/dist/components/Scene/sceneScrollBudget.d.ts

@@ -0,0 +1,38 @@
+export interface SceneScrollAnimationRegistration {
+    animateId: string;
+    delay: number;
+    enterDuration: number;
+    exitDuration: number;
+    after?: string;
+    phase?: {
+        start?: number;
+        end?: number;
+    };
+}
+export interface SceneScrollAnimationBudget {
+    animateId: string;
+    startMs: number;
+    enterStartMs: number;
+    enterEndMs: number;
+    exitStartMs: number | null;
+    exitEndMs: number | null;
+    totalEndMs: number;
+    startPx: number;
+    enterStartPx: number;
+    enterEndPx: number;
+    exitStartPx: number | null;
+    exitEndPx: number | null;
+    totalEndPx: number;
+    phaseStartPx?: number;
+    phaseEndPx?: number;
+    hasExit: boolean;
+}
+export interface ResolvedSceneScrollSequence {
+    budgets: Record<string, SceneScrollAnimationBudget>;
+    totalDurationMs: number;
+    totalBudgetPx: number;
+    /** Phase declarations ignored because their dependency timing has no finite solution. */
+    invalidPhaseIds?: string[];
+}
+export declare function resolveSceneScrollAnimationBudgets(registrations: Map<string, SceneScrollAnimationRegistration>): ResolvedSceneScrollSequence;
+export declare function areResolvedSceneScrollSequencesEqual(left: ResolvedSceneScrollSequence, right: ResolvedSceneScrollSequence): boolean;

package/dist/components/Scene/sceneScrollRuntime.d.ts

@@ -0,0 +1,65 @@
+import { ResolvedSceneScrollSequence, SceneScrollAnimationRegistration } from './sceneScrollBudget';
+import { KeyedScrollExternalStore } from '../runtime/scrollExternalStore';
+/**
+ * Scroll-offset residency of a zone's segment, quantized with a Schmitt trigger
+ * (task-flow 2026-08-14, Plan A "release when far / preload when near"):
+ * the near→far (release) transition fires beyond RELEASE margin past the
+ * segment; the far→near (preload) transition fires once the viewer returns
+ * within PRELOAD margin. The release margin is intentionally the *larger* of
+ * the two — a Schmitt trigger is only stable when the return threshold sits
+ * strictly inside the leave threshold, otherwise hovering between them flaps
+ * release/preload every frame. The timeline store still publishes continuous
+ * progress, so its listeners run during scrolling; selecting this discrete band
+ * keeps approach consumers render-silent until a threshold crossing. Consumed by
+ * AnimateVideo's `releaseOnLeave` to drop decoded video frames once the viewer
+ * has scrolled well past the zone.
+ */
+export type SceneScrollZoneApproach = 'inside' | 'near' | 'far';
+/** Beyond this distance past the segment the band flips to 'far' (release). */
+export declare const SCENE_SCROLL_APPROACH_FAR_VH = 1.5;
+/** Within this distance of the segment a 'far' band flips back to 'near' (preload). */
+export declare const SCENE_SCROLL_APPROACH_NEAR_VH = 1;
+export declare function resolveZoneApproachBand(distancePx: number, viewportSpan: number, previous: SceneScrollZoneApproach): SceneScrollZoneApproach;
+export interface SceneScrollTimelineState {
+    zoneId: string;
+    sceneIndex: number;
+    progressPx: number;
+    totalBudgetPx: number;
+    active: boolean;
+    direction: 'forward' | 'backward' | null;
+    sequence: ResolvedSceneScrollSequence;
+    approach: SceneScrollZoneApproach;
+}
+export interface SceneScrollRuntimeContextValue {
+    registerZone: (zoneId: string, config: {
+        sceneIndex: number;
+    }) => void;
+    unregisterZone: (zoneId: string, sceneIndex: number) => void;
+    setZoneElement: (zoneId: string, sceneIndex: number, element: HTMLElement | null) => void;
+    registerZoneAnimation: (zoneId: string, animation: SceneScrollAnimationRegistration) => SceneScrollAnimationRegistration;
+    unregisterZoneAnimation: (zoneId: string, animateId: string, owner: SceneScrollAnimationRegistration) => void;
+}
+export interface SceneScrollZoneTimelineSnapshot {
+    version?: number;
+    zoneStates: Record<string, SceneScrollTimelineState>;
+}
+export type SceneScrollTimelineStore = KeyedScrollExternalStore<Record<string, SceneScrollTimelineState>, string, SceneScrollTimelineState>;
+export interface SceneScrollZoneTimeline {
+    version?: number;
+    zoneStates?: Record<string, SceneScrollTimelineState>;
+    store?: SceneScrollTimelineStore;
+}
+export type SceneScrollZoneRuntime = SceneScrollRuntimeContextValue & SceneScrollZoneTimelineSnapshot & {
+    /** Stable keyed store for continuous progress consumers. */
+    store?: SceneScrollTimelineStore;
+};
+export declare const SceneScrollRuntimeContext: import('react').Context<SceneScrollRuntimeContextValue | null>;
+export declare const SceneScrollTimelineContext: import('react').Context<SceneScrollZoneTimeline | null>;
+export declare const SceneScrollTakeoverContext: import('react').Context<string | null>;
+export declare function useSceneScrollZoneSelection<T>(zoneId: string | null, enabled: boolean, select: (state: SceneScrollTimelineState | null) => T): T;
+/**
+ * Read only the discrete residency band. The keyed store still receives
+ * continuous progress snapshots, but React compares this primitive selection
+ * and skips consumer renders until the band actually changes.
+ */
+export declare function useSceneScrollZoneApproach(zoneId: string | null, enabled?: boolean): SceneScrollZoneApproach | null;

package/dist/components/Scene/types.d.ts

@@ -0,0 +1,189 @@
+import { AnimationType, DragThresholdConfig, DragTimelineUnit, SceneAnchor, SceneProps, SceneStackMode, ScrollMode, ScrollTimelineState } from '../../types';
+import { DragRelease, DragReleaseInput, ScrollTransitionSnapshot } from '../../hooks/useSceneManager';
+import { DragSceneTransaction, PreparedSceneInvalidation, PreparedSceneSnapshot } from './dragPreparedState';
+import { ScrollSceneFrameStore } from '../runtime/scrollSceneFrameStore';
+export type SceneState = 'initial' | 'entering' | 'active' | 'exiting';
+/**
+ * The single global render-lane slot (D-F1/D-F7). At most ONE render-lane
+ * tween (settle page-slide or bounce) exists at a time — renderProgress has
+ * one owner. The slot lets ANY scene's drag engine take over the in-flight
+ * lane on a new pointerdown, even when the lane was created by a DIFFERENT
+ * scene's engine (a rush re-grab mid-slide lands on whichever scene covers
+ * the touch point — usually the incoming one — while the lane still belongs
+ * to the releasing engine). CineView owns one shared ref; a standalone Scene
+ * falls back to an engine-local slot.
+ */
+export interface DragRenderLane {
+    kind: 'settle' | 'bounce';
+    /** The sceneIndex of the engine that created this lane (unmount cleanup). */
+    ownerSceneIndex: number;
+    /** Permanently stop this continuation. Used by teardown and superseding lanes. */
+    stop: () => void;
+    /**
+     * Reversibly pause at the current render position. A pointer-down candidate
+     * uses this before public drag ownership exists, so commit cannot race the
+     * direction/readiness gate.
+     */
+    suspend?: () => void;
+    /** Resume a previously suspended continuation from its frozen position. */
+    resume?: () => void;
+    /** Permanently discard a suspension after a candidate acquires ownership. */
+    preempt?: () => void;
+    /** Latest frozen/rendered progress, used to seed ownership without a stale React frame. */
+    getCurrent?: () => number;
+}
+/** Synchronous rush re-grab baseline shared across the render and element lanes. */
+export interface DragTakeoverSnapshot {
+    readonly token: number;
+    readonly sceneIndices: readonly number[];
+    readonly staleRatio: number;
+    readonly baseRatio: number | null;
+}
+export interface SceneLegacyCompatProps {
+    mode?: ScrollMode;
+    slideDirection?: 'x' | 'y';
+    slideDuration?: number;
+    sceneTransitionDuration?: number;
+    enterAnimation?: AnimationType;
+    exitAnimation?: AnimationType;
+    exitDuration?: number;
+    sceneWidth?: number | string;
+    sceneHeight?: number | string;
+    sceneAnchor?: SceneAnchor;
+    sceneZIndex?: number;
+    sceneOverflow?: 'hidden' | 'visible';
+    sceneStackMode?: SceneStackMode;
+    scrollSpeed?: number;
+    scrollControlled?: boolean;
+    scrollCommitThreshold?: number;
+    scrollReleaseDuration?: number;
+    scrollLockToSingleScene?: boolean;
+    scrollEnterLength?: number;
+    scrollHoldLength?: number;
+    scrollExitLength?: number;
+    onVisibilityChange?: (visible: boolean, progress: number) => void;
+    preloadImages?: string[];
+}
+export type SceneActivationKind = 'ready' | 'static' | 'commit' | 'programmatic';
+export interface SceneActivationRecord {
+    token: number;
+    kind: SceneActivationKind;
+}
+export interface SceneInternalProps extends SceneProps, SceneLegacyCompatProps {
+    runtimeMode?: ScrollMode;
+    runtimeDirection?: 'x' | 'y';
+    isActive?: boolean;
+    sceneIndex?: number;
+    totalScenes?: number;
+    currentSceneIndex?: number;
+    sceneRuntime?: {
+        mode?: ScrollMode;
+        direction?: 'x' | 'y';
+        isActive?: boolean;
+        sceneIndex?: number;
+        totalScenes?: number;
+        currentSceneIndex?: number;
+        transitionDirection?: 'forward' | 'backward' | null;
+        isSceneAnimating?: boolean;
+        sharedElapsedMs?: number;
+        sharedTimelineDurationMs?: number;
+        /** Monotonic formal-arrival token for this Scene in drag mode. */
+        activationToken?: number;
+        activationKind?: SceneActivationKind | null;
+        viewportWidth?: number;
+        viewportHeight?: number;
+        firstSceneEnterGateKnown?: boolean;
+        firstSceneEnterActive?: boolean;
+        firstSceneEnterReady?: boolean;
+    };
+    dragRuntime?: {
+        progress?: number;
+        renderProgress?: number;
+        timelineProgress?: number;
+        /** Shared per-frame render lane; the drag engine is its only writer. */
+        renderProgressMotion?: import('framer-motion').MotionValue<number>;
+        /** Shared per-frame ratio consumed by each Scene-owned element-track writer. */
+        timelineProgressMotion?: import('framer-motion').MotionValue<number>;
+        isDragging?: boolean;
+        release?: DragRelease | null;
+        threshold?: DragThresholdConfig;
+        /** Root/Scene-resolved mapping; omitted only for standalone legacy callers. */
+        dragMappingConfig?: {
+            unit: DragTimelineUnit;
+            scale: number;
+        };
+        /** Frozen playback data for the target scene; null when no transaction exists. */
+        transaction?: DragSceneTransaction | null;
+        /** Publishes only fully stable Scene preparation to the CineView owner. */
+        onPrepared?: (snapshot: PreparedSceneSnapshot) => void;
+        /** Exact instance/revision invalidation; stale cleanups are ignored by the owner. */
+        onPreparedInvalidated?: (invalidation: PreparedSceneInvalidation) => void;
+        /**
+         * Synchronous candidate preflight. Ownership is granted only after the root
+         * validates the target Scene's business flag and prepared snapshot, creates
+         * the driving transaction, and emits the directional drag-start callback.
+         */
+        onOwnershipRequest?: (direction: 'forward' | 'backward') => boolean;
+        /** Internal re-grab candidate state; never exposed as a public drag session. */
+        candidateSuspended?: boolean;
+        /** Returns true when an in-flight render/element continuation was suspended. */
+        onCandidateSuspensionChange?: (suspended: boolean) => boolean;
+        /** Synchronously registers whether this Scene owns a resumable element continuation. */
+        onElementContinuationChange?: (active: boolean) => void;
+        /** Authoritative cross-lane rush re-grab baseline, written at ownership. */
+        takeoverSnapshot?: import('react').MutableRefObject<DragTakeoverSnapshot | null>;
+        /** Internal pointer-session boundary used for callback de-duplication. */
+        onPointerSessionStart?: () => void;
+        onCommit?: (direction: 'forward' | 'backward', progressRatio: number, elapsedMs: number, timelineDuration?: number) => void;
+        onReset?: () => void;
+        onActivationComplete?: () => void;
+        /** Releases only the matching frozen playback transaction. */
+        onTransactionComplete?: (transactionId: symbol) => void;
+        onProgressChange?: (progress: number) => void;
+        onRenderProgressChange?: (progress: number) => void;
+        onTimelineProgressChange?: (progress: number) => void;
+        onSharedElapsedMsChange?: (elapsedMs: number) => void;
+        onDraggingChange?: (dragging: boolean) => void;
+        onSharedTimelineDurationChange?: (duration: number) => void;
+        onRelease?: (release: DragReleaseInput | null) => void;
+        /**
+         * CineView-owned shared render-lane slot (see {@link DragRenderLane}).
+         * Stable ref for the lifetime of the CineView instance.
+         */
+        renderLane?: import('react').MutableRefObject<DragRenderLane | null>;
+    };
+    scrollRuntime?: {
+        progress?: number;
+        isScrolling?: boolean;
+        direction?: 'forward' | 'backward' | null;
+        transitionSnapshot?: ScrollTransitionSnapshot | null;
+        backdropActive?: boolean;
+        timelineState?: ScrollTimelineState | null;
+        activeSceneIndex?: number;
+        viewportOffset?: number;
+        onProgressChange?: (progress: number) => void;
+        onDirectionChange?: (direction: 'forward' | 'backward' | null) => void;
+        onScrollingChange?: (scrolling: boolean) => void;
+        onCommit?: (direction: 'forward' | 'backward', progressRatio: number) => void;
+        onReset?: () => void;
+        /** Stable imperative frame lane; continuous scroll values never enter React props. */
+        frameStore?: ScrollSceneFrameStore;
+        sceneIndex?: number;
+    };
+    onDragGestureEnd?: (direction: 'forward' | 'backward', progressRatio: number, elapsedMs: number, timelineDuration?: number) => void;
+    onDragReset?: () => void;
+    onActivationComplete?: () => void;
+    onDragProgressChange?: (progress: number) => void;
+    onRenderProgressChange?: (progress: number) => void;
+    onDragTimelineProgressChange?: (progress: number) => void;
+    onSharedElapsedMsChange?: (elapsedMs: number) => void;
+    onDraggingChange?: (dragging: boolean) => void;
+    onSharedTimelineDurationChange?: (duration: number) => void;
+    onDragRelease?: (release: DragReleaseInput | null) => void;
+    onScrollProgressChange?: (progress: number) => void;
+    onScrollDirectionChange?: (direction: 'forward' | 'backward' | null) => void;
+    onScrollingChange?: (scrolling: boolean) => void;
+    onScrollCommit?: (direction: 'forward' | 'backward', progressRatio: number) => void;
+    onScrollReset?: () => void;
+    onSceneChange?: (direction: 'forward' | 'backward') => void;
+}

package/dist/components/Scene/useDragSceneEngine.d.ts

@@ -0,0 +1,67 @@
+import { Dispatch, MutableRefObject, SetStateAction } from 'react';
+import { useAnimation, MotionValue, PanInfo } from 'framer-motion';
+import { DragReleaseInput } from '../../hooks/useSceneManager';
+import { DragThresholdConfig, ScrollMode } from '../../types';
+import { DragRenderLane, DragTakeoverSnapshot, SceneState } from './types';
+type LegacyAnimationControls = ReturnType<typeof useAnimation>;
+export declare function calculateThreshold(velocity: number, config?: DragThresholdConfig): number;
+interface UseDragSceneEngineParams {
+    slideMode: ScrollMode;
+    isActive: boolean;
+    sceneIndex: number;
+    currentSceneIndex: number;
+    totalScenes: number;
+    slideDirection: 'x' | 'y';
+    slideDuration: number;
+    sceneTransitionDuration: number;
+    sceneOffset: number;
+    sceneState: SceneState;
+    thresholdConfig?: DragThresholdConfig;
+    globalDirection: 'forward' | 'backward' | null;
+    globalRenderProgress: number;
+    globalIsDragging: boolean;
+    globalDragProgress: number;
+    globalDragTimelineProgress: number;
+    controls: LegacyAnimationControls;
+    dragProgressMotion: MotionValue<number>;
+    setSceneState: Dispatch<SetStateAction<SceneState>>;
+    setIsAnimating: Dispatch<SetStateAction<boolean>>;
+    resolveDragProgress: (rawProgress: number) => number;
+    getTimelineDuration: () => number;
+    onDragProgressChange?: (progress: number) => void;
+    onRenderProgressChange?: (progress: number) => void;
+    onDragTimelineProgressChange?: (progress: number) => void;
+    /**
+     * Synchronous candidate preflight. The owner must atomically validate the
+     * direction and establish any frozen transaction before returning true.
+     */
+    onOwnershipRequest?: (direction: 'forward' | 'backward') => boolean;
+    /** Internal-only reversible candidate suspension state. Returns whether an element continuation exists. */
+    onCandidateSuspensionChange?: (suspended: boolean) => boolean;
+    /** Authoritative rush re-grab baseline shared with the target element track. */
+    takeoverSnapshot?: MutableRefObject<DragTakeoverSnapshot | null>;
+    onDraggingChange?: (dragging: boolean) => void;
+    onDragRelease?: (release: DragReleaseInput | null) => void;
+    /**
+     * CineView-owned shared render-lane slot (D-F1/D-F7). When provided, the
+     * settle page-slide / bounce tween this engine creates is registered globally
+     * so a NEW gesture starting on any other scene's engine can take it over (a
+     * rush re-grab mid-slide lands the pointerdown on whichever scene covers the
+     * touch point — usually the INCOMING one — which is a different engine than
+     * the one that owns the in-flight lane). Falls back to an engine-local slot
+     * for standalone scenes.
+     */
+    renderLaneRef?: MutableRefObject<DragRenderLane | null>;
+    completeReleaseImmediately?: boolean;
+    onDragEnd?: (direction: 'forward' | 'backward', progressRatio: number, elapsedMs: number, timelineDuration?: number) => void;
+    onDragReset?: () => void;
+}
+interface UseDragSceneEngineResult {
+    handleCandidateSuspend: () => boolean;
+    handleCandidateResume: () => void;
+    handleDragStart: (direction: 'forward' | 'backward') => boolean;
+    handlePan: (_event: MouseEvent | TouchEvent | PointerEvent, info: PanInfo) => void;
+    handlePanEnd: (_event: MouseEvent | TouchEvent | PointerEvent, info: PanInfo) => void;
+}
+export declare function useDragSceneEngine({ slideMode, isActive, sceneIndex, currentSceneIndex, totalScenes, slideDirection, slideDuration, sceneTransitionDuration, sceneOffset, sceneState, globalDirection, globalRenderProgress, globalIsDragging, globalDragProgress, globalDragTimelineProgress, controls, dragProgressMotion, setSceneState, setIsAnimating, resolveDragProgress, getTimelineDuration, onDragProgressChange, onRenderProgressChange, onDragTimelineProgressChange, onOwnershipRequest, onCandidateSuspensionChange, takeoverSnapshot, onDraggingChange, onDragRelease, renderLaneRef, completeReleaseImmediately, onDragEnd, onDragReset, thresholdConfig, }: UseDragSceneEngineParams): UseDragSceneEngineResult;
+export {};

package/dist/components/Scene/useElementTrack.d.ts

@@ -0,0 +1,82 @@
+import { MutableRefObject } from 'react';
+import { MotionValue } from 'framer-motion';
+import { ScrollMode } from '../../types';
+import { DragRelease } from '../../hooks/useSceneManager';
+import { ResolvedDragTimelineConfig } from '../../utils/dragTimelineMapping';
+import { DragSceneTransaction, PreparedSceneSnapshot } from './dragPreparedState';
+import { DragTakeoverSnapshot } from './types';
+/**
+ * useElementTrack — the per-scene element-timeline driver (two-track model,
+ * 2026-06-25).
+ *
+ * SINGLE WRITER invariant: the scene's element track (`elementElapsedMotion`,
+ * elapsed ms of ITS OWN enter timeline T = delay + duration) is written ONLY by
+ * this hook, for this scene. There is no global element scalar and no cross-scene
+ * write path. Across a drag commit the Scene instance is stable (`key={index}`,
+ * window current±1), so an in-flight `animate()` on the track survives the commit
+ * and continues uninterrupted — continuous completion, never a replay, never a
+ * freeze.
+ *
+ * Four driver sources, mutually exclusive in time, all routed through one
+ * controls ref so a new source preempts the previous one:
+ *  - follow-finger: while dragging and this scene is incoming, elapsed = r * T.
+ *  - release-settle: on a switch release targeting this scene, continue
+ *    current -> T at NATURAL rate, in PARALLEL with the render lane.
+ *  - release-bounce: on a non-switch release targeting this scene, return -> 0.
+ *  - cold-start: scene 0's one-shot first-screen enter, 0 -> T at real-time rate,
+ *    with extend-on-growth as the local registry duration grows.
+ *
+ * StrictMode/double-invoke safe: every animate()/stop() is token-guarded via
+ * `releaseTokenRef`, and the cold-start runs at most once via `coldStartRanRef`.
+ */
+interface UseElementTrackParams {
+    slideMode: ScrollMode;
+    isActive: boolean;
+    sceneIndex: number;
+    sceneOffset: number;
+    globalDirection: 'forward' | 'backward' | null;
+    globalIsDragging: boolean;
+    /** Internal re-grab candidate hold; no public drag session exists yet. */
+    candidateSuspended?: boolean;
+    /** Signed render position; its sign gives the live drag direction mid-drag. */
+    globalRenderProgress: number;
+    renderProgressMotion?: MotionValue<number>;
+    /** r — the drag timeline ratio in [0, 1] (abs of the drag fraction). */
+    globalDragTimelineProgress: number;
+    dragTimelineProgressMotion?: MotionValue<number>;
+    /** The single read-only release directive published by the outgoing scene. */
+    dragRelease: DragRelease | null;
+    /**
+     * Cold-start START trigger for scene 0: turns true once first-screen priority
+     * assets are ready (or are forced ready). Distinct from the window flag
+     * `firstSceneEnterActive` (which holds the scene at its initial frame and is
+     * read by useAnimateDrag): a true window with a false ready means "held at
+     * initial, not yet entering" (pre-load and the preventDefault path).
+     */
+    firstSceneEnterReady: boolean;
+    elementElapsedMotion: MotionValue<number>;
+    getTimelineDuration: () => number;
+    /** Registry-aware timeline duration trigger; retained for legacy direct hook callers. */
+    timelineDurationState: number;
+    /** CineView-owned immutable playback transaction for this target scene. */
+    dragTransaction?: DragSceneTransaction | null;
+    /** Latest stable local snapshot; captured once for cold-start/standalone playback. */
+    preparedSnapshot?: PreparedSceneSnapshot | null;
+    /** Scene calls require a prepared snapshot; direct legacy tests may omit it. */
+    requirePreparedSnapshot?: boolean;
+    /** Legacy mapping fallback used only when no frozen playback source exists. */
+    dragMappingConfig?: ResolvedDragTimelineConfig;
+    /** Authoritative rush re-grab baseline written synchronously at ownership. */
+    takeoverSnapshot?: MutableRefObject<DragTakeoverSnapshot | null>;
+    /** Synchronously reports whether a settle/bounce continuation can be suspended. */
+    onElementContinuationChange?: (active: boolean) => void;
+    /** Fired when the element track reaches T (settle / cold-start complete). */
+    onSettleComplete?: () => void;
+    onColdStartComplete?: () => void;
+}
+export interface ElementTrackCommands {
+    completeImmediately: () => void;
+    resetImmediately: () => void;
+}
+export declare function useElementTrack({ slideMode, isActive, sceneIndex, sceneOffset, globalDirection, globalIsDragging, candidateSuspended, globalRenderProgress, globalDragTimelineProgress, renderProgressMotion, dragTimelineProgressMotion, dragRelease, firstSceneEnterReady, elementElapsedMotion, getTimelineDuration, timelineDurationState, dragTransaction, preparedSnapshot, requirePreparedSnapshot, dragMappingConfig, takeoverSnapshot, onElementContinuationChange, onSettleComplete, onColdStartComplete, }: UseElementTrackParams): ElementTrackCommands;
+export {};

package/dist/components/Scene/useNativePointerDrag.d.ts

@@ -0,0 +1,25 @@
+import { MutableRefObject, PointerEvent as ReactPointerEvent } from 'react';
+import { PanInfo } from 'framer-motion';
+interface UseNativePointerDragParams {
+    enabled: boolean;
+    axis: 'x' | 'y';
+    /** Reversibly pauses an in-flight continuation for this pointer candidate. */
+    onCandidateStart?: () => boolean;
+    /** Restores a paused continuation when the candidate ends without ownership. */
+    onCandidateEnd?: () => void;
+    /** Marks a fresh physical pointer session for root-level callback de-duplication. */
+    onPointerSessionStart?: () => void;
+    /** Returns true only when the direction gate grants drag ownership. */
+    onStart: (direction: 'forward' | 'backward') => boolean;
+    onPan: (event: PointerEvent, info: PanInfo) => void;
+    onEnd: (event: PointerEvent, info: PanInfo) => void;
+}
+export interface NativePointerDragHandlers {
+    onPointerDown: (event: ReactPointerEvent<HTMLElement>) => void;
+    onPointerMove: (event: ReactPointerEvent<HTMLElement>) => void;
+    onPointerUp: (event: ReactPointerEvent<HTMLElement>) => void;
+    onPointerCancel: (event: ReactPointerEvent<HTMLElement>) => void;
+    isActiveRef: MutableRefObject<boolean>;
+}
+export declare function useNativePointerDrag({ enabled, axis, onCandidateStart, onCandidateEnd, onPointerSessionStart, onStart, onPan, onEnd, }: UseNativePointerDragParams): NativePointerDragHandlers;
+export {};

package/dist/components/Scene/useSceneAnimationRegistry.d.ts

@@ -0,0 +1,56 @@
+import { AnimateRegistrationInfo, AnimateTimelineLane, FrozenAnimationRegistrySnapshot } from '../../animations/registry';
+import { ParsedAnimationVariant } from '../../types';
+import { CineviewRuntimeContextValue } from '../runtime/runtimeContext';
+interface UseSceneAnimationRegistryParams {
+    sceneIndex: number;
+    baseDuration: number;
+    reportError?: CineviewRuntimeContextValue['reportError'];
+    onStableSnapshot?: (snapshot: FrozenAnimationRegistrySnapshot, revision: number, enterVariantsByAnimateId: ReadonlyMap<string, ParsedAnimationVariant>) => void;
+}
+export interface ScenePreparationLease {
+    /** Publish synchronously when this generation parsed and registered successfully. */
+    complete: () => void;
+    /** Release a superseded/unmounted generation without publishing a transient snapshot. */
+    cancel: () => void;
+}
+export type AfterInvalidReason = 'missing' | 'cycle' | 'duplicate' | 'leader-unregistered' | 'incompatible-lane';
+export type AfterOutcome = {
+    kind: 'pending';
+    leaderId: string;
+    generation?: number;
+} | {
+    kind: 'satisfied';
+    source: 'none' | 'completed';
+    leaderId?: string;
+    generation?: number;
+} | {
+    kind: 'invalid';
+    leaderId: string;
+    reason: AfterInvalidReason;
+};
+export interface SceneAnimationRegistrationLease {
+    readonly animateId: string;
+    readonly generation: number;
+    getCalculatedDelay: () => number;
+    setEnterVariant?: (variant: ParsedAnimationVariant) => void;
+    observeAfter: (listener: (outcome: AfterOutcome) => void) => () => void;
+    publishEnterCompleted: () => void;
+    dispose: () => void;
+}
+export interface SceneAnimationLaneDeclarationLease {
+    dispose: () => void;
+}
+export interface SceneAnimationRegistryPort {
+    timelineDuration: number;
+    isStable: boolean;
+    beginPreparation: () => ScenePreparationLease;
+    registerAnimate: (id: string, info: AnimateRegistrationInfo) => SceneAnimationRegistrationLease;
+    /** Declare a non-scene lane for dependency diagnostics without extending T_self. */
+    declareAnimateLane: (id: string, lane: AnimateTimelineLane) => SceneAnimationLaneDeclarationLease;
+    /** Legacy registration adapter for callers not yet migrated to lease.dispose(). */
+    unregisterAnimate: (id: string) => void;
+    getCalculatedDelay: (animateId: string) => number;
+    getTimelineDuration: () => number;
+}
+export declare function useSceneAnimationRegistry({ sceneIndex, baseDuration, reportError, onStableSnapshot, }: UseSceneAnimationRegistryParams): SceneAnimationRegistryPort;
+export {};

package/dist/components/Scene/useScenePointerInput.d.ts

@@ -0,0 +1,28 @@
+import { PointerEventHandler } from 'react';
+import { PanInfo } from 'framer-motion';
+type PanEvent = MouseEvent | TouchEvent | PointerEvent;
+interface UseScenePointerInputParams {
+    enabled: boolean;
+    axis: 'x' | 'y';
+    onCandidateStart?: () => boolean;
+    onCandidateEnd?: () => void;
+    onPointerSessionStart?: () => void;
+    onDragStart: (direction: 'forward' | 'backward') => boolean;
+    onPan: (event: PanEvent, info: PanInfo) => void;
+    onPanEnd: (event: PanEvent, info: PanInfo) => void;
+    authoredPointerDown?: PointerEventHandler<HTMLDivElement>;
+    authoredPointerMove?: PointerEventHandler<HTMLDivElement>;
+    authoredPointerUp?: PointerEventHandler<HTMLDivElement>;
+    authoredPointerCancel?: PointerEventHandler<HTMLDivElement>;
+}
+export interface ScenePointerInput {
+    onPointerDown: PointerEventHandler<HTMLDivElement>;
+    onPointerMove: PointerEventHandler<HTMLDivElement>;
+    onPointerUp: PointerEventHandler<HTMLDivElement>;
+    onPointerCancel: PointerEventHandler<HTMLDivElement>;
+    onFramerPanStart: () => void;
+    onFramerPan: (event: PanEvent, info: PanInfo) => void;
+    onFramerPanEnd: (event: PanEvent, info: PanInfo) => void;
+}
+export declare function useScenePointerInput({ enabled, axis, onCandidateStart, onCandidateEnd, onPointerSessionStart, onDragStart, onPan, onPanEnd, authoredPointerDown, authoredPointerMove, authoredPointerUp, authoredPointerCancel, }: UseScenePointerInputParams): ScenePointerInput;
+export {};

package/dist/components/Scene/useSceneRuntimeState.d.ts

@@ -0,0 +1,17 @@
+import { SceneRuntimeState } from '../Animate/Animate';
+import { ScrollMode, ScrollTimelineState } from '../../types';
+import { SceneState } from './types';
+interface UseSceneRuntimeStateParams {
+    slideMode: ScrollMode;
+    sceneState: SceneState;
+    isActive: boolean;
+    sceneOffset: number;
+    globalScrollProgress: number;
+    globalScrollDirection: 'forward' | 'backward' | null;
+    globalIsScrolling: boolean;
+    globalScrollBackdropActive: boolean;
+    hasExitAnimation: boolean;
+    scrollTimelineState?: ScrollTimelineState | null;
+}
+export declare function useSceneRuntimeState({ slideMode, sceneState, isActive, sceneOffset, globalScrollProgress, globalScrollDirection, globalIsScrolling, globalScrollBackdropActive, hasExitAnimation, scrollTimelineState, }: UseSceneRuntimeStateParams): SceneRuntimeState;
+export {};

package/dist/components/Scene/useSceneScrollTakeover.d.ts

@@ -0,0 +1,13 @@
+import { RefObject } from 'react';
+import { ScrollMode } from '../../types';
+interface SceneScrollTakeoverConfig {
+    sceneId?: string;
+    sceneIndex: number;
+    mode: ScrollMode;
+    scroll?: {
+        zoneId?: string;
+    };
+    elementRef: RefObject<HTMLElement | null>;
+}
+export declare function useSceneScrollTakeover({ sceneId, sceneIndex, mode, scroll, elementRef, }: SceneScrollTakeoverConfig): string | null;
+export {};

package/dist/components/Scene/useScrollSceneEngine.d.ts

@@ -0,0 +1,28 @@
+import { Dispatch, SetStateAction } from 'react';
+import { useAnimation } from 'framer-motion';
+import { ScrollMode, ScrollTimelineState } from '../../types';
+import { PresetAnimation } from '../../animations/presets';
+import { ScrollTransitionSnapshot } from '../../hooks/useSceneManager';
+import { SceneState } from './types';
+import { ScrollSceneFrameStore } from '../runtime/scrollSceneFrameStore';
+type LegacyAnimationControls = ReturnType<typeof useAnimation>;
+interface UseScrollSceneEngineParams {
+    slideMode: ScrollMode;
+    isActive: boolean;
+    sceneOffset: number;
+    sceneStackMode: 'replace' | 'cover';
+    controls: LegacyAnimationControls;
+    enterVariant: PresetAnimation | null;
+    exitVariant: PresetAnimation | null;
+    globalIsScrolling: boolean;
+    globalScrollProgress: number;
+    globalScrollDirection: 'forward' | 'backward' | null;
+    globalScrollTransitionSnapshot: ScrollTransitionSnapshot | null;
+    globalScrollBackdropActive: boolean;
+    globalScrollTimelineState: ScrollTimelineState | null;
+    scrollFrameStore?: ScrollSceneFrameStore;
+    scrollFrameSceneIndex?: number;
+    setSceneState: Dispatch<SetStateAction<SceneState>>;
+}
+export declare function useScrollSceneEngine({ slideMode, isActive, sceneOffset, sceneStackMode, controls, enterVariant, exitVariant, globalIsScrolling, globalScrollProgress, globalScrollDirection, globalScrollTransitionSnapshot, globalScrollBackdropActive, globalScrollTimelineState, scrollFrameStore, scrollFrameSceneIndex, setSceneState, }: UseScrollSceneEngineParams): void;
+export {};

package/dist/components/runtime/runtimeContext.d.ts

@@ -0,0 +1,14 @@
+import { ScrollMode } from '../../types';
+export interface CineviewRuntimeContextValue {
+    mode: ScrollMode;
+    reportError?: (detail: {
+        code: string;
+        message: string;
+        context?: Record<string, unknown>;
+    }) => void;
+    scrollEnterMargin?: number;
+    scrollExitMargin?: number;
+    prefersReducedMotion?: boolean;
+}
+export declare const CineviewRuntimeContext: import('react').Context<CineviewRuntimeContextValue | null>;
+export declare function useCineviewRuntimeContext(): CineviewRuntimeContextValue | null;

package/dist/components/runtime/scrollExternalStore.d.ts

@@ -0,0 +1,13 @@
+export interface ScrollExternalStore<T> {
+    getSnapshot: () => T;
+    subscribe: (listener: () => void) => () => void;
+    setSnapshot: (next: T) => void;
+}
+export interface KeyedScrollExternalStore<T, K extends PropertyKey, V> {
+    getSnapshot: () => T;
+    setSnapshot: (next: T) => void;
+    getKeySnapshot: (key: K) => V | undefined;
+    subscribeKey: (key: K, listener: () => void) => () => void;
+}
+export declare function createScrollExternalStore<T>(initialSnapshot: T): ScrollExternalStore<T>;
+export declare function createKeyedScrollExternalStore<T, K extends PropertyKey, V>(initialSnapshot: T, selectValue: (snapshot: T, key: K) => V | undefined): KeyedScrollExternalStore<T, K, V>;