layershift 0.1.0

package/dist/types/components/layershift/global.d.ts

@@ -0,0 +1,35 @@
+/**
+ * JSX IntrinsicElements declaration for the <layershift-parallax> custom element.
+ *
+ * Reference this file in your tsconfig.json to get TypeScript support
+ * for the custom element in React/JSX projects:
+ *
+ *   "compilerOptions": {
+ *     "types": ["layershift/global"]
+ *   }
+ */
+
+import type { LayershiftProps } from './types';
+
+declare global {
+  namespace JSX {
+    interface IntrinsicElements {
+      'layershift-parallax': React.DetailedHTMLProps<
+        React.HTMLAttributes<HTMLElement> & {
+          src?: string;
+          'depth-src'?: string;
+          'depth-meta'?: string;
+          'parallax-x'?: number | string;
+          'parallax-y'?: number | string;
+          'parallax-max'?: number | string;
+          layers?: number | string;
+          overscan?: number | string;
+          autoplay?: boolean | string;
+          loop?: boolean | string;
+          muted?: boolean | string;
+        },
+        HTMLElement
+      >;
+    }
+  }
+}

package/dist/types/components/layershift/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Entry point for the <layershift-parallax> Web Component.
+ *
+ * Importing this module registers the custom element with the browser.
+ * After registration, <layershift-parallax> can be used in any HTML document.
+ */
+import { LayershiftElement } from './layershift-element';
+export { LayershiftElement };
+export type { LayershiftProps } from './types';
+export type { LayershiftEventMap, LayershiftReadyDetail, LayershiftPlayDetail, LayershiftPauseDetail, LayershiftLoopDetail, LayershiftFrameDetail, LayershiftErrorDetail, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/components/layershift/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/components/layershift/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAMzD,OAAO,EAAE,iBAAiB,EAAE,CAAC;AAC7B,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,YAAY,EACV,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,SAAS,CAAC"}

package/dist/types/components/layershift/layershift-element.d.ts

@@ -0,0 +1,56 @@
+/**
+ * <layershift-parallax> Web Component
+ *
+ * A self-contained Custom Element that renders a depth-aware parallax
+ * video effect. Encapsulates the entire Three.js pipeline inside a
+ * Shadow DOM — consumers just drop in the tag and provide asset URLs.
+ *
+ * Usage:
+ *   <layershift-parallax
+ *     src="video.mp4"
+ *     depth-src="depth-data.bin"
+ *     depth-meta="depth-meta.json"
+ *   ></layershift-parallax>
+ */
+export declare class LayershiftElement extends HTMLElement {
+    static readonly TAG_NAME = "layershift-parallax";
+    static get observedAttributes(): string[];
+    private shadow;
+    private container;
+    private renderer;
+    private inputHandler;
+    private depthWorker;
+    private video;
+    private initialized;
+    private abortController;
+    private loopCount;
+    constructor();
+    private getAttrFloat;
+    private getAttrBool;
+    private get parallaxX();
+    private get parallaxY();
+    private get parallaxMax();
+    private get overscan();
+    private get shouldAutoplay();
+    private get shouldLoop();
+    private get shouldMute();
+    /**
+     * Dispatch a namespaced custom event that bubbles through Shadow DOM.
+     * All events use the `layershift-parallax:` prefix and are `composed`
+     * so consumers can listen on the host element from the light DOM.
+     */
+    private emit;
+    /**
+     * Attach native video event listeners and re-dispatch them
+     * as namespaced custom events on the host element.
+     */
+    private attachVideoEventListeners;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(_name: string, _oldVal: string | null, _newVal: string | null): void;
+    private setupShadowDOM;
+    private init;
+    private createVideoElement;
+    private dispose;
+}
+//# sourceMappingURL=layershift-element.d.ts.map

package/dist/types/components/layershift/layershift-element.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layershift-element.d.ts","sourceRoot":"","sources":["../../../../src/components/layershift/layershift-element.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAmIH,qBAAa,iBAAkB,SAAQ,WAAW;IAChD,MAAM,CAAC,QAAQ,CAAC,QAAQ,yBAAyB;IAEjD,MAAM,KAAK,kBAAkB,IAAI,MAAM,EAAE,CAOxC;IAED,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,QAAQ,CAAiC;IACjD,OAAO,CAAC,YAAY,CAAsC;IAC1D,OAAO,CAAC,WAAW,CAAwC;IAC3D,OAAO,CAAC,KAAK,CAAiC;IAC9C,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,SAAS,CAAK;;IAStB,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,WAAW;IASnB,OAAO,KAAK,SAAS,GAA0E;IAC/F,OAAO,KAAK,SAAS,GAA0E;IAC/F,OAAO,KAAK,WAAW,GAA8E;IACrG,OAAO,KAAK,QAAQ,GAAuE;IAC3F,OAAO,KAAK,cAAc,GAAuE;IACjG,OAAO,KAAK,UAAU,GAA+D;IACrF,OAAO,KAAK,UAAU,GAAiE;IAIvF;;;;OAIG;IACH,OAAO,CAAC,IAAI;IAUZ;;;OAGG;IACH,OAAO,CAAC,yBAAyB;IA2BjC,iBAAiB,IAAI,IAAI;IAKzB,oBAAoB,IAAI,IAAI;IAI5B,wBAAwB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAgB7F,OAAO,CAAC,cAAc;YAkCR,IAAI;YAsJJ,kBAAkB;IAuChC,OAAO,CAAC,OAAO;CAyBhB"}

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

@@ -0,0 +1,65 @@
+export interface LayershiftProps {
+    src: string;
+    depthSrc: string;
+    depthMeta: string;
+    parallaxX?: number;
+    parallaxY?: number;
+    parallaxMax?: number;
+    layers?: number;
+    overscan?: number;
+    autoplay?: boolean;
+    loop?: boolean;
+    muted?: boolean;
+    className?: string;
+    style?: Record<string, string>;
+}
+/** Fired once after initialization completes successfully. */
+export interface LayershiftReadyDetail {
+    videoWidth: number;
+    videoHeight: number;
+    duration: number;
+    /** Depth analysis profile (present when depth data was analyzed). */
+    depthProfile?: import('../../depth-analysis').DepthProfile;
+    /** Parameters derived from depth analysis (present when depth data was analyzed). */
+    derivedParams?: import('../../depth-analysis').DerivedParallaxParams;
+}
+/** Fired when video starts playing. */
+export interface LayershiftPlayDetail {
+    currentTime: number;
+}
+/** Fired when video pauses. */
+export interface LayershiftPauseDetail {
+    currentTime: number;
+}
+/** Fired when video loops back to start. */
+export interface LayershiftLoopDetail {
+    loopCount: number;
+}
+/** Fired on each new video frame (via requestVideoFrameCallback when available). */
+export interface LayershiftFrameDetail {
+    currentTime: number;
+    frameNumber: number;
+}
+/** Fired on initialization errors. */
+export interface LayershiftErrorDetail {
+    message: string;
+}
+/**
+ * Map of all custom events dispatched by `<layershift-parallax>`.
+ *
+ * Usage with addEventListener:
+ * ```ts
+ * el.addEventListener('layershift-parallax:ready', (e) => {
+ *   console.log(e.detail.videoWidth, e.detail.duration);
+ * });
+ * ```
+ */
+export interface LayershiftEventMap {
+    'layershift-parallax:ready': CustomEvent<LayershiftReadyDetail>;
+    'layershift-parallax:play': CustomEvent<LayershiftPlayDetail>;
+    'layershift-parallax:pause': CustomEvent<LayershiftPauseDetail>;
+    'layershift-parallax:loop': CustomEvent<LayershiftLoopDetail>;
+    'layershift-parallax:frame': CustomEvent<LayershiftFrameDetail>;
+    'layershift-parallax:error': CustomEvent<LayershiftErrorDetail>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/components/layershift/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/components/layershift/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAMD,8DAA8D;AAC9D,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,YAAY,CAAC,EAAE,OAAO,sBAAsB,EAAE,YAAY,CAAC;IAC3D,qFAAqF;IACrF,aAAa,CAAC,EAAE,OAAO,sBAAsB,EAAE,qBAAqB,CAAC;CACtE;AAED,uCAAuC;AACvC,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,+BAA+B;AAC/B,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,4CAA4C;AAC5C,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,oFAAoF;AACpF,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,sCAAsC;AACtC,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC,2BAA2B,EAAE,WAAW,CAAC,qBAAqB,CAAC,CAAC;IAChE,0BAA0B,EAAE,WAAW,CAAC,oBAAoB,CAAC,CAAC;IAC9D,2BAA2B,EAAE,WAAW,CAAC,qBAAqB,CAAC,CAAC;IAChE,0BAA0B,EAAE,WAAW,CAAC,oBAAoB,CAAC,CAAC;IAC9D,2BAA2B,EAAE,WAAW,CAAC,qBAAqB,CAAC,CAAC;IAChE,2BAA2B,EAAE,WAAW,CAAC,qBAAqB,CAAC,CAAC;CACjE"}

package/dist/types/depth-analysis.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Depth analysis and parameter derivation for adaptive parallax tuning.
+ *
+ * This module provides two pure functions:
+ *
+ * 1. `analyzeDepthFrames()` — computes a statistical DepthProfile from
+ *    precomputed depth frames (histogram, percentiles, bimodality).
+ *
+ * 2. `deriveParallaxParams()` — maps a DepthProfile to concrete parallax
+ *    renderer parameters using continuous functions with algebraic
+ *    calibration guarantees.
+ *
+ * ## Calibration invariant
+ *
+ * The derivation formulas are designed so that the "average scene"
+ * (effectiveRange=0.50, bimodality=0.40) produces the exact current
+ * hardcoded defaults. This is an algebraic identity, not an approximation.
+ *
+ * ## Performance
+ *
+ * Both functions run once at initialization. analyzeDepthFrames samples
+ * up to 5 deterministically-chosen frames (~1.3M pixels at 512×512),
+ * completing in <5ms. deriveParallaxParams is O(1) arithmetic.
+ *
+ * ## Determinism
+ *
+ * Identical input always produces identical output. No randomness,
+ * no environment queries, no side effects.
+ */
+/**
+ * Statistical profile of a video's depth distribution.
+ * Computed once from precomputed depth frames at initialization.
+ */
+export interface DepthProfile {
+    /** Mean depth value, normalized [0, 1]. */
+    mean: number;
+    /** Standard deviation of depth [0, ~0.5]. */
+    stdDev: number;
+    /** 5th percentile depth [0, 1]. */
+    p5: number;
+    /** 25th percentile depth [0, 1]. */
+    p25: number;
+    /** Median (50th percentile) depth [0, 1]. */
+    median: number;
+    /** 75th percentile depth [0, 1]. */
+    p75: number;
+    /** 95th percentile depth [0, 1]. */
+    p95: number;
+    /** Effective depth range: p95 - p5. [0, 1]. */
+    effectiveRange: number;
+    /** Interquartile range: p75 - p25. [0, 1]. */
+    iqr: number;
+    /**
+     * Bimodality score [0, 1]. Higher values indicate two distinct
+     * depth clusters (clear foreground/background separation).
+     */
+    bimodality: number;
+    /** Normalized 256-bin histogram (sums to 1.0). */
+    histogram: Float32Array;
+}
+/**
+ * Parallax parameters derived from depth analysis.
+ * All values are clamped to safe bounds.
+ */
+export interface DerivedParallaxParams {
+    parallaxStrength: number;
+    contrastLow: number;
+    contrastHigh: number;
+    verticalReduction: number;
+    dofStart: number;
+    dofStrength: number;
+    pomSteps: number;
+    overscanPadding: number;
+}
+/**
+ * Compute a statistical depth profile from precomputed depth frames.
+ *
+ * Samples up to 5 deterministically-chosen frames to build a 256-bin
+ * histogram, then extracts percentiles, mean, stdDev, and bimodality.
+ *
+ * @param frames - Array of Uint8Array depth frames (0=near, 255=far).
+ * @param width  - Frame width in pixels (e.g. 512).
+ * @param height - Frame height in pixels (e.g. 512).
+ * @returns DepthProfile with all statistics. If frames is empty, returns
+ *   a degenerate profile that will trigger rejection in deriveParallaxParams.
+ */
+export declare function analyzeDepthFrames(frames: Uint8Array[], width: number, height: number): DepthProfile;
+/**
+ * Derive parallax renderer parameters from a depth profile.
+ *
+ * All derivations are continuous functions of depth statistics.
+ * No discrete scene classification. No branching on semantic interpretation.
+ *
+ * Calibration invariant: when effectiveRange=0.50 and bimodality=0.40,
+ * every derived parameter equals the current production default exactly.
+ *
+ * If the depth profile indicates degenerate data (effectiveRange < 0.05
+ * or stdDev < 0.02), returns the exact calibrated defaults.
+ *
+ * @param profile - DepthProfile from analyzeDepthFrames().
+ * @returns DerivedParallaxParams with all values clamped to safe bounds.
+ */
+export declare function deriveParallaxParams(profile: DepthProfile): DerivedParallaxParams;
+//# sourceMappingURL=depth-analysis.d.ts.map

package/dist/types/depth-analysis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"depth-analysis.d.ts","sourceRoot":"","sources":["../../src/depth-analysis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAMH;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IAEb,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IAEf,mCAAmC;IACnC,EAAE,EAAE,MAAM,CAAC;IAEX,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;IAEZ,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IAEf,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;IAEZ,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;IAEZ,+CAA+C;IAC/C,cAAc,EAAE,MAAM,CAAC;IAEvB,8CAA8C;IAC9C,GAAG,EAAE,MAAM,CAAC;IAEZ;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB,kDAAkD;IAClD,SAAS,EAAE,YAAY,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;CACzB;AAyBD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,UAAU,EAAE,EACpB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,YAAY,CAgFd;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,YAAY,GAAG,qBAAqB,CAwDjF"}

package/dist/types/input-handler.d.ts

@@ -0,0 +1,22 @@
+export interface ParallaxInput {
+    x: number;
+    y: number;
+}
+export declare class InputHandler {
+    private readonly motionLerpFactor;
+    private pointerTarget;
+    private motionTarget;
+    private smoothedOutput;
+    private usingMotionInput;
+    private motionListenerAttached;
+    constructor(motionLerpFactor: number);
+    get isMotionSupported(): boolean;
+    get isMotionEnabled(): boolean;
+    enableMotionControls(): Promise<boolean>;
+    update(): ParallaxInput;
+    dispose(): void;
+    private readonly handleMouseMove;
+    private readonly resetPointerTarget;
+    private readonly handleDeviceOrientation;
+}
+//# sourceMappingURL=input-handler.d.ts.map

package/dist/types/input-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-handler.d.ts","sourceRoot":"","sources":["../../src/input-handler.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAMD,qBAAa,YAAY;IAOX,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IAN7C,OAAO,CAAC,aAAa,CAAiC;IACtD,OAAO,CAAC,YAAY,CAAiC;IACrD,OAAO,CAAC,cAAc,CAAiC;IACvD,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,sBAAsB,CAAS;gBAEV,gBAAgB,EAAE,MAAM;IAKrD,IAAI,iBAAiB,IAAI,OAAO,CAkB/B;IAED,IAAI,eAAe,IAAI,OAAO,CAE7B;IAEK,oBAAoB,IAAI,OAAO,CAAC,OAAO,CAAC;IAsB9C,MAAM,IAAI,aAAa;IAgBvB,OAAO,IAAI,IAAI;IASf,OAAO,CAAC,QAAQ,CAAC,eAAe,CAK9B;IAEF,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAGjC;IAEF,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAOtC;CACH"}

package/dist/types/parallax-renderer.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Parallax Renderer — GPU-accelerated depth-aware video parallax.
+ *
+ * Renders a single full-viewport plane textured with the source video
+ * (via THREE.VideoTexture) and a precomputed depth map. A custom
+ * fragment shader displaces UV coordinates per-pixel based on the
+ * depth value and current mouse/gyro input, creating a continuous
+ * parallax effect with no discrete layer banding.
+ *
+ * ## Rendering pipeline (per frame)
+ *
+ * 1. THREE.VideoTexture auto-updates from the <video> element,
+ *    providing the color frame at native display resolution.
+ *
+ * 2. The depth interpolator produces a Uint8Array for the current
+ *    playback time (interpolated between precomputed 5fps keyframes,
+ *    bilateral-filtered on the CPU, then quantized to 0-255).
+ *    This is copied into a single-channel DataTexture on the GPU.
+ *
+ * 3. The InputHandler provides a smoothed {x, y} offset in [-1, 1].
+ *    This is passed to the shader as the uOffset uniform.
+ *
+ * 4. The fragment shader samples the depth map at each pixel's UV,
+ *    computes a UV displacement proportional to (1 - depth) * strength,
+ *    and samples the video texture at the displaced coordinates.
+ *    Near objects (depth ≈ 0) move more; far objects (depth ≈ 1) less.
+ *
+ * 5. When POM is enabled, the shader ray-marches through the depth
+ *    field to find the correct surface intersection, producing
+ *    self-occlusion (near objects cover far objects behind them).
+ *
+ * ## Texture memory
+ *
+ * Only 2 textures per frame: 1 VideoTexture (GPU-managed, zero CPU
+ * upload) + 1 depth DataTexture (1024×1024 Uint8 = 1 MB, uploaded
+ * only when depth changes at ~5fps). This is ~5× less bandwidth
+ * than the old 5-layer RGBA system.
+ */
+import type { ParallaxInput } from './input-handler';
+/** Configuration subset relevant to the parallax renderer. */
+export interface ParallaxRendererConfig {
+    parallaxStrength: number;
+    pomEnabled: boolean;
+    pomSteps: number;
+    overscanPadding: number;
+    /**
+     * Depth-adaptive shader parameters.
+     * When omitted, calibrated defaults matching the current hardcoded values
+     * are used. When provided, the explicit value overrides the derived value.
+     */
+    contrastLow?: number;
+    contrastHigh?: number;
+    verticalReduction?: number;
+    dofStart?: number;
+    dofStrength?: number;
+}
+export declare class ParallaxRenderer {
+    /** Debounce delay for resize events to avoid layout thrashing. */
+    private static readonly RESIZE_DEBOUNCE_MS;
+    /** Compile-time upper bound for the POM for-loop in GLSL. */
+    private static readonly MAX_POM_STEPS;
+    private readonly scene;
+    private readonly camera;
+    private readonly renderer;
+    private readonly container;
+    private videoTexture;
+    private depthTexture;
+    private mesh;
+    private videoAspect;
+    private readDepth;
+    private readInput;
+    private playbackVideo;
+    /**
+     * Optional callback invoked on each new video frame (from RVFC).
+     * The Web Component uses this to dispatch the 'layershift-parallax:frame' event.
+     */
+    private onVideoFrame;
+    private animationFrameHandle;
+    /** requestVideoFrameCallback handle (0 = inactive). */
+    private rvfcHandle;
+    /** Whether RVFC is supported on the current video element. */
+    private rvfcSupported;
+    private resizeObserver;
+    private resizeTimer;
+    private currentPlaneWidth;
+    private currentPlaneHeight;
+    /**
+     * Create the renderer and attach its canvas to the DOM.
+     *
+     * @param parent - The container element that the WebGL canvas is
+     *   appended to. The renderer sizes itself to fill this element.
+     * @param config - Parallax-specific settings (strength, POM, overscan).
+     *   Optional shader parameters are merged with calibrated defaults.
+     */
+    /** Resolved config with all optional shader params filled from defaults. */
+    private readonly config;
+    constructor(parent: HTMLElement, config: ParallaxRendererConfig);
+    /**
+     * Set up the scene: create VideoTexture, depth DataTexture, and the
+     * single mesh with the custom parallax ShaderMaterial.
+     *
+     * Call this once after the video element and depth data are loaded.
+     *
+     * @param video - The <video> element to sample color frames from.
+     *   Must already have metadata loaded (videoWidth/videoHeight set).
+     * @param depthWidth - Width of the precomputed depth map (e.g. 512).
+     * @param depthHeight - Height of the precomputed depth map (e.g. 512).
+     */
+    initialize(video: HTMLVideoElement, depthWidth: number, depthHeight: number): void;
+    /**
+     * Begin the render loop.
+     *
+     * When `requestVideoFrameCallback` is available, two loops run:
+     * 1. RVFC loop — fires once per new video frame, handles depth update.
+     * 2. RAF loop — fires at display refresh rate, handles input + render.
+     *
+     * When RVFC is not available, falls back to a single RAF loop that
+     * does everything (the pre-RVFC behavior).
+     *
+     * @param readDepth - Called with the current video time.
+     *   Returns a Uint8Array of depth values (0=near, 255=far) at the
+     *   depth texture's resolution. The interpolator handles caching
+     *   so redundant calls (same depth frame) return instantly.
+     * @param readInput - Returns the smoothed parallax input {x, y}
+     *   in [-1, 1].
+     * @param onVideoFrame - Optional callback invoked on each new
+     *   video frame. Receives the accurate media time and the
+     *   browser's presented-frame counter.
+     */
+    start(video: HTMLVideoElement, readDepth: (timeSec: number) => Uint8Array, readInput: () => ParallaxInput, onVideoFrame?: (currentTime: number, frameNumber: number) => void): void;
+    /** Stop both render loops and release callbacks. */
+    stop(): void;
+    /** Stop rendering and release all GPU resources. */
+    dispose(): void;
+    /** Check whether requestVideoFrameCallback is available. */
+    private static isRVFCSupported;
+    /**
+     * RVFC callback — fires only when the browser presents a new video frame.
+     *
+     * Handles the expensive depth texture update, which only needs to happen
+     * when the video frame actually changes (~24-30fps, not 60-120fps).
+     *
+     * Uses `metadata.mediaTime` for more accurate depth reads than
+     * `video.currentTime` (which can lag behind the presented frame).
+     */
+    private readonly videoFrameLoop;
+    /**
+     * Main render loop — called every animation frame at display refresh rate.
+     *
+     * When RVFC is active, this only handles:
+     * 1. Updating the parallax offset uniform from input (buttery smooth).
+     * 2. Rendering the scene (single draw call).
+     *
+     * The depth texture is updated separately by videoFrameLoop at video
+     * frame rate. This separation means parallax stays smooth at 60/120fps
+     * even though depth only updates at 24-30fps.
+     *
+     * When RVFC is NOT supported, this falls back to the original behavior:
+     * depth update + input update + render all in a single RAF tick.
+     */
+    private readonly renderLoop;
+    /**
+     * Set up a ResizeObserver on the container element and a fallback
+     * window resize listener. Both trigger a debounced recalculation
+     * of the viewport layout, camera, and plane geometry.
+     */
+    private setupResizeHandling;
+    /** Debounce resize events to avoid expensive layout recalculations. */
+    private readonly scheduleResizeRecalculate;
+    /**
+     * Recalculate the WebGL canvas size, orthographic camera frustum,
+     * and plane geometry to match the current container dimensions.
+     *
+     * The plane is sized to "cover" the viewport (like CSS object-fit:
+     * cover) plus extra overscan padding so that parallax displacement
+     * doesn't reveal the plane edges.
+     */
+    private recalculateViewportLayout;
+    /** Read the container's pixel dimensions, with a minimum of 1×1. */
+    private getViewportSize;
+    /**
+     * Compute the plane dimensions needed to cover the viewport while
+     * preserving the video's aspect ratio, plus overscan padding.
+     *
+     * "Cover" means the plane is scaled so the shorter axis fills the
+     * viewport (the longer axis overflows). Overscan adds extra size
+     * proportional to the parallax strength so that maximum displacement
+     * never reveals the plane edge.
+     *
+     * @returns planeWidth/planeHeight in world units (= pixels, since
+     *   the camera is set up 1:1).
+     */
+    private computeCoverPlaneSize;
+    /** Dispose the mesh, material, and textures from the scene. */
+    private disposeScene;
+}
+//# sourceMappingURL=parallax-renderer.d.ts.map

package/dist/types/parallax-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parallax-renderer.d.ts","sourceRoot":"","sources":["../../src/parallax-renderer.ts"],"names":[],"mappings":"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"}

package/dist/types/precomputed-depth.d.ts

@@ -0,0 +1,81 @@
+export interface DepthMeta {
+    frameCount: number;
+    fps: number;
+    width: number;
+    height: number;
+    sourceFps: number;
+}
+export interface PrecomputedDepthData {
+    meta: DepthMeta;
+    frames: Uint8Array[];
+}
+export interface BinaryDownloadProgress {
+    receivedBytes: number;
+    totalBytes: number | null;
+    fraction: number;
+}
+/**
+ * Worker-backed depth frame interpolator.
+ *
+ * Offloads the bilateral filter, interpolation, and resize to a Web Worker
+ * so the main thread stays free for smooth rendering. Uses double-buffering:
+ * the main thread always has a ready-to-use depth frame while the worker
+ * computes the next one in parallel.
+ *
+ * ## Double-buffer strategy
+ *
+ * - `currentBuffer` — the latest completed depth frame, always available
+ *   for synchronous reads via `sample()`.
+ * - When the render loop calls `sample(timeSec)`, it returns `currentBuffer`
+ *   immediately (zero main-thread work) and posts a request to the worker
+ *   for the new time if it differs from the last requested time.
+ * - When the worker responds, `currentBuffer` is swapped to the new result.
+ * - During the 1-2 frames of latency, the previous depth frame is shown —
+ *   this is imperceptible since depth only changes at ~5fps.
+ */
+export declare class WorkerDepthInterpolator {
+    private worker;
+    private currentBuffer;
+    private pendingTimeSec;
+    private workerBusy;
+    private disposed;
+    private constructor();
+    /**
+     * Create a WorkerDepthInterpolator, initializing the worker with frame data.
+     *
+     * The frame ArrayBuffers are transferred (zero-copy) to the worker.
+     * After this call, the original depthData.frames arrays are neutered
+     * and should not be accessed.
+     */
+    static create(depthData: PrecomputedDepthData, targetWidth: number, targetHeight: number): Promise<WorkerDepthInterpolator>;
+    /**
+     * Get the current depth frame — always synchronous, zero main-thread work.
+     *
+     * Returns the latest completed depth frame from the worker. If the worker
+     * hasn't finished processing the current time yet, returns the previous
+     * frame (1-2 frame latency is imperceptible at ~5fps depth changes).
+     *
+     * Automatically requests the worker to process the new time in the background.
+     */
+    sample(timeSec: number): Uint8Array;
+    /** Send a sample request to the worker if it's not busy. */
+    private requestSample;
+    /** Terminate the worker and release resources. */
+    dispose(): void;
+}
+export declare class DepthFrameInterpolator {
+    private readonly depthData;
+    private readonly targetWidth;
+    private readonly targetHeight;
+    private readonly interpolatedDepth;
+    private readonly resizedDepth;
+    private readonly bilateralOutput;
+    private readonly uint8Output;
+    private lastFrameIndex;
+    private lastNextFrameIndex;
+    private lastLerpFactor;
+    constructor(depthData: PrecomputedDepthData, targetWidth: number, targetHeight: number);
+    sample(timeSec: number): Uint8Array;
+}
+export declare function loadPrecomputedDepth(depthDataUrl: string, depthMetaUrl: string, onProgress?: (progress: BinaryDownloadProgress) => void): Promise<PrecomputedDepthData>;
+//# sourceMappingURL=precomputed-depth.d.ts.map

package/dist/types/precomputed-depth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"precomputed-depth.d.ts","sourceRoot":"","sources":["../../src/precomputed-depth.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,sBAAsB;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,aAAa,CAAa;IAClC,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAS;IAEzB,OAAO;IAQP;;;;;;OAMG;WACU,MAAM,CACjB,SAAS,EAAE,oBAAoB,EAC/B,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,uBAAuB,CAAC;IAqEnC;;;;;;;;OAQG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU;IAKnC,4DAA4D;IAC5D,OAAO,CAAC,aAAa;IAarB,kDAAkD;IAClD,OAAO,IAAI,IAAI;CAIhB;AAED,qBAAa,sBAAsB;IAe/B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAhB/B,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAe;IACjD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAe;IAC/C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAa;IAMzC,OAAO,CAAC,cAAc,CAAM;IAC5B,OAAO,CAAC,kBAAkB,CAAM;IAChC,OAAO,CAAC,cAAc,CAAM;gBAGT,SAAS,EAAE,oBAAoB,EAC/B,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM;IAUvC,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU;CA8DpC;AAED,wBAAsB,oBAAoB,CACxC,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,sBAAsB,KAAK,IAAI,GACtD,OAAO,CAAC,oBAAoB,CAAC,CAO/B"}

package/dist/types/video-source.d.ts

@@ -0,0 +1,23 @@
+export interface FrameExtractionOptions {
+    fps: number;
+    maxDurationSec: number;
+    workingMaxWidth: number;
+}
+export interface ExtractionPlan {
+    fps: number;
+    durationSec: number;
+    frameCount: number;
+    width: number;
+    height: number;
+}
+export interface ExtractedFrame {
+    index: number;
+    timeSec: number;
+    imageData: ImageData;
+    width: number;
+    height: number;
+}
+export declare function createHiddenVideoElement(url: string): Promise<HTMLVideoElement>;
+export declare function createExtractionPlan(video: HTMLVideoElement, options: FrameExtractionOptions): ExtractionPlan;
+export declare function extractFramesBySeeking(video: HTMLVideoElement, plan: ExtractionPlan, onFrame: (frame: ExtractedFrame, totalFrames: number) => Promise<void> | void, onProgress?: (progress: number) => void): Promise<void>;
+//# sourceMappingURL=video-source.d.ts.map

package/dist/types/video-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"video-source.d.ts","sourceRoot":"","sources":["../../src/video-source.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,SAAS,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAID,wBAAsB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAmBrF;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,gBAAgB,EACvB,OAAO,EAAE,sBAAsB,GAC9B,cAAc,CAehB;AAED,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,gBAAgB,EACvB,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,CAAC,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,EAC7E,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,GACtC,OAAO,CAAC,IAAI,CAAC,CAmCf"}