@volter/editor-game 0.5.65

package/src/host/authoring/source-persistence-backend.ts

@@ -0,0 +1,373 @@
+/**
+ * The PERSISTENCE BACKEND seam for a LIVE authoring adapter, on ANY surface:
+ * where a closed gesture's value goes, and what a surface says about that
+ * before the gesture happens.
+ *
+ * IT IS KEYED ON NEITHER SURFACE NOR PROVENANCE — a per-substrate copy is
+ * the fork ARCHITECTURE-CORE §Rules names, wearing a filename: an ingested Pixi
+ * game needs the SAME ownership gate, the SAME per-edit refusals and the SAME
+ * one-transaction-carries-both-halves rule as an ingested three game, and a seam
+ * named after one substrate is how a second copy gets written instead of reused.
+ * `ThreeAuthoringAdapter` and the canvas write target
+ * (`pixi-live-write-target.ts`) are both its consumers; nothing in this file
+ * mentions `Object3D` or `Container`, because the currency is an entity id, a
+ * property path, an anchor and two values.
+ *
+ * The adapter owns the gesture and the session journal; it never decides the
+ * destination. It hands a backend the creation-site anchor for the property
+ * being edited plus the before/after values, and journals the edit live-only
+ * whenever the backend declines — which is the DEFAULT, not the exception.
+ *
+ * ABSENCE IS A BACKEND. An adapter constructed with no backend at all persists
+ * nothing and journals nothing: its edits live on the running object for the
+ * session and the host injects `createEphemeralPersistence` over them. That is
+ * what a play-mode adoption wants — pushing an undo entry there would write
+ * play state into the edit-mode history.
+ *
+ * {@link createCreationSitePersistence} is the other shipped backend, and it
+ * covers two of the three destinations the ownership doctrine names:
+ *  - the CREATION-SITE LITERAL WRITER, when this tier can reach a dev server to
+ *    write the world's own source through (`/__ingest-source/*`);
+ *  - an HONEST LIVE-ONLY-WITH-REASON, when it cannot — inventing a fallback
+ *    that writes somewhere else is exactly the sidecar the doctrine forbids.
+ *    Every refusal still names its gate.
+ *
+ * The third shipped backend is `oid-source-persistence.ts`, for a world whose
+ * own source the serve-time OID transform DID reach — a vendored R3F game is
+ * the case that forces it to exist. There, no `new` expression in the game's
+ * source constructs anything (fiber does, inside `node_modules`), so
+ * creation-site anchoring is structurally empty and its writer can never fire;
+ * the JSX callsite the OID stamp names is the object's real source address.
+ */
+
+import type { NodeCreationSite, WriteAnchorKind } from '@volter/editor-project/adapter';
+import type {
+  ChannelValue,
+  CreationSiteLiteralReport,
+  CreationSiteSurface,
+  CreationSiteWriteScope,
+} from '@volter/editor-core/creation-site-edit';
+import { editorConsole } from '@volter/editor-core/editor-console';
+import { editorIsAuthoring } from '@volter/editor-core/editor-session-mode';
+import type { HistoryService } from '@volter/editor-core/history/history-service';
+import { ingestSourceWritesRecordedIfPrimed } from '@volter/editor-core/ui-source/tier-source-write-backend';
+import type { IngestInspectRequest } from './ingest-source-persistence';
+import {
+  IngestSourcePersistence,
+  ingestOwnershipNow,
+  reportIngestSourceRefusal,
+} from './ingest-source-persistence';
+import { LIVE_ONLY_DESTINATION } from '@volter/editor-core/authoring/write-pipe';
+
+/**
+ * The adapter's own channel read/write, handed to a backend so the live half of
+ * a persisted edit can be restored by undo through the SAME writers an ordinary
+ * edit uses.
+ */
+export interface LiveChannelAccess {
+  /** The value in force for one property, or `undefined` when the node is gone. */
+  read(entityId: string, property: string): ChannelValue | undefined;
+  /** Put a value back on the live object (undo/redo). */
+  apply(entityId: string, property: string, value: ChannelValue): void;
+}
+
+/**
+ * WHAT is being edited — everything a backend needs to decide, before any value
+ * exists. One object rather than a positional list because the two shipped
+ * backends read DIFFERENT members of it: the creation-site backend answers from
+ * `anchor`/`instances`, the OID backend from `sourceOid`, and a positional
+ * signature would have grown a fourth parameter nobody reading the call could
+ * name.
+ */
+export interface SourceWriteSubject {
+  readonly entityId: string;
+  /** An editor property path (a key of the surface's channel table). */
+  readonly property: string;
+  /**
+   * Which surface's vocabulary {@link SourceWriteSubject.property} is in.
+   * Absent ⇒ `three`. It travels with the subject rather than being fixed at
+   * backend construction because it is a fact about the PROPERTY NAME, and the
+   * server — which owns the channel tables — is the only thing that resolves it.
+   */
+  readonly surface?: CreationSiteSurface | undefined;
+  /** Where the value being edited LIVES: the creation site of the object that
+   *  owns the property (for a material colour, the material — not the mesh), or
+   *  the record in the game's own data file that addresses this object. */
+  readonly anchor: NodeCreationSite;
+  /**
+   * WHICH LANE this subject's write would travel, in the pinned vocabulary
+   * (`WriteAnchorKind`) — planned by whoever built the subject, since that is
+   * the code that chose the branch, and carried here so a caller does not have
+   * to re-derive it from the anchor's shape (which cannot distinguish a JSX
+   * prop from a construction literal, nor either from a body-placed spawn).
+   */
+  readonly anchorKind: WriteAnchorKind;
+  /** How many objects that anchor has constructed. A SOURCE-anchor fact only —
+   *  a data record addresses exactly one object by construction, so the count
+   *  is 1 there and nothing reads it. */
+  readonly instances: number;
+  /** Ordinary gestures omit this and address one live object. The explicit
+   * component-default gesture carries `creation-site`, authorizing a rewrite
+   * whose declared effect is all `instances` objects. */
+  readonly writeScope?: CreationSiteWriteScope | undefined;
+  /**
+   * The serve-time OID stamp of the object that OWNS the property (the same
+   * owner hop `anchor` follows), when the served source carried one. Absent for
+   * every unstamped world, which is what makes the two backends' domains
+   * disjoint rather than overlapping.
+   */
+  readonly sourceOid?: string | undefined;
+}
+
+/** One property edit, fully planned, offered to the backend. */
+export interface SourceWriteRequest extends SourceWriteSubject {
+  readonly baseline: ChannelValue;
+  readonly next: ChannelValue;
+  /** History label for the transaction ("Transform Sun"). */
+  readonly label: string;
+}
+
+/**
+ * One REMOVAL, fully planned, offered to the backend — the same subject a write
+ * carries, minus the values. The missing `baseline`/`next` IS the difference:
+ * absence is not a value, and a door that took one would be a value write
+ * wearing another name.
+ */
+export interface SourceRemoveRequest extends SourceWriteSubject {
+  /** History label for the transaction ("Remove Sun position"). */
+  readonly label: string;
+}
+
+/**
+ * THE REMOVAL DOOR — drop the authored value at a subject's address entirely,
+ * rather than writing a value into it.
+ *
+ * WHY A BACKEND NEEDS ONE AT ALL: every dialect writer here appends
+ * (`addIfMissing`), so a gesture on a callsite that authored no `position`
+ * ADDS one, and writing the old numbers back leaves that attribute standing —
+ * the file ends one attribute heavier than it started and no byte-level
+ * edit/revert round trip can close. Only removal expresses that absence.
+ *
+ * ABSENT ⇒ this backend cannot express byte-absence at all, and the adapter
+ * above it declares no `TransformProvider.remove`, so the protocol's removal
+ * door refuses BY NAME (`REMOVAL_UNAVAILABLE`) instead of a value write
+ * pretending to be a revert. The two members are ONE optional group rather
+ * than two optional methods precisely so "there is a door" and "here is who
+ * may walk through it" cannot come apart.
+ */
+export interface SourceRemovalDoor {
+  /**
+   * Is there a door for THIS subject's property, right now?
+   *
+   * SYNCHRONOUS, because its caller is `TransformProvider.editability`, which
+   * has to answer before the gesture. So it may only read what the backend
+   * already holds — the same rule {@link SourcePersistenceBackend.gate} states
+   * for the write side, and for the same reason.
+   */
+  available(subject: SourceWriteSubject): boolean;
+  /**
+   * Attempt the removal. `true` ⇒ the authored value is gone and this
+   * backend's own transaction carries the undo. `false` ⇒ NOTHING was dropped
+   * — the callsite carried no such attribute, or the writer refused it — and
+   * the backend has already reported why, so the caller acks the live-only
+   * floor rather than a revert nobody performed.
+   */
+  perform(request: SourceRemoveRequest): Promise<boolean>;
+}
+
+export type SourceWriteVerdict = { ok: true } | { ok: false; reason: string };
+
+export interface SourcePersistenceBackend {
+  /** Called once by the adapter, before any gesture. */
+  attach(live: LiveChannelAccess): void;
+  /**
+   * The source address this backend would write `sourceOid` at, when it knows
+   * one — the adapter prefers it over the creation-site registry's answer, so a
+   * stamped object's "created at" line names its real JSX callsite instead of
+   * the registry's honest-but-useless "constructed outside project source".
+   *
+   * ABSENT on a backend with no OID index (the creation-site one), and `null`
+   * for an oid this backend's index has not resolved. Never a guess.
+   */
+  anchor?(sourceOid: string): NodeCreationSite | null;
+  /**
+   * Is the value at `sourceOid`'s anchor read by a PHYSICS BODY BINDING — i.e.
+   * would a write here land at a spawn a simulation re-poses from, rather than
+   * at a prop the element itself keeps?
+   *
+   * Only a backend holding the game's own source index can answer, which is why
+   * it lives here rather than on the adapter: the fact is `physicsBinding` /
+   * `r3fAuthoring.bodyForwarded` on the served `OidEntry`
+   * (`ui-source/r3f-physics-binding.ts`). ABSENT ⇒ this backend indexes no
+   * source and every anchor it plans is classified by its own branch alone.
+   */
+  physicsPlaced?(sourceOid: string, property: string): boolean;
+  /** The sentence `transforms.editability` cites for this node + property. */
+  describe(subject: SourceWriteSubject): string;
+  /** Synchronous "is a write even on the table?", with the reason when not.
+   *  Must not await: the live-only path stays as synchronous as it was before
+   *  any of this existed, so an `endEdit(); undo()` sequence still works. */
+  gate(subject: SourceWriteSubject): SourceWriteVerdict;
+  /**
+   * Could this backend write at all right now — a reachable writer, and a
+   * session that is AUTHORING rather than playing? Decides only whether a
+   * CHEAP-gate refusal is worth telling the user about: "that property has no
+   * source anchor" is honesty during an authoring gesture and noise on every
+   * frame of a game somebody is playing.
+   */
+  armed(): boolean;
+  /** Report a refusal where the user can see it. */
+  report(label: string, reason: string): void;
+  /**
+   * READ what the construction statement says these properties are — the
+   * component-instance diff's other half ("the site's literal is the default,
+   * the live object is the instance").
+   *
+   * ABSENT ⇒ this backend has no readable source behind its subjects, and the
+   * adapter reports no component-instance description at all rather than one
+   * whose defaults it made up. Present ⇒ every property gets an answer or is
+   * simply missing from the map, which is the honest "the site names none".
+   */
+  readSiteLiterals?(
+    request: IngestInspectRequest,
+  ): Promise<Record<string, CreationSiteLiteralReport>>;
+  /** Attempt the write. `true` ⇒ persisted, and the adapter skips its journal
+   *  because the backend's own transaction already carries both halves. */
+  write(request: SourceWriteRequest): Promise<boolean>;
+  /**
+   * The other half of `write` for a backend that can express ABSENCE — see
+   * {@link SourceRemovalDoor}. Absent on a backend that cannot, which is how a
+   * lane honestly reports that byte-absence is unreachable through it rather
+   * than reverting with a value write.
+   */
+  readonly removal?: SourceRemovalDoor;
+  /** What `AuthoringAdapter.persistence.destination` reports. */
+  destination(): string;
+  dispose(): void;
+}
+
+export interface CreationSitePersistenceOptions {
+  readonly history: HistoryService | null;
+  /**
+   * Injectable so a unit test can drive the write path without a dev server.
+   * Absent in production: the backend builds its own when the tier can reach
+   * one, and stays at the honest live-only floor when it cannot.
+   */
+  readonly writer?: IngestSourcePersistence | undefined;
+}
+
+export function createCreationSitePersistence(
+  options: CreationSitePersistenceOptions,
+): SourcePersistenceBackend {
+  let writer: IngestSourcePersistence | null = null;
+  return {
+    attach(live) {
+      // Whether an ingest edit is RECORDED is what this session's host serves
+      // (`/__ingest-source/*`, from `creationSiteWritePlugin`), never how the
+      // editor shell was built — the packaged editor runs a production bundle
+      // and serves that route, so `import.meta.env.DEV` refused the write on the
+      // one tier a registry install has. See
+      // `../ui-source/tier-source-write-backend.ts`.
+      writer =
+        options.writer ??
+        (ingestSourceWritesRecordedIfPrimed('An ingest root’s source persistence')
+          ? new IngestSourcePersistence({ history: options.history, live })
+          : null);
+    },
+    describe({ anchor, instances, property, writeScope }) {
+      if (writer) return writer.describe(anchor, instances, property, writeScope);
+      if (!anchor.anchored) return `Live-only edit — ${anchor.reason}.`;
+      return anchor.kind === 'data'
+        ? `Live-only edit — this object is ${anchor.display}.`
+        : `Live-only edit — this object is created at ${anchor.display}.`;
+    },
+    gate({ anchor, instances, property, writeScope }) {
+      if (!writer) return { ok: false, reason: 'this editor tier cannot write project source' };
+      return writer.gate(anchor, instances, property, writeScope);
+    },
+    armed: () => writer !== null && editorIsAuthoring(),
+    readSiteLiterals: (request) => (writer ? writer.inspect(request) : Promise.resolve({})),
+    report: (label, reason) => reportIngestSourceRefusal(label, reason),
+    async write(request) {
+      if (!writer) return false;
+      try {
+        const outcome = await writer.persist(request);
+        if (outcome.persisted) {
+          editorConsole.log(
+            `[ingest] ${request.label} written to the game's own source — ${outcome.detail}`,
+          );
+          return true;
+        }
+        reportIngestSourceRefusal(request.label, outcome.reason);
+        return false;
+      } catch (error) {
+        reportIngestSourceRefusal(
+          request.label,
+          `the write failed: ${error instanceof Error ? error.message : String(error)}`,
+        );
+        return false;
+      }
+    },
+    /**
+     * THE REMOVAL DOOR on the creation-site lane — the byte-absence half the
+     * insertion arm makes necessary: an authored transform can ADD a
+     * `receiver.member.axis = value;` statement for an axis the source never
+     * named, and no value write can revert an added property. The plan is
+     * `planCreationSiteRemoval` (server-side, same `prepare`/`apply` route and
+     * checksum guard as a value write, so a vendored game's lock rides along
+     * in the same gesture): the ONE deletable shape is the whole own-line
+     * assignment statement insertion writes; everything else — constructor
+     * literals, `.set(…)` arguments, alias writes, computed expressions —
+     * refuses in the planner's own words.
+     *
+     * `available` answers for the DOOR (a writer exists and the gate is open
+     * for this subject), the same honesty split the OID lane records: whether
+     * the site currently AUTHORS such a statement is the file's fact, and
+     * `perform` — which returns the server plan's own verdict — answers it.
+     */
+    removal: {
+      available(subject) {
+        if (!writer) return false;
+        return writer.gate(subject.anchor, subject.instances, subject.property, subject.writeScope)
+          .ok;
+      },
+      async perform(request) {
+        if (!writer) return false;
+        try {
+          const outcome = await writer.remove({
+            property: request.property,
+            surface: request.surface,
+            anchor: request.anchor,
+            instances: request.instances,
+            writeScope: request.writeScope,
+            label: request.label,
+          });
+          if (outcome.persisted) {
+            editorConsole.log(
+              `[ingest] ${request.label} — dropped from the game's own source (${outcome.detail})`,
+            );
+            return true;
+          }
+          reportIngestSourceRefusal(request.label, outcome.reason);
+          return false;
+        } catch (error) {
+          reportIngestSourceRefusal(
+            request.label,
+            `the removal failed: ${error instanceof Error ? error.message : String(error)}`,
+          );
+          return false;
+        }
+      },
+    },
+    destination() {
+      const owned = ingestOwnershipNow();
+      return editorIsAuthoring() && owned?.writable && writer
+        ? "the game's own source (creation-site write-back)"
+        : LIVE_ONLY_DESTINATION;
+    },
+    dispose() {
+      writer?.dispose();
+      writer = null;
+    },
+  };
+}

package/src/host/authoring/source-refresh-revisions.ts

@@ -0,0 +1,81 @@
+/** Match source revisions to completed Vite updates, irrespective of channel
+ * order. A websocket message alone is not evidence that an update applied.
+ * Entries are bounded by current file paths, never by edit count.
+ */
+export interface RefreshSource {
+  file: string;
+  path: string;
+  sha: string;
+  timestamp?: number;
+  /** Accepted importer URLs for a changed non-component dependency. */
+  boundaries?: readonly string[];
+}
+
+function updateFile(path: string): string {
+  return decodeURIComponent(path.split('?')[0]!)
+    .replace(/^\/@fs\/(?=[A-Za-z]:\/)/, '')
+    .replace(/^\/@fs/, '');
+}
+
+export class SourceRefreshRevisions {
+  private readonly sources = new Map<string, RefreshSource>();
+  private readonly applied = new Map<string, string>();
+  private readonly expected = new Map<string, string | null>();
+  private missingRevision = false;
+
+  source(source: RefreshSource): void {
+    this.sources.set(source.file, source);
+  }
+
+  complete(updates: readonly { acceptedPath: string; timestamp: number }[]): void {
+    for (const [file, source] of this.sources) {
+      const current = updates.filter((update) => source.timestamp === update.timestamp);
+      const complete = source.boundaries
+        ? source.boundaries.every((boundary) =>
+            current.some((update) => update.acceptedPath === boundary),
+          )
+        : current.some((update) => updateFile(update.acceptedPath) === file);
+      if (!complete) continue;
+      this.applied.set(source.path, source.sha);
+      this.sources.delete(file);
+    }
+  }
+
+  matches(update: { acceptedPath: string; timestamp: number }): boolean {
+    const file = updateFile(update.acceptedPath);
+    return [...this.sources.values()].some(
+      (source) =>
+        source.timestamp === update.timestamp &&
+        (source.boundaries
+          ? source.boundaries.includes(update.acceptedPath)
+          : source.file === file),
+    );
+  }
+
+  revision(resources: readonly { path: string; sha: string | null }[]): void {
+    for (const resource of resources) {
+      this.expected.set(resource.path, resource.sha);
+      if (resource.sha === null) this.applied.delete(resource.path);
+    }
+  }
+
+  needsRemount(): boolean {
+    if (this.missingRevision) return true;
+    for (const [path, sha] of this.expected) {
+      if (sha === null || this.applied.get(path) !== sha) return true;
+    }
+    return false;
+  }
+
+  missing(): void {
+    this.missingRevision = true;
+  }
+
+  /** A completed cold mount consumed these revisions through ordinary source. */
+  mounted(): void {
+    this.expected.clear();
+    this.applied.clear();
+    this.sources.clear();
+    this.missingRevision = false;
+  }
+}

package/src/host/authoring/struct-write-pipe.ts

@@ -0,0 +1,143 @@
+/**
+ * THE STRUCTURAL WRITE PIPE — the ONE producer of the `source-structure`
+ * resolution and its live-only floor, shared by every source-document lane.
+ *
+ * Extracted from three near-verbatim copies (owner-directed overlap audit,
+ * 2026-08-22): `R3fSourceAuthoringAdapter` (`structOp`/`removeMany`/
+ * `groupMany`/`pipedStructWrite`/`structRefusal`), `ReactRootAuthoringAdapter`
+ * (`structOp`/`removeManyElements`/`pipedStructWrite`/`structRefusal`) and
+ * `pixi-source-write-target` (`structOp`/`structMany`/`pipedStruct`/
+ * `structRefusal`). The copies had already drifted in the small ways their own
+ * doc comments warn about — refusal spellings, destination defaults — and one
+ * module makes the drift impossible rather than policed.
+ *
+ * WHY THE STRUCT DIALECT RESOLVES ON ITS OWN VERB (kept from every copy's
+ * header): `writeStruct`/`writeStructMany` is a DIFFERENT DOOR from the
+ * attribute writer, so it acks `source-structure`, never `source-prop` —
+ * resolving a delete on `writeProp`'s presence is how a lane comes to name a
+ * value lane that never carried the bytes. `record` is a no-op because the
+ * backend is wrapped in `withProjectSourceHistory`: the sha-guarded whole-file
+ * transaction that carries the bytes IS the undo entry, and journaling here
+ * would make one gesture two undos.
+ *
+ * WHAT STAYS PER-LANE, deliberately: OID RESOLUTION (identity is the lane's
+ * own scheme — a caller hands in the resolved oid), the DESTINATION sentence,
+ * and the ON-CHANGED hook (react marks dirty and queues a source reconcile;
+ * the canvas target refreshes its index; r3f notifies the store). A lane hands
+ * those in; this module never guesses them.
+ */
+
+import { showTransientHint } from '@volter/editor-core/transient-hint';
+import type { SourceWriteBackend } from '@volter/editor-core/ui-source/source-write-backend';
+import { resolvesLiveOnly, runWritePipe, type WriteAck, type WriteResolution } from '@volter/editor-core/authoring/write-pipe';
+
+/** The `writeStruct` options bag, spelled once (the backend's own shape). */
+export type StructOpOptions = Parameters<SourceWriteBackend['writeStruct']>[2];
+
+export interface StructWritePipeConfig {
+  /** The lane's own refusal/no-op reporter — prefix included, e.g.
+   *  `` (m) => console.warn(`[R3fSourceAuthoringAdapter] ${m}`) ``. */
+  report(message: string): void;
+  /** The live-only floor's reason when no struct door is bound. */
+  readonly noWriterReason: string;
+  /** The lane's backend, read at call time (a session can gain or lose one). */
+  backend(): SourceWriteBackend | null | undefined;
+  /** Ran after a LANDED structural write, before the ack resolves — the
+   *  lane's own reconcile/notify choreography. */
+  onChanged(): void | Promise<void>;
+}
+
+export interface StructWritePipe {
+  /** Every structural source write, through the pipe on the struct verb. */
+  pipedStruct(
+    write: () => Promise<boolean>,
+    op: string,
+    bound: boolean,
+    destination: string,
+  ): Promise<WriteAck>;
+  /** A structural verb that never reaches a writer, answered THROUGH the pipe
+   *  so the lane has exactly ONE producer of the live-only floor. `hint`, when
+   *  given, is the sentence the author who made the gesture also sees. */
+  structRefusal(reason: string, hint?: string): Promise<WriteAck>;
+  /** One `writeStruct` op against a resolved oid; `null` oid refuses by name. */
+  structOp(
+    oid: string | null | undefined,
+    subjectLabel: string,
+    op: string,
+    opts: StructOpOptions,
+    destination: string,
+  ): Promise<WriteAck>;
+  /** One `writeStructMany` batch. The CALLER owns oid collection and any
+   *  every-node-addressable refusal — batching policy is lane policy. */
+  structMany(
+    oids: readonly string[],
+    op: string,
+    opts: { wrapperTag?: string } | undefined,
+    destination: string,
+  ): Promise<WriteAck>;
+}
+
+export function createStructWritePipe(config: StructWritePipeConfig): StructWritePipe {
+  const pipedStruct: StructWritePipe['pipedStruct'] = (write, op, bound, destination) =>
+    runWritePipe({
+      resolve: (): WriteResolution =>
+        bound
+          ? { reaches: 'writer', anchorKind: 'source-structure', destination, write }
+          : resolvesLiveOnly(config.noWriterReason),
+      record: () => undefined,
+      report: (reason) => config.report(`"${op}" stays live-only — ${reason}.`),
+    });
+
+  const structRefusal: StructWritePipe['structRefusal'] = (reason, hint) =>
+    runWritePipe({
+      resolve: () => resolvesLiveOnly(reason),
+      record: () => undefined,
+      report: (said) => {
+        config.report(said);
+        if (hint) showTransientHint(hint);
+      },
+    });
+
+  return {
+    pipedStruct,
+    structRefusal,
+    structOp: (oid, subjectLabel, op, opts, destination) => {
+      if (!oid) {
+        return structRefusal(`"${op}" refused: "${subjectLabel}" has no source stamp.`);
+      }
+      return pipedStruct(
+        async () => {
+          const backend = config.backend()!;
+          const res = await backend.writeStruct(oid, op, opts);
+          if (!res.changed) {
+            config.report(
+              `struct "${op}" refused/no-op for oid "${oid}": ${res.error ?? 'no change'}`,
+            );
+            return false;
+          }
+          await config.onChanged();
+          return true;
+        },
+        op,
+        config.backend()?.writeStruct !== undefined,
+        destination,
+      );
+    },
+    structMany: (oids, op, opts, destination) =>
+      pipedStruct(
+        async () => {
+          const backend = config.backend()!;
+          const res = await backend.writeStructMany!(oids, op, opts);
+          if (!res.changed) {
+            config.report(`batch "${op}" refused/no-op: ${res.error ?? 'no change'}`);
+            return false;
+          }
+          await config.onChanged();
+          return true;
+        },
+        `${op} (batch)`,
+        config.backend()?.writeStructMany !== undefined,
+        destination,
+      ),
+  };
+}

package/src/host/auto-frame-window.ts

@@ -0,0 +1,89 @@
+/**
+ * What is still allowed to move the editor camera after a world is adopted,
+ * and when that stops.
+ *
+ * Opening the Scene tab on an adopted world is not one action, because the
+ * world is not one event: a game captures on its first drawn frame and keeps
+ * building itself for seconds afterwards (a level streams in; an R3F game's
+ * own camera appears only when its `<Suspense>` content resolves). So there is
+ * a WINDOW, and two things may fire inside it — the game's own camera, which
+ * wins outright, and a measured framing, which lands once as the interim
+ * answer. `scene-framing.ts` is what each of those means.
+ *
+ * The rule that outranks both: **the reader's first camera gesture ends the
+ * window** (#1706). Yanking the view out from under someone already looking is
+ * worse than never framing at all, so `cancel()` is total — after it, nothing
+ * in here touches the camera again, whatever is still loading.
+ */
+
+/** How long a requested auto-frame keeps waiting for a world that is still
+ *  building itself, and how often it re-checks. */
+export const AUTO_FRAME_WINDOW_MS = 20_000;
+export const AUTO_FRAME_RETRY_MS = 250;
+/** How long an adopted game gets to produce its OWN camera before the editor
+ *  settles for its measured framing. Shorter than the framing window on
+ *  purpose: replacing the view is welcome while the reader is still watching
+ *  the world appear, and an intrusion long after that. */
+export const AUTO_SEED_WINDOW_MS = 5_000;
+
+/** The two things that may open the reader on the world. Each returns whether
+ *  it actually moved the camera. */
+export interface AutoFrameSteps {
+  /** Adopt the adopted game's own camera; false when it has none yet, or none
+   *  whose view is usable. */
+  seedFromGameCamera(): boolean;
+  /** Frame the content that exists right now; false when there is none yet. */
+  frameContent(): boolean;
+}
+
+export class AutoFrameWindow {
+  #framingDeadline = 0;
+  #seedDeadline = 0;
+  #nextTry = 0;
+  readonly #steps: AutoFrameSteps;
+
+  constructor(steps: AutoFrameSteps) {
+    this.#steps = steps;
+  }
+
+  /** True while something in here may still move the camera. */
+  get pending(): boolean {
+    return this.#framingDeadline > 0 || this.#seedDeadline > 0;
+  }
+
+  /**
+   * Open the window and take the first attempt immediately.
+   * `watchForGameCamera` is false for a world that has no game camera to wait
+   * for — a first-party scene never gets one.
+   */
+  begin(now: number, watchForGameCamera: boolean): void {
+    this.#framingDeadline = now + AUTO_FRAME_WINDOW_MS;
+    this.#seedDeadline = watchForGameCamera ? now + AUTO_SEED_WINDOW_MS : 0;
+    this.#nextTry = 0;
+    this.tick(now);
+  }
+
+  /** Ride the caller's frame loop. Cheap and self-rate-limiting: a no-op
+   *  unless the window is open and the retry cadence has come round. */
+  tick(now: number): void {
+    if (!this.pending || now < this.#nextTry) return;
+    this.#nextTry = now + AUTO_FRAME_RETRY_MS;
+    // The game's own camera outranks any measurement, and ends the window: it
+    // is the answer both other paths were approximating.
+    if (this.#seedDeadline > 0 && this.#steps.seedFromGameCamera()) {
+      this.cancel();
+      return;
+    }
+    // The framing lands ONCE — re-framing every retry would drag the view
+    // around for the whole window while a level streams in.
+    if (this.#framingDeadline > 0 && this.#steps.frameContent()) this.#framingDeadline = 0;
+    if (now >= this.#framingDeadline) this.#framingDeadline = 0;
+    if (now >= this.#seedDeadline) this.#seedDeadline = 0;
+  }
+
+  /** The reader took the camera. Nothing here moves it again. */
+  cancel(): void {
+    this.#framingDeadline = 0;
+    this.#seedDeadline = 0;
+  }
+}