@ryanyahya/opendoc 0.4.0

package/src/server/templates-cli.ts

@@ -0,0 +1,51 @@
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parseArgs } from 'node:util';
+import { TemplateCatalog, readTemplate, readTemplateGuide, templateFile } from './templates';
+import { captureEntryExportInputs } from './export-inputs';
+import { ExportChangedError, publishPDF } from './export-file';
+import { RenderFailure } from './render-error';
+
+const usage = 'Usage: npx opendoc templates list [--json]\n       npx opendoc templates inspect <id> | check <id> | preview <id> [--json]\n       Create an instance with npx opendoc create --template <id> --project <project-id> --title "Title".';
+
+export async function runTemplatesCli(args: string[], root = process.cwd()): Promise<void> {
+  const { values, positionals } = parseArgs({ args: args[0] === '--' ? args.slice(1) : args, allowPositionals: true, options: {
+    json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' },
+  } });
+  if (values.help) { console.log(values.json ? JSON.stringify({ usage }, null, 2) : usage); return; }
+  const [command = 'list', id] = positionals;
+  if (command === 'list' && positionals.length <= 1) {
+    const catalog = new TemplateCatalog(root);
+    try {
+      console.log(JSON.stringify((await catalog.list()).map(({ id, descriptor, error }) => ({ id, ...descriptor, ...(error ? { error } : {}) })), null, 2));
+    } finally { await catalog.close(); }
+  } else if (command === 'inspect' && id && positionals.length === 2) {
+    const descriptor = await readTemplate(root, id);
+    const guide = await readTemplateGuide(root, id);
+    const paths = {
+      definition: `templates/${id}/index.tsx`, descriptor: `templates/${id}/template.json`,
+      guide: `templates/${id}/AGENTS.md`, preview: `templates/${id}/preview.tsx`, starter: `templates/${id}/starter.tsx`,
+    };
+    console.log(JSON.stringify({ id, ...descriptor, paths, guide }, null, 2));
+  } else if ((command === 'check' || command === 'preview') && id && positionals.length === 2) {
+    const catalog = new TemplateCatalog(root);
+    try {
+      const unchanged = await captureEntryExportInputs(root, await templateFile(root, id, 'preview.tsx'));
+      const descriptor = await readTemplate(root, id);
+      await readTemplateGuide(root, id);
+      const preview = await catalog.preview(id);
+      if (!preview.artifact) throw new RenderFailure(preview.error ?? 'Template preview failed.', preview.issues);
+      if (!unchanged()) throw new ExportChangedError();
+      const artifact = preview.artifact;
+      const output = command === 'preview' ? await publishPDF(root, id, await catalog.pdf(id, artifact.hash), unchanged, 'templates') : undefined;
+      console.log(JSON.stringify({ id, name: descriptor.name, status: 'ready', format: artifact.format ?? 'document', pages: artifact.pages.length, hash: artifact.hash, issues: artifact.issues ?? [], ...(output ? { output } : {}), review: 'Inspect every PDF page; automated checks do not establish visual quality.' }, null, 2));
+    } catch (error) {
+      if (error instanceof ExportChangedError) throw new Error('The template changed while preparing its preview. Retry after edits finish; no template PDF was replaced.', { cause: error });
+      throw error;
+    } finally { await catalog.close(); }
+  } else throw new Error(usage);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  runTemplatesCli(process.argv.slice(2)).catch(error => { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; });
+}

package/src/server/templates.ts

@@ -0,0 +1,186 @@
+import { lstat, readdir, readFile, rm, stat } from 'node:fs/promises';
+import { relative, resolve, sep } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { documentDependencies, includesDependency, type DocumentDependencies, isRenderRuntimePath } from './dependencies';
+import type { TemplateDescriptor, TemplateItem, TemplatePreview } from '../shared/templates';
+import { containedFile } from './files';
+import { RenderFailure } from './render-error';
+import { renderEntry, validId } from './render';
+import { createDocumentFromFiles } from './create';
+
+export async function templateFile(root: string, id: string, name: string) {
+  if (!validId(id)) throw new Error('Invalid template ID.');
+  const folder = await containedFile(resolve(root, 'templates'), resolve(root, 'templates', id));
+  return containedFile(folder, resolve(folder, name));
+}
+
+export async function readTemplateGuide(root: string, id: string): Promise<string> {
+  const file = await templateFile(root, id, 'AGENTS.md');
+  const info = await stat(file);
+  if (!info.isFile()) throw new Error('The template guide must be a Markdown file.');
+  if (info.size > 128_000) throw new Error('This template guide is too large to display.');
+  return readFile(file, 'utf8');
+}
+
+export async function readTemplate(root: string, id: string): Promise<TemplateDescriptor> {
+  const path = await templateFile(root, id, 'template.json');
+  if ((await stat(path)).size > 32_000) throw new Error('Template description is too large.');
+  const data = JSON.parse(await readFile(path, 'utf8')) as Record<string, unknown>;
+  if (!data || typeof data !== 'object' || Array.isArray(data) || Object.keys(data).some(key => !['name', 'description', 'format', 'structure', 'documentFormat'].includes(key))) throw new Error('Invalid template description.');
+  if (data.documentFormat !== undefined && data.documentFormat !== 'document' && data.documentFormat !== 'presentation') throw new Error('template.documentFormat must be document or presentation.');
+  for (const key of ['name', 'description', 'format']) {
+    if (typeof data[key] !== 'string' || !(data[key] as string).trim() || (data[key] as string).length > (key === 'description' ? 600 : 120)) throw new Error(`template.${key} needs a short, nonempty description.`);
+  }
+  if (!Array.isArray(data.structure) || !data.structure.length || data.structure.length > 8 || data.structure.some(item => typeof item !== 'string' || !item.trim() || item.length > 240)) throw new Error('template.structure needs one to eight short layout notes.');
+  await Promise.all(['index.tsx', 'preview.tsx', 'starter.tsx', 'AGENTS.md'].map(name => templateFile(root, id, name)));
+  return data as unknown as TemplateDescriptor;
+}
+
+type Preview = TemplatePreview & { directory?: string };
+
+/** Discover descriptions immediately; render only requested previews, with two workers. */
+export class TemplateCatalog {
+  private version = 0;
+  private globalVersion = 0;
+  private versions = new Map<string, number>();
+  private session = randomUUID();
+  private summaries?: { version: number; result: Promise<TemplateItem[]> };
+  private previews = new Map<string, { version: string; result: Promise<Preview> }>();
+  private dependencies = 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); else this.dependencies.clear();
+    if (id) this.versions.set(id, (this.versions.get(id) ?? 0) + 1);
+    else this.globalVersion++;
+  }
+  private revision(id: string) { return `${this.session}:${id}:${this.globalVersion}:${this.versions.get(id) ?? 0}`; }
+  async noteChange(file: string) {
+    const path = resolve(this.root, file);
+    const parts = relative(this.root, path).split(sep);
+    if (parts[0] === 'templates') this.version++;
+    const entries = await readdir(resolve(this.root, 'templates'), { withFileTypes: true }).catch(() => []);
+    const ids = new Set([...entries.filter(entry => entry.isDirectory() && validId(entry.name)).map(entry => entry.name), ...this.previews.keys()]);
+    for (const id of ids) {
+      const dependencies = this.dependencies.get(id);
+      if (isRenderRuntimePath(this.root, path) || (parts[0] === 'themes' && parts[1] === 'neutral') || (parts[0] === 'templates' && (!parts[1] || parts[1] === id))
+        || !dependencies || dependencies.readsFiles || includesDependency(dependencies, path)) this.invalidate(id);
+    }
+  }
+  async list(): Promise<TemplateItem[]> {
+    if (!this.summaries || this.summaries.version !== this.version) {
+      const version = this.version;
+      const result = (async () => {
+        const entries = await readdir(resolve(this.root, 'templates'), { withFileTypes: true }).catch(error => { if (error.code === 'ENOENT') return []; throw error; });
+        return Promise.all(entries.filter(folder => folder.isDirectory() && validId(folder.name)).sort((a, b) => a.name.localeCompare(b.name)).map(async folder => {
+          try { return { id: folder.name, descriptor: await readTemplate(this.root, folder.name), revision: this.revision(folder.name) }; }
+          catch (error) { return { id: folder.name, descriptor: { name: folder.name, description: 'This template needs attention.', format: '', structure: [] }, revision: this.revision(folder.name), error: error instanceof Error ? error.message : String(error) }; }
+        }));
+      })();
+      this.summaries = { version, result };
+    }
+    const snapshot = this.summaries;
+    try {
+      const items = await snapshot.result;
+      return snapshot.version === this.version ? items : this.list();
+    } catch (error) { if (this.summaries === snapshot) this.summaries = undefined; throw error; }
+  }
+  private async render(id: string, version: string): Promise<Preview> {
+    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 template catalog is closed.');
+      const descriptor = await readTemplate(this.root, id);
+      const entry = await templateFile(this.root, id, 'preview.tsx');
+      const dependencies = await documentDependencies(this.root, entry).catch(() => undefined);
+      const rendered = await renderEntry(this.root, entry, `template-${id}`);
+      directory = rendered.directory;
+      if (rendered.artifact.meta.theme !== 'neutral') throw new Error('Template previews must use the Neutral theme.');
+      if (rendered.artifact.format !== (descriptor.documentFormat ?? 'document')) throw new Error('The template preview must use the root matching its documentFormat.');
+      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<Preview> {
+    if (!validId(id)) throw new Error('Invalid template ID.');
+    if (this.closed) throw new Error('The template 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);
+    if (result.error && this.previews.get(id) === snapshot) this.previews.delete(id);
+    return result;
+  }
+  async preview(id: string): Promise<TemplatePreview> {
+    const { directory: _directory, ...item } = await this.current(id);
+    return item;
+  }
+  async pdf(id: string, hash: string) {
+    const item = await this.current(id);
+    if (!item.directory || item.artifact?.hash !== hash) throw new Error('This template preview changed. Reload Templates.');
+    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();
+  }
+}
+
+export async function createFromTemplate(root: string, id: string, input: unknown) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error('Provide a title and a project.');
+  const value = input as Record<string, unknown>;
+  if (Object.keys(value).some(key => !['title', 'theme', 'id', 'projectId', 'format'].includes(key))) throw new Error('Only title, project, theme, format, and an optional document ID are accepted.');
+  if (typeof value.title !== 'string' || (value.id !== undefined && typeof value.id !== 'string')) throw new Error('Give your document a title.');
+  const descriptor = await readTemplate(root, id);
+  const format = descriptor.documentFormat ?? 'document';
+  if (value.format !== undefined && value.format !== format) throw new Error(`This template creates a ${format}. Choose a matching template or omit --format.`);
+  const starter = await readFile(await templateFile(root, id, 'starter.tsx'), 'utf8');
+  const created = await createDocumentFromFiles(root, {
+    title: value.title, id: value.id as string | undefined, projectId: value.projectId as string, theme: value.theme as string | null | undefined, format,
+  }, async (documentId, chosenTheme) => {
+    const replacements: Record<string, string> = { '__OPENDOC_TITLE__': (value.title as string).trim(), '__OPENDOC_THEME__': chosenTheme ?? 'neutral', '__OPENDOC_DOCUMENT_ID__': documentId, '__OPENDOC_THEME_MODULE__': './theme' };
+    const files: Record<string, string> = {};
+    // A data-bound template gives each instance its own ordinary JSON input.
+    const dataPath = resolve(root, 'templates', id, 'data.json');
+    const dataStat = await lstat(dataPath).catch(error => { if (error.code === 'ENOENT') return undefined; throw error; });
+    let rawData = '';
+    if (dataStat) {
+      const dataFile = await templateFile(root, id, 'data.json');
+      if ((await stat(dataFile)).size > 128_000) throw new Error('Template starter data is too large.');
+      rawData = await readFile(dataFile, 'utf8');
+      const data = JSON.parse(rawData.replace(/"(__OPENDOC_TITLE__|__OPENDOC_THEME__)"/g, (_match, marker: string) => JSON.stringify(replacements[marker])));
+      if (!data || typeof data !== 'object' || Array.isArray(data)) throw new Error('Template starter data must be a JSON object.');
+      files['data.json'] = `${JSON.stringify(data, null, 2)}\n`;
+    }
+    for (const marker of ['__OPENDOC_TITLE__', '__OPENDOC_THEME__']) {
+      if (!(starter + rawData).includes(JSON.stringify(marker))) throw new Error(`Template starter is missing its ${marker === '__OPENDOC_TITLE__' ? 'title' : 'theme'} placeholder.`);
+    }
+    if (starter.split('"__OPENDOC_THEME_MODULE__"').length !== 2) throw new Error('Template starter needs exactly one quoted theme module placeholder.');
+    // A single pass over the original source never reinterprets literal user text.
+    files['index.tsx'] = starter.replace(/"(__OPENDOC_TITLE__|__OPENDOC_THEME__|__OPENDOC_DOCUMENT_ID__|__OPENDOC_THEME_MODULE__)"/g, (_match, marker: string) => JSON.stringify(replacements[marker]));
+    return files;
+  });
+  return { id: created.id, title: created.title, entry: created.entry, projectId: created.projectId, template: id, format };
+}

package/src/server/text-layout.ts

@@ -0,0 +1,41 @@
+import type { ElementInfo, LayoutInfo } from '@formepdf/core';
+import type { TextTarget } from '../shared/selection';
+
+/** Only normalize layout whitespace; never guess through changed words. */
+function comparable(text: string) {
+  const positions: number[] = [], chars: string[] = [];
+  for (let index = 0; index < text.length; index++) {
+    if (/\s/u.test(text[index]) || text[index] === '\u00ad') continue;
+    positions.push(index); chars.push(text[index]);
+  }
+  return { text: chars.join(''), positions };
+}
+
+/** Attach line geometry to the logical text tree, including continued pages. */
+export function attachTextLines(layout: LayoutInfo, targets: TextTarget[]) {
+  const values = targets.map(target => comparable(target.text));
+  const cursors = targets.map(() => 0);
+  const blocked = targets.map(() => false);
+  for (const [pageIndex, page] of layout.pages.entries()) {
+    const visit = (node: ElementInfo, inherited?: number) => {
+      const source = node.sourceLocation;
+      const index = source?.file.startsWith('opendoc:block:') ? source.line - 1 : -1;
+      const candidate = targets[index];
+      const own = /^(Text|H[1-6])$/.test(node.nodeType) && candidate && source?.file === `opendoc:block:${candidate.blockId}` ? index : inherited;
+      if (node.nodeType === 'TextLine' && own !== undefined && node.textContent && !blocked[own]) {
+        const target = targets[own], value = values[own];
+        let line = comparable(node.textContent).text;
+        let cursor = cursors[own];
+        if (cursor === value.text.length) cursor = 0; // repeated table headers / page furniture
+        if (!value.text.startsWith(line, cursor) && line.endsWith('-')) line = line.slice(0, -1); // discretionary line-end hyphen
+        if (line && value.text.startsWith(line, cursor)) {
+          const start = value.positions[cursor], end = value.positions[cursor + line.length - 1] + 1;
+          target.lines.push({ page: pageIndex + 1, x: node.x, y: node.y, width: node.width, height: node.height, text: node.textContent, start, end });
+          cursors[own] = cursor + line.length;
+        } else if (line) blocked[own] = true; // Never resume at a coincidentally repeated phrase after an unaligned line.
+      }
+      for (const child of node.children) visit(child, own);
+    };
+    for (const node of page.elements) visit(node);
+  }
+}

package/src/server/text-source.ts

@@ -0,0 +1,307 @@
+import ts from 'typescript';
+import { createHash } from 'node:crypto';
+import type { TextSourceValue } from '../shared/selection';
+
+export const textDigest = (text: string) => createHash('sha256').update(text).digest('hex');
+export const textSourceBindingId = (file: string, digest: string, start: number, end: number) => textDigest(JSON.stringify([file, digest, start, end]));
+
+function unwrap(node: ts.Expression): ts.Expression {
+  while (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isTypeAssertionExpression(node) || ts.isNonNullExpression(node) || ts.isSatisfiesExpression(node)) node = node.expression;
+  return node;
+}
+
+function propertyName(node: ts.PropertyName): string | undefined {
+  return ts.isIdentifier(node) || ts.isStringLiteral(node) || ts.isNumericLiteral(node) ? node.text : undefined;
+}
+
+function propertyValue(node: ts.ObjectLiteralElementLike): ts.Expression | undefined {
+  return ts.isPropertyAssignment(node) ? node.initializer : ts.isShorthandPropertyAssignment(node) && !node.objectAssignmentInitializer ? node.name : undefined;
+}
+
+/** Use the same JSX whitespace/entity rules as the TypeScript compiler, without evaluating code. */
+function jsxValue(raw: string, attribute: boolean): string | undefined {
+  const key = attribute ? 'value' : 'children';
+  const input = attribute ? `const x = <T value=${raw}/>;` : `const x = <T>${raw}</T>;`;
+  const output = ts.transpileModule(input, { compilerOptions: { jsx: ts.JsxEmit.ReactJSX, target: ts.ScriptTarget.ES2022 } }).outputText;
+  const tree = ts.createSourceFile('jsx-value.js', output, ts.ScriptTarget.Latest, true, ts.ScriptKind.JS);
+  let value: string | undefined;
+  function visit(node: ts.Node) {
+    if (ts.isPropertyAssignment(node) && propertyName(node.name) === key && ts.isStringLiteral(node.initializer)) value = node.initializer.text;
+    ts.forEachChild(node, visit);
+  }
+  visit(tree);
+  return value;
+}
+
+export interface TextSourceResolver {
+  resolveAt(line: number, column: number, slot?: string, childIndex?: number): TextSourceValue | undefined;
+}
+
+/** Only provable values in this source file are followed. Imported values and arbitrary expressions stay read-only. */
+export function createTextSourceResolver(file: string, source: string): TextSourceResolver {
+  const tree = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  const digest = textDigest(source);
+  const options: ts.CompilerOptions = { noResolve: true, noLib: true, target: ts.ScriptTarget.ES2022, jsx: ts.JsxEmit.Preserve };
+  const host = ts.createCompilerHost(options);
+  host.getSourceFile = name => name === file ? tree : undefined;
+  host.fileExists = name => name === file;
+  host.readFile = name => name === file ? source : undefined;
+  const checker = ts.createProgram([file], options, host).getTypeChecker();
+  const nodes: ts.Node[] = [];
+  const jsxValues = new Map<ts.Node, string | undefined>();
+  function collect(node: ts.Node) { nodes.push(node); ts.forEachChild(node, collect); }
+  collect(tree);
+
+  function descriptor(node: ts.Node, kind: TextSourceValue['kind'], value: string): TextSourceValue {
+    const start = ts.isJsxText(node) ? node.pos : node.getStart(tree), end = node.end;
+    return { file, digest, start, end, kind, value, bindingId: textSourceBindingId(file, digest, start, end) };
+  }
+  function jsx(node: ts.Node, attribute: boolean) {
+    if (!jsxValues.has(node)) jsxValues.set(node, jsxValue(source.slice(ts.isJsxText(node) ? node.pos : node.getStart(tree), node.end), attribute));
+    return jsxValues.get(node);
+  }
+
+  const safeDeclarations = new Map<ts.VariableDeclaration, boolean>();
+  function referenceSymbol(node: ts.Identifier) {
+    // In `{ meta }`, the identifier's ordinary symbol is the new object's
+    // property; the value symbol is the local variable whose identity escapes.
+    return ts.isShorthandPropertyAssignment(node.parent) && node.parent.name === node
+      ? checker.getShorthandAssignmentValueSymbol(node.parent) : checker.getSymbolAtLocation(node);
+  }
+  function isWriteTarget(node: ts.Node): boolean {
+    // A reference may sit inside parentheses, a type assertion, or a nested
+    // destructuring target. Inspect ancestors instead of only its immediate parent.
+    for (let current = node; current.parent; current = current.parent) {
+      const parent = current.parent;
+      if (ts.isBinaryExpression(parent) && parent.left === current && parent.operatorToken.kind >= ts.SyntaxKind.FirstAssignment && parent.operatorToken.kind <= ts.SyntaxKind.LastAssignment) return true;
+      if ((ts.isPrefixUnaryExpression(parent) || ts.isPostfixUnaryExpression(parent)) && (parent.operator === ts.SyntaxKind.PlusPlusToken || parent.operator === ts.SyntaxKind.MinusMinusToken)) return true;
+      if (ts.isDeleteExpression(parent)) return true;
+      if ((ts.isForOfStatement(parent) || ts.isForInStatement(parent)) && parent.initializer === current) return true;
+    }
+    return false;
+  }
+  function safeDeclaration(declaration: ts.VariableDeclaration): boolean {
+    if (safeDeclarations.has(declaration)) return safeDeclarations.get(declaration)!;
+    safeDeclarations.set(declaration, false);
+    if (!declaration.initializer || !ts.isIdentifier(declaration.name) || !ts.isVariableDeclarationList(declaration.parent) || !(declaration.parent.flags & ts.NodeFlags.Const)) return false;
+    const symbol = checker.getSymbolAtLocation(declaration.name);
+    if (!symbol) return false;
+    const object = ts.isObjectLiteralExpression(unwrap(declaration.initializer));
+    for (const node of nodes) {
+      if (!ts.isIdentifier(node) || node === declaration.name || referenceSymbol(node) !== symbol) continue;
+      if (isWriteTarget(node)) return false;
+      let usage: ts.Node = node;
+      while ((ts.isPropertyAccessExpression(usage.parent) || ts.isElementAccessExpression(usage.parent)) && usage.parent.expression === usage) usage = usage.parent;
+      const parent = usage.parent;
+      // Objects may only be read through properties. Passing their identity around could hide mutations.
+      if (object && usage === node) return false;
+      if (object && ts.isCallExpression(parent) && parent.expression === usage) return false;
+      if (object) {
+        const keys: string[] = [];
+        let access = usage;
+        while (ts.isPropertyAccessExpression(access) || ts.isElementAccessExpression(access)) {
+          const key = ts.isPropertyAccessExpression(access) ? access.name.text : access.argumentExpression && ts.isStringLiteral(access.argumentExpression) ? access.argumentExpression.text : undefined;
+          if (key === undefined) return false;
+          keys.unshift(key); access = access.expression;
+        }
+        let read: ts.Expression = unwrap(declaration.initializer);
+        for (const key of keys) {
+          if (!ts.isObjectLiteralExpression(read) || read.properties.some(item => !propertyValue(item) || !item.name || propertyName(item.name) === undefined)) return false;
+          const properties = read.properties.filter(item => propertyName(item.name!) === key);
+          if (properties.length !== 1 || !propertyValue(properties[0])) return false;
+          read = unwrap(propertyValue(properties[0])!);
+        }
+        // Never authorize through an object whose nested identity escapes to an alias or a call.
+        if (ts.isObjectLiteralExpression(read) || ts.isArrayLiteralExpression(read)) return false;
+      }
+    }
+    safeDeclarations.set(declaration, true);
+    return true;
+  }
+
+  function expressionNode(input: ts.Expression, seen = new Set<ts.Node>()): ts.Expression | undefined {
+    const node = unwrap(input);
+    if (seen.has(node)) return undefined;
+    seen.add(node);
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node) || ts.isObjectLiteralExpression(node)) return node;
+    if (ts.isIdentifier(node)) {
+      const symbol = referenceSymbol(node);
+      const declarations = symbol?.declarations;
+      if (declarations?.length !== 1 || !ts.isVariableDeclaration(declarations[0]) || declarations[0].getSourceFile() !== tree || !safeDeclaration(declarations[0])) return undefined;
+      return expressionNode(declarations[0].initializer!, seen);
+    }
+    if (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) {
+      const key = ts.isPropertyAccessExpression(node) ? node.name.text : node.argumentExpression && ts.isStringLiteral(unwrap(node.argumentExpression)) ? (unwrap(node.argumentExpression) as ts.StringLiteral).text : undefined;
+      const object = expressionNode(node.expression, seen);
+      if (key === undefined || !object || !ts.isObjectLiteralExpression(object)) return undefined;
+      if (object.properties.some(property => !propertyValue(property) || !property.name || propertyName(property.name) === undefined)) return undefined;
+      const matches = object.properties.filter(property => propertyName(property.name!) === key);
+      if (matches.length !== 1 || !propertyValue(matches[0])) return undefined;
+      return expressionNode(propertyValue(matches[0])!, seen);
+    }
+    return undefined;
+  }
+
+  const textProps = new Set(['children', 'title', 'subtitle', 'eyebrow', 'byline', 'caption', 'lead', 'body', 'footer', 'description', 'author', 'label']);
+  const protectedTokens = new Set<ts.Node>();
+  function outerExpression(node: ts.Node) {
+    while ((ts.isParenthesizedExpression(node.parent) || ts.isAsExpression(node.parent) || ts.isTypeAssertionExpression(node.parent) || ts.isNonNullExpression(node.parent) || ts.isSatisfiesExpression(node.parent)) && node.parent.expression === node) node = node.parent;
+    return node;
+  }
+  function textConsumer(input: ts.Expression): boolean {
+    const node = outerExpression(input), parent = node.parent;
+    if (ts.isVariableDeclaration(parent)) {
+      // A direct const alias is checked at all of its own uses below.
+      return parent.initializer === node && ts.isIdentifier(parent.name) && safeDeclaration(parent);
+    }
+    if (ts.isJsxExpression(parent) && parent.expression === node) {
+      return ts.isJsxAttribute(parent.parent) ? textProps.has(parent.parent.name.getText(tree))
+        : ts.isJsxElement(parent.parent) || ts.isJsxFragment(parent.parent);
+    }
+    // Metadata is a documented text consumer, not an arbitrary escaped object.
+    if ((ts.isPropertyAssignment(parent) && parent.initializer === node) || (ts.isShorthandPropertyAssignment(parent) && parent.name === node)) {
+      const property = propertyName(parent.name);
+      const object = outerExpression(parent.parent);
+      const owner = object.parent;
+      return property !== undefined && textProps.has(property) && ts.isVariableDeclaration(owner) && ts.isIdentifier(owner.name) && owner.name.text === 'meta' && owner.initializer === object && safeDeclaration(owner);
+    }
+    return false;
+  }
+  for (const node of nodes) {
+    if (!ts.isIdentifier(node) && !ts.isPropertyAccessExpression(node) && !ts.isElementAccessExpression(node)) continue;
+    if (ts.isVariableDeclaration(node.parent) && node.parent.name === node) continue;
+    const value = expressionNode(node);
+    if (value && (ts.isStringLiteral(value) || ts.isNoSubstitutionTemplateLiteral(value)) && !textConsumer(node)) protectedTokens.add(value);
+  }
+
+  function expression(input: ts.Expression): TextSourceValue | undefined {
+    const node = expressionNode(input);
+    if (!node || protectedTokens.has(node) || (!ts.isStringLiteral(node) && !ts.isNoSubstitutionTemplateLiteral(node))) return undefined;
+    return descriptor(node, 'string', node.text);
+  }
+
+  function openingAt(line: number, column: number): ts.JsxOpeningElement | ts.JsxSelfClosingElement | undefined {
+    if (!Number.isInteger(line) || !Number.isInteger(column) || line < 1 || column < 1) return undefined;
+    const starts = tree.getLineStarts();
+    if (line > starts.length) return undefined;
+    const position = starts[line - 1] + column - 1;
+    return nodes.find(node => (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) && node.getStart(tree) <= position && node.tagName.end >= position) as ts.JsxOpeningElement | ts.JsxSelfClosingElement | undefined;
+  }
+
+  function attribute(opening: ts.JsxOpeningElement | ts.JsxSelfClosingElement, slot: string): TextSourceValue | undefined {
+    // A spread can override an earlier named field, so even a literal beside it is not a proof.
+    if (opening.attributes.properties.some(ts.isJsxSpreadAttribute)) return undefined;
+    const matches = opening.attributes.properties.filter(item => ts.isJsxAttribute(item) && item.name.getText(tree) === slot);
+    if (matches.length !== 1 || !ts.isJsxAttribute(matches[0])) return undefined;
+    const initializer = matches[0].initializer;
+    if (!initializer) return undefined;
+    if (ts.isStringLiteral(initializer)) {
+      const value = jsx(initializer, true);
+      return value === undefined ? undefined : descriptor(initializer, 'jsx-attribute', value);
+    }
+    return ts.isJsxExpression(initializer) && initializer.expression ? expression(initializer.expression) : undefined;
+  }
+
+  function children(opening: ts.JsxOpeningElement | ts.JsxSelfClosingElement) {
+    const rows: { childIndex: number; source?: TextSourceValue }[] = [];
+    if (ts.isJsxSelfClosingElement(opening)) {
+      const source = attribute(opening, 'children');
+      return source ? [{ childIndex: 0, source }] : [];
+    }
+    const parent = opening.parent;
+    if (!ts.isJsxElement(parent)) return rows;
+    for (const child of parent.children) {
+      if (ts.isJsxExpression(child) && !child.expression) continue;
+      let value: TextSourceValue | undefined;
+      if (ts.isJsxText(child)) {
+        const text = jsx(child, false);
+        if (text === undefined || text === '') continue;
+        value = descriptor(child, 'jsx-text', text);
+      } else if (ts.isJsxExpression(child) && child.expression && !child.dotDotDotToken) value = expression(child.expression);
+      rows.push({ childIndex: rows.length, ...(value ? { source: value } : {}) });
+    }
+    if (!rows.length) {
+      const source = attribute(opening, 'children');
+      if (source) rows.push({ childIndex: 0, source });
+    }
+    return rows;
+  }
+
+  // Count linked authored occurrences by token identity, not matching visible text.
+  const occurrenceCounts = new Map<string, number>();
+  const identity = (value: TextSourceValue) => `${value.start}:${value.end}`;
+  for (const node of nodes) {
+    if (!ts.isJsxOpeningElement(node) && !ts.isJsxSelfClosingElement(node)) continue;
+    const values = children(node).map(child => child.source);
+    for (const item of node.attributes.properties) if (ts.isJsxAttribute(item) && item.name.getText(tree) !== 'children') values.push(attribute(node, item.name.getText(tree)));
+    for (const value of values) if (value) occurrenceCounts.set(identity(value), (occurrenceCounts.get(identity(value)) ?? 0) + 1);
+  }
+  const linked = (value: TextSourceValue | undefined) => value ? { ...value, linkedOccurrences: occurrenceCounts.get(identity(value)) ?? 1 } : undefined;
+  return {
+    resolveAt(line, column, slot = 'children', childIndex = 0) {
+      const opening = openingAt(line, column);
+      if (!opening) return undefined;
+      return linked(slot === 'children' ? children(opening)[childIndex]?.source : attribute(opening, slot));
+    },
+  };
+}
+
+export type JsonTextPath = (string | { id: string })[];
+
+/** Index one immutable snapshot; array fields use stable record IDs, never positions. */
+export function createJsonTextSourceResolver(file: string, source: string): (path: JsonTextPath) => TextSourceValue | undefined {
+  const tree = ts.parseJsonText(file, source);
+  if ((tree as unknown as { parseDiagnostics: ts.Diagnostic[] }).parseDiagnostics.length) return () => undefined;
+  const root: ts.Expression | undefined = tree.statements[0] && ts.isExpressionStatement(tree.statements[0]) ? tree.statements[0].expression : undefined;
+  const digest = textDigest(source);
+  const objects = new WeakMap<ts.ObjectLiteralExpression, Map<string, ts.Expression | undefined>>();
+  const arrays = new WeakMap<ts.ArrayLiteralExpression, Map<string, ts.Expression | undefined>>();
+  function fields(node: ts.ObjectLiteralExpression) {
+    let index = objects.get(node);
+    if (!index) {
+      index = new Map();
+      for (const item of node.properties) {
+        if (!ts.isPropertyAssignment(item)) continue;
+        const key = propertyName(item.name);
+        if (key !== undefined) index.set(key, index.has(key) ? undefined : item.initializer);
+      }
+      objects.set(node, index);
+    }
+    return index;
+  }
+  function records(node: ts.ArrayLiteralExpression) {
+    let index = arrays.get(node);
+    if (!index) {
+      index = new Map();
+      for (const item of node.elements) {
+        const id = ts.isObjectLiteralExpression(item) ? fields(item).get('id') : undefined;
+        if (id && ts.isStringLiteral(id)) index.set(id.text, index.has(id.text) ? undefined : item);
+      }
+      arrays.set(node, index);
+    }
+    return index;
+  }
+  return path => {
+    // A record's lookup key is structural identity, even when it is displayed.
+    if (path.at(-1) === 'id' && typeof path.at(-2) === 'object') return undefined;
+    let node = root;
+    for (const part of path) {
+      if (!node) return undefined;
+      if (typeof part === 'string') node = ts.isObjectLiteralExpression(node) ? fields(node).get(part) : undefined;
+      else node = ts.isArrayLiteralExpression(node) && part && typeof part.id === 'string' ? records(node).get(part.id) : undefined;
+    }
+    return node && ts.isStringLiteral(node) ? { file, digest, start: node.getStart(tree), end: node.end, kind: 'json-string', value: node.text, bindingId: textSourceBindingId(file, digest, node.getStart(tree), node.end) } : undefined;
+  };
+}
+
+export function serializeSourceValue(value: TextSourceValue, next: string): string {
+  const serialized = JSON.stringify(next);
+  return value.kind === 'jsx-text' || value.kind === 'jsx-attribute' ? `{${serialized}}` : serialized;
+}
+
+export function validateTextSyntax(file: string, source: string) {
+  if (file.endsWith('.json')) { JSON.parse(source); return; }
+  const tree = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, file.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+  const diagnostics = (tree as ts.SourceFile & { parseDiagnostics: ts.Diagnostic[] }).parseDiagnostics;
+  if (diagnostics.length) throw new Error(`The correction would make the source invalid: ${ts.flattenDiagnosticMessageText(diagnostics[0].messageText, ' ')}`);
+}

package/src/server/themes-cli.ts

@@ -0,0 +1,59 @@
+import { lstat, mkdir } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parseArgs } from 'node:util';
+import { ThemeCatalog, readTheme, readThemeGuide, themeFile, readThemePaths } from './themes';
+import { captureEntryExportInputs } from './export-inputs';
+import { RenderFailure } from './render-error';
+import { ExportChangedError, publishPDF } from './export-file';
+
+const usage = 'Usage: npx opendoc themes list | inspect <id> | check <id> | preview <id> [--json]';
+
+export async function runThemesCli(args: string[], root = process.cwd()): Promise<void> {
+  const { values, positionals } = parseArgs({ args: args[0] === '--' ? args.slice(1) : args, allowPositionals: true, options: {
+    json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' },
+  } });
+  if (values.help) { console.log(values.json ? JSON.stringify({ usage }, null, 2) : usage); return; }
+  const [command = 'list', id, ...extra] = positionals;
+  if (extra.length || !['list', 'inspect', 'check', 'preview'].includes(command) || (command === 'list' ? id !== undefined : !id)) throw new Error(usage);
+  const catalog = new ThemeCatalog(root);
+  try {
+    if (command === 'list') {
+      const choices = (await catalog.list()).map(({ id, name, description, error }) => ({ id, name, description, error }));
+      console.log(JSON.stringify(choices, null, 2));
+    }
+    else {
+      const unchanged = command === 'inspect' ? () => true : await captureEntryExportInputs(root, await themeFile(root, id, 'preview.tsx'));
+      const theme = await readTheme(root, id);
+      const guide = await readThemeGuide(root, id);
+      const paths = await readThemePaths(root, id);
+      if (command === 'inspect') console.log(JSON.stringify({ id, name: theme.name, description: theme.description, useFor: theme.useFor ?? [], principles: theme.principles ?? [], palette: theme.palette ?? [], geometry: theme.geometry ?? [], paths, guideWords: guide.trim().split(/\s+/).length }, null, 2));
+      else {
+        const preview = await catalog.preview(id);
+        if (!preview.artifact) throw new RenderFailure(preview.error ?? 'Theme preview failed.', preview.issues);
+        if (!unchanged()) throw new ExportChangedError();
+        const artifact = preview.artifact;
+        let output: string | undefined;
+        if (command === 'preview') {
+          for (const folder of [resolve(root, 'output'), resolve(root, 'output/themes')]) {
+            await mkdir(folder, { recursive: true });
+            const info = await lstat(folder);
+            if (!info.isDirectory() || info.isSymbolicLink()) throw new Error('Theme exports need a regular local output/themes folder.');
+          }
+          output = resolve(root, 'output/themes', `${id}.pdf`);
+          const previous = await lstat(output).catch(error => { if (error.code === 'ENOENT') return undefined; throw error; });
+          if (previous && (!previous.isFile() || previous.isSymbolicLink())) throw new Error('The theme export destination is not a regular file.');
+          await publishPDF(root, id, await catalog.pdf(id, artifact.hash), unchanged, 'themes');
+        }
+        console.log(JSON.stringify({ id, name: theme.name, status: 'ready', pages: artifact.pages.length, hash: artifact.hash, issues: artifact.issues ?? [], paths, ...(output ? { output } : {}), review: 'Inspect every PDF page; automated checks do not establish visual quality.' }, null, 2));
+      }
+    }
+  } catch (error) {
+    if (error instanceof ExportChangedError) throw new Error('The theme changed while preparing its preview. Retry after edits finish; no theme PDF was replaced.', { cause: error });
+    throw error;
+  } finally { await catalog.close(); }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  runThemesCli(process.argv.slice(2)).catch(error => { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; });
+}