@threenative/core 0.2.0 → 0.3.1

package/dist/playtest.js

@@ -1,535 +1,74 @@
-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", "Captures application runtime errors."),
-  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.performance", "Samples bounded per-render frame cost and renderer counts."),
-  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));
-  const renderPerformance = rendererPerformance(input.renderer);
-  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() },
-    ...renderPerformance === void 0 ? {} : { performance: renderPerformance },
-    ...input.runtimeDiagnosticsSeries === void 0 ? {} : { runtimeDiagnosticsSeries: input.runtimeDiagnosticsSeries().map((sample) => ({ ...sample })) },
-    ...input.resources === void 0 ? {} : { resources: input.resources() }
-  };
-}
-function rendererPerformance(renderer) {
-  const render = renderer.info?.render;
-  const drawCalls = finiteNumber(render?.drawCalls) ? render.drawCalls : void 0;
-  const triangles = finiteNumber(render?.triangles) ? render.triangles : void 0;
-  if (drawCalls === void 0 && triangles === void 0) return void 0;
-  return {
-    ...drawCalls === void 0 ? {} : { drawCalls },
-    ...triangles === void 0 ? {} : { triangles }
-  };
-}
-function finiteNumber(value) {
-  return typeof value === "number" && Number.isFinite(value);
-}
-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 PLAYTEST_PHYSICS_BODY_LIMIT = 100;
-var PLAYTEST_PHYSICS_SAMPLE_LIMIT = 100;
-var ThreePlaytestPhysicsRecorder = class {
-  #physics;
-  #series = [];
-  constructor(physics) {
-    this.#physics = physics;
-  }
-  sample(request, tick) {
-    if (request.label !== void 0) {
-      if (this.#series.some(({ label }) => label === request.label))
-        throw new Error(`TN_PLAYTEST_PHYSICS_LABEL_DUPLICATE: '${request.label}' was already sampled.`);
-      if (this.#series.length >= PLAYTEST_PHYSICS_SAMPLE_LIMIT)
-        throw new Error(`TN_PLAYTEST_PHYSICS_SAMPLE_LIMIT: at most ${PLAYTEST_PHYSICS_SAMPLE_LIMIT} labelled samples are retained.`);
-      this.#series.push({ label: request.label, snapshot: physicsSnapshot(this.#physics.bodies()), tick });
-    }
-    return this.#series.map((sample) => ({ ...sample }));
-  }
-};
-function physicsSnapshot(bodies) {
-  if (!Array.isArray(bodies))
-    throw new Error("TN_PLAYTEST_PHYSICS_BODIES: the physics provider must return an array of bodies.");
-  const retained = bodies.slice(0, PLAYTEST_PHYSICS_BODY_LIMIT);
-  const seen = /* @__PURE__ */ new Set();
-  const primitives = retained.flatMap((body) => {
-    if (typeof body?.id !== "string" || body.id.length === 0)
-      throw new Error("TN_PLAYTEST_PHYSICS_BODY_ID: every observed physics body needs a non-empty string id.");
-    if (seen.has(body.id))
-      throw new Error(`TN_PLAYTEST_PHYSICS_BODY_DUPLICATE: body id '${body.id}' was reported twice in one sample.`);
-    seen.add(body.id);
-    if (typeof body.sleeping !== "boolean")
-      throw new Error(`TN_PLAYTEST_PHYSICS_BODY_SLEEPING: body '${body.id}' must report sleeping as a boolean.`);
-    if (!isFiniteVec3(body.position))
-      throw new Error(`TN_PLAYTEST_PHYSICS_BODY_POSITION: body '${body.id}' must report a finite [x, y, z] position.`);
-    const sleep = { category: "sleep", entity: body.id, value: body.sleeping ? 1 : 0 };
-    const centerOfMass = { category: "center-of-mass", entity: body.id, position: [...body.position] };
-    return [sleep, centerOfMass];
-  });
-  return { artifact: { overflow: { omittedBodies: bodies.length - retained.length }, primitives } };
-}
-function isFiniteVec3(value) {
-  return Array.isArray(value) && value.length === 3 && value.every((component) => typeof component === "number" && Number.isFinite(component));
-}
-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) {
-  if (options.fixedStep === void 0 !== (options.tick === void 0))
-    throw new Error("fixedStep and its authoritative tick provider must be installed together.");
-  if (options.physics !== void 0 && options.tick === void 0)
-    throw new Error("A physics provider requires the authoritative tick provider, and therefore fixedStep.");
-  const recorder = options.physics === void 0 ? void 0 : new ThreePlaytestPhysicsRecorder(options.physics);
-  const host = globalThis;
-  const previous = host[PLAYTEST_BRIDGE_GLOBAL];
-  const registry = new ThreePlaytestEntityRegistry();
-  syncEntities(registry, options.entities);
-  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.physics === void 0 ? [] : ["runtime.physics"],
-    ...options.runtimeDiagnosticsSeries === void 0 ? [] : ["runtime.performance"],
-    ...options.gameplayChannels?.().includes("runtime.contacts") === true ? ["runtime.contacts"] : [],
-    ...options.gameplayChannels?.().includes("runtime.tags") === true ? ["runtime.tags"] : [],
-    ...options.gameplayChannels?.().includes("runtime.world") === true ? ["runtime.world"] : []
-  ];
-  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.");
-        const startTick = options.tick();
-        await options.fixedStep(ticks);
-        const tick = options.tick();
-        const advanced = tick - startTick;
-        if (advanced !== ticks)
-          throw new Error(`fixedStep advanced ${advanced} actual ticks; expected ${ticks}.`);
-        return { clock: { mode: "fixed-step", tick }, ticks: advanced };
-      }
-    },
-    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,
-        runtimeDiagnosticsSeries: options.runtimeDiagnosticsSeries,
-        registry,
-        renderer: options.renderer,
-        resources: options.resources === void 0 ? void 0 : () => options.resources.read(),
-        scene: options.scene,
-        tick: options.tick?.()
-      }, request);
-      const components = options.components?.();
-      const withComponents = components === void 0 || Object.keys(components).length === 0 ? snapshot : { ...snapshot, components };
-      const result = recorder === void 0 || request.include?.includes("physicsDebugSeries") !== true ? withComponents : { ...withComponents, physicsDebugSeries: recorder.sample(request, options.tick()) };
-      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;
+  let paused = 0;
+  const unsupported = /* @__PURE__ */ new Set();
   for (const bus of buses) {
     queued += bus.queued;
     voices += bus.voices;
+    pooled += bus.pooled;
+    paused += bus.pausedVoices;
+    for (const option of bus.unsupported) unsupported.add(option);
   }
-  return { queued, voices };
+  return { paused, pooled, queued, unsupported: [...unsupported].sort(), voices };
+}
+
+// src/version.ts
+var CORE_VERSION = "0.3.1";
+
+// src/pipeline-census.ts
+var PIPELINE_CENSUS_CAPABILITY = "runtime.pipelineCensus";
+
+// 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/playtest.ts
-var CORE_VERSION = "0.1.0";
 var currentAgent = typeof navigator === "undefined" ? "node" : navigator.userAgent;
 function playtest(options = {}) {
   let dispose;
   let attached;
+  let startSceneEntered;
+  let disposePipelineCensus;
   let contactHistory = [];
+  const watcher = createTransitionWatcher();
+  let readTick;
   return {
+    sceneExit: () => {
+      contactHistory = [];
+      watcher.reset();
+    },
+    update: (ctx) => {
+      const tick = readTick?.();
+      if (tick === void 0) return;
+      drainContacts(ctx, contactHistory, tick);
+      watcher.observe(ctx, tick);
+    },
     setup: async (ctx, runtime) => {
+      readTick = runtime?.tick;
       const seed = runtime?.seed ?? null;
       const replayRuntime = runtime?.seed === null || runtime?.seed === void 0 ? void 0 : {
         agent: currentAgent,
@@ -545,20 +84,59 @@ function playtest(options = {}) {
         ...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),
+        gameplay: () => gameplayObservations(ctx, contactHistory, seed, replayRuntime, watcher),
         gameplayChannels: () => gameplayChannels(),
         renderer: ctx.renderer.raw,
+        renderChain: () => {
+          const observation = readRenderChainObservation(ctx.renderer);
+          return observation === void 0 ? void 0 : {
+            ...observation,
+            contributions: observation.contributions.map((contribution) => ({
+              ...contribution
+            })),
+            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,
+          ...ctx.startup.warmup === void 0 ? {} : { warmup: ctx.startup.warmup },
+          ...runtime?.startupCompileSettled === void 0 ? {} : { compileSettled: runtime.startupCompileSettled() },
+          // Wall-clock milestones, so a scenario asserts startup time as an observation instead
+          // of reading it off a console marker after the fact.
+          ...runtime?.startupTimeline === void 0 ? {} : { timeline: runtime.startupTimeline() }
+        })
       });
+      const pipelineCensus = runtime?.pipelineCensus;
+      if (runtime !== void 0 && pipelineCensus !== void 0) {
+        disposePipelineCensus = runtime.observations.contribute({
+          capabilities: [PIPELINE_CENSUS_CAPABILITY],
+          sample: () => ({ pipelineCensus: pipelineCensus() })
+        });
+      }
       installRuntimeChannels(installation.bridge, runtime);
+      if (globalThis[PLAYTEST_RUNNER_EXPECTED_GLOBAL] === true)
+        runtime?.enableRuntimeDiagnostics?.();
       dispose = installation.dispose;
-      attached = holdUntilAttached(installation.bridge, options);
+      attached = holdUntilAttached(installation.bridge, options, () => startSceneEntered);
       const cleanup = () => {
+        disposePipelineCensus?.();
+        disposePipelineCensus = void 0;
         dispose?.();
         dispose = void 0;
         attached = void 0;
+        startSceneEntered = void 0;
         contactHistory = [];
+        readTick = void 0;
+        watcher.reset();
       };
       if (attached !== void 0) {
         const gate = attached.catch((error) => {
@@ -566,7 +144,10 @@ function playtest(options = {}) {
           throw error;
         });
         if (runtime?.holdStart === void 0) await gate;
-        else runtime.holdStart(gate);
+        else {
+          startSceneEntered = runtime.holdStart(gate);
+          void startSceneEntered.catch(() => void 0);
+        }
       }
       return cleanup;
     }
@@ -576,27 +157,54 @@ 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;
+  const host = globalThis;
+  return host[PLAYTEST_RUNNER_EXPECTED_GLOBAL] === true || host.TN_PLAYTEST_ENDPOINT !== void 0;
 }
-function holdUntilAttached(bridge, options) {
+function holdUntilAttached(bridge, options, startSceneEntered) {
   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;
+  const applySetup = bridge.applySetup;
   return new Promise((resolve, reject) => {
+    let settled = false;
     const timer = setTimeout(() => {
+      settled = true;
       reject(
         new Error(
-          `TN_PLAYTEST_ATTACH_TIMEOUT: no playtest runner called describe() within ${timeoutMs}ms.`
+          `TN_PLAYTEST_ATTACH_TIMEOUT: no playtest runner applied setup or called describe() within ${timeoutMs}ms.`
         )
       );
     }, timeoutMs);
     timer.unref?.();
-    bridge.describe = () => {
+    const release = () => {
+      if (settled) return;
+      settled = true;
       clearTimeout(timer);
       resolve();
+    };
+    const fail = (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      reject(error);
+    };
+    if (applySetup !== void 0) {
+      bridge.applySetup = async (request) => {
+        try {
+          await applySetup(request);
+          release();
+        } catch (error) {
+          fail(error);
+          throw error;
+        }
+      };
+    }
+    bridge.describe = async () => {
+      release();
+      await startSceneEntered();
       return describe();
     };
   });
@@ -614,8 +222,8 @@ function installRuntimeChannels(bridge, runtime) {
 function addRuntimeCapabilities(description, contributions) {
   const capabilities = [...description.capabilities];
   const contributed = contributions.flatMap(({ capabilities: capabilities2 }) => capabilities2);
-  for (const capability2 of ["runtime.audio", "runtime.world", ...contributed]) {
-    if (!capabilities.includes(capability2)) capabilities.push(capability2);
+  for (const capability of ["runtime.audio", "runtime.world", ...contributed]) {
+    if (!capabilities.includes(capability)) capabilities.push(capability);
   }
   return { ...description, capabilities };
 }
@@ -661,62 +269,143 @@ function entityObject(entity) {
   const candidate = entity?.mesh ?? entity?.object;
   return candidate instanceof Object3D ? candidate : void 0;
 }
-function gameplayObservations(ctx, contactHistory, seed, replayRuntime) {
+function gameplayObservations(ctx, contactHistory, seed, replayRuntime, watcher) {
   const animation = {};
   const states = {};
   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") {
+      const stride = strideObservation(entity.animation.stride);
       animation[id] = {
         advancedFrames: entity.animation.advancedFrames,
-        clip: entity.animation.current
+        clip: entity.animation.current,
+        ...finished === void 0 ? {} : { finished },
+        ...stride === void 0 ? {} : { stride }
       };
     }
     if (typeof entity?.state === "string") states[id] = entity.state;
   }
   const channels = gameplayChannels();
-  const contacts = channels.includes("runtime.contacts") ? drainContacts(ctx, contactHistory) : void 0;
+  const contacts = channels.includes("runtime.contacts") ? drainContacts(ctx, contactHistory, watcher.lastTick()) : void 0;
   const tags = channels.includes("runtime.tags") ? tagCounts(snapshot) : void 0;
+  const transitions = watcher.read();
   return {
     animation,
     ...contacts === void 0 ? {} : { contacts },
     states,
     ...tags === void 0 ? {} : { tags },
+    ...transitions === void 0 ? {} : { transitions },
     ...runtimeObservation(seed, replayRuntime)
   };
 }
+function strideObservation(value) {
+  if (typeof value !== "object" || value === null) return void 0;
+  const report = value;
+  const numbers = ["clipGroundSpeed", "groundSpeed", "rate"];
+  const flags = ["overridden", "synced"];
+  if (!numbers.every((key) => typeof report[key] === "number" && Number.isFinite(report[key])))
+    return void 0;
+  if (!flags.every((key) => typeof report[key] === "boolean")) return void 0;
+  return {
+    clipGroundSpeed: report.clipGroundSpeed,
+    groundSpeed: report.groundSpeed,
+    overridden: report.overridden,
+    rate: report.rate,
+    synced: report.synced
+  };
+}
 function gameplayChannels(_ctx) {
-  return ["runtime.contacts", "runtime.tags"];
+  return ["runtime.contacts", "runtime.tags", "runtime.transitions"];
 }
-function drainContacts(ctx, history) {
-  for (const id of Object.keys(ctx.entities.snapshot())) {
-    for (const source of entitySources(ctx.entities.get(id))) {
+function drainContacts(ctx, history, tick) {
+  const idsByEntity = /* @__PURE__ */ new Map();
+  ctx.entities.forEach((id, registered) => {
+    for (const value of objectGraphValues(registered))
+      if (!idsByEntity.has(value)) idsByEntity.set(value, id);
+  });
+  ctx.entities.forEach((id, registered) => {
+    for (const source of entitySources(registered)) {
       for (const event of source.drainContacts()) {
-        const entity = findEntityId(ctx, event.body);
-        if (entity === void 0 || event.entity === void 0) continue;
+        const entity = idsByEntity.get(event.body);
+        const other = event.entity ?? (event.area === void 0 ? void 0 : idsByEntity.get(event.area)) ?? idsByEntity.get(source);
+        if (entity === void 0 || other === void 0) continue;
         history.push({
           entity,
           kind: event.started ? "trigger" : "trigger.exit",
-          with: event.entity
+          ...tick === void 0 ? {} : { tick },
+          with: other
         });
         if (history.length > PLAYTEST_PROTOCOL_LIMITS.maxEventsPerDrain) history.shift();
       }
     }
-  }
+  });
   return [...history];
 }
+var PLAYTEST_TRANSITION_LOG_LIMIT = 512;
+function primitiveOrUndefined(value) {
+  if (value === null) return null;
+  if (typeof value === "string" || typeof value === "boolean") return value;
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function createTransitionWatcher() {
+  let previous = /* @__PURE__ */ new Map();
+  let log = [];
+  let seen = false;
+  let tickSeen;
+  const record = (path, to, tick) => {
+    const had = previous.has(path);
+    const from = previous.get(path);
+    previous.set(path, to);
+    if (!had || from === to) return;
+    log.push({ from, path, tick, to });
+    if (log.length > PLAYTEST_TRANSITION_LOG_LIMIT) log.shift();
+  };
+  return {
+    lastTick: () => tickSeen,
+    observe: (ctx, tick) => {
+      tickSeen = tick;
+      seen = true;
+      ctx.entities.forEach((id, entity) => {
+        const candidate = entity;
+        if (typeof candidate.state === "string") record(`states.${id}`, candidate.state, tick);
+      });
+      const state = ctx.state.getState();
+      for (const key of Object.keys(state)) {
+        const value = primitiveOrUndefined(state[key]);
+        if (value !== void 0) record(`state.${key}`, value, tick);
+      }
+    },
+    // Absent until the loop has ticked at least once. A run that never ticked has not observed
+    // that nothing changed; it has observed nothing, and an assertion against it must say so.
+    read: () => seen ? log.map((entry) => ({ ...entry })) : void 0,
+    reset: () => {
+      previous = /* @__PURE__ */ new Map();
+      log = [];
+      seen = false;
+      tickSeen = void 0;
+    }
+  };
+}
 function entitySources(entity) {
-  if (entity === void 0) return [];
-  return Object.values(entity).filter(
-    (value) => typeof value === "object" && value !== null && "drainContacts" in value && typeof value.drainContacts === "function"
+  return objectGraphValues(entity).filter(
+    (value) => "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 objectGraphValues(root) {
+  if (root === void 0) return [];
+  const values = [];
+  const visited = /* @__PURE__ */ new Set();
+  const visit = (value, depth) => {
+    if (value === null || typeof value !== "object" || visited.has(value)) return;
+    visited.add(value);
+    values.push(value);
+    if (depth >= 4 || value instanceof Object3D) return;
+    for (const child of Object.values(value)) visit(child, depth + 1);
+  };
+  visit(root, 0);
+  return values;
 }
 function tagCounts(snapshot) {
   const counts = {};
@@ -740,13 +429,24 @@ function stateResources(ctx) {
       ctx.state.flush();
       const state = ctx.state.getState();
       assertJsonSafe(state);
-      const value = state;
+      const value = cloneJsonValue(state);
       return Object.fromEntries([
-        ["GameState", value],
-        ["state", value]
+        // `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_ATTACH_TIMEOUT_MS, PLAYTEST_RUNNER_EXPECTED_GLOBAL, playtest };
+export { PLAYTEST_ATTACH_TIMEOUT_MS, PLAYTEST_RUNNER_EXPECTED_GLOBAL, PLAYTEST_TRANSITION_LOG_LIMIT, playtest };