@liminis/editor 0.4.1 → 0.6.0

package/dist/markdown/parse.js

@@ -14,6 +14,29 @@ import * as wikiLinkMdast from './vendor/mdast-util-wiki-link/index.js';
 // Wiki-link options: use | as the alias divider (Obsidian/Foam style)
 const wikiLinkOptions = { aliasDivider: '|' };
 const EMPTY_ALIAS_SENTINEL = '__EMPTY_ALIAS__';
+// Private-Use-Area sentinel marking a `!` that immediately precedes `[[`
+// (candidate transclusion/embed marker, #119). The next free codepoint after
+// `annotate-sentinels.ts`'s E000-E003 range and `stringify.ts`'s E004.
+//
+// Why substitute at all, rather than just checking "does the wikiLink node
+// have a `!` text sibling" after parsing: the micromark wiki-link tokenizer
+// is not vendored (see the vendor README) and only hooks the `[` character.
+// A literal `!` immediately before `[[` is claimed *first* by the default
+// image-label-start construct (hooked on `!`), and when that construct fails
+// to find a following `(url)`/`[ref]` — which it always will here, since
+// `[[target]]` is not image syntax — CommonMark's own bracket-resolution
+// falls the *entire* `![[target]]` span back to one literal text node,
+// without ever giving the wiki-link tokenizer a chance to fire on the inner
+// `[[`. A backslash-escaped `\!` sidesteps the image construct entirely (it
+// is consumed as a plain escaped character, not a construct trigger) and
+// `[[target]]` parses normally — confirmed empirically against
+// `micromark-extension-wiki-link@0.0.4`'s tokenizer. Swapping the raw `!`
+// for this sentinel *before* parsing reproduces that same escape-shaped
+// bypass without a real backslash reaching the output, so `[[target]]` parses
+// as a normal wikiLink node with the sentinel left on the preceding text
+// node — which `resolveWikiEmbeds` (below) then reads to decide embed vs.
+// plain link, and always strips before the tree leaves `parseMarkdown`.
+const EMBED_MARKER_SENTINEL = '\u{E005}';
 /**
  * Escape pipes inside wiki-links: [[target|alias]] → [[target\|alias]]
  * This prevents GFM table parsing from splitting wiki-links at the pipe.
@@ -57,6 +80,200 @@ function escapeWikiLinkPipes(text) {
     result += text.slice(cursor);
     return { text: result, replacements };
 }
+/**
+ * Swap a `!` for {@link EMBED_MARKER_SENTINEL}, but only when it is
+ * immediately followed by a *complete, single-line* `[[...]]` span with no
+ * internal `]` — i.e. exactly the shape the wiki-link tokenizer's own
+ * `consumeTarget`/`consumeAlias` states require to succeed (a bare `]` not
+ * immediately followed by a second `]` aborts the whole construct; so does a
+ * line ending). One codepoint swapped for one codepoint, so — unlike
+ * `escapeWikiLinkPipes`/`normalizeWikiLinks` above — this never shifts any
+ * subsequent offset and needs no `Replacement` tracking of its own.
+ *
+ * The "complete span" requirement is load-bearing, not a nicety: an `!`
+ * immediately before `[` is *also* how a real image's alt text starting with
+ * a literal `[` looks at the character level (`![[leading] bracket](x.png)`
+ * is `![` + alt text `[leading] bracket` + `](x.png)`, i.e. contains the raw
+ * substring `![[`). Matching on `!(?=\[\[)` alone — with no lookahead past
+ * the second `[` — can't tell that case apart from a genuine embed candidate
+ * and would substitute inside it, preventing the image construct (which
+ * needs the literal `!`) from ever being tried and corrupting the image
+ * (caught by the `903-image-alt-leading-bracket` regression fixture).
+ * Requiring the run between `[[` and `]]` to contain no internal `]` rules
+ * that case out: `[leading] bracket](x.png)` hits an un-doubled `]` right
+ * after `leading`, so the pattern below never matches there, `!` survives
+ * untouched, and the image construct parses exactly as before this feature
+ * existed (FR-014).
+ *
+ * A `!` that is already backslash-escaped (`\![[...]]`) is left alone: that
+ * spelling already means "literal `!`, then a normal wiki-link" with no
+ * substitution needed (CommonMark consumes the escape before the image
+ * construct ever sees the `!`) — see FR-013's requirement that an author can
+ * explicitly opt out of transclusion for a `#^id`-bearing target.
+ *
+ * "Escaped" here means CommonMark backslash-*parity*, not merely "a `\`
+ * immediately precedes the `!`": an even run of backslashes (`\\!`, `\\\\!`,
+ * ...) pairs off into literal backslashes and does not escape the `!`, while
+ * an odd run (`\!`, `\\\!`, ...) does. A naive one-character lookbehind gets
+ * every even run ≥ 2 wrong (treats the `!` as escaped when it isn't), so the
+ * preceding backslash run is captured and its length checked explicitly.
+ *
+ * A match inside a fenced code block or inline code span must be skipped
+ * entirely, not just left un-embedded: inside those constructs the wiki-link
+ * tokenizer never runs at all (code content is verbatim), so a substituted
+ * sentinel would never get a `wikiLink` node to attach to and restore from —
+ * `resolveWikiEmbeds`'s leftover-sentinel sweep only walks `text` nodes, not
+ * a `code`/`inlineCode` node's `value`, so the sentinel would otherwise leak
+ * through as a literal, invisible Private-Use-Area character in the final
+ * output instead of being restored to `!`. {@link findProtectedRanges}
+ * identifies those spans so the substitution can leave them untouched.
+ */
+function substituteEmbedMarker(text) {
+    const protectedRanges = findProtectedRanges(text);
+    return text.replace(/(\\*)!(\[\[[^\]\n]*\]\])/g, (match, backslashes, bracketed, offset) => {
+        if (protectedRanges.some((r) => offset >= r.start && offset < r.end)) {
+            return match;
+        }
+        return backslashes.length % 2 === 1
+            ? `${backslashes}!${bracketed}`
+            : `${backslashes}${EMBED_MARKER_SENTINEL}${bracketed}`;
+    });
+}
+/**
+ * Finds fenced code blocks and inline code spans in raw markdown text, so
+ * {@link substituteEmbedMarker} can avoid mutating their (verbatim) content.
+ * Deliberately approximate rather than a full CommonMark tokenizer — good
+ * enough to protect the common cases (``` fences, `inline` spans) without
+ * duplicating the real tokenizer this file elsewhere avoids vendoring.
+ */
+function findProtectedRanges(text) {
+    const ranges = [];
+    // Fenced code blocks: a line of (up to 3 leading spaces then) 3+ backticks
+    // or tildes opens one; it's closed by a later line of at least as many of
+    // the same character (optionally indented, nothing else on the line).
+    const fenceOpenRe = /^ {0,3}(`{3,}|~{3,})/;
+    let fenceChar = null;
+    let fenceLen = 0;
+    let fenceStart = -1;
+    let cursor = 0;
+    for (const line of text.split('\n')) {
+        const lineEnd = cursor + line.length;
+        if (fenceChar === null) {
+            const m = fenceOpenRe.exec(line);
+            if (m) {
+                fenceChar = m[1][0];
+                fenceLen = m[1].length;
+                fenceStart = cursor;
+            }
+        }
+        else {
+            const closeRe = new RegExp(`^ {0,3}\\${fenceChar}{${fenceLen},}\\s*$`);
+            if (closeRe.test(line)) {
+                ranges.push({ start: fenceStart, end: lineEnd });
+                fenceChar = null;
+                fenceLen = 0;
+                fenceStart = -1;
+            }
+        }
+        cursor = lineEnd + 1; // +1 for the '\n' consumed by split
+    }
+    if (fenceChar !== null) {
+        ranges.push({ start: fenceStart, end: text.length });
+    }
+    // Inline code spans, outside any fenced block already found: a backtick
+    // run opens a span, closed by the next run of the *same* length (a run of
+    // a different length is span content, not a delimiter) — CommonMark's own
+    // code-span rule. An opening run with no matching close is not a code
+    // span at all (its backticks are literal), so it protects nothing.
+    const isInFence = (pos) => ranges.some((r) => pos >= r.start && pos < r.end);
+    const backtickRun = /`+/g;
+    let pendingOpen = null;
+    let match;
+    while ((match = backtickRun.exec(text)) !== null) {
+        if (isInFence(match.index))
+            continue;
+        const len = match[0].length;
+        if (pendingOpen === null) {
+            pendingOpen = { start: match.index, len };
+        }
+        else if (len === pendingOpen.len) {
+            ranges.push({ start: pendingOpen.start, end: match.index + len });
+            pendingOpen = null;
+        }
+    }
+    return ranges;
+}
+/**
+ * Retype a `wikiLink` node to `wikiEmbed` when it was immediately preceded by
+ * an {@link EMBED_MARKER_SENTINEL} *and* carries a `data.blockId` (#119).
+ *
+ * Two outcomes when a sentinel-terminated text node precedes a `wikiLink`:
+ *  - **Has `blockId`**: this is a genuine transclusion. Strip the sentinel
+ *    off the preceding text (dropping the text node entirely if it was the
+ *    sentinel alone) and retype the node to `wikiEmbed`, carrying the same
+ *    `value`/`data`.
+ *  - **No `blockId`**: FR-013 — `![[file]]` with no anchor is not a supported
+ *    construct in v1. Restore the literal `!` in the preceding text and leave
+ *    the node as an ordinary `wikiLink`, so it degrades to ordinary
+ *    file-only link treatment (no embedding), matching what plain
+ *    `\![[file]]` already does without any sentinel involved.
+ *
+ * A final sweep restores any sentinel left over from a `!` that didn't end up
+ * immediately before a completed `wikiLink` (e.g. the target never closed) —
+ * this sentinel must never leak into rendered/round-tripped content.
+ */
+function resolveWikiEmbeds(root) {
+    function walkChildren(children) {
+        const result = [];
+        for (const rawChild of children) {
+            const child = walk(rawChild);
+            if (child?.type === 'wikiLink' && result.length > 0) {
+                const prevIndex = result.length - 1;
+                const prev = result[prevIndex];
+                if (prev.type === 'text' && typeof prev.value === 'string' && prev.value.endsWith(EMBED_MARKER_SENTINEL)) {
+                    const blockId = child.data?.blockId;
+                    const hasBlockId = typeof blockId === 'string' && blockId.length > 0;
+                    const strippedValue = prev.value.slice(0, -1);
+                    if (hasBlockId) {
+                        if (strippedValue.length === 0) {
+                            result.pop();
+                        }
+                        else {
+                            result[prevIndex] = { ...prev, value: strippedValue };
+                        }
+                        result.push({ ...child, type: 'wikiEmbed' });
+                        continue;
+                    }
+                    result[prevIndex] = { ...prev, value: strippedValue + '!' };
+                    result.push(child);
+                    continue;
+                }
+            }
+            result.push(child);
+        }
+        return result;
+    }
+    function walk(node) {
+        if (!node || typeof node !== 'object')
+            return node;
+        if (node.children && Array.isArray(node.children)) {
+            return { ...node, children: walkChildren(node.children) };
+        }
+        return node;
+    }
+    function restoreLeftoverSentinels(node) {
+        if (!node || typeof node !== 'object')
+            return node;
+        if (node.type === 'text' && typeof node.value === 'string' && node.value.includes(EMBED_MARKER_SENTINEL)) {
+            return { ...node, value: node.value.split(EMBED_MARKER_SENTINEL).join('!') };
+        }
+        if (node.children && Array.isArray(node.children)) {
+            return { ...node, children: node.children.map(restoreLeftoverSentinels) };
+        }
+        return node;
+    }
+    return restoreLeftoverSentinels(walk(root));
+}
 /**
  * Combine two sets of replacements from sequential preprocessing steps.
  * The second set of replacements refers to positions in text AFTER the first set was applied.
@@ -349,6 +566,313 @@ function splitTextNodeEscapes(node, normalizedText) {
     flushRun(runStart, parts.length);
     return result;
 }
+// Any id shape the resolver and the reference-side wiki-link parser already
+// accept — ULID included — gated by the resolver's own position rule: the
+// caret must start a token (line-start or preceded by whitespace), and the
+// captured id must run to end of line (trailing spaces/tabs allowed). This is
+// what makes badge and resolver agree by construction for every id form with
+// no carve-out (#124/FR-002, #126/FR-001) — ULID no longer gets a permissive,
+// position-free rule of its own; Crockford Base32 (ULID's charset) is already
+// a strict subset of this charset, so every ULID that satisfies this position
+// rule keeps badging unchanged (see ADR-122's amendments).
+//
+// The charset excludes `*` (in addition to `#`/`]`/whitespace) to match
+// `liminis-app/src/main/fs.ts`'s `ANCHOR_LINE_PATTERN`
+// (`[^\s\]#*]`) as actually implemented for `liminis#1114` — that resolver
+// pattern narrowed *both* its wrapped and unwrapped branches to exclude `*`,
+// unlike the stale, pre-implementation regex the #127 issue body quoted.
+// `_` stays allowed: excluding it would break the NanoID-with-underscore
+// case (#124/FR-004), and the resolver's own pattern allows it too.
+const WIDE_ID_CHAR = /[^\s\]#*]/;
+// A symmetric emphasis wrapper (`**`, `__`, `*`, `_`) around `^<id>` at line
+// end badges too (#127), so this rule agrees with the widened resolver
+// (`liminis#1114`) for wrapped ids the same way it already agrees for plain
+// ones. The wrapped id charset matches the resolver's actual wrapped-branch
+// charset (`[^\s\]#*]+?` in
+// `ANCHOR_LINE_PATTERN`) — same as `WIDE_ID_CHAR` above; kept as a distinct,
+// separately-named constant since the wrapped and unwrapped charsets are
+// independent knobs in the resolver's pattern and could diverge again.
+// Longest markers first so a `**`/`__` candidate is tried before its `*`/`_`
+// prefix.
+const WRAPPED_ID_CHAR = /[^\s\]#*]/;
+const WRAPPER_MARKERS = ['**', '__', '*', '_'];
+const isSpaceOrTab = (ch) => ch === ' ' || ch === '\t';
+/**
+ * Look for one of `WRAPPER_MARKERS` immediately before `offset` in the raw,
+ * pre-parse `normalizedText`, itself preceded by whitespace or document
+ * start — the same left-boundary rule already applied to a bare caret, just
+ * one token further out. Returns the matched marker string, or
+ * `null` if none of them fit.
+ *
+ * This only needs to look *outside* the current text node (at `offset`, the
+ * node's own start) because a caret can only be adjacent to a *structural*
+ * wrapper marker when it is the first character of its own text node: if a
+ * literal `**`/`_` sat before the caret inside the same text node, that run
+ * of emphasis markers never found a matching closer and CommonMark left it
+ * as ordinary text, which the plain (non-wrapped) left-boundary check
+ * already handles correctly with no wrapper logic involved.
+ */
+function matchWrapperMarkerBefore(normalizedText, offset) {
+    for (const marker of WRAPPER_MARKERS) {
+        const markerStart = offset - marker.length;
+        if (markerStart < 0)
+            continue;
+        if (normalizedText.slice(markerStart, offset) !== marker)
+            continue;
+        if (markerStart === 0 || /\s/.test(normalizedText[markerStart - 1]))
+            return marker;
+    }
+    return null;
+}
+/**
+ * Find every block-anchor match in `decoded` — any id shape, position-gated
+ * by the resolver's own rule, with no separate ULID carve-out (#126) — at
+ * each unescaped `^`, left to right.
+ *
+ * The boundary checks peek one character outside this text node's own
+ * `decoded`/`source` span — into `normalizedText` at `start - 1` (left) or
+ * from `end` onward (right) — rather than inspecting sibling AST nodes: the
+ * raw source character is equivalent and needs no tree traversal (see Plan
+ * stage's "Key Decisions"). This is what lets the rule correctly refuse a
+ * match immediately followed by more prose on the same line, even when that
+ * prose lives in a following sibling node (e.g. a wiki-link right after the
+ * id), and correctly accept one immediately after a preceding sibling ends
+ * with whitespace.
+ *
+ * A symmetric emphasis wrapper (`**`, `__`, `*`, `_`) around the id at line
+ * end also badges (#127), using the same outside-the-node peek:
+ * when the caret is the first character of this text node (`i === 0`) and
+ * the plain whitespace/start rule doesn't hold, it peeks backward for a
+ * wrapper marker; when one is found, the id must then run to this text
+ * node's own end (`idEnd === decoded.length`) and be followed immediately
+ * by the *same* marker string before the usual trailing-whitespace/EOL
+ * check. Both `i === 0` and `idEnd === decoded.length` are load-bearing
+ * invariants, not incidental: they are exactly the positions at which a
+ * *structural* wrapper marker (one CommonMark parsed as real emphasis,
+ * rather than literal text left over from an unmatched delimiter run) can
+ * be adjacent to the caret/id at all — see `matchWrapperMarkerBefore`.
+ */
+function findBlockAnchorMatches(decoded, parts, normalizedText, start, end) {
+    const matches = [];
+    let cursor = 0;
+    for (let i = 0; i < decoded.length; i++) {
+        if (i < cursor)
+            continue;
+        if (decoded[i] !== '^' || parts[i].escaped)
+            continue;
+        // Left boundary: preceded by whitespace, or true document start — or,
+        // when the caret is the first character of this text node, a symmetric
+        // emphasis wrapper immediately before it (#127). That `i === 0` gate is
+        // load-bearing: it's the only position at which a *structural* wrapper
+        // marker (one CommonMark actually parsed as emphasis, not literal text)
+        // can sit immediately before the caret — see `matchWrapperMarkerBefore`.
+        const leftOk = i > 0 ? /\s/.test(decoded[i - 1]) : start === 0 || /\s/.test(normalizedText[start - 1]);
+        let wrapMarker = null;
+        if (!leftOk) {
+            if (i === 0)
+                wrapMarker = matchWrapperMarkerBefore(normalizedText, start);
+            if (!wrapMarker)
+                continue;
+        }
+        // Id capture: greedy run of non-whitespace, non-`]`, non-`#`, non-`*`,
+        // tested against `decoded` rather than raw source. A backslash-escaped `#` or
+        // `]` inside an id (`^abc\#def`) therefore truncates the capture one
+        // character earlier than a regex run over raw, undecoded file text
+        // would (the resolver's own matching model) — but this never produces a
+        // badge/resolver disagreement: whatever follows the truncation point is
+        // identical, non-whitespace content in both the decoded and raw views
+        // (backslash-escaping only ever turns `\X` into `X`, never anything
+        // into whitespace), so the right-boundary check below rejects the match
+        // in both models alike whenever this truncation is reachable. See the
+        // "does not badge an id containing a backslash-escaped delimiter"
+        // regression test.
+        //
+        // When wrapped, `WRAPPED_ID_CHAR` applies instead of `WIDE_ID_CHAR` (see
+        // their definitions) — currently identical charsets, kept as separate
+        // named constants since the resolver's wrapped/unwrapped branches are
+        // independent knobs that could diverge again.
+        const idCharTest = wrapMarker ? WRAPPED_ID_CHAR : WIDE_ID_CHAR;
+        let idEnd = i + 1;
+        while (idEnd < decoded.length && idCharTest.test(decoded[idEnd]))
+            idEnd++;
+        // Empty capture: the character right after `^` is already whitespace
+        // (or end of text), e.g. `a ^ b`, `a ^`, `x ^\t`. `a ^ b` would also be
+        // rejected by the right-boundary check below regardless (the trailing
+        // `b` isn't end-of-line), but a bare trailing caret like `a ^` or
+        // `x ^\t` reaches true end-of-line/end-of-document and would otherwise
+        // pass that check with an empty id — this guard is what actually stops
+        // that case. See "does not badge a bare trailing caret" regression test.
+        if (idEnd === i + 1)
+            continue;
+        // Right boundary: only trailing spaces/tabs before end of line or end of
+        // document — peeking past this node's own end into `normalizedText` if
+        // the capture runs all the way to it.
+        //
+        // When wrapped, the closer is required instead: the id capture must run
+        // all the way to this text node's own end (the mirror image of the
+        // `i === 0` left-boundary gate — a structural closer can only be
+        // adjacent to the id there), the exact same marker string that opened
+        // it must appear immediately after, and only trailing spaces/tabs and
+        // end-of-line/end-of-document may follow that. No fallback to the
+        // unwrapped rule on mismatch — an asymmetric wrapper (e.g. `**^id_`)
+        // must never badge with a corrupted id (#127/SC-003).
+        let rightOk;
+        if (wrapMarker) {
+            if (idEnd !== decoded.length)
+                continue;
+            const closerEnd = end + wrapMarker.length;
+            if (normalizedText.slice(end, closerEnd) !== wrapMarker)
+                continue;
+            let pos = closerEnd;
+            while (pos < normalizedText.length && isSpaceOrTab(normalizedText[pos]))
+                pos++;
+            rightOk = pos === normalizedText.length || normalizedText[pos] === '\n';
+        }
+        else {
+            let j = idEnd;
+            while (j < decoded.length && isSpaceOrTab(decoded[j]))
+                j++;
+            if (j < decoded.length) {
+                rightOk = decoded[j] === '\n';
+            }
+            else {
+                let pos = end;
+                while (pos < normalizedText.length && isSpaceOrTab(normalizedText[pos]))
+                    pos++;
+                rightOk = pos === normalizedText.length || normalizedText[pos] === '\n';
+            }
+        }
+        if (!rightOk)
+            continue;
+        matches.push({ index: i, length: idEnd - i });
+        cursor = idEnd;
+    }
+    return matches;
+}
+/**
+ * Split a single `text` node into `[before, blockAnchor, after, ...]`
+ * siblings wherever it contains a {@link findBlockAnchorMatches} match,
+ * mirroring `splitTextNodeEscapes`'s decode-replay + position-mapping
+ * machinery exactly (including its conservative bail-out when replayed
+ * decoding doesn't exactly reproduce `node.value`, e.g. a character
+ * reference in the span) rather than duplicating it (#122).
+ *
+ * Because this only ever inspects a `text` node's own `value` (plus, for
+ * the boundary checks, one character immediately outside it), it can
+ * never see into `inlineCode`, `code`, `inlineMath`, `wikiLink` or
+ * `wikiEmbed` node content — none of those are `text` nodes once mdast has
+ * typed them — which satisfies the code-span/fenced-code/math edge case and
+ * FR-006 by construction, with no "protected ranges" pre-parse machinery
+ * needed.
+ */
+function splitTextNodeBlockAnchors(node, normalizedText) {
+    const start = node.position?.start?.offset;
+    const end = node.position?.end?.offset;
+    if (start == null || end == null) {
+        return [node];
+    }
+    const source = normalizedText.slice(start, end);
+    const { decoded, parts } = replayDecodeEscapes(source);
+    if (decoded !== node.value) {
+        return [node];
+    }
+    // A caret whose leading `^` came from a backslash escape (`\^`) in the
+    // source is never a match candidate — `findBlockAnchorMatches` checks
+    // `parts[i].escaped` itself before trying either branch. `decoded` has
+    // already resolved `\^` to a plain `^`, so nothing downstream can tell the
+    // two apart on its own; an author who deliberately escaped a caret meant
+    // literal text, not an anchor, and `stringify.ts`'s `blockAnchor` handler
+    // always emits a bare `^id` with no escaping, so badging it would silently
+    // drop the escape on the next save.
+    const matches = findBlockAnchorMatches(decoded, parts, normalizedText, start, end);
+    if (matches.length === 0) {
+        return [node];
+    }
+    const startPos = node.position.start;
+    // Per-offset line/column within `source`, mirroring splitTextNodeEscapes.
+    const positionAt = new Array(source.length + 1);
+    {
+        let line = startPos.line;
+        let column = startPos.column;
+        positionAt[0] = { line, column };
+        for (let i = 0; i < source.length; i++) {
+            if (source[i] === '\n') {
+                line += 1;
+                column = 1;
+            }
+            else {
+                column += 1;
+            }
+            positionAt[i + 1] = { line, column };
+        }
+    }
+    const makePosition = (srcStart, srcEnd) => ({
+        start: { ...positionAt[srcStart - start], offset: srcStart },
+        end: { ...positionAt[srcEnd - start], offset: srcEnd },
+    });
+    const makeTextNode = (value, srcStart, srcEnd) => ({
+        type: 'text',
+        value,
+        position: makePosition(srcStart, srcEnd),
+    });
+    const result = [];
+    let cursor = 0; // index into `parts`/`decoded`
+    for (const match of matches) {
+        const matchStart = match.index;
+        const matchEnd = matchStart + match.length;
+        if (matchStart > cursor) {
+            const value = parts.slice(cursor, matchStart).map((p) => p.char).join('');
+            result.push(makeTextNode(value, start + parts[cursor].srcStart, start + parts[matchStart - 1].srcEnd));
+        }
+        // Captured from raw `source`, not `decoded`: stringify.ts's `blockAnchor`
+        // handler re-emits `^${node.id}` verbatim with no escaping, so the id
+        // must already carry any backslash the author wrote (e.g. `^ab\_cd`) or
+        // that escape is silently dropped on the next save — a round-trip
+        // corruption distinct from, and not covered by, the decoded-vs-raw
+        // truncation reasoning above (that reasoning only shows the *match
+        // boundary* never diverges; it says nothing about what ends up inside
+        // an id that does match).
+        result.push({
+            type: 'blockAnchor',
+            id: source.slice(parts[matchStart + 1].srcStart, parts[matchEnd - 1].srcEnd),
+            position: makePosition(start + parts[matchStart].srcStart, start + parts[matchEnd - 1].srcEnd),
+        });
+        cursor = matchEnd;
+    }
+    if (cursor < parts.length) {
+        const value = parts.slice(cursor, parts.length).map((p) => p.char).join('');
+        result.push(makeTextNode(value, start + parts[cursor].srcStart, start + parts[parts.length - 1].srcEnd));
+    }
+    return result;
+}
+/**
+ * Walk the tree and split every `text` node containing a block anchor (see
+ * `splitTextNodeBlockAnchors`) into siblings. Run after `resolveWikiEmbeds`/
+ * `annotateEmphasisMarkers` (so this never sees wiki-link/embed target text —
+ * FR-006) and before `splitEscapedPunctuation` (so that pass still sees, and
+ * can process, any escaped punctuation left in this split's "before"/"after"
+ * text siblings) (#122).
+ */
+function splitBlockAnchors(root, normalizedText) {
+    function walk(node) {
+        if (!node || typeof node !== 'object')
+            return node;
+        if (node.children && Array.isArray(node.children)) {
+            const children = [];
+            for (const child of node.children) {
+                if (child?.type === 'text') {
+                    children.push(...splitTextNodeBlockAnchors(child, normalizedText));
+                }
+                else {
+                    children.push(walk(child));
+                }
+            }
+            return { ...node, children };
+        }
+        return node;
+    }
+    return walk(root);
+}
 /**
  * Walk the tree and split every `text` node containing a force-escaped
  * character (see `splitTextNodeEscapes`) into siblings. Run last, after all
@@ -434,8 +958,12 @@ function addCheckboxesToOrderedLists(root) {
 }
 export function parseMarkdown(text, _options = {}) {
     // Pre-process to handle edge cases
+    // Step 0: Swap a `!` immediately before `[[` for a sentinel so the
+    // wiki-link tokenizer gets a chance to fire (#119; see EMBED_MARKER_SENTINEL).
+    // Same-length, so it needs no offset-replacement tracking of its own.
+    const embedMarked = substituteEmbedMarker(text);
     // Step 1: Escape pipes inside wiki-links to protect from GFM table parsing
-    const { text: pipesEscaped, replacements: pipeReplacements } = escapeWikiLinkPipes(text);
+    const { text: pipesEscaped, replacements: pipeReplacements } = escapeWikiLinkPipes(embedMarked);
     // Step 2: Normalize empty aliases (existing logic)
     const { text: normalizedText, replacements: aliasReplacements } = normalizeWikiLinks(pipesEscaped);
     // Combine replacements for offset mapping (pipeReplacements first, then adjust aliasReplacements)
@@ -458,8 +986,14 @@ export function parseMarkdown(text, _options = {}) {
     root = stripEscapedPipeFromWikiLinks(root);
     // Post-process: mark wiki-links that had empty aliases in the source
     root = markEmptyAliasWikiLinks(root);
+    // Post-process: retype a sentinel-preceded wiki-link with a blockId to a
+    // transclusion/embed node, and restore the literal `!` everywhere else (#119)
+    root = resolveWikiEmbeds(root);
     // Post-process: annotate emphasis/strong marker characters from original source
     root = annotateEmphasisMarkers(root, text, replacements);
+    // Post-process: split a bare `^ULID` block anchor out of its surrounding
+    // text so it can render as a badge instead of raw text (#122)
+    root = splitBlockAnchors(root, normalizedText);
     // Post-process: split out backslash-escaped punctuation so its escape can
     // be carried through Lexical and restored at stringify time (#17)
     root = splitEscapedPunctuation(root, normalizedText);

package/dist/markdown/stringify.js

@@ -214,7 +214,7 @@ function normalizeWikiLinkNodes(node) {
     if (!node || typeof node !== 'object') {
         return node;
     }
-    if (node.type === 'wikiLink') {
+    if (node.type === 'wikiLink' || node.type === 'wikiEmbed') {
         const data = node.data && typeof node.data === 'object' ? { ...node.data } : {};
         return {
             ...node,
@@ -289,6 +289,27 @@ function widenTableDelimiterDashes(markdown) {
     }
     return lines.join('\n');
 }
+/**
+ * Format the `[[target...]]` (or `[[target...|alias]]`) body shared by the
+ * `wikiLink` and `wikiEmbed` handlers below — everything between the double
+ * brackets, minus the brackets themselves and (for `wikiEmbed`) the leading
+ * `!`. `data.blockId`, when present, is re-appended as `#^blockId` (#119),
+ * mirroring the vendored `mdast-util-wiki-link/to-markdown.ts` — duplicated
+ * rather than shared because this handler otherwise diverges from the
+ * vendored one already (see the module comment above `stringifyMarkdown`).
+ */
+function formatWikiLinkBody(node) {
+    const value = node.value ?? '';
+    const data = node.data && typeof node.data === 'object' ? node.data : {};
+    const blockId = typeof data.blockId === 'string' && data.blockId.length > 0 ? data.blockId : null;
+    const target = blockId ? `${value}#^${blockId}` : value;
+    const alias = typeof data.alias === 'string' ? data.alias : '';
+    const hasAlias = alias.length > 0 && alias !== value;
+    const emptyAlias = data._emptyAlias === true;
+    const divider = wikiLinkOptions.aliasDivider;
+    const aliasPart = hasAlias ? `${divider}${alias}` : emptyAlias ? divider : '';
+    return `${target}${aliasPart}`;
+}
 export function stringifyMarkdown(root, options = {}) {
     // Pre-process: add checkbox text to ordered list items (GFM only outputs for unordered)
     let processedRoot = addCheckboxTextToOrderedLists(root);
@@ -327,15 +348,19 @@ export function stringifyMarkdown(root, options = {}) {
                         return marker + content + marker;
                     },
                     escapedChar: (node) => `${FORCE_ESCAPE_PLACEHOLDER}${node.value}${FORCE_ESCAPE_PLACEHOLDER}`,
-                    wikiLink: (node) => {
-                        const value = node.value ?? '';
-                        const data = node.data && typeof node.data === 'object' ? node.data : {};
-                        const alias = typeof data.alias === 'string' ? data.alias : '';
-                        const hasAlias = alias.length > 0 && alias !== value;
-                        const emptyAlias = data._emptyAlias === true;
-                        const aliasPart = hasAlias ? `${wikiLinkOptions.aliasDivider}${alias}` : emptyAlias ? `${wikiLinkOptions.aliasDivider}` : '';
-                        return `[[${value}${aliasPart}]]`;
-                    },
+                    // Block anchor badge (#122): a `blockAnchor` node produced by
+                    // `splitBlockAnchors` in parse.ts always carries exactly the id
+                    // matched from the source, so re-emitting `^id` is lossless by
+                    // construction — no escaping needed, mirroring `wikiLink`/`wikiEmbed`.
+                    blockAnchor: (node) => `^${node.id}`,
+                    wikiLink: (node) => `[[${formatWikiLinkBody(node)}]]`,
+                    // Transclusion/embed (#119): the `!`-prefixed form of a block-scoped
+                    // wiki-link. `formatWikiLinkBody` requires `data.blockId` be present
+                    // to have been produced by `resolveWikiEmbeds` in parse.ts in the
+                    // first place (FR-013 never lets a blockId-less node reach this
+                    // type), but nothing here depends on that — this handler just emits
+                    // whatever the node carries, `!` and all.
+                    wikiEmbed: (node) => `![[${formatWikiLinkBody(node)}]]`,
                     // Override mdast-util-definition-list's default (`:` + 3 spaces, i.e. a
                     // 4-char marker matching a 4-space continuation indent) with the
                     // single-space `: ` marker convention used throughout PHP Markdown

package/dist/markdown/vendor/mdast-util-wiki-link/README.md

@@ -37,5 +37,22 @@ upstream pulled in.
 
 3. **Types.** The `any`-typed option and node shapes are given real types.
 
+4. **`#^blockId` fragment splitting (#119).** `from-markdown.ts` splits a
+   trailing `#^blockId` fragment off the target into `data.blockId` before
+   `pageResolver` runs, so `data.permalink`/`data.exists` are computed from
+   the file target alone; `to-markdown.ts` re-appends it on the way back out.
+   An ordinary heading anchor (`[[file#heading]]`, no caret) is untouched —
+   only the caret-prefixed Obsidian block-reference form matches. This is
+   deliberately scoped to the `wikiLink` node shape only: the `!`-prefixed
+   transclusion/embed form (`![[file#^id]]`) is *not* handled here — that
+   detection lives in `src/markdown/parse.ts`/`stringify.ts` (a same-length
+   sentinel substitution around the unvendored micromark tokenizer, since a
+   leading `!` before `[[` today makes the *whole* `![[...]]` span fall back
+   to inert text — see the tokenizer's `text: {33: ...}` image-label
+   precedence). A raw `./markdown`-subpath consumer therefore gets
+   `data.blockId` for free but not embed/transclusion detection; this
+   asymmetry is deliberate (documented in `docs/markdown-pipeline.md`) rather
+   than duplicating the sentinel machinery into a second vendored package.
+
 Parse and serialize behaviour is otherwise unchanged. Parity is covered by
 `src/markdown/__tests__/vendor-wiki-link.test.ts`.