@driftengine/native-host 4.0.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Drift Technologies
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,29 @@
+DriftEngine
+Copyright 2026 Drift Technologies
+
+This product includes software developed at Drift Technologies
+(https://github.com/drftrun/driftengine).
+
+Licensed under the Apache License, Version 2.0. Section 4(d) of that licence
+requires this NOTICE to be reproduced in any derivative work you distribute,
+in the source, the documentation, or a display generated by the work.
+
+Models run by DriftCapture
+--------------------------
+DriftCapture runs the models below. Their weights are not in this repository
+and are not distributed with it: tools/capture-weights/ fetches each at the
+revision its manifest pins, verifies it, and converts it, and a game that
+ships one ships it under that model's own licence. Each model's definition in
+this engine is written from its project's published code.
+
+- Depth Anything 3 Small and Depth Anything 3 Base. Apache License 2.0.
+  Copyright (c) 2025 ByteDance Ltd. and/or its affiliates.
+- Depth Anything V2 Small. Apache License 2.0. The University of Hong Kong
+  and TikTok; converted to the Transformers layout by The HuggingFace Team.
+- MobileSAM. Apache License 2.0. Its image encoder is TinyViT, Copyright (c)
+  2022 Microsoft; its prompt encoder and mask decoder are Segment Anything's,
+  Copyright (c) Meta Platforms, Inc. and affiliates.
+- SAM 2.1 tiny. Apache License 2.0. Copyright (c) Meta Platforms, Inc. and
+  affiliates.
+- OWLv2 base patch16. Apache License 2.0. Copyright 2023 Google AI and The
+  HuggingFace Team.

package/README.md

@@ -0,0 +1,58 @@
+# `@driftengine/native-host`
+
+The engine on a native window and a native WebGPU device, with no browser between them.
+
+A game built on the engine runs here unchanged. The host is Node, Dawn — the WebGPU implementation
+Chrome runs — through `@kmamal/gpu`, SDL through `@kmamal/sdl` for the window, input and
+controllers, and Web Audio from `node-web-audio-api`. Around the canvas it supplies the page a game
+expects: `window`, `document`, animation frames, the browser's input events in the order Chrome
+sends them, pointer lock, fullscreen, gamepads, `matchMedia`, and the desktop shell's bridge
+(`__driftHost`) for storage, window modes and quit.
+
+**A game installs it and the packager ships it.** `npm install @driftengine/native-host` in the
+game, at the engine's version, and `drift-package build --target=native-linux-x64` bundles the game
+with it into an archive that carries its own Node. The packager names no range on this package and
+resolves it from the game's own tree, so a game that builds only for the browser or for Electron
+never downloads a native binary.
+
+**A game's contract with it is one export.** In a browser a page finds its canvas in its markup;
+here there is no markup, so the manifest's `native.entry` names a module exporting
+`mount(canvas)`, and the host calls it with its canvas once it has started. A game that already
+mounts onto a canvas it is given needs a file of one line:
+
+```ts
+export { mount } from './game.ts';
+```
+
+`runGame` is that start, and what the packager's generated entry calls; `startHost` is the same
+start without a game, for a tool that draws its own frames. `tileFiles(dir)` is the one thing a
+page has no equivalent of: the texture streamer's tiles read from a directory on disk, for a
+native entry to hand its streamer where a page would fetch them.
+
+## What it is measured against
+
+Every published scene is drawn by this host and by Chrome and compared pixel for pixel on the same
+machine (`npm run native:gate` in the engine's repository). The engine's reference mix is compared
+against Chrome's too. Each behaviour a page reads — an event's order, a refusal's wording, a double
+click's timing — is Chrome's, measured over the DevTools protocol where it can be, and asserted by a
+test beside the module that implements it.
+
+## What it gives up
+
+- Linux x64 is the platform it has been measured on, and the one the packager builds for. Windows
+  and macOS come after 4.0.0: the three bindings publish binaries for both, and what each still
+  needs is a launcher, its signing, and the same measurements against Chrome on its own GPU.
+- There is no DOM beyond the canvas: `document.createElement` refuses by name, so a game's own
+  HTML interface does not come with it.
+- WebGL2 is not offered; the engine runs on WebGPU here.
+- Clip export, `navigator.share` and WebXR are absent, and the engine says so where it asks.
+- The engine's badge is not drawn, and there is no store: `steam.appId` does nothing here, which
+  `drift-package doctor` says for a manifest that sets it.
+- Pipelines are compiled on every start, because the binding exposes no cache for them: most of
+  the start of a small program, 355 ms of 750 measured on 2026-09-19.
+
+Apache-2.0. Dawn, SDL, Node and the Web Audio engine carry their own licences, which a packaged game
+ships in its `licenses/` with every other part's. **One of them is the LGPL**: the Opus decoder
+reads Ogg pages with `codec-parser`, which is LGPL-3.0, so a packaged game carries it as a file of
+its own that a person can replace rather than inside the bundle, with the GPL's text beside it —
+`licenses/GPL-3.0.txt` in this package, which that licence asks to accompany it.

package/dist/activation.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Whether a person has just done something, as a browser's transient activation answers it — the
+ * gate on what a page may do only in answer to a person: pointer lock, fullscreen.
+ *
+ * **Chrome's rules, measured 2026-09-19 in Chrome 151 over the DevTools protocol.** A key down
+ * other than Escape, a mouse press or a finger lifted makes a page active for five seconds: a
+ * request 4.5 s after an unused click was granted and one at 5.5 s refused. Fullscreen spends it —
+ * a second request 100 ms after a granted one was refused — and pointer lock does not: a lock and
+ * then fullscreen from one click were both granted. The input is noted before its event is sent,
+ * so a listener for that very event may already ask.
+ *
+ * What it gives up: a script's own `dispatchEvent` is never a gesture, as in a browser, so input a
+ * capture replays goes through SDL's events (`HostWindow.replay`) to count as one.
+ */
+export declare class UserActivation {
+    private readonly now;
+    private at;
+    private ever;
+    constructor(now: () => number);
+    /** A person did something: a key down, a mouse press, a finger lifted. */
+    notify(): void;
+    /** Spent, by an ask that takes the gesture with it. */
+    consume(): void;
+    get isActive(): boolean;
+    get hasBeenActive(): boolean;
+}

package/dist/activation.js

@@ -0,0 +1,38 @@
+/**
+ * Whether a person has just done something, as a browser's transient activation answers it — the
+ * gate on what a page may do only in answer to a person: pointer lock, fullscreen.
+ *
+ * **Chrome's rules, measured 2026-09-19 in Chrome 151 over the DevTools protocol.** A key down
+ * other than Escape, a mouse press or a finger lifted makes a page active for five seconds: a
+ * request 4.5 s after an unused click was granted and one at 5.5 s refused. Fullscreen spends it —
+ * a second request 100 ms after a granted one was refused — and pointer lock does not: a lock and
+ * then fullscreen from one click were both granted. The input is noted before its event is sent,
+ * so a listener for that very event may already ask.
+ *
+ * What it gives up: a script's own `dispatchEvent` is never a gesture, as in a browser, so input a
+ * capture replays goes through SDL's events (`HostWindow.replay`) to count as one.
+ */
+const ACTIVE_MS = 5000;
+export class UserActivation {
+    now;
+    at = Number.NEGATIVE_INFINITY;
+    ever = false;
+    constructor(now) {
+        this.now = now;
+    }
+    /** A person did something: a key down, a mouse press, a finger lifted. */
+    notify() {
+        this.at = this.now();
+        this.ever = true;
+    }
+    /** Spent, by an ask that takes the gesture with it. */
+    consume() {
+        this.at = Number.NEGATIVE_INFINITY;
+    }
+    get isActive() {
+        return this.now() - this.at < ACTIVE_MS;
+    }
+    get hasBeenActive() {
+        return this.ever;
+    }
+}

package/dist/alphaCopy.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The alpha step of a browser's image copy, done where the browser does it: on the device.
+ *
+ * **Chrome converts alpha in a copy with a shader**, Dawn's `CopyTextureForBrowser`: it divides a
+ * premultiplied image's colour by its alpha, or multiplies a straight one's, in single precision on
+ * the GPU, and into an sRGB texture it decodes the result first so the write's own encode lands on
+ * it. This GPU's division is not correctly rounded, so no arithmetic on the CPU gives the same
+ * bytes: a rounded `c · 255 / a` differed from Chrome on 4,299 of 65,024 (colour, alpha) pairs.
+ * The same steps run here, in the same order and precision, on the same device.
+ *
+ * Measured 2026-09-19 against Chrome on this machine, for every colour at every alpha: the
+ * divide and the multiply, into `rgba8unorm` and into `rgba8unorm-srgb` — see `device.test.ts` for
+ * the pairs held as literals.
+ *
+ * **What it gives up: the bytes are this GPU's.** Another GPU divides differently, and so does
+ * Chrome on it, so the claim is "what Chrome writes on the machine the host runs on", which is
+ * the only thing a pixel gate on that machine can compare.
+ */
+/** Which conversion a copy needs. */
+export type AlphaStep = 'unpremultiply' | 'premultiply';
+export declare class AlphaCopier {
+    private readonly device;
+    private readonly pipelines;
+    private module;
+    constructor(device: GPUDevice);
+    /**
+     * Write an image through `step` into `destination`: `bytes` are four a texel, `imageWidth` wide,
+     * and the top-left `width` by `height` of them is what is copied.
+     *
+     * The destination must allow rendering into it, which a copy's destination already must
+     * (`copyExternalImageToTexture` asks for `RENDER_ATTACHMENT`). Submitted here, so it is ordered
+     * on the queue where the copy it stands in for was called.
+     */
+    copy(bytes: Uint8Array, imageWidth: number, imageHeight: number, step: AlphaStep, destination: GPUCopyExternalImageDestInfo, width: number, height: number): void;
+    private pipelineFor;
+}

package/dist/alphaCopy.js

@@ -0,0 +1,178 @@
+/**
+ * The alpha step of a browser's image copy, done where the browser does it: on the device.
+ *
+ * **Chrome converts alpha in a copy with a shader**, Dawn's `CopyTextureForBrowser`: it divides a
+ * premultiplied image's colour by its alpha, or multiplies a straight one's, in single precision on
+ * the GPU, and into an sRGB texture it decodes the result first so the write's own encode lands on
+ * it. This GPU's division is not correctly rounded, so no arithmetic on the CPU gives the same
+ * bytes: a rounded `c · 255 / a` differed from Chrome on 4,299 of 65,024 (colour, alpha) pairs.
+ * The same steps run here, in the same order and precision, on the same device.
+ *
+ * Measured 2026-09-19 against Chrome on this machine, for every colour at every alpha: the
+ * divide and the multiply, into `rgba8unorm` and into `rgba8unorm-srgb` — see `device.test.ts` for
+ * the pairs held as literals.
+ *
+ * **What it gives up: the bytes are this GPU's.** Another GPU divides differently, and so does
+ * Chrome on it, so the claim is "what Chrome writes on the machine the host runs on", which is
+ * the only thing a pixel gate on that machine can compare.
+ */
+const STEP_WGSL = /* wgsl */ `
+struct Params {
+  origin: vec2i,
+  steps: u32,
+  g: f32, a: f32, b: f32, c: f32, d: f32, e: f32, f: f32,
+}
+
+@group(0) @binding(0) var source: texture_2d<f32>;
+@group(0) @binding(1) var<uniform> params: Params;
+
+@vertex
+fn vertexMain(@builtin(vertex_index) index: u32) -> @builtin(position) vec4f {
+  let x = f32((index << 1u) & 2u);
+  let y = f32(index & 2u);
+  return vec4f(x * 2.0 - 1.0, 1.0 - y * 2.0, 0.0, 1.0);
+}
+
+/* Dawn's parametric transfer function, as its copy shader writes it. */
+fn transfer(v: f32) -> f32 {
+  let absV = abs(v);
+  let sgn = sign(v);
+  if (absV < params.d) {
+    return sgn * (params.c * absV + params.f);
+  }
+  return sgn * (pow(params.a * absV + params.b, params.g) + params.e);
+}
+
+@fragment
+fn fragmentMain(@builtin(position) position: vec4f) -> @location(0) vec4f {
+  var color = textureLoad(source, vec2i(position.xy) - params.origin, 0);
+  if ((params.steps & 1u) != 0u) {
+    if (color.a != 0.0) {
+      color = vec4f(color.rgb / color.a, color.a);
+    }
+  }
+  if ((params.steps & 2u) != 0u) {
+    color = vec4f(color.rgb * color.a, color.a);
+  }
+  if ((params.steps & 4u) != 0u) {
+    color = vec4f(transfer(color.r), transfer(color.g), transfer(color.b), color.a);
+  }
+  return color;
+}
+`;
+/* Usage flags, named here rather than read off a global a host may not have installed. */
+const COPY_DST = 0x2;
+const TEXTURE_BINDING = 0x4;
+const BUFFER_COPY_DST = 0x8;
+const UNIFORM = 0x40;
+const UNPREMULTIPLY = 1;
+const PREMULTIPLY = 2;
+const DECODE_FOR_SRGB = 4;
+/**
+ * The sRGB decode's parameters, as Dawn passes them: computed in double and stored as float, which
+ * is what a `Float32Array` does with the same expressions.
+ */
+const SRGB_DECODE = [2.4, 1 / 1.055, 0.055 / 1.055, 1 / 12.92, 0.04045, 0, 0];
+/** 48 bytes: the struct is 40, and a uniform binding is sized in sixteens. */
+const PARAMS_BYTES = 48;
+export class AlphaCopier {
+    device;
+    pipelines = new Map();
+    module = null;
+    constructor(device) {
+        this.device = device;
+    }
+    /**
+     * Write an image through `step` into `destination`: `bytes` are four a texel, `imageWidth` wide,
+     * and the top-left `width` by `height` of them is what is copied.
+     *
+     * The destination must allow rendering into it, which a copy's destination already must
+     * (`copyExternalImageToTexture` asks for `RENDER_ATTACHMENT`). Submitted here, so it is ordered
+     * on the queue where the copy it stands in for was called.
+     */
+    copy(bytes, imageWidth, imageHeight, step, destination, width, height) {
+        const device = this.device;
+        const target = destination.texture;
+        const format = target.format;
+        const origin = destination.origin;
+        const x = origin?.x ?? 0;
+        const y = origin?.y ?? 0;
+        const source = device.createTexture({
+            label: 'native alpha copy',
+            size: [imageWidth, imageHeight],
+            format: 'rgba8unorm',
+            usage: COPY_DST | TEXTURE_BINDING,
+        });
+        device.queue.writeTexture({ texture: source }, bytes, { bytesPerRow: imageWidth * 4 }, [
+            imageWidth,
+            imageHeight,
+        ]);
+        const params = new ArrayBuffer(PARAMS_BYTES);
+        new Int32Array(params, 0, 2).set([x, y]);
+        const steps = (step === 'unpremultiply' ? UNPREMULTIPLY : PREMULTIPLY) |
+            (format.endsWith('-srgb') ? DECODE_FOR_SRGB : 0);
+        new Uint32Array(params, 8, 1)[0] = steps;
+        new Float32Array(params, 12, 7).set(SRGB_DECODE);
+        const uniforms = device.createBuffer({
+            label: 'native alpha copy',
+            size: PARAMS_BYTES,
+            usage: UNIFORM | BUFFER_COPY_DST,
+        });
+        device.queue.writeBuffer(uniforms, 0, params);
+        const pipeline = this.pipelineFor(format);
+        const group = device.createBindGroup({
+            label: 'native alpha copy',
+            layout: pipeline.getBindGroupLayout(0),
+            entries: [
+                { binding: 0, resource: source.createView() },
+                { binding: 1, resource: { buffer: uniforms } },
+            ],
+        });
+        const encoder = device.createCommandEncoder({ label: 'native alpha copy' });
+        const pass = encoder.beginRenderPass({
+            label: 'native alpha copy',
+            colorAttachments: [
+                {
+                    view: target.createView({
+                        dimension: '2d',
+                        baseMipLevel: destination.mipLevel ?? 0,
+                        mipLevelCount: 1,
+                        baseArrayLayer: origin?.z ?? 0,
+                        arrayLayerCount: 1,
+                    }),
+                    /* Kept, because the copy covers a rectangle and the rest of the level is not its own. */
+                    loadOp: 'load',
+                    storeOp: 'store',
+                },
+            ],
+        });
+        pass.setPipeline(pipeline);
+        pass.setBindGroup(0, group);
+        pass.setViewport(x, y, width, height, 0, 1);
+        pass.setScissorRect(x, y, width, height);
+        pass.draw(3);
+        pass.end();
+        device.queue.submit([encoder.finish()]);
+        /* Released once the work that reads them is done; Dawn's binding asserts on a release under
+           work in flight. */
+        void device.queue.onSubmittedWorkDone().then(() => {
+            source.destroy();
+            uniforms.destroy();
+        });
+    }
+    pipelineFor(format) {
+        const held = this.pipelines.get(format);
+        if (held !== undefined)
+            return held;
+        this.module ??= this.device.createShaderModule({ label: 'native alpha copy', code: STEP_WGSL });
+        const pipeline = this.device.createRenderPipeline({
+            label: 'native alpha copy',
+            layout: 'auto',
+            vertex: { module: this.module, entryPoint: 'vertexMain' },
+            fragment: { module: this.module, entryPoint: 'fragmentMain', targets: [{ format }] },
+            primitive: { topology: 'triangle-list' },
+        });
+        this.pipelines.set(format, pipeline);
+        return pipeline;
+    }
+}

package/dist/audio.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Web Audio for a host with no browser: the Rust engine's contexts, with Opus decoded where it
+ * cannot, and underruns counted.
+ *
+ * **The engine's mix is Web Audio from end to end** — `AudioGraph` and `MixConsole` build nodes on a
+ * context and never touch a device — so the host's job is a Web Audio implementation, not a mixer.
+ * It is `node-web-audio-api` (IRCAM, BSD-3-Clause), `web-audio-api-rs` with prebuilt binaries,
+ * which plays through JACK on Linux, and PipeWire provides that. Chosen by the maintainer on
+ * 2026-09-19.
+ *
+ * **Opus is decoded here**, by libopus as WebAssembly (`ogg-opus-decoder`, MIT), because the Rust
+ * engine's decoder refuses it (measured: "unsupported audio codec") and Opus is the first format the
+ * engine's sound registry looks for. Anything else goes to the Rust engine's own decoder. A decode
+ * comes back at the context's sample rate, as the specification's `decodeAudioData` does: Opus is
+ * always 48 kHz, so a context at another rate has it resampled, by the same engine rendering it
+ * offline.
+ *
+ * **Sample rate and buffer size are the host's to ask for** — `sampleRate` and `latencyHint`, given
+ * to every context the engine creates, and what the device gave is reported once it runs; under
+ * JACK the server sets the buffer, so the latency asked for is a request. **An underrun is counted**
+ * from the context's `renderCapacity` and said once, rather than heard as a click and never
+ * reported.
+ *
+ * What it gives up: a browser's autoplay rule, which has no meaning here, so a context runs from
+ * the moment it is made; and the decoders' sample-for-sample agreement with Chrome's, which no
+ * gate compares yet.
+ */
+type WebAudioModule = {
+    AudioContext: typeof AudioContext;
+    OfflineAudioContext: typeof OfflineAudioContext;
+    AudioBuffer: typeof AudioBuffer;
+};
+export interface AudioDefaults {
+    readonly sampleRate?: number;
+    /** A category, or seconds of buffer. */
+    readonly latencyHint?: AudioContextLatencyCategory | number;
+    /** `none` for a context with no output device: a check, a CI machine. */
+    readonly sink?: 'default' | 'none';
+}
+/** An Ogg stream whose first page carries an Opus header. */
+export declare function isOggOpus(bytes: Uint8Array): boolean;
+/** Watches a context's render capacity and counts the updates in which it could not keep up. */
+export declare class UnderrunCounter {
+    underruns: number;
+    constructor(capacity: EventTarget & {
+        start(options?: {
+            updateInterval?: number;
+        }): void;
+    });
+}
+/** The two context classes a page has, over the Rust engine, with the host's defaults. */
+export declare function hostAudioContexts(defaults?: AudioDefaults): WebAudioModule;
+/** Give the page its audio globals, and hand back what takes them away again. */
+export declare function installAudio(defaults?: AudioDefaults, scope?: Record<string, unknown>): () => void;
+export {};