@driftengine/core 3.61.0

package/dist/scene/node.d.ts

@@ -0,0 +1,128 @@
+import type { Bounds } from '../math/bounds.ts';
+export declare class SceneNode {
+    /** Local translation. Written in place; call `markMoved` if you write it directly. */
+    readonly position: Float32Array<ArrayBuffer>;
+    /**
+     * 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: Float32Array<ArrayBuffer>;
+    readonly scale: Float32Array<ArrayBuffer>;
+    readonly localMatrix: Float32Array<ArrayBuffer>;
+    readonly worldMatrix: Float32Array<ArrayBuffer>;
+    parent: SceneNode | null;
+    readonly children: SceneNode[];
+    /** What `worldMatrix` was last recomputed at. See `revisions`. */
+    worldRevision: number;
+    /**
+     * 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;
+    /**
+     * 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;
+    /** This node's own transform has changed and `localMatrix` is stale. */
+    private localDirty;
+    /** This node or something above it has moved, so `worldMatrix` is stale. */
+    private worldDirty;
+    /** What `worldBounds` was last unioned at, so a child moving alone is still noticed. */
+    private boundsRevision;
+    constructor();
+    setPosition(x: number, y: number, z: number): void;
+    setScale(x: number, y: number, z: number): void;
+    /**
+     * 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;
+    /** Whether this node has geometry of its own, as opposed to only grouping others. */
+    get hasGeometry(): boolean;
+    /** 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    detachChild(child: SceneNode): void;
+    /**
+     * 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;
+    /** @internal Bring this node's ancestor chain up to date, root first. */
+    private refreshAncestors;
+    /**
+     * @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;
+    /** @internal Recompute this subtree. `forced` is set when an ancestor recomputed. */
+    protected recompute(parentWorld: Float32Array | null, forced: boolean): void;
+    /**
+     * @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;
+    /**
+     * @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;
+    /** @internal The composition itself, in one place so the two callers cannot drift. */
+    private composeWorld;
+    /** @internal Mark this node and everything under it as needing a new world matrix. */
+    protected markSubtreeStale(): void;
+}

package/dist/scene/node.js

@@ -0,0 +1,319 @@
+import { mat4, quat } from 'gl-matrix';
+import { createBounds } from '../math/bounds.js';
+/**
+ * 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. */
+    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.
+     */
+    rotation = new Float32Array([0, 0, 0, 1]);
+    scale = new Float32Array([1, 1, 1]);
+    localMatrix = new Float32Array(16);
+    worldMatrix = new Float32Array(16);
+    parent = null;
+    children = [];
+    /** 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.
+     */
+    localBounds = 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.
+     */
+    worldBounds = createBounds();
+    /** This node's own transform has changed and `localMatrix` is stale. */
+    localDirty = true;
+    /** This node or something above it has moved, so `worldMatrix` is stale. */
+    worldDirty = true;
+    /** What `worldBounds` was last unioned at, so a child moving alone is still noticed. */
+    boundsRevision = -1;
+    constructor() {
+        mat4.identity(this.localMatrix);
+        mat4.identity(this.worldMatrix);
+    }
+    setPosition(x, y, z) {
+        this.position[0] = x;
+        this.position[1] = y;
+        this.position[2] = z;
+        this.markMoved();
+    }
+    setScale(x, y, z) {
+        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) {
+        this.localBounds = bounds;
+        this.markMoved();
+    }
+    /** Whether this node has geometry of its own, as opposed to only grouping others. */
+    get hasGeometry() {
+        return this.localBounds !== null;
+    }
+    /** Set the rotation from an axis and an angle in radians. The axis need not be normalised. */
+    setRotationAxisAngle(x, y, z, radians) {
+        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() {
+        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) {
+        if (child === this)
+            throw new Error('SceneNode: a node cannot be its own child (cycle)');
+        for (let at = 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) {
+        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() {
+        this.refreshAncestors();
+        this.recompute(this.parent?.worldMatrix ?? null, false);
+    }
+    /** @internal Bring this node's ancestor chain up to date, root first. */
+    refreshAncestors() {
+        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.
+     */
+    recomputeSelf(parentWorld) {
+        if (this.worldDirty)
+            this.composeWorld(parentWorld);
+    }
+    /** @internal Recompute this subtree. `forced` is set when an ancestor recomputed. */
+    recompute(parentWorld, forced) {
+        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.
+     */
+    childBoundsMoved() {
+        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.
+     */
+    unionBounds() {
+        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. */
+    composeWorld(parentWorld) {
+        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. */
+    markSubtreeStale() {
+        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, at) {
+    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/dist/scene/visit.d.ts

@@ -0,0 +1,38 @@
+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 declare function visitVisible(root: SceneNode, frustum: Frustum, visit: (node: SceneNode) => void, out: VisitResult): VisitResult;
+export declare function createVisitResult(): VisitResult;

package/dist/scene/visit.js

@@ -0,0 +1,43 @@
+import { sphereInFrustum } from '../math/frustum.js';
+/**
+ * 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, frustum, visit, out) {
+    out.visited = 0;
+    out.pruned = 0;
+    out.tested = 0;
+    walk(root, frustum, visit, out);
+    return out;
+}
+function walk(node, frustum, visit, out) {
+    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() {
+    return { visited: 0, pruned: 0, tested: 0 };
+}

package/dist/ui/clipMime.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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.
+ */
+/** 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 declare function describeClipMime(mime: string): ClipMimeDescription;
+/**
+ * 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 declare function supportedClipMimeType(): string | null;

package/dist/ui/clipMime.js

@@ -0,0 +1,88 @@
+/**
+ * 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',
+];
+/**
+ * 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) {
+    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() {
+    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;
+}