@markii/host 0.0.0-stage → 0.17.0-next.2

package/dist/export/note-export.js

@@ -0,0 +1,366 @@
+/**
+ * Static-export plumbing shared by every host (GitHub issue #28, slice 1):
+ * turning one note's text plus its last-run values into a self-contained
+ * HTML document, and working out what the resulting file is called.
+ *
+ * This builds NO renderer of its own. `@markii/html` is the static engine
+ * (`packages/platforms/markii-html`): `renderMarkToHtml` walks
+ * `@markii/core`'s sanitized hast to an HTML string, and
+ * `exportHtmlDocument` wraps that string in the full-page shell with the
+ * shared `doc.css` embedded. Everything here is the thin host-neutral layer
+ * around those two calls, so the VS Code extension and the Obsidian plugin
+ * cannot drift on file naming, on the page CSS an exported file carries, or
+ * on how a value store is handed to the engine.
+ *
+ * WHAT AN EXPORT CONTAINS. The standard component set, with the last run's
+ * values baked in wherever a note binds one (`data=`, `:value[...]`), plus
+ * every pack component the exporting host has loaded (issue #28 slice 2 —
+ * see `buildNoteExport` and `composeNoteHtmlExport` at the bottom of this
+ * file). A host with React and a merged registry in front of it renders the
+ * body itself and hands the string here; a host with neither falls back to
+ * the static engine, where a pack directive comes out as that engine's
+ * ordinary unknown-component fallback: a labeled box with the inner
+ * markdown still rendered inside it. Nothing crashes and no content is
+ * dropped either way; see `@markii/html`'s `render.ts`.
+ */
+import { createValueStore } from '@markii/runtime';
+import { EMPTY_IMAGE_REPORT, embedImagesInHtml } from './image-embed.js';
+/** The last path segment of a `/`-separated path, or the string itself when it has no separator. */
+function lastSegment(pathOrName) {
+    const separator = pathOrName.lastIndexOf('/');
+    return separator === -1 ? pathOrName : pathOrName.slice(separator + 1);
+}
+/** The canonical Markii file extension, matching `apps/vscode/src/mark-document.ts`'s `MARK_EXTENSION`. */
+export const MARK_EXTENSION = '.mk.md';
+/**
+ * The name used when a note has no usable base name at all — a file called
+ * exactly `.mk.md`, or an empty path segment. Rare enough that neither host
+ * offers it as a normal path, but a file name is not optional here, so
+ * there has to be one rather than an empty string.
+ */
+export const FALLBACK_EXPORT_BASE_NAME = 'markii-note';
+/**
+ * The base name an export is built from: the file name with a recognized
+ * Markii/markdown extension removed, case-insensitively. `notes.mk.md` and
+ * `notes.md` both give `notes`; a name with any other extension keeps it
+ * (`notes.txt` gives `notes.txt`), because guessing at an unknown extension
+ * would be more surprising than leaving it alone. A `/`-separated path is
+ * accepted too: only its last segment is read.
+ */
+export function exportBaseName(pathOrName) {
+    const fileName = lastSegment(pathOrName);
+    const lower = fileName.toLowerCase();
+    if (lower.endsWith(MARK_EXTENSION)) {
+        const base = fileName.slice(0, fileName.length - MARK_EXTENSION.length);
+        return base || FALLBACK_EXPORT_BASE_NAME;
+    }
+    if (lower.endsWith('.md')) {
+        const base = fileName.slice(0, fileName.length - '.md'.length);
+        return base || FALLBACK_EXPORT_BASE_NAME;
+    }
+    return fileName || FALLBACK_EXPORT_BASE_NAME;
+}
+/** The exported file's name for `fileName`: `notes.mk.md` + `.html` gives `notes.html`. */
+export function exportedFileName(fileName, extension) {
+    return `${exportBaseName(fileName)}${extension}`;
+}
+/**
+ * The path an export is written to when it lands beside its source note:
+ * the same folder, the same base name, the new extension. `notePath` is a
+ * `/`-separated path — a `vscode.Uri.path` or an Obsidian vault-relative
+ * path, never a platform `fsPath` — so no `node:path` import and no
+ * platform branching is needed, and this module stays environment-free.
+ */
+export function exportedSiblingPath(notePath, extension) {
+    const separator = notePath.lastIndexOf('/');
+    const folder = separator === -1 ? '' : notePath.slice(0, separator + 1);
+    const fileName = notePath.slice(separator + 1);
+    return `${folder}${exportedFileName(fileName, extension)}`;
+}
+/** The exported document's `<title>`: the note's own base name, so a browser tab and a PDF's metadata name the note rather than the format. */
+export function exportDocumentTitle(fileName) {
+    return exportBaseName(fileName);
+}
+/**
+ * The page-level CSS an exported file carries in addition to `doc.css`.
+ *
+ * `doc.css` is deliberately a LIBRARY stylesheet: it styles `.doc` and
+ * never claims `:root` or `body`, because hosts embed it into pages they
+ * do not own. A standalone exported file has no host to supply the page
+ * around it, so this is that page: a ground color, a readable measure, and
+ * print rules, all of them host-authored and trusted (they are passed to
+ * the engine's `composeDocument` as `extraCss`, which is inserted verbatim).
+ *
+ * The print block matters more than it looks: the Obsidian PDF command
+ * prints exactly this document, so the paper layout is decided here rather
+ * than in a host-specific branch. `@page` sets the sheet's own margins
+ * (the PDF command has no separate page-setup step of its own), the
+ * `break-inside: avoid` list keeps a card/callout/table from splitting
+ * across two pages wherever it fits on one, and the collapsed script
+ * marker and the VS Code webview's run marker are hidden on paper: both
+ * are live-preview affordances (a disclosure toggle, a status line about
+ * the last run) that mean nothing on a printed or archived page.
+ */
+/**
+ * The class `composeNoteHtmlExport`/`buildNoteHtmlExport` put on the `.doc`
+ * wrapper when `hideScriptBlocks` is on, and the class `EXPORT_PAGE_CSS`'s
+ * rule below is scoped to.
+ *
+ * Both hosts already have this preference (VS Code's
+ * `markii.hideScriptBlocks`, Obsidian's "Hide script blocks" setting) for
+ * their live preview, hiding only the collapsed `⚙ name` marker and
+ * nothing else — a failure a reader needs to see is never hidden along
+ * with it. An export carries whichever value the exporting host's own
+ * preview was showing, so a note exported with scripts hidden in the
+ * editor stays that way in the file.
+ */
+export const EXPORT_HIDE_SCRIPT_BLOCKS_CLASS = 'mk-export--hide-scripts';
+export const EXPORT_PAGE_CSS = `
+body {
+  margin: 0;
+  background: #fff;
+}
+.doc {
+  box-sizing: border-box;
+  max-width: 46rem;
+  margin: 0 auto;
+  padding: 2.5rem 1.5rem 4rem;
+}
+.doc.${EXPORT_HIDE_SCRIPT_BLOCKS_CLASS} .mk-script {
+  display: none;
+}
+@page {
+  margin: 2cm;
+}
+@media print {
+  .doc {
+    max-width: none;
+    margin: 0;
+    padding: 0;
+  }
+  .doc .mk-card,
+  .doc .mk-callout,
+  .doc .mk-stat,
+  .doc .mk-figure,
+  .doc .mk-unknown,
+  .doc table {
+    break-inside: avoid;
+  }
+  /* A collapsed \`details\` prints as its summary alone, which loses the
+     content the author wrote. On paper there is nothing to expand, so
+     every disclosure prints open. */
+  .doc details > *:not(summary) {
+    display: block;
+  }
+  .doc .mk-script,
+  .doc .mk-preview__run-marker {
+    display: none;
+  }
+}
+`;
+/**
+ * Renders one note to a complete, self-contained HTML document string.
+ *
+ * Never throws: `renderMarkToHtml` already returns its own failure fallback
+ * rather than propagating, so a caller always gets a document it can write.
+ */
+export function buildNoteHtmlExport(options) {
+    return composeNoteHtmlExport({
+        bodyHtml: renderStaticBody(options.engine, options.text, options.values ?? {}, options),
+        engine: options.engine,
+        fileName: options.fileName,
+        ...(options.extraCss !== undefined ? { extraCss: options.extraCss } : {}),
+        ...(options.hideScriptBlocks !== undefined
+            ? { hideScriptBlocks: options.hideScriptBlocks }
+            : {}),
+    });
+}
+/**
+ * The static engine's body for one note: `@markii/html` walking
+ * `@markii/core`'s sanitized hast to a string, with the last run's values
+ * baked in. The one place `renderMarkToHtml` is called, so the static path
+ * and every React path's fallback produce the identical body.
+ */
+function renderStaticBody(engine, text, values, diagnostics = {}) {
+    const store = Object.keys(values).length > 0 ? createValueStore(values) : undefined;
+    return engine.renderBody(text, store, {
+        ...(diagnostics.unavailableComponents !== undefined
+            ? { unavailableComponents: diagnostics.unavailableComponents }
+            : {}),
+        ...(diagnostics.onDiagnostic !== undefined
+            ? { onDiagnostic: diagnostics.onDiagnostic }
+            : {}),
+    });
+}
+/**
+ * Neutralizes the one sequence that can end a `<style>` element early.
+ *
+ * Pack CSS is trusted in the security sense (docs/security.md: packs are
+ * user-installed), but trusted does not mean well-formed, and a stray
+ * `</style` in a pack's stylesheet would close the block and spill the rest
+ * of the sheet into the page as text. `<\/style` is a valid CSS escape for
+ * the same `/` inside a string, and outside a string a bare `</style` was
+ * never valid CSS anyway, so nothing legitimate changes meaning here.
+ */
+function neutralizeStyleClose(cssText) {
+    return cssText.replace(/<\/(style)/gi, '<\\/$1');
+}
+/** A namespace reduced to what is safe inside a CSS comment label. Pack names are validated kebab-case upstream; this only guarantees the comment cannot be escaped. */
+function commentSafeNamespace(namespace) {
+    const cleaned = namespace.replace(/[^a-zA-Z0-9._-]/g, '');
+    return cleaned.length > 0 ? cleaned : 'pack';
+}
+/**
+ * The pack stylesheets as one CSS block, in the order the host loaded them
+ * — the same order its preview injects them, which is what decides the
+ * cascade between two packs that style the same thing. Each block is
+ * labeled with its pack's namespace so a reader of the exported file can
+ * tell whose rules these are.
+ *
+ * Placed AFTER `doc.css` and `EXPORT_PAGE_CSS` by `composeNoteHtmlExport`,
+ * matching docs/packs.md's load order: a pack sees resolved `--mk-*` token
+ * values and is not overridden by the document stylesheet's broader rules.
+ */
+export function packStylesheetsCss(sheets) {
+    return sheets
+        .map((sheet) => `/* pack: ${commentSafeNamespace(sheet.namespace)} */\n${neutralizeStyleClose(sheet.cssText)}`)
+        .join('\n');
+}
+/**
+ * Wraps an already-rendered body in the standalone export page: the same
+ * shell, `doc.css`, and print rules `buildNoteHtmlExport` produces, plus
+ * every loaded pack's stylesheet so pack components in the body are styled.
+ *
+ * Host-neutral and renderer-neutral on purpose: it takes a STRING, so the
+ * React path and the static path compose the identical page and can never
+ * drift on what an exported file carries.
+ */
+export function composeNoteHtmlExport(options) {
+    const packCss = packStylesheetsCss(options.packStylesheets ?? []);
+    const parts = [EXPORT_PAGE_CSS];
+    if (options.extraCss)
+        parts.push(options.extraCss);
+    if (packCss)
+        parts.push(packCss);
+    return options.engine.composeDocument(options.bodyHtml, {
+        title: exportDocumentTitle(options.fileName),
+        extraCss: parts.join('\n'),
+        ...(options.hideScriptBlocks
+            ? { docClassName: EXPORT_HIDE_SCRIPT_BLOCKS_CLASS }
+            : {}),
+    });
+}
+/** The verbatim reason for a thrown value. Diagnostics only, never a notice. */
+function detailOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Builds one note's standalone export document, through the host's React
+ * engine when it offered one and through `@markii/html` otherwise.
+ *
+ * Never throws and never leaves a caller without a file: a renderer that
+ * fails, times out, or throws is classified, recorded in `render`, and
+ * replaced by the static engine's output, which is the same document slice
+ * 1 produced.
+ */
+export async function buildNoteExport(request) {
+    const values = request.values ?? {};
+    const valueCount = Object.keys(values).length;
+    /**
+     * The one place a body becomes a finished document, so image embedding
+     * and page composition cannot end up applied on one path and not the
+     * other. Images are embedded BEFORE composition, since the page shell is
+     * not a place an `<img>` can appear.
+     */
+    const finish = async (bodyHtml, render, packStylesheets) => {
+        const embedded = request.embedImages
+            ? await embedImagesInHtml(bodyHtml, request.embedImages)
+            : { html: bodyHtml, report: EMPTY_IMAGE_REPORT };
+        return {
+            html: composeNoteHtmlExport({
+                engine: request.engine,
+                bodyHtml: embedded.html,
+                fileName: request.fileName,
+                packStylesheets,
+                ...(request.extraCss !== undefined
+                    ? { extraCss: request.extraCss }
+                    : {}),
+                ...(request.hideScriptBlocks !== undefined
+                    ? { hideScriptBlocks: request.hideScriptBlocks }
+                    : {}),
+            }),
+            render,
+            valueCount,
+            images: embedded.report,
+        };
+    };
+    /** The static engine's document. Pack stylesheets are never embedded here: the static body has nothing that would use them. */
+    const staticDocument = (render) => finish(renderStaticBody(request.engine, request.text, values, request), render, []);
+    if (!request.renderBody) {
+        return staticDocument({
+            engine: 'static',
+            reason: request.staticReason ?? 'no-packs',
+        });
+    }
+    let result;
+    try {
+        result = await request.renderBody(request.text, values);
+    }
+    catch (error) {
+        return staticDocument({
+            engine: 'static',
+            reason: 'render-failed',
+            detail: detailOf(error),
+        });
+    }
+    if (!result.ok) {
+        return staticDocument({
+            engine: 'static',
+            reason: result.reason,
+            ...(result.detail !== undefined ? { detail: result.detail } : {}),
+        });
+    }
+    const packStylesheets = request.packStylesheets ?? [];
+    return finish(result.html, {
+        engine: 'react',
+        packCount: request.packCount ?? packStylesheets.length,
+        stylesheetCount: packStylesheets.length,
+    }, packStylesheets);
+}
+/**
+ * Whether `text` contains at least one Markii script fence, i.e. a code
+ * fence whose info string names `lua`. Both hosts' export notices use this
+ * so a note with no scripts is never told to run itself first.
+ */
+export function noteHasScripts(text) {
+    return /^ {0,3}(?:`{3,}|~{3,})[ \t]*lua\b/m.test(text);
+}
+/** The title `exportHtmlDocument` gives the index page itself, distinct from any exported note's own title. */
+const CASCADE_INDEX_TITLE = 'Markii export';
+/**
+ * Builds a cascade archive's `index.html`: a self-contained document
+ * listing every exported note by title, each linking to its own file.
+ *
+ * A cascade archive has no single note to open first once it is
+ * unzipped, and without this a reader has to guess a file name or open the
+ * archive's contents blind. `entries` is expected in the same order the
+ * cascade walked (root note first, breadth first), which is what makes the
+ * list read as a sensible table of contents rather than an alphabetized
+ * jumble.
+ *
+ * Uses the same page shell every exported note gets (`doc.css`,
+ * `EXPORT_PAGE_CSS`), so the index reads as part of the same export rather
+ * than a bare, unstyled file dropped in beside it.
+ */
+export function buildCascadeIndexHtml(entries, engine) {
+    const { escapeHtml } = engine;
+    const items = entries
+        .map((entry) => `<li><a href="${escapeHtml(entry.fileName)}">${escapeHtml(entry.title)}</a></li>`)
+        .join('\n');
+    const body = `<ul class="mk-cascade-index">\n${items}\n</ul>`;
+    return composeNoteHtmlExport({
+        engine,
+        bodyHtml: body,
+        fileName: CASCADE_INDEX_TITLE,
+    });
+}

package/dist/export/note-links.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Reading and rewriting the links one note makes to another (GitHub issue
+ * #28 slice 3, part 2: the cascade export).
+ *
+ * PURE AND HOST-NEUTRAL. Nothing here touches a vault, a workspace, or a
+ * filesystem: it takes a note's text and gives back the links it contains,
+ * or a rewritten copy of that text. Resolving a link target to an actual
+ * note is the host's job, injected by the caller. That is what lets the
+ * Obsidian cascade command and a future VS Code one share this code
+ * unchanged, and it keeps every rule about what counts as a link testable
+ * without a vault.
+ *
+ * WHAT COUNTS AS A LINK. Two forms, both of which a note author uses: a
+ * wikilink (`[[Other note]]`, `[[Other note|shown text]]`,
+ * `[[Other note#a heading]]`) and an ordinary markdown link
+ * (`[shown text](other-note.md)`). An embed or image (`![[...]]`,
+ * `![](...)`) is deliberately NOT a note link: it is a picture or a
+ * transclusion, not a page to walk to. A target with a scheme
+ * (`https:`, `mailto:`), a protocol-relative `//host/path`, or a bare
+ * fragment (`#section`) is not a note link either.
+ *
+ * CODE IS NOT CONTENT. A fenced code block or an inline code span that
+ * happens to contain `[[...]]` is showing link syntax, not using it, so
+ * both are masked out before anything is matched. The mask replaces
+ * characters one for one, so every offset this reports still indexes the
+ * ORIGINAL text.
+ */
+/** One link from a note to something else, as written. */
+export interface NoteLink {
+    /** Which syntax the author used. */
+    readonly kind: 'wikilink' | 'markdown';
+    /**
+     * The link target with any alias and any `#heading` / `^block` fragment
+     * removed: the part a host resolves against its vault or workspace.
+     * Percent escapes in a markdown target are decoded, so `My%20Note.md`
+     * resolves as `My Note.md`.
+     */
+    readonly path: string;
+    /** The `#heading` or `^block` fragment including its leading character, or an empty string. */
+    readonly fragment: string;
+    /** The text shown to a reader: a wikilink's alias or its target, or a markdown link's label. */
+    readonly label: string;
+    /** Offset of the link's first character in the original text. */
+    readonly start: number;
+    /** Offset one past the link's last character in the original text. */
+    readonly end: number;
+}
+/** True for a target that could name a note in this vault or workspace: a non-empty, local, relative path rather than a URL or a bare fragment. */
+export declare function isLocalNoteTarget(target: string): boolean;
+/**
+ * A copy of `text` with every fenced code block and inline code span
+ * replaced by mask characters, so link syntax a note is merely DISPLAYING
+ * is never mistaken for a link the note makes. Length and offsets are
+ * unchanged, and newlines are preserved so line-anchored scanning still
+ * works over the masked copy.
+ */
+export declare function maskCodeRegions(text: string): string;
+/**
+ * Every note link in `text`, in document order. Embeds, images, URLs and
+ * bare fragments are all excluded, and anything inside code is invisible
+ * here.
+ */
+export declare function extractNoteLinks(text: string): NoteLink[];
+/**
+ * Decides one link's replacement destination, or `undefined` to leave the
+ * link exactly as the author wrote it. A cascade passes a resolver that
+ * answers with the sibling `.html` file name for a note that is in the
+ * export, and `undefined` for everything else.
+ */
+export type NoteLinkTargetResolver = (link: NoteLink) => string | undefined;
+/**
+ * Rewrites every link `resolve` claims, leaving every other byte of `text`
+ * untouched.
+ *
+ * A markdown link keeps its shape and only changes destination. A WIKILINK
+ * BECOMES A MARKDOWN LINK, which is a deliberate change and the only way a
+ * cascade is navigable: Markii renders CommonMark, where `[[Other note]]`
+ * is literal text rather than a link, so leaving wikilinks as written would
+ * produce a set of exported pages that cannot reach each other. A wikilink
+ * whose target is NOT in the export is left exactly as written, so nothing
+ * outside the exported set is ever invented.
+ */
+export declare function rewriteNoteLinks(text: string, resolve: NoteLinkTargetResolver): string;

package/dist/export/note-links.js

@@ -0,0 +1,241 @@
+/**
+ * Reading and rewriting the links one note makes to another (GitHub issue
+ * #28 slice 3, part 2: the cascade export).
+ *
+ * PURE AND HOST-NEUTRAL. Nothing here touches a vault, a workspace, or a
+ * filesystem: it takes a note's text and gives back the links it contains,
+ * or a rewritten copy of that text. Resolving a link target to an actual
+ * note is the host's job, injected by the caller. That is what lets the
+ * Obsidian cascade command and a future VS Code one share this code
+ * unchanged, and it keeps every rule about what counts as a link testable
+ * without a vault.
+ *
+ * WHAT COUNTS AS A LINK. Two forms, both of which a note author uses: a
+ * wikilink (`[[Other note]]`, `[[Other note|shown text]]`,
+ * `[[Other note#a heading]]`) and an ordinary markdown link
+ * (`[shown text](other-note.md)`). An embed or image (`![[...]]`,
+ * `![](...)`) is deliberately NOT a note link: it is a picture or a
+ * transclusion, not a page to walk to. A target with a scheme
+ * (`https:`, `mailto:`), a protocol-relative `//host/path`, or a bare
+ * fragment (`#section`) is not a note link either.
+ *
+ * CODE IS NOT CONTENT. A fenced code block or an inline code span that
+ * happens to contain `[[...]]` is showing link syntax, not using it, so
+ * both are masked out before anything is matched. The mask replaces
+ * characters one for one, so every offset this reports still indexes the
+ * ORIGINAL text.
+ */
+/** True when `value` begins with a URL scheme, by the same rule `@markii/core`'s `isSafeUrl` uses: text before the first `:`, but only when that `:` precedes any `/`, `?` or `#`. */
+function hasScheme(value) {
+    const colon = value.indexOf(':');
+    if (colon === -1)
+        return false;
+    const slash = value.indexOf('/');
+    const questionMark = value.indexOf('?');
+    const numberSign = value.indexOf('#');
+    return ((slash === -1 || colon < slash) &&
+        (questionMark === -1 || colon < questionMark) &&
+        (numberSign === -1 || colon < numberSign));
+}
+/** True for a target that could name a note in this vault or workspace: a non-empty, local, relative path rather than a URL or a bare fragment. */
+export function isLocalNoteTarget(target) {
+    if (target.length === 0)
+        return false;
+    if (target.startsWith('#'))
+        return false;
+    if (target.startsWith('//'))
+        return false;
+    return !hasScheme(target);
+}
+/**
+ * The mask character. A space cannot begin or continue any link syntax, and
+ * replacing one character for one keeps every offset aligned with the
+ * original text.
+ */
+const MASK = ' ';
+/**
+ * A copy of `text` with every fenced code block and inline code span
+ * replaced by mask characters, so link syntax a note is merely DISPLAYING
+ * is never mistaken for a link the note makes. Length and offsets are
+ * unchanged, and newlines are preserved so line-anchored scanning still
+ * works over the masked copy.
+ */
+export function maskCodeRegions(text) {
+    const chars = [...text];
+    const mask = (from, to) => {
+        for (let index = from; index < to && index < chars.length; index += 1) {
+            if (chars[index] !== '\n')
+                chars[index] = MASK;
+        }
+    };
+    // Fenced blocks first: a fence's contents are code even when they contain
+    // unbalanced backticks that inline scanning would misread.
+    const fence = /^[ \t]{0,3}(`{3,}|~{3,})[^\n]*$/gm;
+    const fenced = [];
+    let openMatch;
+    while ((openMatch = fence.exec(text)) !== null) {
+        const marker = openMatch[1] ?? '';
+        const markerChar = marker.startsWith('`') ? '`' : '~';
+        const closer = new RegExp(`^[ \\t]{0,3}${markerChar}{${String(marker.length)},}[ \\t]*$`, 'gm');
+        closer.lastIndex = openMatch.index + openMatch[0].length;
+        const closeMatch = closer.exec(text);
+        const bodyEnd = closeMatch
+            ? closeMatch.index + closeMatch[0].length
+            : text.length;
+        fenced.push([openMatch.index, bodyEnd]);
+        fence.lastIndex = bodyEnd;
+    }
+    for (const [from, to] of fenced)
+        mask(from, to);
+    // Inline spans, over what is left: a run of N backticks closes at the
+    // next run of exactly N.
+    let index = 0;
+    while (index < chars.length) {
+        if (chars[index] !== '`') {
+            index += 1;
+            continue;
+        }
+        let runEnd = index;
+        while (runEnd < chars.length && chars[runEnd] === '`')
+            runEnd += 1;
+        const runLength = runEnd - index;
+        let search = runEnd;
+        let closeEnd = -1;
+        while (search < chars.length) {
+            if (chars[search] !== '`') {
+                search += 1;
+                continue;
+            }
+            let candidateEnd = search;
+            while (candidateEnd < chars.length && chars[candidateEnd] === '`') {
+                candidateEnd += 1;
+            }
+            if (candidateEnd - search === runLength) {
+                closeEnd = candidateEnd;
+                break;
+            }
+            search = candidateEnd;
+        }
+        if (closeEnd === -1) {
+            index = runEnd;
+            continue;
+        }
+        mask(index, closeEnd);
+        index = closeEnd;
+    }
+    return chars.join('');
+}
+/** Splits a target into its path and its `#heading` / `^block` fragment. */
+function splitFragment(target) {
+    const hash = target.indexOf('#');
+    const caret = target.indexOf('^');
+    const cut = hash === -1 ? caret : caret === -1 ? hash : Math.min(hash, caret);
+    if (cut === -1)
+        return { path: target, fragment: '' };
+    return { path: target.slice(0, cut), fragment: target.slice(cut) };
+}
+/** Percent-decodes a markdown target, leaving it untouched when it is not valid escaping rather than throwing. */
+function decodeTarget(target) {
+    try {
+        return decodeURIComponent(target);
+    }
+    catch {
+        return target;
+    }
+}
+/** `[[target]]` and `[[target|alias]]`, with a leading `!` captured so an embed can be rejected. */
+const WIKILINK_PATTERN = /(!?)\[\[([^\]\n]*)\]\]/g;
+/**
+ * `[label](target)` and `[label](<target>)`, with an optional `"title"`,
+ * and a leading `!` captured so an image can be rejected. The label
+ * deliberately allows no nested `]`: a label with brackets in it is left
+ * alone rather than guessed at.
+ */
+const MARKDOWN_LINK_PATTERN = /(!?)\[([^\]\n]*)\]\((?:<([^>\n]*)>|([^)\s]*))(?:[ \t]+"[^"\n]*")?\)/g;
+/**
+ * Every note link in `text`, in document order. Embeds, images, URLs and
+ * bare fragments are all excluded, and anything inside code is invisible
+ * here.
+ */
+export function extractNoteLinks(text) {
+    const masked = maskCodeRegions(text);
+    const links = [];
+    let match;
+    WIKILINK_PATTERN.lastIndex = 0;
+    while ((match = WIKILINK_PATTERN.exec(masked)) !== null) {
+        if (match[1] === '!')
+            continue;
+        const inner = match[2] ?? '';
+        const pipe = inner.indexOf('|');
+        const rawTarget = (pipe === -1 ? inner : inner.slice(0, pipe)).trim();
+        const alias = pipe === -1 ? undefined : inner.slice(pipe + 1).trim();
+        if (!isLocalNoteTarget(rawTarget))
+            continue;
+        const { path, fragment } = splitFragment(rawTarget);
+        if (path.length === 0)
+            continue;
+        links.push({
+            kind: 'wikilink',
+            path,
+            fragment,
+            label: alias !== undefined && alias.length > 0 ? alias : rawTarget,
+            start: match.index,
+            end: match.index + match[0].length,
+        });
+    }
+    MARKDOWN_LINK_PATTERN.lastIndex = 0;
+    while ((match = MARKDOWN_LINK_PATTERN.exec(masked)) !== null) {
+        if (match[1] === '!')
+            continue;
+        const rawTarget = match[3] ?? match[4] ?? '';
+        if (!isLocalNoteTarget(rawTarget))
+            continue;
+        const { path, fragment } = splitFragment(decodeTarget(rawTarget));
+        if (path.length === 0)
+            continue;
+        links.push({
+            kind: 'markdown',
+            path,
+            fragment,
+            label: match[2] ?? '',
+            start: match.index,
+            end: match.index + match[0].length,
+        });
+    }
+    return links.sort((left, right) => left.start - right.start);
+}
+/** Escapes the characters that would break out of a markdown link label. */
+function escapeLinkLabel(label) {
+    return label.replace(/([[\]])/g, '\\$1');
+}
+/** Escapes the characters that would break out of a markdown link destination, and percent-encodes spaces so the href survives. */
+function escapeLinkDestination(destination) {
+    return destination.replace(/[()]/g, encodeURIComponent).replace(/ /g, '%20');
+}
+/**
+ * Rewrites every link `resolve` claims, leaving every other byte of `text`
+ * untouched.
+ *
+ * A markdown link keeps its shape and only changes destination. A WIKILINK
+ * BECOMES A MARKDOWN LINK, which is a deliberate change and the only way a
+ * cascade is navigable: Markii renders CommonMark, where `[[Other note]]`
+ * is literal text rather than a link, so leaving wikilinks as written would
+ * produce a set of exported pages that cannot reach each other. A wikilink
+ * whose target is NOT in the export is left exactly as written, so nothing
+ * outside the exported set is ever invented.
+ */
+export function rewriteNoteLinks(text, resolve) {
+    const links = extractNoteLinks(text);
+    let result = text;
+    // Right to left, so an earlier link's offsets stay valid as we splice.
+    for (let index = links.length - 1; index >= 0; index -= 1) {
+        const link = links[index];
+        const destination = resolve(link);
+        if (destination === undefined)
+            continue;
+        const href = escapeLinkDestination(destination) + link.fragment;
+        const replacement = `[${escapeLinkLabel(link.label)}](${href})`;
+        result = result.slice(0, link.start) + replacement + result.slice(link.end);
+    }
+    return result;
+}