@driftengine/physics 3.61.0

package/src/island.ts

@@ -0,0 +1,219 @@
+import { BODY_DYNAMIC } from './bodies.ts';
+import type { BodySet } from './bodies.ts';
+import type { JointSet } from './joints.ts';
+import type { ContactConstraints } from './solver.ts';
+
+/**
+ * Connected components of the contact graph, and the sleeping that rides on them.
+ *
+ * **Only dynamic bodies join islands.** A static floor touches everything standing on it, so
+ * letting it merge would make one island of the whole world and nothing would ever sleep. That is
+ * not an optimisation: it is what an island *means*, and it is why two towers on one floor are two.
+ *
+ * **A body with no contacts is a singleton island**, so every dynamic body belongs to exactly one
+ * and the executor can own the whole substep loop for it rather than integration being a separate
+ * global pass. That is the shape a worker pool needs.
+ *
+ * **Islands are ordered by their lowest body index, and bodies within one by index.** That comes
+ * from the *ascending scan* below, which numbers an island the first time it meets a member — not
+ * from union-find's root choice, which is why swapping the root to the larger index changes no
+ * result and no test catches it. Keeping the smaller one is convention and shortens paths a little;
+ * nothing depends on it. Nothing here iterates a `Map` or a `Set`.
+ */
+
+export class IslandSet {
+  /** How many islands the last build found. */
+  count = 0;
+  /** Constraint indices grouped by island. */
+  constraintOrder: Int32Array;
+  /** Offsets into `constraintOrder`, length `count + 1`. */
+  constraintStart: Int32Array;
+  /** Dynamic body indices grouped by island. */
+  bodyOrder: Int32Array;
+  /** Offsets into `bodyOrder`, length `count + 1`. */
+  bodyStart: Int32Array;
+  /** Which island a body is in, or −1 for a body that is not dynamic. */
+  islandOf: Int32Array;
+
+  private parent: Int32Array;
+  private islandIndex: Int32Array;
+
+  constructor(capacity = 64) {
+    this.constraintOrder = new Int32Array(capacity);
+    this.constraintStart = new Int32Array(capacity + 1);
+    this.bodyOrder = new Int32Array(capacity);
+    this.bodyStart = new Int32Array(capacity + 1);
+    this.islandOf = new Int32Array(capacity);
+    this.parent = new Int32Array(capacity);
+    this.islandIndex = new Int32Array(capacity);
+  }
+
+  /** Joint indices grouped by island. */
+  jointOrder: Int32Array = new Int32Array(32);
+  /** Offsets into `jointOrder`, length `count + 1`. */
+  jointStart: Int32Array = new Int32Array(33);
+
+  build(bodies: BodySet, c: ContactConstraints, joints: JointSet): number {
+    const n = bodies.count;
+    this.ensureBodies(n);
+    this.ensureConstraints(c.count);
+
+    for (let i = 0; i < n; i++) this.parent[i] = i;
+    for (let k = 0; k < c.count; k++) {
+      const a = c.bodyA[k] ?? 0;
+      const b = c.bodyB[k] ?? 0;
+      if (bodies.type[a] !== BODY_DYNAMIC || bodies.type[b] !== BODY_DYNAMIC) continue;
+      this.union(a, b);
+    }
+    /*
+     * A joint is an edge in the same graph a contact is. Two bodies held together would otherwise
+     * sleep independently and be woken independently, and a jointed pair whose halves disagree
+     * about being asleep pulls apart.
+     */
+    for (let k = 0; k < joints.count; k++) {
+      if (joints.broken[k]) continue;
+      const a = joints.bodyA[k] ?? 0;
+      const b = joints.bodyB[k] ?? 0;
+      if (bodies.type[a] !== BODY_DYNAMIC || bodies.type[b] !== BODY_DYNAMIC) continue;
+      this.union(a, b);
+    }
+
+    // Roots in ascending order become islands 0, 1, 2 …, so ordering follows body index.
+    let islands = 0;
+    for (let i = 0; i < n; i++) {
+      this.islandOf[i] = -1;
+      this.islandIndex[i] = -1;
+    }
+    for (let i = 0; i < n; i++) {
+      if (bodies.type[i] !== BODY_DYNAMIC) continue;
+      const root = this.find(i);
+      if (this.islandIndex[root] < 0) this.islandIndex[root] = islands++;
+      this.islandOf[i] = this.islandIndex[root] ?? -1;
+    }
+    this.count = islands;
+    if (islands + 1 > this.bodyStart.length) {
+      this.bodyStart = new Int32Array(islands + 1);
+      this.constraintStart = new Int32Array(islands + 1);
+    }
+
+    // Counting sort of bodies into islands: count, prefix, place.
+    this.bodyStart.fill(0);
+    for (let i = 0; i < n; i++) {
+      const island = this.islandOf[i] ?? -1;
+      if (island >= 0) this.bodyStart[island + 1]++;
+    }
+    for (let i = 0; i < islands; i++) {
+      this.bodyStart[i + 1] = (this.bodyStart[i + 1] ?? 0) + (this.bodyStart[i] ?? 0);
+    }
+    const bodyAt = new Int32Array(islands);
+    for (let i = 0; i < n; i++) {
+      const island = this.islandOf[i] ?? -1;
+      if (island < 0) continue;
+      this.bodyOrder[(this.bodyStart[island] ?? 0) + (bodyAt[island] ?? 0)] = i;
+      bodyAt[island]++;
+    }
+
+    // And of constraints, by whichever of their bodies is dynamic.
+    this.constraintStart.fill(0);
+    for (let k = 0; k < c.count; k++) {
+      const island = this.islandOfConstraint(bodies, c, k);
+      if (island >= 0) this.constraintStart[island + 1]++;
+    }
+    for (let i = 0; i < islands; i++) {
+      this.constraintStart[i + 1] =
+        (this.constraintStart[i + 1] ?? 0) + (this.constraintStart[i] ?? 0);
+    }
+    const conAt = new Int32Array(islands);
+    for (let k = 0; k < c.count; k++) {
+      const island = this.islandOfConstraint(bodies, c, k);
+      if (island < 0) continue;
+      this.constraintOrder[(this.constraintStart[island] ?? 0) + (conAt[island] ?? 0)] = k;
+      conAt[island]++;
+    }
+    // And of joints, the same way.
+    if (islands + 1 > this.jointStart.length) this.jointStart = new Int32Array(islands + 1);
+    if (joints.count > this.jointOrder.length) {
+      let size = this.jointOrder.length || 1;
+      while (size < joints.count) size *= 2;
+      this.jointOrder = new Int32Array(size);
+    }
+    this.jointStart.fill(0);
+    for (let k = 0; k < joints.count; k++) {
+      const island = this.islandOfJoint(bodies, joints, k);
+      if (island >= 0) this.jointStart[island + 1]++;
+    }
+    for (let i = 0; i < islands; i++) {
+      this.jointStart[i + 1] = (this.jointStart[i + 1] ?? 0) + (this.jointStart[i] ?? 0);
+    }
+    const jointAt = new Int32Array(islands);
+    for (let k = 0; k < joints.count; k++) {
+      const island = this.islandOfJoint(bodies, joints, k);
+      if (island < 0) continue;
+      this.jointOrder[(this.jointStart[island] ?? 0) + (jointAt[island] ?? 0)] = k;
+      jointAt[island]++;
+    }
+    return islands;
+  }
+
+  private islandOfJoint(bodies: BodySet, joints: JointSet, k: number): number {
+    if (joints.broken[k]) return -1;
+    const a = joints.bodyA[k] ?? 0;
+    const b = joints.bodyB[k] ?? 0;
+    if (bodies.type[a] === BODY_DYNAMIC) return this.islandOf[a] ?? -1;
+    if (bodies.type[b] === BODY_DYNAMIC) return this.islandOf[b] ?? -1;
+    return -1;
+  }
+
+  private islandOfConstraint(bodies: BodySet, c: ContactConstraints, k: number): number {
+    const a = c.bodyA[k] ?? 0;
+    const b = c.bodyB[k] ?? 0;
+    if (bodies.type[a] === BODY_DYNAMIC) return this.islandOf[a] ?? -1;
+    if (bodies.type[b] === BODY_DYNAMIC) return this.islandOf[b] ?? -1;
+    return -1;
+  }
+
+  /**
+   * The smaller index wins, which shortens paths slightly and is otherwise arbitrary.
+   *
+   * **It is not what orders islands** — the ascending scan in `build` is. Said here because the
+   * version of this comment that claimed otherwise sent a reader looking for a property the code
+   * does not have and does not need.
+   */
+  private union(a: number, b: number): void {
+    const ra = this.find(a);
+    const rb = this.find(b);
+    if (ra === rb) return;
+    if (ra < rb) this.parent[rb] = ra;
+    else this.parent[ra] = rb;
+  }
+
+  private find(i: number): number {
+    let root = i;
+    while ((this.parent[root] ?? root) !== root) root = this.parent[root] ?? root;
+    // Path compression, so a long chain is walked once.
+    let at = i;
+    while ((this.parent[at] ?? at) !== at) {
+      const next = this.parent[at] ?? at;
+      this.parent[at] = root;
+      at = next;
+    }
+    return root;
+  }
+
+  private ensureBodies(n: number): void {
+    if (n <= this.parent.length) return;
+    let size = this.parent.length || 1;
+    while (size < n) size *= 2;
+    this.parent = new Int32Array(size);
+    this.islandOf = new Int32Array(size);
+    this.islandIndex = new Int32Array(size);
+    this.bodyOrder = new Int32Array(size);
+  }
+
+  private ensureConstraints(n: number): void {
+    if (n <= this.constraintOrder.length) return;
+    let size = this.constraintOrder.length || 1;
+    while (size < n) size *= 2;
+    this.constraintOrder = new Int32Array(size);
+  }
+}

package/src/islandSolve.ts

@@ -0,0 +1,218 @@
+/**
+ * One island's substep loop, as a function over flat state, so a worker can run the same one.
+ *
+ * **This exists because `PhysicsWorld` cannot cross a realm boundary and an island's solve can.**
+ * The world holds `ConvexShape` objects, a `DynamicTree` and a `Map` of warm impulses, none of which
+ * a `SharedArrayBuffer` can carry. What the solve actually reads is four sets of typed arrays and
+ * eleven numbers, and that much is portable.
+ *
+ * **One implementation, two callers.** `PhysicsWorld.solveIsland` delegates here and so does
+ * `islandWorker.ts`; there is no second copy of the substep order anywhere. The rule against two
+ * implementations of one decision is what makes that non-negotiable, and `splatSortWorker.ts` is the
+ * precedent for satisfying it across a worker boundary — there by stringifying one function, here by
+ * both sides importing one module. **What would make this wrong** is a substep loop appearing inside
+ * the worker.
+ *
+ * The dials are a `Float64Array` and not an object because the worker reads them out of shared
+ * memory, and a shape both sides agree on without a per-tick message is the cheapest way to let a
+ * consumer change gravity between ticks and have the pool see it.
+ */
+
+import { BODY_DYNAMIC, BODY_STATIC } from './bodies.ts';
+import type { BodySet } from './bodies.ts';
+import type { IslandSet } from './island.ts';
+import { solveJoints } from './joints.ts';
+import type { JointSet } from './joints.ts';
+import { applyRestitution, solveContacts, warmStart } from './solver.ts';
+import type { ContactConstraints, FrictionModel } from './solver.ts';
+
+/* Slots in the dial block. Named because a worker reads them from shared memory by index. */
+export const DIAL_SUBSTEPS = 0;
+export const DIAL_ITERATIONS = 1;
+export const DIAL_DT = 2;
+export const DIAL_GRAVITY_X = 3;
+export const DIAL_GRAVITY_Y = 4;
+export const DIAL_GRAVITY_Z = 5;
+export const DIAL_LINEAR_DAMPING = 6;
+export const DIAL_ANGULAR_DAMPING = 7;
+export const DIAL_CONTACT_HERTZ = 8;
+export const DIAL_CONTACT_DAMPING = 9;
+export const DIAL_JOINT_HERTZ = 10;
+export const DIAL_JOINT_DAMPING = 11;
+export const DIAL_ALLOW_SLEEP = 12;
+export const DIAL_FRICTION_MODEL = 13;
+/** How many slots a dial block has. */
+export const DIAL_COUNT = 14;
+
+/**
+ * `FrictionModel` crosses as a number, and the mapping is written once here.
+ *
+ * A string would cross a `postMessage` perfectly well; it would not survive being read out of a
+ * `Float64Array`, which is where the dials live so that no message is needed at all.
+ */
+export const FRICTION_BOX = 0;
+export const FRICTION_ELLIPTICAL = 1;
+
+export function frictionDial(model: FrictionModel): number {
+  return model === 'elliptical' ? FRICTION_ELLIPTICAL : FRICTION_BOX;
+}
+
+export function frictionModelOf(dial: number): FrictionModel {
+  return dial === FRICTION_ELLIPTICAL ? 'elliptical' : 'box';
+}
+
+/** Ticks below the sleep thresholds before a body is willing to sleep. */
+export const SLEEP_TICKS = 60;
+
+/** Everything one island's solve reaches, and nothing else the world holds. */
+export interface IslandSolveState {
+  bodies: BodySet;
+  constraints: ContactConstraints;
+  joints: JointSet;
+  islands: IslandSet;
+  /* Explicitly `ArrayBufferLike`: a pool's dials are a view on a `SharedArrayBuffer`, and the
+     default parameter is `ArrayBuffer`, which a shared one does not assign to. See
+     `parcel/store.ts` for the same note in the other direction. */
+  dials: Float64Array<ArrayBufferLike>;
+}
+
+/** Whether a body has been still long enough to stop being solved. */
+export function bodyAsleep(bodies: BodySet, allowSleep: boolean, i: number): boolean {
+  return allowSleep && (bodies.sleepTicks[i] ?? 0) >= SLEEP_TICKS;
+}
+
+/** Whether every body in an island is asleep, which is what lets the island be skipped whole. */
+export function islandAsleep(state: IslandSolveState, island: number): boolean {
+  const allowSleep = (state.dials[DIAL_ALLOW_SLEEP] ?? 0) !== 0;
+  const from = state.islands.bodyStart[island] ?? 0;
+  const to = state.islands.bodyStart[island + 1] ?? from;
+  for (let at = from; at < to; at++) {
+    if (!bodyAsleep(state.bodies, allowSleep, state.islands.bodyOrder[at] ?? 0)) return false;
+  }
+  return to > from;
+}
+
+function integrateVelocities(state: IslandSolveState, h: number, from: number, to: number): void {
+  const bodies = state.bodies;
+  const d = state.dials;
+  const allowSleep = (d[DIAL_ALLOW_SLEEP] ?? 0) !== 0;
+  const gx = d[DIAL_GRAVITY_X] ?? 0;
+  const gy = d[DIAL_GRAVITY_Y] ?? 0;
+  const gz = d[DIAL_GRAVITY_Z] ?? 0;
+  const ld = 1 / (1 + h * (d[DIAL_LINEAR_DAMPING] ?? 0));
+  const ad = 1 / (1 + h * (d[DIAL_ANGULAR_DAMPING] ?? 0));
+  for (let at = from; at < to; at++) {
+    const i = state.islands.bodyOrder[at] ?? 0;
+    if (bodies.type[i] !== BODY_DYNAMIC || bodyAsleep(bodies, allowSleep, i)) continue;
+    bodies.velX[i] = ((bodies.velX[i] ?? 0) + h * gx) * ld;
+    bodies.velY[i] = ((bodies.velY[i] ?? 0) + h * gy) * ld;
+    bodies.velZ[i] = ((bodies.velZ[i] ?? 0) + h * gz) * ld;
+    bodies.angX[i] = (bodies.angX[i] ?? 0) * ad;
+    bodies.angY[i] = (bodies.angY[i] ?? 0) * ad;
+    bodies.angZ[i] = (bodies.angZ[i] ?? 0) * ad;
+  }
+}
+
+function integratePositions(state: IslandSolveState, h: number, from: number, to: number): void {
+  const bodies = state.bodies;
+  const allowSleep = (state.dials[DIAL_ALLOW_SLEEP] ?? 0) !== 0;
+  for (let at = from; at < to; at++) {
+    const i = state.islands.bodyOrder[at] ?? 0;
+    if (bodies.type[i] === BODY_STATIC || bodyAsleep(bodies, allowSleep, i)) continue;
+    bodies.posX[i] = (bodies.posX[i] ?? 0) + h * (bodies.velX[i] ?? 0);
+    bodies.posY[i] = (bodies.posY[i] ?? 0) + h * (bodies.velY[i] ?? 0);
+    bodies.posZ[i] = (bodies.posZ[i] ?? 0) + h * (bodies.velZ[i] ?? 0);
+    // First-order exponential map, then renormalise. No sin, no cos.
+    const qx = bodies.rotX[i] ?? 0;
+    const qy = bodies.rotY[i] ?? 0;
+    const qz = bodies.rotZ[i] ?? 0;
+    const qw = bodies.rotW[i] ?? 1;
+    const wx = bodies.angX[i] ?? 0;
+    const wy = bodies.angY[i] ?? 0;
+    const wz = bodies.angZ[i] ?? 0;
+    const half = 0.5 * h;
+    let nx = qx + half * (wx * qw + wy * qz - wz * qy);
+    let ny = qy + half * (wy * qw + wz * qx - wx * qz);
+    let nz = qz + half * (wz * qw + wx * qy - wy * qx);
+    let nw = qw - half * (wx * qx + wy * qy + wz * qz);
+    const len = Math.sqrt(nx * nx + ny * ny + nz * nz + nw * nw) || 1;
+    nx /= len;
+    ny /= len;
+    nz /= len;
+    nw /= len;
+    bodies.rotX[i] = nx;
+    bodies.rotY[i] = ny;
+    bodies.rotZ[i] = nz;
+    bodies.rotW[i] = nw;
+  }
+}
+
+/**
+ * Advance one island through every substep.
+ *
+ * Integration is over this island's bodies only, which is what makes the call independent of every
+ * other island rather than merely ordered against them.
+ */
+export function solveIslandInto(state: IslandSolveState, island: number): void {
+  if (islandAsleep(state, island)) return;
+  const d = state.dials;
+  const substeps = d[DIAL_SUBSTEPS] ?? 1;
+  const iterations = d[DIAL_ITERATIONS] ?? 1;
+  const dt = d[DIAL_DT] ?? 0;
+  const contactHertz = d[DIAL_CONTACT_HERTZ] ?? 0;
+  const contactDamping = d[DIAL_CONTACT_DAMPING] ?? 0;
+  const jointHertz = d[DIAL_JOINT_HERTZ] ?? 0;
+  const jointDamping = d[DIAL_JOINT_DAMPING] ?? 0;
+  const friction = frictionModelOf(d[DIAL_FRICTION_MODEL] ?? 0);
+
+  const h = dt / substeps;
+  const bodies = state.bodies;
+  const joints = state.joints;
+  const c = state.constraints;
+  const order = state.islands.constraintOrder;
+  const from = state.islands.constraintStart[island] ?? 0;
+  const to = state.islands.constraintStart[island + 1] ?? from;
+  const bodyFrom = state.islands.bodyStart[island] ?? 0;
+  const bodyTo = state.islands.bodyStart[island + 1] ?? bodyFrom;
+  const jointOrder = state.islands.jointOrder;
+  const jointFrom = state.islands.jointStart[island] ?? 0;
+  const jointTo = state.islands.jointStart[island + 1] ?? jointFrom;
+
+  for (let s = 0; s < substeps; s++) {
+    integrateVelocities(state, h, bodyFrom, bodyTo);
+    warmStart(bodies, c, order, from, to);
+    for (let it = 0; it < iterations; it++) {
+      // Joints before contacts: a joint is structural and a contact is transient, so letting a
+      // contact win produces a limb that pulls out of its socket when something lands on it.
+      solveJoints(
+        bodies,
+        joints,
+        jointOrder,
+        jointFrom,
+        jointTo,
+        h,
+        dt,
+        true,
+        jointHertz,
+        jointDamping,
+      );
+      solveContacts(bodies, c, order, from, to, h, true, contactHertz, contactDamping, friction);
+    }
+    integratePositions(state, h, bodyFrom, bodyTo);
+    // The relax pass, with the bias off, giving back the energy the bias added.
+    solveJoints(
+      bodies,
+      joints,
+      jointOrder,
+      jointFrom,
+      jointTo,
+      h,
+      dt,
+      false,
+      jointHertz,
+      jointDamping,
+    );
+    solveContacts(bodies, c, order, from, to, h, false, contactHertz, contactDamping, friction);
+  }
+  applyRestitution(bodies, c, order, from, to);
+}

package/src/islandWorker.ts

@@ -0,0 +1,141 @@
+/**
+ * The worker end of the island pool.
+ *
+ * **It contains no physics.** It adopts views over the staging buffer, claims islands from a shared
+ * cursor, and calls `solveIslandInto` — the same function `PhysicsWorld.solveIsland` calls. A
+ * substep loop appearing in this file would be the defect the whole arrangement is shaped to
+ * prevent, because a second copy of the solve order drifts from the first the first time either is
+ * touched and nothing fails until a consumer's replay does.
+ *
+ * **It parks rather than polls.** `Atomics.wait` is permitted off a browser's main thread, so an
+ * idle worker costs nothing between ticks and wakes on an epoch bump with no message sent.
+ *
+ * **Two hosts, one file.** A browser module worker delivers messages through `self.onmessage`;
+ * `node:worker_threads` delivers them through `parentPort`. The difference is eight lines at the
+ * bottom, and paying them is what lets the gate spawn this exact entry point in Node instead of a
+ * stand-in that would prove nothing about threads.
+ */
+
+import { solveIslandInto } from './islandSolve.ts';
+import type { IslandSolveState } from './islandSolve.ts';
+import { SolveStage } from './stage.ts';
+import type { StagePlan } from './stage.ts';
+import {
+  CTL_ACK,
+  CTL_CURSOR,
+  CTL_DONE,
+  CTL_EPOCH,
+  CTL_ISLANDS,
+  CTL_RELOAD,
+  CTL_SOLVED,
+  CTL_STOP,
+} from './workerPool.ts';
+
+/** The only message this worker takes: here is the shared state, and here is who you are. */
+interface StageMessage {
+  kind: 'stage';
+  index: number;
+  control: ArrayBufferLike;
+  buffer: ArrayBufferLike;
+  plan: StagePlan;
+}
+
+let control: Int32Array<ArrayBufferLike> | null = null;
+let state: IslandSolveState | null = null;
+let index = 0;
+
+/**
+ * Take the shared buffers, say so, and park.
+ *
+ * The acknowledgement is an atomic and not a reply message because the caller is waiting on it
+ * synchronously — it has just told every worker to come out of `Atomics.wait` and cannot process a
+ * message of its own until the tick is over.
+ */
+function accept(message: StageMessage): void {
+  if (message?.kind !== 'stage') return;
+  control = new Int32Array(message.control as ArrayBuffer);
+  index = message.index;
+  state = SolveStage.adopt(message.buffer, message.plan).state;
+  /*
+   * **The epoch is read before the acknowledgement, and that order is the whole correctness of a
+   * re-plan.** The caller is spinning on `CTL_ACK` and bumps the epoch the moment it completes. Read
+   * after acknowledging and this worker can capture the epoch it was meant to wake for, then wait
+   * for the one after it — sleeping through the tick, so the join never completes and the pool
+   * declares itself dead. Reading first bounds `seen` below the next bump by construction.
+   */
+  const seen = Atomics.load(control, CTL_EPOCH);
+  Atomics.add(control, CTL_ACK, 1);
+  Atomics.notify(control, CTL_ACK);
+  park(seen);
+}
+
+/** Claim islands until there are none, then report what was solved. */
+function work(ctl: Int32Array<ArrayBufferLike>, solve: IslandSolveState): void {
+  const count = Atomics.load(ctl, CTL_ISLANDS);
+  let solved = 0;
+  for (;;) {
+    const island = Atomics.add(ctl, CTL_CURSOR, 1);
+    if (island >= count) break;
+    solveIslandInto(solve, island);
+    solved += 1;
+  }
+  Atomics.add(ctl, CTL_SOLVED + index, solved);
+  Atomics.add(ctl, CTL_DONE, 1);
+  Atomics.notify(ctl, CTL_DONE);
+}
+
+/**
+ * Sleep until the epoch moves, then either solve, stop, or go back to the event loop.
+ *
+ * Returning on `CTL_RELOAD` is the whole reason a re-plan works: a parked worker cannot receive a
+ * `postMessage`, so the caller lets it out first and the pending message is delivered the moment
+ * this function returns.
+ */
+function park(from: number): void {
+  const ctl = control;
+  if (ctl === null) return;
+  let seen = from;
+  for (;;) {
+    Atomics.wait(ctl, CTL_EPOCH, seen);
+    const epoch = Atomics.load(ctl, CTL_EPOCH);
+    if (epoch === seen) continue;
+    seen = epoch;
+    if (Atomics.load(ctl, CTL_STOP) === 1) return;
+    if (Atomics.load(ctl, CTL_RELOAD) === 1) return;
+    if (state !== null) work(ctl, state);
+  }
+}
+
+const scope = globalThis as unknown as {
+  postMessage?: unknown;
+  onmessage?: ((event: { data: StageMessage }) => void) | null;
+};
+
+if (typeof scope.postMessage === 'function') {
+  scope.onmessage = (event: { data: StageMessage }): void => accept(event.data);
+} else {
+  /*
+   * **No top-level await here, and that is a consumer's build rather than a preference.**
+   *
+   * `workerPool.ts` builds this with `new Worker(new URL('./islandWorker.ts', import.meta.url))`,
+   * which every bundler detects statically and compiles as a worker whether or not the consumer
+   * ever starts a pool. Vite's default worker format is `iife`, and an IIFE cannot carry a
+   * top-level await: a consumer's production build answered `Module format "iife" does not support
+   * top-level await` on 2026-09-05 and could not build at all. A dev server serves module workers
+   * and never sees it, which is why `check:pool` passed over the same code.
+   *
+   * So the Node branch attaches its listener in a microtask instead. Nothing is missed: a Node
+   * `MessagePort` queues messages until `on('message')` attaches, so a `postMessage` issued before
+   * this resolves is delivered when it does.
+   *
+   * A variable specifier so a browser bundler leaves the import alone; this branch never runs in
+   * one.
+   */
+  const nodeWorkers = 'node:worker_threads';
+  void import(/* @vite-ignore */ nodeWorkers).then((mod) => {
+    const { parentPort } = mod as {
+      parentPort: { on(event: 'message', listener: (value: StageMessage) => void): void } | null;
+    };
+    parentPort?.on('message', accept);
+  });
+}