@liminis/editor 0.4.0 → 0.5.0

package/dist/app/editor/nodes/TransclusionNode.js

@@ -0,0 +1,141 @@
+/* eslint-disable react-refresh/only-export-components */
+/**
+ * TransclusionNode - Live-rendered block transclusion (`![[file#^id]]`, #119)
+ *
+ * An **inline** DecoratorNode, unlike the block-level `MermaidNode`: a
+ * `wikiEmbed` mdast node is phrasing content (same family as `wikiLink`/
+ * `image`), so this matches where it actually sits in the tree rather than
+ * forcing paragraph-promotion logic to accommodate it.
+ *
+ * `file`/`blockId` are the sole identity the node carries; `alias` is stored
+ * only for byte-identical round-trip (`![[file#^id|alias]]`) — an embed
+ * renders the resolved block's *live content*, never the alias text, so
+ * nothing here displays it. Content resolution is async and host-resolver-
+ * driven (see `transclusion-render.tsx`), so — mirroring `MermaidNode` — the
+ * actual resolver call happens inside the lazily-loaded `TransclusionComponent`
+ * at decorate-time, not here: this node is a static, serializable value.
+ */
+import { DecoratorNode, $applyNodeReplacement, } from 'lexical';
+import { createElement, lazy, Suspense } from 'react';
+import { renderTransclusionLoading } from './transclusion-loading.js';
+const TransclusionComponent = lazy(() => import('./TransclusionComponent.js'));
+function $convertTransclusionElement(domNode) {
+    const file = domNode.getAttribute('data-lexical-transclusion-file');
+    const blockId = domNode.getAttribute('data-lexical-transclusion-block-id');
+    if (file && blockId) {
+        const alias = domNode.getAttribute('data-lexical-transclusion-alias');
+        const emptyAlias = domNode.getAttribute('data-lexical-transclusion-empty-alias') === 'true';
+        const node = $createTransclusionNode(file, blockId, alias, emptyAlias);
+        return { node };
+    }
+    return null;
+}
+export class TransclusionNode extends DecoratorNode {
+    __file;
+    __blockId;
+    __alias;
+    __emptyAlias;
+    static getType() {
+        return 'transclusion';
+    }
+    static clone(node) {
+        return new TransclusionNode(node.__file, node.__blockId, node.__alias, node.__emptyAlias, node.__key);
+    }
+    constructor(file, blockId, alias = null, emptyAlias = false, key) {
+        super(key);
+        this.__file = file;
+        this.__blockId = blockId;
+        this.__alias = alias;
+        this.__emptyAlias = emptyAlias;
+    }
+    static importJSON(serializedNode) {
+        return $createTransclusionNode(serializedNode.file, serializedNode.blockId, serializedNode.alias, serializedNode.emptyAlias);
+    }
+    exportJSON() {
+        return {
+            type: 'transclusion',
+            version: 1,
+            file: this.__file,
+            blockId: this.__blockId,
+            alias: this.__alias,
+            emptyAlias: this.__emptyAlias,
+        };
+    }
+    createDOM() {
+        const element = document.createElement('span');
+        element.className = 'editor-transclusion';
+        return element;
+    }
+    exportDOM() {
+        const element = document.createElement('span');
+        element.setAttribute('data-lexical-transclusion-file', this.__file);
+        element.setAttribute('data-lexical-transclusion-block-id', this.__blockId);
+        if (this.__alias !== null) {
+            element.setAttribute('data-lexical-transclusion-alias', this.__alias);
+        }
+        if (this.__emptyAlias) {
+            element.setAttribute('data-lexical-transclusion-empty-alias', 'true');
+        }
+        element.className = 'transclusion-export';
+        // Never crash a copy/paste-shaped export by trying to resolve content
+        // synchronously (FR-008) — a plain placeholder is a faithful, inert
+        // stand-in for the live view this node otherwise renders.
+        element.textContent = renderPlaceholderText(this.__file, this.__blockId);
+        return { element };
+    }
+    static importDOM() {
+        return {
+            span: (domNode) => {
+                if (!domNode.hasAttribute('data-lexical-transclusion-file')) {
+                    return null;
+                }
+                return {
+                    conversion: $convertTransclusionElement,
+                    priority: 2,
+                };
+            },
+        };
+    }
+    updateDOM() {
+        return false;
+    }
+    isInline() {
+        return true;
+    }
+    getFile() {
+        return this.__file;
+    }
+    getBlockId() {
+        return this.__blockId;
+    }
+    getAlias() {
+        return this.__alias;
+    }
+    setAlias(alias) {
+        const writable = this.getWritable();
+        writable.__alias = alias;
+    }
+    getEmptyAlias() {
+        return this.__emptyAlias;
+    }
+    setEmptyAlias(emptyAlias) {
+        const writable = this.getWritable();
+        writable.__emptyAlias = emptyAlias;
+    }
+    decorate() {
+        return createElement(Suspense, { fallback: renderTransclusionLoading() }, createElement(TransclusionComponent, {
+            file: this.__file,
+            blockId: this.__blockId,
+            nodeKey: this.__key,
+        }));
+    }
+}
+function renderPlaceholderText(file, blockId) {
+    return `![[${file}#^${blockId}]]`;
+}
+export function $createTransclusionNode(file, blockId, alias = null, emptyAlias = false) {
+    return $applyNodeReplacement(new TransclusionNode(file, blockId, alias, emptyAlias));
+}
+export function $isTransclusionNode(node) {
+    return node instanceof TransclusionNode;
+}

package/dist/app/editor/nodes/index.d.ts

@@ -10,6 +10,8 @@ export { EquationNode, $createEquationNode, $isEquationNode } from './EquationNo
 export type { SerializedEquationNode } from './EquationNode.js';
 export { MermaidNode, $createMermaidNode, $isMermaidNode } from './MermaidNode.js';
 export type { SerializedMermaidNode } from './MermaidNode.js';
+export { TransclusionNode, $createTransclusionNode, $isTransclusionNode } from './TransclusionNode.js';
+export type { SerializedTransclusionNode } from './TransclusionNode.js';
 export { C4Node, $createC4Node, $isC4Node } from './C4Node.js';
 export type { SerializedC4Node } from './C4Node.js';
 export { FrontmatterNode, $createFrontmatterNode, $isFrontmatterNode } from './FrontmatterNode.js';

package/dist/app/editor/nodes/index.js

@@ -6,6 +6,7 @@ export { ImageNode, $createImageNode, $isImageNode } from './ImageNode.js';
 export { HorizontalRuleNode, $createHorizontalRuleNode, $isHorizontalRuleNode } from './HorizontalRuleNode.js';
 export { EquationNode, $createEquationNode, $isEquationNode } from './EquationNode.js';
 export { MermaidNode, $createMermaidNode, $isMermaidNode } from './MermaidNode.js';
+export { TransclusionNode, $createTransclusionNode, $isTransclusionNode } from './TransclusionNode.js';
 export { C4Node, $createC4Node, $isC4Node } from './C4Node.js';
 export { FrontmatterNode, $createFrontmatterNode, $isFrontmatterNode } from './FrontmatterNode.js';
 export { CustomLinkNode, $createCustomLinkNode, $isCustomLinkNode } from './CustomLinkNode.js';

package/dist/app/editor/nodes/transclusion-loading.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The transient "waiting" visual for block transclusion (#119) — split into
+ * its own, deliberately dependency-light module.
+ *
+ * `TransclusionNode.tsx` needs this for its `Suspense` fallback, and
+ * `TransclusionNode.tsx` is part of the `./nodes` subpath's *static* (eagerly
+ * evaluated) import graph — unlike `TransclusionComponent.tsx`, which is only
+ * ever reached through a dynamic `import()`. `transclusion-render.tsx`
+ * imports `parseMarkdown` (and, transitively, the whole micromark/mdast-util
+ * pipeline) to do its real work; if `TransclusionNode.tsx` imported this
+ * function from that module instead, `./nodes` would statically pull in the
+ * entire markdown pipeline it does not otherwise need — exactly the weight
+ * `src/__tests__/nodes-subpath.test.ts` exists to keep out. Keeping this one
+ * function here, with no import of `transclusion-render.tsx`, is what keeps
+ * that boundary intact.
+ */
+import { type ReactNode } from 'react';
+/**
+ * The transient "resolver call in flight" state — not part of
+ * `TransclusionRenderState` (`transclusion-render.tsx`) because it is a UI
+ * concern of the lazily-mounted `TransclusionComponent`, not an outcome the
+ * pure resolver ever produces (it only returns once fully settled). Also
+ * used as the `Suspense` fallback in `TransclusionNode.decorate()` while the
+ * component's own code chunk is still loading, so both "waiting" cases look
+ * the same.
+ */
+export declare function renderTransclusionLoading(): ReactNode;

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

@@ -0,0 +1,29 @@
+/**
+ * The transient "waiting" visual for block transclusion (#119) — split into
+ * its own, deliberately dependency-light module.
+ *
+ * `TransclusionNode.tsx` needs this for its `Suspense` fallback, and
+ * `TransclusionNode.tsx` is part of the `./nodes` subpath's *static* (eagerly
+ * evaluated) import graph — unlike `TransclusionComponent.tsx`, which is only
+ * ever reached through a dynamic `import()`. `transclusion-render.tsx`
+ * imports `parseMarkdown` (and, transitively, the whole micromark/mdast-util
+ * pipeline) to do its real work; if `TransclusionNode.tsx` imported this
+ * function from that module instead, `./nodes` would statically pull in the
+ * entire markdown pipeline it does not otherwise need — exactly the weight
+ * `src/__tests__/nodes-subpath.test.ts` exists to keep out. Keeping this one
+ * function here, with no import of `transclusion-render.tsx`, is what keeps
+ * that boundary intact.
+ */
+import { createElement } from 'react';
+/**
+ * The transient "resolver call in flight" state — not part of
+ * `TransclusionRenderState` (`transclusion-render.tsx`) because it is a UI
+ * concern of the lazily-mounted `TransclusionComponent`, not an outcome the
+ * pure resolver ever produces (it only returns once fully settled). Also
+ * used as the `Suspense` fallback in `TransclusionNode.decorate()` while the
+ * component's own code chunk is still loading, so both "waiting" cases look
+ * the same.
+ */
+export function renderTransclusionLoading() {
+    return createElement('span', { className: 'editor-transclusion-loading' }, 'Loading…');
+}

package/dist/app/editor/nodes/transclusion-render.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 { type ReactNode } from 'react';
+/** A host-injected resolver, matching `EditorHostServices.resolveTransclusion`. */
+export type TransclusionResolver = (file: string, blockId: string) => Promise<string | null>;
+/**
+ * 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 declare const MAX_TRANSCLUSION_DEPTH = 8;
+export type TransclusionRenderState = {
+    kind: 'resolved';
+    content: ReactNode;
+} | {
+    kind: 'unresolved';
+} | {
+    kind: 'circular';
+} | {
+    kind: 'depth-exceeded';
+};
+/**
+ * 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 declare function resolveAndRenderTransclusion(file: string, blockId: string, resolver: TransclusionResolver | undefined, visitedPath?: readonly string[]): Promise<TransclusionRenderState>;
+/** 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 declare function renderTransclusionState(state: TransclusionRenderState): ReactNode;

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, $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,22 @@ 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) ||
+        $isHtmlNode(node) ||
+        $isTransclusionNode(node));
 }
 /**
  * Inclusive bounds of the maximal run of consecutive siblings in `flat` that
@@ -790,6 +796,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',
@@ -1338,8 +1352,36 @@ function convertSingleInlineChild(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.
@@ -1892,6 +1934,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, $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) {
@@ -849,6 +889,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 +908,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;