@voithos-labs/aragonite 0.10.1

package/dist/components/blocks/code/code-renderer.js

@@ -0,0 +1,249 @@
+/**
+ * Code-block renderer. Produces a DocumentFragment with dimmed marker spans
+ * for fences and tokenized spans for the body. Invariant (G1.28):
+ *   fragment.textContent === trimTrailingLineEnding(node.raw)
+ */
+import { metadataOf } from '../../../core/nodes';
+import { trimTrailingLineEnding } from '../../../core/lines';
+import { devWarn } from '../../../dev-warn';
+import { assertInvariant } from '../../../assert';
+import { checkRenderedTextFidelity } from '../../../invariants/render-fidelity';
+import hljs from 'highlight.js/lib/core';
+import { getLanguageGrammar } from './code-languages';
+export function sliceFencedCode(node) {
+    const meta = metadataOf(node, 'fencedCode');
+    const raw = node.raw;
+    const firstNewline = raw.indexOf('\n');
+    if (firstNewline === -1) {
+        return { openerLine: raw, body: '', closerLine: '', infoString: meta.info ?? '' };
+    }
+    const openerLine = raw.slice(0, firstNewline + 1);
+    if (!meta.closed) {
+        return {
+            openerLine,
+            body: raw.slice(openerLine.length),
+            closerLine: '',
+            infoString: meta.info ?? ''
+        };
+    }
+    const closerStart = findClosingFenceStart(raw, openerLine.length, meta.fenceMarker, meta.fenceLength);
+    return {
+        openerLine,
+        body: raw.slice(openerLine.length, closerStart),
+        closerLine: raw.slice(closerStart),
+        infoString: meta.info ?? ''
+    };
+}
+// ── hljs class → code-tok class mapping ───────────────────────────────────
+const HLJS_CLASS_MAP = {
+    'hljs-keyword': 'code-tok-keyword',
+    'hljs-string': 'code-tok-string',
+    'hljs-number': 'code-tok-number',
+    'hljs-comment': 'code-tok-comment',
+    'hljs-doctag': 'code-tok-comment',
+    'hljs-quote': 'code-tok-comment',
+    'hljs-type': 'code-tok-type',
+    'hljs-class': 'code-tok-type',
+    'hljs-name': 'code-tok-type',
+    'hljs-selector-tag': 'code-tok-type',
+    'hljs-built_in': 'code-tok-function',
+    'hljs-function': 'code-tok-function',
+    'hljs-title': 'code-tok-function',
+    'hljs-variable': 'code-tok-variable',
+    'hljs-params': 'code-tok-variable',
+    'hljs-template-variable': 'code-tok-variable',
+    'hljs-operator': 'code-tok-operator',
+    'hljs-punctuation': 'code-tok-punctuation',
+    'hljs-tag': 'code-tok-punctuation',
+    'hljs-bullet': 'code-tok-punctuation',
+    'hljs-meta': 'code-tok-meta',
+    'hljs-template-tag': 'code-tok-meta',
+    'hljs-literal': 'code-tok-literal',
+    'hljs-attr': 'code-tok-attr',
+    'hljs-attribute': 'code-tok-attr',
+    'hljs-selector-id': 'code-tok-attr',
+    'hljs-selector-class': 'code-tok-attr',
+    'hljs-selector-pseudo': 'code-tok-attr',
+    'hljs-addition': 'code-tok-added',
+    'hljs-deletion': 'code-tok-removed',
+    'hljs-section': 'code-tok-heading',
+    'hljs-link': 'code-tok-link',
+    'hljs-regexp': 'code-tok-regexp',
+    'hljs-symbol': 'code-tok-symbol',
+    'hljs-subst': 'code-tok-subst'
+};
+export function mapHljsClass(hljsClass) {
+    const first = hljsClass.split(/\s+/)[0];
+    return HLJS_CLASS_MAP[first] ?? 'code-tok-unknown';
+}
+// ── hljs output walker ────────────────────────────────────────────────────
+export function walkHljsNodes(source, target) {
+    for (const child of source.childNodes) {
+        if (child.nodeType === Node.TEXT_NODE) {
+            target.appendChild(document.createTextNode(child.textContent ?? ''));
+        }
+        else if (child.nodeType === Node.ELEMENT_NODE) {
+            const el = child;
+            const span = document.createElement('span');
+            span.className = mapHljsClass(el.className);
+            walkHljsNodes(el, span);
+            target.appendChild(span);
+        }
+    }
+}
+// ── Body tokenization ─────────────────────────────────────────────────────
+const registeredWithHljs = new Set();
+/** `ignoreIllegals` is set so mid-typing invalid syntax doesn't throw. */
+export function tokenizeBody(body, infoString) {
+    const frag = document.createDocumentFragment();
+    if (body.length === 0)
+        return frag;
+    const grammar = getLanguageGrammar(infoString);
+    if (!grammar) {
+        frag.appendChild(document.createTextNode(body));
+        return frag;
+    }
+    if (!registeredWithHljs.has(grammar.name)) {
+        hljs.registerLanguage(grammar.name, grammar.definition);
+        registeredWithHljs.add(grammar.name);
+    }
+    // `template.innerHTML` normalizes every `\r\n`/`\r` to `\n`, so a CRLF body is
+    // highlighted as pure LF and its endings restored positionally afterward.
+    const hasCarriageReturn = body.includes('\r');
+    const highlightSource = hasCarriageReturn ? body.replace(/\r\n|\r/g, '\n') : body;
+    const result = hljs.highlight(highlightSource, {
+        language: grammar.name,
+        ignoreIllegals: true
+    });
+    const template = document.createElement('template');
+    template.innerHTML = result.value;
+    walkHljsNodes(template.content, frag);
+    if (hasCarriageReturn)
+        restoreLineEndings(frag, body);
+    return frag;
+}
+// An in-order text-node walk rewrites the k-th `\n` back to the k-th original ending.
+// Counts match by construction: every `\r` was stripped before highlighting, so neither
+// hljs nor the HTML parser adds or drops a newline.
+function restoreLineEndings(root, originalBody) {
+    const endings = originalBody.match(/\r\n|\r|\n/g);
+    if (!endings)
+        return;
+    let next = 0;
+    const restore = (node) => {
+        for (const child of node.childNodes) {
+            if (child.nodeType === Node.TEXT_NODE) {
+                const text = child.textContent ?? '';
+                if (text.includes('\n')) {
+                    child.textContent = text.replace(/\n/g, () => endings[next++]);
+                }
+            }
+            else {
+                restore(child);
+            }
+        }
+    };
+    restore(root);
+    // A count mismatch would silently write `undefined` into committed bytes downstream,
+    // so make an hljs-faithfulness regression loud at this seam instead.
+    if (next !== endings.length) {
+        devWarn('code-renderer', `restoreLineEndings count mismatch: ${next} fragment newlines vs ${endings.length} source endings`);
+    }
+}
+// ── Fence marker rendering ────────────────────────────────────────────────
+function makeMarkerSpan(text, extraClass) {
+    const span = document.createElement('span');
+    span.className = extraClass ? `md-marker ${extraClass}` : 'md-marker';
+    span.textContent = text;
+    return span;
+}
+// A fence line's newline is a bare text node CSS cannot reach; wrapping the whole line
+// lets reading/preview modes collapse it with `display: none`. Layout-neutral in source
+// mode — an inline span under `white-space: pre` still breaks on its inner `\n`.
+function makeFenceLine(parts) {
+    const line = document.createElement('span');
+    line.className = 'md-fence-line';
+    for (const part of parts)
+        line.appendChild(part);
+    return line;
+}
+function renderOpenerLine(slice, fenceMarker, fenceLength) {
+    const frag = document.createDocumentFragment();
+    if (slice.openerLine.length === 0)
+        return frag;
+    const fenceChars = fenceMarker.repeat(fenceLength);
+    const openerWithoutNewline = slice.openerLine.replace(/\n$/, '');
+    const hasTrailingNewline = slice.openerLine.endsWith('\n');
+    // The fence may sit behind 0–3 spaces of indent; carry it inside the fence-marker
+    // span so textContent keeps every opener byte.
+    const indent = openerWithoutNewline.match(/^ {0,3}/)[0];
+    const parts = [makeMarkerSpan(indent + fenceChars, 'md-fence')];
+    const afterFence = openerWithoutNewline.slice(indent.length + fenceChars.length);
+    if (afterFence.length > 0) {
+        parts.push(makeMarkerSpan(afterFence, 'md-lang'));
+    }
+    if (hasTrailingNewline) {
+        parts.push(document.createTextNode('\n'));
+    }
+    frag.appendChild(makeFenceLine(parts));
+    return frag;
+}
+function renderCloserLine(slice, leadingNewline) {
+    const frag = document.createDocumentFragment();
+    if (slice.closerLine.length === 0)
+        return frag;
+    const parts = [];
+    // The line break before the closer belongs to the closer's fence line, not the
+    // body's last code line; owning it here lets the wrapper hide both together.
+    if (leadingNewline)
+        parts.push(document.createTextNode('\n'));
+    parts.push(makeMarkerSpan(slice.closerLine, 'md-fence'));
+    frag.appendChild(makeFenceLine(parts));
+    return frag;
+}
+// ── Top-level render ─────────────────────────────────────────────────────
+export function renderCodeBlock(node) {
+    const slice = trimSliceTail(sliceFencedCode(node));
+    const meta = metadataOf(node, 'fencedCode');
+    const frag = document.createDocumentFragment();
+    // The newline before the closer is re-homed onto the closer's fence line, so
+    // reading/preview collapse the bottom blank line with it. An all-blank body is the
+    // exception: stealing its terminating `\n` would drop a visible line.
+    const hasCloser = slice.closerLine.length > 0;
+    // `/\S/` deliberately conflates a whitespace-only body (spaces/tabs, no content
+    // line) with a truly-blank one: both keep their separator and render like blanks.
+    const bodyHasContentLine = /\S/.test(slice.body);
+    const separatorNewline = hasCloser && slice.body.endsWith('\n') && bodyHasContentLine;
+    const bodyText = separatorNewline ? slice.body.slice(0, -1) : slice.body;
+    frag.appendChild(renderOpenerLine(slice, meta.fenceMarker, meta.fenceLength));
+    frag.appendChild(tokenizeBody(bodyText, slice.infoString));
+    frag.appendChild(renderCloserLine(slice, separatorNewline));
+    assertInvariant('rendered-text-fidelity', () => checkRenderedTextFidelity(frag.textContent ?? '', trimTrailingLineEnding(node.raw)));
+    return frag;
+}
+// ── Internal ─────────────────────────────────────────────────────────────────
+// The block's trailing line ending never enters the fragments: strip it from whichever
+// slice piece carries the tail, so G1.28 holds by construction — CRLF included.
+function trimSliceTail(slice) {
+    if (slice.closerLine.length > 0)
+        return { ...slice, closerLine: trimTrailingLineEnding(slice.closerLine) };
+    if (slice.body.length > 0)
+        return { ...slice, body: trimTrailingLineEnding(slice.body) };
+    return { ...slice, openerLine: trimTrailingLineEnding(slice.openerLine) };
+}
+function findClosingFenceStart(raw, searchStart, fenceMarker, fenceLength) {
+    const fencePattern = new RegExp(`^ {0,3}${fenceMarker}{${fenceLength},}\\s*$`);
+    let lineEnd = raw.length;
+    while (lineEnd > searchStart) {
+        const lineStart = raw.lastIndexOf('\n', lineEnd - 2) + 1;
+        if (lineStart < searchStart)
+            break;
+        const line = raw.slice(lineStart, lineEnd).replace(/\n$/, '');
+        if (fencePattern.test(line)) {
+            return lineStart;
+        }
+        lineEnd = lineStart;
+    }
+    // Unreachable when the parser's `closed` flag is consistent with raw.
+    return raw.length;
+}

package/dist/components/blocks/directive/DirectiveContainerBlock.svelte

@@ -0,0 +1,51 @@
+<script lang="ts">
+	// The generic render surface for an unregistered `:::name` directive, built on the
+	// same `createContainerBlock` seam a plugin reaches through the barrel. Chrome stays a
+	// dimmed marker over a gutter rail, not a card box — a document should feel like a document.
+	import { createContainerBlock } from '../../../editor-actions/plugin/container';
+	import BlockList from '../../BlockList.svelte';
+	import type { NodeView } from '../../../core/node-views';
+
+	let { node, index, myPath = [] }: { node: NodeView; index: number; myPath?: number[] } = $props();
+
+	let boxEl: HTMLElement | undefined = $state();
+
+	// The opener line sliced verbatim, not rebuilt from metadata: the line can also
+	// carry an indent, attributes, or trailing spaces the metadata does not hold.
+	const marker = $derived.by(() => {
+		const end = node.raw.indexOf('\n');
+		const line = end === -1 ? node.raw : node.raw.slice(0, end);
+		return line.endsWith('\r') ? line.slice(0, -1) : line;
+	});
+
+	const { blockListProps, containerApi, handleKeydown } = createContainerBlock({
+		getNode: () => node,
+		getIndex: () => index,
+		getPath: () => myPath,
+		getBoxEl: () => boxEl
+	});
+
+	export { containerApi };
+</script>
+
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<div class="directive-block" bind:this={boxEl} onkeydown={handleKeydown}>
+	<span class="directive-marker" contenteditable="false">{marker}</span>
+	<BlockList {...blockListProps} />
+</div>
+
+<style>
+	.directive-block {
+		border-left: 2px solid var(--color-ui-muted, #a4a4a4);
+		padding-left: 0.75em;
+		margin: 6px 0;
+	}
+	.directive-marker {
+		display: block;
+		font-family: var(--font-editor, ui-monospace, monospace);
+		opacity: var(--syntax-marker-dim, 0.65);
+		user-select: none;
+		-webkit-user-select: none;
+		cursor: default;
+	}
+</style>

package/dist/components/blocks/directive/DirectiveContainerBlock.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { NodeView } from '../../../core/node-views';
+type $$ComponentProps = {
+    node: NodeView;
+    index: number;
+    myPath?: number[];
+};
+declare const DirectiveContainerBlock: import("svelte").Component<$$ComponentProps, {
+    containerApi: import("../../../editor-actions/plugin/container").ContainerBlockComponent;
+}, "">;
+type DirectiveContainerBlock = ReturnType<typeof DirectiveContainerBlock>;
+export default DirectiveContainerBlock;

package/dist/components/blocks/directive/activate-directives.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The public activation entry for the `:::name` directive primitive, on the `@voithos-labs/aragonite/plugin`
+ * barrel: grammar plus the generic container and leaf render. A pure-GFM consumer that never calls
+ * it leaves `:::` unclaimed. Lives in `components/` because it binds Svelte components, which core
+ * must not reach. Every registration guards its public probe, so repeat calls are safe.
+ */
+export declare function activateDirectives(): void;

package/dist/components/blocks/directive/activate-directives.js

@@ -0,0 +1,23 @@
+/**
+ * The public activation entry for the `:::name` directive primitive, on the `@voithos-labs/aragonite/plugin`
+ * barrel: grammar plus the generic container and leaf render. A pure-GFM consumer that never calls
+ * it leaves `:::` unclaimed. Lives in `components/` because it binds Svelte components, which core
+ * must not reach. Every registration guards its public probe, so repeat calls are safe.
+ */
+import { activateDirectiveGrammar } from '../../../core/directive/activate';
+import { registerBlockComponent, defineBlockComponent, isBlockComponentRegistered } from '../../../schema/block-component-registry';
+import { declaredPluginKind } from '../../../schema/plugin-kind';
+import { DIRECTIVE_CONTAINER, DIRECTIVE_LEAF } from '../../../core/directive/kinds';
+import DirectiveContainerBlock from './DirectiveContainerBlock.svelte';
+import TextEditableBlock from '../text/TextEditableBlock.svelte';
+export function activateDirectives() {
+    activateDirectiveGrammar();
+    if (!isBlockComponentRegistered(DIRECTIVE_CONTAINER)) {
+        registerBlockComponent(declaredPluginKind(DIRECTIVE_CONTAINER), defineBlockComponent(DirectiveContainerBlock));
+    }
+    // The leaf's descriptor already drives its dimmed marker and split behavior, so it
+    // reuses the built-in text surface directly.
+    if (!isBlockComponentRegistered(DIRECTIVE_LEAF)) {
+        registerBlockComponent(declaredPluginKind(DIRECTIVE_LEAF), defineBlockComponent(TextEditableBlock, () => ({ blockClass: 'directive-leaf' })));
+    }
+}

package/dist/components/blocks/editable-leaf.d.ts

@@ -0,0 +1,126 @@
+/**
+ * The editable-leaf seam a plugin block component builds on: a text-editing block surface with
+ * native caret/IME/undo/cross-block-selection parity, in one factory so a plugin never touches an
+ * editor context key. Two modes: `plain` commits per keystroke, `render-primary` reveals its
+ * source and commits on blur. Call synchronously during init. Contract: plugin-guide § The
+ * editable leaf.
+ */
+import type { BlockEditActions } from '../../action-contracts';
+import type { StickyColumnDirection } from '../../block-component';
+import type { NodeView } from '../../core/node-views';
+import { type PluginEditorLookup } from '../../editor-keys';
+import type { PresentationMode } from '../../presentation-mode';
+import { type CommandId } from '../../schema/commands';
+import { type BlockCommandContext } from '../../schema/block-commands';
+export type EditableLeafMode = 'plain' | 'render-primary';
+/**
+ * The frozen inputs the host component feeds in. A function-valued field is a **live
+ * read**, re-evaluated on every use, so a structural op or undo replacement is observed
+ * rather than snapshotted; `mode` and `singleLine` are static configuration captured at the
+ * factory call.
+ */
+export interface EditableLeafDeps {
+    getNode(): NodeView;
+    getIndex(): number;
+    getPath(): number[];
+    /** The source contenteditable; null while unmounted (render-primary's rendered view). */
+    getEl(): HTMLElement | null;
+    mode?: EditableLeafMode;
+    /** A kind whose bytes are one line: Enter splits the block rather than typing a newline. */
+    singleLine?: boolean;
+    /** render-primary only: the component owns the swap flag and both views. */
+    isRevealed?(): boolean;
+    setRevealed?(revealed: boolean): void;
+    /**
+     * The mounted component's view-state hooks, handed to a minted block command as
+     * `ctx.hooks`. Read live at dispatch: return a getter, never a captured value. The
+     * platform treats it as `unknown`; the plugin casts it.
+     */
+    commandHooks?: () => unknown;
+}
+/**
+ * The one-spread source surface: `<div {...leaf.surfaceProps}>` wires every handler and attribute
+ * a source contenteditable needs, so a consumer cannot drop one (a forgotten `oncompositionend`
+ * breaks IME silently). Symbol-keyed attachments carry the view-lifecycle contracts: a SINGLE text
+ * node, so the ambient offset walk stays exact, and the focus-park on unmount.
+ */
+export interface EditableLeafSurfaceProps {
+    tabindex: number;
+    /** Reading mode makes a plain leaf's always-mounted source inert. */
+    contenteditable: 'true' | 'false';
+    role: 'textbox';
+    spellcheck: 'false';
+    oninput: () => void;
+    onkeydown: (e: KeyboardEvent) => void | Promise<void>;
+    oncopy: (e: ClipboardEvent) => void;
+    oncut: (e: ClipboardEvent) => Promise<void>;
+    onpaste: (e: ClipboardEvent) => Promise<void>;
+    onpointerdown: (e: PointerEvent) => void;
+    onfocusout: () => void;
+    oncompositionstart: () => void;
+    oncompositionend: () => void;
+    /** View-sync + focus-park ride Svelte attachments under symbol keys. */
+    [attachment: symbol]: unknown;
+}
+/**
+ * The one-spread rendered surface: `<div {...leaf.renderProps}>` on a render-primary block's
+ * FOLDED view. One bundle rather than a handler apiece, because a rendered view wired for the
+ * reveal click alone swallows every chord while it holds focus — undo included. Both entries
+ * stand down while the source is up, so the spread may sit on a wrapper the fold keeps.
+ */
+export interface EditableLeafRenderProps {
+    /** Reveal-on-click (shift-click extends a selection instead). */
+    onpointerdown: (e: PointerEvent) => void;
+    /** Chord dispatch at this block's kind: the global tier, then its own commands. */
+    onkeydown: (e: KeyboardEvent) => void;
+}
+export interface EditableLeaf {
+    /** The block's source minus its trailing line ending — the editable text. */
+    readonly sourceText: string;
+    /** The one-spread source surface (attributes + handlers + view/park attachments). */
+    surfaceProps: EditableLeafSurfaceProps;
+    /** render-primary: the one-spread folded surface. */
+    renderProps: EditableLeafRenderProps;
+    /**
+     * The live EFFECTIVE presentation mode. The factory already gates itself in
+     * 'reading' (no reveal, no commits); a plain-mode component additionally binds
+     * `contenteditable` off this so its always-mounted source goes structurally inert.
+     */
+    getPresentationMode(): PresentationMode;
+    /**
+     * The live editor theme name (`data-editor-theme`), for a leaf whose rendered half
+     * comes from an engine emitting its own colors rather than from CSS.
+     */
+    getTheme(): string;
+    /**
+     * This editor instance's options for the plugin owning this block's kind — the
+     * `{ plugin, options }` entry's channel, so two editors in one process configure the
+     * same kind differently. `unknown`, like `commandHooks`: the plugin narrows it.
+     */
+    getOptions(): unknown;
+    focus(offset: number): void;
+    parkCaret(offset: number): void;
+    focusAtColumn(x: number, from: StickyColumnDirection): void;
+    getCursorOffset(): number | null;
+    getSelectedText(): string;
+    setSelection(start: number, end: number): void;
+    measurePartialRects(startOffset: number, endOffset: number): DOMRect[];
+    runCommand(id: CommandId): boolean;
+    /** Insert markdown at the caret exactly as pasting it here would, minus the clipboard —
+     *  publish it as the component's `insertMarkdown` so `editor.insertMarkdown()` reaches
+     *  this leaf. True means the paste pipeline took the text, not that its commit flushed. */
+    insertMarkdown(md: string): boolean;
+    /** Mount/focus the source with the caret at `offset` (plain mode: focus only). */
+    reveal(offset?: number): Promise<void>;
+    /** Commit edited source as one undo entry, fire and forget; the parse decides update / kind
+     *  change / structural split. */
+    commitSource(edited: string): void;
+}
+/**
+ * The node → metadata bridge (plus `commandHooks`) a minted block command resolves
+ * against on the leaf tier — the container factory's `buildContainerKindTarget` sibling.
+ * Every field reads through `deps`' thunks at dispatch, so a node swap or hook rebind is
+ * observed live; `pluginEditor` resolves by the kind's recorded owner.
+ */
+export declare function buildLeafCommandContext(deps: Pick<EditableLeafDeps, 'getNode' | 'getIndex' | 'commandHooks'>, blockEdit: Pick<BlockEditActions, 'updateBlockMetadata'>, pluginEditor?: PluginEditorLookup): Omit<BlockCommandContext, 'arg'>;
+export declare function createEditableLeaf(deps: EditableLeafDeps): EditableLeaf;