@voithos-labs/aragonite 0.10.1

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

@@ -0,0 +1,97 @@
+/**
+ * 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 { ADMONITION, ADMONITION_KINDS, ADMONITION_TITLE, coerceAdmonitionName } from './kinds';
+import { githubAlertsPasteTransform } from './convert-document';
+import { registerGithubAlert } from './github-alert-kind';
+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 node = {
+            kind,
+            leadingTrivia: parsed.leadingTrivia,
+            raw: parsed.raw,
+            innerPrefix: parsed.body?.prefix ?? '',
+            children: [chromeChild(titleKind, title), ...(parsed.body?.children ?? [])],
+            innerSuffix: parsed.body?.suffix ?? ''
+        };
+        setPluginMetadata(node, {
+            name: parsed.fence.name,
+            colonCount: parsed.fence.colonCount,
+            closerColonCount: parsed.closerColonCount,
+            closerNewline: parsed.closerNewline,
+            lineEnding: parsed.lineEnding
+        });
+        return node;
+    };
+}
+const rebuildAdmonitionRaw = createDirectiveRebuild((meta) => coerceAdmonitionName(meta?.name));
+export function registerAdmonitions(options) {
+    activateDirectives(); // idempotent; the shared grammar must be live before the first parse
+    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.
+    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.
+    const cycleKind = registerBlockCommand(admonition, 'admonition.cycleKind', (ctx) => {
+        const meta = getPluginMetadata(ctx.node);
+        const dir = ctx.arg === 'prev' ? -1 : 1;
+        const from = ADMONITION_KINDS.indexOf(coerceAdmonitionName(meta?.name));
+        const next = ADMONITION_KINDS[(from + dir + ADMONITION_KINDS.length) % ADMONITION_KINDS.length];
+        ctx.updateMetadata({ name: next });
+        return true;
+    });
+    registerBlockKind(admonition, {
+        mergeRole: 'container',
+        editable: true,
+        supportsInline: false,
+        // Opaque tier rule: no textual escape hatch at either edge, so both take the gap caret.
+        gapEdges: 'both',
+        container: {
+            // The title lives in the opener line, so raw is not a strip of the children.
+            contract: 'opaque',
+            rebuildRaw: rebuildAdmonitionRaw,
+            bodyWrap: DIRECTIVE_BODY_WRAP,
+            reservedChrome: { kind: title },
+            unwrapRole: {
+                firstChildBackspace: 'keep-reserved-chrome',
+                middleChildBackspace: 'default-merge'
+            }
+        },
+        keymap: [{ chord: 'Mod+7', command: cycleKind }],
+        conformanceFixture: ':::note Heads up\n\nbody\n\n:::\n',
+        closure: containerClosure({
+            roundTripVia: 'container contract=opaque — rebuildAdmonitionRaw (directive)',
+            focus: { mode: 'implemented', via: 'focus walks to the title chrome / first body child' },
+            mergeBackspace: { mode: 'implemented', via: 'mergeRole=container + unwrapRole' },
+            undo: {
+                mode: 'implemented',
+                via: 'updateMetadata — the kind cycle commits as one undoable metadataUpdate'
+            },
+            clipboard: {
+                mode: 'implemented',
+                via: 'byte-slice copy; a slice touching the title re-emits the callout — a mid-title start reopens it around the collected body, a mid-title end yields a title-only callout'
+            },
+            simOracle: {
+                mode: 'implemented',
+                via: 'admonition + paste-transform e2e under the [invariant:] watcher'
+            }
+        })
+    });
+    registerChromeLeaf(title, { blockClass: 'admonition-title' });
+    registerBlockComponent(admonition, defineBlockComponent(AdmonitionBlock));
+    if (options?.convertAlertsOnPaste) {
+        registerPasteTransform(githubAlertsPasteTransform);
+    }
+    // The component registered above renders both kinds.
+    registerGithubAlert();
+}

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

@@ -0,0 +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.
+ */
+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. */
+export declare const githubAlertsPasteTransform: PasteTransform;

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

@@ -0,0 +1,39 @@
+/**
+ * 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.
+ */
+import { parse } from '../../plugin';
+import { convertAlertBlockquoteRaw, hasGithubAlert } from './gh-alert';
+export function convertGithubAlertsInDocument(source) {
+    const doc = parse(source, { scope: 'document' });
+    let changed = false;
+    const parts = [doc.prefix];
+    for (const child of doc.children) {
+        parts.push(child.leadingTrivia);
+        // 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;
+        if (converted !== null) {
+            parts.push(converted);
+            changed = true;
+        }
+        else {
+            parts.push(child.raw);
+        }
+    }
+    parts.push(doc.suffix);
+    return { converted: parts.join(''), changed };
+}
+/** The line probe short-circuits the common no-alert paste before the parse. */
+export const githubAlertsPasteTransform = {
+    name: 'admonitions.github-alerts',
+    transform(text) {
+        if (!hasGithubAlert(text))
+            return null;
+        const { converted, changed } = convertGithubAlertsInDocument(text);
+        return changed ? converted : null;
+    }
+};

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

@@ -0,0 +1,13 @@
+/** 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;
+export declare function stripQuoteMarker(line: string): string;
+export interface AlertConversion {
+    converted: string;
+    changed: boolean;
+}
+/** 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 convertGithubAlerts(text: string): AlertConversion;
+export declare function hasGithubAlert(text: string): boolean;

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

@@ -0,0 +1,83 @@
+/**
+ * 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.
+ */
+import { blockquoteExtent, escalatedColonCount, 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. */
+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
+ *  survives a rebuild. */
+export function matchAlertMarker(line) {
+    const typed = MARKER.exec(line)?.[1];
+    return typed && ALERT_NAMES.has(typed.toLowerCase()) ? typed : null;
+}
+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';
+    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 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++)
+        out += body[i].text + (body[i].lineEnding || fallback);
+    return out + colons + source[source.length - 1].lineEnding;
+}
+/** 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) {
+    const lines = splitLines(raw);
+    if (lines.length === 0)
+        return null;
+    const typed = matchAlertMarker(lines[0].text);
+    return typed ? emitDirective(typed.toLowerCase(), lines) : null;
+}
+export function convertGithubAlerts(text) {
+    const lines = splitLines(text);
+    let converted = '';
+    let changed = false;
+    let i = 0;
+    while (i < lines.length) {
+        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.
+            if (nextIndex > i) {
+                converted += emitDirective(typed.toLowerCase(), lines.slice(i, nextIndex));
+                changed = true;
+                i = nextIndex;
+                continue;
+            }
+        }
+        converted += lines[i].raw;
+        i++;
+    }
+    return { converted, changed };
+}
+export function hasGithubAlert(text) {
+    const lines = splitLines(text);
+    return lines.some((line, i) => matchAlertMarker(line.text) !== null && startsBlockquote(lines, i));
+}
+function startsBlockquote(lines, index) {
+    return index === 0 || !QUOTE_OPEN.test(lines[index - 1].text);
+}

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

@@ -0,0 +1,12 @@
+/**
+ * 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).
+ */
+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. */
+export declare function rebuildGithubAlertRaw(node: CstNode): void;
+export declare function registerGithubAlert(): void;

package/dist/plugins/admonitions/github-alert-kind.js

@@ -0,0 +1,125 @@
+/**
+ * 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).
+ */
+import { OPENER_PRIORITIES, blockquoteExtent, containerClosure, declarePluginKind, declaredPluginKind, defineBlockComponent, getPluginMetadata, parseContainerBody, registerBlockComponent, registerBlockKind, registerBlockOpener, serializeChildren, setPluginMetadata } from '../../plugin';
+import { matchAlertMarker, stripQuoteMarker } from './gh-alert';
+import { GITHUB_ALERT } from './kinds';
+import AdmonitionBlock from './AdmonitionBlock.svelte';
+/** The `> [!TYPE]` marker line is the alert's own chrome, so a blank against it separates
+ *  rather than materializing; nothing closes the alert below. */
+const BODY_WRAP = { afterOpenerLine: true };
+function tryOpen(ctx) {
+    const alertType = matchAlertMarker(ctx.line.text);
+    if (!alertType)
+        return null;
+    // The built-in extent scan, not the marker regex, is the authority on whether this line
+    // opens a blockquote: declining on a zero-line claim keeps a marker-rule drift from
+    // reaching the parse loop as a non-advancing return.
+    const { raw, nextIndex } = blockquoteExtent(ctx.lines, ctx.index, ctx.end);
+    const consumed = nextIndex - ctx.index;
+    if (consumed <= 0)
+        return null;
+    // A fresh parse entry, so the body's own line 0 must not read as the document top.
+    const body = parseContainerBody(stripBody(ctx.lines, ctx.index + 1, nextIndex), BODY_WRAP, {
+        scope: 'fragment'
+    });
+    const node = {
+        kind: declaredPluginKind(GITHUB_ALERT),
+        leadingTrivia: ctx.leadingTrivia,
+        raw,
+        innerPrefix: body.prefix,
+        children: body.children,
+        innerSuffix: body.suffix
+    };
+    setPluginMetadata(node, { alertType });
+    return { node, consumed };
+}
+function stripBody(lines, start, end) {
+    let out = '';
+    for (let i = start; i < end; i++)
+        out += stripQuoteMarker(lines[i].text) + lines[i].lineEnding;
+    return out;
+}
+/** 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. */
+export function rebuildGithubAlertRaw(node) {
+    const alertType = getPluginMetadata(node)?.alertType ?? 'NOTE';
+    const marker = `> [!${alertType}]`;
+    const body = (node.innerPrefix ?? '') + serializeChildren(node.children ?? []) + (node.innerSuffix ?? '');
+    if (body === '') {
+        node.raw = node.raw.endsWith('\n') ? marker + firstLineEnding(node.raw) : marker;
+        return;
+    }
+    node.raw = marker + firstLineEnding(node.raw) + prefixQuoteLines(body);
+}
+/** Not `core/lines.ts`'s `trailingLineEnding`: on a mixed-ending block that reader would
+ *  rewrite the marker's CRLF to LF. Rebuilding threads each line's own ending. */
+function firstLineEnding(raw) {
+    const nl = raw.indexOf('\n');
+    if (nl < 0)
+        return '\n';
+    return raw[nl - 1] === '\r' ? '\r\n' : '\n';
+}
+function prefixQuoteLines(body) {
+    const lines = body.split('\n');
+    return lines
+        .map((line, i) => {
+        if (i === lines.length - 1 && line === '')
+            return '';
+        if (line === '' || line === '\r')
+            return `>${line}`;
+        return `> ${line}`;
+    })
+        .join('\n');
+}
+export function registerGithubAlert() {
+    const kind = declarePluginKind(GITHUB_ALERT);
+    registerBlockOpener(kind, {
+        // Below blockquote so the alert form is claimed first; its own slot, distinct
+        // from every other opener, so the co-installed bundle stays unique (G1.10).
+        priority: OPENER_PRIORITIES.blockquote - 5,
+        tryOpen,
+        interruptsParagraph: (t) => matchAlertMarker(t) !== null
+    });
+    registerBlockKind(kind, {
+        gapEdges: 'none',
+        mergeRole: 'container',
+        editable: true,
+        supportsInline: false,
+        conformanceFixture: '> [!NOTE]\n> Heads up.\n',
+        container: {
+            contract: 'strip',
+            rebuildRaw: rebuildGithubAlertRaw,
+            bodyWrap: BODY_WRAP,
+            // The alert is a blockquote with a marker, so it unwraps as one: lifting the
+            // first child out drops the marker and reparses plain.
+            unwrapRole: {
+                firstChildBackspace: 'lift-first-child-drop-opener',
+                middleChildBackspace: 'default-merge'
+            },
+            // The marker is position-independent, so rebuildRaw re-emits it after a move.
+            reorderChildren: {}
+        },
+        closure: containerClosure({
+            roundTripVia: 'container contract=strip — rebuildGithubAlertRaw re-emits the > [!TYPE] marker (casing from metadata) + > -prefixed body, CRLF threaded',
+            focus: {
+                mode: 'implemented',
+                via: 'focus walks into the first body child via createContainerBlock'
+            },
+            mergeBackspace: {
+                mode: 'implemented',
+                via: 'mergeRole=container + unwrapRole (lift-first-child-drop-opener; default-merge) — Backspace at the body start lifts the first child out and drops the marker, leaving a plain blockquote'
+            },
+            undo: { mode: 'inherit-default' },
+            simOracle: {
+                mode: 'implemented',
+                via: 'github-alert-ops simulation under the loaded-ops corruption oracles (formation, contained merge, marker-dropping unwrap)'
+            }
+        })
+    });
+    registerBlockComponent(kind, defineBlockComponent(AdmonitionBlock));
+}

package/dist/plugins/admonitions/index.d.ts

@@ -0,0 +1,6 @@
+export { admonitionsPlugin } from './register';
+export type { AdmonitionsOptions } from './admonition-kind';
+export { convertGithubAlerts, hasGithubAlert } from './gh-alert';
+export type { AlertConversion } from './gh-alert';
+export { convertGithubAlertsInDocument } from './convert-document';
+export { ADMONITION_KINDS, GITHUB_ALERT, type AdmonitionName, type GithubAlertMetadata } from './kinds';

package/dist/plugins/admonitions/index.js

@@ -0,0 +1,8 @@
+// Two kinds sharing one component: the `:::name` directives, which all resolve to
+// one admonition kind, and native GitHub alerts (`> [!NOTE]`, kind `githubAlert`).
+export { admonitionsPlugin } from './register';
+// convertGithubAlerts is naive full-text and rewrites inside code fences; for a whole
+// document prefer convertGithubAlertsInDocument, which scopes through the parser.
+export { convertGithubAlerts, hasGithubAlert } from './gh-alert';
+export { convertGithubAlertsInDocument } from './convert-document';
+export { ADMONITION_KINDS, GITHUB_ALERT } from './kinds';

package/dist/plugins/admonitions/kinds.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared vocabulary for the admonitions plugin, in its own module so registration
+ * and the component agree on names without a circular import.
+ */
+export declare const ADMONITION = "admonition";
+export declare const ADMONITION_TITLE = "admonition-title";
+export declare const GITHUB_ALERT = "githubAlert";
+/** In cycle order; index 0 is the fallback when a node carries no name in its metadata. */
+export declare const ADMONITION_KINDS: readonly ["note", "tip", "important", "warning", "caution"];
+export type AdmonitionName = (typeof ADMONITION_KINDS)[number];
+export declare function coerceAdmonitionName(value: unknown): AdmonitionName;
+export declare function capitalize(name: string): string;
+/** Every field flows back into the opener bytes through `rebuildRaw`. Primitive-valued
+ *  only: the undo clone shallow-copies metadata. */
+export interface AdmonitionMetadata {
+    name: string;
+    colonCount: number;
+    closerColonCount: number;
+    closerNewline: boolean;
+    lineEnding: string;
+}
+/** The marker's type as typed (`NOTE`, `Note`), stored verbatim so `rebuildRaw` re-emits
+ *  the source casing; readers lowercase through `coerceAdmonitionName` for display. */
+export interface GithubAlertMetadata {
+    alertType: string;
+}

package/dist/plugins/admonitions/kinds.js

@@ -0,0 +1,18 @@
+/**
+ * Shared vocabulary for the admonitions plugin, in its own module so registration
+ * and the component agree on names without a circular import.
+ */
+export const ADMONITION = 'admonition';
+export const ADMONITION_TITLE = 'admonition-title';
+export const GITHUB_ALERT = 'githubAlert';
+/** In cycle order; index 0 is the fallback when a node carries no name in its metadata. */
+export const ADMONITION_KINDS = ['note', 'tip', 'important', 'warning', 'caution'];
+function isAdmonitionName(value) {
+    return typeof value === 'string' && ADMONITION_KINDS.includes(value);
+}
+export function coerceAdmonitionName(value) {
+    return isAdmonitionName(value) ? value : ADMONITION_KINDS[0];
+}
+export function capitalize(name) {
+    return name.charAt(0).toUpperCase() + name.slice(1);
+}

package/dist/plugins/admonitions/register.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Two block kinds from one setup, so this wires `definePlugin` directly rather than
+ * the single-kind `definePluginBlock` sugar.
+ */
+import { type EditorPlugin } from '../../plugin';
+import { type AdmonitionsOptions } from './admonition-kind';
+export declare function admonitionsPlugin(options?: AdmonitionsOptions): EditorPlugin;

package/dist/plugins/admonitions/register.js

@@ -0,0 +1,12 @@
+/**
+ * Two block kinds from one setup, so this wires `definePlugin` directly rather than
+ * the single-kind `definePluginBlock` sugar.
+ */
+import { definePlugin } from '../../plugin';
+import { registerAdmonitions } from './admonition-kind';
+export function admonitionsPlugin(options) {
+    return definePlugin({
+        name: 'admonitions',
+        setup: () => registerAdmonitions(options)
+    });
+}

package/dist/plugins/details/DetailsBlock.svelte

@@ -0,0 +1,129 @@
+<script lang="ts">
+	// Collapse-ness has one definition, the descriptor's `reservedChrome.isCollapsed` probe.
+	// The reader's transient disclosure layers over it by feeding the factory the effective
+	// state, so the window clamp, focus clamp and caret never disagree.
+	import {
+		BlockList,
+		createContainerBlock,
+		isCollapsedContainer,
+		type NodeView
+	} from '../../plugin';
+	import { createReaderDisclosure } from './details-disclosure.svelte';
+
+	let { node, index, myPath = [] }: { node: NodeView; index: number; myPath?: number[] } = $props();
+
+	let boxEl: HTMLElement | undefined = $state();
+
+	const documentOpen = $derived(!isCollapsedContainer(node));
+
+	const { blockListProps, containerApi, updateOwnMetadata, getPresentationMode } =
+		createContainerBlock({
+			getNode: () => node,
+			getIndex: () => index,
+			getPath: () => myPath,
+			getBoxEl: () => boxEl,
+			// The effective state, so a transiently-opened section actually mounts and
+			// measures its body.
+			isCollapsed: () => !open
+		});
+
+	const reading = $derived(getPresentationMode() === 'reading');
+	const reader = createReaderDisclosure({ isDocumentOpen: () => documentOpen });
+	// Leaving reading mode discards the flip: with the bytes editable again, a view
+	// state they disagree with would be a live lie.
+	$effect(() => {
+		if (!reading) reader.reset();
+	});
+	const open = $derived(reading ? reader.open : documentOpen);
+
+	function commitDisclosure() {
+		const isOpen = open;
+		// Collapsing unmounts the body, orphaning a caret inside it, so move it to the summary
+		// in the commit's afterTick. Read before the commit: the toggle suppresses mousedown,
+		// so a mouse toggle leaves the caret in the body.
+		const pos = isOpen ? (containerApi.getCursorPosition?.() ?? null) : null;
+		const caretInBody = pos != null && pos.path[0] >= 1;
+		updateOwnMetadata({ open: !isOpen }, caretInBody ? () => containerApi.focus(0) : undefined);
+	}
+
+	// Reading mode gets the handler that cannot write, not one that declines to: this
+	// is the only mode read, and the toggle keeps working for a reader either way.
+	const onToggle = $derived(reading ? reader.toggle : commitDisclosure);
+
+	export { containerApi };
+</script>
+
+<div class="details-block" bind:this={boxEl}>
+	<button
+		type="button"
+		class="details-toggle"
+		contenteditable="false"
+		aria-expanded={open}
+		aria-label="Toggle details"
+		onmousedown={(e) => e.preventDefault()}
+		onclick={onToggle}
+	></button>
+	<BlockList {...blockListProps} />
+</div>
+
+<style>
+	/* Mirrors the admonition's rail gap and caret column so the two read as a family. */
+	.details-block {
+		position: relative;
+		margin: 0.8em 0;
+		padding: 0.15em 0 0.15em 1.7em;
+		border-left: 3px solid var(--color-border, #3d4047);
+	}
+
+	/* A real focusable button (keyboard disclosure), so it is a sibling of BlockList: the
+	   windowing lookup needs BlockList to stay a direct child, not the sole one. */
+	.details-toggle {
+		position: absolute;
+		left: 0.45em;
+		/* Anchors the button's em geometry to the editor font; without it the UA font-size
+		   shrinks the line-box math below and floats the caret above the summary title. */
+		font: inherit;
+		/* Overlays the summary's first line box exactly (block padding + the leaf's 2px,
+		   one line-height tall), so flex-centering lands the caret on the title line. */
+		top: calc(0.15em + 2px);
+		width: 1.1em;
+		height: 1.6em;
+		display: flex;
+		align-items: center;
+		padding: 0;
+		border: none;
+		background: transparent;
+		cursor: pointer;
+		color: var(--color-text-muted, #aaaaaa);
+	}
+	.details-toggle::before {
+		content: '';
+		display: block;
+		width: 0;
+		height: 0;
+		margin-left: 0.25em;
+		border-left: 6px solid currentColor;
+		border-top: 4px solid transparent;
+		border-bottom: 4px solid transparent;
+		transition: transform 0.1s ease;
+	}
+	.details-toggle[aria-expanded='true']::before {
+		transform: rotate(90deg);
+	}
+	.details-toggle:focus-visible {
+		outline: 2px solid var(--color-accent, #567b67);
+		outline-offset: 1px;
+		border-radius: var(--radius-ui, 3px);
+	}
+
+	/* The summary leaf is promoted to a title row by CSS alone; it stays a real block
+	   inside `.block-list`, so selection and windowing treat it as an ordinary child. */
+	.details-block :global(.details-summary) {
+		font-weight: 600;
+	}
+	.details-block :global(.details-summary:empty)::before {
+		content: 'Summary';
+		color: var(--color-ui-dulled, #afb1b3);
+		pointer-events: none;
+	}
+</style>

package/dist/plugins/details/DetailsBlock.svelte.d.ts

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

package/dist/plugins/details/details-disclosure.svelte.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The half of the `<details>` toggle that writes nothing: reading mode must let a
+ * reader open a collapsed section without touching bytes, and these deps carry no
+ * commit door, so no flip reachable from here can become an edit. Absent-by-default
+ * rather than seeded on entry, so the document's own `open` shows through even for a
+ * block windowed out at the moment of the flip. Scoped to the instance, so it is ephemeral.
+ */
+export interface ReaderDisclosure {
+    /** The reader's flip if they made one, else the document's own state. */
+    readonly open: boolean;
+    toggle(): void;
+    reset(): void;
+}
+export declare function createReaderDisclosure(deps: {
+    /** Getter, so the document's `open` is read live and never snapshotted. */
+    isDocumentOpen: () => boolean;
+}): ReaderDisclosure;

package/dist/plugins/details/details-disclosure.svelte.js

@@ -0,0 +1,24 @@
+/**
+ * The half of the `<details>` toggle that writes nothing: reading mode must let a
+ * reader open a collapsed section without touching bytes, and these deps carry no
+ * commit door, so no flip reachable from here can become an edit. Absent-by-default
+ * rather than seeded on entry, so the document's own `open` shows through even for a
+ * block windowed out at the moment of the flip. Scoped to the instance, so it is ephemeral.
+ */
+export function createReaderDisclosure(deps) {
+    let flipped = $state(null);
+    return {
+        get open() {
+            return flipped ?? deps.isDocumentOpen();
+        },
+        toggle() {
+            flipped = !(flipped ?? deps.isDocumentOpen());
+        },
+        reset() {
+            // Conditional: an unconditional write re-invalidates every reader of `open`
+            // on each pass of the effect that calls this.
+            if (flipped !== null)
+                flipped = null;
+        }
+    };
+}