@ryanyahya/opendoc-headless 0.4.0

package/src/server/themes.ts

@@ -0,0 +1,215 @@
+import { lstat, readdir, readFile, rm, stat } from 'node:fs/promises';
+import { dirname, relative, resolve, sep } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { build } from 'esbuild';
+import { validateTheme, type DocTheme } from '../themes/index';
+import type { ThemePreview, ThemeSummary } from '../shared/themes';
+import { containedFile } from './files';
+import { RenderFailure } from './render-error';
+import { renderEntry, validId } from './render';
+import { bindingDependencies, readAssetRevision, readThemeAssetDefaults, resolveThemeAssets } from '../assets/files';
+import { documentDependencies, includesDependency, type DocumentDependencies, isRenderRuntimePath, isManagedAssetPath } from './dependencies';
+import { authoringResolutionPlugin } from './source-overrides';
+
+export async function themeFile(root: string, id: string, name: 'index.ts' | 'design.md' | 'preview.tsx' | 'components.tsx') {
+  if (typeof id !== 'string' || !validId(id)) throw new Error('Invalid theme ID.');
+  const folder = await containedFile(resolve(root, 'themes'), resolve(root, 'themes', id));
+  const file = await containedFile(folder, resolve(folder, name));
+  const info = await stat(file);
+  if (!info.isFile() || info.size > (name === 'design.md' ? 64_000 : 256_000)) throw new Error(`Theme ${name} must be a regular, reasonably sized local file.`);
+  return file;
+}
+
+/** Bundle the current definition, including local imports. No long-lived Node module cache or restart needed. */
+export async function readTheme(root: string, id: string): Promise<DocTheme> {
+  const [entry] = await Promise.all(['index.ts', 'design.md', 'preview.tsx'].map(name => themeFile(root, id, name as 'index.ts' | 'design.md' | 'preview.tsx')));
+  await readThemePaths(root, id);
+  const result = await build({ absWorkingDir: root, entryPoints: [entry], bundle: true, write: false, format: 'esm', platform: 'node', logLevel: 'silent', plugins: [authoringResolutionPlugin()] });
+  await readThemeGuide(root, id);
+  const module = await import(`data:text/javascript;base64,${Buffer.from(result.outputFiles[0].contents).toString('base64')}`);
+  const theme = module.theme as DocTheme;
+  validateTheme(theme);
+  if (theme.id !== id) throw new Error(`Theme ID ${JSON.stringify(theme.id)} must match its folder ${JSON.stringify(id)}.`);
+  return theme;
+}
+
+export async function readThemeGuide(root: string, id: string) {
+  const markdown = await readFile(await themeFile(root, id, 'design.md'), 'utf8');
+  if (!markdown.trim()) throw new Error('This theme needs a design guide.');
+  return markdown;
+}
+
+export function themePaths(id: string) {
+  return { definition: `themes/${id}/index.ts`, guide: `themes/${id}/design.md`, preview: `themes/${id}/preview.tsx` };
+}
+
+/** Components are optional native PDF code, discovered without executing them. */
+export async function readThemePaths(root: string, id: string): Promise<ReturnType<typeof themePaths> & { components?: string }> {
+  const definition = await themeFile(root, id, 'index.ts');
+  const components = resolve(dirname(definition), 'components.tsx');
+  const exists = await lstat(components).catch(error => { if (error.code === 'ENOENT') return undefined; throw error; });
+  if (!exists) return themePaths(id);
+  await themeFile(root, id, 'components.tsx');
+  return { ...themePaths(id), components: `themes/${id}/components.tsx` };
+}
+function summarize(theme: DocTheme): ThemeSummary {
+  return { id: theme.id, name: theme.name, description: theme.description, body: theme.body, heading: theme.heading, pageSize: theme.pageSize, useFor: theme.useFor ?? [], principles: theme.principles ?? [], palette: theme.palette ?? [], geometry: theme.geometry ?? [] };
+}
+async function summarizeWithAssets(root: string, theme: DocTheme): Promise<ThemeSummary> {
+  const summary = summarize(theme);
+  try {
+    summary.assetDefaults = await readThemeAssetDefaults(root, theme.id);
+    const bindings = await resolveThemeAssets(root, theme.id);
+    summary.baseBody = theme.body; summary.baseHeading = theme.heading;
+    if (bindings.bodyFont) summary.body = (await readAssetRevision(root, 'font', bindings.bodyFont.id, bindings.bodyFont.revision)).name;
+    if (bindings.headingFont) summary.heading = (await readAssetRevision(root, 'font', bindings.headingFont.id, bindings.headingFont.revision)).name;
+  } catch (error) { summary.assetError = error instanceof Error ? error.message : String(error); }
+  return summary;
+}
+
+type RenderedPreview = ThemePreview & { directory?: string };
+/** Small discovery records; PDF work starts only when a specimen is requested, with at most two workers. */
+export class ThemeCatalog {
+  private version = 0;
+  private globalVersion = 0;
+  private themeVersions = new Map<string, number>();
+  private session = randomUUID();
+  private summaries?: { version: number; result: Promise<ThemeSummary[]> };
+  private previews = new Map<string, { version: string; result: Promise<RenderedPreview> }>();
+  private dependencies = new Map<string, DocumentDependencies>();
+  private definitions = new Map<string, DocumentDependencies>();
+  private active = 0;
+  private waiting: (() => void)[] = [];
+  private closed = false;
+  constructor(private root: string) {}
+  invalidate(id?: string) {
+    this.version++;
+    if (id) { this.dependencies.delete(id); this.definitions.delete(id); }
+    else { this.dependencies.clear(); this.definitions.clear(); }
+    if (id) this.themeVersions.set(id, (this.themeVersions.get(id) ?? 0) + 1);
+    else this.globalVersion++;
+  }
+  private revision(id: string) { return `${this.session}:${this.globalVersion}:${this.themeVersions.get(id) ?? 0}`; }
+  /** Catalog publications affect only specimens whose current defaults depend on those bytes. */
+  async noteChange(file: string): Promise<string[]> {
+    const path = resolve(this.root, file);
+    const parts = relative(this.root, path).split(sep);
+    if (parts[0] === 'themes') this.version++;
+    if (!isManagedAssetPath(this.root, path)) {
+      const entries = await readdir(resolve(this.root, 'themes'), { withFileTypes: true }).catch(() => []);
+      const ids = new Set([...entries.filter(entry => entry.isDirectory() && validId(entry.name)).map(entry => entry.name), ...this.previews.keys()]);
+      const affected: string[] = [];
+      for (const id of ids) {
+        const graphs = [this.definitions.get(id), this.dependencies.get(id)].filter(Boolean) as DocumentDependencies[];
+        if (isRenderRuntimePath(this.root, path) || (parts[0] === 'themes' && (!parts[1] || parts[1] === id)) || !graphs.length || (this.previews.has(id) && !this.dependencies.has(id))
+          || graphs.some(graph => graph.readsFiles || includesDependency(graph, path))) { this.invalidate(id); affected.push(id); }
+      }
+      return affected;
+    }
+    const entries = await readdir(resolve(this.root, 'themes'), { withFileTypes: true }).catch(() => []);
+    const affected: string[] = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory() || !validId(entry.name)) continue;
+      const graphs = [this.definitions.get(entry.name), this.dependencies.get(entry.name)].filter(Boolean) as DocumentDependencies[];
+      if (graphs.some(graph => graph.readsFiles || includesDependency(graph, path)) || (this.previews.has(entry.name) && !this.dependencies.has(entry.name))) {
+        affected.push(entry.name); this.invalidate(entry.name); continue;
+      }
+      try {
+        const defaults = await readThemeAssetDefaults(this.root, entry.name);
+        const references = [defaults.logo && ['logos', defaults.logo.id], defaults.bodyFont && ['fonts', defaults.bodyFont], defaults.headingFont && ['fonts', defaults.headingFont]].filter(Boolean) as string[][];
+        if (!references.some(([kind, id]) => parts[1] === kind && (!parts[2] || parts[2] === id))) continue;
+        let relevant = parts.length <= 3 || parts[3] === 'asset.json';
+        try {
+          const bindings = await resolveThemeAssets(this.root, entry.name);
+          const files = (await bindingDependencies(this.root, bindings)).map(file => resolve(this.root, file));
+          relevant ||= files.some(file => file === path || file.startsWith(path + sep));
+        } catch { relevant = true; }
+        if (relevant) { affected.push(entry.name); this.invalidate(entry.name); }
+      } catch { /* Invalid neighboring defaults do not prevent other catalogs refreshing. */ }
+    }
+    return affected;
+  }
+  async list(): Promise<ThemeSummary[]> {
+    if (!this.summaries || this.summaries.version !== this.version) {
+      const version = this.version;
+      const result = (async () => {
+        const entries = await readdir(resolve(this.root, 'themes'), { withFileTypes: true }).catch(error => { if (error.code === 'ENOENT') return []; throw error; });
+        const items: ThemeSummary[] = [];
+        for (const folder of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+          if (!folder.isDirectory() || !validId(folder.name)) continue;
+          try {
+            const entry = await themeFile(this.root, folder.name, 'index.ts');
+            const dependencies = await documentDependencies(this.root, entry).catch(() => undefined);
+            items.push(await summarizeWithAssets(this.root, await readTheme(this.root, folder.name)));
+            if (dependencies && version === this.version) this.definitions.set(folder.name, dependencies);
+          }
+          catch (error) { items.push({ id: folder.name, name: folder.name, description: 'This theme needs attention.', body: '', heading: '', pageSize: '', useFor: [], principles: [], error: error instanceof Error ? error.message : String(error) }); }
+        }
+        return items.map(item => ({ ...item, revision: this.revision(item.id) }));
+      })();
+      this.summaries = { version, result };
+    }
+    const snapshot = this.summaries;
+    const items = await snapshot.result;
+    return snapshot.version === this.version ? items : this.list();
+  }
+  private async render(id: string, version: string): Promise<RenderedPreview> {
+    if (this.active >= 2) await new Promise<void>(accept => this.waiting.push(accept));
+    else this.active++;
+    let directory: string | undefined;
+    try {
+      if (this.closed) throw new Error('The theme catalog is closed.');
+      await readTheme(this.root, id);
+      await readThemeGuide(this.root, id);
+      const entry = await themeFile(this.root, id, 'preview.tsx');
+      const dependencies = await documentDependencies(this.root, entry).catch(() => undefined);
+      const rendered = await renderEntry(this.root, entry, `theme-${id}`);
+      directory = rendered.directory;
+      if (rendered.artifact.meta.theme !== id) throw new Error('The specimen must use its own theme ID.');
+      if (dependencies && version === this.revision(id)) {
+        for (const file of rendered.artifact.assetDependencies ?? []) dependencies.files.add(resolve(this.root, file));
+        this.dependencies.set(id, dependencies);
+      }
+      return rendered;
+    } catch (error) {
+      if (directory) await rm(directory, { recursive: true, force: true });
+      return { error: error instanceof Error ? error.message : String(error), ...(error instanceof RenderFailure ? { issues: error.issues } : {}) };
+    } finally { const next = this.waiting.shift(); if (next) next(); else this.active--; }
+  }
+  private async current(id: string): Promise<RenderedPreview> {
+    if (typeof id !== 'string' || !validId(id)) throw new Error('Invalid theme ID.');
+    if (this.closed) throw new Error('The theme catalog is closed.');
+    let snapshot = this.previews.get(id);
+    if (!snapshot || snapshot.version !== this.revision(id)) {
+      const previous = snapshot;
+      const version = this.revision(id);
+      const result = (async () => {
+        const old = await previous?.result;
+        const next = await this.render(id, version);
+        if (old?.directory) await rm(old.directory, { recursive: true, force: true });
+        return next;
+      })();
+      snapshot = { version, result }; this.previews.set(id, snapshot);
+    }
+    const result = await snapshot.result;
+    if (snapshot.version !== this.revision(id)) return this.current(id);
+    // A failed preview is retryable even before a file watcher observes a repair.
+    if (result.error && this.previews.get(id) === snapshot) this.previews.delete(id);
+    return result;
+  }
+  async preview(id: string): Promise<ThemePreview> {
+    const { directory: _directory, ...preview } = await this.current(id);
+    return preview;
+  }
+  async pdf(id: string, hash: string) {
+    const item = await this.current(id);
+    if (!item.directory || item.artifact?.hash !== hash) throw new Error('This theme preview changed. Reload the theme.');
+    return readFile(resolve(item.directory, 'document.pdf'));
+  }
+  async close() {
+    this.closed = true;
+    const entries = await Promise.all([...this.previews.values()].map(item => item.result));
+    await Promise.all(entries.map(item => item.directory && rm(item.directory, { recursive: true, force: true })));
+    this.previews.clear();
+  }
+}

package/src/server/ttf2eot.d.ts

@@ -0,0 +1,3 @@
+declare module 'ttf2eot' {
+  export default function ttf2eot(font: Uint8Array): Uint8Array;
+}

package/src/server/worker.ts

@@ -0,0 +1,166 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { resolve, dirname, relative, sep } from 'node:path';
+import { readFileSync, realpathSync } from 'node:fs';
+import { createTextSourceResolver, createJsonTextSourceResolver, type TextSourceResolver } from './text-source';
+import { attachTextLines } from './text-layout';
+import type { TextGlobals } from '../document/text-targets';
+import type { TextTarget } from '../shared/selection';
+import { createHash } from 'node:crypto';
+import { renderDocumentSource } from './render-source';
+import type { MediaUse } from '../shared/media';
+import type { AssetUse, DocumentAssets } from '../shared/assets';
+import { readDocumentAssetsAt, resolveThemeAssets } from '../assets/files';
+import type { LayoutInfo, ElementInfo } from '@formepdf/core';
+import type { BlockInfo, DocumentMeta, DocumentProvenance, RenderArtifact, Fragment, DocumentFormat, SlideInfo } from '../shared/types';
+import { RenderFailure } from './render-error';
+import { inspectLayout, assertLayoutSafe, assertSlideLayout } from './preflight';
+import { containedFile } from './files';
+import { readProjects } from './projects';
+import { originalBinding, type SourceOverride } from './source-overrides';
+import { runtimeSource } from '../runtime/paths';
+
+const [inputEntry, destination, overrideFlag] = process.argv.slice(2);
+const entry = realpathSync(inputEntry);
+const root = process.cwd();
+const sourceOverrides = overrideFlag ? await new Promise<SourceOverride[]>(accept => process.once('message', (message: { sourceOverrides: SourceOverride[] }) => accept(message.sourceOverrides))) : [];
+const overrides = new Map(sourceOverrides.map(override => [override.file, override]));
+const globalState = globalThis as TextGlobals & { __opendocTemplateValidated?: boolean; __opendocDataFile?: string; __opendocRoot?: string; __opendocDocumentDirectory?: string; __opendocDocumentAssets?: DocumentAssets; __opendocCapture?: { format: DocumentFormat; slides: SlideInfo[]; themeId: string; meta: DocumentMeta; blocks: Record<string, BlockInfo>; provenance?: Partial<DocumentProvenance>; media?: MediaUse[]; assets?: AssetUse[]; assetBindings?: DocumentAssets; assetDependencies?: string[]; textTargets?: TextTarget[] } };
+globalState.__opendocRoot = root;
+globalState.__opendocDocumentDirectory = dirname(entry);
+const documentDirectory = realpathSync(dirname(entry));
+const resolvers = new Map<string, TextSourceResolver>();
+const fieldResolvers = new Map<string, ReturnType<typeof createJsonTextSourceResolver>>();
+function documentFile(file: string) {
+  try {
+    const absolute = realpathSync(resolve(root, file));
+    return absolute.startsWith(documentDirectory + sep) ? absolute : undefined;
+  } catch { return undefined; }
+}
+globalState.__opendocResolveTextSource = (location, slot, childIndex) => {
+  const absolute = documentFile(location.file);
+  if (!absolute || !/\.[cm]?[jt]sx?$/.test(absolute)) return undefined;
+  let resolver = resolvers.get(absolute);
+  if (!resolver) { resolver = createTextSourceResolver(relative(root, absolute), overrides.get(absolute)?.contents ?? readFileSync(absolute, 'utf8')); resolvers.set(absolute, resolver); }
+  return originalBinding(resolver.resolveAt(location.line, location.column, slot, childIndex), overrides.get(absolute));
+};
+globalState.__opendocResolveTextField = field => {
+  const absolute = globalState.__opendocDataFile && documentFile(globalState.__opendocDataFile);
+  if (!absolute || !absolute.endsWith('.json')) return undefined;
+  let resolver = fieldResolvers.get(absolute);
+  if (!resolver) { resolver = createJsonTextSourceResolver(relative(root, absolute), overrides.get(absolute)?.contents ?? readFileSync(absolute, 'utf8')); fieldResolvers.set(absolute, resolver); }
+  return originalBinding(resolver(field), overrides.get(absolute));
+};
+
+function pagesFromLayout(layout: LayoutInfo, blocks: Record<string, BlockInfo>) {
+  return layout.pages.map(page => {
+    const groups = new Map<string, Fragment>();
+    function visit(node: ElementInfo, inherited?: string) {
+      const file = node.sourceLocation?.file;
+      const id = file?.startsWith('opendoc:block:') ? file.slice('opendoc:block:'.length) : inherited;
+      if (id && blocks[id]) {
+        if (node.textContent) blocks[id].text += `${node.textContent} `;
+        if (node.width > 0 && node.height > 0) {
+          const prev = groups.get(id);
+          const x = node.x, y = node.y;
+          const right = node.x + node.width, bottom = node.y + node.height;
+          if (prev) {
+            const newRight = Math.max(prev.x + prev.width, right), newBottom = Math.max(prev.y + prev.height, bottom);
+            prev.x = Math.min(prev.x, x); prev.y = Math.min(prev.y, y);
+            prev.width = newRight - prev.x; prev.height = newBottom - prev.y;
+          } else groups.set(id, { id, x, y, width: right - x, height: bottom - y });
+        }
+      }
+      for (const child of node.children) visit(child, id);
+    }
+    for (const node of page.elements) visit(node);
+    return { width: page.width, height: page.height, fragments: [...groups.values()] };
+  });
+}
+
+try {
+  const entryPath = relative(root, entry).split(sep).join('/');
+  const themePreview = /^themes\/([a-z0-9-]+)\/preview\.tsx$/.exec(entryPath)?.[1];
+  const templatePreview = /^templates\/[a-z0-9-]+\/preview\.tsx$/.test(entryPath);
+  if (themePreview || templatePreview) {
+    const themeId = themePreview ?? 'neutral';
+    const bindings = resolveThemeAssets(root, themeId);
+    globalState.__opendocDocumentAssets = bindings;
+    // Adapt the module in this isolated worker before a specimen's template
+    // factory executes. Shared exported aliases keep the same object identity.
+    const themeEntry = realpathSync(resolve(root, 'themes', themeId, 'index.ts'));
+    const original = readFileSync(themeEntry, 'utf8');
+    overrides.set(themeEntry, { file: themeEntry, originalDigest: createHash('sha256').update(original).digest('hex'), replacements: [],
+      contents: `${original}\nimport { withDocumentAssets as __opendocWithAssets } from ${JSON.stringify(runtimeSource('assets/index.ts'))};\nObject.assign(theme, __opendocWithAssets(theme, ${JSON.stringify(bindings)}));\n` });
+  } else {
+    globalState.__opendocDocumentAssets = readDocumentAssetsAt(root, dirname(entry));
+  }
+  const source = `
+    import Entry, * as definition from ${JSON.stringify(entry)};
+    import { prepareDocument } from ${JSON.stringify(runtimeSource('document/index.tsx'))};
+    export default function OpenDocRender() {
+      globalThis.__opendocDataFile = definition.provenance?.dataFile;
+      const input = typeof Entry === 'function' ? Entry() : Entry;
+      const prepared = prepareDocument(input);
+      globalThis.__opendocCapture = { format: prepared.format, slides: prepared.slides, themeId: prepared.themeId, meta: definition.meta, blocks: prepared.blocks, provenance: definition.provenance, media: prepared.media, assets: prepared.assets, assetBindings: prepared.assetBindings, assetDependencies: prepared.assetDependencies, textTargets: prepared.textTargets };
+      return prepared.element;
+    }
+  `;
+  const result = await renderDocumentSource(source, entry, overrides);
+  if (sourceOverrides.some(override => override.file.endsWith('.json')) && !globalState.__opendocTemplateValidated) throw new Error('The document does not declare a data parser for these corrections. Ask your agent to change it.');
+  const capture = globalState.__opendocCapture;
+  if (!capture?.meta || typeof capture.meta.title !== 'string' || !capture.meta.title.trim()) throw new Error('Export meta with a nonempty title.');
+  if (capture.meta.kind !== undefined && (typeof capture.meta.kind !== 'string' || !capture.meta.kind.trim())) throw new Error('meta.kind must be a nonempty descriptive label when supplied.');
+  if (typeof capture.meta.description !== 'string') throw new Error('meta.description must be a string.');
+  if (typeof capture.meta.theme !== 'string' || !capture.meta.theme.trim()) throw new Error('meta.theme must identify a theme.');
+  if (capture.meta.theme !== capture.themeId) throw new Error('meta.theme must match the theme used by Document.');
+  if (capture.meta.author !== undefined && typeof capture.meta.author !== 'string') throw new Error('meta.author must be a string.');
+  const provenance: DocumentProvenance = { entry: relative(root, entry) };
+  if (capture.provenance !== undefined) {
+    if (!capture.provenance || typeof capture.provenance !== 'object' || Array.isArray(capture.provenance)) throw new Error('provenance must identify local template and data files.');
+    for (const key of ['template', 'dataFile'] as const) {
+      const value = capture.provenance[key];
+      if (value === undefined) continue;
+      if (typeof value !== 'string' || !value || value.startsWith('/') || value.split(/[\\/]/).includes('..')) throw new Error(`provenance.${key} must be a workspace-relative file path.`);
+      await containedFile(root, resolve(root, value));
+      provenance[key] = value;
+    }
+  }
+  const ownerId = /^documents\/([^/]+)\/index\.tsx$/.exec(entryPath)?.[1];
+  if (ownerId) {
+    const manifest = await readProjects(root);
+    const format = manifest.formats && Object.hasOwn(manifest.formats, ownerId) ? manifest.formats[ownerId] : 'document';
+    if (capture.format !== format) throw new Error(`This ${format} must use the ${format === 'presentation' ? 'Presentation' : 'Document'} root. Create presentations with --format presentation.`);
+  }
+  const textTargets = capture.textTargets ?? [];
+  attachTextLines(result.layout, textTargets);
+  const pages = pagesFromLayout(result.layout, capture.blocks);
+  if (!pages.length) throw new Error('The document rendered no pages.');
+  for (const block of Object.values(capture.blocks)) {
+    block.text = block.text.trim();
+    if (block.source) block.source.file = relative(root, block.source.file);
+  }
+  if (capture.format === 'presentation') assertSlideLayout(result.layout, capture.slides, capture.blocks);
+  const { issues, outline } = inspectLayout(result.layout, capture.blocks);
+  if (capture.format === 'presentation') {
+    // Standalone titles and low captions are intentional slide compositions.
+    for (let index = issues.length - 1; index >= 0; index--) if (issues[index].code === 'stranded-heading') issues.splice(index, 1);
+    for (const issue of issues) {
+      const slide = capture.slides[(issue.page ?? 1) - 1];
+      issue.message = `Slide ${slide?.id ?? issue.page}: ${issue.message.replace(/page (\d+)/g, 'slide $1').replace('or allow the content to flow onto another page', 'or split it into explicit slides')}`;
+    }
+  }
+  for (const message of result.warnings) issues.push({ code: 'renderer-warning', severity: 'warning', message });
+  assertLayoutSafe(issues);
+  const artifact: RenderArtifact = { meta: capture.meta, format: capture.format, ...(capture.format === 'presentation' ? { slides: capture.slides } : {}), media: capture.media ?? [], assets: capture.assets ?? [], assetBindings: capture.assetBindings, assetDependencies: capture.assetDependencies ?? [], textTargets, blocks: capture.blocks, pages, provenance, issues, outline, hash: createHash('sha256').update(result.pdf).digest('hex'), renderedAt: new Date().toISOString() };
+  await mkdir(destination, { recursive: true });
+  await writeFile(resolve(destination, 'document.pdf'), result.pdf);
+  await writeFile(resolve(destination, 'artifact.json'), JSON.stringify(artifact, null, 2));
+  await writeFile(resolve(destination, 'layout.json'), JSON.stringify(result.layout));
+  if (capture.format === 'presentation') await writeFile(resolve(destination, 'presentation.json'), JSON.stringify({ version: 1, hash: artifact.hash, meta: capture.meta, slides: capture.slides, doc: result.doc, layout: result.layout }));
+  process.send?.({ ok: true });
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  process.send?.({ ok: false, error: message, ...(error instanceof RenderFailure ? { issues: error.issues } : {}) });
+  if (!process.send) console.error(message);
+  process.exitCode = 1;
+}

package/src/server/workspace.ts

@@ -0,0 +1,242 @@
+import { EventEmitter } from 'node:events';
+import { access, readdir, rm } from 'node:fs/promises';
+import { relative, resolve, sep } from 'node:path';
+import { renderOnce, validId, documentEntry } from './render';
+import { atomicWrite } from './files';
+import { themePaths, readThemePaths } from './themes';
+import { readProjects } from './projects';
+import { readComments } from './comments';
+import { documentDependencies, includesDependency, type DocumentDependencies, isRenderRuntimePath, isThemeAssetDefaultsPath } from './dependencies';
+import { readMedia, mediaFreshness } from '../media/files';
+import { readAssetHead, readAssetRevision, readDocumentAssets, readThemeAssetDefaults } from '../assets/files';
+import { documentName, getBlock, type DocumentState, type WorkspaceContext, type RenderArtifact } from '../shared/types';
+import { getEditableSelection, getTextTarget, resolveCommentAnchor } from '../shared/anchors';
+import type { ManualEditSummary } from '../shared/selection';
+
+export class Workspace extends EventEmitter {
+  states = new Map<string, DocumentState>();
+  outputs = new Map<string, { directory: string; artifact: RenderArtifact }[]>();
+  context: WorkspaceContext = { documentId: null, blockId: null, page: 1 };
+  manualEditSummary?: (id: string) => Promise<ManualEditSummary | undefined>;
+  private running = new Set<string>();
+  private pending = new Set<string>();
+  private scheduled = new Set<string>();
+  private dependencies = new Map<string, DocumentDependencies>();
+  private debounce?: ReturnType<typeof setTimeout>;
+  private contextWrites = Promise.resolve();
+  private closed = false;
+  constructor(public root: string, public timeoutMs = 30_000) { super(); }
+  list() { return [...this.states.values()].sort((a, b) => documentName(a).localeCompare(documentName(b))); }
+  async discover() {
+    const manifest = await readProjects(this.root);
+    const entries = await readdir(resolve(this.root, 'documents'), { withFileTypes: true }).catch(error => { if (error.code === 'ENOENT') return []; throw error; });
+    const found = new Set<string>();
+    for (const dir of entries) {
+      if (!dir.isDirectory() || !validId(dir.name)) continue;
+      try { await access(resolve(this.root, 'documents', dir.name, 'index.tsx')); await documentEntry(this.root, dir.name); } catch { continue; }
+      found.add(dir.name);
+      if (!this.states.has(dir.name)) this.states.set(dir.name, { id: dir.name, status: 'rendering', revision: 0 });
+      const state = this.states.get(dir.name)!;
+      const format = manifest.formats && Object.hasOwn(manifest.formats, dir.name) ? manifest.formats[dir.name] : 'document';
+      const formatChanged = state.format !== undefined && state.format !== format;
+      state.format = format;
+      if (formatChanged) this.invalidate(dir.name);
+      this.states.get(dir.name)!.projectId = Object.hasOwn(manifest.assignments, dir.name) ? manifest.assignments[dir.name] : null;
+      this.states.get(dir.name)!.name = manifest.names && Object.hasOwn(manifest.names, dir.name) ? manifest.names[dir.name] : undefined;
+    }
+    for (const id of this.states.keys()) if (!found.has(id)) {
+      this.states.delete(id); this.pending.delete(id); this.scheduled.delete(id); this.dependencies.delete(id);
+      for (const out of this.outputs.get(id) ?? []) await rm(out.directory, { recursive: true, force: true });
+      this.outputs.delete(id);
+      if (this.context.documentId === id) this.context = { documentId: null, blockId: null, page: 1 };
+    }
+    return found;
+  }
+  async refresh() {
+    if (this.closed) return;
+    clearTimeout(this.debounce); this.scheduled.clear();
+    for (const id of await this.discover()) this.invalidate(id);
+    this.changed();
+  }
+  async refreshProjects() { await this.discover(); this.changed(); }
+  private stale(id: string) {
+    const state = this.states.get(id);
+    if (!state) return;
+    state.revision++; state.status = 'rendering'; delete state.error;
+    // The edited entry may now import files absent from its previous graph.
+    this.dependencies.delete(id);
+  }
+  invalidate(id: string) {
+    if (!this.states.has(id)) return;
+    this.stale(id); this.pending.add(id); this.pump();
+  }
+  /** Disable affected exports immediately; queue costly discovery and rendering after a short quiet period. */
+  noteChange(file: string) {
+    if (this.closed) return [];
+    const path = resolve(this.root, file);
+    const parts = relative(this.root, path).split(sep);
+    const owner = parts[0] === 'documents' && validId(parts[1] ?? '') ? parts[1] : undefined;
+    const sharedRuntime = isRenderRuntimePath(this.root, path) || (parts[0] === 'documents' && parts.length === 1);
+    const affected: string[] = [];
+    const dependencyUsers = [...this.dependencies].filter(([, dependencies]) => includesDependency(dependencies, path)).map(([id]) => id);
+    for (const id of this.states.keys()) {
+      const dependencies = this.dependencies.get(id);
+      const themeInput = parts[0] === 'themes' && parts[1] === this.states.get(id)?.artifact?.meta.theme && !isThemeAssetDefaultsPath(this.root, path);
+      const match = owner
+        ? id === owner || !dependencies || dependencies.readsFiles || dependencyUsers.includes(id)
+        : sharedRuntime || themeInput || !dependencies || dependencies.readsFiles || dependencyUsers.includes(id);
+      if (match) {
+        this.stale(id); this.pending.delete(id); this.scheduled.add(id); affected.push(id);
+      }
+    }
+    // A new document has no state yet; discovery picks it up when changes settle.
+    if (owner) this.scheduled.add(owner);
+    if (!affected.length && !owner) return affected;
+    clearTimeout(this.debounce);
+    this.debounce = setTimeout(() => { void this.flushChanges().catch(error => this.emit('workspace-error', error)); }, 180);
+    this.changed();
+    return affected;
+  }
+  async flushChanges() {
+    if (this.closed) return;
+    clearTimeout(this.debounce); this.debounce = undefined;
+    const scheduled = new Set(this.scheduled); this.scheduled.clear();
+    const known = new Set(this.states.keys());
+    const found = await this.discover();
+    for (const id of found) if ((scheduled.has(id) || !known.has(id)) && !this.scheduled.has(id)) this.pending.add(id);
+    this.changed(); this.pump();
+  }
+  private pump() {
+    if (this.closed) return;
+    for (const id of this.pending) {
+      if (this.running.size >= 2) break;
+      if (this.running.has(id)) continue;
+      this.pending.delete(id); this.running.add(id);
+      void this.run(id);
+    }
+  }
+  private async run(id: string) {
+    const state = this.states.get(id)!;
+    const revision = state.revision;
+    const dependencyResult = documentEntry(this.root, id).then(entry => documentDependencies(this.root, entry)).catch(() => null);
+    try {
+      const result = await renderOnce(this.root, id, this.timeoutMs);
+      const dependencies = await dependencyResult;
+      if (this.closed || this.states.get(id) !== state || revision !== state.revision) {
+        await rm(result.directory, { recursive: true, force: true });
+      } else {
+        const previous = this.outputs.get(id) ?? [];
+        this.outputs.set(id, [result, ...previous].slice(0, 2));
+        if (dependencies) {
+          for (const file of result.artifact.assetDependencies ?? []) dependencies.files.add(resolve(this.root, file));
+          this.dependencies.set(id, dependencies);
+        } else this.dependencies.delete(id);
+        state.artifact = result.artifact; state.status = 'ready'; delete state.error;
+        // Publish state before asynchronous cleanup; a newer invalidation must stay authoritative.
+        for (const old of previous.slice(1)) await rm(old.directory, { recursive: true, force: true }).catch(error => this.emit('workspace-error', error));
+      }
+    } catch (error) {
+      const dependencies = await dependencyResult;
+      if (this.states.get(id) === state && revision === state.revision) {
+        // Retain a completed current graph even after a missing/corrupt pinned asset fails rendering.
+        // An unresolved import has no trustworthy graph and remains conservatively invalidatable.
+        if (dependencies) this.dependencies.set(id, dependencies); else this.dependencies.delete(id);
+        state.status = 'error'; state.error = error instanceof Error ? error.message : String(error);
+      }
+    } finally { this.running.delete(id); this.changed(); this.pump(); }
+  }
+  output(id: string, hash: string) { return this.outputs.get(id)?.find(out => out.artifact.hash === hash); }
+  changed() { this.emit('change'); void this.writeContext().catch(error => this.emit('workspace-error', error)); }
+  async setContext(context: WorkspaceContext) { this.context = context; await this.writeContext(); }
+  writeContext() {
+    this.contextWrites = this.contextWrites.catch(() => {}).then(async () => {
+      const state = this.context.documentId ? this.states.get(this.context.documentId) : undefined;
+      if (state && this.manualEditSummary) state.manualEdit = await this.manualEditSummary(state.id);
+      const manifest = await readProjects(this.root);
+      const projectId = state ? state.projectId : this.context.documentId ? null : this.context.projectId;
+      const project = manifest.projects.find(project => project.id === projectId) ?? null;
+      let comments: unknown[] = [], commentsError: string | undefined;
+      if (state) try { comments = (await readComments(this.root, state.id)).filter(c => c.status === 'open').map(c => {
+        const resolved = resolveCommentAnchor(state.artifact, c);
+        return { ...c, targetAvailable: resolved.status !== 'missing', anchorStatus: resolved.status, selection: resolved.selection };
+      }); }
+      catch (e) { commentsError = String(e); }
+      let selectedMedia: unknown = null;
+      if (state && this.context.mediaId) {
+        const folder = `documents/${state.id}/media/${this.context.mediaId}`;
+        try { const asset = readMedia(resolve(this.root, 'documents', state.id), this.context.mediaId); selectedMedia = { folder, meta: asset.meta, ...mediaFreshness(asset) }; }
+        catch (error) { selectedMedia = { folder, error: (error as Error).message }; }
+      }
+      let selectedAsset: unknown = null;
+      if (this.context.selectedAsset) {
+        const selection = this.context.selectedAsset;
+        const folder = `assets/${selection.kind === 'logo' ? 'logos' : 'fonts'}/${selection.id}`;
+        try {
+          const head = await readAssetHead(this.root, selection.kind, selection.id);
+          const asset = await readAssetRevision(this.root, selection.kind, selection.id, selection.revision ?? head.revision);
+          selectedAsset = { ...selection, folder, asset, head,
+            variation: asset.kind === 'logo' && selection.variation ? asset.variations.find(item => item.id === selection.variation) ?? null : undefined,
+            face: asset.kind === 'font' && selection.face ? asset.faces.find(item => item.id === selection.face) ?? null : undefined,
+          };
+        } catch (error) { selectedAsset = { ...selection, folder, error: (error as Error).message }; }
+      }
+      let documentAssets: unknown = null;
+      if (state) {
+        const file = `documents/${state.id}/assets.json`;
+        try { documentAssets = { file, bindings: await readDocumentAssets(this.root, state.id), saved: await access(resolve(this.root, file)).then(() => true, () => false) }; }
+        catch (error) { documentAssets = { file, error: (error as Error).message }; }
+      }
+      const selectedBlock = getBlock(state?.artifact, this.context.blockId);
+      const selection = this.context.selection;
+      const selectedTarget = getTextTarget(state?.artifact, selection?.targetId);
+      const selectionCurrent = !!state && !!selection && (!selection?.renderHash || selection.renderHash === state.artifact?.hash)
+        && (selection?.revision === undefined || selection.revision === state.revision) && state.status === 'ready';
+      const editable = selectionCurrent ? getEditableSelection(state?.artifact, selection) : undefined;
+      const themeId = state?.artifact?.meta.theme ?? this.context.themeId ?? project?.defaultTheme ?? null;
+      const theme = themeId ? await readThemePaths(this.root, themeId).then(
+        paths => ({ id: themeId, ...paths, available: true }),
+        () => ({ id: themeId, ...themePaths(themeId), available: false }),
+      ) : null;
+      const assetDefaults = themeId ? await Promise.resolve().then(() => readThemeAssetDefaults(this.root, themeId)).then(
+        choices => ({ file: `themes/${themeId}/assets.json`, choices, appliesTo: 'new-documents' }),
+        error => ({ file: `themes/${themeId}/assets.json`, error: (error as Error).message, appliesTo: 'new-documents' }),
+      ) : undefined;
+      await atomicWrite(resolve(this.root, '.opendoc/current.json'), JSON.stringify({
+        ...this.context, updatedAt: new Date().toISOString(),
+        projectId: project?.id ?? null, project,
+        themeId, theme: theme ? { ...theme, assetDefaults } : null,
+        status: state?.status ?? 'idle', error: state?.error, revision: state?.revision,
+        format: state?.format,
+        slides: state?.artifact?.slides,
+        title: state?.artifact?.meta.title,
+        name: state ? documentName(state) : undefined,
+        provenance: state ? state.artifact?.provenance ?? { entry: `documents/${state.id}/index.tsx` } : null,
+        renderHash: state?.artifact?.hash, source: selectedBlock?.source ?? null,
+        selectedBlock: selectedBlock ?? null,
+        selection: selection ?? null,
+        selectionCurrent,
+        selectedText: selectedTarget ? {
+          targetId: selectedTarget.id, blockId: selectedTarget.blockId, slot: selectedTarget.slot,
+          text: selectedTarget.text.slice(0, 1200),
+          editable: !!editable,
+          source: editable ? { file: editable.source.file, digest: editable.source.digest, start: editable.source.start, end: editable.source.end, linkedOccurrences: editable.source.linkedOccurrences } : null,
+        } : null,
+        manualEdit: { editing: this.context.editing ?? false, pendingEdits: this.context.pendingEdits ?? 0, draftPreview: this.context.draftPreview ?? false, lastCorrection: state?.manualEdit ?? null, renderStatus: state?.status ?? 'idle' },
+        selectedMedia,
+        selectedAsset,
+        documentAssets,
+        renderedAssets: state?.artifact ? { uses: state.artifact.assets ?? [], bindings: state.artifact.assetBindings ?? null, current: state.status === 'ready', renderHash: state.artifact.hash } : null,
+        materials: state ? { media: `documents/${state.id}/media`, usedMedia: state.artifact?.media ?? [] } : null,
+        pendingComments: comments, commentsError,
+      }, null, 2) + '\n');
+    });
+    return this.contextWrites;
+  }
+  async close() {
+    this.closed = true; clearTimeout(this.debounce); this.pending.clear(); this.scheduled.clear();
+    while (this.running.size) await new Promise(r => setTimeout(r, 30));
+    await this.contextWrites;
+    await Promise.all([...this.outputs.values()].flat().map(output => rm(output.directory, { recursive: true, force: true })));
+    this.outputs.clear();
+  }
+}