@ryanyahya/opendoc 0.4.0

package/starter/templates/editorial-essay/index.tsx

@@ -0,0 +1,30 @@
+import type { ReactNode } from 'react';
+import * as F from '@formepdf/react';
+import { TextSlot, Document, Heading, Paragraph, Prose, References, Page } from 'opendoc';
+import { themePage, type DocTheme } from 'opendoc/themes';
+
+export interface EditorialEssayProps {
+  title: string;
+  theme: DocTheme;
+  author?: string;
+  standfirst?: ReactNode;
+  children: ReactNode;
+  references?: Parameters<typeof Document>[0]['references'];
+}
+
+/** Page architecture only. Content remains ordinary, freely ordered PDF blocks. */
+export function EditorialEssay({ title, theme, author, standfirst, children, references }: EditorialEssayProps) {
+  const layoutTheme: DocTheme = theme.design ? theme : { ...theme, fontSize: 11, lineHeight: 1.42, paragraphGap: 0 };
+  return <Document title={title} author={author} theme={layoutTheme} references={references}>
+    <Page {...themePage(theme, { top: 66, bottom: 62, left: 105, right: 105 })}>
+      {(!theme.design || theme.runningFooter) && <F.Fixed position="footer"><F.Text style={{ fontFamily: theme.body, fontSize: 8, color: theme.muted, textAlign: 'right', ...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="essay-title" level={1} baseStyle={{ fontSize: 36, lineHeight: 1.12, marginBottom: 12 }} style={theme.design?.title?.heading}><TextSlot slot="title" from="title">{title}</TextSlot></Heading>
+        {author && <Paragraph id="essay-byline" role="small" baseStyle={{ fontSize: 8.5, letterSpacing: 0.25, color: theme.muted, marginBottom: 24 }} style={theme.design?.title?.byline}><TextSlot slot="author" from="author">{author}</TextSlot></Paragraph>}
+        {standfirst && <Paragraph id="essay-standfirst" role="lead" baseStyle={{ fontSize: 13, lineHeight: 1.45, color: theme.muted, marginBottom: 28 }} style={theme.design?.title?.subtitle}><TextSlot slot="standfirst" from="standfirst">{standfirst}</TextSlot></Paragraph>}
+      </F.View>
+      <Prose paragraphGap={theme.design ? theme.paragraphGap : 6}>{children}</Prose>
+      <References headingBaseStyle={{ fontSize: 10, marginTop: 26, marginBottom: 8 }} />
+    </Page>
+  </Document>;
+}

package/starter/templates/editorial-essay/preview.tsx

@@ -0,0 +1,26 @@
+import * as F from '@formepdf/react';
+import { Paragraph, Figure, Heading } from 'opendoc';
+import { neutral } from '../../themes';
+import { type DocTheme } from 'opendoc/themes';
+import { EditorialEssay } from './index';
+
+export const meta = { title: 'Editorial essay', description: 'A neutral layout specimen with placeholder content.', kind: 'article' as const, theme: 'neutral' };
+const paragraph = 'This is placeholder text for the reading column. Its purpose is to make the page’s proportions visible: the length of a line, the space between paragraphs, and the quiet area around the text. The words carry no argument and describe no findings. In a finished essay, the author’s own material occupies this space and continues naturally from one page to the next.';
+
+export function Specimen({ length = 'typical', theme = neutral }: { length?: 'sparse' | 'typical' | 'long'; theme?: DocTheme } = {}) {
+  const count = length === 'sparse' ? 1 : length === 'long' ? 28 : 5;
+  return <EditorialEssay title={meta.title} theme={theme} author="Author name · Layout specimen" standfirst="A standfirst sits between the title and the essay: a larger, quieter passage with space to breathe before the reading column begins.">
+    {Array.from({ length: count }, (_, index) => <Paragraph key={index} id={`specimen-paragraph-${index + 1}`}>{paragraph}</Paragraph>)}
+    {length !== 'sparse' && <>
+      <Figure id="specimen-visual" caption="An optional visual spans the reading column. Placeholder only.">
+        <F.View style={{ height: 130, backgroundColor: neutral.paper, borderWidth: 0.6, borderColor: neutral.line, justifyContent: 'center', alignItems: 'center' }}>
+          <F.Text style={{ fontSize: 10, color: neutral.muted }}>Full-width visual</F.Text>
+        </F.View>
+      </Figure>
+      <Paragraph id="specimen-closing">{paragraph}</Paragraph>
+      <Heading id="specimen-reference-heading" style={{ fontSize: 11, marginTop: 24 }}>References</Heading>
+      <Paragraph id="specimen-reference" style={{ fontSize: 9.5, color: neutral.muted }}>Reference placement specimen. Real references appear here only when cited; no source is being claimed.</Paragraph>
+    </>}
+  </EditorialEssay>;
+}
+export default Specimen;

package/starter/templates/editorial-essay/starter.tsx

@@ -0,0 +1,15 @@
+import { EditorialEssay } from '../../templates/editorial-essay';
+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: 'An editorial essay, ready for your material.', kind: 'article' as const, theme: themeId };
+export const provenance = { template: 'templates/editorial-essay/index.tsx' };
+
+export default function Essay() {
+  return <EditorialEssay title={title} theme={theme} author="Author name" standfirst="Standfirst — replace this placeholder with your opening summary.">
+    <Paragraph id="essay-opening">Your essay begins here. This is placeholder text, ready to be replaced with your own material.</Paragraph>
+  </EditorialEssay>;
+}

package/starter/templates/editorial-essay/template.json

@@ -0,0 +1,11 @@
+{
+  "name": "Editorial essay",
+  "description": "A literary reading column with indented paragraphs, a considered opening, and quiet page furniture. For essays, opinion pieces, and long-form reflections.",
+  "format": "A4 · Single column",
+  "structure": [
+    "Title, byline, and standfirst share the opening page with the body.",
+    "A narrow column and close paragraph rhythm support sustained reading. Openings sit flush left; subsequent paragraphs begin with a first-line indent.",
+    "Occasional visuals span the full text width; references sit quietly at the end.",
+    "Discreet page numbers leave the page free of running headers and rules."
+  ]
+}

package/starter/templates/executive-brief/AGENTS.md

@@ -0,0 +1,9 @@
+# Executive brief
+
+Treat this as a soft foundation with room for variation and creativity. Its starting character is a compact opening, a visible takeaway, and a broad reading column with economical section spacing. It suggests a concise one- or two-page document; that is a useful aim, not a page limit or a mandated writing method.
+
+Let content and reader guide the composition. A long title may benefit from smaller type through `titleStyle`, a prominent exhibit may need more space, or a short note may need no headings at all. The label, author, date, and takeaway are optional. Do not invent a recommendation, force a problem/solution outline, or add sections to match the specimen. Dates are supplied text; do not imply a review date that has not occurred.
+
+Use ordinary OpenDoc blocks and native Forme flow. Keep titles and takeaways breakable; do not shrink content automatically, split lines by hand, or patch the renderer to force a page count. BriefHeading provides compact defaults. A native unbreakable View can keep a heading with a genuinely short lead; longer prose belongs outside that group. Use readable captions, units, and source notes for exhibits. Preserve stable IDs and evidence accuracy.
+
+The caller's theme supplies visual hierarchy, rhythm, and component treatments. Keep variations for one document local, and preserve other templates and documents. Review the adapted PDF. Shared changes need sparse, typical, and long specimens, a second theme, long opening material, and a working starter. Catalog specimens use Neutral and identify illustrative material explicitly.

package/starter/templates/executive-brief/README.md

@@ -0,0 +1,11 @@
+# Executive brief
+
+A flexible, compact layout for updates, briefings, and decision notes. Defaults are A4 portrait, 52-point side and 48-point top/bottom margins, a 491-point reading column, 11/15.4-point body type, and 8-point paragraph gaps. A 26-point title opens the same page as the body. The optional 14-point takeaway gives the opening emphasis. Page numbers sit at the bottom right.
+
+`ExecutiveBrief` accepts `title`, `theme`, and ordinary OpenDoc blocks as `children`. Optional `label`, `author`, and `date` add small opening details; `date` is supplied display text. `takeaway` accepts inline text and formatting, with no mandatory label or content formula. `titleStyle` accepts native styles for a longer title or an adapted opening. Fonts and colors come from the theme. Optional verified `references` work with the existing Cite blocks and appear after the body.
+
+`BriefHeading` accepts a stable `id`, `children`, and optional native `style`; its starting size is 12.5 points. Use a native `<F.View wrap={false}>` around a heading and a short lead when they need to stay together. Keep the rest in normal flow. Tables and figures use existing OpenDoc blocks with captions and accurate source notes.
+
+One or two pages is an editorial aim, not an enforced limit. Titles, takeaways, and body prose remain breakable, and longer material can continue across pages. There is no custom layout engine, automatic fitting, or required section outline. Adapt the defaults to the content and review the result. See [AGENTS.md](AGENTS.md) for the intended freedom and functional boundaries.
+
+`preview.tsx` supplies sparse, typical, and long specimens, with optional theme selection for review. The catalog uses Neutral; all sample values are explicitly synthetic. `starter.tsx` creates an ordinary linked document, with no extra data format or runtime.

package/starter/templates/executive-brief/index.tsx

@@ -0,0 +1,33 @@
+import type { ReactNode } from 'react';
+import * as F from '@formepdf/react';
+import { TextSlot, Document, Heading, Paragraph, References, Page } from 'opendoc';
+import { themePage, type DocTheme } from 'opendoc/themes';
+
+export function ExecutiveBrief({ title, theme, author, date, label, takeaway, titleStyle, children, references }: {
+  title: string; theme: DocTheme; author?: string; date?: string; label?: string;
+  takeaway?: ReactNode; titleStyle?: F.Style; children: ReactNode;
+  references?: Parameters<typeof Document>[0]['references'];
+}) {
+  const layoutTheme: DocTheme = theme.design ? theme : { ...theme, fontSize: 11, lineHeight: 1.4, paragraphGap: 8 };
+  const details = author || date;
+  return <Document title={title} author={author} theme={layoutTheme} references={references}>
+    <Page {...themePage(theme, { top: 48, bottom: 48, left: 52, right: 52 })} 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: 'right', ...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}>
+        {label && <Paragraph id="brief-label" role="label" baseStyle={{ fontSize: 8.5, color: theme.muted, letterSpacing: 0.6, marginBottom: 8 }} style={theme.design?.title?.eyebrow}>{theme.design?.title?.uppercaseEyebrow ? label.toUpperCase() : <TextSlot slot="label" from="label">{label}</TextSlot>}</Paragraph>}
+        <Heading id="brief-title" level={1} baseStyle={{ fontSize: 26, lineHeight: 1.12, marginBottom: 10 }} style={{ ...theme.design?.title?.heading, ...titleStyle }}><TextSlot slot="title" from="title">{title}</TextSlot></Heading>
+        {details && <Paragraph id="brief-details" role="small" baseStyle={{ fontSize: 9, color: theme.muted, marginBottom: 10 }} style={theme.design?.title?.byline}>{author && <TextSlot slot="author" from="author">{author}</TextSlot>}{author && date ? ' · ' : ''}{date && <TextSlot slot="date" from="date">{date}</TextSlot>}</Paragraph>}
+        {takeaway && <Paragraph id="brief-takeaway" role="lead" baseStyle={{ fontSize: 14, fontWeight: 600, lineHeight: 1.35, marginTop: 8, marginBottom: 16 }} style={theme.design?.title?.subtitle}><TextSlot slot="takeaway" from="takeaway">{takeaway}</TextSlot></Paragraph>}
+      </F.View>
+      <F.View style={{ marginTop: takeaway ? 0 : 10 }}>
+        {children}
+        <References headingBaseStyle={{ fontSize: 12.5, marginTop: 16, marginBottom: 6 }} />
+      </F.View>
+    </Page>
+  </Document>;
+}
+
+/** Compact section hierarchy with ordinary native styles available to the author. */
+export function BriefHeading({ id, style, children }: { id: string; style?: F.Style; children: ReactNode }) {
+  return <Heading id={id} level={2} baseStyle={{ fontSize: 12.5, marginTop: 12, marginBottom: 6 }} style={style}><TextSlot slot="children" from="children">{children}</TextSlot></Heading>;
+}

package/starter/templates/executive-brief/preview.tsx

@@ -0,0 +1,37 @@
+import * as F from '@formepdf/react';
+import { DataTable, Figure, Paragraph } from 'opendoc';
+import { neutral } from '../../themes';
+import { type DocTheme } from 'opendoc/themes';
+import { BriefHeading, ExecutiveBrief } from './index';
+
+export const meta = { title: 'Executive brief', description: 'A Neutral brief specimen with illustrative placeholders only.', kind: 'report' as const, theme: 'neutral' };
+const paragraph = 'This is placeholder prose for the brief. It demonstrates a compact reading rhythm and the relationship between a section heading, supporting detail, and a small exhibit. In an authored document, the reader’s needs and the available evidence determine what belongs here. No business result or recommendation is being claimed.';
+
+export function Specimen({ length = 'typical', theme = neutral }: { length?: 'sparse' | 'typical' | 'long'; theme?: DocTheme } = {}) {
+  const sparse = length === 'sparse';
+  return <ExecutiveBrief title={meta.title} theme={theme}
+    author={sparse ? undefined : 'Author or team'} date={sparse ? undefined : 'Date placeholder'}
+    takeaway={sparse ? undefined : 'A short opening takeaway receives emphasis while the supporting detail remains easy to scan. This is a layout specimen, not a finding.'}>
+    <Paragraph id="specimen-opening">{paragraph}</Paragraph>
+    {!sparse && <>
+      <F.View wrap={false}>
+        <BriefHeading id="specimen-detail-heading">A compact section</BriefHeading>
+        <Paragraph id="specimen-detail-lead">A short lead stays with its heading. Section names and order belong to the writer; this specimen does not prescribe a briefing method.</Paragraph>
+      </F.View>
+      {length === 'long' && Array.from({ length: 9 }, (_, index) => <Paragraph key={index} id={`specimen-detail-${index + 1}`}>{paragraph}</Paragraph>)}
+      <DataTable id="specimen-table" caption="Synthetic values for layout review"
+        columns={[{ label: 'Item', width: 2 }, { label: 'Value (a.u.)', width: 1, align: 'right' }, { label: 'Status', width: 2 }]}
+        rows={Array.from({ length: length === 'long' ? 24 : 3 }, (_, index) => [`Example ${index + 1}`, 10 + index, 'Illustrative only'])}
+        sourceNote="All values are synthetic. a.u. means arbitrary units; no measured outcome is claimed." />
+      {length === 'long' && <Figure id="specimen-figure" caption="A small exhibit can follow the narrative in normal flow." sourceNote="Illustrative placeholder only; no data or source is claimed.">
+        <F.View style={{ height: 95, 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}>
+        <BriefHeading id="specimen-closing-heading">A closing section</BriefHeading>
+        <Paragraph id="specimen-closing">This final passage shows the spacing after an exhibit. The actual brief may end here or continue with further material. Its length follows the content, without shrinking type to meet a page count.</Paragraph>
+      </F.View>
+      <Paragraph id="specimen-reference-note" style={{ fontSize: 9, color: theme.muted, marginTop: 10 }}>Reference placement specimen. Verified references appear after the body when cited; no source is being claimed here.</Paragraph>
+    </>}
+  </ExecutiveBrief>;
+}
+export default Specimen;

package/starter/templates/executive-brief/starter.tsx

@@ -0,0 +1,11 @@
+import { ExecutiveBrief } from '../../templates/executive-brief';
+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: 'An executive brief, ready for your content.', kind: 'report' as const, theme: themeId };
+export const provenance = { template: 'templates/executive-brief/index.tsx' };
+export default function Brief() {
+  return <ExecutiveBrief title={title} theme={theme} takeaway="Replace this placeholder with a concise opening takeaway, or omit it when the brief does not need one."><Paragraph id="brief-opening">Your brief begins here. Add the prose, evidence, and exhibits your reader needs, in the order that makes the material clearest.</Paragraph></ExecutiveBrief>;
+}

package/starter/templates/executive-brief/template.json

@@ -0,0 +1,11 @@
+{
+  "name": "Executive brief",
+  "description": "A compact title block, an optional prominent takeaway, and closely spaced sections with room for small exhibits. For concise updates, briefings, and decision notes.",
+  "format": "A4 · Compact brief",
+  "structure": [
+    "A compact, left-aligned title shares the opening page with the text. A label, author, and date are optional.",
+    "An optional opening takeaway uses larger, stronger type without requiring a particular argument or outline.",
+    "A broad single column and compact section headings make room for prose, a small table, or a figure in the author's chosen order.",
+    "References follow the text and page numbers sit quietly below. Aim for a concise document; longer material flows naturally without forced fitting."
+  ]
+}

package/starter/templates/image-story/AGENTS.md

@@ -0,0 +1,37 @@
+# Image story
+
+An adaptable layout skeleton for image-led documents. Every catalog image position is a replaceable placeholder; no actual artwork, brand identity, or subject matter belongs in this template. Themes supply the appearance and each document owns its content. Use one or two layouts when they help; the seven-page specimen is a menu, not an outline to reproduce. The catalog uses Neutral so the architecture is visible independently of branding.
+
+## Start with the image's job
+
+- `cover`: establish atmosphere with full bleed and a short title in quiet image space.
+- `split-left`: give a portrait image half the page and concise prose a separate column.
+- `split-top`: introduce a scene before the writing; often better for longer headlines.
+- `panorama`: contrast a wide band with a square inset; explain the relationship in the nearby copy.
+- `diptych`: align an unequal pair for comparison or two perspectives.
+- `collage`: three pictures with unequal scale and one overlap, connected by short copy.
+- `overlay`: full bleed with an opaque text panel when the artwork is busy.
+
+The half-page split and panorama with inset are strong everyday defaults. Collages and overlays work best as occasional emphasis. White space, image scale, and changes of rhythm do more than adding a picture to every passage.
+
+## Authoring contract
+
+Create through `pnpm run create -- <id> --project <project> --template image-story --title "Title"`. Keep the generated theme adapter and asset bindings. `ImageStory` is the document root; `ImageStoryPage` accepts a stable `id`, the adapted `theme`, a `layout`, native `title` and optional `eyebrow`, `lead`, `children`, `caption`, and named image props (`image`, `secondary`, `detail`). Each image is `{item:'media-folder-id', fit:'cover', position:{x:0.5,y:0.5}}`; omit fit/position for centered cover. Named media must exist and pass freshness checks. An omitted image prop creates a visible starter placeholder, never a silent blank. `lead` inherits the composition's foreground, including white on image covers. If you add custom `children` over artwork, explicitly choose their foreground against that image too.
+
+Import or generate actual images into the **instance's** `media/<id>/` folder and review them using [Media](../../docs/MEDIA.md). The template and its specimen contain no artwork or prompts; new documents begin with replaceable placeholders. Do not borrow other documents' filesystem paths or bake brand/subject matter into the skeleton.
+
+Image pages are deliberately bounded. Keep their copy short. Adjust `titleStyle` (for example `{fontSize:30}`), change a layout, or make a local variation for a long headline. Put long prose in ordinary OpenDoc `Pages`; add image pages between those flowing sections. The bounded text regions fail preflight if copy clips rather than silently discarding it. Preserve the caller's body typography and spacing. A4/Letter dimensions and colors come from the theme; the composition owns its edge-to-edge geometry. On covers, choose `coverColor` against the actual artwork. A page-background crop is centered; use a local `MediaFrame` composition when exact crop alignment matters.
+
+## Use the primitives outside this template
+
+Use `MediaFrame` from `opendoc` for exact image boxes anywhere. It supports proportional `cover` or `contain`, crop alignment, and `radius` (half a square's width creates a circle). Wrap it in `Figure` for captions or `Block` for an image-only feedback target. Use `Page backgroundMedia="id"` for managed full bleed. See the copyable examples in [Media](../../docs/MEDIA.md). Keep prose and labels native so they remain selectable.
+
+## Lessons already handled by OpenDoc
+
+- Local page-background paths now resolve explicitly. Prefer `backgroundMedia` for provenance and freshness.
+- Native SVG image elements can disappear without failing export. `MediaFrame` prepares the bounded picture through the installed renderer; agents need no base64/filesystem/native-addon helper.
+- Media frames and backgrounds report their use and reject stale generated inputs just like ordinary `Media`.
+- Crop alignment is not anatomical or semantic understanding. Review faces, objects, and focal points. Use `contain` when the whole subject, labels, or evidence must remain visible.
+- Compilation and geometry checks cannot establish image visibility or good composition. Review **every PDF page**, especially the final crop, layering, contrast, captions, and extracted text.
+
+Vary the composition freely to serve the material. Preserve stable block/text identities, accurate image provenance, and the reviewed-PDF workflow.

package/starter/templates/image-story/index.tsx

@@ -0,0 +1,106 @@
+import type { ReactNode } from 'react';
+import * as F from '@formepdf/react';
+import { Block, Document, Heading, MediaFrame, Page, Paragraph, TextSlot, type ImageFrameOptions } from 'opendoc';
+import { themePage, themeType, type DocTheme } from 'opendoc/themes';
+
+export type ImageStoryLayout = 'cover' | 'split-left' | 'split-top' | 'panorama' | 'diptych' | 'collage' | 'overlay';
+export type StoryImage = Pick<ImageFrameOptions, 'fit' | 'position' | 'radius'> & { item: string; alt?: string };
+export interface ImageStoryPageProps {
+  /** A stable identity for this composition, independent of its physical page number. */
+  id: string;
+  theme: DocTheme;
+  layout?: ImageStoryLayout;
+  title: ReactNode;
+  eyebrow?: ReactNode;
+  image?: StoryImage;
+  secondary?: StoryImage;
+  detail?: StoryImage;
+  lead?: ReactNode;
+  children?: ReactNode;
+  caption?: ReactNode;
+  footer?: string;
+  titleStyle?: F.Style;
+  /** Cover text must contrast with the actual artwork. Defaults to white on an image. */
+  coverColor?: string;
+}
+
+export function ImageStory({ children, ...props }: Parameters<typeof Document>[0]) {
+  return <Document {...props}>{children}</Document>;
+}
+
+type Box = { x: number; y: number; w: number; h: number };
+const boxStyle = ({x,y,w,h}: Box): F.Style => ({ position: 'absolute', left: x, top: y, width: w, height: h });
+
+/** An omitted image is a visible starter placeholder. A supplied, broken media item is an error. */
+function Picture({id, image, box, theme, backdrop=false}: {id:string;image?:StoryImage;box:Box;theme:DocTheme;backdrop?:boolean}) {
+  return <Block id={id} style={boxStyle(box)}>
+    {image ? <MediaFrame {...image} width={box.w} height={box.h}/> : <F.View style={{width:box.w,height:box.h,backgroundColor:theme.line,alignItems:backdrop?'flex-end':'center',justifyContent:backdrop?'flex-start':'center',padding:backdrop?24:0}}>
+      <F.Text style={{fontFamily:theme.body,fontSize:10,color:theme.ink}}>Image position</F.Text>
+    </F.View>}
+  </Block>;
+}
+
+/** Bounded editorial pages, paired with ordinary Pages for long, naturally flowing content. */
+export function ImageStoryPage({id,theme,layout='split-left',title,eyebrow,image,secondary,detail,lead,children,caption,footer='IMAGE STORY',titleStyle,coverColor}: ImageStoryPageProps) {
+  if (!['cover','split-left','split-top','panorama','diptych','collage','overlay'].includes(layout)) throw new Error(`Unknown image-story layout: ${layout}.`);
+  const page = themePage(theme);
+  const W = page.size === 'Letter' ? 612 : 595.28, H = page.size === 'Letter' ? 792 : 841.89;
+  const full = layout === 'cover' || layout === 'overlay';
+  const foreground = layout === 'cover' && image ? coverColor ?? '#ffffff' : theme.ink;
+  const footerColor = full && image ? coverColor ?? '#ffffff' : theme.muted;
+  const picture = (slot:string, source:StoryImage|undefined, box:Box, backdrop=false) => <Picture id={`${id}-${slot}`} image={source} box={box} theme={theme} backdrop={backdrop}/>;
+  const prose = <>{lead && <Paragraph id={`${id}-lead`} style={{color:foreground}}><TextSlot slot="lead" from="lead">{lead}</TextSlot></Paragraph>}{children}</>;
+  const text = (box:Box, size:number, body:ReactNode=prose) => <F.View style={{...boxStyle(box),overflow:'hidden'}}>
+    {eyebrow && <Paragraph id={`${id}-eyebrow`} role="label" baseStyle={{marginBottom:18}} style={{color:foreground}}><TextSlot slot="eyebrow" from="eyebrow">{eyebrow}</TextSlot></Paragraph>}
+    <Heading id={`${id}-title`} level={layout==='cover'?1:2} baseStyle={{fontSize:size,lineHeight:1.08,marginTop:0,marginBottom:22}} style={{color:foreground,...titleStyle}}><TextSlot slot="title" from="title">{title}</TextSlot></Heading>
+    <F.View style={{color:foreground}}>{body}</F.View>
+  </F.View>;
+  const body = (box:Box) => <F.View style={{...boxStyle(box),overflow:'hidden'}}>{prose}</F.View>;
+  const note = (box:Box) => caption && <F.View style={{...boxStyle(box),overflow:'hidden'}}><Paragraph id={`${id}-caption`} role="caption" style={{marginBottom:0}}><TextSlot slot="caption" from="caption">{caption}</TextSlot></Paragraph></F.View>;
+  return <Page size={page.size} margin={0} style={{...page.style,lineBreaking:'greedy',backgroundColor:theme.paper}}
+    backgroundMedia={full ? image?.item : undefined} backgroundSize="cover" backgroundPosition="center">
+    {layout === 'cover' && <>
+      {!image && picture('image',undefined,{x:0,y:0,w:W,h:H},true)}
+      {text({x:42,y:H*.23,w:W-110,h:H*.65},56)}
+    </>}
+    {layout === 'split-left' && <>
+      {picture('image',image,{x:0,y:0,w:W/2,h:H})}
+      {text({x:W/2+28,y:H*.22,w:W/2-56,h:H*.66},36)}
+    </>}
+    {layout === 'split-top' && <>
+      {picture('image',image,{x:0,y:0,w:W,h:H/2})}
+      {text({x:42,y:H/2+30,w:W-84,h:H/2-100},40)}
+    </>}
+    {layout === 'panorama' && <>
+      {text({x:42,y:67,w:W-84,h:H*.22},43,null)}
+      {picture('image',image,{x:0,y:H*.32,w:W,h:H*.2})}
+      <F.View style={{position:'absolute',left:W-241,top:H*.47,width:211,height:211,backgroundColor:theme.paper}}/>
+      {picture('secondary',secondary,{x:W-229,y:H*.47+12,w:187,h:187})}
+      {body({x:42,y:H*.57,w:W-313,h:H*.32})}
+      {note({x:W-229,y:H*.47+222,w:187,h:H*.16})}
+    </>}
+    {layout === 'diptych' && <>
+      {text({x:42,y:67,w:W-84,h:H*.2},43,null)}
+      {picture('image',image,{x:42,y:H*.29,w:(W-100)*.30,h:H*.43})}
+      {picture('secondary',secondary,{x:58+(W-100)*.30,y:H*.29,w:(W-100)*.70,h:H*.43})}
+      {body({x:42,y:H*.77,w:W-84,h:H*.15})}
+    </>}
+    {layout === 'collage' && <>
+      {text({x:42,y:67,w:W-84,h:H*.15},43,null)}
+      {picture('image',image,{x:42,y:H*.22,w:W*.365,h:H*.455})}
+      {picture('secondary',secondary,{x:W*.465,y:H*.22,w:W*.535-42,h:W*.535-42})}
+      {body({x:W*.465,y:H*.22+W*.535-24,w:W*.535-42,h:60})}
+      {picture('detail',detail,{x:W*.26,y:H*.67,w:W*.74-42,h:H*.17})}
+      {note({x:42,y:H*.875,w:W-84,h:H*.07})}
+    </>}
+    {layout === 'overlay' && <>
+      {!image && picture('image',undefined,{x:0,y:0,w:W,h:H},true)}
+      <F.View style={{position:'absolute',left:42,top:H*.28,width:W*.60,height:H*.59,backgroundColor:theme.paper}}/>
+      {text({x:68,y:H*.28+28,w:W*.60-52,h:H*.59-56},44)}
+    </>}
+    {theme.runningFooter && <F.View style={{position:'absolute',left:layout==='split-left'?W/2+28:42,top:H-34,width:layout==='split-left'?W/2-56:W-84,flexDirection:'row',justifyContent:'space-between'}}>
+      <F.Text style={{...themeType(theme,'small',{fontFamily:theme.body,fontSize:8}),color:footerColor}}>{footer}</F.Text>
+      <F.Text style={{...themeType(theme,'small',{fontFamily:theme.body,fontSize:8}),color:footerColor}}>{'{{pageNumber}}'}</F.Text>
+    </F.View>}
+  </Page>;
+}

package/starter/templates/image-story/preview.tsx

@@ -0,0 +1,33 @@
+import { ImageStory, ImageStoryPage, type ImageStoryLayout } from './index';
+import { Pages, Paragraph, Section } from 'opendoc';
+import { neutral } from '../../themes';
+import { type DocTheme } from 'opendoc/themes';
+
+export const meta = { title: 'Image story', description: 'A neutral layout skeleton. All text and image positions are replaceable placeholders.', kind: 'layout specimen', theme: 'neutral' };
+const layouts: {id:ImageStoryLayout; title:string; copy:string}[] = [
+  {id:'cover',title:'Document title\ngoes here.',copy:'Subtitle placeholder. Replace with a brief introduction and choose artwork with enough quiet space for the title.'},
+  {id:'split-left',title:'Feature title\ngoes here.',copy:'Lead paragraph placeholder. Replace this text with a short introduction alongside a portrait image.'},
+  {id:'split-top',title:'Section title\ngoes here.',copy:'Introductory paragraph placeholder. Replace with the context the reader needs after viewing the opening image.'},
+  {id:'panorama',title:'Section title goes here.',copy:'Body text placeholder. Explain the relationship between the panoramic image and the smaller inset.'},
+  {id:'diptych',title:'Comparison title\ngoes here.',copy:'Body text placeholder. Describe the two images or viewpoints and why they belong together.'},
+  {id:'collage',title:'Section title goes here.',copy:'Short text placeholder connecting the three image positions.'},
+  {id:'overlay',title:'Feature title\ngoes here.',copy:'Body text placeholder. Replace with concise writing placed on an opaque surface over your chosen image.'},
+];
+
+export function Specimen({length='typical',theme=neutral}: {length?:'sparse'|'typical'|'long';theme?:DocTheme} = {}) {
+  const sparse = length === 'sparse', long = length === 'long';
+  return <ImageStory title={meta.title} theme={theme}>
+    {(sparse || long ? layouts.filter(item=>item.id==='split-top') : layouts).map(item=><ImageStoryPage key={item.id} id={`sample-${item.id}`} theme={theme} layout={item.id}
+      title={long && item.id==='split-top' ? 'A longer editorial title can change the composition without changing the story' : item.title}
+      titleStyle={long && item.id==='split-top' ? {fontSize:29} : undefined}
+      eyebrow={sparse ? undefined : item.id.replaceAll('-',' ').toUpperCase()}
+      caption="Caption placeholder. Describe the image and provide attribution where appropriate."
+      lead={sparse ? undefined : item.copy}/>)}
+    {long && <Pages title="The story continues">
+      <Section id="long-opening" title="Let the prose flow" lead="Image compositions are moments within a longer document, not containers for every paragraph.">
+        {Array.from({length:20},(_,index)=><Paragraph key={index} id={`long-passage-${index+1}`}>{'This is illustrative prose used to demonstrate native pagination. The writing keeps its normal size and reading rhythm while the surrounding image pages remain deliberate pauses. '.repeat(4)}{index===19?' END OF STORY':''}</Paragraph>)}
+      </Section>
+    </Pages>}
+  </ImageStory>;
+}
+export default Specimen;

package/starter/templates/image-story/starter.tsx

@@ -0,0 +1,24 @@
+import { ImageStory, ImageStoryPage } from '../../templates/image-story';
+import { Pages, Paragraph, Section } 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__";
+export const meta = { title, description: 'An image-led document, ready for your material.', kind: 'illustrated feature', theme: "__OPENDOC_THEME__" };
+export const provenance = { template: 'templates/image-story/index.tsx' };
+
+export default function Story() {
+  return <ImageStory title={title} theme={theme}>
+    {/* Import and review document-owned media, then add image={{item:'your-image'}}.
+        Missing image props intentionally show a placeholder; named items must exist.
+        Choose split-top for a longer title, or adjust titleStyle after reviewing the PDF. */}
+    <ImageStoryPage id="opening" theme={theme} layout="split-top" title={title} eyebrow="ILLUSTRATED FEATURE">
+      <Paragraph id="opening-lead">Replace this placeholder with a short introduction. Choose an image that adds meaning to the story and a crop that preserves its subject.</Paragraph>
+    </ImageStoryPage>
+    <Pages title={title}>
+      <Section id="story" title="Continue the story" lead="Long passages belong in ordinary flowing pages.">
+        <Paragraph id="story-opening">Replace this placeholder with your material. Add selected image-story compositions where they help the reader, using stable IDs and document-owned images. There is no required sequence or page count.</Paragraph>
+      </Section>
+    </Pages>
+  </ImageStory>;
+}

package/starter/templates/image-story/template.json

@@ -0,0 +1,13 @@
+{
+  "name": "Image story",
+  "description": "Image-led editorial pages: full-bleed covers, half-page splits, panoramas with insets, diptychs, collage, and floating text panels. Mix selected compositions with flowing prose.",
+  "format": "A4 or Letter · Flexible image compositions",
+  "structure": [
+    "Replaceable image and text placeholders only; artwork belongs to each document and appearance comes from its theme.",
+    "Choose individual compositions; the specimen is a menu, not a required seven-page sequence.",
+    "Managed image frames support proportional crops, containment, alignment, and rounded or circular windows.",
+    "Covers and overlays use reliable full-page managed artwork with native selectable text.",
+    "Bounded feature pages carry concise copy; ordinary Pages carry long prose and references.",
+    "Theme typography, paper, and colors remain live. Adapt title sizes and image balance for the material."
+  ]
+}

package/starter/templates/invoice/AGENTS.md

@@ -0,0 +1,13 @@
+# Invoice
+
+Use this as a soft foundation for an invoice, with room for variation and creativity. The starting composition makes the amount due easy to find, keeps references and dates near the opening, and gives the itemized charges enough width to read. Seller and customer details share a row; payment details and supporting notes follow the pricing. Adapt the title size, spacing, and emphasis to the business and content. A long title may use a smaller `titleStyle`; a simple invoice may omit a project reference, introduction, or notes.
+
+Each invoice owns its `data.json`; the shared template owns layout and the caller's theme owns visual hierarchy, rhythm, and component treatments. Keep variations for one document local or preserve existing shared defaults. Do not add signature or acceptance fields merely because the quotation has them. No invoice status, overdue label, payment deadline, or payment event is inferred from the current date. Use supplied dates and recorded payment amounts only.
+
+Preserve validation, stable IDs, and calculated pricing. Quantities and amounts are decimal strings, currency precision is explicit, and the documented half-up rounding sequence applies. `amountPaid` is a supplied cumulative payment, not a discount; it reduces the balance after tax. Omission starts a new invoice with no recorded payments. Do not type a competing balance into prose or invent bank details. A zero balance does not trigger a fabricated receipt or payment date.
+
+The current contract supports one currency, an optional fixed discount, one supplied tax rate on the discounted subtotal, and payments up to the invoice total. Credits, overpayments, inclusive tax, mixed rates, and other accounting cases need explicit contract extensions. This is a generic invoice format; do not label it compliant with a particular jurisdiction or an electronic-invoicing system without doing that separate work. Sample parties, prices, dates, and payment instructions remain visibly illustrative until replaced with supplied facts.
+
+Use native Forme flow and existing OpenDoc blocks. Keep totals together and let tables, instructions, and notes continue across pages. Keep party details bounded; longer explanations belong in the introduction or notes. Do not manually split lines, force one page, auto-shrink content, or modify the renderer. Review every adapted PDF. Shared changes need sparse, typical, and long data, another theme, zero/partial/full payment checks, currency precision checks, a working instance, and confirmation that quotation pricing remains unchanged. Preserve unrelated work.
+
+The opening logo placeholder is an adaptable brand slot. Replace it with supplied, proportionally sized artwork through `logo`, or pass null to omit it. Do not invent a real company logo or alter its colors to match a theme. Keep the stable logo block ID and check the opening and downstream page breaks after replacement.

package/starter/templates/invoice/README.md

@@ -0,0 +1,40 @@
+# Invoice
+
+A native Forme invoice with a prominent amount due, invoice references and dates, paired seller/customer details, line items, calculated totals, and optional payment instructions. Defaults are A4 portrait, 48-point top/side and 52-point bottom margins, 10.5/14.7-point body text, a 28-point title, and a larger opening balance. The caller's theme supplies appearance. Treat the composition as an adaptable starting point; no page count is enforced.
+
+`invoiceTemplate(theme)` uses the existing `parse`, `meta`, and `render` contract. Bind it to the instance's `data.json` with `bindTemplate`. The catalog creates a separate data file for each invoice and records template/data provenance. Editing that file updates content, metadata, and calculations. `Invoice` accepts parsed `data`, `theme`, and optional native `titleStyle` for a local design variation. The catalog preview uses Neutral.
+
+## Data contract
+
+Required fields are `schemaVersion: 1`, `title`, `number`, `issuedOn`, `seller`, `customer`, `synthetic`, and `pricing`. Optional `dueOn` is a real date on or after the issue date. All dates use `YYYY-MM-DD`; dates and status are not inferred from today's clock. Optional `reference` can identify a supplied purchase order, quotation, or project reference.
+
+Each party has a required single-line `name` of up to 180 characters and optional `details` of up to 700 characters and eight supplied lines. Names and address/contact details wrap naturally in the paired columns. Supplied registration or tax identifiers can appear in these details when appropriate. This generic format does not certify regulatory or electronic-invoicing compliance.
+
+Optional `introduction`, `paymentInstructions`, and `paymentReference` provide supplied prose and remittance details. No bank account is invented. Optional `notes` is an array of `{ id, title, text }` with unique stable IDs. Notes have stable length-prefixed comment targets, while the item table remains one target through pagination. Unknown fields and unsupported amounts fail clearly.
+
+`synthetic` must be explicit. All bundled examples mark their parties, prices, dates, payment details, and recorded payments as illustrative. Set it to false only after replacing the samples with real supplied material. The template does not send invoices or execute payments.
+
+## Pricing and payments
+
+The pricing contract and rounding rules are shared with [Quotation](../quotation/README.md): decimal-string quantities and amounts, explicit currency precision from 0 to 3, each line rounded half up, a fixed discount subtracted from the subtotal, then one supplied tax rate applied to that net subtotal and rounded half up. No tax rate is inferred. The example's 10% is illustrative only.
+
+Optional `amountPaid` is the cumulative amount already received, as a nonnegative decimal string with no more fractional digits than the currency allows. Omission means no payment has been recorded for this new invoice; the payments row is omitted. An explicit `"0.00"` displays a zero-payment row. A supplied payment may cover the whole invoice but cannot exceed it. Amounts must fit within `Number.MAX_SAFE_INTEGER` minor units, although arithmetic uses BigInt throughout.
+
+`calculateInvoice` returns the shared totals, `paidMinor`, and `balanceMinor`. Payments are subtracted **after** discounts and tax; they never change taxable pricing. The opening and final amount due use the same calculated balance. The typical example is USD 1,320.00 total − USD 320.00 received = USD 1,000.00 due. A full payment produces a zero balance without generating an unverified status, receipt, or payment date.
+
+Credits, overpayments, multiple tax rates, inclusive tax, additional charges, and payment-history reconciliation are outside this version's data contract. Extend them explicitly rather than putting a contradictory total in a note. Long tables repeat headers, totals stay together, and long payment instructions or notes remain normal flowing paragraphs. See [AGENTS.md](AGENTS.md) for design flexibility and preservation requirements.
+
+## Logo
+
+The opening has a quiet, outlined **YOUR LOGO** placeholder at the upper right. It appears once, on the cover when present or at the start of the body. Replace it with supplied artwork through the optional `logo` prop, or pass `logo={null}` to omit it. The placeholder follows the selected theme; actual artwork retains its own colors. Keep logo dimensions bounded and preserve its aspect ratio; 88 × 28 points is a starting size, not a brand requirement.
+
+Import reusable artwork into the shared [asset library](../../docs/ASSETS.md), inspect its variation guidance, and bind an exact version to the intended document:
+
+```sh
+pnpm assets -- inspect logo acme
+pnpm assets -- bind my-document logo acme --variation default
+```
+
+Import `Logo` from `opendoc` and supply `<Logo width={88} height={28} />` through the `logo` prop. Choose a variation for the actual page background, preserve its proportions, and review the PDF. The existing logo block provides the feedback target; a decorative mark needs no figure caption. Artwork belongs in the layout, separately from commercial JSON.
+
+The bound starter accepts `invoiceTemplate(theme, { logo: <Logo width={88} height={28} /> })`; use `{ logo: null }` to omit it. Pass the adapted document theme from `./theme` to this factory.

package/starter/templates/invoice/data.json

@@ -0,0 +1,61 @@
+{
+  "schemaVersion": 1,
+  "title": "__OPENDOC_TITLE__",
+  "number": "SAMPLE-INV-001",
+  "issuedOn": "2026-09-08",
+  "dueOn": "2026-09-22",
+  "reference": "SAMPLE-Q-001",
+  "seller": {
+    "name": "Example Studio",
+    "details": "Studio address placeholder\nContact details placeholder"
+  },
+  "customer": {
+    "name": "Example Client",
+    "details": "Client address placeholder\nAttention: project contact"
+  },
+  "synthetic": true,
+  "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"
+    }
+  },
+  "amountPaid": "320.00",
+  "paymentInstructions": "Payment details placeholder. Supply the agreed method and verified recipient details before issuing a real invoice.",
+  "paymentReference": "SAMPLE-INV-001",
+  "notes": [
+    {
+      "id": "scope",
+      "title": "Scope note",
+      "text": "Illustrative services only. Replace the sample with the actual goods or services and any necessary supporting details."
+    }
+  ]
+}