layershift 0.2.2 → 0.3.0

package/dist/types/render-pass-webgpu.d.ts

@@ -0,0 +1,76 @@
+/**
+ * WebGPU Render Pass Framework — pipeline and bind group management.
+ *
+ * Parallel to `render-pass.ts` (WebGL2) but with idiomatic WebGPU patterns:
+ * - Pipeline state objects bake blend/stencil/depth config at creation
+ * - Bind groups replace individual uniform calls
+ * - No mutable state machine
+ *
+ * @see render-pass.ts for the WebGL2 counterpart.
+ */
+/** A single WebGPU render pass with its pipeline and bind group layout. */
+export interface WebGPURenderPass {
+    readonly name: string;
+    readonly pipeline: GPURenderPipeline;
+    readonly bindGroupLayout: GPUBindGroupLayout;
+    dispose(): void;
+}
+/** A WebGPU render pass that outputs to an offscreen texture. */
+export interface WebGPUFBOPass extends WebGPURenderPass {
+    outputTexture: GPUTexture;
+    outputView: GPUTextureView;
+    width: number;
+    height: number;
+    resize(device: GPUDevice, w: number, h: number, format?: GPUTextureFormat): void;
+}
+/** Configuration for creating a WebGPU render pass. */
+export interface WebGPURenderPassConfig {
+    readonly name: string;
+    readonly vertexShader: string;
+    readonly fragmentShader: string;
+    readonly vertexBufferLayouts: GPUVertexBufferLayout[];
+    readonly colorTargets: GPUColorTargetState[];
+    readonly depthStencil?: GPUDepthStencilState;
+    readonly primitive?: GPUPrimitiveState;
+    /** Explicit bind group layout entries. If omitted, uses auto layout. */
+    readonly bindGroupLayoutEntries?: GPUBindGroupLayoutEntry[];
+}
+/** Configuration for creating a WebGPU FBO pass. */
+export interface WebGPUFBOPassConfig extends WebGPURenderPassConfig {
+    readonly outputWidth: number;
+    readonly outputHeight: number;
+    readonly outputFormat?: GPUTextureFormat;
+}
+/**
+ * Create a WebGPU render pass with explicit bind group layout.
+ */
+export declare function createWebGPUPass(device: GPUDevice, config: WebGPURenderPassConfig): WebGPURenderPass;
+/**
+ * Create a WebGPU FBO pass that renders to an offscreen texture.
+ */
+export declare function createWebGPUFBOPass(device: GPUDevice, config: WebGPUFBOPassConfig): WebGPUFBOPass;
+/**
+ * Shared texture registry for WebGPU — manages texture unit allocation.
+ *
+ * Unlike WebGL2, WebGPU doesn't have numbered texture units. Instead,
+ * textures are referenced by bind group entries. This registry provides
+ * a consistent naming scheme across passes.
+ */
+export declare class WebGPUTextureRegistry {
+    private readonly textures;
+    register(name: string, texture: GPUTexture): GPUTextureView;
+    get(name: string): {
+        texture: GPUTexture;
+        view: GPUTextureView;
+    } | undefined;
+    dispose(): void;
+}
+/** Fullscreen quad vertex buffer layout: position (vec2). */
+export declare const FULLSCREEN_QUAD_LAYOUT: GPUVertexBufferLayout;
+/** Mesh vertex buffer layout: position (vec2) only. */
+export declare const MESH_POSITION_LAYOUT: GPUVertexBufferLayout;
+/** Boundary vertex buffer layout: position (vec2) + normal (vec2). */
+export declare const BOUNDARY_VERTEX_LAYOUT: GPUVertexBufferLayout;
+/** Chamfer vertex buffer layout: position (vec2) + normal3 (vec3) + lerpT (float). */
+export declare const CHAMFER_VERTEX_LAYOUT: GPUVertexBufferLayout;
+//# sourceMappingURL=render-pass-webgpu.d.ts.map

package/dist/types/render-pass-webgpu.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-pass-webgpu.d.ts","sourceRoot":"","sources":["../../src/render-pass-webgpu.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,2EAA2E;AAC3E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,eAAe,EAAE,kBAAkB,CAAC;IAC7C,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,iEAAiE;AACjE,MAAM,WAAW,aAAc,SAAQ,gBAAgB;IACrD,aAAa,EAAE,UAAU,CAAC;IAC1B,UAAU,EAAE,cAAc,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAClF;AAED,uDAAuD;AACvD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,mBAAmB,EAAE,qBAAqB,EAAE,CAAC;IACtD,QAAQ,CAAC,YAAY,EAAE,mBAAmB,EAAE,CAAC;IAC7C,QAAQ,CAAC,YAAY,CAAC,EAAE,oBAAoB,CAAC;IAC7C,QAAQ,CAAC,SAAS,CAAC,EAAE,iBAAiB,CAAC;IACvC,wEAAwE;IACxE,QAAQ,CAAC,sBAAsB,CAAC,EAAE,uBAAuB,EAAE,CAAC;CAC7D;AAED,oDAAoD;AACpD,MAAM,WAAW,mBAAoB,SAAQ,sBAAsB;IACjE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,CAAC,EAAE,gBAAgB,CAAC;CAC1C;AAMD;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,sBAAsB,GAC7B,gBAAgB,CAqClB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,mBAAmB,GAC1B,aAAa,CA4Bf;AAMD;;;;;;GAMG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoE;IAE7F,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,cAAc;IAM3D,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,UAAU,CAAC;QAAC,IAAI,EAAE,cAAc,CAAA;KAAE,GAAG,SAAS;IAI5E,OAAO,IAAI,IAAI;CAMhB;AAuBD,6DAA6D;AAC7D,eAAO,MAAM,sBAAsB,EAAE,qBAKpC,CAAC;AAEF,uDAAuD;AACvD,eAAO,MAAM,oBAAoB,EAAE,qBAKlC,CAAC;AAEF,sEAAsE;AACtE,eAAO,MAAM,sBAAsB,EAAE,qBAMpC,CAAC;AAEF,sFAAsF;AACtF,eAAO,MAAM,qBAAqB,EAAE,qBAOnC,CAAC"}

package/dist/types/render-pass.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Shared render pass framework for compositing and effect stacking.
+ *
+ * Provides standardized interfaces (`RenderPass`, `FBOPass`) and a
+ * `TextureRegistry` for unit allocation. Both the parallax and portal
+ * renderers adopt this framework to structure their multi-pass GPU
+ * pipelines consistently.
+ *
+ * ## Design principles
+ *
+ * - **Geometry-agnostic** — passes may use fullscreen quads, indexed
+ *   meshes, or any other geometry. The framework doesn't assume.
+ * - **No common execute()** — passes have wildly different execute
+ *   signatures (bilateral needs raw depth data; JFA flood is iterative;
+ *   parallax just draws). Each renderer calls passes type-safely.
+ * - **Zero per-frame overhead** — TextureRegistry allocates at init
+ *   time. Hot-path code reads slot references directly.
+ * - **Pragmatic** — ~250 lines, not a game engine.
+ */
+/**
+ * A self-contained render pass: owns its shader program, uniform cache,
+ * and knows how to clean itself up.
+ *
+ * `program` and `uniforms` are exposed directly so the render loop can
+ * set per-frame uniforms (e.g., `uOffset`) without method-call overhead.
+ */
+export interface RenderPass {
+    /** Display name for debugging (e.g., "bilateral-filter", "jfa-flood"). */
+    readonly name: string;
+    /** The compiled + linked shader program. */
+    readonly program: WebGLProgram;
+    /** Cached uniform locations. */
+    readonly uniforms: Record<string, WebGLUniformLocation | null>;
+    /** Release GPU resources owned by this pass (program, FBOs). */
+    dispose(gl: WebGL2RenderingContext): void;
+}
+/** A single FBO color attachment descriptor. */
+export interface FBOAttachment {
+    /** The texture backing this attachment. */
+    texture: WebGLTexture;
+    /** Assigned texture unit (e.g., `gl.TEXTURE2` maps to unit 2). */
+    unit: number;
+    /** GL color attachment point (e.g., `gl.COLOR_ATTACHMENT0`). */
+    attachment: number;
+}
+/**
+ * A render pass that writes to an FBO rather than the default framebuffer.
+ *
+ * Manages its own framebuffer and output texture(s). Supports both
+ * single-output passes (bilateral filter → R8) and MRT passes
+ * (portal interior → RGBA8 color + RGBA8 depth).
+ */
+export interface FBOPass extends RenderPass {
+    /** The framebuffer object. Null before first `resize()`. */
+    fbo: WebGLFramebuffer | null;
+    /** Output textures written by this pass. */
+    readonly outputs: readonly FBOAttachment[];
+    /** Width of the FBO in pixels. */
+    width: number;
+    /** Height of the FBO in pixels. */
+    height: number;
+    /**
+     * Resize or recreate the FBO and its attachment textures.
+     * Called on viewport resize, not per-frame.
+     */
+    resize(gl: WebGL2RenderingContext, width: number, height: number): void;
+}
+/**
+ * Ordered list of render passes. Execute in array order.
+ *
+ * This is intentionally a thin type alias, not a class. The dual-loop
+ * architecture (RVFC + RAF) means passes are NOT all executed in one
+ * sequence, so orchestration stays in each renderer's render loop.
+ */
+export type RenderPipeline = readonly RenderPass[];
+/** A named texture with its assigned unit. */
+export interface TextureSlot {
+    /** Human-readable name (e.g., "video", "filteredDepth"). */
+    readonly name: string;
+    /** Assigned texture unit number (0, 1, 2, ...). */
+    readonly unit: number;
+    /** The WebGL texture handle. Null until allocated. */
+    texture: WebGLTexture | null;
+}
+/**
+ * Tracks texture unit assignments for a renderer.
+ *
+ * All allocation happens at init time via `register()`. The hot-path
+ * render loop accesses slots directly by cached reference — no map
+ * lookups per frame.
+ *
+ * Usage:
+ * ```ts
+ * const textures = new TextureRegistry();
+ * const videoSlot = textures.register('video');      // unit 0
+ * const depthSlot = textures.register('filteredDepth'); // unit 1
+ *
+ * // In render loop (hot path) — direct reference, zero lookup:
+ * gl.activeTexture(gl.TEXTURE0 + videoSlot.unit);
+ * gl.bindTexture(gl.TEXTURE_2D, videoSlot.texture);
+ * ```
+ */
+export declare class TextureRegistry {
+    private readonly slots;
+    private nextUnit;
+    /**
+     * Reserve a texture unit for a named texture.
+     *
+     * @returns The `TextureSlot` — hold a reference for hot-path access.
+     * @throws If the name is already registered.
+     */
+    register(name: string): TextureSlot;
+    /**
+     * Get a previously registered slot by name.
+     *
+     * @throws If the name was not registered.
+     */
+    get(name: string): TextureSlot;
+    /** Delete all textures and reset slots to null. */
+    disposeAll(gl: WebGL2RenderingContext): void;
+    /** Number of registered slots. */
+    get size(): number;
+}
+/**
+ * Create a `RenderPass` from vertex/fragment shader source.
+ *
+ * Compiles shaders, links program, caches uniform locations.
+ * The returned pass owns its program and cleans it up on `dispose()`.
+ */
+export declare function createPass(gl: WebGL2RenderingContext, name: string, vertexSource: string, fragmentSource: string, uniformNames: readonly string[]): RenderPass;
+/** Options for creating a single-output FBO pass. */
+export interface FBOPassOptions {
+    /** GL internal format (e.g., `gl.R8`, `gl.RGBA8`, `gl.RG16F`). */
+    internalFormat: number;
+    /** GL format for texImage2D (e.g., `gl.RED`, `gl.RGBA`, `gl.RG`). */
+    format: number;
+    /** GL type for texImage2D (e.g., `gl.UNSIGNED_BYTE`, `gl.FLOAT`). */
+    type: number;
+    /** Texture unit to assign to the output texture. */
+    textureUnit: number;
+    /** Initial FBO width. */
+    width: number;
+    /** Initial FBO height. */
+    height: number;
+}
+/**
+ * Create an `FBOPass` with a single color attachment.
+ *
+ * The FBO and its output texture are created immediately at the given
+ * dimensions. Call `resize()` to recreate at a different size.
+ */
+export declare function createFBOPass(gl: WebGL2RenderingContext, name: string, vertexSource: string, fragmentSource: string, uniformNames: readonly string[], options: FBOPassOptions): FBOPass;
+/** Descriptor for one MRT color attachment. */
+export interface MRTAttachment {
+    /** GL internal format (e.g., `gl.RGBA8`). */
+    internalFormat: number;
+    /** GL format (e.g., `gl.RGBA`). */
+    format: number;
+    /** GL type (e.g., `gl.UNSIGNED_BYTE`). */
+    type: number;
+    /** Texture unit to assign. */
+    textureUnit: number;
+}
+/**
+ * Create an `FBOPass` with multiple color attachments (MRT).
+ *
+ * Used by the portal interior pass which writes both color and depth
+ * to separate textures in a single draw call via `gl.drawBuffers()`.
+ */
+export declare function createMRTPass(gl: WebGL2RenderingContext, name: string, vertexSource: string, fragmentSource: string, uniformNames: readonly string[], attachments: readonly MRTAttachment[], width: number, height: number): FBOPass;
+//# sourceMappingURL=render-pass.d.ts.map

package/dist/types/render-pass.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-pass.d.ts","sourceRoot":"","sources":["../../src/render-pass.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAYH;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAE/B,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,GAAG,IAAI,CAAC,CAAC;IAE/D,gEAAgE;IAChE,OAAO,CAAC,EAAE,EAAE,sBAAsB,GAAG,IAAI,CAAC;CAC3C;AAED,gDAAgD;AAChD,MAAM,WAAW,aAAa;IAC5B,2CAA2C;IAC3C,OAAO,EAAE,YAAY,CAAC;IAEtB,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IAEb,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,OAAQ,SAAQ,UAAU;IACzC,4DAA4D;IAC5D,GAAG,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAE7B,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;IAE3C,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IAEd,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,MAAM,CAAC,EAAE,EAAE,sBAAsB,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACzE;AAED;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,SAAS,UAAU,EAAE,CAAC;AAMnD,8CAA8C;AAC9C,MAAM,WAAW,WAAW;IAC1B,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,sDAAsD;IACtD,OAAO,EAAE,YAAY,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuC;IAC7D,OAAO,CAAC,QAAQ,CAAK;IAErB;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW;IASnC;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW;IAQ9B,mDAAmD;IACnD,UAAU,CAAC,EAAE,EAAE,sBAAsB,GAAG,IAAI;IAS5C,kCAAkC;IAClC,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAMD;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,EAAE,EAAE,sBAAsB,EAC1B,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,SAAS,MAAM,EAAE,GAC9B,UAAU,CAcZ;AAED,qDAAqD;AACrD,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,cAAc,EAAE,MAAM,CAAC;IAEvB,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IAEf,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IAEb,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IAEpB,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IAEd,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,EAAE,EAAE,sBAAsB,EAC1B,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,OAAO,EAAE,cAAc,GACtB,OAAO,CA4ET;AAED,+CAA+C;AAC/C,MAAM,WAAW,aAAa;IAC5B,6CAA6C;IAC7C,cAAc,EAAE,MAAM,CAAC;IAEvB,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IAEf,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IAEb,8BAA8B;IAC9B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,EAAE,EAAE,sBAAsB,EAC1B,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,WAAW,EAAE,SAAS,aAAa,EAAE,EACrC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,OAAO,CA4FT"}

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

@@ -0,0 +1,124 @@
+/**
+ * Abstract base class for Layershift renderers.
+ *
+ * Extracts shared non-GPU logic common to both the parallax and portal
+ * renderers (and their future WebGPU counterparts):
+ *
+ * - Canvas creation + container attachment
+ * - Dual-loop animation management (RVFC + RAF)
+ * - Resize handling with debounce
+ * - Depth dimension clamping + CPU subsampling
+ * - Cover-fit UV computation
+ * - WebGL context loss handling
+ *
+ * Subclasses implement the GPU-specific abstract methods:
+ * `onRenderFrame()`, `onDepthUpdate()`, `recalculateViewportLayout()`,
+ * `disposeRenderer()`, and `onContextRestored()`.
+ */
+import type { ParallaxInput } from './input-handler';
+import type { QualityParams } from './quality';
+export declare abstract class RendererBase {
+    protected static readonly RESIZE_DEBOUNCE_MS = 100;
+    protected readonly canvas: HTMLCanvasElement;
+    protected readonly container: HTMLElement;
+    /** GPU texture dimensions (may be clamped by quality tier). */
+    protected depthWidth: number;
+    protected depthHeight: number;
+    /** Original source depth dimensions (from precomputed data). */
+    protected sourceDepthWidth: number;
+    protected sourceDepthHeight: number;
+    /** Reusable buffer for subsampling depth data when GPU dims < source dims. */
+    protected depthSubsampleBuffer: Uint8Array | null;
+    protected videoAspect: number;
+    protected uvOffset: number[];
+    protected uvScale: number[];
+    protected readDepth: ((timeSec: number) => Uint8Array) | null;
+    protected readInput: (() => ParallaxInput) | null;
+    protected playbackVideo: HTMLVideoElement | null;
+    /**
+     * Optional callback invoked on each new video frame (from RVFC).
+     * The Web Component uses this to dispatch frame events.
+     */
+    protected onVideoFrame: ((currentTime: number, frameNumber: number) => void) | null;
+    protected animationFrameHandle: number;
+    /** requestVideoFrameCallback handle (0 = inactive). */
+    protected rvfcHandle: number;
+    /** Whether RVFC is supported on the current video element. */
+    protected rvfcSupported: boolean;
+    protected resizeObserver: ResizeObserver | null;
+    protected resizeTimer: number | null;
+    /** Adaptive quality parameters. Set by subclass constructor after GL init. */
+    protected qualityParams: QualityParams;
+    constructor(parent: HTMLElement);
+    /**
+     * 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.
+     */
+    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. */
+    protected static isRVFCSupported(): boolean;
+    /**
+     * RAF loop — fires at display refresh rate.
+     * Delegates to subclass `onRenderFrame()` for the actual render work.
+     */
+    private readonly _rafLoop;
+    /**
+     * RVFC callback — fires only when the browser presents a new video frame.
+     * Delegates to subclass `onDepthUpdate()` for depth texture upload.
+     */
+    private readonly _videoFrameLoop;
+    private readonly _handleContextLost;
+    private readonly _handleContextRestored;
+    /**
+     * Set up a ResizeObserver on the container element and a fallback
+     * window resize listener. Called by subclass after GPU init.
+     */
+    protected setupResizeHandling(): void;
+    /** Debounce resize events to avoid expensive layout recalculations. */
+    protected readonly scheduleResizeRecalculate: () => void;
+    /** Read the container's pixel dimensions, with a minimum of 1x1. */
+    protected getViewportSize(): {
+        width: number;
+        height: number;
+    };
+    /**
+     * Clamp depth dimensions to the quality tier's maximum and allocate
+     * the subsample buffer if needed. Called during `initialize()`.
+     */
+    protected clampDepthDimensions(sourceWidth: number, sourceHeight: number, maxDim: number): void;
+    /**
+     * CPU nearest-neighbor depth subsampling.
+     *
+     * Returns the original data if no subsampling is needed, otherwise
+     * fills and returns the pre-allocated subsample buffer.
+     */
+    protected subsampleDepth(depthData: Uint8Array): Uint8Array;
+    /**
+     * Compute cover-fit + overscan UV transform.
+     *
+     * The video fills the viewport (cover-fit), and overscan adds extra
+     * visible area so parallax displacement doesn't reveal edges.
+     * Updates `this.uvOffset` and `this.uvScale`.
+     */
+    protected computeCoverFitUV(parallaxStrength: number, overscanPadding: number): void;
+    /** Main render frame logic (called from RAF loop at display refresh rate). */
+    protected abstract onRenderFrame(): void;
+    /** Depth texture upload + filter (called from RVFC loop at video frame rate). */
+    protected abstract onDepthUpdate(timeSec: number): void;
+    /** Recalculate canvas size, FBOs, UV transform on resize. */
+    protected abstract recalculateViewportLayout(): void;
+    /** Release all GPU resources (called from dispose()). */
+    protected abstract disposeRenderer(): void;
+    /** Rebuild GPU state after context restoration. */
+    protected abstract onContextRestored(): void;
+}
+//# sourceMappingURL=renderer-base.d.ts.map

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

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

package/dist/types/webgl-utils.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared WebGL 2 utilities — compile, link, uniform caching, fullscreen quad.
+ *
+ * Used by both the parallax renderer and the portal renderer to avoid
+ * duplicating boilerplate GL setup code.
+ */
+/** Compile a GLSL shader, throwing on error. */
+export declare function compileShader(gl: WebGL2RenderingContext, type: number, source: string): WebGLShader;
+/** Link a shader program, throwing on error. */
+export declare function linkProgram(gl: WebGL2RenderingContext, vertShader: WebGLShader, fragShader: WebGLShader): WebGLProgram;
+/**
+ * Cache uniform locations for a set of uniform names.
+ *
+ * Returns a record mapping each name to its `WebGLUniformLocation | null`.
+ * Avoids repeated `getUniformLocation` calls per frame.
+ */
+export declare function getUniformLocations(gl: WebGL2RenderingContext, program: WebGLProgram, names: readonly string[]): Record<string, WebGLUniformLocation | null>;
+/**
+ * Create a VAO for the standard fullscreen quad.
+ *
+ * The VAO binds a VBO with 4 clip-space vertices to the `aPosition`
+ * attribute (looked up from the given program). Draw with
+ * `gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4)`.
+ *
+ * @param gl - WebGL 2 context
+ * @param program - Shader program to look up `aPosition` attribute location
+ */
+export declare function createFullscreenQuadVao(gl: WebGL2RenderingContext, program: WebGLProgram): WebGLVertexArrayObject;
+//# sourceMappingURL=webgl-utils.d.ts.map

package/dist/types/webgl-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webgl-utils.d.ts","sourceRoot":"","sources":["../../src/webgl-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,gDAAgD;AAChD,wBAAgB,aAAa,CAC3B,EAAE,EAAE,sBAAsB,EAC1B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,WAAW,CAWb;AAED,gDAAgD;AAChD,wBAAgB,WAAW,CACzB,EAAE,EAAE,sBAAsB,EAC1B,UAAU,EAAE,WAAW,EACvB,UAAU,EAAE,WAAW,GACtB,YAAY,CAiBd;AAMD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,sBAAsB,EAC1B,OAAO,EAAE,YAAY,EACrB,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,MAAM,CAAC,MAAM,EAAE,oBAAoB,GAAG,IAAI,CAAC,CAM7C;AAiBD;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,sBAAsB,EAC1B,OAAO,EAAE,YAAY,GACpB,sBAAsB,CAiBxB"}

package/dist/types/webgpu-utils.d.ts

@@ -0,0 +1,42 @@
+/**
+ * WebGPU Utilities — shared helpers for WebGPU renderers.
+ *
+ * Parallel to `webgl-utils.ts` but for the WebGPU backend.
+ * Provides buffer creation, sampler factories, and fullscreen quad geometry.
+ */
+/**
+ * Create a GPU buffer containing a fullscreen quad (triangle strip, 4 vertices).
+ */
+export declare function createFullscreenQuadBuffer(device: GPUDevice): GPUBuffer;
+/**
+ * Create a GPU vertex buffer from Float32Array data.
+ */
+export declare function createVertexBuffer(device: GPUDevice, data: Float32Array): GPUBuffer;
+/**
+ * Create a GPU index buffer from Uint16Array data.
+ */
+export declare function createIndexBuffer(device: GPUDevice, data: Uint16Array): GPUBuffer;
+/**
+ * Create a GPU uniform buffer of the given byte size.
+ */
+export declare function createUniformBuffer(device: GPUDevice, byteSize: number): GPUBuffer;
+/**
+ * Create a 2D texture with common defaults for render targets.
+ */
+export declare function createRenderTexture(device: GPUDevice, width: number, height: number, format?: GPUTextureFormat): GPUTexture;
+/**
+ * Create a 2D texture for sampling (e.g., video frame, depth data).
+ */
+export declare function createSampleTexture(device: GPUDevice, width: number, height: number, format?: GPUTextureFormat): GPUTexture;
+/** Create a linear-filtering, clamp-to-edge sampler. */
+export declare function createLinearSampler(device: GPUDevice): GPUSampler;
+/** Create a nearest-filtering, clamp-to-edge sampler. */
+export declare function createNearestSampler(device: GPUDevice): GPUSampler;
+/**
+ * Import a video frame into a WebGPU texture using `copyExternalImageToTexture`.
+ *
+ * This is the WebGPU equivalent of `gl.texImage2D(gl.TEXTURE_2D, ..., video)`.
+ * On supported browsers, this is a zero-copy operation.
+ */
+export declare function importVideoFrame(device: GPUDevice, texture: GPUTexture, video: HTMLVideoElement, flipY?: boolean): void;
+//# sourceMappingURL=webgpu-utils.d.ts.map

package/dist/types/webgpu-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webgpu-utils.d.ts","sourceRoot":"","sources":["../../src/webgpu-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAcH;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,CASvE;AAMD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,YAAY,GAAG,SAAS,CASnF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,GAAG,SAAS,CASjF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,CAOlF;AAMD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,gBAA+B,GACtC,UAAU,CAMZ;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,gBAA+B,GACtC,UAAU,CASZ;AAMD,wDAAwD;AACxD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,GAAG,UAAU,CAOjE;AAED,yDAAyD;AACzD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,GAAG,UAAU,CAOlE;AAMD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,UAAU,EACnB,KAAK,EAAE,gBAAgB,EACvB,KAAK,UAAO,GACX,IAAI,CAMN"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "layershift",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Embeddable video effects as Web Components. Drop-in parallax, depth-aware motion, and more.",
   "type": "module",
   "main": "dist/components/layershift.js",
@@ -35,10 +35,15 @@
     "prepublishOnly": "npm run build:package",
     "package": "npx tsx scripts/package-output.ts",
     "preview": "vite preview",
-    "test": "vitest run",
-    "test:watch": "vitest",
+    "test": "vitest run --project=unit",
+    "test:watch": "vitest --project=unit",
+    "test:storybook": "vitest run --project=storybook",
     "test:e2e": "playwright test",
-    "test:all": "vitest run && playwright test"
+    "test:all": "vitest run && playwright test",
+    "docs:dev": "vitepress dev docs",
+    "build:docs": "vitepress build docs",
+    "storybook": "storybook dev -p 6006",
+    "build:storybook": "storybook build -o dist/storybook"
   },
   "repository": {
     "type": "git",
@@ -61,22 +66,37 @@
   },
   "homepage": "https://layershift.io",
   "devDependencies": {
+    "@chromatic-com/storybook": "^5.0.1",
     "@playwright/test": "^1.58.2",
+    "@storybook/addon-a11y": "^10.2.10",
+    "@storybook/addon-docs": "^10.2.10",
+    "@storybook/addon-vitest": "^10.2.10",
+    "@storybook/react-vite": "^10.2.10",
     "@tailwindcss/vite": "^4.2.0",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
     "@types/jsdom": "^27.0.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^5.1.4",
     "@vitest/browser": "^4.0.18",
+    "@vitest/browser-playwright": "^4.0.18",
+    "@vitest/coverage-v8": "^4.0.18",
+    "@webgpu/types": "^0.1.69",
     "@xenova/transformers": "^2.17.2",
     "happy-dom": "^20.6.1",
     "jsdom": "^28.1.0",
+    "mermaid": "^11.12.3",
     "playwright": "^1.58.2",
     "sharp": "^0.34.5",
+    "storybook": "^10.2.10",
     "tailwindcss": "^4.2.0",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vite": "^7.3.1",
+    "vitepress": "^1.6.4",
+    "vitepress-plugin-mermaid": "^2.0.17",
     "vitest": "^4.0.18"
   },
   "dependencies": {