@volter/editor-game 0.5.65

package/src/host/history/json-history-resource.ts

@@ -0,0 +1,254 @@
+import { sha256Hex } from '@volter/editor-core/bytes-codec';
+import { HistoryOperationError, type HistoryService } from '@volter/editor-core/history/history-service';
+import type { ResourceDescriptor, ResourceDriver, ResourceKind } from '@volter/editor-core/history/types';
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+/**
+ * WHO OWNS A LIVE-EDIT JOURNAL, WHO SHARES IT, AND THE ONE PATH ALLOWED TO END
+ * IT. This block is the single statement of that ownership; every journal below
+ * (`three-authoring-adapter`, `pixi-live-write-target`,
+ * `pixi-structure-history`, `dom-authoring-adapter`,
+ * `react-world-authoring-adapter`) reads it rather than restating it.
+ *
+ * THE RULE: **a journal's session is its SUBJECT's, never its MOUNT's.**
+ *  - OWNER — the subject named by {@link JournalSubject.session}. A held
+ *    Edit-mode surface's subject is the WORLD, which outlives every remount
+ *    (HMR, a scene switch, a re-entered ingest), so its journal lives in the one
+ *    {@link AUTHORING_SESSION}. Play's subject is the PLAY RUN, which ends when
+ *    somebody presses ■.
+ *  - SHARERS — every mount of that subject, in succession. Two mounts of one
+ *    world are two sharers of ONE journal: `registerSession` returns the same
+ *    descriptor for the same location, so the second mount rejoins the first
+ *    mount's entries instead of minting a stack of its own.
+ *  - THE ONE TEARDOWN PATH — `HistoryService.expireSession(session)`, called by
+ *    the owner of that session and by nobody else. Today its only caller is
+ *    play's `exitPlayRootAuthoring()` (`play-mode.ts`), which ends the run it
+ *    started. A journal has NO teardown verb of its own, deliberately: a mount
+ *    holding one must not be able to end a session it does not own.
+ *
+ * WHAT THIS COST BEFORE IT WAS STATED (measured 2026-08-16, canvas held
+ * surface): every journal minted `sessionId: \`pixi-${crypto.randomUUID()}\`` —
+ * a fresh identity per MOUNT — and `dispose()` expired it. So a remount marked
+ * the surface's whole undo stack `expired`: `canUndo` went true → false and
+ * `undo()` returned false, while the entity ids the entries addressed were
+ * byte-identical across the remount. A world-scoped stack ended by a per-mount
+ * teardown is exactly the shape build-rule 4 exists to catch.
+ *
+ * SO THE TWO VERBS MEAN DIFFERENT THINGS, and conflating them was the defect:
+ * {@link JsonHistoryResource.dispose} is "THIS MOUNT detaches" (unregister the
+ * driver; entries stay restorable and the next mount re-registers), while
+ * `HistoryService.expireSession` is "the SUBJECT is gone". `dispose()` used to
+ * call `expireSession` itself, which is precisely how a sharer came to end an
+ * owner's session.
+ */
+export interface JournalSubject {
+  /** The subject's session — one path segment. {@link AUTHORING_SESSION} for
+   *  every held/authoring surface; a per-run id for play. */
+  readonly session: string;
+  /** Unique WITHIN that session: which world's which journal. Two journals in
+   *  one world (2D edits vs 2D structure) and two worlds in one session must
+   *  never collide, or the second registration finds the first's driver. */
+  readonly id: string;
+}
+
+/**
+ * The editor's authoring session — deliberately a CONSTANT, because there is
+ * exactly one of it and it lasts as long as the project is open. That is what
+ * makes a remount rejoin rather than restart.
+ */
+export const AUTHORING_SESSION = 'authoring';
+
+/** A held/authoring surface's journal: owned by the world, shared by its
+ *  mounts, never ended by one of them. */
+export function authoringJournal(id: string): JournalSubject {
+  return { session: AUTHORING_SESSION, id };
+}
+
+/** A play run's journal: owned by the run, and ended by it — which is what
+ *  keeps play-time edits out of the edit-mode undo stack after ■. */
+export function playJournal(runId: string, id: string): JournalSubject {
+  return { session: `play-${runId}`, id };
+}
+
+export interface JsonHistoryResourceOptions<T> {
+  readonly history: HistoryService;
+  readonly kind: ResourceKind;
+  readonly scope: 'project' | 'session';
+  readonly location?: string;
+  /** Required for `scope: 'session'` — see {@link JournalSubject}. */
+  readonly subject?: JournalSubject;
+  readonly displayName?: string;
+  readonly capture: () => T;
+  readonly restore: (value: T) => void | Promise<void>;
+  /**
+   * The part of the captured state that constitutes this resource's CONFLICT
+   * IDENTITY — i.e. "has something else changed this resource since the
+   * transaction was recorded?". Defaults to the whole captured value.
+   *
+   * Override it when `capture()` deliberately includes state that is NOT part
+   * of the resource's persisted content and may change on its own. The ingest
+   * overlay resource is the motivating case: its snapshot carries a mirror of
+   * every live `Object3D`'s pose (needed as the RESTORE payload), but an
+   * ingested game is a RUNNING game that animates its own objects every frame.
+   * Hashing that live simulation state as identity made every ingest
+   * transaction fail preflight with `content-conflict` a frame after it was
+   * recorded — so undo silently did nothing (issue #81). The resource's real
+   * content is the overlay it serializes to disk, which only editor edits
+   * touch.
+   */
+  readonly conflictIdentity?: (value: T) => unknown;
+}
+
+/** Concrete JSON document/session resource backed by the project HistoryService. */
+export class JsonHistoryResource<T> {
+  readonly descriptor: ResourceDescriptor;
+  private revision = 0;
+  private readonly unregister: () => void;
+  private disposed = false;
+  /**
+   * Has THIS MOUNT written to the resource yet? The conflict check below is the
+   * only reader, and the reason is the other half of making a journal outlive
+   * its mount: {@link conflictIdentity} is per-mount bookkeeping (which props
+   * the editor has touched), so a REJOINING mount starts empty and every
+   * inherited entry failed preflight with `content-conflict` — the stack
+   * survived the remount and then refused to restore, which is no better than
+   * losing it. A mount that has recorded nothing has observed no divergence and
+   * has no basis to refuse; within a mount the check is unchanged, which is
+   * what keeps issue #81's protection intact.
+   */
+  private recorded = false;
+
+  constructor(private readonly options: JsonHistoryResourceOptions<T>) {
+    if (options.scope === 'project') {
+      if (!options.location) throw new Error('A project JSON history resource needs a location.');
+      this.descriptor = options.history.registry.registerProject(
+        options.kind,
+        options.location,
+        options.displayName,
+      );
+    } else {
+      if (!options.subject) throw new Error('A session JSON history resource needs a subject.');
+      this.descriptor = options.history.registry.registerSession(
+        options.kind,
+        options.subject.session,
+        options.subject.id,
+        options.displayName,
+      );
+    }
+
+    const driver: ResourceDriver = {
+      descriptor: this.descriptor,
+      capture: async () => {
+        const bytes = this.encode(options.capture());
+        return {
+          revision: this.revision,
+          contentType: 'application/json',
+          bytes,
+          sha256: await sha256Hex(bytes),
+        };
+      },
+      preflight: async (expected) => {
+        const bytes = this.encode(options.capture());
+        const actualSha256 = await sha256Hex(bytes);
+        // A mount that has not written here cannot have seen anything diverge.
+        if (!this.recorded) return { ok: true };
+        // Fast path (and the behavior for every resource that does NOT narrow
+        // its identity): the full captured bytes still hash to what the
+        // transaction expects, so nothing has diverged.
+        if (actualSha256 === expected.sha256) return { ok: true };
+        // Otherwise the bytes differ — but that only counts as a CONFLICT if the
+        // part that identifies the resource differs. Compare the narrowed
+        // identity against the expected snapshot's own identity, decoded from
+        // the stored blob. (See `conflictIdentity` — an ingested game mutates
+        // the live-object mirror in its snapshot every frame on its own.)
+        if (options.conflictIdentity) {
+          const expectedValue = JSON.parse(
+            decoder.decode(options.history.snapshots.read(expected).bytes),
+          ) as T;
+          const expectedIdentity = JSON.stringify(options.conflictIdentity(expectedValue));
+          const actualIdentity = JSON.stringify(options.conflictIdentity(options.capture()));
+          if (expectedIdentity === actualIdentity) return { ok: true };
+        }
+        return {
+          ok: false,
+          reason: 'content-conflict',
+          actualRevision: this.revision,
+          actualSha256,
+        };
+      },
+      restore: async (snapshot) => {
+        const bytes = options.history.snapshots.read(snapshot).bytes;
+        await options.restore(JSON.parse(decoder.decode(bytes)) as T);
+        this.revision++;
+      },
+      estimateBytes: (snapshot) => snapshot.byteLength,
+    };
+    this.unregister = options.history.registerDriver(driver);
+  }
+
+  record(label: string, before: T, after: T): Promise<boolean> {
+    if (this.disposed) return Promise.reject(new Error('JSON history resource is disposed.'));
+    this.options.history.assertCanRecordAppliedChange();
+    this.revision++;
+    this.recorded = true;
+    return this.options.history
+      .recordAppliedTransaction(
+        {
+          label,
+          resources: [this.descriptor.key],
+          scope: this.descriptor.scope,
+          ...(this.descriptor.sessionId ? { sessionId: this.descriptor.sessionId } : {}),
+        },
+        [
+          {
+            resource: this.descriptor.key,
+            beforeBytes: this.encode(before),
+            afterBytes: this.encode(after),
+            contentType: 'application/json',
+          },
+        ],
+      )
+      .catch(async (error: unknown) => {
+        try {
+          await this.options.restore(structuredClone(before));
+          this.revision++;
+        } catch (compensationError) {
+          throw this.options.history.blockForCompensationFailure(label, [this.descriptor.key], {
+            operationError: error,
+            compensationError,
+          });
+        }
+        if (!(error instanceof HistoryOperationError)) {
+          this.options.history.reportAppliedChangeFailure(label, [this.descriptor.key], error);
+        }
+        throw error;
+      });
+  }
+
+  /** Must be called immediately before a live or overlay mutation begins. */
+  assertCanMutate(): void {
+    if (this.disposed) throw new Error('JSON history resource is disposed.');
+    this.options.history.assertCanRecordAppliedChange();
+  }
+
+  /**
+   * THIS MOUNT DETACHES — see the ownership block at the top of this file.
+   *
+   * Unregisters the driver and nothing else: the entries stay restorable, and
+   * the next mount of the same subject re-registers over the same descriptor
+   * and inherits them. This deliberately does NOT expire; a mount ending is not
+   * its subject ending, and treating it as one is what emptied a held surface's
+   * undo stack on every remount.
+   */
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.unregister();
+  }
+
+  private encode(value: T): Uint8Array {
+    return encoder.encode(JSON.stringify(value, null, 2));
+  }
+}

package/src/host/ingest/registry.ts

@@ -0,0 +1,261 @@
+/**
+ * THE in-tree ingest registry — one home, one glob, one manifest convention
+ * ONE INGEST HOME.
+ *
+ * Until this wave there were THREE parallel discovery mechanisms, each named
+ * after a rendering library rather than after what it did: `discovery.ts`
+ * globbed `games/`, `discovery2d.ts` globbed `games-2d/`, `discovery-react.ts`
+ * globbed `games-react/`. Each re-implemented the same four steps (glob the
+ * manifests, key them by folder id, parse+validate the single root, cache and
+ * look up by id) and each hard-coded the ADAPTER IDENTITY it would accept —
+ * `ingest-pixi`, `ingest-react` — which is a library name in a seam that is
+ * supposed to be about surfaces. A Phaser or Babylon game had no home.
+ *
+ * There is now ONE glob over ONE directory, and the discriminator is the
+ * manifest's own `surface` (`three | canvas | dom`) — the doctrine vocabulary,
+ * "what the host HANDS the root", never which library draws. A vendored Phaser
+ * game is a `canvas` root and needs no code here; the library it uses is
+ * metadata (`libraryOf`, read off the adapter identity for display/telemetry
+ * only, never branched on for mounting).
+ *
+ * What is deliberately NOT unified: the per-surface MOUNT paths
+ * (`surface-three.ts` / `surface-canvas.ts` / `surface-dom.ts`). Mounting a
+ * three root, a canvas root and a dom root are genuinely different jobs — a
+ * three fixture becomes an `IngestGame`, a canvas fixture an `IngestGame2D`, a
+ * dom fixture a `projectRoot` for
+ * the `/@fs/` resolver. Those three builders remain, each consuming THIS
+ * module's already-parsed entries. Discovery is one; mounting is three.
+ *
+ * Also not unified, and for a reason that is not library-shaped:
+ * `discovery-public-ingest.ts` resolves games vendored under
+ * `public/ingest/<id>/`. `public/` is outside Vite's module graph by
+ * construction (served verbatim in dev, copied at build), so those manifests
+ * are `fetch`ed by id rather than globbed. That split is SERVING-driven, not
+ * library-driven, and both halves are id-keyed.
+ *
+ * ## Why `import.meta.glob`
+ *
+ * These fixtures live inside this package's own source tree, which Vite (and
+ * Vitest, sharing Vite's transform pipeline) knows statically in dev, build and
+ * test alike — no runtime fetch, no `/@fs/`, no dev-server middleware.
+ * `resolveIngestDescriptor` (ingest/resolve-three.ts) is the route for an EXTERNAL
+ * project folder; it is deliberately not used here.
+ */
+
+import { declaredRoots } from '@volter/editor-project/adapter/manifest-interpreter';
+import type { ResolvedAdapter, ResolvedAdapterRoot } from '@volter/editor-project/manifest/load';
+import { loadGameManifest, type ResolvedGameManifest } from '@volter/editor-project/manifest/load';
+
+/** The one manifest glob. Every in-tree ingest fixture, whatever its surface. */
+const manifestModules = import.meta.glob('./games/*/vgai.project.json', {
+  eager: true,
+  import: 'default',
+}) as Record<string, unknown>;
+
+/**
+ * The one entry-module glob, shared by every surface: the host imports a
+ * fixture's own entry module (and its `contractShim`, when it declares one) in
+ * the editor's realm. `.d.ts` is excluded: an ambient declaration file
+ * is not a module and must never become a dynamic-import chunk.
+ *
+ * `vgai.adapter.ts` is excluded too, and for a different reason: it is not a
+ * GAME module at all. It is host-realm DECLARATION (see {@link adapterModules}),
+ * read without booting anything, and a manifest that named it as an `entry` or
+ * a `contractShim` would be nonsense — so it is not in the set those fields
+ * resolve against.
+ */
+export const entryModules = import.meta.glob([
+  './games/*/*.js',
+  './games/*/*.ts',
+  '!./games/*/*.d.ts',
+  '!./games/*/vgai.adapter.ts',
+]) as Record<string, () => Promise<unknown>>;
+
+/**
+ * THE ADAPTER GLOB — one `vgai.adapter.ts` per ingest game, keyed by game id.
+ *
+ * ARCHITECTURE-CORE §The editor protocol: "Placement follows REALM: game-realm
+ * code (a shim that runs inside the game) lives with the game's bundle;
+ * host-realm declaration (`vgai.adapter.ts`) lives where the host can import it
+ * as a real module — a repo-vendored bundle's adapter file lives in the host's
+ * in-tree registry, never inside the verbatim-served bundle." This directory IS
+ * that registry, so it holds BOTH populations:
+ *
+ *   - an in-tree fixture's adapter sits beside its own manifest and entry;
+ *   - a public-bundle game's adapter sits in a folder holding ONLY that file —
+ *     its bytes are served verbatim from `public/ingest/<id>/` and hashed by
+ *     `vendor/games/verify-unaltered.mjs`, so nothing host-owned may go there.
+ *
+ * A folder with no `vgai.project.json` is invisible to {@link manifestModules}
+ * and therefore to {@link discoverIngestEntries} — the second population adds no
+ * fixtures, only declarations.
+ *
+ * LAZY, not eager, on purpose: `defineAdapter` validates at module-evaluation
+ * time and THROWS on a malformed table. Eager evaluation would make one bad
+ * adapter a boot failure for the whole editor; loading only the open game's
+ * adapter keeps that failure where the loader can name it and keep going
+ * (`project-adapter.ts`: "an editor that dies on a project's config file cannot
+ * be used to fix that file"). Vite resolves the glob statically in dev and in
+ * a production build alike, so no generated dispatch table is needed.
+ */
+const adapterModules = import.meta.glob('./games/*/vgai.adapter.ts') as Record<
+  string,
+  () => Promise<unknown>
+>;
+
+/** The adapter module's filename — the contract's ONE spelling, host side. */
+const ADAPTER_FILENAME = 'vgai.adapter.ts';
+
+/** This directory's repo path, so a published `modulePath` names a real file. */
+const REGISTRY_REPO_DIR = 'packages/editor/src/ingest/games';
+
+const ADAPTER_KEY_RE = /^\.\/games\/([^/]+)\/vgai\.adapter\.ts$/;
+
+/**
+ * THE LOOKUP KEY IS THE GAME ID; THE STORAGE KEY IS THE FOLDER NAME. What makes
+ * that the same question is an INVARIANT, not a coincidence.
+ *
+ * `project-adapter.ts` resolves an ingest project's adapter by the id the
+ * project's own manifest declares (`ingestGameIdOf` -> the single `{ ingest }`
+ * root's `id`), and the two functions below map that id straight onto
+ * `./games/<id>/`. So a folder whose game declares a DIFFERENT id binds that
+ * other game's table — silently, because a lookup by key cannot tell a mistaken
+ * key from a correct one.
+ *
+ * The invariant is therefore `folder id === the id that game's manifest
+ * declares`, for BOTH populations this registry serves — in-tree fixtures
+ * (`./games/<id>/vgai.project.json`) and public bundles
+ * (`public/ingest/<id>/vgai.project.json`, whose registry folder holds only the
+ * adapter file). It is guarded ONCE, statically, in
+ * `packages/editor/test/ingest-adapter-modules.test.ts`, which reads both id
+ * spaces off disk — the only realm that can, since `public/` is outside the
+ * module graph and reachable here by `fetch` alone.
+ */
+
+/** Repo-relative path of a game's adapter module, or `null` when it has none. */
+export function ingestAdapterModulePath(gameId: string): string | null {
+  if (!adapterModules[gameFileKey(gameId, ADAPTER_FILENAME)]) return null;
+  return `${REGISTRY_REPO_DIR}/${gameId}/${ADAPTER_FILENAME}`;
+}
+
+/**
+ * Import a game's adapter module. `null` = this game declares none, which is
+ * the ordinary "absence IS the declared native default" case the loader already
+ * knows how to answer; a module that exists and throws is left to throw, so the
+ * loader can name the failure rather than swallow it.
+ */
+export async function importIngestAdapterModule(gameId: string): Promise<unknown | null> {
+  const load = adapterModules[gameFileKey(gameId, ADAPTER_FILENAME)];
+  return load ? await load() : null;
+}
+
+/** Every game id that ships an adapter module, sorted — what conformance scans. */
+export function ingestAdapterGameIds(): string[] {
+  return Object.keys(adapterModules)
+    .map((key) => {
+      const match = ADAPTER_KEY_RE.exec(key);
+      if (!match?.[1]) throw new Error(`ingest registry: unexpected adapter glob key "${key}"`);
+      return match[1];
+    })
+    .sort((a, b) => a.localeCompare(b));
+}
+
+/** Served URLs for a manifest's `assets` map (game-relative path -> URL). */
+export const assetUrls = import.meta.glob('./games/*/assets/**', {
+  eager: true,
+  query: '?url',
+  import: 'default',
+}) as Record<string, string>;
+
+const MANIFEST_KEY_RE = /^\.\/games\/([^/]+)\/vgai\.project\.json$/;
+
+/** Folder-relative glob key for a file inside a discovered game's folder. */
+export function gameFileKey(folderId: string, relPath: string): string {
+  return `./games/${folderId}/${relPath}`;
+}
+
+/** The `surface` vocabulary, restated by value (never imported from a schema
+ *  module, matching how the manifest schema itself mirrors it). */
+export type IngestSurface = 'three' | 'canvas' | 'dom';
+
+/** A manifest root already narrowed to the `ingest` adapter — the registry does
+ *  that narrowing ONCE, so no per-surface builder repeats the check. */
+export type IngestRoot = Omit<ResolvedAdapterRoot, 'adapter'> & {
+  readonly adapter: Extract<ResolvedAdapter, { type: 'ingest' }>;
+};
+
+/** One discovered in-tree ingest fixture: its folder, its parsed manifest, and
+ *  the single ingest root that manifest declares. */
+export interface IngestEntry {
+  readonly folderId: string;
+  readonly manifest: ResolvedGameManifest;
+  readonly root: IngestRoot;
+  readonly surface: IngestSurface;
+}
+
+function folderIdFromManifestKey(key: string): string {
+  const match = MANIFEST_KEY_RE.exec(key);
+  if (!match?.[1]) {
+    throw new Error(`ingest registry: unexpected manifest glob key "${key}"`);
+  }
+  return match[1];
+}
+
+function buildEntry(folderId: string, raw: unknown): IngestEntry {
+  const manifest = loadGameManifest(raw, { configurationKinds: 'defer' });
+  const roots = declaredRoots(manifest);
+  if (roots.length !== 1) {
+    throw new Error(
+      `ingest registry: "${folderId}/vgai.project.json" must declare exactly one root ` +
+        `(found ${roots.length}).`,
+    );
+  }
+  const root = roots[0]!;
+  if (root.adapter.type !== 'ingest') {
+    throw new Error(
+      `ingest registry: "${folderId}/vgai.project.json"'s root must be an { ingest } root ` +
+        `(found adapter identity "${root.adapter.identity}").`,
+    );
+  }
+  // `root.adapter.type === 'ingest'` is proven above; TS cannot narrow the
+  // whole root through a nested discriminant, so restate it once, here, rather
+  // than in each per-surface builder.
+  const ingestRoot = root as IngestRoot;
+  return { folderId, manifest, root: ingestRoot, surface: ingestRoot.adapter.surface };
+}
+
+let _cache: IngestEntry[] | null = null;
+
+/** Every in-tree ingest fixture, whatever its surface, sorted by folder id. */
+export function discoverIngestEntries(): IngestEntry[] {
+  if (!_cache) {
+    _cache = Object.entries(manifestModules)
+      .map(([key, raw]) => buildEntry(folderIdFromManifestKey(key), raw))
+      .sort((a, b) => a.folderId.localeCompare(b.folderId));
+  }
+  return _cache;
+}
+
+/** Every in-tree fixture on one surface — what each per-surface builder reads. */
+export function ingestEntriesOnSurface(surface: IngestSurface): IngestEntry[] {
+  return discoverIngestEntries().filter((e) => e.surface === surface);
+}
+
+/**
+ * The rendering library behind an ingest root, as METADATA — for a report line
+ * or a gallery badge, never as a mount discriminator. Derived from the adapter
+ * identity the manifest schema resolves, which is why a surface with no
+ * library-specific identity honestly answers `undefined` rather than guessing.
+ */
+export function libraryOf(entry: IngestEntry): string | undefined {
+  switch (entry.root.adapter.identity) {
+    case 'ingest-three':
+      return 'three.js';
+    case 'ingest-pixi':
+      return 'PixiJS';
+    case 'ingest-react':
+      return 'React';
+    default:
+      return undefined;
+  }
+}

package/src/host/instance-extract-actions.ts

@@ -0,0 +1,120 @@
+/**
+ * "Extract Component…" — P1 structural extraction.
+ *
+ * The applicability rule and every sentence this action can say, kept pure and
+ * adapter-free for the same reason `instance-fork-actions.ts` (H7) is — the
+ * wiring that knows about adapters lives in
+ * `authoring/instance-extract-menu.ts`, and the SOURCE REWRITE lives
+ * server-side in `ui-source/plan-extract-component.ts`.
+ *
+ * FORK AND EXTRACT ARE COMPLEMENTS, split by the row's role. A COMPONENT
+ * instance row already has a definition module — customizing it is H7's fork
+ * (copy the module, retarget the tag). A NATIVE subtree row (`<group>`,
+ * `<mesh>` — assembled in place, no module of its own) is what THIS action
+ * serves: the subtree becomes a component under `src/prefabs/` with a portable
+ * CSF story, and the row becomes an ordinary instance. The two applicability
+ * predicates are disjoint on the same `role` field, so a hierarchy row offers
+ * at most one of the pair.
+ *
+ * The trailing ellipsis follows the same platform convention fork records: an
+ * action that writes NEW FILES — this one writes two.
+ */
+
+import type { InstanceSourceLocator } from '@volter/editor-core/instance-source-actions';
+
+export const EXTRACT_COMPONENT_LABEL = 'Extract Component…';
+
+/**
+ * The adapter surface this action reads. `canExtractComponent` is the
+ * adapter's own honest answer to "could I write this?" (a write backend with
+ * the extract seam exists and this id has a source element);
+ * `extractComponent` performs it and returns the sentence to show.
+ */
+export interface InstanceExtractSource extends InstanceSourceLocator {
+  readonly canExtractComponent?: ((id: string) => boolean) | undefined;
+  readonly extractComponent?: ((id: string, name?: string) => Promise<string>) | undefined;
+}
+
+/**
+ * Applicability — all about whether the edit is REACHABLE, never about whether
+ * it would succeed (only the plan can say, and its refusals are click-time
+ * hints):
+ *
+ * 1. the row is a NATIVE source element, not a component instance (those fork)
+ *    and not the document row;
+ * 2. the row resolves a source location — there is a subtree to extract;
+ * 3. the adapter can actually write through the extract seam.
+ *
+ * An inapplicable row gets NO item rather than a disabled one — the registry
+ * idiom fork records.
+ */
+export function canExtractNode(
+  node: { readonly role?: string | undefined } | null | undefined,
+  source: InstanceExtractSource | null | undefined,
+  id: string,
+): boolean {
+  // ALLOW-list, not a block-list: only the two native-row roles are subtrees
+  // assembled in place. Every other role either has a module already
+  // ('component' — fork's subject), is not a source element at all
+  // ('folder'/'root'/'document'/'story'), or is still mounting ('boundary').
+  if (node?.role !== 'entity' && node?.role !== 'element') return false;
+  if (!source || typeof source.extractComponent !== 'function') return false;
+  if (typeof source.sourceLocation !== 'function' || !source.sourceLocation(id)) return false;
+  return source.canExtractComponent?.(id) !== false;
+}
+
+// ------------------------------------------------------------------ sentences
+
+/** The success hint NAMES BOTH NEW FILES — the author has to know what was
+ *  created, because undo (which owns the callsite edit) will not remove them. */
+export function extractedHint(
+  tag: string,
+  newName: string,
+  componentPath: string,
+  storyPath: string,
+): string {
+  return (
+    `Extracted <${tag}> → <${newName}> (${componentPath}, story ${storyPath}). ` +
+    'Undo restores the callsite; the new files stay.'
+  );
+}
+
+/** The row lost its source element between menu and click. */
+export function extractUnavailableHint(tag: string): string {
+  return `<${tag}> is no longer in the source index — there is nothing to extract.`;
+}
+
+/** No dev-server write backend in this session (a hosted or read-only tier). */
+export function extractNoBackendHint(tag: string): string {
+  return `This session cannot write project source, so <${tag}> cannot be extracted.`;
+}
+
+/**
+ * The new files were written and the CALLSITE edit then failed. Reported in
+ * full: the module and story are inert (nothing imports them), so the failure
+ * mode is clutter, not breakage — and the author is told exactly that.
+ */
+export function extractPartialHint(
+  tag: string,
+  newName: string,
+  componentPath: string,
+  detail: string,
+): string {
+  return (
+    `Wrote ${componentPath} (and its story) for <${newName}>, but the <${tag}> callsite was ` +
+    `not replaced (${detail}). Nothing imports the new files yet, so they are inert — ` +
+    'delete them or try again.'
+  );
+}
+
+/** Any other refusal: the plan's own named reason, or a transport failure. */
+export function extractRefusedHint(reason: string): string {
+  return `Cannot extract: ${reason}`;
+}
+
+/** Did a hint sentence report a LANDED extraction? Owned by this module —
+ *  the one place the sentences are minted — so the command door's ok/error
+ *  split cannot drift from the wording it matches. */
+export function isExtractedHint(hint: string): boolean {
+  return hint.startsWith('Extracted ');
+}