@ryanyahya/opendoc 0.4.0

package/src/app/DocumentViewControl.tsx

@@ -0,0 +1,31 @@
+import { useEffect, useState } from 'react';
+import { ToggleGroup } from '@base-ui/react/toggle-group';
+import { ToggleButton } from './ui';
+import { Icon } from './ui/Icon';
+
+export type DocumentView = 'gallery' | 'list';
+const storageKey = 'opendoc-document-view';
+function readView(): DocumentView {
+  try { if (localStorage.getItem(storageKey) === 'list') return 'list'; } catch { /* Keep gallery available without browser storage. */ }
+  return 'gallery';
+}
+
+export function useDocumentView() {
+  const [view, setView] = useState<DocumentView>(readView);
+  useEffect(() => {
+    const sync = (event: StorageEvent) => { if (event.key === storageKey || event.key === null) setView(readView()); };
+    window.addEventListener('storage', sync);
+    return () => window.removeEventListener('storage', sync);
+  }, []);
+  return { view, changeView: (next: DocumentView) => {
+    setView(next);
+    try { localStorage.setItem(storageKey, next); } catch { /* Keep the selection for this session. */ }
+  } };
+}
+
+export function DocumentViewControl({ value, onChange }: { value: DocumentView; onChange: (value: DocumentView) => void }) {
+  return <ToggleGroup className="document-view-toggle" aria-label="Document view" value={[value]} onValueChange={values => { if (values[0]) onChange(values[0]); }}>
+    <ToggleButton static label="Gallery view" value="gallery"><Icon name="grid" size={16} /><span>Gallery</span></ToggleButton>
+    <ToggleButton static label="List view" value="list"><Icon name="list" size={16} /><span>List</span></ToggleButton>
+  </ToggleGroup>;
+}

package/src/app/DocumentsBrowser.tsx

@@ -0,0 +1,70 @@
+import { useState, type ReactNode } from 'react';
+import { Menu } from '@base-ui/react/menu';
+import type { Project } from '../shared/projects';
+import { documentName, documentFormat, type DocumentFormat, type DocumentSummary } from '../shared/types';
+import { DocumentCard } from './DocumentCard';
+import type { DocumentActionHandler } from './DocumentActions';
+import { DocumentViewControl, type DocumentView } from './DocumentViewControl';
+import { Button, IconButton, SelectControl } from './ui';
+import { SearchField } from './SearchField';
+import { Icon } from './ui/Icon';
+import './projects.css';
+
+type ViewProps = { view: DocumentView; onViewChange: (view: DocumentView) => void };
+
+function DocumentTools({ noun = 'document', query, onQueryChange, view, onViewChange, filter }: ViewProps & { noun?: string; query: string; onQueryChange: (query: string) => void; filter?: ReactNode }) {
+  return <div className="library-tools document-browser-tools">
+    <SearchField label={`Search ${noun}s`} value={query} onValueChange={onQueryChange} />
+    {filter}
+    <div className="document-view-tools"><DocumentViewControl value={view} onChange={onViewChange} /></div>
+  </div>;
+}
+
+export function DocumentsBrowser({ format = 'document', projects, documents, loaded, view, onViewChange, onCreate, onMove, onAction, disabled }: ViewProps & {
+  format?: DocumentFormat; projects: Project[]; documents: DocumentSummary[]; loaded: boolean; onCreate: () => void; onMove: (document: DocumentSummary) => void; onAction: DocumentActionHandler; disabled: boolean;
+}) {
+  const [query, setQuery] = useState('');
+  const plural = format === 'presentation' ? 'Presentations' : 'Documents';
+  const projectById = new Map(projects.map(project => [project.id, project]));
+  const visible = documents.filter(document => `${documentName(document)} ${document.artifact?.meta.description ?? ''} ${projectById.get(document.projectId ?? '')?.name ?? ''}`.toLowerCase().includes(query.toLowerCase()));
+  return <section className="library-content documents-content">
+    <div className="library-heading"><h1>{plural}</h1><Button className="primary" aria-label={`Create ${format}`} onClick={onCreate} disabled={!loaded || disabled}><Icon name="plus" size={17} /><span>Create {format}</span></Button></div>
+    <DocumentTools noun={format} query={query} onQueryChange={setQuery} view={view} onViewChange={onViewChange} />
+    <div className={view === 'list' ? 'documents-list' : 'document-grid'} role="list">{visible.map(document => {
+      const project = projectById.get(document.projectId ?? '');
+      return <article className="project-document" key={document.id} role="listitem">
+        <DocumentCard document={document} view={view} onAction={onAction} disabled={disabled} onOpen={() => { location.hash = `document/${document.id}`; }} />
+        {project ? <a className="document-project-link" href={`#project/${project.id}`}><Icon name="folder" size={15} /><span>{project.name}</span></a>
+          : <Button className="text-button document-move" onClick={() => onMove(document)} disabled={!projects.length}>Choose a project</Button>}
+      </article>;
+    })}</div>
+    {!visible.length && <div className="empty-state"><h2>{!loaded ? `Loading ${plural.toLowerCase()}…` : query ? `No matching ${plural.toLowerCase()}` : `Your ${plural.toLowerCase()} start here`}</h2><p>{!loaded ? 'Opening your local workspace.' : query ? 'Try a different title or project name.' : projects.length ? format === 'presentation' ? 'Create a presentation with your agent and review every slide here.' : 'Create a document in a project, or choose a layout from Templates.' : 'Create your first project using the + beside Projects in the sidebar.'}</p></div>}
+  </section>;
+}
+
+export function ProjectDocuments({ project, documents, loaded, view, onViewChange, onCreate, onCreatePresentation, onSettings, onAction, disabled }: ViewProps & {
+  project: Project; documents: DocumentSummary[]; loaded: boolean; onCreate: () => void; onCreatePresentation: () => void; onSettings: () => void; onAction: DocumentActionHandler; disabled: boolean;
+}) {
+  const [query, setQuery] = useState('');
+  const [format, setFormat] = useState<'all' | DocumentFormat>('all');
+  const hasFilters = Boolean(query) || format !== 'all';
+  const visible = documents.filter(document => (format === 'all' || documentFormat(document) === format)
+    && `${documentName(document)} ${document.artifact?.meta.description ?? ''}`.toLowerCase().includes(query.toLowerCase()));
+  return <section className="library-content project-documents">
+    <div className="library-heading"><h1>{project.name}</h1><div className="project-actions">
+      <IconButton label="Project settings" onClick={onSettings}><Icon name="gear" size={18} /></IconButton>
+      <Menu.Root><Menu.Trigger render={<Button className="primary project-create-trigger" disabled={!loaded || disabled} />}>
+        <Icon name="plus" size={16} /><span>Create</span><Icon name="down" size={14} />
+      </Menu.Trigger><Menu.Portal><Menu.Positioner className="ui-positioner" sideOffset={6} align="end"><Menu.Popup className="ui-menu-popup">
+        <Menu.Item className="ui-menu-item" onClick={onCreate}><Icon name="document" size={16} />Document</Menu.Item>
+        <Menu.Item className="ui-menu-item" onClick={onCreatePresentation}><Icon name="monitor" size={16} />Presentation</Menu.Item>
+      </Menu.Popup></Menu.Positioner></Menu.Portal></Menu.Root>
+    </div></div>
+    <DocumentTools noun="item" query={query} onQueryChange={setQuery} view={view} onViewChange={onViewChange}
+      filter={<SelectControl label="Filter by format" value={format} onValueChange={value => { if (value === 'all' || value === 'document' || value === 'presentation') setFormat(value); }} items={[
+        { label: 'All formats', value: 'all' }, { label: 'Documents', value: 'document' }, { label: 'Presentations', value: 'presentation' },
+      ]} />} />
+    <div className={view === 'list' ? 'documents-list' : 'document-grid'} role="list">{visible.map(document => <article className="project-document" key={document.id} role="listitem"><DocumentCard document={document} view={view} onAction={onAction} disabled={disabled} onOpen={() => { location.hash = `document/${document.id}`; }} /></article>)}</div>
+    {!visible.length && <div className="empty-state"><h2>{!loaded ? 'Loading project…' : hasFilters ? 'No matching items' : 'Your project is ready'}</h2><p>{!loaded ? 'Opening your local workspace.' : hasFilters ? 'Try another search or choose a different format.' : 'Create a document or presentation with your agent.'}</p>{loaded && (hasFilters ? <Button onClick={() => { setQuery(''); setFormat('all'); }}>Clear filters</Button> : <a href="#templates" className="project-templates-link">Browse templates<Icon name="arrow" size={16} /></a>)}</div>}
+  </section>;
+}

package/src/app/ExportHistoryDialog.tsx

@@ -0,0 +1,86 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { documentName, type DocumentSummary } from '../shared/types';
+import { exportInfo, type ExportHistoryEntry } from '../shared/export';
+import { api } from './api';
+import { Button, Dialog, IconButton, useNotifications } from './ui';
+import { Icon } from './ui/Icon';
+import './export-history.css';
+
+const date = new Intl.DateTimeFormat(undefined, { dateStyle: 'medium', timeStyle: 'short' });
+function fileSize(bytes: number) { return `${new Intl.NumberFormat(undefined, { maximumFractionDigits: 1 }).format(bytes / (bytes >= 1048576 ? 1048576 : 1024))} ${bytes >= 1048576 ? 'MB' : 'KB'}`; }
+
+export function ExportHistoryDialog({ document, connected, onClose }: { document: DocumentSummary | null; connected: boolean; onClose: () => void }) {
+  const [entries, setEntries] = useState<ExportHistoryEntry[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState('');
+  const [canCopy, setCanCopy] = useState(false);
+  const [busy, setBusy] = useState<string | null>(null);
+  const working = useRef(false);
+  const request = useRef(0);
+  const selected = useRef(document?.id);
+  selected.current = document?.id;
+  const notifications = useNotifications();
+  const refresh = useCallback(async () => {
+    if (!document || !connected) return;
+    const sequence = ++request.current;
+    setLoading(true); setError('');
+    try {
+      const rows = await api<ExportHistoryEntry[]>(`/api/documents/${document.id}/exports`, { signal: AbortSignal.timeout(12_000) });
+      if (sequence === request.current) setEntries(rows);
+    } catch (failure) { if (sequence === request.current) setError((failure as Error).message); }
+    finally { if (sequence === request.current) setLoading(false); }
+  }, [document?.id, connected]);
+  useEffect(() => {
+    setEntries([]); setError(''); setCanCopy(false);
+    void refresh();
+    if (document && connected) {
+      api<{ copyFile: boolean }>('/api/exports/capabilities', { signal: AbortSignal.timeout(5_000) }).then(value => { if (selected.current === document.id) setCanCopy(value.copyFile); }).catch(() => {});
+    }
+    const focus = () => { if (!working.current) void refresh(); };
+    window.addEventListener('focus', focus);
+    return () => { request.current++; window.removeEventListener('focus', focus); };
+  }, [refresh]);
+  async function act(entry: ExportHistoryEntry, action: 'copy' | 'reveal' | 'delete') {
+    if (working.current || !connected) return;
+    working.current = true; setBusy(entry.id); setError('');
+    try {
+      await api(`/api/exports/${entry.id}${action === 'delete' ? '' : `/${action}`}`, { method: action === 'delete' ? 'DELETE' : 'POST', signal: AbortSignal.timeout(12_000) });
+      if (action === 'delete') {
+        request.current++; setLoading(false);
+        setEntries(rows => rows.filter(row => row.id !== entry.id));
+        notifications.success(`${entry.filename} removed`, { label: 'Undo', onClick: async () => {
+          await api(`/api/exports/${entry.id}/restore`, { method: 'POST', signal: AbortSignal.timeout(12_000) });
+          if (selected.current === entry.documentId) await refresh();
+          notifications.success('Export restored');
+        } });
+      } else if (action === 'copy') notifications.success(`${exportInfo(entry.format).label} file copied to clipboard`);
+    } catch (failure) { setError((failure as Error).message); }
+    finally { working.current = false; setBusy(null); }
+  }
+  return <Dialog.Root open={!!document} onOpenChange={open => { if (!open && !working.current) onClose(); }}>
+    <Dialog.Portal><Dialog.Backdrop className="ui-dialog-backdrop" /><Dialog.Popup className="help-dialog export-history-dialog">
+      <Dialog.Close render={<Button className="icon-button modal-close" aria-label="Close export history" disabled={!!busy} />}><Icon name="close" /></Dialog.Close>
+      <div className="export-history-heading"><span className="export-history-symbol"><Icon name="history" size={22} /></span><div><Dialog.Title>Previous exports</Dialog.Title><Dialog.Description>{document ? documentName(document) : ''}</Dialog.Description></div></div>
+      <div className="export-history-summary"><span>{loading ? 'Checking saved files…' : `${entries.length} ${entries.length === 1 ? 'export' : 'exports'} · Newest first`}</span><Button className="text-button" disabled={loading || !!busy || !connected} onClick={() => void refresh()}>Refresh</Button></div>
+      {!connected && <p className="field-error" role="status">Reconnect to view and manage exports.</p>}
+      {error && <p className="field-error" role="alert">{error}</p>}
+      <div className="export-history-content" aria-busy={loading || !!busy}>
+        {!entries.length && !loading && !error && connected && <div className="export-history-empty"><Icon name="document" size={34} /><strong>No exports yet</strong><p>Export this document and it will appear here.</p></div>}
+        {!!entries.length && <ul className="export-history-list">{entries.map(entry => <li key={entry.id} className={`export-history-row${entry.available ? '' : ' unavailable'}`}>
+          <span className="export-history-paper" aria-hidden="true"><Icon name="document" size={24} /><span>{(entry.format ?? 'pdf').toUpperCase()}</span></span>
+          <div className="export-history-details">
+            {entry.available ? <a href={`/api/exports/${entry.id}/open`} target="_blank" rel="noreferrer" title={`Open ${entry.filename}`}>{entry.filename}</a> : <strong>{entry.filename}</strong>}
+            <span><time dateTime={entry.createdAt}>{date.format(new Date(entry.createdAt))}</time><span aria-hidden="true"> · </span>{fileSize(entry.bytes)}</span>
+            {!entry.available && <span className="export-history-unavailable">File moved, removed, or changed</span>}
+          </div>
+          <div className="export-history-actions" aria-label={`Actions for ${entry.filename}`}>
+            {canCopy && <IconButton label={`Copy ${entry.filename}`} disabled={!!busy || !connected || !entry.available} onClick={() => void act(entry, 'copy')}><Icon name="copy" size={17} /></IconButton>}
+            <IconButton label={`${canCopy ? 'Show in Finder' : 'Show in folder'}: ${entry.filename}`} disabled={!!busy || !connected || !entry.available} onClick={() => void act(entry, 'reveal')}><Icon name="folder" size={17} /></IconButton>
+            <IconButton label={`Delete export: ${entry.filename}`} className="export-history-delete" disabled={!!busy || !connected} onClick={() => void act(entry, 'delete')}><Icon name="trash" size={17} /></IconButton>
+          </div>
+        </li>)}</ul>}
+      </div>
+      <p className="export-history-footnote">Saved files are independent of later document edits. Deleting an export offers Undo.</p>
+    </Dialog.Popup></Dialog.Portal>
+  </Dialog.Root>;
+}

package/src/app/ExportMenu.tsx

@@ -0,0 +1,127 @@
+import { useEffect, useRef, useState } from 'react';
+import { Popover } from '@base-ui/react/popover';
+import { documentName, documentFormat, type DocumentState } from '../shared/types';
+import { suggestedExportName, exportInfo, type ExportFormat, type SavedExport } from '../shared/export';
+import { api, ApiError } from './api';
+import { Button, Input, SelectControl } from './ui';
+import { Icon } from './ui/Icon';
+import './export.css';
+
+type Attempt = { id: string; hash: string; filename: string; format?: ExportFormat };
+function remembered(id: string): Attempt | null {
+  try {
+    const value = JSON.parse(sessionStorage.getItem(`opendoc:export:${id}`) ?? 'null');
+    return value && typeof value.id === 'string' && typeof value.hash === 'string' && typeof value.filename === 'string' && (value.format === undefined || value.format === 'pdf' || value.format === 'pptx') ? value : null;
+  } catch { return null; }
+}
+
+export function ExportMenu({ state, connected, ready, unsaved, saving, correctionError, canSave, onSave, onShowExports }: {
+  state: DocumentState; connected: boolean; ready: boolean; unsaved: number; saving: boolean; correctionError: string;
+  canSave: boolean; onSave: () => Promise<boolean | undefined>; onShowExports: () => void;
+}) {
+  const [open, setOpen] = useState(false);
+  const [format, setFormat] = useState<ExportFormat>(() => remembered(state.id)?.format ?? 'pdf');
+  const [filename, setFilename] = useState(() => suggestedExportName(documentName(state), format));
+  const [attempt, setAttempt] = useState<Attempt | null>(() => remembered(state.id));
+  const [result, setResult] = useState<SavedExport | null>(null);
+  const [busy, setBusy] = useState(false);
+  const working = useRef(false);
+  const [error, setError] = useState('');
+  const [notice, setNotice] = useState('');
+  const [canCopy, setCanCopy] = useState(false);
+  const [copying, setCopying] = useState(false);
+  const input = useRef<HTMLInputElement>(null);
+  const showFile = useRef<HTMLButtonElement>(null);
+  const showHistory = useRef(false);
+  const activeFormat = result?.format ?? attempt?.format ?? format;
+  const formatLabel = exportInfo(activeFormat).label;
+  useEffect(() => { if (open && result) showFile.current?.focus(); }, [open, result]);
+  useEffect(() => {
+    if (!open || !connected) return;
+    let current = true;
+    api<{ copyFile: boolean }>('/api/exports/capabilities', { signal: AbortSignal.timeout(5_000) })
+      .then(value => { if (current) setCanCopy(value.copyFile); })
+      .catch(() => { if (current) setCanCopy(false); });
+    return () => { current = false; };
+  }, [open, connected]);
+  function remember(value: Attempt | null) {
+    setAttempt(value);
+    try { if (value) sessionStorage.setItem(`opendoc:export:${state.id}`, JSON.stringify(value)); else sessionStorage.removeItem(`opendoc:export:${state.id}`); } catch { /* The open reader retains its request. */ }
+  }
+  async function perform() {
+    if (working.current || !connected || (!attempt && (!ready || unsaved || saving || correctionError))) return;
+    working.current = true; setBusy(true); setError(''); setNotice('');
+    const request = attempt ?? { id: crypto.randomUUID(), hash: state.artifact!.hash, filename, format };
+    remember(request);
+    try {
+      // Retrying the same receipt never creates a second output, including after a restart.
+      const saved = await api<SavedExport>(`/api/documents/${state.id}/exports`, { method: 'POST', body: JSON.stringify(request), signal: AbortSignal.timeout(20_000) });
+      setResult(saved); remember(null);
+    } catch (failure) {
+      if (failure instanceof ApiError && failure.status >= 400 && failure.status < 500) { remember(null); setError(failure.message); }
+      else setError('OpenDoc could not confirm whether the file was saved. Check the export to recover it without creating another copy.');
+    } finally { working.current = false; setBusy(false); }
+  }
+  async function reveal() {
+    if (!result || working.current) return;
+    working.current = true; setBusy(true); setError('');
+    try { await api(`/api/exports/${result.id}/reveal`, { method: 'POST', signal: AbortSignal.timeout(12_000) }); }
+    catch (failure) { setError((failure as Error).message); }
+    finally { working.current = false; setBusy(false); }
+  }
+  async function saveChanges() {
+    if (await onSave()) setOpen(false);
+  }
+  async function copy() {
+    if (!result || working.current || !connected || !canCopy) return;
+    working.current = true; setBusy(true); setCopying(true); setError(''); setNotice('');
+    try {
+      await api(`/api/exports/${result.id}/copy`, { method: 'POST', signal: AbortSignal.timeout(12_000) });
+      setNotice(`${formatLabel} file copied. Paste it into Finder or an app that accepts file attachments.`);
+    } catch (failure) { setError(failure instanceof ApiError ? failure.message : 'OpenDoc could not confirm the copy. Check your connection and try again.'); }
+    finally { working.current = false; setBusy(false); setCopying(false); }
+  }
+  return <Popover.Root open={open} onOpenChange={next => {
+    setOpen(next);
+    if (!next && result && !working.current) { setResult(null); setError(''); setNotice(''); setFilename(suggestedExportName(documentName(state), format)); }
+  }} onOpenChangeComplete={next => {
+    // Let the dropdown restore focus to Export before the history dialog opens.
+    if (!next && showHistory.current) { showHistory.current = false; onShowExports(); }
+  }}>
+    <Popover.Trigger render={<Button className="primary export-button" aria-label={`Export ${documentFormat(state)}`} />}><Icon name="download" size={16} /><span>Export</span><Icon name="down" size={12} /></Popover.Trigger>
+    <Popover.Portal><Popover.Positioner className="ui-positioner" align="end" sideOffset={8} collisionPadding={8}>
+    <Popover.Popup className="ui-popover-popup export-dropdown" initialFocus={interaction => interaction === 'touch' ? true : result || attempt ? true : input.current}>
+      <form onSubmit={event => { event.preventDefault(); if (!result) void perform(); }}>
+      <div className="export-dropdown-body">
+      <div className="export-dropdown-heading">
+        <Popover.Title>{result ? `${formatLabel} saved` : `Export ${formatLabel}`}</Popover.Title>
+        <Popover.Close render={<Button className="icon-button" aria-label="Close export menu" />}><Icon name="close" size={16} /></Popover.Close>
+      </div>
+      <Popover.Description>{result ? 'Saved in your workspace’s output folder.' : activeFormat === 'pptx' ? 'Editable text and shapes · Embedded fonts' : `Original quality · All ${documentFormat(state) === 'presentation' ? 'slides' : 'pages'}`}</Popover.Description>
+      {result ? <>
+        <div className="export-file" role="status"><Icon name="document" size={24} /><div><strong>{result.filename}</strong><span>{new Intl.NumberFormat(undefined, { maximumFractionDigits: 1 }).format(result.bytes / 1024)} KB · {activeFormat.toUpperCase()}</span></div><Icon name="check" size={18} /></div>
+      </> : <>
+        {documentFormat(state) === 'presentation' && !attempt && <div className="create-field export-format"><span>Format</span><SelectControl label="Export format" value={format} disabled={busy} items={[{ value: 'pdf', label: 'PDF' }, { value: 'pptx', label: 'PowerPoint (.pptx)' }]} onValueChange={value => { const next = value as ExportFormat; setFormat(next); setFilename(name => name.trim() ? name.replace(/\.(pdf|pptx)$/i, '') + exportInfo(next).extension : suggestedExportName(documentName(state), next)); setError(''); }} /></div>}
+        <label className="create-field export-filename" htmlFor="export-filename"><span>Filename</span><Input ref={input} id="export-filename" value={attempt?.filename ?? filename} onChange={event => { setFilename(event.target.value); setError(''); }} disabled={busy || !!attempt} maxLength={120} autoComplete="off" /></label>
+        {attempt && !busy && <p className="export-status" role="status">An export is awaiting confirmation. Check it to recover the saved file or finish the same request.</p>}
+        {!attempt && (unsaved > 0 || correctionError || saving) && <div className="export-status" role="status"><strong>{saving ? 'Saving your changes…' : 'Save your corrections first'}</strong><p>{correctionError || 'Save your changes and review the updated PDF before exporting.'}</p>{unsaved > 0 && <Button disabled={!canSave || saving} onClick={() => void saveChanges()}>Save changes first</Button>}</div>}
+        {!attempt && !unsaved && !saving && !correctionError && !ready && <p className="export-status" role="status">{!connected ? 'Reconnect to the local workspace before exporting.' : state.status === 'error' ? 'Fix the document’s render error before exporting.' : 'Waiting for the current PDF preview…'}</p>}
+      </>}
+      {error && <p className="field-error" role="alert">{error}</p>}
+      {notice && <p className="export-notice" role="status">{notice}</p>}
+      {busy && <p className="export-notice" role="status">{copying ? 'Copying the file…' : result ? 'Opening the export folder…' : `Saving ${formatLabel}… You can close this menu and return to check it.`}</p>}
+      {!result && <Button type="submit" className="primary export-save" disabled={busy || !connected || (!attempt && (!ready || !!unsaved || !!correctionError || saving || !filename.trim()))}>{busy ? 'Saving…' : attempt ? 'Check export' : `Save ${formatLabel}`}</Button>}
+      </div>
+      </form>
+      {result && <div className="ui-menu-group">
+        <Button ref={showFile} className="ui-menu-item" onClick={() => void reveal()} disabled={busy || !connected}><Icon name="folder" size={16} />Show in folder</Button>
+        <a className="ui-menu-item" href={`/api/exports/${result.id}/download`} download={result.filename} onClick={() => setNotice('Download requested. Your browser handles where the copy is saved.')}><Icon name="download" size={16} />Download a copy</a>
+        {canCopy && <Button className="ui-menu-item" onClick={() => void copy()} disabled={busy || !connected} focusableWhenDisabled={copying}><Icon name="copy" size={16} />Copy to clipboard</Button>}
+        {activeFormat === 'pdf' && <a className="ui-menu-item" href={`/api/exports/${result.id}/open`} target="_blank" rel="noreferrer"><Icon name="arrow" size={16} />Open PDF to print</a>}
+        <Button className="ui-menu-item" disabled={busy} onClick={() => { setResult(null); setError(''); setNotice(''); setFilename(suggestedExportName(documentName(state), format)); }}><Icon name="plus" size={16} />Export another copy</Button>
+      </div>}
+      <div className="ui-menu-separator" />
+      <Button className="ui-menu-item" onClick={() => { showHistory.current = true; setOpen(false); }}><Icon name="history" size={16} />Previous exports</Button>
+    </Popover.Popup></Popover.Positioner></Popover.Portal>
+  </Popover.Root>;
+}

package/src/app/GuideDialog.tsx

@@ -0,0 +1,80 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { api } from './api';
+import { Button, Dialog } from './ui';
+import { Icon } from './ui/Icon';
+import type { GuideLocation } from './guideLinks';
+import './guides.css';
+
+let markdownModule: Promise<typeof import('./Markdown')> | undefined;
+function loadMarkdown() {
+  markdownModule ??= import('./Markdown').catch(error => { markdownModule = undefined; throw error; });
+  return markdownModule;
+}
+type GuideVisit = GuideLocation & { scrollTop?: number };
+
+export function GuideDialog({ kind, id, name, generation }: { kind: 'template' | 'theme'; id: string; name: string; generation: number | string }) {
+  const template = kind === 'template';
+  const initialFile = template ? `templates/${id}/AGENTS.md` : `themes/${id}/design.md`;
+  const title = template ? 'AGENTS.md' : 'Design guide';
+  const body = useRef<HTMLDivElement>(null);
+  const [open, setOpen] = useState(false);
+  const [visits, setVisits] = useState<GuideVisit[]>([{ file: initialFile }]);
+  const visit = visits.at(-1)!;
+  const [content, setContent] = useState<{ key: string; markdown: string; file: string; Renderer: typeof import('./Markdown')['Markdown'] }>();
+  const [error, setError] = useState('');
+  const [attempt, setAttempt] = useState(0);
+  const key = JSON.stringify([visit.file, generation, attempt]);
+  const guide = content?.key === key ? content : undefined;
+  const Markdown = guide?.Renderer;
+  const initial = visit.file === initialFile;
+
+  useEffect(() => {
+    if (!open) return;
+    const controller = new AbortController();
+    setError(''); setContent(undefined);
+    void api<{ markdown: string; file: string }>(`/api/guides?path=${encodeURIComponent(visit.file)}`, { signal: controller.signal })
+      .then(async result => {
+        if (controller.signal.aborted) return;
+        const { Markdown } = await loadMarkdown();
+        if (!controller.signal.aborted) setContent({ key, ...result, Renderer: Markdown });
+      })
+      .catch(error => { if (!controller.signal.aborted) { setError(error.message); body.current?.focus({ preventScroll: true }); } });
+    return () => controller.abort();
+  }, [open, visit.file, key]);
+
+  const restorePosition = useCallback(() => {
+    const container = body.current;
+    if (!container) return;
+    const heading = visit.fragment ? container.querySelector<HTMLElement>(`[data-guide-heading="${CSS.escape(visit.fragment)}"]`) : null;
+    if (visit.scrollTop !== undefined) container.scrollTop = visit.scrollTop;
+    else if (heading) heading.scrollIntoView({ block: 'start' });
+    else container.scrollTop = 0;
+    container.focus({ preventScroll: true });
+  }, [visit.file, visit.fragment, visit.scrollTop, visits.length]);
+
+  function navigate(next: GuideLocation) {
+    setError('');
+    const scrollTop = body.current?.scrollTop ?? 0;
+    setVisits(previous => [...previous.slice(0, -1), { ...previous.at(-1)!, scrollTop }, next]);
+  }
+
+  return <Dialog.Root open={open} onOpenChange={next => { if (next) { setVisits([{ file: initialFile }]); setError(''); } setOpen(next); }}>
+    <Dialog.Trigger render={<Button className={`text-button${template ? ' template-guide-trigger' : ''}`} />}>{template ? 'View AGENTS.md' : <>Design guide<Icon name="arrow" size={16} /></>}</Dialog.Trigger>
+    <Dialog.Portal><Dialog.Backdrop className="ui-dialog-backdrop" />
+      <Dialog.Popup className="help-dialog template-guide-dialog">
+        <header className="template-guide-heading">
+          <Dialog.Title>{initial ? title : visit.file.split('/').at(-1)}</Dialog.Title>
+          <Dialog.Description>{initial ? name : visit.file}</Dialog.Description>
+          <Dialog.Close render={<Button className="icon-button modal-close" aria-label={template ? 'Close template guide' : 'Close design guide'} />}><Icon name="close" /></Dialog.Close>
+          {visits.length > 1 && <Button className="text-button guide-back" onClick={() => { setError(''); setVisits(previous => previous.length > 1 ? previous.slice(0, -1) : previous); }}><Icon name="left" size={15} />Back to {visits.at(-2)!.file === initialFile ? title : visits.at(-2)!.file.split('/').at(-1)}</Button>}
+        </header>
+        <div ref={body} className="template-guide-body" tabIndex={0} role="region" aria-label={template ? 'Template guide content' : `${name} design guide`} aria-busy={!guide && !error}>
+          {error ? <div role="alert"><p>{initial ? template ? 'Could not load this template’s AGENTS.md.' : 'Could not load this theme’s design guide.' : 'Could not load this guide.'}</p><p>{error}</p><Button onClick={() => { body.current?.focus(); setAttempt(value => value + 1); }}>Try again</Button></div>
+            : !guide ? <p role="status">Loading guide…</p>
+              : guide.markdown.trim() && Markdown ? <Markdown file={guide.file} onNavigate={navigate} onReady={restorePosition}>{guide.markdown}</Markdown>
+                : <p>{initial ? template ? 'This template’s AGENTS.md is empty.' : 'This theme’s design guide is empty.' : 'This guide is empty.'}</p>}
+        </div>
+      </Dialog.Popup>
+    </Dialog.Portal>
+  </Dialog.Root>;
+}

package/src/app/InspectionLayer.tsx

@@ -0,0 +1,77 @@
+import { useLayoutEffect, useRef, useState, type PointerEvent, type ReactNode } from 'react';
+
+type HoverTarget = { left: number; top: number; width: number; height: number; label: string };
+
+// Keep one full-size rectangle alive. Enlarging one-pixel strips magnifies
+// raster rounding at fractional display scales and separates the frame edges.
+export function InspectionLayer({ children }: { children: ReactNode }) {
+  const [target, setTarget] = useState<HoverTarget | null>(null);
+  const [visible, setVisible] = useState(false);
+  const [morph, setMorph] = useState(false);
+  const hovered = useRef<HTMLElement | null>(null);
+  const hiddenAt = useRef(-Infinity);
+  const box = useRef<HTMLDivElement>(null);
+
+  useLayoutEffect(() => {
+    const element = box.current;
+    const reduced = window.matchMedia('(prefers-reduced-motion: reduce)');
+    const cancel = () => element?.getAnimations().forEach(animation => animation.cancel());
+    const onChange = () => { if (reduced.matches) cancel(); };
+    reduced.addEventListener('change', onChange);
+    return () => { reduced.removeEventListener('change', onChange); cancel(); };
+  }, []);
+
+  useLayoutEffect(() => {
+    const element = box.current;
+    if (!element || !target) return;
+    // Read the in-flight visual bounds before retargeting, then animate back
+    // from those bounds to the new geometry using a single transform.
+    const previous = element.getBoundingClientRect();
+    element.getAnimations().forEach(animation => animation.cancel());
+    Object.assign(element.style, {
+      left: `${target.left}px`, top: `${target.top}px`,
+      width: `${target.width}px`, height: `${target.height}px`,
+    });
+    const next = element.getBoundingClientRect();
+    if (!morph || !previous.width || !previous.height || !next.width || !next.height ||
+      !window.matchMedia('(hover: hover) and (pointer: fine) and (prefers-reduced-motion: no-preference)').matches) return;
+    element.animate([
+      { transform: `translate(${(previous.left - next.left) * target.width / next.width}px, ${(previous.top - next.top) * target.height / next.height}px) scale(${previous.width / next.width}, ${previous.height / next.height})` },
+      { transform: 'none' },
+    ], { duration: 180, easing: 'cubic-bezier(0.23, 1, 0.32, 1)' });
+  }, [target, morph]);
+
+  function hide() {
+    if (!hovered.current) return;
+    hovered.current = null;
+    hiddenAt.current = performance.now();
+    setVisible(false);
+  }
+
+  function hover(event: PointerEvent<HTMLDivElement>) {
+    if (event.pointerType !== 'mouse' || !window.matchMedia('(hover: hover) and (pointer: fine)').matches) return;
+    const element = event.target instanceof Element ? event.target.closest<HTMLElement>('.component-target') : null;
+    if (!element || element.classList.contains('selected')) { hide(); return; }
+    if (hovered.current === element) return;
+    setMorph(!!hovered.current || performance.now() - hiddenAt.current < 150);
+    hovered.current = element;
+    setTarget({
+      left: parseFloat(element.style.left), top: parseFloat(element.style.top),
+      width: parseFloat(element.style.width), height: parseFloat(element.style.height),
+      label: element.querySelector('.block-label')?.textContent ?? 'Component',
+    });
+    setVisible(true);
+  }
+
+  const { left: x, top: y } = target ?? { left: 0, top: 0 };
+  return <div className="inspection-layer" onPointerOver={hover} onPointerLeave={hide}
+    onPointerOut={event => {
+      if (!(event.relatedTarget instanceof Element) || !event.relatedTarget.closest('.component-target')) hide();
+    }} onPointerDownCapture={hide} onKeyDownCapture={hide}>
+    {children}
+    <div className="inspection-hover-frame" aria-hidden="true" data-visible={visible} data-morph={morph}>
+      <div ref={box} className="inspection-hover-box" />
+      <span className="block-label" style={{ transform: `translate(${x}px, ${y}px)` }}>{target?.label}</span>
+    </div>
+  </div>;
+}

package/src/app/LogoUploadDialog.tsx

@@ -0,0 +1,92 @@
+import { useEffect, useRef, useState, type FormEvent } from 'react';
+import type { AssetInspection } from '../shared/assets';
+import { api } from './api';
+import { Button, Dialog, Input } from './ui';
+import { Icon } from './ui/Icon';
+
+function UploadPreview({ file }: { file: File }) {
+  const [url, setUrl] = useState('');
+  useEffect(() => { const next = URL.createObjectURL(file); setUrl(next); return () => URL.revokeObjectURL(next); }, [file]);
+  return <span className="logo-upload-preview asset-background-transparent">{url && <img src={url} alt="" />}</span>;
+}
+const accept = '.svg,.png,image/svg+xml,image/png';
+
+/** Creation asks only for the folder name and its default artwork. */
+export function CreateLogoDialog({ connected, onClose, onSaved }: { connected: boolean; onClose: () => void; onSaved: (value: AssetInspection) => void }) {
+  const [name, setName] = useState('');
+  const [step, setStep] = useState<'name' | 'default'>('name');
+  const [file, setFile] = useState<File>();
+  const [error, setError] = useState('');
+  const [busy, setBusy] = useState(false);
+  const working = useRef(false);
+  const nameInput = useRef<HTMLInputElement>(null);
+  const fileInput = useRef<HTMLInputElement>(null);
+  useEffect(() => { if (step === 'default') { if (file && fileInput.current) { const selection = new DataTransfer(); selection.items.add(file); fileInput.current.files = selection.files; } fileInput.current?.focus(); } else nameInput.current?.focus(); }, [step, file]);
+  async function submit(event: FormEvent) {
+    event.preventDefault();
+    if (working.current || !connected || !name.trim()) return;
+    if (step === 'name') { setStep('default'); return; }
+    if (!file) return;
+    working.current = true; setBusy(true); setError('');
+    try {
+      const form = new FormData(); form.set('metadata', JSON.stringify({ name: name.trim() })); form.set('file', file);
+      const result = await api<AssetInspection>('/api/assets/logo', { method: 'POST', body: form });
+      onSaved(result); onClose();
+    } catch (failure) { setError((failure as Error).message); }
+    finally { working.current = false; setBusy(false); }
+  }
+  return <Dialog.Root open onOpenChange={open => { if (!open && !working.current) onClose(); }}><Dialog.Portal><Dialog.Backdrop className="ui-dialog-backdrop" /><Dialog.Popup className="help-dialog create-dialog asset-dialog logo-create-dialog" initialFocus={nameInput}>
+    <Dialog.Close render={<Button className="icon-button modal-close" aria-label="Close add logo" disabled={busy} />}><Icon name="close" /></Dialog.Close>
+    <Dialog.Title>{step === 'name' ? 'Add logo' : 'Upload default logo'}</Dialog.Title>
+    <Dialog.Description>{step === 'name' ? 'Give this logo a name. Its variations will live together inside.' : `${name.trim()} · You can add more variations after this.`}</Dialog.Description>
+    <form onSubmit={event => void submit(event)} aria-busy={busy}>
+      {step === 'name' ? <label className="create-field"><span>Name</span><Input ref={nameInput} value={name} onChange={event => setName(event.target.value)} maxLength={120} required autoComplete="off" placeholder="For example, Northstar" /></label> : <label className="create-field asset-upload logo-default-upload"><span>Default logo</span>{file && <UploadPreview file={file} />}<input ref={fileInput} type="file" accept={accept} required={!file} disabled={busy} onChange={event => { setFile(event.target.files?.[0]); setError(''); }} /><span className="field-hint">SVG or PNG</span></label>}
+      {error && <p className="field-error" role="alert">{error}</p>}
+      <div className="dialog-actions"><Button disabled={busy} onClick={() => { if (step === 'name') onClose(); else { setStep('name'); setError(''); } }}>{step === 'name' ? 'Cancel' : 'Back'}</Button><Button type="submit" className="primary" disabled={busy || !connected || !name.trim() || (step === 'default' && !file)}>{busy ? 'Uploading…' : step === 'name' ? 'Next' : 'Create logo'}</Button></div>
+    </form>
+  </Dialog.Popup></Dialog.Portal></Dialog.Root>;
+}
+
+type PendingVariation = { id: number; file: File; name: string };
+export function AddLogoVariationsDialog({ inspection, connected, onClose, onSaved }: { inspection: AssetInspection; connected: boolean; onClose: () => void; onSaved: (value: AssetInspection) => void }) {
+  const [pending, setPending] = useState<PendingVariation[]>([]);
+  const [error, setError] = useState('');
+  const [busy, setBusy] = useState(false);
+  const [progress, setProgress] = useState('');
+  const current = useRef(inspection);
+  const counter = useRef(0);
+  const working = useRef(false);
+  const input = useRef<HTMLInputElement>(null);
+  const count = current.current.asset.kind === 'logo' ? current.current.asset.variations.length : 0;
+  async function submit(event: FormEvent) {
+    event.preventDefault(); if (!connected || working.current || !pending.length || pending.some(item => !item.name.trim())) return;
+    working.current = true; setBusy(true); setError('');
+    let saved = 0;
+    try {
+      for (const item of pending) {
+        setProgress(`Uploading ${saved + 1} of ${pending.length}…`);
+        const form = new FormData(); form.set('metadata', JSON.stringify({ expectedRevision: current.current.head.revision, name: item.name.trim() })); form.set('file', item.file);
+        current.current = await api<AssetInspection>(`/api/assets/logo/${encodeURIComponent(inspection.asset.id)}/variations`, { method: 'POST', body: form });
+        saved++; setPending(list => list.filter(value => value.id !== item.id));
+      }
+      onSaved(current.current); onClose();
+    } catch (failure) {
+      if (saved) onSaved(current.current);
+      setError(`${saved ? `${saved} ${saved === 1 ? 'variation was' : 'variations were'} added. The remaining files are still here. ` : ''}${(failure as Error).message}`);
+    } finally { working.current = false; setBusy(false); setProgress(''); }
+  }
+  return <Dialog.Root open onOpenChange={open => { if (!open && !working.current) onClose(); }}><Dialog.Portal><Dialog.Backdrop className="ui-dialog-backdrop" /><Dialog.Popup className="help-dialog create-dialog asset-dialog" initialFocus={input}>
+    <Dialog.Close render={<Button className="icon-button modal-close" aria-label="Close add variations" disabled={busy} />}><Icon name="close" /></Dialog.Close>
+    <Dialog.Title>Add variations</Dialog.Title><Dialog.Description>{inspection.asset.name} · Select one or more SVG or PNG files.</Dialog.Description>
+    <form onSubmit={event => void submit(event)} aria-busy={busy}>
+      <label className="create-field asset-upload"><span>Upload variations</span><input ref={input} type="file" accept={accept} multiple disabled={busy} onChange={event => {
+        const files = Array.from(event.target.files ?? []); setError('');
+        if (count + pending.length + files.length > 64) { setError('A logo can hold up to 64 variations. Choose fewer files.'); return; }
+        setPending(list => [...list, ...files.map(file => ({ id: counter.current++, file, name: file.name.replace(/\.[^.]+$/, '').replace(/[-_]+/g, ' ').slice(0, 120) || 'Variation' }))]); event.target.value = '';
+      }} /></label>
+      {pending.length > 0 && <div className="logo-upload-list">{pending.map(item => <div className="logo-upload-row" key={item.id}><UploadPreview file={item.file} /><label className="create-field"><span>Variation name</span><Input value={item.name} required maxLength={120} disabled={busy} onChange={event => setPending(list => list.map(value => value.id === item.id ? { ...value, name: event.target.value } : value))} /><small>{item.file.name}</small></label><Button className="icon-button" aria-label={`Remove ${item.file.name} from upload`} disabled={busy} onClick={() => { setPending(list => list.filter(value => value.id !== item.id)); setError(''); }}><Icon name="close" size={16} /></Button></div>)}</div>}
+      {error && <p className="field-error" role="alert">{error}</p>}
+      <div className="dialog-actions"><Button onClick={onClose} disabled={busy}>Cancel</Button><Button type="submit" className="primary" disabled={busy || !connected || !pending.length || pending.some(item => !item.name.trim())}>{busy ? progress : pending.length ? `Add ${pending.length} ${pending.length === 1 ? 'variation' : 'variations'}` : 'Add variations'}</Button></div>
+    </form>
+  </Dialog.Popup></Dialog.Portal></Dialog.Root>;
+}

package/src/app/Markdown.tsx

@@ -0,0 +1,34 @@
+import { Children, isValidElement, useEffect, type ReactNode } from 'react';
+import ReactMarkdown from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+import { guideHeadingSlug, resolveGuideLink, type GuideLocation } from './guideLinks';
+
+function plainText(children: ReactNode): string {
+  return Children.toArray(children).map(child => typeof child === 'string' || typeof child === 'number' ? String(child) : isValidElement<{ children?: ReactNode }>(child) ? plainText(child.props.children) : '').join('');
+}
+
+export function Markdown({ children, file, onNavigate, onReady }: { children: string; file: string; onNavigate: (location: GuideLocation) => void; onReady?: () => void }) {
+  useEffect(() => { onReady?.(); }, [children, file, onReady]);
+  const headings = new Set<string>();
+  function heading(level: 1 | 2 | 3 | 4 | 5 | 6, children: ReactNode) {
+    const slug = guideHeadingSlug(plainText(children));
+    let unique = slug;
+    for (let count = 1; headings.has(unique); count += 1) unique = `${slug}-${count}`;
+    headings.add(unique);
+    const Tag = `h${level}` as const;
+    return <Tag id={`guide-${unique}`} data-guide-heading={unique}>{children}</Tag>;
+  }
+  return <div className="markdown-body">
+    <ReactMarkdown remarkPlugins={[remarkGfm]} skipHtml components={{
+      a: ({ node: _node, href, ...props }) => {
+        const link = href && resolveGuideLink(file, href);
+        return !link ? <span title={href}>{props.children}</span> : link.kind === 'external'
+          ? <a {...props} href={link.href} target="_blank" rel="noopener noreferrer" />
+          : <a {...props} href={`/api/guides?path=${encodeURIComponent(link.location.file)}${link.location.fragment ? `#${encodeURIComponent(link.location.fragment)}` : ''}`} onClick={event => { event.preventDefault(); onNavigate(link.location); }} />;
+      },
+      h1: ({ children }) => heading(1, children), h2: ({ children }) => heading(2, children), h3: ({ children }) => heading(3, children),
+      h4: ({ children }) => heading(4, children), h5: ({ children }) => heading(5, children), h6: ({ children }) => heading(6, children),
+      table: ({ node: _node, ...props }) => <div className="markdown-table"><table {...props} /></div>,
+    }}>{children}</ReactMarkdown>
+  </div>;
+}