@opsydyn/effect-three 0.4.0 → 0.6.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opsydyn/effect-three",
-  "version": "0.4.0",
+  "version": "0.6.4",
   "description": "Effect-native declarative Three.js scenes: scoped resources, keyed reconciliation, testable frame loop.",
   "license": "MIT",
   "repository": {
@@ -55,6 +55,7 @@
     "test": "bun test --pass-with-no-tests ./src ./test --coverage --coverage-reporter=lcov --coverage-dir=coverage && bun scripts/check-coverage.ts coverage/lcov.info",
     "build": "tsc -b && bun build ./src/index.ts ./src/kernel/index.ts ./src/webgl/index.ts ./src/webgpu/index.ts --root ./src --outdir ./dist --target browser --packages external --splitting --sourcemap=linked",
     "scene:diff": "bun scripts/scene-diff.ts",
+    "scene:preview": "bun scripts/scene-preview.ts",
     "bench": "bun bench/index.ts",
     "bench:check": "bun bench/index.ts --check",
     "api:report": "api-extractor run --local",
@@ -68,7 +69,7 @@
     "@types/bun": "1.4.3",
     "@types/pngjs": "6.0.5",
     "@types/three": "0.186.0",
-    "effect": "4.0.0",
+    "effect": "4.1.0",
     "oxlint": "1.88.0",
     "oxlint-tsgolint": "7.0.2004",
     "pixelmatch": "8.0.0",

package/src/kernel/bodies.ts

@@ -15,7 +15,16 @@ import { Euler, Quaternion, type Scene } from 'three';
 import { bodyId, type BodySource } from './bodySources.ts';
 import type { Body, Joint, Physics, Vec3 } from './description.ts';
 import { bodyEquals, collidersEqual, jointEquals, physicsEquals } from './equality.ts';
-import type { BodyPose, PhysicsEngine, PhysicsJoint, PhysicsWorld, Quat } from './physics.ts';
+import {
+  type BodyPose,
+  type Collision,
+  type PhysicsEngine,
+  type PhysicsJoint,
+  type PhysicsWorld,
+  type Quat,
+  snapshotBytes,
+  snapshotText,
+} from './physics.ts';
 import { createPhysicsDebug } from './physicsDebug.ts';
 
 /** Two bodies began (`started`) or stopped touching: their nodes' keys, and instances'. */
@@ -48,6 +57,19 @@ export type BodyContactForce = {
   readonly maxForceMagnitude: number;
 };
 
+/**
+ * A world driven by `physics({ until })` has reached that step and waits: its run, what
+ * it has done (its step count since it was made), and a checksum of every body's pose
+ * there, so peers that should agree can check that they do.
+ */
+export type PhysicsReached = {
+  readonly run: number;
+  readonly step: number;
+  readonly checksum: string;
+  /** At `physics({ snapshotAt })`: the world there, for another to start `from`. */
+  readonly snapshot?: string;
+};
+
 type Hosted = {
   source: BodySource;
   /** What its colliders were made from; a change makes them again. */
@@ -69,6 +91,13 @@ export type BodyHost = {
   readonly drainCollisions: () => ReadonlyArray<BodyCollision>;
   /** Contact forces over their thresholds since the last call. */
   readonly drainContactForces: () => ReadonlyArray<BodyContactForce>;
+  /** Steps the Model has asked for and the world has reached since the last call. */
+  readonly drainReached: () => ReadonlyArray<PhysicsReached>;
+  /**
+   * Whether a world on `until` still owes steps, or a report: it needs frames even when
+   * nothing else moves, and even under reduced motion, as other peers wait on it.
+   */
+  readonly owesSteps: () => boolean;
   readonly dispose: () => void;
 };
 
@@ -108,6 +137,53 @@ const between = (a: BodyPose, b: BodyPose, alpha: number): BodyPose => {
   };
 };
 
+/**
+ * How far behind `until` (in seconds of simulation) a world may run at scene time's pace,
+ * following an `until` that moves on as time passes; further back (a newcomer replaying,
+ * a page that was busy), it goes straight there.
+ */
+const catchUpAfter = 0.25;
+
+/** The most simulation a world on `until` runs in one frame, in seconds. */
+const mostPerFrame = 1;
+
+const checksumBytes = new DataView(new ArrayBuffer(8));
+
+/** FNV-1a, a byte at a time. */
+const mixByte = (hash: number, byte: number): number => Math.imul(hash ^ byte, 0x0100_0193) >>> 0;
+
+const mixNumber = (hash: number, value: number): number => {
+  checksumBytes.setFloat64(0, value);
+  let mixed = hash;
+  for (let i = 0; i < 8; i++) mixed = mixByte(mixed, checksumBytes.getUint8(i));
+  return mixed;
+};
+
+const mixText = (hash: number, text: string): number => {
+  let mixed = hash;
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    mixed = mixByte(mixByte(mixed, code & 0xff), code >>> 8);
+  }
+  return mixed;
+};
+
+/**
+ * A checksum of where every body is, by id: the bits of each pose's numbers, so peers
+ * agree only if their worlds are the same to the last bit.
+ */
+const checksumOf = (poses: ReadonlyArray<readonly [string, BodyPose]>): string => {
+  let hash = 0x811c_9dc5;
+  for (const [id, { position, quaternion }] of poses.toSorted(([a], [b]) =>
+    a < b ? -1 : a > b ? 1 : 0,
+  )) {
+    hash = mixText(hash, id);
+    for (const value of position) hash = mixNumber(hash, value);
+    for (const value of quaternion) hash = mixNumber(hash, value);
+  }
+  return hash.toString(16).padStart(8, '0');
+};
+
 /** A change that needs a new body: another holder or kind, or colliders made otherwise. */
 const remade = (hosted: Hosted, source: BodySource, signature: string): boolean =>
   hosted.source.holder !== source.holder ||
@@ -156,6 +232,19 @@ export const createBodyHost = (engine: PhysicsEngine | undefined, scene: Scene):
   const debug = createPhysicsDebug(scene);
   let last: number | undefined;
   let accumulator = 0;
+  /** Steps taken since the world was made. */
+  let steps = 0;
+  /** The last `until` reported as reached. */
+  let reported: number | undefined;
+  /** The last `snapshotAt` reported, snapshot and all. */
+  let snapped: number | undefined;
+  let reached: Array<PhysicsReached> = [];
+  /** Snapshots of the latest stops, by step, oldest first, while `keep` asks for them. */
+  const kept = new Map<number, Uint8Array>();
+  /** A run just started from a snapshot: it goes straight to `until`, as one far behind. */
+  let rushing = false;
+  /** What a world made from a snapshot holds already, until this sync takes it on. */
+  let restored: { readonly bodies: Set<string>; readonly joints: Set<string> } | undefined;
 
   /** Draws the world's lines while the description asks for them. */
   const drawDebug = (): void => {
@@ -172,10 +261,51 @@ export const createBodyHost = (engine: PhysicsEngine | undefined, scene: Scene):
     joined.clear();
     accumulator = 0;
     last = undefined;
+    steps = 0;
+    reported = undefined;
+    snapped = undefined;
+    reached = [];
+  };
+
+  /**
+   * The world for a run: made from the snapshot it starts `from`, counting on from its
+   * step, when the engine can; otherwise from the description, at step 0.
+   */
+  const make = (active: PhysicsEngine, physics: Physics): PhysicsWorld => {
+    const { from } = physics;
+    const bytes =
+      from === null
+        ? undefined
+        : from.snapshot === null
+          ? kept.get(from.step)
+          : snapshotBytes(from.snapshot);
+    if (from === null || bytes === undefined || active.restoreWorld === undefined) {
+      kept.clear();
+      return active.createWorld(physics);
+    }
+    // What was kept after the step it goes back to was of a world that went another way.
+    for (const step of kept.keys())
+      if (step > from.step || from.snapshot !== null) kept.delete(step);
+    const made = active.restoreWorld(physics, bytes);
+    steps = from.step;
+    rushing = true;
+    restored = { bodies: new Set(made.bodies), joints: new Set(made.joints) };
+    return made.world;
   };
 
+  /** Takes on a body the restored world holds: shown where the world has it. */
+  const adopt = (active: PhysicsWorld, source: BodySource, signature: string): void => {
+    const pose = active.pose(source.id) ?? source.described();
+    source.place(pose);
+    hosted.set(source.id, { source, signature, previous: pose, current: pose, shown: pose });
+  };
+
+  /** Whether this sync begins a new run: bodies start where the description puts them. */
+  let restarting = false;
+
   const add = (active: PhysicsWorld, source: BodySource, signature: string): void => {
-    const pose = source.pose();
+    const pose = restarting ? source.described() : source.pose();
+    if (restarting) source.place(pose);
     active.add(source.id, source.body, source.colliders(), pose);
     if (source.body.impulse !== null) active.applyImpulse(source.id, source.body.impulse.impulse);
     hosted.set(source.id, { source, signature, previous: pose, current: pose, shown: pose });
@@ -185,6 +315,10 @@ export const createBodyHost = (engine: PhysicsEngine | undefined, scene: Scene):
   const syncBody = (active: PhysicsWorld, source: BodySource): void => {
     const existing = hosted.get(source.id);
     const signature = source.signature();
+    if (existing === undefined && restored?.bodies.has(source.id) === true) {
+      adopt(active, source, signature);
+      return;
+    }
     if (existing === undefined || remade(existing, source, signature)) {
       if (existing !== undefined) active.remove(source.id);
       add(active, source, signature);
@@ -247,11 +381,27 @@ export const createBodyHost = (engine: PhysicsEngine | undefined, scene: Scene):
   const sync: BodyHost['sync'] = (physics, sources) => {
     if (physics === null || engine === undefined) {
       dispose();
+      kept.clear();
       return;
     }
-    if (world === undefined) world = engine.createWorld(physics);
-    // Joints are made below, not configured.
-    else if (!physicsEquals(settings && { ...settings, joints: physics.joints }, physics)) {
+    // Another run: the world goes, and a new one counts from step 0.
+    restarting = settings !== null && settings.run !== physics.run;
+    if (restarting) dispose();
+    if (world === undefined) world = make(engine, physics);
+    // Joints are made below, and the clock and snapshots are the host's: none is configured.
+    else if (
+      !physicsEquals(
+        settings && {
+          ...settings,
+          joints: physics.joints,
+          until: physics.until,
+          snapshotAt: physics.snapshotAt,
+          from: physics.from,
+          keep: physics.keep,
+        },
+        physics,
+      )
+    ) {
       world.configure(physics);
     }
     settings = physics;
@@ -267,7 +417,20 @@ export const createBodyHost = (engine: PhysicsEngine | undefined, scene: Scene):
       world.remove(id);
       hosted.delete(id);
     }
+    if (restored !== undefined) {
+      // What the snapshot held and the description does not, goes; its joints that the
+      // description still has are kept as they were.
+      for (const id of restored.bodies) if (!seen.has(id)) world.remove(id);
+      for (const joint of physics.joints) {
+        if (restored.joints.has(joint.key)) joined.set(joint.key, joint);
+      }
+      for (const id of restored.joints) {
+        if (!joined.has(id)) world.removeJoint(id);
+      }
+      restored = undefined;
+    }
     syncJoints(world, physics.joints);
+    restarting = false;
     drawDebug();
   };
 
@@ -277,10 +440,8 @@ export const createBodyHost = (engine: PhysicsEngine | undefined, scene: Scene):
     }
   };
 
-  const step = (active: PhysicsWorld, seconds: number): void => {
-    for (const body of hosted.values()) body.previous = body.current;
-    kinematicTargets(active);
-    for (const collision of active.step(seconds)) {
+  const heard = (arrived: ReadonlyArray<Collision>, active: PhysicsWorld): void => {
+    for (const collision of arrived) {
       collisions.push({
         ...named(hosted.get(collision.a)?.source, hosted.get(collision.b)?.source, collision),
         started: collision.started,
@@ -293,21 +454,128 @@ export const createBodyHost = (engine: PhysicsEngine | undefined, scene: Scene):
         ...payload,
       });
     }
+  };
+
+  const step = (active: PhysicsWorld, seconds: number): void => {
+    for (const body of hosted.values()) body.previous = body.current;
+    kinematicTargets(active);
+    heard(active.step(seconds), active);
     for (const [id, body] of hosted) body.current = active.pose(id) ?? body.current;
+    steps += 1;
   };
 
-  const tick: BodyHost['tick'] = (elapsed, animating) => {
-    const delta = last === undefined ? 0 : Math.min(0.5, Math.max(0, elapsed - last));
-    last = elapsed;
-    if (world === undefined || settings === null || settings.paused || !animating) return;
-    const timeStep = settings.timeStep;
+  /**
+   * What a world working elsewhere has sent back since the last frame: its collisions and
+   * forces, and where its bodies are now. Whether anything is still to come back; never,
+   * for a world that does what it is asked at once.
+   */
+  const collect = (active: PhysicsWorld): boolean => {
+    if (active.received === undefined) return false;
+    const { collisions: arrived, pending } = active.received();
+    heard(arrived, active);
+    for (const [id, body] of hosted) body.current = active.pose(id) ?? body.current;
+    return pending;
+  };
+
+  /** On scene time: every whole step the time since the last frame holds. */
+  const free = (active: PhysicsWorld, timeStep: number, delta: number): number => {
     accumulator += delta;
-    scene.updateMatrixWorld();
     while (accumulator >= timeStep) {
-      step(world, timeStep);
+      step(active, timeStep);
       accumulator -= timeStep;
     }
-    const alpha = settings.interpolate ? accumulator / timeStep : 1;
+    collect(active);
+    return accumulator / timeStep;
+  };
+
+  /** Whether the world is to stop at `snapshotAt` on its way to `until` and report a snapshot there. */
+  const snapshotOwed = (physics: Physics, until: number): boolean =>
+    physics.snapshotAt !== null &&
+    snapped !== physics.snapshotAt &&
+    steps <= physics.snapshotAt &&
+    physics.snapshotAt <= until;
+
+  /**
+   * Reports where the world is: its checksum, and a snapshot of it when `snapshot` asks;
+   * one is kept too, while the description asks to `keep` some. False, reporting nothing,
+   * while a world working elsewhere has yet to send the snapshot (asking it for one).
+   */
+  const report = (active: PhysicsWorld, physics: Physics, snapshot: boolean): boolean => {
+    const wanted = snapshot || physics.keep > 0;
+    const bytes = wanted ? active.snapshot?.() : undefined;
+    if (wanted && active.snapshot !== undefined && bytes === undefined) return false;
+    if (physics.keep > 0 && bytes !== undefined) {
+      kept.delete(steps);
+      kept.set(steps, bytes);
+      for (const step of kept.keys()) if (kept.size > physics.keep) kept.delete(step);
+    }
+    const { run } = physics;
+    reached.push({
+      run,
+      step: steps,
+      checksum: checksumOf([...hosted.keys()].flatMap((id) => posed(active, id))),
+      ...(snapshot && bytes !== undefined ? { snapshot: snapshotText(bytes) } : {}),
+    });
+    return true;
+  };
+
+  /**
+   * Toward `until`: at scene time's pace while close behind it, straight there (a step
+   * budget a frame) when further back, never past it. A world that has reached it waits
+   * there and reports it once, with the bodies' checksum. A `snapshotAt` on the way is a
+   * stop too: the world reports there with a snapshot, and goes on.
+   */
+  const driven = (active: PhysicsWorld, physics: Physics, until: number, delta: number) => {
+    const { timeStep } = physics;
+    const snapping = snapshotOwed(physics, until);
+    const stop = snapping && physics.snapshotAt !== null ? physics.snapshotAt : until;
+    accumulator += delta;
+    const owed = Math.max(0, stop - steps);
+    const paced = Math.floor(accumulator / timeStep);
+    const behind = rushing || owed > Math.ceil(catchUpAfter / timeStep);
+    rushing = false;
+    const count = Math.min(owed, behind ? owed : paced, Math.ceil(mostPerFrame / timeStep));
+    for (let i = 0; i < count; i++) step(active, timeStep);
+    accumulator = Math.max(0, accumulator - count * timeStep);
+    const pending = collect(active);
+    if (steps < stop) return Math.min(1, accumulator / timeStep);
+    // A world working elsewhere is there once all it was asked has come back, poses and all.
+    if (stop < until) {
+      if (!pending && report(active, physics, true)) snapped = stop;
+      return Math.min(1, accumulator / timeStep);
+    }
+    // Waiting: time spent here is not owed once `until` moves on.
+    accumulator = 0;
+    // Reported there already, it reports again for a snapshot asked for afterwards.
+    if (
+      steps === until &&
+      (reported !== until || snapping) &&
+      !pending &&
+      report(active, physics, snapping)
+    ) {
+      reported = until;
+      if (snapping) snapped = until;
+    }
+    return 1;
+  };
+
+  const posed = (active: PhysicsWorld, id: string): ReadonlyArray<[string, BodyPose]> => {
+    const pose = active.pose(id);
+    return pose === undefined ? [] : [[id, pose]];
+  };
+
+  const tick: BodyHost['tick'] = (elapsed, animating) => {
+    const delta = last === undefined ? 0 : Math.min(0.5, Math.max(0, elapsed - last));
+    last = elapsed;
+    if (world === undefined || settings === null || settings.paused) return;
+    // A world on `until` steps under reduced motion too: other peers wait on it.
+    if (settings.until === null && !animating) return;
+    scene.updateMatrixWorld();
+    const progress =
+      settings.until === null
+        ? free(world, settings.timeStep, delta)
+        : driven(world, settings, settings.until, delta);
+    const alpha = settings.interpolate ? progress : 1;
     for (const body of hosted.values()) {
       if (body.source.body.type === 'dynamic') {
         body.shown = between(body.previous, body.current, alpha);
@@ -333,6 +601,20 @@ export const createBodyHost = (engine: PhysicsEngine | undefined, scene: Scene):
       contactForces = [];
       return drained;
     },
+    drainReached: () => {
+      if (reached.length === 0) return reached;
+      const drained = reached;
+      reached = [];
+      return drained;
+    },
+    owesSteps: () =>
+      world !== undefined &&
+      settings !== null &&
+      !settings.paused &&
+      settings.until !== null &&
+      (steps < settings.until ||
+        reported !== settings.until ||
+        snapshotOwed(settings, settings.until)),
     dispose,
   };
 };

package/src/kernel/build.ts

@@ -6,6 +6,7 @@
 import { CatmullRomCurve3, Color, CubicBezierCurve3, QuadraticBezierCurve3, Vector3 } from 'three';
 
 import type {
+  Asset,
   AmbientLightNode,
   LineNode,
   PointLook,
@@ -1067,13 +1068,19 @@ const noJoints: ReadonlyArray<Joint> = [];
 
 /**
  * A physics world. Defaults as react-three-rapier's `Physics`: Earth gravity
- * `[0, -9.81, 0]`, running, fixed steps of 1/60 s, interpolated; no joints.
+ * `[0, -9.81, 0]`, running, fixed steps of 1/60 s, interpolated; no joints; on scene
+ * time rather than `until` a step the Model sets.
  */
 export const physics = (options: Partial<Physics> = {}): Physics => ({
   gravity: options.gravity ?? [0, -9.81, 0],
   paused: options.paused ?? false,
   timeStep: options.timeStep ?? 1 / 60,
   interpolate: options.interpolate ?? true,
+  until: options.until ?? null,
+  run: options.run ?? 0,
+  snapshotAt: options.snapshotAt ?? null,
+  from: options.from ?? null,
+  keep: options.keep ?? 0,
   debug: options.debug ?? false,
   joints: options.joints ?? noJoints,
 });
@@ -1674,6 +1681,38 @@ export const contactShadows = (
 
 const noOverlays: ReadonlyArray<Overlay> = [];
 const noMeasures: ReadonlyArray<string> = [];
+const noAssets: ReadonlyArray<Asset> = [];
+
+/** What an asset builder takes: an id, the finest URL, and coarser ones to show first. */
+type AssetOptions = {
+  readonly id: string;
+  readonly url: string;
+  readonly levels?: ReadonlyArray<string>;
+};
+
+const noLevels: ReadonlyArray<string> = [];
+
+const assetOf =
+  (kind: Asset['kind']) =>
+  ({ id, url, levels }: AssetOptions): Asset => ({ kind, id, url, levels: levels ?? noLevels });
+
+/** A glTF or GLB model for `scene({ assets })`, lent under `id` for `borrowed({ id })`. */
+export const modelAsset = assetOf('model');
+
+/** A colour texture (sRGB) for `scene({ assets })`, lent under `id` for a material's `map`. */
+export const textureAsset = assetOf('texture');
+
+/**
+ * An equirectangular HDR panorama (`.hdr`) for `scene({ assets })`, lent under `id` for
+ * `environment({ map: id })`.
+ */
+export const environmentAsset = assetOf('environment');
+
+/**
+ * A typeface JSON font (three.js's `FontLoader` format) for `scene({ assets })`, lent under
+ * `id` for `text({ font: id })`.
+ */
+export const fontAsset = assetOf('font');
 
 /** Drei's `zIndexRange` default: near points on top, far ones at 0. */
 const defaultZIndexRange: readonly [number, number] = [16777271, 0];
@@ -1730,6 +1769,7 @@ export const scene = (options: {
   readonly physics?: Physics | null;
   readonly xr?: Xr | null;
   readonly measure?: ReadonlyArray<string>;
+  readonly assets?: ReadonlyArray<Asset>;
   readonly render?: RenderSettings;
   readonly resources?: Partial<ResourceDefinitions>;
   readonly children?: ReadonlyArray<SceneNode>;
@@ -1746,6 +1786,7 @@ export const scene = (options: {
   physics: options.physics ?? null,
   xr: options.xr ?? null,
   measure: options.measure ?? noMeasures,
+  assets: options.assets ?? noAssets,
   render: options.render ?? defaultRenderSettings,
   resources: {
     geometries: options.resources?.geometries ?? noResources.geometries,

package/src/kernel/description.ts

@@ -625,12 +625,56 @@ export type Physics = {
   readonly paused: boolean;
   readonly timeStep: number;
   readonly interpolate: boolean;
+  /**
+   * The step the Model lets the world reach, for a simulation that must run alike
+   * wherever it runs (lockstep, replays; ADR-014). The world advances toward it in fixed
+   * steps at scene time's pace (faster when far behind), stops there and reports
+   * `PhysicsReached`; whatever the description changes while it waits applies at that
+   * step, on every peer. Steps count from 0 when the world is made, and the world never
+   * goes back: a lower `until` holds it where it is. `null` (the default): the world runs
+   * on scene time alone, as react-three-rapier's does.
+   */
+  readonly until: number | null;
+  /**
+   * Which run of the simulation this is: a new number throws the world away and starts
+   * another at step 0, for a peer that takes a session's record and replays it, or a
+   * replay starting over. `0` by default.
+   */
+  readonly run: number;
+  /**
+   * A step the world also stops at on its way to `until`, to report there with a
+   * snapshot of itself (`PhysicsReached.snapshot`) for another world to start `from`. It
+   * does not wait there. `null` (the default): no snapshot. An engine that cannot take
+   * one reports there without.
+   */
+  readonly snapshotAt: number | null;
+  /**
+   * Where a run starts: a snapshot and the step it was taken at. The world is made from
+   * it, holding the bodies and joints it held, and counts on from that step, going
+   * straight to `until`; bodies the description has and it lacks are added where
+   * described. Read only when a run starts; `null` (the default): from the description,
+   * at step 0.
+   */
+  readonly from: PhysicsStart | null;
+  /**
+   * How many of its latest stops (each step it reported at) the world keeps a snapshot
+   * of, itself, for a run to start `from` without one in the description: to roll back
+   * a few steps and go again with an input that came late. `0` (the default): none.
+   */
+  readonly keep: number;
   /** Draw every collider and joint as lines, as react-three-rapier's `<Physics debug>`. */
   readonly debug: boolean;
   /** Joints between bodies, each active while both its bodies exist. */
   readonly joints: ReadonlyArray<Joint>;
 };
 
+/**
+ * Where a run starts: the step, and a world's snapshot there (base64, as
+ * `PhysicsReached` carries it), or `null` for the one the world kept at that step itself
+ * (`keep`). A step it did not keep starts from the description, at step 0.
+ */
+export type PhysicsStart = { readonly step: number; readonly snapshot: string | null };
+
 /** A body a joint holds: a node's, or one instance's of an instances node. */
 export type BodyRef = { readonly key: string; readonly instance: string | null };
 
@@ -1426,6 +1470,22 @@ export type XrGlide = {
   readonly snapDegrees: number;
 };
 
+/** What an asset is: a glTF or GLB model, a colour texture, an HDR panorama, a typeface font. */
+export type AssetKind = 'model' | 'texture' | 'environment' | 'font';
+
+/**
+ * An asset a scene asks for: its kind, the id it is lent under once loaded, and where it
+ * comes from. `levels` are coarser versions, coarsest first, to show while `url` (the
+ * finest) is on its way: each is lent as it arrives, if finer than what is shown, and
+ * reported as a level of detail (ADR-015).
+ */
+export type Asset = {
+  readonly kind: AssetKind;
+  readonly id: string;
+  readonly url: string;
+  readonly levels: ReadonlyArray<string>;
+};
+
 export type SceneDescription = {
   readonly camera: Camera;
   /** Whether the scene claims the pointer's gestures from the page. */
@@ -1456,6 +1516,14 @@ export type SceneDescription = {
    * changes: what Drei's `Bounds` measures, for `fitCamera`. Loaded models included.
    */
   readonly measure: ReadonlyArray<string>;
+  /**
+   * Assets the scene asks for, each lent under its id once loaded: a `borrowed({ id })`
+   * node shows a model, a material's `map: id` a texture, `environment({ map: id })` a
+   * panorama and `text({ font: id })` a font. The host loads each once however many
+   * scenes ask, cancels a load no scene asks for any more, and frees an asset when the
+   * last scene stops asking (ADR-015); it reports each as loaded or failed.
+   */
+  readonly assets: ReadonlyArray<Asset>;
   readonly render: RenderSettings;
   readonly resources: ResourceDefinitions;
   readonly children: ReadonlyArray<SceneNode>;

package/src/kernel/equality.ts

@@ -5,6 +5,7 @@
  * @module
  */
 import type {
+  Asset,
   Animation,
   Behave,
   CameraShake,
@@ -690,6 +691,18 @@ export const shaderGridLookEquals = (a: ShaderGridNode, b: ShaderGridNode): bool
   Object.is(a.fadeFrom, b.fadeFrom) &&
   a.side === b.side;
 
+const assetEquals = (a: Asset, b: Asset | undefined): boolean =>
+  b !== undefined &&
+  a.kind === b.kind &&
+  a.id === b.id &&
+  a.url === b.url &&
+  a.levels.length === b.levels.length &&
+  a.levels.every((level, i) => level === b.levels[i]);
+
+/** Asset list equality: the same kinds, ids, urls and levels, in the same order. */
+export const assetsEqual = (a: ReadonlyArray<Asset>, b: ReadonlyArray<Asset>): boolean =>
+  a === b || (a.length === b.length && a.every((asset, i) => assetEquals(asset, b[i])));
+
 /** Physics world equality. */
 export const physicsEquals = (a: Physics | null, b: Physics | null): boolean =>
   a === b ||
@@ -699,6 +712,15 @@ export const physicsEquals = (a: Physics | null, b: Physics | null): boolean =>
     a.paused === b.paused &&
     Object.is(a.timeStep, b.timeStep) &&
     a.interpolate === b.interpolate &&
+    a.until === b.until &&
+    a.run === b.run &&
+    a.snapshotAt === b.snapshotAt &&
+    a.keep === b.keep &&
+    (a.from === b.from ||
+      (a.from !== null &&
+        b.from !== null &&
+        a.from.step === b.from.step &&
+        a.from.snapshot === b.from.snapshot)) &&
     a.debug === b.debug &&
     jointsEqual(a.joints, b.joints));