@ryanyahya/opendoc 0.4.0

package/src/server/create.ts

@@ -0,0 +1,228 @@
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, realpath, rmdir, unlink, link } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { DOCUMENT_ID_MAX_LENGTH, TITLE_MAX_LENGTH, listStarters, type CreatedDocument, type StarterId, type StarterSummary } from '../shared/starters';
+import { validId } from './render';
+import { requireProject, selectedTheme, withProjects } from './projects';
+import { resolveThemeAssets } from '../assets/files';
+import { documentAssetAdapterSource } from '../assets/adapter';
+
+export { listStarters } from '../shared/starters';
+export type { CreateDocumentInput, CreatedDocument } from '../shared/starters';
+
+type ErrorCode = 'INVALID_INPUT' | 'ALREADY_EXISTS' | 'UNSAFE_PATH' | 'CREATE_FAILED';
+export class CreateDocumentError extends Error {
+  constructor(message: string, public code: ErrorCode, public status: 400 | 409 | 500) { super(message); this.name = 'CreateDocumentError'; }
+}
+const invalid = (message: string) => new CreateDocumentError(message, 'INVALID_INPUT', 400);
+const unsafe = () => new CreateDocumentError('The document location changed or is not a regular workspace folder. Nothing was overwritten.', 'UNSAFE_PATH', 409);
+const exists = (id: string, explicitId: boolean) => new CreateDocumentError(`A folder named "${id}" already exists. Choose a different ${explicitId ? 'document ID' : 'title'}.`, 'ALREADY_EXISTS', 409);
+const isCode = (error: unknown, code: string) => error instanceof Error && 'code' in error && error.code === code;
+
+async function inputValues(root: string, value: unknown) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw invalid('Provide a document title and project.');
+  const input = value as Record<string, unknown>;
+  if (Object.keys(input).some(key => !['title', 'starter', 'id', 'projectId', 'theme', 'format'].includes(key))) throw invalid('Only title, starter, project, theme, format, and an optional document ID are accepted.');
+  if (typeof input.projectId !== 'string' || !validId(input.projectId)) throw invalid('Choose a project before creating a document.');
+  let theme: string | null;
+  try { theme = await selectedTheme(root, input.theme); } catch { throw invalid('Choose an available theme.'); }
+  if (typeof input.title !== 'string' || !input.title.trim()) throw invalid('Give your document a title.');
+  const format = input.format ?? 'document';
+  if (format !== 'document' && format !== 'presentation') throw invalid('Choose document or presentation format.');
+  if (format === 'presentation' && input.starter !== undefined && input.starter !== 'blank') throw invalid('Presentations use a blank slide scaffold; document starters are not supported.');
+  const title = input.title.trim();
+  if (title.length > TITLE_MAX_LENGTH) throw invalid(`Keep the title to ${TITLE_MAX_LENGTH} characters or fewer.`);
+  if (/[\u0000-\u001f\u007f\u2028\u2029]/u.test(title)) throw invalid('The title must fit on one line and cannot contain control characters.');
+  const starter: StarterSummary | undefined = input.starter === undefined || input.starter === 'blank'
+    ? { id: 'blank', name: 'Blank', description: '' }
+    : listStarters().find(item => item.id === input.starter);
+  if (!starter) throw invalid('Choose one of the available document starters.');
+  const derived = title.normalize('NFKD').replace(/\p{M}/gu, '').toLowerCase().replace(/[’']/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, DOCUMENT_ID_MAX_LENGTH).replace(/-$/, '');
+  const id = input.id === undefined ? derived || 'untitled-document' : input.id;
+  if (typeof id !== 'string' || !validId(id) || id.length > DOCUMENT_ID_MAX_LENGTH) throw invalid(`Use a document ID of ${DOCUMENT_ID_MAX_LENGTH} characters or fewer, with lowercase letters, numbers, and single hyphens.`);
+  return { title, id, starter, format: format as 'document' | 'presentation', projectId: input.projectId, theme, explicitId: input.id !== undefined };
+}
+
+function sourceFor(starter: StarterSummary, title: string, themeOverride: string | null, format: 'document' | 'presentation') {
+  const theme = themeOverride ?? 'neutral';
+  if (format === 'presentation') return `import { Presentation, Slide, Heading, type DocumentMeta } from 'opendoc';
+import { theme } from './theme';
+
+export const meta: DocumentMeta = ${JSON.stringify({ title, description: '', theme }, null, 2)};
+
+export default function Draft() {
+  return <Presentation title={meta.title} theme={theme}>
+    <Slide id="opening">
+      <Heading id="opening-title" level={1} style={{ fontSize: 44, lineHeight: 1.1 }}>{meta.title}</Heading>
+    </Slide>
+  </Presentation>;
+}
+`;
+  const bodies: Record<StarterId, string> = {
+    blank: `      <TitleBlock id="opening" title={meta.title} />`,
+    article: `      <TitleBlock id="opening" eyebrow="Article · Working draft" title={meta.title} subtitle="Start with the idea you want the reader to carry away." />
+      <Paragraph id="opening-paragraph">Introduce the question, observation, or experience that makes this piece worth writing. Give the reader a concrete place to begin.</Paragraph>
+      <Section id="argument" title="Develop the idea" lead="Build the argument with specific examples and a clear thread between them.">
+        <Paragraph id="evidence">Add the evidence or experience that supports your point. Cite factual claims and distinguish your interpretation from what a source actually establishes.</Paragraph>
+      </Section>
+      <Section id="ending" title="Leave something with the reader" lead="Return to the opening idea with the understanding the piece has earned." />`,
+    report: `      <TitleBlock id="opening" eyebrow="Report · Working draft" title={meta.title} subtitle="A clear account of the question, the evidence, and what to do next." />
+      <Section id="summary" title="Executive summary" lead="State the question this report answers and the decision it supports. Write the final summary after reviewing the evidence." />
+      <Section id="findings" title="Findings" lead="Present the most relevant findings in a logical order.">
+        <Paragraph id="evidence">For each finding, identify the source, date, and any limits on what it can show. Replace this guidance with verified material.</Paragraph>
+      </Section>
+      <Section id="recommendation" title="Recommendation" lead="Explain the recommended action, who would own it, and what would count as progress.">
+        <Callout id="limitations" title="Before sharing">Make assumptions and unresolved questions explicit. This starter contains guidance only; it does not contain findings or verified claims.</Callout>
+      </Section>`,
+    proposal: `      <TitleBlock id="opening" eyebrow="Proposal · Working draft" title={meta.title} subtitle="A focused plan for a clearly defined need." />
+      <Section id="need" title="The need" lead="Describe the client's situation, the problem to solve, and the outcome that would make the work worthwhile." />
+      <Section id="approach" title="Proposed approach" lead="Explain how the work would proceed and why the approach fits this need.">
+        <List id="scope" items={[
+          { id: 'deliverables', children: 'Deliverables — define the concrete outputs and how they will be accepted.' },
+          { id: 'timing', children: 'Timing — name the phases, dependencies, and review points.' },
+          { id: 'responsibilities', children: 'Responsibilities — explain what each party needs to provide.' },
+        ]} />
+      </Section>
+      <Section id="commercials" title="Scope and next steps" lead="Specify the pricing basis, assumptions, exclusions, and the decision needed to proceed.">
+        <Paragraph id="terms-note">No prices, dates, commitments, or client facts have been supplied. Confirm them before presenting this as a proposal.</Paragraph>
+      </Section>`,
+    research: `      <TitleBlock id="opening" eyebrow="Research paper · Working draft" title={meta.title} subtitle="A question that can be examined, a method that can be understood." />
+      <Section id="abstract" title="Abstract" lead="Summarize the question, method, principal result, and limits only after the study is described. No results have been supplied in this starter." />
+      <Section id="introduction" title="Introduction" lead="Define the research question and explain its importance using traceable sources." />
+      <Section id="methods" title="Methods" lead="Describe the materials or data, selection criteria, procedure, and analysis in enough detail for another reader to evaluate the work." />
+      <Section id="results" title="Results" lead="Report the observations with units and uncertainty where appropriate. Separate measured results from interpretation." />
+      <Section id="discussion" title="Discussion and limitations" lead="Explain what the results support, what they do not support, and which limitations affect the conclusion.">
+        <Paragraph id="sources-note">Add verified reference records and cite them where they support the text. Do not use illustrative values as study results.</Paragraph>
+      </Section>`,
+    technical: `      <TitleBlock id="opening" eyebrow="Technical brief · Working draft" title={meta.title} subtitle="A decision that can be understood, implemented, and checked." />
+      <Section id="context" title="Context and requirements" lead="Explain the system or problem, the intended reader, and the constraints that shape the solution." />
+      <Section id="design" title="Design and decisions" lead="Describe the proposed design and the reasons for the main choices.">
+        <List id="decision-checks" items={[
+          { id: 'interfaces', children: 'Interfaces — define inputs, outputs, and failure behavior.' },
+          { id: 'tradeoffs', children: 'Tradeoffs — record the alternatives and why a choice was made.' },
+          { id: 'constraints', children: 'Constraints — state performance, security, and compatibility requirements that actually apply.' },
+        ]} />
+      </Section>
+      <Section id="verification" title="Verification" lead="Define the checks or measurements that will demonstrate the design works.">
+        <Paragraph id="verification-note">Record observed results separately from targets. Include relevant edge cases and unresolved risks; this starter makes no performance or reliability claims.</Paragraph>
+      </Section>`,
+  };
+  const body = bodies[starter.id];
+  const imports = ['Document', 'Pages', 'TitleBlock', ...(starter.id === 'blank' ? [] : ['Paragraph', 'Section']), ...(body.includes('<List') ? ['List'] : []), ...(body.includes('<Callout') ? ['Callout'] : [])];
+  return `import { ${imports.join(', ')}, type DocumentMeta } from 'opendoc';
+import { theme } from './theme';
+
+export const meta: DocumentMeta = ${JSON.stringify({ title, description: starter.description, ...(starter.id === 'blank' ? {} : { kind: starter.kind }), theme }, null, 2)};
+
+// Ask Codex to develop this draft using your brief and sources. Keep block IDs stable as it grows.
+export default function Draft() {
+  return <Document title={meta.title} theme={theme}>
+    <Pages title={meta.title}>
+${body}
+    </Pages>
+  </Document>;
+}
+`;
+}
+
+/** Reserve the folder exclusively, then expose index.tsx only after every companion file is complete. */
+export async function createDocument(root: string, input: unknown): Promise<CreatedDocument> {
+  const values = await inputValues(root, input);
+  const workspace = await realpath(root);
+  return createInProject(workspace, values, async theme => ({ 'index.tsx': sourceFor(values.starter, values.title, theme, values.format) }));
+}
+
+export async function createDocumentFromFiles(root: string, input: { title: string; id?: string; projectId: string; theme?: string | null; format?: 'document' | 'presentation' }, files: Record<string, string> | ((id: string, theme: string | null) => Record<string, string> | Promise<Record<string, string>>)) {
+  const values = await inputValues(root, input);
+  return createInProject(root, values, async theme => typeof files === 'function' ? files(values.id, theme) : files);
+}
+
+async function createInProject(root: string, values: Awaited<ReturnType<typeof inputValues>>, files: (theme: string | null) => Promise<Record<string, string>>) {
+  return withProjects(root, async (manifest, save) => {
+    const project = requireProject(manifest, values.projectId);
+    let theme: string | null;
+    try { theme = values.theme ?? await selectedTheme(root, project.defaultTheme ?? 'neutral'); }
+    catch { throw invalid('Choose an available theme.'); }
+    const contents = await files(theme);
+    if (Object.hasOwn(contents, 'assets.json') || Object.hasOwn(contents, 'theme.tsx')) throw invalid('assets.json and theme.tsx are created from the chosen theme. Bind different assets after creation.');
+    // Publish the immutable choices and adapter before the entry. Template factories
+    // import this adapter, so their captured theme receives the saved font choices.
+    const selections = resolveThemeAssets(root, theme ?? 'neutral');
+    contents['assets.json'] = `${JSON.stringify(selections, null, 2)}\n`;
+    contents['theme.tsx'] = documentAssetAdapterSource(theme ?? 'neutral');
+    const previous = Object.hasOwn(manifest.assignments, values.id) ? manifest.assignments[values.id] : undefined;
+    const previousFormat = manifest.formats && Object.hasOwn(manifest.formats, values.id) ? manifest.formats[values.id] : undefined;
+    let assigned = false;
+    return reserveDocument(root, values, contents, async () => {
+      manifest.assignments[values.id] = project.id;
+      if (values.format === 'presentation' || previousFormat !== undefined) (manifest.formats ??= {})[values.id] = values.format;
+      await save(); assigned = true;
+    }, async () => {
+      if (!assigned) return;
+      if (previous === undefined) delete manifest.assignments[values.id]; else manifest.assignments[values.id] = previous;
+      if (previousFormat === undefined) { if (manifest.formats) delete manifest.formats[values.id]; } else (manifest.formats ??= {})[values.id] = previousFormat;
+      await save();
+    });
+  });
+}
+
+async function reserveDocument(root: string, { title, id, starter, projectId, explicitId }: Awaited<ReturnType<typeof inputValues>>, files: Record<string, string>, beforePublish: () => Promise<void>, rollback: () => Promise<void>): Promise<CreatedDocument> {
+  if (!files['index.tsx'] || Object.keys(files).some(name => !/^[a-zA-Z0-9_-]+\.(tsx|json)$/.test(name))) throw invalid('Document files need a TSX entry and simple local filenames.');
+  const workspace = await realpath(resolve(root));
+  const documents = resolve(workspace, 'documents');
+  try { await mkdir(documents); } catch (error) { if (!isCode(error, 'EEXIST')) throw error; }
+  const docsInfo = await lstat(documents);
+  if (!docsInfo.isDirectory() || docsInfo.isSymbolicLink() || await realpath(documents) !== documents) throw unsafe();
+  const destination = resolve(documents, id);
+  try { await mkdir(destination); } catch (error) { if (isCode(error, 'EEXIST')) throw exists(id, explicitId); throw error; }
+  const folderInfo = await lstat(destination);
+  const createdFolders: string[] = [];
+  const created = new Map<string, { dev: number; ino: number }>();
+  async function assertFolder() {
+    const [folder, parent] = await Promise.all([lstat(destination), lstat(documents)]);
+    if (!folder.isDirectory() || folder.isSymbolicLink() || folder.dev !== folderInfo.dev || folder.ino !== folderInfo.ino || parent.dev !== docsInfo.dev || parent.ino !== docsInfo.ino || await realpath(destination) !== destination) throw unsafe();
+  }
+  async function writeNew(name: string, content: string) {
+    await assertFolder();
+    const handle = await open(resolve(destination, name), constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o644);
+    try {
+      const info = await handle.stat(); created.set(name, { dev: info.dev, ino: info.ino });
+      await handle.writeFile(content, 'utf8');
+    } finally { await handle.close(); }
+  }
+  async function removeOwn(name: string) {
+    const identity = created.get(name);
+    if (!identity) return;
+    await assertFolder();
+    const current = await lstat(resolve(destination, name)).catch(error => { if (isCode(error, 'ENOENT')) return null; throw error; });
+    if (current?.dev === identity.dev && current.ino === identity.ino) await unlink(resolve(destination, name));
+  }
+  const pending = `.index-${randomUUID()}.tmp`;
+  try {
+    for (const folder of ['media']) {
+      await assertFolder();
+      await mkdir(resolve(destination, folder)); createdFolders.push(folder);
+      await writeNew(`${folder}/.gitkeep`, '');
+    }
+    for (const [name, content] of Object.entries(files)) if (name !== 'index.tsx') await writeNew(name, content);
+    await writeNew(pending, files['index.tsx']);
+    await assertFolder();
+    await beforePublish();
+    await assertFolder();
+    // link is exclusive: even an unexpected index added during creation is never replaced.
+    await link(resolve(destination, pending), resolve(destination, 'index.tsx'));
+    // Publication succeeded. A cleanup problem must not remove the completed document's data.
+    await removeOwn(pending).catch(() => {});
+    return { id, title, starter: starter.id, projectId, entry: `documents/${id}/index.tsx` };
+  } catch (error) {
+    const rollbackError = await rollback().then(() => null, error => error);
+    // A user may have added files while creation was in progress. Remove only our own writes.
+    for (const name of created.keys()) await removeOwn(name).catch(() => {});
+    for (const folder of createdFolders.reverse()) await rmdir(resolve(destination, folder)).catch(() => {});
+    await assertFolder().then(() => rmdir(destination)).catch(() => {});
+    if (rollbackError) throw new CreateDocumentError(`Document creation failed and its project assignment could not be restored. Check projects.json before retrying. ${rollbackError instanceof Error ? rollbackError.message : ''}`, 'CREATE_FAILED', 500);
+    if (error instanceof CreateDocumentError) throw error;
+    throw new CreateDocumentError(`Could not create "${id}". No existing document was overwritten. ${error instanceof Error ? error.message : ''}`, 'CREATE_FAILED', 500);
+  }
+}

package/src/server/dependencies.ts

@@ -0,0 +1,91 @@
+import { build } from 'esbuild';
+import { dirname, relative, resolve, sep } from 'node:path';
+import { existsSync, realpathSync } from 'node:fs';
+import { bindingDependencies, readDocumentAssetsAt, readThemeAssetDefaults, resolveThemeAssets } from '../assets/files';
+import { authoringResolutionPlugin } from './source-overrides';
+import { applicationRoot, runtimeSource } from '../runtime/paths';
+
+export interface DocumentDependencies { files: Set<string>; readsFiles: boolean }
+
+/** Executed outside the authored import graph; stamp these for export freshness as well. */
+export const renderRuntimeInputs = [
+  ...['worker', 'preflight', 'text-layout', 'text-source', 'render', 'render-source', 'source-overrides'].map(name => runtimeSource(`server/${name}.ts`)),
+  runtimeSource('rendering/resolve-sources.ts'),
+  runtimeSource('runtime/paths.ts'), resolve(applicationRoot, 'package.json'), resolve(applicationRoot, 'tsconfig.workspace.json'),
+];
+
+/** Only the new family directories are managed; existing loose fonts remain conservative inputs. */
+export function isManagedAssetPath(root: string, path: string) {
+  const parts = relative(root, resolve(root, path)).split(sep);
+  return parts[0] === 'assets' && ((parts[1] === 'logos' && (!parts[2] || /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(parts[2])))
+    || (parts[1] === 'fonts' && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(parts[2] ?? '')));
+}
+export function isThemeAssetDefaultsPath(root: string, path: string) {
+  return /^themes\/[a-z0-9]+(?:-[a-z0-9]+)*\/assets\.json$/.test(relative(root, resolve(root, path)).split(sep).join('/'));
+}
+
+/** Include absent binding/manifests too, so repairing a failed asset is observable. */
+async function managedInputs(root: string, entry: string) {
+  // documentEntry resolves macOS /var to /private/var; keep the binding path in root's spelling.
+  const parts = relative(realpathSync(root), realpathSync(entry)).split(sep);
+  const files = new Set<string>();
+  const previewTheme = parts[0] === 'themes' && parts[2] === 'preview.tsx' ? parts[1]
+    : parts[0] === 'templates' && parts[2] === 'preview.tsx' ? 'neutral' : undefined;
+  if (previewTheme) {
+    files.add(resolve(root, 'themes', previewTheme, 'assets.json'));
+    try {
+      const defaults = await readThemeAssetDefaults(root, previewTheme);
+      for (const [kind, id] of [['logos', defaults.logo?.id], ['fonts', defaults.bodyFont], ['fonts', defaults.headingFont]] as const)
+        if (id) files.add(resolve(root, 'assets', kind, id, 'asset.json'));
+      const bindings = await resolveThemeAssets(root, previewTheme);
+      for (const path of await bindingDependencies(root, bindings)) files.add(resolve(root, path));
+    } catch { /* The worker reports validation errors; preserve known paths for recovery. */ }
+  } else if (parts[0] === 'documents') {
+    const directory = dirname(resolve(root, ...parts));
+    files.add(resolve(directory, 'assets.json'));
+    try {
+      const bindings = await readDocumentAssetsAt(root, directory);
+      for (const path of await bindingDependencies(root, bindings)) files.add(resolve(root, path));
+    } catch { /* An invalid binding remains watched through its containing document. */ }
+  }
+  return files;
+}
+
+/** Follow imports without executing document code, then add immutable managed asset inputs. */
+export async function documentDependencies(root: string, entry: string): Promise<DocumentDependencies> {
+  const result = await build({
+    absWorkingDir: root, entryPoints: [entry], bundle: true, write: false, metafile: true,
+    platform: 'node', format: 'esm', jsx: 'automatic', logLevel: 'silent', plugins: [authoringResolutionPlugin()],
+    outdir: resolve(root, '.opendoc/dependencies'),
+  });
+  const inputs = Object.entries(result.metafile!.inputs);
+  const managedRoots = ['media', 'assets'].map(folder => runtimeSource(folder)).filter(existsSync).map(folder => realpathSync(folder) + sep);
+  const documentRuntime = realpathSync(runtimeSource('document/index.tsx'));
+  const files = new Set(inputs.map(([file]) => resolve(root, file)));
+  for (const file of ['package.json', 'package-lock.json', 'pnpm-lock.yaml', 'tsconfig.json']) files.add(resolve(root, file));
+  for (const file of renderRuntimeInputs) files.add(file);
+  for (const file of await managedInputs(root, entry)) files.add(file);
+  return {
+    files,
+    // Managed reads have exact dependency records. Arbitrary authored filesystem reads stay conservative.
+    readsFiles: inputs.some(([file, input]) => {
+      const actual = realpathSync(resolve(root, file));
+      return actual !== documentRuntime && !managedRoots.some(folder => actual.startsWith(folder))
+        && input.imports.some(item => /^(node:)?fs(?:\/promises)?$/.test(item.path));
+    }),
+  };
+}
+
+export function includesDependency(dependencies: DocumentDependencies, path: string) {
+  return dependencies.files.has(path) || [...dependencies.files].some(file => file.startsWith(path + sep));
+}
+
+/** Worker inputs that are not necessarily imported by authored components. */
+export function isRenderRuntimePath(root: string, path: string) {
+  const absolute = resolve(root, path);
+  const rel = relative(root, absolute).split(sep).join('/');
+  return (rel.startsWith('assets/') && !isManagedAssetPath(root, path))
+    || /^(package\.json|package-lock\.json|pnpm-lock\.yaml|tsconfig\.json)$/.test(rel)
+    || renderRuntimeInputs.includes(absolute)
+    || absolute === resolve(applicationRoot, 'pnpm-lock.yaml');
+}

package/src/server/documents.ts

@@ -0,0 +1,143 @@
+import type { DocumentFormat } from '../shared/types';
+import { randomUUID } from 'node:crypto';
+import { lstat, mkdir, readdir, readFile, rename, rm, writeFile, copyFile, realpath } from 'node:fs/promises';
+import { resolve, extname } from 'node:path';
+import ts from 'typescript';
+import { atomicWrite } from './files';
+import { validId } from './render';
+import { documentDisplayName, ProjectError, requireProject, withProjects } from './projects';
+
+async function exists(path: string) {
+  return lstat(path).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+}
+async function localDirectory(path: string, create = false) {
+  if (create) await mkdir(path, { recursive: true });
+  const info = await exists(path);
+  if (!info?.isDirectory() || info.isSymbolicLink()) throw new ProjectError('Document folders must be regular local directories.', 409);
+  return path;
+}
+async function documentFolder(root: string, id: string) {
+  if (!validId(id) || id.length > 80) throw new ProjectError('Invalid document ID.');
+  const documents = await localDirectory(resolve(await realpath(root), 'documents'));
+  const folder = resolve(documents, id);
+  if (!await exists(folder)) throw new ProjectError('This document no longer exists.', 404);
+  await localDirectory(folder);
+  const entry = await exists(resolve(folder, 'index.tsx'));
+  if (!entry?.isFile() || entry.isSymbolicLink()) throw new ProjectError('The document needs a regular index.tsx file.', 409);
+  return folder;
+}
+async function trashFolder(root: string) {
+  const runtime = await localDirectory(resolve(await realpath(root), '.opendoc'));
+  return localDirectory(resolve(runtime, 'trash'), true);
+}
+
+export async function renameDocument(root: string, id: string, input: unknown) {
+  if (!input || typeof input !== 'object' || Array.isArray(input) || Object.keys(input).some(key => key !== 'name')) throw new ProjectError('Provide a document name.');
+  const name = documentDisplayName((input as { name?: unknown }).name);
+  return withProjects(root, async (manifest, save) => {
+    await documentFolder(root, id);
+    (manifest.names ??= {})[id] = name;
+    await save(); return { id, name };
+  });
+}
+
+/** Rebind local source paths, without replacing words in authored prose or stable block IDs. */
+function rebaseSource(text: string, file: string, root: string, from: string, to: string) {
+  const prefixes = [[`documents/${from}/`, `documents/${to}/`], [`${resolve(root, 'documents', from)}/`, `${resolve(root, 'documents', to)}/`]];
+  const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, extname(file) === '.json' ? ts.ScriptKind.JSON : extname(file) === '.tsx' ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+  const changes: { start: number; end: number; value: string }[] = [];
+  function visit(node: ts.Node) {
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+      const match = prefixes.find(([prefix]) => node.text.startsWith(prefix));
+      if (match) changes.push({ start: node.getStart(source), end: node.end, value: JSON.stringify(match[1] + node.text.slice(match[0].length)) });
+      // Supplied layout starters bind provenance and media through this instance constant.
+      else if (node.text === from && ts.isVariableDeclaration(node.parent) && ts.isIdentifier(node.parent.name) && node.parent.name.text === 'documentId') changes.push({ start: node.getStart(source), end: node.end, value: JSON.stringify(to) });
+    }
+    ts.forEachChild(node, visit);
+  }
+  visit(source);
+  for (const change of changes.sort((a, b) => b.start - a.start)) text = text.slice(0, change.start) + change.value + text.slice(change.end);
+  return text;
+}
+async function copyDocumentTree(source: string, destination: string, root: string, from: string, to: string) {
+  await mkdir(destination);
+  for (const entry of await readdir(source, { withFileTypes: true })) {
+    const input = resolve(source, entry.name), output = resolve(destination, entry.name);
+    if (entry.isDirectory()) await copyDocumentTree(input, output, root, from, to);
+    else if (entry.isFile()) {
+      if (/\.(?:tsx?|jsx?|mjs|json)$/.test(entry.name)) await writeFile(output, rebaseSource(await readFile(input, 'utf8'), entry.name, root, from, to), { flag: 'wx' });
+      else await copyFile(input, output);
+    } else throw new ProjectError('This document contains a link or special file. Replace it with a local file before duplicating.', 409);
+  }
+}
+
+export async function duplicateDocument(root: string, id: string, title: string) {
+  return withProjects(root, async (manifest, save) => {
+    const source = await documentFolder(root, id);
+    const project = requireProject(manifest, manifest.assignments[id]);
+    const stem = `${id.slice(0, 65).replace(/-$/, '')}-copy`;
+    let copyId = stem, suffix = 2;
+    while (await exists(resolve(root, 'documents', copyId)) || Object.hasOwn(manifest.assignments, copyId) || (manifest.names && Object.hasOwn(manifest.names, copyId)) || (manifest.formats && Object.hasOwn(manifest.formats, copyId))) copyId = `${stem}-${suffix++}`;
+    const staging = resolve(root, 'documents', `.copy-${randomUUID()}`);
+    const name = documentDisplayName(`Copy of ${((manifest.names && Object.hasOwn(manifest.names, id) ? manifest.names[id] : title)).replace(/[\r\n]/g, ' ').trim()}`.slice(0, 160));
+    try {
+      await copyDocumentTree(source, staging, root, id, copyId);
+      manifest.assignments[copyId] = project.id;
+      (manifest.names ??= {})[copyId] = name;
+      if (manifest.formats && Object.hasOwn(manifest.formats, id)) manifest.formats[copyId] = manifest.formats[id];
+      await save();
+      try { await rename(staging, resolve(root, 'documents', copyId)); }
+      catch (error) { delete manifest.assignments[copyId]; delete manifest.names[copyId]; if (manifest.formats) delete manifest.formats[copyId]; await save(); throw error; }
+      return { id: copyId, projectId: project.id, name };
+    } finally { await rm(staging, { recursive: true, force: true }); }
+  });
+}
+
+interface TrashReceipt { format?: DocumentFormat; id: string; projectId: string | null; name?: string; deletedAt: string }
+
+export async function deleteDocument(root: string, id: string) {
+  return withProjects(root, async (manifest, save) => {
+    const source = await documentFolder(root, id);
+    const restoreId = randomUUID();
+    const trash = resolve(await trashFolder(root), restoreId);
+    await mkdir(trash);
+    const receipt: TrashReceipt = { id, format: manifest.formats && Object.hasOwn(manifest.formats, id) ? manifest.formats[id] : 'document', projectId: Object.hasOwn(manifest.assignments, id) ? manifest.assignments[id] : null, name: manifest.names && Object.hasOwn(manifest.names, id) ? manifest.names[id] : undefined, deletedAt: new Date().toISOString() };
+    await atomicWrite(resolve(trash, 'receipt.json'), JSON.stringify(receipt, null, 2));
+    await rename(source, resolve(trash, 'document'));
+    delete manifest.assignments[id];
+    if (manifest.names) delete manifest.names[id];
+    if (manifest.formats) delete manifest.formats[id];
+    try { await save(); }
+    catch (error) { await rename(resolve(trash, 'document'), source); await rm(trash, { recursive: true, force: true }); throw error; }
+    return { id, restoreId };
+  });
+}
+
+export async function restoreDocument(root: string, restoreId: string) {
+  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(restoreId)) throw new ProjectError('Invalid deleted document.');
+  return withProjects(root, async (manifest, save) => {
+    const trash = resolve(await trashFolder(root), restoreId);
+    if (!await exists(trash)) throw new ProjectError('This document has already been restored or is no longer in Trash.', 404);
+    await localDirectory(trash);
+    const receiptFile = resolve(trash, 'receipt.json');
+    const info = await exists(receiptFile);
+    if (!info?.isFile() || info.isSymbolicLink() || info.size > 4096) throw new ProjectError('The deleted document record is invalid.', 409);
+    const receipt = JSON.parse(await readFile(receiptFile, 'utf8')) as TrashReceipt;
+    if (!receipt || typeof receipt.id !== 'string' || !validId(receipt.id) || receipt.id.length > 80 || (receipt.projectId !== null && typeof receipt.projectId !== 'string')) throw new ProjectError('The deleted document record is invalid.', 409);
+    if (receipt.format !== undefined && receipt.format !== 'document' && receipt.format !== 'presentation') throw new ProjectError('The deleted document format is invalid.', 409);
+    if (receipt.name !== undefined) documentDisplayName(receipt.name);
+    if (receipt.projectId) requireProject(manifest, receipt.projectId);
+    const documents = await localDirectory(resolve(root, 'documents'));
+    const destination = resolve(documents, receipt.id);
+    if (await exists(destination) || Object.hasOwn(manifest.assignments, receipt.id) || (manifest.names && Object.hasOwn(manifest.names, receipt.id)) || (manifest.formats && Object.hasOwn(manifest.formats, receipt.id))) throw new ProjectError('A document already uses this ID. Move it aside before restoring this copy.', 409);
+    await localDirectory(resolve(trash, 'document'));
+    if (receipt.projectId) manifest.assignments[receipt.id] = receipt.projectId;
+    if (receipt.name !== undefined) (manifest.names ??= {})[receipt.id] = receipt.name;
+    if (receipt.format !== undefined) (manifest.formats ??= {})[receipt.id] = receipt.format;
+    await save();
+    try { await rename(resolve(trash, 'document'), destination); }
+    catch (error) { delete manifest.assignments[receipt.id]; if (manifest.names) delete manifest.names[receipt.id]; if (manifest.formats) delete manifest.formats[receipt.id]; await save(); throw error; }
+    await rm(trash, { recursive: true, force: true });
+    return { id: receipt.id, projectId: receipt.projectId, name: receipt.name };
+  });
+}