@threenative/core 0.3.0 → 0.3.1

package/dist/playtest.js

@@ -8,14 +8,24 @@ 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 { pooled, 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) {
@@ -36,17 +46,29 @@ function isObject(value) {
   return typeof value === "object" && value !== null;
 }
 
-// src/version.ts
-var CORE_VERSION = "0.3.0";
-
 // src/playtest.ts
 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,
@@ -62,13 +84,16 @@ 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],
@@ -83,19 +108,35 @@ function playtest(options = {}) {
         startup: () => ({
           phase: ctx.startup.phase,
           progress: ctx.startup.progress,
-          ...runtime?.startupCompileSettled === void 0 ? {} : { compileSettled: runtime.startupCompileSettled() }
+          ...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) => {
@@ -103,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;
     }
@@ -113,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();
     };
   });
@@ -198,7 +269,7 @@ 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();
@@ -206,61 +277,136 @@ function gameplayObservations(ctx, contactHistory, seed, replayRuntime) {
     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,
-        ...finished === void 0 ? {} : { finished }
+        ...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) {
-  const snapshot = ctx.entities.snapshot();
+function drainContacts(ctx, history, tick) {
   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))) {
+  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 = idsByEntity.get(event.body);
-        if (entity === void 0 || event.entity === void 0) continue;
+        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 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 = {};
   for (const fields of Object.values(snapshot)) {
@@ -303,4 +449,4 @@ function cloneJsonValue(value) {
   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 };

package/dist/react.d.ts

@@ -1,6 +1,7 @@
 import { ReactNode } from 'react';
-import { C as CanvasLayer } from './canvas-layer-CtrZHgIh.js';
+import { C as CanvasLayer } from './canvas-layer-BLVijiUJ.js';
 import 'three';
+import './renderer-C6hqZpoG.js';
 import 'three/webgpu';
 
 /**
@@ -162,12 +163,13 @@ interface ITextProps {
 /**
  * A rectangle. Paints when its style has a `background`; otherwise it only positions children.
  * @situation group and position native React HUD elements
- * @example <View style={{ centerX: 0, top: 24 }}><Text>READY</Text></View>
+ * @example <View style={{ centerX: true, top: 24 }}><Text>READY</Text></View>
  */
 declare function View(props: IViewProps): ReactNode;
 /**
  * A run of bitmap glyphs, drawn as one instanced quad per lit pixel.
  * @situation show text in a native React HUD without a DOM
+ * @alias objective panel journal
  * @example <Text style={{ color: "#ffffff", fontSize: 24 }}>SCORE 10</Text>
  */
 declare function Text(props: ITextProps): ReactNode;