@quillmark/wasm 0.112.0 → 0.114.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,1511 +0,0 @@
1
- /* tslint:disable */
2
- /* eslint-disable */
3
-
4
- /**
5
- * A path to a value nested inside a field `value`: `string` keys and
6
- * `number` array indices, e.g. `["addr", "street"]` or `["recipients", 0, "name"]`.
7
- */
8
- export type PathStep = string | number;
9
-
10
- /** A field or comment entry in a `Card.payloadItems` list. */
11
- export type PayloadItem =
12
- | {
13
- type: "field";
14
- key: string;
15
- value: unknown;
16
- fill?: boolean;
17
- /**
18
- * Paths to `!must_fill` markers nested *inside* `value` (the `value`
19
- * projection itself is fill-free). Absent when the field has no nested
20
- * placeholders. Preserved across `insertCard` / `makeCard`.
21
- */
22
- nestedFills?: PathStep[][];
23
- }
24
- | { type: "comment"; text: string; inline?: boolean };
25
-
26
- /**
27
- * A single card block, as read back from a document. Every `Card` is a valid
28
- * `CardInput`, so a card read from one document pushes straight into another.
29
- *
30
- * `$` system entries are hoisted to named fields: `kind` (the `$kind`, empty
31
- * string when none), `quill` (`$quill` `name@version`, main card only), `ext`
32
- * (`$ext`), and `seed` (the `$seed` per-kind overlay map, main card only).
33
- * `payloadItems` carries user fields and comments in order.
34
- */
35
- export interface Card {
36
- kind: string;
37
- quill?: string;
38
- ext?: Record<string, unknown>;
39
- seed?: Record<string, unknown>;
40
- payloadItems: PayloadItem[];
41
- /**
42
- * The card body as canonical `Content`, never a markdown string. For the
43
- * markdown projection call `exportMarkdown(card.body)`.
44
- */
45
- body: Content;
46
- }
47
-
48
- /**
49
- * A card written *into* a document, accepted by `Document.insertCard`. Like
50
- * `Card`, but `body` also takes a markdown `string`, and every field but `kind`
51
- * is optional (defaulting to no payload items and an empty body).
52
- */
53
- export interface CardInput {
54
- kind: string;
55
- quill?: string;
56
- ext?: Record<string, unknown>;
57
- seed?: Record<string, unknown>;
58
- payloadItems?: PayloadItem[];
59
- body?: Content | string;
60
- }
61
-
62
- /**
63
- * Canonical richtext content: the model behind a card body and richtext fields.
64
- * One text sequence over a single coordinate space (Unicode scalar values):
65
- * `text` plus line attributes, anchored `marks`, and embedded `islands`. Every
66
- * edit is a splice; markdown is a projection, not the model.
67
- */
68
- export interface Content {
69
- text: string;
70
- lines: ContentLine[];
71
- marks: ContentMark[];
72
- islands: ContentIsland[];
73
- }
74
-
75
- /** One `\n`-separated segment of `Content.text`, in order. `kind` is an open set:
76
- * an unknown role round-trips with opaque `attrs` and renders as a paragraph.
77
- * Every role spells its payload in `attrs`, known or not, so promoting one moves
78
- * no bytes. The open arm blocks discriminant narrowing, so read
79
- * `attrs.level`/`attrs.lang` behind a check of the arm you want. */
80
- export type ContentLine = {
81
- containers: ContentContainer[];
82
- /** A within-block hard line break rather than a new block. Omitted (false) in the common case. */
83
- continues?: boolean;
84
- } & ContentLineKind;
85
-
86
- /** A line's block role, shared by `ContentLine` and the `setKind` op. */
87
- export type ContentLineKind =
88
- | { kind: "para" }
89
- | { kind: "heading"; attrs: { level: number } }
90
- | { kind: "code"; attrs?: { lang?: string } }
91
- | { kind: "island" }
92
- | { kind: "rule" }
93
- | { kind: string; attrs?: unknown };
94
-
95
- /** An ancestor block a line nests inside, outermost first. Open like
96
- * `ContentLine.kind`: an unrecognized container round-trips with opaque `attrs`
97
- * and renders transparently (its lines sit at the enclosing level).
98
- *
99
- * Two adjacent lines sit in the same container iff their whole path matches, so
100
- * `instance` is what tells one container from an adjacent sibling of identical
101
- * shape — two consecutive quotes, two consecutive lists — which contiguity
102
- * alone reads as one.
103
- *
104
- * **A writer owes a distinct value per adjacent sibling run**, not merely a
105
- * value. Runs of one shape sharing one arrive as one: a second list's items come
106
- * back as continuation paragraphs of the first, markers gone. The field is
107
- * required, so a checker reports the omission; it cannot report a `0` stamped on
108
- * both, which is the same write. A codec flattening a tree takes them from
109
- * `assignInstances` in `@quillmark/wasm/runtime` rather than by hand. Any
110
- * distinct pair works; a write is canonicalized to `0`/`1`.
111
- *
112
- * Reading is not the mirror of writing. Every read spells the field, the `0` on
113
- * a container with nothing to be told apart from included. A read also carries a
114
- * discriminator on pairs no writer had to spell: `1.` beside a list starting at
115
- * `3` differs by `start`, so those runs arrive apart with nothing written, and
116
- * the canonical form spends one anyway because Markdown reads only a list's
117
- * first number.
118
- *
119
- * Content parsed from a stored document is the one shape that arrives without
120
- * it — storage omits a zero — and needs a cast. */
121
- export type ContentContainer =
122
- | {
123
- container: "list_item";
124
- attrs: { ordered: boolean; start: number; ordinal: number };
125
- instance: number;
126
- }
127
- | { container: "quote"; instance: number }
128
- | { container: string; attrs?: unknown; instance: number };
129
-
130
- /** A mark over char range `[start, end)` into `Content.text`. The open `type`
131
- * arm blocks discriminant narrowing, so read a payload-carrying arm behind its
132
- * guard: `isLinkMark` (`attrs.url`) / `isAnchorMark` (`attrs.id`), from
133
- * `@quillmark/wasm/runtime`. An `anchor`'s `id` is a caller-supplied opaque
134
- * handle, unique per `Content` and invariant while the mark lives (positions
135
- * rebase, the id never does); it has no markdown projection and survives only
136
- * through the edit lane. */
137
- export type ContentMark = { start: number; end: number } & (
138
- | { type: "strong" | "emph" | "underline" | "strike" | "code" }
139
- | { type: "link"; attrs: { url: string } }
140
- | { type: "anchor"; attrs: { id: string } }
141
- | { type: string; attrs?: unknown }
142
- );
143
-
144
- /** A cell in a `TableProps`. `marks` rides the prose `ContentMark` shape, but
145
- * each mark's `start`/`end` are USV offsets into this cell's `text`, not into
146
- * `Content.text`. */
147
- export interface TableCell {
148
- text: string;
149
- marks: ContentMark[];
150
- }
151
-
152
- /** `props` of a `type: "table"` island: a pipe table normalized to one column
153
- * count that `header`, every row of `rows`, and `aligns` all share. */
154
- export interface TableProps {
155
- header: TableCell[];
156
- rows: TableCell[][];
157
- /** Per-column alignment, one entry per column. */
158
- aligns: ("none" | "left" | "center" | "right")[];
159
- }
160
-
161
- /** `props` of a `type: "image"` island. */
162
- export interface ImageProps {
163
- url: string;
164
- alt: string;
165
- }
166
-
167
- /** How faithfully the markdown projection can carry an island. Open: an unknown
168
- * class round-trips verbatim and reads as `unrepresentable`. */
169
- export type ContentLossClass = "lossless" | "degraded" | "unrepresentable" | (string & {});
170
-
171
- /** A structured object occupying one island slot in `Content.text`. `type` is an
172
- * open set: `props` is `TableProps` for `table` and `ImageProps` for `image`,
173
- * and any other type round-trips with opaque `props`. The open arm blocks
174
- * narrowing, so read `props` behind the `isTableIsland` / `isImageIsland`
175
- * guards (from `@quillmark/wasm/runtime`). */
176
- export type ContentIsland = {
177
- id: string;
178
- loss: ContentLossClass;
179
- } & (
180
- | { type: "table"; props: TableProps }
181
- | { type: "image"; props: ImageProps }
182
- | { type: string; props: unknown }
183
- );
184
-
185
- /**
186
- * A write address: one navigation concept for the whole `Document` surface. An
187
- * absent `field` targets the card body; an absent `card` targets the main card.
188
- * `{}` is the main-card body; `{ card: 2 }` the body of the composable card at
189
- * index 2; `{ field: "intro" }` the main card's `intro` field; `{ card: 2,
190
- * field: "intro" }` a card field.
191
- *
192
- * On the `Addr`-taking verbs a **bare string** is shorthand for `{ field: name }`
193
- * (`doc.storeField("qty", 3)`); a bare number is *not* an addr.
194
- *
195
- * `doc.pathFor(addr)` mints the address as its canonical `DocPath` string, the
196
- * anchor `Diagnostic.path` carries and `session.locate` / `session.fieldBoxes`
197
- * take. A card path is kind-qualified, so a hand-built one needs the card's
198
- * `$kind`, and a wrong-kind path matches nothing silently.
199
- *
200
- * An `Addr` names a field, never a value inside one: every verb that takes one
201
- * would then carry an element axis it cannot answer. The one read that reaches
202
- * inside takes the path as its own argument, `reader.getContentAt(addr, path)`.
203
- */
204
- export interface Addr {
205
- card?: number;
206
- field?: string;
207
- }
208
-
209
- /**
210
- * A card-only address, taken by the card-scoped verbs (`storeFields`,
211
- * `storeExt`, `getExt`, `commitFields`, …). An absent `card` targets the main
212
- * card; a present `field` throws.
213
- */
214
- export interface CardAddr {
215
- card?: number;
216
- }
217
-
218
- /**
219
- * A text-splice change set over the USV content (CodeMirror `ChangeSet`
220
- * semantics), returned by `revise` and by the `rebase` codec. Map a stored
221
- * position through it with `mapPos`.
222
- */
223
- export interface Delta {
224
- ops: ({ retain: number } | { insert: string } | { delete: number })[];
225
- }
226
-
227
- /** Which side of a same-position insertion `mapPos` lands a point on. */
228
- export type Assoc = "before" | "after";
229
-
230
- /**
231
- * A mark edit in final-text coordinates (post-delta, post-line-op). `add` /
232
- * `remove` carry the `ContentMark` vocabulary; `removeAnchor` drops one identity
233
- * anchor by id. An `add` of an `anchor` requires a non-empty `id` not already
234
- * live in the field; a collision or the empty id throws.
235
- */
236
- export type MarkOp =
237
- | ({ op: "add" | "remove"; start: number; end: number } & (
238
- | { type: "strong" | "emph" | "underline" | "strike" | "code" }
239
- | { type: "link"; url: string }
240
- | { type: "anchor"; id: string }
241
- | { type: string; attrs: unknown }
242
- ))
243
- | { op: "removeAnchor"; id: string };
244
-
245
- /**
246
- * A line/block edit. `split`/`join` splice `\n` in post-`delta`,
247
- * post-`islandOps` coordinates; `setKind`/`setContainers`/`setContinues` touch
248
- * metadata. `setContinues` sets or clears a line's within-block hard-break flag
249
- * (`ContentLine.continues`); `continues: true` on line 0 is rejected.
250
- */
251
- export type LineOp =
252
- | { op: "split"; at: number }
253
- | { op: "join"; line: number }
254
- | ({ op: "setKind"; line: number } & ContentLineKind)
255
- | { op: "setContainers"; line: number; containers: ContentContainer[] }
256
- | { op: "setContinues"; line: number; continues: boolean };
257
-
258
- /**
259
- * An island edit: the only channel that reaches an island's payload, a table's
260
- * cells or an image's url. Both ops leave the field's text and marks alone, so
261
- * an island edit keeps every identity anchor in the field.
262
- *
263
- * `set` addresses an existing island by `id`; an unknown `id` throws. `insert`
264
- * places a new island's slot at `at` together with its entry, so a slot never
265
- * exists without an island behind it; its `id` must be non-empty and unused.
266
- * `at` is a position in the text the `delta` and this bundle's earlier island
267
- * ops left, so slots after `a` and `b` of `abc` go in at 1 and 3. A stale frame
268
- * misplaces slots and never throws. A `delta` insert string may not carry a
269
- * slot, which would orphan: split such a splice into the slot-free `delta` plus
270
- * one `insert` per slot.
271
- *
272
- * Deleting an island needs no op: a `delta` that removes its slot drops the
273
- * island whole, and a block island's line demotes to `para`. Re-landing it is an
274
- * `insert` of the full island under its original id; a pasted copy of a live
275
- * island mints a fresh one.
276
- *
277
- * A `set` stores the `loss` it is given; nothing re-derives the class from the
278
- * new `props`.
279
- *
280
- * An island is *inline* (a slot inside a paragraph) unless its line says
281
- * otherwise. A **block** island is one bundle of all three channels, in the
282
- * order they apply: `delta` inserts the `\n` that opens the line, `islandOps`
283
- * inserts the slot, `lineOps` tags the line `{ op: "setKind", kind: "island" }`.
284
- * `{ op: "split" }` cannot open that line, since line ops run after island ops.
285
- */
286
- export type IslandOp =
287
- | ({ op: "set" } & ContentIsland)
288
- | ({ op: "insert"; at: number } & ContentIsland);
289
-
290
- /**
291
- * A committed content edit bundle for `applyChange`, applied in order: a text
292
- * `delta`, then `islandOps`, then `lineOps`, then `markOps` (mark ranges are in
293
- * final-text coordinates). Every field is optional.
294
- *
295
- * Within each channel ops apply in sequence against the state the earlier ones
296
- * left: an island `insert`'s `at` counts earlier ops' slots, and `lineOps`
297
- * positions and indices renumber through earlier `split`/`join`.
298
- *
299
- * **Mark rebase.** `delta`, `islandOps` and `lineOps` each move text, and each
300
- * rebases the marks already in the field by one rule: a range mark's `start`
301
- * takes assoc `after` and its `end` `before`, so an insertion at either edge
302
- * grows text *outside* the span; a **zero-width** mark takes `before`, so an
303
- * insertion at its own position leaves it put. That last case is the one
304
- * position where the two assocs differ, and where an anchor most often sits.
305
- *
306
- * `markOps` name the result, so a caller emitting them predicts this rebase.
307
- * `mapMarks(content, bundle)` runs it instead: pass the bundle's text-moving
308
- * channels, diff the marks it returns against the ones you intend, and emit
309
- * only the difference. Reproducing the rule by hand is a second copy to drift.
310
- */
311
- export interface ChangeBundle {
312
- delta?: Delta;
313
- islandOps?: IslandOp[];
314
- lineOps?: LineOp[];
315
- markOps?: MarkOp[];
316
- }
317
-
318
-
319
-
320
- /**
321
- * One segment of a parsed `Diagnostic.path` (see `parseDocPath`). The head
322
- * carries the document-model root: `main` (only before `body`), a `card`
323
- * (`kind: null` is the unknown-kind `cards[i]` form), or a `field`; the tail is
324
- * `field` / `index` / a terminal `body`.
325
- */
326
- export type DocPathSeg =
327
- | { seg: "main" }
328
- | { seg: "card"; kind: string | null; index: number }
329
- | { seg: "field"; name: string }
330
- | { seg: "index"; index: number }
331
- | { seg: "body" };
332
-
333
-
334
-
335
- /**
336
- * Page dimensions in points (1 pt = 1/72 inch). Report-only: the painter sizes
337
- * the canvas itself from `PaintOptions`. `pageSize` is for callers that need
338
- * page geometry up-front, e.g. to lay out a scrollable list of canvases.
339
- */
340
- export interface PageSize {
341
- widthPt: number;
342
- heightPt: number;
343
- }
344
-
345
- /**
346
- * Inputs to `LiveSession.paint`. Both default to `1`, must be finite and `> 0`,
347
- * and multiply to the effective rasterization scale.
348
- *
349
- * - `layoutScale`: layout-space pixels per point — CSS pixels per pt for an
350
- * on-screen canvas — surfaced back as `layoutWidth` / `layoutHeight`.
351
- * - `densityScale`: backing-store density. Fold `window.devicePixelRatio`,
352
- * in-app zoom, and `visualViewport.scale` into this one value; the default
353
- * `1` produces a non-retina backing store.
354
- */
355
- export interface PaintOptions {
356
- layoutScale?: number;
357
- densityScale?: number;
358
- }
359
-
360
- /**
361
- * Returned by `LiveSession.paint`.
362
- *
363
- * - `layoutWidth` / `layoutHeight`: the display box, in CSS pixels for an
364
- * on-screen canvas, to drive `canvas.style.*`. Independent of `densityScale`.
365
- * - `pixelWidth` / `pixelHeight`: the backing store the painter wrote to
366
- * `canvas.width` / `canvas.height`, `round(layout * densityScale)` unless the
367
- * request exceeded 16384 px per side and `densityScale` was clamped to fit.
368
- * - `clamped`: `true` when that clamp fired, so the page renders soft at the
369
- * same `canvas.style` size.
370
- * - `effectiveDensityScale`: the `densityScale` actually applied.
371
- *
372
- * The painter owns `canvas.width` / `canvas.height` and never touches
373
- * `canvas.style.*`. The write is a whole-backing-store `putImageData`, which
374
- * bypasses the 2D context transform, `globalAlpha`, and clip: give each visible
375
- * page its own `<canvas>`, since no compositing, sub-rect, or transform reaches
376
- * through `paint`. Under `OffscreenCanvasRenderingContext2D` the layout
377
- * dimensions are informational — there is no CSS box to apply them to.
378
- */
379
- export interface PaintResult {
380
- layoutWidth: number;
381
- layoutHeight: number;
382
- pixelWidth: number;
383
- pixelHeight: number;
384
- clamped: boolean;
385
- effectiveDensityScale: number;
386
- }
387
-
388
-
389
-
390
- /**
391
- * The commitment-ladder rung that produced a `ResolvedField.value`.
392
- *
393
- * A container has no rung of its own — it is a namespace, and its value is the
394
- * composition of its cells' — so it reports the strongest rung that contributed:
395
- * `authored` if the document wrote any of it, else `default` if any cell below
396
- * resolved to one, else `blank`.
397
- */
398
- export type FieldSource = "authored" | "default" | "blank";
399
-
400
- /**
401
- * One resolved row: its `name`, the value the render projection would use, and
402
- * the `FieldSource` rung it came from. Rows are an ordered array, so declaration
403
- * order is structural rather than object-key order.
404
- */
405
- export interface ResolvedField {
406
- name: string;
407
- value: unknown;
408
- source: FieldSource;
409
- }
410
-
411
- /**
412
- * The main card's resolved rows in declaration order, plus its body row:
413
- * `null` when the main enables no body.
414
- */
415
- export interface ResolvedMain {
416
- fields: ResolvedField[];
417
- body: ResolvedField | null;
418
- }
419
-
420
- /**
421
- * One composable card's resolved rows in declaration order, with its authored
422
- * `kind` (`null` for an unknown-kind card), its document-array `index`, and its
423
- * body row: `null` when the kind enables no body.
424
- */
425
- export interface ResolvedCard {
426
- kind: string | null;
427
- index: number;
428
- fields: ResolvedField[];
429
- body: ResolvedField | null;
430
- }
431
-
432
- /**
433
- * The resolved-value view (`Quill.resolve`): the main card and every composable
434
- * card. Value and provenance only; completeness stays `Quill.validate`'s.
435
- */
436
- export interface Resolved {
437
- main: ResolvedMain;
438
- cards: ResolvedCard[];
439
- }
440
-
441
-
442
-
443
- /** UI layout hints for a single field. Display order is not a hint: key order
444
- * in the schema's `fields`/`properties` objects is the ordering contract. */
445
- export interface QuillFieldUi {
446
- title?: string;
447
- group?: string;
448
- compact?: boolean;
449
- multiline?: boolean;
450
- /** Label for an `enum`'s blank option. Absent, the consumer supplies a
451
- * conventional label of its own. */
452
- blank_title?: string;
453
- }
454
-
455
- /** One entry in a card's `ui.groups` registry: a display-label override for the
456
- * group id (the map key). An empty object carries no override, and the consumer
457
- * derives the label from the id (`memo_for` → "Memo For"). */
458
- export interface QuillGroupUi {
459
- title?: string;
460
- }
461
-
462
- /** UI layout hints for a card (main or named card kind). */
463
- export interface QuillCardUi {
464
- title?: string;
465
- /** The groups a field's `ui.group` may reference, keyed by group id. Key
466
- * order is the display-order contract, as with `fields`. Absent when the
467
- * card declares no groups. */
468
- groups?: Record<string, QuillGroupUi>;
469
- }
470
-
471
- /** A block construct a body can hold. `paragraph` is the floor and cannot be
472
- * declined, so it is absent. */
473
- export type QuillBlockConstruct =
474
- | "heading"
475
- | "rule"
476
- | "code"
477
- | "list"
478
- | "quote"
479
- | "table"
480
- | "image";
481
-
482
- /** Body namespace for a card (main or named card kind). */
483
- export interface QuillCardBody {
484
- /** When false, consumers must not accept or store body content for this card kind. Defaults to true. */
485
- enabled?: boolean;
486
- /** Example body content embedded verbatim in the blueprint body region. Fallback is "Write <card> body here." */
487
- example?: string;
488
- /** Block constructs this quill's plate does not typeset in this body;
489
- * absent or empty declines nothing. A body that holds one anyway draws a
490
- * non-fatal `plate::unsupported_construct` warning. Nothing verifies the
491
- * claim: absence from this list is not a promise the plate typesets it. */
492
- unsupported?: QuillBlockConstruct[];
493
- }
494
-
495
- /** Schema entry for a single field declared in a quill's `Quill.yaml`.
496
- *
497
- * One declaration, and no `required` key. `default` and `example` say what the
498
- * cell holds, and `default`'s absence is the obligation: a field nobody
499
- * declared a value for carries a `!must_fill` marker in the blueprint and warns
500
- * `validation::must_fill` while the document leaves it unauthored. Neither
501
- * gates render: an absent field blank-fills.
502
- */
503
- export interface QuillFieldSchema {
504
- type: "string" | "number" | "integer" | "boolean" | "array" | "object" | "date" | "datetime" | "richtext" | "plaintext" | "enum";
505
- description?: string;
506
- default?: unknown;
507
- example?: unknown;
508
- /** The closed set of allowed values. Required on `type: "enum"`, and valid
509
- * nowhere else. */
510
- values?: string[];
511
- /** Per-member field sets on a card-level `type: "enum"` field, keyed by
512
- * member: the fields that exist only where the discriminant holds that
513
- * member. Declaring it makes the field rest as a container,
514
- * `{value: <member>, …that member's fields}`, rather than a bare string. */
515
- variants?: Record<string, Record<string, QuillFieldSchema>>;
516
- ui?: QuillFieldUi;
517
- properties?: Record<string, QuillFieldSchema>;
518
- items?: QuillFieldSchema;
519
- /** `true` on a `richtext` or `plaintext` field declared `inline`: the
520
- * single-paragraph, container-free, island-free constraint. */
521
- inline?: boolean;
522
- }
523
-
524
- /** Schema entry for the main card or a named card kind. */
525
- export interface QuillCardSchema {
526
- description?: string;
527
- fields: Record<string, QuillFieldSchema>;
528
- ui?: QuillCardUi;
529
- body?: QuillCardBody;
530
- }
531
-
532
- /**
533
- * Document schema returned by `Quill.schema`: the user-fillable fields only.
534
- * The quill reference (`${metadata.name}@${metadata.version}`) and card-kind
535
- * discriminators are document-level metadata, not schema fields.
536
- */
537
- export interface QuillSchema {
538
- main: QuillCardSchema;
539
- /** Present only when the quill declares at least one named card kind. */
540
- card_kinds?: Record<string, QuillCardSchema>;
541
- }
542
-
543
- /**
544
- * Identity snapshot mirroring the `quill:` section of `Quill.yaml`. The schema
545
- * lives on `Quill.schema`; output formats are a resolved-backend capability read
546
- * from `Quillmark.supportedFormats`, not part of this config snapshot.
547
- */
548
- export interface QuillMetadata {
549
- name: string;
550
- version: string;
551
- backend: string;
552
- author: string;
553
- description: string;
554
- }
555
-
556
-
557
- /**
558
- * A resolved point → content position: the field a click landed in and the USV
559
- * offset into its `Content`. The `LiveSession.positionAt` result, inverse of
560
- * `locate`.
561
- */
562
- export interface ContentHit {
563
- /**
564
- * Canonical `DocPath` field address (same grammar as `FieldRegion.field`).
565
- */
566
- field: string;
567
- /**
568
- * USV offset into the field's `Content`.
569
- */
570
- pos: number;
571
- /**
572
- * `undefined` when the backend does not report granularity.
573
- */
574
- granularity?: HitGranularity;
575
- }
576
-
577
- /**
578
- * A schema field address plus its geometry on the page, for scrolling to or
579
- * highlighting a field; use `LiveSession.fieldAt` for the click direction.
580
- *
581
- * `field` is **not** unique: content fields surface one region per segment
582
- * (paragraph, heading, whole code fence) and per page each touches, a scalar
583
- * referenced at several plate sites surfaces each site, and tracked content
584
- * plus a `field:`-bound widget yields both. Group by `field`. The whole-field
585
- * highlight is the union of a page's `span`-bearing rects, so inter-paragraph
586
- * whitespace stays uncovered; `LiveSession.fieldBoxes(field)` owns that union.
587
- */
588
- export interface FieldRegion {
589
- /**
590
- * Canonical `DocPath` field address (e.g. `"cards.indorsement[1].from"`):
591
- * the grammar `parseDocPath` reads and `Diagnostic.path` carries. Feed it
592
- * back to `fieldBoxes` / `locate`.
593
- */
594
- field: string;
595
- /**
596
- * 0-based page index.
597
- */
598
- page: number;
599
- /**
600
- * `[x0, y0, x1, y1]` in PDF points (1/72″), bottom-left origin.
601
- */
602
- rect: [number, number, number, number];
603
- /**
604
- * The slice this box covers: USV `[start, end)` into the field's `Content`
605
- * for one content segment, `undefined` for a scalar site or widget.
606
- */
607
- span?: [number, number];
608
- }
609
-
610
- /**
611
- * Diagnostic message (error or warning)
612
- */
613
- export interface Diagnostic {
614
- severity: Severity;
615
- code?: string;
616
- message: string;
617
- location?: Location;
618
- /**
619
- * Document-model path anchor (e.g. `"cards.indorsement[0].signature_block"`),
620
- * set on schema validation diagnostics and `undefined` otherwise.
621
- */
622
- path?: string;
623
- hint?: string;
624
- /**
625
- * The facts `message` interpolates, keyed by name. With `code`, enough to
626
- * word this diagnostic in another language.
627
- *
628
- * Declared optional explicitly: `tsify` does not read
629
- * `skip_serializing_if`, so an omitted field would be declared required.
630
- */
631
- args?: Record<string, unknown>;
632
- sourceChain?: string[];
633
- }
634
-
635
- /**
636
- * How precisely a `ContentHit.pos` resolved. Never sub-cluster: `cluster` is
637
- * the finest this API offers, `segment` the floor it degrades to.
638
- */
639
- export type HitGranularity = "cluster" | "segment";
640
-
641
- /**
642
- * Options for rendering.
643
- */
644
- export interface RenderOptions {
645
- format?: OutputFormat;
646
- /**
647
- * Pixels per inch for PNG; ignored for PDF and SVG. Defaults to 144.0.
648
- */
649
- ppi?: number;
650
- /**
651
- * 0-based page indices to render; `undefined` renders all pages. An index
652
- * `>= pageCount` throws `typst::page_index_out_of_bounds`. Not supported
653
- * for PDF output: throws `typst::pdf_page_selection_not_supported`.
654
- */
655
- pages?: number[];
656
- /**
657
- * PDF `/Info` `/Producer` override; defaults to `Quillmark <version>`.
658
- */
659
- producer?: string;
660
- /**
661
- * Populate `RenderResult.regions` with schema-field geometry, for consumers
662
- * without a live session. Defaults to `false`. Page indices are
663
- * document-space even when `pages` selects a subset.
664
- */
665
- regions?: boolean;
666
- }
667
-
668
- /**
669
- * Output formats supported by backends. Gated behind the engine surface so
670
- * tsify omits it from the core bundle, which has no rendering surface.
671
- */
672
- export type OutputFormat = "pdf" | "svg" | "png";
673
-
674
- /**
675
- * Rendered artifact (PDF, SVG, etc.).
676
- */
677
- export interface Artifact {
678
- format: OutputFormat;
679
- /**
680
- * `serde_bytes` so the boundary emits a real `Uint8Array`, not `number[]`.
681
- */
682
- bytes: Uint8Array;
683
- mimeType: string;
684
- }
685
-
686
- /**
687
- * Result of a render operation.
688
- */
689
- export interface RenderResult {
690
- artifacts: Artifact[];
691
- warnings: Diagnostic[];
692
- outputFormat: OutputFormat;
693
- renderTimeMs: number;
694
- /**
695
- * Schema-field geometry, populated only when `RenderOptions.regions` asked
696
- * for it. Page indices are document-space even under a `pages` subset.
697
- */
698
- regions: FieldRegion[];
699
- }
700
-
701
- /**
702
- * Source location for errors and warnings
703
- */
704
- export interface Location {
705
- file: string;
706
- line: number;
707
- column: number;
708
- }
709
-
710
- /**
711
- * What a committed `LiveSession.update` changed. `dirtyPages` lists pages whose
712
- * content differs from the previous compile, including pages the edit added;
713
- * removed pages are implied by `pageCount`.
714
- */
715
- export interface ChangeSet {
716
- pageCount: number;
717
- dirtyPages: number[];
718
- }
719
-
720
- export type Severity = "error" | "warning";
721
-
722
-
723
- /**
724
- * Typed in-memory Quillmark document.
725
- */
726
- export class Document {
727
- free(): void;
728
- [Symbol.dispose](): void;
729
- /**
730
- * **Apply** a committed content edit `bundle` at `addr`, the editor splice:
731
- * text delta first, then island ops, then line ops, then mark ops (mark
732
- * ranges in final-text coordinates), all-or-nothing. An absent `addr.field`
733
- * targets the body, an absent `addr.card` the main card. The island channel
734
- * moves an island alone, so anchors elsewhere in the field survive an edit
735
- * `overwrite` would clear.
736
- *
737
- * Throws on an out-of-range card, a field that is not richtext, a malformed
738
- * bundle, or an op that applies out of bounds; the value is unchanged on a
739
- * failed apply.
740
- *
741
- * Each text-moving channel rebases the marks already in the field, by the
742
- * rule on `ChangeBundle`; `mapMarks` answers where they land, so a caller
743
- * building `markOps` need not predict it.
744
- */
745
- applyChange(addr: Addr | string, bundle: ChangeBundle): void;
746
- /**
747
- * Authoring-ergonomics header introducing a blueprint to an LLM/MCP consumer
748
- * for the given `quillName`, re-exposed from core.
749
- */
750
- static blueprintInstruction(quill_name: string): string;
751
- /**
752
- * The **body** markdown projection: an on-demand, lossy export (content-only
753
- * marks do not survive markdown). A body's type is a format fact, not a
754
- * schema fact, so this read stays quill-free, and a body is never absent.
755
- *
756
- * `addr` is an optional card address (absent = main). A present `field`
757
- * throws: read a field's markdown through `quill.reader(doc).get(field)`,
758
- * which interprets by declared type. An out-of-range `addr.card` throws.
759
- */
760
- bodyMarkdown(addr?: CardAddr): string;
761
- /**
762
- * A single composable card by index, so reading one need not materialize
763
- * every card via [`cards`](Self::cards). An out-of-range `index` throws
764
- * `edit::index_out_of_range`.
765
- */
766
- card(index: number): Card;
767
- /**
768
- * The composable card's own path, `cards.<kind>[index]`: the root
769
- * [`pathFor`](Self::path_for) extends, for anchoring the card rather than
770
- * one of its fields. Total on the index axis; out of range renders
771
- * `cards[index]`.
772
- */
773
- cardPath(index: number): string;
774
- clone(): Document;
775
- /**
776
- * Storage version this build writes via [`toJson`](Document::to_json). The
777
- * tag advances only when the wire format changes, not on every release.
778
- */
779
- static currentStorageVersion(): string;
780
- /**
781
- * Structural equality, excluding parse-time `warnings`.
782
- */
783
- equals(other: Document): boolean;
784
- /**
785
- * Render a Diagnostic as the canonical pretty-printed text, so it looks
786
- * identical whichever consumer surfaces it.
787
- */
788
- static formatDiagnostic(diag: Diagnostic): string;
789
- /**
790
- * Authoring-format rules for the card-yaml markdown surface, re-exposed from
791
- * core. Constant across calls; read once and cache.
792
- */
793
- static formatRules(): string;
794
- /**
795
- * Reconstruct a `Document` from a versioned storage DTO string produced by
796
- * [`toJson`](Document::to_json). The result carries no parse-time warnings.
797
- * Throws if `json` is not a valid storage DTO (malformed JSON, unknown
798
- * `schema`, missing fields, or unparseable quill reference).
799
- */
800
- static fromJson(json: string): Document;
801
- /**
802
- * Parse markdown into a typed Document. Throws on parse errors.
803
- */
804
- static fromMarkdown(markdown: string): Document;
805
- /**
806
- * The whole `$ext` map at `addr` (a card address, absent `card` = main), or
807
- * `undefined` when the card carries none: the `$ext` read that avoids
808
- * serializing the whole card. Throws on a present `field` or an
809
- * out-of-range card.
810
- */
811
- getExt(addr?: CardAddr): Record<string, unknown> | undefined;
812
- /**
813
- * The value stored under `$ext[ns]` at `addr` (a card address, absent `card`
814
- * = main), or `undefined`. Throws on a present `field` or an out-of-range
815
- * card.
816
- */
817
- getExtNamespace(addr: CardAddr, ns: string): unknown;
818
- /**
819
- * Read the **verbatim stored value** at `addr`: a field's raw payload value,
820
- * or the body content when `addr.field` is absent. A bare string is `Addr`
821
- * shorthand for `{ field }`. Needs no schema: the read echo of the verbatim
822
- * `store*` write, distinct from the interpreted
823
- * [`reader.get`](Self::reader_get). Reads are total over the field axis — an
824
- * absent field is `undefined` — and only an out-of-range `addr.card` throws
825
- * `edit::index_out_of_range`.
826
- *
827
- * A content field at rest has one stored form per codec: a `richtext` field
828
- * holds the canonical content object, a `plaintext` field its literal
829
- * string. A document from the bound door (`quill.parse` / `quill.conform`)
830
- * is at rest; one from the transport door may rest as authored until it is
831
- * conformed, and this read reports what is there. For the `Content` either
832
- * way use `reader.getContent`.
833
- *
834
- * The body arm is typed `Content` and answers in the seam form, spelling
835
- * every `ContentContainer.instance`. A field arm echoes the stored bytes,
836
- * which omit a zero: verbatim is the contract, and is why it is `unknown`.
837
- */
838
- getStored(addr: Addr | string): unknown;
839
- /**
840
- * Insert a card: `at` absent appends, a number inserts at that index (in
841
- * `0..=cards.length`). Accepts any `CardInput`, including a card read back
842
- * out of a document. Throws if `card.kind` is not a valid kind name, or if
843
- * `at` is out of range.
844
- */
845
- insertCard(card: CardInput, at?: number): void;
846
- /**
847
- * Whether the field at `addr` is marked `!must_fill`. A bare string is `Addr`
848
- * shorthand for `{ field }`. `false` for an absent field and for a body
849
- * address; only an out-of-range `addr.card` throws.
850
- */
851
- isFill(addr: Addr | string): boolean;
852
- /**
853
- * Replace this document's contents **in place** from a versioned storage DTO
854
- * string: the mutating twin of [`fromJson`](Document::from_json). Parse-time
855
- * `warnings` are cleared. Throws on an invalid DTO, leaving the document
856
- * unchanged.
857
- *
858
- * The cross-WASM-memory `Document` bridge: mutate a document on a
859
- * backend-memory clone, then write the state back into the caller's
860
- * canonical document, without the caller re-binding its variable.
861
- */
862
- loadJson(json: string): void;
863
- /**
864
- * Build a fresh `Card` from a kind and a flat field map: the ergonomic
865
- * constructor for `insertCard`, which also takes any `Card` object
866
- * directly. Each `fields` entry becomes a card field in insertion order;
867
- * `body` defaults to `""`.
868
- *
869
- * Checks only what a detached card can decide alone: field-name grammar and
870
- * value depth. Kind validity is positional, so `insertCard` is its gate and
871
- * any kind string is accepted here.
872
- */
873
- static makeCard(kind: string, fields?: Record<string, unknown>, body?: string): Card;
874
- /**
875
- * Move the card at `from` to position `to`. `from == to` is a no-op.
876
- */
877
- moveCard(from: number, to: number): void;
878
- /**
879
- * A blank document: a main card carrying only `$quill`, an empty body, and
880
- * no composable cards. Absent fields resolve at render time (`default`, else
881
- * the field's blank), so nothing the caller did not set reaches the output.
882
- * For an example-filled starter use `Quill.seedDocument()`. Throws on an
883
- * invalid quill reference.
884
- */
885
- constructor(quill_ref: string);
886
- /**
887
- * **Overwrite** the content value at `addr` with exactly `rt`: value
888
- * semantics, so the identity anchors of any previous value are gone. By
889
- * anchor fate `overwrite` destroys, [`revise`](Document::revise) rebases,
890
- * and [`applyChange`](Document::apply_change) preserves. An absent
891
- * `addr.field` targets the body, an absent `addr.card` the main card.
892
- *
893
- * Throws on an out-of-range card, a malformed field name, or an `rt` that is
894
- * not a canonical content object.
895
- */
896
- overwrite(addr: Addr | string, rt: Content): void;
897
- /**
898
- * `addr`'s canonical `DocPath` string, the anchor `Diagnostic.path` carries:
899
- * `pathFor()` is `main.body`, `pathFor("intro")` `main.intro`,
900
- * `pathFor({card: 2})` `cards.<kind>[2].body`.
901
- *
902
- * The kind is the card's stored `$kind` verbatim, not `validate`'s
903
- * declared-kind filter, since a `Document` holds a `$quill` reference and no
904
- * schema. That is the one edge where this path and a `validate` diagnostic
905
- * path differ for the same card.
906
- *
907
- * **Total on the index axis**, unlike the `Addr` reads, which throw there:
908
- * an out-of-range `{card: 7, field: "from"}` renders `cards[7].from`, which
909
- * parses back and resolves to nothing rather than mis-targeting. Only a
910
- * malformed address throws.
911
- */
912
- pathFor(addr: Addr | string): string;
913
- /**
914
- * The canonical `$quill` reference grammar as author-facing text: the same
915
- * text the `parse::invalid_quill_reference` hint carries. Drive validation
916
- * messages from this instead of re-stating the rule.
917
- */
918
- static quillRefHint(): string;
919
- removeCard(index: number): Card | undefined;
920
- /**
921
- * Remove the `$ext` map on the card `addr` targets entirely, returning the
922
- * previous map or `undefined`. Discards every namespace at once; prefer
923
- * `removeExtNamespace`. Throws on a present `field` or an out-of-range card.
924
- */
925
- removeExt(addr?: CardAddr): Record<string, unknown> | undefined;
926
- /**
927
- * Remove `$ext[ns]` on the card `addr` targets, returning its value or
928
- * `undefined`; drops `$ext` once empty. `addr` is a card address (absent =
929
- * main). Preserves sibling namespaces. Throws on a present `field` or an
930
- * out-of-range card.
931
- */
932
- removeExtNamespace(addr: CardAddr, ns: string): any;
933
- /**
934
- * Remove a field at `addr`, returning the removed value or `undefined`. A
935
- * bare string is `Addr` shorthand for `{ field }`. A body address throws, as
936
- * does an out-of-range card or a malformed name.
937
- */
938
- removeField(addr: Addr | string): any;
939
- /**
940
- * Remove `cardKind` from the main card's `$seed` map, returning its overlay
941
- * or `undefined`; drops `$seed` entirely once empty. Sibling kinds survive.
942
- */
943
- removeSeedOverlay(card_kind: string): any;
944
- /**
945
- * **Revise** the richtext value at `addr` from a markdown string: the
946
- * default write path. Imports the markdown, diffs it against the current
947
- * value, rebases surviving identity anchors, and returns the text `Delta` an
948
- * editor bridge maps its own positions through (`mapPos`). An absent
949
- * `addr.field` targets the body, an absent `addr.card` the main card; an
950
- * absent field cold-imports from empty.
951
- *
952
- * Throws on an out-of-range card, a malformed field name, a present
953
- * non-content field value, or an over-nested markdown input.
954
- */
955
- revise(addr: Addr | string, markdown: string): Delta;
956
- /**
957
- * The main card's `$seed[kind]` overlay object, or `undefined`. Feeds
958
- * `quill.seedCard(kind, overlay)` without serializing the whole main card,
959
- * and keeps `seedCard` pure: the quill never reads the document.
960
- */
961
- seedOverlay(kind: string): Record<string, unknown> | undefined;
962
- /**
963
- * Replace the kind of the card at `index`. Payload and body are untouched;
964
- * schema-aware migration is the caller's responsibility.
965
- * Throws if `index` is out of range or `newKind` is invalid.
966
- */
967
- setCardKind(index: number, new_kind: string): void;
968
- /**
969
- * Replace the QUILL reference string. Throws if `ref_str` is invalid.
970
- */
971
- setQuillRef(ref_str: string): void;
972
- /**
973
- * Read the storage version tag from a raw storage DTO string without a full
974
- * parse, or `undefined`. Unknown future versions come back as-is, which
975
- * distinguishes "build too old" from "payload corrupt" when `fromJson`
976
- * throws. This is the storage version, not a field schema, though the JSON
977
- * key is spelled `"schema"`: that is the DTO's serde tag.
978
- */
979
- static storageVersionOf(json: string): string | undefined;
980
- /**
981
- * Replace the opaque `$ext` map on the card `addr` targets (absent `card` =
982
- * main). `value` must be a plain object. `$ext` carries out-of-band consumer
983
- * state and never reaches the rendered output. Throws on a present `field`
984
- * or an out-of-range card.
985
- */
986
- storeExt(addr: CardAddr, value: any): void;
987
- /**
988
- * Merge `value` into `$ext[ns]` on the card `addr` targets, preserving
989
- * sibling namespaces: the recommended `$ext` write. Throws on a present
990
- * `field` or an out-of-range card.
991
- */
992
- storeExtNamespace(addr: CardAddr, ns: string, value: any): void;
993
- /**
994
- * Store a field verbatim at `addr`, deferring coercion to render; the typed
995
- * write is [`commitField`](Document::commit_field). A bare string is `Addr`
996
- * shorthand for `{ field }`; `{ card: 2, field: "qty" }` targets a
997
- * composable card. Clears any `!must_fill` marker. A body address throws:
998
- * write a body with `revise` / `overwrite`. Throws on an out-of-range card
999
- * or a malformed name.
1000
- */
1001
- storeField(addr: Addr | string, value: any): void;
1002
- /**
1003
- * Store several fields verbatim and atomically on the card `addr` targets.
1004
- * `addr` is a **card address** (`{ card }`, absent = main) and comes first
1005
- * because `card` is itself a legal field name; a present `field` throws.
1006
- * Nothing is applied on error, and the thrown error's `diagnostics` carry
1007
- * one entry per offending field. Throws on an out-of-range card.
1008
- */
1009
- storeFields(addr: CardAddr, fields: Record<string, unknown>): void;
1010
- /**
1011
- * Store a field verbatim at `addr` and mark it `!must_fill`. A body address
1012
- * throws; same validation as [`storeField`](Document::store_field).
1013
- */
1014
- storeFill(addr: Addr | string, value: any): void;
1015
- /**
1016
- * Merge a card-kind's seed `overlay` into the **main** card's `$seed` map
1017
- * under `cardKind`, preserving sibling kinds; `$seed` is main-only, so this
1018
- * takes no address. Sets the starting values new cards of that kind spawn
1019
- * with. Throws if `overlay` cannot be serialized or nests too deep.
1020
- */
1021
- storeSeedOverlay(card_kind: string, overlay: any): void;
1022
- /**
1023
- * Serialize this document to a versioned storage DTO string. Prefer it over
1024
- * `toMarkdown` for persistence: the wire format is frozen per `schema`
1025
- * version and the output is byte-deterministic within one, so equal
1026
- * documents hash equal. Parse-time `warnings` are excluded.
1027
- */
1028
- toJson(): string;
1029
- /**
1030
- * Emit canonical Quillmark Markdown. Round-trip safe: re-parsing the
1031
- * result produces a `Document` equal to `self` by value and by type.
1032
- */
1033
- toMarkdown(): string;
1034
- /**
1035
- * Like [`fromJson`](Document::from_json) but returns `undefined` instead of
1036
- * throwing when `json` is not a valid storage DTO, to discriminate format
1037
- * without exceptions as control flow.
1038
- */
1039
- static tryFromJson(json: string): Document | undefined;
1040
- /**
1041
- * Number of composable cards, excluding the main card.
1042
- */
1043
- readonly cardCount: number;
1044
- readonly cards: Card[];
1045
- /**
1046
- * The document's main (entry) card. Allocates and serializes on each call.
1047
- */
1048
- readonly main: Card;
1049
- readonly quillRef: string;
1050
- /**
1051
- * The non-fatal diagnostics of the load that produced this document: parse
1052
- * warnings, plus `conform::*` warnings when it came through `quill.parse`.
1053
- * Session state, not document value: `equals` and the storage DTO exclude
1054
- * it, and `fromJson` / `loadJson` clear it.
1055
- */
1056
- readonly warnings: Diagnostic[];
1057
- }
1058
-
1059
- /**
1060
- * Live render session: every read serves the current compile. `apply(doc)`
1061
- * recompiles a whole document in place, transactionally — on throw the reads
1062
- * keep serving the last-good compile. Geometry is per-compile, so re-read it
1063
- * after each committed `apply`.
1064
- *
1065
- * A zero-page document yields a valid session (`pageCount === 0`) whose
1066
- * `paint(ctx, 0)` and `pageSize(0)` throw; branch on `pageCount === 0` rather
1067
- * than catching.
1068
- */
1069
- export class LiveSession {
1070
- private constructor();
1071
- free(): void;
1072
- [Symbol.dispose](): void;
1073
- /**
1074
- * The schema field whose content is under a point on `page`: the `DocPath`
1075
- * address to focus in the editor, or `undefined` off any field's ink.
1076
- * `x`/`y` are PDF points with a **bottom-left** origin, the same space as
1077
- * `FieldRegion.rect`, so from a canvas click use
1078
- * `x = clickPx.x / renderScale`, `y = pageHeightPt - clickPx.y / renderScale`.
1079
- * Unlike `regions()`, *every* placement answers, not just the first.
1080
- *
1081
- * `tolPt` is how far off the ink a click still counts, in the same points,
1082
- * and defaults to `0` — exact. Convert the pointer slack a surface wants
1083
- * from CSS pixels at the scale it drew the page (`slackPx / renderScale`),
1084
- * so it stays the same size under the cursor as the page zooms. The
1085
- * nearest placement answers, so raising it only fills a miss.
1086
- */
1087
- fieldAt(page: number, x: number, y: number, tol_pt?: number | null): string | undefined;
1088
- /**
1089
- * The whole-field highlight boxes for `field`: one union rect per page over
1090
- * the field's `span`-bearing content segments, the union `regions()` leaves
1091
- * derived. **Content only**: a field placed solely as a scalar reference or
1092
- * a bound widget carries no `span` and returns `[]`, its box being a single
1093
- * `regions()` rect. Reflects the current compile.
1094
- */
1095
- fieldBoxes(field: string): FieldRegion[];
1096
- /**
1097
- * A content position → **caret rect**, the reverse of `positionAt`: the box
1098
- * to draw a caret at, in the same bottom-left PDF-point space as
1099
- * `FieldRegion.rect`, its `span` collapsed to `[pos, pos]`. `undefined` when
1100
- * the field places no tracked content or the offset maps to no drawn glyph.
1101
- */
1102
- locate(field: string, pos: number): FieldRegion | undefined;
1103
- /**
1104
- * Page dimensions in points (1 pt = 1/72 inch).
1105
- * Throws if the backend has no canvas painter or `page` is out of range.
1106
- */
1107
- pageSize(page: number): PageSize;
1108
- /**
1109
- * Paint `page` into a `CanvasRenderingContext2D` or
1110
- * `OffscreenCanvasRenderingContext2D`. The painter owns
1111
- * `canvas.width`/`height` (no `clearRect` needed); consumers own
1112
- * `canvas.style.*`. If `layoutScale * densityScale` exceeds 16384 px per
1113
- * side, `densityScale` is clamped and `PaintResult` reports it.
1114
- *
1115
- * `put_image_data` writes the whole backing store, bypassing the 2D
1116
- * context's transform, `globalAlpha`, and clip, so each visible page needs
1117
- * its own `<canvas>`: no compositing, sub-rect, or transform reaches through
1118
- * this call.
1119
- *
1120
- * Throws if the backend has no canvas painter, `page` is out of range, `ctx`
1121
- * is the wrong type, or either scale is non-finite or `<= 0`.
1122
- */
1123
- paint(ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, page: number, opts: PaintOptions | undefined): PaintResult;
1124
- /**
1125
- * A point → **content position**: the field *and* a USV offset into its
1126
- * `Content`, for placing a caret or mapping a selection into the content
1127
- * model, or `undefined` off all content ink. `x`/`y`/`tolPt` are PDF
1128
- * points, bottom-left origin, as in `fieldAt`. The offset is cluster-exact
1129
- * and degrades to the containing segment's start on origin-less ink.
1130
- *
1131
- * `tolPt` earns the most here: the leading between two lines lies inside a
1132
- * paragraph and on no glyph, and under `tolPt` such a point takes the
1133
- * nearer line.
1134
- */
1135
- positionAt(page: number, x: number, y: number, tol_pt?: number | null): ContentHit | undefined;
1136
- /**
1137
- * Schema-field geometry for this compiled session: each content field's
1138
- * **first placement** (one region per page it touches) plus widget and
1139
- * scalar-reference-site regions, keyed on the canonical `DocPath` address. A
1140
- * field may appear more than once, so group by `field` (see `FieldRegion`).
1141
- * A session-level query: no render, no byte artifact. The click direction is
1142
- * `fieldAt`. Empty for backends that place no schema fields.
1143
- */
1144
- regions(): FieldRegion[];
1145
- render(opts?: RenderOptions | null): RenderResult;
1146
- /**
1147
- * Recompile the session against `doc`: the edit verb of a live preview. The
1148
- * document compiles through the same pipeline as `open`, then swaps in
1149
- * transactionally — on throw every read keeps serving the last-good compile
1150
- * and the session recovers on the next successful `update`. On success,
1151
- * repaint `dirtyPages ∩ visible`.
1152
- *
1153
- * Distinct from [`applyChange`](Document::apply_change), which splices ops
1154
- * into a document; this recompiles a document the caller already mutated.
1155
- */
1156
- update(doc: Document): ChangeSet;
1157
- /**
1158
- * The backend that produced this session (e.g. `"typst"`).
1159
- */
1160
- readonly backendId: string;
1161
- readonly pageCount: number;
1162
- /**
1163
- * `true` iff `paint` and `pageSize` will succeed for this session.
1164
- */
1165
- readonly supportsCanvas: boolean;
1166
- /**
1167
- * Non-fatal diagnostics of the session's **current compile**, refreshed by
1168
- * each committed `apply`; a failed apply keeps the last-good compile's.
1169
- * Also appended to `RenderResult.warnings` on each `render()`.
1170
- */
1171
- readonly warnings: Diagnostic[];
1172
- }
1173
-
1174
- export class Quill {
1175
- private constructor();
1176
- free(): void;
1177
- [Symbol.dispose](): void;
1178
- /**
1179
- * Land `doc`'s declared content fields at their canonical rest **in
1180
- * place**, returning the `conform::*` diagnostics for values that would not
1181
- * commit. The read-repair verb for a document that arrived through the
1182
- * transport door (`fromMarkdown`, `fromJson`, a stored row).
1183
- *
1184
- * Idempotent: an equal value is not rewritten, so YAML comments and stored
1185
- * bytes survive. A `!must_fill` marker anywhere in a field's value skips
1186
- * that field, and a value the strict write refuses stays as authored with a
1187
- * diagnostic. Throws when `doc` declares a different `$quill`, before any
1188
- * mutation.
1189
- */
1190
- conform(doc: Document): Diagnostic[];
1191
- /**
1192
- * Build a quill from a file tree. Pure: the declared backend is resolved
1193
- * later, at render time. Accepts a `Map<string, Uint8Array>` or a plain
1194
- * object.
1195
- */
1196
- static fromTree(tree: Map<string, Uint8Array>): Quill;
1197
- /**
1198
- * Parse `markdown` and conform it against this quill: the primary ingestion
1199
- * path, and the bound twin of the schema-free `Document.fromMarkdown`. The
1200
- * returned document rests at its canonical form (a `richtext` field as a
1201
- * content object, a `plaintext` field as its literal string), so `getStored`
1202
- * answers by the field's declared codec, not by how the document was built.
1203
- *
1204
- * Parse warnings and the `conform::*` diagnostics both land on
1205
- * `doc.warnings`. Throws on a parse failure, or when `markdown` declares a
1206
- * `$quill` this quill does not answer to. To open a document whose `$quill`
1207
- * is stale, use `Document.fromMarkdown`, `setQuillRef`, then `quill.conform`.
1208
- */
1209
- parse(markdown: string): Document;
1210
- /**
1211
- * The resolved-value view of `doc`: for every declared field, the value the
1212
- * render projection would use and the `FieldSource` rung it came from
1213
- * (`"authored" | "default" | "blank"`). The card body is a `body` sibling on
1214
- * its card, never a row in `fields`, and `null` when the kind enables no
1215
- * body. Value and provenance only; completeness stays `validate`'s.
1216
- */
1217
- resolve(doc: Document): Resolved;
1218
- /**
1219
- * Seed a starter composable `Card` of the given kind (carries `$kind`),
1220
- * layering an optional per-kind seed `overlay` over the schema-example base
1221
- * (`overlay › example › absent`). `undefined` when `cardKind` is not
1222
- * declared in this quill's schema.
1223
- *
1224
- * Pass `document.seedOverlay(cardKind)` as `overlay` so a card added to a
1225
- * template-derived document inherits its curated starting values; omit it
1226
- * for the bare schema seed.
1227
- */
1228
- seedCard(card_kind: string, overlay: Record<string, unknown> | undefined): Card | undefined;
1229
- /**
1230
- * Seed a starter `Document` from the schema: the main card plus one instance
1231
- * of each composable card kind, each committing its fields' `example:`
1232
- * values and leaving every other field absent (interpolated at render as
1233
- * `default:`, else the field's blank). A field with both renders its example.
1234
- */
1235
- seedDocument(): Document;
1236
- /**
1237
- * Seed a starter main `Card` (carries `$quill`) from the schema: the
1238
- * `$kind: main` card of [`seedDocument`](Self::seed_document) alone.
1239
- */
1240
- seedMain(): Card;
1241
- /**
1242
- * Flatten this quill back into its canonical file tree, the inverse of
1243
- * [`fromTree`](Self::from_tree). Keys are `"/"`-joined relative paths.
1244
- *
1245
- * This is how a quill crosses a WASM linear-memory boundary as data: a
1246
- * `Quill` built in one build cannot be passed to an engine in another, so
1247
- * `@quillmark/wasm/runtime` re-feeds this tree to the backend build's
1248
- * `Quill.fromTree` on demand.
1249
- */
1250
- toTree(): Map<string, Uint8Array>;
1251
- /**
1252
- * Validate `doc` against this quill's schema, returning every diagnostic
1253
- * (empty when the document is valid). Forwards the canonical
1254
- * `validation::*` diagnostics the engine emits, including the non-fatal
1255
- * `validation::must_fill` warning per `!must_fill` marker left behind.
1256
- */
1257
- validate(doc: Document): Diagnostic[];
1258
- /**
1259
- * The *declared* backend identifier (e.g. `"typst"`): intent, not a
1260
- * resolved capability. Capability is read from the engine.
1261
- */
1262
- readonly backendId: string;
1263
- readonly blueprint: string;
1264
- /**
1265
- * Identity snapshot of the `quill:` section of `Quill.yaml` plus any extra
1266
- * `quill:` keys. Pure config: output formats are a resolved-backend
1267
- * capability read from `Quillmark.supportedFormats`, not part of this.
1268
- */
1269
- readonly metadata: QuillMetadata;
1270
- /**
1271
- * Document schema for the quill: the user-fillable fields plus their `ui`
1272
- * hints. Key order in `fields`/`properties` is declaration order, the
1273
- * ordering contract.
1274
- */
1275
- readonly schema: QuillSchema;
1276
- }
1277
-
1278
- /**
1279
- * Render engine: a backend registry and render dispatcher. Render build only:
1280
- * the core build constructs and validates quills without it.
1281
- */
1282
- export class Quillmark {
1283
- free(): void;
1284
- [Symbol.dispose](): void;
1285
- constructor();
1286
- /**
1287
- * Open a live render session for `doc` against `quill`'s backend.
1288
- */
1289
- open(quill: Quill, doc: Document): LiveSession;
1290
- /**
1291
- * Render `doc` against `quill` in one shot. Convenience over `open` +
1292
- * `LiveSession.render`: an unset `output_format` falls back to the
1293
- * backend's first supported format.
1294
- */
1295
- render(quill: Quill, doc: Document, opts?: RenderOptions | null): RenderResult;
1296
- /**
1297
- * The output formats `quill`'s backend can emit; resolves the backend but
1298
- * compiles nothing. Throws `engine::backend_not_found` when no registered
1299
- * backend matches the quill's declared one.
1300
- */
1301
- supportedFormats(quill: Quill): OutputFormat[];
1302
- /**
1303
- * Whether `quill`'s backend can paint sessions to a canvas; `false` when the
1304
- * backend is unsupported. A cheap probe before mounting a preview UI. The
1305
- * authoritative answer is the session's `supportsCanvas` getter.
1306
- */
1307
- supportsCanvas(quill: Quill): boolean;
1308
- }
1309
-
1310
- /**
1311
- * Export canonical `Content` to its markdown projection. Throws if `rt` is not
1312
- * canonical content.
1313
- */
1314
- export function exportMarkdown(rt: Content): string;
1315
-
1316
- /**
1317
- * Serialize structured [`DocPathSeg`] segments back to the canonical path
1318
- * string: the inverse of `parseDocPath`. Throws on a segment array the
1319
- * deserializer rejects, and on an empty one.
1320
- */
1321
- export function formatDocPath(segs: DocPathSeg[]): string;
1322
-
1323
- /**
1324
- * Import a markdown string to canonical `Content`: the pure, document-free
1325
- * codec. `overwrite(addr, importMarkdown(md))` spells the cold, anchor-losing
1326
- * write; prefer `revise` for edit semantics. Throws on an over-nested input.
1327
- */
1328
- export function importMarkdown(markdown: string): Content;
1329
-
1330
- /**
1331
- * Where `bundle`'s text-moving channels (`delta`, then `islandOps`, then
1332
- * `lineOps`) leave `content`'s marks: the final-text coordinates the bundle's
1333
- * `markOps` are written in, under the rebase rule stated on `ChangeBundle`.
1334
- * The document-free read an editor diffs against to decide which `markOps` to
1335
- * emit, rather than reproducing that rule in its own language.
1336
- *
1337
- * `bundle.markOps` are ignored. The answer is normalized, as the store's is:
1338
- * marks a text move drops (out of range, zero-width formatting) are absent,
1339
- * and same-kind runs a move left adjacent arrive already unioned, so a bundle
1340
- * carrying no `markOps` names the marks the field will hold.
1341
- * Throws on a non-content `content`, a malformed bundle, or an op that applies
1342
- * out of bounds: `applyChange`'s errors on the same ops.
1343
- */
1344
- export function mapMarks(content: Content, bundle: ChangeBundle): ContentMark[];
1345
-
1346
- /**
1347
- * Map a base content position (a USV index into `Content.text`, not a UTF-16
1348
- * offset) through a `delta` to its new position, holding a caret stable across
1349
- * a `revise`. `assoc` decides the side of a same-position insertion (`"after"`
1350
- * moves past it). Throws on a malformed `delta`.
1351
- *
1352
- * This maps a position the *caller* holds. For the marks already in a field,
1353
- * `mapMarks` applies the store's own assoc rule across every channel of a
1354
- * `ChangeBundle`.
1355
- */
1356
- export function mapPos(delta: Delta, pos: number, assoc: Assoc): number;
1357
-
1358
- /**
1359
- * Parse a canonical document-model `Diagnostic.path` (`cards.<kind>[<i>].<field>`,
1360
- * `main.body`, `recipients[0].name`) into structured [`DocPathSeg`] segments, so
1361
- * a consumer routes on segments instead of regexing the string. Throws on a
1362
- * malformed path.
1363
- */
1364
- export function parseDocPath(path: string): DocPathSeg[];
1365
-
1366
- /**
1367
- * Rebase `markdown` onto a `base` content: the document-free twin of `revise`,
1368
- * returning the new `content` and the text `delta` (offsets are USV indices into
1369
- * `Content.text`, surviving anchors rebased). Throws on an over-nested markdown
1370
- * input or a non-content `base`.
1371
- */
1372
- export function rebase(base: Content, markdown: string): { content: Content; delta: Delta };
1373
-
1374
- /**
1375
- * Runs at instantiation, so a Rust panic reaches the console as a stack trace
1376
- * rather than `unreachable`. Not the package's `init` — that name belongs to
1377
- * the hand-written runtime, which owns instantiation itself.
1378
- */
1379
- export function start(): void;
1380
-
1381
- export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
1382
-
1383
- export interface InitOutput {
1384
- readonly memory: WebAssembly.Memory;
1385
- readonly __wbg_document_free: (a: number, b: number) => void;
1386
- readonly __wbg_livesession_free: (a: number, b: number) => void;
1387
- readonly __wbg_quill_free: (a: number, b: number) => void;
1388
- readonly __wbg_quillmark_free: (a: number, b: number) => void;
1389
- readonly document__addCard: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => void;
1390
- readonly document__commitField: (a: number, b: number, c: number, d: number, e: number) => void;
1391
- readonly document__commitFields: (a: number, b: number, c: number, d: number, e: number) => void;
1392
- readonly document__readerGet: (a: number, b: number, c: number, d: number) => void;
1393
- readonly document__readerGetContent: (a: number, b: number, c: number, d: number) => void;
1394
- readonly document__readerGetContentAt: (a: number, b: number, c: number, d: number, e: number) => void;
1395
- readonly document__reviseField: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
1396
- readonly document_applyChange: (a: number, b: number, c: number, d: number) => void;
1397
- readonly document_blueprintInstruction: (a: number, b: number, c: number) => void;
1398
- readonly document_bodyMarkdown: (a: number, b: number, c: number) => void;
1399
- readonly document_card: (a: number, b: number, c: number) => void;
1400
- readonly document_cardCount: (a: number) => number;
1401
- readonly document_cardPath: (a: number, b: number, c: number) => void;
1402
- readonly document_cards: (a: number, b: number) => void;
1403
- readonly document_clone: (a: number) => number;
1404
- readonly document_currentStorageVersion: (a: number) => void;
1405
- readonly document_equals: (a: number, b: number) => number;
1406
- readonly document_formatDiagnostic: (a: number, b: number) => void;
1407
- readonly document_formatRules: (a: number) => void;
1408
- readonly document_fromJson: (a: number, b: number, c: number) => void;
1409
- readonly document_fromMarkdown: (a: number, b: number, c: number) => void;
1410
- readonly document_getExt: (a: number, b: number, c: number) => void;
1411
- readonly document_getExtNamespace: (a: number, b: number, c: number, d: number, e: number) => void;
1412
- readonly document_getStored: (a: number, b: number, c: number) => void;
1413
- readonly document_insertCard: (a: number, b: number, c: number, d: number) => void;
1414
- readonly document_isFill: (a: number, b: number, c: number) => void;
1415
- readonly document_loadJson: (a: number, b: number, c: number, d: number) => void;
1416
- readonly document_main: (a: number, b: number) => void;
1417
- readonly document_makeCard: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
1418
- readonly document_moveCard: (a: number, b: number, c: number, d: number) => void;
1419
- readonly document_new: (a: number, b: number, c: number) => void;
1420
- readonly document_overwrite: (a: number, b: number, c: number, d: number) => void;
1421
- readonly document_pathFor: (a: number, b: number, c: number) => void;
1422
- readonly document_quillRef: (a: number, b: number) => void;
1423
- readonly document_quillRefHint: (a: number) => void;
1424
- readonly document_removeCard: (a: number, b: number, c: number) => void;
1425
- readonly document_removeExt: (a: number, b: number, c: number) => void;
1426
- readonly document_removeExtNamespace: (a: number, b: number, c: number, d: number, e: number) => void;
1427
- readonly document_removeField: (a: number, b: number, c: number) => void;
1428
- readonly document_removeSeedOverlay: (a: number, b: number, c: number, d: number) => void;
1429
- readonly document_revise: (a: number, b: number, c: number, d: number, e: number) => void;
1430
- readonly document_seedOverlay: (a: number, b: number, c: number, d: number) => void;
1431
- readonly document_setCardKind: (a: number, b: number, c: number, d: number, e: number) => void;
1432
- readonly document_setQuillRef: (a: number, b: number, c: number, d: number) => void;
1433
- readonly document_storageVersionOf: (a: number, b: number, c: number) => void;
1434
- readonly document_storeExt: (a: number, b: number, c: number, d: number) => void;
1435
- readonly document_storeExtNamespace: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
1436
- readonly document_storeField: (a: number, b: number, c: number, d: number) => void;
1437
- readonly document_storeFields: (a: number, b: number, c: number, d: number) => void;
1438
- readonly document_storeFill: (a: number, b: number, c: number, d: number) => void;
1439
- readonly document_storeSeedOverlay: (a: number, b: number, c: number, d: number, e: number) => void;
1440
- readonly document_toJson: (a: number, b: number) => void;
1441
- readonly document_toMarkdown: (a: number, b: number) => void;
1442
- readonly document_tryFromJson: (a: number, b: number) => number;
1443
- readonly document_warnings: (a: number, b: number) => void;
1444
- readonly exportMarkdown: (a: number, b: number) => void;
1445
- readonly formatDocPath: (a: number, b: number) => void;
1446
- readonly importMarkdown: (a: number, b: number, c: number) => void;
1447
- readonly livesession_backendId: (a: number, b: number) => void;
1448
- readonly livesession_fieldAt: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
1449
- readonly livesession_fieldBoxes: (a: number, b: number, c: number, d: number) => void;
1450
- readonly livesession_locate: (a: number, b: number, c: number, d: number) => number;
1451
- readonly livesession_pageCount: (a: number) => number;
1452
- readonly livesession_pageSize: (a: number, b: number, c: number) => void;
1453
- readonly livesession_paint: (a: number, b: number, c: number, d: number, e: number) => void;
1454
- readonly livesession_positionAt: (a: number, b: number, c: number, d: number, e: number) => number;
1455
- readonly livesession_regions: (a: number, b: number) => void;
1456
- readonly livesession_render: (a: number, b: number, c: number) => void;
1457
- readonly livesession_supportsCanvas: (a: number) => number;
1458
- readonly livesession_update: (a: number, b: number, c: number) => void;
1459
- readonly livesession_warnings: (a: number, b: number) => void;
1460
- readonly mapMarks: (a: number, b: number, c: number) => void;
1461
- readonly mapPos: (a: number, b: number, c: number, d: number) => void;
1462
- readonly parseDocPath: (a: number, b: number, c: number) => void;
1463
- readonly quill_backendId: (a: number, b: number) => void;
1464
- readonly quill_blueprint: (a: number, b: number) => void;
1465
- readonly quill_conform: (a: number, b: number, c: number) => void;
1466
- readonly quill_fromTree: (a: number, b: number) => void;
1467
- readonly quill_metadata: (a: number, b: number) => void;
1468
- readonly quill_parse: (a: number, b: number, c: number, d: number) => void;
1469
- readonly quill_resolve: (a: number, b: number, c: number) => void;
1470
- readonly quill_schema: (a: number, b: number) => void;
1471
- readonly quill_seedCard: (a: number, b: number, c: number, d: number, e: number) => void;
1472
- readonly quill_seedDocument: (a: number) => number;
1473
- readonly quill_seedMain: (a: number, b: number) => void;
1474
- readonly quill_toTree: (a: number) => number;
1475
- readonly quill_validate: (a: number, b: number, c: number) => void;
1476
- readonly quillmark_new: () => number;
1477
- readonly quillmark_open: (a: number, b: number, c: number, d: number) => void;
1478
- readonly quillmark_render: (a: number, b: number, c: number, d: number, e: number) => void;
1479
- readonly quillmark_supportedFormats: (a: number, b: number, c: number) => void;
1480
- readonly quillmark_supportsCanvas: (a: number, b: number) => number;
1481
- readonly rebase: (a: number, b: number, c: number, d: number) => void;
1482
- readonly start: () => void;
1483
- readonly __wbindgen_export: (a: number, b: number) => number;
1484
- readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
1485
- readonly __wbindgen_export3: (a: number) => void;
1486
- readonly __wbindgen_export4: (a: number, b: number, c: number) => void;
1487
- readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
1488
- readonly __wbindgen_start: () => void;
1489
- }
1490
-
1491
- export type SyncInitInput = BufferSource | WebAssembly.Module;
1492
-
1493
- /**
1494
- * Instantiates the given `module`, which can either be bytes or
1495
- * a precompiled `WebAssembly.Module`.
1496
- *
1497
- * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
1498
- *
1499
- * @returns {InitOutput}
1500
- */
1501
- export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
1502
-
1503
- /**
1504
- * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
1505
- * for everything else, calls `WebAssembly.instantiate` directly.
1506
- *
1507
- * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
1508
- *
1509
- * @returns {Promise<InitOutput>}
1510
- */
1511
- export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;