@typfolio/core 0.1.0 → 0.2.0

package/README.md

@@ -41,11 +41,22 @@ The font name in the template must match the supplied font. Fonts and WASM are l
 - `copyAssets` (a `createCompiler` option, default `true`): by default `compile` copies every asset when it captures the request, so mutating, reusing, or detaching a buffer after calling `compile` cannot change the result. `copyAssets: false` mounts the caller's `Uint8Array` views as they are and skips that copy, which matters for multi-megabyte assets. The contract then is: the caller must not mutate, detach, or reuse an asset's buffer until the promise returned by `compile` settles. Validation of paths, types, reserved paths and JSON input is identical either way. `@typfolio/workers` sets it inside its workers, where the request arrives as a private transferred copy; set it yourself only when you own the buffers for the duration of the call.
 - `pdf`: zero or one standard, tags, and creation timestamp in Unix seconds. Read `compiler.capabilities` for current support. Unsupported options are rejected.
 - `compile(request, { signal })`: Promise of PDF bytes, diagnostics, and title metadata.
+- A template made with `defineTemplate({ entrypoint?, files, input?, partials? })` takes `{ template, input, partials, assets?, pdf? }`, typed by its schemas (`TemplateRequest<typeof template>`). `defineInput(schema, path)` pairs a [Standard Schema](https://standardschema.dev) (Zod, Valibot, ArkType, …) with the path of its JSON Schema file; `definePartial({ files, input, partials? })` is Typst code with runtime data of its own. Each piece of data is checked against its schema before compiling (`INVALID_INPUT`, with the issues; an asynchronous schema is awaited) and mounted at its schema's path, where its file reads it with `input(json.with(...))`. Such a template compiles only the files it declares; a file it imports without declaring it fails with a message that says what to do. See `docs/template-authoring.md`.
+- `createAttachments()`: `add(bytes, extension)` returns a path such as `/attachments/0.png` to put in the data, and `assets` holds the files for the request. The same bytes added twice share one path.
 - `dispose()`: idempotent; stops new jobs and waits for accepted work.
 
+`createLazyCompiler(options)` takes the same options but is synchronous and returns a `PdfClient`: nothing is downloaded until its first `compile`, which loads the WASM and fonts once for every later call. A failed load is not kept, so the next call tries again, and calls run one at a time in order, so callers never see `BUSY`. Create it once at module level and pass it to `PdfProvider`, or as `usePdf`'s `client`:
+
+```ts
+import { createLazyCompiler } from '@typfolio/core';
+import wasmUrl from '@typfolio/wasm/compiler.wasm?url';
+
+export const pdfClient = createLazyCompiler({ wasm: wasmUrl, fonts: ['/fonts/report.otf'] });
+```
+
 One active call is allowed per compiler. Concurrent calls reject with `TypstPdfError.code === 'BUSY'`. Core does not schedule jobs. A signal can cancel before synchronous execution; hard cancellation requires a worker. Upstream WASM initialization is shared per JS realm: reuse the same `wasm` value for multiple compilers in that realm.
 
-`TypstPdfError` provides `code`, `message`, `diagnostics`, and (when relevant) `cause`. Compile diagnostic ranges use upstream zero-based line/column notation. Export diagnostics can have only text.
+`TypstPdfError` provides `code`, `message`, `diagnostics`, and (when relevant) `cause`. A diagnostic Typfolio recognises carries a `code` of its own (`file-not-found` with `file`, `missing-glyph` with `text`) and a one-line message that links to what to do; switch on the codes, not the messages. [docs/errors.md](../../docs/errors.md) lists them all. Compile diagnostic ranges use upstream zero-based line/column notation. Export diagnostics can have only text.
 
 Remote Typst packages (everything except the bundled one), page ranges, experimental feature flags, and simultaneous PDF standards are not implemented. The pinned upstream builder requires dynamic function construction, so a strict CSP that forbids `unsafe-eval` needs a future binding change. Importing the JS module alone does not instantiate WASM or fetch resources.
 
@@ -58,7 +69,7 @@ Remote Typst packages (everything except the bundled one), page ranges, experime
 #let data = input(json.with("./report.schema.json"))
 ```
 
-Under Typfolio `input()` returns `request.input` and never reads the schema. In an editor (where nothing sets `sys.inputs`) it imports the sample builder from `sample.typ`, inside the function body, and builds a sample from the JSON Schema so completion works; `--input typfolio-sample=minimal` previews the sparse sample instead of the default `full` one. The runtime embeds only `lib.typ`. `compiler.capabilities.typstPackages` is `['@local/typfolio:0.1.0']`; any other `@namespace/name:version` import fails with a `COMPILATION` error that names the supported package. The directory layout is the one Tinymist expects for `--package-path`; see `docs/template-authoring.md` for the editor setting. The shipped `.typ`/`.toml` files are the source of truth: `tools/generate-typst-package.mjs` (the first step of `npm run build`) generates `src/typst-package.generated.ts` (`typst.toml` and `lib.typ`, the runtime module) and `packages/dev-tools/src/sample-source.generated.ts` (`sample.typ`, imported only by `@typfolio/dev-tools`). Neither is edited by hand.
+Under Typfolio `input()` returns `request.input` and never reads the schema; in a template made with `defineTemplate`, it returns the data mounted at the schema's path. In an editor (where nothing sets `sys.inputs`) it imports the sample builder from `sample.typ`, inside the function body, and builds a sample from the JSON Schema so completion works; `--input typfolio-sample=minimal` previews the sparse sample instead of the default `full` one. The runtime embeds only `lib.typ`. `compiler.capabilities.typstPackages` is `['@local/typfolio:0.1.0']`; any other `@namespace/name:version` import fails with a `COMPILATION` error that names the supported package. The directory layout is the one Tinymist expects for `--package-path`; see `docs/template-authoring.md` for the editor setting. The shipped `.typ`/`.toml` files are the source of truth: `tools/generate-typst-package.ts` (the first step of `npm run build`) generates `src/typst-package.generated.ts` (`typst.toml` and `lib.typ`, the runtime module) and `packages/dev-tools/src/sample-source.generated.ts` (`sample.typ`, imported only by `@typfolio/dev-tools`). Neither is edited by hand.
 
 ## Dev-time tools
 
@@ -69,8 +80,8 @@ Tools used while building and testing templates, not while serving requests, liv
 Browser-only helpers live behind separate subpath entries so Node, worker, and server code that imports `@typfolio/core` never loads DOM code. The main entry exports none of them, and none touch browser globals at import time.
 
 - `@typfolio/core/capture`: `captureProps`, `captureAssets`, `TypfolioCaptureError`, and the adapter and result types.
-- `@typfolio/core/capture/svg`: `svgCapture`, a dependency-free adapter that serializes one inline SVG and preserves vector output.
-- `@typfolio/core/capture/dom`: `domPngCapture`, an opt-in PNG fallback for arbitrary DOM. It loads `html2canvas` by dynamic import only when it first runs. `html2canvas` is an optional peer dependency: install it only if you use this adapter. If it is missing when the default rasterizer runs, the capture rejects with `CAPTURE_FAILED` and the import error as `cause`; passing your own `rasterize` never loads it.
+- `@typfolio/core/capture/svg`: `svgCapture`, a dependency-free adapter that serializes one inline SVG and preserves vector output, and `serializeSvg(svg, { fontFamily?, beforeSerialize? })`, the same serializer for an SVG element you already hold. It inlines the computed paint and text styles (chart libraries often style SVGs from page CSS), rewrites `url(#id)` references to be local, writes the drawn size, and returns the file as bytes. The SVG must be in a document and have a rendered size. `beforeSerialize(svg)` runs on the copy just before it is written (remove a tooltip, add a `<title>`); the live SVG is never passed to it. `@typfolio/react`'s `usePdf` uses it for charts.
+- `@typfolio/core/capture/dom`: `domPngCapture`, an opt-in PNG fallback for arbitrary DOM. It loads `html2canvas` by dynamic import only when it first runs. `html2canvas` is an optional peer dependency: install it only if you use this adapter. If it is missing when the default rasterizer runs, the capture rejects with `CAPTURE_FAILED` and the import error as `cause`; passing your own `rasterize` never loads it. `beforeRasterize(element)` runs on html2canvas's copy of the element before it is drawn, never on the live page.
 
 Each marked region owns its adapter `kind` and its alt text. `captureProps` returns the data attributes (`data-typfolio-capture`, `data-typfolio-capture-kind`, and `data-typfolio-capture-alt` or `data-typfolio-capture-decorative`) to spread onto any element. They add no role or accessible name. `@typfolio/react/capture` offers a `CaptureRegion` component over the same attributes; plain DOM and other frameworks can spread `captureProps` directly.
 
@@ -89,7 +100,7 @@ for (const [name, value] of Object.entries(captureProps({
 
 const captured = await captureAssets(document.querySelector('#report'), {
   adapters: {
-    svg: svgCapture({ removeSelectors: ['.chart-tooltip'] }),
+    svg: svgCapture({ beforeSerialize: svg => svg.querySelector('.chart-tooltip')?.remove() }),
     png: domPngCapture({ pixelRatio: 2, backgroundColor: '#fff' }),
   },
   require: ['performance-chart'],

package/dist/capture/dom.d.ts

@@ -5,7 +5,8 @@ export interface DomPngRasterizeOptions {
     readonly useCORS: boolean;
     readonly imageTimeoutMs?: number;
     readonly logging: boolean;
-    readonly removeSelectors: readonly string[];
+    /** Runs on the rasterizer's clone of the element, never on the live page. */
+    readonly beforeRasterize?: (element: HTMLElement) => void;
 }
 export type DomPngRasterizer = (element: HTMLElement, options: DomPngRasterizeOptions) => Promise<HTMLCanvasElement>;
 export interface DomPngCaptureOptions {
@@ -16,8 +17,12 @@ export interface DomPngCaptureOptions {
     readonly useCORS?: boolean;
     readonly imageTimeoutMs?: number;
     readonly logging?: boolean;
-    readonly removeSelectors?: readonly string[];
+    /**
+     * Runs on html2canvas's clone of the element before it is drawn: remove transient parts such
+     * as tooltips or focus rings. The live element on the page is never passed here.
+     */
+    readonly beforeRasterize?: (element: HTMLElement) => void;
     /** Custom-host and test escape hatch. */
     readonly rasterize?: DomPngRasterizer;
 }
-export declare function domPngCapture({ pixelRatio, backgroundColor, useCORS, imageTimeoutMs, logging, removeSelectors, rasterize, }?: DomPngCaptureOptions): CaptureAdapter;
+export declare function domPngCapture({ pixelRatio, backgroundColor, useCORS, imageTimeoutMs, logging, beforeRasterize, rasterize, }?: DomPngCaptureOptions): CaptureAdapter;

package/dist/capture/dom.js

@@ -47,10 +47,7 @@ async function defaultRasterizer(element, options, context) {
         imageTimeout: options.imageTimeoutMs,
         logging: options.logging,
         onclone(_document, clonedElement) {
-            for (const selector of options.removeSelectors) {
-                for (const removable of clonedElement.querySelectorAll(selector))
-                    removable.remove();
-            }
+            options.beforeRasterize?.(clonedElement);
         },
         scale: options.pixelRatio,
         useCORS: options.useCORS,
@@ -77,17 +74,16 @@ function pngBytes(canvas, context) {
         }
     });
 }
-export function domPngCapture({ pixelRatio, backgroundColor, useCORS = false, imageTimeoutMs, logging = false, removeSelectors = [], rasterize, } = {}) {
+export function domPngCapture({ pixelRatio, backgroundColor, useCORS = false, imageTimeoutMs, logging = false, beforeRasterize, rasterize, } = {}) {
     if (pixelRatio !== undefined && (!Number.isFinite(pixelRatio) || pixelRatio <= 0)) {
         throw new TypfolioCaptureError('INVALID_OPTIONS', 'DOM pixelRatio must be greater than zero');
     }
     if (imageTimeoutMs !== undefined && (!Number.isInteger(imageTimeoutMs) || imageTimeoutMs < 0)) {
         throw new TypfolioCaptureError('INVALID_OPTIONS', 'DOM imageTimeoutMs must be a non-negative integer');
     }
-    if (removeSelectors.some(value => !value.trim())) {
-        throw new TypfolioCaptureError('INVALID_OPTIONS', 'DOM removeSelectors must be non-empty');
+    if (beforeRasterize !== undefined && typeof beforeRasterize !== 'function') {
+        throw new TypfolioCaptureError('INVALID_OPTIONS', 'DOM beforeRasterize must be a function');
     }
-    const selectors = Object.freeze([...removeSelectors]);
     return Object.freeze({
         name: 'DOM PNG capture',
         extensions: Object.freeze(['.png']),
@@ -107,7 +103,7 @@ export function domPngCapture({ pixelRatio, backgroundColor, useCORS = false, im
                 useCORS,
                 imageTimeoutMs,
                 logging,
-                removeSelectors: selectors,
+                beforeRasterize,
             };
             const canvas = rasterize === undefined
                 ? await defaultRasterizer(element, rasterizeOptions, context)

package/dist/capture/svg.d.ts

@@ -1,10 +1,23 @@
 import { type CaptureAdapter } from '../capture.js';
-export interface SvgCaptureOptions {
+export interface SvgSerializeOptions {
+    /** Overrides text/tspan fonts only in the serialized clone. */
+    readonly fontFamily?: string;
+    /**
+     * Runs on the clone just before it is serialized, after its styles are inlined and its size
+     * is set: remove transient parts such as tooltips, add a `<title>`, rewrite labels. The live
+     * SVG on the page is never passed here.
+     */
+    readonly beforeSerialize?: (svg: SVGSVGElement) => void;
+}
+export interface SvgCaptureOptions extends SvgSerializeOptions {
     /** Selects exactly one SVG inside the marked region. Defaults to `svg`. */
     readonly selector?: string;
-    /** Overrides text/tspan fonts only in the exported clone. */
-    readonly fontFamily?: string;
-    /** Removes transient descendants such as chart tooltips from the clone. */
-    readonly removeSelectors?: readonly string[];
 }
-export declare function svgCapture({ selector, fontFamily, removeSelectors, }?: SvgCaptureOptions): CaptureAdapter;
+/**
+ * Serializes a drawn SVG as a standalone file: a clone with the computed paint and text styles
+ * inlined (chart libraries often style SVGs from document CSS, which a standalone file does not
+ * have), local `url(#id)` references, and the size it was drawn at. The SVG must be in a
+ * document and have a rendered size.
+ */
+export declare function serializeSvg(svg: SVGSVGElement, options?: SvgSerializeOptions): Uint8Array;
+export declare function svgCapture({ selector, fontFamily, beforeSerialize, }?: SvgCaptureOptions): CaptureAdapter;

package/dist/capture/svg.js

@@ -47,69 +47,88 @@ function findSvg(element, selector, context) {
     }
     return matches[0];
 }
-export function svgCapture({ selector = 'svg', fontFamily, removeSelectors = [], } = {}) {
-    if (!selector.trim()) {
-        throw new TypfolioCaptureError('INVALID_OPTIONS', 'SVG selector must be non-empty');
-    }
+function checkSerializeOptions({ fontFamily, beforeSerialize }) {
     if (fontFamily !== undefined && !fontFamily.trim()) {
         throw new TypfolioCaptureError('INVALID_OPTIONS', 'SVG fontFamily must be non-empty');
     }
-    if (removeSelectors.some(value => !value.trim())) {
-        throw new TypfolioCaptureError('INVALID_OPTIONS', 'SVG removeSelectors must be non-empty');
+    if (beforeSerialize !== undefined && typeof beforeSerialize !== 'function') {
+        throw new TypfolioCaptureError('INVALID_OPTIONS', 'SVG beforeSerialize must be a function');
+    }
+}
+/**
+ * Serializes a drawn SVG as a standalone file: a clone with the computed paint and text styles
+ * inlined (chart libraries often style SVGs from document CSS, which a standalone file does not
+ * have), local `url(#id)` references, and the size it was drawn at. The SVG must be in a
+ * document and have a rendered size.
+ */
+export function serializeSvg(svg, options = {}) {
+    checkSerializeOptions(options);
+    const { fontFamily, beforeSerialize } = options;
+    const view = svg.ownerDocument.defaultView;
+    if (view === null) {
+        throw new TypfolioCaptureError('NOT_READY', 'The SVG document is no longer available');
     }
-    const selectors = [...removeSelectors];
+    const bounds = svg.getBoundingClientRect();
+    if (!(bounds.width > 0) || !(bounds.height > 0)) {
+        throw new TypfolioCaptureError('NOT_READY', 'The SVG has no rendered size');
+    }
+    const cloned = svg.cloneNode(true);
+    if (!isSvg(cloned)) {
+        throw new TypfolioCaptureError('CAPTURE_FAILED', 'The SVG could not be cloned');
+    }
+    const originals = [svg, ...svg.querySelectorAll('*')];
+    const copies = [cloned, ...cloned.querySelectorAll('*')];
+    originals.forEach((original, index) => {
+        const copy = copies[index];
+        const computed = view.getComputedStyle(original);
+        const isText = original.localName === 'text' || original.localName === 'tspan';
+        if (hasStyle(copy)) {
+            for (const property of svgStyles) {
+                const value = computed.getPropertyValue(property);
+                if (value)
+                    copy.style.setProperty(property, value);
+            }
+            if (fontFamily && isText)
+                copy.style.setProperty('font-family', fontFamily);
+        }
+        if (fontFamily && isText)
+            copy.setAttribute('font-family', fontFamily);
+        for (const attribute of copy.attributes) {
+            copy.setAttribute(attribute.name, attribute.value.replace(/url\(["']?[^)#]*#([^)"' ]+)["']?\)/g, 'url(#$1)'));
+        }
+    });
+    for (const removable of cloned.querySelectorAll('script, foreignObject'))
+        removable.remove();
+    cloned.setAttribute('width', String(bounds.width));
+    cloned.setAttribute('height', String(bounds.height));
+    if (!cloned.hasAttribute('viewBox')) {
+        cloned.setAttribute('viewBox', `0 0 ${bounds.width} ${bounds.height}`);
+    }
+    beforeSerialize?.(cloned);
+    // The serializer declares the SVG namespace itself. An `xmlns` attribute on the clone (chart
+    // libraries such as Highcharts set one) can be written a second time: invalid XML.
+    cloned.removeAttribute('xmlns');
+    return encoder.encode(new view.XMLSerializer().serializeToString(cloned));
+}
+export function svgCapture({ selector = 'svg', fontFamily, beforeSerialize, } = {}) {
+    if (!selector.trim()) {
+        throw new TypfolioCaptureError('INVALID_OPTIONS', 'SVG selector must be non-empty');
+    }
+    const serializeOptions = { fontFamily, beforeSerialize };
+    checkSerializeOptions(serializeOptions);
     return Object.freeze({
         name: 'SVG capture',
         extensions: Object.freeze(['.svg']),
         capture(element, context) {
             const svg = findSvg(element, selector, context);
-            const view = svg.ownerDocument.defaultView;
-            if (view === null) {
+            if (svg.ownerDocument.defaultView === null) {
                 throw new TypfolioCaptureError('NOT_READY', 'The SVG document is no longer available', context.captureId, context.path);
             }
             const bounds = svg.getBoundingClientRect();
             if (!(bounds.width > 0) || !(bounds.height > 0)) {
                 throw new TypfolioCaptureError('NOT_READY', `Capture ${context.captureId} has no rendered size`, context.captureId, context.path);
             }
-            const cloned = svg.cloneNode(true);
-            if (!isSvg(cloned)) {
-                throw new TypfolioCaptureError('CAPTURE_FAILED', `Capture ${context.captureId} could not clone its SVG`, context.captureId, context.path);
-            }
-            const originals = [svg, ...svg.querySelectorAll('*')];
-            const copies = [cloned, ...cloned.querySelectorAll('*')];
-            originals.forEach((original, index) => {
-                const copy = copies[index];
-                const computed = view.getComputedStyle(original);
-                if (hasStyle(copy)) {
-                    for (const property of svgStyles) {
-                        const value = computed.getPropertyValue(property);
-                        if (value)
-                            copy.style.setProperty(property, value);
-                    }
-                    if (fontFamily && (original.localName === 'text' || original.localName === 'tspan')) {
-                        copy.style.setProperty('font-family', fontFamily);
-                    }
-                }
-                if (fontFamily && (original.localName === 'text' || original.localName === 'tspan')) {
-                    copy.setAttribute('font-family', fontFamily);
-                }
-                for (const attribute of copy.attributes) {
-                    copy.setAttribute(attribute.name, attribute.value.replace(/url\(["']?[^)#]*#([^)"' ]+)["']?\)/g, 'url(#$1)'));
-                }
-            });
-            for (const removable of cloned.querySelectorAll('script, foreignObject'))
-                removable.remove();
-            for (const removableSelector of selectors) {
-                for (const removable of cloned.querySelectorAll(removableSelector))
-                    removable.remove();
-            }
-            cloned.setAttribute('xmlns', svgNamespace);
-            cloned.setAttribute('width', String(bounds.width));
-            cloned.setAttribute('height', String(bounds.height));
-            if (!cloned.hasAttribute('viewBox')) {
-                cloned.setAttribute('viewBox', `0 0 ${bounds.width} ${bounds.height}`);
-            }
-            return encoder.encode(new view.XMLSerializer().serializeToString(cloned));
+            return serializeSvg(svg, serializeOptions);
         },
     });
 }

package/dist/definition.d.ts

@@ -0,0 +1,156 @@
+import { type PdfOptions, type PdfRequest } from './types.js';
+/**
+ * The Standard Schema interface (https://standardschema.dev), declared here so core depends on no
+ * schema library: Zod, Valibot, ArkType and others implement it.
+ */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly '~standard': {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        } | undefined;
+    };
+}
+export type StandardSchemaResult<Output> = {
+    readonly value: Output;
+    readonly issues?: undefined;
+} | {
+    readonly issues: readonly StandardSchemaIssue[];
+};
+export interface StandardSchemaIssue {
+    readonly message: string;
+    readonly path?: readonly (PropertyKey | {
+        readonly key: PropertyKey;
+    })[] | undefined;
+}
+/** What a schema accepts: the data a caller passes. */
+export type InferSchemaInput<S> = S extends StandardSchemaV1<infer Input, unknown> ? Input : unknown;
+/**
+ * A runtime input of a template or a partial: the data, and where its JSON Schema file sits in the
+ * template's file tree. The Typst file reads it with `input(json.with("./<file>.schema.json"))`: in
+ * an editor that file is the schema (for a sample), and when Typfolio compiles, the data is mounted
+ * at the same path. The path is the input's identity: nothing else names it.
+ */
+export interface TemplateInput<T = unknown> {
+    /** Virtual path of the schema file, relative to the template root, e.g. `common/header.schema.json`. */
+    readonly path: string;
+    /** Validates the data before compiling, and types it. Optional. */
+    readonly schema?: StandardSchemaV1<T, unknown>;
+    /** Type-only. */
+    readonly '~type'?: T;
+}
+/** Pairs a schema with the virtual path of its JSON Schema file. */
+export declare function defineInput<S extends StandardSchemaV1>(schema: S, path: string): TemplateInput<InferSchemaInput<S>>;
+/** Typst code that takes runtime data of its own: its files, its input, and the partials it uses. */
+export interface PartialDefinition<T = unknown, P extends PartialsMap = PartialsMap> {
+    readonly kind: 'typfolio-partial';
+    readonly files: Readonly<Record<string, string>>;
+    readonly input: TemplateInput<T>;
+    readonly partials: P;
+}
+export type PartialsMap = Readonly<Record<string, PartialDefinition<any, any>>>;
+type UnionToIntersection<U> = (U extends unknown ? (arg: U) => void : never) extends (arg: infer I) => void ? I : never;
+/** The data a map of partials needs, nested partials included, by key. */
+export type PartialsData<P extends PartialsMap> = {
+    [K in keyof P]: P[K] extends PartialDefinition<infer T, PartialsMap> ? T : never;
+} & UnionToIntersection<{
+    [K in keyof P]: P[K] extends PartialDefinition<unknown, infer N> ? PartialsData<N> : never;
+}[keyof P]>;
+export declare function definePartial<T, P extends PartialsMap = Record<never, never>>(definition: {
+    readonly files: Readonly<Record<string, string>>;
+    readonly input: TemplateInput<T>;
+    readonly partials?: P;
+}): PartialDefinition<T, P>;
+/** One runtime input of a compiled template: `key` is `null` for the template's own input. */
+export interface TemplateInputSlot {
+    readonly key: string | null;
+    readonly path: string;
+    readonly schema?: StandardSchemaV1;
+}
+/**
+ * A template: its Typst files (its own and every partial's), its entrypoint, and its runtime inputs.
+ * `Input` and `Partials` type a request for it.
+ */
+export interface TemplateDefinition<Input = undefined, Partials = Record<never, never>> {
+    readonly kind: 'typfolio-template';
+    readonly entrypoint: string;
+    readonly files: Readonly<Record<string, string>>;
+    readonly inputs: readonly TemplateInputSlot[];
+    /** Type-only. */
+    readonly '~types'?: {
+        readonly input: Input;
+        readonly partials: Partials;
+    };
+}
+export declare function defineTemplate<I = undefined, P extends PartialsMap = Record<never, never>>(definition: {
+    /** Defaults to `main.typ`. */
+    readonly entrypoint?: string;
+    readonly files: Readonly<Record<string, string>>;
+    readonly input?: TemplateInput<I>;
+    readonly partials?: P;
+}): TemplateDefinition<I, PartialsData<P>>;
+export declare function isTemplateDefinition(value: unknown): value is TemplateDefinition<unknown, unknown>;
+/** A request for a defined template, typed by it: its input and its partials' data. */
+export type TemplateRequest<T> = T extends TemplateDefinition<infer I, infer P> ? {
+    template: T;
+    assets?: Readonly<Record<string, Uint8Array>>;
+    pdf?: PdfOptions;
+} & ([I] extends [undefined] ? {
+    input?: undefined;
+} : unknown extends I ? {
+    input?: unknown;
+} : {
+    input: I;
+}) & ([keyof P] extends [never] ? {
+    partials?: Record<never, never>;
+} : {
+    partials: P;
+}) : never;
+/**
+ * What `compile` checks a request against: one for a template made with `defineTemplate` must be its
+ * `TemplateRequest`; any other request is accepted as it is.
+ */
+export type CheckedRequest<R> = R extends {
+    template: infer T;
+} ? T extends TemplateDefinition<unknown, unknown> ? TemplateRequest<T> : unknown : unknown;
+/** Any request a client accepts: a plain one, one for a defined template, or the low-level form. */
+export type AnyPdfRequest = PdfRequest<unknown> | DocumentsRequest | {
+    template: TemplateDefinition<unknown, unknown>;
+    input?: unknown;
+    partials?: Readonly<Record<string, unknown>>;
+    assets?: Readonly<Record<string, Uint8Array>>;
+    pdf?: PdfOptions;
+};
+/** The low-level form of a request: documents mounted at their schema paths. */
+export interface DocumentsRequest {
+    template: {
+        entrypoint: string;
+        files: Readonly<Record<string, string>>;
+    };
+    input: null;
+    documents: Readonly<Record<string, unknown>>;
+    assets?: Readonly<Record<string, Uint8Array>>;
+    pdf?: PdfOptions;
+}
+/**
+ * Turns a request for a defined template into its low-level form, checking each document against its
+ * schema. A schema that validates synchronously throws here, before anything is captured; one that
+ * returns a promise is checked by the returned `validated`, which the caller awaits before compiling.
+ * A plain request passes through.
+ */
+export declare function resolveRequest(request: AnyPdfRequest): {
+    request: PdfRequest<unknown> | DocumentsRequest;
+    validated?: Promise<void>;
+};
+/**
+ * Files a request carries, referenced from its data by path: `add(bytes, "png")` returns
+ * `/attachments/0.png` and keeps the bytes for `assets`. The same bytes added twice share one path.
+ */
+export declare function createAttachments(directory?: string): {
+    add(bytes: Uint8Array, extension: string): string;
+    readonly assets: Readonly<Record<string, Uint8Array>>;
+};
+export {};

package/dist/definition.js

@@ -0,0 +1,161 @@
+import { TypstPdfError } from './types.js';
+/** Pairs a schema with the virtual path of its JSON Schema file. */
+export function defineInput(schema, path) {
+    if (!isStandardSchema(schema))
+        throw new TypeError('defineInput: schema must implement Standard Schema (~standard)');
+    return Object.freeze({ path: relativePath(path), schema: schema });
+}
+export function definePartial(definition) {
+    const { files, input, partials = {} } = definition ?? {};
+    if (!input || typeof input.path !== 'string')
+        throw new TypeError('definePartial: input must come from defineInput(schema, path)');
+    return Object.freeze({ kind: 'typfolio-partial', files: Object.freeze({ ...files }), input, partials: Object.freeze({ ...partials }) });
+}
+export function defineTemplate(definition) {
+    const { entrypoint = 'main.typ', files, input, partials = {} } = definition ?? {};
+    const merged = { ...files };
+    const slots = [];
+    const paths = new Map();
+    const claim = (path, owner) => {
+        const previous = paths.get(path);
+        if (previous !== undefined)
+            throw new TypeError(`defineTemplate: ${owner} and ${previous} both read their input from ${path}`);
+        paths.set(path, owner);
+    };
+    if (input !== undefined) {
+        if (typeof input.path !== 'string')
+            throw new TypeError('defineTemplate: input must come from defineInput(schema, path)');
+        const path = relativePath(input.path);
+        claim(path, 'the template');
+        slots.push({ key: null, path, ...(input.schema ? { schema: input.schema } : {}) });
+    }
+    // Partials, nested ones included, each once: the same definition under one key may be reached twice.
+    const byKey = new Map();
+    const visit = (map, trail) => {
+        for (const [key, partial] of Object.entries(map)) {
+            if (!partial || partial.kind !== 'typfolio-partial')
+                throw new TypeError(`defineTemplate: ${trail}${key} is not a definePartial(...)`);
+            const known = byKey.get(key);
+            if (known === partial)
+                continue;
+            if (known !== undefined)
+                throw new TypeError(`defineTemplate: two different partials are both named "${key}"`);
+            byKey.set(key, partial);
+            const path = relativePath(partial.input.path);
+            claim(path, `partial "${key}"`);
+            slots.push({ key, path, ...(partial.input.schema ? { schema: partial.input.schema } : {}) });
+            for (const [path, source] of Object.entries(partial.files)) {
+                if (path in merged && merged[path] !== source)
+                    throw new TypeError(`defineTemplate: ${path} is given twice with different contents (partial "${key}")`);
+                merged[path] = source;
+            }
+            visit(partial.partials, `${trail}${key}.`);
+        }
+    };
+    visit(partials, '');
+    for (const path of paths.keys()) {
+        if (Object.keys(merged).some(file => relativePath(file) === path)) {
+            throw new TypeError(`defineTemplate: ${path} is an input path; do not list the schema file in files (it is not shipped, the data is mounted there)`);
+        }
+    }
+    return Object.freeze({
+        kind: 'typfolio-template',
+        entrypoint,
+        files: Object.freeze(merged),
+        inputs: Object.freeze(slots),
+    });
+}
+export function isTemplateDefinition(value) {
+    return typeof value === 'object' && value !== null && value.kind === 'typfolio-template';
+}
+function invalidInput(slot, issues) {
+    const owner = slot.key === null ? 'The template input' : `The data of partial "${slot.key}"`;
+    const lines = issues.slice(0, 10).map(issue => {
+        const path = (issue.path ?? []).map(part => (typeof part === 'object' ? part.key : part)).map(String).join('.');
+        return `- ${path ? `${path}: ` : ''}${issue.message}`;
+    });
+    const more = issues.length > 10 ? `\n- … ${issues.length - 10} more` : '';
+    return Object.assign(new TypstPdfError('INVALID_INPUT', `${owner} does not match its schema (${slot.path}):\n${lines.join('\n')}${more}`, [], { cause: issues }), { issues });
+}
+/**
+ * Turns a request for a defined template into its low-level form, checking each document against its
+ * schema. A schema that validates synchronously throws here, before anything is captured; one that
+ * returns a promise is checked by the returned `validated`, which the caller awaits before compiling.
+ * A plain request passes through.
+ */
+export function resolveRequest(request) {
+    if (!request || !isTemplateDefinition(request.template))
+        return { request: request };
+    const { template, partials = {} } = request;
+    for (const key of Object.keys(partials)) {
+        if (!template.inputs.some(slot => slot.key === key)) {
+            throw new TypstPdfError('INVALID_REQUEST', `partials.${key}: this template has no partial "${key}"; it has ${template.inputs.filter(slot => slot.key !== null).map(slot => `"${slot.key}"`).join(', ') || 'none'}`);
+        }
+    }
+    const documents = {};
+    const pending = [];
+    for (const slot of template.inputs) {
+        const value = slot.key === null ? request.input : partials[slot.key];
+        if (value === undefined) {
+            throw new TypstPdfError('INVALID_REQUEST', slot.key === null
+                ? `The template reads its input from ${slot.path}, but the request has no input`
+                : `Partial "${slot.key}" reads its input from ${slot.path}, but the request has no partials.${slot.key}`);
+        }
+        documents[slot.path] = value;
+        if (slot.schema) {
+            const result = slot.schema['~standard'].validate(value);
+            if (result instanceof Promise) {
+                pending.push(result.then(settled => { if (settled.issues)
+                    throw invalidInput(slot, settled.issues); }));
+            }
+            else if (result.issues) {
+                throw invalidInput(slot, result.issues);
+            }
+        }
+    }
+    const resolved = {
+        template: { entrypoint: template.entrypoint, files: template.files },
+        input: null,
+        documents,
+        ...(request.assets === undefined ? {} : { assets: request.assets }),
+        ...(request.pdf === undefined ? {} : { pdf: request.pdf }),
+    };
+    return pending.length ? { request: resolved, validated: Promise.all(pending).then(() => undefined) } : { request: resolved };
+}
+/**
+ * Files a request carries, referenced from its data by path: `add(bytes, "png")` returns
+ * `/attachments/0.png` and keeps the bytes for `assets`. The same bytes added twice share one path.
+ */
+export function createAttachments(directory = 'attachments') {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(directory) || directory.endsWith('/') || directory.includes('..')) {
+        throw new TypeError(`createAttachments: directory must be a relative path, got ${JSON.stringify(directory)}`);
+    }
+    const assets = {};
+    const seen = new Map();
+    return {
+        add(bytes, extension) {
+            if (!(bytes instanceof Uint8Array))
+                throw new TypeError('attach: bytes must be a Uint8Array');
+            const ext = String(extension).replace(/^\./, '').toLowerCase();
+            if (!/^[a-z0-9]+$/.test(ext))
+                throw new TypeError(`attach: the extension must be letters and digits, got ${JSON.stringify(extension)}`);
+            const known = seen.get(bytes);
+            if (known !== undefined)
+                return known;
+            const name = `${directory}/${seen.size}.${ext}`;
+            seen.set(bytes, `/${name}`);
+            assets[name] = bytes;
+            return `/${name}`;
+        },
+        get assets() {
+            return assets;
+        },
+    };
+}
+function isStandardSchema(value) {
+    return typeof value === 'object' && value !== null && typeof value['~standard']?.validate === 'function';
+}
+// Paths are checked when compiling, where every file and input path is; here they are only compared.
+function relativePath(path) {
+    return String(path).replace(/^\/+/, '');
+}