@ryanyahya/opendoc 0.4.0

package/docs/MEDIA.md

@@ -0,0 +1,112 @@
+# Document media
+
+Each document owns its prepared media. OpenDoc embeds and previews those visuals; the project and coding agent manage original reference material. There is no source library or required source-folder layout. Reusable logos and fonts belong in the shared **Logos** and **Fonts** tabs of **Media & Assets**; see [Assets](ASSETS.md). Do not copy those families into each document's media folder.
+
+Run commands from the workspace root. The paths below refer to that workspace, not the installed package containing this guide.
+
+```text
+documents/cooling-curves/
+  index.tsx
+  media/
+    cooling-curves/
+      meta.json                 title, description, file and relationships
+      image.png                 the embedding image
+      data.json                 rows prepared for this chart
+      recipe.py                 optional reproducible preparation
+      generation.json           recorded image and input hashes
+    temperature-drop/
+      ...                       another view of the same source
+```
+
+Original datasets, supplied PDFs, previous drafts, and reference documents stay wherever the surrounding project manages them. Do not copy or move originals just to satisfy OpenDoc. Several documents may use the same original. Prepared selections, calculations, chart specifications, and editable diagram files belong beside the image that uses them. The coding agent interprets the originals, prepares visuals, and checks evidence and attribution.
+
+## Describe a visual
+
+Every `media/<id>/meta.json` requires `title`, `description`, `file`, and `kind`. IDs use lowercase words separated by single hyphens. `kind` is `photo`, `illustration`, `chart`, `diagram`, or `image`.
+
+```json
+{
+  "title": "Temperature over time",
+  "description": "Two illustrative cooling curves from one synthetic dataset.",
+  "file": "image.png",
+  "kind": "chart",
+  "alt": "Cup A falls from 80 to 53 degrees Celsius; Cup B falls to 62.",
+  "sources": ["Project teaching dataset; synthetic, not measured"],
+  "data": "data.json",
+  "recipe": "recipe.py",
+  "attribution": "Synthetic teaching example; no experiment was conducted."
+}
+```
+
+`alt`, `sources`, `data`, `recipe`, and `attribution` are optional. `sources` contains descriptive provenance notes or locations for the author: OpenDoc displays the text but never resolves, downloads, hashes, or requires those files. Existing source-path notes remain valid. `file`, `data`, and `recipe` identify owned files relative to the media item; parent traversal, hidden paths, and symlinks are rejected for these files. Unknown fields are rejected. Titles are limited to 200 characters; descriptions and each source note to 4,000.
+
+PNG and JPEG are the supported media embedding formats, up to 50 MB and 100 megapixels. Preserve an SVG or other editable original alongside a PNG export; arbitrary SVG text rendering is not reliable in the current PDF engine. Shared logos have their own SVG/PNG import path with automatic PNG preparation; use [Assets](ASSETS.md) for those. Use an image large enough for its printed size—about 300 pixels per inch for charts—and inspect labels at actual reading size. Keep important chart values in a selectable table as well: raster chart labels are image pixels in the PDF.
+
+## Add, generate, and review
+
+Use the existing image tool or a suitable chart/diagram tool to produce the visual. The media contract does not choose a generator, run recipes automatically, or install their dependencies. Choose tools already available for the task. Keep any recipe reproducible and resolve its files from its own location. Sample documents are not a required dependency.
+
+```sh
+npx opendoc media import my-report overview --file /path/to/image.png --title "Overview" --description "The main stages." --kind diagram
+```
+
+Media imports copy an image and refuse to overwrite an existing media folder. Media is added by the agent from chat attachments, generated visuals, or downloaded images. The app browses these document-owned folders and edits their details; it has no media upload form. An ordinary photograph can consist of only an image and metadata. For generated work, add the prepared data and recipe before recording it. Add provenance notes when useful. Editing a title, description, or other metadata in the app never records a generated visual as reviewed.
+
+After generating, review the actual image for values, labels, scales, units, and provenance. Then record the reviewed inputs:
+
+```sh
+npx opendoc media record my-report overview
+npx opendoc media check my-report overview
+```
+
+`record` snapshots file hashes; it does not generate or validate a chart. Never use it just to silence a stale warning. Changing prepared data, a recipe, or a recorded image marks the item as needing regeneration. Regenerate and review the affected images, then record their new versions. Original-source changes are the author’s responsibility; OpenDoc does not infer whether they require a new chart or a revised argument. Images with inputs but no generation record also require review and recording.
+
+## Place it in the PDF
+
+```tsx
+<Figure id="overview-figure" caption="The main stages." sourceNote="Based on the supplied reference.">
+  <Media item="overview" width={460} />
+</Figure>
+```
+
+Import `Media` from `opendoc` with the other document primitives. Width is a positive value in PDF points. An optional positive `height` sets a maximum bound; the image keeps its aspect ratio. Alternative text defaults to metadata, or can be supplied as `alt`. Preserve the enclosing Figure ID when replacing an image so feedback stays attached.
+
+The document cannot export a stale or unrecorded derived image. Its previous successful preview remains visible, with the current error. After recording, export and review the actual PDF, including caption placement and adjacent page breaks. Raw `Image` and vector `Svg` primitives remain available, but only managed media items appear in the Media browser and receive these provenance checks. For pictures inside SVG layouts, use the frame support below.
+
+## Image frames and full-page artwork
+
+Use `Media` when an image should keep its natural proportions inside a maximum bound. Use `MediaFrame` when the layout needs an **exact rectangle**. It supports `cover` (default: proportional crop) or `contain` (whole image, transparent unused space), normalized `position` (`0` left/top, `0.5` center, `1` right/bottom), and an optional `radius` in PDF points. Width and height are required. Dimensions in `style` do not override them.
+
+```tsx
+import { Block, Figure, MediaFrame, Page, Heading, Paragraph } from 'opendoc';
+
+<Figure id="opening-scene" caption="A supplied photograph of the site.">
+  <MediaFrame item="site" width={490} height={240}
+    fit="cover" position={{x:0.65,y:0.5}} />
+</Figure>
+
+// A circular crop. Use containment for diagrams and images whose labels must stay visible.
+<Block id="portrait"><MediaFrame item="portrait" width={160} height={160} radius={80}/></Block>
+
+// Artwork reaches the page edges; the margin only reserves room for the native text.
+<Page size="A4" margin={48} backgroundMedia="cover-art" backgroundSize="cover">
+  <Heading id="cover-title" level={1} style={{color:'#ffffff',fontSize:54}}>A short title</Heading>
+  <Paragraph id="cover-subtitle" style={{color:'#ffffff'}}>Choose quiet image space for the words.</Paragraph>
+</Page>
+```
+
+Frames and `backgroundMedia` use the same document-owned media IDs, freshness checks, and usage records as `Media`. Frames inherit their enclosing `Block` or `Figure` for feedback; a page background records page-level usage without a block selection. Missing named images fail rendering. You cannot combine `backgroundMedia` and `backgroundImage` on one page. For an unmanaged local PNG/JPEG, `backgroundImage="./image.png"` resolves relative to the authored document; it does not add managed provenance. Managed backgrounds default to centered `cover`; `backgroundSize="contain"` preserves the whole picture, and `backgroundPosition` accepts `center` or a corner such as `top-left`. OpenDoc prepares these proportional local-image backgrounds before sending them to the native page layer, which otherwise stretches images. Explicit `fill` retains stretching; remote URLs retain the native renderer's behavior.
+
+The installed renderer prepares cropped/rounded frames as bounded PNGs, leaving the originals intact and surrounding text selectable. It uses up to 216 dpi with a 4096-pixel edge limit; this does not add detail to a low-resolution source. You do not need to read files, encode base64, import a native addon, or clip an oversized `Image` yourself. Native SVG `<image>` content can disappear without an export error, so use `MediaFrame` for image composition instead. Do not rasterize an entire text page to work around image placement.
+
+For starting compositions, read workspace-root `templates/image-story/AGENTS.md` and view its real PDF in **Templates**. It demonstrates full bleed, vertical/horizontal halves, panoramas with insets, diptychs, collage, and floating text panels. You can use the primitives without using that template. Generate or choose images for their intended aspect ratio and quiet text areas; never crop away a face, important object, label, or evidence merely to match a frame. Always inspect the rendered PDF for image visibility, crop, contrast, caption placement, and text extraction. A successful export is not a visual review.
+
+## Browse and continue with Codex
+
+The **Media** tab in **Media & Assets** lists visuals across documents, searchable by title, description, kind, and document. Existing Media links keep working. Byte-identical images share one browser card; ownership, metadata, and source relationships stay separate. A filename match alone never merges images. The detail view shows their document, current PDF usage, prepared files, and optional source notes.
+
+File downloads are limited to document-owned media files. Original references are shown only as source notes. Selecting a media item updates `.opendoc/current.json` with its folder, metadata, and input status so Codex can work on the right item. Selection remains observed context, never an instruction to change the document. Metadata is editable in the app or through ordinary local files and the coding agent; prepared data, recipes, and regeneration remain agent work.
+
+## Existing projects
+
+Existing original files and media folders remain in place. Older generation records may contain original-source hashes; those remain historical information and no longer participate in media checks. Current checks cover only the image and its own prepared data and recipe. Normal document imports still participate in dependency tracking and rerendering. Citations, references, and source notes in PDFs continue to work independently of file organization.

package/docs/PROJECTS.md

@@ -0,0 +1,55 @@
+# Projects
+
+A workspace contains projects, and every newly created document must have a project. A new workspace starts with **Getting started** and the **Welcome to OpenDoc** document and welcome presentation. Paths in this guide refer to the workspace root; the installed guide itself lives in `node_modules/opendoc/docs`.
+
+## In the app
+
+Use the **+ beside Projects in the sidebar** to create a project. A name is required; a default theme is optional. Choose a project in the sidebar to create and find its documents. **Documents** shows all documents across the workspace, with project links beneath their previews. There is no separate projects overview page. On narrow screens, **Open sidebar** reveals the full project list and creation button. **Project settings** changes its name or default theme. **Move to project** changes an existing document’s membership. A project can be deleted only when it has no documents.
+
+**Create document** and **Create presentation** provide agent prompts carrying the current project, without a title, purpose, or theme form. **Use this template** and theme-based creation carry the selected layout or theme in the prompt. The agent follows [opendoc-create](../.agents/skills/opendoc-create/SKILL.md), resolves any missing project from the brief or current context, and asks when a meaningful design preference is unclear. Naming the skill is optional. Creation requires project membership; the CLI uses an explicit theme override, then the project default, then Neutral. Those fallbacks apply after the agent resolves the user's direction. Explicitly requested starter examples retain their own fallback themes. Changing a project default applies to future work. Moving a document or presentation keeps its existing theme.
+
+Switch between **Gallery** and **List** beside the document count in Documents or any project. List shows a compact first-page PDF thumbnail, name, document details, and a project link in Documents. The browser remembers one shared view preference. Switching views preserves the current search.
+
+The **…** menu on every card or list row offers **Rename**, **Duplicate**, **Move to project…**, and **Delete**. These actions also appear in the reader’s **Document options** menu. Rename changes the library name; the PDF title stays authored in source. Duplicate copies saved source, local media, and feedback into the same project, rebinding supplied template instance IDs and local data paths. It does not include unsaved browser drafts. Delete asks for confirmation and shows an **Undo** notification. Its saved folder and receipt remain recoverable in `.opendoc/trash/<restore-id>/`; existing PDF exports remain in `output/`. Restore refuses to overwrite a reused ID and requires the original project to exist.
+
+Opening a document hides the workspace sidebar and gives the reader the full window. The header’s back arrow returns to the project, Documents, or other workspace view you opened from and restores navigation. A directly opened document returns to its project, or Documents if it has no project. The same pattern applies on mobile.
+
+If files from an older workspace have no assignment, **Documents** keeps them accessible and offers **Choose a project** beneath each unassigned document. OpenDoc does not invent a replacement project or silently discard these files.
+
+## Local files
+
+`projects.json` owns project names, optional default themes, document assignments, and optional library names:
+
+```json
+{
+  "version": 1,
+  "projects": [
+    { "id": "getting-started", "name": "Getting started", "defaultTheme": "neutral" }
+  ],
+  "assignments": { "welcome": "getting-started" },
+  "names": { "welcome": "Workspace guide" }
+}
+```
+
+Documents remain at `documents/<id>/index.tsx`. Grouping is separate from physical folders. Renaming projects or documents and moving documents do not move files or rewrite imports, media, comments, or PDF contents. Document IDs are unique across the workspace. Templates and themes remain shared resources.
+
+The creation service records membership before exposing a new document entry. Browser and command-line changes serialize through a local lock and atomically replace the manifest. Invalid registries are reported without being overwritten. If a process terminates while holding the project lock, the next operation recovers it only after confirming the owner is no longer running. An active or unrecognized lock remains protected; retry after the other operation finishes rather than deleting its lock blindly.
+
+The optional `names` map is keyed by stable document ID. Without an override, the app uses the PDF metadata title. The generated `.opendoc/current.json` distinguishes the library `name` from the authored `title` and includes the active project and its default theme alongside the document or selection. Do not edit this generated context by hand.
+
+## Commands
+
+Run from the workspace root, or add `--workspace <path>`. Use `npx opendoc --help` for the command list and `--json` for machine-readable output.
+
+```sh
+npx opendoc projects list
+npx opendoc projects create client-work --name "Client work" --theme neutral
+npx opendoc projects update client-work --name "Client publications" --theme civic-spectrum
+npx opendoc projects update client-work --theme none
+npx opendoc create proposal --project client-work --title "A proposal"
+npx opendoc create brief --project client-work --title "A technical brief" --theme field-manual
+npx opendoc projects assign proposal client-work
+npx opendoc projects delete empty-project
+```
+
+A missing or unknown project prevents creation before any document folder is written. Use the normal creation command for bespoke documents too, then replace its editable source. If importing existing document folders, assign each one using the project command. Preserve unrelated assignments and stable document IDs.

package/docs/PROSE.md

@@ -0,0 +1,15 @@
+# Continuous prose
+
+`Prose` is an optional OpenDoc region for continuous reading text. The Editorial essay template uses it for its body. Existing documents retain their paragraph behavior unless they explicitly use this region.
+
+It leaves the first paragraph flush left and indents subsequent paragraphs by 1½ em. Paragraph gaps default to zero; set `paragraphGap` to a non-negative number of points for extra spacing. Editorial essay uses `<Prose paragraphGap={6}>`. Headings, section starts, figures, tables, callouts, lists, and explicit breaks restart the reading sequence. Section lead paragraphs stay flush; their following paragraphs indent. Captions, tables, and reference entries do not receive body formatting. Pure author components and fragments expand before formatting, so their paragraph IDs and source locations remain available for comments.
+
+## Forme compatibility
+
+Forme 0.20.1 has no native first-line-indent style. OpenDoc uses an isolated inline U+2003 em-space run, sized to the requested indent. Its measured advance is fixed; an ordinary leading whitespace string is stretchable glue in this engine and does not reliably preserve its width. This is a compatibility shim, not a native Forme feature. No word joiner, tabs, manual line splitting, dependency patch, or full-paragraph padding is involved.
+
+The body uses greedy line breaking by default to keep measured text within the column in this renderer. An explicit paragraph `lineBreaking` choice takes precedence. The spacer appears only at the paragraph's beginning; Forme handles all subsequent lines and page fragments. It leaves the body line height unchanged. Searchable and copied text retain the authored words; layout-oriented extraction may include normal indentation spaces.
+
+This helper deliberately supports one measured 1½-em indent. Do not generalize it to arbitrary spacing without new PDF coordinate checks: Forme can merge a spacer run that has the same font size as the body and treat it as stretchable whitespace. Do not nest `Prose` regions; sibling regions start separate paragraph sequences. Keep regions within a single document's body. Use a separate region or a structural break to begin a new passage, not blank paragraphs.
+
+Regression checks read actual PDF coordinates with the bundled Sans and Serif fonts, check continuation lines across pages, verify heading/figure/section resets, and preserve mixed inline formatting, citations, source locations, and existing non-Prose paragraphs. Recheck the spacer advance and extraction before using a new font or upgrading Forme. Replace this shim with native first-line indentation when the engine supports it and those checks pass.

package/docs/SELECTION.md

@@ -0,0 +1,59 @@
+# Selection and quick corrections
+
+OpenDoc uses stable component selection for text editing and feedback. A fixed-width bottom bar offers Edit and Comment for the selection; both use the same panel above it. Saved comments have their own bottom-right dock. Hover outlines identify components before clicking. Text selection and copying stay inside the editor; the PDF itself supports component selection, links, navigation, and reading.
+
+## Correcting text
+
+Click a component to select it without opening a panel. Choose the Edit icon to edit its full text value, or the Comment icon to write feedback. The bar keeps the same dimensions when either panel opens or closes. Valid changes enter a browser draft and update a separately rendered PDF preview. Moving to another component, clicking outside, **Done**, Cmd/Ctrl+Enter, and Escape keep those changes without writing source. A change that crosses source values or generated content must be corrected or reset before leaving the editor. Formatting and structural changes remain agent work.
+
+The floating bar keeps the pending count, Undo, Redo, Discard, and Save all together. Consecutive typing in one source value coalesces into history steps; native textarea undo remains available, while Cmd/Ctrl+Z and Shift+Cmd/Ctrl+Z operate on draft history outside text fields. Save all or Cmd/Ctrl+S validates the combined candidate and writes the group. Save errors retain the draft. A successful source save then updates the canonical PDF; only a ready result displays the saved confirmation. Export stays paused while text changes remain unsaved.
+
+Drafts and their bounded history survive document navigation and reloads in the same browser tab. If source changes elsewhere, Refresh draft carries forward only edits whose original values and identities still match. Conflicts keep the draft for review. Storage failures retain the in-memory draft and warn before a reload can lose it. The latest saved group has one guarded, server-session-local Undo; later source changes invalidate it instead of overwriting newer work.
+
+Open editors remember the source version they came from. Untouched text follows source updates; modified text from an older or unknown version stays available for review without silently becoming a new draft change.
+
+A correction replaces text within one proven writable source value and preserves surrounding structure and formatting. Shared local constants update every occurrence, and the draft count counts that shared value once. Mixed formatting stays intact: individual changes must stay inside one existing source value. Imported, computed, and unsupported expressions are available for feedback rather than guessed from their displayed wording.
+
+The renderer issues writable targets. Requests do not choose arbitrary files or source spans. The server checks the baseline document revision, PDF hash, source digests, and source ownership; validates all candidate files; and renders a real draft PDF through isolated source overrides. Previewing never changes document source or canonical artifacts. Save stages the validated replacements and uses guarded rollback on a write failure, preserving intervening external changes. These safeguards do not imply a filesystem-wide atomic rename across independent files.
+
+## Binding reusable content
+
+Native OpenDoc blocks provide content slots. Shared components can declare a caller-owned prop with the transparent `TextSlot` helper:
+
+```tsx
+import { Paragraph, TextSlot } from 'opendoc';
+
+export function Byline({ author }: { author: string }) {
+  return <Paragraph id="byline">
+    <TextSlot slot="author" from="author">{author}</TextSlot>
+  </Paragraph>;
+}
+```
+
+For a validated data template, bind a string in the instance's `provenance.dataFile`:
+
+```tsx
+<TextSlot slot="client-name" field={['client', 'name']}>
+  {data.client.name}
+</TextSlot>
+
+{data.terms.map(term => <Paragraph id={`term-${term.id}`} key={term.id}>
+  <TextSlot slot="text" field={['terms', { id: term.id }, 'text']}>
+    {term.text}
+  </TextSlot>
+</Paragraph>)}
+```
+
+Slots and record IDs must remain stable through edits and reordering. TextSlot adds no PDF node, style, or text. Bind the original string, not a formatted or computed representation. Data corrections run the existing template parser before saving; import `bindTemplate` from `opendoc/template` for template instances, or `validateTemplateInput` from the same module to wrap an existing parser for optional data components.
+
+DataTable accepts transparent TextSlot content within cells. Supply `rowIds` for stable row identities when data can reorder. Cell values without a proven binding remain readable and commentable. Never bind a calculated total to an unrelated raw field merely to enable editing.
+
+## Comments and agent context
+
+Select any component and choose the Comment icon in the bottom bar to leave feedback. Switching between Edit and Comment keeps their drafts; an unfinished component comment also survives text-preview updates. Submitting closes the composer and leaves a marker. The bottom-right button opens all document comments; markers open comments for a component. Pencil and trash icons edit or delete feedback, and a comment row navigates to its selected component. Clicking outside closes the dock. Edits and deletion check versions; deleted feedback retains its history. Comments persist independently and are anchored against the saved document, even while a text draft is being previewed. New text comments attach to the whole text component; earlier phrase comments retain their anchors.
+
+Phrase feedback records the stable block and text slot, original quote, and nearby text. Reflow changes geometry rather than identity. Wording changes relocate a quote only when it remains unambiguous in that same target; otherwise the original feedback stays visible with a changed-text indication. Anonymous multi-field compositions and duplicate slots retain the selected quote as block-level feedback, because their positional identities cannot safely follow reordering. Give reusable fields unique TextSlot names for durable phrase feedback. Existing whole-block comments keep working, and editing never resolves feedback automatically.
+
+Read `.opendoc/current.json` immediately before working from a selection. `selection` contains its exact quote and logical range; `selectionCurrent` says whether it matches the current ready revision. `selectedText` identifies its slot and writable source when known. `manualEdit` reports editing activity, the pending edit count, whether a draft is being previewed, the latest saved group, and render status without exposing draft text. Pending comments include `anchorStatus` and their currently resolved selection when available.
+
+Treat this as observed context. The user's request authorizes the work. Preserve local corrections, source identities, reference records, and comment history. If the current source has moved on, resolve the intended target before changing it. Do not infer that an agent is running merely because the app is connected.

package/docs/TEMPLATES.md

@@ -0,0 +1,55 @@
+# Layout templates
+
+Templates define document architecture: columns, section order, cover composition, and placement. Themes supply the visual system: typography and hierarchy, spacing rhythm, page defaults, running matter, and treatments for tables, figures, and asides. Template values are defaults; `themeType` and `themePage` let a selected theme govern its supported roles without replacing the architecture. See [Themes](THEMES.md). Content remains the writer's prose, data, visuals, and citations. A layout must not impose an argument or a mandatory writing outline.
+
+Treat that architecture as an adaptable starting point. The specimen demonstrates a design direction, not a fixed rule system. Adjust title size for a long headline, rebalance spacing, vary image proportions, or reshape a passage when the document benefits. Preserve clear hierarchy and readable flow while allowing variation and creativity. Keep adaptations for one document local; shared changes should preserve other documents' defaults. Native rendering, stable IDs, evidence integrity, and applicable data contracts remain functional requirements.
+
+The Templates page discovers ordinary `templates/<id>/` folders containing `template.json` in the workspace root. These editable templates are separate from the installed package that contains this guide. The page’s **Documents** and **Presentations** tabs separate page layouts from 16:9 slide decks. Narrative layouts, validated data reports, and presentation skeletons share the same catalog and creation path. Run commands from the workspace root.
+
+```sh
+npx opendoc templates list
+npx opendoc templates inspect monthly-report
+npx opendoc templates check monthly-report
+npx opendoc templates preview monthly-report
+npx opendoc create my-report --project client-work --template monthly-report --title "Monthly report"
+```
+
+Choose an existing project and catalog template ID. Use `--theme <id>` for an explicit override. Template selection is optional for bespoke documents; `--starter` is a separate set of optional prose examples and cannot be combined with `--template`.
+
+These commands work in both editions without a browser. `check` validates the descriptor and renders the Neutral specimen with the same format/layout checks as the catalog. `preview` additionally writes `output/templates/<id>.pdf` with source freshness checks. For page images, extracted text, and structured review evidence, use `npx opendoc review --template <id> --json`, then inspect its returned artifacts. Headless theme/template creation and reuse stay in the remote workspace; the recipient can review the specimen PDF without installing OpenDoc. See [Headless](HEADLESS.md#create-themes-and-templates-remotely).
+
+Each catalog folder contains:
+
+- `AGENTS.md`: brief, qualitative guidance on the design's character and useful defaults, explicitly allowing content-led variation and giving examples. Distinguish flexible visual choices from functional requirements. The shared attitude lives in `templates/AGENTS.md`.
+- `index.tsx`: the reusable pure layout component. Accept a theme from the caller. Preserve structural dimensions where necessary; use theme helpers for type roles and page defaults. Do not reset the caller’s body size, line height, or paragraph gap.
+- `template.json`: `name`, `description`, `format` (a human-readable label), and `structure` (one to eight short layout notes). Presentation templates add `"documentFormat": "presentation"`; omission means `document`. This determines project registration, catalog grouping, and the required root in the PDF specimen.
+- `preview.tsx`: a default pure document component and document metadata, rendered with the shared `neutral` theme. Use clearly marked placeholders so different templates can be compared on structure. This is an actual PDF rendered by the same worker and preflight as documents.
+- `starter.tsx`: a working ordinary document, with double-quoted `"__OPENDOC_TITLE__"` and `"__OPENDOC_THEME__"` literals. Creation replaces these literals with safely quoted user values and copies the result into a new document folder, alongside generated `theme.tsx` and `assets.json` files. Keep workspace-relative provenance and imports valid from `documents/<id>/index.tsx`. The reusable layout stays linked to its template folder.
+
+The starter imports `{ theme }` from the exact quoted `"__OPENDOC_THEME_MODULE__"` sentinel once; creation replaces this sentinel import with the generated `./theme` adapter. Use that same adapted theme for template factories and `Document`; importing the base theme directly would bypass saved font choices. It also uses `"__OPENDOC_THEME__"` for metadata and `"__OPENDOC_TITLE__"` for the title. Keep the import’s explanatory TypeScript ignore comment while it is an unresolved starter. Replacement runs once so literal user text is never reinterpreted.
+
+A data-bound catalog template may also contain `data.json` (up to 128 KB, a JSON object). Creation copies it into the document before publishing the TSX entry; the title and theme literals may appear in that JSON instead of the starter. The optional double-quoted `"__OPENDOC_DOCUMENT_ID__"` literal in the TSX receives the validated document ID, for accurate data provenance. This uses the same exclusive creation path and never overwrites an existing instance. Quotation demonstrates this pattern. Keep data parsing and calculation in the template contract, not the catalog UI.
+
+Use workspace-root `templates/editorial-essay` as the first example. Its layout accepts arbitrary OpenDoc blocks, with no prescribed section outline or JSON format. Import the `DocumentTemplate<T>` contract and binding helpers from `opendoc/template`; import `themeType` and `themePage` from `opendoc/themes`. The contract provides `parse`, `meta`, and `render` for validated data-driven reports. Use it when content needs validation; a narrative page layout can accept ordinary blocks. Keep imports of reusable workspace layouts relative, such as `../../templates/monthly-report` from a document entry.
+
+The page presents every specimen in Neutral. A separate theme choice applies when creating a document; the preview remains neutral for comparison. New documents use the existing exclusive folder creation path, preserve existing files, and enter the normal preview/comment/export workflow. A malformed template stays visible with an error; it does not remove other templates. Preview changes invalidate the catalog, and proofs remain outside the document library.
+
+Supply sparse, typical, and long specimens, check every rendered page, and verify that changing the theme preserves the intended architecture. Do not promise multi-column sequential text flow until it has been demonstrated in the renderer. A pair of bounded side-by-side panels is not proof of continuous two-column pagination.
+
+## Presentation templates
+
+Use `Presentation` and explicit `Slide` components. Each slide remains one 960 × 540 PDF page. The template's declared format is inferred during creation; an explicit `--format` must agree. For example:
+
+```sh
+npx opendoc create investor-deck --project client-work --template pitch-deck --title "Company pitch"
+```
+
+The catalog includes Pitch deck, Brand guidelines, Company profile, and Proposal deck. Each guide records research sources and a recommended skeleton. Adapt the sequence to the audience and brief; the outline is a starting point. Keep editable copy, evidence fields, and visual assignments in the instance starter. Shared template code supplies composition. Mark missing evidence and image slots clearly, use document-owned media when populating them, and never use invented numbers or credentials as a finished company's facts.
+
+Inspect every slide, including sparse content, long titles, and another theme. Long content must be edited, recomposed, or divided into explicitly authored slides; it cannot flow onto an accidental continuation page or be silently reduced to fit.
+
+Custom template creation happens with the external agent. The page's Create template action supplies a reusable prompt; there is no embedded AI service or form builder.
+
+## Project membership
+
+Every created document or presentation instance requires a destination project. The creation prompt carries the selected template; the agent resolves the project and any meaningful design preferences through [opendoc-create](../.agents/skills/opendoc-create/SKILL.md). The CLI uses an explicit theme choice, then the project default, then Neutral. Moving an instance or changing a project default leaves its source and current theme intact. Template specimens remain shared resources outside the project document list. **View AGENTS.md** opens the selected template’s current guidance in a scrollable Markdown dialog.

package/docs/THEMES.md

@@ -0,0 +1,106 @@
+# Themes
+
+A theme is OpenDoc’s reusable document design system. It controls more than fonts and colors: opening hierarchy, page rhythm, component treatments, tables, captions, asides, and running matter share one executable definition. A short design guide explains how to use those decisions. A real PDF specimen makes the result inspectable in the app.
+
+Themes are authored in source by the external coding agent. Users describe the outcome or supply references; they explore the completed result in the Themes view. The app can choose shared logo and font defaults for new documents; design tokens remain controlled in source. There are no visual tuning controls or embedded AI.
+
+## A small source bundle
+
+```text
+themes/<kebab-case-id>/
+  index.ts       executable definition; named theme export
+  design.md      exact palette, type, geometry, composition, usage, and basis
+  components.tsx reusable visual components, when the system needs them
+  preview.tsx    an independent visual showcase and applied document example
+  assets.json    optional shared logo/body/heading defaults for new documents
+```
+
+These folders belong to the workspace root, not the installed package. The folder ID and `theme.id` must agree. Keep `index.ts` pure data; do not import or re-export React components from it. OpenDoc loads this small module for discovery and loads the preview only on demand. New folders need no registry edit. New documents use the `theme.tsx` adapter generated beside their source:
+
+```tsx
+import { theme } from './theme';
+
+export const meta = {
+  title: 'A clear proposal',
+  description: 'The proposal and its supporting detail.',
+  theme: theme.id,
+};
+// Pass the same theme to <Document theme={theme} ...> or the chosen template.
+```
+
+Metadata identifies the relationship. The theme passed to the document or template actually controls rendering. Keep them consistent. Every real document still belongs to a project; a theme specimen is a separate preview artifact and does not need a project or a document-library entry.
+
+The generated adapter imports the base theme from `../../themes/<id>` and calls `withDocumentAssets` with the document's saved `assets.json`. Use the adapted theme before constructing a template, not only when rendering `Document`; factories may already capture its font roles. Shared colors, geometry, and other rules remain live. Existing direct theme imports remain supported. See [Assets](ASSETS.md) for the adapter and exact-version contract.
+
+## What belongs in the definition
+
+Import `DocTheme`, `themeType`, and `themePage` from `opendoc/themes`. Root properties provide identity, font families, semantic colors, base reading metrics, page size and running-matter defaults. `palette` holds up to 16 named six-digit hex colors with semantic roles. `geometry` holds up to eight short rules; `useFor` and `principles` summarize the design. These bounded fields power the app without loading every guide. The grouped `design` rules style native OpenDoc components:
+
+| Group | Responsibility |
+| --- | --- |
+| Typography | Heading levels, labels, leads, small text, captions, and code |
+| Page and opening | Page geometry, title block, and cover treatment |
+| Furniture | Running header, footer, folio, and their typography |
+| Table and figure | Headers, cells, row treatments, figure spacing, and captions |
+| Callout, list, and code | Useful supporting components with a consistent voice |
+
+Values use the native PDF style contract. Read the type definition and one selected theme rather than assuming browser CSS works. Standard role rules cover ordinary prose and tables; `components.tsx` supplies distinctive constructions such as a modular grid, spectrum rail, circular diagram, evidence chain or analytical exhibit. Export shared tokens from `index.ts` and import them into components. A preview uses these same reusable components. Explicit document/template choices may override a theme where their composition requires it; ordinary content consumes theme roles. Use OpenDoc `Page` and `Pages` for reliable page surfaces, with native Forme primitives inside them.
+
+Use local fonts and assets. The bundled typefaces are the default. Register custom TTF/OTF faces through `theme.fonts`, with workspace-relative `src` paths, family, numeric weight, and style; keep their license alongside. Then use the registered family in the appropriate type roles. Declaring an unregistered family name or CSS fallback stack does not embed a PDF font. Check actual PDF text extraction as well as appearance; see the package's [third-party notices](../THIRD_PARTY.md).
+
+For reusable user-supplied logos and font families, prefer the shared asset library and optional theme defaults. Do not copy those families into every theme or document. The source-font registration below remains useful for a design system's own runtime typefaces and existing themes. Theme components should import `documentFont` from `opendoc` and call `documentFont('body')` or `documentFont('heading')` inside their render function when they explicitly need the document's semantic family. This lets saved font choices reach the component; deliberate code, caption, label, and furniture families can retain their own typefaces.
+
+For example, after obtaining and checking these local font files, a theme could include:
+
+```ts
+// Properties inside the theme definition; replace with verified local assets.
+body: 'Acme Sans',
+heading: 'Acme Sans',
+fonts: [
+  { family: 'Acme Sans', src: 'themes/acme/assets/AcmeSans-Regular.ttf', fontWeight: 400, fontStyle: 'normal' },
+  { family: 'Acme Sans', src: 'themes/acme/assets/AcmeSans-Semibold.ttf', fontWeight: 600, fontStyle: 'normal' },
+  { family: 'Acme Sans', src: 'themes/acme/assets/AcmeSans-Italic.ttf', fontWeight: 400, fontStyle: 'italic' },
+  { family: 'Acme Sans', src: 'themes/acme/assets/AcmeSans-SemiboldItalic.ttf', fontWeight: 600, fontStyle: 'italic' },
+],
+```
+
+These paths are examples, not supplied assets. Register each weight/style combination the theme uses. Additional family declarations may be needed in specific typography roles; labels and code can deliberately retain the bundled fonts. Do not replace the reserved `OpenDoc` font families.
+
+## What belongs in design.md
+
+The guide is a concrete, opinionated design system. Include exact hex values and color roles; type sizes, weights and leading; margins, grid, gutters and spacing units; shape geometry and rule weights; supported compositions; treatment of evidence, imagery and branding; component names and inputs; and specific do/don’t rules. Keep it only as long as the system needs; favor concrete, scannable instructions.
+
+Code executes the values; the guide makes them understandable and repeatable. Keep numeric tables synchronized with exported tokens. Do not duplicate component implementations. A short basis section identifies supplied requirements, inspected references, interpretations and font/asset substitutions. Do not claim an external brand’s authority for an inspired theme.
+
+Original inspiration material remains in the surrounding project’s existing organization. Do not automatically copy or load reference archives. Record useful pointers and keep only necessary local runtime assets with the theme. A document agent ordinarily needs the selected guide, not the research that produced it.
+
+## Specimen and verification
+
+`preview.tsx` exports nonempty `meta.title`, `meta.description`, `meta.theme`, and a default pure component. Make an independent showcase that expresses this system: usually two to four pages combining identity, visible palette/type/geometry and a plausible applied document. Use theme-owned components and standard themed primitives. Distinction must extend into the interior composition and evidence treatment. The shared `ThemeSpecimen` demonstrates the simpler foundations; a new distinctive system should use its own showcase.
+
+The catalog includes Civic Spectrum’s colored modular rail, Field Manual’s annotated evidence chain, McKinsey Consulting’s analytical exhibits, and the warm editorial house style of OpenDoc Neutral. Their guides describe each system and its reusable compositions. Neutral provides a simpler foundation and is the document fallback when no theme is supplied.
+
+Run these commands from the workspace root:
+
+```sh
+npx opendoc themes list
+npx opendoc themes inspect <id>
+npx opendoc themes check <id>
+npx opendoc themes preview <id>
+```
+
+`list` is compact discovery. `inspect` identifies the selected definition, guide, optional components, preview, and bounded design summary without rendering every theme. `check` validates and renders the selected specimen. `preview` exports `output/themes/<id>.pdf` with source freshness checks; an edit during rendering cannot silently replace the previous reviewed export. Themes use the same isolated rendering and layout checks as authored documents.
+
+Run `npx opendoc check` after changing source. Review every exported specimen page at readable size and inspect representative extracted text. Long titles, dense tables, custom fonts, and altered page geometry deserve representative longer-content checks. Existing usage matters: a shared theme change can reflow documents that import it. Review affected examples instead of treating a passing specimen as proof that all documents are unchanged.
+
+## Themes, templates, and projects
+
+The theme defines visual language. A template defines document-type architecture, such as an essay opening, a proposal structure, or invoice geometry. Content determines what is said. Media retains its meaning and evidence even when placed inside a new visual system.
+
+Projects can provide a default theme for new documents. A document can explicitly choose another. Creating or refining a theme does not silently change a project default or reassign existing documents. Documents already importing a shared theme receive its source changes, so that change should be intentional and verified.
+
+The theme detail's **Assets for new documents** section chooses an optional logo, body family, and heading family. **Keep theme font** preserves the source definition. Defaults live in `themes/<id>/assets.json`, separate from `index.ts`, and are captured as exact asset versions during creation. Changing a default does not rebind existing documents; moving, duplicating, or restoring one preserves its selections. A preferred logo is available to `Logo` and the agent but is never inserted automatically. Inspect or change defaults through `npx opendoc assets defaults <theme-id>`; see [Assets](ASSETS.md) for the guarded update command and file shape.
+
+The app’s Themes view is for browsing real specimens, exact colors and geometry, reading the guide, seeing usage, and handing requests to the external agent. The current context identifies the active selection and its file paths so the agent can resolve “this theme.” It does not embed all guides or component bodies. Read the selected guide, then only the component source needed for the task. Re-read `.opendoc/current.json` when resolving a selection. Do not expose the local session token.
+
+For the reference-to-theme workflow, use the [opendoc-create-theme skill](../.agents/skills/opendoc-create-theme/SKILL.md). For document creation, read [Authoring](AUTHORING.md) and resolve the destination [Project](PROJECTS.md).

package/node_modules/@formepdf/core/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Molitor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/node_modules/@formepdf/core/README.md

@@ -0,0 +1,53 @@
+# @formepdf/core
+
+WASM-powered PDF rendering engine for [Forme](https://github.com/formepdf/forme).
+
+## Install
+
+```bash
+npm install @formepdf/react @formepdf/core
+```
+
+## Usage
+
+```tsx
+import { Document, Page, Text } from '@formepdf/react';
+import { renderDocument } from '@formepdf/core';
+import { writeFileSync } from 'fs';
+
+const doc = (
+  <Document>
+    <Page size="Letter" margin={54}>
+      <Text style={{ fontSize: 24 }}>Hello Forme</Text>
+    </Page>
+  </Document>
+);
+
+const pdfBytes = await renderDocument(doc);
+writeFileSync('output.pdf', pdfBytes);
+```
+
+## What this package does
+
+This package contains the compiled WASM binary of Forme's Rust layout engine. It handles:
+
+- Page-native layout with automatic content splitting
+- Font loading, subsetting, and TrueType embedding
+- PDF generation with links, bookmarks, images, and SVG
+- Table layout with automatic header repetition
+
+You write components with `@formepdf/react`. This package turns them into PDF bytes.
+
+## API
+
+### `renderDocument(jsx)`
+
+Takes a JSX document tree and returns a `Uint8Array` of PDF bytes.
+
+### `renderDocumentWithLayout(jsx)`
+
+Returns both the PDF bytes and layout metadata (element positions, sizes, page info). Used by the dev server for the element inspector.
+
+## Docs
+
+Full documentation at [docs.formepdf.com](https://docs.formepdf.com)

package/node_modules/@formepdf/core/dist/attachments.d.ts

@@ -0,0 +1,55 @@
+/**
+ * PDF attachments + Factur-X/ZUGFeRD e-invoice container options.
+ *
+ * Environment-neutral (Node, browser, workers): used by every entry
+ * point so the option mapping cannot drift between them.
+ *
+ * Tier-1 container support only: the caller supplies the invoice XML;
+ * Forme embeds it as a PDF/A-3 associated file with the Factur-X XMP
+ * identification. Forme does NOT generate or validate EN 16931 semantic
+ * content.
+ */
+/** `/AFRelationship` values (PDF 2.0 §14.13, required by PDF/A-3). */
+export type AfRelationship = 'Data' | 'Source' | 'Alternative' | 'Supplement' | 'Unspecified';
+export interface AttachmentOptions {
+    /** Filename recorded in the PDF (e.g. `factur-x.xml`). */
+    name: string;
+    /** File content: bytes, or a string treated as UTF-8 text. */
+    data: Uint8Array | string;
+    /** MIME type (PDF/A-3 requires one); default `application/octet-stream`. */
+    mimeType?: string;
+    /** Default `Unspecified` (the Factur-X path derives it from the profile). */
+    relationship?: AfRelationship;
+    /** Optional human-readable description. */
+    description?: string;
+    /**
+     * `/Params /ModDate` as a PDF date string (`D:YYYYMMDDHHmmSSZ`).
+     * Defaults to a fixed constant — never wall-clock — so output stays
+     * byte-deterministic.
+     */
+    modDate?: string;
+}
+/** Factur-X / ZUGFeRD profile names, exactly as XMP spells them. */
+export type FacturXProfile = 'MINIMUM' | 'BASIC WL' | 'BASIC' | 'EN 16931' | 'EXTENDED' | 'XRECHNUNG';
+export interface FacturXOptions {
+    /** The invoice XML (caller-supplied; Forme does not generate or validate it). */
+    xml: Uint8Array | string;
+    /** Factur-X profile — drives XMP `fx:ConformanceLevel` and the default `/AFRelationship`. */
+    profile: FacturXProfile;
+    /** Attachment filename; default `factur-x.xml` (`xrechnung.xml` for XRECHNUNG). */
+    filename?: string;
+    /** Override the profile-derived `/AFRelationship`. */
+    relationship?: AfRelationship;
+    /** XMP `fx:Version`; default `1.0`. */
+    version?: string;
+    /** `/Params /ModDate`; deterministic default. */
+    modDate?: string;
+}
+/**
+ * Map `attachments` / `facturX` options onto the serialized document.
+ * Shared by the Node, browser, and worker entries.
+ */
+export declare function applyAttachmentOptions(doc: Record<string, unknown>, options?: {
+    attachments?: AttachmentOptions[];
+    facturX?: FacturXOptions;
+}): void;

package/node_modules/@formepdf/core/dist/attachments.js

@@ -0,0 +1,59 @@
+/**
+ * PDF attachments + Factur-X/ZUGFeRD e-invoice container options.
+ *
+ * Environment-neutral (Node, browser, workers): used by every entry
+ * point so the option mapping cannot drift between them.
+ *
+ * Tier-1 container support only: the caller supplies the invoice XML;
+ * Forme embeds it as a PDF/A-3 associated file with the Factur-X XMP
+ * identification. Forme does NOT generate or validate EN 16931 semantic
+ * content.
+ */
+function toBase64(data) {
+    const bytes = typeof data === 'string' ? new TextEncoder().encode(data) : data;
+    // Node fast path; browser/workers fall back to btoa over a binary string.
+    const B = globalThis.Buffer;
+    if (B)
+        return B.from(bytes).toString('base64');
+    let bin = '';
+    for (let i = 0; i < bytes.length; i += 0x8000) {
+        bin += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    }
+    return btoa(bin);
+}
+/**
+ * Map `attachments` / `facturX` options onto the serialized document.
+ * Shared by the Node, browser, and worker entries.
+ */
+export function applyAttachmentOptions(doc, options) {
+    const attachments = [];
+    for (const a of options?.attachments ?? []) {
+        attachments.push({
+            name: a.name,
+            src: toBase64(a.data),
+            mimeType: a.mimeType,
+            relationship: a.relationship,
+            description: a.description,
+            modDate: a.modDate,
+        });
+    }
+    const fx = options?.facturX;
+    if (fx) {
+        const filename = fx.filename ?? (fx.profile === 'XRECHNUNG' ? 'xrechnung.xml' : 'factur-x.xml');
+        attachments.push({
+            name: filename,
+            src: toBase64(fx.xml),
+            mimeType: 'text/xml',
+            relationship: fx.relationship,
+            modDate: fx.modDate,
+        });
+        doc.zugferd = {
+            conformanceLevel: fx.profile,
+            documentFileName: filename,
+            version: fx.version,
+        };
+    }
+    if (attachments.length > 0) {
+        doc.attachments = attachments;
+    }
+}