layershift 0.2.2 → 0.4.0

package/dist/types/quality.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Adaptive Quality Scaling — device capability probing and tier classification.
+ *
+ * Probes WebGL context + navigator APIs once at init time, classifies the
+ * device into a quality tier (high / medium / low), and resolves concrete
+ * parameters that both renderers and Web Components consume to adjust:
+ *
+ * - **Render resolution** — DPR cap (2.0 / 1.5 / 1.0)
+ * - **Depth resolution** — depth texture max dimension (512 / 512 / 256)
+ * - **Sample count** — POM steps (16 / 16 / 8), bilateral kernel (5×5 / 5×5 / 3×3)
+ * - **JFA resolution** — distance field divisor (2 / 2 / 4) for portal effect
+ *
+ * Override precedence (unchanged): explicit config > quality-derived > calibrated defaults.
+ *
+ * @see ADR-012 for the architectural decision and rationale.
+ */
+/** Device quality classification. */
+export type QualityTier = 'high' | 'medium' | 'low';
+/** Concrete rendering parameters resolved from a quality tier. */
+export interface QualityParams {
+    readonly tier: QualityTier;
+    /** Maximum device pixel ratio (2.0 / 1.5 / 1.0). */
+    readonly dprCap: number;
+    /** Maximum depth texture dimension — depth maps larger than this are downscaled (512 / 512 / 256). */
+    readonly depthMaxDim: number;
+    /** POM ray-march step count (16 / 16 / 8). */
+    readonly pomSteps: number;
+    /** Bilateral filter kernel radius in texels — kernel is (2r+1)×(2r+1) (2 / 2 / 1). */
+    readonly bilateralRadius: number;
+    /** JFA distance field resolution divisor (2 = half-res, 4 = quarter-res). */
+    readonly jfaDivisor: number;
+}
+/** Raw device capability probe results. */
+export interface DeviceCapabilities {
+    /** GPU renderer string from WEBGL_debug_renderer_info, or 'unknown'. */
+    readonly gpuRenderer: string;
+    /** GL_MAX_TEXTURE_SIZE. */
+    readonly maxTextureSize: number;
+    /** navigator.hardwareConcurrency (logical cores), or 0 if unavailable. */
+    readonly hardwareConcurrency: number;
+    /** navigator.deviceMemory in GB, or 0 if unavailable. */
+    readonly deviceMemory: number;
+    /** window.devicePixelRatio. */
+    readonly devicePixelRatio: number;
+    /** Total screen pixels (width × height). */
+    readonly screenPixels: number;
+    /** Whether the device appears to be mobile (touch + small screen). */
+    readonly isMobile: boolean;
+}
+/**
+ * Probe device capabilities from the WebGL context and navigator APIs.
+ *
+ * This is intentionally lightweight — it reads values that are already
+ * available (no async, no benchmarks). Called once at init time.
+ */
+export declare function probeCapabilities(gl: WebGL2RenderingContext): DeviceCapabilities;
+/**
+ * Classify device capabilities into a quality tier using a score-based heuristic.
+ *
+ * Weighted signals are summed to produce a score:
+ * - Score >= 0 → high
+ * - Score -25 to -1 → medium
+ * - Score < -25 → low
+ */
+export declare function classifyDevice(caps: DeviceCapabilities): QualityTier;
+/**
+ * Resolve quality parameters for a renderer.
+ *
+ * - If `quality` is a specific tier ('high' | 'medium' | 'low'), return
+ *   that tier's parameters directly (no probing).
+ * - If `quality` is 'auto' or undefined, probe device capabilities and
+ *   classify automatically.
+ *
+ * Called once per renderer at construction time. The returned params are
+ * stored as `private readonly qualityParams` and read during init and resize.
+ *
+ * @param gl - WebGL 2 rendering context (used for GPU probing).
+ * @param quality - Explicit tier, 'auto', or undefined (defaults to 'auto').
+ */
+export declare function resolveQuality(gl: WebGL2RenderingContext, quality?: 'auto' | QualityTier): QualityParams;
+/**
+ * Probe device capabilities from a WebGPU adapter.
+ *
+ * Extracts the same `DeviceCapabilities` shape as the WebGL2 probe,
+ * allowing the shared `classifyDevice()` scoring logic to work for both backends.
+ */
+export declare function probeCapabilitiesWebGPU(adapterInfo: GPUAdapterInfo): DeviceCapabilities;
+/**
+ * Resolve quality parameters for a WebGPU renderer.
+ *
+ * Same logic as `resolveQuality()` but accepts a `GPUAdapterInfo` instead
+ * of a WebGL context.
+ */
+export declare function resolveQualityWebGPU(adapterInfo: GPUAdapterInfo, quality?: 'auto' | QualityTier): QualityParams;
+//# sourceMappingURL=quality.d.ts.map

package/dist/types/quality.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quality.d.ts","sourceRoot":"","sources":["../../src/quality.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,qCAAqC;AACrC,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAEpD,kEAAkE;AAClE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sGAAsG;IACtG,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,sFAAsF;IACtF,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,2CAA2C;AAC3C,MAAM,WAAW,kBAAkB;IACjC,wEAAwE;IACxE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2BAA2B;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,0EAA0E;IAC1E,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,yDAAyD;IACzD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,+BAA+B;IAC/B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,4CAA4C;IAC5C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAkCD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,sBAAsB,GAAG,kBAAkB,CA0ChF;AA2CD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,kBAAkB,GAAG,WAAW,CAmCpE;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,EAAE,EAAE,sBAAsB,EAC1B,OAAO,CAAC,EAAE,MAAM,GAAG,WAAW,GAC7B,aAAa,CAMf;AAMD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,cAAc,GAAG,kBAAkB,CAkCvF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,cAAc,EAC3B,OAAO,CAAC,EAAE,MAAM,GAAG,WAAW,GAC7B,aAAa,CAMf"}

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,129 @@
+/**
+ * Abstract base class for Layershift renderers.
+ *
+ * Extracts shared non-GPU logic common to both the depth-effect and portal
+ * renderers (and their 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 { MediaSource } from './media-source';
+import type { EffectInput } 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;
+    /** When true, computeCoverFitUV mirrors the X-axis for selfie mode. */
+    protected isCameraSource: boolean;
+    protected uvOffset: number[];
+    protected uvScale: number[];
+    protected readDepth: ((timeSec: number) => Uint8Array) | null;
+    protected readInput: (() => EffectInput) | null;
+    protected mediaSource: MediaSource | 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);
+    /** The underlying canvas element. */
+    get canvasElement(): HTMLCanvasElement;
+    /**
+     * Begin the render loop.
+     *
+     * For live sources (video/camera) with RVFC support, 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.
+     *
+     * For static sources (image) or when RVFC is unavailable, RAF-only.
+     */
+    start(source: MediaSource, readDepth: (timeSec: number) => Uint8Array, readInput: () => EffectInput, 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/shared/channel-to-renderer.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Adapter: converts ChannelLayer[] → renderer configs.
+ *
+ * Both DepthEffectRenderer (WebGL2) and DepthEffectRendererWebGPU consume
+ * scalar config values. This adapter derives those scalars from the
+ * channel/curve model, keeping both renderers untouched.
+ *
+ * Also exports evaluateCurve(), which the curve editor UI will need.
+ */
+import type { ChannelLayer, DepthCurve } from './filter-config';
+/**
+ * Evaluate a DepthCurve at a given depth value (0-1).
+ */
+export declare function evaluateCurve(curve: DepthCurve, depth: number): number;
+/**
+ * Bake a DepthCurve into a sampled LUT (for GPU upload).
+ *
+ * DEPTH CONVENTION (canonical — see DEPTH_CONVENTION.md):
+ *   Depth Anything v2 outputs higher = closer.
+ *   The depth texture stores 0.0 = far, 1.0 = near.
+ *   The curve editor x-axis is 0 = far, 1 = near.
+ *   These match, so the LUT is a direct mapping with NO inversion.
+ *   The shader samples `texture(uCurve, vec2(depth, 0.5))`, and
+ *   depth=0(far) → LUT index 0 → curve x=0(far). Correct.
+ */
+export declare function bakeCurveLUT(curve: DepthCurve, size?: number): Uint8Array;
+export interface RendererConfigValues {
+    parallaxStrength: number;
+    pomEnabled: boolean;
+    pomSteps: number;
+    contrastLow: number;
+    contrastHigh: number;
+    verticalReduction: number;
+    dofStart: number;
+    dofStrength: number;
+    blurRadius: number;
+    glowColor: [number, number, number];
+    glowRadius: number;
+    glowSoftness: number;
+    tiltEnabled: boolean;
+    tiltHalfTanFov: number;
+    tiltTransitionWidth: number;
+    tiltPeakIntensity: number;
+}
+/**
+ * Derives DepthEffectRenderer config from the channel model.
+ *
+ * - Displacement channel params → strength, pomEnabled, pomSteps
+ * - Blur channel curve → dofStart, dofStrength
+ * - contrastLow/contrastHigh/verticalReduction have no channel equivalent
+ *   yet, so they're passed through from fallback values.
+ */
+export declare function channelsToRendererConfig(channels: ChannelLayer[], fallback: {
+    contrastLow: number;
+    contrastHigh: number;
+    verticalReduction: number;
+}): RendererConfigValues;
+export interface CurveLUTs {
+    displacementLUT: Uint8Array | null;
+    blurLUT: Uint8Array | null;
+    glowLUT: Uint8Array | null;
+    colorShiftLUT: Uint8Array | null;
+    colorShiftParams: {
+        hueShift: number;
+        saturation: number;
+        brightness: number;
+        tintStrength: number;
+        tintColor: [number, number, number];
+    } | null;
+}
+export declare function bakeCurveLUTs(channels: ChannelLayer[]): CurveLUTs;
+//# sourceMappingURL=channel-to-renderer.d.ts.map

package/dist/types/shared/channel-to-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-to-renderer.d.ts","sourceRoot":"","sources":["../../../src/shared/channel-to-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAe,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAM7E;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CA2BtE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,SAAM,GAAG,UAAU,CAOtE;AAcD,MAAM,WAAW,oBAAoB;IACnC,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,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,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,YAAY,EAAE,EACxB,QAAQ,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAA;CAAE,GACjF,oBAAoB,CAyCtB;AAED,MAAM,WAAW,SAAS;IACxB,eAAe,EAAE,UAAU,GAAG,IAAI,CAAC;IACnC,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;IAC3B,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;IAC3B,aAAa,EAAE,UAAU,GAAG,IAAI,CAAC;IACjC,gBAAgB,EAAE;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;KACrC,GAAG,IAAI,CAAC;CACV;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,SAAS,CAsBjE"}

package/dist/types/shared/filter-config.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Filter config schema — defines the shape of an authored filter.
+ *
+ * This is the central data model shared between the editor, web component,
+ * and export pipeline. Every parameter the user configures is captured here,
+ * and the export pipeline serializes it to JSON.
+ */
+export type EffectType = 'parallax' | 'tilt-shift' | 'depth-glow' | 'rack-focus' | 'depth-color-grade' | 'fog-atmosphere' | 'pop-out' | 'freestyle';
+export declare const EFFECT_LABELS: Record<EffectType, string>;
+export declare const EFFECT_DESCRIPTIONS: Record<EffectType, string>;
+export interface CurvePoint {
+    /** Depth position (0=far, 1=near). */
+    x: number;
+    /** Intensity at this depth (0-1). */
+    y: number;
+    /** Bezier handle for incoming tangent (relative to point). */
+    handleIn?: {
+        x: number;
+        y: number;
+    };
+    /** Bezier handle for outgoing tangent (relative to point). */
+    handleOut?: {
+        x: number;
+        y: number;
+    };
+}
+export type CurveInterpolation = 'linear' | 'smooth' | 'step';
+export interface DepthCurve {
+    /** Control points defining the curve shape. Must be sorted by x ascending. */
+    points: CurvePoint[];
+    /** Interpolation mode between control points. */
+    interpolation: CurveInterpolation;
+}
+export type ChannelType = 'displacement' | 'blur' | 'glow' | 'color-shift';
+export declare const CHANNEL_LABELS: Record<ChannelType, string>;
+export interface DisplacementChannelParams {
+    /** Overall displacement strength multiplier. */
+    strength: number;
+    /** Enable parallax occlusion mapping. */
+    pomEnabled: boolean;
+    /** POM ray-march step count. */
+    pomSteps: number;
+}
+export interface BlurChannelParams {
+    /** Maximum blur radius (at curve intensity = 1). */
+    maxRadius: number;
+    /** Blur kernel sample count. */
+    samples: number;
+    /** Parametric: center of the sharp focus band in depth space (0-1). Used by tilt-shift. */
+    focalCenter?: number;
+    /** Parametric: width of the sharp focus band (0-1). Used by tilt-shift. */
+    focalWidth?: number;
+    /** Parametric: peak blur intensity at edges (0-1). */
+    peakIntensity?: number;
+    /** Parametric: transition softness from sharp to blurred (0-1). */
+    transitionSoftness?: number;
+    /** Enable tilted focal plane blur (Scheimpflug simulation). Used by tilt-shift. */
+    tiltEnabled?: boolean;
+    /** Virtual FOV in degrees for pseudo-world reconstruction (default 50). */
+    tiltFov?: number;
+}
+export interface GlowChannelParams {
+    /** Glow color [r, g, b] each 0-1. */
+    color: [number, number, number];
+    /** Glow spread radius. */
+    radius: number;
+    /** Edge softness of glow boundary. */
+    softness: number;
+    /** Parametric: depth threshold below which glow begins (0-1, 0=near). */
+    glowThreshold?: number;
+    /** Parametric: peak glow intensity (0-1). */
+    glowIntensity?: number;
+}
+export interface ColorShiftChannelParams {
+    /** Hue rotation in degrees (-180 to 180). */
+    hueShift: number;
+    /** Saturation multiplier (0 = grayscale, 1 = unchanged, >1 = boosted). */
+    saturation: number;
+    /** Brightness/value multiplier (0 = black, 1 = unchanged, >1 = brighter). */
+    brightness: number;
+    /** Blend factor toward tintColor (0 = no tint, 1 = fully tinted). */
+    tintStrength: number;
+    /** Target tint color [r, g, b] each 0-1. Used for fog/atmosphere effects. */
+    tintColor: [number, number, number];
+    /** Depth where the color-shift effect begins (0=far, 1=near). */
+    depthStart: number;
+    /** Depth where the color-shift effect reaches full intensity. */
+    depthEnd: number;
+}
+export type ChannelParams = {
+    'displacement': DisplacementChannelParams;
+    'blur': BlurChannelParams;
+    'glow': GlowChannelParams;
+    'color-shift': ColorShiftChannelParams;
+};
+export interface ChannelLayer<T extends ChannelType = ChannelType> {
+    /** Which channel this layer drives. */
+    channel: T;
+    /** Depth-to-intensity transfer function. */
+    curve: DepthCurve;
+    /** Channel-specific parameters (non-depth-dependent knobs). */
+    params: ChannelParams[T];
+    /** Display label in the layer panel. */
+    label: string;
+    /** Mute this channel without deleting it. */
+    enabled: boolean;
+    /**
+     * True if the user has manually edited the curve in the curve editor.
+     * When set, parametric sliders update params but do NOT regenerate the curve,
+     * preserving the user's manual edits. Reset when switching effect presets.
+     */
+    curveManuallyEdited?: boolean;
+}
+export interface MotionConfig {
+    /** X-axis sensitivity multiplier. */
+    sensitivityX: number;
+    /** Y-axis sensitivity multiplier. */
+    sensitivityY: number;
+    /** Interpolation smoothing factor (0-1, lower = smoother). */
+    lerpFactor: number;
+    /** When true, XY input rotates a tilted focal plane in 3D space (Scheimpflug). */
+    tiltPlaneInput?: boolean;
+    /** Pitch sensitivity in radians per unit input Y (default 0.35). */
+    tiltPitchSensitivity?: number;
+    /** Yaw sensitivity in radians per unit input X (default 0.15). */
+    tiltYawSensitivity?: number;
+}
+export type EdgeStrategy = 'fade' | 'clamp' | 'mirror' | 'wrap';
+export interface FilterConfig {
+    /** Filter name (kebab-case, used for tag name: <layershift-{name}>). */
+    name: string;
+    /** Display name. */
+    displayName: string;
+    /** Effect type. */
+    effectType: EffectType;
+    /** Video source reference. */
+    video: {
+        id: string;
+        src: string;
+        depthSrc: string;
+        depthMeta: string;
+        type: 'video' | 'image';
+    };
+    /** Channel layer stack — the curve-based effect model. */
+    channels: ChannelLayer[];
+    /** Motion/input configuration. */
+    motion: MotionConfig;
+    /** Edge handling strategy. */
+    edgeStrategy: EdgeStrategy;
+    /** Overscan padding (UV space). */
+    overscanPadding: number;
+    /** Adaptive quality preference. */
+    quality: 'auto' | 'high' | 'medium' | 'low';
+}
+export declare const DEFAULT_MOTION: MotionConfig;
+export declare const DEFAULT_LINEAR_RISING: DepthCurve;
+export declare const DEFAULT_FLAT_FULL: DepthCurve;
+export declare const DEFAULT_VALLEY: DepthCurve;
+export declare const DEFAULT_CHANNEL_PARAMS: {
+    [K in ChannelType]: ChannelParams[K];
+};
+/** A single axis target. 'input' routes to renderer per-frame offset. */
+export interface InputAxisTarget {
+    /** 'input' for renderer offset, or a ChannelType for channel param. */
+    target: 'input' | ChannelType;
+    /** Param name within the target. */
+    param: string;
+    /** Display label for this axis. */
+    label: string;
+}
+export interface InputMapping {
+    x: InputAxisTarget;
+    y: InputAxisTarget;
+}
+/** Valid ranges for channel params controllable via the ball. */
+export declare const PARAM_RANGES: Record<string, {
+    min: number;
+    max: number;
+    default: number;
+}>;
+/** Default input mappings per effect type. */
+export declare const DEFAULT_INPUT_MAPPINGS: Record<EffectType, InputMapping>;
+export declare const DEFAULT_CHANNELS: ChannelLayer[];
+//# sourceMappingURL=filter-config.d.ts.map