@msb235/blits-rapier 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+This package follows [semver](https://semver.org). Below 1.0.0, a breaking change bumps the minor
+version and everything else the patch. The release workflow refuses a `rapier-v*` tag with no
+section here.
+
+## 0.2.0
+
+### Breaking
+
+- `@msb235/blits` is a peer at `^0.17.0`, where it was `^0.16.1`. Built and tested against engine
+  0.17.0; nothing here uses what that release changed.
+
+### Added
+
+- `physics` takes `weight`, a number or a signal, for every body's simulated voice. A signal hands
+  bodies between physics and authored poses with nothing written from the frame loop. Fading
+  `simulated` out ended it for good, so a body could not be handed back.
+
+### Fixed
+
+- A body handed back to physics starts where it was shown, at the speed it was shown moving. The
+  world went on simulating it while an authored voice held it, so it jumped back to wherever the
+  simulation had taken it, such as against a wall that a push had sent it to.
+
+## 0.1.0
+
+### Added
+
+- `physics`, which holds a Rapier world in a blits mix: bodies as subjects, `force` and `torque`
+  voices on each body's controls, a simulated voice in a role that crossfades with authored
+  motion, impulses and drops logged at mix time, and exact replay on a seek. 2D and 3D share the
+  API through `channels2` and `channels3`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Baker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,94 @@
-# Temporary Holding Version
+# @msb235/blits-rapier
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Holds a [Rapier](https://rapier.rs) rigid-body world in a [blits](https://github.com/orochi235/blits)
+mix. Voices push bodies around, each body's simulated pose is a voice that blends with authored
+motion, and a seek, a loop or a debugger's scrub replays the world exactly. 2D and 3D share one API;
+the Rapier module you pass decides which.
+
+```
+npm install @msb235/blits @msb235/blits-rapier @dimforge/rapier3d-compat   # or rapier2d-compat
+```
+
+```ts
+import RAPIER from '@dimforge/rapier3d-compat';
+import { kit, patch } from '@msb235/blits';
+import { channels3, type Pose3, physics } from '@msb235/blits-rapier';
+import { createHistory } from '@weasel-js/history';
+
+await RAPIER.init();
+const sim = physics(kit<Pose3>(channels3), {
+  rapier: RAPIER,
+  history: { ms: 10_000, every: 250, tape: createHistory },   // only to seek
+});
+sim.body(RAPIER.RigidBodyDesc.fixed(), RAPIER.ColliderDesc.cuboid(10, 0.1, 10));
+const box = sim.body(
+  RAPIER.RigidBodyDesc.dynamic().setTranslation(0, 4, 0),
+  RAPIER.ColliderDesc.cuboid(0.5, 0.5, 0.5),
+);
+
+const gust = patch<object, Pose3>(1500, (phase) => ({ force: [Math.sin(phase * Math.PI) * 8, 0, 0] }), {
+  writes: ['force'],
+});
+box.drive({ patch: gust });
+
+// each frame
+sim.sync(now);                                   // in place of sim.mix.sync
+const { position, rotation } = sim.mix.probe(box);
+```
+
+## Bodies
+
+- **`sim.body(desc, ...colliders)`** adds a body from Rapier's own descriptions, built with the
+  module you passed. Nothing else about Rapier is wrapped. The body joins the world on the step
+  after the mix's current time, or on the first frame when the mix has not synced yet.
+- **A body is the mix's subject for its pose**, `position` and `rotation`: `sim.mix.probe(body)`
+  reads it. Its **`controls`** is a second subject, whose `force` and `torque` push the body. They
+  are read before the world steps and the pose after, which is why they are two subjects.
+- **`body.drive(spec)`** cues a voice on the controls; its weight scales the push.
+  **`body.cue(spec)`** cues one on the pose. Neither spec names `subjects`.
+- **`body.simulated`** is the `Handle` of the voice that shows the body where the world puts it, in
+  the role `sim.role`, at the weight `physics` was given (default 1). A voice cued in that role is
+  an alternative to the simulation, and the two crossfade by weight. To hand bodies to authored
+  poses and back, give `physics` a `weight` signal and the authored voices its complement, such as
+  `share(k, 0, 2)` and `share(k, 1, 2)` of one `level`. While a body's simulated voice is at weight 0
+  and a voice in the role holds it, the world puts the body where it is shown, moving as fast as
+  the shown pose moves, so handing it back starts the simulation from there. A voice outside the
+  role adds on top of wherever physics has it.
+- **`body.impulse(v)`** applies an impulse once, on the step after the mix's current time.
+  **`body.drop()`** takes the body out of the world then. Both are logged at that time, so a seek
+  back before it undoes them and playing forward through it does them again.
+- **`sim.world()`** is the Rapier world as the last `sync` left it, for reading: raycasts, contact
+  queries, debugging draws. A change made to it directly is lost at the next seek.
+
+## Channels
+
+| Channel | 2D (`channels2`) | 3D (`channels3`) | On |
+|---|---|---|---|
+| `position` | `vec(2, sum())` | `vec(3, sum())` | the body |
+| `rotation` | `angle()`, radians | `quat()`, `[x, y, z, w]` | the body |
+| `force` | `vec(2, sum())` | `vec(3, sum())` | its controls |
+| `torque` | `sum()` | `vec(3, sum())` | its controls |
+
+Spread them into a kit with your own channels. Forces and torques are in Rapier's units, newtons
+and newton-meters for a body whose mass you set in kilograms.
+
+## The clock and seeking
+
+`physics` makes the mix, with `stepMs` 1000 / 60 unless you set it; the world takes one Rapier step
+per interval, so it runs at the same rate whatever the frame rate. Pass `history` and a `tape` to
+seek. The world lives in the mix as the state of a stateful patch, so blits' history keeps a copy
+every `every` ms and a seek replays from the nearest one. A copy is Rapier's snapshot, kept as
+bytes and rebuilt into a world only when a replay needs it, so history costs memory in proportion
+to the world's size and `ms / every`. Each frame's pushes are logged beside it for the replay and
+pruned with history.
+
+Replay matches the first pass exactly on one machine. To match across machines, pass Rapier's
+deterministic build.
+
+## Not yet
+
+- Kinematic bodies moved by a voice. They need a channel with no rest, which blits' `vec` of
+  `sum()` is not.
+- Paging history to a `store`: a Rapier description is not plain data, so a body's add cannot be
+  written out.
+- Soft bodies, cloth and ropes.

package/dist/channels.d.ts

@@ -0,0 +1,23 @@
+import { type Channel, type Vec } from '@msb235/blits';
+/** The channels a 2D world reads and writes: a body's pose, and the push on its controls. */
+export interface Pose2 {
+    position: Vec<2>;
+    rotation: number;
+    force: Vec<2>;
+    torque: number;
+}
+/** The channels a 3D world reads and writes: a body's pose, and the push on its controls. */
+export interface Pose3 {
+    position: Vec<3>;
+    rotation: Vec<4>;
+    force: Vec<3>;
+    torque: Vec<3>;
+}
+/** A 2D world's channels, to spread into a kit. */
+export declare const channels2: {
+    [K in keyof Pose2]: Channel<Pose2[K]>;
+};
+/** A 3D world's channels, to spread into a kit. */
+export declare const channels3: {
+    [K in keyof Pose3]: Channel<Pose3[K]>;
+};

package/dist/channels.js

@@ -0,0 +1,15 @@
+import { angle, quat, sum, vec } from '@msb235/blits';
+/** A 2D world's channels, to spread into a kit. */
+export const channels2 = {
+    position: vec(2, sum()),
+    rotation: angle(),
+    force: vec(2, sum()),
+    torque: sum(),
+};
+/** A 3D world's channels, to spread into a kit. */
+export const channels3 = {
+    position: vec(3, sum()),
+    rotation: quat(),
+    force: vec(3, sum()),
+    torque: vec(3, sum()),
+};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { channels2, channels3, type Pose2, type Pose3 } from './channels.js';
+export { type Body, type Physics, type PhysicsOptions, physics } from './physics.js';
+export type { RapierBody, RapierModule, RapierVector, RapierWorld } from './rapier.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { channels2, channels3 } from './channels.js';
+export { physics } from './physics.js';

package/dist/physics.d.ts

@@ -0,0 +1,48 @@
+import { type Handle, type Kit, type Mix, type MixOptions, type Signal, type VoiceSpec } from '@msb235/blits';
+import type { Pose2, Pose3 } from './channels.js';
+import { type RapierModule, type RapierWorld } from './rapier.js';
+/** What `physics` takes: a mix's options, the Rapier module, and the world's gravity. */
+export interface PhysicsOptions<H> extends MixOptions<H> {
+    /** An initialized Rapier module. `@dimforge/rapier3d-compat` makes a 3D world, `rapier2d-compat` a 2D one. */
+    rapier: RapierModule;
+    /** Default: `[0, -9.81]` or `[0, -9.81, 0]`. */
+    gravity?: readonly number[];
+    /**
+     * The weight of every body's simulated voice, a signal reading each body. A signal hands a body
+     * between physics and authored motion with no weight written from the frame loop. Default 1.
+     */
+    weight?: number | Signal<object, H>;
+}
+/** A rigid body: the mix's subject for its pose, with its controls beside it. */
+export interface Body<O, H> {
+    readonly key: number;
+    /** The subject whose `force` and `torque` push the body, read before the world steps. */
+    readonly controls: object;
+    /** The voice that shows the body where the world puts it, in `Physics.role`, at `PhysicsOptions.weight`. */
+    readonly simulated: Handle<object>;
+    /** Cues a voice on the body's pose. In `Physics.role` it is an alternative to the simulation; outside it, it adds on top. */
+    cue(spec: Omit<VoiceSpec<object, O, H>, 'subjects'>): Handle<object>;
+    /** Cues a voice on the body's controls. */
+    drive(spec: Omit<VoiceSpec<object, O, H>, 'subjects'>): Handle<object>;
+    /** Applies an impulse once, on the step after the mix's current time, and again on any replay through it. */
+    impulse(v: readonly number[]): void;
+    /** Takes the body out of the world on the step after the mix's current time. A seek back before then brings it back. */
+    drop(): void;
+}
+/** A Rapier world held in a blits mix. */
+export interface Physics<O, H> {
+    readonly mix: Mix<object, O, H>;
+    /** The role every body's simulated voice plays. */
+    readonly role: string;
+    /**
+     * Adds a body made from Rapier's descriptions, on the step after the mix's current time, or on
+     * the first step before the mix has synced.
+     */
+    body(desc: unknown, ...colliders: unknown[]): Body<O, H>;
+    /** Syncs the mix to `now`, reads every body's controls, and steps the world. Call it in place of `mix.sync`. */
+    sync(now: number): void;
+    /** The world as it stands after the last `sync`, for reading. A change made to it is lost at the next seek. */
+    world(): RapierWorld | undefined;
+}
+/** Makes a mix that holds a Rapier world, stepped on its `stepMs` clock and replayed by its history. */
+export declare function physics<O extends Pose2 | Pose3, H extends object = Record<string, never>>(kit: Kit<O>, opts: PhysicsOptions<H>): Physics<O, H>;

package/dist/physics.js

@@ -0,0 +1,205 @@
+import { mix, patch, } from '@msb235/blits';
+import { dimsOf } from './rapier.js';
+import { applyLog, copy, insert, worldOf } from './world.js';
+const ROLE = 'physics';
+const copyOf = (r) => typeof r === 'number' ? r : [...r];
+/** Makes a mix that holds a Rapier world, stepped on its `stepMs` clock and replayed by its history. */
+export function physics(kit, opts) {
+    const { rapier, gravity, weight, ...rest } = opts;
+    const dims = dimsOf(rapier);
+    const g = gravity ?? (dims.n === 2 ? [0, -9.81] : [0, -9.81, 0]);
+    const m = mix(kit, { ...rest, stepMs: rest.stepMs ?? 1000 / 60 });
+    const log = [];
+    // Each frame's pushes at its mix time. A seek replays steps on what the host reads now, so the
+    // world reads the pushes of the frame that caused each step from here instead: the first frame
+    // at or after the step's end, looked up half a step early since replayed times can round apart.
+    const pushLog = [];
+    const keep = rest.history?.ms ?? 0;
+    const frameAt = (t) => {
+        let lo = 0;
+        let hi = pushLog.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >> 1;
+            if (pushLog[mid].at < t)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        return pushLog[lo] ?? pushLog[pushLog.length - 1];
+    };
+    let seen;
+    let live;
+    const world = patch(0, (_p, _s, setting) => {
+        const s = setting.state;
+        // A world first read before it has stepped holds the bodies added before then.
+        if (Number.isNaN(s.t)) {
+            applyLog(s, worldOf(s, rapier), log, setting.timestamp, 0, dims);
+            s.t = setting.timestamp;
+        }
+        seen = s;
+        return {};
+    }, {
+        writes: [],
+        state: () => ({
+            bytes: null,
+            world: new rapier.World(dims.vector(g)),
+            handles: new Map(),
+            t: Number.NaN,
+        }),
+        step: (s, dt, _subject, setting) => {
+            const w = worldOf(s, rapier);
+            w.timestep = dt / 1000;
+            applyLog(s, w, log, setting.timestamp, dt / 2, dims);
+            const frame = frameAt(setting.timestamp - dt / 2);
+            const pushes = frame?.pushes ?? {};
+            const holds = frame?.holds ?? {};
+            for (const k in holds) {
+                const handle = s.handles.get(+k);
+                const h = holds[k];
+                if (handle !== undefined && h !== undefined)
+                    dims.place(w.getRigidBody(handle), h.now, h.before, h.dt);
+            }
+            const pushed = [];
+            for (const k in pushes) {
+                const handle = s.handles.get(+k);
+                if (handle === undefined)
+                    continue;
+                const v = pushes[k];
+                const b = w.getRigidBody(handle);
+                b.addForce(dims.vector(v), true);
+                dims.torque(b, dims.n === 2 ? (v[2] ?? 0) : v.slice(3));
+                pushed.push(handle);
+            }
+            w.step();
+            for (const handle of pushed) {
+                const b = w.getRigidBody(handle);
+                b.resetForces(false);
+                b.resetTorques(false);
+            }
+            s.t = setting.timestamp;
+        },
+        clone: copy,
+    });
+    const WORLD = {};
+    let started = false;
+    const simulated = patch(0, (_p, subject) => {
+        const handle = live?.handles.get(subject.key);
+        if (live === undefined || handle === undefined)
+            return {};
+        const b = worldOf(live, rapier).getRigidBody(handle);
+        return { position: dims.position(b), rotation: dims.rotation(b) };
+    }, { writes: ['position', 'rotation'] });
+    const now = () => (Number.isNaN(m.timestamp) ? Number.NEGATIVE_INFINITY : m.timestamp);
+    const driven = new Set();
+    // Each body's voices in the simulation's role besides its own, and its pose the last frame they held it.
+    const authored = new Map();
+    const held = new Map();
+    const out = m.pose();
+    const shown = m.pose();
+    // Read at the end of each frame, for the next frame's steps to apply.
+    let holding = {};
+    const holdsAt = (at) => {
+        const holds = {};
+        for (const [body, voices] of authored) {
+            const playing = voices.filter((v) => v.state !== 'done');
+            if (playing.length === 0) {
+                authored.delete(body);
+                held.delete(body);
+                continue;
+            }
+            if (playing.length < voices.length)
+                authored.set(body, playing);
+            const p = m.probe(body, shown);
+            // Shown with none of the simulation, the body is put where it is shown, so the simulation
+            // takes it back from there.
+            if (!live?.handles.has(body.key) ||
+                body.simulated.weightOf(body) > 0 ||
+                !playing.some((v) => v.weightOf(body) > 0)) {
+                held.delete(body);
+                continue;
+            }
+            const now = { position: [...p.position], rotation: copyOf(p.rotation) };
+            const last = held.get(body);
+            holds[body.key] = { now, before: last?.pose, dt: last === undefined ? 0 : at - last.at };
+            held.set(body, { pose: now, at });
+        }
+        return holds;
+    };
+    let next = 0;
+    return {
+        mix: m,
+        role: ROLE,
+        body(desc, ...colliders) {
+            const key = next++;
+            insert(log, { at: now(), key, kind: 'add', desc, colliders });
+            const controls = {};
+            const own = (spec, subject) => {
+                if ('subjects' in spec)
+                    throw new Error('blits-rapier: a body cues on itself; its spec names no subjects');
+                return m.cue({ ...spec, subjects: [subject] });
+            };
+            const body = {
+                key,
+                controls,
+                simulated: undefined,
+                cue: (spec) => {
+                    const h = own(spec, body);
+                    if (spec.role === ROLE)
+                        authored.set(body, [...(authored.get(body) ?? []), h]);
+                    return h;
+                },
+                drive: (spec) => {
+                    driven.add(body);
+                    return own(spec, controls);
+                },
+                impulse: (v) => insert(log, { at: now(), key, kind: 'impulse', v: [...v] }),
+                drop: () => {
+                    insert(log, { at: now(), key, kind: 'drop' });
+                },
+            };
+            body.simulated = m.cue({
+                patch: simulated,
+                subjects: [body],
+                role: ROLE,
+                ...(weight === undefined ? {} : { weight }),
+            });
+            return body;
+        },
+        sync(t) {
+            m.sync(t);
+            // Cued before the mix has a time, the world would catch up from mix time 0 on its first step.
+            if (!started) {
+                started = true;
+                m.cue({ patch: world, subjects: [WORLD] });
+            }
+            const pushes = {};
+            for (const body of driven) {
+                const p = m.probe(body.controls, out);
+                const torque = typeof p.torque === 'number' ? [p.torque] : p.torque;
+                if (p.force.some((x) => x !== 0) || torque.some((x) => x !== 0))
+                    pushes[body.key] = [...p.force, ...torque];
+            }
+            const at = m.timestamp;
+            let back = false;
+            while (pushLog.length > 0 && pushLog[pushLog.length - 1].at >= at) {
+                pushLog.pop();
+                back = true;
+            }
+            // A seek back leaves the holds read before it, and their speeds, behind.
+            if (back) {
+                holding = {};
+                held.clear();
+            }
+            pushLog.push({ at, pushes, holds: holding });
+            let old = 0;
+            while (old < pushLog.length - 1 && pushLog[old + 1].at < at - keep)
+                old++;
+            if (old > 0)
+                pushLog.splice(0, old);
+            m.probe(WORLD);
+            live = seen;
+            holding = holdsAt(at);
+        },
+        world: () => (live === undefined ? undefined : worldOf(live, rapier)),
+    };
+}

package/dist/rapier.d.ts

@@ -0,0 +1,66 @@
+/** A vector as Rapier takes and gives it: `z` in 3D only. */
+export interface RapierVector {
+    x: number;
+    y: number;
+    z?: number;
+}
+/** What blits-rapier uses of a Rapier rigid body, in either build. */
+export interface RapierBody {
+    readonly handle: number;
+    translation(): RapierVector;
+    rotation(): number | {
+        x: number;
+        y: number;
+        z: number;
+        w: number;
+    };
+    addForce(force: RapierVector, wake: boolean): void;
+    addTorque(torque: never, wake: boolean): void;
+    applyImpulse(impulse: RapierVector, wake: boolean): void;
+    resetForces(wake: boolean): void;
+    resetTorques(wake: boolean): void;
+    setTranslation(v: RapierVector, wake: boolean): void;
+    setRotation(r: never, wake: boolean): void;
+    setLinvel(v: RapierVector, wake: boolean): void;
+    setAngvel(v: never, wake: boolean): void;
+}
+/** What blits-rapier uses of a Rapier world, in either build. */
+export interface RapierWorld {
+    timestep: number;
+    step(): void;
+    takeSnapshot(): Uint8Array;
+    createRigidBody(desc: never): RapierBody;
+    createCollider(desc: never, parent?: never): unknown;
+    getRigidBody(handle: number): RapierBody;
+    removeRigidBody(body: never): void;
+    free(): void;
+}
+/**
+ * A Rapier module, `@dimforge/rapier2d-compat` or `@dimforge/rapier3d-compat` or a build like
+ * them, already initialized. Which one is passed decides the dimensions.
+ */
+export interface RapierModule {
+    World: {
+        new (gravity: never): RapierWorld;
+        restoreSnapshot(data: Uint8Array): RapierWorld;
+    };
+}
+/** The arithmetic that differs between the 2D and 3D builds, behind one shape. */
+export interface Dims {
+    readonly n: 2 | 3;
+    vector(v: readonly number[]): RapierVector;
+    position(body: RapierBody): number[];
+    /** An angle in 2D, `[x, y, z, w]` in 3D: what the `rotation` channel holds. */
+    rotation(body: RapierBody): number | number[];
+    /** Adds `torque`, a number in 2D and three numbers in 3D. */
+    torque(body: RapierBody, torque: number | readonly number[]): void;
+    /** Puts the body at a pose, moving at the speed it took to get there from `before` over `dt` ms. */
+    place(body: RapierBody, now: Placed, before: Placed | undefined, dt: number): void;
+}
+/** A body's position and rotation as the channels hold them. */
+export interface Placed {
+    position: readonly number[];
+    rotation: number | readonly number[];
+}
+/** The 3D build where the module has `Vector3`, else the 2D. */
+export declare function dimsOf(rapier: RapierModule): Dims;

package/dist/rapier.js

@@ -0,0 +1,63 @@
+const speed = (now, before, dt) => now.map((x, i) => (before === undefined || dt <= 0 ? 0 : (x - (before[i] ?? x)) / (dt / 1000)));
+const two = {
+    n: 2,
+    vector: (v) => ({ x: v[0] ?? 0, y: v[1] ?? 0 }),
+    position: (b) => {
+        const t = b.translation();
+        return [t.x, t.y];
+    },
+    rotation: (b) => b.rotation(),
+    torque: (b, t) => b.addTorque((typeof t === 'number' ? t : (t[0] ?? 0)), true),
+    place: (b, now, before, dt) => {
+        const r = now.rotation;
+        b.setTranslation(two.vector(now.position), true);
+        b.setRotation(r, true);
+        b.setLinvel(two.vector(speed(now.position, before?.position, dt)), true);
+        let turn = before === undefined ? 0 : r - before.rotation;
+        turn -= 2 * Math.PI * Math.round(turn / (2 * Math.PI));
+        b.setAngvel((dt > 0 ? turn / (dt / 1000) : 0), true);
+    },
+};
+const three = {
+    n: 3,
+    vector: (v) => ({ x: v[0] ?? 0, y: v[1] ?? 0, z: v[2] ?? 0 }),
+    position: (b) => {
+        const t = b.translation();
+        return [t.x, t.y, t.z ?? 0];
+    },
+    rotation: (b) => {
+        const q = b.rotation();
+        return [q.x, q.y, q.z, q.w];
+    },
+    torque: (b, t) => b.addTorque(three.vector(typeof t === 'number' ? [0, 0, t] : t), true),
+    place: (b, now, before, dt) => {
+        const [x, y, z, w] = now.rotation;
+        b.setTranslation(three.vector(now.position), true);
+        b.setRotation({ x, y, z, w }, true);
+        b.setLinvel(three.vector(speed(now.position, before?.position, dt)), true);
+        b.setAngvel(three.vector(spin(now.rotation, before?.rotation, dt)), true);
+    },
+};
+/** The angular velocity turning `before` into `now` over `dt` ms, both `[x, y, z, w]`. */
+function spin(now, before, dt) {
+    if (before === undefined || dt <= 0)
+        return [0, 0, 0];
+    const [ax, ay, az, aw] = now;
+    const [bx, by, bz, bw] = before;
+    // now · conj(before), taken the short way round.
+    let x = bw * ax - bx * aw - by * az + bz * ay;
+    let y = bw * ay - by * aw - bz * ax + bx * az;
+    let z = bw * az - bz * aw - bx * ay + by * ax;
+    let w = bw * aw + bx * ax + by * ay + bz * az;
+    if (w < 0)
+        [x, y, z, w] = [-x, -y, -z, -w];
+    const s = Math.hypot(x, y, z);
+    if (s < 1e-12)
+        return [0, 0, 0];
+    const k = (2 * Math.atan2(s, w)) / s / (dt / 1000);
+    return [x * k, y * k, z * k];
+}
+/** The 3D build where the module has `Vector3`, else the 2D. */
+export function dimsOf(rapier) {
+    return 'Vector3' in rapier ? three : two;
+}

package/dist/world.d.ts

@@ -0,0 +1,43 @@
+import type { Dims, RapierModule, RapierWorld } from './rapier.js';
+/**
+ * A world as the world subject's state. A copy for history holds only `bytes`, Rapier's snapshot,
+ * so a copy blits lets go of is plain memory; `worldOf` rebuilds the world on first use.
+ */
+export interface State {
+    bytes: Uint8Array | null;
+    world: RapierWorld | null;
+    /** Each present body's Rapier handle, by its key. */
+    handles: Map<number, number>;
+    /** The mix time of the last step, NaN before the first. */
+    t: number;
+}
+/** Something done to the world at a mix time, applied by whichever step reaches it, on every replay. */
+export type Entry = {
+    at: number;
+    key: number;
+    kind: 'add';
+    desc: unknown;
+    colliders: readonly unknown[];
+} | {
+    at: number;
+    key: number;
+    kind: 'drop';
+} | {
+    at: number;
+    key: number;
+    kind: 'impulse';
+    v: readonly number[];
+};
+/** The state's world, rebuilt from its snapshot where it has none yet. */
+export declare function worldOf(state: State, rapier: RapierModule): RapierWorld;
+/** A copy sharing nothing with `state`, holding the world as a snapshot. */
+export declare function copy(state: State): State;
+/** Puts `entry` into `log` after every entry at or before its time. */
+export declare function insert(log: Entry[], entry: Entry): void;
+/**
+ * Applies the entries a step from the state's time to `to` passes: those at or after the state's
+ * time and before `to`, or every one before `to` on a state never stepped. An entry logged at the
+ * time the world last stepped to applies on the step after. Both ends are taken `slack` early: a
+ * replayed step's times can differ from the first pass's by rounding.
+ */
+export declare function applyLog(state: State, world: RapierWorld, log: readonly Entry[], to: number, slack: number, dims: Dims): void;

package/dist/world.js

@@ -0,0 +1,57 @@
+/** The state's world, rebuilt from its snapshot where it has none yet. */
+export function worldOf(state, rapier) {
+    if (state.world === null) {
+        state.world = rapier.World.restoreSnapshot(state.bytes);
+        state.bytes = null;
+    }
+    return state.world;
+}
+/** A copy sharing nothing with `state`, holding the world as a snapshot. */
+export function copy(state) {
+    return {
+        bytes: state.world === null ? state.bytes : state.world.takeSnapshot(),
+        world: null,
+        handles: new Map(state.handles),
+        t: state.t,
+    };
+}
+/** Puts `entry` into `log` after every entry at or before its time. */
+export function insert(log, entry) {
+    let i = log.length;
+    while (i > 0 && log[i - 1].at > entry.at)
+        i--;
+    log.splice(i, 0, entry);
+}
+/**
+ * Applies the entries a step from the state's time to `to` passes: those at or after the state's
+ * time and before `to`, or every one before `to` on a state never stepped. An entry logged at the
+ * time the world last stepped to applies on the step after. Both ends are taken `slack` early: a
+ * replayed step's times can differ from the first pass's by rounding.
+ */
+export function applyLog(state, world, log, to, slack, dims) {
+    const from = state.t - slack;
+    for (const e of log) {
+        if (e.at >= to - slack)
+            break;
+        if (e.at < from)
+            continue;
+        const handle = state.handles.get(e.key);
+        if (e.kind === 'add') {
+            if (handle !== undefined)
+                continue;
+            const body = world.createRigidBody(e.desc);
+            for (const c of e.colliders)
+                world.createCollider(c, body);
+            state.handles.set(e.key, body.handle);
+        }
+        else if (handle === undefined) {
+        }
+        else if (e.kind === 'drop') {
+            world.removeRigidBody(world.getRigidBody(handle));
+            state.handles.delete(e.key);
+        }
+        else {
+            world.getRigidBody(handle).applyImpulse(dims.vector(e.v), true);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@msb235/blits-rapier",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Pairs Rapier rigid-body physics with a blits mix: voices push bodies, and each body's simulated pose blends with authored motion",
+  "keywords": [
+    "physics",
+    "rapier",
+    "blits",
+    "animation"
+  ],
+  "license": "MIT",
+  "author": "orochi235",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/orochi235/blits.git",
+    "directory": "packages/rapier"
+  },
+  "homepage": "https://github.com/orochi235/blits/tree/main/packages/rapier#readme",
+  "bugs": "https://github.com/orochi235/blits/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "prepack": "rm -rf dist && npm run build"
+  },
+  "peerDependencies": {
+    "@msb235/blits": "^0.17.0",
+    "@dimforge/rapier2d-compat": ">=0.21.0 <1.0.0",
+    "@dimforge/rapier3d-compat": ">=0.21.0 <1.0.0"
+  },
+  "devDependencies": {
+    "@dimforge/rapier2d-compat": "0.21.0",
+    "@dimforge/rapier3d-compat": "0.21.0",
+    "@msb235/blits": "0.17.0"
+  },
+  "peerDependenciesMeta": {
+    "@dimforge/rapier2d-compat": {
+      "optional": true
+    },
+    "@dimforge/rapier3d-compat": {
+      "optional": true
+    }
+  }
+}