@driftengine/capture 4.0.0

package/LICENSE

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

package/NOTICE

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

package/README.md

@@ -0,0 +1,68 @@
+# `@driftengine/capture`
+
+A video to a playable scene, on the player's own device — no service, no account, and a runtime
+that never fetches.
+
+**66,373 bytes gzipped**, measured by `scripts/size-gate.test.mjs` against
+`scripts/fixtures/size/capture-only.ts`. Optional: nothing in `@driftengine/core` imports it.
+
+## What is here so far
+
+The models a capture runs, each written as a **definition**: a function of a model's weights that
+`@driftengine/texture`'s `graphFromWeights` builds into a graph the engine's one neural runtime runs,
+on the CPU as a reference or on the device through `@driftengine/core`'s `createGraphRunner`.
+
+| Export                                                                                                                                             | What it is                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `depthAnything3(config, views, h, w)`                                                                                                              | Depth Anything 3 at `views` images of `h × w` pixels: logits per view and a pose encoding for all of them                                                                                                                                                                                                                                                                                                                                                  |
+| `DEPTH_ANYTHING_3.small`, `.base`                                                                                                                  | The two accepted sizes, from each checkpoint's configuration at its pinned revision                                                                                                                                                                                                                                                                                                                                                                        |
+| `depthAnything2(config, h, w)`, `DEPTH_ANYTHING_2_SMALL`                                                                                           | Depth Anything V2 Small, the lighter fallback: relative inverse depth from one view, in Transformers' layout                                                                                                                                                                                                                                                                                                                                               |
+| `decodeDepth`, `decodeCamera`                                                                                                                      | The logits as depth and a confidence of at least one; a pose encoding as world-to-camera and a pinhole                                                                                                                                                                                                                                                                                                                                                     |
+| `mobileSamEncoder(config)`, `mobileSamDecoder(config, tokens, refine?)`, `MOBILE_SAM`                                                              | MobileSAM in two graphs: an image to its embedding once, and a prompt's tokens — and the last mask, to refine — to four masks and their predicted quality                                                                                                                                                                                                                                                                                                  |
+| `samPromptTokens`, `samTokenCount`, `samMasksToImage`, `stabilityScore`                                                                            | A prompt of points and a box as the decoder's tokens; the masks brought to the original image; the upstream's stability score                                                                                                                                                                                                                                                                                                                              |
+| `sam21Encoder(config)`, `sam21Decoder(config, tokens, options)`, `Sam21Tracker`, `SAM_21_TINY`                                                     | SAM 2.1: masks from a point or a box on an image, and objects tracked through a video by a memory of the frames before them, the loop on the host and its networks as graphs                                                                                                                                                                                                                                                                               |
+| `owlv2Image(config)`, `owlv2Text(config, queries)`, `owlv2Logits`, `owlv2Detections`, `OWLV2_BASE`                                                 | OWLv2: an image's patches once, a set of text queries once, joined on the host into a logit a patch and query and those into boxes above a threshold                                                                                                                                                                                                                                                                                                       |
+| `clipTokenizer(merges)`, `owlv2Tokens`                                                                                                             | CLIP's byte-level tokenizer from the merges a converted file carries, and queries padded as the text graph takes them                                                                                                                                                                                                                                                                                                                                      |
+| `eachFrame(source, visit)`, `selectFrames(source, { budget, every? })`, `browserFrameSource(clip)`                                                 | A clip through the host's own `FrameSource`, read one frame at a time; the frames a capture keeps, spaced by equal motion; a browser's video element behind one                                                                                                                                                                                                                                                                                            |
+| `prepareDepthFrame`, `prepareSamFrame`, `prepareSam2Frame`, `prepareOwlv2Frame`                                                                    | A frame as each model's own upstream prepares it, down to the resize each library uses                                                                                                                                                                                                                                                                                                                                                                     |
+| `createDepthEstimator(config, weights, run)`                                                                                                       | A clip's frames to depth, confidence and a camera a view, a graph kept per prepared size                                                                                                                                                                                                                                                                                                                                                                   |
+| `svd3`, `svdN`, `symmetricEigen`, `cholesky`, `levenbergMarquardt`, `schurSolve`                                                                   | The decompositions structure from motion needs, in double precision, each held to its own identity                                                                                                                                                                                                                                                                                                                                                         |
+| `detectFeatures`, `describeFeatures`, `matchFeatures`                                                                                              | Corners, a description of each turned by its own orientation, and the matches between two frames — mutual, and unambiguous from both sides                                                                                                                                                                                                                                                                                                                 |
+| `relativePose(a, b, count, intrinsics, random, out)`, `triangulate(...)`                                                                           | The pose between two views by seeded RANSAC over both models, and the points behind the matches; **a pair with no parallax is reported as a turn** rather than fitted with a translation                                                                                                                                                                                                                                                                   |
+| `renderTestScene(scene, camera, out, depth?)`, `lookAt`                                                                                            | Analytic scenes ray cast on the CPU, with the true depth beside the colour: the fixture every later stage is held to                                                                                                                                                                                                                                                                                                                                       |
+| `estimatePoses(frames, options, out)`                                                                                                              | The clip's camera path: tracks, a two-view or depth-model start, every frame placed by what it sees, and a bundle adjustment — with per-pose confidence, **`parallax: false` where the clip only turned**, and a scale that is metric only when a length was given                                                                                                                                                                                         |
+| `optimiseGaussians(targets, poses, options)`                                                                                                       | A clip's frames and its camera path fitted into Gaussians, out as `@driftengine/splats`' own `SplatSource`: Adam over six families, scale as a logarithm and opacity as a logit, densified by which Gaussians the frames pull on and pruned by what has faded, with a degree-1 band on request                                                                                                                                                             |
+| `rasteriseGaussians(set, camera, out)`, `projectGaussian`, `accumulateGradients`, `imageLoss`                                                      | The reference rasteriser the fit descends: the projection `@driftengine/splats`' shader performs, low-pass included, and every analytic gradient behind it — checked against a central difference of itself                                                                                                                                                                                                                                                |
+| `splatColour`, `sh1Basis`, `SH_C1`                                                                                                                 | The degree-1 band, evaluated exactly as that shader evaluates it, so a capture fitted here is shaded there the same way                                                                                                                                                                                                                                                                                                                                    |
+| `structuralSimilarity(a, b, width, height)`                                                                                                        | How alike two pictures are, structure included — what a fit is judged by, where a squared difference is only what it descends                                                                                                                                                                                                                                                                                                                              |
+| `renderDepth(set, camera, depth, coverage)`                                                                                                        | How far away a cloud is, a pixel at a time: each splat's own depth weighted by how much of the pixel it lit, with the coverage beside it — because a depth averaged out of a tenth of a pixel's light is not a measurement                                                                                                                                                                                                                                 |
+| `createVolume(dims, origin, spacing)`, `fuseDepth(views, volume)`                                                                                  | Many views averaged into one truncated signed distance, weighted by how squarely each saw the surface. Space in front of a surface is carved out, space behind it is left alone, and a surface one view saw is kept at the weight one view is worth                                                                                                                                                                                                        |
+| `marchVolume(volume, options?)`                                                                                                                    | That volume's crossing as a mesh, by tetrahedra rather than cubes so it is closed by construction, **facing outwards** — and open where the capture never looked, rather than capped with a surface nobody measured                                                                                                                                                                                                                                        |
+| `decimate(mesh, budget, options?)`                                                                                                                 | The mesh brought to a triangle budget by quadric-error collapse: a wall flattens, a corner keeps its detail, the border of an open capture is held, and a collapse that would turn a face inside out is refused                                                                                                                                                                                                                                            |
+| `collisionMesh(mesh, options?)`                                                                                                                    | The drawn mesh cleaned for collision: triangles with no area taken out, because a plane needs a normal, and the vertices nothing uses any more taken with them. What comes back is what `meshShape` takes                                                                                                                                                                                                                                                  |
+| `propHulls(mesh, options?)`                                                                                                                        | A prop as convex hulls, asked for inside `COLL`'s own caps rather than checked against them after the expensive part — a room is a mesh body and a prop is hulls, and the difference is that one can be thrown                                                                                                                                                                                                                                             |
+| `delight(views, mesh, options, out)`                                                                                                               | A surface's material, separated from the light it was photographed under: what stays the same across views is the material, what moves is the light, and an intensity jump the colour does not follow is a shadow. **Every vertex carries a confidence**, and the module states plainly what that confidence grades and what it does not — on the synthetic scene a cast shadow that darkens a floor 4.8× in the photographs comes back 2.2× in the albedo |
+| `renderLit(scene, camera, light, out)`, `nearestHit`                                                                                               | The lit fixture those measurements are made against: a triangle mesh, one directional light, a hard shadow ray and a normalised specular lobe — enough to pose the question and no more                                                                                                                                                                                                                                                                    |
+| `segmentGeometry(mesh, options?)`                                                                                                                  | The mesh cut into surfaces with no model loaded at all: runs of triangles that share an edge and a plane, largest first. A floor, its walls and the top of a table are findable without knowing what any of them _is_, and that is most of what a scene needs                                                                                                                                                                                              |
+| `liftMasks(views, mesh, labels)`, `promptGrid(width, height, across, down, random)`                                                                | A segmentation model's masks voted onto the mesh across every view that saw a triangle, and the seeded lattice it is prompted on — a triangle no view claimed is left unassigned rather than given to its neighbour                                                                                                                                                                                                                                        |
+| `labelMasks(view, detections, queries, overlap?)`                                                                                                  | A detector's boxes put names to a segmenter's mask indices, by how far each box and mask agree — the mask's own pixels against the box, so a box drawn around a room does not name every cushion in it. A mask that agrees with nothing keeps no name, and no name is scenery                                                                                                                                                                              |
+| `proposeEntities(regions, options?)`, `SCENERY_COMPONENTS`, `WALKABLE_COMPONENTS`, `MOVABLE_COMPONENTS`                                            | Each region as a _proposal_, and the word is load-bearing: **a region nobody labelled becomes scenery** — drawn, solid, and doing nothing. The largest surface a character could stand on gets a navigation surface; a named region small enough to shift is offered as movable                                                                                                                                                                            |
+| `captureFile(scene)`, `proposalScene`, `readProposals`, `PROPOSAL_COMPONENT`                                                                       | Every stage as one `.drft`: the mesh, its materials and decode program, the cloud, a prop's hulls, the way across the scene and the proposals. **The proposals travel under a component this package declares**, not under a consumer's `transform`, whose field ids belong to that consumer — a capture proposes in its own words and an editor decides what a scene ends up holding                                                                      |
+| `miniatureCheckpoint`, `miniatureCheckpoint2`, `miniatureImages`, `miniatureSamCheckpoint`, `miniatureSam21Checkpoint`, `miniatureOwlv2Checkpoint` | Seeded miniatures of each layout — every tensor name and shape — for tests and for checking a port of yours                                                                                                                                                                                                                                                                                                                                                |
+
+**A definition runs twice.** Once over a checkpoint, when `tools/capture-weights/` converts it, and
+again over the converted file whenever a clip needs the graph at a new size: every device kernel
+bakes its shapes, and a clip's aspect ratio decides the patch grid. Every weight the source holds is
+read or set aside by name, so a forgotten bias is refused rather than run.
+
+**Each model answers as its upstream's own code does.** The tests hold each definition to numbers
+the upstream's modules wrote for its miniature at the manifest's pinned revision — Depth Anything 3's
+own repository, Transformers for V2, SAM 2.1 and OWLv2, and MobileSAM's own repository — within a few parts in a
+million;
+`tools/capture-weights/reference/` is the hand-run oracle that produced them.
+
+## Weights
+
+None ship with this package. `tools/capture-weights/manifest.json` pins each accepted model to a
+commit and a SHA-256, and `docs/SHIPPING.md` §12 says what a game ships with one: the converted file,
+the model's licence, and its attribution, which `NOTICE` carries too.

package/dist/browserFrames.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A clip in a browser as a `FrameSource`: a video element decoded into a canvas, a frame at a time.
+ *
+ * **A declared browser module** — a native host writes its own source over its own decoder, which is
+ * the whole point of the seam. Nothing else in this package touches a DOM.
+ *
+ * **Why a video element rather than WebCodecs.** `VideoDecoder` takes encoded chunks and a browser
+ * ships no demuxer to make them from an MP4, so a WebCodecs source means a demuxing dependency in a
+ * package whose bar for one is high. A video element demuxes, decodes and seeks with nothing added,
+ * and `drawImage` into a 2D canvas is how its frame becomes bytes. **What it gives up**: a frame is
+ * addressed by time rather than by its place in the stream — the middle of frame `index` at the
+ * clip's rate — so a clip of variable frame rate answers the frame covering that instant rather
+ * than the `index`-th one. What would make that wrong is a capture that needs a particular frame
+ * rather than a moment; nothing here does, since frames are chosen by motion.
+ *
+ * **The rate is measured, not assumed**, from the first frames the decoder presents, and falls back
+ * to the caller's `frameRate` where `requestVideoFrameCallback` is absent.
+ */
+import type { FrameSource } from './frames.ts';
+/** A browser's clip, and how to let it go. */
+export interface BrowserClip extends FrameSource {
+    /** Releases the element and the object URL; the source answers nothing afterwards. */
+    close(): void;
+}
+/**
+ * The clip's frames, addressed at the clip's rate. `frameRate` is the fallback where the browser
+ * cannot say what the rate is.
+ */
+export declare function browserFrameSource(clip: Blob, options?: {
+    readonly frameRate?: number;
+}): Promise<BrowserClip>;

package/dist/browserFrames.js

@@ -0,0 +1,105 @@
+const once = (video, event) => new Promise((resolve, reject) => {
+    const done = () => {
+        video.removeEventListener(event, done);
+        video.removeEventListener('error', failed);
+        resolve();
+    };
+    const failed = () => {
+        video.removeEventListener(event, done);
+        video.removeEventListener('error', failed);
+        reject(new Error(`the clip could not be read: ${video.error?.message ?? 'no reason given'}`));
+    };
+    video.addEventListener(event, done);
+    video.addEventListener('error', failed);
+});
+/** The rate the decoder presents frames at, from two it presents, or null where it cannot say. */
+async function measuredRate(video) {
+    if (typeof video.requestVideoFrameCallback !== 'function')
+        return null;
+    const times = [];
+    await new Promise((resolve) => {
+        const take = (_now, metadata) => {
+            times.push(metadata.mediaTime);
+            if (times.length >= 3)
+                resolve();
+            else
+                video.requestVideoFrameCallback?.(take);
+        };
+        video.requestVideoFrameCallback?.(take);
+        void video.play().catch(() => resolve());
+        setTimeout(resolve, 2000);
+    });
+    video.pause();
+    const steps = [];
+    for (let i = 1; i < times.length; i += 1)
+        steps.push(times[i] - times[i - 1]);
+    const shortest = Math.min(...steps.filter((step) => step > 0));
+    return Number.isFinite(shortest) && shortest > 0 ? 1 / shortest : null;
+}
+/**
+ * The clip's frames, addressed at the clip's rate. `frameRate` is the fallback where the browser
+ * cannot say what the rate is.
+ */
+export async function browserFrameSource(clip, options = {}) {
+    // platform: browser default — this module is the browser's own `FrameSource`.
+    const url = URL.createObjectURL(clip);
+    const video = document.createElement('video');
+    video.preload = 'auto';
+    video.muted = true;
+    video.playsInline = true;
+    video.src = url;
+    await once(video, 'loadedmetadata');
+    /*
+     * **A container that parses is not a track that decodes**, and the difference is silent.
+     *
+     * Chrome on Linux plays no HEVC, which is what every recent phone records by default. The file
+     * loads, `loadedmetadata` fires, `duration` comes back correct to the millisecond — and
+     * `videoWidth` is zero, because nothing decoded. Left alone, the first frame draws a zero-wide
+     * image into a zero-wide canvas and dies inside `getImageData` with "the source width is 0",
+     * which names neither the clip nor the codec and sends a reader into the canvas code.
+     *
+     * So it is refused here, by name, with the duration as evidence that the file itself is fine.
+     * **What this cannot do is say which codec it was**: the element reports no track it could not
+     * decode, so the message names the one that always works rather than guessing at the one that
+     * did not.
+     */
+    if (video.videoWidth === 0 || video.videoHeight === 0) {
+        const seconds = Number.isFinite(video.duration) ? video.duration.toFixed(2) : 'an unknown';
+        throw new Error(`this browser cannot decode the clip's video track: it read ${seconds} s of container and ` +
+            'no picture. A codec this browser does not have is the usual cause — HEVC on a build ' +
+            'without it, which is what most phones record. Convert the clip to H.264 and try again.');
+    }
+    const rate = (await measuredRate(video)) ?? options.frameRate ?? 30;
+    const width = video.videoWidth;
+    const height = video.videoHeight;
+    const count = Math.max(1, Math.floor(video.duration * rate));
+    const canvas = new OffscreenCanvas(width, height);
+    const context = canvas.getContext('2d', { willReadFrequently: true });
+    if (context === null)
+        throw new Error('a clip needs a 2D canvas to become pixels');
+    let open = true;
+    return {
+        frameCount: () => (open ? count : 0),
+        async frameAt(index, out) {
+            if (!open)
+                throw new Error('the clip is closed');
+            if (out.length >= width * height * 4) {
+                /* The middle of the frame, so rounding cannot land on the boundary either side. */
+                const at = Math.min((index + 0.5) / rate, Math.max(0, video.duration - 1 / rate));
+                if (Math.abs(video.currentTime - at) > 1e-6) {
+                    video.currentTime = at;
+                    await once(video, 'seeked');
+                }
+                context.drawImage(video, 0, 0, width, height);
+                out.set(context.getImageData(0, 0, width, height).data);
+            }
+            return { width, height };
+        },
+        close() {
+            open = false;
+            video.removeAttribute('src');
+            video.load();
+            URL.revokeObjectURL(url);
+        },
+    };
+}

package/dist/collide.d.ts

@@ -0,0 +1,59 @@
+/**
+ * A captured mesh as something to stand on and to put in a file.
+ *
+ * **The mesh a capture draws and the mesh it collides against are the same triangles and not the
+ * same array.** What comes out of `marchVolume` and `decimate` is built for a picture: it carries
+ * normals and colours a collision test never reads, and it carries the occasional triangle with no
+ * area, which is harmless in a render and is not harmless in a contact — a plane needs a normal,
+ * and a triangle with no area has none. So the collision mesh is the drawn one with the arealess
+ * triangles taken out and the vertices nothing uses any more taken with them.
+ *
+ * **A room is a static mesh body and a prop is a set of hulls, and the difference is not size.** A
+ * mesh body is exact and cannot move: every triangle is tested as it stands, which is what a floor
+ * and a wall want. A convex decomposition is approximate and can be thrown: a hull has a centre of
+ * mass, an inertia and a cheap support function, which is what a crate wants. Giving a room hulls
+ * would round off its corners; giving a crate a mesh body would leave it unable to be picked up.
+ *
+ * **The container's caps are the decomposition's brief.** `COLL` holds at most thirty-two hulls of
+ * at most sixty-four points, so a decomposition that ignored them would produce a prop that cannot
+ * be written — found at the writer, after the expensive part. It is asked for inside them instead.
+ */
+import { type MeshData } from '@driftengine/drft';
+import { type DecomposeOptions } from '@driftengine/physics';
+/** A mesh as `meshShape` takes it, and what had to go for it to be one. */
+export interface CollisionSource {
+    readonly positions: Float32Array;
+    readonly indices: Uint32Array;
+    /** Triangles dropped for having no area to have a plane from. */
+    readonly dropped: number;
+}
+export interface CollisionOptions {
+    /**
+     * The smallest triangle kept, in square metres.
+     *
+     * **Not zero**, because a triangle of a square micrometre has a plane in the arithmetic and none
+     * in any useful sense: its normal is the direction of its own rounding error, and a contact
+     * against it points somewhere arbitrary. A square millimetre is far below anything a capture
+     * resolves and far above where a cross product stops meaning anything.
+     */
+    readonly minimumArea?: number;
+}
+/** `mesh`'s triangles, less the ones with no area, renumbered onto the vertices that remain. */
+export declare function collisionMesh(mesh: MeshData, options?: CollisionOptions): CollisionSource;
+/** A prop's hulls, and how much empty space they added. */
+export interface PropHulls {
+    /** xyz-packed points per hull, as `COLL` writes them and `hullShape` takes them. */
+    readonly hulls: readonly Float32Array[];
+    /** `(hullVolume − sourceVolume) / sourceVolume`, from the decomposition itself. */
+    readonly bloat: number;
+}
+/**
+ * `mesh` decomposed into convex hulls the container can hold.
+ *
+ * **Asked for inside the caps rather than checked against them afterwards.** A decomposition is the
+ * expensive part of baking a prop, and one that comes back with thirty-three hulls is one that has
+ * to be thrown away and asked for again — so the cap is what it is asked for. A hull that still
+ * arrives with more points than a record can hold is refused by name, because silently dropping its
+ * points changes the shape a game collides against without telling anybody.
+ */
+export declare function propHulls(mesh: MeshData | CollisionSource, options?: DecomposeOptions): PropHulls;

package/dist/collide.js

@@ -0,0 +1,92 @@
+/**
+ * A captured mesh as something to stand on and to put in a file.
+ *
+ * **The mesh a capture draws and the mesh it collides against are the same triangles and not the
+ * same array.** What comes out of `marchVolume` and `decimate` is built for a picture: it carries
+ * normals and colours a collision test never reads, and it carries the occasional triangle with no
+ * area, which is harmless in a render and is not harmless in a contact — a plane needs a normal,
+ * and a triangle with no area has none. So the collision mesh is the drawn one with the arealess
+ * triangles taken out and the vertices nothing uses any more taken with them.
+ *
+ * **A room is a static mesh body and a prop is a set of hulls, and the difference is not size.** A
+ * mesh body is exact and cannot move: every triangle is tested as it stands, which is what a floor
+ * and a wall want. A convex decomposition is approximate and can be thrown: a hull has a centre of
+ * mass, an inertia and a cheap support function, which is what a crate wants. Giving a room hulls
+ * would round off its corners; giving a crate a mesh body would leave it unable to be picked up.
+ *
+ * **The container's caps are the decomposition's brief.** `COLL` holds at most thirty-two hulls of
+ * at most sixty-four points, so a decomposition that ignored them would produce a prop that cannot
+ * be written — found at the writer, after the expensive part. It is asked for inside them instead.
+ */
+import { MAX_COLLIDER_HULLS } from '@driftengine/drft';
+import { decomposeConvex } from '@driftengine/physics';
+const DEFAULT_MINIMUM_AREA = 1e-6;
+/** `mesh`'s triangles, less the ones with no area, renumbered onto the vertices that remain. */
+export function collisionMesh(mesh, options = {}) {
+    const minimumArea = options.minimumArea ?? DEFAULT_MINIMUM_AREA;
+    const triangles = mesh.indices.length / 3;
+    const renumbered = new Map();
+    const positions = [];
+    const indices = [];
+    let dropped = 0;
+    for (let face = 0; face < triangles; face += 1) {
+        const a = mesh.indices[face * 3];
+        const b = mesh.indices[face * 3 + 1];
+        const c = mesh.indices[face * 3 + 2];
+        if (areaOf(mesh.positions, a, b, c) < minimumArea) {
+            dropped += 1;
+            continue;
+        }
+        for (const vertex of [a, b, c]) {
+            let at = renumbered.get(vertex);
+            if (at === undefined) {
+                at = positions.length / 3;
+                renumbered.set(vertex, at);
+                for (let k = 0; k < 3; k += 1)
+                    positions.push(mesh.positions[vertex * 3 + k]);
+            }
+            indices.push(at);
+        }
+    }
+    return {
+        positions: Float32Array.from(positions),
+        indices: Uint32Array.from(indices),
+        dropped,
+    };
+}
+/** Twice the area of a triangle, halved: the length of the cross product of two of its edges. */
+function areaOf(positions, a, b, c) {
+    const ux = positions[b * 3] - positions[a * 3];
+    const uy = positions[b * 3 + 1] - positions[a * 3 + 1];
+    const uz = positions[b * 3 + 2] - positions[a * 3 + 2];
+    const vx = positions[c * 3] - positions[a * 3];
+    const vy = positions[c * 3 + 1] - positions[a * 3 + 1];
+    const vz = positions[c * 3 + 2] - positions[a * 3 + 2];
+    const nx = uy * vz - uz * vy;
+    const ny = uz * vx - ux * vz;
+    const nz = ux * vy - uy * vx;
+    return Math.sqrt(nx * nx + ny * ny + nz * nz) / 2;
+}
+/**
+ * `mesh` decomposed into convex hulls the container can hold.
+ *
+ * **Asked for inside the caps rather than checked against them afterwards.** A decomposition is the
+ * expensive part of baking a prop, and one that comes back with thirty-three hulls is one that has
+ * to be thrown away and asked for again — so the cap is what it is asked for. A hull that still
+ * arrives with more points than a record can hold is refused by name, because silently dropping its
+ * points changes the shape a game collides against without telling anybody.
+ */
+export function propHulls(mesh, options = {}) {
+    const decomposition = decomposeConvex(mesh.positions, mesh.indices, {
+        ...options,
+        maxHulls: Math.min(options.maxHulls ?? MAX_COLLIDER_HULLS, MAX_COLLIDER_HULLS),
+    });
+    /*
+     * **The points need no cap of their own**, and it is worth saying why rather than checking for
+     * something that cannot happen. A part carries at most one point per support direction, which is
+     * fifty, and a collider record holds sixty-four — so the decomposition is already inside the
+     * container by construction. `collide.test.ts` asserts that relationship rather than this file
+     * testing each hull against a limit it can never reach.
+     */
+    return { hulls: decomposition.parts.map((part) => part.points), bloat: decomposition.bloat };
+}