@vgai/engine 0.5.1 → 0.5.3

package/src/adapter/authoring.ts

@@ -8,7 +8,7 @@
  * interface and the advertised `capabilities` — it never branches on which
  * implementer it is talking to.
  *
- * The interface lives in the engine (not the editor) so `MountedGame.authoring`
+ * The interface lives in the engine (not the editor) so `MountedThreeRoot.authoring`
  * can reference it without the engine depending on the editor; implementers live
  * in `packages/editor/src/authoring/`.
  *
@@ -21,39 +21,34 @@
  */
 
 import type * as THREE from 'three';
-import type { SceneEntity } from '../scene/scene-types';
-import type { Transform, TransformOwner } from './transform';
+import type { Transform } from './transform';
 
-/** Booleans the editor UI gates affordances on (hide what an adapter can't do). */
+/**
+ * Booleans the editor UI gates affordances on (hide what an adapter can't do).
+ *
+ * Deliberately SMALL: a capability flag earns its place only when the shell
+ * actually branches on it. Structural affordances (create/delete/reparent) are
+ * gated by `structure` PROVIDER PRESENCE instead — the flag and the provider
+ * cannot disagree that way. (WO-2 deleted `material`/`create`/`delete`/
+ * `reparent`/`layout`, which no shell code ever read.)
+ */
 export interface AuthoringCapabilities {
   transform: boolean;
-  material: boolean;
   inspectorFields: boolean;
-  create: boolean;
-  delete: boolean;
-  reparent: boolean;
   persist: boolean;
-  /**
-   * UI layout authoring (anchors/offsets/pivot/flex) — distinct from 3D
-   * `transform`. Optional so existing 3D adapters need not declare it. A UI
-   * adapter sets this true and implements {@link LayoutProvider}; the 3D gizmo /
-   * TransformProvider are NOT the UI manipulation path (spec K7).
-   */
-  layout?: boolean;
 }
 
 /**
  * The adapter's own answer to "what is truth behind these rows, and how
- * writable is it" (spec 29 §5, docs/unified-world-editor/
- * 29-hierarchy-philosophy.md). Provenance never varies WITHIN one adapter's
+ * writable is it" (spec 29 §5). Provenance never varies WITHIN one adapter's
  * rows — it is a property of the world boundary — so it is declared ONCE per
  * adapter and rendered at the SEAM (the composite's `world:<id>` group row,
  * or the panel header for a bare adapter), never per row. Only the adapter
  * knows its truth: the shell must read this field, never guess from adapter
- * identity (rule zero). Machine-readable operation gates stay in
- * {@link AuthoringCapabilities}/provider presence — this type carries the
- * HUMAN explanation those gates can point at when an affordance is present
- * but unavailable.
+ * identity (rule zero). Machine-readable operation gates stay in {@link
+ * AuthoringCapabilities}/provider presence — this type carries the HUMAN
+ * explanation those gates can point at when an affordance is present but
+ * unavailable.
  */
 export interface AuthoringProvenance {
   /**
@@ -106,21 +101,16 @@ export interface EditorNode {
    * as `<header>` beneath a React component name or a document's file path. */
   secondaryLabel?: string;
   kind: 'mesh' | 'light' | 'camera' | 'group' | 'object' | (string & {});
+  /**
+   * What to CALL this node's type in the inspector header — the component or
+   * class an author thinks of it as, when that differs from the native `kind`
+   * the shell uses to pick an icon. An `<Enemy>` renders a `group`, but "group"
+   * is a fact about its implementation, not its identity; Godot names the class
+   * here and Unity names the prefab. Adapters that omit it keep showing `kind`.
+   */
+  typeLabel?: string;
   parentId: string | null;
   childIds: string[];
-  flags: {
-    runtimeOnly?: boolean;
-    locked?: boolean;
-    transformOwner?: TransformOwner;
-    /** D8 — member of a RootGroup, not the active one; children may be unloaded. */
-    inactiveRoot?: boolean;
-    /** Design state currently projected into the live authoring surface. */
-    active?: boolean;
-    /** The adapter resolved this boundary, but it is not editable here. */
-    readOnly?: boolean;
-    /** The adapter could not resolve the declared authoring boundary. */
-    error?: boolean;
-  };
 }
 
 export interface PropertyDescriptor {
@@ -130,25 +120,64 @@ export interface PropertyDescriptor {
   readonly?: boolean;
   options?: unknown[];
   /**
-   * Optional domain-shaped grouping (T3.4 slice 2, docs/ADAPTER-AUTHORING-
-   * DESIGN.md §1.E): properties sharing the same `group` label render
-   * together under a titled sub-section in the generic inspector, instead of
-   * the flat property grid. Backward-compatible — omitted (or two
-   * descriptors with different/no `group`) renders exactly as before this
-   * field existed. This is the ONLY authoring-richness addition v1 makes;
-   * there is no schema and no new PropertyDescriptor `type` — a custom
-   * adapter reports its own domain concepts (health/score/an enum, …) through
-   * the SAME provider, merely labeled into a named group.
+   * Optional domain-shaped grouping (T3.4 slice 2): properties sharing the
+   * same `group` label render together under a titled sub-section in the
+   * generic inspector, instead of the flat property grid. Backward-compatible
+   * — omitted (or two descriptors with different/no `group`) renders exactly
+   * as before this field existed. This is the ONLY authoring-richness
+   * addition v1 makes; there is no schema and no new PropertyDescriptor
+   * `type` — a custom adapter reports its own domain concepts
+   * (health/score/an enum, …) through the SAME provider, merely labeled into
+   * a named group.
    */
   group?: string;
+  /**
+   * The value shown is the DECLARED DEFAULT — the document does not carry this
+   * property, the thing that owns it does. Every mainstream inspector
+   * distinguishes these (Unity greys an unmodified field and bolds an
+   * overridden one) because otherwise you cannot tell what a document actually
+   * says from what it merely inherits. Editing a defaulted property writes it
+   * into the document for the first time.
+   */
+  defaulted?: boolean;
+  /**
+   * This property can be REMOVED from the document, reverting it to the
+   * declared default — Unity's revert arrow, Godot's reset arrow. Only set when
+   * removal is legal: the owner declares the property optional (or gives it a
+   * default), so dropping it leaves a still-valid document. The inverse of
+   * editing a `defaulted` property.
+   */
+  resettable?: boolean;
+  /**
+   * The SOURCE TEXT of the default a revert returns this property to (`1.55`,
+   * `'raider'`), so the revert affordance can name its destination instead of
+   * saying "default" and hoping.
+   *
+   * Set ONLY when the owner actually declares a default the adapter can read.
+   * Absence is the honest, common case: an optional property with no declared
+   * default is still removable — what takes over is then the owner's own
+   * internal fallback or nothing at all, which this side does not know. Never
+   * fill it with the property's CURRENT value: that is what the author is
+   * discarding, not what they get back.
+   */
+  revertsTo?: string;
 }
 
 export interface HierarchyProvider {
   roots(): EditorNode[];
   node(id: string): EditorNode | null;
-  /** The live object for raycast/gizmo binding (null for non-object nodes). */
-  object3D(id: string): THREE.Object3D | null;
-  idForObject3D(o: THREE.Object3D): string | null;
+  /**
+   * OPTIONAL, THREE-SPECIFIC — the live `Object3D` for raycast/gizmo binding
+   * (null for a node this adapter has no object for). A Pixi, DOM or React
+   * adapter has no `Object3D` at all: it OMITS this method rather than
+   * implementing a `() => null` stub that pretends the concept applies. Callers
+   * already treat `null` as "no object here", so absence and `null` mean the
+   * same thing to them — optional-chain it (`hierarchy.object3D?.(id) ?? null`).
+   */
+  object3D?(id: string): THREE.Object3D | null;
+  /** OPTIONAL, THREE-SPECIFIC — inverse of {@link object3D}. Same rule: an
+   *  adapter with no `Object3D` tree omits it. */
+  idForObject3D?(o: THREE.Object3D): string | null;
 }
 
 export interface SelectionProvider {
@@ -163,17 +192,13 @@ export interface SelectionProvider {
   ): SelectionResolution | null;
 }
 
-/** Adapter-owned result of semantic selection resolution. Separate ids keep
- * selection, inspection, and manipulation from becoming accidental aliases. */
+/** Adapter-owned result of semantic selection resolution: the raw native/render
+ * hit mapped to the node the author actually means. (The former
+ * `inspectorId`/`transformId`/`boundaryId` aliases were never read by the
+ * shell — deleted in WO-2.) */
 export interface SelectionResolution {
-  /** Hierarchy selection and default Inspector subject. */
+  /** Hierarchy selection and Inspector subject. */
   id: string;
-  /** Optional alternate Inspector subject. Defaults to {@link id}. */
-  inspectorId?: string;
-  /** Native transform subject. `null` means the selection is non-spatial. */
-  transformId?: string | null;
-  /** Nearest closed component/prefab/assembly boundary, when any. */
-  boundaryId?: string | null;
 }
 
 export type TransformChannel = 'position' | 'rotation' | 'scale';
@@ -188,7 +213,6 @@ export interface TransformProvider {
   /** Honest inspector presentation for the substrate's transform vocabulary. */
   dimensions?(id: string): '2d' | '3d' | null;
   get(id: string): Transform;
-  owner(id: string): TransformOwner;
   /** Pre-gesture persistence check. Omitted means the adapter's transform
    * capability applies uniformly. A false result must suppress manipulation
    * before the live object is moved, never discover refusal at drag end. */
@@ -199,6 +223,17 @@ export interface TransformProvider {
   endEdit(id: string): void;
 }
 
+/**
+ * One transform gesture event (see {@link AuthoringAdapter.observeTransforms}).
+ * `live` is a mid-gesture preview pose (the gizmo's live drag path); `commit`
+ * closes the gesture.
+ */
+export interface TransformObservation {
+  readonly id: string;
+  readonly transform: Transform;
+  readonly phase: 'live' | 'commit';
+}
+
 export interface InspectorProvider {
   /** Schema-driven — NOT fixed to `SceneEntity`. */
   properties(id: string): PropertyDescriptor[];
@@ -217,21 +252,33 @@ export interface InspectorProvider {
 }
 
 /**
- * UI layout authoring (K7) — anchors/offsets/pivot/flex props on a UI node. This
- * is the manipulation path for the DOM-overlay UI editor (handles, anchor presets,
- * flex inspector) and is deliberately SEPARATE from {@link TransformProvider}
- * (which is 3D position/quaternion/scale and cannot express flex/anchor layout).
- * The layout shape is format-neutral (a plain object the UI adapter understands).
+ * An authored node that is itself an asset, even when its bytes are embedded
+ * in another source document instead of living at a standalone project path.
+ *
+ * The first concrete case is inline SVG in a DOM/React root: its `<path>` and
+ * `<g>` implementation is no more part of the authoring hierarchy than the
+ * meshes inside an imported model. The adapter owns the native-to-asset
+ * conversion; the shell only opens the returned image in its ordinary Asset
+ * Editor document.
  */
-export interface LayoutProvider {
-  /** The node's current layout object (anchors/offsets/pivot/flex), or null. */
-  get(id: string): Record<string, unknown> | null;
-  /** Pause whatever drives layout (animation) before a gesture, if needed. */
-  beginEdit(id: string): void;
-  /** Apply a (partial) layout patch — merged onto the node's layout. */
-  apply(id: string, layoutPatch: Record<string, unknown>): void;
-  /** Commit the gesture (one undo step). */
-  endEdit(id: string): void;
+export interface AuthoringAssetSubject {
+  readonly kind: 'image';
+  readonly name: string;
+  readonly mediaType: 'image/svg+xml';
+  readonly text: string;
+  /** Project-root-relative source definition, when the adapter can prove it. */
+  readonly sourcePath?: string;
+}
+
+export interface AssetSubjectProvider {
+  get(id: string): AuthoringAssetSubject | null;
+  /**
+   * Assets known to this authoring document even when they are not in its
+   * currently focused hierarchy projection. React story boards use this to
+   * expose SVGs mounted in inactive story frames without flattening those
+   * frames into the active hierarchy.
+   */
+  entries?(): ReadonlyArray<{ id: string; subject: AuthoringAssetSubject }>;
 }
 
 export interface StructureProvider {
@@ -300,21 +347,18 @@ export interface StructureProvider {
 }
 
 /**
- * PersistenceProvider — whether and where an adapter's edits persist (design:
- * `docs/PERSISTENCE-PROVIDER-DESIGN.md` §2). The ACTIVE adapter's provider is the
- * ONE place this is decided — the host (editor) never hard-codes a destination or
- * guards on session flags; it asks the provider.
+ * PersistenceProvider — whether and where an adapter's edits persist (design).
+ * The ACTIVE adapter's provider is the ONE place this is decided — the host
+ * (editor) never hard-codes a destination or guards on session flags; it asks the
+ * provider.
  */
 export interface PersistenceProvider {
   isDirty(): boolean;
   /** Save to the adapter's OWN source of truth (.vscn / overlay file / …). */
   save(): Promise<void>;
-  serialize(): unknown;
-  /** Migration aid (first-party direction): pull a subtree into `.vscn` entities. */
-  captureToVscn?(ids: string[]): SceneEntity[];
   /**
    * Human/agent-readable destination this provider persists to — e.g.
-   * `"scenes/main.vscn.json"`, `".vgai/overlays/fps.json"`, or `"ephemeral
+   * `"scenes/main.vscn.json"`, `"live-only (not saved)"`, or `"ephemeral
    * (discarded on stop)"`. Drives the save-status UI and makes routing
    * inspectable (design §2). Implementers whose destination can change during
    * the session (e.g. the first-party provider tracks the loaded `.vscn` path)
@@ -378,43 +422,21 @@ export interface StoriesProvider {
   isolate?(nodeId: string | null, storyId?: string): void;
 }
 
-/** D6 (S-C) — GameComponent management; config editing stays on InspectorProvider. */
-export interface ComponentsProvider {
-  available(nodeId: string): string[];
-  list(nodeId: string): { type: string }[];
-  add(nodeId: string, type: string): void;
-  remove(nodeId: string, type: string): void;
-  /**
-   * OPTIONAL read accessor (W3.1, docs/DATA-TOOLS-DESIGN.md §3.3): the raw
-   * authored config record for one attached component (`list()` names the
-   * types; this reads one type's per-entity data), or `null` when the entity
-   * or component doesn't exist. Returns a shallow copy — callers must write
-   * through `InspectorProvider.set('components.<Type>.<field>', v)`, never by
-   * mutating this. Absent ⇒ config is not readable through this provider
-   * (tools degrade to `config: null`).
-   */
-  config?(nodeId: string, type: string): Record<string, unknown> | null;
+/**
+ * Where a drop landed, when the shell knows. The VIEWPORT knows a world point
+ * (its ground-plane raycast under the cursor); the hierarchy panel does not,
+ * and passes nothing. Optional both ways: an adapter with no placement concept
+ * ignores it, and a caller with no point omits it — so neither side has to
+ * pretend. Coordinates are world-space, in the adapter's own units.
+ */
+export interface AssetDropContext {
+  readonly position?: readonly [number, number, number];
 }
 
 /** Asset drop (hierarchy + viewport). */
 export interface AssetDropProvider {
   accepts(nodeId: string, assetPath: string): boolean;
-  drop(nodeId: string, assetPath: string): void | Promise<void>;
-}
-
-/** One adapter-owned reusable-entity format the shared hierarchy can save.
- * The adapter owns the bytes and semantics; the shell owns only the filename
- * dialog. This keeps native 2D entity assets out of Three prefab code while
- * preserving one editor language for the operation. */
-export interface EntityAssetSaveDescriptor {
-  defaultFolder: string;
-  extension: string;
-  label: string;
-}
-
-export interface EntityAssetProvider {
-  describeSave(nodeId: string): EntityAssetSaveDescriptor | null;
-  save(nodeId: string, path: string): Promise<boolean>;
+  drop(nodeId: string, assetPath: string, context?: AssetDropContext): void | Promise<void>;
 }
 
 /** Plain-object rect shape shared by {@link RectProvider} — the same fields a real
@@ -488,106 +510,6 @@ export interface BoxEditProvider {
   referencePoint?(id: string): BoxEditReferencePoint | null;
 }
 
-export interface TilemapCell {
-  column: number;
-  row: number;
-}
-
-/** One bounded native tile grid projected into the shared world overlay.
- * Geometry is affine and host-relative: `origin` is local cell corner [0,0],
- * while `columnStep`/`rowStep` are the transformed one-cell basis vectors.
- * This compact shape represents nested rotation, non-uniform scale, reflection,
- * and zoom without fabricating axis-aligned cell polygons. */
-export interface TilemapEditGrid {
-  columns: number;
-  columnStep: { x: number; y: number };
-  origin: { x: number; y: number };
-  palette: ReadonlyArray<{ frame: string; index: number }>;
-  rows: number;
-  rowStep: { x: number; y: number };
-}
-
-/** Native tile-cell authoring. Palette selection is editor-session state;
- * source truth receives only atlas-frame indices, with -1 meaning an empty cell.
- * begin/apply/end bracket one exact project-history transaction. */
-export interface TilemapEditProvider {
-  apply(id: string, cell: TilemapCell): void;
-  begin(id: string, tileIndex: number): void;
-  /** Resolve a host-relative pointer through the adapter's native transform. */
-  cellAt(id: string, point: { x: number; y: number }): TilemapCell | null;
-  end(id: string): void;
-  grid(id: string): TilemapEditGrid | null;
-  /** Load the native Pixi atlas used to render palette thumbnails. */
-  loadTileset(id: string): Promise<SpriteAtlas2D>;
-}
-
-export type PhysicsShape2DHandle = 'half-height' | 'half-width' | 'radius';
-
-/** One native 2D physics shape projected into host-relative viewport pixels.
- * `origin` is collider-local [0,0]; `xAxis`/`yAxis` are the transformed
- * one-pixel basis vectors. Keeping the complete affine basis preserves nested
- * rotation, non-uniform scale, reflection, centered canvas placement, and
- * viewport zoom without teaching the shared shell about Pixi or Rapier. */
-export interface PhysicsShape2DProjection {
-  collider:
-    | { shape: 'cuboid'; halfExtents: readonly [number, number] }
-    | { shape: 'ball'; radius: number }
-    | { shape: 'capsule'; halfHeight: number; radius: number };
-  editable: boolean;
-  id: string;
-  origin: { x: number; y: number };
-  sensor: boolean;
-  xAxis: { x: number; y: number };
-  yAxis: { x: number; y: number };
-}
-
-/** Adapter-owned native collider inspection and spatial editing. Shapes are
- * readable independently of editability so locked/read-only source remains
- * inspectable. begin/apply/end bracket one exact project-history transaction. */
-export interface PhysicsShape2DProvider {
-  apply(id: string, handle: PhysicsShape2DHandle, point: { x: number; y: number }): void;
-  begin(id: string, handle: PhysicsShape2DHandle): void;
-  end(id: string): void;
-  shapes(): readonly PhysicsShape2DProjection[];
-}
-
-/** One named sub-texture in a Pixi-compatible spritesheet atlas. `x`/`y` are
- * source-image pixels; width/height are the runtime-facing dimensions Pixi
- * swaps when `rotated` reports packed 90-degree storage. */
-export interface SpriteAtlasFrame2D {
-  height: number;
-  name: string;
-  rotated: boolean;
-  width: number;
-  x: number;
-  y: number;
-}
-
-export interface SpriteAtlas2D {
-  atlasPath: string;
-  frames: readonly SpriteAtlasFrame2D[];
-  /** Project-relative image source named by the atlas. */
-  imagePath: string;
-  /** Image bytes loaded through the owning adapter's storage backend. */
-  imageBytes: Uint8Array;
-  imageMediaType: string;
-}
-
-export interface SpriteFrames2DDescriptor {
-  atlasPath: string;
-  editable: boolean;
-  selectedFrame: string | null;
-}
-
-/** Source-backed Pixi spritesheet discovery and frame selection. Atlas parsing
- * remains adapter-owned; the universal Inspector only renders this projection.
- * `select` writes source truth and creates one project-history transaction. */
-export interface SpriteFrames2DProvider {
-  describe(id: string): SpriteFrames2DDescriptor | null;
-  load(id: string): Promise<SpriteAtlas2D>;
-  select(id: string, frame: string | null): void;
-}
-
 /** Text-content editing — currently OFF-contract (the react adapter has an `editText(id)`
  *  method, react-world-authoring-adapter.ts:728, not reachable via the contract). Bring it
  *  on so the overlay's double-click-to-edit-text (D3) is contract-driven. */
@@ -616,6 +538,27 @@ export interface ColorSampleProvider {
   backgroundChainAt(clientX: number, clientY: number): string[] | null;
 }
 
+/**
+ * WO-IDX1 — where a node's live object was CREATED in the game's own source.
+ *
+ * `display` is the `file:line` the editor shows verbatim. The unanchored shape
+ * carries a `reason` rather than a blank, because "we don't know" and "a
+ * library built it" are different facts and neither may present as silence
+ * (the honest-floor rule).
+ */
+export type NodeCreationSite =
+  | { anchored: true; file: string; line: number; col: number; display: string }
+  | { anchored: false; reason: string };
+
+/**
+ * Absent ⇒ this adapter's substrate has no creation-site index at all (a
+ * document-backed world's truth is the document, not a construction site).
+ * Present ⇒ every id gets an answer, anchored or reasoned.
+ */
+export interface CreationSiteProvider {
+  anchor(id: string): NodeCreationSite;
+}
+
 export interface AuthoringAdapter {
   readonly capabilities: AuthoringCapabilities;
   /** Spec 29 §5 — seam-level provenance ("what is truth behind these rows").
@@ -626,8 +569,8 @@ export interface AuthoringAdapter {
   readonly selection?: SelectionProvider;
   readonly transforms?: TransformProvider;
   readonly inspector?: InspectorProvider;
-  /** UI layout authoring path (K7) — present on UI adapters, absent on 3D adapters. */
-  readonly layout?: LayoutProvider;
+  /** The selected node is an atomic asset that can open in the Asset Editor. */
+  readonly assetSubject?: AssetSubjectProvider;
   readonly structure?: StructureProvider;
   readonly persistence?: PersistenceProvider;
   /** D8 — mutually-exclusive root groups (radio roots). Absent ⇒ no grouped roots. */
@@ -642,12 +585,6 @@ export interface AuthoringAdapter {
   /** T0 (spec 27 §2) — spatial drag-resize/move → source/data write for non-Object3D
    *  (DOM) nodes. Absent ⇒ no box-edit gesture for this adapter. */
   readonly boxEdit?: BoxEditProvider;
-  /** Native 2D physics debug geometry and shape handles. */
-  readonly physicsShapes2D?: PhysicsShape2DProvider;
-  /** Native Pixi spritesheet frame discovery/selection. */
-  readonly spriteFrames2D?: SpriteFrames2DProvider;
-  /** Native bounded tile-cell painting. Absent means no viewport tile editor. */
-  readonly tilemapEdit?: TilemapEditProvider;
   /** T0 (spec 27 §2) — double-click-to-edit-text on the contract (wires the react
    *  adapter's existing off-contract `editText`). Absent ⇒ no in-place text edit. */
   readonly text?: TextProvider;
@@ -656,16 +593,21 @@ export interface AuthoringAdapter {
   readonly colorSample?: ColorSampleProvider;
   /** D4 — storybook stories. Absent ⇒ no stories for any node in this adapter. */
   readonly stories?: StoriesProvider;
-  /** D6 (S-C) — GameComponent management. Absent ⇒ no component authoring. */
-  readonly components?: ComponentsProvider;
+  /** WO-IDX1 — the source location that constructed a node's live object.
+   *  Absent ⇒ this adapter indexes no creation sites. */
+  readonly creationSite?: CreationSiteProvider;
   /** Asset drop (hierarchy + viewport). Absent ⇒ this adapter accepts no drops. */
   readonly assetDrop?: AssetDropProvider;
-  /** Save a native entity subtree as an adapter-owned reusable asset. */
-  readonly entityAssets?: EntityAssetProvider;
-  /** Undo/redo for this adapter's edits (first-party delegates to the store; an
-   *  ingest adapter keeps its own overlay-backed stack). Absent ⇒ host falls back. */
-  undo?(): void;
-  redo?(): void;
   /** Change notification → UI refresh. */
   subscribe?(listener: () => void): () => void;
+  /**
+   * Observe transform GESTURES on this adapter's nodes — the one seam the
+   * animation sequencer needs to record a drag as keyframes and to refresh its
+   * design baselines. Deliberately narrow (one event shape, one consumer, no
+   * general event bus): before it existed, the sequencer could only observe
+   * the first-party store's own `.vscn` transform path, so a live or
+   * source-backed world's gestures were invisible to it. Absent ⇒ this
+   * adapter reports no gestures.
+   */
+  observeTransforms?(listener: (event: TransformObservation) => void): () => void;
 }

package/src/adapter/colyseus-networking-adapter.ts

@@ -19,6 +19,7 @@ import type {
   NetConditioning,
   NetMessageEvent,
   NetPeer,
+  NetPlayerIdentity,
   NetRates,
   NetworkingAdapter,
   ReplicationStats,
@@ -31,6 +32,16 @@ export interface ColyseusNetworkingConfig {
   localSessionId(): string | null;
   /** Peers currently in the room. */
   peers(): NetPeer[];
+  /**
+   * The game's own `id → Object3D` map (P-4). The SEAM
+   * (`NetworkingAdapter`) is keyed by node id so a non-three world can
+   * implement it at all; the accessors below stay `Object3D`-keyed because a
+   * three game already thinks in objects. This one member is the bridge, and
+   * it is the game's to declare — the engine never guesses an identity
+   * convention on a game's behalf. Returning `null` means "no such node here",
+   * and every accessor degrades exactly as it does for an unreplicated object.
+   */
+  resolve(nodeId: string): THREE.Object3D | null;
   /** Network id for an object, or null if it is not replicated (→ local authored). */
   networkId(o: THREE.Object3D): string | null;
   /** Owning peer/session id for a replicated object (null = server-owned). */
@@ -65,19 +76,36 @@ export interface ColyseusNetworkingConfig {
    *  must be supplied together for the inspector to show the controls. */
   getConditioning?(): NetConditioning;
   setConditioning?(c: NetConditioning): void;
+  /** Optional capability: read the local player's identity off the game's own
+   *  room state (→ adapter `getPlayerIdentity`, a seat label). Independent of
+   *  the setter below — a game can expose a read-only identity. */
+  playerIdentity?(): NetPlayerIdentity | undefined;
+  /** Optional capability: set the local player's identity through the game's own
+   *  mechanism (→ adapter `setPlayerIdentity`, an editable name field). Present
+   *  only when the game supports a settable name; drives the game's real path
+   *  (a join option the server honours, a rename message, …). */
+  setPlayerIdentity?(identity: NetPlayerIdentity): void | Promise<void>;
 }
 
 export function createColyseusNetworkingAdapter(cfg: ColyseusNetworkingConfig): NetworkingAdapter {
   const adapter: NetworkingAdapter = {
     peers: () => cfg.peers(),
-    networkId: (o) => cfg.networkId(o),
-    authority: (o) => {
-      if (cfg.networkId(o) == null) return 'local'; // not replicated → local authored
+    // The seam speaks node ids; `cfg.resolve` is the one crossing into Three's
+    // vocabulary. An unresolvable id behaves exactly like an unreplicated
+    // object — local authority, editable — rather than throwing or fabricating.
+    networkId: (nodeId) => {
+      const o = cfg.resolve(nodeId);
+      return o ? cfg.networkId(o) : null;
+    },
+    authority: (nodeId) => {
+      const o = cfg.resolve(nodeId);
+      if (!o || cfg.networkId(o) == null) return 'local'; // not replicated → local authored
       if (cfg.serverAuthoritative?.(o)) return 'server';
       return cfg.ownerId(o) === cfg.localSessionId() ? 'local' : 'remote';
     },
-    editable: (o) => {
-      if (cfg.networkId(o) == null) return true; // local authored object
+    editable: (nodeId) => {
+      const o = cfg.resolve(nodeId);
+      if (!o || cfg.networkId(o) == null) return true; // local authored object
       if (cfg.serverAuthoritative?.(o)) return false; // server owns it → inspect-only
       return cfg.ownerId(o) === cfg.localSessionId(); // only your own peer's objects
     },
@@ -102,5 +130,16 @@ export function createColyseusNetworkingAdapter(cfg: ColyseusNetworkingConfig):
     adapter.getConditioning = () => getConditioning();
     adapter.setConditioning = (c) => setConditioning(c);
   }
+  // Identity read and write are INDEPENDENTLY optional: a game may expose a
+  // read-only seat label (identity, no setter) or a settable name (both). The
+  // editor shows an editable field only when `setPlayerIdentity` is present.
+  const playerIdentity = cfg.playerIdentity?.bind(cfg);
+  if (playerIdentity) {
+    adapter.getPlayerIdentity = () => playerIdentity() ?? {};
+  }
+  const setPlayerIdentity = cfg.setPlayerIdentity?.bind(cfg);
+  if (setPlayerIdentity) {
+    adapter.setPlayerIdentity = (id) => setPlayerIdentity(id);
+  }
   return adapter;
 }