@threenative/core 0.1.0

package/dist/playtest.d.ts

@@ -0,0 +1,11 @@
+import { JsonValue } from '@threenative/playtest';
+import { b as GamePluginHooks } from './game-DRPs3M7r.js';
+import 'three';
+import 'zustand/vanilla';
+
+declare function playtest<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined>(options?: PlaytestOptions): GamePluginHooks<TState, TPhysics>;
+interface PlaytestOptions {
+    readonly events?: () => JsonValue[];
+}
+
+export { type PlaytestOptions, playtest };

package/dist/playtest.js

@@ -0,0 +1,614 @@
+import { Vector2, Vector3, Box3, Matrix4, Frustum, 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.`);
+  });
+}
+var buses = /* @__PURE__ */ new Set();
+function audioRuntimeSnapshot() {
+  let queued = 0;
+  let voices = 0;
+  for (const bus of buses) {
+    queued += bus.queued;
+    voices += bus.voices;
+  }
+  return { queued, voices };
+}
+
+// src/playtest.ts
+var CORE_VERSION = "0.1.0";
+var currentAgent = typeof navigator === "undefined" ? "node" : navigator.userAgent;
+function playtest(options = {}) {
+  let dispose;
+  let contactHistory = [];
+  return {
+    setup: (ctx, runtime) => {
+      const diagnostics = [];
+      const seed = runtime?.seed ?? null;
+      const replayRuntime = runtime?.seed === null || runtime?.seed === void 0 ? void 0 : {
+        agent: currentAgent,
+        core: CORE_VERSION,
+        randomState: ctx.random.state,
+        rapier: runtime.rapier ?? null,
+        step: runtime.step
+      };
+      const installation = installThreePlaytestBridge({
+        camera: ctx.camera,
+        diagnostics: () => [...diagnostics],
+        entities: () => bridgeEntities(ctx),
+        components: () => componentObservations(ctx.entities.snapshot()),
+        ...runtime === void 0 ? {} : { fixedStep: (ticks) => advance(runtime, ticks) },
+        ...options.events === void 0 ? {} : { events: options.events },
+        gameplay: () => gameplayObservations(ctx, contactHistory, seed, replayRuntime),
+        gameplayChannels: () => gameplayChannels(),
+        renderer: ctx.renderer.raw,
+        resources: stateResources(ctx),
+        scene: ctx.scene
+      });
+      installRuntimeChannels(installation.bridge);
+      dispose = installation.dispose;
+      return () => {
+        dispose?.();
+        dispose = void 0;
+        contactHistory = [];
+      };
+    }
+  };
+}
+function installRuntimeChannels(bridge) {
+  const describe = bridge.describe;
+  bridge.describe = () => Promise.resolve(describe()).then((description) => addRuntimeCapabilities(description));
+}
+function addRuntimeCapabilities(description) {
+  const capabilities = [...description.capabilities];
+  for (const capability2 of ["runtime.audio", "runtime.world"]) {
+    if (!capabilities.includes(capability2)) capabilities.push(capability2);
+  }
+  return { ...description, capabilities };
+}
+function runtimeObservation(seed, replayRuntime) {
+  return {
+    audio: audioRuntimeSnapshot(),
+    world: {
+      seed,
+      ...replayRuntime === void 0 ? {} : { runtime: replayRuntime }
+    }
+  };
+}
+function advance(runtime, ticks) {
+  runtime.fixedStep(ticks);
+}
+function bridgeEntities(ctx) {
+  return [
+    { id: "camera.main", object: ctx.camera },
+    ...Object.keys(ctx.entities.snapshot()).flatMap((id) => {
+      const object = entityObject(ctx.entities.get(id));
+      return object === void 0 ? [] : [{ id, object }];
+    })
+  ];
+}
+function entityObject(entity) {
+  if (entity instanceof Object3D) return entity;
+  const candidate = entity?.mesh ?? entity?.object;
+  return candidate instanceof Object3D ? candidate : void 0;
+}
+function gameplayObservations(ctx, contactHistory, seed, replayRuntime) {
+  const animation = {};
+  const states = {};
+  const snapshot = ctx.entities.snapshot();
+  for (const id of Object.keys(snapshot)) {
+    const entity = ctx.entities.get(id);
+    if (typeof entity?.animation?.current === "string" && typeof entity.animation.advancedFrames === "number") {
+      animation[id] = {
+        advancedFrames: entity.animation.advancedFrames,
+        clip: entity.animation.current
+      };
+    }
+    if (typeof entity?.state === "string") states[id] = entity.state;
+  }
+  const channels = gameplayChannels();
+  const contacts = channels.includes("runtime.contacts") ? drainContacts(ctx, contactHistory) : void 0;
+  const tags = channels.includes("runtime.tags") ? tagCounts(snapshot) : void 0;
+  return {
+    animation,
+    ...contacts === void 0 ? {} : { contacts },
+    states,
+    ...tags === void 0 ? {} : { tags },
+    ...runtimeObservation(seed, replayRuntime)
+  };
+}
+function gameplayChannels(_ctx) {
+  return ["runtime.contacts", "runtime.tags"];
+}
+function drainContacts(ctx, history) {
+  for (const id of Object.keys(ctx.entities.snapshot())) {
+    for (const source of entitySources(ctx.entities.get(id))) {
+      for (const event of source.drainContacts()) {
+        const entity = findEntityId(ctx, event.body);
+        if (entity === void 0 || event.entity === void 0) continue;
+        history.push({
+          entity,
+          kind: event.started ? "trigger" : "trigger.exit",
+          with: event.entity
+        });
+        if (history.length > PLAYTEST_PROTOCOL_LIMITS.maxEventsPerDrain) history.shift();
+      }
+    }
+  }
+  return [...history];
+}
+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"
+  );
+}
+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)) {
+    for (const tag of fields.tags ?? []) counts[tag] = { count: (counts[tag]?.count ?? 0) + 1 };
+  }
+  return counts;
+}
+function componentObservations(snapshot) {
+  const components = {};
+  for (const [id, fields] of Object.entries(snapshot)) {
+    if (Object.keys(fields).length === 0) continue;
+    assertJsonSafe(fields, `$.components.${id}`);
+    components[id] = fields;
+  }
+  return components;
+}
+function stateResources(ctx) {
+  return {
+    read: () => {
+      ctx.state.flush();
+      const state = ctx.state.getState();
+      assertJsonSafe(state);
+      const value = state;
+      return { GameState: value, state: value };
+    }
+  };
+}
+
+export { playtest };

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@threenative/core",
+  "version": "0.1.0",
+  "description": "The small vanilla Three.js game runtime foundation.",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./playtest": {
+      "types": "./dist/playtest.d.ts",
+      "import": "./dist/playtest.js"
+    },
+    "./hot": {
+      "types": "./dist/hot.d.ts",
+      "import": "./dist/hot.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "three": "0.185.1",
+    "zustand": "5.x"
+  },
+  "devDependencies": {
+    "@types/three": "0.185.3",
+    "publint": "0.3.22",
+    "tsup": "8.5.1",
+    "typescript": "5.9.3",
+    "@threenative/playtest": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup --config tsup.config.ts && publint",
+    "typecheck": "tsc --noEmit",
+    "test": "pnpm run build"
+  }
+}