@ryanyahya/opendoc-headless 0.4.0

package/node_modules/undici-types/webidl.d.ts

@@ -0,0 +1,228 @@
+// These types are not exported, and are only used internally
+
+/**
+ * Take in an unknown value and return one that is of type T
+ */
+type Converter<T> = (object: unknown) => T
+
+type SequenceConverter<T> = (object: unknown, iterable?: IterableIterator<T>) => T[]
+
+type RecordConverter<K extends string, V> = (object: unknown) => Record<K, V>
+
+interface ConvertToIntOpts {
+  clamp?: boolean
+  enforceRange?: boolean
+}
+
+interface WebidlErrors {
+  exception (opts: { header: string, message: string }): TypeError
+  /**
+   * @description Throw an error when conversion from one type to another has failed
+   */
+  conversionFailed (opts: {
+    prefix: string
+    argument: string
+    types: string[]
+  }): TypeError
+  /**
+   * @description Throw an error when an invalid argument is provided
+   */
+  invalidArgument (opts: {
+    prefix: string
+    value: string
+    type: string
+  }): TypeError
+}
+
+interface WebidlUtil {
+  /**
+   * @see https://tc39.es/ecma262/#sec-ecmascript-data-types-and-values
+   */
+  Type (object: unknown):
+    | 'Undefined'
+    | 'Boolean'
+    | 'String'
+    | 'Symbol'
+    | 'Number'
+    | 'BigInt'
+    | 'Null'
+    | 'Object'
+
+  /**
+   * @see https://webidl.spec.whatwg.org/#abstract-opdef-converttoint
+   */
+  ConvertToInt (
+    V: unknown,
+    bitLength: number,
+    signedness: 'signed' | 'unsigned',
+    opts?: ConvertToIntOpts
+  ): number
+
+  /**
+   * @see https://webidl.spec.whatwg.org/#abstract-opdef-converttoint
+   */
+  IntegerPart (N: number): number
+
+  /**
+   * Stringifies {@param V}
+   */
+  Stringify (V: any): string
+
+  /**
+   * Mark a value as uncloneable for Node.js.
+   * This is only effective in some newer Node.js versions.
+   */
+  markAsUncloneable (V: any): void
+}
+
+interface WebidlConverters {
+  /**
+   * @see https://webidl.spec.whatwg.org/#es-DOMString
+   */
+  DOMString (V: unknown, prefix: string, argument: string, opts?: {
+    legacyNullToEmptyString: boolean
+  }): string
+
+  /**
+   * @see https://webidl.spec.whatwg.org/#es-ByteString
+   */
+  ByteString (V: unknown, prefix: string, argument: string): string
+
+  /**
+   * @see https://webidl.spec.whatwg.org/#es-USVString
+   */
+  USVString (V: unknown): string
+
+  /**
+   * @see https://webidl.spec.whatwg.org/#es-boolean
+   */
+  boolean (V: unknown): boolean
+
+  /**
+   * @see https://webidl.spec.whatwg.org/#es-any
+   */
+  any <Value>(V: Value): Value
+
+  /**
+   * @see https://webidl.spec.whatwg.org/#es-long-long
+   */
+  ['long long'] (V: unknown): number
+
+  /**
+   * @see https://webidl.spec.whatwg.org/#es-unsigned-long-long
+   */
+  ['unsigned long long'] (V: unknown): number
+
+  /**
+   * @see https://webidl.spec.whatwg.org/#es-unsigned-long
+   */
+  ['unsigned long'] (V: unknown): number
+
+  /**
+   * @see https://webidl.spec.whatwg.org/#es-unsigned-short
+   */
+  ['unsigned short'] (V: unknown, opts?: ConvertToIntOpts): number
+
+  /**
+   * @see https://webidl.spec.whatwg.org/#idl-ArrayBuffer
+   */
+  ArrayBuffer (V: unknown): ArrayBufferLike
+  ArrayBuffer (V: unknown, opts: { allowShared: false }): ArrayBuffer
+
+  /**
+   * @see https://webidl.spec.whatwg.org/#es-buffer-source-types
+   */
+  TypedArray (
+    V: unknown,
+    TypedArray: NodeJS.TypedArray | ArrayBufferLike
+  ): NodeJS.TypedArray | ArrayBufferLike
+  TypedArray (
+    V: unknown,
+    TypedArray: NodeJS.TypedArray | ArrayBufferLike,
+    opts?: { allowShared: false }
+  ): NodeJS.TypedArray | ArrayBuffer
+
+  /**
+   * @see https://webidl.spec.whatwg.org/#es-buffer-source-types
+   */
+  DataView (V: unknown, opts?: { allowShared: boolean }): DataView
+
+  /**
+   * @see https://webidl.spec.whatwg.org/#BufferSource
+   */
+  BufferSource (
+    V: unknown,
+    opts?: { allowShared: boolean }
+  ): NodeJS.TypedArray | ArrayBufferLike | DataView
+
+  ['sequence<ByteString>']: SequenceConverter<string>
+  
+  ['sequence<sequence<ByteString>>']: SequenceConverter<string[]>
+
+  ['record<ByteString, ByteString>']: RecordConverter<string, string>
+
+  [Key: string]: (...args: any[]) => unknown
+}
+
+export interface Webidl {
+  errors: WebidlErrors
+  util: WebidlUtil
+  converters: WebidlConverters
+
+  /**
+   * @description Performs a brand-check on {@param V} to ensure it is a
+   * {@param cls} object.
+   */
+  brandCheck <Interface>(V: unknown, cls: Interface, opts?: { strict?: boolean }): asserts V is Interface
+
+  /**
+   * @see https://webidl.spec.whatwg.org/#es-sequence
+   * @description Convert a value, V, to a WebIDL sequence type.
+   */
+  sequenceConverter <Type>(C: Converter<Type>): SequenceConverter<Type>
+
+  illegalConstructor (): never
+
+  /**
+   * @see https://webidl.spec.whatwg.org/#es-to-record
+   * @description Convert a value, V, to a WebIDL record type.
+   */
+  recordConverter <K extends string, V>(
+    keyConverter: Converter<K>,
+    valueConverter: Converter<V>
+  ): RecordConverter<K, V>
+
+  /**
+   * Similar to {@link Webidl.brandCheck} but allows skipping the check if third party
+   * interfaces are allowed.
+   */
+  interfaceConverter <Interface>(cls: Interface): (
+    V: unknown,
+    opts?: { strict: boolean }
+  ) => asserts V is typeof cls
+
+  // TODO(@KhafraDev): a type could likely be implemented that can infer the return type
+  // from the converters given?
+  /**
+   * Converts a value, V, to a WebIDL dictionary types. Allows limiting which keys are
+   * allowed, values allowed, optional and required keys. Auto converts the value to
+   * a type given a converter.
+   */
+  dictionaryConverter (converters: {
+    key: string,
+    defaultValue?: () => unknown,
+    required?: boolean,
+    converter: (...args: unknown[]) => unknown,
+    allowedValues?: unknown[]
+  }[]): (V: unknown) => Record<string, unknown>
+
+  /**
+   * @see https://webidl.spec.whatwg.org/#idl-nullable-type
+   * @description allows a type, V, to be null
+   */
+  nullableConverter <T>(
+    converter: Converter<T>
+  ): (V: unknown) => ReturnType<typeof converter> | null
+
+  argumentLengthCheck (args: { length: number }, min: number, context: string): void
+}

package/node_modules/undici-types/websocket.d.ts

@@ -0,0 +1,150 @@
+/// <reference types="node" />
+
+import type { Blob } from 'buffer'
+import type { MessagePort } from 'worker_threads'
+import {
+  EventInit,
+  EventListenerOptions,
+  AddEventListenerOptions,
+  EventListenerOrEventListenerObject
+} from './patch'
+import Dispatcher from './dispatcher'
+import { HeadersInit } from './fetch'
+
+export type BinaryType = 'blob' | 'arraybuffer'
+
+interface WebSocketEventMap {
+  close: CloseEvent
+  error: ErrorEvent
+  message: MessageEvent
+  open: Event
+}
+
+interface WebSocket extends EventTarget {
+  binaryType: BinaryType
+  
+  readonly bufferedAmount: number
+  readonly extensions: string
+
+  onclose: ((this: WebSocket, ev: WebSocketEventMap['close']) => any) | null
+  onerror: ((this: WebSocket, ev: WebSocketEventMap['error']) => any) | null
+  onmessage: ((this: WebSocket, ev: WebSocketEventMap['message']) => any) | null
+  onopen: ((this: WebSocket, ev: WebSocketEventMap['open']) => any) | null
+
+  readonly protocol: string
+  readonly readyState: number
+  readonly url: string
+
+  close(code?: number, reason?: string): void
+  send(data: string | ArrayBufferLike | Blob | ArrayBufferView): void
+
+  readonly CLOSED: number
+  readonly CLOSING: number
+  readonly CONNECTING: number
+  readonly OPEN: number
+
+  addEventListener<K extends keyof WebSocketEventMap>(
+    type: K,
+    listener: (this: WebSocket, ev: WebSocketEventMap[K]) => any,
+    options?: boolean | AddEventListenerOptions
+  ): void
+  addEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | AddEventListenerOptions
+  ): void
+  removeEventListener<K extends keyof WebSocketEventMap>(
+    type: K,
+    listener: (this: WebSocket, ev: WebSocketEventMap[K]) => any,
+    options?: boolean | EventListenerOptions
+  ): void
+  removeEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | EventListenerOptions
+  ): void
+}
+
+export declare const WebSocket: {
+  prototype: WebSocket
+  new (url: string | URL, protocols?: string | string[] | WebSocketInit): WebSocket
+  readonly CLOSED: number
+  readonly CLOSING: number
+  readonly CONNECTING: number
+  readonly OPEN: number
+}
+
+interface CloseEventInit extends EventInit {
+  code?: number
+  reason?: string
+  wasClean?: boolean
+}
+
+interface CloseEvent extends Event {
+  readonly code: number
+  readonly reason: string
+  readonly wasClean: boolean
+}
+
+export declare const CloseEvent: {
+  prototype: CloseEvent
+  new (type: string, eventInitDict?: CloseEventInit): CloseEvent
+}
+
+interface MessageEventInit<T = any> extends EventInit {
+  data?: T
+  lastEventId?: string
+  origin?: string
+  ports?: (typeof MessagePort)[]
+  source?: typeof MessagePort | null
+}
+
+interface MessageEvent<T = any> extends Event {
+  readonly data: T
+  readonly lastEventId: string
+  readonly origin: string
+  readonly ports: ReadonlyArray<typeof MessagePort>
+  readonly source: typeof MessagePort | null
+  initMessageEvent(
+    type: string,
+    bubbles?: boolean,
+    cancelable?: boolean,
+    data?: any,
+    origin?: string,
+    lastEventId?: string,
+    source?: typeof MessagePort | null,
+    ports?: (typeof MessagePort)[]
+  ): void;
+}
+
+export declare const MessageEvent: {
+  prototype: MessageEvent
+  new<T>(type: string, eventInitDict?: MessageEventInit<T>): MessageEvent<T>
+}
+
+interface ErrorEventInit extends EventInit {
+  message?: string
+  filename?: string
+  lineno?: number
+  colno?: number
+  error?: any
+}
+
+interface ErrorEvent extends Event {
+  readonly message: string
+  readonly filename: string
+  readonly lineno: number
+  readonly colno: number
+  readonly error: any
+}
+
+export declare const ErrorEvent: {
+  prototype: ErrorEvent
+  new (type: string, eventInitDict?: ErrorEventInit): ErrorEvent
+}
+
+interface WebSocketInit {
+  protocols?: string | string[],
+  dispatcher?: Dispatcher,
+  headers?: HeadersInit
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@ryanyahya/opendoc-headless",
+  "version": "0.4.0",
+  "description": "Remote document and editable presentation production for agents, with the complete OpenDoc starter library.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "opendoc": {
+    "edition": "headless"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "dependencies": {
+    "@formepdf/core": "0.20.1-opendoc.3",
+    "@formepdf/react": "0.20.1",
+    "@napi-rs/canvas": "1.0.8",
+    "@resvg/resvg-js": "^2.6.2",
+    "@shbernal/ts-pptx": "3.7.0",
+    "fast-xml-parser": "^5.11.1",
+    "fontkit": "^2.0.4",
+    "pdfjs-dist": "6.3.289",
+    "react": "19.2.8",
+    "ttf2eot": "3.1.0",
+    "@types/fontkit": "^2.0.9",
+    "@types/node": "^22.13.0",
+    "@types/react": "^19.2.0",
+    "esbuild": "0.28.2",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.3"
+  },
+  "bin": {
+    "opendoc": "./bin/opendoc.mjs",
+    "opendoc-headless": "./bin/opendoc.mjs"
+  },
+  "exports": {
+    ".": "./src/document/index.tsx",
+    "./assets": "./src/assets/index.ts",
+    "./template": "./src/template/index.ts",
+    "./themes": "./src/themes/index.ts",
+    "./jsx-runtime": "./src/runtime/jsx-runtime.ts",
+    "./jsx-dev-runtime": "./src/runtime/jsx-dev-runtime.ts",
+    "./package.json": "./package.json",
+    "./tsconfig.workspace.json": "./tsconfig.workspace.json"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "starter/",
+    "docs/",
+    ".agents/skills/",
+    "AGENTS.md",
+    "README.md",
+    "VALIDATION.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "LICENSE",
+    "THIRD_PARTY.md",
+    "licenses/",
+    "vendor/formepdf/",
+    "tsconfig.workspace.json",
+    "scripts/rebuild-forme.mjs"
+  ],
+  "bundleDependencies": [
+    "@formepdf/core",
+    "@formepdf/react",
+    "@types/node",
+    "@types/react"
+  ]
+}

package/scripts/rebuild-forme.mjs

@@ -0,0 +1,61 @@
+// Maintenance only. Normal installations use the checked-in package archive.
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const destination = resolve(root, 'vendor/formepdf');
+const work = process.argv[2]
+  ? resolve(process.argv[2])
+  : mkdtempSync(resolve(tmpdir(), 'opendoc-forme-rebuild-'));
+if (process.argv[2] && existsSync(work)) throw new Error(`Choose a new build directory; ${work} already exists.`);
+const commit = '0d706f839617b775e90edcc93d6001a8b0145a78';
+const originalIntegrity = '348ERmxZGqMbTuLzAikY/ktKqn+FZuFuxT6KBLf0k9s4wHO8kR9z8C4fMutPYXy9dM+ynVlr+Buqt6xPCE6RkA==';
+const env = { ...process.env, RUSTUP_TOOLCHAIN: process.env.RUSTUP_TOOLCHAIN ?? '1.98.1' };
+function run(command, args, cwd = work, capture = false) {
+  return execFileSync(command, args, { cwd, env, encoding: 'utf8', stdio: capture ? 'pipe' : 'inherit' });
+}
+mkdirSync(work, { recursive: true });
+// Rust panic locations otherwise embed the builder's home and Cargo registry paths.
+const mappings = [
+  [homedir(), '/build/home'],
+  [process.env.CARGO_HOME ?? resolve(homedir(), '.cargo'), '/build/cargo'],
+  [process.env.RUSTUP_HOME ?? resolve(homedir(), '.rustup'), '/build/rustup'],
+  [work, '/build/forme'], [realpathSync(work), '/build/forme'],
+];
+env.CARGO_ENCODED_RUSTFLAGS = [...(process.env.CARGO_ENCODED_RUSTFLAGS?.split('\u001f') ?? []),
+  ...mappings.map(([from, to]) => `--remap-path-prefix=${from}=${to}`)].join('\u001f');
+console.log(`Rebuilding Forme in ${work}`);
+if (!run('rustc', ['--version'], work, true).startsWith('rustc 1.98.1 ')) throw new Error('This patch is built with Rust 1.98.1.');
+if (run('wasm-pack', ['--version'], work, true).trim() !== 'wasm-pack 0.15.0') throw new Error('Install wasm-pack 0.15.0 to reproduce the package.');
+run('git', ['clone', '--depth', '1', '--branch', 'v0.20.1', 'https://github.com/formepdf/forme.git', 'source']);
+const source = resolve(work, 'source');
+if (run('git', ['rev-parse', 'HEAD'], source, true).trim() !== commit) throw new Error('The upstream tag no longer matches the pinned commit.');
+for (const patch of ['text-writer.patch', 'font-subset.patch']) {
+  run('git', ['apply', '--check', resolve(destination, patch)], source);
+  run('git', ['apply', resolve(destination, patch)], source);
+}
+run('cargo', ['test', '--manifest-path', 'engine/Cargo.toml', '--lib', '--locked'], source);
+for (const [target, folder] of [['bundler', 'pkg'], ['web', 'pkg-web'], ['nodejs', 'pkg-node']]) {
+  run('wasm-pack', ['build', '--target', target, '--out-dir', `../packages/core/${folder}`, '--features', 'wasm', '--locked'], resolve(source, 'engine'));
+  const wasm = readFileSync(resolve(source, 'packages/core', folder, 'forme_bg.wasm'));
+  if (mappings.some(([from]) => wasm.includes(Buffer.from(from)))) throw new Error('The generated engine still contains a local build path.');
+}
+const packed = JSON.parse(run('npm', ['pack', '@formepdf/core@0.20.1', '--ignore-scripts', '--json'], work, true))[0];
+const archive = resolve(work, packed.filename);
+if (createHash('sha512').update(readFileSync(archive)).digest('base64') !== originalIntegrity) throw new Error('The published upstream package failed its integrity check.');
+run('tar', ['-xzf', archive]);
+const pkg = resolve(work, 'package');
+for (const folder of ['pkg', 'pkg-web', 'pkg-node']) {
+  rmSync(resolve(pkg, folder), { recursive: true });
+  cpSync(resolve(source, 'packages/core', folder), resolve(pkg, folder), { recursive: true });
+  rmSync(resolve(pkg, folder, '.gitignore'), { force: true });
+}
+const manifest = JSON.parse(readFileSync(resolve(pkg, 'package.json'), 'utf8'));
+manifest.version = '0.20.1-opendoc.3';
+writeFileSync(resolve(pkg, 'package.json'), JSON.stringify(manifest, null, 2) + '\n');
+cpSync(resolve(source, 'LICENSE'), resolve(pkg, 'LICENSE'));
+run('npm', ['pack', '--ignore-scripts', '--pack-destination', destination], pkg);

package/src/assets/adapter.ts

@@ -0,0 +1,122 @@
+import { constants, lstatSync, readFileSync, renameSync } from 'node:fs';
+import { lstat, open, readFile, realpath, unlink, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { resolve } from 'node:path';
+import ts from 'typescript';
+import { AssetError, assertAssetId, assetHash, safeAssetPath } from './files';
+
+export function documentAssetAdapterSource(themeId: string) {
+  assertAssetId(themeId);
+  return `import { theme as base } from '../../themes/${themeId}';
+import { withDocumentAssets, type DocumentAssets } from 'opendoc/assets';
+import assets from './assets.json';
+
+export const theme = withDocumentAssets(base, assets as DocumentAssets);
+`;
+}
+const unsupported = () => new AssetError('This template uses a custom or ambiguous theme import. Ask your agent to pass withDocumentAssets(baseTheme, savedAssets) into its template factory before binding fonts. No source was changed.', 409);
+const conflict = () => new AssetError('This document changed while preparing its asset choices. Reload it before binding fonts. Your source was not overwritten.', 409);
+
+/** Upgrade recognized legacy imports without evaluating source or rewriting document content. */
+export async function ensureDocumentAssetAdapter(workspace: string, documentId: string): Promise<{ changed: boolean; theme?: string }> {
+  assertAssetId(documentId);
+  const root = await realpath(workspace), folder = resolve(root, 'documents', documentId);
+  safeAssetPath(root, folder, true);
+  const entry = safeAssetPath(root, resolve(folder, 'index.tsx'));
+  const initial = await lstat(entry);
+  if (initial.size > 1_000_000) throw new AssetError('This document entry is too large to adapt automatically. Ask your agent to use withDocumentAssets in its theme import.');
+  const contents = await readFile(entry, 'utf8'), digest = assetHash(contents);
+  const source = ts.createSourceFile(entry, contents, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  const imports = source.statements.filter(ts.isImportDeclaration).filter(node => ts.isStringLiteral(node.moduleSpecifier));
+  const pathFor = (node: ts.ImportDeclaration) => (node.moduleSpecifier as ts.StringLiteral).text;
+  const existing = imports.find(node => /^\.\/theme(?:\.tsx?)?$/.test(pathFor(node)) && !node.importClause?.isTypeOnly);
+  if (existing) {
+    const candidates = /\.tsx?$/.test(pathFor(existing)) ? [resolve(folder, pathFor(existing))] : [resolve(folder, 'theme.ts'), resolve(folder, 'theme.tsx')];
+    let file: string | undefined;
+    for (const candidate of candidates) { try { file = safeAssetPath(root, candidate); break; } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; } }
+    if (!file) throw new AssetError('This document is missing its local theme adapter. Restore that file before binding fonts.', 409);
+    const adapter = ts.createSourceFile(file, await readFile(file, 'utf8'), ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+    const helpers = new Set<string>();
+    for (const statement of adapter.statements) if (ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier) && /^(?:opendoc\/assets|\.\.\/\.\.\/src\/assets(?:\/index(?:\.ts)?)?)$/.test(statement.moduleSpecifier.text) && !statement.importClause?.isTypeOnly && statement.importClause?.namedBindings && ts.isNamedImports(statement.importClause.namedBindings)) {
+      for (const name of statement.importClause.namedBindings.elements) if (!name.isTypeOnly && (name.propertyName ?? name.name).text === 'withDocumentAssets') helpers.add(name.name.text);
+    }
+    let adapted = false;
+    const visit = (node: ts.Node) => { if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && helpers.has(node.expression.text)) adapted = true; ts.forEachChild(node, visit); };
+    visit(adapter);
+    if (!adapted) throw unsupported();
+    return { changed: false };
+  }
+  const selected: { declaration: ts.ImportDeclaration; theme: string; specifiers: ts.ImportSpecifier[] }[] = [];
+  let unsupportedThemeImport = false;
+  for (const declaration of imports) {
+    const path = pathFor(declaration), direct = /^\.\.\/\.\.\/themes\/([a-z0-9]+(?:-[a-z0-9]+)*)(?:\/index(?:\.ts)?)?$/.exec(path)?.[1];
+    const registry = /^(?:opendoc\/themes|\.\.\/\.\.\/themes(?:\/index(?:\.ts)?)?)$/.test(path);
+    if ((!direct && !registry) || declaration.importClause?.isTypeOnly) continue;
+    const clause = declaration.importClause;
+    if (!clause?.namedBindings || !ts.isNamedImports(clause.namedBindings) || clause.name) { unsupportedThemeImport = true; continue; }
+    const themes = new Map<string, ts.ImportSpecifier[]>();
+    for (const specifier of clause.namedBindings.elements) {
+      if (specifier.isTypeOnly) continue;
+      const imported = (specifier.propertyName ?? specifier.name).text;
+      const theme = direct ? imported === 'theme' || imported === direct ? direct : undefined : imported === 'neutral' ? imported : undefined;
+      if (theme) themes.set(theme, [...(themes.get(theme) ?? []), specifier]);
+    }
+    for (const [theme, specifiers] of themes) selected.push({ declaration, theme, specifiers });
+  }
+  const template = imports.some(node => !node.importClause?.isTypeOnly && /^(?:opendoc\/template$|\.\.\/\.\.\/(?:templates|src\/template)(?:\/|$))/.test(pathFor(node)));
+  if (unsupportedThemeImport || new Set(selected.map(item => item.theme)).size > 1 || (!selected.length && template)) throw unsupported();
+  // Ordinary legacy documents with no explicit theme use Document's runtime adapter.
+  if (!selected.length) return { changed: false };
+  const theme = selected[0].theme;
+  safeAssetPath(root, resolve(root, 'themes', theme, 'index.ts'));
+  if (await lstat(resolve(folder, 'theme.ts')).catch(error => { if (error.code === 'ENOENT') return null; throw error; })) throw new AssetError('This document already has a theme.ts that would shadow the asset adapter. Ask your agent to integrate its saved assets; the existing file was preserved.', 409);
+  const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed, removeComments: true });
+  const replacements = selected.map(item => {
+    const clause = item.declaration.importClause!, names = clause.namedBindings as ts.NamedImports;
+    const remaining = names.elements.filter(name => !item.specifiers.includes(name));
+    const themeImport = ts.factory.createImportDeclaration(undefined, ts.factory.createImportClause(false, undefined,
+      ts.factory.createNamedImports(item.specifiers.map(name => ts.factory.createImportSpecifier(false, name.name.text === 'theme' ? undefined : ts.factory.createIdentifier('theme'), ts.factory.createIdentifier(name.name.text))))), ts.factory.createStringLiteral('./theme'));
+    const rest = remaining.length ? ts.factory.updateImportDeclaration(item.declaration, item.declaration.modifiers,
+      ts.factory.updateImportClause(clause, clause.isTypeOnly, clause.name, ts.factory.createNamedImports(remaining)), item.declaration.moduleSpecifier, item.declaration.attributes) : undefined;
+    return { start: item.declaration.getStart(source), end: item.declaration.end, text: [rest, themeImport].filter(Boolean).map(node => printer.printNode(ts.EmitHint.Unspecified, node!, source)).join('\n') };
+  });
+  let updated = contents;
+  for (const replacement of replacements.sort((a, b) => b.start - a.start)) updated = updated.slice(0, replacement.start) + replacement.text + updated.slice(replacement.end);
+  const adapterFile = resolve(folder, 'theme.tsx'), adapterSource = documentAssetAdapterSource(theme);
+  const created = new Map<string, { ino: number; digest: string }>();
+  const pending = resolve(folder, `.asset-adapter-${randomUUID()}.tmp`);
+  const folderInfo = await lstat(folder);
+  function assertCurrent() {
+    safeAssetPath(root, folder, true); safeAssetPath(root, entry);
+    const currentFolder = lstatSync(folder), current = lstatSync(entry);
+    if (currentFolder.dev !== folderInfo.dev || currentFolder.ino !== folderInfo.ino || current.dev !== initial.dev || current.ino !== initial.ino || assetHash(readFileSync(entry)) !== digest) throw conflict();
+  }
+  async function createCompanion(file: string, value: string, acceptsExisting: boolean) {
+    assertCurrent();
+    let handle;
+    try { handle = await open(file, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o644); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+      safeAssetPath(root, file);
+      if (!acceptsExisting && await readFile(file, 'utf8') !== value) throw new AssetError('This document already has a custom theme.tsx. Ask your agent to integrate its saved assets; the existing file was preserved.', 409);
+      return;
+    }
+    try { const info = await handle.stat(); created.set(file, { ino: info.ino, digest: assetHash(value) }); await handle.writeFile(value); }
+    finally { await handle.close(); }
+  }
+  try {
+    // An empty manifest keeps a first-time upgrade renderable until the caller
+    // publishes its exact choices. Existing choices are never replaced here.
+    await createCompanion(resolve(folder, 'assets.json'), '{"version":1}\n', true);
+    await createCompanion(adapterFile, adapterSource, false);
+    await writeFile(pending, updated, { flag: 'wx', mode: initial.mode & 0o777 });
+    assertCurrent();
+    renameSync(pending, entry);
+    return { changed: true, theme };
+  } catch (error) {
+    for (const [file, identity] of created) {
+      try { if ((await lstat(file)).ino === identity.ino && assetHash(await readFile(file)) === identity.digest) await unlink(file); } catch { /* Preserve a companion changed by another writer. */ }
+    }
+    throw error;
+  } finally { await unlink(pending).catch(() => {}); }
+}