@volter/project 0.5.211 → 0.5.213

package/src/adapter/adapter-module.ts

@@ -1,46 +1,14 @@
 /**
- * `editor/volter.adapter.ts` — THE ADAPTER MODULE CONTRACT.
+ * The project’s `editor/volter.adapter.ts` default-exports a definition created
+ * by {@link defineAdapter}. Regions and documents are strict, validated data;
+ * editor Layout, style and keymap are imported runtime values. Unknown keys
+ * are rejected.
  *
- * ARCHITECTURE-CORE §The editor protocol, "The adapter is the game's own
- * module": the editor is a universal CLIENT of a fixed protocol and every game
- * supplies a SERVER — its adapter. That adapter is the game's OWN module,
- * `editor/volter.adapter.ts`, sitting beside `volter.project.json`, default-exporting
- * {@link defineAdapter}'s result.
- *
- * It is CODE (bindings are expressions — a scene entry may carry a closure the
- * host evaluates against the mounted game) with a CONFIG's discipline: the top
- * level is a STATICALLY EVALUABLE BINDING TABLE, readable without booting the
- * game. Concretely, that is the split this module enforces:
- *
- *   - the TABLE SHAPE — regions, the scene table, observation declarations —
- *     is plain data, validated by {@link AdapterDefinitionSchema} the moment
- *     the module is evaluated. `.strict()` throughout: an unrecognized key is
- *     an error naming the key, never a silent pass-through (CLAUDE.md,
- *     "Unknown input must REJECT LOUDLY").
- *   - individual FIELDS may be closures, evaluated lazily against the mounted
- *     game (`ObservationDeclaration.answer`). A closure is never required to
- *     read the table. `editor.Layout` is an imported React component: the
- *     editor invokes it to compose surfaces and edit/play behavior. It is a
- *     runtime value, never a serialized manifest setting or a registry key.
- *
- * **Zero inference.** A binding is a DECLARATION or a finder SELECTION the
- * adapter makes — never something the host sniffs out. Finder algorithms
- * (scenes from an entrypoint selection, prefabs from story registrations, …)
- * ship host-side under `adapter/finders/`, and this module names them by
- * SELECTION only ({@link FinderSelection}). That is deliberate and load-bearing
- * twice over:
- *   1. the engine never runs a finder nobody selected — enforced mechanically
- *      by `packages/engine/test/finder-import-boundary.test.ts`, whose only
- *      sanctioned importer of the finder namespace is the editor's adapter
- *      loader;
- *   2. this module therefore imports NOTHING from `adapter/finders/`, so a
- *      game's `editor/volter.adapter.ts` pulls no finder implementation (and no source
- *      parser) into its own bundle. The dependency runs one way: finders
- *      import their parameter types from HERE.
- *
- * The manifest keeps only what must be readable without evaluating any module
- * — identity, roots, boot mode, `server.room`. Everything that binds behavior
- * is the adapter's. This wave adds NO manifest field.
+ * Bindings explicitly declare values or select host-side finders. This module
+ * contains finder parameter types and selections without importing finder
+ * implementations, so project bundles do not pull in host source parsers.
+ * The manifest retains project identity and roots; the
+ * adapter binds behavior.
  */
 
 import type { KeymapContribution, StyleContribution } from './editor-looks';
@@ -50,52 +18,46 @@ import type { ResolvedAdapterRoot } from '../manifest/load';
 import type { AdapterSurface } from './adapter-surface';
 import { WRITE_ANCHOR_KINDS, type WriteAnchorKind } from './authoring';
 
+/** Where the adapter module lives, relative to the project's `volter.project.json`. */
+export const ADAPTER_MODULE_FILENAME = 'editor/volter.adapter.ts';
+
 // ---------------------------------------------------------------------------
 // Regions
 // ---------------------------------------------------------------------------
 
 /**
- * The native substrate serving a region. A surface is only the host-provided
- * medium (`canvas`); this declaration is what distinguishes Pixi, Babylon and
- * Phaser without runtime sniffing.
- */
-export const SUBSTRATE_NAMES = ['three', 'pixi', 'dom', 'babylon', 'phaser'] as const;
-export type SubstrateName = (typeof SUBSTRATE_NAMES)[number];
-
-/**
- * A region's WORLD BASIS — which axis points up, and where its ground sits.
- *
- * The editor needs a ground plane to place a dropped asset or a probe point on.
- * That plane used to be the constant `y = 0` compiled into `editor-viewport.ts`,
- * which is a guess about the GAME's convention: a Z-up world (the CAD/Blender
- * idiom foreign R3F games routinely carry) got its drops silently projected onto
- * the wrong plane. It is exactly the shape "zero inference" names — a fact the
- * game's author can state, so the fix is a declaration slot rather than a
- * smarter sniff (ARCHITECTURE-CORE §The editor protocol).
+ * A substrate an installed integration serves, as it registers it through its serving half
+ * (`ProjectServingModule.substrates`, `@volter/sdk/session/project-serving`). A surface is only
+ * the host-provided medium (`canvas`); the substrate is the library a project declares on it, and
+ * this registration is what makes that declaration known to the editor. `project` names no
+ * substrate itself: a region's declared {@link AdapterRegion.substrate} is validated against the
+ * registered names ({@link parseAdapterDefinition}), and a `manifest-roots` region takes its
+ * surface's {@link SubstrateRegistration.default} row ({@link regionsFromManifestRoots}).
  */
-export interface AdapterRegionBasis {
-  /** World axis pointing away from the ground. */
-  readonly up: 'y' | 'z';
-  /** Ground offset along {@link up}, in world units. */
-  readonly groundHeight: number;
+export interface SubstrateRegistration {
+  /** The name a region declares in `substrate`. */
+  readonly substrate: string;
+  /** The surface this substrate serves. */
+  readonly surface: AdapterSurface;
+  /** The source dialects, by name (a spelling of source on this substrate), that a region on it
+   *  may declare in {@link AdapterRegion.dialect}. */
+  readonly dialects: readonly string[];
+  /**
+   * The default row for {@link surface}: the dialect (one of {@link dialects}) and anchors a
+   * first-party root of that surface gets when no explicit `regions` list says otherwise. Absent
+   * when this substrate is not the surface's default.
+   */
+  readonly default?: {
+    readonly dialect: string;
+    readonly anchors: readonly WriteAnchorKind[];
+  };
 }
 
-/**
- * The NATIVE basis — what {@link regionsFromManifestRoots} emits and what a
- * region that declares none is read as. +Y up, ground at 0: three.js' own
- * convention, which every first-party root is authored in. Stated as a value so
- * "the default" has one home instead of a copy at each reader.
- */
-export const NATIVE_REGION_BASIS: AdapterRegionBasis = Object.freeze({
-  up: 'y',
-  groundHeight: 0,
-});
-
 /**
  * One matrix REGION: a root, its surface, and the library selections that
  * serve it. Universality lives at region granularity — which libraries serve a
- * surface is a per-surface ENGINE fact, so a new surface root in an existing
- * game is one manifest line and one derived region, never new adapter code
+ * surface is a per-surface fact its integration registers, so a new surface root in an existing
+ * project is one manifest line and one derived region, never new adapter code
  * (that is exactly what {@link regionsFromManifestRoots} does).
  */
 export interface AdapterRegion {
@@ -103,13 +65,17 @@ export interface AdapterRegion {
   readonly id: string;
   /** What the host hands this root. */
   readonly surface: AdapterSurface;
-  /** Native substrate, by name. */
-  readonly substrate: SubstrateName;
   /**
-   * Dialect writer, by name (`r3f`, `jsx`, `pixi-react`, …) — the truth
-   * family's source writer for this region. `null` states outright that the
-   * host writes no source here: the region's truth is the game's own code,
-   * which the host does not author (a module or ingest root).
+   * Native substrate, by a registered name ({@link SubstrateRegistration}). `null` when the
+   * derivation names none: no installed integration gives this region's surface a default row, or
+   * the registrations are unknown.
+   */
+  readonly substrate: string | null;
+  /**
+   * The source dialect, by name: the spelling of source the host writes for this region, one of
+   * its substrate's registered {@link SubstrateRegistration.dialects}. `null` states outright
+   * that the host writes no source here: the region's truth is the project's own code, which the
+   * host does not author (a module or ingest root).
    */
   readonly dialect: string | null;
   /**
@@ -118,29 +84,22 @@ export interface AdapterRegion {
    * the matrix, which is a work order — never a silently unsupported edit.
    */
   readonly anchors: readonly WriteAnchorKind[];
-  /**
-   * This region's world basis. Omitted = {@link NATIVE_REGION_BASIS}, which is
-   * a DECLARED default (the native adapter emits it outright), not a silent
-   * fallback — same shape as an absent `editor/volter.adapter.ts` meaning
-   * `nativeAdapter()`.
-   */
-  readonly basis?: AdapterRegionBasis;
   /**
    * Project-relative globs naming source files this region OWNS, for the
    * ambiguous remainder that import reach cannot place.
    *
    * A file's surface/dialect is derived from WHICH REGION'S IMPORT CLOSURE
    * reaches it — a load-bearing fact, because the region's manifest entry is
-   * what the host actually executes at mount (the game would break first if it
+   * what the host actually executes at mount (the project would break first if it
    * lied). Reach through several regions of the SAME surface is unambiguous;
    * reach through regions of DIFFERING surfaces, or through none at all, is
-   * genuinely undecidable from outside, and this is where the game's author
+   * genuinely undecidable from outside, and this is where the project's author
    * states the answer instead of the host guessing it from the file's bytes.
    *
-   * READER: `packages/sdk/src/kit/ui-source/file-region-resolver.ts`'s
+   * READER: `packages/sdk/src/ui-source/file-region-resolver.ts`'s
    * `resolveFileRegion`, consulted BEFORE reach — a declared include wins,
    * because it is a first-party statement about this exact file. Every OID
-   * stamping tier, the HMR classifier, the R3F authoring diagnostics and
+   * stamping tier, the HMR classifier, the dialect's authoring diagnostics and
    * Content's component grouping read that one resolver.
    *
    * {@link regionsFromManifestRoots} emits none: the native default is PURE
@@ -157,18 +116,13 @@ export interface AdapterRegion {
    * Surfaces this root mounts BESIDE {@link AdapterRegion.surface}, each with
    * the source files that render on it. Together with `surface` — the manifest
    * root's own adapter, which is always the PRIMARY — this states the root's
-   * FULL mounted surface set (decision, 2026-08-16; ARCHITECTURE-CORE §The
-   * editor protocol).
+   * FULL mounted surface set.
    *
-   * A root is not always one surface. The shipped case is an R3F game whose
-   * `three` root mounts a canvas AND adopts a DOM HUD beside it
-   * (`adoptGameDomRoot` already adopts the pair together): its HUD modules
-   * render react-dom host elements, and `userData-oid` on a `<div>` is a prop
-   * react-dom does not recognize, so the editor must know they are the `dom`
-   * half. Before this slot there was nowhere to say so — `id` names the
-   * manifest root this region grades, so a second `dom` region for such a root
-   * would either name a root the host would try to MOUNT (fabrication, which
-   * the anti-shim rule forbids) or name no root at all.
+   * One root may mount several surfaces, such as a canvas and a DOM overlay.
+   * The declared surface determines how each source file is stamped: React DOM
+   * elements need DOM OIDs, while `userData-oid` belongs to a stage element.
+   * Additional surfaces belong to this root's `mounts`; a separate region would
+   * identify another manifest root for the host to mount.
    *
    * Each mount's `include` is REQUIRED and carries the same glob vocabulary as
    * {@link AdapterRegion.include} (`**`, `*`, `?`). A mount with no files would
@@ -176,7 +130,7 @@ export interface AdapterRegion {
    * no question any reader asks.
    *
    * READER: the same one — `resolveFileRegion`'s rung 1. A file claimed by a
-   * region's own `include` AND by a mount is a contradiction in the game's own
+   * region's own `include` AND by a mount is a contradiction in the project's own
    * declaration and settles nothing, exactly as two regions claiming one file
    * do; it falls through to reach, and failing that to the caller's loud
    * ambiguous path.
@@ -203,7 +157,7 @@ export interface AdapterRegionMount {
 const AdapterRegionMountSchema = z
   .object({
     surface: z
-      .enum(['three', 'canvas', 'dom'])
+      .enum(['stage', 'canvas', 'dom'])
       .describe('An additional surface this root mounts, beside the manifest root’s own adapter'),
     include: z
       .array(z.string().min(1))
@@ -215,32 +169,28 @@ const AdapterRegionMountSchema = z
   })
   .strict();
 
-const AdapterRegionBasisSchema = z
-  .object({
-    up: z.enum(['y', 'z']).describe('World axis pointing away from the ground'),
-    groundHeight: z.number().describe('Ground offset along `up`, in world units'),
-  })
-  .strict();
-
 const AdapterRegionSchema = z
   .object({
     id: z.string().min(1).describe('Manifest root id this region grades'),
-    surface: z.enum(['three', 'canvas', 'dom']).describe('Render surface the host hands this root'),
-    substrate: z.enum(SUBSTRATE_NAMES).describe('Native substrate serving this region, by name'),
+    surface: z.enum(['stage', 'canvas', 'dom']).describe('Render surface the host hands this root'),
+    substrate: z
+      .string()
+      .min(1)
+      .describe(
+        'Native substrate serving this region, by name; the editor validates it against the ' +
+          'substrates its installed integrations register',
+      ),
     dialect: z
       .string()
       .min(1)
       .nullable()
       .describe(
-        'Dialect writer serving this region, by name; null states outright that the host writes ' +
-          "no source here (the region's truth is the game's own code)",
+        "Source dialect of this region, by name, one of its substrate's registered dialects; null " +
+          "states outright that the host writes no source here (the region's truth is the project's own code)",
       ),
     anchors: z
       .array(z.enum(WRITE_ANCHOR_KINDS as [WriteAnchorKind, ...WriteAnchorKind[]]))
       .describe('Anchor kinds this region’s writer serves'),
-    basis: AdapterRegionBasisSchema.optional().describe(
-      'World basis (up axis + ground height); omit for the native +Y / 0 default',
-    ),
     include: z
       .array(z.string().min(1))
       .min(1)
@@ -263,7 +213,7 @@ const AdapterRegionSchema = z
 /**
  * How a definition supplies its regions: the RULE `'manifest-roots'` (the
  * native default — a declaration may be a rule rather than a list, the way
- * `roots[]` never enumerates a world's contents), or an explicit list a game
+ * `roots[]` never enumerates a world's contents), or an explicit list a project
  * with novel bindings states outright.
  */
 export type RegionBinding = 'manifest-roots' | readonly AdapterRegion[];
@@ -280,32 +230,9 @@ const RegionBindingSchema = z.union([
  * neither is a fact the manifest states: which files a region owns beyond
  * its entry's reach, and which surfaces its root mounts beside its own.
  */
-export interface AdapterRegionOverlay {
-  /** See {@link AdapterRegion.include}. */
-  readonly include?: readonly string[];
-  /** See {@link AdapterRegion.mounts}. */
-  readonly mounts?: readonly AdapterRegionMount[];
-}
+export type AdapterRegionOverlay = Pick<AdapterRegion, 'include' | 'mounts'>;
 
-const AdapterRegionOverlaySchema = z
-  .object({
-    include: z
-      .array(z.string().min(1))
-      .min(1)
-      .optional()
-      .describe(
-        'Project-relative globs (`**`, `*`, `?`) naming source files this derived region owns, ' +
-          'for files no root entry’s import closure reaches; a declared include wins over reach',
-      ),
-    mounts: z
-      .array(AdapterRegionMountSchema)
-      .min(1)
-      .optional()
-      .describe(
-        'Surfaces this root mounts BESIDE its own adapter, each with the files that render on ' +
-          'them; with the derived region’s own surface, the root’s full mounted surface set',
-      ),
-  })
+const AdapterRegionOverlaySchema = AdapterRegionSchema.pick({ include: true, mounts: true })
   .strict()
   .refine((value) => value.include !== undefined || value.mounts !== undefined, {
     message:
@@ -314,22 +241,10 @@ const AdapterRegionOverlaySchema = z
   });
 
 /**
- * PARAMETERS FOR THE RULE, keyed by manifest root id (decision, 2026-08-17;
- * ARCHITECTURE-CORE §The editor protocol, "Declared includes LAYER onto the
- * manifest-roots rule").
- *
- * The finder-selection shape, one level up: `regions: 'manifest-roots'` SELECTS
- * the mechanical derivation, and this table DECLARES the per-region parameters
- * it cannot derive. The two compose — {@link regionsFromManifestRoots} merges
- * them — so a first-party project states one include without hand-writing its
- * whole region table, and adding a root still grows the table for free.
- *
- * Illegal beside an explicit `regions` LIST, and rejected by name: that form is
- * the full REPLACEMENT, and its entries carry `include`/`mounts` themselves.
- * Two homes for one fact is how a declaration goes stale in one of them.
- *
- * MEASURED BASIS: a replace-only region binding means no `nativeAdapter()`
- * project can declare a single include without restating every region.
+ * Per-root parameters for the `manifest-roots` region rule.
+ * {@link regionsFromManifestRoots} merges these includes and mounts into its
+ * derived regions. An explicit region list carries its own parameters and
+ * cannot be combined with this table.
  */
 const RegionIncludesSchema = z
   .record(z.string().min(1), AdapterRegionOverlaySchema)
@@ -344,48 +259,43 @@ const RegionIncludesSchema = z
  * RESOLVED manifest (`@volter/project/manifest/load` already decided both — this never
  * re-derives them).
  *
- * The per-surface library table below is an ENGINE fact, stated once:
+ * Which library serves a surface is not this module's to say: each surface's
+ * row is the {@link SubstrateRegistration.default} an installed integration
+ * registers, passed in as `registered`:
  *
- * | root `adapter`        | projector | dialect       | anchors                                              |
- * |-----------------------|-----------|---------------|------------------------------------------------------|
- * | `three`               | `three`   | `r3f`         | source-prop, source-structure, construction-literal  |
- * | `canvas`              | `pixi`    | `pixi-react`  | source-prop, source-structure, construction-literal  |
- * | `dom`                 | `dom`     | `jsx`         | source-prop, source-structure                        |
- * | `{module,surface}`    | (surface) | `null`        | live-only                                            |
- * | `{ingest,surface}`    | (surface) | `null`        | live-only                                            |
+ * | root `adapter`     | substrate         | dialect           | anchors           |
+ * |--------------------|-------------------|-------------------|-------------------|
+ * | a surface          | its default row's | the row's dialect | the row's anchors |
+ * | a surface, no row  | `null`            | `null`            | live-only         |
+ * | unknown rows       | `null`            | `null`            | none              |
+ * | `{module,surface}` | its default row's | `null`            | live-only         |
+ * | `{ingest,surface}` | its default row's | `null`            | live-only         |
  *
- * `source-structure` rides with every first-party dialect because all three
- * write through the SAME structural door (`/__ui-source/struct`) — a region
- * that can rewrite a JSX attribute in a file can rewrite that file's element
- * tree. It is listed separately rather than folded into `source-prop` because
- * they are different doors: a lane could lose one and keep the other, and the
- * matrix has to be able to say so.
+ * A root whose surface no integration serves gets a region all the same,
+ * because the region's id and surface are what file placement reads; it names
+ * no substrate and declares `live-only`, since no dialect writer authors it.
  *
- * A module/ingest root's truth is the game's own source, which no first-party
+ * A module/ingest root's truth is the project's own source, which no first-party
  * dialect writer authors — so it declares `live-only` rather than implying a
  * write path it does not have. That is a red cell and therefore a work order,
  * which is the point of stating it.
  *
- * Every derived region carries {@link NATIVE_REGION_BASIS} outright, so the
- * editor's ground plane READS a declaration on the native path too — the
- * default is published, never assumed at the read site.
- *
  * It DERIVES no {@link AdapterRegion.include} and no {@link AdapterRegion.mounts},
  * and there is no derivation that could: the manifest states ONE adapter per
  * root and names only its entry, so a root's extra owned files and its second
- * mounted surface are facts only the game can state. It states them as
+ * mounted surface are facts only the project can state. It states them as
  * `regionIncludes` PARAMETERS, which this function merges onto the region it
- * derives for that root — the rule stays selected, the parameters are declared
- * (ARCHITECTURE-CORE §The editor protocol, "Declared includes LAYER onto the
- * manifest-roots rule"). A key naming no declared root merges onto nothing;
+ * derives for that root — the rule stays selected, the parameters are declared.
+ * A key naming no declared root merges onto nothing;
  * the LOADER reports that, because only it can see both sides.
  */
 export function regionsFromManifestRoots(
   roots: readonly ResolvedAdapterRoot[],
+  registered: readonly SubstrateRegistration[],
   regionIncludes: Readonly<Record<string, AdapterRegionOverlay>> = {},
 ): AdapterRegion[] {
   return roots.map((root) => ({
-    ...derivedRegion(root),
+    ...derivedRegion(root, registered),
     ...overlayOf(regionIncludes[root.id]),
   }));
 }
@@ -412,38 +322,22 @@ export function unmatchedRegionIncludeIds(
 }
 
 /** One root's region, before any declared parameters are merged onto it. */
-function derivedRegion(root: ResolvedAdapterRoot): AdapterRegion {
+function derivedRegion(
+  root: ResolvedAdapterRoot,
+  registered: readonly SubstrateRegistration[],
+): AdapterRegion {
   const surface = root.surface;
+  const row = registered.find((entry) => entry.surface === surface && entry.default !== undefined);
   const firstParty = root.adapter.type === 'builtin';
-  const substrate: SubstrateName = surface === 'canvas' ? 'pixi' : surface;
-  const basis = NATIVE_REGION_BASIS;
-  if (!firstParty) {
-    return {
-      id: root.id,
-      surface,
-      substrate,
-      dialect: null,
-      anchors: ['live-only'] as const,
-      basis,
-    };
-  }
-  if (surface === 'dom') {
-    return {
-      id: root.id,
-      surface,
-      substrate,
-      dialect: 'jsx',
-      anchors: ['source-prop', 'source-structure'] as const,
-      basis,
-    };
+  if (!row?.default) {
+    return { id: root.id, surface, substrate: null, dialect: null, anchors: ['live-only'] as const };
   }
   return {
     id: root.id,
     surface,
-    substrate,
-    dialect: surface === 'three' ? 'r3f' : 'pixi-react',
-    anchors: ['source-prop', 'source-structure', 'construction-literal'] as const,
-    basis,
+    substrate: row.substrate,
+    dialect: firstParty ? row.default.dialect : null,
+    anchors: firstParty ? [...row.default.anchors] : (['live-only'] as const),
   };
 }
 
@@ -459,8 +353,8 @@ export const EXPORTED_COMPOSITION_REGIONS = 'exported-composition-regions';
 
 /**
  * `scenesFromEntrypointSelection` — read the entrypoint's ACTIVE-SCENE
- * SELECTION, the load-bearing reference (the game itself executes it, so it
- * cannot drift: the game would break first).
+ * SELECTION, the load-bearing reference (the project itself executes it, so it
+ * cannot drift: the project would break first).
  */
 export interface ScenesFromEntrypointSelectionParams {
   readonly finder: 'scenesFromEntrypointSelection';
@@ -484,21 +378,9 @@ export interface ScenesFromEntrypointSelectionParams {
   readonly selection?: string;
 }
 
-/**
- * `prefabsFromStories` — read the colocated portable-CSF story registrations.
- * A prefab is an ordinary source component a designer independently places,
- * declared by a story whose `meta.component` names it; the story registration
- * is the load-bearing reference here (removing it removes the declaration).
- * Zero parameters: the selection IS the whole configuration.
- */
-export interface PrefabsFromStoriesParams {
-  readonly finder: 'prefabsFromStories';
-}
-
 /**
  * A finder selection: the finder's registered NAME plus its own parameters.
- * The set of finders is OPEN (ARCHITECTURE-CORE §The editor protocol,
- * "Documents, not scenes"): the engine's own register in
+ * The set of finders is OPEN: the engine's own register in
  * `adapter/finders/registry.ts`, a contribution registers more, and this
  * module validates only the envelope — each finder's parameters are checked
  * against ITS schema the moment the loader runs it, loudly and by name.
@@ -517,70 +399,72 @@ const FinderSelectionSchema = z
 // ---------------------------------------------------------------------------
 
 /**
- * How the RUNNING game is navigated to an entry — the `reachable` honesty
+ * Where a `root-mount` entry sits in its region's entrypoint: the key it holds in
+ * the entrypoint's module-level selection table.
+ */
+interface RootMountSelection {
+  /** Identifier of the table (`const <table> = { <key>: <Component>, … }`). */
+  readonly table: string;
+  readonly key: string;
+  /**
+   * The entrypoint indexes its table with this key right now
+   * (`scenes[activeScene]`), so mounting the region renders this entry: it is the
+   * region's standing document in Edit. Absent when the key cannot be read
+   * statically; never a guess.
+   */
+  readonly active?: boolean;
+}
+
+/**
+ * How the RUNNING project is navigated to an entry — the `reachable` honesty
  * clause, stated rather than assumed. An entry whose reach is `none` is a
  * declared-but-unreachable scene: a red cell carrying its own reason.
  */
 export type SceneReach =
-  /** Mounting the region IS opening it — the single-composition degenerate case. */
-  | { readonly kind: 'root-mount' }
   /**
-   * The entrypoint's own selection table reaches it under `key`.
-   *
-   * `active` is the SECOND load-bearing fact about the same slot: the
-   * entrypoint indexes its table with one key right now (`scenes[activeScene]`),
-   * and that key's composition is literally what mounting the region renders.
-   * So an active entry is the region's own standing document — it NAMES that
-   * document rather than earning a second one beside it, exactly as
-   * `root-mount` does. Absent means "not known to be the one at the slot",
-   * which is the honest answer whenever the key cannot be read statically; it
-   * is never a guess, and it is per-entry because two regions each have their
-   * own slot with its own occupant.
+   * Mounting the entry's region opens it. Without `selection`, the region mounts
+   * one composition and this entry is it. With `selection`, the region's
+   * entrypoint renders `table[key]` at its swap slot, so the region mounted at
+   * that key opens this entry.
    */
-  | {
-      readonly kind: 'entrypoint-selection';
-      readonly selection: string;
-      readonly key: string;
-      readonly active?: boolean;
-    }
+  | { readonly kind: 'root-mount'; readonly selection?: RootMountSelection }
   /** A portable story mounts it in isolation. */
   | { readonly kind: 'story'; readonly storyId: string }
   /**
-   * The RUNNING game's own published scenes contract reaches it, under
-   * `sceneId` (`adapter/ingest/game-contract.ts`'s `scenes.list()` ids).
+   * The RUNNING project's own published scenes contract reaches it, under
+   * `sceneId` (one of the ids its `scenes.list()` publishes).
    *
-   * This is the LIVE reach: opening it while playing means asking the game to
-   * navigate, the way its own buttons do. An authorable entry that also names
-   * `source` can independently own an Edit isolation document; reach never
-   * decides whether a source composition can be mounted as a piece.
+   * An authorable entry that also names `source` owns an isolation document;
+   * reach never decides whether a source composition can be mounted as a piece.
    *
    * A DECLARATION, never an inference: the host does not sniff a mapping
    * between a table entry and a contract id, and it does not assume the two
-   * vocabularies coincide. The adapter states which contract id this entry is,
-   * and the host validates that id against the game's OWN `list()` at the
-   * moment it navigates — so a game that stops publishing the scene refuses by
-   * name instead of navigating somewhere else.
+   * vocabularies coincide. The adapter states which contract id this entry is.
    */
-  | { readonly kind: 'game-contract'; readonly sceneId: string }
+  | { readonly kind: 'project-contract'; readonly sceneId: string }
   /** Declared, with no code path that opens it. */
   | { readonly kind: 'none'; readonly reason: string };
 
-const SceneReachSchema = z.union([
-  z.object({ kind: z.literal('root-mount') }).strict(),
+const SceneReachSchema = z.discriminatedUnion('kind', [
   z
     .object({
-      kind: z.literal('entrypoint-selection'),
-      selection: z.string().min(1),
-      key: z.string().min(1),
-      active: z.boolean().optional(),
+      kind: z.literal('root-mount'),
+      selection: z
+        .object({
+          table: z.string().min(1),
+          key: z.string().min(1),
+          active: z.boolean().optional(),
+        })
+        .strict()
+        .optional(),
     })
     .strict(),
   z.object({ kind: z.literal('story'), storyId: z.string().min(1) }).strict(),
-  z.object({ kind: z.literal('game-contract'), sceneId: z.string().min(1) }).strict(),
+  z.object({ kind: z.literal('project-contract'), sceneId: z.string().min(1) }).strict(),
   z.object({ kind: z.literal('none'), reason: z.string().min(1) }).strict(),
 ]);
 
-/** Where an entry's composition lives in the game's own source. */
+/** Where an entry's composition lives in the project's own source. */
 export interface SceneSource {
   /** Project-relative path. */
   readonly path: string;
@@ -595,15 +479,12 @@ const SceneSourceSchema = z
 /**
  * One entry of the scene table. Scenes and prefabs are SIBLINGS here — both
  * are registered compositions the editor opens in isolation through the same
- * verb, differing only in instance site (ARCHITECTURE-CORE §Roots: "A scene is
- * a ROLE, not a kind … the same kind of thing as a prefab").
+ * verb, differing only in instance site.
  */
 export interface DocumentEntry {
   readonly id: string;
   readonly label: string;
-  /** `scene` (swaps at the entrypoint's slot) or `prefab` (placed by a designer). */
-  /** OPEN: `scene` and `prefab` are the first two kinds; a page, a component,
-   *  a model, a bake are kinds the same way. */
+  /** Open document kind, such as scene, prefab, page, component, model or bake. */
   readonly kind: string;
   /** Owning region id; `null` for a project-scoped entry bound to no one root. */
   readonly region: string | null;
@@ -614,12 +495,11 @@ export interface DocumentEntry {
   readonly authorable: boolean;
   readonly reach: SceneReach;
   readonly source?: SceneSource;
-  /** Optional adapter-declared prerequisite run before `source` is constructed
-   *  in Edit isolation. The export is a zero-argument function; the host never
-   *  infers setup from neighboring filenames or game globals. */
-  readonly isolationSetup?: SceneSource;
   /** Which finder produced it; absent = the adapter stated it outright. */
   readonly finder?: string;
+  /** `true` = its editor opens it before its file is written, and its first save writes the file: what `editor.open`
+   *  of its id opens when the file is not there yet. */
+  readonly opensUnwritten?: boolean;
 }
 
 const DocumentEntrySchema = z
@@ -631,8 +511,8 @@ const DocumentEntrySchema = z
     authorable: z.boolean(),
     reach: SceneReachSchema,
     source: SceneSourceSchema.optional(),
-    isolationSetup: SceneSourceSchema.optional(),
     finder: z.string().min(1).optional(),
+    opensUnwritten: z.boolean().optional(),
   })
   .strict();
 
@@ -659,171 +539,37 @@ const AdapterDocumentTableSchema = z
   })
   .strict();
 
-// ---------------------------------------------------------------------------
-// Observation
-// ---------------------------------------------------------------------------
-
-/**
- * The two faces a declaration projects onto. They are exactly the two
- * `DebugAdapter` halves (`adapter/system-adapter.ts`): `state` becomes a
- * provider (`providers()` / `state(name)`), `command` becomes a verb
- * (`commands()` / `invoke(name, args)`). There is deliberately no third kind —
- * see {@link OBSERVATION_KIND_REFUSAL}.
- */
-export const OBSERVATION_KINDS = ['command', 'state'] as const;
-export type ObservationKind = (typeof OBSERVATION_KINDS)[number];
-
-/**
- * Why a declaration may not name a `SystemAdapters` slot here.
- *
- * A game's system slots are already declared through the game contract's own
- * `systemAdapters` carrier (`adapter/ingest/game-contract.ts`), which validates
- * each slot per-surface and reports a malformed one BY NAME
- * (`contract-system-adapters.ts`). A second door onto the same slots is exactly
- * the two-declarations-one-slot problem `game-contract.ts` records for `debug`,
- * where it says outright that a second door "would let a game declare two
- * different debug planes with no rule for which wins".
- */
-const OBSERVATION_KIND_REFUSAL =
-  "observation.kind must be 'command' or 'state' — the two DebugAdapter faces a declaration " +
-  'projects onto. A SystemAdapters slot is declared through the game contract’s `systemAdapters` ' +
-  'carrier, which validates it per-surface; declaring one here would be a second door onto the ' +
-  'same slot with no rule for which wins.';
-
-/**
- * One statically declared observation slot. Declaring a slot and ANSWERING it
- * live are separate facts (the two-state rule): a slot declared here whose
- * `answer` throws, whose `answer` is absent, or whose game never booted reads as
- * broken, never as "the game has none". The projector
- * (`adapter/ingest/observation-debug-adapter.ts`) keeps that distinction: an
- * unanswerable slot is still LISTED, and refuses by name when read.
- */
-export interface ObservationDeclaration {
-  readonly id: string;
-  readonly kind: ObservationKind;
-  readonly description?: string | undefined;
-  /** Command execution side; omitted means a local app-owned command. */
-  readonly locus?: 'client' | 'server' | undefined;
-  /**
-   * Lazily evaluated against the mounted game. The field may be a closure; the
-   * TABLE around it stays statically readable, which is the whole discipline.
-   *
-   * What `game` IS is the host's to hand over and is stated at the projector:
-   * for an ingest mount it is the REALM the game's own modules ran in, because
-   * a foreign game's public handles are the only thing the host can honestly
-   * pass (`observation-debug-adapter.ts`).
-   */
-  readonly answer?: (game: unknown, ...args: unknown[]) => unknown;
-}
-
-const ObservationDeclarationSchema = z
-  .object({
-    id: z.string().min(1),
-    kind: z.enum(OBSERVATION_KINDS, { error: () => OBSERVATION_KIND_REFUSAL }),
-    description: z.string().min(1).optional(),
-    locus: z.enum(['client', 'server']).optional(),
-    answer: z
-      .custom<(game: unknown) => unknown>((value) => typeof value === 'function', {
-        message: 'observation.answer must be a function evaluated against the mounted game',
-      })
-      .optional(),
-  })
-  .strict()
-  .refine((value) => value.kind === 'command' || value.locus === undefined, {
-    path: ['locus'],
-    message: 'observation.locus is valid only for a command declaration',
-  });
-
-// ---------------------------------------------------------------------------
-// Native input
-// ---------------------------------------------------------------------------
-
-/** The action value shapes the session input door already speaks. */
-export const ADAPTER_INPUT_VALUE_TYPES = [
-  'digital',
-  'scalar',
-  'vector2',
-  'pointerDelta',
-  'pointerPosition',
-] as const;
-export type AdapterInputValueType = (typeof ADAPTER_INPUT_VALUE_TYPES)[number];
-export type AdapterInputValue = boolean | number | { readonly x: number; readonly y: number };
-
-/** One action in an app-owned input store. */
-export interface AdapterInputAction {
-  readonly name: string;
-  readonly valueType: AdapterInputValueType;
-}
-
-/**
- * Adapter-side binding from the universal session input door to a game's
- * ordinary input store. The game owns both its physical-device listeners and
- * its state; this table only tells the host how to drive that same state for a
- * bot or live REPL session. No component imports this contract.
- */
-export interface AdapterInputBinding {
-  /** Manifest root whose native scheduler consumes these actions. */
-  readonly root: string;
-  /** Current action vocabulary. A closure permits an app-owned dynamic map. */
-  readonly actions: (game: unknown) => readonly AdapterInputAction[];
-  /** Apply one action through the app's own input-store write path. */
-  readonly set: (game: unknown, action: string, value: AdapterInputValue) => void;
-  /** Release every app-owned virtual action. */
-  readonly clear: (game: unknown) => void;
-}
-
-const AdapterInputBindingSchema = z
-  .object({
-    root: z.string().min(1),
-    actions: z.custom<AdapterInputBinding['actions']>((value) => typeof value === 'function', {
-      message: 'input.actions must be a function returning the app-owned action vocabulary',
-    }),
-    set: z.custom<AdapterInputBinding['set']>((value) => typeof value === 'function', {
-      message: 'input.set must be a function writing the app-owned input store',
-    }),
-    clear: z.custom<AdapterInputBinding['clear']>((value) => typeof value === 'function', {
-      message: 'input.clear must be a function releasing app-owned virtual actions',
-    }),
-  })
-  .strict();
-
 // ---------------------------------------------------------------------------
 // The definition
 // ---------------------------------------------------------------------------
 
 /** Project-owned editor defaults. User layout choices remain session state. */
-export interface AdapterEditorLayoutProps {
-  readonly playing: boolean;
-  readonly paused: boolean;
-}
 export interface AdapterEditorConfiguration {
-  /** Imported React implementation; owns both composition and edit/play presentation. */
-  readonly Layout?: ComponentType<AdapterEditorLayoutProps>;
+  /** Imported React component the editor renders as its composition. */
+  readonly Layout?: ComponentType;
 
   /**
-   * The project's LOOK, imported from the package that carries it
-   * (`@volter/editor-blender`'s `blenderStyle`). Palette, material, icon set and chrome
-   * regions in one object — the same `StyleContribution` the package's
-   * `workspace.style` contribution registers, named here as the project's
-   * choice. Beneath a person's own settings and above their cross-project
-   * ones (`settings-store.ts`).
+   * A style this project PINS, imported from the package that carries it
+   * (`<package>`'s exported style): the same `StyleContribution` the package's
+   * `workspace.style` contribution registers, with the colour theme it was drawn with. Set, it
+   * outranks a person's cross-project choice (`settings-store.ts`); left out, the project wears
+   * the product's default, its built-in extension's `configurationDefaults`, and a person chooses
+   * freely. Projects `create` scaffolds leave it out.
    */
   readonly style?: StyleContribution;
-  /** The project's KEY BINDINGS, imported the same way (`blenderKeymap`). */
+  /** The project's KEY BINDINGS, imported the same way (`<package>`'s exported keymap). */
   readonly keymap?: KeymapContribution;
 
   /** Registered workspace to open when this checkout has no saved workspace. */
   readonly workspace?: string;
   /** Inspector layout beneath the active workspace and the user's override. */
   readonly inspector?: 'column' | 'properties' | 'card';
-  /** Utility registry ids to reveal when Play settles; omitted means none. */
-  readonly playUtilities?: readonly string[];
 }
 
 const AdapterEditorConfigurationSchema = z
   .object({
     Layout: z
-      .custom<ComponentType<AdapterEditorLayoutProps>>(
+      .custom<ComponentType>(
         (value) => typeof value === 'function',
         'Layout must be an imported React component',
       )
@@ -848,7 +594,6 @@ const AdapterEditorConfigurationSchema = z
       .optional(),
     workspace: z.string().min(1).optional(),
     inspector: z.enum(['column', 'properties', 'card']).optional(),
-    playUtilities: z.array(z.string().min(1)).optional(),
   })
   .strict();
 
@@ -864,24 +609,20 @@ export interface AdapterDefinition {
    */
   readonly regionIncludes: Readonly<Record<string, AdapterRegionOverlay>>;
   readonly documents: AdapterDocumentTable;
-  readonly observation: readonly ObservationDeclaration[];
-  readonly input?: AdapterInputBinding | undefined;
 }
 
-/** What a game writes. Every field optional — the near-empty adapter is the
- *  first-party case, and an adapter's SIZE measures the game's distance from
+/** What a project writes. Every field optional — the near-empty adapter is the
+ *  first-party case, and an adapter's SIZE measures the project's distance from
  *  native. */
 export interface AdapterDefinitionInput {
   readonly editor?: AdapterEditorConfiguration;
   readonly regions?: RegionBinding;
   readonly regionIncludes?: Readonly<Record<string, AdapterRegionOverlay>>;
   readonly documents?: AdapterDocumentTable;
-  readonly observation?: readonly ObservationDeclaration[];
-  readonly input?: AdapterInputBinding | undefined;
 }
 
 /**
- * Why the two forms may not be combined, said in the error a game's author
+ * Why the two forms may not be combined, said in the error a project's author
  * reads. An explicit region list REPLACES the derivation and its entries carry
  * `include`/`mounts` themselves; layering a second table over it would put one
  * fact in two homes, with no rule for which wins.
@@ -892,14 +633,12 @@ const REGION_INCLUDES_WITH_LIST_REFUSAL =
   'its own `include`/`mounts`. Move these globs onto the matching `regions[]` entry, or drop the ' +
   'list and let the derivation run.';
 
-export const AdapterDefinitionSchema = z
+const AdapterDefinitionSchema = z
   .object({
     editor: AdapterEditorConfigurationSchema.optional(),
     regions: RegionBindingSchema.optional(),
     regionIncludes: RegionIncludesSchema.optional(),
     documents: AdapterDocumentTableSchema.optional(),
-    observation: z.array(ObservationDeclarationSchema).optional(),
-    input: AdapterInputBindingSchema.optional(),
   })
   .strict()
   // An EMPTY table beside a list is fine and must stay fine: `defineAdapter`
@@ -914,10 +653,19 @@ export const AdapterDefinitionSchema = z
     { message: REGION_INCLUDES_WITH_LIST_REFUSAL },
   );
 
+/** The error a malformed definition throws, naming each key. */
+function invalidDefinition(issues: z.ZodError['issues']): Error {
+  return new Error(
+    `editor/volter.adapter.ts: invalid adapter definition — ${issues
+      .map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`)
+      .join('; ')}`,
+  );
+}
+
 /**
- * Validate and freeze a game's binding table.
+ * Validate and freeze a project's binding table.
  *
- * Called TWICE by design and with one schema: once here, in the game's own
+ * Called TWICE by design and with one schema: once here, in the project's own
  * module, so a malformed table fails at the author's own file with the key
  * named; and once in the host's loader, because the loaded default export is
  * untrusted input crossing a module boundary. Two call sites, one rule — not
@@ -925,41 +673,19 @@ export const AdapterDefinitionSchema = z
  */
 export function defineAdapter(input: AdapterDefinitionInput = {}): AdapterDefinition {
   const parsed = AdapterDefinitionSchema.safeParse(input);
-  if (!parsed.success) {
-    throw new Error(
-      `editor/volter.adapter.ts: invalid adapter definition — ${parsed.error.issues
-        .map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`)
-        .join('; ')}`,
-    );
-  }
+  if (!parsed.success) throw invalidDefinition(parsed.error.issues);
   return Object.freeze({
     ...(input.editor
       ? {
-          editor: Object.freeze({
-            ...input.editor,
-            ...(input.editor.playUtilities
-              ? { playUtilities: Object.freeze([...input.editor.playUtilities]) }
-              : {}),
-          }),
+          editor: Object.freeze({ ...input.editor }),
         }
       : {}),
     regions: input.regions ?? 'manifest-roots',
     regionIncludes: Object.freeze({ ...(input.regionIncludes ?? {}) }),
     documents: Object.freeze({ ...(input.documents ?? {}) }),
-    observation: Object.freeze([...(input.observation ?? [])]),
-    ...(input.input ? { input: input.input } : {}),
   });
 }
 
-/** Extra bindings a near-native game adds without restating the native ones. */
-export interface NativeAdapterOptions {
-  /** Scene-table entries this game states outright, beside what the finders find. */
-  readonly scenes?: readonly DocumentEntry[];
-  /** Per-region `include`/`mounts` parameters for the derivation — see
-   *  {@link AdapterDefinition.regionIncludes}. */
-  readonly regionIncludes?: Readonly<Record<string, AdapterRegionOverlay>>;
-}
-
 /**
  * THE NATIVE DEFAULT — regions derived mechanically from the manifest's
  * `roots[]`, and a scene table produced by the two shipped finders. This is
@@ -967,12 +693,10 @@ export interface NativeAdapterOptions {
  * is also what a project with NO `editor/volter.adapter.ts` gets: that absence is the
  * declared native default, not a silent fallback.
  */
-export function nativeAdapter(options: NativeAdapterOptions = {}): AdapterDefinition {
+export function nativeAdapter(): AdapterDefinition {
   return defineAdapter({
     regions: 'manifest-roots',
-    ...(options.regionIncludes ? { regionIncludes: options.regionIncludes } : {}),
     documents: {
-      ...(options.scenes ? { entries: options.scenes } : {}),
       find: [
         { finder: 'scenesFromEntrypointSelection', regions: EXPORTED_COMPOSITION_REGIONS },
         { finder: 'prefabsFromStories' },
@@ -982,16 +706,35 @@ export function nativeAdapter(options: NativeAdapterOptions = {}): AdapterDefini
 }
 
 /**
- * Parse an untrusted default export (the loaded `editor/volter.adapter.ts`) into a
- * definition. Rejects loudly — an unknown key, a bad finder name, a
- * `selection` paired with the rule form all fail by name.
+ * Parse an untrusted adapter-module default export through {@link defineAdapter}.
+ * Validate explicit regions against installed substrate registrations, including
+ * each substrate’s allowed dialects. Finder names and selection parameters are
+ * validated by the loader that resolves those selections.
  */
-export function parseAdapterDefinition(value: unknown): AdapterDefinition {
+export function parseAdapterDefinition(
+  value: unknown,
+  registered: readonly SubstrateRegistration[],
+): AdapterDefinition {
   if (value === null || typeof value !== 'object') {
     throw new Error(
       'editor/volter.adapter.ts must default-export defineAdapter({…}) / nativeAdapter() — ' +
         `got ${value === null ? 'null' : typeof value}`,
     );
   }
-  return defineAdapter(value as AdapterDefinitionInput);
+  const definition = defineAdapter(value as AdapterDefinitionInput);
+  if (definition.regions === 'manifest-roots') return definition;
+  const substrates = z.object({
+    regions: z.array(z.object({ substrate: z.enum(registered.map((entry) => entry.substrate)) })),
+  });
+  const parsed = substrates.safeParse({ regions: definition.regions });
+  if (!parsed.success) throw invalidDefinition(parsed.error.issues);
+  const dialectIssues = definition.regions.flatMap((region, index) => {
+    const dialects = registered.find((entry) => entry.substrate === region.substrate)?.dialects ?? [];
+    const dialect = z.enum(dialects).nullable().safeParse(region.dialect);
+    return dialect.success
+      ? []
+      : dialect.error.issues.map((issue) => ({ ...issue, path: ['regions', index, 'dialect', ...issue.path] }));
+  });
+  if (dialectIssues.length > 0) throw invalidDefinition(dialectIssues);
+  return definition;
 }