@voithos-labs/aragonite 0.10.1

package/docs/guide/directives.md

@@ -0,0 +1,223 @@
+# Directives
+
+Markdown has no syntax for "a box with a name on it" (e.g. no callout, no admonition, no embed, nothing). The community settled on `:::name` fences instead, and aragonite speaks that dialect: a fence with a **name**, and the editor hands the whole thing to whichever plugin claimed the name.
+
+```
+:::note Heads up
+Some body markdown.
+:::
+```
+
+Claim the `note` name and you get a real block kind for it: your own component, keymap, commands, the works. A name nobody claimed still parses, renders as a plain labelled box, and saves back byte for byte (i.e. a document written with your plugin survives being opened without it).
+
+---
+
+<details>
+<summary>So, what are directives?</summary>
+<p>A named box in Markdown, written as a <code>:::name</code> fence, that a plugin can claim by name and turn into its own block</p>
+</details>
+
+---
+
+This page assumes you have read the [plugin guide](plugin-guide.md). Directives replace the parsing half of a plugin (you don't write an opener; defined in the next section), not the registration underneath it (you still have to declare a kind).
+
+## One opener for everyone
+
+There is exactly one opener (opener /ˈōp(ə)nər/: the part of the aragonite parser that recognizes the syntax a block starts with. Each block kind usually brings its own; a paragraph is what you get when none of them match.) for `:::`, `::` and `:`, and it dispatches on the name. Your plugin never registers an opener of its own.
+
+The reason is the way this feature usually gets built wrong: if every plugin registered its own `:::` opener, the first one to register would greedily claim every `:::whatever` fence, and no second plugin could ever own its own name. One shared opener, a registry lookup by name, done.
+
+```
+:::name info…
+      │  the one opener
+      ▼
+  registry lookup by (tier, name)
+      ├─ registered   → your kind
+      └─ unregistered → the generic box
+```
+
+## The three tiers
+
+| Tier          | Syntax                 | Colons    | Where  | Body                                    |
+| ------------- | ---------------------- | --------- | ------ | --------------------------------------- |
+| **Container** | `:::name info` … `:::` | 3 or more | block  | nested markdown, real child blocks      |
+| **Leaf**      | `::name info`          | 2         | block  | one line, no children                   |
+| **Text**      | `:name[label]{attrs}`  | 1         | inline | an atomic widget, source shown on focus |
+
+The colon count is the tier (one colon is text, two is a leaf, three or more is a container). A name is a letter followed by letters, digits or hyphens (no underscores). And the text tier is deliberately shy: `:name` only counts when a `[` or `{` follows immediately, so `:smile:`, `10:30` and `http://` all stay plain text, as they should.
+
+**Nesting containers.** The closing syntax for a container follows a simple rule: it closes on the first line that (only) contains a sequence of colons with length >= the length of the opening colons. This is, coincidentally, the same rule used for the code fences (in that case it's backticks instead of colons).
+
+As a consequence, to nest containers, the outer fence has to be longer:
+
+```
+::::note          outer opens with 4 colons
+:::warning         inner :::… is body, not a closer
+inner body
+:::                inner closes (3 ≥ 3)
+::::              outer closes (4 ≥ 4)
+```
+
+---
+
+<details>
+<summary>Pasting BS into the Container</summary>
+Don't worry, we've got A-Hole protection. Pasting a ::: into a container won't ruin things - the editor lengthens the note's fence so the paste doesn't close it; delete the line again and the fence shrinks back.
+
+So,
+
+```
+:::note
+Some text.
+:::
+```
+
+turns into:
+
+```
+::::note
+Some text.
+:::
+::::
+```
+
+so to speak. One thing: the widened fence is what gets saved, so after a reload the container simply is a `::::` container and stays one; the shrink-back only happens while it's live in the editor.
+</details>
+
+---
+
+## Claiming a name
+
+```ts
+registerDirective(tier, name, definition);
+```
+
+A tier has to be passed in for registering, so a container and a leaf may share a name. A few things to know:
+
+- **A duplicate register throws.** Same as `customElements`, same as every other registry in aragonite: no silent override. The second `registerDirective` throws on install, which is a rude way for your user to find out. If you want first-wins, opt into it yourself: check `isDirectiveRegistered(tier, name)` and skip your registration when the name is taken.
+- **Binding a name to a kind.** You declare a kind as usual (see plugin guide); registerDirective binds a name to it and, for containers, gives it a fromDirective that builds your node from the parsed fence. e.g.
+
+```ts
+registerDirective('container', 'note', {
+	kind: NOTE, // the kind you declared
+	fromDirective: (parsed) => {
+		// how to build one from a ':::note' fence
+		const node: CstNode = {
+			kind: NOTE,
+			leadingTrivia: parsed.leadingTrivia,
+			raw: parsed.raw,
+			innerPrefix: parsed.body?.prefix ?? '',
+			// the title rides as child 0 (a chrome leaf; see the plugin guide)
+			children: [chromeChild(NOTE_TITLE, parsed.fence.info.trim()), ...(parsed.body?.children ?? [])],
+			innerSuffix: parsed.body?.suffix ?? ''
+		};
+		setPluginMetadata(node, {
+			name: parsed.fence.name,
+			// the four fence fields createDirectiveRebuild needs, under these exact names
+			colonCount: parsed.fence.colonCount,
+			closerColonCount: parsed.closerColonCount,
+			closerNewline: parsed.closerNewline,
+			lineEnding: parsed.lineEnding
+		});
+		return node;
+	}
+});
+```
+
+- **Binding many names to one kind.** Name to kind is not a one to one relationship - it can be many to one. Say you want `:::note`, `:::warning` and `:::tip`, and they all behave the same (same component, same keymap, same collapse), differing only in colour and icon. Rather than declaring three kinds, declare one, call it callout, and register all three names against it:
+
+```ts
+registerDirective('container', 'note',    { kind: CALLOUT, fromDirective: build });
+registerDirective('container', 'warning', { kind: CALLOUT, fromDirective: build });
+registerDirective('container', 'tip',     { kind: CALLOUT, fromDirective: build });
+```
+
+The factory (broadly, a function that takes the parsed pieces of a fence (its name, info string, body, etc.) and builds the corresponding block's node) (aka fromDirective in this case) just keeps the name in the node's metadata so the component knows which one it is.
+
+### When is `fromDirective` required?
+
+`fromDirective` is required, optional or refused depending on the tier (and yes, it fails loud):
+
+| Tier      | `fromDirective` | Why                                                                                    |
+| --------- | --------------- | -------------------------------------------------------------------------------------- |
+| Container | required        | a container has to build its own node, or the generic rebuild has nothing to work with |
+| Leaf      | optional        | without one, the leaf just restamps its kind; with one, you build the node             |
+| Text      | refused         | inline nodes are kind-only; a factory would never be called                            |
+
+p.s. Please, for chrissake, don't hand-write `rebuildRaw` for a container, lest you enjoy watching a car crash. `createDirectiveRebuild` does all of it; the plugin guide's walkthrough shows it in use.
+
+## The info string and attributes
+
+Everything after the name on the opener line is the **info string**. For `:::note Heads up` that's `' Heads up'`, leading space included, so trim it before you show it.
+
+If you want the remark-style `[label]{#id .class key=value}` convention, `parseDirectiveAttributes(info)` reads it into `{ label, id, classes, properties }`. It is opt-in and pure: a directive whose "info" is just a title (`:::note My Title`) never calls it.
+
+```ts
+parseDirectiveAttributes('[Heads up]{#intro .warning level=3}');
+// { label: 'Heads up', id: 'intro', classes: ['warning'], properties: { level: '3' } }
+
+parseDirectiveAttributes(' Heads up');
+// { classes: [], properties: {} }
+```
+
+One limitation though: the helper goes one way, info to structure, not the inverse. A directive that edits its attributes rewrites its own info string (through its metadata and `rebuildRaw`, the same path a title edit takes). If a real plugin needs the inverse, it is an additive addition; raise an issue and present your case.
+
+## Switching it on
+
+Directives ship inert. `activateDirectives()` turns the grammar on (the generic boxes, the `:::` and `::` block openers, and the inline `:` recognizer).
+
+Remember, call it once at startup, before the editor first parses anything (a document parsed before the call will not re-parse, and a dev-mode warning will call you out). The call is also idempotent, so several plugins (and hot-reload re-runs) can each make it without stepping on each other.
+
+## What you get on `@voithos-labs/aragonite/plugin`
+
+Everything here is marked pre-freeze, meaning it may still change shape until 1.0.
+
+The ones you will actually use:
+
+| Entry                    | When you reach for it                                                                                                                                                      |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `activateDirectives`     | once, at startup, to turn directives on at all                                                                                                                             |
+| `registerDirective`      | to claim a name for your kind (this whole page)                                                                                                                            |
+| `isDirectiveRegistered`  | to check whether a name is already taken, if you want first-wins instead of a throw                                                                                        |
+| `createDirectiveRebuild` | to get a `rebuildRaw` for your container without writing one (the thing you were told not to hand-write); it assumes your child 0 is the editable title on the opener line |
+| `DIRECTIVE_BODY_WRAP`    | put it in your container kind's `bodyWrap`; it tells the parser how a `:::` body is wrapped in blank lines                                                                 |
+
+The ones you probably won't:
+
+| Entry                      | When you reach for it                                                                                         |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `parseDirectiveAttributes` | if your info strings use the `[label]{#id .class key=value}` convention and you want them read into an object |
+| `serializeDirective`       | writes a fence back out from its parts; `createDirectiveRebuild` already calls it for you                     |
+| `escalatedColonCount`      | how many colons a fence needs to hold a given body; only if you build `:::name` text by hand                  |
+
+Plus the types: `DirectiveTier`, `DirectiveDefinition`, `ParsedDirective`, `DirectiveFence` and `DirectiveAttributes`.
+
+The one type worth knowing by heart is `ParsedDirective`, because it is what your `fromDirective` gets handed:
+
+| Field                                             | What it is                                                                                                                                         |
+| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fence`                                           | the opener line, taken apart: `tier`, `colonCount`, `name`, `info`                                                                                 |
+| `body`                                            | everything between the fences, already parsed (a leaf has none); its `children` become your node's body blocks                                     |
+| `leadingTrivia`, `raw`                            | the blank lines before the block, and the block's exact source text; copy both onto your node untouched, or it will not save back to what was read |
+| `closerColonCount`, `closerNewline`, `lineEnding` | how the closing fence looked and which line ending the file used, so the fence can be written back exactly, CRLF included                          |
+
+For the `:::note Heads up` fence at the top of this page, your factory gets:
+
+```ts
+{
+	fence: { tier: 'container', colonCount: 3, name: 'note', info: ' Heads up' },
+	body: {
+		kind: 'document',
+		prefix: '',
+		children: [/* the "Some body markdown." paragraph, already parsed */],
+		suffix: ''
+	},
+	leadingTrivia: '',
+	raw: ':::note Heads up\nSome body markdown.\n:::\n',
+	closerColonCount: 3,
+	closerNewline: true,
+	lineEnding: '\n'
+}
+```
+
+One thing to know before you write your metadata type: `createDirectiveRebuild` needs it to carry `colonCount`, `closerColonCount`, `closerNewline` and `lineEnding`, under exactly those names. Those four are how it writes the fence back identical to the one it read. The compiler will tell you if one is missing; now you also know why.

package/docs/guide/plugin-api.md

@@ -0,0 +1,329 @@
+# Plugin API Reference
+
+Every export of `@voithos-labs/aragonite/plugin`, grouped by job, so you can find a name and what it does without reading the package's entry module. Nobody reads this page top to bottom; Ctrl+F your way to the name you're after. The recipes behind the names live in the [plugin guide](plugin-guide.md), and each group links to its section there.
+
+## API reference
+
+Values are the calls you make, and the types beside them describe what those calls take and hand back.
+
+Five words recur in every table, so here they are once:
+
+- A **kind** is aragonite's word for a block type. Paragraph is a kind, fenced code is a kind, your plugin's block is about to be one.
+- A block's **raw** is its exact source bytes, and saving a document is just concatenating them.
+- An **opener** is the piece of the parser that recognizes the line a block starts with.
+- A **leaf** is a block with no child blocks; a **container** holds other blocks.
+- To **mint** is to create a branded, registry-backed identity (a kind, a command id) in the one authorized place; a duplicate throws.
+
+A group tagged _(pre-freeze / unstable)_ may still change shape until the 1.0 freeze; an untagged group already holds its final shape. The tags copy the section notes in the entry module (`src/lib/plugin.ts`).
+
+Adding an export? Give it a row in its group, tagged the way its entry-module section is tagged. A test (`src/lib/test/plugins/plugin-guide-coverage.test.ts`) diffs this page against the entry module and fails naming any export without a row. It finds the catalog by the exact `## API reference` heading above, so if you rename the heading, rename it there too.
+
+The groups, in page order:
+
+| Group                                                   | What it covers                                                                               |
+| ------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| [The plugin unit](#the-plugin-unit)                     | Packaging your extension, installing it, and what each mounted editor hands it back          |
+| [Kind declaration](#kind-declaration)                   | Minting a new block type's identity                                                          |
+| [The block-kind descriptor](#the-block-kind-descriptor) | Telling the editor how your block type behaves, and the checklist every one must fill in     |
+| [The component registry](#the-component-registry)       | Binding a block type to the Svelte component that renders it                                 |
+| [The parser opener](#the-parser-opener)                 | Teaching the parser to recognize your block's syntax                                         |
+| [Enter completion](#enter-completion)                   | Letting one typed line become a construct whose lines must sit together                      |
+| [Registration probes](#registration-probes)             | Checking what's already registered, so a module that runs twice stays safe                   |
+| [Directive authoring](#directive-authoring)             | Owning a `:::name` block without writing your own parsing                                    |
+| [Container authoring](#container-authoring)             | Blocks that hold other blocks, plus their title line                                         |
+| [Editable-leaf authoring](#editable-leaf-authoring)     | A text-editing block with the editor's own caret, undo, and selection                        |
+| [Inline authoring](#inline-authoring)                   | Your own syntax inside a paragraph, rendered as a widget                                     |
+| [Commands and keybindings](#commands-and-keybindings)   | Keyboard shortcuts and commands, per block type or editor-wide                               |
+| [Paste transforms](#paste-transforms)                   | Rewriting pasted text before the editor parses it                                            |
+| [Decorations](#decorations)                             | View-only annotations over content your plugin does not own                                  |
+| [Events](#events)                                       | What the editor tells your plugin has happened, and the shapes it says it in                 |
+| [Rects](#rects)                                         | Where things are on screen: block boxes, ranges, the caret, scrolling to a block             |
+| [Caret geometry](#caret-geometry)                       | Answering where a press inside your block puts the caret                                     |
+| [Selection geometry](#selection-geometry)               | The shapes that describe what the user has selected                                          |
+| [Parse and serialize](#parse-and-serialize)             | Markdown in, tree out, and back again                                                        |
+| [Grammar scanners](#grammar-scanners)                   | The editor's own code-fence, HTML-tag, and blockquote rules, reusable so you never fork them |
+| [Node access and metadata](#node-access-and-metadata)   | Reading the document tree, and storing your own data on a block                              |
+| [Performance helpers](#performance-helpers)             | A small cache and a scan index for render and recognition work                               |
+
+### The plugin unit
+
+_(pre-freeze / unstable)_ The installable package, and the per-editor context it gets back. Wiring and the traps: [The plugin unit](plugin-guide.md#the-plugin-unit) and [One process, many editors](plugin-guide.md#one-process-many-editors).
+
+| Export               | Role                                                                                                                                                                                                                |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `definePlugin`       | Validate a `{ name, setup }` unit at definition time and return it, ready for the editor's `plugins` prop                                                                                                           |
+| `definePluginBlock`  | The single-block shortcut: one kind, one component, one register step, packaged as a unit                                                                                                                           |
+| `isPluginInstalled`  | Has a plugin of this name installed? For the rare setup that has to branch on it                                                                                                                                    |
+| `EditorPlugin`       | The unit's shape; the `plugins` prop and the main entry's `installPlugins` take these                                                                                                                               |
+| The `plugins` prop   | Installs once per process, and activates per editor: an editor runs the hooks, kinds, commands and paste transforms of exactly the plugins it lists (no prop at all activates every installed one)                  |
+| `EditorPluginEntry`  | One `plugins` prop entry: a bare unit, or `{ plugin, options }` to vary options per editor                                                                                                                          |
+| `PluginSetupContext` | What `setup(ctx)` receives; its `onEditor(cb)` registers a per-editor callback (call it from `setup`, synchronously)                                                                                                |
+| `OnEditorCallback`   | The callback itself: receives the `EditorContext` of each mounted editor that listed your plugin, may return a cleanup function the editor runs at unmount                                                          |
+| `EditorContext`      | One editor's view for your plugin: `editorId`, the live read-only `document`, subscribe-only `events`, this editor's `options`, its `decorations` and `rects` surfaces, and the live `presentationMode` and `theme` |
+| `PresentationMode`   | The union of the editor's view modes (source, reading, the previews, live); every mode read reports the effective one, meaning the mode actually in force. [Presentation modes](plugin-guide.md#presentation-modes) |
+
+### Kind declaration
+
+Every kind starts here. No other call accepts a bare string where a kind goes.
+
+| Export                            | Role                                                                                                    |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `declarePluginKind`               | Mint a block kind from a name and get the kind back; a collision with a built-in or a prior kind throws |
+| `declaredPluginKind`              | Recover an already-declared kind in another module, no cast; throws for a name nobody declared          |
+| `PluginBlockKind`, `AnyBlockKind` | The plugin-declared kind type, and the union of built-in and plugin kinds a node can carry              |
+
+### The block-kind descriptor
+
+The **descriptor** is a kind's written behavior: how it merges, whether it's editable, its container shape. Its required `closure` field is the kind's answer to each cross-cutting editor system (undo, search, selection, clipboard and friends), so a new kind can't ship silently broken under a subsystem nobody asked about. Cell by cell: [The closure block](plugin-guide.md#the-closure-block).
+
+| Export                                         | Role                                                                                                                                                                                                  |
+| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `registerBlockKind`                            | Register a kind's descriptor; the kind errors at first use without one                                                                                                                                |
+| `augmentBlockKind`                             | Merge extra fields into a kind your own plugin registered; built-in kinds and another plugin's kinds are refused with a throw                                                                         |
+| `BlockKindRegistration`, `BlockKindDescriptor` | What `registerBlockKind` accepts, and the flat read-side shape lookups hand back                                                                                                                      |
+| `BlockKindAugmentation`                        | The patch `augmentBlockKind` merges; a partial `container` group merges into the existing one                                                                                                         |
+| `ContainerDescriptorGroup`                     | The descriptor's container-only half: `rebuildRaw` (the hook that recomputes a container's raw from its children after an edit), the body wrap, the reserved title line, unwrap behavior              |
+| `MergeRole`, `UnwrapRole`                      | Closed sets naming how a kind merges on Backspace, and how a container releases a child at its edge                                                                                                   |
+| `ChildRawChange`                               | `rebuildRaw`'s optional second argument: which one child's bytes just moved, for a rebuilder that re-emits only that region. Ignoring it and re-deriving the whole raw is always correct, just slower |
+| `ClosureBlock`, `ClosureColumn`, `ClosureCell` | The closure matrix: nine columns, one cell each, and a cell is `implemented` (name the mechanism), `inherit-default`, or `not-supported` (name the degradation). A missing column fails the typecheck |
+| `simpleLeafClosure`, `SimpleLeafClosureCells`  | Closure preset for a plain text leaf: bakes the five cells every such leaf answers alike, requires the four your component determines (`focus`, `searchPaint`, `undo`, `simOracle`)                   |
+| `containerClosure`, `ContainerClosureCells`    | Closure preset for a container of real child blocks: bakes the four structural cells plus `roundTrip: implemented`, requires the round trip's `via` string and the four the container determines      |
+
+### The component registry
+
+| Export                                    | Role                                                                                                                             |
+| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `registerBlockComponent`                  | Bind a kind to the Svelte component that renders it; without one the kind renders as a visible raw-text fallback (you'll notice) |
+| `defineBlockComponent`                    | Wrap your component into the registry's entry shape; a container that forgot to publish its API fails the typecheck here         |
+| `BlockComponentEntry`                     | The registry entry: the component, plus an optional per-node extra-props hook                                                    |
+| `BlockComponent`, `BlockComponentExports` | The surface a block component publishes: a leaf's own members, or a container's single `containerApi` export                     |
+| `BlockComponentProps`                     | The props every block component receives: its node, its position, the read-only whole document, the editor's geometry surface    |
+
+### The parser opener
+
+Where your opener sits on the ladder, and the two placement rules: [Opener priority](plugin-guide.md#opener-priority).
+
+| Export                                   | Role                                                                                                                                                                                                                  |
+| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `registerBlockOpener`                    | Teach the parser to recognize your kind's Markdown syntax                                                                                                                                                             |
+| `BlockOpener`, `OpenContext`             | The opener contract, and the line cursor its `tryOpen` inspects: the lines, the position, the parse's scope and depth                                                                                                 |
+| `BlockOpenerResult`                      | A claim: the node built, plus `consumed`, the count of lines it took                                                                                                                                                  |
+| `OPENER_PRIORITIES`                      | The built-in priorities your opener picks its own number relative to; lower dispatches first _(pre-freeze / unstable)_                                                                                                |
+| `lineStartsOuterBlock`, `OuterBlockScan` | "Does this line start a block at the outer level?" The shared end-of-extent test for a container opener scanning its own lines, and its input flag saying whether a paragraph is open above _(pre-freeze / unstable)_ |
+
+### Enter completion
+
+_(pre-freeze / unstable)_ The recipe: [Typing a multi-line construct into existence](plugin-guide.md#typing-a-multi-line-construct-into-existence).
+
+| Export                   | Role                                                                                                                                    |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `registerBlockCompleter` | Let one typed line complete into a grammar whose lines must sit adjacent, which Enter alone can never type                              |
+| `BlockCompleter`         | The contract: `tryComplete(line)` claims with a result, or declines with null                                                           |
+| `CompletionResult`       | A claim: the lines to insert, endings omitted (the editor attaches the document's own), plus where the caret seats inside the insertion |
+
+### Registration probes
+
+Every registry on this surface is register-once (a duplicate throws, it never overrides). These are the matching is-it-there checks, for a module that may run twice (hot reload, a re-import) to ask before registering. Guard on these rather than on a module-level flag of your own: the flag outlives the test kit's platform reset, and the guide's registration section tells you how that afternoon goes. The directive and inline tiers keep their own probes, `isDirectiveRegistered` and `isInlineKindDeclared`, in their groups below.
+
+| Export                                                                                                         | Role                                               |
+| -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| `isBlockKindDeclared`                                                                                          | Is this kind name already declared?                |
+| `isBlockKindRegistered`, `isBlockComponentRegistered`, `isBlockOpenerRegistered`, `isBlockCompleterRegistered` | One guard per register-once call on the block side |
+| `isPasteTransformRegistered`                                                                                   | The same guard, keyed by a paste transform's name  |
+
+### Directive authoring
+
+_(pre-freeze / unstable)_ The `:::name` grammar itself is the [directives guide](directives.md)'s subject; the worked container is [the walkthrough](plugin-guide.md#walkthrough-a-conspiracy-container-end-to-end).
+
+| Export                                                   | Role                                                                                                                                                                          |
+| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `activateDirectives`                                     | Turn the `:::name` grammar on, once at startup, before the first parse; every other export here is inert until it runs                                                        |
+| `registerDirective`                                      | Map a `(tier, name)` pair to one of your kinds; a container mapping must bring its node factory (`fromDirective`), or registration throws                                     |
+| `isDirectiveRegistered`                                  | The is-it-there check for a directive name                                                                                                                                    |
+| `parseDirectiveAttributes`                               | Opt-in reader pulling a `[label]` and a `{#id .class key=val}` block out of a directive's info string; one-way, it reads and never writes back                                |
+| `serializeDirective`                                     | Re-emit a directive's exact bytes from its parts (colon count, name, verbatim info string, body, closer shape), growing the fences itself so no body line reads as the closer |
+| `escalatedColonCount`                                    | The fence length a body forces, for an emitter building `:::name` text by hand instead of through `serializeDirective`                                                        |
+| `createDirectiveRebuild`                                 | Build the raw-recompute hook (`rebuildRaw`) for a directive container whose child 0 is an editable title; owns the fence bytes, CRLF included                                 |
+| `DIRECTIVE_BODY_WRAP`                                    | The wrap every `:::` body parses with; declare it as your container kind's `bodyWrap` so a blank line against the fence settles where it belongs                              |
+| `DirectiveDefinition`, `ParsedDirective`                 | The registration's shape, and the parsed fence your factory receives: the fence parts, the parsed body, the exact consumed bytes                                              |
+| `DirectiveTier`, `DirectiveFence`, `DirectiveAttributes` | The three tiers (container, leaf, text), one parsed opener line, and what the attribute reader returns                                                                        |
+
+### Container authoring
+
+_(pre-freeze / unstable)_ A container's **chrome** is its own furniture: the border, the title line, an icon if you like. The factory hides everything else (child-list state, ancestor wiring, the mounting of only what's visible), so your component only has to supply the chrome. Worked end to end in [the walkthrough](plugin-guide.md#walkthrough-a-conspiracy-container-end-to-end).
+
+| Export                                          | Role                                                                                                                                                                                                               |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `createContainerBlock`                          | Wire a nested-child-list container so your component is as thin as the built-in blockquote's                                                                                                                       |
+| `BlockList`                                     | The child-list component your container renders, spread with the factory's props, as a direct child of your box                                                                                                    |
+| `registerChromeLeaf`                            | Register a container's title or summary line as a kind of its own, with a sensible default keymap                                                                                                                  |
+| `chromeChild`                                   | Build the reserved child-0 node for that line: the title text plus its newline (an empty title keeps the bare newline)                                                                                             |
+| `isCollapsedContainer`                          | Read a container's collapse state through its descriptor, so your component and the editor's own walks agree                                                                                                       |
+| `ContainerBlock`, `ContainerBlockComponent`     | What the factory returns (the child-list props, the `containerApi` you publish, the keydown handler, plus the commit, focus-exit, mode, theme and options entries), and the shape that `containerApi` must satisfy |
+| `ContainerBlockDeps`, `ContainerBlockListProps` | The factory's inputs, live getters rather than captured values, and the props `BlockList` takes                                                                                                                    |
+| `RefSlots`                                      | The per-child reference accessors the child-list props carry                                                                                                                                                       |
+| `ChromeLeafOptions`                             | `registerChromeLeaf`'s options: a CSS class for styling the line, keymap overrides, the merge role                                                                                                                 |
+
+### Editable-leaf authoring
+
+_(pre-freeze / unstable)_ The container factory's sibling for leaves; the full story is [The editable leaf](plugin-guide.md#the-editable-leaf).
+
+| Export                                                | Role                                                                                                                                                   |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `createEditableLeaf`                                  | Wire a text-editing leaf with the editor's own caret, IME, undo, selection and clipboard; one spread wires the whole surface                           |
+| `EditableLeaf`                                        | What the factory returns: the spreads, the focus surface your component re-exports, the mode and option reads                                          |
+| `EditableLeafMode`                                    | The two modes: `'plain'` (always-editable source, per-keystroke commits) and `'render-primary'` (rendered view, reveal to edit, one commit on leaving) |
+| `EditableLeafSurfaceProps`, `EditableLeafRenderProps` | The two spreads: the source surface's, and the folded rendered view's (a render-primary block spreads both)                                            |
+| `EditableLeafDeps`                                    | The factory's inputs: live getters for the node, the index, the path, and your source element, plus the static `mode` and `singleLine` settings        |
+| `StickyColumnDirection`                               | Which vertical direction the caret is entering your block from, handed to `focusAtColumn` so the column carries across lines                           |
+
+### Inline authoring
+
+_(pre-freeze / unstable)_ Syntax inside a paragraph: recognize it at a trigger character, render it as an **atomic widget** (one indivisible rendered thing the caret can sit beside but not inside), give it an editing policy. A **rung** is one level in the ordered ladder of recognizers a trigger consults. The render paths and the tier's limits: [Inline kinds](plugin-guide.md#inline-kinds).
+
+| Export                                                    | Role                                                                                                                                                                                                                                                                                       |
+| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `declarePluginInlineKind`                                 | Mint an inline kind, the one-level-down twin of `declarePluginKind`                                                                                                                                                                                                                        |
+| `declaredPluginInlineKind`                                | Recover a declared inline kind in another module                                                                                                                                                                                                                                           |
+| `isInlineKindDeclared`                                    | The is-it-there check for an inline kind                                                                                                                                                                                                                                                   |
+| `registerInlineSyntax`                                    | Hook the inline scanner on one trigger character with your recognizer; a reserved trigger (one a built-in owns, like `[`) takes a prefix rung                                                                                                                                              |
+| `INLINE_PRIORITIES`                                       | The inline ladder, lower consulted first: `prefixOverride` outranks a reserved trigger's built-in case, `plugin` is the bare-trigger default                                                                                                                                               |
+| `InlineSyntaxRecognizer`                                  | The recognizer contract: inspect the raw at the trigger, claim a span by returning a node, or decline with null                                                                                                                                                                            |
+| `InlineSyntaxOptions`                                     | The options bag: the multi-character `prefix`, the `priority`, and `rewriteImage`                                                                                                                                                                                                          |
+| `ImageSyntaxRewriter`, `ImageFields`                      | The `rewriteImage` contract, for a rung whose recognizer builds built-in image nodes and must write edits back in its own syntax, and the edited fields it receives                                                                                                                        |
+| `registerInlineWidgetKind`                                | Render an inline kind as a live atomic widget: a Svelte `component` (recommended) or a hand-built `buildWidget`, never both                                                                                                                                                                |
+| `mintWidgetShell`                                         | Mint the marked, source-stamped span a `buildWidget` returns; its attributes are what the caret's position walk reads                                                                                                                                                                      |
+| `PluginInlineKind`, `InlineNode`                          | The inline kind type, and the node your recognizer builds                                                                                                                                                                                                                                  |
+| `InlineWidgetDescriptor`                                  | The widget registration: the is-this-a-widget test, one render path, the editing policy                                                                                                                                                                                                    |
+| `InlineWidgetComponentProps`                              | A component widget's props: frozen `{ inline, source }`, plus live getters for the mode, the theme, the document, and the content version, and `navigateTo` to jump to another block, optionally at an offset in it (aim at a leaf: a container path scrolls into view but seats no caret) |
+| `InlineWidgetEditingPolicy`, `InlineWidgetEditingContext` | The policy (reveal source on caret entry, delete granularity, edge behavior, a selected-key handler, whether the widget claims the activation click), and the context that handler receives                                                                                                |
+| `isWidgetActivationClick`                                 | Whether a click activates a widget: a Ctrl/Cmd chord while editing, a plain click in reading mode                                                                                                                                                                                          |
+
+### Commands and keybindings
+
+_(pre-freeze / unstable)_ Which tier dispatches what: [Block commands](plugin-guide.md#block-commands).
+
+| Export                                       | Role                                                                                                                                                                                                       |
+| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `registerBlockCommand`                       | Mint a `(kind, name)` command and get back its id, for a keymap binding to target                                                                                                                          |
+| `registerGlobalCommand`                      | Mint a process-wide command run against whichever editor dispatched it, optionally on a global chord; also returns its id                                                                                  |
+| `CommandId`                                  | A built-in command's id; a vocabulary your keymaps may bind too                                                                                                                                            |
+| `KeyBinding`                                 | One keymap entry: a chord (fixed-order `Mod` / `Alt` / `Shift` plus the key), a command id, an optional baked argument                                                                                     |
+| `BlockCommandContext`, `BlockCommandHandler` | What a block command's handler receives (the focused node, read-only; the argument; `updateMetadata`, the way to commit a metadata change; the mounted component's own hooks), and the handler's signature |
+| `PluginCommandId`, `AnyCommandId`            | A minted command's id, and the union spanning built-in and minted                                                                                                                                          |
+
+### Paste transforms
+
+_(pre-freeze / unstable)_ The recipe: [Paste transforms](plugin-guide.md#paste-transforms).
+
+| Export                   | Role                                                                                                                                                                  |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `registerPasteTransform` | Register a pre-parse rewrite of pasted text; transforms run at every paste site, in install order, each seeing the previous one's output, and never on load or typing |
+| `PasteTransform`         | The unit: a process-unique `name`, plus `transform(text)` returning the replacement or null for "not mine"                                                            |
+
+### Decorations
+
+_(pre-freeze / unstable)_ View-only annotations drawn over the rendered document. They live outside the tree, so they reach neither the saved bytes nor the undo stack. You register a source per editor through `editor.decorations` (your `onEditor` context). The recipe and both authoring contracts: [Decorations](plugin-guide.md#decorations).
+
+| Export                                                                       | Role                                                                                                                                                                                           |
+| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DecorationRegistry`                                                         | The `editor.decorations` surface; `addSource` registers a source and returns its handle                                                                                                        |
+| `DecorationSource`                                                           | A named, pure source: `provide(document, ctx)` returns the decorations to render, and is re-run after every edit                                                                               |
+| `DecorationSourceHandle`                                                     | The handle back: `invalidate()` re-runs just your source, synchronously, except from an `edit` handler, where it waits for the commit to publish; `dispose()` removes it                       |
+| `ProvideContext`                                                             | `provide`'s second argument, carrying `editEpoch`: a counter that bumps once per document change and never on `invalidate()`. Key a cached scan on it                                          |
+| `Decoration`                                                                 | The union of the four decoration types a source may return                                                                                                                                     |
+| `MarkDecoration`, `WidgetDecoration`, `ReplaceDecoration`, `BlockDecoration` | The four: a styled span over an inline range, a zero-width widget at an offset, a widget covering a range whose bytes stay in the document, and a whole-block treatment with an optional badge |
+| `DecorationWidgetSpec`                                                       | How a decoration's widget renders: a Svelte `component`, or a hand-built `buildDom`                                                                                                            |
+
+### Events
+
+_(pre-freeze / unstable)_ The payloads `EditorContext.events` delivers to an `on(name, handler)` subscription. The channel itself: [The plugin unit](plugin-guide.md#the-plugin-unit).
+
+| Export                                | Role                                                                                                                                                                  |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `EditorEventMap`                      | Event name to payload, so a handler you declare apart from the `on` call still types                                                                                  |
+| `EditEvent`                           | The `edit` payload: `op`, the `path` it landed at, a per-op `detail`, and a `timestamp`. `op` and `detail` are correlated, so narrowing `op` narrows `detail` with it |
+| `OperationKind`                       | The structural-operation vocabulary `EditEvent.op` draws from                                                                                                         |
+| `SelectionChangeEvent`, `EditorError` | The other two payloads worth naming: the anchor/focus pair (or null), and a contained failure with its `origin` and context                                           |
+
+### Rects
+
+_(pre-freeze / unstable)_ Where things are on screen, reached through `editor.rects` (your `onEditor` context) or the `rects` prop every block component receives.
+
+| Export        | Role                                                                                                                                                                                                                                                                                                                                                   |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `EditorRects` | The geometry surface: a block's box, an inline range's rects (one per visual line), the native caret, a `reveal` that mounts a block the editor had skipped (it only mounts blocks in view), a `scrollTo` that mounts then brings a block into view, and a `navigateTo` that also lands the caret there, at the block's start or at an offset you name |
+
+### Caret geometry
+
+_(pre-freeze / unstable)_ What a kind fills its descriptor's `caretTargetAtPoint` with. The rendered view and the source are different strings, so only your kind knows how a press on one lines up with the other; these three are the pieces that don't depend on your grammar. The worked example is the quickstart's parrot: [The first fifteen minutes](plugin-guide.md#the-first-fifteen-minutes).
+
+| Export                    | Role                                                                                                                                                                                                                      |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `caretOffsetAtPoint`      | The character offset in one of your own elements nearest a viewport point; the point clamps into that element's box first, so a press on your chrome still names one, and null means the element holds no position at all |
+| `CaretTarget`             | What the hook answers: the child path to the leaf (empty when your block is the leaf) and the offset inside it                                                                                                            |
+| `CURSOR_END`, `CursorEnd` | The offset meaning "wherever that leaf ends", and its type; a plain `0` is the other end, since that one is a real offset                                                                                                 |
+
+### Selection geometry
+
+_(pre-freeze / unstable)_ The selection shapes a decoration source or geometry consumer reads.
+
+| Export                              | Role                                                                                                                                                                                                                                                                                                                                |
+| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `EditorSelection`, `SelectionPoint` | The `selectionChange` payload, an anchor/focus pair, and one endpoint of it: a `{ path, offset }`. Inside a table `offset` counts cells rather than characters, and `cellCoordinate` doesn't reliably say so, so check the block's kind the way [the consumer guide](consumer-guide.md#reading-the-document-and-the-selection) does |
+| `SELECTION_END`, `SelectionEnd`     | The importable "through the end of this block's measurable content" value `rangeRects` accepts as `end`, and its type                                                                                                                                                                                                               |
+
+### Parse and serialize
+
+_(pre-freeze / unstable)_ The editor's own parse and serialize entries, re-exported here so an opener or a transform never digs into the package's internals.
+
+| Export                                    | Role                                                                                                                                                                                               |
+| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `parse`                                   | Parse a body of Markdown into a document you can lift children from                                                                                                                                |
+| `ParseScope`                              | What a parse entry is told about its input: a whole document, or one block's bytes (`'fragment'`)                                                                                                  |
+| `parseContainerBody`, `ContainerBodyWrap` | Parse a body that sits between your container's own fence lines, keeping the separating blank lines out of the children; the wrap says which fence lines exist, and matches your kind's `bodyWrap` |
+| `serialize`                               | A whole document back to its exact source bytes                                                                                                                                                    |
+| `serializeChildren`                       | Child nodes joined back into their exact source bytes                                                                                                                                              |
+| `Document`                                | The parsed-document shape both parse entries return                                                                                                                                                |
+| `splitLines`                              | Split source into the parsed lines every line-scoped helper here consumes                                                                                                                          |
+| `ParsedLine`                              | One source line: its text, its bytes with the ending, the ending itself, its offsets                                                                                                               |
+| `isBlankLine`                             | The GFM blank-line test, spaces and tabs only. Don't substitute `trim()`: it would let a pasted non-breaking space split a block                                                                   |
+| `trimTrailingLineEnding`                  | Cut the one trailing line ending (LF or CRLF) off a block's bytes, giving the text you display                                                                                                     |
+| `normalizeLineEndings`                    | CRLF to LF, for text arriving from outside the document (a plugin-owned input surface)                                                                                                             |
+
+### Grammar scanners
+
+_(pre-freeze / unstable)_ The built-in rules for three grammars a plugin commonly claims, exported so you reuse them instead of forking the spec (the spec is longer than it looks, every time, trust me).
+
+| Export                    | Role                                                                                                                                                                                                        |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `matchFenceOpen`          | Recognize a CommonMark code-fence opener line, keeping the verbatim indent and info bytes a byte-exact rebuild needs                                                                                        |
+| `matchFenceClose`         | Is this line the closer for a matched opener (same marker, at least its run length)?                                                                                                                        |
+| `escalatedFenceLength`    | The fence run a body forces so none of its lines reads as the closer; a floor, never a shortening. A kind that rebuilds its own raw around a body owes this, and grows the closer to match                  |
+| `FenceOpen`               | A matched opener: marker, run length, trimmed `info`, verbatim `indent` and `infoRaw`                                                                                                                       |
+| `htmlBlockTagLineMatcher` | Build a recognizer answering `'open'`, `'close'`, or null for one tag name's HTML block line, in every spelling the spec passes through (indented, upper-cased, trailing space), not just the canonical one |
+| `blockquoteExtent`        | Scan a blockquote's full extent (CommonMark lazy continuation) from a start line: its exact bytes plus the index past it (a slice bound, not a consumed count), no child decomposition                      |
+
+### Node access and metadata
+
+_(pre-freeze / unstable, beyond the stable metadata pair `setPluginMetadata` / `getPluginMetadata`)_ The document tree from a plugin's side of the glass: what you read arrives read-only, and what you build yourself stays writable ([Views](plugin-guide.md#views-what-you-read-what-you-own)).
+
+| Export                                   | Role                                                                                                                                                     |
+| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `CstNode`                                | The writable tree-node shape you construct: what a factory builds and a `rebuildRaw` mutates                                                             |
+| `NodeView`, `DocumentView`               | The read-only views every read surface hands you. Writing bytes through one is a compile error                                                           |
+| `setPluginMetadata`, `getPluginMetadata` | Store and read your kind's own typed per-node data, no casting; keep the stored shape primitive-valued                                                   |
+| `getContentRange`, `ContentRange`        | The content span inside a block's raw, syntax markers excluded (a heading's `#`, a setext underline)                                                     |
+| `headingLevel`                           | A heading's level, ATX or setext, null for anything else: the outline read a table-of-contents plugin wants                                              |
+| `computeInlineContent`                   | Inline-parse a prose leaf, uncached and safe inside a reactive read; reference-style links come back unresolved, since no link resolver reaches a plugin |
+| `isProseKind`                            | Does this kind host inline content? The gate that keeps a code block's bytes out of an inline walk                                                       |
+
+### Performance helpers
+
+_(pre-freeze / unstable)_ Two small tools the renderer recipe and the inline recognizers lean on.
+
+| Export               | Role                                                                                                                                                                                                           |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `createBoundedMemo`  | A bounded, least-recently-used memo for per-source work. Async work stores the promise (in-flight renders shared, failures cached like successes); `cloneOnRead` covers a cached value holding a live DOM node |
+| `BoundedMemoOptions` | The memo's options: the entry `cap`, the optional `cloneOnRead`                                                                                                                                                |
+| `createScanIndex`    | Turn a per-block position collector into a "first candidate at or after this offset" lookup (-1 when none), so a recognizer's decline costs one block scan instead of one per trigger                          |