@ryanyahya/opendoc-headless 0.4.0

package/docs/TEMPLATES.md

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

package/docs/THEMES.md

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

package/node_modules/@formepdf/core/LICENSE

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

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

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

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

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

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

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

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

@@ -0,0 +1,8 @@
+/**
+ * Extract embedded JSON data from a Forme-generated PDF.
+ *
+ * Scans the PDF bytes for a `forme-data.json` EmbeddedFile attachment,
+ * decompresses the stream, and parses the JSON. Returns `null` if the
+ * PDF doesn't contain embedded data (e.g. non-Forme PDF).
+ */
+export declare function extractData(pdfBytes: Uint8Array): unknown | null;

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

@@ -0,0 +1,56 @@
+import { inflateSync } from 'node:zlib';
+/**
+ * Extract embedded JSON data from a Forme-generated PDF.
+ *
+ * Scans the PDF bytes for a `forme-data.json` EmbeddedFile attachment,
+ * decompresses the stream, and parses the JSON. Returns `null` if the
+ * PDF doesn't contain embedded data (e.g. non-Forme PDF).
+ */
+export function extractData(pdfBytes) {
+    const text = new TextDecoder('latin1').decode(pdfBytes);
+    // Find the FileSpec referencing forme-data.json
+    const fsMatch = text.match(/\/F\s*\(forme-data\.json\)/);
+    if (!fsMatch)
+        return null;
+    // Extract the EmbeddedFile stream object number from /EF << /F N 0 R >>
+    // Search around the FileSpec location for the /EF reference
+    const fsStart = fsMatch.index;
+    const fsRegion = text.slice(Math.max(0, fsStart - 200), fsStart + 200);
+    const efMatch = fsRegion.match(/\/EF\s*<<\s*\/F\s+(\d+)\s+0\s+R\s*>>/);
+    if (!efMatch)
+        return null;
+    const streamObjId = efMatch[1];
+    // Find the stream object: "N 0 obj ... stream\n...\nendstream"
+    const objPattern = new RegExp(streamObjId + '\\s+0\\s+obj\\b');
+    const objMatch = text.match(objPattern);
+    if (!objMatch)
+        return null;
+    const objStart = objMatch.index;
+    // Find stream start (after "stream\r\n" or "stream\n")
+    const streamKeyword = text.indexOf('stream', objStart);
+    if (streamKeyword === -1)
+        return null;
+    let streamDataStart = streamKeyword + 6; // "stream".length
+    // Skip \r\n or \n after "stream"
+    if (pdfBytes[streamDataStart] === 0x0d)
+        streamDataStart++; // \r
+    if (pdfBytes[streamDataStart] === 0x0a)
+        streamDataStart++; // \n
+    // Find endstream
+    const endstreamPos = text.indexOf('\nendstream', streamDataStart);
+    if (endstreamPos === -1)
+        return null;
+    const compressedBytes = pdfBytes.slice(streamDataStart, endstreamPos);
+    // Check if FlateDecode is used
+    const objRegion = text.slice(objStart, streamKeyword);
+    const isCompressed = objRegion.includes('/FlateDecode');
+    let jsonBytes;
+    if (isCompressed) {
+        jsonBytes = inflateSync(Buffer.from(compressedBytes));
+    }
+    else {
+        jsonBytes = compressedBytes;
+    }
+    const jsonString = new TextDecoder('utf-8').decode(jsonBytes);
+    return JSON.parse(jsonString);
+}