@ryanyahya/opendoc 0.4.0

package/starter/templates/quotation/examples/typical.json

@@ -0,0 +1,64 @@
+{
+  "schemaVersion": 1,
+  "title": "Website content package",
+  "number": "SAMPLE-Q-001",
+  "issuedOn": "2026-09-08",
+  "validUntil": "2026-09-22",
+  "seller": {
+    "name": "Example Studio",
+    "details": "Studio address placeholder\nContact details placeholder"
+  },
+  "client": {
+    "name": "Example Client",
+    "details": "Client address placeholder\nAttention: project contact"
+  },
+  "synthetic": true,
+  "introduction": "A sample scope and pricing schedule. Replace the illustrative details with the work and commercial terms actually agreed with the client.",
+  "pricing": {
+    "currency": {
+      "code": "USD",
+      "decimals": 2
+    },
+    "items": [
+      {
+        "id": "planning",
+        "description": "Content planning workshop",
+        "quantity": "2.5",
+        "unit": "hours",
+        "unitPrice": "160.00"
+      },
+      {
+        "id": "writing",
+        "description": "Website copy package: supplied scope and agreed deliverables",
+        "quantity": "1",
+        "unit": "package",
+        "unitPrice": "600.00"
+      },
+      {
+        "id": "review",
+        "description": "Review and revision sessions",
+        "quantity": "3",
+        "unit": "hours",
+        "unitPrice": "75.00"
+      }
+    ],
+    "discount": "25.00",
+    "tax": {
+      "label": "Illustrative tax",
+      "ratePercent": "10"
+    }
+  },
+  "terms": [
+    {
+      "id": "delivery",
+      "title": "Delivery",
+      "text": "Illustrative schedule placeholder. Supply the milestones, dependencies, and delivery dates that apply to the actual work."
+    },
+    {
+      "id": "payment",
+      "title": "Payment",
+      "text": "Illustrative payment placeholder. Supply the agreed payment schedule and any relevant reference details."
+    }
+  ],
+  "acceptance": "Optional acceptance wording placeholder. Replace with the agreed process, or omit this area when acceptance is recorded elsewhere."
+}

package/starter/templates/quotation/index.tsx

@@ -0,0 +1,51 @@
+import type { ReactNode } from 'react';
+import * as F from '@formepdf/react';
+import { TextSlot, Block, Document, Heading, Paragraph, Strong, Page } from 'opendoc';
+import { defineTemplate } from 'opendoc/template';
+import { themePage, type DocTheme } from 'opendoc/themes';
+import { BusinessLogo } from '../_shared/BusinessLogo';
+import { Pricing } from '../_shared/Pricing';
+import { parseQuotation, type QuotationData } from './schema';
+export { parseQuotation } from './schema';
+export type { QuotationData } from './schema';
+
+export function Quotation({ data, theme, titleStyle, logo }: { data: QuotationData; theme: DocTheme; titleStyle?: F.Style; logo?: ReactNode }) {
+  const layoutTheme = theme.design ? theme : { ...theme, fontSize: 10.5, lineHeight: 1.4, paragraphGap: 8 };
+  return <Document title={data.title} author={data.seller.name} theme={layoutTheme}>
+    <Page {...themePage(theme, { top: 48, bottom: 52, left: 48, right: 48 })} style={{ lineBreaking: 'greedy', ...theme.design?.page?.style }}>
+      {(!theme.design || theme.runningFooter) && <F.Fixed position="footer"><F.Text style={{ fontFamily: theme.design ? theme.body : undefined, fontSize: 8, color: theme.muted, textAlign: 'right', ...theme.design?.furniture?.text, ...theme.design?.furniture?.footer }}>{data.synthetic ? 'Illustrative quotation · ' : ''}{theme.design?.furniture?.pageNumber === 'total' ? '{{pageNumber}} / {{totalPages}}' : '{{pageNumber}}'}</F.Text></F.Fixed>}
+      <F.View style={theme.design?.title?.block}>
+        <F.View wrap={false} style={{ flexDirection: 'row', justifyContent: 'space-between', alignItems: 'center', marginBottom: 8 }}>
+          <Paragraph id="quote-label" role="label" baseStyle={{ fontSize: 9, letterSpacing: 0.8, color: theme.muted, marginBottom: 0 }} style={theme.design?.title?.eyebrow}>QUOTATION</Paragraph>
+          <BusinessLogo id="quote-logo" theme={theme}>{logo}</BusinessLogo>
+        </F.View>
+        <Heading id="quote-title" level={1} baseStyle={{ fontSize: 28, lineHeight: 1.15, marginBottom: 12 }} style={{ ...theme.design?.title?.heading, ...titleStyle }}><TextSlot slot="title" field={['title']}>{data.title}</TextSlot></Heading>
+        <Paragraph id="quote-reference" role="small" baseStyle={{ fontSize: 9, marginBottom: 20 }} style={theme.design?.title?.byline}>No. <TextSlot slot="number" field={['number']}>{data.number}</TextSlot> · Issued <TextSlot slot="issuedOn" field={['issuedOn']}>{data.issuedOn}</TextSlot>{data.validUntil ? <> · Valid through <TextSlot slot="validUntil" field={['validUntil']}>{data.validUntil}</TextSlot></> : ''}</Paragraph>
+      </F.View>
+      <Block id="quote-parties"><F.View wrap={false} style={{ flexDirection: 'row', gap: 28, marginBottom: 16 }}>
+        {([['From', data.seller, 'seller'], ['Prepared for', data.client, 'client']] as const).map(([label, details, partyField]) => {
+          return <F.View key={label} style={{ flex: 1 }}>
+            <F.Text style={{ fontSize: 8.5, color: theme.muted, marginBottom: 5, ...theme.design?.typography?.small }}>{label}</F.Text>
+            <F.Text style={{ fontWeight: 600, marginBottom: 5 }}><TextSlot slot={`${partyField}-name`} field={[partyField, 'name']}>{details.name}</TextSlot></F.Text>
+            {details.details && <F.Text style={{ fontSize: 9.5, color: theme.muted, ...theme.design?.typography?.small }}><TextSlot slot={`${partyField}-details`} field={[partyField, 'details']}>{details.details}</TextSlot></F.Text>}
+          </F.View>;
+        })}
+      </F.View></Block>
+      {data.synthetic && <Paragraph id="quote-sample-notice" role="small" baseStyle={{ fontSize: 9, color: theme.muted }}>Illustrative quotation. All parties, prices, dates, and terms are synthetic. This is not a commercial offer.</Paragraph>}
+      {data.introduction && <Paragraph id="quote-introduction"><TextSlot slot="introduction" field={['introduction']}>{data.introduction}</TextSlot></Paragraph>}
+      <Pricing data={data.pricing} theme={theme} totalLabel="Quoted total" />
+      {data.terms.map(term => <Paragraph key={term.id} id={`quote-term-${term.id.length}-${term.id}`} role="small" baseStyle={{ fontSize: 9.5, marginBottom: 10 }}><Strong><TextSlot slot="title" field={['terms', { id: term.id }, 'title']}>{term.title}</TextSlot>. </Strong><TextSlot slot="text" field={['terms', { id: term.id }, 'text']}>{term.text}</TextSlot></Paragraph>)}
+      {data.acceptance && <F.View wrap={data.acceptance.length > 420}>
+        <Paragraph id="quote-acceptance" role="small" baseStyle={{ fontSize: 9.5, marginTop: 10 }}><Strong>Acceptance. </Strong><TextSlot slot="acceptance" field={['acceptance']}>{data.acceptance}</TextSlot></Paragraph>
+        <Block id="quote-signature-fields"><F.View wrap={false} style={{ flexDirection: 'row', gap: 22, marginTop: 12 }}>
+          {['Name', 'Signature', 'Date'].map(label => <F.View key={label} style={{ flex: 1 }}><F.View style={{ height: 22, borderBottomWidth: 0.6, borderColor: theme.line }} /><F.Text style={{ fontSize: 8, color: theme.muted, marginTop: 5, ...theme.design?.typography?.small }}>{label}</F.Text></F.View>)}
+        </F.View></Block>
+      </F.View>}
+    </Page>
+  </Document>;
+}
+export const quotationTemplate = (theme: DocTheme, { logo }: { logo?: ReactNode } = {}) => defineTemplate<QuotationData>({
+  parse: parseQuotation,
+  meta: data => ({ title: data.title, description: `Quotation ${data.number} for ${data.client.name}.`, kind: 'report', theme: theme.id, author: data.seller.name }),
+  render: data => <Quotation data={data} theme={theme} logo={logo} />,
+});

package/starter/templates/quotation/preview.tsx

@@ -0,0 +1,12 @@
+import { neutral } from '../../themes';
+import { type DocTheme } from 'opendoc/themes';
+import { parseQuotation, quotationTemplate } from './index';
+import typical from './examples/typical.json';
+import sparse from './examples/sparse.json';
+import long from './examples/long.json';
+export const meta = quotationTemplate(neutral).meta(parseQuotation(typical));
+export function Specimen({ length = 'typical', theme = neutral }: { length?: 'sparse' | 'typical' | 'long'; theme?: DocTheme } = {}) {
+  const template = quotationTemplate(theme);
+  return template.render(template.parse({ sparse, typical, long }[length]));
+}
+export default Specimen;

package/starter/templates/quotation/schema.ts

@@ -0,0 +1,27 @@
+import { date, object, optionalText, parsePricing, text, type PricingData } from '../_shared/commerce';
+export interface QuotationData {
+  schemaVersion: 1; title: string; number: string; issuedOn: string; validUntil?: string;
+  seller: { name: string; details?: string }; client: { name: string; details?: string };
+  synthetic: boolean; introduction?: string; pricing: PricingData;
+  terms: { id: string; title: string; text: string }[]; acceptance?: string;
+}
+export function parseQuotation(input: unknown): QuotationData {
+  const data = object(input, ['schemaVersion', 'title', 'number', 'issuedOn', 'validUntil', 'seller', 'client', 'synthetic', 'introduction', 'pricing', 'terms', 'acceptance'], 'quotation');
+  if (data.schemaVersion !== 1) throw new Error('quotation.schemaVersion: expected 1.');
+  if (typeof data.synthetic !== 'boolean') throw new Error('quotation.synthetic: explicitly supply true or false.');
+  const party = (input: unknown, path: string) => { const value = object(input, ['name', 'details'], path); return { name: text(value.name, `${path}.name`, 180, 1), details: optionalText(value.details, `${path}.details`, 700, 8) }; };
+  const issuedOn = date(data.issuedOn, 'quotation.issuedOn');
+  const validUntil = data.validUntil === undefined || data.validUntil === null ? undefined : date(data.validUntil, 'quotation.validUntil');
+  if (validUntil && validUntil < issuedOn) throw new Error('quotation.validUntil: must be on or after issuedOn.');
+  if (data.terms !== undefined && !Array.isArray(data.terms)) throw new Error('quotation.terms: expected an array.');
+  const seen = new Set<string>();
+  const terms = ((data.terms ?? []) as unknown[]).map((raw, i) => {
+    const path = `quotation.terms[${i}]`, term = object(raw, ['id', 'title', 'text'], path), id = text(term.id, `${path}.id`, 100);
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(id) || seen.has(id)) throw new Error(`${path}.id: supply a unique stable ID.`);
+    seen.add(id);
+    return { id, title: text(term.title, `${path}.title`, 120), text: text(term.text, `${path}.text`) };
+  });
+  return { schemaVersion: 1, title: text(data.title, 'quotation.title', 300), number: text(data.number, 'quotation.number', 80), issuedOn, validUntil,
+    seller: party(data.seller, 'quotation.seller'), client: party(data.client, 'quotation.client'), synthetic: data.synthetic,
+    introduction: optionalText(data.introduction, 'quotation.introduction'), pricing: parsePricing(data.pricing), terms, acceptance: optionalText(data.acceptance, 'quotation.acceptance') };
+}

package/starter/templates/quotation/starter.tsx

@@ -0,0 +1,12 @@
+import { bindTemplate } from 'opendoc/template';
+import { quotationTemplate } from '../../templates/quotation';
+// @ts-ignore The selected local theme module is inserted when this starter becomes a document.
+import { theme } from "__OPENDOC_THEME_MODULE__";
+import data from './data.json';
+const documentId = "__OPENDOC_DOCUMENT_ID__";
+const themeId = "__OPENDOC_THEME__";
+// Bind a shared logo, pass <Logo slot="primary" /> through the logo option, or pass null to omit it.
+const bound = bindTemplate(quotationTemplate(theme), data);
+export const meta = { ...bound.meta, theme: themeId };
+export const provenance = { template: 'templates/quotation/index.tsx', dataFile: `documents/${documentId}/data.json` };
+export default bound.Document;

package/starter/templates/quotation/template.json

@@ -0,0 +1,11 @@
+{
+  "name": "Quotation",
+  "description": "Business and client details, a clear pricing schedule, calculated totals, and optional terms and acceptance. For service and product quotations.",
+  "format": "A4 \u00b7 Business quotation",
+  "structure": [
+    "A compact quotation heading, reference, issue date, and optional validity date introduce the same page as the pricing. An optional logo slot sits at the upper right.",
+    "Seller and client details sit side by side, followed by an optional scope introduction.",
+    "Line items flow in a table with repeating headers. Calculated totals align to the right beneath it.",
+    "Optional terms and acceptance follow the pricing. Each document owns its data; themes change the appearance and the layout stays adaptable."
+  ]
+}

package/starter/templates/scientific-paper/AGENTS.md

@@ -0,0 +1,11 @@
+# Scientific paper
+
+Treat this template as a soft foundation for a manuscript, with room for variation and creativity. Its starting character is compact, legible, and focused on the research: a modest title and author block, a distinct abstract, and continuous single-column reading. The dimensions are defaults, not fixed rules. Reduce a long title through `titleStyle`, adapt the abstract or heading treatment, and adjust spacing or exhibit proportions to serve the material. Follow an actual journal's supplied instructions when relevant; this template does not itself claim journal compliance.
+
+Let the writer and research determine the section order. An abstract, keywords, affiliations, and correspondence line are optional. Omit unused elements rather than filling them with invented information. Use `PaperHeading` for compact heading defaults, or ordinary Heading with native styles. Give a short heading and lead a native unbreakable View only when they need to stay together; leave longer passages breakable. Do not impose a mandatory methods/results/discussion outline on every type of paper.
+
+Figures, tables, labels, units, uncertainty, captions, and reference text should remain readable. Adapt a dense exhibit rather than simply shrinking everything. Use the existing Figure, DataTable, Cite, and CrossReference blocks so numbering and references stay consistent. Numeric and author-date citations are existing workspace formats, not promises of a particular publisher's bibliography style. Only cite real supplied or verified sources in authored manuscripts; specimens must clearly identify illustrative records and data.
+
+Keep layout native to Forme: Page, Fixed, View, Text, Image, and Table through the existing OpenDoc blocks. No Prose indentation shim, custom text fitting, manual line splitting, simulated two-column pagination, or renderer patches. For charts, use the established local Media workflow and native image placement. Preserve stable IDs and source provenance. Keep document-specific variations local or expose small options that preserve shared defaults.
+
+Use Neutral for the catalog preview. Review each adapted PDF; shared changes also need sparse and long specimens, a second theme, a long abstract, reference extraction, and a working starter. Preserve unrelated templates and documents.

package/starter/templates/scientific-paper/README.md

@@ -0,0 +1,13 @@
+# Scientific paper
+
+A flexible, single-column manuscript layout using native Forme flow. Defaults are A4 portrait, 72-point side and 58-point top/bottom margins, a 22-point centered title, 11/16.5-point body typography, and 9-point paragraph gaps. The abstract is inset 24 points on each side and uses 10/14.5-point text. The body width is approximately 451 points; the abstract width is approximately 403 points. Page numbers sit centrally below the text.
+
+`ScientificPaper` takes `title`, `theme`, and ordinary OpenDoc blocks as `children`. Optional `authors`, `affiliations`, and `correspondence` form the opening. `abstract` accepts inline content, including Strong, Em, or Cite; `keywords` is an optional string. Both remain breakable, and an abstract's label is part of the same paragraph so it cannot be stranded by itself. Omitted fields leave no reserved panels. For a structured abstract, use inline labels and content or make a local variant with ordinary Paragraph blocks.
+
+`titleStyle` accepts native Forme text styles for adjustments such as a smaller long title or left alignment. `PaperHeading` supplies compact level-2 and level-3 defaults, with an optional `style` override. There is no required section order. Keep a heading with a short lead using a native `View wrap={false}` where needed; do not wrap whole sections in an unbreakable group.
+
+Pass verified `references` and use `Cite` for citations. `citationStyle` accepts the workspace's existing `numeric` (default) or `author-date` formats. These are not full implementations of named journal bibliography styles. References follow the body. Use existing Figure, DataTable, and CrossReference blocks for numbered evidence and native table continuation. Native charts have the workspace's known font-encoding limitation; the established [Media workflow](../../docs/MEDIA.md) supplies chart assets rendered as native images. Size a complete Figure and caption to fit a page.
+
+The caller's theme supplies visual hierarchy, rhythm, and component treatments. The default catalog proof uses Neutral; `Specimen` in `preview.tsx` accepts sparse, typical, and long variants plus a theme for review. Its prose, visual areas, and table values are expressly illustrative. `starter.tsx` creates an ordinary linked document. Preserve stable authored IDs; the specimen's sequence IDs are only for its fixed proof.
+
+This is a starting manuscript design, not a journal submission specification. Adapt it to the actual document and any supplied publisher instructions, following [AGENTS.md](AGENTS.md). No custom typography engine, floating-column logic, or automatic fitting is involved.

package/starter/templates/scientific-paper/index.tsx

@@ -0,0 +1,47 @@
+import type { ReactNode } from 'react';
+import * as F from '@formepdf/react';
+import { TextSlot, Document, Heading, Paragraph, References, Strong, Page } from 'opendoc';
+import { themePage, type DocTheme } from 'opendoc/themes';
+
+export interface ScientificPaperProps {
+  title: string;
+  theme: DocTheme;
+  authors?: string;
+  affiliations?: ReactNode;
+  correspondence?: string;
+  abstract?: ReactNode;
+  keywords?: string;
+  titleStyle?: F.Style;
+  citationStyle?: Parameters<typeof Document>[0]['citationStyle'];
+  references?: Parameters<typeof Document>[0]['references'];
+  children: ReactNode;
+}
+
+/** A manuscript opening and one continuous column, entirely in native Forme flow. */
+export function ScientificPaper({ title, theme, authors, affiliations, correspondence, abstract, keywords, titleStyle, citationStyle, references, children }: ScientificPaperProps) {
+  const layoutTheme: DocTheme = theme.design ? theme : { ...theme, fontSize: 11, lineHeight: 1.5, paragraphGap: 9 };
+  return <Document title={title} author={authors} theme={layoutTheme} references={references} citationStyle={citationStyle}>
+    <Page {...themePage(theme, { top: 58, bottom: 58, left: 72, right: 72 })} style={{ lineBreaking: 'greedy', ...theme.design?.page?.style }}>
+      {(!theme.design || theme.runningFooter) && <F.Fixed position="footer"><F.Text style={{ fontFamily: theme.body, fontSize: 8, color: theme.muted, textAlign: 'center', ...theme.design?.furniture?.text, ...theme.design?.furniture?.footer }}>{theme.design?.furniture?.pageNumber === 'total' ? '{{pageNumber}} / {{totalPages}}' : '{{pageNumber}}'}</F.Text></F.Fixed>}
+      <F.View style={theme.design?.title?.block}>
+        <Heading id="paper-title" level={1} baseStyle={{ fontSize: 22, lineHeight: 1.18, textAlign: 'center', marginBottom: 14 }} style={{ ...theme.design?.title?.heading, ...titleStyle }}><TextSlot slot="title" from="title">{title}</TextSlot></Heading>
+        {authors && <Paragraph id="paper-authors" role="small" baseStyle={{ fontSize: 11, textAlign: 'center', marginBottom: 6 }} style={theme.design?.title?.byline}><TextSlot slot="authors" from="authors">{authors}</TextSlot></Paragraph>}
+        {affiliations && <Paragraph id="paper-affiliations" role="small" baseStyle={{ fontSize: 9.5, textAlign: 'center', color: theme.muted, marginBottom: 6 }} style={theme.design?.title?.byline}><TextSlot slot="affiliations" from="affiliations">{affiliations}</TextSlot></Paragraph>}
+        {correspondence && <Paragraph id="paper-correspondence" role="small" baseStyle={{ fontSize: 8.5, textAlign: 'center', color: theme.muted, marginBottom: 6 }} style={theme.design?.title?.byline}><TextSlot slot="correspondence" from="correspondence">{correspondence}</TextSlot></Paragraph>}
+      </F.View>
+      {(abstract || keywords) && <F.View style={{ marginLeft: 24, marginRight: 24, marginTop: 18, marginBottom: 20 }}>
+        {abstract && <Paragraph id="paper-abstract" role="small" baseStyle={{ fontSize: 10, lineHeight: 1.45, marginBottom: keywords ? 10 : 0 }}><Strong>Abstract. </Strong><TextSlot slot="abstract" from="abstract">{abstract}</TextSlot></Paragraph>}
+        {keywords && <Paragraph id="paper-keywords" role="small" baseStyle={{ fontSize: 9, lineHeight: 1.4, marginBottom: 0 }}><Strong>Keywords: </Strong><TextSlot slot="keywords" from="keywords">{keywords}</TextSlot></Paragraph>}
+      </F.View>}
+      <F.View style={{ marginTop: abstract || keywords ? 0 : 18 }}>
+        {children}
+        <References headingBaseStyle={{ fontSize: 14, marginTop: 20, marginBottom: 8 }} />
+      </F.View>
+    </Page>
+  </Document>;
+}
+
+/** Compact heading defaults; authors may override native styles for their manuscript. */
+export function PaperHeading({ id, level = 2, style, children }: { id: string; level?: 2 | 3; style?: F.Style; children: ReactNode }) {
+  return <Heading id={id} level={level} baseStyle={{ fontSize: level === 2 ? 14 : 11.5, marginTop: 16, marginBottom: 7 }} style={style}><TextSlot slot="children" from="children">{children}</TextSlot></Heading>;
+}

package/starter/templates/scientific-paper/preview.tsx

@@ -0,0 +1,43 @@
+import * as F from '@formepdf/react';
+import { DataTable, Figure, Paragraph } from 'opendoc';
+import { neutral } from '../../themes';
+import { type DocTheme } from 'opendoc/themes';
+import { PaperHeading, ScientificPaper } from './index';
+
+export const meta = { title: 'Scientific paper', description: 'A Neutral manuscript specimen with illustrative placeholders only.', kind: 'research' as const, theme: 'neutral' };
+const paragraph = 'This is placeholder text for the manuscript. It demonstrates the length of a line, the space between paragraphs, and the relationship between headings and continuous prose. No study was conducted and no findings are reported. In an authored paper, the research question, methods, and evidence would determine the organization and the level of detail needed by the reader.';
+
+export function Specimen({ length = 'typical', theme = neutral }: { length?: 'sparse' | 'typical' | 'long'; theme?: DocTheme } = {}) {
+  const sparse = length === 'sparse';
+  return <ScientificPaper title={meta.title} theme={theme}
+    authors={sparse ? undefined : 'Author name · Coauthor name'}
+    affiliations={sparse ? undefined : 'Department and institution · Affiliation placeholder'}
+    correspondence={sparse ? undefined : 'Correspondence details, when needed'}
+    abstract={sparse ? undefined : 'This abstract is a layout specimen. It shows a compact summary set apart from the main reading column. The text describes no real research, data, or conclusions. Its length and structure can be adapted to the paper and any applicable publisher instructions.'}
+    keywords={sparse ? undefined : 'manuscript; formatting; illustrative specimen'}>
+    <F.View wrap={false}>
+      <PaperHeading id="specimen-opening-heading">A manuscript section</PaperHeading>
+      <Paragraph id="specimen-opening-lead">A short opening stays with its heading. Section names and their order belong to the writer.</Paragraph>
+    </F.View>
+    <Paragraph id="specimen-opening">{paragraph}</Paragraph>
+    {!sparse && <>
+      {Array.from({ length: length === 'long' ? 12 : 1 }, (_, index) => <Paragraph key={index} id={`specimen-body-${index + 1}`}>{paragraph}</Paragraph>)}
+      <Figure id="specimen-figure" caption="Illustrative figure position. Captions identify the visual; labels and units belong where they can be read." sourceNote="Placeholder only. No measured data or source is claimed.">
+        <F.View style={{ height: 135, backgroundColor: theme.paper, borderWidth: 0.6, borderColor: theme.line, justifyContent: 'center', alignItems: 'center' }}>
+          <F.Text style={{ fontSize: 10, color: theme.muted }}>Figure area · Illustrative placeholder</F.Text>
+        </F.View>
+      </Figure>
+      <F.View wrap={false}>
+        <PaperHeading id="specimen-subheading" level={3}>A subordinate heading</PaperHeading>
+        <Paragraph id="specimen-detail">The smaller heading marks a change within the passage. This text demonstrates hierarchy without prescribing a research outline.</Paragraph>
+      </F.View>
+      <DataTable id="specimen-table" caption="Synthetic values for layout review" columns={[{ label: 'Sample', width: 1.5 }, { label: 'Value (a.u.)', width: 1, align: 'right' }, { label: 'Status', width: 1.4 }]}
+        rows={Array.from({ length: length === 'long' ? 25 : 4 }, (_, index) => [`Example ${index + 1}`, 10 + index, 'Illustrative only'])}
+        sourceNote="All values are synthetic; a.u. means arbitrary units. No research finding is claimed." />
+      <Paragraph id="specimen-closing">This closing passage follows the table in normal flow. The manuscript can continue with any sections the material requires.</Paragraph>
+      <PaperHeading id="specimen-reference-heading">References</PaperHeading>
+      <Paragraph id="specimen-reference" style={{ fontSize: 9.5, color: theme.muted }}>Reference placement specimen. Real references appear here only when cited; no source is being claimed.</Paragraph>
+    </>}
+  </ScientificPaper>;
+}
+export default Specimen;

package/starter/templates/scientific-paper/starter.tsx

@@ -0,0 +1,15 @@
+import { ScientificPaper } from '../../templates/scientific-paper';
+import { Paragraph } from 'opendoc';
+// @ts-ignore The selected local theme module is inserted when this starter becomes a document.
+import { theme } from "__OPENDOC_THEME_MODULE__";
+
+const title = "__OPENDOC_TITLE__";
+const themeId = "__OPENDOC_THEME__";
+export const meta = { title, description: 'A scientific manuscript, ready for your material.', kind: 'research' as const, theme: themeId };
+export const provenance = { template: 'templates/scientific-paper/index.tsx' };
+
+export default function Paper() {
+  return <ScientificPaper title={title} theme={theme} authors="Author name" abstract="Replace this placeholder with a summary of your manuscript.">
+    <Paragraph id="paper-opening">Your manuscript begins here. Replace this placeholder with your own material and choose the sections that fit the research and intended reader.</Paragraph>
+  </ScientificPaper>;
+}

package/starter/templates/scientific-paper/template.json

@@ -0,0 +1,11 @@
+{
+  "name": "Scientific paper",
+  "description": "A compact manuscript opening, a distinct abstract, and a continuous reading column with clear figures, tables, and references. For research manuscripts, preprints, and scholarly notes.",
+  "format": "A4 · Single-column manuscript",
+  "structure": [
+    "A centered title, author line, and optional affiliations share the first page with the manuscript.",
+    "An optional inset abstract and keywords separate the summary from the main text without a cover page.",
+    "Compact heading levels organize a continuous single column. Figures and tables sit in the author's chosen reading order.",
+    "Cited references follow the body and page numbers sit centrally below. The layout is adaptable and does not prescribe a journal style or section outline."
+  ]
+}

package/starter/themes/Specimen.tsx

@@ -0,0 +1,54 @@
+import {
+  Callout, Cite, CrossReference, DataTable, Document, Em, Figure, Heading, List,
+  PageBreak, Pages, Paragraph, References, Section, Strong, Text, TitleBlock, View,
+  type DocTheme,
+} from 'opendoc';
+
+/** One shared proof: themes and authored documents use the same PDF primitives. */
+export function ThemeSpecimen({ theme }: { theme: DocTheme }) {
+  return <Document title={`${theme.name} — A page with purpose`} theme={theme}
+    references={{ design: { title: `${theme.name} design guide — themes/${theme.id}/design.md`, author: 'OpenDoc' } }}>
+    <Pages title={`${theme.name} / Design specimen`} footer={`${theme.name} / Illustrative specimen`}>
+      <TitleBlock id="specimen-opening" eyebrow="A page with purpose" title={theme.name}
+        subtitle={theme.description} byline="Typography, composition, and the details that hold a document together." />
+      <Section id="specimen-reading" title="Make room for the thought"
+        lead="A page begins with a relationship: a heading invites us in, a paragraph gives us a place to settle, and the space around both sets the pace.">
+        <Paragraph id="specimen-prose">Good document design makes different kinds of information easy to recognize. A title can be confident without crowding the opening. Body text can be comfortable without losing momentum. A <Strong>short phrase</Strong> can carry the central thought; <Em>an italic aside</Em> can change the voice. Here, the same words appear in every theme so the differences in hierarchy, rhythm, and emphasis are visible.</Paragraph>
+      </Section>
+      <Heading id="specimen-details" level={3}>The small decisions matter</Heading>
+      <List id="specimen-principles" items={[
+        { id: 'alignment', children: 'Shared edges connect the different elements of a page.' },
+        { id: 'rhythm', children: 'A consistent rhythm holds related passages together.' },
+        { id: 'contrast', children: 'Contrast gives the reader a clear place to begin.' },
+      ]} />
+      <Callout id="specimen-aside" title="One useful interruption">
+        An aside should earn its place. Use this treatment for a decision, a qualification, or a detail the reader needs to notice before continuing.
+      </Callout>
+      <PageBreak />
+      <Section id="specimen-evidence" title="Give evidence a clear place"
+        lead="A visual and a table should belong to the same publication as the prose. Their labels, rules, captions, and spacing carry the theme at a smaller scale." />
+      <Figure id="specimen-figure" caption="An illustrative comparison, with each value placed beside its mark."
+        sourceNote="Synthetic values in arbitrary units. No measurements are claimed.">
+        <View style={{ paddingTop: 8, paddingBottom: 8 }}>
+          {[{ label: 'First', value: 18 }, { label: 'Second', value: 31 }, { label: 'Third', value: 46 }].map((item, index) =>
+            <View key={item.label} style={{ flexDirection: 'row', alignItems: 'center', gap: 12, marginBottom: 12 }}>
+              <Text style={{ width: 48, fontFamily: theme.body, fontSize: 9, color: theme.muted }}>{item.label}</Text>
+              <View style={{ flex: 1, height: 18, justifyContent: 'center' }}>
+                <View style={{ width: `${item.value * 2}%`, height: 18, backgroundColor: index === 2 ? theme.accent : theme.line }} />
+              </View>
+              <Text style={{ width: 25, fontFamily: theme.body, fontSize: 9, color: theme.ink, textAlign: 'right' }}>{item.value}</Text>
+            </View>)}
+        </View>
+      </Figure>
+      <DataTable id="specimen-table" caption="The same illustrative values, available as selectable text."
+        columns={[{ label: 'Example', width: 1.1 }, { label: 'Treatment', width: 2.2 }, { label: 'Value', width: 0.7 }]}
+        rows={[
+          ['First', 'Supporting comparison', 18],
+          ['Second', 'Supporting comparison', 31],
+          ['Third', 'Single point of emphasis', 46],
+        ]} sourceNote="Synthetic values, in arbitrary units." />
+      <Paragraph id="specimen-closing"><CrossReference target="specimen-figure" /> and <CrossReference target="specimen-table" /> show the same comparison. The local design guide describes this theme’s composition and usage. <Cite source="design" /></Paragraph>
+      <References title="Design reference" />
+    </Pages>
+  </Document>;
+}

package/starter/themes/civic-spectrum/components.tsx

@@ -0,0 +1,92 @@
+import type { ReactNode } from 'react';
+import * as F from '@formepdf/react';
+import { Block, Heading, Page, Paragraph } from 'opendoc';
+import { colors, metrics, theme } from './index';
+
+const spectrum = [colors.blue, colors.sky, colors.leaf, colors.sun, colors.flame, colors.violet];
+
+/** The unequal lengths are an identity device, never a quantitative chart. */
+export function SpectrumRail({ height = metrics.railHeight }: { height?: number }) {
+  return <F.View style={{ flexDirection: 'row', height, width: '100%' }}>
+    {spectrum.map((color, index) => <F.View key={color} style={{ flex: metrics.railWeights[index], height, backgroundColor: color }} />)}
+  </F.View>;
+}
+
+/** Flowing publication pages: the asymmetric compositions inside remain content-driven. */
+export function CivicPages({ children, title, section = 'CS', footer = 'Civic Spectrum', rail = false }: {
+  children: ReactNode; title: string; section?: string; footer?: string; rail?: boolean;
+}) {
+  return <Page size="A4" margin={{ top: metrics.margin, right: metrics.margin, bottom: metrics.bottomMargin, left: metrics.margin }} style={{ backgroundColor: colors.stock }}>
+    <F.Fixed position="header"><F.View style={{ flexDirection: 'row', justifyContent: 'space-between', paddingBottom: 16 }}>
+      <F.Text style={{ fontSize: 8, color: colors.muted }}>{title}</F.Text>
+      <F.Text style={{ fontSize: 8, fontWeight: 600, color: colors.ink }}>{section}</F.Text>
+    </F.View></F.Fixed>
+    <F.Fixed position="footer"><F.View style={{ borderTopWidth: 0.75, borderColor: colors.rule, paddingTop: 12, flexDirection: 'row', justifyContent: 'space-between' }}>
+      <F.Text style={{ fontSize: 8, fontWeight: 600, color: colors.ink }}>{footer}</F.Text>
+      <F.Text style={{ fontSize: 8, fontWeight: 600, color: colors.ink }}>{'{{pageNumber}}'}</F.Text>
+    </F.View></F.Fixed>
+    {rail && <F.View style={{ marginBottom: 24 }}><SpectrumRail /></F.View>}
+    {children}
+  </Page>;
+}
+
+export function SquareSignal({ id, label, color = colors.blue }: { id: string; label: string; color?: string }) {
+  return <Block id={id} style={{ flexDirection: 'row', alignItems: 'center', gap: 8 }}>
+    <F.View style={{ width: metrics.signalSize, height: metrics.signalSize, backgroundColor: color, flexShrink: 0 }} />
+    <F.Text style={{ fontSize: 8, fontWeight: 600, letterSpacing: 1, color: colors.ink }}>{label.toUpperCase()}</F.Text>
+  </Block>;
+}
+
+export function CivicBadge({ id, value, label, color = colors.blue, filled = false }: {
+  id: string; value: string; label: string; color?: string; filled?: boolean;
+}) {
+  return <Block id={id}>
+    <F.View style={{ width: metrics.badgeSize, height: metrics.badgeSize, borderWidth: 0.75, borderColor: color, backgroundColor: filled ? color : colors.stock, justifyContent: 'center', alignItems: 'center' }}>
+      <F.Text style={{ fontSize: value.length > 2 ? 44 : 60, lineHeight: 1, fontWeight: 600, letterSpacing: -1.5, color: filled ? colors.ink : color }}>{value}</F.Text>
+    </F.View>
+    <F.Text style={{ width: metrics.badgeSize, fontSize: 8, lineHeight: 1.35, color: colors.muted, marginTop: 12 }}>{label}</F.Text>
+  </Block>;
+}
+
+export function CivicSplit({ id, main, aside }: { id: string; main: ReactNode; aside: ReactNode }) {
+  return <Block id={id} style={{ flexDirection: 'row', gap: metrics.gutter, alignItems: 'flex-start' }}>
+    <F.View style={{ width: metrics.mainWidth }}>{main}</F.View>
+    <F.View style={{ flex: 1, minWidth: 0 }}>{aside}</F.View>
+  </Block>;
+}
+
+export function CivicOpening({ id, kicker, title, subtitle, color = colors.blue }: {
+  id: string; kicker: string; title: string; subtitle?: string; color?: string;
+}) {
+  return <F.View wrap={false} style={{ marginBottom: 24 }}>
+    <SquareSignal id={`${id}-signal`} label={kicker} color={color} />
+    <Heading id={`${id}-title`} level={1} style={{ marginTop: 20 }}>{title}</Heading>
+    {subtitle && <Paragraph id={`${id}-subtitle`} role="lead" style={{ marginBottom: 0 }}>{subtitle}</Paragraph>}
+  </F.View>;
+}
+
+/** A category module. Keep each color's meaning consistent throughout a document. */
+export function SignalBlock({ id, code, title, children, color = colors.blue }: {
+  id: string; code: string; title: string; children: ReactNode; color?: string;
+}) {
+  return <Block id={id} style={{ borderTopWidth: 4, borderColor: color, paddingTop: 12, marginBottom: 24 }}>
+    <F.View style={{ flexDirection: 'row', justifyContent: 'space-between', gap: 8, marginBottom: 8 }}>
+      <F.Text style={{ fontSize: 14, lineHeight: 1.1, fontWeight: 600, color: colors.ink }}>{title}</F.Text>
+      <F.Text style={{ fontSize: 8, color: colors.muted }}>{code}</F.Text>
+    </F.View>
+    <F.Text style={{ fontSize: 10, lineHeight: 1.4, color: colors.muted }}>{children}</F.Text>
+  </Block>;
+}
+
+/** Palette is shown as a real legend, with accessible text labels and exact values. */
+export function SpectrumLegend({ id }: { id: string }) {
+  const entries = theme.palette!.slice(0, 6);
+  return <Block id={id}>
+    {[entries.slice(0, 3), entries.slice(3)].map((row, index) => <F.View key={index} style={{ flexDirection: 'row', gap: 12, marginBottom: 16 }}>
+      {row.map(entry => <F.View key={entry.name} style={{ flex: 1, flexDirection: 'row', gap: 8 }}>
+        <F.View style={{ width: 28, height: 28, flexShrink: 0, backgroundColor: entry.value }} />
+        <F.View style={{ flex: 1 }}><F.Text style={{ fontSize: 9, fontWeight: 600 }}>{entry.name}</F.Text><F.Text style={{ fontFamily: 'OpenDoc Mono', fontSize: 8, color: colors.muted, marginTop: 3 }}>{entry.value}</F.Text></F.View>
+      </F.View>)}
+    </F.View>)}
+  </Block>;
+}

package/starter/themes/civic-spectrum/design.md

@@ -0,0 +1,70 @@
+# Civic Spectrum
+
+Warm civic modernism: lucid public information, compact grotesk type, square signals, and generous asymmetric space. Its signature is the **unequal six-color rail**, not a collection of interchangeable accent colors. Use it for community and cultural reports, public-information pages, and editorial explainers.
+
+## Palette and meaning
+
+| Role | Hex | Use |
+| --- | --- | --- |
+| Signal blue | `#2F7EA5` | Orientation, primary emphasis, arrival |
+| Sky | `#7ABED0` | Supporting information and shared activity |
+| Leaf | `#5F9D7A` | Participation, progress, positive movement |
+| Sun | `#E3C84F` | Attention and selected evidence; use dark text |
+| Flame | `#E27D47` | Action, urgent emphasis, a next step |
+| Violet | `#7D6FA6` | Context and reflection |
+| Stock | `#FFFFFF` | White page background |
+| Ink | `#17232B` | Primary text and optional inverse surface |
+| Muted | `#68747A` | Secondary text and annotations |
+| Rule | `#C9CEC7` | Quiet boundaries and alignment marks |
+| Inverse text | `#F8F5EC` | Text on the ink surface |
+| Inverse notes | `#B9C2C3` | Secondary text on dark |
+| Inverse rule | `#516068` | Boundaries on dark |
+
+Use one dominant signal in a passage. The entire spectrum belongs on an identity rail or in an explicit palette legend. On an applied page, two or three colors are acceptable only when they identify distinct categories. Preserve those assignments throughout a document. Sun is a good note surface; it is not a universal highlight pen. Use Ink text on the light signal fields. White text is reserved for sufficiently dark fields such as Signal blue or Ink.
+
+## Page geometry and shapes
+
+The print grid is A4 portrait, **48 pt top/side margins and 56 pt bottom margin**. The approximately 499 pt field has six columns separated by **12 pt gutters**. `CivicSplit` assigns **328 pt** to the main reading field and the remaining approximately 159 pt to supporting material, with a 12 pt gap. This creates a four-column reading field and a two-column supporting field.
+
+Work from a **4 pt baseline** and prefer 8, 12, 16, 24, and 32 pt spacing. The unequal rail is **12 pt high** with the invariant proportion **2 : 1 : 3 : 1.5 : 2 : 1**, in blue, sky, leaf, sun, flame, violet order. Its lengths are an identity device, never quantitative data. An 8 pt rail is available for a secondary signature.
+
+Wayfinding markers are **8 × 8 pt squares**. Badges are **132 × 132 pt squares**, outlined with a 0.75 pt rule or filled with a meaningful color. Category modules start with a **4 pt top rule** and 12 pt inset. Corners are square. Do not introduce shadows, gradients, rounded cards, glass surfaces, or ornamental circles. Large empty areas are deliberate: keep one side of a reading spread quieter rather than filling every cell.
+
+## Typography
+
+The local print family is **OpenDoc Sans**, the bundled Source Sans 3 derivative. It substitutes for the slide theme's Archivo. Use the real 600 face for emphasis and display; body is 400. The substitution preserves a clear grotesk voice but does not claim identical Archivo letterforms. OpenDoc Mono is used only for exact hexadecimal labels in the specimen.
+
+| Role | Size / line height | Notes |
+| --- | --- | --- |
+| Cover display | 52 pt / 1.02 | Tight, confident; identity specimen uses 54 pt / 0.98 |
+| Main title | 42 pt / 1.04 | Tracking −0.8 pt; flush left |
+| Section | 23 pt / 1.10 | Tracking −0.35 pt; 24 pt before, 12 after |
+| Subheading | 14 pt / 1.20 | 20 pt before, 8 after |
+| Lead | 16 pt / 1.40 | Muted, short measure |
+| Body | 11 pt / 1.50 | 12 pt paragraph gap |
+| Caption | 9 pt / 1.40 | Keep close to its figure |
+| Label | 8 pt | Uppercase only for short wayfinding labels |
+
+Sentence case is the default. Do not make body passages uppercase. Long text flows; do not shrink the type to preserve a fixed page count.
+
+## Reusable components
+
+Import `theme` from `themes/civic-spectrum` and the components from its `components.tsx`. Use them inside an OpenDoc `Document` receiving that theme.
+
+- `CivicPages({title, section?, footer?, rail?, children})` supplies white stock, real repeating furniture, and optional opening rail. Its content flows naturally across pages.
+- `CivicOpening({id, kicker, title, subtitle?, color?})` couples the square signal to the title and lead.
+- `CivicSplit({id, main, aside})` establishes the four/two-column relationship. Use independent supporting material in the aside; do not rely on it for sequential prose continuation.
+- `SquareSignal({id, label, color?})`, `CivicBadge({id, value, label, color?, filled?})`, and `SignalBlock({id, code, title, color?, children})` are reusable wayfinding elements.
+- `SpectrumRail({height?})` carries the identity. `SpectrumLegend({id})` displays exact palette values when explaining the system.
+
+Pass unique, stable IDs. Native `Heading`, `Paragraph`, `DataTable`, `Figure`, and `Callout` also consume this theme's rules; do not recreate their styling in each document.
+
+## Evidence, imagery, and application
+
+Use direct labels, explicit units, and rectangular partitions when the data supports them. The specimen's 120 m² room is synthetic; its areas and percentages are selectable in the accompanying table. Native tables use an Ink header, inverse labels, 10 pt cell padding, and 0.5 pt horizontal rules. Captions describe the exhibit, and source notes identify its basis. Real evidence keeps its meaning even when it uses additional colors.
+
+Images may fill the reading field or a deliberate wider band; preserve aspect ratio and use a nearby caption. A photograph can carry a public story, but it must not be filler. Logos retain supplied proportions and clear space. Do not invent a transit map, civic crest, or institutional endorsement.
+
+## Implementation and review
+
+The system combines a six-color rail, square signals, asymmetric composition, and the Orient / Explain / Move structure. It uses bundled OpenDoc fonts and native page primitives. `index.ts` and reusable components are executable; keep these concrete specifications synchronized when changing them. Review every specimen page, narrow-column wraps, exact palette text, and table/figure labels in the exported PDF.