@ryanyahya/opendoc 0.4.0

package/src/app/ui/ui.css

@@ -0,0 +1,388 @@
+/* Shared interaction tokens. Document themes have their own independent palette. */
+:root {
+  --page-title-size: 18px;
+  --title-size: 14px;
+  --title-leading: 20px;
+  --label-size: 13px;
+  --label-leading: 18px;
+  --body-size: 13px;
+  --body-leading: 20px;
+  --control-radius: 6px;
+  --control-hit-size: 32px;
+  --data-row-height: 32px;
+  --browse-row-height: 40px;
+  --badge-height: 20px;
+  --badge-radius: 6px;
+  /* Reserved for a future switch; the app currently has no switch control. */
+  --switch-width: 24px;
+  --switch-height: 14px;
+  --switch-thumb-size: 10px;
+  --popup-radius: 6px;
+  --menu-font-size: 12.5px;
+  --menu-leading: 18px;
+  --menu-row-height: 32px;
+  --menu-padding: 4px;
+  --menu-item-padding: 5px 8px;
+  --menu-item-gap: 8px;
+  --menu-min-width: 184px;
+  --motion-quick: 140ms;
+}
+@media (pointer: coarse) {
+  :root { --data-row-height: 44px; --menu-row-height: 44px; }
+}
+#root {
+  isolation: isolate;
+}
+.ui-button {
+  cursor: pointer;
+  border: 1px solid var(--line);
+  border-radius: var(--control-radius);
+  background: var(--surface-raised);
+  color: inherit;
+  padding: 6px 10px;
+  font-size: var(--label-size);
+  line-height: var(--label-leading);
+  font-weight: 500;
+  min-width: var(--control-hit-size);
+  min-height: var(--control-hit-size);
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 7px;
+  transition:
+    background-color var(--motion-quick),
+    color var(--motion-quick),
+    box-shadow var(--motion-quick),
+    scale 140ms cubic-bezier(0.2, 0, 0, 1);
+}
+.ui-button:hover {
+  background: var(--control-hover);
+}
+.ui-button:active:not(:disabled) {
+  background: var(--control-active);
+}
+.ui-button:disabled,
+.ui-button[data-disabled] {
+  opacity: 0.45;
+  cursor: not-allowed;
+}
+:where(button, a, input, textarea, [tabindex]):focus-visible {
+  outline: 2px solid var(--focus-ring);
+  outline-offset: 3px;
+}
+:where(input, textarea):focus-visible {
+  outline: 1px solid var(--focus-ring);
+  outline-offset: -1px;
+  box-shadow: 0 0 3px color-mix(in srgb, var(--focus-ring) 25%, transparent);
+}
+.ui-button.primary {
+  background: var(--accent);
+  border-color: var(--accent);
+  color: var(--on-accent);
+  font-weight: 500;
+  box-shadow: var(--shadow-control);
+  padding: 6px 10px;
+}
+.ui-button.primary:hover {
+  background: var(--accent-hover);
+  border-color: var(--accent-hover);
+}
+.ui-button.primary:active:not(:disabled) {
+  background: var(--accent-active);
+  border-color: var(--accent-active);
+}
+.ui-button.icon-button {
+  background: transparent;
+  border: 0;
+  min-width: var(--control-hit-size);
+  min-height: var(--control-hit-size);
+  padding: 6px;
+}
+.ui-button.icon-button:hover {
+  background: var(--control-hover);
+}
+.ui-button.text-button {
+  border: 0;
+  background: transparent;
+  padding: 3px 0;
+  color: var(--accent-ink);
+  font-size: 13px;
+  justify-content: flex-start;
+}
+.ui-button.text-button:hover {
+  color: var(--accent-ink-hover);
+}
+.appearance-option { display: flex; align-items: center; gap: var(--menu-item-gap); }
+.ui-button.tool-button {
+  background: transparent;
+  border: 0;
+  font-size: var(--label-size);
+  line-height: var(--label-leading);
+  font-weight: 500;
+  padding: 7px 9px;
+  color: var(--muted);
+}
+.ui-button.tool-button:hover {
+  background: var(--control-hover);
+}
+.ui-button.tool-button[data-pressed] {
+  background: var(--selected-surface);
+  color: var(--accent-ink);
+}
+.ui-button.ui-select {
+  min-height: var(--control-hit-size);
+  min-width: 90px;
+  justify-content: space-between;
+  background: transparent;
+  border: 0;
+  padding: 6px 8px;
+  font-size: var(--label-size);
+  line-height: var(--label-leading);
+  font-weight: 500;
+}
+.ui-button.ui-select:hover,
+.ui-button.ui-select[data-popup-open] {
+  background: var(--control-hover);
+}
+.ui-positioner {
+  z-index: 62;
+  outline: 0;
+}
+.ui-menu-popup,
+.ui-popover-popup,
+.ui-select-popup {
+  max-width: calc(100vw - 24px);
+  max-height: var(--available-height);
+  overflow-y: auto;
+  padding: var(--menu-padding);
+  border: 1px solid var(--line);
+  border-radius: var(--popup-radius);
+  background: var(--popup-surface);
+  color: var(--ink);
+  box-shadow: var(--shadow-popup);
+}
+.ui-menu-popup { min-width: var(--menu-min-width); }
+.ui-select-popup {
+  min-width: min(max(var(--anchor-width), 128px), calc(100vw - 24px));
+  transform-origin: var(--transform-origin);
+  transition:
+    opacity var(--motion-quick),
+    transform var(--motion-quick);
+}
+.ui-menu-item,
+.ui-select-item {
+  display: flex;
+  align-items: center;
+  gap: var(--menu-item-gap);
+  padding: var(--menu-item-padding);
+  min-height: var(--menu-row-height);
+  border-radius: calc(var(--popup-radius) - 2px);
+  font-size: var(--menu-font-size);
+  line-height: var(--menu-leading);
+  font-weight: 400;
+  overflow-wrap: anywhere;
+  cursor: default;
+  user-select: none;
+  outline: 0;
+}
+.ui-menu-item[data-highlighted],
+.ui-select-item[data-highlighted],
+.ui-menu-item:focus-visible,
+.ui-select-item:focus-visible {
+  background: var(--control-hover);
+}
+.ui-select-item[data-selected] {
+  color: var(--accent-ink);
+  font-weight: 500;
+}
+.ui-select-item { justify-content: space-between; gap: 16px; }
+.ui-menu-item { cursor: pointer; background: transparent; }
+.ui-popover-popup .ui-menu-item { width: 100%; justify-content: flex-start; border: 0; text-decoration: none; }
+.ui-popover-popup .ui-menu-item:hover { background: var(--control-hover); }
+.ui-menu-item > svg { flex-shrink: 0; color: var(--muted); }
+.ui-menu-item > span:not(.pill):not(.ui-menu-check) { flex: 1; min-width: 0; }
+.ui-menu-item[data-disabled], .ui-select-item[data-disabled] { opacity: 0.45; cursor: default; }
+.ui-menu-check { margin-inline-start: auto; display: flex; }
+.ui-menu-label { margin: 0; padding: var(--menu-item-padding); font-size: var(--menu-font-size); line-height: var(--menu-leading); font-weight: 500; color: var(--muted); }
+.ui-menu-group { margin-top: 4px; }
+.ui-menu-separator { height: 1px; background: var(--line); margin: 3px var(--menu-padding); }
+.ui-menu-item-danger, .ui-menu-item-danger > svg { color: var(--destructive); }
+.ui-select-popup[data-starting-style],
+.ui-select-popup[data-ending-style] {
+  opacity: 0;
+  transform: translateY(-3px);
+}
+.ui-tooltip {
+  max-width: 240px;
+  background: var(--inverse-surface);
+  color: var(--inverse-ink);
+  border-radius: 5px;
+  padding: 6px 9px;
+  font-size: 11px;
+  line-height: 1.4;
+  box-shadow: var(--shadow-tooltip);
+  transition: opacity var(--motion-quick);
+}
+.ui-tooltip[data-starting-style],
+.ui-tooltip[data-ending-style] {
+  opacity: 0;
+}
+.ui-dialog-backdrop {
+  position: fixed;
+  inset: 0;
+  z-index: 60;
+  background: var(--backdrop);
+  transition: opacity 160ms;
+}
+.ui-dialog-backdrop[data-starting-style],
+.ui-dialog-backdrop[data-ending-style] {
+  opacity: 0;
+}
+.help-dialog {
+  position: fixed;
+  top: 50%;
+  left: 50%;
+  z-index: 61;
+  margin: 0;
+  width: min(490px, calc(100vw - 32px));
+  max-height: calc(100dvh - 48px);
+  overflow-y: auto;
+  transform: translate(-50%, -50%);
+  transition:
+    opacity 160ms,
+    translate 160ms;
+}
+.help-dialog[data-starting-style],
+.help-dialog[data-ending-style] {
+  opacity: 0;
+  translate: 0 6px;
+}
+.ui-notifications {
+  position: fixed;
+  bottom: 24px;
+  right: 24px;
+  z-index: 70;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  width: min(380px, calc(100vw - 32px));
+  outline: 0;
+}
+.ui-notification {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 12px 12px 12px 16px;
+  border: 1px solid var(--line);
+  border-radius: var(--popup-radius);
+  background: var(--popup-surface);
+  color: var(--ink);
+  box-shadow: var(--shadow-popup);
+  transition:
+    opacity 160ms,
+    transform 160ms;
+}
+.ui-notification-title {
+  font-size: 13px;
+  line-height: 1.5;
+  overflow-wrap: anywhere;
+}
+.ui-notification[data-kind="error"] {
+  border-color: var(--error-line);
+}
+.ui-notification[data-starting-style],
+.ui-notification[data-ending-style] {
+  opacity: 0;
+  transform: translateY(6px);
+}
+.ui-notification[data-limited] {
+  display: none;
+}
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    transition: none !important;
+    animation: none !important;
+    scroll-behavior: auto !important;
+  }
+}
+
+.ui-button:not([data-static]):active:not(:disabled):not([data-disabled]) {
+  scale: 0.96;
+}
+.ui-select {
+  font-variant-numeric: tabular-nums;
+}
+.copy-status-icon {
+  position: relative;
+  width: 16px;
+  height: 16px;
+  flex-shrink: 0;
+}
+.copy-status-icon > span {
+  position: absolute;
+  inset: 0;
+  display: grid;
+  place-items: center;
+  opacity: 1;
+  scale: 1;
+  filter: blur(0px);
+  transition:
+    opacity 300ms cubic-bezier(0.2, 0, 0, 1),
+    scale 300ms cubic-bezier(0.2, 0, 0, 1),
+    filter 300ms cubic-bezier(0.2, 0, 0, 1);
+}
+.copy-prompt:not([data-copied]) .copy-status-icon .copy-done,
+.copy-prompt[data-copied] .copy-status-icon .copy-idle {
+  opacity: 0;
+  scale: 0.25;
+  filter: blur(4px);
+}
+.copy-status-label {
+  display: grid;
+  text-align: start;
+}
+.copy-status-label > span {
+  grid-area: 1 / 1;
+}
+.copy-prompt:not([data-copied]) .copy-status-label .copy-done,
+.copy-prompt[data-copied] .copy-status-label .copy-idle {
+  visibility: hidden;
+}
+.ui-button.copy-prompt {
+  padding-inline-start: 12px;
+}
+@media (prefers-reduced-motion: reduce) {
+  .ui-button {
+    scale: 1 !important;
+  }
+}
+
+.search-field { display: flex; align-items: center; gap: 10px; min-width: 200px; max-width: 440px; flex: 1; min-height: var(--control-hit-size); padding: 0 10px; background: var(--surface-raised); border: 1px solid var(--line); border-radius: var(--control-radius); color: var(--muted); font-size: var(--body-size); line-height: var(--body-leading); }
+.search-field:focus-within { border-color: var(--focus-ring); box-shadow: 0 0 3px color-mix(in srgb, var(--focus-ring) 25%, transparent); }
+.search-field input { border: 0; background: none; outline: none; box-shadow: none; width: 100%; min-width: 0; padding: 5px 0; }
+.search-field input::placeholder { color: var(--muted); }
+@media (forced-colors: active) {
+  .search-field:focus-within { outline: 1px solid Highlight; outline-offset: -1px; }
+}
+@media (max-width: 620px) { .search-field { min-width: 0; flex-basis: 100%; } }
+.ui-tabs { display: flex; gap: 24px; border-bottom: 1px solid var(--line); margin-top: 24px; }
+.ui-tab { position: relative; appearance: none; border: 0; border-radius: 0; display: inline-flex; align-items: center; justify-content: center; min-height: 44px; padding: 12px 0; background: transparent; color: var(--muted); font: inherit; font-size: var(--label-size); line-height: var(--label-leading); font-weight: 500; cursor: pointer; }
+.ui-tab::after { content: ''; position: absolute; height: 2px; left: 0; right: 0; bottom: -1px; background: transparent; }
+.ui-tab:hover, .ui-tab[data-active] { color: var(--ink); }
+.ui-tab:hover::after { background: var(--line-strong); }
+.ui-tab[data-active]::after { background: var(--ink); }
+.ui-tab:focus-visible { outline-offset: -3px; border-radius: 4px; }

package/src/app/useReaderPreview.ts

@@ -0,0 +1,19 @@
+import { useEffect, useState } from 'react';
+import type { RenderArtifact } from '../shared/types';
+import { usePdf } from './Pdf';
+
+type Preview = { artifact?: RenderArtifact; pdfUrl?: string };
+
+/** Keep the last complete PDF and its geometry together while the next loads. */
+export function useReaderPreview(id: string, next: Preview) {
+  const [shown, setShown] = useState(next);
+  const loading = usePdf(id, next.artifact?.hash, true, 'documents', next.pdfUrl);
+  const previous = usePdf(id, shown.artifact?.hash, true, 'documents', shown.pdfUrl);
+  useEffect(() => {
+    if (loading.pdf) setShown(next);
+  }, [loading.pdf, next.artifact, next.pdfUrl]);
+  const error = loading.error;
+  return loading.pdf
+    ? { pdf: loading.pdf, artifact: next.artifact, error: '', loading: false, retry: loading.retry }
+    : { pdf: previous.pdf, artifact: shown.artifact, error, loading: !error, retry: loading.retry };
+}

package/src/app/useTextEditing.ts

@@ -0,0 +1,155 @@
+import { useEffect, useRef, useState } from 'react';
+import type { DocumentState } from '../shared/types';
+import type { TextEditPreview } from '../shared/selection';
+import { api } from './api';
+import {
+  createSession, createSessionStore, materializeTarget, pendingEdits,
+  rebaseSession, redo, sessionForDocument, undo, updateComponent, type EditSession,
+} from './editSession';
+
+const drafts = createSessionStore(() => window.sessionStorage);
+const memoryDrafts = new Map<string, EditSession>();
+type SaveReceipt = { id: string; revision: number };
+const receipts = new Map<string, SaveReceipt>();
+function readReceipt(id: string): SaveReceipt | undefined {
+  if (receipts.has(id)) return receipts.get(id);
+  try {
+    const receipt = JSON.parse(sessionStorage.getItem(`opendoc:saved-draft:${id}`) ?? 'null');
+    return typeof receipt?.id === 'string' && Number.isInteger(receipt.revision) ? receipt : undefined;
+  } catch { return undefined; }
+}
+function keepReceipt(id: string, receipt?: SaveReceipt) {
+  if (receipt) receipts.set(id, receipt); else receipts.delete(id);
+  try { if (receipt) sessionStorage.setItem(`opendoc:saved-draft:${id}`, JSON.stringify(receipt)); else sessionStorage.removeItem(`opendoc:saved-draft:${id}`); } catch { /* The current tab retains its receipt. */ }
+}
+
+/** Draft PDFs and source saves deliberately have separate lifetimes. */
+export function useTextEditing(state: DocumentState, connected: boolean, onState: (state: DocumentState) => void) {
+  const [storedSession, setSession] = useState<EditSession | null>(() => memoryDrafts.get(state.id) ?? drafts.read(state.id)?.session ?? null);
+  const session = sessionForDocument(storedSession, { revision: state.revision, hash: state.artifact?.hash });
+  const current = useRef(storedSession);
+  const [preview, setPreview] = useState<TextEditPreview | null>(null);
+  const [previewing, setPreviewing] = useState(false);
+  const [error, setError] = useState('');
+  const [saving, setSaving] = useState(() => !!readReceipt(state.id));
+  const [savedId, setSavedId] = useState<string | null>(() => readReceipt(state.id)?.id ?? null);
+  const [undoing, setUndoing] = useState(false);
+  const [saved, setSaved] = useState(false);
+  const requestVersion = useRef(0);
+  const previewAbort = useRef<AbortController | null>(null);
+  const previewTimer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  const busy = useRef(!!readReceipt(state.id));
+  const submitted = useRef<SaveReceipt | null>(readReceipt(state.id) ?? null);
+  const restoredSave = useRef(!!readReceipt(state.id));
+  const [persistenceFailed, setPersistenceFailed] = useState(false);
+  const changes = session ? pendingEdits(session) : [];
+  const count = changes.length;
+  const stale = !!session && (count > 0 || !!session.future.length) && (session.hash !== state.artifact?.hash || session.revision !== state.revision) && !savedId;
+  const previewKey = session ? JSON.stringify([session.hash, session.revision, changes]) : '';
+
+  function keep(next: EditSession | null) {
+    current.current = next;
+    setSession(next);
+    if (next) { memoryDrafts.set(state.id, next); setPersistenceFailed(!drafts.write(state.id, next)); }
+    else { memoryDrafts.delete(state.id); drafts.clear(state.id); setPersistenceFailed(false); }
+    setSaved(false);
+  }
+
+  useEffect(() => {
+    const version = ++requestVersion.current;
+    const controller = new AbortController();
+    previewAbort.current = controller;
+    if (!count) { setPreview(null); setPreviewing(false); return; }
+    if (stale || !connected || savedId) { setPreviewing(false); return; }
+    setPreviewing(true);
+    const timer = previewTimer.current = setTimeout(() => {
+      void api<TextEditPreview>(`/api/documents/${state.id}/edits/preview`, {
+        method: 'POST', body: JSON.stringify({ revision: session!.revision, hash: session!.hash, edits: changes }), signal: controller.signal,
+      }).then(next => {
+        if (version !== requestVersion.current) return;
+        setPreview(next); setError('');
+      }).catch((failure: Error) => {
+        if (!controller.signal.aborted && version === requestVersion.current) setError(failure.message);
+      }).finally(() => { if (version === requestVersion.current) setPreviewing(false); });
+    }, 450);
+    return () => { clearTimeout(timer); controller.abort(); };
+  }, [previewKey, stale, connected, savedId, state.id]);
+
+  useEffect(() => {
+    if (!savedId || (!restoredSave.current && state.revision <= (submitted.current?.revision ?? -1)) || state.status === 'rendering') return;
+    restoredSave.current = false;
+    if (state.manualEdit?.id !== savedId) {
+      keep(null); keepReceipt(state.id); setPreview(null); setSavedId(null); setSaving(false); busy.current = false;
+      setError('Your changes were saved. The document has since changed; you are viewing its latest version.');
+      return;
+    }
+    if (state.status === 'ready') {
+      keep(null); keepReceipt(state.id); setPreview(null); setSavedId(null); setSaving(false); setError(''); setSaved(true); busy.current = false;
+    } else if (state.status === 'error') {
+      setSaving(false); busy.current = false;
+      setError('Your changes were saved, but the PDF could not update. Undo the saved changes or ask your agent to repair the document.');
+    }
+  }, [savedId, state.status, state.revision, state.manualEdit?.id]);
+  useEffect(() => {
+    if (!persistenceFailed || !count) return;
+    const protect = (event: BeforeUnloadEvent) => { event.preventDefault(); event.returnValue = ''; };
+    window.addEventListener('beforeunload', protect);
+    return () => window.removeEventListener('beforeunload', protect);
+  }, [persistenceFailed, count]);
+  useEffect(() => { if (!saved) return; const timer = setTimeout(() => setSaved(false), 2500); return () => clearTimeout(timer); }, [saved]);
+
+  function target(id: string | undefined) {
+    if (!id) return undefined;
+    const active = sessionForDocument(current.current, { revision: state.revision, hash: state.artifact?.hash });
+    return active ? materializeTarget(active, id) : state.artifact?.textTargets?.find(item => item.id === id);
+  }
+  function change(targetId: string, text: string) {
+    if (busy.current || savedId) return 'Wait for the current save to finish.';
+    const base = sessionForDocument(current.current, { revision: state.revision, hash: state.artifact?.hash })
+      ?? createSession({ revision: state.revision, hash: state.artifact!.hash, targets: state.artifact?.textTargets ?? [] });
+    const result = updateComponent(base, targetId, text);
+    if (!result.error) { keep(result.session); setError(''); }
+    return result.error;
+  }
+  function discard() {
+    if (busy.current || savedId) return;
+    ++requestVersion.current; keep(null); setPreview(null); setPreviewing(false); setError('');
+  }
+  function undoDraft() { if (session && !busy.current && !savedId) { keep(undo(session)); setError(''); } }
+  function redoDraft() { if (session && !busy.current && !savedId) { keep(redo(session)); setError(''); } }
+  function refresh() {
+    if (!current.current || !state.artifact || state.status !== 'ready' || busy.current) return;
+    const result = rebaseSession(current.current, { revision: state.revision, hash: state.artifact.hash, targets: state.artifact.textTargets ?? [] });
+    if (result.error) setError(result.error);
+    else { keep(result.session); setError(''); }
+  }
+  async function save() {
+    const draft = current.current;
+    if (!draft || !pendingEdits(draft).length || busy.current || !connected || stale || state.status !== 'ready') return false;
+    busy.current = true; setSaving(true); setSaved(false); setError(''); ++requestVersion.current;
+    clearTimeout(previewTimer.current); previewAbort.current?.abort(); setPreviewing(false);
+    try {
+      const next = await api<DocumentState>(`/api/documents/${state.id}/edits`, {
+        method: 'POST', body: JSON.stringify({ revision: draft.revision, hash: draft.hash, edits: pendingEdits(draft) }),
+      });
+      if (!next.manualEdit) throw new Error('OpenDoc could not confirm this save. Your draft is still here.');
+      submitted.current = { id: next.manualEdit.id, revision: draft.revision };
+      keepReceipt(state.id, submitted.current);
+      setSavedId(next.manualEdit.id); onState(next);
+      return true;
+    } catch (failure) { setError((failure as Error).message); setSaving(false); busy.current = false; return false; }
+  }
+  async function undoSaved() {
+    if (!state.manualEdit?.canUndo || busy.current || !connected || (count && !savedId)) return false;
+    busy.current = true; setUndoing(true); setError('');
+    try {
+      const next = await api<DocumentState>(`/api/documents/${state.id}/edits/${state.manualEdit.id}/undo`, { method: 'POST', body: '{}' });
+      keep(null); keepReceipt(state.id); setPreview(null); setSavedId(null); setSaving(false); onState(next); return true;
+    } catch (failure) { setError((failure as Error).message); return false; }
+    finally { busy.current = false; setUndoing(false); }
+  }
+
+  return { session, preview, previewing, error, count, stale, saving, savedId, undoing, saved, persistenceFailed, dismissError: () => setError(''),
+    canUndo: !!session?.past.length, canRedo: !!session?.future.length,
+    target, change, discard, undoDraft, redoDraft, refresh, save, undoSaved };
+}

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(() => {}); }
+}