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