@volter/project 0.5.211 → 0.5.212

package/src/adapter/system-seam-contract.ts

@@ -4,25 +4,11 @@
 
 import type { PhysicsAdapter2D } from './physics-adapter-2d';
 import { defineSeamShape, type SeamShape } from './seam-evidence';
-import type {
-  AudioAdapter,
-  CameraAdapter,
-  DebugAdapter,
-  NavigationAdapter,
-  NetworkingAdapter,
-  PhysicsAdapter,
-  RenderDebugAdapter,
-  SystemAdapters,
-} from './system-adapter';
+import type { CameraAdapter, PhysicsAdapter, SystemAdapters } from './system-adapter';
 
 export const SYSTEM_ADAPTERS_SHAPE = defineSeamShape<SystemAdapters>()({
   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' },
-  debug: { optional: true, kind: 'value', required: 'operation' },
-  renderDebug: { optional: true, kind: 'value', required: 'effect' },
 });
 
 export const PHYSICS_ADAPTER_SHAPE = defineSeamShape<PhysicsAdapter>()({
@@ -48,91 +34,15 @@ export const PHYSICS_2D_ADAPTER_SHAPE = defineSeamShape<PhysicsAdapter2D>()({
   unfreeze: { optional: false, kind: 'function', required: 'effect' },
 });
 
-export const NETWORKING_ADAPTER_SHAPE = defineSeamShape<NetworkingAdapter>()({
-  peers: { optional: false, kind: 'function', required: 'operation' },
-  networkId: { optional: false, kind: 'function', required: 'operation' },
-  authority: { optional: false, kind: 'function', required: 'operation' },
-  editable: { optional: false, kind: 'function', required: 'operation' },
-  getConnectionState: { optional: true, kind: 'function', required: 'operation' },
-  getRoomInfo: { optional: true, kind: 'function', required: 'operation' },
-  getReplicationStats: { optional: true, kind: 'function', required: 'operation' },
-  subscribe: { optional: false, kind: 'function', required: 'effect' },
-  getStateSnapshot: { optional: true, kind: 'function', required: 'operation' },
-  messageEvents: { optional: true, kind: 'function', required: 'operation' },
-  getRates: { optional: true, kind: 'function', required: 'operation' },
-  getConditioning: { optional: true, kind: 'function', required: 'operation' },
-  setConditioning: { optional: true, kind: 'function', required: 'effect' },
-  getServerConfig: { optional: true, kind: 'function', required: 'operation' },
-  getPlayerIdentity: { optional: true, kind: 'function', required: 'operation' },
-  setPlayerIdentity: { optional: true, kind: 'function', required: 'effect' },
-  getTrafficByType: { optional: true, kind: 'function', required: 'operation' },
-  sendMessage: { optional: true, kind: 'function', required: 'effect' },
-  getConditioningLimits: { optional: true, kind: 'function', required: 'operation' },
-  ping: { optional: true, kind: 'function', required: 'effect' },
-  inspectServer: { optional: true, kind: 'function', required: 'operation' },
-  disconnectClient: { optional: true, kind: 'function', required: 'effect' },
-  editServerState: { optional: true, kind: 'function', required: 'effect' },
-  deleteServerState: { optional: true, kind: 'function', required: 'effect' },
-  sendToClient: { optional: true, kind: 'function', required: 'effect' },
-  broadcast: { optional: true, kind: 'function', required: 'effect' },
-  disposeRoom: { optional: true, kind: 'function', required: 'effect' },
-  stateFieldType: { optional: true, kind: 'function', required: 'operation' },
-  clearTraffic: { optional: true, kind: 'function', required: 'effect' },
-  getTrafficByEntity: { optional: true, kind: 'function', required: 'operation' },
-  isRecording: { optional: true, kind: 'function', required: 'operation' },
-  setRecording: { optional: true, kind: 'function', required: 'effect' },
-});
-
-export const NAVIGATION_ADAPTER_SHAPE = defineSeamShape<NavigationAdapter>()({
-  hasNavMesh: { optional: false, kind: 'function', required: 'operation' },
-  findPath: { optional: false, kind: 'function', required: 'effect' },
-  debugMesh: { optional: false, kind: 'function', required: 'operation' },
-  bake: { optional: true, kind: 'function', required: 'effect' },
-  exportData: { optional: true, kind: 'function', required: 'operation' },
-  clear: { optional: true, kind: 'function', required: 'effect' },
-  crowdAgents: { optional: true, kind: 'function', required: 'operation' },
-});
-
-export const AUDIO_ADAPTER_SHAPE = defineSeamShape<AudioAdapter>()({
-  resume: { optional: true, kind: 'function', required: 'effect' },
-  setMuted: { optional: false, kind: 'function', required: 'effect' },
-  isMuted: { optional: false, kind: 'function', required: 'operation' },
-  graphSnapshot: { optional: true, kind: 'function', required: 'operation' },
-  transportState: { optional: true, kind: 'function', required: 'operation' },
-  acquireMeters: { optional: true, kind: 'function', required: 'effect' },
-  acquireRecordingStream: { optional: true, kind: 'function', required: 'effect' },
-  renderOffline: { optional: true, kind: 'function', required: 'operation' },
-  audioEvents: { optional: true, kind: 'function', required: 'operation' },
-});
-
 export const CAMERA_ADAPTER_SHAPE = defineSeamShape<CameraAdapter>()({
   snapshot: { optional: false, kind: 'function', required: 'operation' },
   subscribe: { optional: false, kind: 'function', required: 'effect' },
 });
 
-export const DEBUG_ADAPTER_SHAPE = defineSeamShape<DebugAdapter>()({
-  providers: { optional: false, kind: 'function', required: 'operation' },
-  state: { optional: false, kind: 'function', required: 'operation' },
-  stateAll: { optional: false, kind: 'function', required: 'operation' },
-  commands: { optional: false, kind: 'function', required: 'operation' },
-  invoke: { optional: false, kind: 'function', required: 'effect' },
-  events: { optional: false, kind: 'function', required: 'operation' },
-});
-
-export const RENDER_DEBUG_ADAPTER_SHAPE = defineSeamShape<RenderDebugAdapter>()({
-  captureFrame: { optional: false, kind: 'function', required: 'effect' },
-  memorySnapshot: { optional: true, kind: 'function', required: 'operation' },
-});
-
 type NonPhysicsSystemSlot = Exclude<keyof SystemAdapters, 'physics'>;
 
 export const SYSTEM_PROVIDER_SHAPES: {
   readonly [K in NonPhysicsSystemSlot]: SeamShape<NonNullable<SystemAdapters[K]>>;
 } = {
-  networking: NETWORKING_ADAPTER_SHAPE,
-  navigation: NAVIGATION_ADAPTER_SHAPE,
-  audio: AUDIO_ADAPTER_SHAPE,
   camera: CAMERA_ADAPTER_SHAPE,
-  debug: DEBUG_ADAPTER_SHAPE,
-  renderDebug: RENDER_DEBUG_ADAPTER_SHAPE,
 };

package/src/adapter/transform.ts

@@ -1,7 +1,8 @@
 /**
  * The neutral transform value used across adapter interfaces. Position + scale
- * are xyz; rotation is a quaternion (xyzw) — matching `Object3D.quaternion`, so
- * adapters never have to agree on an Euler convention.
+ * are xyz; rotation is a quaternion (xyzw) — matching, e.g., the 3D
+ * integration's scene-object quaternion, so adapters never have to agree on an
+ * Euler convention.
  */
 export interface Transform {
   position: [number, number, number];
@@ -21,7 +22,7 @@ export interface Transform {
  * `'unresolved'` is the answer for a node THIS ADAPTER DOES NOT KNOW, and it is
  * a distinct answer on purpose: every other member names a driver, so returning
  * one of them for an unknown id is a positive claim about a node the
- * implementer has never seen. A game-scoped physics adapter is asked about
+ * implementer has never seen. A project-scoped physics adapter is asked about
  * every node the editor touches, including nodes belonging to another root —
  * "not mine" has to be sayable.
  */

package/src/adapter/workspace-arrangement.ts

@@ -1,52 +1,37 @@
-/** The editor's OWN captured dock arrangements (Animate, Look), shared data used by
- * imported layout components. A package's workspace ships its own beside its
- * layout contribution (`@volter/editor-blender`'s `model-arrangement.json`). */
+/**
+ * Dock arrangement data shared by layout contributions. Each package keeps
+ * its workspace arrangement beside the owning layout contribution.
+ */
 
 /**
- * ONE EDITOR AREA of a workspace, and the document that fills it.
- *
- * **A Blender editor AREA is an editor group; the drawer holds utilities**
- * (orchestrator ruling 2026-09-19, WORK.md I5). Blender's UV Editing is a
- * side-by-side split of the centre (786/785 measured on the engine), Shading
- * and Animation a top/bottom split, and both the dock and the frame have
- * exactly that shape in editor groups — a second group beside or below the
- * document, with the workspace's own split ratio. So the UV editor, the node
- * editor and the image view are DOCUMENTS a workspace opens
- * into editor groups, never drawer views; the drawer keeps the utilities that
- * are not Blender areas (Console, Profiler, Network).
- *
- * THIS AMENDS "a workspace positions chrome and dock groups only; it never
- * opens documents" (ARCHITECTURE-CORE §Editor chrome, 2026-08-30), and the
- * amendment is narrow: a workspace opens the documents ITS OWN REFERENCE
- * FRAME'S SCREEN HAS, named here, and never a session's content. That is why
- * `normalizePresetLayout` still strips every `kind: 'document'` panel out of a
- * captured arrangement — the capture carries the GROUP and its settled size,
- * this list carries which document fills it, and the two never overlap.
+ * A workspace editor area is an editor group filled by a declared document.
+ * Areas specify their position and initial split ratio; the drawer hosts
+ * utilities. Captured arrangements retain group geometry, while this list
+ * names each area’s document contribution. normalizePresetLayout removes
+ * captured document panels so the two declarations do not overlap.
  */
 export interface WorkspaceAreaContribution {
-  /** Stable area id, scoped to the workspace. BOTH hosts key an editor group by
-   *  it: the dock's group id is `volter:area:<id>`, and under the Code-OSS frame
-   *  it is the key of `volterDocuments.ts`'s `Map<areaId, IEditorGroup>` — the
-   *  group `IEditorGroupsService.addGroup` created from this area's `place`
-   *  (WORK.md §THE TIMELINE item 1, landed 2026-09-20). */
+  /**
+   * Stable workspace-scoped area id. The dock keys its group as
+   * volter:area:<id>; the native frame maps the same id to its editor group.
+   */
   readonly id: string;
-  /** The `workspace.document` CONTRIBUTION id this area opens (the
-   *  contribution's file-derived id, e.g. `blender-uv-editor.document`), not a
-   *  document id: the document is minted per open subject. */
+  /** The declared `workspace.document` contribution id this area opens.
+   * The document instance id is minted per open subject. */
   readonly document: string;
   /** Where the group sits relative to the centre document's group. */
   readonly place: 'left' | 'right' | 'above' | 'below';
-  /** The area's share of that split, 0..1 — Blender's own measured ratio,
-   *  cited by the workspace that declares it. It is the BOOTSTRAP size only:
+  /** The area's share of that split, 0..1, with its source cited by the
+   *  workspace that declares it. It is the BOOTSTRAP size only:
    *  once a capture of this workspace exists, the captured leaf's own size
    *  wins, exactly as the drawer's captured height wins over its default.
    *  Under the frame the same rule is `setSize` applied ONCE at group
    *  creation, against the two groups' combined extent — a person's drag on
    *  the sash is never overwritten, and a group they closed is re-created at
-   *  this ratio on the next reconcile, because a Blender area is resized or
-   *  joined, never closed. The one other stand-up is the area's document
+   *  this ratio on the next reconcile, because an area is resized or joined,
+   *  never closed. The one other stand-up is the area's document
    *  changing its job and asking for that job's size
-   *  (`@volter/sdk/kit/workspace-areas`' `setWorkspaceAreaRatio`). */
+   *  (editor-core's `src/workspace-areas.ts`' `setWorkspaceAreaRatio`). */
   readonly ratio: number;
 }
 
@@ -55,35 +40,30 @@ export interface WorkspaceArrangement {
   readonly id: string;
   readonly title: string;
   readonly regions?: {
-    /** The WORKSPACE tab strip in the top bar (Blender's); a click on a tab
+    /** The WORKSPACE tab strip in the top bar; a click on a tab
      *  is the explicit act that switches. Absent means hidden. */
     readonly workspaceTabs?: 'shown' | 'hidden';
     readonly header?: 'shown' | 'hidden';
     readonly shelf?: 'shown' | 'hidden';
     readonly inspector?: 'column' | 'properties';
     readonly drawer?: 'shown' | 'hidden';
-    /** The top bar's runtime TELEMETRY cluster — the frame-rate readout, its
-     *  sparkline and the audio meter. `hidden` leaves the corner to the quiet
-     *  product controls (Invite, Account); the Profiler utility remains the
-     *  door to the same numbers. Absent means shown. */
-    readonly telemetry?: 'shown' | 'hidden';
     /** The `·TypeName` a component-instance row prints after its name in the
-     *  hierarchy. `hidden` leaves the row its NAME alone, the way Blender's
-     *  Outliner does — there the type is the glyph. The type stays reachable
+     *  hierarchy. `hidden` leaves the row its NAME alone, for a look whose
+     *  type is the row's glyph. The type stays reachable
      *  through the row's own tooltip and the inspector. Absent means shown. */
     readonly hierarchyTypeSuffix?: 'shown' | 'hidden';
     /** The dotted RULE a component-instance row draws under its name in the
-     *  hierarchy. `hidden` leaves the name unmarked, the way Blender's Outliner
-     *  does — it marks an instance nowhere in that panel, in any selection
-     *  state. The fact stays reachable through the row's own tooltip, its Go to
+     *  hierarchy. `hidden` leaves the name unmarked, for a look that marks an
+     *  instance nowhere in that panel, in any selection state. The fact stays reachable through the row's own tooltip, its Go to
      *  Callsite / Open Component Source actions and the inspector. Absent means
      *  shown. */
     readonly hierarchyInstanceRule?: 'shown' | 'hidden';
     /** Which restriction columns a hierarchy row carries at its right edge:
      *  this editor's selection lock beside the eye (`select+viewport`), or
-     *  Blender's default filter (`viewport+render`) — the eye in its own
-     *  column with the render column reserved and blank, three.js having one
-     *  visibility flag for viewport and render alike. Absent means the pair. */
+     *  the viewport and render pair (`viewport+render`) — the eye in its own
+     *  column with the render column reserved and blank, since e.g. the 3D
+     *  integration's scene objects have one visibility flag for viewport and
+     *  render alike. Absent means the pair. */
     readonly hierarchyRestrictions?: 'select+viewport' | 'viewport+render';
   };
   /** The workspace's EDITOR AREAS beside the centre document — see

package/src/manifest/editor-port.ts

@@ -1,21 +1,7 @@
 /**
- * The editor's built-in port fallback, and the paired HMR-socket derivation.
- *
- * ONE owner for the number, because it is spelled in a launcher (the editor's `edit` command),
- * three servers (dev / prod / packaged), and a client default — a duplicated
- * literal across those drifts silently.
- *
- * **Why not Vite's 5173.** It used to be exactly that, and 5173 is the default
- * of every Vite app on the machine. On a box running any other Vite dev server
- * the engine-repo editor and that app fight over one port, and — worse —
- * `http://…:5173` can resolve to a FOREIGN application. Measured 2026-08-07:
- * an unrelated process on 5173 was what the editor's tab self-heal opened.
- *
- * **The band.** 20000-20199 is Volter's own reserved band: fixed, hand-picked
- * ports that must never be minted for a worktree session. Machine-local
- * allocations start at 20200, so one can never land on this default by chance.
- * 20173 keeps Vite's memorable `173` tail while sitting in a range nothing
- * else claims.
+ * The editor’s default port and paired HMR-socket port. Launchers, servers and
+ * clients share this constant. The reserved 20000–20199 band is excluded from
+ * machine-local session allocation, which starts at 20200.
  */
 export const DEFAULT_EDITOR_PORT = 20_173;
 
@@ -26,9 +12,8 @@ export const DEFAULT_EDITOR_PORT = 20_173;
  * worktree sessions cannot collide merely because their editor ports differ
  * by 100. Anything outside that band keeps the simple +100 offset.
  *
- * `DEFAULT_EDITOR_PORT` derives 30173 through the first arm — no special case,
- * which is the point: the old expression carried a hardcoded `5173 -> 24678`
- * exception precisely because the default sat outside the band it designed.
+ * `DEFAULT_EDITOR_PORT` derives 30173 through the first arm, with no special
+ * case.
  */
 export function editorHmrPort(editorPort: number): number {
   return editorPort >= 20_000 && editorPort < 30_100 ? editorPort + 10_000 : editorPort + 100;
@@ -44,23 +29,12 @@ function urlAuthorityHost(host: string): string {
 }
 
 /**
- * The ONE composer for an editor origin — every URL volter PRINTS, OPENS,
- * SELF-HEALS with, records in `.volter/session.json`, or dials.
- *
- * **It never says `localhost`.** A bare-`localhost` URL is a different address
- * from the one the server is listening on: on a dual-stack box `localhost`
- * resolves `::1` first while the editor binds `127.0.0.1`, so the URL reaches
- * whatever else happens to hold that port on IPv6. Measured 2026-08-07 — the
- * tab bijection's self-heal opened an UNRELATED application in the owner's
- * browser because it composed its reopen URL from `localhost` instead of the
- * host the server had actually bound.
+ * Compose an editor origin from its actual bind host. Callers that only know
+ * a port use IPv4 loopback. Wildcard binds also use loopback for a visitable
+ * local URL, including WSL2 loopback forwarding.
  *
- * `bindHost` is the host the server bound (`resolveBindHost`); callers that
- * only know a port — the CLI and SDK clients dialing a local session — omit it
- * and get the IPv4 loopback literal. A wildcard bind (`0.0.0.0` / `::`, which
- * is what WSL gets) is not an address a browser can visit, so it degrades to
- * that same literal: reachable from the same box, and reachable from Windows
- * through WSL2's loopback forwarding.
+ * A `localhost` URL can resolve to IPv6 while the server binds IPv4, reaching
+ * a different listener; emitted origins therefore use an explicit address.
  */
 export function editorOrigin(port: number, bindHost?: string): string {
   const host = (bindHost ?? '').trim();

package/src/manifest/filename.ts

@@ -1,45 +1,6 @@
-// The project manifest's FILENAME. There is exactly ONE.
-//
-// The manifest is `volter.project.json`, and NOTHING reads a second spelling
-// (the legacy-removal doctrine, `docs/ARCHITECTURE-CORE.md` §Vocabulary). Two
-// accepted names is the defect, not the convenience: both get written, and
-// copies of the "try both" probe spread into modules that agree with the real
-// resolver only by coincidence.
-//
-// The removed name REJECTS LOUDLY, naming the exact one-line fix — never
-// silently ignored, never redirected. A directory
-// carrying only `volter.game.json` is an error with a `git mv` in the message,
-// not a project that quietly fails to open.
-//
-// This module is the ONE place either literal is spelled out, and it is
-// dependency-free (no `node:fs`) so browser bundles can import it. The
-// filesystem side lives in `./locate` (`resolveManifestPath`, `hasManifest`,
-// `assertNoRemovedManifestFilename`).
+// The project manifest's FILENAME. There is exactly ONE, and this module is the one place it is
+// spelled out. It is dependency-free (no `node:fs`) so browser bundles can import it; the
+// filesystem side lives in `./locate` (`resolveManifestPath`, `hasManifest`).
 
 /** The manifest filename. Every reader reads it; every writer writes it. */
 export const MANIFEST_FILENAME = 'volter.project.json';
-
-/** The removed filename. Read by nothing — its only job is the error message. */
-export const REMOVED_MANIFEST_FILENAME = 'volter.game.json';
-
-/** True for the manifest filename (basename comparison). */
-export function isManifestFilename(name: string): boolean {
-  return name === MANIFEST_FILENAME;
-}
-
-/**
- * The verbatim rejection an on-disk `volter.game.json` earns — the one-line fix
- * spelled out, per the removed-format contract. Shared by the Node
- * (`./locate`) and browser (storage-backend) halves so a project author sees
- * the same sentence wherever the stale name is found.
- */
-export function removedManifestFilenameMessage(where: string): string {
-  return (
-    `${where}: found \`${REMOVED_MANIFEST_FILENAME}\` and no \`${MANIFEST_FILENAME}\`. ` +
-    `\`${REMOVED_MANIFEST_FILENAME}\` was REMOVED (the legacy-removal doctrine, ` +
-    'docs/ARCHITECTURE-CORE.md §Vocabulary) — nothing reads it any more, and it is ' +
-    'deliberately NOT read as a fallback, because a second accepted name is the defect.\n' +
-    `Fix: rename it — \`git mv ${REMOVED_MANIFEST_FILENAME} ${MANIFEST_FILENAME}\`. ` +
-    'The contents are unchanged; only the filename moved.'
-  );
-}

package/src/manifest/load-file.ts

@@ -1,13 +1,13 @@
-// T3.1 slice 1 — Node-only path wrapper around `loadGameManifest` (§5).
+// Node-only path wrapper around `loadProjectManifest`.
 //
 // Kept in its own module (rather than folded into `load.ts`) so that
-// `loadGameManifest` itself stays free of `node:fs` — anything that only
+// `loadProjectManifest` itself stays free of `node:fs` — anything that only
 // needs the pure parse/resolve function (e.g. a future browser/hosted-editor
 // caller) can import `./load` without pulling a Node-only module into its
 // bundle.
 
 import { readFileSync } from 'node:fs';
-import { type LoadGameManifestOptions, loadGameManifest, type ResolvedGameManifest } from './load';
+import { loadProjectManifest, type ResolvedProjectManifest } from './load';
 import { resolveManifestPath } from './locate';
 
 // The dual-name filesystem lookup lives in `./locate` (Zod-free on purpose);
@@ -15,19 +15,13 @@ import { resolveManifestPath } from './locate';
 // module.
 export { hasManifest, manifestWritePath, resolveManifestPath } from './locate';
 
-/** Read + JSON.parse `path`, then resolve it via `loadGameManifest`. Node-only. */
-export function loadGameManifestFile(
-  path: string,
-  options: LoadGameManifestOptions = {},
-): ResolvedGameManifest {
+/** Read + JSON.parse `path`, then resolve it via `loadProjectManifest`. Node-only. */
+export function loadProjectManifestFile(path: string): ResolvedProjectManifest {
   const raw: unknown = JSON.parse(readFileSync(path, 'utf-8'));
-  return loadGameManifest(raw, options);
+  return loadProjectManifest(raw);
 }
 
-/** {@link loadGameManifestFile} against `dir`'s `volter.project.json`. */
-export function loadGameManifestDir(
-  dir: string,
-  options: LoadGameManifestOptions = {},
-): ResolvedGameManifest {
-  return loadGameManifestFile(resolveManifestPath(dir), options);
+/** {@link loadProjectManifestFile} against `dir`'s `volter.project.json`. */
+export function loadProjectManifestDir(dir: string): ResolvedProjectManifest {
+  return loadProjectManifestFile(resolveManifestPath(dir));
 }