@volter/editor-core 0.5.57

package/server/worktree-retention.mjs

@@ -0,0 +1,205 @@
+// Task ownership lives beside Git's worktree metadata, outside disposable checkouts.
+import { execFileSync } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import {
+  existsSync,
+  linkSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+
+const git = (root, args) => execFileSync('git', ['-C', root, ...args], { encoding: 'utf8' }).trim();
+function canonical(target) {
+  const absolute = resolve(target);
+  return existsSync(absolute)
+    ? realpathSync(absolute)
+    : join(canonical(dirname(absolute)), basename(absolute));
+}
+function location(repo, target) {
+  const common = git(repo, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+  const path = canonical(target);
+  const id = createHash('sha256').update(path).digest('hex');
+  return { path, file: join(common, 'task-worktrees', `${id}.json`), id };
+}
+function write(file, record) {
+  const tmp = `${file}.${randomUUID()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(record, null, 2));
+  renameSync(tmp, file);
+}
+function locked(repo, target, action) {
+  const loc = location(repo, target);
+  mkdirSync(dirname(loc.file), { recursive: true });
+  // A crashed writer's lock is retained for explicit owner recovery, never stolen by age.
+  const lock = `${loc.file}.lock`;
+  mkdirSync(lock);
+  try {
+    return action(loc);
+  } finally {
+    rmSync(lock, { recursive: true });
+  }
+}
+function read(file) {
+  return existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : null;
+}
+function registered(repo, path) {
+  return git(repo, ['worktree', 'list', '--porcelain', '-z'])
+    .split('\0')
+    .includes(`worktree ${path}`);
+}
+function generationFile(repo, path) {
+  if (canonical(git(path, ['rev-parse', '--show-toplevel'])) !== path)
+    throw new Error('Path is not the registered worktree root.');
+  if (
+    git(repo, ['rev-parse', '--path-format=absolute', '--git-common-dir']) !==
+    git(path, ['rev-parse', '--path-format=absolute', '--git-common-dir'])
+  )
+    throw new Error('Worktree belongs to a different repository.');
+  return join(git(path, ['rev-parse', '--absolute-git-dir']), 'task-generation');
+}
+function markGeneration(repo, path, record) {
+  const file = generationFile(repo, path);
+  if (existsSync(file)) {
+    if (readFileSync(file, 'utf8') !== record.generation)
+      throw new Error('Worktree generation differs from creation intent.');
+  } else {
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    try {
+      writeFileSync(temporary, record.generation, { flag: 'wx' });
+      linkSync(temporary, file); // Exclusive publication of complete bytes only.
+    } finally {
+      rmSync(temporary, { force: true });
+    }
+  }
+}
+function verifyGeneration(repo, path, record) {
+  if (readFileSync(generationFile(repo, path), 'utf8') !== record.generation)
+    throw new Error('Worktree generation changed; old completion cannot remove it.');
+}
+function preserve(repo, ref, head) {
+  try {
+    git(repo, ['update-ref', ref, head, '']);
+  } catch (error) {
+    if (git(repo, ['rev-parse', '--verify', ref]) !== head) throw error;
+  }
+}
+export function registerTaskWorktree(repo, target, owner, branch) {
+  if (!owner?.trim()) throw new Error('A task owner is required.');
+  locked(repo, target, ({ path, file }) => {
+    if (existsSync(path) || registered(repo, path))
+      throw new Error(`Worktree destination already exists: ${path}`);
+    const previous = read(file);
+    if (previous && previous.state !== 'finished')
+      throw new Error(
+        'An earlier task still owns this path; inspect its retained creation/removal receipt.',
+      );
+    write(file, {
+      version: 1,
+      generation: randomUUID(),
+      root: path,
+      owner,
+      branch,
+      createdAt: new Date().toISOString(),
+      state: 'creating',
+    });
+  });
+}
+export function markTaskWorktreeCreated(repo, target) {
+  locked(repo, target, ({ path, file }) => {
+    const record = read(file);
+    if (record?.state !== 'creating' || !registered(repo, path))
+      throw new Error('No matching worktree creation intent.');
+    markGeneration(repo, path, record);
+    write(file, { ...record, state: 'active' });
+  });
+}
+function removePreserved(repo, path, file, record) {
+  if (!existsSync(path)) {
+    if (registered(repo, path))
+      throw new Error('Checkout is missing but Git still registers it; inspect before recovering.');
+  } else {
+    verifyGeneration(repo, path, record);
+    if (git(path, ['status', '--porcelain']) !== '')
+      throw new Error('Worktree has uncommitted or untracked work.');
+    if (git(path, ['rev-parse', 'HEAD']) !== record.preservedCommit)
+      throw new Error('HEAD changed after completion; retain this worktree for review.');
+    git(repo, ['worktree', 'remove', path]);
+  }
+  write(file, { ...record, state: 'finished', finishedAt: new Date().toISOString() });
+}
+export function finishTaskWorktree(
+  repo,
+  target,
+  { owner, mergedInto, consumersRetired = false } = {},
+) {
+  locked(repo, target, ({ path, file, id }) => {
+    if (path === canonical(git(repo, ['rev-parse', '--show-toplevel'])))
+      throw new Error('Run finish from another checkout.');
+    if (!consumersRetired)
+      throw new Error('Retire the task’s editor, terminals and other consumers before finishing.');
+    const record = read(file);
+    if (record?.root !== path || record.owner !== owner)
+      throw new Error('This worktree belongs to a different task or is unregistered.');
+    if (record.state === 'finished' && !existsSync(path) && !registered(repo, path)) return;
+    if (record.state === 'removing') return removePreserved(repo, path, file, record);
+    if (record.state !== 'active')
+      throw new Error('Worktree creation did not finish; inspect the retained intent.');
+    if (!mergedInto)
+      throw new Error(
+        'Specify the ref that preserves the completed task (--merged-into origin/main).',
+      );
+    verifyGeneration(repo, path, record);
+    if (git(path, ['status', '--porcelain']) !== '')
+      throw new Error('Worktree has uncommitted or untracked work.');
+    const head = git(path, ['rev-parse', 'HEAD']);
+    const preserved = git(repo, ['rev-parse', '--verify', `${mergedInto}^{commit}`]);
+    git(repo, ['merge-base', '--is-ancestor', head, preserved]);
+    const ref = `refs/task-worktrees/${id}/${record.generation}`;
+    preserve(repo, ref, head);
+    const removing = {
+      ...record,
+      state: 'removing',
+      preservedRef: ref,
+      preservedCommit: head,
+      mergedInto: preserved,
+      consumersRetiredAt: new Date().toISOString(),
+    };
+    write(file, removing);
+    removePreserved(repo, path, file, removing);
+  });
+}
+export function removeArchivedWorktree(repo, target) {
+  locked(repo, target, ({ path, file, id }) => {
+    // The existing explicit archive caller checks current tree, live sessions and dirtiness.
+    const previous = read(file);
+    if (previous && !['active', 'removing', 'adopting'].includes(previous.state))
+      throw new Error('Task creation or an older generation needs review before archive.');
+    const record = previous ?? {
+      version: 1,
+      generation: randomUUID(),
+      root: path,
+      owner: 'explicit-archive',
+      state: 'adopting',
+    };
+    if (!previous) write(file, record);
+    if (record.state === 'adopting') markGeneration(repo, path, record);
+    verifyGeneration(repo, path, record);
+    if (record.state === 'removing') return removePreserved(repo, path, file, record);
+    const head = git(path, ['rev-parse', 'HEAD']);
+    const ref = `refs/task-worktrees/${id}/${record.generation}`;
+    preserve(repo, ref, head);
+    const removing = {
+      ...record,
+      state: 'removing',
+      preservedRef: ref,
+      preservedCommit: head,
+      consumersRetiredAt: new Date().toISOString(),
+    };
+    write(file, removing);
+    removePreserved(repo, path, file, removing);
+  });
+}

package/src/EditorContext.tsx

@@ -0,0 +1,169 @@
+import { type ReactNode, useEffect, useRef } from 'react';
+import { SHELL_OBJECT3D_DOCUMENT_WRITE_POLICY } from './authoring/shell-object3d-document-write-policy';
+import { SHELL_VIEWPORT_AUTHORING_POLICY } from './authoring/shell-viewport-policy';
+
+import { connectCommandListener } from './command-listener';
+import { startSceneDocuments } from './components/scene-documents';
+import { saveThumbnail } from './editor-api';
+import { reportTabCensus } from './editor-presence';
+import { EditorRuntimeProvider, type EditorStats } from './editor-runtime';
+import { EditorShellStore, type EditorStatePersistence } from './editor-shell-store';
+import { EditorSession } from './history/editor-session';
+import { bootstrapProject } from './initial-project';
+import { installObject3DDocumentWritePolicy } from './object3d-document-write-policy';
+import { startProjectAdapterLoad } from './project-adapter';
+import { startProjectDeclarationRefresh } from './project-declaration-refresh';
+import { writeProjectLocalSection } from './project-local-state';
+import { getCurrentProject } from './project-manager';
+import { startProjectSessionReset } from './project-session-reset';
+import { startProjectToolContributionDiscovery } from './project-tool-discovery';
+import { startProjectToolCatalog } from './project-tools';
+import { registerShellStoreForHost } from './shell-store-door';
+import { startTabCensus } from './tab-census';
+import { installViewportAuthoringPolicy } from './viewport-authoring-policy';
+
+/**
+ * The store's persistence collaborator, bound to the server SDK. ONE module
+ * constant, not an object literal at the install site: `attachStatePersistence`
+ * keeps the one-owner rule `attachHistory` keeps, so a fresh literal on every
+ * render (a strict-mode double render, any re-render of the provider) was a
+ * different owner and threw — measured 2026-09-02 as "EditorStore is already
+ * attached to a state persistence" from `<EditorProvider>` on every editor boot.
+ */
+const SERVER_STATE_PERSISTENCE: EditorStatePersistence = hmrStableValue(
+  'SERVER_STATE_PERSISTENCE',
+  () => ({ save: (state) => writeProjectLocalSection('view', state), saveThumbnail }),
+);
+
+/**
+ * The same object across a Fast Refresh of THIS module. The store lives in a
+ * ref, which Fast Refresh preserves, but a module-scope constant is minted
+ * again on every re-evaluation — so the second render after an HMR edit
+ * handed the store a NEW persistence object and `attachStatePersistence`'s
+ * one-owner rule threw (measured 2026-09-03, editing a sibling module in
+ * this file's graph while the editor was open: every panel went dark). The
+ * context itself already rides `import.meta.hot.data` for exactly this
+ * reason (`createHmrStableReactContext`); the collaborator does the same.
+ */
+function hmrStableValue<T>(key: string, create: () => T): T {
+  const data = import.meta.hot?.data as Record<string, T> | undefined;
+  if (data?.[key]) return data[key] as T;
+  const value = create();
+  if (data) data[key] = value;
+  return value;
+}
+
+export function EditorProvider({ children }: { children: ReactNode }) {
+  const storeRef = useRef<EditorShellStore | null>(null);
+  if (!storeRef.current) {
+    storeRef.current = new EditorShellStore();
+    // The host door (`@volter/editor-sdk/host`, `session`) reads this store.
+    registerShellStoreForHost(storeRef.current);
+  }
+
+  const sessionRef = useRef<EditorSession | null>(null);
+  if (!sessionRef.current) {
+    const project = getCurrentProject();
+    sessionRef.current = new EditorSession(project?.rootPath ?? 'unknown-project');
+  }
+  storeRef.current.attachHistory(sessionRef.current.history);
+  // The shell's answers to the gizmo viewport's questions — which adapter is
+  // active, what is under the pointer, which root is world-hidden. Installed
+  // HERE (boot, before any viewport mounts) rather than in `the world root's stage`,
+  // because an Asset Lab document's own viewport can be the only one on
+  // screen; see `viewport-authoring-policy.ts`. Idempotent for the same
+  // policy object, so a strict-mode double render is a no-op.
+  installViewportAuthoringPolicy(SHELL_VIEWPORT_AUTHORING_POLICY);
+  // The shell's answers to the Asset Lab 3D document's writes — its own
+  // persistence binding, whole-file source replacement, thumbnail framing.
+  // Installed HERE for the same reason as the policy above: an Asset Lab
+  // document can be the only surface on screen, and its writes must reach the
+  // project the moment it mounts. See `object3d-document-write-policy.ts`.
+  installObject3DDocumentWritePolicy(SHELL_OBJECT3D_DOCUMENT_WRITE_POLICY);
+  // The shell binds the server SDK as the store's persistence; the store
+  // itself imports no transport (ARCHITECTURE-CORE §Editor chrome).
+  storeRef.current.attachStatePersistence(SERVER_STATE_PERSISTENCE);
+
+  const statsRef = useRef<EditorStats | null>(null);
+  if (!statsRef.current) {
+    statsRef.current = {
+      fps: 0,
+      frameTime: 0,
+      drawCalls: 0,
+      triangles: 0,
+      cameraPosition: { x: 0, y: 0, z: 0 },
+      cameraTarget: { x: 0, y: 0, z: 0 },
+    };
+  }
+
+  const initRef = useRef<Promise<void> | null>(null);
+  if (!initRef.current) {
+    // Detect the project AND run its script registry. Tracked by
+    // `projectBootstrapSettled()`, which play-mode awaits — see that function's
+    // doc comment for the defect this ordering exists to prevent.
+    initRef.current = bootstrapProject();
+  }
+
+  useEffect(() => {
+    return connectCommandListener(storeRef.current!, sessionRef.current!.historyCommands);
+  }, []);
+
+  // Project-tool discovery is EDITOR-INIT lifecycle, not a side effect of any
+  // one surface — it runs (and keeps re-running on project change / tool-file
+  // add/unlink) whether or not a workspace is mounted.
+  // The workspace host only consumes the discovered registrations.
+  useEffect(() => startProjectToolContributionDiscovery(), []);
+  useEffect(() => startProjectToolCatalog(), []);
+
+  // The project's own adapter (`vgai.adapter.ts`, or the declared native
+  // default when it has none) — a PROJECT capability, loaded at init and on
+  // every project switch, exactly like the discoveries above.
+  useEffect(() => startProjectAdapterLoad(), []);
+  useEffect(() => startProjectDeclarationRefresh(), []);
+
+  // The other half of that lifecycle: what must NOT survive a project switch.
+  // `onProjectChange` re-derives against the new project; this ends the
+  // PREVIOUS one's live sessions and measurement ledgers, which are module
+  // state and do not go away with the layout remount. See
+  // `project-session-reset.ts` for the list.
+  useEffect(() => startProjectSessionReset(), []);
+
+  // The scene table's EDIT client: every authorable scene the adapter declares
+  // becomes a workspace document, the default open by default
+  // (`components/scene-documents.tsx`). Bound beside the load above because it
+  // consumes exactly what that publishes and nothing else.
+  useEffect(() => startSceneDocuments(storeRef.current!), []);
+
+  // The tab's RESOURCE CENSUS (tab-census.ts) — a 0.2 Hz sample that rides the
+  // heartbeat, so a browser-level renderer death has a cause line instead of a
+  // bare 1006. Editor-init lifecycle for the same reason as the discoveries
+  // above: it must run whether or not any panel that reads it is mounted.
+  useEffect(() => startTabCensus({ report: reportTabCensus }), []);
+
+  const sessionMounted = useRef(false);
+  useEffect(() => {
+    sessionMounted.current = true;
+    const session = sessionRef.current!;
+    return () => {
+      sessionMounted.current = false;
+      // Fast Refresh replays effects while preserving the store and session.
+      // Dispose only if the provider remains unmounted after that replay.
+      queueMicrotask(() => {
+        if (!sessionMounted.current) session.dispose();
+      });
+    };
+  }, []);
+
+  return (
+    <EditorRuntimeProvider
+      runtime={{
+        store: storeRef.current,
+        stats: statsRef.current,
+        initPromise: initRef.current!,
+        session: sessionRef.current,
+      }}
+    >
+      {children}
+    </EditorRuntimeProvider>
+  );
+}