@driftengine/core 3.61.0

package/src/render/windStreakRenderer.ts

@@ -0,0 +1,130 @@
+import type { FrameView } from './frameView.ts';
+import type { Vec3 } from '../math/color.ts';
+import { compileProgram, uniformLocations } from './shader.ts';
+import { WIND_STREAK_FRAG, WIND_STREAK_VERT } from './shaders/windStreaks.ts';
+import {
+  WIND_STREAK_DEFAULTS,
+  buildWindStreakLattice,
+  createResolvedWindStreaks,
+  resolveWindStreaks,
+  windStreakStrength,
+  type WindStreakSettings,
+} from './windStreakDraw.ts';
+import type { WindField } from './windField.ts';
+
+/**
+ * Makes the wind visible once it is strong enough to be worth seeing.
+ *
+ * The threshold matters as much as the effect. Debris in a light breeze is
+ * visual noise across the whole game; debris only when it is genuinely blowing
+ * is information — it tells the player why their glide is drifting, at the one
+ * moment they need to know.
+ *
+ * **The thresholds, the drift rate and the lattice are in `windStreakDraw.ts`**, so the WebGPU
+ * pass shows the same weather rather than its own approximation of it.
+ */
+export type WindStreakOptions = WindStreakSettings;
+
+export class WindStreakRenderer {
+  private readonly program: WebGLProgram;
+  private readonly uniforms: Record<string, WebGLUniformLocation>;
+  private readonly vao: WebGLVertexArrayObject;
+  private readonly buffers: WebGLBuffer[] = [];
+  private readonly vertexCount: number;
+  private readonly count: number;
+  /** Exposed so callers can size their own budgets against it. */
+  private readonly cellSize: number;
+  private readonly onsetSpeed: number;
+  private readonly fullSpeed: number;
+
+  constructor(gl: WebGL2RenderingContext, options: WindStreakOptions = {}) {
+    this.count = options.count ?? WIND_STREAK_DEFAULTS.count;
+    this.cellSize = options.cellSize ?? WIND_STREAK_DEFAULTS.cellSize;
+    this.onsetSpeed = options.onsetSpeed ?? WIND_STREAK_DEFAULTS.onsetSpeed;
+    this.fullSpeed = options.fullSpeed ?? WIND_STREAK_DEFAULTS.fullSpeed;
+
+    this.program = compileProgram(gl, WIND_STREAK_VERT, WIND_STREAK_FRAG, 'windStreaks');
+    this.uniforms = uniformLocations(gl, this.program, 'windStreakRenderer');
+
+    const lattice = buildWindStreakLattice(this.count);
+    const { corners, indices } = lattice;
+    this.vertexCount = lattice.vertexCount;
+
+    const vao = gl.createVertexArray();
+    if (vao === null) throw new Error('WindStreakRenderer: createVertexArray failed');
+    this.vao = vao;
+    gl.bindVertexArray(vao);
+    const attach = (data: Float32Array, location: number, size: number): void => {
+      const buffer = gl.createBuffer();
+      if (buffer === null) throw new Error('WindStreakRenderer: createBuffer failed');
+      this.buffers.push(buffer);
+      gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+      gl.bufferData(gl.ARRAY_BUFFER, data, gl.STATIC_DRAW);
+      gl.enableVertexAttribArray(location);
+      gl.vertexAttribPointer(location, size, gl.FLOAT, false, 0, 0);
+    };
+    attach(corners, 0, 2);
+    attach(indices, 1, 1);
+    gl.bindVertexArray(null);
+  }
+
+  /** How visible the wind is right now, 0 when there is nothing to show. */
+  strengthFor(speed: number): number {
+    return windStreakStrength(speed, this.onsetSpeed, this.fullSpeed);
+  }
+
+  /** Refilled per call rather than allocated; this is a per-frame path. */
+  private readonly resolved = createResolvedWindStreaks();
+
+  draw(
+    gl: WebGL2RenderingContext,
+    camera: FrameView,
+    wind: WindField,
+    timeSeconds: number,
+    tint: Vec3,
+    /** True when the camera is below the waterline. */
+    submerged = false,
+  ): void {
+    /* Chosen in `windStreakDraw.ts` so both backends show the same weather. */
+    const settled = resolveWindStreaks(
+      wind.speed,
+      wind.driftX,
+      wind.driftZ,
+      this.onsetSpeed,
+      this.fullSpeed,
+      submerged,
+      this.resolved,
+    );
+    if (!settled.visible) return;
+
+    const u = this.uniforms;
+    gl.useProgram(this.program);
+    gl.uniformMatrix4fv(u['uViewProj'] ?? null, false, camera.viewProjection);
+    gl.uniform3fv(u['uCameraPos'] ?? null, camera.position);
+    gl.uniform2f(u['uWind'] ?? null, wind.velocityX, wind.velocityZ);
+    gl.uniform2f(u['uDrift'] ?? null, settled.driftX, settled.driftZ);
+    gl.uniform1f(u['uSpeed'] ?? null, wind.speed);
+    gl.uniform1f(u['uStrength'] ?? null, settled.strength);
+    gl.uniform1f(u['uCount'] ?? null, this.count);
+    gl.uniform1f(u['uCellSize'] ?? null, this.cellSize);
+    gl.uniform1f(u['uTime'] ?? null, timeSeconds);
+    gl.uniform3fv(u['uTint'] ?? null, tint);
+
+    gl.enable(gl.BLEND);
+    gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+    gl.depthMask(false);
+    gl.disable(gl.CULL_FACE);
+    gl.bindVertexArray(this.vao);
+    gl.drawArrays(gl.TRIANGLES, 0, this.vertexCount);
+    gl.bindVertexArray(null);
+    gl.enable(gl.CULL_FACE);
+    gl.depthMask(true);
+    gl.disable(gl.BLEND);
+  }
+
+  dispose(gl: WebGL2RenderingContext): void {
+    for (const buffer of this.buffers) gl.deleteBuffer(buffer);
+    gl.deleteVertexArray(this.vao);
+    gl.deleteProgram(this.program);
+  }
+}

package/src/scene/node.ts

@@ -0,0 +1,336 @@
+import { mat4, quat } from 'gl-matrix';
+
+import { createBounds } from '../math/bounds.ts';
+import type { Bounds } from '../math/bounds.ts';
+
+/**
+ * A transform with a parent, and the world matrix it derives.
+ *
+ * **Additive and never required.** Three consumers describe their worlds their own way and none of
+ * them has to adopt this; nothing in the renderer knows a node exists. What it offers is the one
+ * thing an immediate-mode API makes a caller repeat — composing a child's placement out of its
+ * parent's — done once, and done only for what moved.
+ *
+ * **It does not draw, and that is deliberate rather than unfinished.** The render graph work
+ * established that a caller's draw order carries meaning: alpha and depth make *after* different
+ * from *before*, and it is why a registered pass runs where a caller invokes it rather than at a
+ * phase the engine picks. A traversal that issued draws would take that back. `visitVisible`
+ * yields nodes; what to do with one is the caller's.
+ */
+
+/** Bumped on every world recomputation, so a caller can tell whether anything happened. */
+let revisions = 0;
+
+export class SceneNode {
+  /** Local translation. Written in place; call `markMoved` if you write it directly. */
+  readonly position = new Float32Array([0, 0, 0]);
+  /**
+   * Local rotation, as a quaternion.
+   *
+   * **A quaternion and not the yaw this engine uses everywhere else.** Every rotation in the tree
+   * today is a yaw or a matrix, because nothing has needed to *interpolate* one — and a node is
+   * what animation will hold, where "rigid TRS, then skinning" is the first line of that track.
+   * Interpolating Euler angles gives gimbal artefacts and a path through orientations nobody
+   * authored, and carrying the right type from the start is cheaper than migrating every node a
+   * consumer has built.
+   */
+  readonly rotation = new Float32Array([0, 0, 0, 1]);
+  readonly scale = new Float32Array([1, 1, 1]);
+
+  readonly localMatrix = new Float32Array(16);
+  readonly worldMatrix = new Float32Array(16);
+
+  parent: SceneNode | null = null;
+  readonly children: SceneNode[] = [];
+
+  /** What `worldMatrix` was last recomputed at. See `revisions`. */
+  worldRevision = 0;
+
+  /**
+   * This node's own geometry, in its own space, or null for a node that only groups.
+   *
+   * Set from a mesh's `bounds`, which the renderer measures at upload — so a caller hands over
+   * what it already has rather than describing its geometry twice.
+   */
+  private localBounds: Bounds | null = null;
+
+  /**
+   * A sphere enclosing this node's geometry **and every descendant's**.
+   *
+   * **The union is what makes a traversal a partition rather than a loop.** A parent that can be
+   * tested once and answer for everything beneath it lets a frustum discard a subtree; a parent
+   * covering only its own geometry answers for nothing, and the walk has to visit every node to
+   * find out — which is the linear scan a hierarchy exists to replace.
+   *
+   * A node with no geometry and no children is a point at its own origin, which is the honest
+   * answer and is never inside a frustum by accident: a zero radius passes only where the point
+   * itself does.
+   */
+  readonly worldBounds: Bounds = createBounds();
+
+  /** This node's own transform has changed and `localMatrix` is stale. */
+  private localDirty = true;
+  /** This node or something above it has moved, so `worldMatrix` is stale. */
+  private worldDirty = true;
+  /** What `worldBounds` was last unioned at, so a child moving alone is still noticed. */
+  private boundsRevision = -1;
+
+  constructor() {
+    mat4.identity(this.localMatrix);
+    mat4.identity(this.worldMatrix);
+  }
+
+  setPosition(x: number, y: number, z: number): void {
+    this.position[0] = x;
+    this.position[1] = y;
+    this.position[2] = z;
+    this.markMoved();
+  }
+
+  setScale(x: number, y: number, z: number): void {
+    this.scale[0] = x;
+    this.scale[1] = y;
+    this.scale[2] = z;
+    this.markMoved();
+  }
+
+  /**
+   * Say what geometry this node holds, in its own space.
+   *
+   * Held by reference rather than copied: a mesh's bounds do not change after upload, and a
+   * caller passing the same mesh to a thousand nodes should not pay for a thousand copies.
+   */
+  setBounds(bounds: Bounds | null): void {
+    this.localBounds = bounds;
+    this.markMoved();
+  }
+
+  /** Whether this node has geometry of its own, as opposed to only grouping others. */
+  get hasGeometry(): boolean {
+    return this.localBounds !== null;
+  }
+
+  /** Set the rotation from an axis and an angle in radians. The axis need not be normalised. */
+  setRotationAxisAngle(x: number, y: number, z: number, radians: number): void {
+    const length = Math.sqrt(x * x + y * y + z * z);
+    const scale = length > 1e-12 ? 1 / length : 0;
+    quat.setAxisAngle(this.rotation, [x * scale, y * scale, z * scale], radians);
+    this.markMoved();
+  }
+
+  /**
+   * Say that this node's transform was written directly.
+   *
+   * `position`, `rotation` and `scale` are handed out as arrays a caller can write in place,
+   * because copying three vectors per node per frame is the allocation-free path an animation
+   * system wants. The cost is that this class cannot see the write, so a caller doing it says so.
+   */
+  markMoved(): void {
+    this.localDirty = true;
+    this.markSubtreeStale();
+  }
+
+  /**
+   * Put `child` under this node, taking it from wherever it was.
+   *
+   * **A cycle is refused here rather than discovered while walking**, because a walk that meets
+   * one does not throw: it recurses until the stack is gone, inside a frame loop, with the tab
+   * stopped and no useful trace. The check walks up from this node, which is the depth of the
+   * tree and not its size.
+   */
+  attachChild(child: SceneNode): void {
+    if (child === this) throw new Error('SceneNode: a node cannot be its own child (cycle)');
+    for (let at: SceneNode | null = this; at !== null; at = at.parent) {
+      if (at === child) throw new Error('SceneNode: that would make a cycle');
+    }
+    if (child.parent === this) return;
+    child.parent?.detachChild(child);
+    child.parent = this;
+    this.children.push(child);
+    child.markSubtreeStale();
+  }
+
+  detachChild(child: SceneNode): void {
+    const at = this.children.indexOf(child);
+    if (at < 0) return;
+    this.children.splice(at, 1);
+    child.parent = null;
+    child.markSubtreeStale();
+  }
+
+  /**
+   * Bring this node and everything under it up to date.
+   *
+   * **Only what moved.** A hierarchy that recomputes every world matrix every frame is slower
+   * than the callers it replaces, which already keep matrices they touch only when something
+   * moves. A clean subtree is skipped entirely, which is what makes the walk proportional to what
+   * changed rather than to the size of the world.
+   *
+   * **Its ancestors are brought up to date first, and that is a correctness fix rather than a
+   * courtesy.** Without it, updating a branch after moving something above it composes against a
+   * stale parent and puts the whole branch in the wrong place — silently, with no error and a
+   * plausible-looking matrix. Walking up costs the depth of the tree, not its size, and touches
+   * only this node's own ancestors: a sibling subtree is not recomputed for it.
+   */
+  updateWorld(): void {
+    this.refreshAncestors();
+    this.recompute(this.parent?.worldMatrix ?? null, false);
+  }
+
+  /** @internal Bring this node's ancestor chain up to date, root first. */
+  private refreshAncestors(): void {
+    const parent = this.parent;
+    if (parent === null) return;
+    parent.refreshAncestors();
+    parent.recomputeSelf(parent.parent?.worldMatrix ?? null);
+  }
+
+  /**
+   * @internal Recompute just this node's matrices, leaving its children alone.
+   *
+   * **`worldDirty` is left set on purpose.** This node's children have not been recomputed, and
+   * clearing it here would let a later `updateWorld` at the root decide the subtree is clean and
+   * skip them. `recompute` is what clears it, once the whole subtree really is current.
+   */
+  private recomputeSelf(parentWorld: Float32Array | null): void {
+    if (this.worldDirty) this.composeWorld(parentWorld);
+  }
+
+  /** @internal Recompute this subtree. `forced` is set when an ancestor recomputed. */
+  protected recompute(parentWorld: Float32Array | null, forced: boolean): void {
+    const changed = forced || this.worldDirty;
+    if (changed) {
+      this.composeWorld(parentWorld);
+      this.worldDirty = false;
+    }
+    for (const child of this.children) child.recompute(this.worldMatrix, changed);
+    if (changed || this.childBoundsMoved()) this.unionBounds();
+  }
+
+  /**
+   * @internal Whether any child's world bounds are newer than this node's own union.
+   *
+   * A child that moved without this node moving still grows the parent, and the walk above has
+   * already recomputed it by the time this asks.
+   */
+  private childBoundsMoved(): boolean {
+    for (const child of this.children) {
+      if (child.worldRevision > this.boundsRevision) return true;
+    }
+    return false;
+  }
+
+  /**
+   * @internal This node's geometry, placed, then grown to hold every child.
+   *
+   * Growing a sphere to contain another is the standard construction: if one already contains the
+   * other it is unchanged, and otherwise the new sphere spans from the far side of each. Written
+   * out rather than taken from a library because it runs per node per change and the three-line
+   * version allocates a vector.
+   */
+  private unionBounds(): void {
+    const local = this.localBounds;
+    let cx = this.worldMatrix[12] ?? 0;
+    let cy = this.worldMatrix[13] ?? 0;
+    let cz = this.worldMatrix[14] ?? 0;
+    let radius = 0;
+
+    if (local !== null) {
+      const lx = local.centre[0] ?? 0;
+      const ly = local.centre[1] ?? 0;
+      const lz = local.centre[2] ?? 0;
+      const m = this.worldMatrix;
+      cx = (m[0] ?? 0) * lx + (m[4] ?? 0) * ly + (m[8] ?? 0) * lz + (m[12] ?? 0);
+      cy = (m[1] ?? 0) * lx + (m[5] ?? 0) * ly + (m[9] ?? 0) * lz + (m[13] ?? 0);
+      cz = (m[2] ?? 0) * lx + (m[6] ?? 0) * ly + (m[10] ?? 0) * lz + (m[14] ?? 0);
+      /* The largest axis scale, for the reason `boundsVisible` gives at length. */
+      const sx = axisScale(m, 0);
+      const sy = axisScale(m, 4);
+      const sz = axisScale(m, 8);
+      radius = local.radius * Math.max(sx, sy, sz);
+    }
+
+    let started = local !== null;
+    for (const child of this.children) {
+      const other = child.worldBounds;
+      /* A child that is a point with nothing under it contributes nothing. */
+      if (other.radius === 0 && !child.hasGeometry && child.children.length === 0) continue;
+      const ox = other.centre[0] ?? 0;
+      const oy = other.centre[1] ?? 0;
+      const oz = other.centre[2] ?? 0;
+      if (!started) {
+        cx = ox;
+        cy = oy;
+        cz = oz;
+        radius = other.radius;
+        started = true;
+        continue;
+      }
+      const dx = ox - cx;
+      const dy = oy - cy;
+      const dz = oz - cz;
+      const distance = Math.sqrt(dx * dx + dy * dy + dz * dz);
+      if (distance + other.radius <= radius) continue;
+      if (distance + radius <= other.radius) {
+        cx = ox;
+        cy = oy;
+        cz = oz;
+        radius = other.radius;
+        continue;
+      }
+      const grown = (distance + radius + other.radius) * 0.5;
+      const along = distance > 1e-12 ? (grown - radius) / distance : 0;
+      cx += dx * along;
+      cy += dy * along;
+      cz += dz * along;
+      radius = grown;
+    }
+
+    this.worldBounds.centre[0] = cx;
+    this.worldBounds.centre[1] = cy;
+    this.worldBounds.centre[2] = cz;
+    this.worldBounds.radius = radius;
+    this.worldBounds.min[0] = cx - radius;
+    this.worldBounds.min[1] = cy - radius;
+    this.worldBounds.min[2] = cz - radius;
+    this.worldBounds.max[0] = cx + radius;
+    this.worldBounds.max[1] = cy + radius;
+    this.worldBounds.max[2] = cz + radius;
+    revisions += 1;
+    this.boundsRevision = revisions;
+  }
+
+  /** @internal The composition itself, in one place so the two callers cannot drift. */
+  private composeWorld(parentWorld: Float32Array | null): void {
+    if (this.localDirty) {
+      mat4.fromRotationTranslationScale(this.localMatrix, this.rotation, this.position, this.scale);
+      this.localDirty = false;
+    }
+    if (parentWorld === null) this.worldMatrix.set(this.localMatrix);
+    else mat4.multiply(this.worldMatrix, parentWorld, this.localMatrix);
+    revisions += 1;
+    this.worldRevision = revisions;
+  }
+
+  /** @internal Mark this node and everything under it as needing a new world matrix. */
+  protected markSubtreeStale(): void {
+    if (this.worldDirty) return;
+    this.worldDirty = true;
+    for (const child of this.children) child.markSubtreeStale();
+  }
+}
+
+/**
+ * The length of one of a matrix's three basis columns.
+ *
+ * `Math.sqrt` of a sum of squares rather than `Math.hypot`, which `scripts/determinism.mjs` refuses
+ * inside the simulation set: ECMAScript declines to specify `hypot`, so two engines may answer an
+ * ulp apart and a world matrix feeds a query. What `hypot` buys and this gives up is range — a sum
+ * of squares overflows above about 1e154 — and a basis column of a transform is near one.
+ */
+function axisScale(m: ArrayLike<number>, at: number): number {
+  const x = m[at] ?? 0;
+  const y = m[at + 1] ?? 0;
+  const z = m[at + 2] ?? 0;
+  return Math.sqrt(x * x + y * y + z * z);
+}

package/src/scene/visit.ts

@@ -0,0 +1,82 @@
+import { sphereInFrustum } from '../math/frustum.ts';
+import type { Frustum } from '../math/frustum.ts';
+import type { SceneNode } from './node.ts';
+
+/**
+ * What a traversal discarded, and what it handed over.
+ *
+ * **The pruned count is a measurement rather than a curiosity.** A hierarchy that prunes nothing
+ * is a linear scan with extra steps, and the only way to know which one a given world produces is
+ * to count. A caller printing this beside its frame time is what turns "the partition helps" from
+ * a belief into a number.
+ */
+export interface VisitResult {
+  /** Nodes with geometry handed to the visitor. */
+  visited: number;
+  /** Subtrees rejected whole, each standing for every node beneath it. */
+  pruned: number;
+  /** Nodes reached and tested, which is what `pruned` saved a multiple of. */
+  tested: number;
+}
+
+/**
+ * Walk a hierarchy, skipping any subtree the frustum rejects.
+ *
+ * **This is the spatial partition, and there is no second structure.** A node's world bounds
+ * enclose every descendant's, so rejecting a parent rejects everything under it — which is what a
+ * bounding-volume hierarchy is. The caller builds it by describing its world, and the pruning is
+ * free. `IMPROVEMENTS.md` recorded a trigger for building a BVH; this retires it rather than
+ * meeting it.
+ *
+ * **It does not draw.** `visit` is handed a node and the caller decides what verb that is worth,
+ * in whatever order it likes. The render graph work established that draw order carries meaning,
+ * and a traversal that issued draws would be deciding it.
+ *
+ * **A node with no geometry is not visited, but its children are.** A group is scaffolding, and
+ * handing one to a visitor gives a caller something with nothing to draw.
+ *
+ * Allocates nothing: `out` is the caller's, and the visitor is called rather than collected.
+ */
+export function visitVisible(
+  root: SceneNode,
+  frustum: Frustum,
+  visit: (node: SceneNode) => void,
+  out: VisitResult,
+): VisitResult {
+  out.visited = 0;
+  out.pruned = 0;
+  out.tested = 0;
+  walk(root, frustum, visit, out);
+  return out;
+}
+
+function walk(
+  node: SceneNode,
+  frustum: Frustum,
+  visit: (node: SceneNode) => void,
+  out: VisitResult,
+): void {
+  out.tested += 1;
+  const bounds = node.worldBounds;
+  if (
+    !sphereInFrustum(
+      frustum,
+      bounds.centre[0] ?? 0,
+      bounds.centre[1] ?? 0,
+      bounds.centre[2] ?? 0,
+      bounds.radius,
+    )
+  ) {
+    out.pruned += 1;
+    return;
+  }
+  if (node.hasGeometry) {
+    out.visited += 1;
+    visit(node);
+  }
+  for (const child of node.children) walk(child, frustum, visit, out);
+}
+
+export function createVisitResult(): VisitResult {
+  return { visited: 0, pruned: 0, tested: 0 };
+}

package/src/ui/clipMime.ts

@@ -0,0 +1,109 @@
+/**
+ * What a browser can record a clip in, and what that choice commits the file to.
+ *
+ * Split out of `frameRecorder.ts`, and the reason is the caller rather than the code.
+ * A game asks `supportedClipMimeType` at boot to decide whether an export button
+ * should exist at all, which is a question about the *browser* — but asking it used to
+ * drag `FrameRecorder` and `offerClip` into the same bundle chunk, and those are only
+ * wanted once somebody actually exports something. A probe with no imports of its own
+ * can be read from anywhere for nothing.
+ */
+
+/**
+ * Container and codec preferences, best first.
+ *
+ * **The first two ask for AAC by name, and that is the point of them.** The list used
+ * to open with `video/mp4;codecs=avc1`, which names the video codec and leaves the
+ * audio to the browser — so a recording that *could* have been AAC was only AAC if the
+ * browser felt like it, and there was no way to find out afterwards which it had been.
+ * Asking explicitly makes the answer a fact `isTypeSupported` reports before a single
+ * frame is recorded, and `describeClipMime` reads it back off the accepted string.
+ *
+ * This matters more than it looks, because the audio codec is what decides whether the
+ * file can be posted. MP4 carrying Opus is legal ISO and Android's MediaCodec cannot
+ * decode it, so the TikTok app refuses it outright.
+ *
+ * `avc1` unqualified follows the profile-qualified form because a build can accept the
+ * general string and reject a specific profile, and either is better than falling to
+ * WebM. WebM stays last: it is a real file that real desktop uploaders take, and it is
+ * the only thing some browsers can produce.
+ */
+const MIME_CANDIDATES = [
+  'video/mp4;codecs="avc1.640028,mp4a.40.2"',
+  'video/mp4;codecs="avc1,mp4a.40.2"',
+  /*
+   * Opus named on purpose, and *above* the bare `avc1` that would otherwise match it.
+   *
+   * It looks like asking for the worse file, and it is not: on a build with no AAC
+   * encoder the browser picks Opus for `codecs=avc1` anyway — verified, it is what every
+   * `MediaRecorder` clip in this project has carried — so the choice is not between AAC
+   * and Opus here, it is between an Opus file that says so and an Opus file that does
+   * not. Naming it turns a vague "could not confirm AAC" into the accurate warning, with
+   * the remux to go with it. Anywhere AAC exists, the two candidates above match first.
+   */
+  'video/mp4;codecs="avc1,opus"',
+  'video/mp4;codecs=avc1',
+  'video/webm;codecs=vp9,opus',
+  'video/webm;codecs=vp8,opus',
+  'video/webm',
+] as const;
+
+/** What a recording MIME type commits the file to. See `describeClipMime`. */
+export interface ClipMimeDescription {
+  readonly container: 'mp4' | 'webm' | 'unknown';
+  /**
+   * `unspecified` is not a synonym for "fine". It means the string named no audio
+   * codec, so the browser chose one and the file does not say which — the state this
+   * type exists to stop a caller from having to guess about.
+   */
+  readonly audio: 'aac' | 'opus' | 'unspecified';
+  /**
+   * True only for MP4 carrying AAC: the one combination every share target on a phone
+   * ingests without transcoding.
+   *
+   * Deliberately false for `unspecified`, which is a claim about knowledge rather than
+   * about the file. A caller that reports "this may not upload" on a file that turns
+   * out fine has been slightly annoying; one that stays quiet on a file that dies at
+   * an upload screen has wasted a clip nobody can re-record.
+   */
+  readonly shareable: boolean;
+}
+
+/**
+ * Read back what a recording MIME type promises, without recording anything.
+ *
+ * Pure, and string-parsing rather than clever: the accepted candidate above is the only
+ * evidence available about a `MediaRecorder` file's audio codec, since the blob's `type`
+ * is just the string it was handed.
+ */
+export function describeClipMime(mime: string): ClipMimeDescription {
+  const lower = mime.toLowerCase();
+  const container = lower.startsWith('video/mp4')
+    ? 'mp4'
+    : lower.startsWith('video/webm')
+      ? 'webm'
+      : 'unknown';
+  // `mp4a.40.2` is AAC-LC; `mp4a.40.5`/`.29` are the HE variants, all of them AAC as
+  // far as anything receiving the file is concerned.
+  const audio = lower.includes('mp4a.40') ? 'aac' : lower.includes('opus') ? 'opus' : 'unspecified';
+  return { container, audio, shareable: container === 'mp4' && audio === 'aac' };
+}
+
+/**
+ * Whether this browser can record at all, and in what.
+ *
+ * MP4 first where it exists, because it is the format every social app accepts
+ * without transcoding — a WebM upload that silently fails on a phone is worse
+ * than no export button.
+ */
+export function supportedClipMimeType(): string | null {
+  if (typeof MediaRecorder === 'undefined') return null;
+  for (const mime of MIME_CANDIDATES) {
+    try {
+      if (MediaRecorder.isTypeSupported(mime)) return mime;
+    } catch {
+      // Some engines throw rather than returning false. Same answer either way.
+    }
+  }
+  return null;
+}