@volter/editor-core 0.5.57

package/src/authoring/boundary-authoring-adapter.ts

@@ -0,0 +1,184 @@
+/**
+ * BoundaryAuthoringAdapter — A1's read-only {@link AuthoringAdapter} for a
+ * manifest-declared world that is NOT currently mounted (edit mode only runs
+ * the manifest's sole Three world live — every other declared world is disclosed,
+ * not simulated; see `edit-mode-authoring.ts`'s doc comment for the seam this
+ * plugs into, and B1 for the "mount it live" upgrade path).
+ *
+ * A single node, one per world: label = the declared entry/scene document (or
+ * the world id when it has none), with error/read-only state carried as
+ * metadata rather than punctuation embedded in the name. `kind` = the
+ * manifest world kind, inspector exposes kind/adapter/entry-or-scene
+ * path/zOrder/pausable (+ `reason` when unresolvable) as READ-ONLY
+ * properties. No children, no live object, no structural/transform ops — this
+ * adapter's entire job is "say the world exists and why it isn't live yet".
+ *
+ * Resolvability is a CALLER decision (`edit-mode-authoring.ts` computes the
+ * reason from the manifest world entry) — this adapter just renders whatever
+ * reason string it's given; it never itself decides a world is broken.
+ */
+
+import type {
+  AuthoringAdapter,
+  AuthoringCapabilities,
+  AuthoringProvenance,
+  EditorNode,
+  HierarchyProvider,
+  InspectorProvider,
+  PickProvider,
+  PropertyDescriptor,
+  SelectionProvider,
+} from '@volter/editor-project/adapter';
+import type { EditorShellStore } from '../editor-shell-store';
+
+/** The display-relevant slice of a manifest world entry — deliberately loose
+ *  (plain strings, not the engine's validated `AdapterRoot['kind']` union) so
+ *  an UNRESOLVABLE world (unknown kind, e.g.) can still be described. */
+export interface BoundaryRootInfo {
+  readonly id: string;
+  readonly kind: string;
+  /** Display string for the manifest's `adapter` field (e.g. `'default'`,
+   *  `'module:<path>'`) — omitted when not meaningfully derivable. */
+  readonly adapter?: string | undefined;
+  /** Whichever of `scene`/`entry` the world declares (display-only — this
+   *  adapter never reads the file). */
+  readonly entryOrScenePath?: string | undefined;
+  readonly zOrder: number;
+  readonly pausable: boolean;
+}
+
+const NO_CAPABILITIES: AuthoringCapabilities = {
+  transform: false,
+  inspectorFields: false,
+  persist: false,
+};
+
+export class BoundaryAuthoringAdapter implements AuthoringAdapter {
+  readonly capabilities: AuthoringCapabilities = NO_CAPABILITIES;
+
+  readonly provenance: AuthoringProvenance = {
+    source: 'boundary',
+    label: 'read-only',
+    detail:
+      'Declared world without a live editing surface in this viewport — disclosed, not simulated; rows are read-only.',
+  };
+  private readonly world: BoundaryRootInfo;
+  /** Non-null ⇒ error-node mode (#18) — set by the caller, never computed here. */
+  private readonly reason: string | null;
+  private readonly store: EditorShellStore;
+  /**
+   * D12 (B4) — a design-time layer's own stage hit-test, wired in by
+   * `design-time-layers.ts`'s layer-mount success handler: when a mount
+   * returns a `pick` but NO authoring adapter (an opaque/foreign root that can
+   * report where a click landed without offering a source-authoring surface),
+   * that handler re-wraps the world's Boundary through this constructor
+   * parameter, so the pick rides on THIS adapter rather than a second
+   * substrate-specific one. Absent for every other Boundary (an unresolved or
+   * error world, and every world whose mount reported no `pick`) ⇒ this
+   * adapter reports no `pickable` at all. A plain
+   * conditionally-assigned field (not a getter always returning `{ pick:
+   * undefined }`) — this repo's `exactOptionalPropertyTypes` requires the key
+   * to be genuinely ABSENT, not present with an `undefined` value, to satisfy
+   * `AuthoringAdapter.pickable?: PickProvider`.
+   */
+  readonly pickable?: PickProvider;
+
+  constructor(
+    store: EditorShellStore,
+    world: BoundaryRootInfo,
+    reason?: string,
+    pick?: PickProvider['pick'],
+  ) {
+    this.store = store;
+    this.world = world;
+    this.reason = reason ?? null;
+    if (pick) this.pickable = { pick };
+  }
+
+  private get label(): string {
+    return this.world.entryOrScenePath?.split('/').pop() ?? this.world.id;
+  }
+
+  private get node(): EditorNode {
+    return {
+      id: this.world.id,
+      label: this.label,
+      secondaryLabel: this.reason ? 'Unavailable' : 'Read-only',
+      role: 'boundary',
+      kind: this.world.kind,
+      parentId: null,
+      childIds: [],
+    };
+  }
+
+  readonly hierarchy: HierarchyProvider = {
+    roots: (): EditorNode[] => [this.node],
+    node: (id) => (id === this.world.id ? this.node : null),
+    // No `object3D`/`idForObject3D`: a boundary node has no live object at all.
+  };
+
+  /**
+   * Selection delegates to the editor-global {@link EditorShellStore} selection set
+   * — the SAME seam `ThreeAuthoringAdapter`/`ReactRootAuthoringAdapter` use
+   * (selection is editor UI state, not a per-adapter document concern). Without
+   * this, clicking a Boundary/error node in `IngestHierarchy` (the panel the
+   * composite drives) would be a silent no-op, so the node — and its `reason`
+   * (#18) — could never be selected or inspected (defect 3). It also makes the
+   * composite's empty-clear (`selection.set([])` routed to `children[0]`) work
+   * when a Boundary sorts first (defect 4).
+   */
+  readonly selection: SelectionProvider = {
+    get: () => [...this.store.selectedEntityIds],
+    set: (ids) => this.store.selectMultiple(ids),
+  };
+
+  readonly inspector: InspectorProvider = {
+    properties: (id): PropertyDescriptor[] => {
+      if (id !== this.world.id) return [];
+      const props: PropertyDescriptor[] = [
+        { path: 'kind', label: 'Kind', type: 'string', readonly: true },
+      ];
+      if (this.world.adapter !== undefined) {
+        props.push({ path: 'adapter', label: 'Adapter', type: 'string', readonly: true });
+      }
+      if (this.world.entryOrScenePath !== undefined) {
+        props.push({ path: 'path', label: 'Entry / Scene', type: 'string', readonly: true });
+      }
+      props.push(
+        { path: 'zOrder', label: 'Z Order', type: 'number', readonly: true },
+        { path: 'pausable', label: 'Pausable', type: 'boolean', readonly: true },
+      );
+      if (this.reason) {
+        props.push({ path: 'reason', label: 'Reason', type: 'string', readonly: true });
+      }
+      return props;
+    },
+    get: (id, path) => {
+      if (id !== this.world.id) return undefined;
+      switch (path) {
+        case 'kind':
+          return this.world.kind;
+        case 'adapter':
+          return this.world.adapter;
+        case 'path':
+          return this.world.entryOrScenePath;
+        case 'zOrder':
+          return this.world.zOrder;
+        case 'pausable':
+          return this.world.pausable;
+        case 'reason':
+          return this.reason ?? undefined;
+        default:
+          return undefined;
+      }
+    },
+    // Read-only — every property above is display-derived from the manifest;
+    // there is nowhere to persist a write to (matches how a not-yet-mounted
+    // world has no live document). No-op rather than throw, matching the
+    // reserved-paths convention's "adapters that don't support a path simply
+    // don't offer it" floor.
+    set: (_id, _path, _value) => {
+      // Intentionally inert.
+    },
+  };
+}

package/src/authoring/breakpoint-state.ts

@@ -0,0 +1,43 @@
+/**
+ * The active BREAKPOINT for style edits (design ledger: breakpoints) — a CSS
+ * media condition like `(max-width: 767px)`, or null for base. While set,
+ * react-world style edits land in the element's named-style rule inside that
+ * `@media` block; the dev server's serve-time container-query rewrite is what
+ * previews the result per frame width.
+ *
+ * MODULE state, not adapter state (measured): design-time re-renders recreate
+ * the authoring adapters between the select gesture and the next style edit,
+ * so an instance field silently reset to base — the select still showed the
+ * breakpoint while the write landed unscoped. Session-scoped UI state, like
+ * the transform mode; never persisted, never game truth.
+ */
+
+// globalThis-backed: the editor page can hold MORE THAN ONE instance of this
+// module (measured: even after a cold load, the select's set and the
+// adapter's read disagreed — the write landed unscoped while the select held
+// the breakpoint), so module-local state is not a singleton here. One global
+// slot is.
+interface BreakpointGlobal {
+  __vgaiActiveBreakpoint?: string | null;
+  __vgaiBreakpointListeners?: Set<() => void>;
+}
+const g = globalThis as BreakpointGlobal;
+
+function listeners(): Set<() => void> {
+  g.__vgaiBreakpointListeners ??= new Set();
+  return g.__vgaiBreakpointListeners;
+}
+
+export function activeBreakpoint(): string | null {
+  return g.__vgaiActiveBreakpoint ?? null;
+}
+
+export function setActiveBreakpoint(media: string | null): void {
+  g.__vgaiActiveBreakpoint = media;
+  for (const listener of listeners()) listener();
+}
+
+export function subscribeBreakpoint(listener: () => void): () => void {
+  listeners().add(listener);
+  return () => listeners().delete(listener);
+}

package/src/authoring/canvas-scene-guides.ts

@@ -0,0 +1,76 @@
+import type { RootViewController } from './world-pan-state';
+
+export interface CanvasSceneGuide {
+  readonly id: string;
+  readonly axis: 'x' | 'y';
+  readonly value: number;
+}
+
+interface GuideState {
+  guides: CanvasSceneGuide[];
+  listeners: Set<() => void>;
+  revision: number;
+}
+
+const states = new WeakMap<RootViewController, GuideState>();
+let nextGuideId = 0;
+
+function stateFor(view: RootViewController): GuideState {
+  let state = states.get(view);
+  if (!state) {
+    state = { guides: [], listeners: new Set(), revision: 0 };
+    states.set(view, state);
+  }
+  return state;
+}
+
+function publish(state: GuideState): void {
+  state.revision += 1;
+  for (const listener of state.listeners) listener();
+}
+
+export function canvasSceneGuides(view: RootViewController): readonly CanvasSceneGuide[] {
+  return stateFor(view).guides;
+}
+
+export function canvasSceneGuideRevision(view: RootViewController): number {
+  return stateFor(view).revision;
+}
+
+export function subscribeCanvasSceneGuides(
+  view: RootViewController,
+  listener: () => void,
+): () => void {
+  const state = stateFor(view);
+  state.listeners.add(listener);
+  return () => state.listeners.delete(listener);
+}
+
+export function addCanvasSceneGuide(
+  view: RootViewController,
+  axis: CanvasSceneGuide['axis'],
+  value: number,
+): string {
+  nextGuideId += 1;
+  const state = stateFor(view);
+  const id = `canvas-guide-${nextGuideId}`;
+  state.guides = [...state.guides, { id, axis, value }];
+  publish(state);
+  return id;
+}
+
+export function moveCanvasSceneGuide(view: RootViewController, id: string, value: number): void {
+  const state = stateFor(view);
+  const next = state.guides.map((guide) => (guide.id === id ? { ...guide, value } : guide));
+  if (next.every((guide, index) => guide === state.guides[index])) return;
+  state.guides = next;
+  publish(state);
+}
+
+export function removeCanvasSceneGuide(view: RootViewController, id: string): void {
+  const state = stateFor(view);
+  const next = state.guides.filter((guide) => guide.id !== id);
+  if (next.length === state.guides.length) return;
+  state.guides = next;
+  publish(state);
+}

package/src/authoring/component-instance-root.ts

@@ -0,0 +1,171 @@
+/**
+ * ONE predicate for "is this object the outermost node of a component
+ * instance?", shared by every reader of the OID convention.
+ *
+ * ## Why this exists
+ *
+ * `vite-plugin-ui-oid`'s transform stamps `userData.authoringInstance` (the
+ * CALLSITE oid) on **every host element inside a component definition**, not
+ * just on the one the component returns — that is what lets a click on a mesh
+ * deep inside `<Coin/>` resolve to the `<Coin/>` callsite, and what lets a
+ * gizzmo drag rewrite the callsite's own props.
+ *
+ * So `authoringInstance !== undefined` answers "which instance does this node
+ * BELONG to", and it is the wrong question to ask when you mean "is this node
+ * that instance's root". Reading it as the latter is what made the hierarchy
+ * print `Stage` on every one of `Stage`'s interior nodes and type all of them
+ * `component`: `WorldEnvironment`, `GridMap` and `Coins` all carry `Stage`'s
+ * stamp, because they are all inside `Stage`'s definition.
+ *
+ * The boundary question has a structural answer that needs no extra stamp: an
+ * instance's root is the node whose `authoringInstance` its PARENT does not
+ * share. A component that returns several spatial roots (R3F003) therefore has
+ * several — which is exactly what that warning is about, and not something this
+ * predicate should hide.
+ */
+
+import { getUserData } from '@volter/editor-threejs/ecs/user-data';
+import type * as THREE from 'three';
+
+/**
+ * True when `object` is the outermost node of one component instance — the row
+ * that should print the component's label and read as `role: 'component'`.
+ *
+ * False for an interior host element of that same instance (it belongs to the
+ * instance but is not its boundary) and for any node the transform never
+ * stamped.
+ */
+export function isComponentInstanceRoot(object: THREE.Object3D | null | undefined): boolean {
+  return instanceCallsiteOid(object) !== undefined;
+}
+
+/**
+ * WHICH INSTANCE this node belongs to — the raw `authoringInstance` stamp,
+ * read in exactly one place.
+ *
+ * Deliberately NOT the same question as {@link isComponentInstanceRoot} (see
+ * this module's header): every host element inside a component definition
+ * carries it, so it groups a subtree and never bounds one. Callers that want
+ * "same instance?" (the constraint stack's own-parts walk, the adapter's owner
+ * chain) want THIS; callers that want "is this the instance's row" want the
+ * predicate above.
+ */
+export function instanceStampOf(object: THREE.Object3D | null | undefined): string | undefined {
+  const instance = getUserData(object, 'authoringInstance');
+  return typeof instance === 'string' && instance ? instance : undefined;
+}
+
+/**
+ * The element's OWN definition-side oid — where this JSX element is WRITTEN, as
+ * opposed to the callsite that instantiated whatever renders it.
+ *
+ * `oid` is stamped by `vite-plugin-ui-oid` on every host element, so it is
+ * present on a component's root element and on each of its interior ones alike.
+ * It is NOT an address: at an instance root the address is the callsite
+ * ({@link authoringOidOf}). Read it when the DEFINITION is the subject —
+ * "Fork Component…" copying the component, or the occurrence rule below asking
+ * which definition element a live object renders.
+ */
+export function ownOidOf(
+  /** An `Object3D`, or a MATERIAL — fiber can pierce a stamp onto a
+   *  `<meshStandardMaterial userData-oid=…>` child element, and a material
+   *  carries `userData` without being a scene-graph node, so that stamp is its
+   *  only handle. Structural, so both pass without this module knowing which. */
+  stamped: { readonly userData?: Record<string, unknown> } | null | undefined,
+): string | undefined {
+  const own = stamped?.userData?.['oid'];
+  return typeof own === 'string' && own ? own : undefined;
+}
+
+/** The callsite oid `object` is the ROOT of, or `undefined`. */
+function instanceCallsiteOid(object: THREE.Object3D | null | undefined): string | undefined {
+  const instance = instanceStampOf(object);
+  if (instance === undefined) return undefined;
+  return getUserData(object?.parent, 'authoringInstance') === instance ? undefined : instance;
+}
+
+/** A third-party R3F component cannot be instrumented inside its package, but
+ * many ecosystem components forward unknown props to their native host root.
+ * The editor-injected callsite prop therefore lands directly on the resulting
+ * Object3D (Drei cameras are the canonical example). It is a callsite address,
+ * not the object's definition-side `userData.oid`. */
+function forwardedCallsiteOid(object: THREE.Object3D | null | undefined): string | undefined {
+  const forwarded = (object as (THREE.Object3D & { __vgaiOid?: unknown }) | null | undefined)
+    ?.__vgaiOid;
+  return typeof forwarded === 'string' && forwarded ? forwarded : undefined;
+}
+
+/**
+ * THE OCCURRENCE CONVENTION — one source address, several live objects.
+ *
+ * A single JSX element can render more than once (a `.map()` over 44 spawn
+ * points instantiates ONE `<Coin/>` callsite 44 times), and a component's
+ * interior element can be reparented out of its instance's subtree so that it,
+ * too, resolves to the callsite oid. Either way the adapters' walks meet the
+ * same oid twice, and both mint the same shape of id: the first one seen in
+ * depth-first order keeps the bare address, later ones get `#1`, `#2`, ….
+ *
+ * The suffix is spelled HERE and nowhere else. It was previously written out at
+ * four sites — two minting walks (`projection/three.ts`,
+ * `R3fSourceAuthoringAdapter.indexGraph`), one authority check, and one
+ * presence report that stripped it back off with `split('#')[0]` — which is how
+ * a convention becomes four conventions.
+ */
+export function occurrenceId(baseId: string, occurrence: number): string {
+  return occurrence === 0 ? baseId : `${baseId}#${occurrence}`;
+}
+
+/** True for `…#1`, `…#2` — an id that is NOT its address's first occurrence. */
+export function isOccurrenceId(id: string): boolean {
+  return id.includes('#');
+}
+
+/** `id` with any occurrence suffix removed — the address all its occurrences share. */
+export function withoutOccurrence(id: string): string {
+  const hash = id.indexOf('#');
+  return hash < 0 ? id : id.slice(0, hash);
+}
+
+/**
+ * Whether two live objects are renders of THE SAME JSX element.
+ *
+ * This is the CAPABILITY question behind an occurrence id, and it is the whole
+ * reason the two causes above must not be treated alike. N objects that share
+ * one callsite AND render one definition element are N renders of one element;
+ * the element is the unit of edit, so a literal prop on it is honestly
+ * writable and moving one moves all — which is exactly what the source says. A
+ * reparented interior element renders a DIFFERENT definition element, merely
+ * addressed by the callsite it escaped from, so writing that callsite's props
+ * would edit the instance instead of the object under the pointer.
+ *
+ * Both objects having no own oid counts as the same element: an unstamped pair
+ * is a component with several spatial roots (R3F003), which the callsite's own
+ * authoring contract already refuses on better grounds than a guess here.
+ */
+export function rendersSameSourceElement(
+  a: THREE.Object3D | null | undefined,
+  b: THREE.Object3D | null | undefined,
+): boolean {
+  return ownOidOf(a) === ownOidOf(b);
+}
+
+/**
+ * The oid that ADDRESSES `object` in source — the key every id, source
+ * location and prop write resolves through.
+ *
+ * At an instance ROOT it is the CALLSITE oid, because that is where the author
+ * put this instance and where a gizmo drag must land: moving `Coin1` rewrites
+ * `<Coin name='Coin1' position={…}/>` in the parent scene, not the shared
+ * `<Coin/>` definition every coin renders from.
+ *
+ * ANYWHERE ELSE it is the element's OWN definition oid. An interior host
+ * element of a component carries the instance stamp too (that is how a click
+ * on it resolves to the instance), but the stamp is not its address: reading
+ * it as one gave every interior node of `Stage` the id
+ * `r3f:<world>:<Stage's callsite>#N` — a position among `Stage`'s stamped
+ * elements rather than a name — and pointed each one's source location and
+ * prop writes at the `<Stage/>` callsite instead of at itself.
+ */
+export function authoringOidOf(object: THREE.Object3D | null | undefined): string | undefined {
+  return instanceCallsiteOid(object) ?? forwardedCallsiteOid(object) ?? ownOidOf(object);
+}