@driftengine/native-host 4.0.0

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@driftengine/native-host",
+  "version": "4.0.0",
+  "description": "The engine on a native window and a native WebGPU device, with no browser between them",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "drift-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json",
+    "./*": "./*"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.mjs",
+    "!src/**/__snapshots__",
+    "licenses",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@jsquash/jpeg": "1.6.0",
+    "ogg-opus-decoder": "1.7.5"
+  },
+  "optionalDependencies": {
+    "@kmamal/gpu": "0.2.0",
+    "@kmamal/sdl": "0.11.13",
+    "node-web-audio-api": "2.2.0"
+  },
+  "devDependencies": {
+    "@driftengine/audio": "4.0.0"
+  },
+  "peerDependencies": {
+    "@driftengine/core": "4.0.0",
+    "@driftengine/package": "4.0.0",
+    "@driftengine/texture": "4.0.0",
+    "@driftengine/ui2d": "4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@driftengine/texture": {
+      "optional": true
+    },
+    "@driftengine/ui2d": {
+      "optional": true
+    }
+  },
+  "author": "Drift Technologies",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drftrun/driftengine.git",
+    "directory": "packages/native-host"
+  },
+  "homepage": "https://github.com/drftrun/driftengine#readme",
+  "bugs": "https://github.com/drftrun/driftengine/issues",
+  "keywords": [
+    "driftengine",
+    "3d",
+    "webgpu",
+    "typescript",
+    "native",
+    "desktop",
+    "dawn",
+    "sdl"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepack": "node ../../scripts/build.mjs @driftengine/native-host"
+  }
+}

package/src/activation.ts

@@ -0,0 +1,42 @@
+/**
+ * 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 {
+  private at = Number.NEGATIVE_INFINITY;
+  private ever = false;
+
+  constructor(private readonly now: () => number) {}
+
+  /** A person did something: a key down, a mouse press, a finger lifted. */
+  notify(): void {
+    this.at = this.now();
+    this.ever = true;
+  }
+
+  /** Spent, by an ask that takes the gesture with it. */
+  consume(): void {
+    this.at = Number.NEGATIVE_INFINITY;
+  }
+
+  get isActive(): boolean {
+    return this.now() - this.at < ACTIVE_MS;
+  }
+
+  get hasBeenActive(): boolean {
+    return this.ever;
+  }
+}

package/src/alphaCopy.ts

@@ -0,0 +1,201 @@
+/**
+ * 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';
+
+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 {
+  private readonly device: GPUDevice;
+  private readonly pipelines = new Map<GPUTextureFormat, GPURenderPipeline>();
+  private module: GPUShaderModule | null = null;
+
+  constructor(device: GPUDevice) {
+    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: Uint8Array,
+    imageWidth: number,
+    imageHeight: number,
+    step: AlphaStep,
+    destination: GPUCopyExternalImageDestInfo,
+    width: number,
+    height: number,
+  ): void {
+    const device = this.device;
+    const target = destination.texture;
+    const format = target.format;
+    const origin = destination.origin as GPUOrigin3DDict | undefined;
+    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();
+    });
+  }
+
+  private pipelineFor(format: GPUTextureFormat): GPURenderPipeline {
+    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/src/audio.ts

@@ -0,0 +1,246 @@
+/**
+ * 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.
+ */
+
+import { createRequire } from 'node:module';
+
+import { OggOpusDecoder } from 'ogg-opus-decoder';
+
+import { correctAutomation } from './audioParams.ts';
+
+type WebAudioModule = {
+  AudioContext: typeof AudioContext;
+  OfflineAudioContext: typeof OfflineAudioContext;
+  AudioBuffer: typeof AudioBuffer;
+};
+
+/* A native module published as CommonJS. */
+const webAudio = createRequire(import.meta.url)('node-web-audio-api') as WebAudioModule;
+
+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 function isOggOpus(bytes: Uint8Array): boolean {
+  const text = (at: number, length: number) =>
+    String.fromCharCode(...bytes.subarray(at, at + length));
+  return bytes.length > 36 && text(0, 4) === 'OggS' && text(28, 8) === 'OpusHead';
+}
+
+/**
+ * How many samples an Ogg Opus stream holds: its last page's granule position less the header's
+ * pre-skip. The decoder drops the pre-skip and hands back the last packet whole, so it runs long;
+ * a browser's decode ends where the stream says it does. Measured on the fixture: 24,312 decoded,
+ * 24,000 kept, and those are Chrome's samples at no offset, to within 9.5e-6 — two builds of libopus
+ * rounding differently, about −100 dB.
+ */
+function opusLength(bytes: Uint8Array): number {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  let granule = 0;
+  for (let at = 0; at + 27 <= bytes.length && view.getUint32(at) === 0x4f676753;) {
+    granule = Number(view.getBigInt64(at + 6, true));
+    const segments = bytes[at + 26] as number;
+    let length = 0;
+    for (let s = 0; s < segments; s += 1) length += bytes[at + 27 + s] as number;
+    at += 27 + segments + length;
+  }
+  /* The header is the first page's packet, after its 27 bytes and its segment table. */
+  const preSkip = view.getUint16(27 + (bytes[26] as number) + 10, true);
+  return Math.max(0, granule - preSkip);
+}
+
+/** Opus to an `AudioBuffer` at `target`'s rate. */
+async function decodeOpus(bytes: Uint8Array, target: BaseAudioContext): Promise<AudioBuffer> {
+  const decoder = new OggOpusDecoder();
+  await decoder.ready;
+  try {
+    const decoded = await decoder.decodeFile(bytes);
+    if (decoded.errors.length > 0) {
+      throw new Error(
+        `[driftengine] the Opus stream did not decode: ${decoded.errors[0]?.message ?? ''}`,
+      );
+    }
+    const channels = decoded.channelData.length;
+    const frames = Math.min(decoded.samplesDecoded, opusLength(bytes));
+    const at48 = new webAudio.AudioBuffer({
+      numberOfChannels: channels,
+      length: frames,
+      sampleRate: decoded.sampleRate,
+    });
+    decoded.channelData.forEach((samples, channel) =>
+      at48.copyToChannel(samples.subarray(0, frames) as Float32Array<ArrayBuffer>, channel),
+    );
+    if (decoded.sampleRate === target.sampleRate) return at48;
+    /*
+     * The length as Chrome works it out — divided by the ratio of the rates, truncated — which
+     * makes 24,000 samples at 48 kHz 22,049 at 44.1 kHz rather than 22,050, because the ratio is
+     * not exact in a double. Measured in Chrome's own decode of the fixture.
+     */
+    const length = Math.floor(frames / (decoded.sampleRate / target.sampleRate));
+    const resampler = new webAudio.OfflineAudioContext(channels, length, target.sampleRate);
+    const source = resampler.createBufferSource();
+    source.buffer = at48;
+    source.connect(resampler.destination);
+    source.start();
+    return await resampler.startRendering();
+  } finally {
+    decoder.free();
+  }
+}
+
+/** `decodeAudioData`, in both of its shapes: a promise, and the two callbacks. */
+function decodeWith(
+  context: BaseAudioContext,
+  engine: (data: ArrayBuffer) => Promise<AudioBuffer>,
+  data: ArrayBuffer,
+  success?: DecodeSuccessCallback | null,
+  failure?: DecodeErrorCallback | null,
+): Promise<AudioBuffer> {
+  const bytes = new Uint8Array(data);
+  const decoding = isOggOpus(bytes) ? decodeOpus(bytes, context) : engine(data);
+  return decoding.then(
+    (buffer) => {
+      success?.(buffer);
+      return buffer;
+    },
+    (error: unknown) => {
+      failure?.(error as DOMException);
+      throw error;
+    },
+  );
+}
+
+/** Watches a context's render capacity and counts the updates in which it could not keep up. */
+export class UnderrunCounter {
+  underruns = 0;
+
+  constructor(capacity: EventTarget & { start(options?: { updateInterval?: number }): void }) {
+    capacity.addEventListener('update', (event) => {
+      if (((event as Event & { underrunRatio?: number }).underrunRatio ?? 0) <= 0) return;
+      this.underruns += 1;
+      if (this.underruns === 1) {
+        console.warn(
+          '[driftengine] audio underran: the output could not be fed in time. Counted from here on.',
+        );
+      }
+    });
+    capacity.start({ updateInterval: 1 });
+  }
+}
+
+/** The two context classes a page has, over the Rust engine, with the host's defaults. */
+export function hostAudioContexts(defaults: AudioDefaults = {}): WebAudioModule {
+  /* The Rust engine's scheduled ramps, corrected to Chrome's (`audioParams.ts`). */
+  correctAutomation();
+  const options = {
+    ...(defaults.sampleRate === undefined ? {} : { sampleRate: defaults.sampleRate }),
+    ...(defaults.latencyHint === undefined ? {} : { latencyHint: defaults.latencyHint }),
+    ...(defaults.sink === 'none' ? { sinkId: { type: 'none' } } : {}),
+  };
+  class HostAudioContext extends webAudio.AudioContext {
+    readonly underruns: UnderrunCounter | null;
+    constructor(asked: AudioContextOptions = {}) {
+      super({ ...options, ...asked });
+      /*
+       * Reported once the device has said what it gave, which it does a few milliseconds after the
+       * context starts: under JACK the server sets the buffer, so `latencyHint` is a request
+       * (measured here: 21 ms for either category, PipeWire's quantum). Asked for rather than
+       * listened for, because starting the render-capacity watch below starts the context before
+       * a `statechange` listener could hear it.
+       */
+      if (defaults.sink !== 'none') {
+        let tries = 0;
+        const report = (): void => {
+          tries += 1;
+          if (this.outputLatency <= 0 && tries < 50) {
+            setTimeout(report, 20).unref();
+            return;
+          }
+          const frames = Math.round(this.outputLatency * this.sampleRate);
+          console.log(
+            `[driftengine] audio: ${this.sampleRate} Hz, ${frames} frames of output latency (${(this.outputLatency * 1000).toFixed(1)} ms)`,
+          );
+        };
+        setTimeout(report, 20).unref();
+      }
+      /* Nothing renders against a clock with no device, so there is nothing to underrun. */
+      this.underruns =
+        defaults.sink === 'none'
+          ? null
+          : new UnderrunCounter(
+              (this as unknown as { renderCapacity: EventTarget & { start(): void } })
+                .renderCapacity,
+            );
+    }
+    override decodeAudioData(
+      data: ArrayBuffer,
+      success?: DecodeSuccessCallback | null,
+      failure?: DecodeErrorCallback | null,
+    ): Promise<AudioBuffer> {
+      return decodeWith(this, (bytes) => super.decodeAudioData(bytes), data, success, failure);
+    }
+  }
+  class HostOfflineAudioContext extends webAudio.OfflineAudioContext {
+    override decodeAudioData(
+      data: ArrayBuffer,
+      success?: DecodeSuccessCallback | null,
+      failure?: DecodeErrorCallback | null,
+    ): Promise<AudioBuffer> {
+      return decodeWith(this, (bytes) => super.decodeAudioData(bytes), data, success, failure);
+    }
+  }
+  return {
+    AudioContext: HostAudioContext as unknown as typeof AudioContext,
+    OfflineAudioContext: HostOfflineAudioContext as unknown as typeof OfflineAudioContext,
+    AudioBuffer: webAudio.AudioBuffer,
+  };
+}
+
+/** Give the page its audio globals, and hand back what takes them away again. */
+export function installAudio(
+  defaults: AudioDefaults = {},
+  scope: Record<string, unknown> = globalThis as Record<string, unknown>,
+): () => void {
+  const contexts = hostAudioContexts(defaults);
+  const held = (['AudioContext', 'OfflineAudioContext', 'AudioBuffer'] as const).map(
+    (name) => [name, name in scope, scope[name]] as const,
+  );
+  scope['AudioContext'] = contexts.AudioContext;
+  scope['OfflineAudioContext'] = contexts.OfflineAudioContext;
+  scope['AudioBuffer'] = contexts.AudioBuffer;
+  return () => {
+    for (const [name, had, value] of held) {
+      if (had) scope[name] = value;
+      else delete scope[name];
+    }
+  };
+}