@volter/editor-core 0.5.57

package/server/routes/configurations.ts

@@ -0,0 +1,419 @@
+/**
+ * `/__editor/configurations` — the RUNNER for a project's declared run configurations
+ * (ARCHITECTURE-CORE §The project model: the `run[]` axis). The manifest
+ * declares an entrypoint by registered kind; this is the host that starts
+ * and stops the `process` kind beside the editor and reports it, and
+ * expands a `compound` into its members (`play` is the browser's own mount,
+ * never started here). The editor's transport, `vgai run <id>` and a
+ * harness all come through this one door, so a process started by any of
+ * them is the same process, listed the same way, and dies with the session.
+ *
+ *   GET  /__editor/configurations                 → { configurations: [{ id, kind, status, pid?, port?, entry? }] }
+ *   POST /__editor/configurations/:id/start       → { ok, started: [id…], attached: [id…], ready }
+ *   POST /__editor/configurations/:id/stop        → { ok, stopped: [id…] }
+ *   GET  /__editor/configurations/:id/log         → { lines }
+ *
+ * A port already answering before a start is ATTACHED, not fought over: the
+ * caller wanted "a server on that port", and one is there. A port nothing
+ * answers on after the readiness timeout is reported as not ready, with the
+ * process's own last lines, never as success.
+ */
+
+import { type ChildProcess, spawn } from 'node:child_process';
+import net from 'node:net';
+import { join } from 'node:path';
+import type { Request, Response } from 'express';
+import type { DeclaredConfiguration } from '@volter/editor-project/manifest/configuration-kinds';
+import {
+  configurationKind,
+  PLAY_CONFIGURATION_ID,
+} from '@volter/editor-project/manifest/configuration-kinds';
+import { loadGameManifestDir } from '@volter/editor-project/manifest/load-file';
+import { nodeRuntimeIssue } from '@volter/editor-project/manifest/runtime-environment';
+import type { EditorServerRouter } from '../editor-server';
+import { packageProjectWebBuild } from '../project-build-artifact';
+import { ensureProjectConfigurationKinds, kindModuleLoader } from '../project-kinds';
+import { executeProjectTool } from '../project-tools';
+import type { RouteContext } from './context';
+
+const READY_TIMEOUT_MS = 30_000;
+const READY_POLL_MS = 300;
+const LOG_LINES = 200;
+
+interface RunningProcess {
+  readonly id: string;
+  readonly child: ChildProcess;
+  readonly port: number | null;
+  readonly log: string[];
+  startedAt: number;
+}
+
+const running = new Map<string, RunningProcess>();
+
+function portAnswers(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = net.connect({ host: '127.0.0.1', port });
+    const done = (value: boolean) => {
+      socket.destroy();
+      resolve(value);
+    };
+    socket.once('connect', () => done(true));
+    socket.once('error', () => done(false));
+    socket.setTimeout(500, () => done(false));
+  });
+}
+
+async function httpAnswers(port: number, path: string): Promise<boolean> {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}${path}`);
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+async function waitReady(port: number | null, http: string | undefined): Promise<boolean> {
+  if (port === null) return true;
+  const deadline = Date.now() + READY_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    const up = http ? await httpAnswers(port, http) : await portAnswers(port);
+    if (up) return true;
+    await new Promise((r) => setTimeout(r, READY_POLL_MS));
+  }
+  return false;
+}
+
+function pushLog(entry: RunningProcess, chunk: string): void {
+  for (const line of chunk.split(/\r?\n/)) {
+    if (!line) continue;
+    entry.log.push(line);
+    if (entry.log.length > LOG_LINES) entry.log.splice(0, entry.log.length - LOG_LINES);
+  }
+}
+
+async function declaredRun(ctx: RouteContext): Promise<readonly DeclaredConfiguration[]> {
+  const kindErrors = await ensureProjectConfigurationKinds(ctx.projectRoot);
+  if (kindErrors.length > 0) throw new Error(kindErrors.join('\n'));
+  return loadGameManifestDir(ctx.projectRoot).configurations;
+}
+
+function processFields(configuration: DeclaredConfiguration): {
+  entry: string;
+  command: string | undefined;
+  port: number | null;
+  cwd: string | undefined;
+  env: Record<string, string> | undefined;
+  http: string | undefined;
+} {
+  return {
+    entry: configuration['entry'] as string,
+    command: configuration['command'] as string | undefined,
+    port: typeof configuration['port'] === 'number' ? (configuration['port'] as number) : null,
+    cwd: configuration['cwd'] as string | undefined,
+    env: configuration['env'] as Record<string, string> | undefined,
+    http: (configuration['ready'] as { http?: string } | undefined)?.http,
+  };
+}
+
+async function startProcess(
+  ctx: RouteContext,
+  configuration: DeclaredConfiguration,
+): Promise<{ started: boolean; attached: boolean; ready: boolean; log: string[] }> {
+  const live = running.get(configuration.id);
+  if (live && live.child.exitCode === null) {
+    return { started: false, attached: true, ready: true, log: [...live.log] };
+  }
+  const fields = processFields(configuration);
+  if (fields.port !== null && (await portAnswers(fields.port))) {
+    // Something already serves the port. Attach: the caller asked for a
+    // server there, and one is there — a foreign one is still one.
+    return { started: false, attached: true, ready: true, log: [] };
+  }
+  const isWin = process.platform === 'win32';
+  const cwd = fields.cwd ? join(ctx.projectRoot, fields.cwd) : ctx.projectRoot;
+  const command = fields.command ?? `npx tsx ${fields.entry}`;
+  const child = spawn(command, {
+    cwd,
+    env: { ...process.env, ...(fields.env ?? {}) },
+    shell: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    detached: !isWin,
+  });
+  const entry: RunningProcess = {
+    id: configuration.id,
+    child,
+    port: fields.port,
+    log: [],
+    startedAt: Date.now(),
+  };
+  child.stdout?.on('data', (d: Buffer) => pushLog(entry, d.toString('utf8')));
+  child.stderr?.on('data', (d: Buffer) => pushLog(entry, d.toString('utf8')));
+  child.once('exit', (code, signal) => {
+    pushLog(entry, `[exited: code ${code ?? 'null'}${signal ? `, signal ${signal}` : ''}]`);
+  });
+  running.set(configuration.id, entry);
+  const ready = await waitReady(fields.port, fields.http);
+  return { started: true, attached: false, ready, log: [...entry.log] };
+}
+
+function stopProcess(id: string): boolean {
+  const live = running.get(id);
+  if (!live) return false;
+  running.delete(id);
+  if (live.child.exitCode !== null) return false;
+  const pid = live.child.pid;
+  try {
+    if (process.platform !== 'win32' && pid !== undefined) process.kill(-pid, 'SIGTERM');
+    else live.child.kill('SIGTERM');
+  } catch {
+    // already gone
+  }
+  return true;
+}
+
+/** Kill every process this runner started — the session is ending. */
+export function stopAllConfigurations(): void {
+  for (const id of [...running.keys()]) stopProcess(id);
+}
+
+function membersOf(
+  configuration: DeclaredConfiguration,
+  all: readonly DeclaredConfiguration[],
+): DeclaredConfiguration[] {
+  if (configuration.kind !== 'compound') return [configuration];
+  const ids = (configuration['run'] as readonly string[]) ?? [];
+  return ids
+    .filter((id) => id !== PLAY_CONFIGURATION_ID)
+    .flatMap((id) => {
+      const member = all.find((c) => c.id === id);
+      return member ? membersOf(member, all) : [];
+    });
+}
+
+export function registerConfigurationRoutes(router: EditorServerRouter, ctx: RouteContext): void {
+  router.get('/__editor/configurations', async (_req: Request, res: Response) => {
+    let declared: readonly DeclaredConfiguration[];
+    try {
+      declared = await declaredRun(ctx);
+    } catch (error) {
+      res.status(400).json({ error: error instanceof Error ? error.message : String(error) });
+      return;
+    }
+    res.json({
+      configurations: declared.map((configuration) => {
+        const live = running.get(configuration.id);
+        const alive = live !== undefined && live.child.exitCode === null;
+        return {
+          id: configuration.id,
+          kind: configuration.kind,
+          role: configurationKind(configuration.kind)?.role ?? null,
+          describe: configurationKind(configuration.kind)?.describe ?? null,
+          status: alive ? 'running' : 'stopped',
+          ...(alive ? { pid: live.child.pid, since: live.startedAt } : {}),
+          ...(configuration.kind === 'process'
+            ? { entry: configuration['entry'], port: configuration['port'] ?? null }
+            : {}),
+          ...(configuration.kind === 'compound'
+            ? { run: configuration['run'], instances: configuration['instances'] ?? null }
+            : {}),
+        };
+      }),
+    });
+  });
+
+  router.post('/__editor/configurations/:id/start', async (req: Request, res: Response) => {
+    const id = String(req.params['id']);
+    let declared: readonly DeclaredConfiguration[];
+    try {
+      declared = await declaredRun(ctx);
+    } catch (error) {
+      res.status(400).json({ error: error instanceof Error ? error.message : String(error) });
+      return;
+    }
+    const configuration = declared.find((c) => c.id === id);
+    if (!configuration) {
+      res.status(404).json({
+        error: `No run configuration "${id}" — declared: ${declared.map((c) => `"${c.id}"`).join(', ') || 'none'}`,
+      });
+      return;
+    }
+    const members = membersOf(configuration, declared);
+    const unrunnable = members.filter((m) => m.kind !== 'process');
+    if (unrunnable.length > 0) {
+      res.status(400).json({
+        error: `No runner for kind ${unrunnable.map((m) => `"${m.kind}"`).join(', ')} — this host starts "process" (and "compound" of them)`,
+      });
+      return;
+    }
+    // The runtime a process needs is package.json `engines.node`, declared
+    // once and read here (ARCHITECTURE-CORE §The project model, environment).
+    const runtimeIssue = nodeRuntimeIssue(ctx.projectRoot);
+    if (runtimeIssue) {
+      res.status(400).json({ error: `Configuration "${id}" cannot start: ${runtimeIssue}` });
+      return;
+    }
+    const started: string[] = [];
+    const attached: string[] = [];
+    let ready = true;
+    const logs: Record<string, string[]> = {};
+    for (const member of members) {
+      const outcome = await startProcess(ctx, member);
+      if (outcome.started) started.push(member.id);
+      if (outcome.attached) attached.push(member.id);
+      if (!outcome.ready) ready = false;
+      logs[member.id] = outcome.log;
+    }
+    res.json({ ok: ready, started, attached, ready, logs });
+  });
+
+  // ---- build-role configurations: run to completion, stream the log, package
+  let activeBuild: ChildProcess | null = null;
+  let packaging = false;
+  router.post('/__editor/configurations/:id/build', async (req: Request, res: Response) => {
+    const id = String(req.params['id']);
+    if (activeBuild || packaging) {
+      res.status(409).json({ error: 'A build is already running.' });
+      return;
+    }
+    let declared: readonly DeclaredConfiguration[];
+    try {
+      declared = await declaredRun(ctx);
+    } catch (error) {
+      res.status(400).json({ error: error instanceof Error ? error.message : String(error) });
+      return;
+    }
+    const configuration = declared.find((c) => c.id === id);
+    if (!configuration) {
+      res.status(404).json({
+        error: `No configuration "${id}" — declared: ${declared.map((c) => `"${c.id}"`).join(', ') || 'none'}`,
+      });
+      return;
+    }
+    const kind = configurationKind(configuration.kind);
+    if (kind?.role !== 'build') {
+      res.status(400).json({
+        error: `Configuration "${id}" is ${kind ? `a ${kind.role}-role ${configuration.kind}` : 'of an unregistered kind'} — build starts a build-role configuration`,
+      });
+      return;
+    }
+    if (configuration.kind !== 'bundle') {
+      // A contributed build kind runs as the project TOOL it names.
+      const bridge = kind.build;
+      if (!bridge) {
+        res.status(400).json({
+          error: `No runner for build kind "${configuration.kind}" — this host builds "bundle" and any kind whose contribution names a tool`,
+        });
+        return;
+      }
+      res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        Connection: 'keep-alive',
+      });
+      res.write(':ok\n\n');
+      const say = (line: string) => res.write(`event: log\ndata: ${JSON.stringify(line)}\n\n`);
+      say(`Running tool ${bridge.tool} for configuration "${id}"…`);
+      try {
+        const outcome = await executeProjectTool({
+          account: ctx.account,
+          projectRoot: ctx.projectRoot,
+          loadModule: kindModuleLoader() ?? undefined,
+          name: bridge.tool,
+          input: bridge.input(configuration),
+          confirmed: true,
+        });
+        const ok = outcome.status === 200 && (outcome.body as { ok?: boolean }).ok !== false;
+        if (!ok) {
+          const detail = (outcome.body as { error?: { message?: string } }).error?.message;
+          say(`Tool refused: ${detail ?? JSON.stringify(outcome.body).slice(0, 300)}`);
+        }
+        res.write(
+          `event: done\ndata: ${JSON.stringify({ ok, code: ok ? 0 : 1, report: ok ? outcome.body : undefined })}\n\n`,
+        );
+      } catch (error) {
+        say(`Error: ${error instanceof Error ? error.message : String(error)}`);
+        res.write(`event: done\ndata: ${JSON.stringify({ ok: false, code: null })}\n\n`);
+      } finally {
+        res.end();
+      }
+      return;
+    }
+    const script = (configuration['script'] as string | undefined) ?? 'build';
+    const args = (configuration['args'] as readonly string[] | undefined) ?? [];
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive',
+    });
+    res.write(':ok\n\n');
+    const child = spawn('npm', ['run', script, ...(args.length > 0 ? ['--', ...args] : [])], {
+      cwd: ctx.projectRoot,
+      // The editor runs in development mode. A bundled artifact must compile
+      // production branches, including the exported-game boundary.
+      env: { ...process.env, NODE_ENV: 'production' },
+      shell: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    activeBuild = child;
+    const sendLine = (line: string) => {
+      res.write(`event: log\ndata: ${JSON.stringify(line)}\n\n`);
+    };
+    let buffer = '';
+    const flushLines = (chunk: Buffer) => {
+      buffer += chunk.toString('utf-8');
+      const lines = buffer.split('\n');
+      buffer = lines.pop() ?? '';
+      for (const line of lines) sendLine(line);
+    };
+    child.stdout?.on('data', flushLines);
+    child.stderr?.on('data', flushLines);
+    child.on('close', async (code) => {
+      if (buffer) sendLine(buffer);
+      buffer = '';
+      activeBuild = null;
+      if (code !== 0) {
+        res.write(`event: done\ndata: ${JSON.stringify({ ok: false, code })}\n\n`);
+        res.end();
+        return;
+      }
+      packaging = true;
+      try {
+        const report = await packageProjectWebBuild(ctx.projectRoot);
+        sendLine(
+          `Packaged ${report.fileCount} files (${report.outputBytes} bytes) as ` +
+            `${report.artifact} (${report.artifactBytes} bytes).`,
+        );
+        res.write(`event: done\ndata: ${JSON.stringify({ ok: true, code, report })}\n\n`);
+      } catch (error) {
+        sendLine(`Error: ${(error as Error).message}`);
+        res.write(`event: done\ndata: ${JSON.stringify({ ok: false, code: null })}\n\n`);
+      } finally {
+        packaging = false;
+        res.end();
+      }
+    });
+    req.on('close', () => {
+      if (activeBuild === child && child.exitCode === null) child.kill();
+    });
+  });
+
+  router.post('/__editor/configurations/:id/stop', async (req: Request, res: Response) => {
+    const id = String(req.params['id']);
+    let declared: readonly DeclaredConfiguration[] = [];
+    try {
+      declared = await declaredRun(ctx);
+    } catch {
+      // a manifest that no longer parses still lets a running child be stopped by id
+    }
+    const configuration = declared.find((c) => c.id === id);
+    const targets = configuration ? membersOf(configuration, declared).map((m) => m.id) : [id];
+    const stopped = targets.filter((t) => stopProcess(t));
+    res.json({ ok: true, stopped });
+  });
+
+  router.get('/__editor/configurations/:id/log', (req: Request, res: Response) => {
+    const id = String(req.params['id']);
+    const live = running.get(id);
+    res.json({ lines: live ? [...live.log] : [] });
+  });
+}

package/server/routes/context.ts

@@ -0,0 +1,264 @@
+/**
+ * `RouteContext` — the editor server's closure, named once.
+ *
+ * `createEditorServer` used to be a single ~7,700-line function body: every
+ * route handler was a closure over the same pile of `const`/`let` bindings, so
+ * the only way to know what a route touched was to read the whole file. The
+ * split moves route bodies OUT, into `register<Family>Routes(router, ctx)`
+ * modules, and this interface is what crosses that boundary: the same
+ * bindings, materialized once, in one place a reader can enumerate.
+ *
+ * Two rules keep it honest:
+ *
+ *  - **Immutable bindings are plain properties.** A family module destructures
+ *    them (`const { account } = ctx`), which is why the moved route bodies are
+ *    otherwise byte-for-byte what they were.
+ *  - **Mutable session state is a getter/setter pair**, and a route reads it as
+ *    `ctx.projectRoot`. Destructuring a `let` would copy it, and the copy would
+ *    silently go stale the moment the project changed — the one failure this
+ *    boundary could plausibly introduce, so it is made unrepresentable.
+ */
+
+import type {
+  CollaborationParticipantLocation,
+  CollaborationRole,
+  SourceRevision,
+} from '@volter/editor-sdk/session/collaboration-types';
+import type { EditorServerCompatibility } from '@volter/editor-sdk/session/editor-compatibility';
+import type { Request, Response } from 'express';
+import type { TripwireGate } from '../support/project/build-discipline';
+import type {
+  SessionJournal,
+  SessionJournalEvent,
+} from '../support/project/session-journal';
+import type { ProjectComponentEntry } from '../../src/asset-workflow/project-content';
+import type { HarnessChatSnapshot } from '../../src/harness-chat-types';
+import type { EditorAccountService } from '../account-service';
+import type { CollaborationSession } from '../collaboration-session';
+import type { ConsoleLedger } from '../console-ledger';
+import type { EditorServerOptions } from '../editor-server';
+import type { EngineProvenance } from '../engine-provenance';
+import type { HarnessChatService } from '../harness-chat-service';
+import type { PlayPhaseRecord } from '../play-stall';
+import type { ProjectModuleLoader } from '../project-tools';
+import type { ProjectWorkCoordinator } from '../project-work-coordinator';
+import type { ShareGatewayClaims } from '../share-claims';
+import type { ShareHost } from '../share-host';
+import type { TabHeartbeatServer } from '../tab-heartbeat';
+import type { TabLifecycleController } from '../tab-lifecycle';
+import type { TeamAgentMirror } from '../team-agent-mirror';
+import type { WorktreeIdentity } from '../worktree-identity';
+
+/**
+ * The three fields share-claim verification actually reads. Structural so a
+ * raw WebSocket upgrade request can be checked by the same function an Express
+ * `Request` is.
+ */
+export interface ShareClaimSource {
+  readonly method: string;
+  readonly originalUrl: string;
+  header(name: string): string | undefined;
+}
+
+/** A verified share claim, as the routes read it. */
+export interface TrustedShareIdentity extends Omit<ShareGatewayClaims, 'role'> {
+  role: CollaborationRole;
+}
+
+/**
+ * What a control message answers with. A tab reports four facts upstream — it
+ * picked a command up, the command finished, its state snapshot, which surface
+ * it is showing — over its control socket OR as a POST, and both land on the
+ * same handler so the two transports cannot answer differently.
+ */
+export type ControlOutcome = { status: 200 } | { status: 400 | 403 | 409; error: string };
+
+/** Whether the `<project>/src` validation watcher is running, and why not. */
+export type SourceValidationState = 'active' | 'awaiting-src' | 'no-project';
+
+export interface RouteContext {
+  // ---- Roots ------------------------------------------------------------
+  /** The engine checkout serving this editor. Also the "no project" sentinel. */
+  readonly engineRoot: string;
+  /** Where the shared scaffolder reads templates and capabilities from. */
+  /** The open project, or `engineRoot` when none is open. Reassigned by open. */
+  projectRoot: string;
+  /** `<projectRoot>/public` — the served asset root. Follows `projectRoot`. */
+  publicRoot: string;
+
+  // ---- Project mutation (the ONE write path for project-owned files) ----
+  /**
+   * Write a set of project resources as one attributed, conflict-checked
+   * transaction, returning the collaboration revision it produced (or `null`
+   * when no session is recording). Every family that writes the project's own
+   * files goes through this — there is no second write path.
+   */
+  readonly commitProjectMutation: (
+    req: Request,
+    resources: readonly { path: string; content: string | Buffer | null }[],
+  ) => Promise<SourceRevision | null | undefined>;
+  /** The matching error answer, including the structured conflict shape. */
+  readonly projectMutationError: (res: Response, error: unknown) => void;
+  /**
+   * Live conflict tickets: a 409 hands the client an id, and the client's
+   * resolve call redeems it. Written by `projectMutationError`, read by the
+   * source-conflict routes.
+   */
+  readonly sourceConflictTickets: Map<string, { paths: Set<string>; expiresAt: number }>;
+  /** The open project's parsed manifest, or `null` when it cannot be read. */
+  readonly readProjectManifest: () => unknown;
+
+  // ---- Loading the project's own modules on the Node side ---------------
+  readonly loadProjectModule: ProjectModuleLoader | undefined;
+
+  // ---- Global account (never project state) -----------------------------
+  readonly account: EditorAccountService;
+
+  /** The project's component index (cached, invalidated by the src watcher). */
+  readonly currentProjectComponents: () => Promise<ProjectComponentEntry[]>;
+
+  /** WHICH engine source this server is running, resolved once at boot. */
+  readonly enginePromise: Promise<EngineProvenance>;
+
+  // ---- Session identity -------------------------------------------------
+  /** This process's registered session, as other editors and the CLI see it. */
+  readonly currentSessionIdentity: () => WorktreeIdentity | null;
+
+  // ---- Owner-local authority --------------------------------------------
+  /**
+   * Loopback AND not carrying a share-gateway claim — i.e. the person who
+   * launched this editor, not one of their session's guests.
+   */
+  readonly localOwnerRequest: (req: Request) => boolean;
+  /** `localOwnerRequest`, having already answered 403 when it is false. */
+  readonly requireLocalOwner: (req: Request, res: Response) => boolean;
+
+  // ---- Opening a project (the runtime switch) ---------------------------
+  /** Where the launcher's user-global settings live. */
+  readonly launcherSettingsPath: string;
+  /** Where the recent-projects list lives. */
+  readonly recentProjectsPath: string;
+  /** Record a visit, unless this session is not somebody's launcher. */
+  readonly recordRecentProject: (name: string, projectDir: string) => Promise<void>;
+  /** (Re)start the project file watchers for whatever `projectRoot` now is. */
+  readonly startWatcher: () => void;
+  /** Re-poll generation jobs for the open project. */
+  readonly reconcileGenerations: () => Promise<void>;
+  /** This server's editor/project compatibility identity. */
+  readonly compatibilityIdentity: () => EditorServerCompatibility;
+  /** When this server started serving THIS project. Reset by a switch. */
+  servingProjectSince: number;
+  /** The project-local session journal, reopened on a switch. */
+  journal: SessionJournal | null;
+  /** The two build-discipline gates, reset to idle on a switch. */
+  cadenceGate: TripwireGate;
+  unplayedGate: TripwireGate;
+
+  // ---- The live session's own vitals -----------------------------------
+  /** The unresolved error/warning ledger every `vgai` command reprints. */
+  readonly consoleLedger: ConsoleLedger;
+  /** Per-file validation state, as the watchers computed it. */
+  readonly projectValidation: Map<string, { errors: string[]; at: number }>;
+  readonly projectWarnings: Map<string, { warnings: string[]; at: number }>;
+  /** The same validation state, pre-formatted as replayable `server-log`s. */
+  readonly currentValidationLogEntries: () => { level: 'error' | 'warn'; message: string }[];
+  /** Server-OBSERVED writes under `public/` — never browser-reported. */
+  publicAssetsLastChangedAt: number | null;
+  publicAssetsLastPath: string | null;
+  publicAssetsChangedCount: number;
+  /** When a GET last produced genuine editor HTML — the verified-open signal. */
+  lastIndexRequestAt: number | null;
+  /** Whether the `<project>/src` validation watcher is actually running. */
+  sourceValidation: SourceValidationState;
+
+  // ---- Tabs, clients and the command relay ------------------------------
+  /** Every SSE client id currently attached to one tab. */
+  readonly clientIdsForTab: (tabId: string) => string[];
+  /** Which tab an SSE client belongs to, and the reverse map. */
+  readonly tabIdForClient: (clientId: string | null) => string | null;
+  readonly clientTabIds: Map<string, string>;
+  /** The tab bijection's tables. `hostTabLifecycle` is the local owner's. */
+  readonly hostTabLifecycle: TabLifecycleController;
+  /** Subscribe to a tab's page reloading under the same tabId (any table). */
+  readonly onTabReloaded: (listener: (tabId: string, epochCount: number) => void) => void;
+  readonly participantTabLifecycles: Map<string, TabLifecycleController>;
+  readonly clientTabLifecycles: Map<string, TabLifecycleController>;
+  readonly tabLifecycleForParticipant: (
+    participantId: string,
+    hostEligible?: boolean,
+  ) => TabLifecycleController;
+  /** `null` when this session runs headless — the whole loop is off. */
+  readonly tabBijectionOptions: {
+    enabled: boolean;
+    editorUrl: string;
+    openUrl?: ((url: string) => void) | undefined;
+  } | null;
+  /** The tab heartbeat server (worker beats and their socket fallback). */
+  readonly heartbeat: TabHeartbeatServer;
+  /** Pre-listener page errors, per SSE client. */
+  readonly pageErrorsByClient: Map<string, string[]>;
+  /** Debounced leave timers, so a reload is not read as a departure. */
+  readonly participantLeaveTimers: Map<string, ReturnType<typeof setTimeout>>;
+  /** An id's first 8 characters — every log line in the relay uses it. */
+  readonly short: (id: string | null | undefined) => string;
+  /** The play phase the running game last reported. */
+  livePlayPhase: PlayPhaseRecord | null;
+  /** Live connection counts per collaboration participant. */
+  readonly participantConnections: Map<string, number>;
+  /** Which participant IS the local host, once a tab has claimed it. */
+  hostParticipantId: string | null;
+
+  // ---- Editor state, as tabs report it ----------------------------------
+  editorState: Record<string, unknown>;
+  editorStateUpdatedAt: number | null;
+  readonly editorStatesByClient: Map<string, { state: Record<string, unknown>; updatedAt: number }>;
+
+  // ---- The session journal & build-discipline tripwires ------------------
+  /** Append one event to `<project>/logs/editor-*.jsonl`. */
+  readonly journalEvent: (event: SessionJournalEvent) => void;
+  /** Re-evaluate the commit-cadence / never-played banners. Guarded inside. */
+  readonly announceBuildDisciplineTripwires: () => void;
+  /** The play-run log file currently being appended to, or `null`. */
+  activeLogFile: string | null;
+
+  // ---- Agent harness ----------------------------------------------------
+  readonly harnessChat: HarnessChatService;
+  /** The standing reason the Chat view has no agent, or `null` (`frontend-handoff.ts`). */
+  readonly frontendRefusal: () => string | null;
+  /** The project's own work tracker, as a snapshot + one action endpoint. */
+  readonly projectWork: ProjectWorkCoordinator;
+
+  // ---- How this server was constructed ----------------------------------
+  readonly options: EditorServerOptions;
+
+  // ---- Collaboration ----------------------------------------------------
+  /** The open project's collaboration session, or `null` when none is open. */
+  readonly currentCollaboration: () => CollaborationSession | null;
+  /** Where a joining participant is, as the session records it. */
+  readonly currentCollaborationLocation: () => CollaborationParticipantLocation | undefined;
+  /** `currentCollaboration()`, having already answered 400 when it is null. */
+  readonly collaborationOr400: (res: Response) => CollaborationSession | null;
+  /** The role a joining participant gets when their invitation names none. */
+  readonly defaultCollaborationRole: (
+    participantId: string,
+    invitedRole?: CollaborationRole,
+  ) => CollaborationRole;
+  /** Agent-turn bookkeeping, shared with the harness-chat snapshot listener. */
+  readonly markAgentTurnRunning: (participantId: string) => void;
+  readonly markAgentTurnEnded: (participantId: string) => void;
+  /** Mirrors harness output into the team thread. */
+  readonly teamMirror: TeamAgentMirror;
+  readonly postMirroredTeamMessages: (snapshot: HarnessChatSnapshot) => void;
+  /** Participants attributed to THIS machine rather than a gateway credential. */
+  readonly localParticipantIds: Set<string>;
+
+  // ---- Sharing ----------------------------------------------------------
+  /** The verified share claim on a request, or `null` for the local owner. */
+  readonly trustedShareIdentity: (req: ShareClaimSource) => TrustedShareIdentity | null;
+  /** The cookie secret the local tab presents to reach `/__editor/share-control`. */
+  readonly browserShareControlSecret: string;
+  /** The live share host, once one has been started. */
+  shareHost: ShareHost | null;
+  /** Which local participant IS the owner, once their account is verified. */
+  localShareHost: { participantId: string; account: ShareGatewayClaims['account'] } | null;
+}