@threenative/core 0.1.0 → 0.3.0

package/dist/playtest.js

@@ -1,463 +1,52 @@
-import { Vector2, Vector3, Box3, Matrix4, Frustum, Object3D } from 'three';
+import { assertJsonSafe, PLAYTEST_PROTOCOL_LIMITS } from '@threenative/playtest/protocol';
+import { installThreePlaytestBridge } from '@threenative/playtest/three';
+import { Object3D } from 'three';
 
-// ../playtest/dist/index.js
-var PLAYTEST_CAPABILITY_REGISTRY = [
-  capability("browser.canvas", "Samples canvas pixels and health."),
-  capability("browser.console", "Captures browser console and page errors."),
-  capability("browser.dom", "Reads bounded DOM observations."),
-  capability("browser.input", "Delivers keyboard and pointer input."),
-  capability("browser.network", "Captures failed browser requests."),
-  capability("browser.screenshot", "Captures viewport screenshots."),
-  capability("browser.trace", "Captures a bounded Playwright trace."),
-  capability("camera.observe", "Samples the active camera transform and projection."),
-  capability("entity.bounds", "Projects registered entity bounds into the viewport."),
-  capability("entity.observe", "Samples registered entity transforms and visibility."),
-  capability("entity.setup", "Applies bounded transforms to registered entities."),
-  capability("runtime.animation", "Samples application-owned animation state."),
-  capability("runtime.audio", "Samples application-owned audio runtime state."),
-  capability("runtime.components", "Samples registered JSON-safe component state."),
-  capability("runtime.contacts", "Samples bounded collision and trigger contacts."),
-  capability("runtime.diagnostics", "Samples application-owned runtime diagnostics."),
-  capability("runtime.events", "Drains bounded application event observations."),
-  capability("runtime.fixedStep", "Advances an application-owned deterministic tick."),
-  capability("runtime.physics", "Samples bounded application-owned physics observations."),
-  capability("runtime.resources", "Reads and writes registered JSON-safe application state."),
-  capability("runtime.state", "Samples application-owned state-machine state."),
-  capability("runtime.tags", "Samples bounded application-owned entity tags."),
-  capability("runtime.ui", "Samples registered JSON-safe UI and HUD state."),
-  capability("runtime.world", "Samples bounded runtime world metadata.")
-];
-new Set(PLAYTEST_CAPABILITY_REGISTRY.map(({ name }) => name));
-function capability(name, description) {
-  return { description, name, protocolVersion: 1 };
-}
-var PLAYTEST_PROTOCOL_LIMITS = {
-  maxEventsPerDrain: 1e3};
-function assertJsonSafe(value, path = "$") {
-  if (value === null || typeof value === "string" || typeof value === "boolean") {
-    return;
-  }
-  if (typeof value === "number") {
-    if (Number.isFinite(value)) {
-      return;
-    }
-    throw new TypeError(`${path} must contain only finite JSON numbers.`);
-  }
-  if (Array.isArray(value)) {
-    value.forEach((item, index) => assertJsonSafe(item, `${path}[${index}]`));
-    return;
-  }
-  if (typeof value === "object") {
-    for (const [key, item] of Object.entries(value)) {
-      assertJsonSafe(item, `${path}.${key}`);
-    }
-    return;
-  }
-  throw new TypeError(`${path} must be JSON-safe.`);
-}
-var PLAYTEST_BRIDGE_GLOBAL = "__THREENATIVE_PLAYTEST_BRIDGE__";
-var PLAYTEST_PROTOCOL_VERSION = 1;
-var PLAYTEST_PROTOCOL_LIMITS2 = {
-  maxEntitiesPerSample: 100,
-  maxEventsPerDrain: 1e3,
-  maxPayloadBytes: 1e6,
-  operationTimeoutMs: 5e3
-};
-function jsonByteLength(value) {
-  return new TextEncoder().encode(JSON.stringify(value)).byteLength;
-}
-function assertJsonSafe2(value, path = "$") {
-  if (value === null || typeof value === "string" || typeof value === "boolean") {
-    return;
-  }
-  if (typeof value === "number") {
-    if (Number.isFinite(value)) {
-      return;
-    }
-    throw new TypeError(`${path} must contain only finite JSON numbers.`);
-  }
-  if (Array.isArray(value)) {
-    value.forEach((item, index) => assertJsonSafe2(item, `${path}[${index}]`));
-    return;
-  }
-  if (typeof value === "object") {
-    for (const [key, item] of Object.entries(value)) {
-      assertJsonSafe2(item, `${path}.${key}`);
-    }
-    return;
-  }
-  throw new TypeError(`${path} must be JSON-safe.`);
-}
-var ThreePlaytestEntityRegistry = class {
-  #entries = /* @__PURE__ */ new Map();
-  register(entry) {
-    const path = entry.path ?? objectPath(entry.object);
-    const existing = this.#entries.get(entry.id);
-    if (existing !== void 0) {
-      throw new Error(
-        `Duplicate playtest entity id '${entry.id}' conflicts between '${existing.path}' and '${path}'. Register a unique stable id for each observed object.`
-      );
-    }
-    this.#entries.set(entry.id, { ...entry, path });
-  }
-  get(id) {
-    return this.#entries.get(id);
-  }
-  replace(entries) {
-    this.#entries.clear();
-    entries.forEach((entry) => this.register(entry));
-  }
-  select(ids) {
-    if (ids === void 0) return [...this.#entries.values()];
-    return ids.flatMap((id) => {
-      const entry = this.#entries.get(id);
-      return entry === void 0 ? [] : [entry];
-    });
-  }
-};
-function objectPath(object) {
-  const parts = [];
-  let current = object;
-  while (current !== null) {
-    parts.unshift(current.name || `${current.type}[${current.uuid.slice(0, 8)}]`);
-    current = current.parent;
-  }
-  return parts.join("/");
-}
-function sampleThreeObservations(input, request) {
-  input.scene.updateMatrixWorld(true);
-  input.camera.updateMatrixWorld(true);
-  const rendererSize = input.renderer.getDrawingBufferSize(new Vector2());
-  const entities = input.registry.select(request.entities).map(({ id, object }) => observeEntity(id, object, input.camera, rendererSize.x, rendererSize.y));
-  return {
-    clock: {
-      mode: input.clockMode,
-      ...input.tick === void 0 ? { timeMs: performance.now() } : { tick: input.tick }
-    },
-    ...input.diagnostics === void 0 ? {} : { diagnostics: input.diagnostics() },
-    entities,
-    ...input.gameplay === void 0 ? {} : { gameplay: input.gameplay() },
-    ...input.resources === void 0 ? {} : { resources: input.resources() }
-  };
-}
-function observeEntity(id, object, camera, viewportWidth, viewportHeight) {
-  const position = object.getWorldPosition(new Vector3());
-  const bounds = projectedBounds(object, camera, viewportWidth, viewportHeight);
-  return {
-    ...bounds === void 0 ? {} : { bounds },
-    id,
-    transform: {
-      position: [position.x, position.y, position.z],
-      rotation: [object.quaternion.x, object.quaternion.y, object.quaternion.z, object.quaternion.w],
-      scale: [object.scale.x, object.scale.y, object.scale.z]
-    },
-    visible: object.visible && bounds !== void 0 && bounds.width > 0 && bounds.height > 0
-  };
-}
-function projectedBounds(object, camera, viewportWidth, viewportHeight) {
-  const worldBounds = new Box3().setFromObject(object);
-  if (worldBounds.isEmpty()) return void 0;
-  const projection = new Matrix4().multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse);
-  if (!new Frustum().setFromProjectionMatrix(projection).intersectsBox(worldBounds)) return void 0;
-  const min = worldBounds.min;
-  const max = worldBounds.max;
-  const points = [
-    new Vector3(min.x, min.y, min.z),
-    new Vector3(min.x, min.y, max.z),
-    new Vector3(min.x, max.y, min.z),
-    new Vector3(min.x, max.y, max.z),
-    new Vector3(max.x, min.y, min.z),
-    new Vector3(max.x, min.y, max.z),
-    new Vector3(max.x, max.y, min.z),
-    new Vector3(max.x, max.y, max.z)
-  ].map((point) => point.project(camera));
-  const minX = Math.min(...points.map(({ x }) => x));
-  const maxX = Math.max(...points.map(({ x }) => x));
-  const minY = Math.min(...points.map(({ y }) => y));
-  const maxY = Math.max(...points.map(({ y }) => y));
-  return {
-    height: Math.max(0, (maxY - minY) * 0.5 * viewportHeight),
-    width: Math.max(0, (maxX - minX) * 0.5 * viewportWidth),
-    x: (minX + 1) * 0.5 * viewportWidth,
-    y: (1 - maxY) * 0.5 * viewportHeight
-  };
-}
-var BRIDGE_METHODS = /* @__PURE__ */ new Set([
-  "advance",
-  "applySetup",
-  "describe",
-  "drainEvents",
-  "focus",
-  "ready",
-  "sample"
-]);
-function connectDevicePlaytestBridge(bridge, endpoint) {
-  const nativeInstallation = connectNativeMailbox(bridge);
-  if (nativeInstallation !== void 0) return nativeInstallation;
-  let closed = false;
-  let reportedError = false;
-  let scheduled;
-  const schedule = () => {
-    if (closed) return;
-    if (typeof globalThis.requestAnimationFrame === "function") {
-      scheduled = globalThis.requestAnimationFrame(() => void poll());
-    } else {
-      scheduled = setTimeout(() => void poll(), 50);
-    }
-  };
-  const poll = async () => {
-    if (closed) return;
-    try {
-      const response = await fetch(endpoint);
-      if (response.status !== 204) {
-        if (!response.ok) throw new Error(`Device bridge poll failed with HTTP ${response.status}.`);
-        const request = parseRequest(await response.json());
-        await postResponse(endpoint, await dispatch(bridge, request));
-      }
-    } catch (error) {
-      if (!reportedError) {
-        reportedError = true;
-        console.error(`TN_PLAYTEST_DEVICE_TRANSPORT: ${error instanceof Error ? error.message : String(error)}`);
-      }
-    } finally {
-      schedule();
-    }
-  };
-  schedule();
-  return {
-    close: () => {
-      closed = true;
-      if (scheduled === void 0) return;
-      if (typeof globalThis.cancelAnimationFrame === "function" && typeof scheduled === "number") {
-        globalThis.cancelAnimationFrame(scheduled);
-      } else clearTimeout(scheduled);
-    }
-  };
-}
-function connectNativeMailbox(bridge) {
-  const globals = globalThis;
-  const mailbox = globals.TN_PLAYTEST_MAILBOX;
-  const host = globals.__THREENATIVE_NATIVE__?.playtest;
-  if (typeof mailbox?.request !== "string" || typeof mailbox.response !== "string" || typeof host?.receive !== "function" || typeof host.respond !== "function") return void 0;
-  let closed = false;
-  let frame;
-  const respond = (response) => {
-    if (!host.respond(mailbox.response, JSON.stringify(response))) {
-      console.error("TN_PLAYTEST_DEVICE_TRANSPORT: native mailbox response failed");
-    }
-  };
-  const poll = () => {
-    if (closed) return;
-    const raw = host.receive(mailbox.request);
-    if (raw !== void 0) {
-      try {
-        const request = parseRequest(JSON.parse(raw));
-        void dispatch(bridge, request).then(respond);
-      } catch (error) {
-        respond({
-          error: { message: error instanceof Error ? error.message : String(error) },
-          id: "invalid"
-        });
-      }
-    }
-    frame = globalThis.requestAnimationFrame(poll);
-  };
-  respond({ id: "ready", result: null });
-  frame = globalThis.requestAnimationFrame(poll);
-  return {
-    close: () => {
-      closed = true;
-      if (frame !== void 0) globalThis.cancelAnimationFrame(frame);
-    }
-  };
-}
-function readPlaytestEndpoint() {
-  const value = globalThis.TN_PLAYTEST_ENDPOINT;
-  return typeof value === "string" && value.length > 0 ? value : void 0;
-}
-async function dispatch(bridge, request) {
-  try {
-    if (request.method.startsWith("input.")) {
-      return { id: request.id, result: dispatchInput(request.method, request.argument) };
-    }
-    if (!BRIDGE_METHODS.has(request.method)) {
-      throw new Error(`Bridge operation '${request.method}' is unavailable.`);
-    }
-    const operation = bridge[request.method];
-    if (typeof operation !== "function") throw new Error(`Bridge operation '${request.method}' is unavailable.`);
-    const result = await operation.call(bridge, request.argument);
-    if (result !== void 0) assertBounded(result);
-    return { id: request.id, ...result === void 0 ? {} : { result } };
-  } catch (error) {
-    return { error: { message: error instanceof Error ? error.message : String(error) }, id: request.id };
-  }
-}
-function dispatchInput(method, argument) {
-  const host = globalThis.__THREENATIVE_NATIVE__?.playtestInput;
-  if (!isRecord(argument)) throw new Error(`Device ${method} requires an object argument.`);
-  if (method === "input.keyDown" || method === "input.keyUp") {
-    if (typeof argument.key !== "string") throw new Error(`Device ${method} requires a key.`);
-    const code = argument.key;
-    const key = /^Key[A-Z]$/u.test(code) ? code.slice(3).toLowerCase() : code;
-    if (typeof host?.keyboard !== "function") throw new Error("Native playtest keyboard input is unavailable.");
-    host.keyboard(method === "input.keyDown" ? "keydown" : "keyup", key, code);
-    return null;
-  }
-  if (method === "input.pointer") {
-    if (typeof argument.x !== "number" || typeof argument.y !== "number" || typeof argument.buttons !== "number") {
-      throw new Error("Device input.pointer requires numeric x, y, and buttons.");
-    }
-    if (typeof host?.pointer !== "function") throw new Error("Native playtest pointer input is unavailable.");
-    const type = argument.type === "down" ? "pointerdown" : argument.type === "up" ? "pointerup" : "pointermove";
-    host.pointer(type, argument.x, argument.y, argument.buttons);
-    return null;
-  }
-  throw new Error(`Device input operation '${method}' is unavailable.`);
-}
-function parseRequest(value) {
-  assertBounded(value);
-  if (!isRecord(value) || typeof value.id !== "string" || typeof value.method !== "string") {
-    throw new Error("Device request must contain string id and method fields.");
-  }
-  return value;
-}
-async function postResponse(endpoint, response) {
-  const result = await fetch(endpoint, {
-    body: JSON.stringify(response),
-    headers: { "content-type": "application/json" },
-    method: "POST"
-  });
-  if (!result.ok) throw new Error(`Device bridge response failed with HTTP ${result.status}.`);
-}
-function assertBounded(value) {
-  assertJsonSafe2(value);
-  if (jsonByteLength(value) > PLAYTEST_PROTOCOL_LIMITS2.maxPayloadBytes) {
-    throw new Error(`Device bridge payload exceeds ${PLAYTEST_PROTOCOL_LIMITS2.maxPayloadBytes} bytes.`);
-  }
-}
-function isRecord(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function installThreePlaytestBridge(options) {
-  const host = globalThis;
-  const previous = host[PLAYTEST_BRIDGE_GLOBAL];
-  const registry = new ThreePlaytestEntityRegistry();
-  syncEntities(registry, options.entities);
-  let tick = 0;
-  const capabilities = () => [
-    "camera.observe",
-    "entity.bounds",
-    "entity.observe",
-    "entity.setup",
-    ...options.fixedStep === void 0 ? [] : ["runtime.fixedStep"],
-    ...options.resources === void 0 ? [] : ["runtime.resources"],
-    ...options.diagnostics === void 0 ? [] : ["runtime.diagnostics"],
-    ...Object.keys(options.components?.() ?? {}).length === 0 ? [] : ["runtime.components"],
-    ...options.events === void 0 ? [] : ["runtime.events"],
-    ...options.gameplay === void 0 ? [] : ["runtime.animation", "runtime.state"],
-    ...options.gameplayChannels?.().includes("runtime.contacts") === true ? ["runtime.contacts"] : [],
-    ...options.gameplayChannels?.().includes("runtime.tags") === true ? ["runtime.tags"] : []
-  ];
-  const bridge = {
-    ...options.fixedStep === void 0 ? {} : {
-      advance: async (ticks) => {
-        if (!Number.isInteger(ticks) || ticks <= 0) throw new Error("advance ticks must be a positive integer.");
-        await options.fixedStep(ticks);
-        const startTick = tick;
-        tick += ticks;
-        return { clock: { mode: "fixed-step", tick }, ticks: tick - startTick };
-      }
-    },
-    applySetup: async (request) => applySetup(registry, options.resources, request),
-    ...options.events === void 0 ? {} : {
-      drainEvents: async (limit = PLAYTEST_PROTOCOL_LIMITS2.maxEventsPerDrain) => {
-        if (!Number.isInteger(limit) || limit < 0) throw new Error("drainEvents limit must be a non-negative integer.");
-        const events = options.events();
-        assertJsonSafe2(events);
-        return events.slice(0, Math.min(limit, PLAYTEST_PROTOCOL_LIMITS2.maxEventsPerDrain));
-      }
-    },
-    describe: () => ({
-      capabilities: capabilities(),
-      limits: PLAYTEST_PROTOCOL_LIMITS2,
-      name: "@threenative/playtest/three",
-      protocolVersion: PLAYTEST_PROTOCOL_VERSION
-    }),
-    ready: () => ({ ready: true }),
-    sample: (request) => {
-      syncEntities(registry, options.entities);
-      const snapshot = sampleThreeObservations({
-        camera: options.camera,
-        clockMode: options.fixedStep === void 0 ? "render-frame" : "fixed-step",
-        diagnostics: options.diagnostics,
-        gameplay: options.gameplay,
-        registry,
-        renderer: options.renderer,
-        resources: options.resources === void 0 ? void 0 : () => options.resources.read(),
-        scene: options.scene,
-        tick: options.fixedStep === void 0 ? void 0 : tick
-      }, request);
-      const components = options.components?.();
-      const result = components === void 0 || Object.keys(components).length === 0 ? snapshot : { ...snapshot, components };
-      assertJsonSafe2(result);
-      return result;
-    }
-  };
-  host[PLAYTEST_BRIDGE_GLOBAL] = bridge;
-  const endpoint = readPlaytestEndpoint();
-  let device;
-  if (endpoint !== void 0) device = connectDevicePlaytestBridge(bridge, endpoint);
-  return {
-    bridge,
-    dispose: () => {
-      device?.close();
-      if (host[PLAYTEST_BRIDGE_GLOBAL] !== bridge) return;
-      if (previous === void 0) delete host[PLAYTEST_BRIDGE_GLOBAL];
-      else host[PLAYTEST_BRIDGE_GLOBAL] = previous;
-    },
-    registerEntity: (entry) => registry.register(entry),
-    syncEntities: () => syncEntities(registry, options.entities)
-  };
-}
-function syncEntities(registry, entities) {
-  if (entities === void 0) return;
-  registry.replace(typeof entities === "function" ? entities() : entities);
-}
-function applySetup(registry, resources, request) {
-  request.entities?.forEach(({ entity, transform }) => {
-    const object = registry.get(entity)?.object;
-    if (object === void 0) throw new Error(`Setup entity '${entity}' is not registered.`);
-    if (transform.position !== void 0) object.position.fromArray(transform.position);
-    if (transform.rotation !== void 0) object.quaternion.fromArray(transform.rotation);
-    if (transform.scale !== void 0) object.scale.fromArray(transform.scale);
-    object.updateMatrix();
-  });
-  request.resources?.forEach(({ id, path, value }) => {
-    assertJsonSafe2(value);
-    if (resources?.write === void 0) throw new Error(`Resource setup '${id}' requires a writable resources provider.`);
-    if (!resources.write(id, path, value)) throw new Error(`Resource setup '${id}' was rejected by the application provider.`);
-  });
-}
+// src/playtest.ts
 var buses = /* @__PURE__ */ new Set();
 function audioRuntimeSnapshot() {
   let queued = 0;
   let voices = 0;
+  let pooled = 0;
   for (const bus of buses) {
     queued += bus.queued;
     voices += bus.voices;
+    pooled += bus.pooled;
   }
-  return { queued, voices };
+  return { pooled, queued, voices };
+}
+
+// src/render/chain.ts
+var REPORT_KEY = /* @__PURE__ */ Symbol.for("threenative.renderChain.report");
+function storedReport(target) {
+  return target[REPORT_KEY];
+}
+function readRenderChainReport(renderer) {
+  if (!isObject(renderer)) return void 0;
+  const raw = readRawRenderer(renderer);
+  return storedReport(renderer) ?? (isObject(raw) ? storedReport(raw) : void 0);
+}
+function readRenderChainObservation(renderer) {
+  return readRenderChainReport(renderer)?.applied;
+}
+function readRawRenderer(renderer) {
+  return "raw" in renderer ? renderer.raw : renderer;
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null;
 }
 
+// src/version.ts
+var CORE_VERSION = "0.3.0";
+
 // src/playtest.ts
-var CORE_VERSION = "0.1.0";
 var currentAgent = typeof navigator === "undefined" ? "node" : navigator.userAgent;
 function playtest(options = {}) {
   let dispose;
+  let attached;
   let contactHistory = [];
   return {
-    setup: (ctx, runtime) => {
-      const diagnostics = [];
+    setup: async (ctx, runtime) => {
       const seed = runtime?.seed ?? null;
       const replayRuntime = runtime?.seed === null || runtime?.seed === void 0 ? void 0 : {
         agent: currentAgent,
@@ -468,38 +57,124 @@ function playtest(options = {}) {
       };
       const installation = installThreePlaytestBridge({
         camera: ctx.camera,
-        diagnostics: () => [...diagnostics],
         entities: () => bridgeEntities(ctx),
         components: () => componentObservations(ctx.entities.snapshot()),
-        ...runtime === void 0 ? {} : { fixedStep: (ticks) => advance(runtime, ticks) },
+        ...runtime === void 0 ? {} : { fixedStep: runtime.fixedStep, tick: runtime.tick },
+        ...runtime?.runtimeDiagnosticsSeries === void 0 ? {} : { runtimeDiagnosticsSeries: runtime.runtimeDiagnosticsSeries },
         ...options.events === void 0 ? {} : { events: options.events },
         gameplay: () => gameplayObservations(ctx, contactHistory, seed, replayRuntime),
         gameplayChannels: () => gameplayChannels(),
         renderer: ctx.renderer.raw,
+        renderChain: () => {
+          const observation = readRenderChainObservation(ctx.renderer);
+          return observation === void 0 ? void 0 : {
+            ...observation,
+            dropped: observation.dropped.map((stage) => ({ ...stage })),
+            requested: [...observation.requested],
+            stages: [...observation.stages],
+            velocity: { ...observation.velocity }
+          };
+        },
         resources: stateResources(ctx),
-        scene: ctx.scene
+        scene: ctx.scene,
+        // A runner advances ticks far faster than a launch completes, and compute dispatch and
+        // the first world present are both held behind an opaque loading layer. Published so the
+        // runner waits for the world rather than observing a frozen simulation behind a loader.
+        startup: () => ({
+          phase: ctx.startup.phase,
+          progress: ctx.startup.progress,
+          ...runtime?.startupCompileSettled === void 0 ? {} : { compileSettled: runtime.startupCompileSettled() }
+        })
       });
-      installRuntimeChannels(installation.bridge);
+      installRuntimeChannels(installation.bridge, runtime);
+      if (globalThis[PLAYTEST_RUNNER_EXPECTED_GLOBAL] === true)
+        runtime?.enableRuntimeDiagnostics?.();
       dispose = installation.dispose;
-      return () => {
+      attached = holdUntilAttached(installation.bridge, options);
+      const cleanup = () => {
         dispose?.();
         dispose = void 0;
+        attached = void 0;
         contactHistory = [];
       };
+      if (attached !== void 0) {
+        const gate = attached.catch((error) => {
+          cleanup();
+          throw error;
+        });
+        if (runtime?.holdStart === void 0) await gate;
+        else runtime.holdStart(gate);
+      }
+      return cleanup;
     }
   };
 }
-function installRuntimeChannels(bridge) {
+var PLAYTEST_ATTACH_TIMEOUT_MS = 3e4;
+var PLAYTEST_RUNNER_EXPECTED_GLOBAL = "__THREENATIVE_PLAYTEST_RUNNER_EXPECTED__";
+function shouldHoldUntilAttached(options) {
+  if (options.holdUntilAttached !== void 0) return options.holdUntilAttached;
+  return globalThis[PLAYTEST_RUNNER_EXPECTED_GLOBAL] === true;
+}
+function holdUntilAttached(bridge, options) {
+  if (!shouldHoldUntilAttached(options)) return void 0;
+  const timeoutMs = options.attachTimeoutMs ?? PLAYTEST_ATTACH_TIMEOUT_MS;
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new Error(`TN_PLAYTEST_ATTACH_TIMEOUT_INVALID: ${String(options.attachTimeoutMs)}`);
+  }
   const describe = bridge.describe;
-  bridge.describe = () => Promise.resolve(describe()).then((description) => addRuntimeCapabilities(description));
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(
+        new Error(
+          `TN_PLAYTEST_ATTACH_TIMEOUT: no playtest runner called describe() within ${timeoutMs}ms.`
+        )
+      );
+    }, timeoutMs);
+    timer.unref?.();
+    bridge.describe = () => {
+      clearTimeout(timer);
+      resolve();
+      return describe();
+    };
+  });
 }
-function addRuntimeCapabilities(description) {
+function installRuntimeChannels(bridge, runtime) {
+  const describe = bridge.describe;
+  bridge.describe = () => Promise.resolve(describe()).then(
+    (description) => addRuntimeCapabilities(description, runtime?.observations.contributions() ?? [])
+  );
+  const sample = bridge.sample;
+  bridge.sample = (request) => Promise.resolve(sample(request)).then(
+    (snapshot) => addRuntimeObservations(snapshot, request, runtime?.observations.contributions() ?? [])
+  );
+}
+function addRuntimeCapabilities(description, contributions) {
   const capabilities = [...description.capabilities];
-  for (const capability2 of ["runtime.audio", "runtime.world"]) {
-    if (!capabilities.includes(capability2)) capabilities.push(capability2);
+  const contributed = contributions.flatMap(({ capabilities: capabilities2 }) => capabilities2);
+  for (const capability of ["runtime.audio", "runtime.world", ...contributed]) {
+    if (!capabilities.includes(capability)) capabilities.push(capability);
   }
   return { ...description, capabilities };
 }
+function addRuntimeObservations(snapshot, request, contributions) {
+  const result = { ...snapshot };
+  for (const contribution of contributions) {
+    const slice = contribution.sample(request);
+    if (typeof slice !== "object" || slice === null || Array.isArray(slice)) {
+      throw new TypeError("A runtime observation contribution must return a top-level object.");
+    }
+    assertJsonSafe(slice, "$.runtimeContribution");
+    for (const [key, value] of Object.entries(slice)) {
+      if (Object.hasOwn(result, key)) {
+        throw new Error(
+          `TN_PLAYTEST_OBSERVATION_COLLISION: top-level key '${key}' already exists.`
+        );
+      }
+      result[key] = value;
+    }
+  }
+  return result;
+}
 function runtimeObservation(seed, replayRuntime) {
   return {
     audio: audioRuntimeSnapshot(),
@@ -509,9 +184,6 @@ function runtimeObservation(seed, replayRuntime) {
     }
   };
 }
-function advance(runtime, ticks) {
-  runtime.fixedStep(ticks);
-}
 function bridgeEntities(ctx) {
   return [
     { id: "camera.main", object: ctx.camera },
@@ -532,10 +204,12 @@ function gameplayObservations(ctx, contactHistory, seed, replayRuntime) {
   const snapshot = ctx.entities.snapshot();
   for (const id of Object.keys(snapshot)) {
     const entity = ctx.entities.get(id);
+    const finished = typeof entity?.animation?.finished === "boolean" ? entity.animation.finished : void 0;
     if (typeof entity?.animation?.current === "string" && typeof entity.animation.advancedFrames === "number") {
       animation[id] = {
         advancedFrames: entity.animation.advancedFrames,
-        clip: entity.animation.current
+        clip: entity.animation.current,
+        ...finished === void 0 ? {} : { finished }
       };
     }
     if (typeof entity?.state === "string") states[id] = entity.state;
@@ -555,10 +229,20 @@ function gameplayChannels(_ctx) {
   return ["runtime.contacts", "runtime.tags"];
 }
 function drainContacts(ctx, history) {
-  for (const id of Object.keys(ctx.entities.snapshot())) {
+  const snapshot = ctx.entities.snapshot();
+  const idsByEntity = /* @__PURE__ */ new Map();
+  for (const id of Object.keys(snapshot)) {
+    const registered = ctx.entities.get(id);
+    if (registered === void 0) continue;
+    for (const value of Object.values(registered)) {
+      if (value !== null && typeof value === "object" && !idsByEntity.has(value))
+        idsByEntity.set(value, id);
+    }
+  }
+  for (const id of Object.keys(snapshot)) {
     for (const source of entitySources(ctx.entities.get(id))) {
       for (const event of source.drainContacts()) {
-        const entity = findEntityId(ctx, event.body);
+        const entity = idsByEntity.get(event.body);
         if (entity === void 0 || event.entity === void 0) continue;
         history.push({
           entity,
@@ -577,12 +261,6 @@ function entitySources(entity) {
     (value) => typeof value === "object" && value !== null && "drainContacts" in value && typeof value.drainContacts === "function"
   );
 }
-function findEntityId(ctx, target) {
-  return Object.keys(ctx.entities.snapshot()).find((id) => {
-    const entity = ctx.entities.get(id);
-    return entity !== void 0 && Object.values(entity).some((value) => value === target);
-  });
-}
 function tagCounts(snapshot) {
   const counts = {};
   for (const fields of Object.values(snapshot)) {
@@ -605,10 +283,24 @@ function stateResources(ctx) {
       ctx.state.flush();
       const state = ctx.state.getState();
       assertJsonSafe(state);
-      const value = state;
-      return { GameState: value, state: value };
+      const value = cloneJsonValue(state);
+      return Object.fromEntries([
+        // `state` is canonical. Keep `GameState` as a compatibility alias until published
+        // scenarios have migrated, then remove the alias in a future breaking release.
+        ["state", value],
+        ["GameState", value]
+      ]);
     }
   };
 }
+function cloneJsonValue(value) {
+  if (Array.isArray(value)) return value.map((item) => cloneJsonValue(item));
+  if (typeof value === "object" && value !== null) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [key, cloneJsonValue(item)])
+    );
+  }
+  return value;
+}
 
-export { playtest };
+export { PLAYTEST_ATTACH_TIMEOUT_MS, PLAYTEST_RUNNER_EXPECTED_GLOBAL, playtest };