@yali-engine/render 0.0.0-stage → 0.4.0

package/dist/debug-lines.js

@@ -0,0 +1,158 @@
+import { debugLines } from "./shaders.gen.js";
+/** Bytes per debug vertex: x, y, z (f32, camera-relative once queued) and an RGBA8 colour. */
+export const DEBUG_VERTEX_BYTES = 16;
+/**
+ * Debug line segments for this frame (`render.debug`, ADR-0087): plugins queue them after the
+ * camera has moved (Extract or later), the renderer draws them at the end of the scene pass,
+ * depth-tested against it, and the queue empties every frame. Positions are converted to
+ * camera-relative f32 as they are queued, from f64 origins, so lines far from the world origin
+ * stay exact. Allocation-free once the buffer has grown.
+ *
+ * @example
+ * const render = app.resource<RenderContext>('render');
+ * render.debug.line([0, 0, 0], [0, 2, 0], 0xff0000ff); // a red post, 2 m tall
+ */
+export class DebugLines {
+    /** Vertices queued this frame (two per segment). */
+    count = 0;
+    /** At most this many vertices per frame; more are dropped (and counted). */
+    capacity;
+    /** Vertices dropped this frame over `capacity`. */
+    dropped = 0;
+    /** Vertices the last drawn frame had (what `clear` emptied; the `render.debugLines` counter). */
+    drawn = 0;
+    #f32 = new Float32Array(0);
+    #u32 = new Uint32Array(0);
+    #camera;
+    constructor(camera, capacity = 1 << 20) {
+        this.#camera = camera;
+        this.capacity = capacity;
+    }
+    /** The queued vertices (`count × 16` bytes from offset 0). */
+    get data() {
+        return this.#f32;
+    }
+    #reserve(n) {
+        const room = Math.max(0, Math.min(n, this.capacity - this.count));
+        this.dropped += n - room;
+        const need = (this.count + room) * 4;
+        if (need > this.#f32.length) {
+            const next = new Float32Array(Math.max(need, this.#f32.length * 2, 4096));
+            next.set(this.#f32.subarray(0, this.count * 4));
+            this.#f32 = next;
+            this.#u32 = new Uint32Array(next.buffer);
+        }
+        return room;
+    }
+    /**
+     * Queues `count` vertices from a packed buffer: 16 bytes each (x, y, z as f32 relative to
+     * `origin`, then RGBA8), starting at vertex `first` of the views `f32` / `u32` (one buffer,
+     * e.g. WASM memory). `origin` is f64 world coordinates.
+     */
+    add(f32, u32, first, count, origin) {
+        const eye = this.#camera.eye;
+        const ox = origin[0] - eye[0];
+        const oy = origin[1] - eye[1];
+        const oz = origin[2] - eye[2];
+        const n = this.#reserve(count);
+        const dst = this.#f32;
+        const dstU = this.#u32;
+        for (let i = 0; i < n; i++) {
+            const s = (first + i) * 4;
+            const d = (this.count + i) * 4;
+            dst[d] = f32[s] + ox;
+            dst[d + 1] = f32[s + 1] + oy;
+            dst[d + 2] = f32[s + 2] + oz;
+            dstU[d + 3] = u32[s + 3];
+        }
+        this.count += n;
+    }
+    /** Queues one segment between world points `a` and `b`, colour `rgba` (red in the low byte). */
+    line(a, b, rgba) {
+        if (this.#reserve(2) < 2)
+            return;
+        const eye = this.#camera.eye;
+        const d = this.count * 4;
+        const f = this.#f32;
+        f[d] = a[0] - eye[0];
+        f[d + 1] = a[1] - eye[1];
+        f[d + 2] = a[2] - eye[2];
+        f[d + 4] = b[0] - eye[0];
+        f[d + 5] = b[1] - eye[1];
+        f[d + 6] = b[2] - eye[2];
+        this.#u32[d + 3] = rgba >>> 0;
+        this.#u32[d + 7] = rgba >>> 0;
+        this.count += 2;
+    }
+    /** Empties the queue (the renderer calls it after each frame). */
+    clear() {
+        this.drawn = this.count;
+        this.count = 0;
+        this.dropped = 0;
+    }
+}
+/** Draws a `DebugLines` queue in the scene pass (WebGPU). */
+export class DebugLinesPass {
+    device;
+    #pipeline;
+    #group = null;
+    #buffer = null;
+    #format;
+    #camera;
+    constructor(device, format, camera) {
+        this.device = device;
+        this.#format = format;
+        this.#camera = camera;
+    }
+    async init(cache) {
+        this.#pipeline = await cache.render({
+            label: 'yali:debug-lines',
+            vertex: {
+                shader: debugLines,
+                entryPoint: 'vs',
+                buffers: [
+                    {
+                        arrayStride: DEBUG_VERTEX_BYTES,
+                        attributes: [
+                            { shaderLocation: 0, offset: 0, format: 'float32x3' },
+                            { shaderLocation: 1, offset: 12, format: 'unorm8x4' },
+                        ],
+                    },
+                ],
+            },
+            fragment: { shader: debugLines, entryPoint: 'fs', targets: [{ format: this.#format }] },
+            primitive: { topology: 'line-list' },
+            // Reverse-Z: nearer is greater. Lines never write depth, so they never hide each other.
+            depthStencil: { format: 'depth32float', depthWriteEnabled: false, depthCompare: 'greater-equal' },
+        });
+        this.#group = this.device.createBindGroup({
+            label: 'yali:debug-lines',
+            layout: this.#pipeline.getBindGroupLayout(0),
+            entries: [{ binding: 0, resource: { buffer: this.#camera } }],
+        });
+    }
+    /** Uploads and draws `lines` into `pass` (inside the scene pass, after its draws). */
+    encode(pass, lines) {
+        if (lines.count === 0 || !this.#group)
+            return;
+        const bytes = lines.count * DEBUG_VERTEX_BYTES;
+        if (!this.#buffer || this.#buffer.size < bytes) {
+            this.#buffer?.destroy();
+            this.#buffer = this.device.createBuffer({ label: 'yali:debug-lines', size: Math.max(bytes, 1 << 16) * 2, usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST });
+        }
+        this.device.queue.writeBuffer(this.#buffer, 0, lines.data.buffer, 0, bytes);
+        pass.setPipeline(this.#pipeline);
+        pass.setBindGroup(0, this.#group);
+        pass.setVertexBuffer(0, this.#buffer, 0, bytes);
+        pass.draw(lines.count);
+    }
+    /** GPU buffers held (the leak check). */
+    get liveBuffers() {
+        return this.#buffer ? 1 : 0;
+    }
+    destroy() {
+        this.#buffer?.destroy();
+        this.#buffer = null;
+    }
+}
+//# sourceMappingURL=debug-lines.js.map

package/dist/debug-lines.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-lines.js","sourceRoot":"","sources":["../src/debug-lines.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,8FAA8F;AAC9F,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAErC;;;;;;;;;;GAUG;AACH,MAAM,OAAO,UAAU;IACrB,oDAAoD;IACpD,KAAK,GAAG,CAAC,CAAC;IACV,4EAA4E;IAC5E,QAAQ,CAAS;IACjB,mDAAmD;IACnD,OAAO,GAAG,CAAC,CAAC;IACZ,iGAAiG;IACjG,KAAK,GAAG,CAAC,CAAC;IACV,IAAI,GAAG,IAAI,YAAY,CAAC,CAAC,CAAC,CAAC;IAC3B,IAAI,GAAG,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC;IACjB,OAAO,CAAc;IAE9B,YAAY,MAAmB,EAAE,QAAQ,GAAG,CAAC,IAAI,EAAE;QACjD,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED,8DAA8D;IAC9D,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED,QAAQ,CAAC,CAAS;QAChB,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QAClE,IAAI,CAAC,OAAO,IAAI,CAAC,GAAG,IAAI,CAAC;QACzB,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;QACrC,IAAI,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YAC5B,MAAM,IAAI,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;YAC1E,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;YAChD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;YACjB,IAAI,CAAC,IAAI,GAAG,IAAI,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC3C,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;OAIG;IACH,GAAG,CAAC,GAAiB,EAAE,GAAgB,EAAE,KAAa,EAAE,KAAa,EAAE,MAAyB;QAC9F,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC;QAC7B,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QAC9B,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QAC9B,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QAC9B,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC/B,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACvB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC3B,MAAM,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;YAC1B,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;YAC/B,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;YACrB,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;YAC7B,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;YAC7B,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAC3B,CAAC;QACD,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC;IAClB,CAAC;IAED,gGAAgG;IAChG,IAAI,CAAC,CAAoB,EAAE,CAAoB,EAAE,IAAY;QAC3D,IAAI,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC;YAAE,OAAO;QACjC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC;QAC7B,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;QACzB,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC;QACpB,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QACrB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QACzB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QACzB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QACzB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QACzB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QACzB,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,KAAK,CAAC,CAAC;QAC9B,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,KAAK,CAAC,CAAC;QAC9B,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC;IAClB,CAAC;IAED,kEAAkE;IAClE,KAAK;QACH,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;QACf,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC;IACnB,CAAC;CACF;AAED,6DAA6D;AAC7D,MAAM,OAAO,cAAc;IAChB,MAAM,CAAY;IAC3B,SAAS,CAAqB;IAC9B,MAAM,GAAwB,IAAI,CAAC;IACnC,OAAO,GAAqB,IAAI,CAAC;IACjC,OAAO,CAAmB;IAC1B,OAAO,CAAY;IAEnB,YAAY,MAAiB,EAAE,MAAwB,EAAE,MAAiB;QACxE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,KAAoB;QAC7B,IAAI,CAAC,SAAS,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC;YAClC,KAAK,EAAE,kBAAkB;YACzB,MAAM,EAAE;gBACN,MAAM,EAAE,UAAU;gBAClB,UAAU,EAAE,IAAI;gBAChB,OAAO,EAAE;oBACP;wBACE,WAAW,EAAE,kBAAkB;wBAC/B,UAAU,EAAE;4BACV,EAAE,cAAc,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE;4BACrD,EAAE,cAAc,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE;yBACtD;qBACF;iBACF;aACF;YACD,QAAQ,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE;YACvF,SAAS,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE;YACpC,wFAAwF;YACxF,YAAY,EAAE,EAAE,MAAM,EAAE,cAAc,EAAE,iBAAiB,EAAE,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE;SAClG,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC;YACxC,KAAK,EAAE,kBAAkB;YACzB,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,kBAAkB,CAAC,CAAC,CAAC;YAC5C,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;SAC9D,CAAC,CAAC;IACL,CAAC;IAED,sFAAsF;IACtF,MAAM,CAAC,IAA0B,EAAE,KAAiB;QAClD,IAAI,KAAK,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,OAAO;QAC9C,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,GAAG,kBAAkB,CAAC;QAC/C,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,KAAK,EAAE,CAAC;YAC/C,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,CAAC;YACxB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,KAAK,EAAE,kBAAkB,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,cAAc,CAAC,MAAM,GAAG,cAAc,CAAC,QAAQ,EAAE,CAAC,CAAC;QACrK,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;QAC5E,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACjC,IAAI,CAAC,YAAY,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAClC,IAAI,CAAC,eAAe,CAAC,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;QAChD,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACzB,CAAC;IAED,yCAAyC;IACzC,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9B,CAAC;IAED,OAAO;QACL,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,CAAC;QACxB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;IACtB,CAAC;CACF"}

package/dist/device-profile.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Device identity and tier selection (ADR-0010: identity collection ported from Character XYZ
+ * `mesh/sculpt/instrument/device-profile.ts`; DESIGN.md §14 tier rules).
+ *
+ * The GPU is identified twice on purpose. `GPUAdapterInfo` is vague on most drivers
+ * (vendor "amd", architecture "" is a normal answer), but it is the only source of the
+ * limits. `WEBGL_debug_renderer_info` is the only reliable human-readable card name, and
+ * it needs a real GL context, so the probe creates a 1×1 context and immediately forces it
+ * lost (browsers cap live GL contexts and drop the oldest).
+ *
+ * Nothing here throws: it runs on machines we have never seen, in browsers missing half
+ * these APIs. Every read is feature-detected and degrades to null.
+ */
+/** Everything a perf log needs to name the machine that produced it. */
+export interface DeviceProfile {
+    capturedAt: string;
+    userAgent: string;
+    platform: string | null;
+    mobile: boolean | null;
+    deviceModel: string | null;
+    cpuCores: number | null;
+    deviceMemoryGb: number | null;
+    screen: {
+        width: number;
+        height: number;
+        dpr: number;
+    };
+    touchPoints: number | null;
+    gpu: {
+        vendor: string | null;
+        architecture: string | null;
+        description: string | null;
+        webglRenderer: string | null;
+        maxStorageBufferBindingSizeMb: number | null;
+        maxBufferSizeMb: number | null;
+    };
+}
+/** Collects the profile. Never throws. */
+export declare function collectDeviceProfile(adapter?: GPUAdapter | null): Promise<DeviceProfile>;
+/**
+ * What a device-filter rule can turn off. Each changes only what the render plugin picks by
+ * default; an option the app sets explicitly wins.
+ * - `shadows`: no sun shadows (ADR-0068).
+ * - `staging`: uploads through `writeBuffer`, not the mapped staging ring (ADR-0056).
+ * - `bundles`: draws encoded each frame, not replayed from a render bundle (ADR-0050).
+ * - `gpu-cull`: the CPU cull with ordinary draws, no indirect draws (ADR-0057).
+ * - `storage-instances`: instances as vertex attributes, no vertex-stage storage (ADR-0045).
+ * - `compressed-textures`: RGBA8 textures, no BC / ASTC / ETC2 (ADR-0060).
+ */
+export type DisableableFeature = 'shadows' | 'staging' | 'bundles' | 'gpu-cull' | 'storage-instances' | 'compressed-textures';
+/** A device-filter rule (DESIGN.md §14: Unity's Graphics Device Filtering, as data). */
+export interface DeviceFilterRule {
+    readonly id: string;
+    /**
+     * Every present field must match (substring, case-insensitive): the user agent (browser,
+     * version), the platform (OS), the device model, and the GPU's vendor, architecture and
+     * WebGL renderer string.
+     */
+    readonly match: {
+        readonly userAgent?: string;
+        readonly platform?: string;
+        readonly device?: string;
+        readonly vendor?: string;
+        readonly architecture?: string;
+        readonly renderer?: string;
+        /** The WebGPU backend the adapter came up on (exact). */
+        readonly backend?: 'webgpu' | 'webgpu-compat';
+    };
+    readonly action: {
+        readonly maxTier?: Tier;
+        readonly disableFeatures?: readonly DisableableFeature[];
+        /** Use the WebGL2 backend instead of WebGPU (unless the app asked for `backend: 'webgpu'`). */
+        readonly useWebGL2?: boolean;
+    };
+    /** Why, with the measurement behind it. */
+    readonly reason: string;
+    readonly issueUrl?: string;
+}
+/** Quality tiers (DESIGN.md §14). */
+export type Tier = 't0' | 't1' | 't2';
+/**
+ * Known-bad combinations, shipped with the engine; an app replaces or extends it with the
+ * render plugin's `deviceFilter` option. An entry needs a measured failure behind it. (Character XYZ's Brave depth-buffer boot race was checked against this
+ * renderer on 2026-10-16 and does not reproduce, so it is not listed. The Galaxy F04's slow
+ * indirect draws and staging maps are compatibility-mode costs, handled by the backend's
+ * defaults, not by a device row: ADR-0056, ADR-0057.)
+ */
+export declare const DEVICE_FILTER: readonly DeviceFilterRule[];
+/**
+ * Picks the tier: compatibility mode or WebGL2 → T0; a mobile/touch-first device → T1; otherwise T2. Then
+ * the device-filter table may lower it. Returns the tier, why, the matching rule ids, and
+ * the features the matching rules turn off (an override sets the tier only).
+ */
+export declare function selectTier(backend: 'webgpu' | 'webgpu-compat' | 'webgl2', profile: DeviceProfile, rules?: readonly DeviceFilterRule[], override?: Tier): {
+    tier: Tier;
+    source: 'caps' | 'filter' | 'override';
+    matched: string[];
+    disable: DisableableFeature[];
+    useWebGL2: boolean;
+};

package/dist/device-profile.js

@@ -0,0 +1,131 @@
+/**
+ * Device identity and tier selection (ADR-0010: identity collection ported from Character XYZ
+ * `mesh/sculpt/instrument/device-profile.ts`; DESIGN.md §14 tier rules).
+ *
+ * The GPU is identified twice on purpose. `GPUAdapterInfo` is vague on most drivers
+ * (vendor "amd", architecture "" is a normal answer), but it is the only source of the
+ * limits. `WEBGL_debug_renderer_info` is the only reliable human-readable card name, and
+ * it needs a real GL context, so the probe creates a 1×1 context and immediately forces it
+ * lost (browsers cap live GL contexts and drop the oldest).
+ *
+ * Nothing here throws: it runs on machines we have never seen, in browsers missing half
+ * these APIs. Every read is feature-detected and degrades to null.
+ */
+const str = (v) => (typeof v === 'string' && v.length > 0 ? v : null);
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+const mb = (v) => {
+    const n = num(v);
+    return n === null ? null : Math.round(n / 1048576);
+};
+/** The card name via WebGL, in a context that is created and immediately lost. */
+function probeWebglRenderer() {
+    try {
+        if (typeof document === 'undefined')
+            return null;
+        const canvas = document.createElement('canvas');
+        canvas.width = canvas.height = 1;
+        const gl = canvas.getContext('webgl');
+        if (!gl)
+            return null;
+        try {
+            const dbg = gl.getExtension('WEBGL_debug_renderer_info');
+            return str(dbg ? gl.getParameter(dbg.UNMASKED_RENDERER_WEBGL) : gl.getParameter(gl.RENDERER));
+        }
+        finally {
+            gl.getExtension('WEBGL_lose_context')?.loseContext();
+        }
+    }
+    catch {
+        return null;
+    }
+}
+/** Collects the profile. Never throws. */
+export async function collectDeviceProfile(adapter) {
+    const nav = typeof navigator === 'undefined' ? null : navigator;
+    let platform = null;
+    let mobile = null;
+    let model = null;
+    try {
+        const ua = nav?.userAgentData;
+        platform = str(ua?.platform);
+        mobile = typeof ua?.mobile === 'boolean' ? ua.mobile : null;
+        // Rejects (rather than resolving empty) on browsers that refuse the hints.
+        const high = await ua?.getHighEntropyValues?.(['model']).catch(() => ({}));
+        model = str(high?.model); // "" on desktops and iPadOS collapses to null
+    }
+    catch {
+        /* no UA-CH */
+    }
+    const info = adapter?.info;
+    const limits = adapter?.limits;
+    return {
+        capturedAt: new Date().toISOString(),
+        userAgent: nav?.userAgent ?? '',
+        platform: platform ?? str(nav?.platform),
+        mobile,
+        deviceModel: model,
+        cpuCores: num(nav?.hardwareConcurrency),
+        deviceMemoryGb: num(nav?.deviceMemory),
+        screen: {
+            width: typeof screen === 'undefined' ? 0 : screen.width,
+            height: typeof screen === 'undefined' ? 0 : screen.height,
+            dpr: typeof devicePixelRatio === 'undefined' ? 1 : devicePixelRatio,
+        },
+        touchPoints: num(nav?.maxTouchPoints),
+        gpu: {
+            vendor: str(info?.vendor),
+            architecture: str(info?.architecture),
+            description: str(info?.description),
+            webglRenderer: probeWebglRenderer(),
+            maxStorageBufferBindingSizeMb: mb(limits?.maxStorageBufferBindingSize),
+            maxBufferSizeMb: mb(limits?.maxBufferSize),
+        },
+    };
+}
+/**
+ * Known-bad combinations, shipped with the engine; an app replaces or extends it with the
+ * render plugin's `deviceFilter` option. An entry needs a measured failure behind it. (Character XYZ's Brave depth-buffer boot race was checked against this
+ * renderer on 2026-10-16 and does not reproduce, so it is not listed. The Galaxy F04's slow
+ * indirect draws and staging maps are compatibility-mode costs, handled by the backend's
+ * defaults, not by a device row: ADR-0056, ADR-0057.)
+ */
+export const DEVICE_FILTER = [
+    {
+        id: 'powervr-compat-no-depth-writes',
+        match: { vendor: 'img-tec', backend: 'webgpu-compat' },
+        action: { useWebGL2: true },
+        reason: 'Galaxy F04 (PowerVR GE8320), Chrome 155, WebGPU compatibility mode, 2026-10-20: depth writes never land (a draw tests against the cleared depth, never against earlier draws; every depth format, across passes too), so later draws paint over nearer ones and shadow maps stay empty. WebGL2 on the same phone renders the goldens and is as fast or faster (20k cubes governed 48-57 fps vs 48-52; full PBR 29-38 vs 25).',
+        issueUrl: 'https://issues.chromium.org/issues/575736568',
+    },
+];
+const TIER_ORDER = ['t0', 't1', 't2'];
+/**
+ * Picks the tier: compatibility mode or WebGL2 → T0; a mobile/touch-first device → T1; otherwise T2. Then
+ * the device-filter table may lower it. Returns the tier, why, the matching rule ids, and
+ * the features the matching rules turn off (an override sets the tier only).
+ */
+export function selectTier(backend, profile, rules = DEVICE_FILTER, override) {
+    const has = (hay, needle) => needle === undefined || (hay ?? '').toLowerCase().includes(needle.toLowerCase());
+    const matched = rules.filter((r) => has(profile.userAgent, r.match.userAgent) &&
+        has(profile.platform, r.match.platform) &&
+        has(profile.deviceModel, r.match.device) &&
+        has(profile.gpu.vendor, r.match.vendor) &&
+        has(profile.gpu.architecture, r.match.architecture) &&
+        has(profile.gpu.webglRenderer, r.match.renderer) &&
+        (r.match.backend === undefined || r.match.backend === backend));
+    const useWebGL2 = backend !== 'webgl2' && matched.some((r) => r.action.useWebGL2);
+    const disable = [...new Set(matched.flatMap((r) => r.action.disableFeatures ?? []))];
+    if (override)
+        return { tier: override, source: 'override', matched: matched.map((r) => r.id), disable, useWebGL2 };
+    const touchFirst = profile.mobile === true || ((profile.touchPoints ?? 0) > 0 && Math.min(profile.screen.width, profile.screen.height) < 900);
+    let tier = backend !== 'webgpu' ? 't0' : touchFirst ? 't1' : 't2';
+    let source = 'caps';
+    for (const r of matched) {
+        if (r.action.maxTier && TIER_ORDER.indexOf(r.action.maxTier) < TIER_ORDER.indexOf(tier)) {
+            tier = r.action.maxTier;
+            source = 'filter';
+        }
+    }
+    return { tier, source, matched: matched.map((r) => r.id), disable, useWebGL2 };
+}
+//# sourceMappingURL=device-profile.js.map

package/dist/device-profile.js.map

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

package/dist/device.d.ts

@@ -0,0 +1,39 @@
+/** Which API the device came from (DESIGN.md §14). */
+export type Backend = 'webgpu' | 'webgpu-compat';
+/** A configured GPU device and its canvas. */
+export interface Gpu {
+    readonly adapter: GPUAdapter;
+    readonly device: GPUDevice;
+    readonly context: GPUCanvasContext;
+    readonly format: GPUTextureFormat;
+    readonly backend: Backend;
+    readonly adapterInfo: {
+        vendor: string;
+        architecture: string;
+        description: string;
+    };
+    /** Optional features that were available and requested. */
+    readonly features: ReadonlySet<string>;
+    /** Resolves when the device is lost (DESIGN.md §3: Recovering arrives with increment 6). */
+    readonly lost: Promise<GPUDeviceLostInfo>;
+}
+/**
+ * Acquires an adapter and device for `canvas`, preferring core WebGPU and retrying in
+ * compatibility mode (DESIGN.md §14).
+ *
+ * Limits are **requested explicitly**: an `adapter.limits` value is only the maximum the
+ * adapter *could* grant, and the device gets the spec defaults unless asked. Instanced
+ * drawing needs large storage buffers, so those are requested up to the adapter's maximum.
+ *
+ * @example
+ * const gpu = await acquireGpu(document.querySelector('canvas')!);
+ */
+export declare function acquireGpu(canvas: HTMLCanvasElement | OffscreenCanvas, options?: {
+    powerPreference?: GPUPowerPreference;
+    compat?: boolean;
+    /**
+     * Called with the chosen adapter before a device or the canvas context exists; throwing
+     * here leaves the canvas free for another backend (the device filter's WebGL2 rows).
+     */
+    accept?: (adapter: GPUAdapter, backend: Backend) => void | Promise<void>;
+}): Promise<Gpu>;

package/dist/device.js

@@ -0,0 +1,79 @@
+import { YaliError } from '@yali-engine/core';
+/** Optional features Yali requests when the adapter has them. */
+const WANTED_FEATURES = [
+    'timestamp-query',
+    'shader-f16',
+    'indirect-first-instance',
+    // Compressed textures (ADR-0060): the texture store samples the best family the device has.
+    'texture-compression-bc',
+    'texture-compression-astc',
+    'texture-compression-etc2',
+];
+/**
+ * Acquires an adapter and device for `canvas`, preferring core WebGPU and retrying in
+ * compatibility mode (DESIGN.md §14).
+ *
+ * Limits are **requested explicitly**: an `adapter.limits` value is only the maximum the
+ * adapter *could* grant, and the device gets the spec defaults unless asked. Instanced
+ * drawing needs large storage buffers, so those are requested up to the adapter's maximum.
+ *
+ * @example
+ * const gpu = await acquireGpu(document.querySelector('canvas')!);
+ */
+export async function acquireGpu(canvas, options = {}) {
+    const gpu = navigator.gpu;
+    if (!gpu) {
+        throw new YaliError('WEBGPU_UNAVAILABLE', 'This browser has no WebGPU (navigator.gpu is undefined).', 'Use Chrome/Edge 113+, Safari 26+ or Firefox 141+ (Windows); renderPlugin falls back to WebGL2 unless backend is "webgpu" (ADR-0070).');
+    }
+    let backend = 'webgpu';
+    let adapter = options.compat ? null : await gpu.requestAdapter({ powerPreference: options.powerPreference ?? 'high-performance' });
+    if (!adapter) {
+        adapter = await gpu.requestAdapter({ featureLevel: 'compatibility' });
+        backend = 'webgpu-compat';
+    }
+    if (!adapter) {
+        throw new YaliError('WEBGPU_NO_ADAPTER', 'WebGPU is present but no adapter is available (blocklisted GPU or driver?).', 'Update the GPU driver, or check chrome://gpu for why WebGPU is disabled.');
+    }
+    await options.accept?.(adapter, backend);
+    const features = WANTED_FEATURES.filter((f) => adapter.features.has(f));
+    const limits = adapter.limits;
+    const requiredLimits = {
+        maxStorageBufferBindingSize: limits.maxStorageBufferBindingSize,
+        maxBufferSize: limits.maxBufferSize,
+        maxComputeWorkgroupsPerDimension: limits.maxComputeWorkgroupsPerDimension,
+        // The shadow atlas is cascades × size wide (ADR-0068); compatibility mode defaults to 4096.
+        maxTextureDimension2D: limits.maxTextureDimension2D,
+        // GPU cloth runs a cloth per workgroup, as wide as the device allows (ADR-0101).
+        maxComputeInvocationsPerWorkgroup: limits.maxComputeInvocationsPerWorkgroup,
+        maxComputeWorkgroupSizeX: limits.maxComputeWorkgroupSizeX,
+        // The cluster cull's page bits are a ninth storage buffer (ADR-0134); a device without one streams coarse first.
+        maxStorageBuffersPerShaderStage: limits.maxStorageBuffersPerShaderStage,
+    };
+    // Compatibility mode grants 0 storage buffers to the vertex and fragment stages unless
+    // asked: request what the adapter allows, and the renderer picks its path from the result.
+    for (const name of ['maxStorageBuffersInVertexStage', 'maxStorageBuffersInFragmentStage']) {
+        const v = limits[name];
+        if (typeof v === 'number')
+            requiredLimits[name] = v;
+    }
+    const device = await adapter.requestDevice({ requiredFeatures: features, requiredLimits });
+    const context = canvas.getContext('webgpu');
+    if (!context) {
+        throw new YaliError('WEBGPU_NO_CONTEXT', 'canvas.getContext("webgpu") returned null.', 'Use a canvas that has no other context.');
+    }
+    const format = gpu.getPreferredCanvasFormat();
+    // COPY_SRC lets `render.capture()` read back exactly what was drawn (golden images, MCP).
+    context.configure({ device, format, alphaMode: 'opaque', usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC });
+    const info = adapter.info;
+    return {
+        adapter,
+        device,
+        context,
+        format,
+        backend,
+        adapterInfo: { vendor: info.vendor, architecture: info.architecture, description: info.description },
+        features: new Set(features),
+        lost: device.lost,
+    };
+}
+//# sourceMappingURL=device.js.map

package/dist/device.js.map

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

package/dist/environment.d.ts

@@ -0,0 +1,60 @@
+import type { PipelineCache } from './pipeline-cache.ts';
+/** A procedural sky (M2 increment 5): every colour linear, the sun a radiance. */
+export interface SkyOptions {
+    /** Direction towards the sun (normalized here). */
+    readonly sun?: readonly [number, number, number];
+    readonly zenith?: readonly [number, number, number];
+    readonly horizon?: readonly [number, number, number];
+    readonly ground?: readonly [number, number, number];
+    /** Radiance of the sun disk in the sky (what reflections see). */
+    readonly sunDisk?: readonly [number, number, number];
+    /** Angular radius of the disk, degrees. */
+    readonly sunAngle?: number;
+}
+/** The default sky. */
+export declare const DEFAULT_SKY: Required<SkyOptions>;
+/** Texels per cube face at the base level, and its mip count. */
+export declare const ENV_SIZE = 128;
+export declare const ENV_MIPS = 6;
+/**
+ * The environment for image-based lighting (M2 increment 5): a procedural sky rendered into a
+ * cube map, each lower mip GGX-prefiltered for its roughness (`shaders/env/sky.wesl`), and the
+ * same sky projected onto nine spherical-harmonic coefficients for diffuse irradiance (CPU).
+ * Built once at start and again when `setSky` changes it; render passes only, so compatibility
+ * mode can run it. The draw reads `prefiltered` and `sh9`.
+ */
+export declare class Environment {
+    #private;
+    readonly device: GPUDevice;
+    /** Cube map the draw samples by roughness (mip m: roughness m / (mips − 1)). */
+    readonly prefiltered: GPUTexture;
+    readonly mips = 6;
+    /** Irradiance / π as SH9, 9 × vec4 (rgb, 0): the draw's diffuse ambient for a normal n. */
+    readonly sh9: Float32Array<ArrayBuffer>;
+    /** Bumped when the cube or SH changed. */
+    version: number;
+    constructor(device: GPUDevice);
+    init(cache: PipelineCache): Promise<void>;
+    /** Changes the sky (unset fields keep their values) and rebuilds the cube and SH. */
+    setSky(sky: SkyOptions): void;
+    /** The current sky. */
+    get sky(): Readonly<Required<SkyOptions>>;
+    /** Renders the sky into every mip of the base cube, then prefilters; projects SH9. */
+    build(): void;
+    destroy(): void;
+}
+/** `sky` with `changes`' set fields applied. */
+export declare function mergeSky(sky: Required<SkyOptions>, changes: SkyOptions): Required<SkyOptions>;
+/** The sky pass's `SkyParams` (24 floats) for cube face `f` of mip `m`, at `out[o]`: every backend packs it so. */
+export declare function packSkyParams(out: Float32Array, o: number, s: Required<SkyOptions>, m: number, f: number): void;
+/** The SH9 irradiance of sky `s` (`Environment.sh9`), into `out`. */
+export declare function skySh9(out: Float32Array, s: Required<SkyOptions>): void;
+/** `sky` of shaders/env/sky.wesl, in TS (for the SH projection). */
+export declare function skyRadiance(s: Required<SkyOptions>, sun: readonly number[], d: readonly number[]): [number, number, number];
+/**
+ * Projects `radiance` onto real SH up to l = 2 and convolves with the clamped cosine
+ * (Ramamoorthi & Hanrahan 2001), divided by π: `out` evaluated at n is the Lambert
+ * diffuse radiance for albedo 1. Coefficient order: Y00, Y1-1 (y), Y10 (z), Y11 (x), Y2-2 (xy),
+ * Y2-1 (yz), Y20, Y21 (xz), Y22 (x² − y²): `sh_irradiance` in draw.wesl reads the same.
+ */
+export declare function projectSh9(out: Float32Array, radiance: (d: readonly number[]) => readonly number[]): void;