@agimon-ai/doompi-web 0.0.1-alpha.0

package/src/adapters/syncGuard.ts

@@ -0,0 +1,119 @@
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { describeSyncDrift, readSyncDrift } from '@agimon-ai/doompi/services';
+
+const DOOMPI_PACKAGE = '@agimon-ai/doompi';
+const CLI_SEGMENTS = ['dist', 'bin', 'cli.mjs'];
+const SYNC_ARGS = ['sync'];
+/** How often the watcher re-reads the drift inputs. */
+const WATCH_INTERVAL_MS = 2_000;
+
+export interface SyncGuardOptions {
+  repoRoot: string;
+  onNotice?: (message: string) => void;
+  /** Test seam for running the sync itself. */
+  runSync?: (repoRoot: string) => Promise<void>;
+  /** Test seam for the drift read. */
+  readDrift?: (repoRoot: string) => { fresh: boolean; reasons: readonly string[] };
+  intervalMs?: number;
+}
+
+export interface SyncGuard {
+  /**
+   * Syncs the repository when anything a session reads has drifted.
+   *
+   * Serialized: several sessions starting at once wait on one sync rather
+   * than racing to rebuild the same artifacts over each other.
+   */
+  ensureSynced(): Promise<void>;
+  /** Re-syncs on drift and reports when artifacts changed under a running cockpit. */
+  watch(onSynced: () => void): void;
+  close(): void;
+}
+
+/** Runs the launcher's own sync, in its own process so the hub keeps serving. */
+function spawnSync(repoRoot: string, onNotice: (message: string) => void): Promise<void> {
+  const cli = path.join(
+    path.dirname(createRequire(import.meta.url).resolve(`${DOOMPI_PACKAGE}/package.json`)),
+    ...CLI_SEGMENTS,
+  );
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [cli, ...SYNC_ARGS], { cwd: repoRoot, stdio: ['ignore', 'pipe', 'pipe'] });
+    const tail: string[] = [];
+    const keep = (chunk: Buffer): void => {
+      tail.push(chunk.toString());
+      if (tail.length > 20) tail.shift();
+    };
+    child.stdout?.on('data', keep);
+    child.stderr?.on('data', keep);
+    child.once('error', (error) => {
+      onNotice(`sync could not start: ${error.message}`);
+      resolve();
+    });
+    child.once('exit', (code) => {
+      // A failed sync is reported, not thrown: the session the caller wanted
+      // still starts, and it starts against whatever the last good sync left.
+      if (code !== 0) onNotice(`sync exited ${String(code)}: ${tail.join('').trim().slice(-400)}`);
+      resolve();
+    });
+  });
+}
+
+/**
+ * Keeps the repository synced under a running cockpit.
+ *
+ * A session launched from the browser reads what sync produced: the resolved
+ * composition, the plugin bundle, and the package API routes. Nothing forces
+ * a person clicking "new session" to have run sync first, and a stale one
+ * fails quietly rather than loudly, so the hub checks and syncs itself.
+ */
+export function createSyncGuard(options: SyncGuardOptions): SyncGuard {
+  const notice = options.onNotice ?? ((): void => {});
+  const runSync = options.runSync ?? ((repoRoot: string) => spawnSync(repoRoot, notice));
+  const readDrift = options.readDrift ?? ((repoRoot: string) => readSyncDrift({ repoRoot }));
+  let inFlight: Promise<void> | undefined;
+  let timer: ReturnType<typeof setInterval> | undefined;
+  let closed = false;
+
+  const syncOnce = async (drift: { reasons: readonly string[] }): Promise<void> => {
+    notice(`syncing: ${describeSyncDrift({ fresh: false, reasons: drift.reasons as never })}`);
+    await runSync(options.repoRoot);
+    notice('sync complete');
+  };
+
+  const ensureSynced = async (): Promise<void> => {
+    if (closed) return;
+    // Joining the run already in flight is what makes concurrent launches
+    // wait for one sync instead of starting several.
+    if (inFlight) return inFlight;
+    const drift = readDrift(options.repoRoot);
+    if (drift.fresh) return;
+    inFlight = syncOnce(drift).finally(() => {
+      inFlight = undefined;
+    });
+    return inFlight;
+  };
+
+  return {
+    ensureSynced,
+    watch(onSynced) {
+      if (timer) return;
+      timer = setInterval(() => {
+        if (closed || inFlight) return;
+        const drift = readDrift(options.repoRoot);
+        if (drift.fresh) return;
+        void ensureSynced().then(() => {
+          if (!closed) onSynced();
+        });
+      }, options.intervalMs ?? WATCH_INTERVAL_MS);
+      // The hub should not be held open by its own watcher.
+      timer.unref?.();
+    },
+    close() {
+      closed = true;
+      if (timer) clearInterval(timer);
+      timer = undefined;
+    },
+  };
+}

package/src/adapters/threadJournals.ts

@@ -0,0 +1,184 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { journalFrames, retainNewest } from '../services/journalTail.ts';
+import type { SessionFrame } from '../types/session.ts';
+
+const DEFAULT_POLL_MS = 1000;
+/** Journalled messages kept per thread, the same allowance an attach restores. */
+const DEFAULT_RETAIN_LIMIT = 300;
+/** How far back a first read goes into a long journal; older lines stay on disk. */
+const DEFAULT_MAX_INITIAL_BYTES = 8 * 1024 * 1024;
+const JOURNAL_EXTENSION = '.jsonl';
+const NEWLINE = 0x0a;
+
+export interface ThreadFrameEvent {
+  sessionId: string;
+  threadId: string;
+  frame: SessionFrame;
+}
+
+export interface ThreadJournalsOptions {
+  /** Names the journal of one thread, or undefined while no source knows it yet. */
+  resolve(sessionId: string, threadId: string): string | undefined;
+  pollMs?: number;
+  retainLimit?: number;
+  maxInitialBytes?: number;
+  onNotice?: (message: string) => void;
+}
+
+export interface ThreadJournals {
+  /** Follows the thread for one more subscriber and returns its retained history, oldest first. */
+  subscribe(sessionId: string, threadId: string): SessionFrame[];
+  unsubscribe(sessionId: string, threadId: string): void;
+  /** Live frames of every followed thread; the return value stops listening. */
+  onFrame(listener: (event: ThreadFrameEvent) => void): () => void;
+  close(): void;
+}
+
+interface Tail {
+  sessionId: string;
+  threadId: string;
+  refs: number;
+  /** Unknown until a source names the journal; asked again on every tick. */
+  path: string | undefined;
+  /** The byte after the last complete line read, so a torn line is re-read whole. */
+  offset: number;
+  retained: SessionFrame[];
+  warned: boolean;
+}
+
+function keyOf(sessionId: string, threadId: string): string {
+  return `${sessionId}\n${threadId}`;
+}
+
+/** Bytes [start, end) of a file, or undefined when it cannot be read right now. */
+function readRange(file: string, start: number, end: number): Buffer | undefined {
+  const buffer = Buffer.alloc(end - start);
+  let fd: number | undefined;
+  try {
+    fd = fs.openSync(file, 'r');
+    const read = fs.readSync(fd, buffer, 0, buffer.length, start);
+    return buffer.subarray(0, read);
+  } catch {
+    // The writer may be rotating or the file may have gone; the next tick looks again.
+    return undefined;
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+/**
+ * Tails Pi session journals for the pages following them.
+ *
+ * A thread is any journal a data channel can name for a session, such as a
+ * subagent run's own session file. The hub reads only what the file gained
+ * since the last look and stops at the last newline, so a line the writer is
+ * still appending is never folded half-way; a file that shrank is read from
+ * the start again, which is harmless because the page dedupes entries by id.
+ */
+export function createThreadJournals(options: ThreadJournalsOptions): ThreadJournals {
+  const pollMs = options.pollMs ?? DEFAULT_POLL_MS;
+  const retainLimit = options.retainLimit ?? DEFAULT_RETAIN_LIMIT;
+  const maxInitialBytes = options.maxInitialBytes ?? DEFAULT_MAX_INITIAL_BYTES;
+  const notice = options.onNotice ?? ((): void => {});
+  const tails = new Map<string, Tail>();
+  const listeners = new Set<(event: ThreadFrameEvent) => void>();
+  let timer: NodeJS.Timeout | undefined;
+
+  const journalPathOf = (tail: Tail): string | undefined => {
+    const candidate = options.resolve(tail.sessionId, tail.threadId);
+    if (candidate === undefined) return undefined;
+    if (path.isAbsolute(candidate) && candidate.endsWith(JOURNAL_EXTENSION)) return candidate;
+    if (!tail.warned) {
+      tail.warned = true;
+      notice(`thread ${tail.threadId} of session ${tail.sessionId} names '${candidate}', which is not a journal`);
+    }
+    return undefined;
+  };
+
+  /** Folds what the journal gained since the last look and returns the new frames. */
+  const advance = (tail: Tail): SessionFrame[] => {
+    tail.path ??= journalPathOf(tail);
+    if (tail.path === undefined) return [];
+    let size: number;
+    try {
+      size = fs.statSync(tail.path).size;
+    } catch {
+      // Not written yet, or gone: the thread stays empty until the next tick finds it.
+      return [];
+    }
+    if (size < tail.offset) {
+      tail.offset = 0;
+      tail.retained = [];
+    }
+    let start = tail.offset;
+    let cut = false;
+    if (start === 0 && size > maxInitialBytes) {
+      start = size - maxInitialBytes;
+      cut = true;
+    }
+    if (size <= start) return [];
+    const chunk = readRange(tail.path, start, size);
+    if (chunk === undefined) return [];
+    const lastNewline = chunk.lastIndexOf(NEWLINE);
+    if (lastNewline === -1) return [];
+    // A cut lands mid-line; the line it tore is dropped rather than misread.
+    const firstLine = cut ? chunk.indexOf(NEWLINE) + 1 : 0;
+    const frames = firstLine > lastNewline ? [] : journalFrames(chunk.toString('utf8', firstLine, lastNewline + 1));
+    tail.offset = start + lastNewline + 1;
+    if (frames.length > 0) tail.retained = retainNewest([...tail.retained, ...frames], retainLimit);
+    return frames;
+  };
+
+  const tick = (): void => {
+    for (const tail of tails.values()) {
+      const frames = advance(tail);
+      for (const frame of frames) {
+        for (const listener of listeners) listener({ sessionId: tail.sessionId, threadId: tail.threadId, frame });
+      }
+    }
+  };
+
+  const syncTimer = (): void => {
+    if (tails.size > 0 && timer === undefined) timer = setInterval(tick, pollMs);
+    if (tails.size === 0 && timer !== undefined) {
+      clearInterval(timer);
+      timer = undefined;
+    }
+  };
+
+  return {
+    subscribe(sessionId, threadId) {
+      const key = keyOf(sessionId, threadId);
+      let tail = tails.get(key);
+      if (tail === undefined) {
+        tail = { sessionId, threadId, refs: 0, path: undefined, offset: 0, retained: [], warned: false };
+        tails.set(key, tail);
+        advance(tail);
+        syncTimer();
+      }
+      tail.refs += 1;
+      return [...tail.retained];
+    },
+    unsubscribe(sessionId, threadId) {
+      const key = keyOf(sessionId, threadId);
+      const tail = tails.get(key);
+      if (tail === undefined) return;
+      tail.refs -= 1;
+      if (tail.refs <= 0) tails.delete(key);
+      syncTimer();
+    },
+    onFrame(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    close() {
+      if (timer !== undefined) clearInterval(timer);
+      timer = undefined;
+      tails.clear();
+      listeners.clear();
+    },
+  };
+}

package/src/adapters/webBundler.ts

@@ -0,0 +1,83 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { PLUGIN_ROOTS_FILE } from '../services/webDevRoots.ts';
+import { SERVER_REGISTRY_FILE, webHostPackageRoot, writeSyncWebPluginModules } from './webPluginGenerate.ts';
+import { scanWebPlugins } from './webPluginScan.ts';
+import { webPluginCssAlias, webPluginOverridePlugin } from './webPluginVite.ts';
+
+/** Shared runtime packages every plugin's client code must resolve to the host copies. */
+const DEDUPED_RUNTIMES = [
+  'react',
+  'react-dom',
+  '@tanstack/store',
+  '@tanstack/react-store',
+  '@agimon-ai/doompi-web-components',
+];
+
+export interface BundleCockpitWebOptions {
+  /** Package roots to scan for doompiWeb manifests, usually the installed composition. */
+  pluginRoots: readonly string[];
+  /** Output directory; receives web/ (the bundle), generated/ (the entry modules), and pluginRoots.json. */
+  outDir: string;
+  onNotice?: (message: string) => void;
+}
+
+export interface BundleCockpitWebResult {
+  /** The assets directory to serve (contains index.html and the server registry). */
+  assetsDir: string;
+  pluginIds: string[];
+}
+
+/**
+ * Builds the cockpit SPA against the installed plugin set.
+ *
+ * This is what `doompi sync` calls: manifests come from the given package
+ * roots (no hardcoded plugin dependencies anywhere), the generated entry
+ * modules are aliased over the committed builtin registry, and Vite compiles
+ * everything (host shell plus each plugin's shipped web source) into one
+ * bundle. The server registry written next to the assets tells the hub which
+ * built hub entries to load, and the roots file beside the bundle lets the
+ * dev server serve the same composition with hot reload.
+ */
+export async function bundleCockpitWeb(options: BundleCockpitWebOptions): Promise<BundleCockpitWebResult> {
+  const notice = options.onNotice ?? ((): void => {});
+  const hostRoot = webHostPackageRoot();
+  const plugins = scanWebPlugins(hostRoot, options.pluginRoots, notice);
+  notice(
+    `bundling the cockpit with ${String(plugins.length)} web plugin(s): ${plugins.map((p) => p.pluginId).join(', ')}`,
+  );
+
+  const generatedDir = path.join(options.outDir, 'generated');
+  const assetsDir = path.join(options.outDir, 'web');
+  const generated = writeSyncWebPluginModules(plugins, generatedDir);
+  const roots = [...new Set(options.pluginRoots.map((root) => path.resolve(root)))];
+  fs.writeFileSync(path.join(options.outDir, PLUGIN_ROOTS_FILE), `${JSON.stringify(roots, null, 2)}\n`);
+
+  // Vite and its plugins are regular dependencies so this works from an
+  // installed package, not only the workspace.
+  const { build } = await import('vite');
+  const { default: react } = await import('@vitejs/plugin-react');
+  const { default: tailwindcss } = await import('@tailwindcss/vite');
+
+  const clientRoot = path.join(hostRoot, 'src', 'web');
+
+  await build({
+    configFile: false,
+    envDir: false,
+    logLevel: 'warn',
+    root: clientRoot,
+    plugins: [webPluginOverridePlugin(clientRoot, generated), react(), tailwindcss()],
+    resolve: {
+      dedupe: [...DEDUPED_RUNTIMES],
+      alias: [webPluginCssAlias(generated)],
+    },
+    build: {
+      outDir: assetsDir,
+      emptyOutDir: true,
+      sourcemap: false,
+    },
+  });
+
+  fs.writeFileSync(path.join(assetsDir, SERVER_REGISTRY_FILE), generated.serverRegistry);
+  return { assetsDir, pluginIds: plugins.map((plugin) => plugin.pluginId) };
+}

package/src/adapters/webHubPluginLoader.ts

@@ -0,0 +1,67 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import type { WebHubChannel } from '@agimon-ai/doompi-web-contracts';
+import { SERVER_REGISTRY_FILE } from './webPluginGenerate.ts';
+import { BUILTIN_HUB_CHANNELS } from './webHubPlugins.generated.ts';
+
+interface RegistryEntry {
+  pluginId?: unknown;
+  hubEntry?: unknown;
+}
+
+const UNKNOWN_PLUGIN_ID = 'unknown';
+
+/** The synced bundle's server registry, or an empty list when there is none to read. */
+function registryEntries(assetsDir: string, onNotice: (message: string) => void): RegistryEntry[] {
+  const registryPath = path.join(assetsDir, SERVER_REGISTRY_FILE);
+  if (!fs.existsSync(registryPath)) return [];
+  try {
+    const parsed: unknown = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+    return Array.isArray(parsed) ? (parsed as RegistryEntry[]) : [];
+  } catch (error) {
+    onNotice(`web plugin registry ${registryPath} is unreadable (${String(error)}); plugin channels skipped`);
+    return [];
+  }
+}
+
+/**
+ * Assembles the hub's data channels for the assets being served.
+ *
+ * A synced bundle carries webPlugins.server.json naming each plugin's built
+ * hub entry by absolute path; those are imported lazily so an absent or
+ * broken plugin package is a notice and an empty tab, never a crash. Without
+ * a registry (the package's own prebuilt bundle, or a custom assets dir) the
+ * built-in channels are the whole set.
+ */
+export async function loadHubChannels(
+  assetsDir: string,
+  onNotice: (message: string) => void,
+): Promise<WebHubChannel[]> {
+  const channels: WebHubChannel[] = [...BUILTIN_HUB_CHANNELS];
+  for (const entry of registryEntries(assetsDir, onNotice)) {
+    const pluginId = typeof entry.pluginId === 'string' ? entry.pluginId : UNKNOWN_PLUGIN_ID;
+    if (typeof entry.hubEntry !== 'string') continue;
+    try {
+      const module = (await import(pathToFileURL(entry.hubEntry).href)) as { webHubChannels?: unknown };
+      if (!Array.isArray(module.webHubChannels)) {
+        throw new Error(`'${entry.hubEntry}' exports no webHubChannels array`);
+      }
+      channels.push(...(module.webHubChannels as WebHubChannel[]));
+    } catch (error) {
+      const cause = error instanceof Error ? error.message : String(error);
+      onNotice(`web plugin '${pluginId}' hub channels unavailable (${cause}); its panels stay empty`);
+    }
+  }
+  const seen = new Set<string>();
+  const unique: WebHubChannel[] = [];
+  for (const channel of channels) {
+    if (seen.has(channel.frameType)) {
+      onNotice(`duplicate web channel '${channel.frameType}' dropped; frame types are global`);
+      continue;
+    }
+    seen.add(channel.frameType);
+    unique.push(channel);
+  }
+  return unique;
+}

package/src/adapters/webHubPlugins.generated.ts

@@ -0,0 +1,4 @@
+// Generated by src/adapters/webPluginGenerate.ts. Do not edit by hand.
+import type { WebHubChannel } from '@agimon-ai/doompi-web-contracts';
+
+export const BUILTIN_HUB_CHANNELS: readonly WebHubChannel[] = [];

package/src/adapters/webPluginGenerate.ts

@@ -0,0 +1,172 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import type { DeclaredWebPlugin } from '../services/webPluginManifest.ts';
+import { scanWebPlugins } from './webPluginScan.ts';
+
+const HEADER = '// Generated by src/adapters/webPluginGenerate.ts. Do not edit by hand.';
+
+/** Walks up to the owning package.json: correct from src and from the unbundled dist tree alike. */
+function ownPackageRoot(): string {
+  let dir = path.dirname(fileURLToPath(import.meta.url));
+  for (;;) {
+    if (fs.existsSync(path.join(dir, 'package.json'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) throw new Error('doompi-web could not locate its own package root.');
+    dir = parent;
+  }
+}
+
+const packageRoot = ownPackageRoot();
+
+export const BUILTIN_CLIENT_MODULE = path.join('src', 'web', 'app', 'webPlugins.generated.ts');
+export const BUILTIN_HUB_MODULE = path.join('src', 'adapters', 'webHubPlugins.generated.ts');
+export const BUILTIN_CSS_MODULE = path.join('src', 'web', 'styles', 'webPluginSources.generated.css');
+/** The server-side registry a synced bundle carries next to its assets. */
+export const SERVER_REGISTRY_FILE = 'webPlugins.server.json';
+
+export function webHostPackageRoot(): string {
+  return packageRoot;
+}
+
+function camel(pluginId: string): string {
+  return pluginId.replace(/-([a-z0-9])/g, (_, ch: string) => ch.toUpperCase());
+}
+
+function relativeImport(fromDir: string, toFile: string): string {
+  const spec = path.relative(fromDir, toFile).split(path.sep).join('/');
+  return spec.startsWith('.') ? spec : `./${spec}`;
+}
+
+function renderClientModule(plugins: readonly DeclaredWebPlugin[], style: 'relative' | 'absolute'): string {
+  const lines = [HEADER, "import type { WebPluginDefinition } from '@agimon-ai/doompi-web-contracts';"];
+  const names: string[] = [];
+  const fromDir = path.join(packageRoot, 'src', 'web', 'app');
+  for (const plugin of plugins) {
+    const name = `${camel(plugin.pluginId)}Plugin`;
+    names.push(name);
+    const entry = path.join(plugin.packageDir, plugin.client.entry);
+    // The committed builtin module keeps machine-neutral relative imports; the
+    // sync-generated module lives outside src, is aliased over the committed
+    // path, and resolves imports against its real location, so every entry
+    // becomes an absolute file URL into the installed packages.
+    const specifier = style === 'relative' ? relativeImport(fromDir, entry) : pathToFileURL(entry).href;
+    lines.push(`import { webPlugin as ${name} } from '${specifier}';`);
+  }
+  lines.push('', `export const webPlugins: readonly WebPluginDefinition[] = [${names.join(', ')}];`, '');
+  return lines.join('\n');
+}
+
+function renderBuiltinHubModule(plugins: readonly DeclaredWebPlugin[]): string {
+  const lines = [HEADER, "import type { WebHubChannel } from '@agimon-ai/doompi-web-contracts';"];
+  const names: string[] = [];
+  for (const plugin of plugins) {
+    if (plugin.hub === undefined || !plugin.isHost) continue;
+    const name = `${camel(plugin.pluginId)}Channels`;
+    names.push(name);
+    const specifier = relativeImport(
+      path.join(packageRoot, 'src', 'adapters'),
+      path.join(plugin.packageDir, plugin.hub.entry),
+    );
+    lines.push(`import { webHubChannels as ${name} } from '${specifier}';`);
+  }
+  lines.push('');
+  lines.push(
+    names.length === 0
+      ? 'export const BUILTIN_HUB_CHANNELS: readonly WebHubChannel[] = [];'
+      : `export const BUILTIN_HUB_CHANNELS: readonly WebHubChannel[] = [${names.map((name) => `...${name}`).join(', ')}];`,
+  );
+  lines.push('');
+  return lines.join('\n');
+}
+
+function renderCssModule(plugins: readonly DeclaredWebPlugin[]): string {
+  const lines = [`/* ${HEADER.slice(3)} */`];
+  for (const plugin of plugins) {
+    if (plugin.isHost) continue; // The host tree is already inside Tailwind's scan root.
+    lines.push(`@source "${path.dirname(path.join(plugin.packageDir, plugin.client.entry))}";`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+export interface ServerRegistryEntry {
+  pluginId: string;
+  channels: string[];
+  /** Absolute path to the built hub entry exporting webHubChannels. */
+  hubEntry: string;
+}
+
+function renderServerRegistry(plugins: readonly DeclaredWebPlugin[]): string {
+  const entries: ServerRegistryEntry[] = [];
+  for (const plugin of plugins) {
+    if (plugin.hub === undefined) continue;
+    // Host channels are compiled into the server; only externals need loading.
+    if (plugin.isHost) continue;
+    entries.push({
+      pluginId: plugin.pluginId,
+      channels: plugin.channels,
+      hubEntry: path.join(plugin.packageDir, plugin.hub.dist ?? plugin.hub.entry),
+    });
+  }
+  return `${JSON.stringify(entries, null, 2)}\n`;
+}
+
+/** The committed builtin registry, rendered from the host package alone. */
+export function renderBuiltinWebPluginModules(): Map<string, string> {
+  const plugins = scanWebPlugins(packageRoot);
+  return new Map([
+    [BUILTIN_CLIENT_MODULE, renderClientModule(plugins, 'relative')],
+    [BUILTIN_HUB_MODULE, renderBuiltinHubModule(plugins)],
+    [BUILTIN_CSS_MODULE, renderCssModule(plugins)],
+  ]);
+}
+
+/**
+ * Keeps the committed builtin registry fresh: write-if-changed locally,
+ * check-only (throw) in CI. Both vite.config.ts and tsdown.config.ts call
+ * this at config-load time.
+ */
+export function ensureBuiltinWebPluginModules({ check = false }: { check?: boolean } = {}): void {
+  const stale: string[] = [];
+  for (const [relativePath, content] of renderBuiltinWebPluginModules()) {
+    const filePath = path.join(packageRoot, relativePath);
+    const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : undefined;
+    if (existing === content) continue;
+    if (check) {
+      stale.push(relativePath);
+      continue;
+    }
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content);
+  }
+  if (stale.length > 0) {
+    throw new Error(
+      `Stale generated web plugin modules: ${stale.join(', ')}. Run pnpm build in doompi-web and commit them.`,
+    );
+  }
+}
+
+export interface SyncGeneratedModules {
+  clientModulePath: string;
+  cssModulePath: string;
+  serverRegistry: string;
+}
+
+/**
+ * The sync-time variant: renders the full plugin set (host built-ins plus the
+ * installed composition's packages) into a generation directory the bundler
+ * aliases over the committed builtin modules, plus the server-side registry
+ * the hub loads at startup.
+ */
+export function writeSyncWebPluginModules(
+  plugins: readonly DeclaredWebPlugin[],
+  generatedDir: string,
+): SyncGeneratedModules {
+  fs.mkdirSync(generatedDir, { recursive: true });
+  const clientModulePath = path.join(generatedDir, 'webPlugins.generated.ts');
+  const cssModulePath = path.join(generatedDir, 'webPluginSources.generated.css');
+  fs.writeFileSync(clientModulePath, renderClientModule(plugins, 'absolute'));
+  fs.writeFileSync(cssModulePath, renderCssModule(plugins));
+  return { clientModulePath, cssModulePath, serverRegistry: renderServerRegistry(plugins) };
+}