@ryanyahya/opendoc 0.4.0

package/src/app/editSession.ts

@@ -0,0 +1,238 @@
+import type { TextEditInput, TextSourceValue, TextTarget } from '../shared/selection';
+import { componentCorrection } from './componentCorrection';
+
+export type PendingTextEdit = Pick<TextEditInput, 'targetId' | 'start' | 'end' | 'replacement'>;
+export interface DraftTextEdit extends PendingTextEdit { sourceId: string }
+export interface EditSessionBaseline { revision: number; hash: string; targets: TextTarget[] }
+export interface EditSession extends EditSessionBaseline {
+  pending: DraftTextEdit[];
+  past: DraftTextEdit[][];
+  future: DraftTextEdit[][];
+  group?: { sourceId: string; at: number };
+}
+export interface EditSessionUpdate { session: EditSession; error?: string }
+
+const HISTORY_LIMIT = 50;
+const GROUP_MS = 500;
+const MAX_REPLACEMENT = 8_000;
+const STORAGE_PREFIX = 'opendoc:text-draft:';
+
+/** Identity always belongs to the captured source, never the changing preview offsets. */
+export function sourceIdentity(source: TextSourceValue): string {
+  return JSON.stringify([source.file, source.digest, source.start, source.end]);
+}
+
+function sourceBindings(targets: TextTarget[]) {
+  const bindings = new Map<string, { targetId: string; start: number; end: number; value: string }>();
+  for (const target of targets) for (const run of target.runs) {
+    if (!run.source || run.protected || run.source.value !== target.text.slice(run.start, run.end)) continue;
+    const id = sourceIdentity(run.source);
+    if (!bindings.has(id)) bindings.set(id, { targetId: target.id, start: run.start, end: run.end, value: run.source.value });
+  }
+  return bindings;
+}
+
+export function createSession(baseline: EditSessionBaseline): EditSession {
+  return { revision: baseline.revision, hash: baseline.hash, targets: structuredClone(baseline.targets), pending: [], past: [], future: [] };
+}
+
+/** An idle session must not bring old source text back after an external update. */
+export function sessionForDocument(session: EditSession | null, document: { revision: number; hash?: string }): EditSession | null {
+  if (!session) return null;
+  return session.pending.length || session.future.length || (session.revision === document.revision && session.hash === document.hash) ? session : null;
+}
+
+/** These targets are for editing; page geometry still belongs to the rendered PDF. */
+export function materializeTarget(session: EditSession, targetId: string): TextTarget | undefined {
+  const target = session.targets.find(target => target.id === targetId);
+  if (!target) return undefined;
+  const replacements = new Map(session.pending.map(edit => [edit.sourceId, edit.replacement]));
+  if (!target.runs.some(run => run.source && replacements.has(sourceIdentity(run.source)))) return target;
+  let text = '', cursor = 0;
+  const runs = target.runs.map(run => {
+    text += target.text.slice(cursor, run.start);
+    const start = text.length;
+    const replacement = run.source && replacements.get(sourceIdentity(run.source));
+    const value = typeof replacement === 'string' ? replacement : target.text.slice(run.start, run.end);
+    text += value;
+    cursor = run.end;
+    return { ...run, start, end: text.length, ...(run.source ? { source: { ...run.source, value } } : {}) };
+  });
+  text += target.text.slice(cursor);
+  return { ...target, text, runs };
+}
+
+export function pendingEdits(session: EditSession): PendingTextEdit[] {
+  return session.pending.map(({ targetId, start, end, replacement }) => ({ targetId, start, end, replacement }));
+}
+
+function equalEdits(left: DraftTextEdit[], right: DraftTextEdit[]) {
+  return left.length === right.length && left.every((edit, index) => edit.sourceId === right[index].sourceId && edit.replacement === right[index].replacement);
+}
+
+export function updateComponent(session: EditSession, targetId: string, text: string, now = Date.now()): EditSessionUpdate {
+  const target = materializeTarget(session, targetId);
+  if (!target) return { session, error: 'This component is no longer available.' };
+  if (text === target.text) return { session };
+  const correction = componentCorrection(target, text);
+  if (!correction) return { session, error: 'Change one text value at a time. Formatting and generated content need an agent.' };
+  if (correction.replacement.length > MAX_REPLACEMENT) return { session, error: 'Keep each text value under 8,000 characters.' };
+  const run = target.runs.find(run => run.source && !run.protected && run.start === correction.start && run.end === correction.end);
+  if (!run?.source) return { session, error: 'This text value is no longer editable.' };
+  const sourceId = sourceIdentity(run.source);
+  const binding = sourceBindings(session.targets).get(sourceId);
+  if (!binding) return { session, error: 'This text value is no longer editable.' };
+  const pending = session.pending.filter(edit => edit.sourceId !== sourceId);
+  if (correction.replacement !== binding.value) {
+    const edit = { sourceId, targetId: binding.targetId, start: binding.start, end: binding.end, replacement: correction.replacement };
+    // Keep a stable order when typing so history compares values, not edit order.
+    const previousIndex = session.pending.findIndex(edit => edit.sourceId === sourceId);
+    pending.splice(previousIndex < 0 ? pending.length : previousIndex, 0, edit);
+  }
+  if (equalEdits(pending, session.pending)) return { session };
+  const grouped = session.group?.sourceId === sourceId && now >= session.group.at && now - session.group.at <= GROUP_MS;
+  let past = grouped ? session.past : [...session.past, session.pending].slice(-HISTORY_LIMIT);
+  // Typing back to the beginning of a group should not leave an empty undo step.
+  const cancelled = past.length > 0 && equalEdits(pending, past[past.length - 1]);
+  if (cancelled) past = past.slice(0, -1);
+  return { session: { ...session, pending, past, future: [], group: cancelled ? undefined : { sourceId, at: now } } };
+}
+
+export function undo(session: EditSession): EditSession {
+  if (!session.past.length) return session;
+  return { ...session, pending: session.past[session.past.length - 1], past: session.past.slice(0, -1), future: [...session.future, session.pending].slice(-HISTORY_LIMIT), group: undefined };
+}
+
+export function redo(session: EditSession): EditSession {
+  if (!session.future.length) return session;
+  return { ...session, pending: session.future[session.future.length - 1], past: [...session.past, session.pending].slice(-HISTORY_LIMIT), future: session.future.slice(0, -1), group: undefined };
+}
+
+/** Rebase only after an explicit refresh; ambiguous or externally changed values stay untouched. */
+export function rebaseSession(session: EditSession, baseline: EditSessionBaseline): EditSessionUpdate {
+  const next = createSession(baseline);
+  const bindings = sourceBindings(next.targets);
+  const pending = new Map<string, DraftTextEdit>();
+  const conflict = (): EditSessionUpdate => ({ session, error: 'Some edited text changed outside this draft. Keep the draft open and ask your agent to reconcile it.' });
+  for (const edit of session.pending) {
+    let nextSourceId: string | undefined;
+    for (const previousTarget of session.targets) {
+      const previousRuns = previousTarget.runs.filter(run => run.source && sourceIdentity(run.source) === edit.sourceId);
+      if (!previousRuns.length) continue;
+      const target = next.targets.find(target => target.id === previousTarget.id);
+      if (!target || target.stable === false || previousTarget.stable === false) return conflict();
+      for (const previousRun of previousRuns) {
+        const source = previousRun.source!;
+        const identity = (source as TextSourceValue & { bindingId?: string }).bindingId ?? sourceIdentity(source);
+        let candidates = target.runs.filter(run => run.source && !run.protected
+          && ((run.source as TextSourceValue & { bindingId?: string }).bindingId ?? sourceIdentity(run.source)) === identity);
+        if (!candidates.length && target.text === previousTarget.text) {
+          candidates = target.runs.filter(run => run.source && !run.protected && run.start === previousRun.start && run.end === previousRun.end
+            && run.source.file === source.file && run.source.kind === source.kind && run.source.value === source.value);
+        }
+        if (!candidates.length || new Set(candidates.map(run => sourceIdentity(run.source!))).size !== 1
+          || candidates.some(run => run.source!.value !== source.value || target.text.slice(run.start, run.end) !== source.value)) return conflict();
+        const id = sourceIdentity(candidates[0].source!);
+        if (nextSourceId && nextSourceId !== id) return conflict();
+        nextSourceId = id;
+      }
+    }
+    if (!nextSourceId) return conflict();
+    const binding = bindings.get(nextSourceId);
+    if (!binding) return conflict();
+    const existing = pending.get(nextSourceId);
+    if (existing && existing.replacement !== edit.replacement) return conflict();
+    pending.set(nextSourceId, { sourceId: nextSourceId, targetId: binding.targetId, start: binding.start, end: binding.end, replacement: edit.replacement });
+  }
+  next.pending = [...pending.values()];
+  next.past = next.pending.length ? [[]] : [];
+  return { session: next };
+}
+
+type SessionStorage = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+type UnknownRecord = Record<string, unknown>;
+function record(value: unknown): value is UnknownRecord { return !!value && typeof value === 'object' && !Array.isArray(value); }
+function integer(value: unknown): value is number { return Number.isSafeInteger(value) && (value as number) >= 0; }
+function finite(value: unknown): value is number { return typeof value === 'number' && Number.isFinite(value); }
+function optionalString(value: unknown) { return value === undefined || typeof value === 'string'; }
+function optionalBoolean(value: unknown) { return value === undefined || typeof value === 'boolean'; }
+
+function validSource(value: unknown): value is TextSourceValue {
+  return record(value) && typeof value.file === 'string' && value.file.length > 0 && typeof value.digest === 'string' && value.digest.length > 0
+    && integer(value.start) && integer(value.end) && value.end > value.start
+    && ['jsx-text', 'jsx-attribute', 'string', 'json-string'].includes(value.kind as string) && typeof value.value === 'string'
+    && optionalString(value.bindingId) && (value.linkedOccurrences === undefined || integer(value.linkedOccurrences));
+}
+
+function validTarget(value: unknown): value is TextTarget {
+  if (!record(value) || typeof value.id !== 'string' || !value.id || typeof value.blockId !== 'string' || !value.blockId || typeof value.slot !== 'string'
+    || typeof value.text !== 'string' || !optionalBoolean(value.stable) || !optionalString(value.reason) || !Array.isArray(value.runs) || !Array.isArray(value.lines)) return false;
+  const text = value.text;
+  let previousEnd = 0;
+  for (const run of value.runs) {
+    if (!record(run) || !integer(run.start) || !integer(run.end) || run.start < previousEnd || run.end < run.start || run.end > text.length
+      || !optionalBoolean(run.protected) || !optionalString(run.reason) || (run.source !== undefined && (!validSource(run.source) || run.source.value !== text.slice(run.start, run.end)))) return false;
+    previousEnd = run.end;
+  }
+  return value.lines.every(line => record(line) && integer(line.page) && line.page > 0 && finite(line.x) && finite(line.y) && finite(line.width) && line.width >= 0
+    && finite(line.height) && line.height >= 0 && typeof line.text === 'string' && integer(line.start) && integer(line.end) && line.end >= line.start && line.end <= text.length);
+}
+
+/** Validate against the saved baseline so source drift preserves a recoverable, stale draft. */
+function restoredSession(value: unknown): EditSession | undefined {
+  if (!record(value) || value.version !== 1 || !record(value.session)) return undefined;
+  const session = value.session;
+  if (!integer(session.revision) || typeof session.hash !== 'string' || !session.hash || !Array.isArray(session.targets) || !session.targets.every(validTarget)
+    || new Set(session.targets.map(target => target.id)).size !== session.targets.length) return undefined;
+  const targets = session.targets;
+  const sourceValues = new Map<string, string>();
+  for (const target of targets) for (const run of target.runs) if (run.source) {
+    const key = sourceIdentity(run.source);
+    if (sourceValues.has(key) && sourceValues.get(key) !== run.source.value) return undefined;
+    sourceValues.set(key, run.source.value);
+  }
+  const bindings = sourceBindings(targets);
+  function validSnapshot(snapshot: unknown): snapshot is DraftTextEdit[] {
+    if (!Array.isArray(snapshot) || snapshot.length > bindings.size) return false;
+    const ids = new Set<string>();
+    for (const edit of snapshot) {
+      if (!record(edit) || typeof edit.sourceId !== 'string' || ids.has(edit.sourceId) || typeof edit.replacement !== 'string' || edit.replacement.length > MAX_REPLACEMENT) return false;
+      const binding = bindings.get(edit.sourceId);
+      if (!binding || edit.targetId !== binding.targetId || edit.start !== binding.start || edit.end !== binding.end || edit.replacement === binding.value) return false;
+      ids.add(edit.sourceId);
+    }
+    return true;
+  }
+  if (!validSnapshot(session.pending) || !Array.isArray(session.past) || session.past.length > HISTORY_LIMIT || !session.past.every(validSnapshot)
+    || !Array.isArray(session.future) || session.future.length > HISTORY_LIMIT || !session.future.every(validSnapshot)) return undefined;
+  // A reload is a fresh typing group. Only validated fields survive restoration.
+  return { revision: session.revision, hash: session.hash, targets, pending: session.pending, past: session.past, future: session.future };
+}
+
+/** Inject sessionStorage at the UI boundary; the model is also usable without a browser. */
+export function createSessionStore(storage: SessionStorage | (() => SessionStorage)) {
+  const access = () => typeof storage === 'function' ? storage() : storage;
+  const key = (documentId: string) => `${STORAGE_PREFIX}${encodeURIComponent(documentId)}`;
+  return {
+    read(documentId: string, current?: Pick<EditSessionBaseline, 'revision' | 'hash'>): { session: EditSession; stale: boolean } | undefined {
+      try {
+        const raw = access().getItem(key(documentId));
+        if (raw === null) return undefined;
+        const session = restoredSession(JSON.parse(raw));
+        if (!session) { access().removeItem(key(documentId)); return undefined; }
+        return { session, stale: !!current && (session.revision !== current.revision || session.hash !== current.hash) };
+      } catch {
+        try { access().removeItem(key(documentId)); } catch { /* Storage itself may be unavailable. */ }
+        return undefined;
+      }
+    },
+    write(documentId: string, session: EditSession): boolean {
+      try { access().setItem(key(documentId), JSON.stringify({ version: 1, session: { ...session, group: undefined, past: session.past.slice(-HISTORY_LIMIT), future: session.future.slice(-HISTORY_LIMIT) } })); return true; }
+      catch { return false; }
+    },
+    clear(documentId: string): boolean {
+      try { access().removeItem(key(documentId)); return true; }
+      catch { return false; }
+    },
+  };
+}

package/src/app/editorRecovery.ts

@@ -0,0 +1,25 @@
+export interface EditorBaseline { hash: string; revision: number; text: string }
+export interface OpenEditorRecord { targetId: string; text: string; baseline?: EditorBaseline }
+export interface EditorRecovery { record: OpenEditorRecord; stage: boolean; error?: string }
+
+export function readOpenEditor(value: unknown): OpenEditorRecord | undefined {
+  if (!value || typeof value !== 'object') return undefined;
+  const record = value as Partial<OpenEditorRecord>;
+  if (typeof record.targetId !== 'string' || typeof record.text !== 'string' || record.text.length > 8000) return undefined;
+  const baseline = record.baseline;
+  return { targetId: record.targetId, text: record.text, ...(baseline && typeof baseline.hash === 'string' && Number.isInteger(baseline.revision) && typeof baseline.text === 'string' ? { baseline } : {}) };
+}
+
+/** Raw editor recovery cannot establish a new source baseline for old wording. */
+export function recoverEditor(record: OpenEditorRecord, current: EditorBaseline, pending?: EditorBaseline, typing = false): EditorRecovery {
+  const unchanged = !!record.baseline && record.text === record.baseline.text;
+  // A validated pending session already owns this exact text and its source guards.
+  // An untouched older editor must also not undo a newer accepted draft on restore.
+  if (pending && (record.text === pending.text || (!typing && unchanged))) return { record: { ...record, text: pending.text, baseline: pending }, stage: false };
+  if (!record.baseline && record.text === current.text) return { record: { ...record, baseline: current }, stage: false };
+  if (!record.baseline) return { record, stage: false, error: 'This recovered text needs review before it can join your draft.' };
+  const matches = record.baseline.hash === current.hash && record.baseline.revision === current.revision;
+  if (matches) return { record, stage: record.text !== (pending?.text ?? current.text) };
+  if (unchanged && !typing) return { record: { ...record, text: current.text, baseline: current }, stage: false };
+  return { record, stage: false, error: 'The document changed. Your text is kept here for review.' };
+}

package/src/app/export-history.css

@@ -0,0 +1,31 @@
+.help-dialog.export-history-dialog { width: min(660px, calc(100vw - 32px)); max-width: 660px; max-height: min(780px, calc(100dvh - 48px)); display: flex; flex-direction: column; padding: 28px; }
+.export-history-heading { display: flex; align-items: center; gap: 14px; padding-right: 26px; min-width: 0; }
+.export-history-heading > div { min-width: 0; }
+.help-dialog .export-history-heading h2 { margin: 0 0 5px; }
+.help-dialog .export-history-heading p { margin: 0; overflow-wrap: anywhere; }
+.export-history-symbol { color: var(--muted); display: grid; place-items: center; flex: 0 0 44px; height: 44px; background: var(--surface-alt); border: 1px solid var(--line); border-radius: 12px; }
+.export-history-summary { display: flex; align-items: center; justify-content: space-between; gap: 12px; margin: 22px 0 8px; color: var(--muted); font-size: 12px; }
+.export-history-summary .text-button { font-size: 12px; }
+.export-history-content { overflow-y: auto; min-height: 110px; overscroll-behavior: contain; margin: 0 -8px; padding: 0 8px; }
+.export-history-list { list-style: none; padding: 0; margin: 0; }
+.export-history-row { display: flex; align-items: center; gap: 14px; padding: 16px 0; border-top: 1px solid var(--line); }
+.export-history-paper { width: 40px; height: 52px; display: flex; flex-direction: column; align-items: center; justify-content: center; flex-shrink: 0; gap: 2px; color: var(--muted); background: var(--surface-alt); border: 1px solid var(--line); border-radius: 5px; }
+.export-history-paper > span { font-size: 8px; font-weight: 650; letter-spacing: .08em; }
+.export-history-details { min-width: 0; flex: 1; display: flex; flex-direction: column; gap: 6px; }
+.export-history-details > a, .export-history-details > strong { font-size: 13px; font-weight: 550; line-height: 1.45; color: var(--ink); overflow-wrap: anywhere; text-decoration: none; }
+.export-history-details > a:hover { text-decoration: underline; text-underline-offset: 3px; }
+.export-history-details > span { font-size: 11px; color: var(--muted); line-height: 1.5; }
+.export-history-actions { display: flex; align-items: center; gap: 2px; }
+.export-history-actions .icon-button { width: 32px; height: 32px; }
+.export-history-delete:hover:not(:disabled) { color: var(--destructive); }
+.export-history-empty { display: flex; flex-direction: column; align-items: center; text-align: center; padding: 32px 16px; gap: 12px; color: var(--muted); }
+.export-history-empty strong { font-size: 14px; color: var(--ink); }
+.export-history-empty p { font-size: 13px; margin: 0; }
+.help-dialog .export-history-footnote { font-size: 11px; line-height: 1.6; color: var(--muted); padding-top: 16px; margin: 8px 0 0; border-top: 1px solid var(--line); }
+@media (max-width: 520px) {
+  .help-dialog.export-history-dialog { padding: 22px 18px; }
+  .export-history-row { gap: 10px; flex-wrap: wrap; }
+  .export-history-actions { margin-left: auto; }
+  .export-history-paper { display: none; }
+  .export-history-details { flex-basis: calc(100% - 110px); }
+}

package/src/app/export.css

@@ -0,0 +1,17 @@
+.export-dropdown { width: 320px; }
+.export-dropdown-body { padding: 8px; }
+.export-dropdown-heading { display: flex; align-items: center; justify-content: space-between; gap: 12px; }
+.export-dropdown-heading h2 { margin: 0; font-size: var(--title-size); line-height: var(--title-leading); font-weight: 500; }
+.export-dropdown-heading .icon-button { margin: -4px -4px -4px 0; }
+.export-dropdown-body > p { margin: 6px 0 0; color: var(--muted); font-size: var(--label-size); line-height: 1.5; }
+.export-dropdown .export-filename { display: grid; gap: 8px; margin-top: 18px; }
+.export-format { display: grid; gap: 8px; margin-top: 16px; }
+.export-format .ui-select { width: 100%; justify-content: space-between; }
+.export-file { display: flex; align-items: center; gap: 10px; padding-block: 16px 6px; }
+.export-file > div { flex: 1; min-width: 0; }
+.export-file strong { display: block; font-size: var(--label-size); font-weight: 500; overflow-wrap: anywhere; }
+.export-file span { display: block; margin-top: 4px; font-size: 12px; color: var(--muted); }
+.export-status { padding: 10px; margin: 12px 0 0; background: var(--surface-raised); border: 1px solid var(--control-line); border-radius: var(--control-radius); font-size: var(--label-size); line-height: 1.5; }
+.export-status p { margin: 6px 0 10px; }
+.export-dropdown-body > .field-error { color: var(--destructive); }
+.export-save { width: 100%; justify-content: center; margin-top: 16px; }

package/src/app/guideLinks.ts

@@ -0,0 +1,21 @@
+export type GuideLocation = { file: string; fragment?: string };
+type GuideLink = { kind: 'guide'; location: GuideLocation } | { kind: 'external'; href: string };
+
+/** Resolve links against the guide file, never the app's URL or navigation hash. */
+export function resolveGuideLink(file: string, href: string): GuideLink | undefined {
+  href = href.trim();
+  if (!href) return undefined;
+  if (/^(https?:)?\/\//i.test(href)) return { kind: 'external', href };
+  if (/^[a-z][a-z\d+.-]*:/i.test(href) || href.includes('\\')) return undefined;
+  try {
+    const url = new URL(href, `https://guides.invalid/${file}`);
+    if (url.origin !== 'https://guides.invalid') return undefined;
+    const path = decodeURIComponent(url.pathname).replace(/^\/+/, '');
+    if (!path.endsWith('.md')) return undefined;
+    return { kind: 'guide', location: { file: path, ...(url.hash ? { fragment: decodeURIComponent(url.hash.slice(1)) } : {}) } };
+  } catch { return undefined; }
+}
+
+export function guideHeadingSlug(text: string) {
+  return text.trim().toLowerCase().replace(/[^\p{L}\p{N}\s_-]/gu, '').replace(/\s+/g, '-');
+}

package/src/app/guides.css

@@ -0,0 +1,40 @@
+.template-guide-trigger { margin-top: 12px; }
+.help-dialog.template-guide-dialog { width: min(760px, calc(100vw - 32px)); max-width: 760px; padding: 0; overflow: hidden; display: flex; flex-direction: column; }
+.template-guide-heading { position: relative; padding: 24px 64px 20px 32px; border-bottom: 1px solid var(--line); flex-shrink: 0; }
+.template-guide-dialog .template-guide-heading h2 { font-size: var(--title-size); line-height: var(--title-leading); font-weight: 500; margin: 0; }
+.template-guide-dialog .template-guide-heading p { margin: 5px 0 0; font-size: 13px; }
+.template-guide-body { padding: 28px 32px 36px; overflow-y: auto; overscroll-behavior: contain; min-height: 0; overflow-wrap: anywhere; }
+.template-guide-body:focus-visible { outline: 2px solid var(--focus-ring); outline-offset: -4px; }
+.template-guide-body > p:first-child, .template-guide-body > div > p:first-child { margin-top: 0; }
+.markdown-body { font-size: 15px; line-height: 1.75; color: var(--ink); }
+.template-guide-dialog .markdown-body :is(h1, h2, h3, h4, h5, h6) { font-family: inherit; color: var(--ink); line-height: 1.3; letter-spacing: -0.02em; margin: 1.6em 0 0.65em; font-weight: 600; }
+.markdown-body h1 { font-size: 26px; }
+.template-guide-dialog .markdown-body h2 { font-size: 21px; }
+.markdown-body h3 { font-size: 18px; }
+.markdown-body :is(h4, h5, h6) { font-size: 16px; }
+.markdown-body > :first-child { margin-top: 0; }
+.markdown-body > :last-child { margin-bottom: 0; }
+.template-guide-dialog .markdown-body p { color: inherit; font-size: inherit; line-height: inherit; margin: 0 0 1em; }
+.markdown-body :is(ul, ol) { padding-left: 24px; margin: 0 0 1em; }
+.markdown-body li + li { margin-top: 0.4em; }
+.markdown-body li > :is(ul, ol) { margin: 0.4em 0; }
+.markdown-body li > p { margin-bottom: 0.5em; }
+.markdown-body a { color: var(--accent-ink); text-decoration: underline; text-underline-offset: 3px; }
+.markdown-body code { font-family: ui-monospace, monospace; font-size: 0.88em; background: var(--surface-alt); padding: 2px 5px; border-radius: 4px; }
+.markdown-body pre { overflow-x: auto; padding: 16px; margin: 0 0 1em; background: var(--surface); border: 1px solid var(--line); border-radius: 6px; line-height: 1.6; }
+.markdown-body pre code { padding: 0; background: none; border-radius: 0; overflow-wrap: normal; }
+.markdown-body blockquote { margin: 0 0 1em; padding: 2px 0 2px 18px; border-left: 3px solid var(--line-strong); color: var(--muted); }
+.markdown-body blockquote > :last-child { margin-bottom: 0; }
+.markdown-body hr { border: 0; border-top: 1px solid var(--line); margin: 28px 0; }
+.markdown-body img { max-width: 100%; height: auto; }
+.markdown-table { overflow-x: auto; margin-bottom: 1em; }
+.markdown-body table { border-collapse: collapse; width: 100%; font-size: 14px; }
+.markdown-body :is(th, td) { padding: 9px 12px; border: 1px solid var(--line); text-align: left; }
+.markdown-body th { background: var(--surface); font-weight: 600; }
+.markdown-body .contains-task-list { list-style: none; padding-left: 0; }
+.markdown-body .task-list-item input { margin-right: 8px; }
+.guide-back { margin-top: 8px; }
+@media (max-width: 620px) {
+  .template-guide-heading { padding: 20px 56px 16px 20px; }
+  .template-guide-body { padding: 24px 20px 28px; }
+}

package/src/app/main.tsx

@@ -0,0 +1,221 @@
+import { ExportHistoryDialog } from "./ExportHistoryDialog";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { createRoot } from "react-dom/client";
+import { AssetsBrowser } from "./AssetsBrowser";
+import { TemplatesBrowser } from "./TemplatesBrowser";
+import { ThemesBrowser } from "./ThemesBrowser";
+import { Reader } from "./Reader";
+import { CreateDocumentDialog } from "./CreateDocumentDialog";
+import { ProjectDialog, MoveDocumentDialog } from "./ProjectDialogs";
+import { ProjectDocuments, DocumentsBrowser } from "./DocumentsBrowser";
+import { Sidebar } from "./Sidebar";
+import { AppearanceMenuItems } from "./AppearanceControl";
+import { DocumentActionDialog, DocumentMenuItems, type DocumentActionHandler } from "./DocumentActions";
+import { useAppearance } from "./appearance";
+import { useDocumentView } from "./DocumentViewControl";
+import { Icon } from "./ui/Icon";
+import { Button, IconButton, UiProvider, useNotifications } from "./ui";
+import { api } from "./api";
+import type { ThemeSummary } from "../shared/themes";
+import { documentName, documentFormat, type DocumentFormat, type DocumentState, type DocumentSummary } from "../shared/types";
+import { emptyProjects, type Project, type ProjectsManifest } from "../shared/projects";
+import "./style.css";
+
+function route() {
+  const hash = location.hash.slice(1);
+  if (hash === "presentations") return { view: "presentations", id: "" };
+  if (hash === "themes" || hash.startsWith("themes/")) return { view: "themes", id: hash.slice(7) };
+  const [templatePath, templateQuery] = hash.split('?');
+  if (templatePath === "templates" || templatePath.startsWith("templates/")) return { view: "templates", id: templatePath.slice(10), templateFormat: new URLSearchParams(templateQuery).get('format') === 'presentation' ? 'presentation' as const : 'document' as const };
+  if (hash === "assets" || hash.startsWith("assets/")) return { view: "assets", id: hash.slice(7) || "media" };
+  if (hash === "media" || hash.startsWith("media/")) return { view: "assets", id: `media${hash.length > 5 ? `/${hash.slice(6)}` : ""}` };
+  if (hash.startsWith("project/")) return { view: "project", id: hash.slice(8) };
+  return hash.startsWith("document/")
+    ? { view: "document", id: hash.slice(9) }
+    : { view: "library", id: "" };
+}
+const go = (hash: string) => { location.hash = hash; };
+
+function App() {
+  const { appearance, changeAppearance } = useAppearance();
+  const { view: documentView, changeView: changeDocumentView } = useDocumentView();
+  const [current, setCurrent] = useState(route);
+  const lastBrowseRoute = useRef<ReturnType<typeof route> | null>(null);
+  useEffect(() => { if (current.view !== "document") lastBrowseRoute.current = current; }, [current]);
+  const [documents, setDocuments] = useState<DocumentSummary[]>([]);
+  const [themes, setThemes] = useState<ThemeSummary[]>([]);
+  const [manifest, setManifest] = useState<ProjectsManifest>(emptyProjects);
+  const [error, setError] = useState("");
+  const [connected, setConnected] = useState(true);
+  const [help, setHelp] = useState(false);
+  const [creationFormat, setCreationFormat] = useState<DocumentFormat>('document');
+  const [projectDialog, setProjectDialog] = useState<{ project: Project | null } | null>(null);
+  const notifications = useNotifications();
+  const [exportDocument, setExportDocument] = useState<DocumentSummary | null>(null);
+  const [documentAction, setDocumentAction] = useState<{ document: DocumentSummary; action: "rename" | "delete" } | null>(null);
+  const [duplicating, setDuplicating] = useState(false);
+  const copying = useRef(false);
+  const [moving, setMoving] = useState<DocumentSummary | null>(null);
+  const [generation, setGeneration] = useState(0);
+  const [loaded, setLoaded] = useState(false);
+  const refreshing = useRef<Promise<void> | null>(null);
+  const refreshAgain = useRef(false);
+  const requestAbort = useRef<AbortController | null>(null);
+  const refresh = useCallback(() => {
+    refreshAgain.current = true;
+    if (refreshing.current) return refreshing.current;
+    refreshing.current = (async () => {
+      do {
+        refreshAgain.current = false;
+        try {
+          const [next, projects, nextThemes] = await Promise.all([
+            api<DocumentSummary[]>("/api/documents?view=summary", { signal: requestAbort.current?.signal }),
+            api<ProjectsManifest>("/api/projects", { signal: requestAbort.current?.signal }),
+            api<ThemeSummary[]>("/api/themes", { signal: requestAbort.current?.signal }),
+          ]);
+          if (requestAbort.current?.signal.aborted) return;
+          setManifest(projects);
+          setThemes(nextThemes);
+          setDocuments((previous) => {
+            const existing = new Map(previous.map((item) => [item.id, item]));
+            const merged = next.map((item) => {
+              const before = existing.get(item.id);
+              return before && JSON.stringify(before) === JSON.stringify(item) ? before : item;
+            });
+            return merged.length === previous.length && merged.every((item, index) => item === previous[index]) ? previous : merged;
+          });
+          setError(""); setLoaded(true); setGeneration((value) => value + 1);
+        } catch (error) { if (!requestAbort.current?.signal.aborted) setError((error as Error).message); }
+      } while (refreshAgain.current && !requestAbort.current?.signal.aborted);
+    })().finally(() => { refreshing.current = null; });
+    return refreshing.current;
+  }, []);
+  useEffect(() => {
+    requestAbort.current = new AbortController();
+    void refresh();
+    let events: WebSocket;
+    let stopped = false;
+    let reconnectTimer: ReturnType<typeof setTimeout> | undefined;
+    let reconnectDelay = 500;
+    let refreshTimer: ReturnType<typeof setTimeout> | undefined;
+    const connect = () => {
+      events = new WebSocket(`${location.protocol === 'https:' ? 'wss:' : 'ws:'}//${location.host}/api/events`);
+      events.onopen = () => { reconnectDelay = 500; setConnected(true); };
+      events.onmessage = (event) => {
+        if (stopped || !['connected', 'changed'].includes(event.data)) return;
+        // Catch up after every connection, including changes during initial loading.
+        clearTimeout(refreshTimer); refreshTimer = setTimeout(() => void refresh(), 80);
+      };
+      events.onerror = () => { setConnected(false); events.close(); };
+      events.onclose = () => {
+        if (stopped) return;
+        setConnected(false);
+        reconnectTimer = setTimeout(connect, reconnectDelay);
+        reconnectDelay = Math.min(reconnectDelay * 2, 5_000);
+      };
+    };
+    connect();
+    const change = () => setCurrent(route());
+    window.addEventListener("hashchange", change);
+    return () => { stopped = true; clearTimeout(reconnectTimer); events.close(); clearTimeout(refreshTimer); requestAbort.current?.abort(); window.removeEventListener("hashchange", change); };
+  }, [refresh]);
+  const activeSummary = current.view === "document" ? documents.find(document => document.id === current.id) : undefined;
+  const [detail, setDetail] = useState<{ key: string; state: DocumentState }>();
+  const [detailAttempt, setDetailAttempt] = useState(0);
+  const [detailError, setDetailError] = useState('');
+  const detailKey = activeSummary ? JSON.stringify(activeSummary) : '';
+  const activeId = activeSummary?.id;
+  useEffect(() => {
+    if (!activeId) return;
+    const controller = new AbortController();
+    setDetailError('');
+    void api<DocumentState>(`/api/documents/${activeId}`, { signal: controller.signal })
+      .then(state => { if (!controller.signal.aborted) setDetail({ key: detailKey, state }); })
+      .catch(error => { if (!controller.signal.aborted) setDetailError(error.message); });
+    return () => controller.abort();
+  }, [activeId, detailKey, detailAttempt]);
+  // Keep the previous PDF visible during a refresh, with currentness controls disabled.
+  const active: DocumentState | undefined = activeSummary ? detail?.key === detailKey ? detail.state : {
+    ...activeSummary, status: 'rendering', artifact: detail?.state.id === activeSummary.id ? detail.state.artifact : undefined,
+  } : undefined;
+  const routeProjectId = current.view === "project" ? current.id : active?.projectId;
+  const project = manifest.projects.find(project => project.id === routeProjectId);
+  const origin = lastBrowseRoute.current;
+  const originProject = origin?.view === "project" ? manifest.projects.find(project => project.id === origin.id) : undefined;
+  const backHash = origin
+    ? origin.view === "project" ? originProject ? `project/${originProject.id}` : "library" : `${origin.view}${origin.id ? `/${origin.id}` : ""}${origin.view === 'templates' && origin.templateFormat === 'presentation' ? '?format=presentation' : ''}`
+    : project ? `project/${project.id}` : activeSummary && documentFormat(activeSummary) === "presentation" ? "presentations" : "library";
+  const backLabel = origin
+    ? origin.view === "project" ? originProject?.name ?? "Documents" : ({ library: "Documents", presentations: "Presentations", assets: "Media & Assets", templates: "Templates", themes: "Themes" }[origin.view] ?? "Documents")
+    : project?.name ?? (activeSummary && documentFormat(activeSummary) === "presentation" ? "Presentations" : "Documents");
+  const projectDocuments = documents.filter(document => document.projectId === project?.id);
+  useEffect(() => {
+    if (current.view !== "document" && current.view !== "assets" && current.view !== "themes") void api("/api/context", {
+      method: "POST", body: JSON.stringify({ projectId: current.view === "project" ? project?.id ?? null : null, documentId: null, blockId: null, page: 1, themeId: null, selectedAsset: null }),
+    }).catch(() => {});
+  }, [current.view, project?.id]);
+  useEffect(() => {
+    document.title = active ? `${documentName(active)} · OpenDoc` : project ? `${project.name} · OpenDoc` : "OpenDoc";
+  }, [active?.artifact?.meta.title, active?.name, active?.id, project?.name]);
+  const onDocumentAction: DocumentActionHandler = (document, action) => {
+    if (action === "exports") { setExportDocument(document); return; }
+    if (action === "move") { setMoving(document); return; }
+    if (action !== "duplicate") { setDocumentAction({ document, action }); return; }
+    if (copying.current || !connected) return;
+    copying.current = true; setDuplicating(true);
+    void api<{ id: string; name: string }>(`/api/documents/${document.id}/duplicate`, { method: 'POST' }).then(async copy => {
+      await refresh();
+      notifications.success(`${copy.name} created`, { label: 'Open', onClick: () => go(`document/${copy.id}`) });
+    }).catch(error => notifications.error(error.message)).finally(() => { copying.current = false; setDuplicating(false); });
+  };
+  const createProject = () => setProjectDialog({ project: null });
+  const createDocument = (format: DocumentFormat = 'document') => { setCreationFormat(format); setHelp(true); };
+  return <div className={`app ${current.view === "document" ? "reading" : ""}`}>
+    {current.view !== "document" && <Sidebar view={current.view} projectId={project?.id} projects={manifest.projects} documents={documents} loaded={loaded} connected={connected} appearance={appearance} onAppearanceChange={changeAppearance} onCreateProject={createProject} onProjectSettings={project => setProjectDialog({ project })} />}
+    <main className="main">
+      {current.view === "document" && !active && <header className="topbar">
+        <IconButton label={`Back to ${backLabel}`} render={<a href={`#${backHash}`} />} nativeButton={false}><Icon name="left" /></IconButton>
+        <div className="breadcrumb"><a href={project ? `#project/${project.id}` : "#library"} title={project?.name ?? "Documents"}>{project?.name ?? "Documents"}</a><span>/</span><span>Document</span></div>
+      </header>}
+      {!connected && <div className="connection-banner" role="status">Connection lost. Reconnecting to OpenDoc. Editing and export will resume when the server returns.</div>}
+      {detailError && activeSummary && <div className="error-banner" role="alert"><span>{detailError}</span><Button onClick={() => setDetailAttempt(value => value + 1)}>Try again</Button></div>}
+      {error && <div className="error-banner" role="alert"><span>{error}</span><Button className="text-button" onClick={() => void refresh()}>Try again</Button></div>}
+      {current.view === "document" ? active ? <Reader key={active.id} state={active} generation={generation} connected={connected} onShowExports={() => setExportDocument(active)}
+        identity={<>
+          <IconButton label={`Back to ${backLabel}`} className="reader-back" render={<a href={`#${backHash}`} />} nativeButton={false}><Icon name="left" size={17} /></IconButton>
+          <div className="reader-document"><a href={project ? `#project/${project.id}` : "#library"} title={project?.name ?? "Documents"}>{project?.name ?? "Documents"}</a><span className="reader-context-separator" aria-hidden="true">/</span><span className="reader-document-title" title={documentName(active)}>{documentName(active)}</span></div>
+        </>}
+        options={<>
+          <DocumentMenuItems document={active} onAction={onDocumentAction} disabled={!connected || duplicating} />
+          <AppearanceMenuItems value={appearance} onChange={changeAppearance} />
+        </>}
+      /> : <div className="empty-state"><h1>{loaded ? "Document not found" : error ? "Workspace unavailable" : "Loading document…"}</h1><p>{loaded ? "Its source may have been moved or removed from this workspace." : "Opening your local workspace."}</p><Button onClick={() => go("library")}>Back to documents</Button></div>
+        : current.view === "project" ? project ? <ProjectDocuments key={project.id} project={project} documents={projectDocuments} loaded={loaded} view={documentView} onViewChange={changeDocumentView} onCreate={() => createDocument()} onCreatePresentation={() => createDocument('presentation')} onSettings={() => setProjectDialog({ project })} onAction={onDocumentAction} disabled={!connected || duplicating} /> : <div className="empty-state"><h1>{loaded ? "Project not found" : "Loading project…"}</h1><p>{loaded ? "It may have been removed. Your other projects are still available." : "Opening your local workspace."}</p><Button onClick={() => go("library")}>Back to documents</Button></div>
+        : current.view === "assets" ? <AssetsBrowser selection={current.id} generation={generation} documents={documents} themes={themes} connected={connected} />
+        : current.view === "templates" ? <TemplatesBrowser selection={current.id} generation={generation} format={current.templateFormat} />
+        : current.view === "themes" ? <ThemesBrowser connected={connected} themes={themes} selection={current.id} generation={generation} loaded={loaded} documents={documents} projects={manifest.projects} onRefresh={() => void refresh()} /> : <DocumentsBrowser key={current.view} format={current.view === 'presentations' ? 'presentation' : 'document'} projects={manifest.projects} documents={documents.filter(document => documentFormat(document) === (current.view === 'presentations' ? 'presentation' : 'document'))} loaded={loaded} view={documentView} onViewChange={changeDocumentView} onCreate={() => createDocument(current.view === 'presentations' ? 'presentation' : 'document')} onMove={setMoving} onAction={onDocumentAction} disabled={!connected || duplicating} />}
+    </main>
+    <CreateDocumentDialog format={creationFormat} open={help} onOpenChange={setHelp} project={project} />
+    <ProjectDialog themes={themes} open={Boolean(projectDialog)} project={projectDialog?.project ?? null} documentCount={documents.filter(document => document.projectId === projectDialog?.project?.id).length} connected={connected} onOpenChange={open => { if (!open) setProjectDialog(null); }} onSaved={saved => {
+      setManifest(previous => ({ ...previous, projects: previous.projects.some(project => project.id === saved.id) ? previous.projects.map(project => project.id === saved.id ? saved : project) : [...previous.projects, saved] }));
+      go(`project/${saved.id}`); void refresh();
+    }} onDeleted={() => { setManifest(previous => ({ ...previous, projects: previous.projects.filter(project => project.id !== projectDialog?.project?.id) })); go("library"); void refresh(); }} />
+    <ExportHistoryDialog document={exportDocument} connected={connected} onClose={() => setExportDocument(null)} />
+    <DocumentActionDialog selection={documentAction} connected={connected} onClose={() => setDocumentAction(null)} onRenamed={(id, name) => {
+      setDocuments(previous => previous.map(document => document.id === id ? { ...document, name } : document)); void refresh();
+    }} onDeleted={(document, restoreId) => {
+      setDocuments(previous => previous.filter(item => item.id !== document.id));
+      if (current.view === 'document' && current.id === document.id) go(document.projectId ? `project/${document.projectId}` : documentFormat(document) === 'presentation' ? 'presentations' : 'library');
+      void refresh();
+      notifications.success(`${documentName(document)} deleted`, { label: 'Undo', onClick: async () => {
+        await api(`/api/document-trash/${restoreId}/restore`, { method: 'POST' });
+        await refresh(); notifications.success(`${documentName(document)} restored`);
+      } });
+    }} />
+    <MoveDocumentDialog document={moving} projects={manifest.projects} connected={connected} onClose={() => setMoving(null)} onMoved={projectId => {
+      setDocuments(previous => previous.map(document => document.id === moving?.id ? { ...document, projectId } : document)); void refresh();
+    }} />
+  </div>;
+}
+
+createRoot(document.getElementById("root")!).render(<UiProvider><App /></UiProvider>);