@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/platform/xr-surface.js

@@ -0,0 +1,214 @@
+/// <reference path="./xr-types.d.ts" preserve="true" />
+/**
+ * The XR surface (ws/xr; ARCHITECTURE "Surface"): a `SceneTarget` per eye per frame. Built on
+ * the WebXR/WebGPU binding, it makes one `XRProjectionLayer` for the session (colour in
+ * `SCENE_FORMAT`, since every material's pipeline writes that format, plus a `DEPTH_FORMAT`
+ * depth texture) and each frame turns the viewer pose into `XrEyeView`s: a `Camera` whose
+ * projection and view matrices are the `XRView`'s (`viewIndex` = eye index, depth on) and a
+ * `SceneTarget` adopting the eye's part of the layer (`SceneTarget.external`). Eyes that share
+ * one layer texture (the default `texture` layout, side by side) share one target and differ by
+ * `camera.screen`, so the renderer clears it once and scissors each eye to its viewport; a
+ * `texture-array` layer gives each eye its own target over its array layer.
+ *
+ * Two ways to draw the eyes. Direct (the default): each eye is a scene pass into its layer
+ * target; the colour goes to the layer as linear HDR, the emissive target is written and
+ * dropped and no post stack runs. Through the post stack (`scene: true`, ws/xr-post, what
+ * `createGame` uses): the surface keeps `scene`, one HDR `SceneTarget` the size of an eye
+ * (allocated on the first frame, resized when the layer's eye size changes), every eye camera
+ * covers it whole and the caller renders each eye into it and resolves it into the eye's layer
+ * target at `eye.viewport` (`renderer.render(frame, eye.camera, surface.scene)` then
+ * `renderer.resolve(surface.scene, eye.target.color.view, eye.viewport)`), so the headset sees
+ * the same bloom, tone map and grade as the screen; the layer then takes `colorFormat`, the
+ * format the post stack writes (`renderer.format`), and no depth by default.
+ *
+ * `head` is a camera at the viewer pose with the first eye's projection, for the scenes' one
+ * `render(frame, camera, alpha)` call per frame.
+ */
+import { Camera } from '../render/camera.js';
+import { DEPTH_FORMAT } from '../render/material.js';
+import { SCENE_FORMAT, SceneTarget, } from '../render/scene-target.js';
+class EyeView {
+    index;
+    eye = 'none';
+    camera;
+    target;
+    viewport = { x: 0, y: 0, width: 0, height: 0 };
+    /** The array layer this eye reads through (0 for a plain texture). */
+    layer = 0;
+    /** This eye's own target, used unless an earlier eye already adopted the same texture. */
+    own;
+    constructor(index, device, first, aux) {
+        this.index = index;
+        this.camera = new Camera();
+        this.camera.depthTest = true;
+        this.camera.depthWrite = true;
+        this.camera.viewIndex = index;
+        this.own = SceneTarget.external({
+            device,
+            color: first.colorTexture,
+            depth: first.depthStencilTexture,
+            view: first.getViewDescriptor(),
+            label: `xr-eye-${index}`,
+            aux,
+        });
+        this.target = this.own;
+    }
+}
+export class XrSurface {
+    session;
+    device;
+    binding;
+    layer;
+    referenceSpace;
+    /**
+     * A camera at the viewer pose (between the eyes) with the first eye's projection, depth on,
+     * updated by `views`: what the scenes record through once per frame.
+     */
+    head = new Camera();
+    /**
+     * With `scene: true`, the eye-sized HDR target every eye renders into before `resolve`;
+     * made by the first `views` with a pose and resized when the eye size changes. Null before
+     * then, and always null for a direct surface.
+     */
+    scene = null;
+    eyes = [];
+    out = [];
+    viaScene;
+    /** `opts.aux`: on the scene target with `scene`, else on each eye target. */
+    aux;
+    destroyed = false;
+    /**
+     * Makes the session's projection layer and installs it (`session.updateRenderState`).
+     * Throws where the browser has no `XRGPUBinding`; check `XrSurface.supported()` first.
+     */
+    constructor(session, device, opts) {
+        this.session = session;
+        this.device = device;
+        const Binding = globalThis.XRGPUBinding;
+        if (!Binding)
+            throw new Error('XrSurface: this browser has no WebXR/WebGPU binding');
+        this.referenceSpace = opts.referenceSpace;
+        this.viaScene = opts.scene === true;
+        this.aux = opts.aux;
+        this.binding = new Binding(session, device);
+        const depth = opts.depthStencilFormat === undefined
+            ? this.viaScene
+                ? null
+                : DEPTH_FORMAT
+            : opts.depthStencilFormat;
+        this.layer = this.binding.createProjectionLayer({
+            colorFormat: opts.colorFormat ?? SCENE_FORMAT,
+            ...(depth ? { depthStencilFormat: depth } : {}),
+            textureType: opts.textureType ?? 'texture',
+        });
+        session.updateRenderState({
+            layers: [this.layer],
+            depthNear: opts.depthNear ?? 0.1,
+            depthFar: opts.depthFar ?? 1000,
+        });
+        this.head.depthTest = true;
+        this.head.depthWrite = true;
+    }
+    /** True where `XRGPUBinding` exists (the WebXR/WebGPU binding). */
+    static supported() {
+        return typeof globalThis.XRGPUBinding !== 'undefined';
+    }
+    /**
+     * The eyes of this frame, in viewer-pose order, each with its camera aimed and its target
+     * adopting the layer's texture for the frame. Empty when the pose is unavailable (tracking
+     * lost). The array and the views are reused; read them within the frame.
+     */
+    views(frame) {
+        const out = this.out;
+        out.length = 0;
+        if (this.destroyed)
+            return out;
+        const pose = frame.getViewerPose(this.referenceSpace);
+        if (!pose)
+            return out;
+        const views = pose.views;
+        for (let i = 0; i < views.length; i++) {
+            const v = views[i];
+            const sub = this.binding.getViewSubImage(this.layer, v);
+            let eye = this.eyes[i];
+            if (!eye) {
+                eye = new EyeView(i, this.device, sub, this.viaScene ? undefined : this.aux);
+                this.eyes[i] = eye;
+            }
+            eye.eye = v.eye;
+            const cam = eye.camera;
+            cam.setProjection(v.projectionMatrix);
+            cam.setViewMatrix(v.transform.inverse.matrix);
+            const vd = sub.getViewDescriptor();
+            const layer = vd.baseArrayLayer ?? 0;
+            const vp = eye.viewport;
+            vp.x = sub.viewport.x;
+            vp.y = sub.viewport.y;
+            vp.width = sub.viewport.width;
+            vp.height = sub.viewport.height;
+            // An earlier eye on the same texture and array layer: share its target (one clear).
+            let target = null;
+            for (let j = 0; j < i; j++) {
+                const o = out[j];
+                if (o.target.adoptedColor === sub.colorTexture && o.layer === layer) {
+                    target = o.target;
+                    break;
+                }
+            }
+            if (!target) {
+                target = eye.own;
+                target.adopt({
+                    color: sub.colorTexture,
+                    depth: sub.depthStencilTexture,
+                    view: vd,
+                    viewport: vp,
+                });
+            }
+            eye.target = target;
+            eye.layer = layer;
+            const s = cam.screen;
+            if (this.viaScene) {
+                // The eye renders into the whole scene target; `viewport` places the resolve.
+                s.x = 0;
+                s.y = 0;
+                s.width = 1;
+                s.height = 1;
+                const sc = this.scene ?? this.makeScene();
+                sc.resize(vp.width, vp.height);
+            }
+            else {
+                s.x = vp.x / target.width;
+                s.y = vp.y / target.height;
+                s.width = vp.width / target.width;
+                s.height = vp.height / target.height;
+            }
+            out.push(eye);
+        }
+        if (views.length > 0) {
+            this.head.setProjection(views[0].projectionMatrix);
+            this.head.setViewMatrix(pose.transform.inverse.matrix);
+        }
+        return out;
+    }
+    makeScene() {
+        this.scene = new SceneTarget(this.device, {
+            width: 1,
+            height: 1,
+            label: 'xr-scene',
+            aux: this.aux,
+        });
+        return this.scene;
+    }
+    /** Frees the eye targets' own textures, the scene target and the layer. The session is left to its owner. */
+    destroy() {
+        if (this.destroyed)
+            return;
+        this.destroyed = true;
+        for (const e of this.eyes)
+            e.own.destroy();
+        this.eyes.length = 0;
+        this.scene?.destroy();
+        this.scene = null;
+        this.layer.destroy();
+    }
+}

package/dist/platform/xr-types.d.ts

@@ -0,0 +1,262 @@
+/**
+ * Ambient declarations for the parts of the WebXR Device API, the WebXR Hand Input module and
+ * the WebXR/WebGPU binding the engine uses (ws/xr). TypeScript's DOM lib has none of them and
+ * the engine takes no `@types/webxr` dependency. Everything here is optional at runtime: callers
+ * check `navigator.xr` and `XRGPUBinding` before touching them, so the engine typechecks and
+ * runs where WebXR is missing (every row of the e2e matrix). Files that use these types
+ * reference this file with `/// <reference path="…/xr-types.d.ts" />` so a program that enters
+ * the engine through `harness/` (tsconfig.e2e.json) sees them too.
+ */
+
+type XRSessionMode = 'inline' | 'immersive-vr' | 'immersive-ar';
+type XRReferenceSpaceType = 'viewer' | 'local' | 'local-floor' | 'bounded-floor' | 'unbounded';
+type XREye = 'none' | 'left' | 'right';
+type XRHandedness = 'none' | 'left' | 'right';
+type XRTargetRayMode = 'gaze' | 'tracked-pointer' | 'screen' | 'transient-pointer';
+type XRHandJoint =
+  | 'wrist'
+  | 'thumb-metacarpal'
+  | 'thumb-phalanx-proximal'
+  | 'thumb-phalanx-distal'
+  | 'thumb-tip'
+  | 'index-finger-metacarpal'
+  | 'index-finger-phalanx-proximal'
+  | 'index-finger-phalanx-intermediate'
+  | 'index-finger-phalanx-distal'
+  | 'index-finger-tip'
+  | 'middle-finger-metacarpal'
+  | 'middle-finger-phalanx-proximal'
+  | 'middle-finger-phalanx-intermediate'
+  | 'middle-finger-phalanx-distal'
+  | 'middle-finger-tip'
+  | 'ring-finger-metacarpal'
+  | 'ring-finger-phalanx-proximal'
+  | 'ring-finger-phalanx-intermediate'
+  | 'ring-finger-phalanx-distal'
+  | 'ring-finger-tip'
+  | 'pinky-finger-metacarpal'
+  | 'pinky-finger-phalanx-proximal'
+  | 'pinky-finger-phalanx-intermediate'
+  | 'pinky-finger-phalanx-distal'
+  | 'pinky-finger-tip';
+
+interface XRSessionInit {
+  requiredFeatures?: string[];
+  optionalFeatures?: string[];
+}
+
+interface XRSystem {
+  isSessionSupported(mode: XRSessionMode): Promise<boolean>;
+  requestSession(mode: XRSessionMode, init?: XRSessionInit): Promise<XRSession>;
+}
+
+interface Navigator {
+  /** The WebXR entry point; undefined where the browser has no WebXR. */
+  readonly xr?: XRSystem;
+}
+
+interface XRRigidTransform {
+  readonly position: DOMPointReadOnly;
+  readonly orientation: DOMPointReadOnly;
+  /** Column-major 4×4, the same layout as `mat4`. */
+  readonly matrix: Float32Array;
+  readonly inverse: XRRigidTransform;
+}
+
+// biome-ignore lint/suspicious/noEmptyInterface: an opaque handle
+interface XRSpace {}
+
+interface XRReferenceSpace extends XRSpace {
+  getOffsetReferenceSpace(originOffset: XRRigidTransform): XRReferenceSpace;
+}
+
+interface XRJointSpace extends XRSpace {
+  readonly jointName: XRHandJoint;
+}
+
+interface XRHand {
+  readonly size: number;
+  get(joint: XRHandJoint): XRJointSpace | undefined;
+}
+
+interface XRPose {
+  readonly transform: XRRigidTransform;
+  readonly emulatedPosition: boolean;
+}
+
+interface XRJointPose extends XRPose {
+  /** Joint radius in metres. */
+  readonly radius: number | undefined;
+}
+
+interface XRViewport {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+interface XRView {
+  readonly eye: XREye;
+  /** Column-major 4×4 projection for this eye. */
+  readonly projectionMatrix: Float32Array;
+  /** The eye's pose in the reference space; `transform.inverse.matrix` is the view matrix. */
+  readonly transform: XRRigidTransform;
+  readonly recommendedViewportScale?: number | null;
+  requestViewportScale?(scale: number | null): void;
+}
+
+interface XRViewerPose extends XRPose {
+  readonly views: readonly XRView[];
+}
+
+interface XRInputSource {
+  readonly handedness: XRHandedness;
+  readonly targetRayMode: XRTargetRayMode;
+  readonly targetRaySpace: XRSpace;
+  readonly gripSpace?: XRSpace | null;
+  /** `xr-standard` mapping: `buttons[0]` is the trigger, `buttons[1]` the squeeze. */
+  readonly gamepad?: Gamepad | null;
+  readonly hand?: XRHand | null;
+  readonly profiles: readonly string[];
+}
+
+interface XRInputSourceArray {
+  readonly length: number;
+  [index: number]: XRInputSource;
+  [Symbol.iterator](): IterableIterator<XRInputSource>;
+}
+
+interface XRFrame {
+  readonly session: XRSession;
+  readonly predictedDisplayTime: number;
+  getViewerPose(referenceSpace: XRReferenceSpace): XRViewerPose | undefined;
+  getPose(space: XRSpace, baseSpace: XRSpace): XRPose | undefined;
+  /** Hand Input module; missing where hands are not supported. */
+  getJointPose?(joint: XRJointSpace, baseSpace: XRSpace): XRJointPose | undefined;
+}
+
+type XRFrameRequestCallback = (time: DOMHighResTimeStamp, frame: XRFrame) => void;
+
+interface XRRenderStateInit {
+  depthNear?: number;
+  depthFar?: number;
+  layers?: XRLayer[];
+}
+
+interface XRRenderState {
+  readonly depthNear: number;
+  readonly depthFar: number;
+  readonly layers?: readonly XRLayer[];
+}
+
+interface XRSessionEvent extends Event {
+  readonly session: XRSession;
+}
+
+interface XRInputSourceEvent extends Event {
+  readonly frame: XRFrame;
+  readonly inputSource: XRInputSource;
+}
+
+interface XRInputSourcesChangeEvent extends Event {
+  readonly session: XRSession;
+  readonly added: readonly XRInputSource[];
+  readonly removed: readonly XRInputSource[];
+}
+
+interface XRSessionEventMap {
+  end: XRSessionEvent;
+  inputsourceschange: XRInputSourcesChangeEvent;
+  select: XRInputSourceEvent;
+  selectstart: XRInputSourceEvent;
+  selectend: XRInputSourceEvent;
+  squeeze: XRInputSourceEvent;
+  squeezestart: XRInputSourceEvent;
+  squeezeend: XRInputSourceEvent;
+  visibilitychange: XRSessionEvent;
+}
+
+interface XRSession extends EventTarget {
+  readonly inputSources: XRInputSourceArray;
+  readonly renderState: XRRenderState;
+  readonly visibilityState: 'visible' | 'visible-blurred' | 'hidden';
+  requestReferenceSpace(type: XRReferenceSpaceType): Promise<XRReferenceSpace>;
+  updateRenderState(state?: XRRenderStateInit): void;
+  requestAnimationFrame(callback: XRFrameRequestCallback): number;
+  cancelAnimationFrame(handle: number): void;
+  end(): Promise<void>;
+  addEventListener<K extends keyof XRSessionEventMap>(
+    type: K,
+    listener: (this: XRSession, ev: XRSessionEventMap[K]) => void,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  removeEventListener<K extends keyof XRSessionEventMap>(
+    type: K,
+    listener: (this: XRSession, ev: XRSessionEventMap[K]) => void,
+    options?: boolean | EventListenerOptions,
+  ): void;
+  removeEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | EventListenerOptions,
+  ): void;
+}
+
+// ── WebXR Layers + WebXR/WebGPU binding ───────────────────────────────────────
+
+// biome-ignore lint/suspicious/noEmptyInterface: an opaque handle
+interface XRLayer {}
+
+interface XRCompositionLayer extends XRLayer {
+  readonly layout: 'default' | 'mono' | 'stereo' | 'stereo-left-right' | 'stereo-top-bottom';
+  readonly mipLevels: number;
+  needsRedraw: boolean;
+  destroy(): void;
+}
+
+interface XRProjectionLayer extends XRCompositionLayer {
+  readonly textureWidth: number;
+  readonly textureHeight: number;
+  readonly textureArrayLength: number;
+  readonly ignoreDepthValues: boolean;
+  fixedFoveation?: number | null;
+}
+
+interface XRGPUProjectionLayerInit {
+  colorFormat?: GPUTextureFormat;
+  depthStencilFormat?: GPUTextureFormat;
+  /** `texture` (default): one texture, eyes side by side; `texture-array`: one layer per eye. */
+  textureType?: 'texture' | 'texture-array';
+  textureUsage?: GPUTextureUsageFlags;
+  scaleFactor?: number;
+}
+
+interface XRGPUSubImage {
+  readonly colorTexture: GPUTexture;
+  readonly depthStencilTexture?: GPUTexture | null;
+  /** The part of `colorTexture` this view draws into, in texture pixels, origin top-left. */
+  readonly viewport: XRViewport;
+  /** The texture view to make (array layer, mip) for this view. */
+  getViewDescriptor(): GPUTextureViewDescriptor;
+}
+
+interface XRGPUBinding {
+  readonly nativeProjectionScaleFactor: number;
+  createProjectionLayer(init?: XRGPUProjectionLayerInit): XRProjectionLayer;
+  getViewSubImage(layer: XRProjectionLayer, view: XRView): XRGPUSubImage;
+  getPreferredColorFormat(): GPUTextureFormat;
+}
+
+interface XRGPUBindingConstructor {
+  readonly prototype: XRGPUBinding;
+  new (session: XRSession, device: GPUDevice): XRGPUBinding;
+}
+
+/** The WebXR/WebGPU binding; undefined where the browser does not have it. */
+declare var XRGPUBinding: XRGPUBindingConstructor | undefined;

package/dist/post/ao.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The AO sample radius in uv (0..1 of the screen) for a world `radius` at view depth `z`
+ * through a projection of x scale `projScale`: `projScale × radius / z / 2` under a
+ * perspective camera, `projScale × radius / 2` under an orthographic one (where depth does not
+ * shrink anything). The shader's `ruv` does the same.
+ */
+export declare function aoProjectedRadius(radius: number, projScale: number, z: number, ortho: boolean): number;
+/** Shared by both AO passes and DoF: depth → view-space position. */
+export declare const WGSL_DEPTH_VIEW = "\nfn view_pos(uv: vec2f, depth: f32) -> vec3f {\n  let ndc = vec3f(uv.x * 2.0 - 1.0, 1.0 - uv.y * 2.0, depth);\n  let p = P.invProj * vec4f(ndc, 1.0);\n  return p.xyz / p.w;\n}\nfn linear_depth(uv: vec2f, depth: f32) -> f32 {\n  return -view_pos(uv, depth).z;\n}\n/** The centre of the depth texel under `uv`: positions must be rebuilt where the depth was read. */\nfn texel_uv(uv: vec2f, dim: vec2f) -> vec2f {\n  return (floor(clamp(uv, vec2f(0.0), vec2f(0.9999)) * dim) + 0.5) / dim;\n}\n";
+export declare const AO_WGSL = "\n\nstruct PostUniforms {\n  frame: vec4f,      // time, aspect, 1/width, 1/height\n  enables: vec4f,    // bloom, fog, rays, vignette\n  enables2: vec4f,   // grade, tonemap (0 none, 1 aces, 2 reinhard), dither, exposure\n  bloom: vec4f,      // intensity, threshold, knee, emissiveWeight\n  bloom2: vec4f,     // scatter, -, -, -\n  fogColor: vec4f,   // rgb, density\n  fog: vec4f,        // top, bottom, noiseScale, speed\n  fog2: vec4f,       // lightScatter, falloff, -, -\n  rays: vec4f,       // light uv x, y, intensity, decay\n  rays2: vec4f,      // density, weight, source radius (uv-y units), source intensity\n  raysColor: vec4f,  // rgb, bloomSource\n  vignette: vec4f,   // intensity, radius, softness, -\n  vignetteColor: vec4f,\n  lift: vec4f,\n  gamma: vec4f,\n  gain: vec4f,\n  grade: vec4f,      // saturation, contrast, -, -\n  quality: vec4f,    // ray samples, fog octaves, ortho projection (1, ws/post-4), -\n  ao: vec4f,         // enabled (0 without depth), radius, intensity, bias\n  ao2: vec4f,        // power, samples, proj x scale, proj y scale\n  dof: vec4f,        // enabled (0 without depth), focus distance, focus range, max blur (uv of width)\n  dof2: vec4f,       // near blur, taps, near plane, far plane\n  invProj: mat4x4f,  // clip -> view\n  fxaa: vec4f,       // enabled, subpixel, edgeThreshold, -\n  lut: vec4f,        // enabled, (size-1)/size, intensity, 0.5/size\n  grain: vec4f,      // intensity, cell size (px), luminanceResponse, seed\n  aberration: vec4f, // intensity (px), radialOnly, -, -\n  sharpen: vec4f,    // amount, -, -, -\n  outline: vec4f,    // enabled (0 without depth), thickness (scene px), depthThreshold, normalThreshold\n  outlineColor: vec4f, // rgb, intensity\n  // Post 3 (ws/post-3).\n  taa: vec4f,        // enabled (0 without depth), feedback, sharpen, clampMode (0 aabb, 1 variance)\n  taa2: vec4f,       // view jitter x (uv), view jitter y (uv), reset (1 = copy the current frame), velocity reprojection (1, ws/post-5)\n  ssr: vec4f,        // enabled (0 without depth), maxSteps, thickness, maxDistance\n  ssr2: vec4f,       // roughnessCutoff, intensity, fadeEdges (uv), rough-metal target (1)\n  exposure: vec4f,   // auto (1), histogramLow, histogramHigh, keyValue\n  wb0: vec4f,        // white-balance matrix row 0 (rgb weights), enabled\n  wb1: vec4f,        // row 1\n  wb2: vec4f,        // row 2\n  motionBlur: vec4f, // enabled (0 without depth), intensity, samples, velocity target (1 = object)\n  dirt: vec4f,       // enabled, intensity, -, -\n  reproj: mat4x4f,   // current clip -> previous frame's clip (identity on a reset)\n  // Post 5 (ws/post-5).\n  taa3: vec4f,       // depthReject (fraction), velocityReject (px), history filter (1 = Catmull-Rom, ws/post-6), -\n};\n@group(0) @binding(0) var<uniform> P: PostUniforms;\n\n@group(0) @binding(1) var nearest: sampler;\n@group(0) @binding(2) var linSamp: sampler;\n@group(0) @binding(3) var depthTex: texture_depth_2d;\n\nfn view_pos(uv: vec2f, depth: f32) -> vec3f {\n  let ndc = vec3f(uv.x * 2.0 - 1.0, 1.0 - uv.y * 2.0, depth);\n  let p = P.invProj * vec4f(ndc, 1.0);\n  return p.xyz / p.w;\n}\nfn linear_depth(uv: vec2f, depth: f32) -> f32 {\n  return -view_pos(uv, depth).z;\n}\n/** The centre of the depth texel under `uv`: positions must be rebuilt where the depth was read. */\nfn texel_uv(uv: vec2f, dim: vec2f) -> vec2f {\n  return (floor(clamp(uv, vec2f(0.0), vec2f(0.9999)) * dim) + 0.5) / dim;\n}\n\n\n/** Depth at the texel under `uv` and the view position of that texel's centre (w = depth). */\nfn fetch(uv: vec2f, dim: vec2f) -> vec4f {\n  let tuv = texel_uv(uv, dim);\n  let d = textureSampleLevel(depthTex, nearest, tuv, 0u);\n  return vec4f(view_pos(tuv, d), d);\n}\n\n/** Interleaved-gradient noise (Jimenez 2014), 0..1 per output pixel. */\nfn ign(px: vec2f) -> f32 {\n  return fract(52.9829189 * fract(0.06711056 * px.x + 0.00583715 * px.y));\n}\n\n@fragment fn fs_main(in: FullscreenIn) -> @location(0) vec4f {\n  let dim = vec2f(textureDimensions(depthTex));\n  let c = fetch(in.uv, dim);\n  if (c.w >= 1.0) {\n    return vec4f(1.0);\n  }\n  let p = c.xyz;\n  let uv = texel_uv(in.uv, dim);\n  // Normal from the closer neighbour on each axis (one depth texel).\n  let t = 1.0 / dim;\n  let pl = fetch(uv - vec2f(t.x, 0.0), dim).xyz;\n  let pr = fetch(uv + vec2f(t.x, 0.0), dim).xyz;\n  let pu = fetch(uv - vec2f(0.0, t.y), dim).xyz;\n  let pd = fetch(uv + vec2f(0.0, t.y), dim).xyz;\n  var dx = pr - p;\n  if (abs(pl.z - p.z) < abs(pr.z - p.z)) { dx = p - pl; }\n  var dy = pu - p;\n  if (abs(pd.z - p.z) < abs(pu.z - p.z)) { dy = p - pd; }\n  let n = normalize(cross(dx, dy));\n\n  let radius = P.ao.y;\n  let z = -p.z;\n  // World radius projected to uv: proj scale (over the depth under a perspective camera, not\n  // under an ortho one: P.quality.z), halved for the -1..1 \u2192 0..1 range.\n  let zs = select(max(z, 1e-3), 1.0, P.quality.z > 0.5);\n  let ruv = vec2f(P.ao2.z, P.ao2.w) * radius / zs * 0.5;\n  let count = i32(P.ao2.y);\n  let rot = ign(in.pos.xy) * 6.2831853;\n  var occ = 0.0;\n  for (var i = 0; i < count; i++) {\n    let a = (f32(i) + 0.5) / f32(count);\n    let ang = rot + a * 6.2831853 * 3.0;\n    let suv = uv + vec2f(cos(ang), sin(ang)) * ruv * sqrt(a);\n    let s = fetch(suv, dim);\n    if (s.w >= 1.0) { continue; }\n    let sp = s.xyz;\n    let v = sp - p;\n    let vv = dot(v, v);\n    let vn = dot(v, n) - P.ao.w;\n    let falloff = max(0.0, 1.0 - vv / (radius * radius));\n    occ += max(0.0, vn * inverseSqrt(vv + 1e-4)) * falloff;\n  }\n  occ = occ / f32(count) * 2.0 * P.ao.z;\n  let ao = pow(clamp(1.0 - occ, 0.0, 1.0), P.ao2.x);\n  return vec4f(ao, ao, ao, 1.0);\n}\n";
+/** 4×4 depth-aware blur of the AO term (half res in, half res out). */
+export declare const AO_BLUR_WGSL = "\n\nstruct PostUniforms {\n  frame: vec4f,      // time, aspect, 1/width, 1/height\n  enables: vec4f,    // bloom, fog, rays, vignette\n  enables2: vec4f,   // grade, tonemap (0 none, 1 aces, 2 reinhard), dither, exposure\n  bloom: vec4f,      // intensity, threshold, knee, emissiveWeight\n  bloom2: vec4f,     // scatter, -, -, -\n  fogColor: vec4f,   // rgb, density\n  fog: vec4f,        // top, bottom, noiseScale, speed\n  fog2: vec4f,       // lightScatter, falloff, -, -\n  rays: vec4f,       // light uv x, y, intensity, decay\n  rays2: vec4f,      // density, weight, source radius (uv-y units), source intensity\n  raysColor: vec4f,  // rgb, bloomSource\n  vignette: vec4f,   // intensity, radius, softness, -\n  vignetteColor: vec4f,\n  lift: vec4f,\n  gamma: vec4f,\n  gain: vec4f,\n  grade: vec4f,      // saturation, contrast, -, -\n  quality: vec4f,    // ray samples, fog octaves, ortho projection (1, ws/post-4), -\n  ao: vec4f,         // enabled (0 without depth), radius, intensity, bias\n  ao2: vec4f,        // power, samples, proj x scale, proj y scale\n  dof: vec4f,        // enabled (0 without depth), focus distance, focus range, max blur (uv of width)\n  dof2: vec4f,       // near blur, taps, near plane, far plane\n  invProj: mat4x4f,  // clip -> view\n  fxaa: vec4f,       // enabled, subpixel, edgeThreshold, -\n  lut: vec4f,        // enabled, (size-1)/size, intensity, 0.5/size\n  grain: vec4f,      // intensity, cell size (px), luminanceResponse, seed\n  aberration: vec4f, // intensity (px), radialOnly, -, -\n  sharpen: vec4f,    // amount, -, -, -\n  outline: vec4f,    // enabled (0 without depth), thickness (scene px), depthThreshold, normalThreshold\n  outlineColor: vec4f, // rgb, intensity\n  // Post 3 (ws/post-3).\n  taa: vec4f,        // enabled (0 without depth), feedback, sharpen, clampMode (0 aabb, 1 variance)\n  taa2: vec4f,       // view jitter x (uv), view jitter y (uv), reset (1 = copy the current frame), velocity reprojection (1, ws/post-5)\n  ssr: vec4f,        // enabled (0 without depth), maxSteps, thickness, maxDistance\n  ssr2: vec4f,       // roughnessCutoff, intensity, fadeEdges (uv), rough-metal target (1)\n  exposure: vec4f,   // auto (1), histogramLow, histogramHigh, keyValue\n  wb0: vec4f,        // white-balance matrix row 0 (rgb weights), enabled\n  wb1: vec4f,        // row 1\n  wb2: vec4f,        // row 2\n  motionBlur: vec4f, // enabled (0 without depth), intensity, samples, velocity target (1 = object)\n  dirt: vec4f,       // enabled, intensity, -, -\n  reproj: mat4x4f,   // current clip -> previous frame's clip (identity on a reset)\n  // Post 5 (ws/post-5).\n  taa3: vec4f,       // depthReject (fraction), velocityReject (px), history filter (1 = Catmull-Rom, ws/post-6), -\n};\n@group(0) @binding(0) var<uniform> P: PostUniforms;\n\n@group(0) @binding(1) var nearest: sampler;\n@group(0) @binding(2) var linSamp: sampler;\n@group(0) @binding(3) var depthTex: texture_depth_2d;\n@group(0) @binding(4) var aoTex: texture_2d<f32>;\n\nfn view_pos(uv: vec2f, depth: f32) -> vec3f {\n  let ndc = vec3f(uv.x * 2.0 - 1.0, 1.0 - uv.y * 2.0, depth);\n  let p = P.invProj * vec4f(ndc, 1.0);\n  return p.xyz / p.w;\n}\nfn linear_depth(uv: vec2f, depth: f32) -> f32 {\n  return -view_pos(uv, depth).z;\n}\n/** The centre of the depth texel under `uv`: positions must be rebuilt where the depth was read. */\nfn texel_uv(uv: vec2f, dim: vec2f) -> vec2f {\n  return (floor(clamp(uv, vec2f(0.0), vec2f(0.9999)) * dim) + 0.5) / dim;\n}\n\n\n@fragment fn fs_main(in: FullscreenIn) -> @location(0) vec4f {\n  let dim = vec2f(textureDimensions(depthTex));\n  let uv = in.uv;\n  let t = 1.0 / vec2f(textureDimensions(aoTex));\n  let dc = textureSampleLevel(depthTex, nearest, uv, 0u);\n  if (dc >= 1.0) {\n    return vec4f(1.0);\n  }\n  let zc = linear_depth(texel_uv(uv, dim), dc);\n  var sum = 0.0;\n  var wsum = 0.0;\n  for (var y = 0; y < 4; y++) {\n    for (var x = 0; x < 4; x++) {\n      let o = vec2f(f32(x) - 1.5, f32(y) - 1.5) * t;\n      let suv = uv + o;\n      let zs = linear_depth(texel_uv(suv, dim), textureSampleLevel(depthTex, nearest, suv, 0u));\n      let w = 1.0 / (1.0 + 16.0 * abs(zs - zc) / max(zc, 1e-3));\n      sum += textureSampleLevel(aoTex, nearest, suv, 0.0).r * w;\n      wsum += w;\n    }\n  }\n  let ao = sum / max(wsum, 1e-4);\n  return vec4f(ao, ao, ao, 1.0);\n}\n";

package/dist/post/ao.js

@@ -0,0 +1,136 @@
+/**
+ * Screen-space ambient occlusion (ws/post-depth): a half-res pass over the scene depth, then a
+ * 4×4 depth-aware blur. The composite multiplies the result into the scene colour before bloom.
+ *
+ * Positions come back from depth through `P.invProj`; normals from the smaller of the two depth
+ * differences on each axis (so creases keep their edge). 12 (`PostQuality.aoSamples`) spiral
+ * samples per pixel, rotated per pixel by interleaved-gradient noise, weighted by the cosine
+ * to the normal and a smooth falloff inside `ao.radius`. The radius projects to the screen
+ * through the projection's x/y scale, over the view depth for a perspective camera and without
+ * it for an orthographic one (`aoProjectedRadius`, ws/post-4).
+ */
+import { WGSL_POST_UNIFORMS } from './settings.js';
+/**
+ * The AO sample radius in uv (0..1 of the screen) for a world `radius` at view depth `z`
+ * through a projection of x scale `projScale`: `projScale × radius / z / 2` under a
+ * perspective camera, `projScale × radius / 2` under an orthographic one (where depth does not
+ * shrink anything). The shader's `ruv` does the same.
+ */
+export function aoProjectedRadius(radius, projScale, z, ortho) {
+    return (projScale * radius * 0.5) / (ortho ? 1 : Math.max(z, 1e-3));
+}
+/** Shared by both AO passes and DoF: depth → view-space position. */
+export const WGSL_DEPTH_VIEW = /* wgsl */ `
+fn view_pos(uv: vec2f, depth: f32) -> vec3f {
+  let ndc = vec3f(uv.x * 2.0 - 1.0, 1.0 - uv.y * 2.0, depth);
+  let p = P.invProj * vec4f(ndc, 1.0);
+  return p.xyz / p.w;
+}
+fn linear_depth(uv: vec2f, depth: f32) -> f32 {
+  return -view_pos(uv, depth).z;
+}
+/** The centre of the depth texel under \`uv\`: positions must be rebuilt where the depth was read. */
+fn texel_uv(uv: vec2f, dim: vec2f) -> vec2f {
+  return (floor(clamp(uv, vec2f(0.0), vec2f(0.9999)) * dim) + 0.5) / dim;
+}
+`;
+export const AO_WGSL = /* wgsl */ `
+${WGSL_POST_UNIFORMS}
+@group(0) @binding(1) var nearest: sampler;
+@group(0) @binding(2) var linSamp: sampler;
+@group(0) @binding(3) var depthTex: texture_depth_2d;
+${WGSL_DEPTH_VIEW}
+
+/** Depth at the texel under \`uv\` and the view position of that texel's centre (w = depth). */
+fn fetch(uv: vec2f, dim: vec2f) -> vec4f {
+  let tuv = texel_uv(uv, dim);
+  let d = textureSampleLevel(depthTex, nearest, tuv, 0u);
+  return vec4f(view_pos(tuv, d), d);
+}
+
+/** Interleaved-gradient noise (Jimenez 2014), 0..1 per output pixel. */
+fn ign(px: vec2f) -> f32 {
+  return fract(52.9829189 * fract(0.06711056 * px.x + 0.00583715 * px.y));
+}
+
+@fragment fn fs_main(in: FullscreenIn) -> @location(0) vec4f {
+  let dim = vec2f(textureDimensions(depthTex));
+  let c = fetch(in.uv, dim);
+  if (c.w >= 1.0) {
+    return vec4f(1.0);
+  }
+  let p = c.xyz;
+  let uv = texel_uv(in.uv, dim);
+  // Normal from the closer neighbour on each axis (one depth texel).
+  let t = 1.0 / dim;
+  let pl = fetch(uv - vec2f(t.x, 0.0), dim).xyz;
+  let pr = fetch(uv + vec2f(t.x, 0.0), dim).xyz;
+  let pu = fetch(uv - vec2f(0.0, t.y), dim).xyz;
+  let pd = fetch(uv + vec2f(0.0, t.y), dim).xyz;
+  var dx = pr - p;
+  if (abs(pl.z - p.z) < abs(pr.z - p.z)) { dx = p - pl; }
+  var dy = pu - p;
+  if (abs(pd.z - p.z) < abs(pu.z - p.z)) { dy = p - pd; }
+  let n = normalize(cross(dx, dy));
+
+  let radius = P.ao.y;
+  let z = -p.z;
+  // World radius projected to uv: proj scale (over the depth under a perspective camera, not
+  // under an ortho one: P.quality.z), halved for the -1..1 → 0..1 range.
+  let zs = select(max(z, 1e-3), 1.0, P.quality.z > 0.5);
+  let ruv = vec2f(P.ao2.z, P.ao2.w) * radius / zs * 0.5;
+  let count = i32(P.ao2.y);
+  let rot = ign(in.pos.xy) * 6.2831853;
+  var occ = 0.0;
+  for (var i = 0; i < count; i++) {
+    let a = (f32(i) + 0.5) / f32(count);
+    let ang = rot + a * 6.2831853 * 3.0;
+    let suv = uv + vec2f(cos(ang), sin(ang)) * ruv * sqrt(a);
+    let s = fetch(suv, dim);
+    if (s.w >= 1.0) { continue; }
+    let sp = s.xyz;
+    let v = sp - p;
+    let vv = dot(v, v);
+    let vn = dot(v, n) - P.ao.w;
+    let falloff = max(0.0, 1.0 - vv / (radius * radius));
+    occ += max(0.0, vn * inverseSqrt(vv + 1e-4)) * falloff;
+  }
+  occ = occ / f32(count) * 2.0 * P.ao.z;
+  let ao = pow(clamp(1.0 - occ, 0.0, 1.0), P.ao2.x);
+  return vec4f(ao, ao, ao, 1.0);
+}
+`;
+/** 4×4 depth-aware blur of the AO term (half res in, half res out). */
+export const AO_BLUR_WGSL = /* wgsl */ `
+${WGSL_POST_UNIFORMS}
+@group(0) @binding(1) var nearest: sampler;
+@group(0) @binding(2) var linSamp: sampler;
+@group(0) @binding(3) var depthTex: texture_depth_2d;
+@group(0) @binding(4) var aoTex: texture_2d<f32>;
+${WGSL_DEPTH_VIEW}
+
+@fragment fn fs_main(in: FullscreenIn) -> @location(0) vec4f {
+  let dim = vec2f(textureDimensions(depthTex));
+  let uv = in.uv;
+  let t = 1.0 / vec2f(textureDimensions(aoTex));
+  let dc = textureSampleLevel(depthTex, nearest, uv, 0u);
+  if (dc >= 1.0) {
+    return vec4f(1.0);
+  }
+  let zc = linear_depth(texel_uv(uv, dim), dc);
+  var sum = 0.0;
+  var wsum = 0.0;
+  for (var y = 0; y < 4; y++) {
+    for (var x = 0; x < 4; x++) {
+      let o = vec2f(f32(x) - 1.5, f32(y) - 1.5) * t;
+      let suv = uv + o;
+      let zs = linear_depth(texel_uv(suv, dim), textureSampleLevel(depthTex, nearest, suv, 0u));
+      let w = 1.0 / (1.0 + 16.0 * abs(zs - zc) / max(zc, 1e-3));
+      sum += textureSampleLevel(aoTex, nearest, suv, 0.0).r * w;
+      wsum += w;
+    }
+  }
+  let ao = sum / max(wsum, 1e-4);
+  return vec4f(ao, ao, ao, 1.0);
+}
+`;

package/dist/post/blend.d.ts

@@ -0,0 +1,27 @@
+import { type Ease } from '../tween/ease.js';
+import type { PostSettings, PostSettingsPatch } from './settings.js';
+export type { Ease };
+export declare const easeLinear: Ease;
+/** Smoothstep: gentle start and end. The default for `blendTo`. */
+export declare const easeInOut: Ease;
+export declare const easeOut: Ease;
+export declare const easeIn: Ease;
+/**
+ * Interpolates post settings over time. Numbers and RGB triples ease from their value when
+ * `blendTo` is called; everything else switches at once (`enabled: true`, so a pass can fade
+ * in) or at the end (`enabled: false`, `tonemap`, `dither`, `levels`, so a pass can fade out).
+ * Pure: no GPU, no clock. `PostStack` advances it with the frame time.
+ */
+export declare class PostBlender {
+    private tracks;
+    /** True while any value is still moving. */
+    get active(): boolean;
+    blendTo(target: PostSettings, patch: PostSettingsPatch, seconds: number, ease: Ease): void;
+    /** Stop blending the given keys (e.g. after `set` overwrote them). */
+    cancel(patch: PostSettingsPatch): void;
+    /** Jump every track to its end value. */
+    finish(target: PostSettings): void;
+    /** Move every track forward by `dt` seconds and write the values into `target`. */
+    advance(target: PostSettings, dt: number): void;
+    private drop;
+}