@ryanyahya/opendoc 0.4.0

package/starter/themes/mckinsey-consulting/index.ts

@@ -0,0 +1,60 @@
+import type { DocTheme } from 'opendoc/themes';
+
+export const colors = {
+  white: '#FFFFFF', ink: '#051C2C', focus: '#2251FF', muted: '#4D4D4D', rule: '#D0D0D0',
+  soft: '#F0F0F0', pale: '#AAE6F0', cyan: '#00A9F4', blue1: '#034B6F', blue2: '#027AB1',
+  blue3: '#39BDF3', blue4: '#71D2F1', positive: '#3C96B4', caution: '#FAA082', negative: '#E5546C',
+};
+
+export const theme: DocTheme = {
+  id: 'mckinsey-consulting', name: 'McKinsey Consulting',
+  description: 'An independent consulting system: answer-first headlines, rigorous exhibits, deep blue structure and electric blue focus.',
+  body: 'OpenDoc Sans', heading: 'OpenDoc Sans', ink: colors.ink, muted: colors.muted,
+  accent: colors.focus, paper: colors.white, line: colors.rule,
+  fontSize: 10.5, lineHeight: 1.42, margin: 48, paragraphGap: 10,
+  pageSize: 'A4', runningHeader: true, runningFooter: true, footerLabel: 'Analysis / Working paper',
+  useFor: ['Executive decisions', 'Analytical reports', 'Business cases'],
+  principles: ['State the answer before the evidence.', 'Make the comparison explicit.', 'Let one datum carry the color.'],
+  palette: [
+    { name: 'Deep blue', value: colors.ink, role: 'Structure, text and inverse covers' },
+    { name: 'Electric blue', value: colors.focus, role: 'One focal datum or conclusion' },
+    { name: 'White', value: colors.white, role: 'Exhibit canvas and inverse text' },
+    { name: 'Gray', value: colors.muted, role: 'Annotations and source notes' },
+    { name: 'Rule', value: colors.rule, role: 'Hairlines and chart axes' },
+    { name: 'Soft', value: colors.soft, role: 'Context bands' },
+    { name: 'Pale blue', value: colors.pale, role: 'Implication fields and selected rows' },
+    { name: 'Cyan', value: colors.cyan, role: 'Secondary emphasis' },
+    { name: 'Series 1', value: colors.blue1, role: 'Ordered dark series' },
+    { name: 'Series 2', value: colors.blue2, role: 'Ordered mid-dark series' },
+    { name: 'Series 3', value: colors.blue3, role: 'Ordered mid-light series' },
+    { name: 'Series 4', value: colors.blue4, role: 'Ordered light series' },
+    { name: 'Positive', value: colors.positive, role: 'Favorable movement' },
+    { name: 'Caution', value: colors.caution, role: 'Watch items' },
+    { name: 'Negative', value: colors.negative, role: 'Adverse exceptions' },
+  ],
+  geometry: [
+    'Square rectangles; no rounded analytical containers.',
+    'A4, 48 pt margins, 12-column construction with 12 pt gutters.',
+    'A 4 pt spacing unit; 0.5 pt rules and directly labeled bars.',
+    'Claim → metric frame → evidence → implication → source.',
+  ],
+  design: {
+    typography: {
+      h1: { fontSize: 31, lineHeight: 1.1, letterSpacing: -0.6, marginBottom: 16 },
+      h2: { fontSize: 19, lineHeight: 1.15, marginTop: 24, marginBottom: 10 },
+      h3: { fontSize: 12, marginTop: 16, marginBottom: 8 },
+      label: { fontSize: 8, fontWeight: 600, letterSpacing: 1.1 },
+      lead: { fontSize: 12, lineHeight: 1.4, color: colors.muted },
+      small: { fontSize: 8, lineHeight: 1.35 },
+      caption: { fontSize: 8.5, lineHeight: 1.35 },
+    },
+    page: { margin: { top: 48, bottom: 52, left: 48, right: 48 }, style: { backgroundColor: colors.white } },
+    title: { block: { borderBottomWidth: 0, paddingBottom: 0, marginBottom: 24 }, eyebrow: { marginBottom: 12 } },
+    cover: { page: { backgroundColor: colors.ink }, block: { borderTopWidth: 0, marginTop: 92 }, title: { fontSize: 58, lineHeight: 1.04, color: colors.white }, subtitle: { color: colors.pale }, eyebrow: { color: colors.pale }, byline: { color: colors.pale }, footer: { color: colors.pale } },
+    furniture: { header: { letterSpacing: 0.7, paddingBottom: 16 }, text: { fontSize: 7.5 }, footer: { borderTopWidth: 0.5, paddingTop: 8 }, pageNumber: 'total' },
+    table: { header: { backgroundColor: colors.ink }, headerText: { color: colors.white, fontSize: 8.5, fontWeight: 600 }, cell: { padding: 8 }, text: { fontSize: 9 }, alternate: colors.soft },
+    figure: { block: { marginTop: 12, marginBottom: 20 } },
+    callout: { block: { backgroundColor: colors.pale, borderLeftWidth: 0, padding: 16, marginBottom: 16 }, title: { color: colors.ink, fontWeight: 600, fontSize: 10 }, text: { fontSize: 10.5, color: colors.ink } },
+    list: { gap: 8, item: { marginBottom: 8 } },
+  },
+};

package/starter/themes/mckinsey-consulting/preview.tsx

@@ -0,0 +1,53 @@
+import { Document, Pages, Heading, Paragraph, DataTable, Text, View } from 'opendoc';
+import { theme, colors as c } from './index';
+import { ConsultingCover, ExhibitTitle, RankedBars, Implication, SourceNote } from './components';
+
+export const meta = { title: 'McKinsey Consulting — Make the answer visible', description: theme.description, theme: theme.id };
+
+export default function Preview() {
+  return <Document title={meta.title} theme={theme}>
+    <ConsultingCover id="consulting-identity" title={'Make the\nanswer visible.'} subtitle="A disciplined system for conclusions, comparisons and decisions." />
+    <Pages title="McKinsey Consulting / The system" footer="Design grammar / Independent adaptation">
+      <ExhibitTitle id="consulting-system" number="01" topic="Visual grammar" metric="A4 portrait / all dimensions in points / embedded local typography">Structure stays quiet. The answer carries the color.</ExhibitTitle>
+      <View style={{ flexDirection: 'row', gap: 20 }}>
+        <View style={{ width: 198 }}>
+          <Heading id="consulting-palette-title" level={3} style={{ marginTop: 0 }}>A semantic palette</Heading>
+          {theme.palette!.map(color => <View key={color.name} style={{ flexDirection: 'row', gap: 8, alignItems: 'center', marginBottom: 6 }}>
+            <View style={{ width: 22, height: 22, backgroundColor: color.value, borderWidth: color.value === c.white ? 0.5 : 0, borderColor: c.rule }} />
+            <View><Text style={{ fontSize: 8.5, fontWeight: 600 }}>{color.name}</Text><Text style={{ fontSize: 7.5, fontFamily: 'OpenDoc Mono', color: c.muted }}>{color.value}</Text></View>
+          </View>)}
+        </View>
+        <View style={{ flex: 1 }}>
+          <Text style={{ fontSize: 48, fontWeight: 600, lineHeight: 1.05, letterSpacing: -1, marginBottom: 8 }}>Aa 82%</Text>
+          <Paragraph id="consulting-type" style={{ fontSize: 9 }}>OpenDoc Sans is the embedded substitute. The original McKinsey Sans is proprietary; no brand font or logo is redistributed.</Paragraph>
+          <DataTable id="consulting-type-scale" columns={[{ label: 'Role', width: 1.7 }, { label: 'pt / leading', width: 1 }]} rows={[
+            ['Cover', '62 / 1.01'], ['Conclusion', '31 / 1.10'], ['Section', '19 / 1.15'], ['Body', '10.5 / 1.42'], ['Source', '8 / 1.35'],
+          ]} />
+          <Heading id="consulting-geometry-title" level={3}>Geometry is analytical</Heading>
+          <View style={{ flexDirection: 'row', gap: 8, alignItems: 'flex-end', marginBottom: 12 }}>
+            <View style={{ width: 40, height: 40, backgroundColor: c.ink }} /><View style={{ width: 64, height: 24, backgroundColor: c.focus }} /><View style={{ width: 84, height: 8, backgroundColor: c.pale }} />
+          </View>
+          <Paragraph id="consulting-geometry" style={{ fontSize: 9 }}>Square corners. A 4 pt spacing unit. A 12-column construction with 12 pt gutters inside 48 pt page margins. Fine 0.5 pt rules separate comparisons.</Paragraph>
+          <Paragraph id="consulting-composition" style={{ fontSize: 9 }}>Give the evidence most of the page. Use one assertive title, define the metric, directly label the marks, then state the implication and source.</Paragraph>
+        </View>
+      </View>
+      <SourceNote id="consulting-basis">An independent OpenDoc interpretation of analytical publication conventions, without affiliation. Detailed palette roles and component guidance are in this theme’s design guide.</SourceNote>
+    </Pages>
+    <Pages title="McKinsey Consulting / Applied exhibit" footer="Illustrative analysis / No empirical claim">
+      <ExhibitTitle id="consulting-applied" number="02" topic="Value pool" metric="Share of identified opportunity by lever, % of total / illustrative scenario">Three levers account for 82% of the opportunity.</ExhibitTitle>
+      <RankedBars id="consulting-bars" max={40} rows={[
+        { label: 'Simplify intake', detail: 'Reduce repeated entry', value: 32 },
+        { label: 'Balance capacity', detail: 'Match effort to demand', value: 28 },
+        { label: 'Shorten handoffs', detail: 'Clarify the next owner', value: 22 },
+        { label: 'Improve routing', detail: 'Reduce avoidable loops', value: 11 },
+        { label: 'Other changes', detail: 'Remaining opportunity', value: 7 },
+      ]} />
+      <View wrap={false} style={{ flexDirection: 'row', gap: 16, alignItems: 'center', marginTop: 4, marginBottom: 12 }}>
+        <Text style={{ width: 124, fontSize: 48, fontWeight: 600, color: c.focus, lineHeight: 1 }}>82%</Text>
+        <Text style={{ flex: 1, fontSize: 12, lineHeight: 1.35 }}>The first three levers contain most of the modeled value. Start there, then test whether the assumptions hold.</Text>
+      </View>
+      <Implication id="consulting-next">Prioritize validation of the three largest levers before funding a wider transformation. An attractive estimate becomes a decision only after its assumptions survive scrutiny.</Implication>
+      <SourceNote id="consulting-source">Source: synthetic example created to demonstrate this theme. Values total 100%; the first three sum to 82%. Bars share a zero baseline and a 40% maximum. These figures describe no organization.</SourceNote>
+    </Pages>
+  </Document>;
+}

package/starter/themes/neutral/design.md

@@ -0,0 +1,35 @@
+# Neutral
+
+Neutral is OpenDoc’s plain proofing system: dark type, white paper, and quiet gray structure. It is useful for working documents, correspondence, and evaluating a template’s proportions before choosing a more expressive theme. Its character comes from clarity and restraint. It should look finished enough to share, with no brand identity imposed on the material.
+
+## Composition and rhythm
+
+Use a dependable left edge and a comfortable reading column. The opening gives the title priority, followed by a short subtitle or byline when useful. Body sections retain a visible hierarchy without turning each heading into an event. Keep the document’s main reading path obvious; a second column is appropriate only when the chosen template or content needs it.
+
+Maintain regular paragraph spacing and enough separation before a new section. Use headings to mark changes in thought and lists for genuinely parallel material. A heading belongs with its opening passage. Let longer prose and tables flow naturally instead of shrinking them to preserve a page count.
+
+## Type and emphasis
+
+The sans-serif family carries both display and reading text. Weight and scale establish hierarchy; grayscale distinguishes secondary notes. Use bold for a short emphasis and italic for a change of voice. Keep labels readable and avoid using uppercase for ordinary sentences. The executable definition in `index.ts` owns all sizes, spacing, and style values. The default A4 page uses 54 pt margins, 11 pt body type, 1.5 leading, and 12 pt paragraph gaps. Standard headings are 30, 21, and 14 pt with 1.2 leading and weight 600; title blocks start at 32 pt. Captions are 9 pt and small notes 8.5 pt. A template may supply different starting proportions; document styles can adapt them.
+
+## Palette
+
+Ink `#242424` carries main text; muted `#666666` carries annotations; accent `#424242` carries labels and table headers; surface `#ffffff` keeps panels and page fields white; rule `#d6d6d6` defines quiet boundaries. Use weights 400 and 600 from the bundled OpenDoc Sans family. OpenDoc Mono remains the code family.
+
+## Supporting material
+
+Tables should remain easy to scan, with consistent column alignment and numbers aligned for comparison. Captions state what is shown; source notes remain close enough to read as part of the exhibit. Grayscale row treatments and rules organize information without making a dense cage.
+
+Charts use direct labels and a clear comparison basis. Use darker marks for a focal value and lighter marks for context. Distinguish multiple series through labels or shape when color adds no necessary information. Preserve evidence-critical colors in supplied media; neutral page furniture does not require recoloring a real chart.
+
+Images follow the reading column or the template’s deliberate wider field. Keep the original aspect ratio, a useful crop, and a nearby caption. Callouts provide one restrained interruption, not a container around every paragraph.
+
+## Branding and density
+
+Neutral has no built-in logo, decorative motif, or institutional voice. Use the actual document’s author, title, and footer information. Add a supplied mark only when required by the brief and leave enough space around it.
+
+The system should handle both a short note and a long report. For dense content, simplify the presentation or use the appropriate template rather than reducing all type. Avoid ornamental icons, shadows, decorative rules, invented brand marks, and arbitrary accent colors.
+
+## Basis and review
+
+This is an original OpenDoc proofing theme, not an extracted external brand. `preview.tsx` uses the shared specimen and the same executable theme as authored documents. Review line lengths, restrained contrast, table alignment, and running matter in the exported PDF. The specimen’s comparison values are illustrative only.

package/starter/themes/neutral/index.ts

@@ -0,0 +1,21 @@
+import type { DocTheme } from 'opendoc/themes';
+
+/** The plain proofing system shared by the template catalog. */
+export const neutral: DocTheme = {
+  id: 'neutral', name: 'Neutral', description: 'A plain, adaptable proofing system with black type, gray details, and an open white page.',
+  body: 'OpenDoc Sans', heading: 'OpenDoc Sans', ink: '#242424', muted: '#666666',
+  accent: '#424242', paper: '#ffffff', line: '#d6d6d6',
+  fontSize: 11, lineHeight: 1.5, margin: 54, paragraphGap: 12,
+  pageSize: 'A4', runningHeader: false, runningFooter: true, footerLabel: '',
+  useFor: ['Layout proofs', 'Everyday documents', 'A starting point for a custom system'],
+  principles: ['Let content and structure lead.', 'Keep the page quiet.', 'Make every level easy to recognize.'],
+  palette: [
+    { name: 'Ink', value: '#242424', role: 'Main text and headings' },
+    { name: 'Muted', value: '#666666', role: 'Secondary text and annotations' },
+    { name: 'Accent', value: '#424242', role: 'Labels, table headers, and selected emphasis' },
+    { name: 'Surface', value: '#ffffff', role: 'Covers, callouts, code panels, and alternate table rows' },
+    { name: 'Rule', value: '#d6d6d6', role: 'Quiet structure and table boundaries' },
+  ],
+  geometry: ['A4 portrait; 54 pt default margins.', '11 pt body, 1.5 line height, 12 pt paragraph spacing.', 'Square corners, a clear left edge, and naturally flowing pages.'],
+};
+export const theme = neutral;

package/starter/themes/neutral/preview.tsx

@@ -0,0 +1,4 @@
+import { ThemeSpecimen } from '../Specimen';
+import { theme } from './index';
+export const meta = { title: `${theme.name} design specimen`, description: theme.description, theme: theme.id };
+export default function Preview() { return <ThemeSpecimen theme={theme} />; }

package/starter/themes/opendoc-neutral/components.tsx

@@ -0,0 +1,77 @@
+import type { ReactNode } from 'react';
+import { Fixed, View, Text, type Style } from '@formepdf/react';
+import { Block, Heading, Page, Paragraph, TextSlot, documentFont } from 'opendoc';
+import { colors, metrics } from './index';
+
+export type Surface = 'paper' | 'white' | 'dark';
+export const surfaceColors = (surface: Surface) => surface === 'dark'
+  ? { background: colors.night, ink: colors.inverse, muted: colors.inverseMuted, rule: colors.inverseRule }
+  : { background: surface === 'white' ? colors.white : colors.paper, ink: colors.ink, muted: colors.muted, rule: colors.rule };
+
+/** A flowing surface; running furniture repeats if the content needs another page. */
+export function NeutralPages({ title, label = 'OpenDoc Neutral', surface = 'paper', children, header = true }: {
+  title: string; label?: string; surface?: Surface; children: ReactNode; header?: boolean;
+}) {
+  const c = surfaceColors(surface);
+  return <Page size="A4" margin={{ top: metrics.margin, right: metrics.margin, bottom: metrics.bottom, left: metrics.margin }} style={{ backgroundColor: c.background, color: c.ink }}>
+    {header && <Fixed position="header"><View style={{ flexDirection: 'row', justifyContent: 'space-between', paddingBottom: 18 }}>
+      <Text style={{ fontFamily: 'OpenDoc Mono', fontSize: 7, color: c.muted }}>{label}</Text>
+      <Text style={{ fontFamily: 'OpenDoc Mono', fontSize: 7, color: c.muted }}>{title}</Text>
+    </View></Fixed>}
+    <Fixed position="footer"><View style={{ flexDirection: 'row', justifyContent: 'space-between', borderTopWidth: metrics.rule, borderColor: c.rule, paddingTop: 10 }}>
+      <Text style={{ fontFamily: 'OpenDoc Mono', fontSize: 7, color: c.muted }}>{label}</Text>
+      <Text style={{ fontFamily: 'OpenDoc Mono', fontSize: 7, color: c.muted }}>{'{{pageNumber}}'}</Text>
+    </View></Fixed>
+    {children}
+  </Page>;
+}
+
+export function NeutralOpening({ id, eyebrow, title, subtitle, surface = 'paper', display = false }: {
+  id: string; eyebrow: string; title: string; subtitle?: string; surface?: Surface; display?: boolean;
+}) {
+  const c = surfaceColors(surface);
+  return <Block id={id} style={{ marginBottom: 24 }}>
+    <Paragraph id={`${id}-eyebrow`} role="label" style={{ color: surface === 'dark' ? colors.inverseMuted : colors.blue, marginBottom: 18 }}><TextSlot slot="eyebrow" from="eyebrow">{eyebrow}</TextSlot></Paragraph>
+    <Heading id={`${id}-title`} level={1} style={{ color: c.ink, fontFamily: documentFont('heading'), ...(display ? { fontSize: 62, lineHeight: 1.03, letterSpacing: -2.1 } : {}), marginBottom: subtitle ? 16 : 0 }}><TextSlot slot="title" from="title">{title}</TextSlot></Heading>
+    {subtitle && <Paragraph id={`${id}-subtitle`} role="lead" style={{ color: c.muted, marginBottom: 0 }}><TextSlot slot="subtitle" from="subtitle">{subtitle}</TextSlot></Paragraph>}
+  </Block>;
+}
+
+/** Independent bounded columns, deliberately not advertised as sequential text flow. */
+export function NeutralColumns({ left, right, ratio = 'equal', style }: { left: ReactNode; right: ReactNode; ratio?: 'equal' | 'narrow-left'; style?: Style }) {
+  return <View style={{ flexDirection: 'row', gap: metrics.gutter, alignItems: 'flex-start', ...style }}>
+    <View style={{ flex: 1, minWidth: 0 }}>{left}</View>
+    <View style={{ flex: ratio === 'equal' ? 1 : 2, minWidth: 0 }}>{right}</View>
+  </View>;
+}
+
+export function NeutralQuote({ id, children, attribution, surface = 'paper' }: { id: string; children: ReactNode; attribution: string; surface?: Surface }) {
+  const c = surfaceColors(surface);
+  return <Block id={id} style={{ borderTopWidth: 2, borderColor: surface === 'dark' ? colors.inverse : colors.blue, paddingTop: 18, marginTop: 18, marginBottom: 24 }}>
+    <Paragraph id={`${id}-text`} style={{ fontFamily: 'OpenDoc Serif', fontStyle: 'italic', fontSize: 28, lineHeight: 1.2, color: c.ink, marginBottom: 16 }}>{children}</Paragraph>
+    <Paragraph id={`${id}-attribution`} role="label" style={{ color: c.muted, marginBottom: 0 }}><TextSlot slot="attribution" from="attribution">{attribution}</TextSlot></Paragraph>
+  </Block>;
+}
+
+/** Native vector-like page shapes, used sparingly as the theme's opening motif. */
+export function PaperStudy({ id, surface = 'paper' }: { id: string; surface?: Surface }) {
+  const dark = surface === 'dark';
+  return <Block id={id} style={{ height: 186, flexDirection: 'row', gap: 16, alignItems: 'flex-end' }}>
+    <View style={{ flex: 1, height: 114, padding: 18, backgroundColor: dark ? colors.inverseRule : colors.stone }}>
+      <View style={{ width: 20, height: 3, backgroundColor: dark ? colors.inverseMuted : colors.muted, marginBottom: 36 }} />
+      <View style={{ height: 1, backgroundColor: dark ? colors.inverseMuted : colors.muted, marginBottom: 8 }} />
+      <View style={{ height: 1, width: '62%', backgroundColor: dark ? colors.inverseMuted : colors.muted }} />
+    </View>
+    <View style={{ flex: 1, height: 150, padding: 18, backgroundColor: dark ? colors.inverse : colors.ink }}>
+      <View style={{ width: 20, height: 3, backgroundColor: colors.blue, marginBottom: 32 }} />
+      <View style={{ height: 32, width: 32, borderWidth: 1, borderColor: dark ? colors.ink : colors.inverse, marginBottom: 18 }} />
+      <View style={{ height: 1, backgroundColor: dark ? colors.ink : colors.inverse }} />
+    </View>
+    <View style={{ flex: 1, height: 186, padding: 18, backgroundColor: colors.blue }}>
+      <View style={{ width: 20, height: 3, backgroundColor: colors.white, marginBottom: 38 }} />
+      <View style={{ height: 54, width: 54, borderWidth: 1, borderColor: colors.white, marginBottom: 25 }} />
+      <View style={{ height: 1, backgroundColor: colors.white, marginBottom: 8 }} />
+      <View style={{ height: 1, width: '62%', backgroundColor: colors.white }} />
+    </View>
+  </Block>;
+}

package/starter/themes/opendoc-neutral/design.md

@@ -0,0 +1,70 @@
+# OpenDoc Neutral
+
+The OpenDoc house style makes room for writing, evidence, and imagery. Warm paper and charcoal establish its character; scale, a flexible grid, fine rules, and one blue signal give it visual taste. It is a reusable everyday system, with expressive openings and dark surfaces available when the content benefits.
+
+## Palette
+
+| Role | Hex | Use |
+| --- | --- | --- |
+| Paper | #FCFBF8 | Ordinary reading pages |
+| White | #FFFFFF | Charts and analytical tables |
+| Ink / Night | #171A1D | Primary text; dark page surface |
+| Muted | #62686D | Secondary copy |
+| Blue | #3758F9 | Labels, citations, a chart focus, or one composition |
+| Wash | #ECEEF9 | Occasional callout |
+| Stone | #EAE7DF | Code panels and neutral diagrams |
+| Rule | #D7D7D2 | Light-surface dividers |
+| Inverse | #F7F6F2 | Primary text on charcoal |
+| Inverse muted | #B6BABE | Secondary text on charcoal |
+| Inverse rule | #41464B | Dark-surface dividers |
+
+Use genuine white and charcoal page backgrounds, independent of the app's appearance. Keep charts on white. Use blue for a clear point of emphasis; ordinary pages should not become collections of colored boxes.
+
+## Type and rhythm
+
+The bundled OpenDoc Sans carries headings and body text. OpenDoc Serif italic supplies a deliberate editorial quotation or reflective passage; OpenDoc Mono identifies labels, page furniture, and code. All are embedded local faces. Saved body/heading bindings can replace semantic families; the intentional serif and monospace voices remain distinct.
+
+| Role | Size / weight | Line height | Tracking |
+| --- | --- | --- | --- |
+| Display opening | 62 pt / 600 | 1.03 | -2.1 pt |
+| Page opening | 34 pt / 600 | 1.08 | -1.1 pt |
+| Section heading | 20 pt / 600 | 1.18 | -0.35 pt |
+| Small heading | 12 pt / 600 | 1.25 | Normal |
+| Body | 10.5 pt / 400 | 1.48 | Normal |
+| Lead | 13 pt / 400 | 1.45 | Normal |
+| Editorial quote | 28 pt / 400 italic | 1.2 | Normal |
+| Label | 7.5 pt / 400 mono | Inherited | 0.7 pt |
+| Caption / small | 8.5 / 8 pt | 1.4 | Normal |
+| Table body / header | 9 / 8 pt | 1.35 / inherited | Normal |
+| Code | 8 pt / 400 mono | 1.5 | Normal |
+| Running furniture | 7 pt / 400 mono | Inherited | Normal |
+
+Body paragraphs have 10 pt after-space. Ordinary h2 headings have 20 pt before and 10 pt after; h3 headings have 14 pt before and 8 pt after. Large openings use an 18 pt label gap, a 16 pt title-to-subtitle gap, and 24 pt below the composition. Use 6 pt as the spacing unit for custom arrangements; these optical type spacings are intentional exceptions.
+
+## Grid and surfaces
+
+A4 portrait has 48 pt top and side margins, 56 pt bottom, and a 499.28 pt content width. A 24 pt gutter gives two 237.64 pt columns, or a 158.43 / 316.85 pt asymmetric split. Use a 0.6 pt rule and square corners. Running labels sit above the reading field; a fine rule and actual folio close each page.
+
+Use `NeutralPages` for flowing reading, white evidence, or charcoal pages. Its header/footer repeat on continuation pages. Ordinary prose must be allowed to flow. Use `NeutralColumns` for independent bounded material, not sequential story text. An opening may have a large deliberate gap; a long report should not be manually paginated paragraph by paragraph.
+
+## Reusable compositions
+
+See [components.tsx](components.tsx) for the executable implementations.
+
+- `NeutralPages`: title, optional label, surface (`paper`, `white`, `dark`), optional header, and children. On dark surfaces, explicitly give standard headings, paragraphs, and captions the corresponding inverse color; their semantic theme colors otherwise remain dark ink.
+- `NeutralOpening`: stable id, eyebrow, title, optional subtitle, surface, and optional display scale. Keeps the same title/subtitle identities when its text changes.
+- `NeutralColumns`: left and right content, equal or narrow-left ratio, optional native style. Give each column its own reading path.
+- `NeutralQuote`: stable id, authored quote, attribution, and surface. Uses a 2 pt leading rule and a real serif italic face. Attribute original house copy honestly.
+- `PaperStudy`: stable id and surface. Three native page-like planes (114, 150, and 186 pt high, with 16 pt gaps) express the move from working material to a finished page. Use only as an opening or closing visual, not as repeated filler.
+
+## Evidence, imagery, and identity
+
+Tables have charcoal column headers, white labels, 8 pt cell padding, restrained alternating rows (#F1F1EE), and 0.5 pt bottom rules. Keep numeric columns right aligned. Captions and source notes stay close to figures. Use managed chart images, retain prepared data and recipes, and repeat the key values in selectable text or a native table. Clearly label synthetic demonstrations.
+
+Images keep their aspect ratio. Favor a substantial image and an explanatory caption over a collage of tiny decorations. A dark gallery page can let a photograph carry the composition. Generated artwork must be labeled as such and retain its prompt/provenance; it is not documentary evidence.
+
+The shared OpenDoc logo is the existing wordmark, imported from `assets/brand/wordmark.png`. Its dark variation belongs on light surfaces. Preserve the original proportions and transparency. Place it explicitly through a saved `Logo` binding; no mark is inserted automatically. The theme's specimen stays self-contained and does not rely on a document's private media.
+
+## Basis
+
+Original house system created for the user's OpenDoc Neutral brief: tasteful neutral styling, a welcome document that demonstrates varied layouts, detailed data graphics, generated imagery, identity, and light/dark pages. The existing OpenDoc wordmark and bundled local font families are retained. The composition and palette are original design interpretations, not an adaptation of an external brand. The independent specimen and the welcome document are the review surfaces.

package/starter/themes/opendoc-neutral/index.ts

@@ -0,0 +1,54 @@
+import type { DocTheme } from 'opendoc/themes';
+
+export const colors = {
+  paper: '#FCFBF8', white: '#FFFFFF', ink: '#171A1D', muted: '#62686D',
+  blue: '#3758F9', wash: '#ECEEF9', rule: '#D7D7D2', stone: '#EAE7DF',
+  night: '#171A1D', inverse: '#F7F6F2', inverseMuted: '#B6BABE', inverseRule: '#41464B',
+};
+export const metrics = { margin: 48, bottom: 56, gutter: 24, rule: 0.6, unit: 6, measure: 499.28 };
+
+export const theme: DocTheme = {
+  id: 'opendoc-neutral', name: 'OpenDoc Neutral',
+  description: 'The OpenDoc house style: warm paper, charcoal, a precise blue signal, generous typography, and a flexible editorial grid.',
+  body: 'OpenDoc Sans', heading: 'OpenDoc Sans',
+  ink: colors.ink, muted: colors.muted, accent: colors.blue, paper: colors.paper, line: colors.rule,
+  fontSize: 10.5, lineHeight: 1.48, margin: metrics.margin, paragraphGap: 10,
+  pageSize: 'A4', runningHeader: true, runningFooter: true, footerLabel: 'OpenDoc',
+  useFor: ['Everyday documents with a considered identity', 'Editorial guides and visual reports', 'Proposals, evidence, and working papers'],
+  principles: ['Use scale and whitespace before adding decoration.', 'Give the reader one clear point of entry.', 'Use blue to identify what matters.', 'Let long content flow; compose short material deliberately.'],
+  palette: [
+    { name: 'Paper', value: colors.paper, role: 'Warm reading pages' },
+    { name: 'White', value: colors.white, role: 'Analytical pages and image fields' },
+    { name: 'Ink', value: colors.ink, role: 'Primary text and dark page surface' },
+    { name: 'Muted', value: colors.muted, role: 'Secondary explanations and captions' },
+    { name: 'Blue', value: colors.blue, role: 'A single emphasis, citation, or chart focus' },
+    { name: 'Wash', value: colors.wash, role: 'Occasional supporting panel' },
+    { name: 'Stone', value: colors.stone, role: 'Neutral structure and diagram fields' },
+    { name: 'Rule', value: colors.rule, role: 'Fine dividers and table boundaries' },
+    { name: 'Inverse', value: colors.inverse, role: 'Text on charcoal pages' },
+    { name: 'Inverse muted', value: colors.inverseMuted, role: 'Captions and secondary text on charcoal' },
+    { name: 'Inverse rule', value: colors.inverseRule, role: 'Dividers on charcoal' },
+  ],
+  geometry: ['A4 portrait; 48 pt top/side and 56 pt bottom margins.', 'A 499 pt content field: equal columns or a 1:2 split, with 24 pt gutters.', 'A 6 pt spacing unit; 0.6 pt rules; square corners.', '10.5 pt reading type at 1.48 leading; 34 pt openings and 62 pt display type.', 'Warm reading pages, white analytical pages, and charcoal image or closing pages.'],
+  design: {
+    page: { margin: { top: 48, right: 48, bottom: 56, left: 48 }, style: { backgroundColor: colors.paper } },
+    typography: {
+      h1: { fontSize: 34, fontWeight: 600, lineHeight: 1.08, letterSpacing: -1.1, marginTop: 0, marginBottom: 18 },
+      h2: { fontSize: 20, fontWeight: 600, lineHeight: 1.18, letterSpacing: -0.35, marginTop: 20, marginBottom: 10 },
+      h3: { fontSize: 12, fontWeight: 600, lineHeight: 1.25, marginTop: 14, marginBottom: 8 },
+      label: { fontFamily: 'OpenDoc Mono', fontSize: 7.5, letterSpacing: 0.7, color: colors.blue },
+      lead: { fontSize: 13, lineHeight: 1.45, color: colors.muted },
+      small: { fontFamily: 'OpenDoc Sans', fontSize: 8, lineHeight: 1.4, color: colors.muted },
+      caption: { fontFamily: 'OpenDoc Sans', fontSize: 8.5, lineHeight: 1.4, color: colors.muted },
+      code: { fontFamily: 'OpenDoc Mono', fontSize: 8, lineHeight: 1.5, color: colors.ink },
+    },
+    title: { block: { paddingBottom: 24, borderBottomWidth: 0, marginBottom: 18 }, heading: { fontSize: 34 }, eyebrow: { marginBottom: 16 }, subtitle: { fontSize: 13 }, uppercaseEyebrow: false },
+    cover: { title: { fontSize: 62, lineHeight: 1.03, letterSpacing: -2.1 }, subtitle: { fontSize: 16 }, page: { backgroundColor: colors.paper } },
+    furniture: { text: { fontFamily: 'OpenDoc Mono', fontSize: 7, color: colors.muted }, header: { paddingBottom: 18 }, footer: { borderTopWidth: 0.6, paddingTop: 10 }, pageNumber: 'page', uppercaseHeader: false },
+    table: { block: { marginTop: 10, marginBottom: 18 }, header: { backgroundColor: colors.ink }, headerText: { fontSize: 8, fontWeight: 600, color: colors.white }, cell: { padding: 8, borderBottomWidth: 0.5 }, text: { fontSize: 9, lineHeight: 1.35 }, alternate: '#F1F1EE' },
+    figure: { block: { marginTop: 10, marginBottom: 16 } },
+    callout: { block: { backgroundColor: colors.wash, borderLeftWidth: 2, borderColor: colors.blue, padding: 16 }, title: { fontSize: 8, color: colors.blue }, text: { fontSize: 10, lineHeight: 1.45 } },
+    code: { block: { marginTop: 8, marginBottom: 16 }, panel: { backgroundColor: colors.stone, padding: 16 } },
+    list: { gap: 8, markerWidth: 16, item: { fontSize: 10.5, lineHeight: 1.45 } },
+  },
+};

package/starter/themes/opendoc-neutral/preview.tsx

@@ -0,0 +1,43 @@
+import { Document, Paragraph, Heading, DataTable, Strong, View } from 'opendoc';
+import { theme, colors } from './index';
+import { NeutralPages, NeutralOpening, NeutralColumns, NeutralQuote, PaperStudy } from './components';
+
+export const meta = { title: 'OpenDoc Neutral', description: 'A three-page house-style specimen: typographic identity, a working report, and a charcoal closing.', theme: theme.id };
+export default function Specimen() {
+  return <Document title={meta.title} theme={theme}>
+    <NeutralPages title="The house style" header={false}>
+      <Paragraph id="specimen-wordmark" style={{ fontSize: 18, fontWeight: 600, letterSpacing: -0.5, marginBottom: 72 }}>OpenDoc</Paragraph>
+      <NeutralOpening id="specimen-opening" eyebrow="A HOUSE STYLE / 01" title={'Clarity has\ncharacter.'} subtitle="OpenDoc Neutral brings a considered visual language to everyday work." display />
+      <Paragraph id="specimen-intent" style={{ width: 365, marginTop: 8, marginBottom: 42 }}>Warm paper. Confident typography. A precise blue signal. A flexible grid that gives words, images, and evidence room to do their work.</Paragraph>
+      <PaperStudy id="specimen-paper-study" />
+      <Paragraph id="specimen-caption" role="small" style={{ marginTop: 18 }}>One visual language, from a short working note to a substantial publication.</Paragraph>
+    </NeutralPages>
+    <NeutralPages title="Applied / a working report" surface="white">
+      <NeutralOpening id="specimen-report" eyebrow="A WORKING REPORT / 02" title="Make the decision easy to find." subtitle="A fictional studio review shows the system at reading scale." />
+      <NeutralColumns left={<>
+        <Heading id="specimen-principle" level={2} style={{ marginTop: 0 }}>Start with the reader</Heading>
+        <Paragraph id="specimen-reading">A useful report gives the reader a clear reason to continue. Put the decision near the beginning, develop the evidence, and keep qualifications close to the claim they affect.</Paragraph>
+        <Paragraph id="specimen-long-reading">This column is ordinary selectable text. It can be revised without redrawing the page, and longer sections can continue naturally. The grid supplies structure while the content determines how much space is needed.</Paragraph>
+      </>} right={<>
+        <Heading id="specimen-evidence" level={2} style={{ marginTop: 0 }}>Keep the basis visible</Heading>
+        <Paragraph id="specimen-evidence-copy">Every number below is <Strong>illustrative</Strong>. A restrained header, aligned values, and a nearby source note make the comparison easy to inspect.</Paragraph>
+        <Paragraph id="specimen-review-copy">Use fine rules instead of a dense cage. Keep labels short and units explicit. Preserve the data and record identities when an agent prepares the next edition.</Paragraph>
+      </>} />
+      <DataTable id="specimen-table" caption="Illustrative studio allocation" columns={[{ label: 'Workstream', width: 2 }, { label: 'Hours', align: 'right' }, { label: 'Share', align: 'right' }]} rows={[["Research", 24, '20%'], ["Drafting", 48, '40%'], ["Design", 30, '25%'], ["Review", 18, '15%']]} rowIds={['research', 'drafting', 'design', 'review']} sourceNote="Synthetic specimen values, totaling 120 hours. No work was measured." />
+      <NeutralQuote id="specimen-quote" attribution="OpenDoc / house principle">Give the page a clear purpose, then give it room.</NeutralQuote>
+    </NeutralPages>
+    <NeutralPages title="A change of pace" surface="dark">
+      <NeutralOpening id="specimen-dark" eyebrow="THE INVERSE SURFACE / 03" title={'Quiet pages.\nStrong ideas.'} subtitle="Charcoal creates a deliberate pause for an opening, a large image, or a final thought." surface="dark" display />
+      <NeutralQuote id="specimen-dark-quote" attribution="Original OpenDoc house copy" surface="dark">The craft is in what the reader can see, understand, and use.</NeutralQuote>
+      <View style={{ marginTop: 32 }}><NeutralColumns left={<>
+        <Paragraph id="specimen-dark-grid" role="label" style={{ color: colors.inverseMuted }}>GRID</Paragraph>
+        <Paragraph id="specimen-dark-grid-copy" style={{ color: colors.inverse }}>A4 portrait. 48 pt side margins. 24 pt gutters. Equal columns or a one-to-two split.</Paragraph>
+      </>} right={<>
+        <Paragraph id="specimen-dark-type" role="label" style={{ color: colors.inverseMuted }}>VOICE</Paragraph>
+        <Paragraph id="specimen-dark-type-copy" style={{ color: colors.inverse }}>Sans for clarity, serif italic for reflection, monospace for labels. Real local faces, embedded in the PDF.</Paragraph>
+      </>} /></View>
+      <View style={{ marginTop: 36, flexDirection: 'row', gap: 12 }}>{[colors.paper, colors.stone, colors.muted, colors.blue].map(color => <View key={color} style={{ height: 42, flex: 1, backgroundColor: color }} />)}</View>
+      <Paragraph id="specimen-dark-end" role="small" style={{ marginTop: 18, color: colors.inverseMuted }}>The guide and reusable source components live with the theme. The finished welcome document shows the same system with real media and shared assets.</Paragraph>
+    </NeutralPages>
+  </Document>;
+}

package/starter/themes/types.ts

@@ -0,0 +1,3 @@
+// Compatibility entry for existing workspace themes. New themes can import from opendoc/themes.
+export { themeType, themePage, validateTheme } from 'opendoc/themes';
+export type { DocTheme, ThemeDesign, ThemeFont, ThemeTypeRole } from 'opendoc/themes';

package/tsconfig.workspace.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "jsxImportSource": "opendoc",
+    "strict": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "baseUrl": ".",
+    "typeRoots": ["./node_modules/@types"],
+    "types": ["node"],
+    "paths": {
+      "react": ["./node_modules/@types/react/index.d.ts"],
+      "react/*": ["./node_modules/@types/react/*"],
+      "@formepdf/react": ["./node_modules/@formepdf/react/dist/index.d.ts"]
+    }
+  }
+}

package/vendor/formepdf/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/vendor/formepdf/README.md

@@ -0,0 +1,97 @@
+# Forme text writer and font subset repair
+
+OpenDoc uses `@formepdf/core` **0.20.1-opendoc.3**, based on upstream
+[`v0.20.1`, commit `0d706f839617b775e90edcc93d6001a8b0145a78`](https://github.com/formepdf/forme/tree/0d706f839617b775e90edcc93d6001a8b0145a78).
+The published JavaScript interface is unchanged. `text-writer.patch` repairs the
+Rust PDF writer, while `font-subset.patch` repairs embedded TrueType metadata.
+The source repository's archive contains rebuilt bundler, web, and Node WASM
+engines. The workspace override pins this repaired engine for contributors.
+
+Both installable editions, `opendoc` and `opendoc-headless`, bundle this repaired
+core with Forme's React serializer and shared JavaScript definitions.
+`pnpm package:pack` materializes ordinary npm trees in temporary staging
+directories. Both editions render in Node, so distribution retains the repaired
+`pkg-node` engine byte for byte and omits the unused browser and worker WASM
+targets. The staged core manifest exposes only its Node entry and layout helpers;
+it does not advertise the removed targets. The duplicate source archive remains
+in this repository and is excluded from both runtime packages. Consumers need no
+override, local archive path, Rust tools, or build hook. Native dependencies such
+as `esbuild`, canvas, and resvg stay unbundled so npm installs the binaries
+appropriate to the consumer's operating system and architecture.
+
+OpenDoc already supplies its own TSX bundling and source-location capture. The
+only remaining `@formepdf/renderer` operation was asset source resolution.
+`src/rendering/resolve-sources.ts` retains the 0.20.1 package's `dist/resolve.js`
+implementation, with only TypeScript annotations and formatting changes. This
+avoids importing the unrelated HTML compiler. Its copyright is Daniel Molitor,
+2026, and the MIT license in this directory covers the retained resolver as well
+as the engine. Future upgrades should compare that small module with the
+upstream resolver explicitly.
+
+The `opendoc.3` build also remaps local source, home, Cargo, and toolchain paths
+to anonymous `/build/` paths using Rust's
+[`--remap-path-prefix`](https://doc.rust-lang.org/rustc/remap-source-paths.html).
+This removes builder-specific paths from embedded panic diagnostics without
+changing the renderer API. The rebuild script checks every generated WASM engine
+for the original local paths before packaging it.
+
+## Repair
+
+- Allocate PDF character codes by glyph **and source text**, with an explicit
+  CIDToGIDMap. A shaped `fi` and literal `fi` can use the same glyph without losing
+  their distinct source text.
+- Write full UTF-16BE sequences in ToUnicode, including ligatures and surrogate
+  pairs. Keep the original GSUB, GPOS, and kerning tables in every imported font.
+- Position custom-font glyphs using their shaped x/y coordinates, including
+  kerning, mark offsets, letter spacing, and cumulative justified spaces. Use the
+  same positioning for watermarks. Preserve fractional font sizes and widths.
+- Reset word spacing at style boundaries to avoid leaking custom-font text state.
+- Record actual TrueType table lengths while keeping table starts aligned to
+  four bytes. In particular, a short `loca` contains exactly `numGlyphs + 1`
+  entries; alignment padding is outside its recorded length.
+- Preserve the original `maxp` profile except for `numGlyphs`. The retained
+  outlines, glyph instructions, and copied `fpgm`, `prep`, and `cvt ` tables still
+  need the original interpreter resource limits.
+- Keep the `head` directory checksum calculated with zero `checkSumAdjustment`.
+  Write the adjustment only into the table, so the whole font sums to `0xB1B0AFBA`.
+
+These metadata repairs follow the OpenType [font file and checksum
+rules](https://learn.microsoft.com/en-us/typography/opentype/spec/otff) and
+[`maxp` profile](https://learn.microsoft.com/en-us/typography/opentype/spec/maxp).
+
+This is a source-level engine fix. It does not alter font files, disable shaping,
+normalize away missing spaces, or relax compatibility checks. Existing renamed
+OpenDoc font derivatives remain unchanged for document continuity.
+
+## Rebuild
+
+In a source checkout, `pnpm install --frozen-lockfile` uses the checked-in archive
+and needs no Rust tools. To rebuild from that checkout, install Rust **1.98.1**, its `wasm32-unknown-unknown` target,
+and **wasm-pack 0.15.0**, then run:
+
+```sh
+node scripts/rebuild-forme.mjs
+```
+
+The script verifies the upstream commit and original npm tarball SHA-512, applies
+both readable patches, runs the engine's library tests, builds all three WASM entry
+points with the upstream lockfile, and packages the existing published JS with
+those engines. Build files stay in a fresh operating-system temporary directory;
+an optional first argument chooses a new directory that must not already exist.
+The printed directory is retained for inspecting build results. Set
+`RUSTUP_TOOLCHAIN=stable` only if that
+installed toolchain is exactly 1.98.1.
+
+After deliberately replacing the archive, refresh the pnpm lockfile and run
+`pnpm check`, `pnpm test`, and `pnpm build`. Review the PDF specimens for all five
+Google Fonts families and verify their original file hashes. See
+`tests/font-renderer.test.ts` for PDF extraction and geometry regressions and
+`tests/font-subset.test.ts` for lengths, checksums, and hinting metadata read from
+the actual embedded font streams. The subset patch also contains Rust regressions
+for alignment, checksums, and profile preservation using the upstream font fixture.
+
+## Upstream replacement
+
+When an upstream version includes equivalent fixes, remove the local override
+and archive only after these regressions and existing document checks pass.
+The patch and engine remain under Forme's MIT license, retained in `LICENSE`.