@volter/project 0.0.0-stage → 0.5.204

package/src/adapter/frame-capture.ts

@@ -0,0 +1,80 @@
+/**
+ * What a WebGL frame capture IS — the reading `SystemAdapters`'s frame-capture
+ * door answers with. The contract owns the shape; the instrument that records
+ * it shadow-patches a live WebGL2 context and is the game runtime's
+ * (`@volter/editor-game/runtime/dev/webgl-frame-capture`).
+ */
+
+/** The five WebGL2 draw entry points this instrument wraps. */
+export type FrameCaptureEntryPoint =
+  | 'drawArrays'
+  | 'drawElements'
+  | 'drawArraysInstanced'
+  | 'drawElementsInstanced'
+  | 'drawRangeElements';
+
+/** Per-draw attribution supplied by {@link WebGLFrameCapture.annotateNextDraw}
+ *  (the render adapter derives it from the three.js object about to draw). */
+export interface DrawAnnotation {
+  object: { name: string; type: string; entityId?: string };
+  geometry: { type: string; name: string; attributes: string[]; indexed: boolean };
+  material: { type: string; name: string };
+}
+
+/** Where a draw rendered: the default framebuffer (canvas) or a bound FBO. */
+export type DrawTarget =
+  | { kind: 'canvas' }
+  | {
+      kind: 'framebuffer';
+      /** Color-attachment width, or `null` when not cheaply queryable
+       *  (texture attachment — raw WebGL2 has no size query). */
+      width: number | null;
+      height: number | null;
+      /** Capture-local identity tag (`framebuffer#N`), not a GL debug name. */
+      label: string | null;
+    };
+
+export interface FrameCaptureDrawCall {
+  readonly index: number;
+  readonly entryPoint: FrameCaptureEntryPoint;
+  /** Decoded primitive mode, e.g. `'TRIANGLES'`, `'LINES'` (raw enum when
+   *  unrecognised). */
+  readonly mode: string;
+  /** Vertex/index count passed to the draw. */
+  readonly count: number;
+  /** Instance count for the instanced entry points, else `null` (not 0 —
+   *  a non-instanced draw has no instance count to report). */
+  readonly instanceCount: number | null;
+  /** Capture-local program identity (`program#N`), or `null` when no program
+   *  was bound via `useProgram`. */
+  readonly programLabel: string | null;
+  readonly target: DrawTarget;
+  /** Shadow-tracked viewport `[x, y, w, h]` at draw time. */
+  readonly viewport: readonly [number, number, number, number];
+  readonly state: {
+    readonly blend: boolean;
+    readonly depthTest: boolean;
+    readonly depthWrite: boolean;
+    readonly cull: 'front' | 'back' | 'none';
+    readonly scissor: boolean;
+  };
+  /** The annotation this draw consumed, or `null` when none was pending
+   *  (unattributed — e.g. a shadow/composer pass draw). */
+  readonly annotation: DrawAnnotation | null;
+}
+
+export interface FrameCapture {
+  readonly id: number;
+  /** Injected capture timestamp (ms) — see `createWebGLFrameCapture` options. */
+  readonly capturedAt: number;
+  readonly drawCalls: readonly FrameCaptureDrawCall[];
+  readonly totals: {
+    /** Draws RECORDED (excludes any dropped past the cap). */
+    readonly drawCalls: number;
+    /** Recorded draws with `annotation: null`. */
+    readonly unattributed: number;
+    /** Draws dropped because the cap was hit (0 when nothing was dropped). */
+    readonly truncated: number;
+  };
+  readonly notes: readonly string[];
+}

package/src/adapter/host-context.ts

@@ -0,0 +1,114 @@
+/** Host-provided surfaces for adapter mounting.
+ * Product-specific execution handles belong in that product's extension of
+ * these contexts; the shared project contract must not import its runtime.
+ */
+import type { AdapterSurface } from './adapter-surface';
+
+/** The canvas/container the game renders into, plus its size. */
+export interface HostSurface {
+  readonly canvas: HTMLCanvasElement;
+  readonly width: number;
+  readonly height: number;
+}
+
+/**
+ * The surface-INDEPENDENT half of every host context — see this file's header
+ * for ownership of product-specific extensions. Generic host code (a
+ * harness, a tier report, anything that must not care what it is mounting) can
+ * type against this; a real adapter always receives one of the per-surface
+ * contexts below.
+ */
+export interface HostContextBase {
+  /**
+   * No GPU/DOM/audio available (Node conformance tests). A first-party adapter
+   * skips postprocessing/render/audio/input-map loading but still builds the
+   * scene + Rapier + components, so its scene/authoring/physics can be exercised
+   * headlessly. Browser hosts leave this false/undefined → full behavior.
+   */
+  readonly headless?: boolean;
+}
+
+/**
+ * What a `three`-surface root is handed. This is the ONLY context carrying
+ * three's own objects — the split's entire point (see the header): a Pixi or
+ * React root is never handed a `WebGLRenderer` it cannot use. The objects are
+ * opaque here; `@volter/editor-threejs` names the Three-typed context, and a
+ * runtime names its own.
+ */
+export interface ThreeHostContext<Three = unknown, Renderer = unknown, Assets = unknown>
+  extends HostContextBase {
+  /** The ONE shared three instance — identity matters for capture (see ingest). */
+  readonly three: Three;
+  /** Canvas/container + size; a self-driven game may take the surface over. */
+  readonly surface: HostSurface;
+  /** Host renderer — host-driven games render through it. */
+  readonly renderer: Renderer;
+  /** Shared GLTF/texture cache. */
+  readonly assets: Assets;
+}
+
+/**
+ * What a `canvas`-surface root is handed: a raw canvas + its
+ * logical size, plus the
+ * compositing hints the multi-root host computes once for every stacked
+ * surface. No `three`, no `renderer`, no `assets` — a Pixi root builds its own
+ * `PIXI.Application` and its own asset cache from this.
+ */
+export interface CanvasHostContext extends HostContextBase {
+  readonly canvas: HTMLCanvasElement;
+  readonly width: number;
+  readonly height: number;
+  /** DPR override (T6.1 slice 1, D5 §3 — "one DPR
+   *  everywhere"): the roots-path host computes ONE dpr for every stacked
+   *  surface and passes it here; omitted -> the canvas adapter's own
+   *  default (`window.devicePixelRatio`, uncapped). */
+  readonly dpr?: number;
+  /** This root is stacked ABOVE another root (D5 §1): clear with alpha 0
+   *  instead of an opaque background so the layer below shows through. */
+  readonly transparent?: boolean;
+  /** Capture tier cost (D5 §4) — the renderer's `preserveDrawingBuffer`. */
+  readonly preserveDrawingBuffer?: boolean;
+}
+
+/**
+ * What a `dom`-surface root is handed (the shape `runtime/create-runtime.ts`
+ * used to spell `ReactRootHost`).
+ *
+ * `container` is the absolutely-positioned, z-ordered DOM-root layer `<div>`
+ * the host already created and stacked (same box/z-order rules as a canvas per
+ * D5 §1) — the adapter's `mount` renders its react tree INTO
+ * this exact element via `createRoot`; it must never create its own root
+ * element (the DOM analog of three's "the root's runtime renders into the
+ * surface it is handed" rule).
+ *
+ * `game` (inherited, and deliberately still optional): a
+ * `default-react` sibling mounted BESIDE an ingest root (`packages/editor/src/
+ * ingest-siblings.ts`) has no native `Game` to hand it — there is no
+ * first-party loop for the sibling to join, only the ingested
+ * root's own foreign runtime — so its host carries no `game` at all rather than
+ * fabricating an empty one (anti-shim rule); the sibling mounts its entry
+ * component bare, as every `dom` root renders. `mountOneReactRoot`
+ * (`runtime/create-runtime.ts`, the NATIVE multi-root runtime path) still
+ * ALWAYS supplies a real `game` — this optionality is reached only by the
+ * composite sibling's own hand-built host, never by weakening the native path's
+ * guarantee.
+ */
+export interface DomHostContext extends HostContextBase {
+  readonly container: HTMLElement;
+}
+
+/**
+ * Map an {@link AdapterSurface} to the host context that surface's roots are
+ * handed — the mirror image of `MountedRootFor<K>` (`root-adapter.ts`), and
+ * what makes `RootAdapter<K>.mount`'s PARAMETER K-typed. A hypothetical 4th
+ * surface resolves to `never` here, so it cannot be mounted until it declares
+ * its own context (the same fail-to-compile discipline `assertNever` gives the
+ * dispatch sites).
+ */
+export type HostContextFor<K extends AdapterSurface> = K extends 'three'
+  ? ThreeHostContext
+  : K extends 'canvas'
+    ? CanvasHostContext
+    : K extends 'dom'
+      ? DomHostContext
+      : never;

package/src/adapter/index.ts

@@ -0,0 +1,209 @@
+/**
+ * Adapter interfaces — the seams the engine host and the editor DEPEND ON.
+ *
+ *   host    → RootAdapter ← { the editor's R3F root mounts, IngestRootAdapter, … }
+ *   editor  → AuthoringAdapter ← { ThreeAuthoringAdapter, ReactRootAuthoringAdapter, … }
+ *   game    → SystemAdapters (physics/networking/navigation/audio/camera/debug)
+ *
+ * The first-party Rapier/Colyseus stack is ONE implementer of these
+ * interfaces, not the engine's vocabulary.
+ *
+ * **This module is TYPE-ONLY, and must stay that way (P-6).** It used to
+ * value-export its own implementers — `createRapierPhysicsAdapter`,
+ * `createColyseusNetworkingAdapter`, `createNavigationAdapter` — so
+ * `import type { AuthoringAdapter } from './index'` was the only
+ * thing keeping the three/Rapier/Colyseus stack out of a Pixi or React
+ * consumer's module graph. A seam that ships its implementers is not a
+ * seam. Import an implementer from its OWN path instead:
+ *
+ *   `@volter/threejs-runtime/adapter/rapier-physics-adapter`    createRapierPhysicsAdapter
+ *   `@volter/threejs-runtime/adapter/first-party-navigation-system`       createNavigationAdapter
+ */
+
+export type { AdapterSurface } from './adapter-surface';
+export type {
+  AssetDropContext,
+  AssetDropProvider,
+  AssetSubjectProvider,
+  AuthoringAdapter,
+  AuthoringAssetSubject,
+  AuthoringCapabilities,
+  AuthoringProvenance,
+  AuthoringProviderKey,
+  AuthoringTruth,
+  BoxEditProvider,
+  BoxEditReferencePoint,
+  ColorSampleProvider,
+  ComponentInstanceApplyResult,
+  ComponentInstanceDescription,
+  ComponentInstanceOverride,
+  ComponentInstancesProvider,
+  DOMRectLike,
+  EditorNode,
+  EditorNodeRole,
+  HierarchyProvider,
+  InspectorProvider,
+  NodeCreationSite,
+  PersistenceProvider,
+  PickProvider,
+  PropertyDescriptor,
+  FrameCorners,
+  RectProvider,
+  RelatedSubjectLink,
+  RelatedSubjectsProvider,
+  SelectionProvider,
+  SelectionResolution,
+  SpatialDragHandle,
+  SpatialHandleGuide,
+  SpatialHandleLayer,
+  SpatialHandlesProvider,
+  SpatialPoint3,
+  StoriesProvider,
+  StoryRef,
+  StructuralClipboardOutcome,
+  StructuralIdsWrite,
+  StructuralIdWrite,
+  StructuralWriteOutcome,
+  StructureProvider,
+  CreatableKind,
+  TextProvider,
+  TransformChannel,
+  TransformEditability,
+  TransformProvider,
+  TransformSourceCommitProvider,
+  TruthProvider,
+  WriteAck,
+  WriteAnchorKind,
+} from './authoring';
+export {
+  AUTHORING_PROVIDER_KEYS,
+  emptyWriteAnchorKindCounts,
+  measureAuthoringProviders,
+  WRITE_ANCHOR_KINDS,
+} from './authoring';
+export {
+  AUTHORING_ADAPTER_SHAPE,
+  AUTHORING_PROVIDER_SHAPES,
+  HIERARCHY_PROVIDER_SHAPE,
+} from './authoring-seam-contract';
+export type {
+  EntryStaticSurface,
+  ObservationBinding,
+  ProjectBinding,
+  ProjectionBinding,
+  ProtocolFamily,
+  RootBinding,
+  RootBindingParts,
+  RootDeclaration,
+  SubstrateBinding,
+  TruthBinding,
+} from './binding';
+export { createRootBinding } from './binding';
+export type {
+  CanvasHostContext,
+  DomHostContext,
+  HostContextBase,
+  HostContextFor,
+  HostSurface,
+  ThreeHostContext,
+} from './host-context';
+/** The offline-audio contract an `AudioAdapter.renderOffline` implements.
+ *  Defined beside the render-mode harness that first needed it; re-exported
+ *  here so a world binding the seam imports one name from one place. */
+export type { OfflineAudioRenderer, RenderedAudio } from './render-audio';
+export type {
+  MountedCanvasRoot,
+  MountedCanvasSubstrate,
+  MountedReactRoot,
+  MountedRoot,
+  MountedRootBase,
+  MountedThreeRoot,
+  RootAdapter,
+  RootStateObserver,
+  SurfaceAdapter,
+  SurfaceAdapterFor,
+} from './root-adapter';
+export {
+  MOUNTED_CANVAS_SURFACE_SHAPE,
+  MOUNTED_DOM_SURFACE_SHAPE,
+  MOUNTED_ROOT_BASE_SHAPE,
+  MOUNTED_THREE_SURFACE_SHAPE,
+  ROOT_ADAPTER_SHAPE,
+  ROOT_STATE_OBSERVER_SHAPE,
+} from './root-seam-contract';
+export type {
+  SeamEvidenceOutcome,
+  SeamEvidenceReceipt,
+  SeamEvidenceSource,
+  SeamEvidenceState,
+  SeamEvidenceVerdict,
+  SeamProofStage,
+  SeamShape,
+} from './seam-evidence';
+export {
+  defineSeamShape,
+  gradeSeamCarrier,
+  gradeSeamEvidence,
+  inspectSeamShape,
+  SEAM_PROOF_STAGES,
+  SeamEvidenceLedger,
+  seamStageAtLeast,
+} from './seam-evidence';
+export type {
+  AudioAdapter,
+  AudioDebugEvent,
+  AudioGraphNode,
+  AudioMeterFrame,
+  AudioMeterHandle,
+  AudioRecordingHandle,
+  AudioTransportState,
+  CameraAdapter,
+  CameraRuntimeCamera,
+  CameraRuntimeSnapshot,
+  CameraRuntimeTransition,
+  ConnectionState,
+  DebugAdapter,
+  NavCrowdAgentState,
+  NavigationAdapter,
+  NavPoint,
+  NetConditioning,
+  NetMessageEvent,
+  NetPeer,
+  NetPlayerIdentity,
+  NetConditioningLimits,
+  NetRates,
+  NetServerClient,
+  NetServerInspection,
+  NetServerRoom,
+  NetTypeTraffic,
+  NetEntityTraffic,
+  NetServerConfig,
+  NetworkingAdapter,
+  PhysicsAdapter,
+  PhysicsCarrier,
+  PhysicsColliderShape,
+  PhysicsColliderSnapshot,
+  PhysicsJointSnapshot,
+  PhysicsJointType,
+  RenderDebugAdapter,
+  ReplicationStats,
+  RoomInfo,
+  SystemAdapters,
+  Unsubscribe,
+} from './system-adapter';
+/** The two narrowings of the tagged `SystemAdapters['physics']` union — see
+ *  `PhysicsAdapter`'s comment for why it is tagged at all. */
+export { displayKeyedPhysics, nodeKeyedPhysics, physicsOwnerOf } from './system-adapter';
+export {
+  AUDIO_ADAPTER_SHAPE,
+  CAMERA_ADAPTER_SHAPE,
+  DEBUG_ADAPTER_SHAPE,
+  NAVIGATION_ADAPTER_SHAPE,
+  NETWORKING_ADAPTER_SHAPE,
+  PHYSICS_2D_ADAPTER_SHAPE,
+  PHYSICS_ADAPTER_SHAPE,
+  RENDER_DEBUG_ADAPTER_SHAPE,
+  SYSTEM_ADAPTERS_SHAPE,
+  SYSTEM_PROVIDER_SHAPES,
+} from './system-seam-contract';
+export type { Transform, TransformOwner } from './transform';

package/src/adapter/ingest/contract-system-slots.ts

@@ -0,0 +1,28 @@
+/**
+ * THE TWO VERDICTS a declared system slot can carry besides an adapter: a
+ * positive ABSENCE with the game's own evidence, and a MALFORMED declaration
+ * with the reason it could not be honoured.
+ *
+ * They are the contract's because the entry-module surface names them
+ * (`./native-entry-surface.ts`'s `NativeSystemsBinding.absent`) and the
+ * coverage report reads them; the projection that produces them is the game
+ * runtime's (`@volter/editor-game/runtime/adapter/ingest/contract-system-adapters`).
+ */
+
+import type { VolterGameSystemAdapters } from './game-contract';
+
+/** One system slot of the game contract, by name. */
+export type ContractSystemSlot = keyof VolterGameSystemAdapters;
+
+/** One slot the game positively answered as having nothing behind it. */
+export interface ContractSystemEmptySlot {
+  readonly slot: ContractSystemSlot;
+  /** The game's own source-level evidence, verbatim. */
+  readonly evidence: string;
+}
+
+/** One slot whose declaration could not be honoured, and why. */
+export interface ContractSystemMalformedSlot {
+  readonly slot: ContractSystemSlot;
+  readonly reason: string;
+}

package/src/adapter/ingest/game-contract-seams.ts

@@ -0,0 +1,86 @@
+/** Exhaustive proof requirements for the game→host contract. Declarations are
+ * intentionally insufficient for lifecycle, navigation, commands, state, and
+ * system carriers: their consumers must produce stronger receipts. */
+
+import { defineSeamShape } from '../seam-evidence';
+import type {
+  VolterGameCommand,
+  VolterGameContract,
+  VolterGameHierarchyGroup,
+  VolterGameLifecycle,
+  VolterGameScene,
+  VolterGameScenes,
+  VolterGameStateProvider,
+  VolterGameSystemAdapters,
+  VolterGameSystemEmpty,
+  VolterGameSystems,
+} from './game-contract';
+
+export const GAME_CONTRACT_SHAPE = defineSeamShape<VolterGameContract>()({
+  contractVersion: { optional: false, kind: 'value', required: 'shape' },
+  root: { optional: true, kind: 'value', required: 'effect' },
+  presentation: { optional: true, kind: 'value', required: 'effect' },
+  world: { optional: true, kind: 'value', required: 'effect' },
+  ready: { optional: true, kind: 'value', required: 'effect' },
+  lifecycle: { optional: true, kind: 'value', required: 'effect' },
+  scenes: { optional: true, kind: 'value', required: 'effect' },
+  systems: { optional: true, kind: 'value', required: 'operation' },
+});
+
+export const GAME_LIFECYCLE_SHAPE = defineSeamShape<VolterGameLifecycle>()({
+  start: { optional: true, kind: 'function', required: 'effect' },
+  pause: { optional: true, kind: 'function', required: 'effect' },
+  resume: { optional: true, kind: 'function', required: 'effect' },
+  dispose: { optional: true, kind: 'function', required: 'effect' },
+});
+
+export const GAME_SCENES_SHAPE = defineSeamShape<VolterGameScenes>()({
+  list: { optional: false, kind: 'function', required: 'operation' },
+  current: { optional: false, kind: 'function', required: 'operation' },
+  goTo: { optional: false, kind: 'function', required: 'effect' },
+});
+
+export const GAME_SCENE_SHAPE = defineSeamShape<VolterGameScene>()({
+  id: { optional: false, kind: 'value', required: 'shape' },
+  label: { optional: false, kind: 'value', required: 'shape' },
+});
+
+export const GAME_COMMAND_SHAPE = defineSeamShape<VolterGameCommand>()({
+  name: { optional: false, kind: 'value', required: 'shape' },
+  description: { optional: true, kind: 'value', required: 'shape' },
+  argsJsonSchema: { optional: true, kind: 'value', required: 'shape' },
+  run: { optional: false, kind: 'function', required: 'effect' },
+});
+
+export const GAME_STATE_PROVIDER_SHAPE = defineSeamShape<VolterGameStateProvider>()({
+  name: { optional: false, kind: 'value', required: 'shape' },
+  tier: { optional: true, kind: 'value', required: 'shape' },
+  read: { optional: false, kind: 'function', required: 'operation' },
+});
+
+export const GAME_HIERARCHY_GROUP_SHAPE = defineSeamShape<VolterGameHierarchyGroup>()({
+  id: { optional: false, kind: 'value', required: 'shape' },
+  label: { optional: false, kind: 'value', required: 'shape' },
+  count: { optional: false, kind: 'value', required: 'operation' },
+});
+
+export const GAME_SYSTEMS_SHAPE = defineSeamShape<VolterGameSystems>()({
+  commands: { optional: true, kind: 'value', required: 'operation' },
+  state: { optional: true, kind: 'value', required: 'operation' },
+  hierarchy: { optional: true, kind: 'function', required: 'operation' },
+  systemAdapters: { optional: true, kind: 'value', required: 'operation' },
+});
+
+export const GAME_SYSTEM_ADAPTERS_SHAPE = defineSeamShape<VolterGameSystemAdapters>()({
+  physics: { optional: true, kind: 'value', required: 'effect' },
+  networking: { optional: true, kind: 'value', required: 'operation' },
+  navigation: { optional: true, kind: 'value', required: 'operation' },
+  audio: { optional: true, kind: 'value', required: 'effect' },
+  camera: { optional: true, kind: 'value', required: 'effect' },
+  renderDebug: { optional: true, kind: 'value', required: 'effect' },
+});
+
+export const GAME_SYSTEM_EMPTY_SHAPE = defineSeamShape<VolterGameSystemEmpty>()({
+  present: { optional: false, kind: 'value', required: 'shape' },
+  evidence: { optional: false, kind: 'value', required: 'claim' },
+});