@voithos-labs/aragonite 0.10.4 → 0.10.7

package/dist/components/menu/SelectionToolbar.svelte

@@ -1,10 +1,8 @@
 <script lang="ts">
 	/**
-	 * The editor's own formatting popover over a selection, in Notion's shape: a row of the
-	 * marks, then labelled rows for what acts on the selection as a whole. Built on the same
-	 * doors a host's chrome would use (`selectionChange`, the rect API, the command door), so
-	 * the consumer-guide recipe and this component cannot disagree about what a selection
-	 * toolbar may read.
+	 * The editor's own formatting popover over a selection: a row of marks, then labelled rows
+	 * for what acts on the whole selection. Built only on the public API a host's toolbar would
+	 * use (`selectionChange`, the rect API, `runCommand`), so the consumer-guide recipe matches it.
 	 */
 	import type { EditorInstance } from '../../editor-props';
 	import type { EditorSelection } from '../../selection/primitives';
@@ -14,7 +12,8 @@
 	import { SELECTION_TOOLBAR_LABEL } from '../../a11y-strings';
 	import { keepFlyoutOnScreen } from './flyout-placement';
 	import { runClipboardAction } from './clipboard-actions';
-	import MenuIcon, { type MenuIconName } from './MenuIcon.svelte';
+	import MenuIcon from './MenuIcon.svelte';
+	import type { MenuIconName } from '../../menu-icons';
 
 	type ToolbarEditor = Pick<
 		EditorInstance,
@@ -68,20 +67,20 @@
 	let current: EditorSelection | null = null;
 	let barEl: HTMLDivElement | undefined = $state();
 
-	// A labelled row the door declines leaves the bar, where a mark only dims: the icons keep the
-	// bar's shape, a dead row is a line of noise over a selection it cannot act on.
+	// A labelled row the editor refuses is dropped, where a mark only dims: the icons keep the
+	// bar's shape, while a row that does nothing is noise over a selection it cannot act on.
 	const rows = $derived(ROWS.filter((row) => !declined.has(row.command)));
 	const offersHeading = $derived(!declined.has(TURN_INTO_COMMAND));
 
 	interface Placement {
 		x: number;
 		y: number;
-		/** The selection's first rect, for the flip above when there is no room below. */
+		/** The selection's first rectangle, used when the bar has to go above it instead. */
 		flipY: number;
 	}
 
-	// The editor root's top is the floor the flip may not cross: whatever host chrome sits
-	// above the editor ends where the root begins.
+	// The editor root's top is the line the bar may not cross: whatever the host draws above
+	// the editor ends where the root begins.
 	function topInset(): number {
 		return Math.max(0, root?.getBoundingClientRect().top ?? 0);
 	}
@@ -93,7 +92,7 @@
 	}
 
 	// The bar's own size, measured once it is in the DOM, so the placement can keep it on screen:
-	// pushed left at the right edge, flipped above the selection when there is no room below.
+	// pushed left at the right edge, moved above the selection when there is no room below.
 	let size = $state<{ w: number; h: number } | null>(null);
 	$effect(() => {
 		if (!barEl || !placement) return;
@@ -114,13 +113,12 @@
 
 	$effect(() => editor.getEvents().on('selectionChange', update));
 
-	// Only once the drag is over: a bar that appears and re-seats under a moving pointer is in the
-	// way of the very selection being made. The press is watched at the document, since the drag
-	// can end anywhere; the release places the bar from the selection that stood at that moment.
+	// Shown only once the drag is over, since a bar moving under the pointer is in the way;
+	// watched at the document, where the drag can end anywhere.
 	let pointerHeld = false;
 	$effect(() => {
-		// A press on the bar itself is a button, not a drag: arming the release here would re-place
-		// the bar (and close its flyout) under the click that follows.
+		// A pointer-down on the bar itself is a button, not a drag: watching for its release
+		// would re-place the bar, and close its flyout, under the click that follows.
 		const down = (e: PointerEvent) => {
 			if (e.button === 0 && !barEl?.contains(e.target as Node)) pointerHeld = true;
 		};
@@ -141,7 +139,7 @@
 		};
 	});
 
-	// The editor's own right-click menu takes the selection's spot; two cards over one range read
+	// The editor's own right-click menu takes the selection's spot; two panels over one range read
 	// as a glitch, so the bar hides while it is open and comes back where the selection still is.
 	let menuOpen = false;
 	$effect(() =>
@@ -182,8 +180,8 @@
 		placement = selection ? shownOver(selection) : null;
 	}
 
-	// The door decides where the bar belongs: over a code fence or an equation's source it declines
-	// every mark, and a bar of greyed buttons is worse than none.
+	// The editor decides where the bar belongs: over a code fence or an equation's source it
+	// refuses every mark, and a bar of greyed-out buttons is worse than none.
 	function shownOver(selection: EditorSelection): Placement | null {
 		if (menuOpen || pointerHeld) return null;
 		if (MARKS.every((mark) => declined.has(mark.command))) return null;
@@ -194,10 +192,8 @@
 		const { start, end } = normalizeSelection(selection);
 		const sameBlock = start.path.join('.') === end.path.join('.');
 		if (!sameBlock) {
-			// The bar hangs off where the selection ENDS, so the end block's rects come first. A
-			// selection that starts at the very end of one block (a drag that left the block
-			// upward, or began at the previous paragraph's end) leaves the start block's remaining
-			// range empty, so that read is a fallback, and the start block's whole box the last one.
+			// The bar hangs off where the selection ends; the start block's remaining range, then
+			// its whole box, are the fallbacks when the end block yields no rectangle.
 			const rects = editor.getRects();
 			const endRects =
 				editor.getBlockKindAt(end.path) !== 'table' && end.offset > 0
@@ -209,27 +205,26 @@
 			const measured = anchored.length ? anchored : rects.rangeRects(start.path, 0, SELECTION_END);
 			return measured.length ? belowRight(measured) : null;
 		}
-		// An intra-table rectangle shares the table's path and carries cell indices on endpoints the
-		// flag need not mark, so the kind read is what excludes it rather than the flag.
+		// A rectangle inside one table shares the table's path and holds cell indices on endpoints
+		// the cross-block flag need not set, so the kind is what rules it out, not the flag.
 		if (editor.getBlockKindAt(start.path) === 'table') return null;
 		if (start.offset === end.offset) return null;
 		const rects = editor.getRects().rangeRects(start.path, start.offset, end.offset);
 		return rects.length ? belowRight(rects) : null;
 	}
 
-	/** The bar opens like a menu: below the selection's last line and to the right of where it
-	 *  ends, never over the text. The clamp above pushes it left at the viewport edge and flips it
-	 *  above the first line when there is no room below. */
+	/** Below the selection's last line and right of where it ends, never over the text; the
+	 *  clamp above moves it left or above when there is no room. */
 	function belowRight(rects: DOMRect[]): Placement | null {
 		const first = rects[0];
 		const last = rects[rects.length - 1];
-		// Scrolled out from under the host's chrome or off the bottom: nothing to anchor to.
+		// Scrolled out from under whatever the host draws above, or off the bottom: nowhere to go.
 		if (last.bottom < topInset() || first.top > window.innerHeight) return null;
 		return { x: last.right + BAR_GAP, y: last.bottom + BAR_GAP, flipY: first.top };
 	}
 
-	// The id, not a synthesized chord: a host rebind moves the shortcut and leaves the button. A
-	// declined run means the bar's premise went stale under it, so the boolean hides the bar.
+	// The command id, not a made-up keystroke: a host rebind moves the shortcut and leaves the
+	// button. A refused run means what the bar assumed has changed, so the bar hides.
 	function fire(command: string, arg?: unknown): void {
 		turnIntoOpen = false;
 		if (!editor.runCommand(command, arg)) placement = null;
@@ -336,8 +331,8 @@
 {/if}
 
 <style>
-	/* Surface and rows are the shared `.md-menu` family (editor.css); only the marks row and the
-	   flyout hang are this popover's own. */
+	/* The panel and its rows are the shared `.md-menu` family (editor.css); only the marks row
+	   and where the flyout hangs are this popover's own. */
 	.selection-toolbar {
 		z-index: 100;
 		min-width: 0;
@@ -356,7 +351,7 @@
 		width: 34px;
 		height: 30px;
 		padding: 0;
-		color: var(--color-ui-muted, #8f8f89);
+		color: var(--color-ui-muted, #93938d);
 	}
 	.selection-toolbar-mark:hover:not(:disabled),
 	.selection-toolbar-mark[aria-pressed='true'] {

package/dist/components/menu/SelectionToolbar.svelte.d.ts

@@ -1,9 +1,7 @@
 /**
-     * The editor's own formatting popover over a selection, in Notion's shape: a row of the
-     * marks, then labelled rows for what acts on the selection as a whole. Built on the same
-     * doors a host's chrome would use (`selectionChange`, the rect API, the command door), so
-     * the consumer-guide recipe and this component cannot disagree about what a selection
-     * toolbar may read.
+     * The editor's own formatting popover over a selection: a row of marks, then labelled rows
+     * for what acts on the whole selection. Built only on the public API a host's toolbar would
+     * use (`selectionChange`, the rect API, `runCommand`), so the consumer-guide recipe matches it.
      */
 import type { EditorInstance } from '../../editor-props';
 type ToolbarEditor = Pick<EditorInstance, 'getSelection' | 'getRects' | 'getBlockKindAt' | 'runCommand' | 'canRunCommand' | 'isCommandActive' | 'getEvents'>;

package/dist/components/menu/clipboard-actions.d.ts

@@ -1,8 +1,7 @@
 /**
- * The clipboard rows a menu offers where Ctrl+X/C/V would go: cut and copy through the
- * document's own command (so the editor's copy handlers write what they always write), paste by
- * handing the clipboard's text to the focused surface as a paste event — the same road a real
- * Ctrl+V takes — either as it is, or escaped so Markdown syntax in it lands as literal text.
+ * The clipboard rows a menu offers: cut and copy through the document's own command, so the
+ * editor's copy handlers run as usual, and paste as a paste event on the focused editable,
+ * as is or escaped so Markdown syntax arrives as literal text.
  */
 export type ClipboardAction = 'cut' | 'copy' | 'paste' | 'paste-plain';
 /** Markdown-significant bytes, escaped so pasted text reads back exactly as pasted. */

package/dist/components/menu/clipboard-actions.js

@@ -1,8 +1,7 @@
 /**
- * The clipboard rows a menu offers where Ctrl+X/C/V would go: cut and copy through the
- * document's own command (so the editor's copy handlers write what they always write), paste by
- * handing the clipboard's text to the focused surface as a paste event — the same road a real
- * Ctrl+V takes — either as it is, or escaped so Markdown syntax in it lands as literal text.
+ * The clipboard rows a menu offers: cut and copy through the document's own command, so the
+ * editor's copy handlers run as usual, and paste as a paste event on the focused editable,
+ * as is or escaped so Markdown syntax arrives as literal text.
  */
 /** Markdown-significant bytes, escaped so pasted text reads back exactly as pasted. */
 export function escapeMarkdownLiteral(text) {

package/dist/components/menu/default-context-actions.d.ts

@@ -1,15 +1,6 @@
-/**
- * What every non-prose block's context menu offers after the kind's own rows: copy it (its
- * Markdown), replace it with the clipboard, remove it — each named for what the block is
- * ("Remove code block", "Copy image"). Plain, not red: every one is a Ctrl+Z away. Prose blocks
- * are the page's background and keep the browser's own menu (`Editor.svelte`).
- */
 import type { NodeView } from '../../core/node-views';
-/** The noun the menu uses for a block: a paragraph holding nothing but an image is "image". */
-export declare function blockNoun(node: NodeView): string;
-/** Prose is the page's background: it takes no block menu of its own. An image alone in a
- *  paragraph is a block, not prose. */
-export declare function isProseBackground(node: NodeView): boolean;
-/** Test-only. */
-export declare function __resetDefaultContextActionsForTests(): void;
+import type { InlineReading } from '../../core/inline/inline-cache';
+/** The noun the menu uses for a block: its kind's name mid-sentence, and "image" or "images"
+ *  for a paragraph holding nothing but images. */
+export declare function blockNoun(node: NodeView, reading: InlineReading): string;
 export declare function registerDefaultContextActions(): void;

package/dist/components/menu/default-context-actions.js

@@ -1,76 +1,58 @@
-import { EVERY_KIND, registerBlockContextActions } from '../../schema/context-actions';
-import { applyPasteTransforms } from '../../tree-operations/paste/paste-transforms';
-const KIND_NAMES = {
-    paragraph: 'paragraph',
-    heading: 'heading',
-    setextHeading: 'heading',
-    fencedCode: 'code block',
-    indentedCode: 'code block',
-    mathBlock: 'math block',
-    mathFence: 'math block',
-    table: 'table',
-    blockquote: 'quote',
-    list: 'list',
-    thematicBreak: 'divider',
-    html: 'HTML block',
-    linkReferenceDefinition: 'link definition'
-};
-const IMAGE_ONLY = /^\s*!\[[^\]]*\]\([^)]*\)\s*$/;
-const PROSE_KINDS = new Set(['paragraph', 'heading', 'setextHeading']);
-/** The noun the menu uses for a block: a paragraph holding nothing but an image is "image". */
-export function blockNoun(node) {
-    if (node.kind === 'paragraph' && IMAGE_ONLY.test(node.raw))
-        return 'image';
-    return KIND_NAMES[node.kind] ?? 'block';
-}
-/** Prose is the page's background: it takes no block menu of its own. An image alone in a
- *  paragraph is a block, not prose. */
-export function isProseBackground(node) {
-    return PROSE_KINDS.has(node.kind) && blockNoun(node) !== 'image';
+/**
+ * What every non-prose block's context menu offers after the kind's own rows: copy it (its
+ * Markdown), replace it with the clipboard, remove it, each named for what the block is
+ * ("Remove code block", "Copy image"). Plain, not red: every one is a Ctrl+Z away. Prose blocks
+ * are the page's background and take the clipboard rows instead (`editor-root-menus.ts`).
+ */
+import { blockKindLabel } from '../../a11y-strings';
+import { pictureImageCount } from '../../core/inline/picture';
+import { EVERY_KIND, registerBuiltinBlockContextActions } from '../../schema/context-actions';
+/** The noun the menu uses for a block: its kind's name mid-sentence, and "image" or "images"
+ *  for a paragraph holding nothing but images. */
+export function blockNoun(node, reading) {
+    const images = pictureImageCount(node, reading);
+    if (images > 0)
+        return images === 1 ? 'image' : 'images';
+    const label = blockKindLabel(node.kind);
+    // An initialism keeps its capitals: "HTML block", not "hTML block".
+    return /^.[A-Z]/.test(label) ? label : label.charAt(0).toLowerCase() + label.slice(1);
 }
 let registered = false;
-/** Test-only. */
-export function __resetDefaultContextActionsForTests() {
-    registered = false;
-}
 export function registerDefaultContextActions() {
     if (registered)
         return;
     registered = true;
-    registerBlockContextActions(EVERY_KIND, (node) => {
-        const noun = blockNoun(node);
-        return [
-            {
-                id: 'block.copy',
-                label: `Copy ${noun}`,
-                icon: 'copy',
-                run: () => navigator.clipboard.writeText(node.raw)
-            },
-            {
-                id: 'block.replace',
-                label: 'Replace with clipboard',
-                icon: 'clipboard',
-                run: async (ctx) => {
-                    let text;
-                    try {
-                        text = await navigator.clipboard.readText();
-                    }
-                    catch {
-                        return;
-                    }
-                    if (text.trim() === '')
-                        return;
-                    // The paste transforms first, as any paste gets, so a plugin's rewrite applies.
-                    const md = applyPasteTransforms(text);
-                    await ctx.replaceRaw(md.endsWith('\n') ? md : md + '\n');
+    registerBuiltinBlockContextActions(EVERY_KIND, 'block', (node, _path, noun) => [
+        {
+            id: 'block.copy',
+            label: `Copy ${noun}`,
+            icon: 'copy',
+            run: () => navigator.clipboard.writeText(node.raw)
+        },
+        {
+            id: 'block.replace',
+            label: 'Replace with clipboard',
+            icon: 'clipboard',
+            run: async (ctx) => {
+                let text;
+                try {
+                    text = await navigator.clipboard.readText();
+                }
+                catch {
+                    return;
                 }
-            },
-            {
-                id: 'block.remove',
-                label: `Remove ${noun}`,
-                icon: 'trash',
-                run: (ctx) => ctx.deleteBlock()
+                if (text.trim() === '')
+                    return;
+                // The paste transforms first, as any paste gets, so a plugin's rewrite applies.
+                const md = ctx.transformPaste(text);
+                await ctx.replaceRaw(md.endsWith('\n') ? md : md + '\n');
             }
-        ];
-    });
+        },
+        {
+            id: 'block.remove',
+            label: `Remove ${noun}`,
+            icon: 'trash',
+            run: (ctx) => ctx.deleteBlock()
+        }
+    ]);
 }

package/dist/components/menu/flyout-placement.d.ts

@@ -1,6 +1,6 @@
 /**
- * Svelte attachment for a menu flyout: measures the surface once it is in the DOM and moves it
- * to stay inside the viewport (`flyoutPlacement`). The element's own CSS hangs it off the row's
+ * Svelte attachment for a menu flyout: measures the panel once it is in the DOM and moves it to
+ * stay inside the viewport (`flyoutPlacement`). The element's own CSS hangs it off the row's
  * right edge; this writes the correction inline, so the rule lives in one place for every menu.
  */
 export declare function keepFlyoutOnScreen(node: HTMLElement): void;

package/dist/components/menu/flyout-placement.js

@@ -1,6 +1,6 @@
 /**
- * Svelte attachment for a menu flyout: measures the surface once it is in the DOM and moves it
- * to stay inside the viewport (`flyoutPlacement`). The element's own CSS hangs it off the row's
+ * Svelte attachment for a menu flyout: measures the panel once it is in the DOM and moves it to
+ * stay inside the viewport (`flyoutPlacement`). The element's own CSS hangs it off the row's
  * right edge; this writes the correction inline, so the rule lives in one place for every menu.
  */
 import { flyoutPlacement } from '../blocks/table/table-menu-model';

package/dist/components/menu/menu-presence.svelte.d.ts

@@ -0,0 +1,12 @@
+/**
+ * How many editor menus are showing, which is what `menuChange` reports. Every menu attaches
+ * `track` to its root element, so a menu reads open for exactly as long as it is mounted,
+ * whichever way it closes. A count, so two menus overlapping still read as one open.
+ */
+import type { Attachment } from 'svelte/attachments';
+export interface MenuPresence {
+    /** A getter, so a reader re-runs when a menu opens or closes. */
+    readonly isOpen: boolean;
+    track: Attachment;
+}
+export declare function createMenuPresence(): MenuPresence;

package/dist/components/menu/menu-presence.svelte.js

@@ -0,0 +1,19 @@
+/**
+ * How many editor menus are showing, which is what `menuChange` reports. Every menu attaches
+ * `track` to its root element, so a menu reads open for exactly as long as it is mounted,
+ * whichever way it closes. A count, so two menus overlapping still read as one open.
+ */
+import { untrack } from 'svelte';
+export function createMenuPresence() {
+    let open = $state(0);
+    return {
+        get isOpen() {
+            return open > 0;
+        },
+        track() {
+            // Untracked, or the attachment would depend on the count it writes and rerun forever.
+            untrack(() => open++);
+            return () => untrack(() => open--);
+        }
+    };
+}

package/dist/components/paste-image-arm.d.ts

@@ -1,15 +1,13 @@
 /**
- * The host image-import arm of a paste, shared by the editable-surface clipboard skeleton and the
- * editor-root fallback. It ends at "here is the markdown nobody claimed"; each caller owns what
- * happens next. Two ordering rules: files are read before the first await (`clipboardData` is not
- * dependably live afterwards), and a multi-block selection reaches the delete only after the hook
- * answers, so a failed import destroys nothing.
+ * Hands a paste's images to the host's import hook, for the blocks' clipboard code and the
+ * editor-root fallback alike. Files are read before the first await, since `clipboardData` may
+ * not stay live, and a multi-block selection is deleted only after the hook answers.
  */
 import type { PasteImageHook } from '../editor-keys';
 import { type EditorEvents } from '../editor-events';
 import type { CrossBlockHandlers } from '../selection/cross-block/dispatch';
 export interface ImagePasteArmDeps {
-    /** Undefined leaves an image-bearing paste on the text/plain path — `filesOf`
+    /** Undefined leaves a paste carrying images on the text/plain path: `filesOf`
      *  then reports none. */
     onPasteImage: PasteImageHook | undefined;
     /** A failed import reports here rather than vanishing. */
@@ -19,11 +17,8 @@ export interface ImagePasteArmDeps {
 export interface ImagePasteArm {
     /** Call before the handler's first await; empty when no hook is installed. */
     filesOf(data: DataTransfer | null): File[];
-    /**
-     * Import `files` in clipboard order, then offer the markdown to the cross-block
-     * seam. Null means the arm is finished (nothing imported, or a multi-block
-     * selection took the insertion); markdown means no selection claimed it.
-     */
+    /** Imports `files` in clipboard order and offers the markdown to the cross-block paste; null
+     *  when nothing is left to do, the markdown when no selection took it. */
     run(e: ClipboardEvent, files: File[]): Promise<string | null>;
 }
 export declare function createImagePasteArm(deps: ImagePasteArmDeps): ImagePasteArm;

package/dist/components/paste-image-arm.js

@@ -1,9 +1,7 @@
 /**
- * The host image-import arm of a paste, shared by the editable-surface clipboard skeleton and the
- * editor-root fallback. It ends at "here is the markdown nobody claimed"; each caller owns what
- * happens next. Two ordering rules: files are read before the first await (`clipboardData` is not
- * dependably live afterwards), and a multi-block selection reaches the delete only after the hook
- * answers, so a failed import destroys nothing.
+ * Hands a paste's images to the host's import hook, for the blocks' clipboard code and the
+ * editor-root fallback alike. Files are read before the first await, since `clipboardData` may
+ * not stay live, and a multi-block selection is deleted only after the hook answers.
  */
 import { emitClipboardError } from '../editor-events';
 export function createImagePasteArm(deps) {
@@ -14,13 +12,12 @@ export function createImagePasteArm(deps) {
             if (!importImage)
                 return null;
             const markdown = await importAll(deps, importImage, files);
-            // Empty markdown ends the arm like no markdown, and keeps the seam's payload
-            // below non-empty.
+            // Empty markdown ends this the same way no markdown does, and keeps the
+            // cross-block paste from being handed an empty string.
             if (!markdown)
                 return null;
-            // Inherit the ordinary paste route rather than placing anything here: the
-            // delete collapses start-wins and the receiving block may be merged away. The
-            // seam reads `isCrossBlock` LIVE, so a mid-import selection is the one replaced.
+            // The ordinary paste route, which reads `isCrossBlock` live, since the delete can
+            // collapse or merge away the receiving block.
             if (await deps.crossBlock.handlePaste(e, markdown))
                 return null;
             return markdown;
@@ -33,11 +30,8 @@ export function createImagePasteArm(deps) {
 function imageFilesOf(data) {
     return Array.from(data?.files ?? []).filter((file) => file.type.startsWith('image/'));
 }
-/**
- * One insertion, not one per image: a hook may return multi-line markdown, whose
- * structural paste can split the block out from under a second insertion addressed at
- * anchor + length — and one paste gesture owes the user one undo entry.
- */
+/** One insertion for every image: multi-line markdown can split the block out from under a
+ *  second insertion, and one paste is one undo entry. */
 async function importAll(deps, importImage, files) {
     const markdown = [];
     for (const image of files) {
@@ -51,9 +45,8 @@ async function importAll(deps, importImage, files) {
                 markdown.push(inserted);
         }
         catch (error) {
-            // One failed import skips its image; the rest of the paste still lands. Still
-            // a clipboard failure, not a command throw: the host needs to know an asset
-            // it started importing will not appear in the document.
+            // A failed import skips its image and reports a clipboard error, so the host knows
+            // that asset will not appear.
             emitClipboardError(deps.events, { error });
         }
     }

package/dist/components/portal.d.ts

@@ -3,9 +3,6 @@
  * instance: the node keeps its identity, its Svelte scope classes and its place in the
  * reactive tree, so only its position in the DOM moves.
  */
-/**
- * Attachment factory: appends the node to `target`, and puts it back where it was when the
- * target changes or the attachment tears down. A null target leaves the node home, which is
- * how the seam stays absent by default.
- */
+/** Appends the node to `target` and puts it back when the target changes or the attachment
+ *  tears down; a null target leaves the node where it is. */
 export declare function portalInto(target: HTMLElement | null | undefined): (node: HTMLElement) => (() => void) | void;

package/dist/components/portal.js

@@ -3,17 +3,14 @@
  * instance: the node keeps its identity, its Svelte scope classes and its place in the
  * reactive tree, so only its position in the DOM moves.
  */
-/**
- * Attachment factory: appends the node to `target`, and puts it back where it was when the
- * target changes or the attachment tears down. A null target leaves the node home, which is
- * how the seam stays absent by default.
- */
+/** Appends the node to `target` and puts it back when the target changes or the attachment
+ *  tears down; a null target leaves the node where it is. */
 export function portalInto(target) {
     return (node) => {
         if (!target)
             return;
-        // A marker holds the home position: the siblings around it can change while the node
-        // is away, so a captured `nextSibling` would insert against a stale reference.
+        // A comment marks where the node came from: the siblings around it can change while
+        // the node is away, so a captured `nextSibling` would be a stale reference.
         const marker = node.ownerDocument.createComment('');
         node.parentNode?.insertBefore(marker, node);
         target.appendChild(node);

package/dist/core/directive/activate.d.ts

@@ -1,8 +1,7 @@
 /**
- * Grammar-side activation for the `:::name` directive primitive. No components: core must not
- * reach the component tree, so the public `activateDirectives` layers render on top of this.
- * Call-based, not a module-load side effect, so a consumer that never calls it leaves `:::` and
- * `:` unclaimed. Must run before the editor parses, ahead of the grammar-consumed latch (G1.17).
- * A second activation site is a no-op: every step guards on something the tier itself owns.
+ * Grammar-side activation for the `:::name` directive syntax. The public `activateDirectives`
+ * adds the components (core can't import them) and makes both belong to no plugin. A call, not an
+ * import side effect, so `:::` and `:` stay free until someone asks. Must run before the editor
+ * first parses (G1.17); calling it twice is a no-op, since every step checks its registration first.
  */
 export declare function activateDirectiveGrammar(): void;

package/dist/core/directive/activate.js

@@ -1,25 +1,24 @@
 /**
- * Grammar-side activation for the `:::name` directive primitive. No components: core must not
- * reach the component tree, so the public `activateDirectives` layers render on top of this.
- * Call-based, not a module-load side effect, so a consumer that never calls it leaves `:::` and
- * `:` unclaimed. Must run before the editor parses, ahead of the grammar-consumed latch (G1.17).
- * A second activation site is a no-op: every step guards on something the tier itself owns.
+ * Grammar-side activation for the `:::name` directive syntax. The public `activateDirectives`
+ * adds the components (core can't import them) and makes both belong to no plugin. A call, not an
+ * import side effect, so `:::` and `:` stay free until someone asks. Must run before the editor
+ * first parses (G1.17); calling it twice is a no-op, since every step checks its registration first.
  */
 import { registerDirectiveKinds, registerDirectiveTextKind, DIRECTIVE_TEXT } from './kinds';
 import { registerDirectiveOpeners } from './container-opener';
 import { declaredPluginInlineKind, isInlineKindDeclared } from '../../schema/plugin-kind';
 import { registerInlineSyntax } from '../inline/scan/plugin-syntax';
 import { recognizeTextDirective } from './text-recognizer';
+import { defaultGrammarView } from '../../schema/block-openers';
 export function activateDirectiveGrammar() {
-    // The inline rung has nothing of its own to probe, so it borrows the `directiveText` latch,
-    // read HERE before `registerDirectiveTextKind` sets it. It cannot ask whether `:` is taken:
-    // the trigger is SHARED (emoji rungs on it too), so that question answers for another plugin.
+    // The inline handler has no registration of its own to check, so it borrows the
+    // `directiveText` flag, read before it is set; the `:` trigger is shared with emoji.
     const alreadyActive = isInlineKindDeclared(DIRECTIVE_TEXT);
     registerDirectiveKinds();
     registerDirectiveOpeners();
     registerDirectiveTextKind();
     if (!alreadyActive) {
         const kind = declaredPluginInlineKind(DIRECTIVE_TEXT);
-        registerInlineSyntax(':', (raw, pos, end) => recognizeTextDirective(raw, pos, end, kind));
+        registerInlineSyntax(':', (raw, pos, end, grammar) => recognizeTextDirective(raw, pos, end, kind, grammar ?? defaultGrammarView));
     }
 }