@volter/editor-core 0.5.57

package/src/authoring/design-time-mount-registry.ts

@@ -0,0 +1,235 @@
+/**
+ * A DESIGN-TIME MOUNT IS REGISTERED, NOT DISPATCHED — the fifth registry in
+ * the family of `workspace-document-restore.ts` (a kind owns its persisted
+ * state), `document-open-registry.ts` (a kind owns how it opens),
+ * `chrome-slot-registry.ts` (the host owns the place, a package owns what
+ * sits there) and `content-entry-source-registry.ts` (the host owns the
+ * Content scope, a package owns why a component is content). Here: the host
+ * owns the design-time layer STACK and a package owns how a medium MOUNTS
+ * into it.
+ *
+ * WHY IT EXISTS. `design-time-layers.ts` dispatched the two media in ONE
+ * expression — `candidate.kind === 'canvas' ? mountCanvasLayer(…) :
+ * mountReactLayer(…)` — against a single `LayerMountResult` contract whose
+ * own docblock said the failure/teardown/play lifecycle is "the SAME for both
+ * media". A contract two implementations already share, chosen by a literal
+ * the host spells, is a registry that has not been written yet. Past the
+ * dispatch it hard-coded two more per-medium facts: canvas REMOUNTS when a
+ * write lands with no HMR channel, dom RE-PROJECTS when the story registry
+ * publishes, and canvas layers are always interactive because the 2D scene IS
+ * the document's subject. Each is a statement about a MEDIUM, made in the
+ * host (WORK.md §The open-source launch item 12, §Stories leave the host edge
+ * 9).
+ *
+ * THE SHAPE is transcribed from `content-entry-source-registry.ts:96-134`:
+ * register / list / subscribe, with the same owner-replaces-owner rule so an
+ * HMR re-evaluation leaves one mount and not two. Two deliberate differences,
+ * each with its reason:
+ *
+ *  - NO VERSION COUNTER. That registry publishes one because a React panel
+ *    reads it through `useSyncExternalStore`; this one's only reader is the
+ *    layer stack, which subscribes and re-reads. A counter with no caller is
+ *    a name that gets built because it was named.
+ *  - THE INVALIDATION HOOKS ARE NOT RE-FANNED into `subscribeDesignTimeMounts`
+ *    (the content registry re-fans its sources' `subscribe` into one signal).
+ *    A staleness signal is not a registration change: it must reach the ONE
+ *    layer stack that mounted that medium, carrying which action to take
+ *    (remount, which tears down first, or re-project, which keeps the old
+ *    layer up until the new one settles). The stack binds them itself, per
+ *    mount, and unbinds on teardown.
+ *
+ * WHAT THE HOST STILL OWNS, and why it is not a leak: the layer ELEMENT and
+ * everything about its place in the stack — the mount epoch that supersedes
+ * an in-flight mount, the z-order, the pan transform, the eye, the play
+ * handoff and Stop's rebuild, and the `BoundaryAuthoringAdapter` disclosure a
+ * failed or unregistered mount degrades to. A mount is handed a layer and
+ * asked to fill it; it never decides when it exists.
+ *
+ * NOTHING REGISTERED IS A REAL ANSWER. A build whose package list carries no
+ * mount for a medium leaves that world's Boundary node standing with a reason
+ * that names the kind and says no package registered a mount for it — the
+ * same honest emptiness a document kind with no registered opener gives, and
+ * the reason the stack waits rather than fails: contributions load
+ * asynchronously (`project-tool-discovery.ts` defers the pass behind the
+ * first viewport frame), so "not registered yet" and "not registered at all"
+ * are different answers and only the second is worth showing.
+ */
+
+import type * as THREE from 'three';
+import type { EditorShellStore } from '../editor-shell-store';
+import type { CompositeAuthoringAdapter } from './composite-authoring-adapter';
+import type { DesignTimeRootDescriptor, LayerMountResult } from './design-time-layers';
+import type { RootViewController } from './world-pan-state';
+
+/**
+ * Everything a mount reads from the HOST, and deliberately nothing more — the
+ * stack does not hand over itself. Measured against the two mount functions
+ * as they stood: `mountReactLayer` read the project root, the shell store and
+ * the activation document id; `mountCanvasLayer` read those three plus the
+ * presentation's view controller.
+ */
+export interface DesignTimeMountContext {
+  /** The open project's absolute root path — resolved once by the stack, and
+   *  the reason it refuses to mount anything when there is no project. */
+  readonly projectRootPath: string;
+  /** The ONE format-neutral shell store (selection, history handle, play
+   *  state) every authoring adapter is constructed against. */
+  readonly store: EditorShellStore;
+  /** Present only when the document this layer belongs to presents its own
+   *  independent editor camera and viewport renderer rather than the shared
+   *  artboard (`mountDesignTimeLayers`' `presentation`). A mount that has no
+   *  camera of its own ignores it. */
+  readonly view?: RootViewController;
+  /** When set, first-mount work writes named segments onto this document's
+   *  activation clock (`viewport-activation-timings`). */
+  readonly activationDocumentId?: string;
+}
+
+/**
+ * A medium that mounts into a LAYER of the design-time stack, over the shared
+ * artboard: `dom` and `canvas`.
+ */
+export type DesignTimeLayerKind = DesignTimeRootDescriptor['kind'];
+
+/**
+ * A medium that mounts onto the WORLD ROOT's 3D stage instead of into a layer
+ * over it: `three`. Its design session adopts the stage's own renderer and
+ * scene rather than being handed an element to fill — the same question ("how
+ * does this medium mount at design time?"), answered on a different surface,
+ * which is why it is this registry's second shape and not a second registry.
+ */
+export type DesignTimeStageKind = 'three';
+
+export type DesignTimeMountKind = DesignTimeLayerKind | DesignTimeStageKind;
+
+/** What every registration carries, whichever surface it mounts on. */
+interface DesignTimeMountBase {
+  /** The medium this mounts, in the descriptor's own vocabulary. */
+  readonly kind: DesignTimeMountKind;
+  /** Which module registered it. Re-registering the same owner+kind REPLACES,
+   *  so an HMR re-evaluation leaves one mount, not two. */
+  readonly owner: string;
+  /**
+   * This medium's mounted worlds are STALE and must be torn down and mounted
+   * again from current source. The mount owns the condition (which tier, which
+   * watch, which debounce); the stack owns whether it may act right now (not
+   * while play is running, not after teardown). Returns its teardown.
+   */
+  readonly remountWhen?: (invalidate: () => void) => () => void;
+  /**
+   * The same staleness, for a medium that can mount the NEW world before
+   * taking the old one down — no visible reload flash. Returns its teardown.
+   */
+  readonly reprojectWhen?: (invalidate: () => void) => () => void;
+}
+
+export interface DesignTimeLayerMount extends DesignTimeMountBase {
+  readonly kind: DesignTimeLayerKind;
+  /** The resolved adapter identity a mount failure is reported under
+   *  (`MountFailureReport['identity']`, e.g. `default-react`/`default-pixi`).
+   *  It lives here because it is a fact about the mount; the host used to
+   *  spell both literals in its own catch block. */
+  readonly identity: string;
+  /** This medium's layer always forwards pointer events: its content IS the
+   *  document's subject (a click on it is how you select in it), so the
+   *  `interactive` toggle — which exists for a medium whose design-time
+   *  hover/press testing competes with authoring gestures — does not apply. */
+  readonly alwaysInteractive?: boolean;
+  /**
+   * Fill `layer` with this medium's design-time world and report what the
+   * stack should publish for it. Throwing is the sanctioned failure: the
+   * stack degrades that world to its Boundary disclosure node with the
+   * thrown message, exactly as it always did.
+   */
+  readonly mount: (
+    candidate: DesignTimeRootDescriptor,
+    layer: HTMLElement,
+    context: DesignTimeMountContext,
+  ) => Promise<LayerMountResult>;
+}
+
+/** Everything the world root's stage hands its medium's design session. It is
+ *  the stage's own three handles: nothing here is a layer, a candidate or a
+ *  project path, because the session resolves its world from the manifest
+ *  itself. Measured against `mountR3FDesignSession` as it stood. */
+export interface WorldRootSessionContext {
+  /** The ONE format-neutral shell store the session's adapter is built over. */
+  readonly store: EditorShellStore;
+  /** The edit-mode composite the session swaps its own child adapter into. */
+  readonly composite: CompositeAuthoringAdapter;
+  /** The stage's renderer — the session adopts it rather than building one. */
+  readonly renderer: THREE.WebGLRenderer;
+}
+
+export interface DesignTimeStageMount extends DesignTimeMountBase {
+  readonly kind: DesignTimeStageKind;
+  /**
+   * Mount this medium's design session onto the world root's stage. Returns
+   * its teardown. Throwing is the sanctioned failure, the same as a layer
+   * mount's.
+   */
+  readonly mountWorldRootSession: (context: WorldRootSessionContext) => Promise<() => void>;
+}
+
+export type DesignTimeMount = DesignTimeLayerMount | DesignTimeStageMount;
+
+const _mounts: DesignTimeMount[] = [];
+const listeners = new Set<() => void>();
+
+function publish(): void {
+  for (const listener of listeners) listener();
+}
+
+/** Install a mount for one medium. Returns the teardown. */
+export function registerDesignTimeMount(mount: DesignTimeMount): () => void {
+  const stale = _mounts.findIndex((item) => item.owner === mount.owner && item.kind === mount.kind);
+  if (stale >= 0) _mounts.splice(stale, 1);
+  _mounts.push(mount);
+  publish();
+  return () => {
+    const at = _mounts.indexOf(mount);
+    if (at < 0) return;
+    _mounts.splice(at, 1);
+    publish();
+  };
+}
+
+const EMPTY: readonly DesignTimeMount[] = [];
+
+/** Everything registered, in registration order. A stable array while nothing
+ *  changes, so a reader can compare identities across a notification. */
+export function designTimeMounts(): readonly DesignTimeMount[] {
+  return _mounts.length === 0 ? EMPTY : _mounts;
+}
+
+/** The mount for one medium, or `null` — "no package registered one", which
+ *  is a real answer and never an error. The LAST registration wins, the same
+ *  way a later chrome-slot filler of the same order does. The overloads are
+ *  how a caller that knows its surface gets the shape that surface mounts
+ *  with, without narrowing at the call site. */
+export function designTimeMountFor(kind: DesignTimeLayerKind): DesignTimeLayerMount | null;
+export function designTimeMountFor(kind: DesignTimeStageKind): DesignTimeStageMount | null;
+export function designTimeMountFor(kind: DesignTimeMountKind): DesignTimeMount | null;
+export function designTimeMountFor(kind: DesignTimeMountKind): DesignTimeMount | null {
+  for (let i = _mounts.length - 1; i >= 0; i--) {
+    const mount = _mounts[i];
+    if (mount && mount.kind === kind) return mount;
+  }
+  return null;
+}
+
+/** Registration changes only. A mounted layer's own staleness travels through
+ *  that mount's `remountWhen`/`reprojectWhen` instead — see the module note. */
+export function subscribeDesignTimeMounts(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/** Test-only reset (mirrors the restore, open, chrome-slot and content-source
+ *  registries'). */
+export function __resetDesignTimeMountsForTest(): void {
+  _mounts.length = 0;
+  publish();
+}

package/src/authoring/design-time-settle.ts

@@ -0,0 +1,343 @@
+/**
+ * THE DESIGN-TIME SETTLE, and the only place its constants are spelled.
+ *
+ * This is deliberately NOT an interactive-document boot step. Scene and Asset
+ * Lab documents show authored state immediately and advance content only when
+ * the user starts an explicit simulation or animation transport. A hidden
+ * settle before reveal violated Edit ≠ Play and made a complex local scene wait
+ * up to four seconds for construction quiescence plus 90 invisible steps.
+ *
+ * The remaining callers are deliberate off-screen preview/capture operations
+ * that ask for a derived rest pose. That is why {@link settleDesignWorld} takes
+ * a {@link SettleTarget} rather than a viewport type: the seam is "a world with
+ * a host-driven tick," while the caller owns the decision to simulate.
+ *
+ * **The settle is a PURE FUNCTION OF SOURCE.** It never reads accumulated
+ * state, never persists a result, and is never a second truth beside the
+ * source: every mount re-derives the world from the file and re-runs the same
+ * bounded simulation from the same authored spawn. That is what makes the two
+ * interaction contracts hold — a gizmo commit writes the JSX literal, the
+ * session re-derives from source, and the settle re-runs from the EDIT's
+ * position (the edit wins, nothing snaps back); and two mounts of identical
+ * source produce the same rest state.
+ *
+ * ## THE SEAM IT DRIVES, and why it is not a physics API
+ *
+ * `MountedThreeRoot.update(dt)` — the world's own host-driven tick, the exact
+ * one `runFrameImpl` (`@vgai/game-runtime/runtime/game`) calls at play time. For an R3F
+ * world that is `world3d-react/r3f-adapter.tsx`'s `update()`: it runs the
+ * engine phases and then `advance(elapsed, true, state)`, which under
+ * `frameloop: 'never'` is what runs every `useFrame` subscriber.
+ *
+ * A physics integration is one of those subscribers, so driving `update()`
+ * drives the world's physics THROUGH THE WORLD'S OWN DECLARATION — including
+ * whatever gravity/iterations/solver props its own `<Physics>` element
+ * carries. Worked example, `@react-three/cannon@6.6.0`: its provider registers
+ * `useFrame(loop)` (`node_modules/@react-three/cannon/dist/index.js:12166`)
+ * and `loop` posts `worker.step({ maxSubSteps, stepSize, timeSinceLastCalled })`
+ * (`:12032`) to its own Web Worker. Nothing here knows any of that, and
+ * nothing here should: the editor reaching for a named physics library's step
+ * API would be an editor that only settles the physics engines it has heard
+ * of.
+ *
+ * ## WHY IT IS ASYNC, and why it steps in ROUNDS
+ *
+ * That worker is OFF-THREAD. `worker.step()` posts a message; the resulting
+ * pose arrives on a later task and is applied to `object.matrix` from the
+ * worker's own `frame` handler (`:12120`). A synchronous burst of `update()`
+ * calls would therefore measure nothing but the spawn pose. So the settle
+ * yields to the event loop, and it does so once per ROUND of
+ * {@link SETTLE_STEPS_PER_ROUND} steps rather than once per step: the worker
+ * queue is FIFO, so a round's steps pipeline and its frames land together,
+ * which costs one event-loop turn per round instead of one per step.
+ *
+ * ## WHY REST IS ONLY DECLARED AFTER MOTION
+ *
+ * The naive rest test — "the scene did not move this round, so we are done" —
+ * is TRUE at round one for the exact reason the settle exists: an off-thread
+ * physics engine has not answered yet, so nothing has moved YET. Declaring
+ * rest there would settle to the spawn pose and call it a rest state. Rest is
+ * therefore gated on having OBSERVED motion first; a world that never moves
+ * under simulation ends at {@link SETTLE_MAX_ROUNDS} with reason `'still'`,
+ * which costs it that many event-loop turns and nothing else.
+ *
+ * Non-finite poses are the same class of not-yet-answered and are handled the
+ * same way: `@react-three/cannon` writes `object.matrix` from worker buffers
+ * that are unwritten at frame zero, so two of racing-game's meshes are
+ * measurably `NaN` before the first frame lands (see `content-bounds.ts`'s own
+ * measurement of exactly this). A round whose sample is non-finite is
+ * NOT COMPARABLE: it resets the rest run and is never counted as motion.
+ */
+
+import type * as THREE from 'three';
+
+/**
+ * What a settle needs from a world, and nothing more: the graph to measure and
+ * the world's OWN host-driven tick to advance. `MountedThreeRoot` satisfies it
+ * structurally, and so does every other design-time surface's source (a story
+ * mount's `advance`, a project contribution's `build().update`) — which is the
+ * point: one settle, one shape, no per-surface copy.
+ */
+export interface SettleTarget {
+  /** The subtree whose motion is measured. A whole `THREE.Scene` for a mounted
+   *  root; a story's own wrapper group for an off-screen story mount. */
+  readonly scene: THREE.Object3D;
+  /** The world's own tick. Absent ⇒ nothing to advance (`'unsupported'`). */
+  readonly update?: ((dt: number) => void) | undefined;
+  /**
+   * Whether this mount has an off-thread physics stepper subscribed (a
+   * `<Physics>` provider, a cannon worker, a first-party adapter).
+   *
+   * The quiet-wait and still-rounds exist because that stepper is SILENT at
+   * spawn: declaring rest before it answers would freeze a vehicle at a pose
+   * the game never has. A tree, a jump pad, a mesh with no physics has
+   * nothing that can move later, so both waits are wasted — pass `false` and
+   * the settle returns immediately. Omitted is the SAFE default (settle):
+   * callers that have not looked must not skip a rigid body.
+   */
+  readonly hasPhysicsSubscriber?: boolean;
+}
+
+/** The simulated timestep each settle step advances — the engine's own fixed
+ *  timestep (`core/game-loop.ts`'s `fixedTimestep ?? 1/60`), so a settle step
+ *  is the same quantum a play frame is. */
+export const SETTLE_STEP_SECONDS = 1 / 60;
+
+/** Steps advanced between event-loop yields. 6 steps = 0.1 simulated second —
+ *  enough that an off-thread physics worker's frames for the round have
+ *  something to show, small enough that rest is detected within 0.1s of it
+ *  happening. */
+export const SETTLE_STEPS_PER_ROUND = 6;
+
+/** Hard budget: 15 rounds = 90 steps = **1.5 simulated seconds**. A body
+ *  dropped onto its own suspension or resolved out of an interpenetration
+ *  reaches rest well inside that; a world that is still moving at 1.5s is
+ *  animating rather than settling, and Edit mode owes it a freeze, not a
+ *  longer run. */
+export const SETTLE_MAX_ROUNDS = 15;
+
+/** Rest threshold: world units moved by the FASTEST-moving node across one
+ *  round. 1e-4 units per 0.1s is 1 millimetre per second in a metres-scaled
+ *  world — below it, nothing a viewer or a capture can distinguish is
+ *  happening. */
+export const SETTLE_REST_EPSILON = 1e-4;
+
+/** Consecutive quiet rounds required before rest is declared, so a body
+ *  pausing at the top of a bounce is not mistaken for a rest state. */
+export const SETTLE_REST_ROUNDS = 2;
+
+/** After the last step, event-loop turns awaited for an off-thread physics
+ *  engine's in-flight frames to land. This is what makes "then FREEZES" true
+ *  rather than asserted: the settle does not return while a pose it caused is
+ *  still on its way. */
+export const SETTLE_DRAIN_TURNS = 10;
+
+/**
+ * How long the scene graph must stop CHANGING SHAPE before the settle starts
+ * stepping, and the hard ceiling on waiting for that.
+ *
+ * WHY THIS EXISTS, measured. A world's `mount()` resolves at fiber's first
+ * commit, which is NOT the end of construction: suspended asset loads
+ * (racing-game's Draco chassis/track GLBs and its HDR environment) add nodes —
+ * including physics bodies — for as long as they take. Step the world during
+ * that window and a body created at round 3 gets 12 fewer steps than one
+ * created at round 0, so the SAME source settles differently depending on how
+ * warm the HTTP cache was. Measured directly: two boots of unchanged
+ * racing-game source produced chassis Y = 0.7549 and 0.7927.
+ *
+ * So the settle waits for the world to stop being BUILT before it simulates.
+ * Node count is the signal (an asset resolving adds nodes; a texture arriving
+ * does not change the count and does not change physics either). Both bounds
+ * are wall-clock because what is being waited on is I/O, not frames.
+ */
+export const SETTLE_BUILD_STABLE_MS = 250;
+export const SETTLE_BUILD_TIMEOUT_MS = 4000;
+
+/** Why the settle ended. */
+export type SettleOutcome =
+  /** The world moved and then came to rest. */
+  | 'rest'
+  /** The world was still moving when the step budget ran out. */
+  | 'budget'
+  /** Nothing in the world ever moved under simulation. */
+  | 'still'
+  /** The world is not host-driven — there is no `update(dt)` to advance. */
+  | 'unsupported';
+
+export interface SettleReport {
+  readonly outcome: SettleOutcome;
+  /** Simulation steps actually advanced. */
+  readonly steps: number;
+  /** World units the fastest node moved across the final measured round. */
+  readonly lastMotion: number;
+  /** Milliseconds spent waiting for the world to stop being BUILT, and whether
+   *  that wait ended because the graph went quiet (`true`) or because it hit
+   *  {@link SETTLE_BUILD_TIMEOUT_MS} (`false` — the settle then runs against a
+   *  world still loading, and its result is honestly not reproducible). */
+  readonly buildWaitMs: number;
+  readonly buildSettled: boolean;
+}
+
+/** Injectables. Real callers pass nothing; a test drives the loop and the
+ *  clock so the wall-clock bounds above cost it no wall clock. */
+export interface SettleHooks {
+  yieldTurn?: () => Promise<void>;
+  now?: () => number;
+}
+
+/** Every node's world position, flattened. Length changes (an async model
+ *  resolving mid-settle) make two samples NOT COMPARABLE, which is the honest
+ *  answer rather than a wrong distance. */
+function samplePositions(scene: THREE.Object3D): number[] {
+  scene.updateMatrixWorld(true);
+  const out: number[] = [];
+  scene.traverse((object) => {
+    const e = object.matrixWorld.elements;
+    out.push(e[12] as number, e[13] as number, e[14] as number);
+  });
+  return out;
+}
+
+/** How many nodes the world currently has — the build-quiesce signal. */
+function countNodes(scene: THREE.Object3D): number {
+  let n = 0;
+  scene.traverse(() => {
+    n++;
+  });
+  return n;
+}
+
+/**
+ * The largest distance any node moved between two samples, or `NaN` when the
+ * two are not comparable (different node counts, or a pose that is not a
+ * number yet).
+ */
+function maxMotion(before: number[], after: number[]): number {
+  if (before.length !== after.length) return Number.NaN;
+  let max = 0;
+  for (let i = 0; i < after.length; i += 3) {
+    const dx = (after[i] as number) - (before[i] as number);
+    const dy = (after[i + 1] as number) - (before[i + 1] as number);
+    const dz = (after[i + 2] as number) - (before[i + 2] as number);
+    const d = Math.sqrt(dx * dx + dy * dy + dz * dz);
+    if (!Number.isFinite(d)) return Number.NaN;
+    if (d > max) max = d;
+  }
+  return max;
+}
+
+/** One event-loop turn — a MACROtask, because an off-thread worker's message
+ *  cannot land in a microtask drain. */
+const nextTurn = (): Promise<void> => new Promise((resolve) => setTimeout(resolve, 0));
+
+/**
+ * Block until the world's node count has held still for
+ * {@link SETTLE_BUILD_STABLE_MS}, or {@link SETTLE_BUILD_TIMEOUT_MS} runs out.
+ * See those constants for the measurement that put this phase here.
+ */
+async function awaitConstructionQuiesced(
+  scene: THREE.Object3D,
+  yieldTurn: () => Promise<void>,
+  now: () => number,
+): Promise<{ buildWaitMs: number; buildSettled: boolean }> {
+  const start = now();
+  let nodes = countNodes(scene);
+  let quietSince = start;
+  let buildSettled = false;
+  while (now() - start < SETTLE_BUILD_TIMEOUT_MS) {
+    if (now() - quietSince >= SETTLE_BUILD_STABLE_MS) {
+      buildSettled = true;
+      break;
+    }
+    await yieldTurn();
+    const next = countNodes(scene);
+    if (next !== nodes) {
+      nodes = next;
+      quietSince = now();
+    }
+  }
+  return { buildWaitMs: now() - start, buildSettled };
+}
+
+function idleSettleReport(outcome: 'unsupported' | 'still'): SettleReport {
+  return { outcome, steps: 0, lastMotion: 0, buildWaitMs: 0, buildSettled: true };
+}
+
+/**
+ * The narrow skip: no physics subscriber means nothing can move after spawn,
+ * so the construction quiet-wait and the still-rounds are both wasted. Omitted
+ * is treated as "yes, settle" — a caller that has not looked must not skip a
+ * rigid body. The predicate lives here so a revert (always-skip, or treating
+ * omitted as skip) reds the physics rest test.
+ */
+export function designWorldHasPhysicsSubscriber(root: SettleTarget): boolean {
+  return root.hasPhysicsSubscriber !== false;
+}
+
+/**
+ * Derive a rest pose for a caller that explicitly requested one, then leave the
+ * world frozen. Advances the world's OWN `update(dt)` — see this module's
+ * header for why that is the seam and why the loop is shaped the way it is.
+ */
+export async function settleDesignWorld(
+  root: SettleTarget,
+  hooks: SettleHooks = {},
+): Promise<SettleReport> {
+  const yieldTurn = hooks.yieldTurn ?? nextTurn;
+  const now = hooks.now ?? (() => Date.now());
+  const update = root.update?.bind(root);
+  if (!update) return idleSettleReport('unsupported');
+  if (!designWorldHasPhysicsSubscriber(root)) return idleSettleReport('still');
+
+  // ---- 1. wait for the world to stop being BUILT
+  const { buildWaitMs, buildSettled } = await awaitConstructionQuiesced(root.scene, yieldTurn, now);
+
+  // ---- 2. the bounded settle itself
+  let previous = samplePositions(root.scene);
+  let steps = 0;
+  let quietRounds = 0;
+  let observedMotion = false;
+  let lastMotion = 0;
+  let outcome: SettleOutcome = 'still';
+
+  for (let round = 0; round < SETTLE_MAX_ROUNDS; round++) {
+    for (let step = 0; step < SETTLE_STEPS_PER_ROUND; step++) {
+      update(SETTLE_STEP_SECONDS);
+      steps++;
+    }
+    await yieldTurn();
+    const current = samplePositions(root.scene);
+    const motion = maxMotion(previous, current);
+    previous = current;
+    if (!Number.isFinite(motion)) {
+      // Not comparable — the world is mid-answer. Never rest, never motion.
+      quietRounds = 0;
+      continue;
+    }
+    lastMotion = motion;
+    if (motion > SETTLE_REST_EPSILON) {
+      observedMotion = true;
+      quietRounds = 0;
+      outcome = 'budget';
+      continue;
+    }
+    quietRounds++;
+    if (observedMotion && quietRounds >= SETTLE_REST_ROUNDS) {
+      outcome = 'rest';
+      break;
+    }
+  }
+
+  // ---- 3. FREEZE. Nothing is stepped from here; the drain only waits out
+  // poses this settle already caused, so the scene the editor draws from now
+  // on is a real rest state rather than one still being written into.
+  for (let turn = 0; turn < SETTLE_DRAIN_TURNS; turn++) {
+    await yieldTurn();
+    const current = samplePositions(root.scene);
+    const motion = maxMotion(previous, current);
+    previous = current;
+    if (Number.isFinite(motion) && motion <= SETTLE_REST_EPSILON) break;
+  }
+
+  return { outcome, steps, lastMotion, buildWaitMs, buildSettled };
+}