@ryanyahya/opendoc 0.4.0

package/src/document/page.tsx

@@ -0,0 +1,53 @@
+import { deflateSync } from 'node:zlib';
+import { Page as NativePage, parseColor, type PageProps as NativePageProps } from '@formepdf/react';
+import { readyMedia, mediaUri, framedMedia, pageImage, type ImageFrameOptions } from '../media/render';
+
+export interface PageProps extends NativePageProps {
+  /** Document-owned media item; includes freshness checks and rendered usage tracking. */
+  backgroundMedia?: string;
+}
+
+function crc32(bytes: Uint8Array) {
+  let crc = 0xffffffff;
+  for (const byte of bytes) {
+    crc ^= byte;
+    for (let bit = 0; bit < 8; bit++) crc = (crc >>> 1) ^ (crc & 1 ? 0xedb88320 : 0);
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+/** A tiny lossless image uses the renderer's actual full-page background layer. */
+function solidBackground(input: string) {
+  const color = ({ white: '#ffffff', black: '#000000', transparent: '#00000000' } as Record<string, string>)[input.toLowerCase()] ?? input;
+  if (!/^#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(color) && !/^rgba?\([\d.,\s]+\)$/i.test(color)) throw new Error('Page backgroundColor needs a hex or rgb/rgba color.');
+  const { r, g, b, a } = parseColor(color);
+  if ([r, g, b, a].some(channel => !Number.isFinite(channel) || channel < 0 || channel > 1)) throw new Error('Page backgroundColor contains an invalid color channel.');
+  const chunk = (type: string, data: Buffer) => {
+    const name = Buffer.from(type), length = Buffer.alloc(4), checksum = Buffer.alloc(4);
+    length.writeUInt32BE(data.length);
+    checksum.writeUInt32BE(crc32(Buffer.concat([name, data])));
+    return Buffer.concat([length, name, data, checksum]);
+  };
+  const header = Buffer.alloc(13);
+  header.writeUInt32BE(1, 0); header.writeUInt32BE(1, 4); header[8] = 8; header[9] = 6;
+  const pixel = Buffer.from([0, ...[r, g, b, a].map(channel => Math.round(channel * 255))]);
+  const png = Buffer.concat([Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]), chunk('IHDR', header), chunk('IDAT', deflateSync(pixel)), chunk('IEND', Buffer.alloc(0))]);
+  return `data:image/png;base64,${png.toString('base64')}`;
+}
+
+/** Native flow and geometry, with backgroundColor painted behind every continuation page. */
+export function Page({ style, backgroundImage, backgroundMedia, ...props }: PageProps) {
+  if (backgroundMedia !== undefined && backgroundImage !== undefined) throw new Error('Page accepts either backgroundMedia or backgroundImage, not both.');
+  const sizes = {A4: [595.28, 841.89], A3: [841.89, 1190.55], A5: [419.53, 595.28], Letter: [612, 792], Legal: [612, 1008], Tabloid: [792, 1224]} as const;
+  const size = props.size ?? 'A4';
+  const [width, height] = typeof size === 'string' ? sizes[size] : [size.width, size.height];
+  const fit = props.backgroundSize ?? (backgroundMedia !== undefined ? 'cover' : 'fill');
+  const positions = {'center': {x: .5, y: .5}, 'top-left': {x: 0, y: 0}, 'top-right': {x: 1, y: 0}, 'bottom-left': {x: 0, y: 1}, 'bottom-right': {x: 1, y: 1}};
+  const frame: ImageFrameOptions | undefined = fit === 'fill' ? undefined : {width, height, fit, position: positions[props.backgroundPosition ?? 'center']};
+  const asset = backgroundMedia !== undefined ? readyMedia(backgroundMedia) : undefined;
+  // The native background layer stretches its bitmap. Prepare cover/contain at the page ratio first.
+  const image = asset ? (frame ? framedMedia(asset, frame) : mediaUri(asset)) : backgroundImage !== undefined ? pageImage(backgroundImage, frame) : undefined;
+  if (style?.backgroundColor === undefined || image !== undefined) return <NativePage {...props} backgroundImage={image} style={style} />;
+  const { backgroundColor, ...contentStyle } = style;
+  return <NativePage {...props} style={contentStyle} backgroundImage={solidBackground(backgroundColor)} backgroundSize="fill" backgroundPosition="center" />;
+}

package/src/document/text-targets.tsx

@@ -0,0 +1,162 @@
+import React, { createElement, isValidElement, type ReactElement, type ReactNode } from 'react';
+import * as F from '@formepdf/react';
+import type { SourceLocation } from '../shared/types';
+import type { TextRun, TextSourceValue, TextTarget } from '../shared/selection';
+
+export type TextFieldPath = (string | { id: string })[];
+export interface TextSlotProps {
+  /** Stable content name, independent of pagination and array order. */
+  slot: string;
+  /** A literal prop on the calling component. */
+  from?: string;
+  /** A string in the instance's provenance.dataFile; arrays use record IDs. */
+  field?: TextFieldPath;
+  /** Internal offset when a native block groups its authored children. */
+  childIndex?: number;
+  /** Set false for a generated slot whose identity depends on array position. */
+  stable?: boolean;
+  reason?: string;
+  children?: ReactNode;
+}
+
+/** Transparent source provenance. It introduces no text, styles, or PDF nodes. */
+export function TextSlot({ children }: TextSlotProps) { return <>{children}</>; }
+
+export type TextResolution = (location: SourceLocation, slot: string, childIndex?: number) => TextSourceValue | undefined;
+export type TextGlobals = typeof globalThis & {
+  __opendocResolveTextSource?: TextResolution;
+  __opendocResolveTextField?: (field: TextFieldPath) => TextSourceValue | undefined;
+};
+type Binding = { slot?: string; source?: TextSourceValue; origin?: SourceLocation; from?: string; childIndex?: number; stable?: boolean; protected?: boolean; reason?: string };
+const textTypes = new Set<unknown>([F.Text, F.H1, F.H2, F.H3, F.H4, F.H5, F.H6]);
+
+function rawText(node: ReactNode): string {
+  if (typeof node === 'string' || typeof node === 'number') return String(node);
+  if (Array.isArray(node)) return node.map(rawText).join('');
+  return isValidElement<{ children?: ReactNode }>(node) ? rawText(node.props.children) : '';
+}
+
+/** Capture authored leaves before Forme flattens inline runs into text lines. */
+export class TextCapture {
+  private bindings = new WeakMap<object, Binding>();
+  private origins = new WeakMap<object, SourceLocation>();
+  constructor(private sourceMap: WeakMap<object, SourceLocation>) {}
+
+  remember(element: object, source?: SourceLocation) { if (source) this.origins.set(element, source); }
+  copy(from: object, to: object) {
+    const binding = this.bindings.get(from), origin = this.origins.get(from);
+    if (binding) this.bindings.set(to, binding);
+    if (origin) this.origins.set(to, origin);
+  }
+  wrap(children: ReactNode, props: TextSlotProps, caller?: SourceLocation): ReactElement {
+    if (typeof props.slot !== 'string' || !props.slot.trim()) throw new Error('TextSlot needs a nonempty stable content name.');
+    const globals = globalThis as TextGlobals;
+    const source = props.field ? globals.__opendocResolveTextField?.(props.field)
+      : props.from && props.from !== 'children' && caller ? globals.__opendocResolveTextSource?.(caller, props.from) : undefined;
+    const marker = createElement(React.Fragment, {}, children);
+    this.bindings.set(marker, { slot: props.slot, source, origin: caller, from: props.from, childIndex: props.childIndex, stable: props.stable, reason: props.reason, protected: !!props.reason });
+    return marker;
+  }
+  protect(children: ReactNode, reason: string): ReactElement {
+    const marker = createElement(React.Fragment, {}, children);
+    this.bindings.set(marker, { protected: true, reason });
+    return marker;
+  }
+
+  complete(root: ReactNode): { element: ReactElement; textTargets: TextTarget[] } {
+    const textTargets: TextTarget[] = [];
+    const counts = new Map<string, number>();
+    const used = new Set<string>();
+    const identities = new Map<TextTarget, { named: boolean; key: string }>();
+    const globals = globalThis as TextGlobals;
+    const resolve = (location: SourceLocation | undefined, slot: string, childIndex?: number) => location ? globals.__opendocResolveTextSource?.(location, slot, childIndex) : undefined;
+    const containsProtected = (node: ReactNode): boolean => {
+      if (Array.isArray(node)) return node.some(containsProtected);
+      if (!isValidElement<{ children?: ReactNode }>(node)) return false;
+      return !!this.bindings.get(node)?.protected || containsProtected(node.props.children);
+    };
+
+    const gather = (node: ReactNode, runs: TextRun[], buffer: { text: string }, inherited?: Binding, source?: TextSourceValue) => {
+      if (typeof node === 'string' || typeof node === 'number') {
+        const text = String(node); if (!text) return;
+        const candidate = inherited?.source ?? source;
+        const writable = !inherited?.protected && candidate?.value === text ? candidate : undefined;
+        const start = buffer.text.length; buffer.text += text;
+        runs.push({ start, end: buffer.text.length, ...(writable ? { source: writable } : {}),
+          ...(!writable ? { protected: !!inherited?.protected, reason: inherited?.reason ?? 'Ask your agent to change this text.' } : {}) });
+        return;
+      }
+      if (Array.isArray(node)) { node.forEach(child => gather(child, runs, buffer, inherited)); return; }
+      if (!isValidElement<{ children?: ReactNode }>(node)) return;
+      const own = this.bindings.get(node);
+      const binding = inherited?.protected ? inherited : own ? { ...inherited, ...own } : inherited;
+      // A bound scalar may be wrapped by transparent/formatting elements. Keep
+      // it one writable run only when all rendered content is that exact scalar.
+      if (binding?.source && !binding.protected && !containsProtected(node.props.children) && rawText(node.props.children) === binding.source.value) {
+        const start = buffer.text.length; buffer.text += binding.source.value;
+        runs.push({ start, end: buffer.text.length, source: binding.source });
+        return;
+      }
+      const origin = own?.origin ?? this.origins.get(node);
+      const from = own?.from ?? 'children';
+      const children = Array.isArray(node.props.children) ? node.props.children : [node.props.children];
+      children.forEach((child, index) => gather(child, runs, buffer, binding,
+        typeof child === 'string' || typeof child === 'number' ? resolve(origin, from, index + (own?.childIndex ?? 0)) : undefined));
+    };
+    const descendantSlot = (node: ReactNode): Binding | undefined => {
+      if (Array.isArray(node)) {
+        const bindings = node.map(descendantSlot).filter((value): value is Binding => !!value);
+        return bindings.find(binding => !binding.protected) ?? bindings[0];
+      }
+      if (!isValidElement<{ children?: ReactNode }>(node)) return undefined;
+      const binding = this.bindings.get(node), child = descendantSlot(node.props.children);
+      return binding?.slot === 'children' ? child ?? binding : binding?.slot ? binding : child;
+    };
+    const clean = (node: ReactNode, blockId?: string, withinText = false, inherited?: Binding): ReactNode => {
+      if (Array.isArray(node)) return node.map(child => clean(child, blockId, withinText, inherited));
+      if (!isValidElement<{ children?: ReactNode }>(node)) return node;
+      const location = this.sourceMap.get(node);
+      const id = location?.file.startsWith('opendoc:block:') ? location.file.slice(14) : blockId;
+      const own = this.bindings.get(node);
+      const binding = inherited?.protected ? inherited : own ? { ...inherited, ...own } : inherited;
+      if (node.type === React.Fragment) return clean(node.props.children, id, withinText, binding);
+      const textRoot = !withinText && textTypes.has(node.type);
+      let target: TextTarget | undefined;
+      if (textRoot && id) {
+        const count = (counts.get(id) ?? 0) + 1; counts.set(id, count);
+        const named = binding?.slot ? binding : descendantSlot(node.props.children);
+        const slot = named?.slot ?? (count === 1 ? 'children' : `text-${count}`);
+        const key = `${id}:${encodeURIComponent(slot)}`;
+        const runs: TextRun[] = [], buffer = { text: '' };
+        gather(node, runs, buffer, binding);
+        if (buffer.text) {
+          target = { id: used.has(key) ? `${key}:${count}` : key, blockId: id, slot, text: buffer.text, runs, lines: [], stable: named?.stable !== false };
+          used.add(target.id); textTargets.push(target);
+          identities.set(target, { named: !!named?.slot, key });
+          if (!runs.some(run => run.source)) target.reason = runs.find(run => run.reason)?.reason;
+        }
+      }
+      const result = createElement(node.type, { ...node.props, key: node.key }, clean(node.props.children, id, withinText || textRoot, binding));
+      // Keep block source tags compatible with preflight and fragments; the
+      // synthetic line records which text target owns this native text node.
+      if (target) this.sourceMap.set(result, { file: `opendoc:block:${id}`, line: textTargets.length, column: 1 });
+      else if (location) this.sourceMap.set(result, location);
+      return result;
+    };
+    const element = clean(root) as ReactElement;
+    const slots = new Map<string, TextTarget[]>();
+    for (const target of textTargets) {
+      const identity = identities.get(target)!;
+      if (!identity.named && (counts.get(target.blockId) ?? 0) > 1) target.stable = false;
+      const group = slots.get(identity.key) ?? []; group.push(target); slots.set(identity.key, group);
+    }
+    for (const group of slots.values()) if (group.length > 1) for (const target of group) target.stable = false;
+    const linked = new Map<string, TextSourceValue[]>();
+    for (const target of textTargets) for (const run of target.runs) if (run.source) {
+      const value = run.source, key = `${value.file}:${value.digest}:${value.start}:${value.end}`;
+      const values = linked.get(key) ?? []; values.push(value); linked.set(key, values);
+    }
+    for (const values of linked.values()) for (const value of values) value.linkedOccurrences = Math.max(value.linkedOccurrences ?? 1, values.length);
+    return { element, textTargets };
+  }
+}

package/src/media/files.ts

@@ -0,0 +1,124 @@
+import { readFileSync, realpathSync, lstatSync, statSync, openSync, readSync, closeSync } from 'node:fs';
+import { resolve, relative, sep, extname, basename } from 'node:path';
+import { createHash } from 'node:crypto';
+import type { MediaMeta, MediaKind } from '../shared/media';
+
+export const mediaId = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const kinds: MediaKind[] = ['photo', 'illustration', 'chart', 'diagram', 'image'];
+const fileHashes = new Map<string, {stamp: string; hash: string}>();
+function fileHash(file: string) {
+  const info = statSync(file, {bigint:true});
+  const stamp = `${info.size}:${info.mtimeNs}:${info.ctimeNs}:${info.ino}`;
+  const cached = fileHashes.get(file);
+  if (cached?.stamp === stamp) return cached.hash;
+  const digest = createHash('sha256'), buffer = Buffer.allocUnsafe(64 * 1024);
+  const fd = openSync(file, 'r');
+  try { let count; while ((count = readSync(fd, buffer, 0, buffer.length, null)) > 0) digest.update(buffer.subarray(0,count)); }
+  finally { closeSync(fd); }
+  const after = statSync(file,{bigint:true});
+  if (`${after.size}:${after.mtimeNs}:${after.ctimeNs}:${after.ino}` !== stamp) throw new Error('A source changed while it was being read. Try again after the edit finishes.');
+  const hash = digest.digest('hex');
+  if (fileHashes.size >= 256) fileHashes.delete(fileHashes.keys().next().value!);
+  fileHashes.set(file,{stamp,hash}); return hash;
+}
+export const hashBytes = (bytes: Uint8Array) => createHash('sha256').update(bytes).digest('hex');
+
+export function localPath(value: unknown, label: string): asserts value is string {
+  if (typeof value !== 'string' || !value || value.includes('\\') || value.startsWith('/') || value.split('/').some(part => !part || part === '.' || part === '..' || part.startsWith('.')) || /[\u0000-\u001f]/.test(value)) throw new Error(`${label} must be a relative local path without hidden files or parent traversal.`);
+}
+/** Refuse symlinks as well as paths outside the owning folder. */
+export function ownedFile(directory: string, name: string) {
+  localPath(name, 'File path');
+  const base = realpathSync(directory);
+  let current = base;
+  for (const part of name.split('/')) {
+    current = resolve(current, part);
+    if (lstatSync(current).isSymbolicLink()) throw new Error('Linked files are not supported. Copy the file into the owning document.');
+  }
+  const file = realpathSync(current);
+  const rel = relative(base, file);
+  if (rel === '..' || rel.startsWith(`..${sep}`) || !statSync(file).isFile()) throw new Error('Expected a regular file inside the owning folder.');
+  return file;
+}
+export function mediaDirectory(document: string, id: string) {
+  if (!mediaId.test(id)) throw new Error('Use a lowercase media folder name with single hyphens.');
+  const base = realpathSync(document);
+  const dir = resolve(base, 'media', id);
+  for (const folder of [resolve(base, 'media'), dir]) if (lstatSync(folder).isSymbolicLink() || !lstatSync(folder).isDirectory()) throw new Error('Media must live in ordinary folders inside its document.');
+  return dir;
+}
+export function parseMediaMeta(value: unknown): MediaMeta {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('meta.json must contain a media record.');
+  const v = value as Record<string, unknown>;
+  const keys = ['title', 'description', 'file', 'kind', 'alt', 'sources', 'data', 'recipe', 'attribution'];
+  for (const key of Object.keys(v)) if (!keys.includes(key)) throw new Error(`Unknown media field: ${key}.`);
+  for (const key of ['title', 'description']) if (typeof v[key] !== 'string' || !(v[key] as string).trim() || (v[key] as string).length > (key === 'title' ? 200 : 4000)) throw new Error(`Media ${key} must be nonempty text (${key === 'title' ? 200 : 4000} characters maximum).`);
+  localPath(v.file, 'Media file');
+  if (!['.png', '.jpg', '.jpeg'].includes(extname(v.file).toLowerCase())) throw new Error('The embedding image must be PNG or JPEG. Keep other originals beside it and export a PNG copy.');
+  if (!kinds.includes(v.kind as MediaKind)) throw new Error(`Media kind must be ${kinds.join(', ')}.`);
+  for (const key of ['alt', 'attribution']) if (v[key] !== undefined && (typeof v[key] !== 'string' || !(v[key] as string).trim())) throw new Error(`Media ${key} must be nonempty text when provided.`);
+  for (const key of ['data', 'recipe']) if (v[key] !== undefined) localPath(v[key], `Media ${key}`);
+  if (v.sources !== undefined) {
+    if (!Array.isArray(v.sources)) throw new Error('Media sources must be a list of provenance notes or locations.');
+    for (const source of v.sources) if (typeof source !== 'string' || !source.trim() || source.length > 4000 || /[\u0000-\u001f]/.test(source)) throw new Error('Each source reference must be nonempty text, up to 4,000 characters.');
+    if (new Set(v.sources).size !== v.sources.length) throw new Error('Media source references must be unique.');
+  }
+  return v as unknown as MediaMeta;
+}
+export function imageInfo(bytes: Buffer) {
+  if (bytes.length >= 24 && bytes.subarray(0, 8).equals(Buffer.from([137,80,78,71,13,10,26,10])) && bytes.toString('ascii',12,16) === 'IHDR') {
+    return checkedImage('image/png', bytes.readUInt32BE(16), bytes.readUInt32BE(20));
+  }
+  if (bytes[0] === 255 && bytes[1] === 216) {
+    let offset = 2;
+    while (offset + 4 <= bytes.length) {
+      if (bytes[offset++] !== 255) break;
+      while (bytes[offset] === 255) offset++;
+      const marker = bytes[offset++];
+      if (marker === 217 || marker === 218) break;
+      if (marker === 1 || (marker >= 208 && marker <= 215)) continue;
+      const size = bytes.readUInt16BE(offset);
+      if (size < 2 || offset + size > bytes.length) break;
+      if ([192,193,194,195,197,198,199,201,202,203,205,206,207].includes(marker) && size >= 7) return checkedImage('image/jpeg',bytes.readUInt16BE(offset+5),bytes.readUInt16BE(offset+3));
+      offset += size;
+    }
+  }
+  throw new Error('The image is not a readable PNG or JPEG. Export it again from its original.');
+}
+function checkedImage(mime: string, width: number, height: number) {
+  if (!width || !height || width * height > 100_000_000) throw new Error('Media image dimensions must be positive and no more than 100 megapixels.');
+  return { mime, width, height };
+}
+export function readMedia(document: string, id: string) {
+  const directory = mediaDirectory(document, id);
+  const metaFile = ownedFile(directory, 'meta.json');
+  if (statSync(metaFile).size > 32_000) throw new Error('Keep media metadata below 32 KB.');
+  const meta = parseMediaMeta(JSON.parse(readFileSync(metaFile, 'utf8')));
+  const image = ownedFile(directory, meta.file);
+  if (statSync(image).size > 50_000_000) throw new Error('Keep an embedding image below 50 MB.');
+  const bytes = readFileSync(image);
+  const info = imageInfo(bytes);
+  if (info.mime !== (extname(meta.file).toLowerCase() === '.png' ? 'image/png' : 'image/jpeg')) throw new Error('The image extension does not match its contents.');
+  const inputs: Record<string, string> = Object.create(null);
+  for (const path of [meta.data, meta.recipe]) if (path) inputs[`media/${id}/${path}`] = fileHash(ownedFile(directory, path));
+  return { directory, meta, image, bytes, ...info, hash: hashBytes(bytes), inputs };
+}
+export interface GenerationRecord { version: 1; imageHash: string; inputs: Record<string,string>; recordedAt: string }
+export function mediaFreshness(media: ReturnType<typeof readMedia>) {
+  if (!Object.keys(media.inputs).length) return { freshness: 'original' as const, changedInputs: [] };
+  try {
+    const file = ownedFile(media.directory, 'generation.json');
+    if (statSync(file).size > 64_000) throw new Error('Generation record is too large.');
+    const record = JSON.parse(readFileSync(file, 'utf8')) as GenerationRecord;
+    if (record.version !== 1 || !record.inputs || typeof record.inputs !== 'object' || Array.isArray(record.inputs) || typeof record.imageHash !== 'string') throw new Error('Invalid generation.json. Regenerate and record this image again.');
+    // Older records may include original-source hashes. Those remain historical notes.
+    const prefix = `media/${basename(media.directory)}/`;
+    const recordedInputs = Object.keys(record.inputs).filter(key => key.startsWith(prefix));
+    const changedInputs = [...new Set([...recordedInputs, ...Object.keys(media.inputs)])].filter(key => record.inputs[key] !== media.inputs[key]);
+    if (record.imageHash !== media.hash) changedInputs.push(media.meta.file);
+    return { freshness: changedInputs.length ? 'stale' as const : 'current' as const, changedInputs };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { freshness: 'unrecorded' as const, changedInputs: [] };
+    throw error;
+  }
+}

package/src/media/render.ts

@@ -0,0 +1,63 @@
+import { readFileSync, statSync } from 'node:fs';
+import { Resvg } from '@resvg/resvg-js';
+import { resolve } from 'node:path';
+import { imageInfo, readMedia, mediaFreshness } from './files';
+
+type RenderGlobals = typeof globalThis & { __opendocRoot?: string; __opendocDocumentDirectory?: string };
+const globals = globalThis as RenderGlobals;
+
+/** The same source and freshness contract serves ordinary media, frames, and page backgrounds. */
+export function readyMedia(item: string) {
+  if (!globals.__opendocDocumentDirectory) throw new Error('Media must render inside an OpenDoc document.');
+  const asset = readMedia(globals.__opendocDocumentDirectory, item);
+  const status = mediaFreshness(asset);
+  if (status.freshness === 'stale') throw new Error(`Media "${item}" needs regeneration: ${status.changedInputs.join(', ')} changed. Generate and review the image, then run npx opendoc media record <document> ${item}.`);
+  if (status.freshness === 'unrecorded') throw new Error(`Media "${item}" has inputs but no generation record. Generate and review it, then run npx opendoc media record <document> ${item}.`);
+  return asset;
+}
+
+export const mediaUri = (asset: { mime: string; bytes: Buffer }) => `data:${asset.mime};base64,${asset.bytes.toString('base64')}`;
+
+export interface ImageFrameOptions {
+  width: number;
+  height: number;
+  fit?: 'cover' | 'contain';
+  /** Crop/alignment: 0 is left/top, 0.5 is center, 1 is right/bottom. */
+  position?: { x: number; y: number };
+  /** Points; half the side of a square makes a circular image. */
+  radius?: number;
+}
+
+/** Rasterize only the bounded image frame, never the surrounding PDF text or original file. */
+export function framedMedia(asset: {bytes: Buffer; mime: string; width: number; height: number}, { width, height, fit = 'cover', position = { x: 0.5, y: 0.5 }, radius = 0 }: ImageFrameOptions) {
+  if (![width, height].every(value => Number.isFinite(value) && value > 0)) throw new Error('MediaFrame needs positive width and height in points.');
+  if (!['cover', 'contain'].includes(fit)) throw new Error('MediaFrame fit must be cover or contain.');
+  if (!position || ![position.x, position.y].every(value => Number.isFinite(value) && value >= 0 && value <= 1)) throw new Error('MediaFrame position needs x and y between 0 and 1.');
+  if (!Number.isFinite(radius) || radius < 0 || radius > Math.min(width, height) / 2) throw new Error('MediaFrame radius must be between zero and half the shorter side.');
+  const scale = (fit === 'cover' ? Math.max : Math.min)(width / asset.width, height / asset.height);
+  const w = asset.width * scale, h = asset.height * scale;
+  const x = (width - w) * position.x, y = (height - h) * position.y;
+  // Authoring resolution keeps this native addon in the installed runtime.
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}"><defs><clipPath id="frame"><rect width="${width}" height="${height}" rx="${radius}"/></clipPath></defs><g clip-path="url(#frame)"><image href="${mediaUri(asset)}" x="${x}" y="${y}" width="${w}" height="${h}"/></g></svg>`;
+  // 216 dpi at ordinary page sizes, bounded to avoid oversized intermediate bitmaps.
+  const outputScale = Math.min(3, 4096 / Math.max(width, height));
+  const bytes = new Resvg(svg, { fitTo: { mode: 'width', value: Math.max(1, Math.ceil(width * outputScale)) } }).render().asPng();
+  return mediaUri({ mime: 'image/png', bytes });
+}
+
+/** Native background paths bypass Forme's normal image resolver. Resolve local files explicitly. */
+export function pageImage(source: string, frame?: ImageFrameOptions) {
+  if (/^https?:/i.test(source)) return source;
+  if (/^data:/i.test(source)) {
+    if (!frame) return source;
+    const match = /^data:image\/(?:png|jpeg);base64,(.+)$/is.exec(source);
+    if (!match) throw new Error('Proportional page backgrounds need a PNG or JPEG base64 data URI.');
+    const bytes = Buffer.from(match[1], 'base64');
+    return framedMedia({bytes, ...imageInfo(bytes)}, frame);
+  }
+  const file = resolve(globals.__opendocDocumentDirectory ?? process.cwd(), source);
+  if (statSync(file).size > 50_000_000) throw new Error('Keep a page background image below 50 MB.');
+  const bytes = readFileSync(file);
+  const asset = { bytes, ...imageInfo(bytes) };
+  return frame ? framedMedia(asset, frame) : mediaUri(asset);
+}

package/src/rendering/resolve-sources.ts

@@ -0,0 +1,84 @@
+/**
+ * Asset resolver from @formepdf/renderer 0.20.1, dist/resolve.js.
+ * Copyright (c) 2026 Daniel Molitor. MIT; see vendor/formepdf/LICENSE.
+ * Only TypeScript annotations and formatting differ from upstream. Keeping this
+ * narrow module avoids loading the unrelated HTML compiler in every render.
+ */
+import { readFile } from 'node:fs/promises';
+import { resolve, extname } from 'node:path';
+
+interface AssetNode {
+  kind?: { type?: string; src?: unknown };
+  children?: AssetNode[];
+}
+
+export function uint8ArrayToBase64(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString('base64');
+}
+
+/// Resolve font sources to base64 strings for the WASM engine.
+/// File paths are resolved relative to `basePath` (defaults to cwd).
+/// Uint8Array values are base64-encoded. Data URIs pass through as-is.
+export async function resolveFontSources(doc: Record<string, unknown>, basePath?: string): Promise<void> {
+  const fonts = doc.fonts as { src?: unknown }[] | undefined;
+  if (!fonts?.length) return;
+  const baseDir = basePath ?? process.cwd();
+  for (const font of fonts) {
+    if (font.src instanceof Uint8Array) {
+      font.src = uint8ArrayToBase64(font.src);
+    } else if (typeof font.src === 'string' && !font.src.startsWith('data:')) {
+      const fontPath = resolve(baseDir, font.src);
+      const bytes = await readFile(fontPath);
+      font.src = uint8ArrayToBase64(new Uint8Array(bytes));
+    }
+  }
+}
+
+const MIME_BY_EXT: Record<string, string> = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.svg': 'image/svg+xml',
+  '.bmp': 'image/bmp',
+  '.ico': 'image/x-icon',
+  '.avif': 'image/avif',
+};
+
+/// Resolve image sources — converts HTTP/HTTPS URLs and local file paths to base64 data URIs.
+/// Walks the document tree recursively. File paths are resolved relative to `basePath`.
+export async function resolveImageSources(doc: Record<string, unknown>, basePath?: string): Promise<void> {
+  const children = doc.children as AssetNode[] | undefined;
+  if (!children?.length) return;
+  await Promise.all(children.map((node) => resolveImageSourcesInNode(node, basePath)));
+}
+
+async function resolveImageSourcesInNode(node: AssetNode, basePath?: string): Promise<void> {
+  const kind = node.kind;
+  if (kind?.type === 'Image' && typeof kind.src === 'string') {
+    const src = kind.src;
+    if (src.startsWith('data:')) {
+      // Already a data URI — pass through.
+    } else if (src.startsWith('http://') || src.startsWith('https://')) {
+      const res = await fetch(src);
+      if (!res.ok) throw new Error(`Failed to fetch image: ${src} (${res.status})`);
+      const contentType = res.headers.get('content-type') || 'image/png';
+      const buf = new Uint8Array(await res.arrayBuffer());
+      kind.src = `data:${contentType};base64,${uint8ArrayToBase64(buf)}`;
+    } else if (basePath) {
+      const filePath = resolve(basePath, src);
+      const ext = extname(filePath).toLowerCase();
+      const mime = MIME_BY_EXT[ext] || 'application/octet-stream';
+      const bytes = await readFile(filePath);
+      kind.src = `data:${mime};base64,${uint8ArrayToBase64(new Uint8Array(bytes))}`;
+    }
+  }
+  const children = node.children;
+  if (children?.length) await Promise.all(children.map((child) => resolveImageSourcesInNode(child, basePath)));
+}
+
+/// Resolve all asset sources (fonts + images) in parallel.
+export async function resolveAllSources(doc: Record<string, unknown>, basePath?: string): Promise<void> {
+  await Promise.all([resolveFontSources(doc, basePath), resolveImageSources(doc, basePath)]);
+}

package/src/runtime/jsx-dev-runtime.ts

@@ -0,0 +1,2 @@
+export { Fragment, jsxDEV } from 'react/jsx-dev-runtime';
+export type { JSX } from 'react/jsx-dev-runtime';

package/src/runtime/jsx-runtime.ts

@@ -0,0 +1,2 @@
+export { Fragment, jsx, jsxs } from 'react/jsx-runtime';
+export type { JSX } from 'react/jsx-runtime';

package/src/runtime/paths.ts

@@ -0,0 +1,12 @@
+import { createRequire } from 'node:module';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** Code and dependencies belong to the installation; authored files belong to the workspace. */
+export const applicationRoot = fileURLToPath(new URL('../../', import.meta.url));
+export const runtimeRequire = createRequire(new URL('../../package.json', import.meta.url));
+export const runtimeResolve = (specifier: string) => {
+  const url = import.meta.resolve(specifier);
+  return url.startsWith('file:') ? fileURLToPath(url) : url;
+};
+export const runtimeSource = (path: string) => resolve(applicationRoot, 'src', path);