@typfolio/core 0.1.0 → 0.2.0

package/dist/engine.js

@@ -1,5 +1,5 @@
 import init, { TypstCompilerBuilder } from '@typfolio/wasm';
-import { TypstPdfError } from './types.js';
+import { errorLink, TypstPdfError } from './types.js';
 import { resolvePackage } from './typst-package.js';
 let initialization;
 let loadedSource;
@@ -31,6 +31,31 @@ function message(error) {
         return String(error);
     }
 }
+const quoted = /"((?:[^"\\]|\\.)*)"/g;
+const unquote = (text) => { try {
+    return JSON.parse(`"${text}"`);
+}
+catch {
+    return text;
+} };
+// The binding reports a failed PDF export as Rust debug text,
+// `[SourceDiagnostic { severity: Error, span: …, message: "…", trace: [], hints: ["…"] }]`:
+// one diagnostic per message, its hints appended. A character no loaded font can display (refused
+// by a PDF standard) is `missing-glyph`. Anything else is kept as it is.
+function exportDiagnostics(text) {
+    const found = text.split('SourceDiagnostic {').slice(1).flatMap((part) => {
+        const [, said] = /message: "((?:[^"\\]|\\.)*)"/.exec(part) ?? [];
+        if (said === undefined)
+            return [];
+        const message = unquote(said);
+        const [, glyph] = /^PDF\/\S+ error: the text `"(.*)"` could not be displayed with font/.exec(message) ?? [];
+        if (glyph !== undefined)
+            return [{ severity: 'error', code: 'missing-glyph', text: glyph, message: `${message}. See ${errorLink('missing-glyph')}` }];
+        const hints = [...(/hints: \[(.*)\]/s.exec(part)?.[1] ?? '').matchAll(quoted)].map(([, hint]) => `\nhint: ${unquote(hint)}`);
+        return [{ severity: 'error', message: message + hints.join('') }];
+    });
+    return found.length ? found : [{ severity: 'error', message: text }];
+}
 function fontUrl(value) {
     if (value instanceof URL)
         return value;
@@ -126,12 +151,9 @@ class Engine {
         let diagnostics = [];
         try {
             this.compiler.reset_shadow();
-            for (const [path, bytes] of request.files) {
-                if (!this.compiler.map_shadow(path, bytes))
-                    throw new TypstPdfError('ENGINE', `Could not mount ${path}`);
-            }
-            // For a runtime compile these are the helper package plus the input at its root (absolute paths inside a package resolve there).
-            for (const [path, bytes] of extras.mounts) {
+            // The request's files, then the extras: for a runtime compile, the helper package plus the input at
+            // its root (absolute paths inside a package resolve there).
+            for (const [path, bytes] of [...request.files, ...extras.mounts]) {
                 if (!this.compiler.map_shadow(path, bytes))
                     throw new TypstPdfError('ENGINE', `Could not mount ${path}`);
             }
@@ -151,9 +173,9 @@ class Engine {
         catch (error) {
             if (error instanceof TypstPdfError)
                 throw error;
-            // Upstream export failures currently lack structured source locations.
-            const text = message(error);
-            throw new TypstPdfError('COMPILATION', text, [...diagnostics, { severity: 'error', message: text }], { cause: error });
+            // Upstream export failures (a PDF standard's checks) lack source locations.
+            const failures = exportDiagnostics(message(error));
+            throw new TypstPdfError('COMPILATION', failures.map(d => d.message).join('\n'), [...diagnostics, ...failures], { cause: error });
         }
         finally {
             try {

package/dist/explain.d.ts

@@ -0,0 +1,2 @@
+/** Turns each "failed to load file" diagnostic about a file the request lacks into `file-not-found`. */
+export declare function explainCompileError(error: unknown, files: ReadonlyMap<string, Uint8Array>): unknown;

package/dist/explain.js

@@ -0,0 +1,42 @@
+import { errorLink, TypstPdfError } from './types.js';
+const decoder = new TextDecoder();
+function resolve(from, path) {
+    const parts = path.startsWith('/') ? [] : from.split('/').slice(1, -1);
+    for (const part of path.split('/')) {
+        if (part === '' || part === '.')
+            continue;
+        if (part === '..')
+            parts.pop();
+        else
+            parts.push(part);
+    }
+    return `/${parts.join('/')}`;
+}
+// The file a missing-file diagnostic is about. Typst reports only "failed to load file (is a
+// directory)", with the range of the path string in the file that reads it.
+function missingPath(diagnostic, files) {
+    if (!/failed to load file/.test(diagnostic.message) || diagnostic.package || !diagnostic.path)
+        return undefined;
+    const source = files.get(diagnostic.path);
+    const range = /^(\d+):(\d+)-(\d+):(\d+)$/.exec(diagnostic.range ?? '');
+    if (!source || !range || range[1] !== range[3])
+        return undefined;
+    const literal = decoder.decode(source).split('\n')[Number(range[1])]?.slice(Number(range[2]), Number(range[4])).trim();
+    const quoted = literal && /^"([^"\\]*)"$/.exec(literal);
+    return quoted ? resolve(diagnostic.path, quoted[1]) : undefined;
+}
+/** Turns each "failed to load file" diagnostic about a file the request lacks into `file-not-found`. */
+export function explainCompileError(error, files) {
+    if (!(error instanceof TypstPdfError) || error.code !== 'COMPILATION')
+        return error;
+    let found = false;
+    const diagnostics = error.diagnostics.map(diagnostic => {
+        const file = missingPath(diagnostic, files);
+        if (file === undefined || files.has(file))
+            return diagnostic;
+        found = true;
+        const message = `File not found: ${file} (read by ${diagnostic.path}). See ${errorLink('file-not-found')}`;
+        return { ...diagnostic, code: 'file-not-found', file, message };
+    });
+    return found ? new TypstPdfError('COMPILATION', diagnostics.map(d => d.message).join('\n'), diagnostics, { cause: error }) : error;
+}

package/dist/index.d.ts

@@ -1,6 +1,8 @@
-import { type FontSource, type PdfCompiler, type WasmSource } from './types.js';
+import { type FontSource, type PdfClient, type PdfCompiler, type WasmSource } from './types.js';
 export { capabilities, pdfStandards, TypstPdfError } from './types.js';
-export type { JsonValue, PdfOptions, PdfStandard, PdfRequest, PdfTemplate, PdfResult, PdfClient, PdfCompiler, Diagnostic, ErrorCode } from './types.js';
+export type { JsonValue, PdfOptions, PdfStandard, PdfRequest, PdfTemplate, PdfResult, PdfClient, PdfCompiler, Diagnostic, DiagnosticCode, ErrorCode } from './types.js';
+export { createAttachments, defineInput, definePartial, defineTemplate } from './definition.js';
+export type { AnyPdfRequest, CheckedRequest, DocumentsRequest, InferSchemaInput, PartialDefinition, PartialsData, PartialsMap, StandardSchemaIssue, StandardSchemaResult, StandardSchemaV1, TemplateDefinition, TemplateInput, TemplateInputSlot, TemplateRequest, } from './definition.js';
 export type { FontSource, WasmSource } from './types.js';
 export { templateFromFiles } from './template.js';
 export type { TemplateFromFilesOptions, TemplateFiles } from './template.js';
@@ -22,5 +24,19 @@ export interface CompilerOptions {
      */
     copyAssets?: boolean;
 }
+/** A `PdfClient` whose compiler is created on its first `compile`. */
+export interface LazyCompiler extends PdfClient {
+    /** Stops accepting jobs, waits for the queued ones, and frees the compiler if one was created. */
+    dispose(): Promise<void>;
+}
+/**
+ * A compiler for the page, created when it is first needed: nothing is downloaded or initialized until
+ * the first `compile`, which loads the WASM and the fonts once for every later call. A load that fails is
+ * not kept, so the next `compile` tries again. Calls run one at a time, in order, so callers never see
+ * `BUSY`; a call whose signal is aborted before its turn rejects with `ABORTED` without running. A request
+ * is read when its turn comes. Synchronous, so it can be created at module level and passed as a
+ * `PdfClient` (to `PdfProvider`, or as `client`). Use `@typfolio/workers` to compile off the main thread.
+ */
+export declare function createLazyCompiler(options: CompilerOptions): LazyCompiler;
 /** One active job per compiler. Use a worker client for queues and hard cancellation. */
 export declare function createCompiler(options: CompilerOptions): Promise<PdfCompiler>;

package/dist/index.js

@@ -1,9 +1,61 @@
 import { copyFonts, createEngine, fetchFonts, initialize } from './engine.js';
 import { prepareRequest } from './request.js';
 import { capabilities, TypstPdfError } from './types.js';
-import { packageMounts, runtimeMarker } from './typst-package.js';
+import { resolveRequest } from './definition.js';
+import { explainCompileError } from './explain.js';
+import { documentsMarker, packageMounts, runtimeMarker } from './typst-package.js';
 export { capabilities, pdfStandards, TypstPdfError } from './types.js';
+export { createAttachments, defineInput, definePartial, defineTemplate } from './definition.js';
 export { templateFromFiles } from './template.js';
+/**
+ * A compiler for the page, created when it is first needed: nothing is downloaded or initialized until
+ * the first `compile`, which loads the WASM and the fonts once for every later call. A load that fails is
+ * not kept, so the next `compile` tries again. Calls run one at a time, in order, so callers never see
+ * `BUSY`; a call whose signal is aborted before its turn rejects with `ABORTED` without running. A request
+ * is read when its turn comes. Synchronous, so it can be created at module level and passed as a
+ * `PdfClient` (to `PdfProvider`, or as `client`). Use `@typfolio/workers` to compile off the main thread.
+ */
+export function createLazyCompiler(options) {
+    // Font sources are checked (and byte fonts copied) now, so a mistake shows where the client is made.
+    const fonts = copyFonts(options?.fonts);
+    let loading;
+    let queue = Promise.resolve();
+    let closed = false;
+    const load = () => {
+        if (loading === undefined) {
+            const attempt = createCompiler({ ...options, fonts });
+            loading = attempt;
+            attempt.catch(() => {
+                if (loading === attempt)
+                    loading = undefined;
+            });
+        }
+        return loading;
+    };
+    const disposed = () => new TypstPdfError('DISPOSED', 'The compiler is disposed');
+    return {
+        compile(request, compileOptions = {}) {
+            if (closed)
+                return Promise.reject(disposed());
+            const job = queue.then(async () => {
+                if (closed)
+                    throw disposed();
+                if (compileOptions.signal?.aborted) {
+                    throw new TypstPdfError('ABORTED', 'Compilation was cancelled', [], { cause: compileOptions.signal.reason });
+                }
+                return (await load()).compile(request, compileOptions);
+            });
+            queue = job.catch(() => undefined);
+            return job;
+        },
+        async dispose() {
+            closed = true;
+            await queue;
+            const compiler = await loading?.catch(() => undefined);
+            await compiler?.dispose();
+        },
+    };
+}
 /** One active job per compiler. Use a worker client for queues and hard cancellation. */
 export async function createCompiler(options) {
     const sources = copyFonts(options?.fonts);
@@ -27,14 +79,25 @@ export async function createCompiler(options) {
             if (busy)
                 throw new TypstPdfError('BUSY', 'The compiler already has an active job');
             checkAbort(options.signal);
-            const prepared = prepareRequest(request, { copyAssets }); // Capture data before yielding to caller code.
+            // A defined template's documents are checked against their schemas here; a synchronous schema
+            // throws before anything is captured.
+            const { request: resolved, validated } = resolveRequest(request);
+            const prepared = prepareRequest(resolved, { copyAssets }); // Capture data before yielding to caller code.
             busy = true;
             let release;
             finished = new Promise(resolve => { release = resolve; });
             try {
-                await Promise.resolve();
+                // Yields to the caller even without an asynchronous schema, so a signal can still abort.
+                await validated;
                 checkAbort(options.signal);
-                const result = engine.compile(prepared, { mounts: packageMounts(prepared.files.get('/input.json')), inputs: [runtimeMarker] });
+                const inputs = prepared.documents ? [runtimeMarker, documentsMarker] : [runtimeMarker];
+                let result;
+                try {
+                    result = engine.compile(prepared, { mounts: packageMounts(prepared.files.get('/input.json')), inputs });
+                }
+                catch (error) {
+                    throw explainCompileError(error, prepared.files);
+                }
                 checkAbort(options.signal);
                 return result;
             }

package/dist/internal.d.ts

@@ -5,4 +5,6 @@
 export { createEngine, initialize, resolveFonts } from './engine.js';
 export type { CompileExtras } from './engine.js';
 export { prepareRequest } from './request.js';
+export { isTemplateDefinition, resolveRequest } from './definition.js';
 export { bundledPackageDirectory, packageFileMounts } from './typst-package.js';
+export { explainCompileError } from './explain.js';

package/dist/internal.js

@@ -4,4 +4,6 @@
  */
 export { createEngine, initialize, resolveFonts } from './engine.js';
 export { prepareRequest } from './request.js';
+export { isTemplateDefinition, resolveRequest } from './definition.js';
 export { bundledPackageDirectory, packageFileMounts } from './typst-package.js';
+export { explainCompileError } from './explain.js';

package/dist/request.d.ts

@@ -1,12 +1,14 @@
+import type { DocumentsRequest } from './definition.js';
 import { type PdfRequest } from './types.js';
 export declare function virtualPath(path: unknown): string;
 export interface PrepareRequestOptions {
     /** Copy every asset (default). `false` mounts the caller's `Uint8Array` views as they are. */
     readonly copyAssets?: boolean;
 }
-export declare function prepareRequest(request: PdfRequest<unknown>, options?: PrepareRequestOptions): {
+export declare function prepareRequest(request: PdfRequest<unknown> | DocumentsRequest, options?: PrepareRequestOptions): {
     entrypoint: string;
     files: Map<string, Uint8Array<ArrayBufferLike>>;
+    documents: boolean;
     pdf: {
         pdf_standard: any;
         pdf_tags: {};

package/dist/request.js

@@ -63,7 +63,7 @@ function jsonData(value, ancestors, at) {
 export function prepareRequest(request, options = {}) {
     const copyAssets = options.copyAssets ?? true;
     const value = record(request, 'request');
-    keys(value, ['template', 'input', 'assets', 'pdf'], 'request');
+    keys(value, ['template', 'input', 'documents', 'assets', 'pdf'], 'request');
     // A string template is shorthand for { files: { 'main.typ': template } } with the default entrypoint.
     const template = typeof value.template === 'string'
         ? { files: { [defaultEntrypoint]: value.template } }
@@ -74,7 +74,7 @@ export function prepareRequest(request, options = {}) {
     const files = new Map();
     const put = (name, contents) => {
         const path = virtualPath(name);
-        if (path === '/input.json')
+        if (path === '/input.json' || path.startsWith('/input.json/'))
             invalid('/input.json is reserved for request.input');
         if (isReservedPath(path))
             invalid(`${reservedDirectory}/ is reserved for core's Typst package: ${path}`);
@@ -103,16 +103,24 @@ export function prepareRequest(request, options = {}) {
             put(name, copyAssets ? new Uint8Array(bytes) : bytes);
         }
     }
-    if (Array.from(files.keys()).some(path => path.startsWith('/input.json/')))
-        invalid('/input.json is reserved for request.input');
-    try {
-        files.set('/input.json', encoder.encode(JSON.stringify(jsonData(value.input, new Set(), 'input'))));
-    }
-    catch (error) {
-        if (error instanceof TypstPdfError)
-            throw error;
-        throw new TypstPdfError('INVALID_REQUEST', 'Could not serialize input as JSON', [], { cause: error });
+    // The JSON bytes of request data, or INVALID_REQUEST naming it.
+    const json = (data, at) => {
+        try {
+            return encoder.encode(JSON.stringify(jsonData(data, new Set(), at)));
+        }
+        catch (error) {
+            if (error instanceof TypstPdfError)
+                throw error;
+            throw new TypstPdfError('INVALID_REQUEST', `Could not serialize ${at} as JSON`, [], { cause: error });
+        }
+    };
+    // Documents: JSON data mounted at the paths of their schema files, read with `input(json.with(...))`.
+    const documents = value.documents !== undefined;
+    if (documents) {
+        for (const [name, data] of Object.entries(record(value.documents, 'documents')))
+            put(name, json(data, `document ${name}`));
     }
+    files.set('/input.json', json(value.input, 'input'));
     const pdf = value.pdf === undefined ? {} : record(value.pdf, 'pdf');
     keys(pdf, ['standards', 'tags', 'creationTimestamp'], 'pdf');
     const standards = pdf.standards ?? [];
@@ -128,7 +136,7 @@ export function prepareRequest(request, options = {}) {
     if (pdf.creationTimestamp !== undefined && !Number.isSafeInteger(pdf.creationTimestamp))
         invalid('creationTimestamp must be Unix seconds as a safe integer');
     return {
-        entrypoint, files,
+        entrypoint, files, documents,
         pdf: { pdf_standard: standards[0], pdf_tags: pdf.tags ?? true, creation_timestamp: pdf.creationTimestamp },
     };
 }

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { AnyPdfRequest, CheckedRequest } from './definition.js';
 export type JsonValue = null | boolean | number | string | JsonValue[] | {
     [key: string]: JsonValue;
 };
@@ -34,6 +35,8 @@ export interface PdfRequest<Input = JsonValue> {
     assets?: Readonly<Record<string, Uint8Array>>;
     pdf?: PdfOptions;
 }
+/** A failure Typfolio recognises; `docs/errors.md` explains each and what to do. */
+export type DiagnosticCode = 'file-not-found' | 'missing-glyph';
 export interface Diagnostic {
     severity: 'error' | 'warning' | string;
     message: string;
@@ -41,7 +44,15 @@ export interface Diagnostic {
     /** Upstream range: zero-based line:column-line:column. */
     range?: string;
     package?: string;
+    /** Set on a failure Typfolio recognises; switch on it rather than on `message`. */
+    code?: DiagnosticCode;
+    /** `file-not-found`: the missing file, as an absolute virtual path. */
+    file?: string;
+    /** `missing-glyph`: the text none of the loaded fonts can display. */
+    text?: string;
 }
+/** The section of docs/errors.md that explains `code`. */
+export declare const errorLink: (code: DiagnosticCode) => string;
 export interface PdfResult {
     bytes: Uint8Array;
     diagnostics: readonly Diagnostic[];
@@ -50,7 +61,8 @@ export interface PdfResult {
     };
 }
 export interface PdfClient {
-    compile(request: PdfRequest<unknown>, options?: {
+    /** A plain request, or one for a template made with `defineTemplate`, type-checked against its `TemplateRequest`. */
+    compile<R extends AnyPdfRequest>(request: R & CheckedRequest<R>, options?: {
         signal?: AbortSignal;
     }): Promise<PdfResult>;
 }
@@ -72,7 +84,8 @@ export declare const capabilities: Readonly<{
     readonly typstPackages: readonly string[];
     readonly hardCancellation: false;
 }>;
-export type ErrorCode = 'INITIALIZATION' | 'INVALID_REQUEST' | 'UNSUPPORTED_OPTION' | 'BUSY' | 'DISPOSED' | 'ABORTED' | 'COMPILATION' | 'ENGINE';
+/** `INVALID_INPUT`: a defined template's input, or a partial's data, does not match its schema. */
+export type ErrorCode = 'INITIALIZATION' | 'INVALID_REQUEST' | 'INVALID_INPUT' | 'UNSUPPORTED_OPTION' | 'BUSY' | 'DISPOSED' | 'ABORTED' | 'COMPILATION' | 'ENGINE';
 export declare class TypstPdfError extends Error {
     readonly code: ErrorCode;
     readonly diagnostics: readonly Diagnostic[];

package/dist/types.js

@@ -1,5 +1,7 @@
 import { bundledPackageSpec } from './typst-package.js';
 export const pdfStandards = ['1.4', '1.5', '1.6', '1.7', '2.0', 'a-1b', 'a-1a', 'a-2b', 'a-2u', 'a-2a', 'a-3b', 'a-3u', 'a-3a', 'a-4', 'a-4f', 'a-4e', 'ua-1'];
+/** The section of docs/errors.md that explains `code`. */
+export const errorLink = (code) => `https://github.com/HelioCampus/typfolio/blob/main/docs/errors.md#${code}`;
 export const capabilities = Object.freeze({
     output: 'pdf',
     standards: Object.freeze([...pdfStandards]),

package/dist/typst-package.d.ts

@@ -16,3 +16,5 @@ export declare function packageFileMounts(): [string, Uint8Array][];
 export declare function packageMounts(input: Uint8Array): [string, Uint8Array][];
 /** `sys.inputs` entry that tells the helper it is running under Typfolio. */
 export declare const runtimeMarker: [string, string];
+/** Set when the request mounts documents: `input(json.with(path))` then reads the data mounted at `path`. */
+export declare const documentsMarker: [string, string];

package/dist/typst-package.generated.d.ts

@@ -3,7 +3,7 @@ export declare const typfolioPackage: {
     readonly name: "typfolio";
     readonly version: "0.1.0";
     readonly files: {
-        readonly "typst.toml": "[package]\nname = \"typfolio\"\nversion = \"0.1.0\"\nentrypoint = \"lib.typ\"\nauthors = [\"Typfolio\"]\ndescription = \"Read the Typfolio request input in a template, with a sample built from a JSON Schema for editor completion.\"\n";
-        readonly "lib.typ": "// @local/typfolio: the template-side helper for Typfolio.\n//\n//   #import \"@local/typfolio:0.1.0\": input\n//   #let data = input(json.with(\"./report.schema.json\"))\n//\n// While Typfolio compiles, core sets `sys.inputs.typfolio` and `input()` returns the request input\n// (mounted at the package root as /input.json). In an editor nothing sets it, so `input()` builds a\n// sample from the JSON Schema and the editor can complete `#data.` fields. The sample is for\n// authoring only: it is not validated, and keywords that only restrict values are ignored.\n//\n// The sample builder lives in `sample.typ` and is imported inside `input()`, in the editor branch only,\n// so a runtime compile never loads it. `--input typfolio-sample=minimal` (Tinymist's `typstExtraArgs`)\n// previews the sparsest sample instead of the default \"full\" one.\n//\n// The schema is passed as a function created in the template (`json.with(path)`) because a relative\n// path written inside this package would resolve against the package, not the template.\n\n/// Returns the request input under Typfolio and a schema-built sample in the editor.\n///\n/// `schema` is `json.with(\"<path>\")` (a function that loads the schema, with the path resolved\n/// relative to the calling file) or an already-loaded schema dictionary.\n#let input(schema) = {\n  if \"typfolio\" in sys.inputs { return json(\"/input.json\") }\n  import \"sample.typ\": sample-from-schema\n  let mode = sys.inputs.at(\"typfolio-sample\", default: \"full\")\n  if type(schema) == function { return sample-from-schema(schema(), mode: mode) }\n  if type(schema) == dictionary { return sample-from-schema(schema, mode: mode) }\n  if schema == none {\n    panic(\"@local/typfolio: input() needs a JSON Schema so the editor can build a sample. Pass json.with(\\\"<schema>.json\\\"), for example input(json.with(\\\"./report.schema.json\\\")).\")\n  }\n  panic(\"@local/typfolio: input() expects json.with(\\\"<schema>.json\\\") or a schema dictionary, got \" + repr(type(schema)))\n}\n";
+        readonly "typst.toml": "[package]\nname = \"typfolio\"\nversion = \"0.1.0\"\nentrypoint = \"lib.typ\"\n";
+        readonly "lib.typ": "\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n#let input(schema) = {\n  if \"typfolio\" in sys.inputs {\n    if sys.inputs.at(\"typfolio-inputs\", default: none) != \"documents\" { return json(\"/input.json\") }\n\n    if type(schema) == function { return schema() }\n    panic(\"@local/typfolio: in a template made with defineTemplate, input() needs json.with(\\\"<schema>.json\\\"): the data is mounted at that path\")\n  }\n  import \"sample.typ\": sample-from-schema\n  let mode = sys.inputs.at(\"typfolio-sample\", default: \"full\")\n  if type(schema) == function { return sample-from-schema(schema(), mode: mode) }\n  if type(schema) == dictionary { return sample-from-schema(schema, mode: mode) }\n  if schema == none {\n    panic(\"@local/typfolio: input() needs a JSON Schema so the editor can build a sample. Pass json.with(\\\"<schema>.json\\\"), for example input(json.with(\\\"./report.schema.json\\\")).\")\n  }\n  panic(\"@local/typfolio: input() expects json.with(\\\"<schema>.json\\\") or a schema dictionary, got \" + repr(type(schema)))\n}\n";
     };
 };

package/dist/typst-package.generated.js

@@ -6,7 +6,7 @@ export const typfolioPackage = {
     "name": "typfolio",
     "version": "0.1.0",
     "files": {
-        "typst.toml": "[package]\nname = \"typfolio\"\nversion = \"0.1.0\"\nentrypoint = \"lib.typ\"\nauthors = [\"Typfolio\"]\ndescription = \"Read the Typfolio request input in a template, with a sample built from a JSON Schema for editor completion.\"\n",
-        "lib.typ": "// @local/typfolio: the template-side helper for Typfolio.\n//\n//   #import \"@local/typfolio:0.1.0\": input\n//   #let data = input(json.with(\"./report.schema.json\"))\n//\n// While Typfolio compiles, core sets `sys.inputs.typfolio` and `input()` returns the request input\n// (mounted at the package root as /input.json). In an editor nothing sets it, so `input()` builds a\n// sample from the JSON Schema and the editor can complete `#data.` fields. The sample is for\n// authoring only: it is not validated, and keywords that only restrict values are ignored.\n//\n// The sample builder lives in `sample.typ` and is imported inside `input()`, in the editor branch only,\n// so a runtime compile never loads it. `--input typfolio-sample=minimal` (Tinymist's `typstExtraArgs`)\n// previews the sparsest sample instead of the default \"full\" one.\n//\n// The schema is passed as a function created in the template (`json.with(path)`) because a relative\n// path written inside this package would resolve against the package, not the template.\n\n/// Returns the request input under Typfolio and a schema-built sample in the editor.\n///\n/// `schema` is `json.with(\"<path>\")` (a function that loads the schema, with the path resolved\n/// relative to the calling file) or an already-loaded schema dictionary.\n#let input(schema) = {\n  if \"typfolio\" in sys.inputs { return json(\"/input.json\") }\n  import \"sample.typ\": sample-from-schema\n  let mode = sys.inputs.at(\"typfolio-sample\", default: \"full\")\n  if type(schema) == function { return sample-from-schema(schema(), mode: mode) }\n  if type(schema) == dictionary { return sample-from-schema(schema, mode: mode) }\n  if schema == none {\n    panic(\"@local/typfolio: input() needs a JSON Schema so the editor can build a sample. Pass json.with(\\\"<schema>.json\\\"), for example input(json.with(\\\"./report.schema.json\\\")).\")\n  }\n  panic(\"@local/typfolio: input() expects json.with(\\\"<schema>.json\\\") or a schema dictionary, got \" + repr(type(schema)))\n}\n"
+        "typst.toml": "[package]\nname = \"typfolio\"\nversion = \"0.1.0\"\nentrypoint = \"lib.typ\"\n",
+        "lib.typ": "\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n#let input(schema) = {\n  if \"typfolio\" in sys.inputs {\n    if sys.inputs.at(\"typfolio-inputs\", default: none) != \"documents\" { return json(\"/input.json\") }\n\n    if type(schema) == function { return schema() }\n    panic(\"@local/typfolio: in a template made with defineTemplate, input() needs json.with(\\\"<schema>.json\\\"): the data is mounted at that path\")\n  }\n  import \"sample.typ\": sample-from-schema\n  let mode = sys.inputs.at(\"typfolio-sample\", default: \"full\")\n  if type(schema) == function { return sample-from-schema(schema(), mode: mode) }\n  if type(schema) == dictionary { return sample-from-schema(schema, mode: mode) }\n  if schema == none {\n    panic(\"@local/typfolio: input() needs a JSON Schema so the editor can build a sample. Pass json.with(\\\"<schema>.json\\\"), for example input(json.with(\\\"./report.schema.json\\\")).\")\n  }\n  panic(\"@local/typfolio: input() expects json.with(\\\"<schema>.json\\\") or a schema dictionary, got \" + repr(type(schema)))\n}\n"
     }
 };

package/dist/typst-package.js

@@ -26,3 +26,5 @@ export function packageMounts(input) {
 }
 /** `sys.inputs` entry that tells the helper it is running under Typfolio. */
 export const runtimeMarker = ['typfolio', version];
+/** Set when the request mounts documents: `input(json.with(path))` then reads the data mounted at `path`. */
+export const documentsMarker = ['typfolio-inputs', 'documents'];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typfolio/core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Framework-independent Typst PDF compiler for the browser and Node, running on WebAssembly",
   "type": "module",
   "license": "Apache-2.0",
@@ -13,6 +13,7 @@
   "homepage": "https://github.com/HelioCampus/typfolio#readme",
   "bugs": { "url": "https://github.com/HelioCampus/typfolio/issues" },
   "files": ["dist", "typst-packages", "README.md"],
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
     "./capture": { "types": "./dist/capture.d.ts", "import": "./dist/capture.js" },
@@ -20,8 +21,16 @@
     "./capture/dom": { "types": "./dist/capture/dom.d.ts", "import": "./dist/capture/dom.js" },
     "./internal": { "types": "./dist/internal.d.ts", "import": "./dist/internal.js" }
   },
+  "typesVersions": {
+    "*": {
+      "capture": ["./dist/capture.d.ts"],
+      "capture/svg": ["./dist/capture/svg.d.ts"],
+      "capture/dom": ["./dist/capture/dom.d.ts"],
+      "internal": ["./dist/internal.d.ts"]
+    }
+  },
   "dependencies": {
-    "@typfolio/wasm": "0.1.0"
+    "@typfolio/wasm": "0.1.1"
   },
   "peerDependencies": {
     "html2canvas": "^1.4.1"

package/typst-packages/local/typfolio/0.1.0/lib.typ

@@ -3,10 +3,14 @@
 //   #import "@local/typfolio:0.1.0": input
 //   #let data = input(json.with("./report.schema.json"))
 //
-// While Typfolio compiles, core sets `sys.inputs.typfolio` and `input()` returns the request input
-// (mounted at the package root as /input.json). In an editor nothing sets it, so `input()` builds a
-// sample from the JSON Schema and the editor can complete `#data.` fields. The sample is for
-// authoring only: it is not validated, and keywords that only restrict values are ignored.
+// While Typfolio compiles, core sets `sys.inputs.typfolio` and `input()` returns runtime data. For a
+// template made with `defineTemplate`, every input (the template's own and each partial's) is mounted
+// at the path of its schema file, so `input(json.with("./header.schema.json"))` reads the header's
+// data there: the schema path is the input's identity, and a file can only read its own. For a plain
+// request, the input is the package root's /input.json. In an editor nothing sets the marker, so
+// `input()` builds a sample from the JSON Schema and the editor can complete `#data.` fields. The
+// sample is for authoring only: it is not validated, and keywords that only restrict values are
+// ignored.
 //
 // The sample builder lives in `sample.typ` and is imported inside `input()`, in the editor branch only,
 // so a runtime compile never loads it. `--input typfolio-sample=minimal` (Tinymist's `typstExtraArgs`)
@@ -20,7 +24,12 @@
 /// `schema` is `json.with("<path>")` (a function that loads the schema, with the path resolved
 /// relative to the calling file) or an already-loaded schema dictionary.
 #let input(schema) = {
-  if "typfolio" in sys.inputs { return json("/input.json") }
+  if "typfolio" in sys.inputs {
+    if sys.inputs.at("typfolio-inputs", default: none) != "documents" { return json("/input.json") }
+    // The data is mounted where the schema file sits, so the same function now loads the data.
+    if type(schema) == function { return schema() }
+    panic("@local/typfolio: in a template made with defineTemplate, input() needs json.with(\"<schema>.json\"): the data is mounted at that path")
+  }
   import "sample.typ": sample-from-schema
   let mode = sys.inputs.at("typfolio-sample", default: "full")
   if type(schema) == function { return sample-from-schema(schema(), mode: mode) }