@volter/editor-core 0.5.57

package/src/authoring/selection-scope.ts

@@ -0,0 +1,195 @@
+import type { AuthoringAdapter, EditorNode } from '@volter/editor-project/adapter';
+import { setAuthoringSelection } from './consumer-actions';
+
+/** Session-only contents scope shared by hierarchy, viewport picking, and
+ * hotkeys. The adapter remains the source of hierarchy/ownership truth; this
+ * module only records which semantic boundary the user has opened. */
+interface SelectionScopeState {
+  adapter: AuthoringAdapter;
+  stack: string[];
+}
+
+let state: SelectionScopeState | null = null;
+const listeners = new Set<() => void>();
+let version = 0;
+
+function emit(): void {
+  version += 1;
+  for (const listener of listeners) listener();
+}
+
+function isScopeNode(node: EditorNode | null): boolean {
+  return (
+    !!node && (node.role === 'component' || node.role === 'instance' || node.role === 'boundary')
+  );
+}
+
+function isDescendant(adapter: AuthoringAdapter, id: string, ancestorId: string): boolean {
+  let current: string | null = id;
+  let guard = 0;
+  while (current && guard++ < 1000) {
+    if (current === ancestorId) return true;
+    current = adapter.hierarchy.node(current)?.parentId ?? null;
+  }
+  return false;
+}
+
+export function subscribeSelectionScope(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function selectionScopeVersion(): number {
+  return version;
+}
+
+/** Current boundary id for pick resolution. Deliberately adapter-agnostic:
+ * layered picking resolves through a composite's child adapter while the
+ * hierarchy owns the composite adapter that opened the scope. */
+export function currentSelectionScopeId(): string | null {
+  return state?.stack.at(-1) ?? null;
+}
+
+export function selectionScopeStack(adapter: AuthoringAdapter): string[] {
+  if (state?.adapter !== adapter) return [];
+  const valid = state.stack.filter((id) => adapter.hierarchy.node(id) !== null);
+  if (valid.length !== state.stack.length) {
+    state = valid.length > 0 ? { adapter, stack: valid } : null;
+  }
+  return valid;
+}
+
+export function enterSelectionScope(adapter: AuthoringAdapter, id: string): boolean {
+  const node = adapter.hierarchy.node(id);
+  if (!isScopeNode(node) || node!.childIds.length === 0) return false;
+
+  const current = state?.adapter === adapter ? state.stack : [];
+  const parentScope = current.at(-1);
+  if (parentScope && !isDescendant(adapter, id, parentScope)) return false;
+  if (parentScope === id) return false;
+  state = { adapter, stack: [...current, id] };
+  setAuthoringSelection(adapter, [id]);
+  emit();
+  return true;
+}
+
+/** Navigate to an existing breadcrumb boundary, or null for the full Game. */
+export function setSelectionScope(adapter: AuthoringAdapter, id: string | null): void {
+  if (id === null) {
+    if (state === null) return;
+    state = null;
+    emit();
+    return;
+  }
+  const current = selectionScopeStack(adapter);
+  const index = current.indexOf(id);
+  if (index < 0) return;
+  state = { adapter, stack: current.slice(0, index + 1) };
+  setAuthoringSelection(adapter, [id]);
+  emit();
+}
+
+export function exitSelectionScope(adapter: AuthoringAdapter): boolean {
+  if (state && state.adapter !== adapter) {
+    state = null;
+    emit();
+    return true;
+  }
+  const current = selectionScopeStack(adapter);
+  if (current.length === 0) return false;
+  const next = current.slice(0, -1);
+  state = next.length > 0 ? { adapter, stack: next } : null;
+  const selectionId = next.at(-1) ?? current[0]!;
+  setAuthoringSelection(adapter, [selectionId]);
+  emit();
+  return true;
+}
+
+export function enterSelectedScope(adapter: AuthoringAdapter): boolean {
+  const selected = adapter.selection?.get() ?? [];
+  return selected.length === 1 ? enterSelectionScope(adapter, selected[0]!) : false;
+}
+
+/**
+ * Drill in ONE level (the viewport's double-click, Figma's own gesture): open
+ * `boundaryId`'s scope, then select whatever the SAME pointer resolves to now
+ * that the scope is open.
+ *
+ * `repick` is the caller's own pick — `layered-pick.ts` already passes
+ * `currentSelectionScopeId()` into `SelectionProvider.resolve`, and the
+ * adapter's resolve already answers with the next member down its own owner
+ * chain. So there is no second chain-walking rule here, and this module still
+ * knows nothing about how a surface picks. Repeat the gesture to keep
+ * descending; {@link exitSelectionScope} (Escape) walks back out.
+ */
+export function drillIntoSelectionScope(
+  adapter: AuthoringAdapter,
+  boundaryId: string,
+  repick: () => string | null,
+): boolean {
+  if (!enterSelectionScope(adapter, boundaryId)) return false;
+  // `enterSelectionScope` already selected the boundary; a deeper member under
+  // the same pointer is what the gesture actually asked for. When the chain
+  // ends here the boundary stays selected — entering was still correct.
+  const deeper = repick();
+  if (deeper && deeper !== boundaryId) setAuthoringSelection(adapter, [deeper]);
+  return true;
+}
+
+/**
+ * Figma's outside-click rule: a click that lands outside an open scope leaves
+ * it. Pops every entry whose boundary does not CONTAIN `id`, so the stack
+ * follows the click to the level that does; a `null` id (empty space) closes
+ * every scope.
+ *
+ * Selection stays the caller's to set — the pick that produced `id` was
+ * already resolved against the scope that was open (a chain without the scope
+ * in it resolves to its own outermost owner), so this only makes the stack
+ * agree with where the click landed.
+ */
+export function popSelectionScopesToContain(adapter: AuthoringAdapter, id: string | null): boolean {
+  const current = selectionScopeStack(adapter);
+  if (current.length === 0) return false;
+  let depth = 0;
+  while (id !== null && depth < current.length && isDescendant(adapter, id, current[depth]!)) {
+    depth += 1;
+  }
+  if (depth === current.length) return false;
+  state = depth > 0 ? { adapter, stack: current.slice(0, depth) } : null;
+  emit();
+  return true;
+}
+
+/**
+ * ONE click's answer, across the scope exit the click itself causes — the
+ * whole of the viewport's single-click resolution.
+ *
+ * A pick resolves against whatever scope is OPEN (`layered-pick.ts` hands
+ * `currentSelectionScopeId()` to the adapter's own resolve), so a click that
+ * leaves the innermost scope was resolved by a scope that is about to be
+ * wrong. With a one-deep stack that is invisible — popping lands at "no
+ * scope", which is what the stale answer already assumed. With a stack THREE
+ * deep it is visible: the stale resolve answers with the chain's outermost
+ * owner, one level shallower than the same click gives once the stack has
+ * followed it, so the user has to click twice to land where one click should
+ * have (reviewer, #1235).
+ *
+ * So: resolve, let {@link popSelectionScopesToContain} follow the hit, and
+ * re-resolve ONCE — only when the stack actually moved, because a click that
+ * stays inside the open scope has nothing to re-resolve against. The second
+ * answer needs no second pop: it is a member of the scope the first pop
+ * settled on.
+ */
+export function pickAcrossScopeExit(
+  adapter: AuthoringAdapter,
+  repick: () => string | null,
+): string | null {
+  const hit = repick();
+  return popSelectionScopesToContain(adapter, hit) ? repick() : hit;
+}
+
+/** Test-only reset; production scope is intentionally session-local. */
+export function _resetSelectionScopeForTest(): void {
+  state = null;
+  emit();
+}

package/src/authoring/shell-document-ops.ts

@@ -0,0 +1,169 @@
+/**
+ * Format-neutral shell document operations.
+ *
+ * Save destination, save state, hierarchy rows and select-all are questions
+ * about a DOCUMENT, and the shell owns none. Answering them from store fields
+ * would bind the shell chrome — status bar, application menus, command relay,
+ * hotkeys — to one format; these helpers ask the ACTIVE
+ * {@link AuthoringAdapter} instead, so the same chrome works for a TSX/R3F
+ * world, a React root, and an ingested game alike.
+ */
+
+import type { AuthoringAdapter, NodeCreationSite, WriteAnchorKind } from '@volter/editor-project/adapter';
+import type { EditorShellStore } from '../editor-shell-store';
+import { forEachHierarchyNode } from '../hierarchy-walk';
+import { getActiveAuthoring } from './active-adapter';
+import { saveAuthoringDocument, setAuthoringSelection } from './consumer-actions';
+import { resolvePanelAuthoring } from './panel-authoring';
+
+/** The authoring adapter owned by the active center document. This is the same
+ * resolution used by Hierarchy and Inspector; shell commands must not keep
+ * driving the scene adapter after an asset/source document becomes active. */
+export function activeDocumentAuthoring(store: EditorShellStore): AuthoringAdapter {
+  return resolvePanelAuthoring(store).adapter;
+}
+
+/** One flattened hierarchy row — the wire shape `editor.hierarchy.inspect` reports. */
+export interface ShellHierarchyRow {
+  id: string;
+  name: string;
+  childIds: string[];
+}
+
+/**
+ * The active adapter's hierarchy, flattened breadth-first to id/name/childIds
+ * rows. `[]` when the adapter owns no tree (the no-authoring floor).
+ */
+export function activeHierarchyRows(store: EditorShellStore): ShellHierarchyRow[] {
+  const rows: ShellHierarchyRow[] = [];
+  forEachHierarchyNode(activeDocumentAuthoring(store).hierarchy, (node) => {
+    rows.push({ id: node.id, name: node.label, childIds: [...node.childIds] });
+  });
+  return rows;
+}
+
+/**
+ * The source path represented by an adapter's document node.
+ *
+ * Source-authored adapters persist edits immediately and intentionally expose
+ * no PersistenceProvider. Their hierarchy still owns an honest document node
+ * whose secondary label is the project-relative source path (`src/world.tsx`,
+ * for example). Prefer that source identity for document chrome instead of
+ * leaking a composite persistence fallback such as "(no persistable child)".
+ */
+export function authoringDocumentSourcePath(adapter: AuthoringAdapter): string | null {
+  let found: string | null = null;
+  forEachHierarchyNode(adapter.hierarchy, (node) => {
+    const sourcePath = node.secondaryLabel?.trim();
+    if (node.role !== 'document' || !sourcePath) return;
+    found = sourcePath;
+    return false; // the first document row answers; never walk the whole tree for it
+  });
+  return found;
+}
+
+/** The active source-authored document path, when its adapter exposes one. */
+export function activeDocumentSourcePath(store: EditorShellStore): string | null {
+  return authoringDocumentSourcePath(getActiveAuthoring(store));
+}
+
+/** The exact source filename represented by a project-relative path. */
+export function sourceFileName(sourcePath: string | null | undefined): string | null {
+  const trimmed = sourcePath?.trim();
+  if (!trimmed) return null;
+  return trimmed.split(/[\\/]/).filter(Boolean).at(-1) ?? null;
+}
+
+/**
+ * Where a save would land, straight from the active adapter's
+ * `PersistenceProvider`, or `null` when this adapter persists nothing.
+ */
+export function activeSaveDestination(store: EditorShellStore): string | null {
+  const adapter = getActiveAuthoring(store);
+  return adapter.capabilities.persist ? (adapter.persistence?.destination ?? null) : null;
+}
+
+/**
+ * Whether the active adapter has unsaved edits.
+ *
+ * A source-backed adapter may be clean because it rolled a failed write back.
+ * Its provider still reports that failure until a later successful write
+ * clears the project-history error; clean and successful are not synonyms.
+ */
+export function activeSaveState(store: EditorShellStore): 'saved' | 'unsaved' | 'failed' {
+  const persistence = getActiveAuthoring(store).persistence;
+  if (persistence?.lastError?.()) return 'failed';
+  return persistence?.isDirty() ? 'unsaved' : 'saved';
+}
+
+/** The active adapter's human-readable persistence failure, when any. */
+export function activeSaveFailure(store: EditorShellStore): string | null {
+  return getActiveAuthoring(store).persistence?.lastError?.() ?? null;
+}
+
+/**
+ * The creation-site anchor for the CURRENT selection, as the control
+ * API reports it (`vgai status` / `vgai eval`'s `editor.status()`).
+ *
+ * `null` has one meaning and one only: there is nothing to ask about — no
+ * selection, or an active adapter that indexes no creation sites. Whenever the
+ * adapter DOES index them the answer is a record, anchored or reasoned; a
+ * silent blank for "we couldn't find it" is exactly what the honest-floor rule
+ * forbids.
+ */
+export function activeSelectionCreationSite(store: EditorShellStore): NodeCreationSite | null {
+  const adapter = activeDocumentAuthoring(store);
+  const id = adapter.selection?.get()[0] ?? null;
+  if (!id) return null;
+  return adapter.truth?.resolve(id, 'position').site ?? null;
+}
+
+/**
+ * The WRITE-side sibling of {@link activeSelectionCreationSite}: which lane
+ * would carry an edit to the current selection (`WriteAnchorKind`).
+ *
+ * Reported beside the anchor because the anchor alone cannot answer it — two
+ * subjects at the same kind of `file:line` can belong to different lanes with
+ * different correctness contracts. A caller sweeping the hierarchy for one
+ * subject per lane reads this per row; `vgai doctor`'s edit-write walk is that
+ * caller, and it is what makes the walk exhaustive over the kinds a world has
+ * instead of stopping at whichever row answered first.
+ *
+ * `null` on the same terms as the anchor: nothing selected, or an adapter that
+ * plans no distinguishable lanes.
+ *
+ * READ THROUGH THE SAME BINDING THE WRITE TAKES ({@link activeDocumentAuthoring},
+ * which is what `setActiveInspectionField` resolves too). A classifier reached
+ * through a different resolver than the writer is how a subject came to be
+ * reported in one lane while its edit travelled another.
+ */
+export function activeSelectionWriteAnchorKind(store: EditorShellStore): WriteAnchorKind | null {
+  const adapter = activeDocumentAuthoring(store);
+  const id = adapter.selection?.get()[0] ?? null;
+  if (!id) return null;
+  return adapter.truth?.resolve(id, 'position').writeAnchorKind ?? null;
+}
+
+/** Current document-local selection, shared by UI actions and the control API. */
+export function activeSelectionIds(store: EditorShellStore): string[] {
+  return [...(activeDocumentAuthoring(store).selection?.get() ?? store.selectedEntityIds)];
+}
+
+/** Route selection through the active document's native adapter. */
+export function selectAuthoringNodes(store: EditorShellStore, ids: readonly string[]): void {
+  const adapter = activeDocumentAuthoring(store);
+  if (!setAuthoringSelection(adapter, ids)) store.selectMultiple([...ids]);
+}
+
+/** Select every node the active adapter's hierarchy exposes. */
+export function selectAllAuthoringNodes(store: EditorShellStore): void {
+  selectAuthoringNodes(
+    store,
+    activeHierarchyRows(store).map((row) => row.id),
+  );
+}
+
+/** Save through the active adapter's persistence provider (no-op when it has none). */
+export async function saveActiveAuthoring(store: EditorShellStore): Promise<void> {
+  await saveAuthoringDocument(getActiveAuthoring(store), 'the shell saved the active document');
+}

package/src/authoring/shell-object3d-document-write-policy.ts

@@ -0,0 +1,108 @@
+/**
+ * THE SHELL'S ANSWERS to `Object3DDocumentWritePolicy` — the composition the
+ * editor installs at boot (`EditorContext.tsx`'s `EditorProvider`).
+ *
+ * `openPersistence` and `replaceSource` are one-line delegations to the
+ * modules that already owned them. `saveThumbnailFraming` moved here WHOLE
+ * from `components/Object3DDocumentToolbar.tsx` (nothing about it changed) —
+ * merging `.vgai/thumbnails.json` is transport work end to end: read the
+ * project's manifest, refuse an unreadable one, write the merged bytes back
+ * through the project-file route.
+ *
+ * The point of the seam is only that the Asset Lab 3D document and its
+ * toolbar no longer import the server SDK barrel, the project file history,
+ * or the storage backend (ARCHITECTURE-CORE §Editor chrome, "the viewport
+ * stack is separable").
+ *
+ * This file is the shell side of that boundary and is free to import all of
+ * them.
+ */
+
+import {
+  loadProjectThumbnailManifest,
+  resetProjectThumbnailManifestCache,
+  THUMBNAIL_MANIFEST_PATH,
+  THUMBNAIL_PROFILE,
+} from '../asset-workflow/thumbnail-system';
+import { workspaceHistoryService } from '../components/workspace-history';
+import { projectFiles } from '../files/project-files';
+import { getProjectFileHistory } from '../history/project-file-history';
+import { getProjectResourceHistoryBackend } from '../history/project-root-history-backends';
+import { replaceProjectSource } from '../history/source-history-backend';
+import type {
+  Object3DDocumentThumbnailFraming,
+  Object3DDocumentWritePolicy,
+} from '../object3d-document-write-policy';
+import { sourceWriteBackendIfPrimed } from '../ui-source/tier-source-write-backend';
+import { openObject3DDocumentPersistence } from './object3d-document-persistence';
+
+async function persistThumbnailFraming(
+  assetPath: string,
+  framing: Object3DDocumentThumbnailFraming | undefined,
+): Promise<void> {
+  const read = await loadProjectThumbnailManifest();
+  // REFUSE rather than rebuild. `absent` and `unreadable` used to arrive as the
+  // same `null`, so a manifest that merely failed to parse was treated as "no
+  // manifest yet" and the write below replaced every framing entry in the
+  // project with `{}`.
+  if (read.status === 'unreadable') {
+    throw new Error(
+      `${THUMBNAIL_MANIFEST_PATH} is present but could not be read (${read.reason}). ` +
+        'Refusing to overwrite it — fix or delete the file, then try again.',
+    );
+  }
+  const manifest =
+    read.status === 'ok'
+      ? read.manifest
+      : {
+          version: 1 as const,
+          profile: THUMBNAIL_PROFILE.version,
+          generatedAt: new Date().toISOString(),
+          entries: {},
+        };
+  const key = assetPath.replace(/^\/+/, '');
+  const prior = manifest.entries[key] ?? {
+    state: 'fallback' as const,
+    profileVersion: THUMBNAIL_PROFILE.version,
+    issueCode: 'thumbnail.pending-regeneration',
+  };
+  const updated = {
+    ...manifest,
+    // Re-stamp the profile that produced this rewrite while KEEPING every
+    // existing entry; each entry's own `profileVersion` is what marks it stale.
+    profile: THUMBNAIL_PROFILE.version,
+    generatedAt: new Date().toISOString(),
+    entries: {
+      ...manifest.entries,
+      [key]: { ...prior, framing },
+    },
+  };
+  const content = `${JSON.stringify(updated, null, 2)}\n`;
+  const history = workspaceHistoryService();
+  const written = history
+    ? await getProjectFileHistory(
+        history,
+        getProjectResourceHistoryBackend(),
+        'project-resources',
+      ).write(THUMBNAIL_MANIFEST_PATH, content, {
+        label: `${framing ? 'Save' : 'Reset'} thumbnail framing ${assetPath}`,
+        kind: 'project-file',
+        contentType: 'application/json',
+      })
+    : await projectFiles.write(THUMBNAIL_MANIFEST_PATH, content).then(() => true);
+  if (written) resetProjectThumbnailManifestCache();
+}
+
+export const SHELL_OBJECT3D_DOCUMENT_WRITE_POLICY: Object3DDocumentWritePolicy = {
+  openPersistence: (options) => openObject3DDocumentPersistence(options),
+  replaceSource: async (history, request) => {
+    // The session's recorder, read per use rather than captured: it is
+    // confirmed once at boot and a caller that captured it earlier would hold
+    // `undefined` for the session (a human hit exactly that duplicating from
+    // the Asset Editor — runhuman pass 41).
+    const backend = sourceWriteBackendIfPrimed('The Asset Editor');
+    if (!backend) throw new Error('This editor tier cannot write project source.');
+    return replaceProjectSource(backend, history, request);
+  },
+  saveThumbnailFraming: persistThumbnailFraming,
+};

package/src/authoring/shell-viewport-policy.ts

@@ -0,0 +1,48 @@
+/**
+ * THE SHELL'S ANSWERS to `ViewportAuthoringPolicy` — the composition the
+ * editor installs at boot (`EditorContext.tsx`'s `EditorProvider`).
+ *
+ * Every member here is a one-line delegation to the module that already owned
+ * that answer. Nothing moved and nothing was reimplemented: the point of the
+ * seam is only that `editor-viewport.ts` no longer imports these modules, so
+ * the gizmo viewport does not carry the composite adapter, the workspace
+ * document registry, or the layered-pick walk in its own closure
+ * (ARCHITECTURE-CORE §Editor chrome, "the viewport stack is separable").
+ *
+ * This file is the shell side of that boundary and is free to import all of
+ * them.
+ */
+
+import type { ViewportAuthoringPolicy } from '../viewport-authoring-policy';
+import { getActiveAuthoring } from './active-adapter';
+import { CompositeAuthoringAdapter } from './composite-authoring-adapter';
+import { pickTopmost } from './layered-pick';
+import { resolvePanelAuthoring } from './panel-authoring';
+import { isViewportToolContextVisible, resolveViewportToolContext } from './viewport-tool-context';
+import {
+  applyRootHiddenVisibility,
+  isThreejsSurfaceVisible,
+  resolveThreeViewportRootId,
+  suppressRootEnvironment,
+} from './world-hidden-viewport';
+
+export const SHELL_VIEWPORT_AUTHORING_POLICY: ViewportAuthoringPolicy = {
+  activeAuthoring: (store) => getActiveAuthoring(store),
+  panelAuthoring: (store) => resolvePanelAuthoring(store).adapter,
+  pick: (store, clientX, clientY, intent) => pickTopmost(store, clientX, clientY, { intent }),
+  toolOwner: (adapter, selectedIds) => resolveViewportToolContext(adapter, selectedIds),
+  // Both halves of "is this owner painted here" — visibility says a three
+  // surface is drawn at all, selection ownership says it is the world being
+  // edited. The viewport ANDs the result with `kind === 'three'`, exactly as it
+  // did when it called these two itself.
+  toolOwnerPainted: (store, owner) =>
+    isThreejsSurfaceVisible(store) && isViewportToolContextVisible(store, owner),
+  threeSurfaceShowing: (store, adapter) =>
+    isThreejsSurfaceVisible(store) &&
+    (adapter instanceof CompositeAuthoringAdapter
+      ? adapter.childAdapters().some((child) => child.kind === 'three')
+      : !adapter.rects && typeof adapter.hierarchy.object3D === 'function'),
+  threeViewportRootId: (store) => resolveThreeViewportRootId(store),
+  applyRootHiddenVisibility,
+  suppressRootEnvironment,
+};