@liminis/editor 0.4.0 → 0.5.0

package/README.md

@@ -8,14 +8,16 @@ It is the editor from [Liminis](https://github.com/verveguy/liminis), extracted
 into this repository so it can stand on its own. MIT-licensed.
 
 Its history, and how to read the `ADR-0NNN`, `FR-NNN` and `#NNN` references that
-travelled with the code, are recorded in [`docs/provenance.md`](./docs/provenance.md).
+travelled with the code, are recorded in [`docs/provenance.md`](./docs/provenance.md)
+([on the docs site](https://v3rv.com/liminis-editor/guide/provenance/)).
 
 ## What you get
 
 - **`<Editor>`** — a WYSIWYG markdown editor. Tables, task lists (including in
   ordered lists), footnotes, definition lists, callouts, toggles, code blocks
   with Prism highlighting, images, LaTeX equations, Mermaid diagrams, C4
-  diagrams, YAML frontmatter, and wiki-links.
+  diagrams, YAML frontmatter, and wiki-links — including block-scoped links
+  and live transclusion (`[[file#^id]]` / `![[file#^id]]`).
 - **A markdown pipeline** — `parseMarkdown` / `stringifyMarkdown` and the mdast
   ↔ Lexical mappers, usable with no editor mounted.
 - **An annotation mechanism** — range-anchored markers over document text that
@@ -441,6 +443,49 @@ read-only editor still shows the floating toolbar with the configured
 affordance (formatting controls are omitted there, since they would be
 inert).
 
+## Block-scoped links and transclusion
+
+Wiki-links (`[[target]]` / `[[target|alias]]`) extend to an optional
+Obsidian-style block-id fragment: `[[file#^id]]` links to one specific block
+inside a file rather than the file as a whole, and `![[file#^id]]`
+**transcludes** it — renders that block's actual, current content inline at
+the reference site. This is a live view, not a copy: if the source block's
+text changes, every transclusion of it reflects that on next render.
+
+Resolving `file#^id` to content is host work, through one optional injected
+function:
+
+```tsx
+<EditorHostProvider services={{ resolveTransclusion: async (file, blockId) => {
+  // look up the block by id across your whole corpus — ids are workspace-global,
+  // not scoped to one file (matching Liminis's own `^ULID` convention)
+  return lookupBlockContent(file, blockId) // string | null
+} }}>
+  <Editor initialContent={markdown} onChange={setMarkdown} />
+</EditorHostProvider>
+```
+
+With no resolver injected, or one that returns `null`, `![[file#^id]]`
+renders a clearly marked "unresolved" placeholder rather than throwing —
+consistent with every other host service in this package. A transclusion
+cycle (block A transcludes B, which transcludes A — directly or through a
+longer chain) is detected and rendered as a "circular transclusion"
+indicator rather than hanging; nested transclusion is supported to a bounded
+depth, beyond which it degrades to a clear fallback rather than a crash.
+
+**If you are maintaining this package: do not remove the cycle/depth guard**
+in `src/app/editor/nodes/transclusion-render.tsx`, and **do not loosen the
+embed-marker detection** in `src/markdown/parse.ts` to a bare `!` lookahead
+— see `docs/markdown-pipeline.md`'s "Block-scoped links and transclusion"
+section for what each guards against and the regression fixture that pins
+it down.
+
+`[[file#^id]]` (link-only, no `!`) instead requests navigation to that
+specific block when the host supports it, and degrades no worse than
+today's file-only wiki-link navigation when it doesn't — no extra host
+wiring required beyond the resolver above, which also backs its
+"does this block exist" styling.
+
 ## Documentation
 
 - [`docs/editor-api.md`](./docs/editor-api.md) — the `<Editor>` props and the
@@ -490,12 +535,35 @@ over the same round-trip fixture corpus the package's own test suite uses, so
 every fixture-representable node class renders somewhere in it. See
 [`examples/demo/README.md`](./examples/demo/README.md).
 
-`examples/demo` is also the source of the public GitHub Pages site: a
+`examples/demo` is also the demo on the public GitHub Pages site, at
+**[v3rv.com/liminis-editor/demo/](https://v3rv.com/liminis-editor/demo/)** — a
 `release`-triggered (not merge-triggered) build of this same shell, showing a
-visible version badge for the published release it represents and a
-Documentation tab rendering this README. Between releases the deployed site
-stays on the last published version even as `main` keeps moving — that
-staleness is intentional, not a bug (see `docs/decisions/adr-082.md`).
+visible version badge for the published release it represents. Between releases
+the deployed site stays on the last published version even as `main` keeps
+moving — that staleness is intentional, not a bug (see
+`docs/decisions/adr-082.md`).
+
+## Documentation site
+
+**[v3rv.com/liminis-editor](https://v3rv.com/liminis-editor/)** publishes the
+pages in [`docs/`](./docs/) with search, cross-links, and the C4 diagrams
+rendered live rather than as pictures.
+
+`docs/*.md` remains the source of truth and is not moved or modified for the
+site: it ships inside the published tarball, `tests/adr-citations.test.ts` walks
+it, and it is cited by path from ADRs, the CHANGELOG and source comments.
+`site/scripts/sync-docs.mjs` generates the site's copy from it, taking each
+page's title from its H1.
+
+```bash
+pnpm --dir site demo    # build the demo and stage it at /demo/ (once)
+pnpm --dir site dev     # serve the docs at http://localhost:4321/liminis-editor/
+pnpm --dir site diagrams # re-render the committed SVGs after editing a ```c4 fence
+```
+
+`site/` is its own package, deliberately not a workspace member — the same
+reasoning as `examples/`. An Astro toolchain has no business in the dev install
+CI runs for lint, typecheck and test.
 
 ## Electron e2e shell
 
@@ -510,7 +578,8 @@ application, to exist. See
 ```bash
 pnpm build:examples   # builds and packs the package once, then builds both
                        # examples/demo and examples/electron against it
-pnpm build:site       # builds examples/demo only — what the release-triggered
+pnpm build:site       # builds examples/demo only — wrapped by the site's
+                       # `pnpm --dir site demo`, which the release-triggered
                        # Pages deploy runs (see the Demo section above)
 ```
 

package/dist/app/editor/LinkClickPlugin.js

@@ -43,7 +43,11 @@ export function LinkClickPlugin({ editable = true }) {
                 // URL is stored in data-href (not href) to prevent webview interception
                 const url = linkElement.getAttribute('data-href');
                 if (url) {
-                    openLink(url);
+                    // Block-scoped link (#119): additive, so a host that hasn't
+                    // implemented block-aware navigation still gets `url` and opens
+                    // the file exactly as before (FR-004).
+                    const blockId = linkElement.getAttribute('data-block-id') ?? undefined;
+                    openLink(url, blockId);
                 }
             }
             // In editable mode without modifier: No action needed - since there's no href,

package/dist/app/editor/WikiLinkExistencePlugin.d.ts

@@ -2,14 +2,24 @@
  * WikiLinkExistencePlugin - Checks wiki-links and marks broken ones
  *
  * This plugin scans for wiki-links in the editor DOM and checks if their
- * target files exist anywhere in the workspace. Links to non-existent files
- * get a CSS class applied to render them in red.
+ * target files (or, for a block-scoped link, target block — #119) exist
+ * anywhere in the workspace. Links that don't resolve get a CSS class
+ * applied to render them in red.
  *
- * Uses the host-supplied `resolveWikiLinks` service, which handles:
+ * A plain file-only link (`data-wiki-target`, no `data-block-id`) uses the
+ * host-supplied `resolveWikiLinks` service, which handles:
  * - Directory links (e.g., "entities/teams/") → resolves to index.md or README.md
  * - File links with extension (e.g., "notes.md") → checks directly
  * - File links without extension (e.g., "notes") → tries .md, .mdc
  *
+ * A block-scoped link (`data-block-id` present, `[[file#^id]]`) instead
+ * checks via `resolveTransclusion` — the same host resolver transclusion
+ * uses for content, per the Plan's "one resolver, two consumers" decision.
+ * `resolveTransclusion` returns content, not a boolean, but existence is
+ * exactly "did this resolve to something non-null" (FR-004's edge case: an
+ * id that doesn't exist is unresolved, not an error, with the same styling
+ * an unresolved file-only wikilink already gets).
+ *
  * The check is performed:
  * - When the document is loaded
  * - When the document content changes (debounced)

package/dist/app/editor/WikiLinkExistencePlugin.js

@@ -5,21 +5,31 @@ import { useEditorHost } from '../../host/context.js';
  * WikiLinkExistencePlugin - Checks wiki-links and marks broken ones
  *
  * This plugin scans for wiki-links in the editor DOM and checks if their
- * target files exist anywhere in the workspace. Links to non-existent files
- * get a CSS class applied to render them in red.
+ * target files (or, for a block-scoped link, target block — #119) exist
+ * anywhere in the workspace. Links that don't resolve get a CSS class
+ * applied to render them in red.
  *
- * Uses the host-supplied `resolveWikiLinks` service, which handles:
+ * A plain file-only link (`data-wiki-target`, no `data-block-id`) uses the
+ * host-supplied `resolveWikiLinks` service, which handles:
  * - Directory links (e.g., "entities/teams/") → resolves to index.md or README.md
  * - File links with extension (e.g., "notes.md") → checks directly
  * - File links without extension (e.g., "notes") → tries .md, .mdc
  *
+ * A block-scoped link (`data-block-id` present, `[[file#^id]]`) instead
+ * checks via `resolveTransclusion` — the same host resolver transclusion
+ * uses for content, per the Plan's "one resolver, two consumers" decision.
+ * `resolveTransclusion` returns content, not a boolean, but existence is
+ * exactly "did this resolve to something non-null" (FR-004's edge case: an
+ * id that doesn't exist is unresolved, not an error, with the same styling
+ * an unresolved file-only wikilink already gets).
+ *
  * The check is performed:
  * - When the document is loaded
  * - When the document content changes (debounced)
  */
 export function WikiLinkExistencePlugin() {
     const [editor] = useLexicalComposerContext();
-    const { resolveWikiLinks } = useEditorHost();
+    const { resolveWikiLinks, resolveTransclusion } = useEditorHost();
     const checkTimeoutRef = useRef(null);
     const lastCheckedRef = useRef(new Set());
     useEffect(() => {
@@ -27,47 +37,48 @@ export function WikiLinkExistencePlugin() {
         if (!rootElement)
             return;
         const checkWikiLinks = async () => {
-            // Find all wiki-link elements
+            // Find all wiki-link elements, split into plain (file-only) and
+            // block-scoped (carrying data-block-id) groups.
             const wikiLinks = rootElement.querySelectorAll('a[data-wiki-link="true"]');
             if (wikiLinks.length === 0)
                 return;
-            // Collect unique target paths
-            const targets = new Set();
+            const plainTargets = new Set();
+            const blockRefs = new Set();
             wikiLinks.forEach((link) => {
                 const target = link.getAttribute('data-wiki-target');
-                if (target) {
-                    targets.add(target);
+                if (!target)
+                    return;
+                const blockId = link.getAttribute('data-block-id');
+                if (blockId) {
+                    blockRefs.add(`${target}#^${blockId}`);
+                }
+                else {
+                    plainTargets.add(target);
                 }
             });
-            if (targets.size === 0)
+            if (plainTargets.size === 0 && blockRefs.size === 0)
                 return;
-            // Skip if we've already checked these exact targets
-            const targetsArray = Array.from(targets);
-            const targetKey = targetsArray.sort().join('|');
-            if (lastCheckedRef.current.has(targetKey)) {
+            // Skip if we've already checked this exact combination of targets.
+            const checkKey = [...plainTargets, ...blockRefs].sort().join('|');
+            if (lastCheckedRef.current.has(checkKey)) {
                 return;
             }
-            // Use the host-supplied resolver which handles directory links, etc.
             try {
-                if (!resolveWikiLinks) {
-                    console.warn('[WikiLinkExistencePlugin] resolveWikiLinks host service not available');
-                    return;
-                }
-                // Resolve all wiki-link paths
-                const resolved = await resolveWikiLinks(targetsArray);
-                lastCheckedRef.current.add(targetKey);
+                const plainResolved = await resolvePlainTargets(plainTargets, resolveWikiLinks);
+                const blockResolved = await resolveBlockRefs(blockRefs, resolveTransclusion);
+                lastCheckedRef.current.add(checkKey);
                 // Update CSS classes on wiki-links
                 wikiLinks.forEach((link) => {
                     const target = link.getAttribute('data-wiki-target');
-                    if (target) {
-                        // Link exists if resolver returned a non-null path
-                        const exists = resolved[target] !== null;
-                        if (!exists) {
-                            link.classList.add('editor-link-broken');
-                        }
-                        else {
-                            link.classList.remove('editor-link-broken');
-                        }
+                    if (!target)
+                        return;
+                    const blockId = link.getAttribute('data-block-id');
+                    const exists = blockId ? blockResolved.get(`${target}#^${blockId}`) : plainResolved.get(target);
+                    if (exists === false) {
+                        link.classList.add('editor-link-broken');
+                    }
+                    else {
+                        link.classList.remove('editor-link-broken');
                     }
                 });
             }
@@ -99,6 +110,54 @@ export function WikiLinkExistencePlugin() {
                 clearTimeout(checkTimeoutRef.current);
             }
         };
-    }, [editor, resolveWikiLinks]);
+    }, [editor, resolveWikiLinks, resolveTransclusion]);
     return null;
 }
+/**
+ * Resolve plain (file-only) wiki-link targets via `resolveWikiLinks`.
+ * Absent the resolver (or no targets to check), every target is left
+ * unresolved-status `undefined` so the caller leaves its styling alone
+ * rather than marking it broken — consistent with the rest of this host
+ * seam's "service missing = feature unavailable, do nothing" convention.
+ */
+async function resolvePlainTargets(targets, resolveWikiLinks) {
+    const result = new Map();
+    if (targets.size === 0 || !resolveWikiLinks) {
+        return result;
+    }
+    const resolved = await resolveWikiLinks([...targets]);
+    for (const target of targets) {
+        // A missing key (as opposed to an explicit `null`) is treated as
+        // existing, matching this plugin's pre-#119 behavior — resolveWikiLinks
+        // isn't contractually required to return an entry for every target, and
+        // FR-014 requires plain wikilink resolution to be unaffected by this
+        // feature.
+        result.set(target, resolved[target] !== null);
+    }
+    return result;
+}
+/**
+ * Resolve block-scoped references (`file#^blockId` keys) via
+ * `resolveTransclusion`, one call per unique reference (the resolver's
+ * contract is single-reference, unlike `resolveWikiLinks`'s batch shape).
+ */
+async function resolveBlockRefs(refs, resolveTransclusion) {
+    const result = new Map();
+    if (refs.size === 0 || !resolveTransclusion) {
+        return result;
+    }
+    await Promise.all([...refs].map(async (ref) => {
+        const separatorIndex = ref.indexOf('#^');
+        const file = ref.slice(0, separatorIndex);
+        const blockId = ref.slice(separatorIndex + 2);
+        try {
+            const content = await resolveTransclusion(file, blockId);
+            result.set(ref, content !== null && content !== undefined);
+        }
+        catch {
+            // FR-009: a rejected resolver is treated as "unresolved", not an error.
+            result.set(ref, false);
+        }
+    }));
+    return result;
+}

package/dist/app/editor/editorNodes.js

@@ -3,7 +3,7 @@ import { CodeNode, CodeHighlightNode } from '@lexical/code';
 import { AutoLinkNode } from '@lexical/link';
 import { MarkNode } from '@lexical/mark';
 import { TableNode, TableRowNode, TableCellNode } from '@lexical/table';
-import { CalloutNode, ToggleContainerNode, ToggleTitleNode, ToggleContentNode, ImageNode, HorizontalRuleNode, EquationNode, MermaidNode, C4Node, FrontmatterNode, FootnoteNode, HtmlNode, ListItemParagraphBreakNode, CustomLinkNode, CustomListNode, DefinitionListNode, DefinitionTermNode, DefinitionDescriptionNode, CustomListItemNode, } from './nodes/index.js';
+import { CalloutNode, ToggleContainerNode, ToggleTitleNode, ToggleContentNode, ImageNode, HorizontalRuleNode, EquationNode, MermaidNode, C4Node, FrontmatterNode, FootnoteNode, HtmlNode, ListItemParagraphBreakNode, CustomLinkNode, CustomListNode, DefinitionListNode, DefinitionTermNode, DefinitionDescriptionNode, CustomListItemNode, TransclusionNode, } from './nodes/index.js';
 export const editorNodes = [
     HeadingNode,
     QuoteNode,
@@ -24,6 +24,7 @@ export const editorNodes = [
     HorizontalRuleNode,
     EquationNode,
     MermaidNode,
+    TransclusionNode,
     C4Node,
     FrontmatterNode,
     FootnoteNode,

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

@@ -3,6 +3,10 @@ import { DOMConversionMap, EditorConfig, LexicalNode } from 'lexical';
 export type SerializedCustomLinkNode = SerializedLinkNode & {
     wikiAliasState?: 'empty';
     wikiLinkOrigin?: true;
+    /** Obsidian-style `#^blockId` fragment (#119), carried as a field separate
+     * from `url` so it never has to round-trip through the lossy `.md#`
+     * URL-string channel the plain anchor-link path uses. */
+    blockId?: string;
 };
 /**
  * CustomLinkNode - Extends Lexical's LinkNode to prevent VS Code webview link interception
@@ -24,6 +28,14 @@ export declare class CustomLinkNode extends LinkNode {
      * @internal
      */
     __wikiLinkOrigin: boolean;
+    /**
+     * Obsidian-style `#^blockId` fragment (#119), when this link is a
+     * block-scoped wiki-link (`[[file#^id]]`). `null` for an ordinary
+     * file-only or heading-anchor wiki-link. Deliberately a field separate
+     * from `__url` — see `mdastToLexical.ts`/`lexicalToMdast.ts` for why.
+     * @internal
+     */
+    __blockId: string | null;
     constructor(url: string, attributes?: {
         rel?: null | string;
         target?: null | string;
@@ -48,6 +60,8 @@ export declare class CustomLinkNode extends LinkNode {
     getWikiAliasState(): 'empty' | null;
     setWikiLinkOrigin(origin: boolean): void;
     getWikiLinkOrigin(): boolean;
+    setBlockId(blockId: string | null): void;
+    getBlockId(): string | null;
 }
 export declare function $createCustomLinkNode(url: string, attributes?: {
     rel?: null | string;

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

@@ -19,10 +19,19 @@ export class CustomLinkNode extends LinkNode {
      * @internal
      */
     __wikiLinkOrigin;
+    /**
+     * Obsidian-style `#^blockId` fragment (#119), when this link is a
+     * block-scoped wiki-link (`[[file#^id]]`). `null` for an ordinary
+     * file-only or heading-anchor wiki-link. Deliberately a field separate
+     * from `__url` — see `mdastToLexical.ts`/`lexicalToMdast.ts` for why.
+     * @internal
+     */
+    __blockId;
     constructor(url, attributes, key) {
         super(url, attributes, key);
         this.__wikiAliasState = null;
         this.__wikiLinkOrigin = false;
+        this.__blockId = null;
     }
     static getType() {
         return 'link'; // Use same type to replace the default LinkNode
@@ -31,6 +40,7 @@ export class CustomLinkNode extends LinkNode {
         const cloned = new CustomLinkNode(node.__url, { rel: node.__rel, target: node.__target, title: node.__title }, node.__key);
         cloned.__wikiAliasState = node.__wikiAliasState;
         cloned.__wikiLinkOrigin = node.__wikiLinkOrigin;
+        cloned.__blockId = node.__blockId;
         return cloned;
     }
     createDOM(config) {
@@ -54,6 +64,9 @@ export class CustomLinkNode extends LinkNode {
         if (this.isWikiLink()) {
             element.setAttribute('data-wiki-link', 'true');
             element.setAttribute('data-wiki-target', this.__url);
+            if (this.__blockId) {
+                element.setAttribute('data-block-id', this.__blockId);
+            }
         }
         else if (this.isExternalLink()) {
             // External links get blue styling to differentiate from wiki-links
@@ -97,6 +110,7 @@ export class CustomLinkNode extends LinkNode {
             else {
                 anchor.removeAttribute('data-wiki-link');
                 anchor.removeAttribute('data-wiki-target');
+                anchor.removeAttribute('data-block-id');
                 anchor.classList.remove('editor-link-broken');
                 if (this.isExternalLink()) {
                     anchor.classList.add('editor-link-external');
@@ -106,6 +120,14 @@ export class CustomLinkNode extends LinkNode {
                 }
             }
         }
+        if (this.__blockId !== prevNode.__blockId) {
+            if (this.__blockId && this.isWikiLink()) {
+                anchor.setAttribute('data-block-id', this.__blockId);
+            }
+            else {
+                anchor.removeAttribute('data-block-id');
+            }
+        }
         if (target !== prevNode.__target) {
             if (target) {
                 anchor.target = target;
@@ -155,6 +177,9 @@ export class CustomLinkNode extends LinkNode {
         if (serializedNode.wikiLinkOrigin) {
             node.__wikiLinkOrigin = true;
         }
+        if (serializedNode.blockId) {
+            node.__blockId = serializedNode.blockId;
+        }
         node.setFormat(serializedNode.format);
         node.setIndent(serializedNode.indent);
         node.setDirection(serializedNode.direction);
@@ -167,6 +192,7 @@ export class CustomLinkNode extends LinkNode {
             version: 1,
             wikiAliasState: this.__wikiAliasState ?? undefined,
             wikiLinkOrigin: this.__wikiLinkOrigin ? true : undefined,
+            blockId: this.__blockId ?? undefined,
         };
     }
     setWikiAliasState(state) {
@@ -183,6 +209,13 @@ export class CustomLinkNode extends LinkNode {
     getWikiLinkOrigin() {
         return this.__wikiLinkOrigin;
     }
+    setBlockId(blockId) {
+        const writable = this.getWritable();
+        writable.__blockId = blockId;
+    }
+    getBlockId() {
+        return this.__blockId;
+    }
 }
 function convertAnchorElement(domNode) {
     let node = null;
@@ -195,6 +228,10 @@ function convertAnchorElement(domNode) {
                 target: domNode.getAttribute('target'),
                 title: domNode.getAttribute('title'),
             });
+            const blockId = domNode.getAttribute('data-block-id');
+            if (blockId) {
+                node.__blockId = blockId;
+            }
         }
     }
     return { node };

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

@@ -0,0 +1,8 @@
+import { NodeKey } from 'lexical';
+interface TransclusionComponentProps {
+    file: string;
+    blockId: string;
+    nodeKey: NodeKey;
+}
+export default function TransclusionComponent({ file, blockId }: TransclusionComponentProps): JSX.Element;
+export {};

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

@@ -0,0 +1,65 @@
+/**
+ * TransclusionComponent - resolves and renders a block transclusion
+ * (`![[file#^id]]`, #119)
+ *
+ * Mirrors `MermaidComponent`'s split: `TransclusionNode` is a static,
+ * serializable value (`file`/`blockId`/`alias`); the actual host-resolver
+ * call happens here, inside the lazily-loaded component, since resolution is
+ * `Promise`-based and the mdast<->Lexical mapper is synchronous.
+ */
+import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext';
+import { useEffect, useRef, useState } from 'react';
+import { useEditorHost } from '../../../host/context.js';
+import { resolveAndRenderTransclusion, renderTransclusionState, } from './transclusion-render.js';
+import { renderTransclusionLoading } from './transclusion-loading.js';
+// Matches WikiLinkExistencePlugin's debounce window for the same reason:
+// both re-run a host resolver on every dirty editor update, and without
+// debouncing that fires one resolver call (potentially I/O-bound) per
+// keystroke per visible reference.
+const RESOLVE_DEBOUNCE_MS = 300;
+export default function TransclusionComponent({ file, blockId }) {
+    const [editor] = useLexicalComposerContext();
+    const { resolveTransclusion } = useEditorHost();
+    const [state, setState] = useState(null);
+    // Guards against a stale resolution landing after a newer one already
+    // started (e.g. file/blockId changed, or two update-listener firings
+    // overlap) — only the most recent request is allowed to commit state.
+    const generationRef = useRef(0);
+    useEffect(() => {
+        let cancelled = false;
+        let debounceTimeout = null;
+        const resolve = async () => {
+            const generation = ++generationRef.current;
+            const result = await resolveAndRenderTransclusion(file, blockId, resolveTransclusion, []);
+            if (!cancelled && generation === generationRef.current) {
+                setState(result);
+            }
+        };
+        void resolve();
+        // FR-006/SC-002: re-resolve on every document change so an edit to the
+        // source block — in this document, or elsewhere once the host's own
+        // resolver reflects it — shows up without the host having to remount
+        // the editor. Pull-based and unmemoized (every dirty update re-resolves
+        // every visible transclusion): an accepted v1 cost, not a correctness
+        // gap — see the Plan's "no push/invalidation channel" risk note. The
+        // debounce below only bounds *how often* that cost is paid per burst of
+        // edits, mirroring WikiLinkExistencePlugin's existing convention.
+        const unregister = editor.registerUpdateListener(({ dirtyElements, dirtyLeaves }) => {
+            if (dirtyElements.size > 0 || dirtyLeaves.size > 0) {
+                if (debounceTimeout)
+                    clearTimeout(debounceTimeout);
+                debounceTimeout = setTimeout(() => { void resolve(); }, RESOLVE_DEBOUNCE_MS);
+            }
+        });
+        return () => {
+            cancelled = true;
+            if (debounceTimeout)
+                clearTimeout(debounceTimeout);
+            unregister();
+        };
+    }, [editor, file, blockId, resolveTransclusion]);
+    if (state === null) {
+        return renderTransclusionLoading();
+    }
+    return renderTransclusionState(state);
+}

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

@@ -0,0 +1,48 @@
+/**
+ * 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, DOMConversionMap, DOMExportOutput, LexicalNode, NodeKey, SerializedLexicalNode, Spread } from 'lexical';
+export type SerializedTransclusionNode = Spread<{
+    file: string;
+    blockId: string;
+    alias: string | null;
+    emptyAlias: boolean;
+}, SerializedLexicalNode>;
+export declare class TransclusionNode extends DecoratorNode<JSX.Element> {
+    __file: string;
+    __blockId: string;
+    __alias: string | null;
+    __emptyAlias: boolean;
+    static getType(): string;
+    static clone(node: TransclusionNode): TransclusionNode;
+    constructor(file: string, blockId: string, alias?: string | null, emptyAlias?: boolean, key?: NodeKey);
+    static importJSON(serializedNode: SerializedTransclusionNode): TransclusionNode;
+    exportJSON(): SerializedTransclusionNode;
+    createDOM(): HTMLElement;
+    exportDOM(): DOMExportOutput;
+    static importDOM(): DOMConversionMap | null;
+    updateDOM(): boolean;
+    isInline(): boolean;
+    getFile(): string;
+    getBlockId(): string;
+    getAlias(): string | null;
+    setAlias(alias: string | null): void;
+    getEmptyAlias(): boolean;
+    setEmptyAlias(emptyAlias: boolean): void;
+    decorate(): JSX.Element;
+}
+export declare function $createTransclusionNode(file: string, blockId: string, alias?: string | null, emptyAlias?: boolean): TransclusionNode;
+export declare function $isTransclusionNode(node: LexicalNode | null | undefined): node is TransclusionNode;