@driftengine/audio 3.62.0 → 4.0.0

package/NOTICE

@@ -7,3 +7,23 @@ This product includes software developed at Drift Technologies
 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

@@ -4,7 +4,7 @@ Layered stems, synthesis, rhythm and kick detection, distance and stereo placeme
 sources, reverb zones a **source** can be inside as well as the listener, and first-order
 ambisonic soundfields decoded through six virtual speakers.
 
-**Cost: 6.0 KB gzipped on top of core.** Measured by `scripts/size-gate.test.mjs`, which fails if it drifts more than
+**Cost: 6.1 KB gzipped on top of core.** Measured by `scripts/size-gate.test.mjs`, which fails if it drifts more than
 3% — the number is a fact about the build rather than a claim in a document.
 
 Part of [DriftEngine](../../README.md). See [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md)

package/dist/filters.d.ts

@@ -18,6 +18,16 @@
  * *feeling* of accelerating rather than the number.
  */
 export declare function cutoffForSpeed(speed: number, maxSpeed: number): number;
+/**
+ * Where the master low-pass stands until somebody moves it: open, at the top of its range.
+ *
+ * **It stood at `cutoffForSpeed(0, 1)` — 320 Hz — until 2026-09-19**, so every mix was heard
+ * through a wall until its caller drove the speed curve above: one game's "the filter opens as you
+ * sprint" standing in as every consumer's default. A game that wants its world muffled at rest
+ * says so with `setCutoff(cutoffForSpeed(0, max))`, and one that never thought about it hears its
+ * mix.
+ */
+export declare const MASTER_OPEN_HZ = 20000;
 export declare function clamp01(value: number): number;
 /**
  * The lift, at rest and at full.

package/dist/filters.js

@@ -22,6 +22,16 @@ export function cutoffForSpeed(speed, maxSpeed) {
     const t = Math.min(Math.max(speed / safeMax, 0), 1);
     return 320 * (18000 / 320) ** t;
 }
+/**
+ * Where the master low-pass stands until somebody moves it: open, at the top of its range.
+ *
+ * **It stood at `cutoffForSpeed(0, 1)` — 320 Hz — until 2026-09-19**, so every mix was heard
+ * through a wall until its caller drove the speed curve above: one game's "the filter opens as you
+ * sprint" standing in as every consumer's default. A game that wants its world muffled at rest
+ * says so with `setCutoff(cutoffForSpeed(0, max))`, and one that never thought about it hears its
+ * mix.
+ */
+export const MASTER_OPEN_HZ = 20000;
 export function clamp01(value) {
     return Number.isFinite(value) ? Math.min(Math.max(value, 0), 1) : 0;
 }

package/dist/index.d.ts

@@ -7,7 +7,7 @@
  */
 export { SoundRegistry } from './registry.ts';
 export { AudioGraph } from './graph.ts';
-export { cutoffForSpeed } from './filters.ts';
+export { MASTER_OPEN_HZ, cutoffForSpeed } from './filters.ts';
 export { audioContextConstructor, claimPlaybackSession } from './session.ts';
 export { AUDIO_FORMATS, audioCandidateUrls } from './formats.ts';
 export { fetchAudioManifest, parseAudioManifest } from './manifest.ts';

package/dist/index.js

@@ -7,7 +7,7 @@
  */
 export { SoundRegistry } from './registry.js';
 export { AudioGraph } from './graph.js';
-export { cutoffForSpeed } from './filters.js';
+export { MASTER_OPEN_HZ, cutoffForSpeed } from './filters.js';
 /* The two lines that make Web Audio audible on an iPhone, for a consumer whose audio is one
    decoded file through its own chain rather than a stem player. `AudioGraph` already calls both
    and in this order; anything building its own context has to do the same. */

package/dist/manifest.js

@@ -15,7 +15,9 @@
  * that some of them are music.
  */
 /** Every name in a manifest, or an empty list if there is not one. */
-export async function fetchAudioManifest(url, fetchImpl = (target) => fetch(target)) {
+export async function fetchAudioManifest(url, 
+// platform: browser default — `FetchLike` is the seam and this is its default
+fetchImpl = (target) => fetch(target)) {
     let parsed;
     try {
         const response = await fetchImpl(url);

package/dist/mix/defaultLayout.d.ts

@@ -7,10 +7,10 @@ import { type DelayInsert } from './returns.ts';
  * The mix as it has always been, expressed in buses and inserts.
  *
  * ```
- *   music ─ [lift] ─ tap ─ [slam] ─┐
- *     └─ sends from tap ───────────┼→ master ─ [master lowpass] ─ out ─→ destination
- *   effects ─────────────────────── ┘                                    ↑
- *   reverb · longReverb · delay ────────────────────────────────────────┘
+ *   music ─ [align] ─ [lift] ─ tap ─ [slam] ─┐
+ *     └─ sends from tap ─────────────────────┼→ master ─ [master lowpass] ─ out ─→ destination
+ *   effects ───────────────────────────────── ┘                                    ↑
+ *   reverb · longReverb · delay ──────────────────────────────────────────────────┘
  * ```
  *
  * **This is a transcription and it is meant to stay one.** Every level, every frequency and every

package/dist/mix/defaultLayout.js

@@ -22,9 +22,14 @@ export function defaultLayout(mix, levels) {
      * muting the score while keeping the game audible is the single most-used audio setting there is.
      */
     const music = mix.bus('music', { level: levels.music });
+    const slam = slamInsert(mix.context, () => mix.scheduleAt());
+    /*
+     * The slam's wet arm is late by its shaper's latency and meets the dry arm and every send at the
+     * output, so all of them wait for it here, at the head of the bus. See `SlamInsert.align`.
+     */
+    music.insert(slam.align);
     const lift = liftInsert(mix.context, () => mix.scheduleAt());
     music.insert(lift);
-    const slam = slamInsert(mix.context, () => mix.scheduleAt());
     /*
      * Below the tap, so the sends never hear it: a six-second convolution of a clipped bass hit is a
      * mess, and it would still be arriving three gates later.

package/dist/mix/inserts.d.ts

@@ -42,6 +42,26 @@ export interface SlamInsert extends MixInsert {
      * been removed, and would be at its weakest where half the gates are taken.
      */
     readonly wetInput: AudioNode;
+    /**
+     * The wet arm's latency, given to everything the wet arm is summed with: a stage for the head of
+     * the bus, fed from the node `wetInput` is, ahead of the dry arm and of every send.
+     *
+     * The wet arm's shaper is oversampled, and an oversampler is a pair of resampling filters that
+     * delay what passes by an amount no specification fixes — measured 2026-09-19, 192 samples at 4x
+     * in Chrome and 128 in `node-web-audio-api`. With nothing on the other side waiting for it, a
+     * strike combed against the very score it was blended into: 1.6 dB of a full strike cancelled in
+     * Chrome, and a different comb on each implementation. So this is the same oversampling around a
+     * curve that changes nothing, and it is as late as the wet arm wherever it runs, with nothing
+     * measured and nothing looked up.
+     *
+     * **What it costs.** The bus it heads is late by that latency, about four milliseconds, against
+     * every bus it does not head; it is band-limited as the oversampler band-limits, which is
+     * −98 dB of difference from a plain delay up to 20 kHz, measured in Chrome; and the bus pays for
+     * a second oversampler, about 7 ms of render per two seconds of mono there. What would make it
+     * wrong: an implementation whose oversampling latency depends on the curve, or a shaper that
+     * reports its latency, which would let a plain `DelayNode` do this for less.
+     */
+    readonly align: MixInsert;
     /** The dry path's duck and the wet path's blend, exposed so a test can assert an idle stage. */
     readonly dryGain: GainNode;
     readonly wetGain: GainNode;
@@ -58,7 +78,7 @@ export interface SlamInsert extends MixInsert {
  * music path colours the score for the whole run — a track mastered near full scale is already
  * touching any knee low enough to be useful — so the effect would stop being an event and become
  * the sound of the game. With a dry path at unity and a wet path at zero, an idle graph is
- * sample-identical to one without this stage in it, which is what lets the identity gate pass
- * across a rewrite that moved it into a bus.
+ * sample-identical to one without this stage in it but for `align`, which is what lets the identity
+ * gate pass across a rewrite that moved it into a bus.
  */
 export declare function slamInsert(context: BaseAudioContext, scheduleAt: ScheduleClock): SlamInsert;

package/dist/mix/inserts.js

@@ -1,4 +1,4 @@
-import { LIFT_FLOOR_HZ, SLAM_ATTACK_SEC, SLAM_CLIP_KNEE, SLAM_CLOSED_HZ, SLAM_DECAY_SEC, SLAM_DRIVE, SLAM_DUCK, SLAM_OPEN_HZ, SLAM_SHELF_DB, SLAM_SHELF_HZ, clamp01, cutoffForSpeed, liftFrequencyHz, liftGainFor, } from '../filters.js';
+import { LIFT_FLOOR_HZ, MASTER_OPEN_HZ, SLAM_ATTACK_SEC, SLAM_CLIP_KNEE, SLAM_CLOSED_HZ, SLAM_DECAY_SEC, SLAM_DRIVE, SLAM_DUCK, SLAM_OPEN_HZ, SLAM_SHELF_DB, SLAM_SHELF_HZ, clamp01, liftFrequencyHz, liftGainFor, } from '../filters.js';
 /**
  * The stages a bus can carry, as things rather than as lines in one constructor.
  *
@@ -24,14 +24,14 @@ function ramp(param, value, scheduleAt) {
 export function masterFilterInsert(context, scheduleAt) {
     const filter = context.createBiquadFilter();
     filter.type = 'lowpass';
-    filter.frequency.value = cutoffForSpeed(0, 1);
+    filter.frequency.value = MASTER_OPEN_HZ;
     filter.Q.value = 0.7;
     return {
         input: filter,
         output: filter,
         filter,
         setCutoff(hz) {
-            ramp(filter.frequency, Math.min(Math.max(hz, 40), 20000), scheduleAt);
+            ramp(filter.frequency, Math.min(Math.max(hz, 40), MASTER_OPEN_HZ), scheduleAt);
         },
         /*
          * Not a second filter in the chain: the master low-pass is already there and already ramped, so
@@ -82,6 +82,15 @@ export function liftInsert(context, scheduleAt) {
         },
     };
 }
+/** The wet arm's oversampling, which `align` repeats on the other side. */
+const SLAM_OVERSAMPLE = '4x';
+/**
+ * How far from zero `align` passes a signal unchanged: 18 dB above full scale, for a bus that sums
+ * stems each mastered near it. What it gives up is the floor — the curve is looked up at a position
+ * scaled down by this, which rounds, measured at −123 dB on a sine at half scale in Chrome; the
+ * range is a power of two so the scaling itself is exact.
+ */
+const ALIGN_RANGE = 8;
 /**
  * The slam: a parallel band of driven low end, blended in for a fraction of a second and gone.
  *
@@ -93,10 +102,20 @@ export function liftInsert(context, scheduleAt) {
  * music path colours the score for the whole run — a track mastered near full scale is already
  * touching any knee low enough to be useful — so the effect would stop being an event and become
  * the sound of the game. With a dry path at unity and a wet path at zero, an idle graph is
- * sample-identical to one without this stage in it, which is what lets the identity gate pass
- * across a rewrite that moved it into a bus.
+ * sample-identical to one without this stage in it but for `align`, which is what lets the identity
+ * gate pass across a rewrite that moved it into a bus.
  */
 export function slamInsert(context, scheduleAt) {
+    /*
+     * A two-point curve is a straight line from end to end, so scaled down by the range going in and
+     * back up by it coming out, it is the identity for anything within ±`ALIGN_RANGE`.
+     */
+    const alignInput = context.createGain();
+    alignInput.gain.value = 1 / ALIGN_RANGE;
+    const align = context.createWaveShaper();
+    align.curve = new Float32Array([-ALIGN_RANGE, ALIGN_RANGE]);
+    align.oversample = SLAM_OVERSAMPLE;
+    alignInput.connect(align);
     const dry = context.createGain();
     dry.gain.value = 1;
     const output = context.createGain();
@@ -122,7 +141,7 @@ export function slamInsert(context, scheduleAt) {
     shaper.curve = softClipCurve();
     // The clip generates harmonics well above the band it came from; without oversampling those
     // alias back down as grit that does not belong to the hit.
-    shaper.oversample = '4x';
+    shaper.oversample = SLAM_OVERSAMPLE;
     const wet = context.createGain();
     wet.gain.value = 0;
     shelf.connect(lowpass);
@@ -134,6 +153,7 @@ export function slamInsert(context, scheduleAt) {
         input: dry,
         output,
         wetInput: shelf,
+        align: { input: alignInput, output: align },
         dryGain: dry,
         wetGain: wet,
         /**

package/dist/registry.js

@@ -5,6 +5,7 @@ export class SoundRegistry {
     origins = new Map();
     /** Slots whose stand-in threw. Empty is the normal state; see `unbuilt`. */
     failed = new Map();
+    // platform: browser default — `FetchLike` is the seam and this is its default
     constructor(fetchImpl = (url) => fetch(url)) {
         this.fetchImpl = fetchImpl;
     }

package/dist/session.js

@@ -43,8 +43,10 @@
  * that goes quiet in a pocket.
  */
 export function claimPlaybackSession() {
+    // platform: feature probe — absent is a defined state, and the line below reads it
     if (typeof navigator === 'undefined')
         return;
+    // platform: feature probe — guarded by the line above; absent is a defined state
     const session = navigator.audioSession;
     if (session === undefined || session === null)
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/audio",
-  "version": "3.62.0",
+  "version": "4.0.0",
   "description": "Layered stems, synthesis, rhythm analysis and positional placement",
   "license": "Apache-2.0",
   "type": "module",

package/src/filters.ts

@@ -24,6 +24,17 @@ export function cutoffForSpeed(speed: number, maxSpeed: number): number {
   return 320 * (18000 / 320) ** t;
 }
 
+/**
+ * Where the master low-pass stands until somebody moves it: open, at the top of its range.
+ *
+ * **It stood at `cutoffForSpeed(0, 1)` — 320 Hz — until 2026-09-19**, so every mix was heard
+ * through a wall until its caller drove the speed curve above: one game's "the filter opens as you
+ * sprint" standing in as every consumer's default. A game that wants its world muffled at rest
+ * says so with `setCutoff(cutoffForSpeed(0, max))`, and one that never thought about it hears its
+ * mix.
+ */
+export const MASTER_OPEN_HZ = 20000;
+
 export function clamp01(value: number): number {
   return Number.isFinite(value) ? Math.min(Math.max(value, 0), 1) : 0;
 }

package/src/index.ts

@@ -8,7 +8,7 @@
 
 export { SoundRegistry } from './registry.ts';
 export { AudioGraph } from './graph.ts';
-export { cutoffForSpeed } from './filters.ts';
+export { MASTER_OPEN_HZ, cutoffForSpeed } from './filters.ts';
 /* The two lines that make Web Audio audible on an iPhone, for a consumer whose audio is one
    decoded file through its own chain rather than a stem player. `AudioGraph` already calls both
    and in this order; anything building its own context has to do the same. */

package/src/manifest.ts

@@ -20,6 +20,7 @@ import type { FetchLike } from './registry.ts';
 /** Every name in a manifest, or an empty list if there is not one. */
 export async function fetchAudioManifest(
   url: string,
+  // platform: browser default — `FetchLike` is the seam and this is its default
   fetchImpl: FetchLike = (target) => fetch(target),
 ): Promise<string[]> {
   let parsed: unknown;

package/src/mix/defaultLayout.ts

@@ -15,10 +15,10 @@ import { convolverInsert, delayInsert, type DelayInsert } from './returns.ts';
  * The mix as it has always been, expressed in buses and inserts.
  *
  * ```
- *   music ─ [lift] ─ tap ─ [slam] ─┐
- *     └─ sends from tap ───────────┼→ master ─ [master lowpass] ─ out ─→ destination
- *   effects ─────────────────────── ┘                                    ↑
- *   reverb · longReverb · delay ────────────────────────────────────────┘
+ *   music ─ [align] ─ [lift] ─ tap ─ [slam] ─┐
+ *     └─ sends from tap ─────────────────────┼→ master ─ [master lowpass] ─ out ─→ destination
+ *   effects ───────────────────────────────── ┘                                    ↑
+ *   reverb · longReverb · delay ──────────────────────────────────────────────────┘
  * ```
  *
  * **This is a transcription and it is meant to stay one.** Every level, every frequency and every
@@ -67,9 +67,14 @@ export function defaultLayout(mix: MixConsole, levels: MixLevels): DefaultLayout
    * muting the score while keeping the game audible is the single most-used audio setting there is.
    */
   const music = mix.bus('music', { level: levels.music });
+  const slam = slamInsert(mix.context, () => mix.scheduleAt());
+  /*
+   * The slam's wet arm is late by its shaper's latency and meets the dry arm and every send at the
+   * output, so all of them wait for it here, at the head of the bus. See `SlamInsert.align`.
+   */
+  music.insert(slam.align);
   const lift = liftInsert(mix.context, () => mix.scheduleAt());
   music.insert(lift);
-  const slam = slamInsert(mix.context, () => mix.scheduleAt());
   /*
    * Below the tap, so the sends never hear it: a six-second convolution of a clipped bass hit is a
    * mess, and it would still be arriving three gates later.

package/src/mix/inserts.ts

@@ -1,6 +1,7 @@
 import type { ScheduleClock } from '../ambientLoop.ts';
 import {
   LIFT_FLOOR_HZ,
+  MASTER_OPEN_HZ,
   SLAM_ATTACK_SEC,
   SLAM_CLIP_KNEE,
   SLAM_CLOSED_HZ,
@@ -11,7 +12,6 @@ import {
   SLAM_SHELF_DB,
   SLAM_SHELF_HZ,
   clamp01,
-  cutoffForSpeed,
   liftFrequencyHz,
   liftGainFor,
 } from '../filters.ts';
@@ -54,14 +54,14 @@ export function masterFilterInsert(
 ): MasterFilterInsert {
   const filter = context.createBiquadFilter();
   filter.type = 'lowpass';
-  filter.frequency.value = cutoffForSpeed(0, 1);
+  filter.frequency.value = MASTER_OPEN_HZ;
   filter.Q.value = 0.7;
   return {
     input: filter,
     output: filter,
     filter,
     setCutoff(hz: number): void {
-      ramp(filter.frequency, Math.min(Math.max(hz, 40), 20000), scheduleAt);
+      ramp(filter.frequency, Math.min(Math.max(hz, 40), MASTER_OPEN_HZ), scheduleAt);
     },
     /*
      * Not a second filter in the chain: the master low-pass is already there and already ramped, so
@@ -128,12 +128,42 @@ export interface SlamInsert extends MixInsert {
    * been removed, and would be at its weakest where half the gates are taken.
    */
   readonly wetInput: AudioNode;
+  /**
+   * The wet arm's latency, given to everything the wet arm is summed with: a stage for the head of
+   * the bus, fed from the node `wetInput` is, ahead of the dry arm and of every send.
+   *
+   * The wet arm's shaper is oversampled, and an oversampler is a pair of resampling filters that
+   * delay what passes by an amount no specification fixes — measured 2026-09-19, 192 samples at 4x
+   * in Chrome and 128 in `node-web-audio-api`. With nothing on the other side waiting for it, a
+   * strike combed against the very score it was blended into: 1.6 dB of a full strike cancelled in
+   * Chrome, and a different comb on each implementation. So this is the same oversampling around a
+   * curve that changes nothing, and it is as late as the wet arm wherever it runs, with nothing
+   * measured and nothing looked up.
+   *
+   * **What it costs.** The bus it heads is late by that latency, about four milliseconds, against
+   * every bus it does not head; it is band-limited as the oversampler band-limits, which is
+   * −98 dB of difference from a plain delay up to 20 kHz, measured in Chrome; and the bus pays for
+   * a second oversampler, about 7 ms of render per two seconds of mono there. What would make it
+   * wrong: an implementation whose oversampling latency depends on the curve, or a shaper that
+   * reports its latency, which would let a plain `DelayNode` do this for less.
+   */
+  readonly align: MixInsert;
   /** The dry path's duck and the wet path's blend, exposed so a test can assert an idle stage. */
   readonly dryGain: GainNode;
   readonly wetGain: GainNode;
   strike(amount: number): void;
 }
 
+/** The wet arm's oversampling, which `align` repeats on the other side. */
+const SLAM_OVERSAMPLE: OverSampleType = '4x';
+/**
+ * How far from zero `align` passes a signal unchanged: 18 dB above full scale, for a bus that sums
+ * stems each mastered near it. What it gives up is the floor — the curve is looked up at a position
+ * scaled down by this, which rounds, measured at −123 dB on a sine at half scale in Chrome; the
+ * range is a power of two so the scaling itself is exact.
+ */
+const ALIGN_RANGE = 8;
+
 /**
  * The slam: a parallel band of driven low end, blended in for a fraction of a second and gone.
  *
@@ -145,10 +175,21 @@ export interface SlamInsert extends MixInsert {
  * music path colours the score for the whole run — a track mastered near full scale is already
  * touching any knee low enough to be useful — so the effect would stop being an event and become
  * the sound of the game. With a dry path at unity and a wet path at zero, an idle graph is
- * sample-identical to one without this stage in it, which is what lets the identity gate pass
- * across a rewrite that moved it into a bus.
+ * sample-identical to one without this stage in it but for `align`, which is what lets the identity
+ * gate pass across a rewrite that moved it into a bus.
  */
 export function slamInsert(context: BaseAudioContext, scheduleAt: ScheduleClock): SlamInsert {
+  /*
+   * A two-point curve is a straight line from end to end, so scaled down by the range going in and
+   * back up by it coming out, it is the identity for anything within ±`ALIGN_RANGE`.
+   */
+  const alignInput = context.createGain();
+  alignInput.gain.value = 1 / ALIGN_RANGE;
+  const align = context.createWaveShaper();
+  align.curve = new Float32Array([-ALIGN_RANGE, ALIGN_RANGE]);
+  align.oversample = SLAM_OVERSAMPLE;
+  alignInput.connect(align);
+
   const dry = context.createGain();
   dry.gain.value = 1;
   const output = context.createGain();
@@ -175,7 +216,7 @@ export function slamInsert(context: BaseAudioContext, scheduleAt: ScheduleClock)
   shaper.curve = softClipCurve();
   // The clip generates harmonics well above the band it came from; without oversampling those
   // alias back down as grit that does not belong to the hit.
-  shaper.oversample = '4x';
+  shaper.oversample = SLAM_OVERSAMPLE;
   const wet = context.createGain();
   wet.gain.value = 0;
 
@@ -189,6 +230,7 @@ export function slamInsert(context: BaseAudioContext, scheduleAt: ScheduleClock)
     input: dry,
     output,
     wetInput: shelf,
+    align: { input: alignInput, output: align },
     dryGain: dry,
     wetGain: wet,
     /**

package/src/registry.ts

@@ -40,6 +40,7 @@ export class SoundRegistry {
   /** Slots whose stand-in threw. Empty is the normal state; see `unbuilt`. */
   private readonly failed = new Map<SoundSlot, string>();
 
+  // platform: browser default — `FetchLike` is the seam and this is its default
   constructor(private readonly fetchImpl: FetchLike = (url) => fetch(url)) {}
 
   register(slot: SoundSlot, source: SoundSource): void {

package/src/session.ts

@@ -54,7 +54,9 @@ interface AudioSessionLike {
  * that goes quiet in a pocket.
  */
 export function claimPlaybackSession(): void {
+  // platform: feature probe — absent is a defined state, and the line below reads it
   if (typeof navigator === 'undefined') return;
+  // platform: feature probe — guarded by the line above; absent is a defined state
   const session = (navigator as Navigator & { audioSession?: AudioSessionLike }).audioSession;
   if (session === undefined || session === null) return;
   try {