@quillmark/wasm 0.115.0 → 0.116.0

package/runtime/runtime.d.ts

@@ -21,6 +21,8 @@ import type {
 	rebase,
 	mapPos,
 	mapMarks,
+	isInline,
+	isPlain,
 	parseDocPath,
 	formatDocPath,
 	formatDiagnostic
@@ -41,6 +43,8 @@ export interface CoreSurface {
 	rebase: typeof rebase;
 	mapPos: typeof mapPos;
 	mapMarks: typeof mapMarks;
+	isInline: typeof isInline;
+	isPlain: typeof isPlain;
 	parseDocPath: typeof parseDocPath;
 	formatDocPath: typeof formatDocPath;
 	formatDiagnostic: typeof formatDiagnostic;
@@ -103,6 +107,7 @@ export type {
 	Severity,
 	QuillSchema,
 	QuillFieldSchema,
+	QuillFieldType,
 	QuillCardSchema,
 	QuillCardBody,
 	QuillFieldUi,
@@ -292,8 +297,9 @@ export interface ContentHit {
  *
  * ```js
  * const [x0, y0, x1, y1] = region.rect;
- * // Into a raster painted at renderScale (= layoutScale × densityScale):
- * const left = x0 * renderScale, top = (pageHeightPt - y1) * renderScale;
+ * // Into a painted raster, at the scale it was painted at:
+ * const scale = canvas.width / pageWidthPt;
+ * const left = x0 * scale, top = (pageHeightPt - y1) * scale;
  * // Or, for an HTML overlay on a width:100% canvas, as % of the page, which
  * // tracks the displayed size across DPI and pane resize with no scale to thread:
  * const leftPct = (x0 / pageWidthPt) * 100, topPct = (1 - y1 / pageHeightPt) * 100;
@@ -303,9 +309,9 @@ export interface FieldRegion {
 	/**
 	 * The field's canonical `DocPath` address (`parseDocPath`-routable), not a
 	 * backend widget name: `main.signature_block`,
-	 * `cards.<kind>[<i>].signature_block` (`cards[<i>].…` when the card's kind is
-	 * unknown), an array element bracketed and a key dotted. The same spelling
-	 * `Diagnostic.path` uses, so the two join on string equality.
+	 * `cards.<kind>[<i>].signature_block`, an array element bracketed and a key
+	 * dotted. The same spelling `Diagnostic.path` uses, so the two join on
+	 * string equality.
 	 */
 	field: string;
 	/** 0-based page index. */
@@ -343,36 +349,6 @@ export interface PageSize {
 	heightPt: number;
 }
 
-/** Inputs to `paint`. */
-export interface PaintOptions {
-	/** How big the page is on screen, in CSS px per point. Default 1. */
-	layoutScale?: number;
-	/**
-	 * How sharp it is: `window.devicePixelRatio`, in-app zoom and
-	 * `visualViewport.scale` folded into one number. Default 1, because the
-	 * painter cannot see any of them (SSR, tests, off-screen).
-	 */
-	densityScale?: number;
-}
-
-/** Output of `paint`. */
-export interface PaintResult {
-	layoutWidth: number;      // canvas.style.width target; independent of densityScale
-	layoutHeight: number;
-	pixelWidth: number;       // canvas.width the painter wrote (clamped at 16384)
-	pixelHeight: number;
-	/**
-	 * True when the backing-store clamp forced `densityScale` down: the page
-	 * renders soft at the same `canvas.style` size.
-	 */
-	clamped: boolean;
-	/**
-	 * The `densityScale` actually applied, reduced proportionally when
-	 * `clamped`. `layoutScale × effectiveDensityScale` is the rasterized scale.
-	 */
-	effectiveDensityScale: number;
-}
-
 /**
  * Output of {@link LiveSession.update}: `dirtyPages` lists the pages whose
  * content differs from the previous compile, including added pages; removed
@@ -425,21 +401,27 @@ export declare class Engine {
 	 * synchronously before the first await, so the caller may `free()` them as
 	 * soon as this call returns.
 	 *
-	 * This is the surface that merges the two warning halves:
-	 * {@link RenderResult.warnings} carries `doc.warnings` (parse, `conform::*`,
-	 * `plate::unsupported_construct`) ahead of the compile's own. A
-	 * {@link LiveSession} outlives the document it opened from, so
-	 * {@link LiveSession.render} carries the compile half alone.
+	 * {@link RenderResult.warnings} carries the whole pipeline's, in order:
+	 * `doc.warnings` (parse and `conform::*`), every `quill.validate(doc)`
+	 * warning, then the compile's own. A {@link LiveSession} outlives the
+	 * document it opened from, so {@link LiveSession.render} carries the
+	 * compile's alone: read `doc.warnings` and `quill.validate(doc)` beside it.
+	 *
+	 * `today` reads as on {@link open}.
 	 */
-	render(quill: Quill, doc: Document, options?: RenderOptions): Promise<RenderResult>;
+	render(quill: Quill, doc: Document, options?: RenderOptions, today?: string): Promise<RenderResult>;
 
 	/**
 	 * Open a live render session (canvas preview / per-page paint / `update`).
 	 * The `quill` and `doc` handles are read synchronously before the first
 	 * await, so the caller may `free()` them as soon as this call returns; the
 	 * caller owns the returned session and must `.free()` it.
+	 *
+	 * `today` (`YYYY-MM-DD`, default the local date) is the render date: a
+	 * `today` date field renders as it, and so does a plate's
+	 * `datetime.today()`. The session keeps it for every `update`.
 	 */
-	open(quill: Quill, doc: Document): Promise<LiveSession>;
+	open(quill: Quill, doc: Document, today?: string): Promise<LiveSession>;
 
 	/**
 	 * Output formats `quill`'s backend can emit. An always-free pre-render probe:
@@ -504,15 +486,17 @@ export declare class LiveSession {
 	 * The schema field whose content is under a point on `page`: the canonical
 	 * `DocPath` address to focus in the editor, or `undefined` off any field's
 	 * ink. `x`/`y` are PDF points with a **bottom-left** origin, the same space as
-	 * {@link FieldRegion.rect}, so from a canvas click invert the overlay
-	 * transform documented there: `x = clickPx.x / renderScale`,
-	 * `y = pageHeightPt - clickPx.y / renderScale`. Unlike {@link regions},
+	 * {@link FieldRegion.rect}. A pointer event reports CSS pixels, so divide by
+	 * the CSS px per point the page is shown at,
+	 * `k = canvas.clientWidth / pageWidthPt`, not by {@link paint}'s `scale`,
+	 * which carries `devicePixelRatio`: `x = e.offsetX / k`,
+	 * `y = pageHeightPt - e.offsetY / k`. Unlike {@link regions},
 	 * *every* placement answers, not just the first.
 	 *
 	 * `tolPt` is how far off the ink a click still counts, in the same points,
 	 * and defaults to `0` — exact. It is pointer slack, so derive it from the
-	 * scale the page was drawn at (`slackPx / renderScale`) rather than fixing a
-	 * value in points, which shrinks under the cursor as the page zooms out. The
+	 * same `k` (`slackPx / k`) rather than fixing a value in points, which
+	 * shrinks under the cursor as the page zooms out. The
 	 * nearest placement answers and containment is distance zero, so raising
 	 * `tolPt` only ever fills a miss.
 	 */
@@ -531,14 +515,16 @@ export declare class LiveSession {
 	 * canonical `DocPath` address (`parseDocPath`-routable), as {@link regions} keys.
 	 */
 	locate(field: string, pos: number): FieldRegion | undefined;
-	/** Page geometry in points (1/72″). Report-only; the painter sizes the canvas. */
+	/** Page geometry in points (1/72″). */
 	pageSize(page: number): PageSize;
 	/**
-	 * Paint `page` into a 2D canvas context, sizing the backing store itself (it
-	 * owns `canvas.width`/`height`; the caller owns `canvas.style.*`). The
-	 * rasterization scale is `layoutScale × densityScale`, clamped so neither
-	 * backing dimension exceeds 16384 px; {@link PaintResult.clamped} reports the
-	 * clamp and {@link PaintResult.effectiveDensityScale} the density applied.
+	 * Paint `page` into a 2D canvas context at `scale` backing-store pixels per
+	 * point: `devicePixelRatio` times the CSS px per point the page is shown at.
+	 * The painter owns `canvas.width`/`height`, reducing `scale` where it must so
+	 * neither exceeds 16384 px, so `canvas.width / widthPt` is the scale painted
+	 * at; the caller owns `canvas.style.*`, and a canvas styled `width: 100%`
+	 * needs nothing back from the paint. Throws `backend::invalid_raster_scale`
+	 * on a `scale` that is not finite and positive.
 	 *
 	 * The write is a whole-backing-store `putImageData`, which bypasses the 2D
 	 * context transform, `globalAlpha`, and clip, so give each visible page its
@@ -551,8 +537,8 @@ export declare class LiveSession {
 	paint(
 		ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D,
 		page: number,
-		options?: PaintOptions
-	): PaintResult;
+		scale: number
+	): void;
 	free(): void;
 }
 
@@ -656,8 +642,8 @@ export declare class CardWriter {
 	/** The bound card index. */
 	readonly index: number;
 	/**
-	 * The bound card's `$kind`, empty string when it carries none. Throws
-	 * `IndexOutOfRange` for a bad bound index.
+	 * The bound card's `$kind`. Throws `IndexOutOfRange` for a bad bound
+	 * index.
 	 */
 	readonly kind: string;
 	set(name: string, value: unknown): void;
@@ -738,10 +724,11 @@ export declare class DocumentReader {
 	 * The resolved-value view: for every declared field, the value the render
 	 * projection would use and the rung it came from (`authored` / `default` /
 	 * `blank`). The one read that blank-fills and coerces; {@link get} reports
-	 * what the document carries. Value and provenance only; completeness stays
-	 * `quill.validate`'s.
+	 * what the document carries. Value and provenance only; diagnostics stay
+	 * `quill.validate`'s. `today` reads as on {@link Engine.open}; an editor
+	 * pairing it with a session passes the session's opening date.
 	 */
-	resolve(): Resolved;
+	resolve(today?: string): Resolved;
 	/**
 	 * A {@link CardReader} for the composable card at `index`. Index validity is
 	 * checked lazily at read time, so an out-of-range index does not throw here.
@@ -762,8 +749,8 @@ export declare class CardReader {
 	/** The bound card index. */
 	readonly index: number;
 	/**
-	 * The bound card's `$kind` (empty string when it carries none). Throws
-	 * `IndexOutOfRange` if the bound index is out of range.
+	 * The bound card's `$kind`. Throws `IndexOutOfRange` if the bound index is
+	 * out of range.
 	 */
 	readonly kind: string;
 	/**

package/runtime/runtime.js

@@ -20,6 +20,7 @@ import initCore, { Quill, Document } from '../core/wasm.js';
 // Resolution-time, so `node:fs` never enters a browser graph.
 import { toModuleSource } from '#quillmark-env';
 import { importMarkdown, exportMarkdown, rebase, mapPos, mapMarks } from '../core/wasm.js';
+import { isInline, isPlain } from '../core/wasm.js';
 import { parseDocPath, formatDocPath, formatDiagnostic } from '../core/wasm.js';
 
 // A `--target web` build exports its classes synchronously but carries no wasm
@@ -49,6 +50,8 @@ const CORE_SURFACE = Object.freeze({
 	rebase,
 	mapPos,
 	mapMarks,
+	isInline,
+	isPlain,
 	parseDocPath,
 	formatDocPath,
 	formatDiagnostic
@@ -519,15 +522,16 @@ export class Engine {
 	 * @param {Quill} quill
 	 * @param {Document} doc
 	 * @param {object} [options] render options (`{ format, ppi, pages, regions }`)
+	 * @param {string} [today] the render date, `YYYY-MM-DD`
 	 * @returns {Promise<import('./runtime.js').RenderResult>}
 	 */
-	async render(quill, doc, options) {
+	async render(quill, doc, options, today) {
 		return this.#withClones(
 			'engine.render(quill, doc)',
 			quill,
 			doc,
 			({ engine, quill: q, doc: d, docWarnings }) => {
-				const result = engine.render(q, d, options ?? undefined);
+				const result = engine.render(q, d, options ?? undefined, today);
 				result.warnings = docWarnings.concat(result.warnings);
 				return result;
 			}
@@ -537,14 +541,15 @@ export class Engine {
 	/**
 	 * @param {Quill} quill
 	 * @param {Document} doc
+	 * @param {string} [today] the render date, `YYYY-MM-DD`
 	 * @returns {Promise<LiveSession>}
 	 */
-	async open(quill, doc) {
+	async open(quill, doc, today) {
 		return this.#withClones(
 			'engine.open(quill, doc)',
 			quill,
 			doc,
-			({ mod, engine, quill: q, doc: d }) => new LiveSession(engine.open(q, d), mod)
+			({ mod, engine, quill: q, doc: d }) => new LiveSession(engine.open(q, d, today), mod)
 		);
 	}
 
@@ -660,10 +665,10 @@ export class LiveSession {
 	/**
 	 * @param {CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D} ctx
 	 * @param {number} page
-	 * @param {object} [options]
+	 * @param {number} scale
 	 */
-	paint(ctx, page, options) {
-		return this.#inner.paint(ctx, page, options);
+	paint(ctx, page, scale) {
+		this.#inner.paint(ctx, page, scale);
 	}
 
 	free() {
@@ -866,10 +871,11 @@ export class DocumentReader {
 		return this.#doc._readerGet(this.#quill, {});
 	}
 	/**
+	 * @param {string} [today] the render date, `YYYY-MM-DD`
 	 * @returns {Resolved}
 	 */
-	resolve() {
-		return this.#quill._resolve(this.#doc);
+	resolve(today) {
+		return this.#quill._resolve(this.#doc, today);
 	}
 	/**
 	 * @param {number} index