@liminis/editor 0.4.1 → 0.6.0

package/dist/app/editor/nodes/transclusion-render.js

@@ -0,0 +1,186 @@
+/**
+ * Pure, host-resolver-driven resolution and rendering for block transclusion
+ * (`![[file#^id]]`, #119). Split out from `TransclusionComponent.tsx` so the
+ * cycle/depth guard and the mdast->JSX mini renderer are unit-testable
+ * without mounting Lexical or React.
+ *
+ * Not a second `LexicalComposer`: transclusion is render-only (bidirectional
+ * editing of transcluded content is explicitly out of scope), so resolved
+ * block content is parsed once with the existing `parseMarkdown` and walked
+ * into plain React elements by a small dedicated renderer here, rather than
+ * mounting a second editable surface.
+ */
+import { createElement, Fragment } from 'react';
+import { parseMarkdown } from '../../../markdown/parse.js';
+/**
+ * Nested transclusion depth bound (FR-011). A Plan-stage numeric choice, not
+ * derived from anything structural — deep enough that legitimate nesting
+ * (a summary block quoting a handful of sub-tasks, one level each) never
+ * hits it, shallow enough that a missed-cycle edge case still terminates
+ * fast. Checked *before* the resolver call at each level, so a document
+ * that would exceed it never spends host I/O on content that gets discarded.
+ */
+export const MAX_TRANSCLUSION_DEPTH = 8;
+function blockKey(file, blockId) {
+    return `${file}#^${blockId}`;
+}
+/**
+ * Resolve a `file#^blockId` reference to rendered content, guarding against
+ * cycles and unbounded nesting.
+ *
+ * `visitedPath` is the chain of `file#^blockId` keys already open on *this*
+ * branch of the resolution tree (ancestors, not a single global "already
+ * transcluded anywhere" set) — the same block transcluded from two unrelated
+ * sites in the same document must not falsely trip the cycle guard for the
+ * second site.
+ */
+export async function resolveAndRenderTransclusion(file, blockId, resolver, visitedPath = []) {
+    const key = blockKey(file, blockId);
+    if (visitedPath.includes(key)) {
+        return { kind: 'circular' };
+    }
+    if (visitedPath.length >= MAX_TRANSCLUSION_DEPTH) {
+        return { kind: 'depth-exceeded' };
+    }
+    if (!resolver) {
+        return { kind: 'unresolved' };
+    }
+    let raw;
+    try {
+        raw = await resolver(file, blockId);
+    }
+    catch {
+        // FR-009: a resolver that throws is treated the same as one that
+        // couldn't resolve — never let a host's rejected promise escape as an
+        // unhandled error into the editor.
+        raw = null;
+    }
+    if (raw === null || raw === undefined || typeof raw !== 'string') {
+        // The `typeof` guard is load-bearing, not defensive padding: a resolver
+        // that violates its own `Promise<string | null>` contract (returns a
+        // number/object/etc.) must still degrade to "unresolved" rather than
+        // reaching `parseMarkdown` with a non-string and throwing.
+        return { kind: 'unresolved' };
+    }
+    try {
+        const { root } = parseMarkdown(raw);
+        const nextVisitedPath = [...visitedPath, key];
+        const content = await renderNodes(root.children, resolver, nextVisitedPath);
+        return { kind: 'resolved', content: createElement(Fragment, null, ...content) };
+    }
+    catch {
+        // Never let a parse/render failure on resolved content escape as an
+        // unhandled error into the editor — same "never throw" invariant as the
+        // resolver-rejection guard above.
+        return { kind: 'unresolved' };
+    }
+}
+/** Render a {@link TransclusionRenderState} to a React node, for both the
+ * top-level `TransclusionComponent` and a nested `wikiEmbed` inside
+ * resolved content — the two share the same visual vocabulary. */
+export function renderTransclusionState(state) {
+    switch (state.kind) {
+        case 'resolved':
+            return createElement('span', { className: 'editor-transclusion-content' }, state.content);
+        case 'unresolved':
+            return createElement('span', { className: 'editor-transclusion-unresolved', title: 'This block could not be found.' }, 'Unresolved block reference');
+        case 'circular':
+            return createElement('span', { className: 'editor-transclusion-circular', title: 'This block transcludes itself.' }, 'Circular transclusion');
+        case 'depth-exceeded':
+            return createElement('span', { className: 'editor-transclusion-depth-exceeded', title: 'Transclusion nested too deeply.' }, 'Transclusion nested too deeply');
+    }
+}
+async function renderNodes(nodes, resolver, visitedPath) {
+    const rendered = await Promise.all(nodes.map((node, index) => renderNode(node, resolver, visitedPath, index)));
+    return rendered;
+}
+/**
+ * Renders the subset of mdast node types the spec's own example (a checkbox
+ * action item, plain prose, a nested transclusion) needs, plus common inline
+ * formatting. Anything else falls back to plain extracted text — a
+ * deliberate v1 scope limit (see the Plan's "lightweight renderer" risk
+ * note), not a gap to silently paper over: this must never crash on
+ * arbitrary block content (FR-015 lets *any* `^id`-carrying block be a
+ * target, not just the checkbox shape the host emits today).
+ */
+async function renderNode(node, resolver, visitedPath, key) {
+    const n = node;
+    if (!n || typeof n.type !== 'string') {
+        return null;
+    }
+    switch (n.type) {
+        case 'root':
+        case 'paragraph': {
+            const children = await renderNodes(n.children ?? [], resolver, visitedPath);
+            return createElement('span', { key, className: 'editor-transclusion-paragraph' }, ...children);
+        }
+        case 'text':
+            return n.value ?? '';
+        case 'strong': {
+            const children = await renderNodes(n.children ?? [], resolver, visitedPath);
+            return createElement('strong', { key }, ...children);
+        }
+        case 'emphasis': {
+            const children = await renderNodes(n.children ?? [], resolver, visitedPath);
+            return createElement('em', { key }, ...children);
+        }
+        case 'delete': {
+            const children = await renderNodes(n.children ?? [], resolver, visitedPath);
+            return createElement('del', { key }, ...children);
+        }
+        case 'inlineCode':
+            return createElement('code', { key }, n.value ?? '');
+        case 'break':
+            return createElement('br', { key });
+        case 'heading': {
+            const children = await renderNodes(n.children ?? [], resolver, visitedPath);
+            return createElement('strong', { key, className: 'editor-transclusion-heading' }, ...children);
+        }
+        case 'list': {
+            const children = await renderNodes(n.children ?? [], resolver, visitedPath);
+            return createElement('span', { key, className: 'editor-transclusion-list' }, ...children);
+        }
+        case 'listItem': {
+            const children = await renderNodes(n.children ?? [], resolver, visitedPath);
+            const checked = n.checked;
+            if (checked === true || checked === false) {
+                return createElement('span', { key, className: 'editor-transclusion-list-item' }, createElement('input', { type: 'checkbox', checked, readOnly: true, disabled: true }), ' ', ...children);
+            }
+            return createElement('span', { key, className: 'editor-transclusion-list-item' }, '• ', ...children);
+        }
+        case 'wikiEmbed': {
+            const target = n.value ?? '';
+            const data = n.data;
+            const blockId = data?.blockId;
+            if (!blockId) {
+                // Never produced by parseMarkdown (FR-013 keeps a blockId-less node
+                // typed `wikiLink`), but a hand-built mdast tree from a resolver
+                // could still lack one — degrade to plain text rather than crash.
+                return extractPlainText(n);
+            }
+            const nested = await resolveAndRenderTransclusion(target, blockId, resolver, visitedPath);
+            return createElement('span', { key }, renderTransclusionState(nested));
+        }
+        case 'wikiLink': {
+            // A link-only reference inside transcluded content: render its label
+            // as inert text. Live navigation from inside a transclusion is out of
+            // scope (this is a read-only render, not a second editable surface).
+            const data = n.data;
+            return data?.alias || n.value || '';
+        }
+        default:
+            return extractPlainText(n);
+    }
+}
+/** Generic fallback: recursively join every `.value` string found, so an
+ * unrecognized node type still shows *something* rather than nothing. */
+function extractPlainText(node) {
+    const n = node;
+    if (!n)
+        return '';
+    if (typeof n.value === 'string')
+        return n.value;
+    if (Array.isArray(n.children))
+        return n.children.map(extractPlainText).join('');
+    return '';
+}

package/dist/app/mapper/lexicalToMdast.js

@@ -5,7 +5,7 @@ import { $isCodeNode } from '@lexical/code';
 import { $isLinkNode } from '@lexical/link';
 import { $isMarkNode } from '@lexical/mark';
 import { $isTableNode, $isTableRowNode, $isTableCellNode } from '@lexical/table';
-import { $isHorizontalRuleNode, $isImageNode, $isCalloutNode, $isToggleContainerNode, $isToggleTitleNode, $isToggleContentNode, $isEquationNode, $isMermaidNode, $isC4Node, $isFrontmatterNode, $isFootnoteNode, $isCustomListNode, $isDefinitionListNode, $isDefinitionTermNode, $isDefinitionDescriptionNode, $isCustomListItemNode, $isHtmlNode, $isListItemParagraphBreakNode, } from '../editor/nodes/index.js';
+import { $isHorizontalRuleNode, $isImageNode, $isCalloutNode, $isToggleContainerNode, $isToggleTitleNode, $isToggleContentNode, $isEquationNode, $isMermaidNode, $isC4Node, $isFrontmatterNode, $isFootnoteNode, $isBlockAnchorNode, $isCustomListNode, $isDefinitionListNode, $isDefinitionTermNode, $isDefinitionDescriptionNode, $isCustomListItemNode, $isHtmlNode, $isListItemParagraphBreakNode, $isTransclusionNode, } from '../editor/nodes/index.js';
 import { SENTINEL_CLOSE_END, SENTINEL_CLOSE_START, SENTINEL_OPEN_END, SENTINEL_OPEN_START, stripAnnotateSentinels, } from '../../markdown/annotate-sentinels.js';
 // Convert Lexical editor state to mdast tree
 export function exportLexicalToMdast(editor, options = {}) {
@@ -231,16 +231,23 @@ function markPhrasingContext(mark) {
 }
 /**
  * An inline node that emits markdown syntax of its own around (or instead of)
- * text — a link, wiki link, image, inline equation, footnote reference or
- * inline HTML. When one of these is a mark's own child it is *wholly* inside
- * that mark by construction, so the mark's boundary token belongs outside the
- * whole construct rather than inside its text.
+ * text — a link, wiki link, image, inline equation, footnote reference,
+ * inline HTML, or transclusion embed (#119). When one of these is a mark's
+ * own child it is *wholly* inside that mark by construction, so the mark's
+ * boundary token belongs outside the whole construct rather than inside its
+ * text.
  *
  * Line breaks are excluded deliberately: they carry no syntax a boundary can
  * fall inside, and today's leaf walk skips straight past them.
  */
 function isHoistableConstruct(node) {
-    return $isLinkNode(node) || $isImageNode(node) || $isEquationNode(node) || $isFootnoteNode(node) || $isHtmlNode(node);
+    return ($isLinkNode(node) ||
+        $isImageNode(node) ||
+        $isEquationNode(node) ||
+        $isFootnoteNode(node) ||
+        $isBlockAnchorNode(node) ||
+        $isHtmlNode(node) ||
+        $isTransclusionNode(node));
 }
 /**
  * Inclusive bounds of the maximal run of consecutive siblings in `flat` that
@@ -371,26 +378,32 @@ function canCarryHoistedTokens(parent) {
  * The same question asked of the *construct* rather than its container, because
  * one container routes its children unevenly.
  *
- * `convertListItemNode` sends only text runs, line breaks and links through the
- * inline phrasing path; every other child goes to the block dispatcher, which
- * has nowhere to put a phrasing token. Hoisting a boundary onto one of those
- * would drop the token silently, and `locateLiveMarkdownRange` would then fail
- * to find the mark at all.
+ * `convertListItemNode` sends only text runs, line breaks, links and block
+ * anchors through the inline phrasing path; every other child goes to the
+ * block dispatcher, which has nowhere to put a phrasing token. Hoisting a
+ * boundary onto one of those would drop the token silently, and
+ * `locateLiveMarkdownRange` would then fail to find the mark at all.
  *
- * No document reaches that state today, which is why this is a guard rather
- * than a fix: an image, inline equation, footnote reference or inline HTML
- * inside a list item is *itself* block-promoted by that same dispatcher, so it
- * does not survive a round trip inline (`- The value $x^2$ matters` exports as
- * three blocks) and any range over it is already rejected by
- * `locateLiveMarkdownRange`'s slice check. Repairing that unrelated,
- * pre-existing round-trip defect must not silently regress annotation ranges as
- * its side effect.
+ * No document reaches that state today for the remaining types, which is why
+ * this is a guard rather than a fix: an image, inline equation, footnote
+ * reference or inline HTML inside a list item is *itself* block-promoted by
+ * that same dispatcher, so it does not survive a round trip inline (`- The
+ * value $x^2$ matters` exports as three blocks) and any range over it is
+ * already rejected by `locateLiveMarkdownRange`'s slice check. Repairing that
+ * unrelated, pre-existing round-trip defect must not silently regress
+ * annotation ranges as its side effect.
+ *
+ * Block anchors are the one exception (#122): `- [ ] ... ^ULID` is the
+ * primary real-world shape this issue targets, so `convertListItemNode` keeps
+ * a `BlockAnchorNode` inline rather than letting it fall to the block
+ * dispatcher — see the `$isBlockAnchorNode` branch there — and a hoisted
+ * boundary onto one genuinely does reach the output.
  */
 function hoistedTokenReachesOutput(node) {
     let parent = node.getParent();
     while (parent && $isMarkNode(parent))
         parent = parent.getParent();
-    return $isListItemNode(parent) ? $isLinkNode(node) : true;
+    return $isListItemNode(parent) ? ($isLinkNode(node) || $isBlockAnchorNode(node)) : true;
 }
 /**
  * The node a mark's boundary token should be emitted outside of, or null to
@@ -710,6 +723,9 @@ function convertFootnoteInlineChildren(labelNode) {
                 label: child.getFootnoteId(),
             });
         }
+        else if ($isBlockAnchorNode(child)) {
+            contentChildren.push({ type: 'blockAnchor', id: child.getId() });
+        }
         contentChildren.push(...hoistedTokenNodesFor(child, 'after'));
         restIndex++;
         child = rest[restIndex] ?? null;
@@ -790,6 +806,14 @@ function convertLexicalNode(node) {
     if ($isHtmlNode(node)) {
         return [{ type: 'html', value: node.getHtml() }];
     }
+    if ($isTransclusionNode(node)) {
+        // TransclusionNode is inline (#119) and is always constructed as a
+        // paragraph's child by mdastToLexical.ts; reached here only if it
+        // somehow ends up as a direct block-level child (e.g. a paste-driven
+        // DOM import) — wrap it in a paragraph rather than losing it, mirroring
+        // convertEquationNode's inline-equation branch above.
+        return [{ type: 'paragraph', children: [convertTransclusionNode(node)] }];
+    }
     // Fallback: create paragraph
     const paragraph = {
         type: 'paragraph',
@@ -953,6 +977,30 @@ function convertListItemNode(node, _ordered, spread) {
             // be emitted here too.
             inlineChildren.push(...hoistedTokenNodesFor(child, 'before'), convertLinkNode(child), ...hoistedTokenNodesFor(child, 'after'));
         }
+        else if ($isBlockAnchorNode(child)) {
+            // A block anchor sitting directly under a ListItemNode — the primary
+            // real-world shape this issue targets (`- [ ] ... ^ULID`, #122) — must
+            // stay inline rather than fall to the block dispatcher below: unlike
+            // image/equation/footnote/html (a documented, pre-existing gap this
+            // issue does not touch — see `hoistedTokenReachesOutput`'s docstring),
+            // a dropped anchor here would break the checkbox-action-item pattern
+            // the spec calls out as the primary usage.
+            //
+            // Unlike the $isLinkNode branch above, a link's format lives on its
+            // text children (applied on import via applyFormatToLinkChildren), but
+            // a BlockAnchorNode carries its own format bits directly (like
+            // FootnoteNode/EquationNode) — so they must be wrapped here explicitly,
+            // the same way the general inline path does via getMergeableFormat +
+            // buildFormattedContent, or a bold/italic badge would silently lose its
+            // markers on export.
+            flushTextRun();
+            const anchorMdast = { type: 'blockAnchor', id: child.getId() };
+            const format = getMergeableFormat(child) ?? 0;
+            const anchorContent = format
+                ? wrapWithFormat([anchorMdast], format, child.getStrongMarker(), child.getEmphasisMarker())
+                : anchorMdast;
+            inlineChildren.push(...hoistedTokenNodesFor(child, 'before'), anchorContent, ...hoistedTokenNodesFor(child, 'after'));
+        }
         else {
             // Any other block-type child (ParagraphNode, CodeNode, TableNode,
             // QuoteNode, etc.) — flush accumulated inline text first, then delegate
@@ -1290,7 +1338,7 @@ function getMergeableFormat(child) {
     if ($isTextNode(child)) {
         return child.getFormat() & MERGEABLE_FORMAT_MASK;
     }
-    if ($isEquationNode(child) || $isFootnoteNode(child)) {
+    if ($isEquationNode(child) || $isFootnoteNode(child) || $isBlockAnchorNode(child)) {
         return child.getFormat() & MERGEABLE_FORMAT_MASK;
     }
     return null;
@@ -1334,12 +1382,44 @@ function convertSingleInlineChild(child) {
                 label: child.getFootnoteId(),
             }];
     }
+    else if ($isBlockAnchorNode(child)) {
+        // Block anchor badge (#122): convert back to a blockAnchor mdast node
+        return [{ type: 'blockAnchor', id: child.getId() }];
+    }
     else if ($isHtmlNode(child)) {
         // Inline HTML preserved opaquely: convert back to a phrasing html mdast node
         return [{ type: 'html', value: child.getHtml() }];
     }
+    else if ($isTransclusionNode(child)) {
+        // Transclusion embed (#119): convert back to a wikiEmbed mdast node
+        return [convertTransclusionNode(child)];
+    }
     return [];
 }
+/**
+ * Convert a `TransclusionNode` back to a `wikiEmbed` mdast node.
+ *
+ * `alias`/`_emptyAlias` are carried purely for byte-identical round-trip
+ * (FR-003) — read directly off the node's own explicit fields rather than
+ * inferred from any rendered text, since an embed never displays its alias
+ * (see `mdastToLexical.ts`'s `$createTransclusionNodeFromMdast` for the
+ * matching import-side reasoning).
+ */
+function convertTransclusionNode(node) {
+    const alias = node.getAlias();
+    const data = { blockId: node.getBlockId() };
+    if (alias) {
+        data.alias = alias;
+    }
+    else if (node.getEmptyAlias()) {
+        data._emptyAlias = true;
+    }
+    return {
+        type: 'wikiEmbed',
+        value: node.getFile(),
+        data,
+    };
+}
 // Flattens a list of leaf-level inline nodes into mdast content with no
 // format wrapping — the base case once every bold/italic/strikethrough bit
 // a run carries has been consumed by an enclosing wrapper.
@@ -1389,6 +1469,10 @@ function convertLeavesRaw(nodes) {
                 label: node.getFootnoteId(),
             });
         }
+        else if ($isBlockAnchorNode(node)) {
+            flushCode();
+            content.push({ type: 'blockAnchor', id: node.getId() });
+        }
     }
     flushCode();
     return content;
@@ -1415,7 +1499,7 @@ function resolveMarkers(nodes) {
             strongMarker = strongMarker ?? getMarkdownMarker(style, '--md-strong-marker');
             emphasisMarker = emphasisMarker ?? getMarkdownMarker(style, '--md-emphasis-marker');
         }
-        else if ($isEquationNode(node) || $isFootnoteNode(node)) {
+        else if ($isEquationNode(node) || $isFootnoteNode(node) || $isBlockAnchorNode(node)) {
             strongMarker = strongMarker ?? node.getStrongMarker();
             emphasisMarker = emphasisMarker ?? node.getEmphasisMarker();
         }
@@ -1795,6 +1879,9 @@ function convertLinkNode(node) {
                 label: child.getFootnoteId(),
             });
         }
+        else if ($isBlockAnchorNode(child)) {
+            children.push({ type: 'blockAnchor', id: child.getId() });
+        }
         else if ($isHtmlNode(child)) {
             children.push({ type: 'html', value: child.getHtml() });
         }
@@ -1892,6 +1979,13 @@ function convertLinkNode(node) {
         else {
             data._noAlias = true;
         }
+        // Block-scoped link (#119): carried as a field separate from `target`
+        // (never folded into the value/URL string) — see CustomLinkNode's own
+        // doc comment for why.
+        const blockId = linkNode.getBlockId?.();
+        if (blockId) {
+            data.blockId = blockId;
+        }
         return {
             type: 'wikiLink',
             value: target,

package/dist/app/mapper/mdastToLexical.js

@@ -2,7 +2,7 @@ import { $createParagraphNode, $createTextNode, $createLineBreakNode, $isLineBre
 import { $createHeadingNode, $createQuoteNode } from '@lexical/rich-text';
 import { $createCodeNode } from '@lexical/code';
 import { $isLinkNode } from '@lexical/link';
-import { $createHorizontalRuleNode, $createImageNode, $isImageNode, $createCalloutNode, $createToggleContainerNode, $createToggleTitleNode, $createToggleContentNode, $createEquationNode, $isEquationNode, $createFootnoteNode, $isFootnoteNode, $createHtmlNode, $isHtmlNode, $createMermaidNode, $createC4Node, $createFrontmatterNode, $createCustomLinkNode, $createCustomListNode, $createDefinitionListNode, $createDefinitionTermNode, $createDefinitionDescriptionNode, $createCustomListItemNode, $createListItemParagraphBreakNode, } from '../editor/nodes/index.js';
+import { $createHorizontalRuleNode, $createImageNode, $isImageNode, $createCalloutNode, $createToggleContainerNode, $createToggleTitleNode, $createToggleContentNode, $createEquationNode, $isEquationNode, $createFootnoteNode, $isFootnoteNode, $createBlockAnchorNode, $isBlockAnchorNode, $createHtmlNode, $isHtmlNode, $createMermaidNode, $createC4Node, $createFrontmatterNode, $createCustomLinkNode, $createCustomListNode, $createDefinitionListNode, $createDefinitionTermNode, $createDefinitionDescriptionNode, $createCustomListItemNode, $createListItemParagraphBreakNode, $createTransclusionNode, } from '../editor/nodes/index.js';
 import { parseFormattedAlias } from '../editor/MarkdownShortcutsPlugin.js';
 import { $createTableNode, $createTableRowNode, $createTableCellNode, TableCellHeaderStates } from '@lexical/table';
 import { getFileType } from '../../utils/file-types.js';
@@ -275,6 +275,9 @@ function convertBlockNode(node) {
             const paragraph = $createParagraphNode();
             const link = $createCustomLinkNode(url);
             link.setWikiLinkOrigin(true);
+            if (wikiLink.data?.blockId) {
+                link.setBlockId(wikiLink.data.blockId);
+            }
             // Parse format markers in alias (e.g., **bold**, *italic*, ~~strike~~)
             const { text: plainText, formats } = parseFormattedAlias(rawDisplayText);
             const textNode = $createTextNode(plainText);
@@ -285,6 +288,27 @@ function convertBlockNode(node) {
             paragraph.append(link);
             return [paragraph];
         }
+        case 'wikiEmbed': {
+            // Transclusion/embed appearing at block level (shouldn't happen — a
+            // `wikiEmbed` is phrasing content, mirroring `wikiLink`/`image` — but
+            // handle gracefully; wrap in a paragraph, matching the wikiLink case above).
+            const wikiEmbed = node;
+            const paragraph = $createParagraphNode();
+            const target = wikiEmbed.value || '';
+            const blockId = wikiEmbed.data?.blockId;
+            if (target && blockId) {
+                paragraph.append($createTransclusionNodeFromMdast(target, blockId, wikiEmbed.data));
+            }
+            else {
+                // Malformed (missing target or blockId): degrade to inert text
+                // rather than an empty paragraph, which would silently drop the
+                // original content — same reasoning as the inline `wikiEmbed` case.
+                console.warn('[mdastToLexical] block-level wikiEmbed missing target or blockId:', wikiEmbed);
+                const fragment = blockId ? `${target}#^${blockId}` : target;
+                paragraph.append($createTextNode(`![[${fragment}]]`));
+            }
+            return [paragraph];
+        }
         case 'footnoteDefinition': {
             // Footnote definition: render as indented paragraphs with superscript label.
             // On export, lexicalToMdast detects this pattern (indent=1, starts with FootnoteNode)
@@ -768,6 +792,22 @@ function convertToggleMarker(marker) {
     container.append(content);
     return [container];
 }
+/**
+ * Build a `TransclusionNode` from a `wikiEmbed` mdast node's `value`/`data`,
+ * shared by the block-level (defensive) and inline `wikiEmbed` cases below.
+ *
+ * `alias`/`_emptyAlias` are carried purely for byte-identical round-trip
+ * (#119, FR-003) — an embed never *displays* its alias text (it renders the
+ * resolved block's live content instead), so unlike `wikiLink` there is no
+ * rendered text to infer "was there an alias" from on export; the flag has
+ * to be stored explicitly on the node.
+ */
+function $createTransclusionNodeFromMdast(target, blockId, data) {
+    const rawAlias = data?.alias;
+    const emptyAlias = data?._emptyAlias === true;
+    const hasAlias = typeof rawAlias === 'string' && rawAlias.length > 0 && rawAlias !== target;
+    return $createTransclusionNode(target, blockId, hasAlias ? rawAlias : null, emptyAlias);
+}
 function convertInlineNode(node) {
     // Defensive: handle null/undefined nodes
     if (!node?.type) {
@@ -805,6 +845,12 @@ function convertInlineNode(node) {
             const fnRef = node;
             return [$createFootnoteNode(fnRef.identifier)];
         }
+        case 'blockAnchor': {
+            // Block anchor badge (#122): render `^ULID` as a compact badge instead
+            // of raw text, using BlockAnchorNode to preserve the id for round-trip.
+            const anchor = node;
+            return [$createBlockAnchorNode(anchor.id)];
+        }
         case 'wikiLink': {
             // Wiki-links from mdast-util-wiki-link: [[path|alias]]
             const wikiLink = node;
@@ -849,6 +895,12 @@ function convertInlineNode(node) {
             // (convertLinkNode) always emits it back as a wiki-link even when a host
             // has disabled promotion of ordinary links (liminis#951).
             link.setWikiLinkOrigin(true);
+            // Block-scoped link (#119): carried as a field separate from `url` so
+            // it never inherits the lossy `.md#`-anchor URL-string round trip the
+            // plain heading-anchor branches above use.
+            if (wikiLink.data?.blockId) {
+                link.setBlockId(wikiLink.data.blockId);
+            }
             // Preserve empty-alias state for round-trip
             if (wikiLink.data?._emptyAlias) {
                 link.setWikiAliasState('empty');
@@ -862,6 +914,26 @@ function convertInlineNode(node) {
             link.append(textNode);
             return [link];
         }
+        case 'wikiEmbed': {
+            // Transclusion/embed from parse.ts's embed-sentinel post-process: `![[file#^id]]`
+            const wikiEmbed = node;
+            const target = wikiEmbed.value;
+            const blockId = wikiEmbed.data?.blockId;
+            // Never produced by parseMarkdown without both (FR-002/FR-013 guarantee
+            // a `wikiEmbed` always carries a file target and a blockId), but a
+            // hand-built mdast tree from an external `./markdown` consumer could
+            // still lack one — degrade to inert text rather than crash (FR-008's
+            // "never throw" spirit applies just as much to malformed input as to a
+            // missing resolver). Reconstructs whatever of the original syntax is
+            // available rather than dropping the content: a blank node would
+            // silently erase user-visible text for no parser-level reason.
+            if (!target || !blockId) {
+                console.warn('[mdastToLexical] wikiEmbed missing target or blockId:', wikiEmbed);
+                const fragment = blockId ? `${target ?? ''}#^${blockId}` : (target ?? '');
+                return [$createTextNode(`![[${fragment}]]`)];
+            }
+            return [$createTransclusionNodeFromMdast(target, blockId, wikiEmbed.data)];
+        }
         case 'html': {
             // Check for inline equation: $...$
             const html = node.value;
@@ -925,7 +997,7 @@ function convertStrong(node) {
                 applyFormatToLinkChildren(n, 'bold', marker);
                 nodes.push(n);
             }
-            else if ($isEquationNode(n) || $isFootnoteNode(n)) {
+            else if ($isEquationNode(n) || $isFootnoteNode(n) || $isBlockAnchorNode(n)) {
                 if (!n.hasFormat('bold')) {
                     n.toggleFormat('bold');
                 }
@@ -960,7 +1032,7 @@ function convertEmphasis(node) {
                 applyFormatToLinkChildren(n, 'italic', marker);
                 nodes.push(n);
             }
-            else if ($isEquationNode(n) || $isFootnoteNode(n)) {
+            else if ($isEquationNode(n) || $isFootnoteNode(n) || $isBlockAnchorNode(n)) {
                 if (!n.hasFormat('italic')) {
                     n.toggleFormat('italic');
                 }
@@ -1059,7 +1131,7 @@ function convertDelete(node) {
                 applyFormatToLinkChildren(n, 'strikethrough');
                 nodes.push(n);
             }
-            else if ($isEquationNode(n) || $isFootnoteNode(n)) {
+            else if ($isEquationNode(n) || $isFootnoteNode(n) || $isBlockAnchorNode(n)) {
                 if (!n.hasFormat('strikethrough')) {
                     n.toggleFormat('strikethrough');
                 }

package/dist/host/defaults.js

@@ -43,5 +43,6 @@ export function resolveHostServices(services) {
         resolveWikiLinks: services?.resolveWikiLinks,
         onScrollToAnchor: services?.onScrollToAnchor,
         corrections: services?.corrections,
+        resolveTransclusion: services?.resolveTransclusion,
     };
 }

package/dist/host/messages.d.ts

@@ -19,7 +19,13 @@ export interface HostMessageApi {
     requestSettings: () => void;
     applyTextEdits: (edits: TextEdit[], reason: 'typing' | 'drag' | 'paste' | 'format') => void;
     writeAsset: (dataUri: string, suggestedName?: string) => void;
-    openLink: (url: string) => void;
+    /**
+     * `blockId` is additive (#119): a host that hasn't implemented block-aware
+     * navigation still receives `url` and opens the file exactly as before —
+     * FR-004's "degrades no worse than today's file-only wikilink navigation"
+     * falls out for free, with no host-side change required.
+     */
+    openLink: (url: string, blockId?: string) => void;
 }
 export declare function createHostMessageApi(bridge: EditorHostBridge, log: EditorLogger): HostMessageApi;
 /** Hook form of {@link createHostMessageApi}, bound to the ambient host services. */

package/dist/host/messages.js

@@ -31,9 +31,9 @@ export function createHostMessageApi(bridge, log) {
         writeAsset: (dataUri, suggestedName) => {
             postMessage({ type: 'WRITE_ASSET', dataUri, suggestedName });
         },
-        openLink: (url) => {
-            log.debug('openLink', { url });
-            postMessage({ type: 'OPEN_LINK', url });
+        openLink: (url, blockId) => {
+            log.debug('openLink', { url, blockId });
+            postMessage(blockId ? { type: 'OPEN_LINK', url, blockId } : { type: 'OPEN_LINK', url });
         },
     };
 }

package/dist/host/types.d.ts

@@ -70,6 +70,19 @@ export interface EditorHostServices {
     notifyError?: (message: string, description?: string) => void;
     /** Correction persistence + knowledge-graph services. */
     corrections?: CorrectionHostServices;
+    /**
+     * Resolve a workspace-global block reference (`file#^blockId`, #119) to
+     * that block's current markdown content. Backs both transclusion
+     * (`![[file#^id]]`) and existence-checking for block-scoped links
+     * (`[[file#^id]]`) — see `TransclusionComponent`/`WikiLinkExistencePlugin`.
+     *
+     * Returns `null` when the file or block id does not resolve (FR-009); the
+     * two are not distinguished here — a host that cares to tell them apart
+     * can encode that in its own lookup, but the contract only needs
+     * resolved-vs-not. Absent entirely (the default), transclusion renders an
+     * "unresolved" placeholder rather than throwing (FR-008).
+     */
+    resolveTransclusion?: (file: string, blockId: string) => Promise<string | null>;
 }
 /** `EditorHostServices` with every member resolved to a concrete implementation. */
-export type ResolvedEditorHostServices = Required<Pick<EditorHostServices, 'bridge' | 'logger' | 'notifyError'>> & Pick<EditorHostServices, 'resolveWikiLinks' | 'onScrollToAnchor' | 'corrections'>;
+export type ResolvedEditorHostServices = Required<Pick<EditorHostServices, 'bridge' | 'logger' | 'notifyError'>> & Pick<EditorHostServices, 'resolveWikiLinks' | 'onScrollToAnchor' | 'corrections' | 'resolveTransclusion'>;