@voithos-labs/aragonite 0.10.4 → 0.10.7

package/dist/plugin.js

@@ -1,26 +1,30 @@
-// The plugin-authoring surface, published at the `@voithos-labs/aragonite/plugin` subpath. Only the
-// authoring API belongs here — not the `<Editor>` embedding barrel (index.ts), no test
-// helpers, no internal dispatch. Sections tagged (pre-freeze) may change until the 1.0
-// freeze.
+// The plugin-authoring API, published at the `@voithos-labs/aragonite/plugin` subpath. Only the
+// authoring API belongs here: not the `<Editor>` embedding barrel (index.ts), no test
+// helpers, no internal dispatch. Nothing is frozen before 1.0: a (pre-freeze) section may change
+// shape, and an untagged one keeps its model while its call shapes can still change.
 import TextEditableBlock from './components/blocks/text/TextEditableBlock.svelte';
 import { registerChromeLeaf as bindChromeLeaf } from './editor-actions/plugin/chrome-leaf';
 import { computeInlineContent as parseLeafInline } from './core/inline';
+import { defaultGrammarView } from './schema/block-openers';
+import { everyInstalledPlugin } from './schema/plugin-activation';
+import { getLanguageAliases as aliasesIn, listLanguages as languagesIn } from './components/blocks/code/code-languages';
+import { tokenizeBody } from './components/blocks/code/code-renderer';
 // ── Plugin unit (pre-freeze) ─────────────────────────────────────────────────
-// Installation is once per process — the editor's `plugins` prop does it, so a
-// consumer rarely calls installPlugins directly.
+// Installation happens once per process; the editor's `plugins` prop does it, so a
+// consumer rarely calls `installPlugins` directly.
 export { definePlugin, isPluginInstalled } from './schema/plugin-install';
 // The single-block shortcut: one kind, one component, one register step.
 export { definePluginBlock } from './schema/define-plugin-block';
 // ── Kind declaration ─────────────────────────────────────────────────────────
 export { declarePluginKind, declaredPluginKind } from './schema/plugin-kind';
-// ── Inline authoring surface (pre-freeze) ────────────────────────────────────
-// Mint an inline kind, hook the scanner on a trigger character, register a live atomic widget.
+// ── Inline authoring API (pre-freeze) ────────────────────────────────────────
+// Declare an inline kind, hook the scanner on a trigger character, register a live widget.
 export { declarePluginInlineKind, declaredPluginInlineKind, isInlineKindDeclared } from './schema/plugin-kind';
 export { registerInlineSyntax, INLINE_PRIORITIES } from './core/inline/scan/plugin-syntax';
 export { registerInlineWidgetKind, mintWidgetShell, isWidgetActivationClick } from './core/inline/inline-widgets';
 // ── Block-kind descriptor registry ───────────────────────────────────────────
-// BlockKindRegistration is the write-side shape; BlockKindDescriptor is the flat
-// read-side one, still exported as the referent of ContainerDescriptorGroup's fields.
+// `BlockKindRegistration` is the shape you register; fields that only mean something together
+// are declared together, so an incoherent pair fails to compile.
 export { registerBlockKind, augmentBlockKind } from './schema/block-kind-descriptor';
 export { simpleLeafClosure, containerClosure } from './schema/closure';
 // ── Component registry ───────────────────────────────────────────────────────
@@ -30,30 +34,40 @@ export { registerBlockOpener } from './schema/block-openers';
 // The shared "does this line start a block at the outer level" gate, so a container opener
 // scanning its own extent ends it where cmark-gfm does instead of forking the rule.
 export { lineStartsOuterBlock } from './schema/block-openers';
-// The built-in priority ladder a plugin opener prices against (pre-freeze) — see the
+// The built-in priority order a plugin opener places itself in (pre-freeze); see the
 // plugin guide's opener-priority section for the two placement rules.
 export { OPENER_PRIORITIES } from './schema/opener-priorities';
 // ── Enter-completion registry (pre-freeze) ───────────────────────────────────
-// The opener's sibling for a grammar whose lines must be adjacent, which Enter alone can
-// never type into existence: a completer reads one typed line and answers the lines that
-// complete it, plus where the caret seats inside the mint.
+// A completer reads one typed line and answers the lines that complete it, plus the caret: for a
+// grammar whose lines must be adjacent, which Enter alone never types.
 export { registerBlockCompleter } from './schema/block-completions';
 // ── Code-block languages (pre-freeze) ────────────────────────────────────────
-// The registry behind fenced-code highlighting. The editor bootstraps a curated set (every
-// grammar is bundle weight for every consumer), so a host needing more registers them itself,
-// BEFORE mounting an editor: a block on screen re-tokenizes only when its bytes next change.
-// An unregistered language is not an error — the fence still round-trips, just untokenized.
-// `listLanguages` lists each language once; `getLanguageAliases` holds the other spellings.
-export { registerLanguage, listLanguages, getLanguageAliases } from './components/blocks/code/code-languages';
-// The code block's own tokenizer, for a plugin whose source surface wants the same highlighting
-// (block math paints its LaTeX with it). Text-preserving: the fragment's textContent is `body`.
-export { tokenizeBody as highlightCode } from './components/blocks/code/code-renderer';
-// ── Command mint (pre-freeze) ────────────────────────────────────────────────
-// A (kind, name) block-command mints a PluginCommandId; AnyCommandId spans built-in and minted.
+// The registry behind fenced-code highlighting: register extra languages before mounting (an
+// unregistered one round-trips untokenized). The reads below see every installed plugin's.
+export { registerLanguage } from './components/blocks/code/code-languages';
+/** Every language once, under its canonical name, sorted. */
+export function listLanguages() {
+    return languagesIn(everyInstalledPlugin);
+}
+/** The other spellings a language answers to, asked by any of them. */
+export function getLanguageAliases(name) {
+    return aliasesIn(name, everyInstalledPlugin);
+}
+/** The code block's own tokenizer, for a plugin's own source view (block math paints its LaTeX
+ *  with it). Text-preserving: the fragment's `textContent` is `body`. */
+export function highlightCode(body, language) {
+    return tokenizeBody(body, language, everyInstalledPlugin);
+}
+// The code block's own drawing of a fenced source, for a kind that holds its own fence: split
+// with `sliceFencedSource`, draw with `renderFencedSource` and your body painter.
+export { sliceFencedSource, renderFencedSource, fenceBodyAsDrawn } from './components/blocks/code/code-renderer';
+// ── Registering commands (pre-freeze) ────────────────────────────────────────
+// A (kind, name) block command creates a `PluginCommandId`; `AnyCommandId` covers both.
 export { registerBlockCommand } from './schema/block-commands';
 // The block context menu: a kind's right-click actions, empty unless something registers them.
 export { registerBlockContextActions } from './schema/context-actions';
-// A global command is process-wide but runs against the dispatching instance's EditorContext.
+// A global command is process-wide but runs against the dispatching instance's `EditorContext`,
+// with the argument `runCommand(id, arg)` or the chord's binding carried.
 export { registerGlobalCommand } from './schema/global-commands';
 // ── Parse / serialize helpers (pre-freeze) ───────────────────────────────────
 // Re-exported so an opener needn't reach into core/ deep paths the packaged artifact
@@ -61,50 +75,57 @@ export { registerGlobalCommand } from './schema/global-commands';
 export { parse } from './core/parser';
 export { serialize, concatChildren as serializeChildren } from './core/serializer';
 export { trimTrailingLineEnding, normalizeLineEndings } from './core/lines';
-// The `ParsedLine[]` every line-scoped seam here consumes — without it a `source →
+// The `ParsedLine[]` every line-based helper here takes; without it a `source →
 // source` transform holding nothing but a string could not reach `blockquoteExtent`.
 export { splitLines } from './core/lines';
-// GFM §2.1's blank line (spaces and tabs only). `String.trim()` would admit the whole
-// Unicode whitespace set and split a block on a pasted non-breaking space.
+// A line a plugin writes takes the document's ending, and per-line work reads a line's text
+// without its ending, so a CRLF document stays CRLF through a plugin's write rule.
+export { documentLineEnding, firstLineEnding, ownTrailingLineEnding, trailingLineEnding, displayLines, joinDisplayLines } from './core/lines';
+// GFM §2.1's blank line (spaces and tabs only) and its whitespace, for a plugin's grammar.
+// `String.trim()` and JS `\s` would also take a non-breaking space, which is content.
 export { isBlankLine } from './core/parser';
-// A container whose body sits between chrome lines of its own (`:::note` … `:::`,
-// `<summary>` … `</details>`) parses that body here, not with `parse`: the blank line
-// against a chrome line is a separator, and only this seam knows to keep it out of the
-// children. See `design/syntax-tree.md` § blank lines.
+export { isBlankText, isWhitespaceChar, trimWhitespace } from './core/lines';
+// A body between marker lines of its own (`:::note` … `:::`) parses here, not with `parse`: the
+// blank line against a marker line is a separator (`docs/design/syntax-tree.md` § Blank lines).
 export { parseContainerBody } from './core/parser';
 // ── Fence grammar (pre-freeze) ───────────────────────────────────────────────
-// The built-in CommonMark fence recognizers, so a plugin claiming a fence (```mermaid) never
-// reimplements the rules. The opener match keeps verbatim indent/info bytes, for byte-exact
-// rebuilds; `escalatedFenceLength` is `escalatedColonCount`'s fence twin, owed by any kind that
-// rebuilds its own raw around a body it did not parse.
-export { matchFenceOpen, matchFenceClose, escalatedFenceLength } from './core/parsers/fence-syntax';
+// The CommonMark fence grammar, so a plugin taking over a fence (```mermaid) never reimplements
+// it: `fenceRawWrite` serves as its `rawWrite`, and `escalatedFenceLength` sizes a rebuilt fence.
+export { matchFenceOpen, matchFenceClose, escalatedFenceLength, findFenceCloser, fenceAnatomy, matchFenceInfo } from './core/parsers/fence-syntax';
+export { scanFence } from './core/parsers/fenced-code';
+export { fenceRawWrite, fenceShapeOfRaw } from './schema/fenced-code-raw';
 // ── HTML tag-line grammar (pre-freeze) ───────────────────────────────────────
-// CommonMark's type-6 tag-line shape for one tag name. What actually closes such a
-// container is everything the spec passes through raw (indented, upper-cased, trailing
-// space) — looser than any canonical form a rebuild emits.
+// CommonMark's type-6 tag-line shape for one tag name. What closes such a container is anything
+// the spec passes through raw, looser than the canonical form a rebuild emits.
 export { htmlBlockTagLineMatcher } from './core/parsers/html-block';
 // ── Blockquote grammar (pre-freeze) ──────────────────────────────────────────
-// The built-in blockquote extent scanner, so a plugin claiming a blockquote-shaped
-// construct (`> [!NOTE]`) reuses CommonMark §5.1 lazy continuation instead of forking it.
+// The built-in blockquote extent scanner, so a plugin that takes over a blockquote-shaped
+// construct (`> [!NOTE]`) reuses CommonMark §5.1 lazy continuation instead of writing its own.
 export { blockquoteExtent } from './core/parsers/blockquote';
 // Store/read a plugin kind's own metadata shape without casting through `BlockMetadata`.
 export { setPluginMetadata, getPluginMetadata } from './core/nodes';
 // The content span within a block's raw, syntax markers excluded (a heading's `#` prefix).
 export { getContentRange } from './core/inline';
-// A heading's level (ATX or setext), null otherwise: the typed path past the
-// built-in-node narrowing this barrel keeps internal.
+// A heading's level (ATX or setext), null otherwise: the typed way to ask, since the
+// built-in node narrowing stays internal to this barrel.
 export { headingLevel } from './core/nodes';
-// Pure and uncached — the reactive-safe path a widget's `$derived` reads. `isProseKind`
-// gates the walk so a code block's bytes are never inline-scanned.
+// Pure and uncached, so a widget's `$derived` can read it safely. `isProseKind` guards the
+// traversal so a code block's bytes are never inline-scanned.
 export { isProseKind } from './core/inline';
+// Pre-order over a document or subtree, with 'skip' and 'stop', so a plugin writes no recursion.
+export { walkBlocks } from './core/paths';
+// The block at a path, or null for the root or a path that leads nowhere.
+export { blockNodeAt } from './tree-operations/node-primitives';
 /**
- * Inline-parse a prose leaf. No link-reference resolver is available to a plugin, so
- * reference links parse as `unresolvedReference`; every other construct fully resolves.
+ * Inline-parse a prose leaf with every installed plugin's syntax, for a pipeline with no editor
+ * mounted. Inside an editor use `EditorContext.computeInlineContent`, which reads only the plugins
+ * that editor lists and resolves the document's reference links. With no document here, a
+ * reference link reads as its bracketed text.
  */
 export function computeInlineContent(node) {
-    return parseLeafInline(node);
+    return parseLeafInline(node, undefined, defaultGrammarView);
 }
-// ── Idempotent-registration probes ─────────────────────────────────────────────
+// ── Re-registration checks ─────────────────────────────────────────────────────
 // The register-once registries throw on duplicate; a plugin re-registers safely
 // (HMR / re-import) by guarding on these.
 export { isBlockKindDeclared } from './schema/plugin-kind';
@@ -113,60 +134,62 @@ export { isBlockComponentRegistered } from './schema/block-component-registry';
 export { isBlockOpenerRegistered } from './schema/block-openers';
 export { isBlockCompleterRegistered } from './schema/block-completions';
 export { isPasteTransformRegistered } from './tree-operations/paste/paste-transforms';
-// ── Container-authoring surface (pre-freeze) ─────────────────────────────────
+export { isLanguageRegistered } from './components/blocks/code/code-languages';
+// ── Container-authoring API (pre-freeze) ─────────────────────────────────────
 // Lets a plugin build an editable nested container as thinly as the built-in
 // blockquote, without touching any editor context key.
 export { default as BlockList } from './components/BlockList.svelte';
 export { createContainerBlock } from './editor-actions/plugin/container';
-// The one seam allowed to import components/, so editor-actions keeps no upward
-// value edge to the component tree.
+// The one place allowed to import from `components/`, so `editor-actions` keeps no upward
+// value dependency on the component tree.
 export function registerChromeLeaf(kind, opts) {
     bindChromeLeaf(kind, TextEditableBlock, opts);
 }
-// Mint the reserved child-0 node for a container's chrome leaf: text plus its newline.
+// Create the reserved child-0 node for a container's title leaf: the text plus its newline.
 export { chromeChild } from './editor-actions/plugin/chrome-leaf';
-// One definition of collapsed, shared by a component's getter and the model-layer walks.
+// One definition of collapsed, shared by a component's getter and the traversals over the CST.
 export { isCollapsedContainer } from './schema/reserved-chrome';
-// ── Editable-leaf authoring surface (pre-freeze) ─────────────────────────────
-// A text-editing leaf with native caret/IME/undo/selection parity, plain (per-keystroke
-// commits) or render-primary (reveal-to-edit, one commit on blur). The
-// createContainerBlock sibling for leaves.
+// ── Editable-leaf authoring API (pre-freeze) ─────────────────────────────────
+// A text-editing leaf with the browser's own caret, IME, undo and selection: plain (a commit per
+// keystroke) or render-first (source while the caret is inside, one commit on blur).
 export { createEditableLeaf } from './components/blocks/editable-leaf';
 // ── Directive authoring (pre-freeze) ─────────────────────────────────────────
-// `activateDirectives()` claims `:::` — call it once at startup, before the editor
-// parses. The other symbols are inert: importing them does NOT claim the grammar.
+// `activateDirectives()` takes over `:::`; call it once at startup, before the editor
+// parses. The other symbols do nothing on their own: importing them takes over no grammar.
 export { activateDirectives } from './components/blocks/directive/activate-directives';
 export { registerDirective, isDirectiveRegistered } from './core/directive/registry';
-// `escalatedColonCount` is the rule `serializeDirective` already applies; exported for
-// emitters that build `:::name` text by concatenation instead of through the CST, where
-// a body line reproducing the fence would otherwise close the container early.
+// `escalatedColonCount` is the rule `serializeDirective` applies, for emitters building `:::name`
+// text by concatenation, where a body line reproducing the fence would close it early.
 export { escalatedColonCount, parseDirectiveAttributes, serializeDirective } from './core/directive/grammar';
 // The `rebuildRaw` for a directive container whose child 0 is an editable title.
 export { createDirectiveRebuild } from './editor-actions/plugin/directive-container';
 // The wrap every `:::` body parses with; a directive kind declares it as its `container.bodyWrap`
-// so the editor's separator settle knows the blank line against the fence belongs to the fence.
+// so the editor's blank-line fix-up knows the blank line against the fence belongs to the fence.
 export { DIRECTIVE_BODY_WRAP } from './core/directive/kinds';
 // ── Renderer utilities (pre-freeze) ──────────────────────────────────────────
-// A bounded LRU memo for a renderer's per-source work, sync or async (store the
-// promise). See the plugin guide's renderer recipe.
+// Where an injected renderer is set and cached per theme, with the plugin's own fallback when it's
+// missing or throws; and the bounded LRU memo under it. See the plugin guide's renderer recipe.
 export { createBoundedMemo } from './bounded-memo';
+export { createRendererSlot, createAsyncRendererSlot, renderSourceFallback } from './renderer-slot';
 // ── Recognizer scan index (pre-freeze) ───────────────────────────────────────
-// The bounded decline for a grammar with no early-stop byte (the guide's inline-kinds
-// section): a per-block position collector becomes a memoized lookup answering the first
-// candidate at or after `from` (-1 when none), one scan per block behind a cap-2 memo.
+// For a grammar with no early-stop byte: collect candidate positions once per block, then answer
+// the first at or after `from` (-1 when none) behind a two-entry memo.
 export { createScanIndex } from './scan-index';
 // ── Paste transforms (pre-freeze) ────────────────────────────────────────────
 // A pre-parse clipboard rewrite: inspect the raw pasted text, replace it or decline
-// (null). Transforms run in install order at every paste site — never on load or typing.
+// (null). Transforms run in install order at every paste, never on load or while typing.
 export { registerPasteTransform } from './tree-operations/paste/paste-transforms';
+// ── Insert catalogue (pre-freeze) ────────────────────────────────────────────
+// The blocks the insert menus offer, read through `editor.insertCatalogue`. A plugin adds its own
+// block from `setup`, listed only in the editors that activate it; the icon is a menu glyph name.
+export { registerInsertEntry } from './schema/insert-catalogue';
 // ── Caret geometry (pre-freeze) ──────────────────────────────────────────────
-// The kit a kind answers `caretTargetAtPoint` with: the landing shape, the probe that turns a
-// point in one of your own elements into an offset (NEAREST, so a press on your chrome still
-// names one), and the sentinel for "wherever this leaf ends".
+// What a kind answers `caretTargetAtPoint` with, the helper that turns a point in your element
+// into the nearest offset, and the value for wherever the leaf ends.
 export { caretOffsetAtPoint } from './cursor/point-offset';
 export { CURSOR_END } from './block-component';
 // ── Pointer gestures (pre-freeze) ────────────────────────────────────────────
-// Put this attribute on an element whose drags are your widget's own (a pan, a brush) and the
-// editor's pointer arms leave a press inside it alone: no block range, no click ladder.
+// Put this attribute on an element whose drags belong to your widget (a pan, a brush) and the
+// editor's pointer handlers leave a click inside it alone: no block range, no click handling.
 export { POINTER_GESTURE_ATTR } from './selection/pointer-gesture';
 export { SELECTION_END } from './block-component';

package/dist/plugins/admonitions/AdmonitionBlock.svelte

@@ -1,11 +1,15 @@
 <!--
-  One alert box for both admonition kinds: the directive admonition (editable title
-  chrome leaf at child 0) and the GitHub alert (no title, a static badge instead).
-  createContainerBlock hides all child-list state, so this owns only its chrome;
-  node/index/path go in as thunks so each is re-read live, never snapshotted.
+  One alert box for both kinds: the directive admonition (an editable title at child 0)
+  and the GitHub alert (no title, a static badge instead).
 -->
 <script lang="ts">
-	import { BlockList, createContainerBlock, getPluginMetadata, type NodeView } from '../../plugin';
+	import {
+		BlockList,
+		createContainerBlock,
+		getPluginMetadata,
+		isBlankText,
+		type NodeView
+	} from '../../plugin';
 	import {
 		capitalize,
 		coerceAdmonitionName,
@@ -30,7 +34,7 @@
 			? coerceAdmonitionName(getPluginMetadata<GithubAlertMetadata>(node)?.alertType?.toLowerCase())
 			: coerceAdmonitionName(getPluginMetadata<AdmonitionMetadata>(node)?.name)
 	);
-	const titleEmpty = $derived(isAlert || (node.children?.[0]?.raw ?? '').trim() === '');
+	const titleEmpty = $derived(isAlert || isBlankText(node.children?.[0]?.raw ?? ''));
 
 	export { containerApi };
 </script>
@@ -54,7 +58,7 @@
 </div>
 
 <style>
-	/* A gutter rail, not a card: a document, not a boxed callout. */
+	/* A line down the left margin, not a card: this reads as a document, not a boxed callout. */
 	.admonition {
 		position: relative;
 		margin: 0.8em 0;
@@ -62,9 +66,8 @@
 		border-left: 3px solid var(--adm-accent);
 	}
 
-	/* One block per kind carries the whole axis: accent, icon glyph, untitled label. Fixed hex,
-	   not theme tokens: GitHub's alert palette is canonically one color per kind, so admonitions
-	   read identically across host themes. */
+	/* One block per kind sets what varies, in fixed hex after GitHub's one-color-per-kind alert
+	   palette, so an admonition looks the same whatever theme the host uses. */
 	.admonition[data-kind='note'] {
 		--adm-accent: #1f6feb;
 		--adm-label: 'Note';
@@ -101,7 +104,7 @@
 		line-height: 1.4em;
 	}
 
-	/* The alert badge is static chrome, never a caret target. */
+	/* The alert badge is decoration, never a caret target. */
 	.admonition[data-alert-source='github'] :global(.admonition-title) {
 		user-select: none;
 		cursor: default;

package/dist/plugins/admonitions/admonition-kind.js

@@ -2,7 +2,7 @@
  * The reference `:::name` directive container. Reuses the shared directive grammar rather
  * than a hand-written opener, so the fence bytes stay the round-trip truth.
  */
-import { activateDirectives, chromeChild, containerClosure, createDirectiveRebuild, declarePluginKind, defineBlockComponent, DIRECTIVE_BODY_WRAP, registerBlockComponent, registerBlockKind, registerBlockCommand, registerChromeLeaf, registerDirective, registerPasteTransform, isDirectiveRegistered, setPluginMetadata, getPluginMetadata } from '../../plugin';
+import { activateDirectives, chromeChild, containerClosure, createDirectiveRebuild, declarePluginKind, defineBlockComponent, DIRECTIVE_BODY_WRAP, registerBlockComponent, registerBlockKind, registerBlockCommand, registerChromeLeaf, registerDirective, registerPasteTransform, isDirectiveRegistered, setPluginMetadata, getPluginMetadata, trimWhitespace } from '../../plugin';
 import { ADMONITION, ADMONITION_KINDS, ADMONITION_TITLE, coerceAdmonitionName } from './kinds';
 import { githubAlertsPasteTransform } from './convert-document';
 import { registerGithubAlert } from './github-alert-kind';
@@ -10,7 +10,7 @@ import AdmonitionBlock from './AdmonitionBlock.svelte';
 /** Child 0 is the title (the opener line's info, editable); children 1+ are the body. */
 function admonitionFromDirective(kind, titleKind) {
     return (parsed) => {
-        const title = parsed.fence.info.trim();
+        const title = trimWhitespace(parsed.fence.info);
         const node = {
             kind,
             leadingTrivia: parsed.leadingTrivia,
@@ -35,13 +35,14 @@ export function registerAdmonitions(options) {
     const admonition = declarePluginKind(ADMONITION);
     const title = declarePluginKind(ADMONITION_TITLE);
     const build = admonitionFromDirective(admonition, title);
-    // Every name resolves to one kind, which reads its variant back from metadata.
+    // Every name resolves to one kind, which reads its variant back from metadata. A name
+    // something else claimed first stays theirs.
     for (const name of ADMONITION_KINDS) {
         if (!isDirectiveRegistered('container', name)) {
             registerDirective('container', name, { kind: admonition, fromDirective: build });
         }
     }
-    // `updateMetadata` is the sanctioned commit path: patch, rebuildRaw, one undoable edit.
+    // `updateMetadata` is the only supported commit path: patch, rebuildRaw, one undoable edit.
     const cycleKind = registerBlockCommand(admonition, 'admonition.cycleKind', (ctx) => {
         const meta = getPluginMetadata(ctx.node);
         const dir = ctx.arg === 'prev' ? -1 : 1;
@@ -51,10 +52,14 @@ export function registerAdmonitions(options) {
         return true;
     });
     registerBlockKind(admonition, {
+        label: 'Admonition',
+        // A note reads as part of the text around it, so it shows no drag handle.
+        pageRole: 'prose',
         mergeRole: 'container',
         editable: true,
         supportsInline: false,
-        // Opaque tier rule: no textual escape hatch at either edge, so both take the gap caret.
+        // An opaque container has no text at either edge for the caret to step into, so both
+        // edges take the gap caret.
         gapEdges: 'both',
         container: {
             // The title lives in the opener line, so raw is not a strip of the children.
@@ -62,10 +67,7 @@ export function registerAdmonitions(options) {
             rebuildRaw: rebuildAdmonitionRaw,
             bodyWrap: DIRECTIVE_BODY_WRAP,
             reservedChrome: { kind: title },
-            unwrapRole: {
-                firstChildBackspace: 'keep-reserved-chrome',
-                middleChildBackspace: 'default-merge'
-            }
+            unwrapRole: { middleChildBackspace: 'default-merge' }
         },
         keymap: [{ chord: 'Mod+7', command: cycleKind }],
         conformanceFixture: ':::note Heads up\n\nbody\n\n:::\n',
@@ -87,7 +89,7 @@ export function registerAdmonitions(options) {
             }
         })
     });
-    registerChromeLeaf(title, { blockClass: 'admonition-title' });
+    registerChromeLeaf(title, { label: 'Title', blockClass: 'admonition-title' });
     registerBlockComponent(admonition, defineBlockComponent(AdmonitionBlock));
     if (options?.convertAlertsOnPaste) {
         registerPasteTransform(githubAlertsPasteTransform);

package/dist/plugins/admonitions/convert-document.d.ts

@@ -1,11 +1,11 @@
 /**
- * Document-scoped GitHub-alert conversion, the sanctioned rewrite pattern:
- * `getSource()` → transform → write the `source` prop back. Scoping through
- * `parse` rather than line scanning is what makes it fence-safe; nested alerts are
- * skipped because rewriting one would mean rebuilding its ancestors' raw.
+ * GitHub-alert conversion over a whole document, and the supported way to rewrite one:
+ * `getSource()` → transform → write the `source` prop back. Going through `parse` rather
+ * than scanning lines is what makes it fence-safe; nested alerts are skipped because
+ * rewriting one would mean rebuilding its ancestors' raw.
  */
 import { type PasteTransform } from '../../plugin';
 import { type AlertConversion } from './gh-alert';
 export declare function convertGithubAlertsInDocument(source: string): AlertConversion;
-/** The line probe short-circuits the common no-alert paste before the parse. */
+/** The line scan short-circuits the common no-alert paste before the parse. */
 export declare const githubAlertsPasteTransform: PasteTransform;

package/dist/plugins/admonitions/convert-document.js

@@ -1,13 +1,14 @@
 /**
- * Document-scoped GitHub-alert conversion, the sanctioned rewrite pattern:
- * `getSource()` → transform → write the `source` prop back. Scoping through
- * `parse` rather than line scanning is what makes it fence-safe; nested alerts are
- * skipped because rewriting one would mean rebuilding its ancestors' raw.
+ * GitHub-alert conversion over a whole document, and the supported way to rewrite one:
+ * `getSource()` → transform → write the `source` prop back. Going through `parse` rather
+ * than scanning lines is what makes it fence-safe; nested alerts are skipped because
+ * rewriting one would mean rebuilding its ancestors' raw.
  */
-import { parse } from '../../plugin';
+import { documentLineEnding, parse } from '../../plugin';
 import { convertAlertBlockquoteRaw, hasGithubAlert } from './gh-alert';
 export function convertGithubAlertsInDocument(source) {
     const doc = parse(source, { scope: 'document' });
+    const ending = documentLineEnding(doc);
     let changed = false;
     const parts = [doc.prefix];
     for (const child of doc.children) {
@@ -15,7 +16,7 @@ export function convertGithubAlertsInDocument(source) {
         // Both kinds feed the same first-line converter: a plain blockquote may still
         // hold a mid-quote marker, which must stay literal.
         const isAlertShaped = child.kind === 'blockquote' || child.kind === 'githubAlert';
-        const converted = isAlertShaped ? convertAlertBlockquoteRaw(child.raw) : null;
+        const converted = isAlertShaped ? convertAlertBlockquoteRaw(child.raw, ending) : null;
         if (converted !== null) {
             parts.push(converted);
             changed = true;
@@ -27,7 +28,7 @@ export function convertGithubAlertsInDocument(source) {
     parts.push(doc.suffix);
     return { converted: parts.join(''), changed };
 }
-/** The line probe short-circuits the common no-alert paste before the parse. */
+/** The line scan short-circuits the common no-alert paste before the parse. */
 export const githubAlertsPasteTransform = {
     name: 'admonitions.github-alerts',
     transform(text) {

package/dist/plugins/admonitions/gh-alert.d.ts

@@ -1,3 +1,10 @@
+/**
+ * The one place `> [!TYPE]` is recognized, shared with the native `githubAlert` opener.
+ * Both converters ask the parser how far the blockquote runs, so CommonMark §5.1 lazy
+ * continuation is handled identically. For a whole document use `convert-document.ts`
+ * instead: the scanner here is not fence-safe.
+ */
+import { type LineEnding } from '../../plugin';
 /** The type as typed (`NOTE`, `Note`); the opener stores it verbatim so source casing
  *  survives a rebuild. */
 export declare function matchAlertMarker(line: string): string | null;
@@ -8,6 +15,6 @@ export interface AlertConversion {
 }
 /** GitHub honors `[!TYPE]` only on the blockquote's first line; everything after,
  *  lazy-continuation lines and later literal markers alike, is body. */
-export declare function convertAlertBlockquoteRaw(raw: string): string | null;
+export declare function convertAlertBlockquoteRaw(raw: string, ending: LineEnding): string | null;
 export declare function convertGithubAlerts(text: string): AlertConversion;
 export declare function hasGithubAlert(text: string): boolean;

package/dist/plugins/admonitions/gh-alert.js

@@ -1,15 +1,15 @@
 /**
- * The single home for `> [!TYPE]` recognition, reused by the native `githubAlert` opener.
- * Both converters run the parser's own extent authority so CommonMark §5.1 lazy
- * continuation lands identically. On a whole document prefer the wrapper in
- * `convert-document.ts`: the stream scanner here is not fence-safe.
+ * The one place `> [!TYPE]` is recognized, shared with the native `githubAlert` opener.
+ * Both converters ask the parser how far the blockquote runs, so CommonMark §5.1 lazy
+ * continuation is handled identically. For a whole document use `convert-document.ts`
+ * instead: the scanner here is not fence-safe.
  */
-import { blockquoteExtent, escalatedColonCount, splitLines } from '../../plugin';
+import { blockquoteExtent, escalatedColonCount, firstLineEnding, splitLines } from '../../plugin';
 import { ADMONITION_KINDS } from './kinds';
 const ALERT_NAMES = new Set(ADMONITION_KINDS);
 const CANONICAL_COLONS = 3;
-/** Every `>` pattern here caps indent at CommonMark's 0–3 spaces: past that the line is
- *  indented code, and claiming it would promote a literal `>` to a marker on rebuild. */
+/** Every `>` pattern here caps indent at CommonMark's 0 to 3 spaces: past that the line is
+ *  indented code, and taking it would promote a literal `>` to a marker on rebuild. */
 const MARKER = /^ {0,3}>[ \t]*\[!([A-Za-z]+)\][ \t]*$/;
 const QUOTE_OPEN = /^ {0,3}>/;
 /** The type as typed (`NOTE`, `Note`); the opener stores it verbatim so source casing
@@ -22,20 +22,16 @@ export function stripQuoteMarker(line) {
     const m = /^ {0,3}>[ \t]?/.exec(line);
     return m ? line.slice(m[0].length) : line;
 }
-/**
- * Each emitted line keeps its source line ending so CRLF survives; the closer runs one line past
- * the source, which is what the fallback covers. The body converts in the same pass: stripping a
- * quote level promotes a nested `> [!TIP]` to a top-level marker a later pass would convert again.
- */
-function emitDirective(name, source) {
-    const fallback = source.find((line) => line.lineEnding !== '')?.lineEnding ?? '\n';
+/** Each emitted line keeps its own ending, else `ending`, so CRLF survives. The body converts in
+ *  the same pass, since stripping a quote level exposes a nested `> [!TIP]` to a second pass. */
+function emitDirective(name, source, fallback) {
     const stripped = source
         .slice(1)
         .map((line) => stripQuoteMarker(line.text) + (line.lineEnding || fallback))
         .join('');
-    const body = splitLines(convertGithubAlerts(stripped).converted);
-    // Fence lengthened past any colon run in the body, which would otherwise read as the
-    // container's own closer once this output is written into the document.
+    const body = splitLines(convertAlerts(stripped, fallback).converted);
+    // The fence runs longer than any colon run in the body, which would otherwise read as
+    // this container's own closer once the output is written into the document.
     const colons = ':'.repeat(escalatedColonCount(body.map((line) => line.text).join('\n'), CANONICAL_COLONS));
     let out = `${colons}${name}${source[0].lineEnding || fallback}`;
     for (let i = 0; i < body.length; i++)
@@ -44,14 +40,17 @@ function emitDirective(name, source) {
 }
 /** GitHub honors `[!TYPE]` only on the blockquote's first line; everything after,
  *  lazy-continuation lines and later literal markers alike, is body. */
-export function convertAlertBlockquoteRaw(raw) {
+export function convertAlertBlockquoteRaw(raw, ending) {
     const lines = splitLines(raw);
     if (lines.length === 0)
         return null;
     const typed = matchAlertMarker(lines[0].text);
-    return typed ? emitDirective(typed.toLowerCase(), lines) : null;
+    return typed ? emitDirective(typed.toLowerCase(), lines, ending) : null;
 }
 export function convertGithubAlerts(text) {
+    return convertAlerts(text, firstLineEnding(text) ?? '\n');
+}
+function convertAlerts(text, ending) {
     const lines = splitLines(text);
     let converted = '';
     let changed = false;
@@ -60,10 +59,10 @@ export function convertGithubAlerts(text) {
         const typed = matchAlertMarker(lines[i].text);
         if (typed && startsBlockquote(lines, i)) {
             const { nextIndex } = blockquoteExtent(lines, i, lines.length);
-            // A marker line always opens a quote, so the extent claims at least this line;
-            // floored anyway because a loosened indent cap would hang this loop.
+            // A marker line always opens a quote, so the extent covers at least this line;
+            // checked anyway because a loosened indent cap would hang this loop.
             if (nextIndex > i) {
-                converted += emitDirective(typed.toLowerCase(), lines.slice(i, nextIndex));
+                converted += emitDirective(typed.toLowerCase(), lines.slice(i, nextIndex), ending);
                 changed = true;
                 i = nextIndex;
                 continue;

package/dist/plugins/admonitions/github-alert-kind.d.ts

@@ -1,12 +1,10 @@
 /**
- * Native GitHub alerts as a strip container in the blockquote mold, bytes kept and
- * never rewritten to `:::note`. The marker lives only in the container's raw +
- * metadata, so `strip(raw)` equals the serialized children. A separate kind rather
- * than a directive-admonition variant, so kind stability and rebuildRaw stay
- * unambiguous per kind (the ATX/setext heading precedent).
+ * Native GitHub alerts as a strip container shaped like a blockquote: the source bytes are
+ * kept, never rewritten to `:::note`. The marker lives only in the container's raw and
+ * metadata, so `strip(raw)` equals the serialized children. Its own kind rather than a
+ * variant of the directive admonition, so kind stability and rebuildRaw stay unambiguous.
  */
 import { type CstNode } from '../../plugin';
-/** Splitting the body on `\n` keeps a `\r` at each segment's tail, so CRLF rides through;
- *  the marker's own ending is read off the current raw. */
+/** Every body line keeps its own ending; the marker line keeps the one the current raw gives it. */
 export declare function rebuildGithubAlertRaw(node: CstNode): void;
 export declare function registerGithubAlert(): void;