cli-jaw 2.0.4 → 2.0.5

package/public/manager/src/notes/rendering/MarkdownRenderer.tsx

@@ -1,5 +1,5 @@
-import { isValidElement } from 'react';
-import type { ComponentProps, ReactNode } from 'react';
+import { createElement, isValidElement, useMemo } from 'react';
+import type { ComponentProps, CSSProperties, ReactNode } from 'react';
 import ReactMarkdown from 'react-markdown';
 import rehypeKatex from 'rehype-katex';
 import rehypeSanitize from 'rehype-sanitize';
@@ -14,15 +14,45 @@ import {
     notesImageSrc,
     safeMarkdownUrl,
 } from './markdown-render-security';
+import { buildWikiLinkLookup, splitChildrenWithWikiLinks, type WikiLinkContext } from '../wiki-link-rendering';
+import { splitPreviewFrontmatter } from '../frontmatter-preview';
+import type { NotesNoteLinkRef, NotesNoteMetadata } from '../notes-types';
 
 type MarkdownRendererProps = {
     markdown: string;
+    outgoing?: NotesNoteLinkRef[] | undefined;
+    notes?: readonly NotesNoteMetadata[] | undefined;
+    onWikiLinkNavigate?: ((path: string) => void) | undefined;
 };
 
 type MarkdownAnchorProps = ComponentProps<'a'> & {
     node?: unknown;
 };
 
+type WikiContainerTag =
+    | 'p'
+    | 'li'
+    | 'h1'
+    | 'h2'
+    | 'h3'
+    | 'h4'
+    | 'h5'
+    | 'h6'
+    | 'blockquote'
+    | 'td'
+    | 'th'
+    | 'em'
+    | 'strong'
+    | 'del';
+
+type WikiContainerProps = {
+    children?: ReactNode;
+    className?: string | undefined;
+    id?: string | undefined;
+    style?: CSSProperties | undefined;
+    node?: unknown;
+};
+
 function textFromNode(node: ReactNode): string {
     if (typeof node === 'string' || typeof node === 'number') return String(node);
     if (Array.isArray(node)) return node.map(textFromNode).join('');
@@ -37,7 +67,27 @@ function languageFromCodeNode(node: ReactNode): string {
     return match?.[1] ?? 'text';
 }
 
+const NOOP_NAVIGATE = (_path: string): void => {};
+
 export function MarkdownRenderer(props: MarkdownRendererProps) {
+    const renderedMarkdown = useMemo(
+        () => splitPreviewFrontmatter(props.markdown).body,
+        [props.markdown],
+    );
+
+    const wikiCtx = useMemo<WikiLinkContext>(() => ({
+        lookup: buildWikiLinkLookup(props.outgoing),
+        outgoing: props.outgoing,
+        notes: props.notes,
+        onNavigate: props.onWikiLinkNavigate ?? NOOP_NAVIGATE,
+    }), [props.outgoing, props.notes, props.onWikiLinkNavigate]);
+
+    const wikiTransform = (tag: WikiContainerTag) => (containerProps: WikiContainerProps) => {
+        const { children, node: _node, className, id, style } = containerProps;
+        const transformed = splitChildrenWithWikiLinks(children, wikiCtx, tag);
+        return createElement(tag, { className, id, style }, transformed);
+    };
+
     return (
         <ReactMarkdown
             skipHtml
@@ -76,9 +126,23 @@ export function MarkdownRenderer(props: MarkdownRendererProps) {
                     if (!safeSrc) return null;
                     return <img {...imageProps} src={safeSrc} alt={alt ?? ''} loading="lazy" />;
                 },
+                p: wikiTransform('p'),
+                li: wikiTransform('li'),
+                h1: wikiTransform('h1'),
+                h2: wikiTransform('h2'),
+                h3: wikiTransform('h3'),
+                h4: wikiTransform('h4'),
+                h5: wikiTransform('h5'),
+                h6: wikiTransform('h6'),
+                blockquote: wikiTransform('blockquote'),
+                td: wikiTransform('td'),
+                th: wikiTransform('th'),
+                em: wikiTransform('em'),
+                strong: wikiTransform('strong'),
+                del: wikiTransform('del'),
             }}
         >
-            {props.markdown}
+            {renderedMarkdown}
         </ReactMarkdown>
     );
 }

package/public/manager/src/notes/rendering/MermaidBlock.tsx

@@ -1,4 +1,5 @@
 import { useEffect, useId, useState } from 'react';
+import { preprocessMermaid, sanitizeMermaidForRetry } from '../../../../js/render/mermaid-preprocess';
 
 type MermaidApi = {
     initialize(config: Record<string, unknown>): void;
@@ -40,7 +41,16 @@ export function MermaidBlock(props: MermaidBlockProps) {
             setState({ status: 'loading' });
             try {
                 const mermaid = await loadMermaid();
-                const { svg } = await mermaid.render(`notes-mermaid-${reactId}`, props.code);
+                const code = preprocessMermaid(props.code);
+                const id = `notes-mermaid-${reactId}`;
+                let svg: string;
+                try {
+                    ({ svg } = await mermaid.render(id, code));
+                } catch (firstErr: unknown) {
+                    const retryCode = sanitizeMermaidForRetry(code);
+                    if (!retryCode) throw firstErr;
+                    ({ svg } = await mermaid.render(`${id}-retry`, retryCode));
+                }
                 if (!cancelled) setState({ status: 'ready', svg });
             } catch (err) {
                 if (!cancelled) {

package/public/manager/src/notes/useNoteDocument.ts

@@ -20,6 +20,11 @@ export type UseNoteDocumentResult = {
     clearConflict: () => void;
 };
 
+async function settlePendingEditorChanges(): Promise<void> {
+    await Promise.resolve();
+    await new Promise<void>(resolve => setTimeout(resolve, 0));
+}
+
 export function useNoteDocument(): UseNoteDocumentResult {
     const [file, setFile] = useState<DashboardNoteFileResponse | null>(null);
     const [content, setContentState] = useState('');
@@ -29,6 +34,7 @@ export function useNoteDocument(): UseNoteDocumentResult {
     const [error, setError] = useState<string | null>(null);
     const [conflict, setConflict] = useState<NoteConflictState | null>(null);
     const latestContentRef = useRef('');
+    const dirtyRef = useRef(false);
     const savingRef = useRef(false);
 
     const load = useCallback(async (path: string): Promise<void> => {
@@ -39,6 +45,7 @@ export function useNoteDocument(): UseNoteDocumentResult {
             const next = await fetchNoteFile(path);
             setFile(next);
             latestContentRef.current = next.content;
+            dirtyRef.current = false;
             setContentState(next.content);
             setDirty(false);
         } catch (err) {
@@ -50,12 +57,14 @@ export function useNoteDocument(): UseNoteDocumentResult {
 
     function setContent(value: string): void {
         latestContentRef.current = value;
+        dirtyRef.current = true;
         setContentState(value);
         setDirty(true);
     }
 
     const save = useCallback(async (): Promise<void> => {
-        if (!file || !dirty || savingRef.current) return;
+        await settlePendingEditorChanges();
+        if (!file || !dirtyRef.current || savingRef.current) return;
         const contentSnapshot = latestContentRef.current;
         savingRef.current = true;
         setSaving(true);
@@ -70,6 +79,7 @@ export function useNoteDocument(): UseNoteDocumentResult {
             setFile(saved);
             if (latestContentRef.current === contentSnapshot) {
                 latestContentRef.current = saved.content;
+                dirtyRef.current = false;
                 setContentState(saved.content);
                 setDirty(false);
             }
@@ -95,7 +105,7 @@ export function useNoteDocument(): UseNoteDocumentResult {
             savingRef.current = false;
             setSaving(false);
         }
-    }, [dirty, file]);
+    }, [file]);
 
     const reloadFromDisk = useCallback(async (): Promise<void> => {
         if (!file) return;
@@ -103,6 +113,7 @@ export function useNoteDocument(): UseNoteDocumentResult {
     }, [file, load]);
 
     const overwrite = useCallback(async (): Promise<void> => {
+        await settlePendingEditorChanges();
         if (!file || savingRef.current) return;
         const contentSnapshot = latestContentRef.current;
         savingRef.current = true;
@@ -113,6 +124,7 @@ export function useNoteDocument(): UseNoteDocumentResult {
             setFile(saved);
             if (latestContentRef.current === contentSnapshot) {
                 latestContentRef.current = saved.content;
+                dirtyRef.current = false;
                 setContentState(saved.content);
                 setDirty(false);
             }

package/public/manager/src/notes/useNotesModel.ts

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { fetchNotesIndex, fetchNotesInfo, fetchNotesTree } from './notes-api';
 import { useInvalidationSubscription } from '../sync/useInvalidationSubscription';
 import { useNotesExternalSync } from './useNotesExternalSync';
@@ -6,10 +6,13 @@ import type { NotesTreeEntry, NotesVaultIndexSnapshot } from './notes-types';
 
 export type NotesModelState = {
     tree: NotesTreeEntry[];
+    filteredTree: NotesTreeEntry[];
     index: NotesVaultIndexSnapshot | null;
     loading: boolean;
     error: string | null;
     notesRoot: string | null;
+    tagFilter: string | null;
+    setTagFilter: (tag: string | null) => void;
     refresh: (selectPath?: string | null) => Promise<void>;
 };
 
@@ -36,12 +39,26 @@ function hasFile(entries: NotesTreeEntry[], path: string): boolean {
     return false;
 }
 
+function pruneTreeByPaths(entries: NotesTreeEntry[], allowed: Set<string>): NotesTreeEntry[] {
+    const out: NotesTreeEntry[] = [];
+    for (const entry of entries) {
+        if (entry.kind === 'file') {
+            if (allowed.has(entry.path)) out.push(entry);
+            continue;
+        }
+        const children = pruneTreeByPaths(entry.children || [], allowed);
+        if (children.length > 0) out.push({ ...entry, children });
+    }
+    return out;
+}
+
 export function useNotesModel(options: UseNotesModelOptions): NotesModelState {
     const [tree, setTree] = useState<NotesTreeEntry[]>([]);
     const [index, setIndex] = useState<NotesVaultIndexSnapshot | null>(null);
     const [loading, setLoading] = useState(false);
     const [error, setError] = useState<string | null>(null);
     const [notesRoot, setNotesRoot] = useState<string | null>(null);
+    const [tagFilter, setTagFilter] = useState<string | null>(null);
     const requestIdRef = useRef(0);
     const selectedPathRef = useRef(options.selectedPath);
     const onSelectedPathChangeRef = useRef(options.onSelectedPathChange);
@@ -87,5 +104,25 @@ export function useNotesModel(options: UseNotesModelOptions): NotesModelState {
         void refresh();
     }, [options.active, refresh]);
 
-    return { tree, index, loading, error, notesRoot, refresh };
+    const filteredTree = useMemo(() => {
+        if (!tagFilter || !index) return tree;
+        const allowed = new Set<string>();
+        for (const note of index.notes) {
+            if (note.tags && note.tags.includes(tagFilter)) allowed.add(note.path);
+        }
+        if (allowed.size === 0) return [];
+        return pruneTreeByPaths(tree, allowed);
+    }, [tagFilter, tree, index]);
+
+    return {
+        tree,
+        filteredTree,
+        index,
+        loading,
+        error,
+        notesRoot,
+        tagFilter,
+        setTagFilter,
+        refresh,
+    };
 }

package/public/manager/src/notes/wiki-link-codemirror-completion.ts

@@ -0,0 +1,55 @@
+import {
+    autocompletion,
+    insertCompletionText,
+    pickedCompletion,
+    type Completion,
+    type CompletionContext,
+    type CompletionResult,
+} from '@codemirror/autocomplete';
+import type { Extension } from '@codemirror/state';
+import type { NotesNoteMetadata } from './notes-types';
+import {
+    formatWikiLinkCompletion,
+    getWikiLinkCompletionRangeAtCursor,
+    getWikiLinkSuggestions,
+} from './wiki-link-suggestions';
+
+function wikiLinkCompletionApply(suggestion: ReturnType<typeof getWikiLinkSuggestions>[number]): NonNullable<Completion['apply']> {
+    return (view, completion, from, to) => {
+        const toWithClosingSuffix = view.state.sliceDoc(to, to + 2) === ']]' ? to + 2 : to;
+        view.dispatch({
+            ...insertCompletionText(view.state, formatWikiLinkCompletion(suggestion), from, toWithClosingSuffix),
+            annotations: pickedCompletion.of(completion),
+        });
+    };
+}
+
+export function wikiLinkCodeMirrorCompletion(notes: readonly NotesNoteMetadata[]): Extension {
+    function source(context: CompletionContext): CompletionResult | null {
+        const line = context.state.doc.lineAt(context.pos);
+        const lineText = context.state.sliceDoc(line.from, line.to);
+        const range = getWikiLinkCompletionRangeAtCursor(lineText, context.pos - line.from);
+        if (!range) return null;
+        const completionTo = line.from + range.to - (range.hasClosingSuffix ? 2 : 0);
+        const options: Completion[] = getWikiLinkSuggestions(notes, range.query).map(suggestion => ({
+            label: suggestion.title || suggestion.path,
+            detail: suggestion.path,
+            info: suggestion.matchKind === 'alias' ? `Alias: ${suggestion.aliases.join(', ')}` : suggestion.matchKind,
+            type: 'text',
+            apply: wikiLinkCompletionApply(suggestion),
+            boost: suggestion.score,
+        }));
+        if (options.length === 0) return null;
+        return {
+            from: line.from + range.from,
+            to: completionTo,
+            options,
+            validFor: /^[^\]\n]*$/,
+        };
+    }
+
+    return autocompletion({
+        activateOnTyping: true,
+        override: [source],
+    });
+}

package/public/manager/src/notes/wiki-link-rendering.ts

@@ -0,0 +1,129 @@
+import { Children, createElement, isValidElement, type MouseEvent, type ReactNode } from 'react';
+import type { NotesNoteLinkRef, NotesNoteMetadata } from './notes-types';
+import {
+    buildOutgoingWikiLinkLookup,
+    isEscaped,
+    resolveClientWikiLink,
+    WIKI_LINK_RE,
+    wikiLinkDisplayText,
+    wikiLinkReasonLabel,
+    type ClientWikiLinkResolution,
+} from './wiki-link-resolver';
+
+export {
+    firstUnescaped,
+    invalidWikiLinkTarget,
+    isEscaped,
+    parseWikiLinkToken,
+    WIKI_LINK_RE,
+    wikiLinkDisplayText,
+    wikiLinkReasonLabel,
+    type ClientWikiLinkResolution,
+    type ParsedWikiLinkToken,
+} from './wiki-link-resolver';
+
+type RenderableWikiLink = NotesNoteLinkRef | ClientWikiLinkResolution;
+
+export function buildWikiLinkLookup(
+    outgoing: readonly NotesNoteLinkRef[] | undefined | null,
+): Map<string, ClientWikiLinkResolution> {
+    return buildOutgoingWikiLinkLookup(outgoing);
+}
+
+export type WikiLinkContext = {
+    lookup: Map<string, RenderableWikiLink>;
+    outgoing?: readonly NotesNoteLinkRef[] | undefined;
+    notes?: readonly NotesNoteMetadata[] | undefined;
+    onNavigate: (path: string) => void;
+};
+
+function transformString(text: string, ctx: WikiLinkContext, keyPrefix: string): ReactNode[] {
+    if (!text) return [text];
+    const hasFallback = Boolean(ctx.notes?.length);
+    if (ctx.lookup.size === 0 && !hasFallback) return [text];
+    WIKI_LINK_RE.lastIndex = 0;
+    const result: ReactNode[] = [];
+    let cursor = 0;
+    let index = 0;
+    let match: RegExpExecArray | null;
+    while ((match = WIKI_LINK_RE.exec(text)) !== null) {
+        const start = match.index;
+        const end = start + match[0].length;
+        if (isEscaped(text, start)) continue;
+        const link = ctx.lookup.get(match[0]) ?? resolveClientWikiLink(match[0], ctx.outgoing, ctx.notes, start);
+        if (!link) continue;
+        if (start > cursor) result.push(text.slice(cursor, start));
+        const display = wikiLinkDisplayText(link, match[0]);
+        const key = `${keyPrefix}-wl-${index++}`;
+        if (link.status === 'resolved' && link.resolvedPath) {
+            const target = link.resolvedPath;
+            result.push(
+                createElement(
+                    'a',
+                    {
+                        key,
+                        className: 'notes-wikilink',
+                        href: `#${encodeURIComponent(target)}`,
+                        title: target,
+                        'data-notes-wiki-status': link.status,
+                        onClick: (event: MouseEvent<HTMLAnchorElement>) => {
+                            event.preventDefault();
+                            ctx.onNavigate(target);
+                        },
+                    },
+                    display,
+                ),
+            );
+        } else {
+            const reasonLabel = wikiLinkReasonLabel(link);
+            result.push(
+                createElement(
+                    'span',
+                    {
+                        key,
+                        className: 'notes-wikilink is-broken',
+                        title: reasonLabel,
+                        'data-notes-wiki-status': link.status,
+                        'aria-label': `Broken wikilink: ${match[1]}`,
+                    },
+                    display,
+                ),
+            );
+        }
+        cursor = end;
+    }
+    if (cursor === 0) return [text];
+    if (cursor < text.length) result.push(text.slice(cursor));
+    return result;
+}
+
+export function splitTextWithWikiLinks(
+    text: string,
+    lookup: Map<string, RenderableWikiLink>,
+    onNavigate: (path: string) => void,
+): ReactNode[] {
+    return transformString(text, { lookup, onNavigate }, 'text');
+}
+
+export function splitChildrenWithWikiLinks(children: ReactNode, ctx: WikiLinkContext, keyPrefix: string): ReactNode {
+    if (ctx.lookup.size === 0 && !ctx.notes?.length) return children;
+    const out: ReactNode[] = [];
+    let stringIndex = 0;
+    Children.forEach(children, (child, i) => {
+        if (typeof child === 'string') {
+            const segments = transformString(child, ctx, `${keyPrefix}-${stringIndex++}-${i}`);
+            for (const seg of segments) out.push(seg);
+            return;
+        }
+        if (typeof child === 'number' || typeof child === 'boolean' || child === null || child === undefined) {
+            out.push(child);
+            return;
+        }
+        if (isValidElement(child)) {
+            out.push(child);
+            return;
+        }
+        out.push(child);
+    });
+    return out;
+}

package/public/manager/src/notes/wiki-link-resolver.ts

@@ -0,0 +1,220 @@
+import type { NotesNoteLinkRef, NotesNoteMetadata } from './notes-types';
+
+export const WIKI_LINK_RE = /\[\[([^\[\]\n]+)\]\]/g;
+
+const WIKI_LINK_TOKEN_RE = /^\[\[([^\[\]\n]+)\]\]$/;
+const NOTE_FILE_EXT = '.md';
+const RESERVED_NOTE_SEGMENTS = new Set(['.git', '.assets', '_templates', '_snippets', '_plugins']);
+
+export type ParsedWikiLinkToken = {
+    raw: string;
+    inner: string;
+    target: string;
+    heading: string | null;
+    displayText: string | null;
+};
+
+export type ClientWikiLinkResolution = NotesNoteLinkRef & {
+    source: 'outgoing' | 'notes-fallback';
+};
+
+type NotesIndex = {
+    byPath: Map<string, NotesNoteMetadata>;
+    byPathNoExt: Map<string, NotesNoteMetadata>;
+    byAlias: Map<string, NotesNoteMetadata[]>;
+    byStem: Map<string, NotesNoteMetadata[]>;
+};
+
+export function isEscaped(text: string, index: number): boolean {
+    let backslashes = 0;
+    for (let cursor = index - 1; cursor >= 0 && text[cursor] === '\\'; cursor--) {
+        backslashes++;
+    }
+    return backslashes % 2 === 1;
+}
+
+export function firstUnescaped(text: string, char: string): number {
+    for (let index = 0; index < text.length; index++) {
+        if (text[index] === char && !isEscaped(text, index)) return index;
+    }
+    return -1;
+}
+
+export function parseWikiLinkToken(raw: string): ParsedWikiLinkToken | null {
+    const match = raw.match(WIKI_LINK_TOKEN_RE);
+    if (!match) return null;
+    const inner = match[1]?.trim() ?? '';
+    if (!inner) return null;
+    const pipe = firstUnescaped(inner, '|');
+    const targetPart = (pipe === -1 ? inner : inner.slice(0, pipe)).trim();
+    const displayPart = pipe === -1 ? '' : inner.slice(pipe + 1).trim();
+    const headingIndex = firstUnescaped(targetPart, '#');
+    const target = (headingIndex === -1 ? targetPart : targetPart.slice(0, headingIndex)).trim();
+    const heading = headingIndex === -1 ? '' : targetPart.slice(headingIndex + 1).trim();
+    if (!target) return null;
+    return {
+        raw,
+        inner,
+        target,
+        heading: heading || null,
+        displayText: displayPart || null,
+    };
+}
+
+export function buildOutgoingWikiLinkLookup(
+    outgoing: readonly NotesNoteLinkRef[] | undefined | null,
+): Map<string, ClientWikiLinkResolution> {
+    const map = new Map<string, ClientWikiLinkResolution>();
+    if (!outgoing) return map;
+    for (const link of outgoing) {
+        if (!map.has(link.raw)) map.set(link.raw, { ...link, source: 'outgoing' });
+    }
+    return map;
+}
+
+function appendMulti(map: Map<string, NotesNoteMetadata[]>, key: string, note: NotesNoteMetadata): void {
+    const current = map.get(key) ?? [];
+    current.push(note);
+    map.set(key, current);
+}
+
+function pathWithoutExt(path: string): string {
+    return path.endsWith(NOTE_FILE_EXT) ? path.slice(0, -NOTE_FILE_EXT.length) : path;
+}
+
+function noteStem(path: string): string {
+    const filename = path.split('/').at(-1) || path;
+    return pathWithoutExt(filename);
+}
+
+function buildNotesIndex(notes: readonly NotesNoteMetadata[] | undefined | null): NotesIndex {
+    const index: NotesIndex = {
+        byPath: new Map(),
+        byPathNoExt: new Map(),
+        byAlias: new Map(),
+        byStem: new Map(),
+    };
+    for (const note of notes ?? []) {
+        index.byPath.set(note.path, note);
+        index.byPathNoExt.set(pathWithoutExt(note.path), note);
+        for (const alias of note.aliases) appendMulti(index.byAlias, alias, note);
+        appendMulti(index.byStem, noteStem(note.path), note);
+    }
+    return index;
+}
+
+function sortedPaths(notes: readonly NotesNoteMetadata[]): string[] {
+    return notes.map(note => note.path).sort((a, b) => a.localeCompare(b));
+}
+
+function hasReservedNoteSegment(target: string): boolean {
+    return target.split('/').some(part => RESERVED_NOTE_SEGMENTS.has(part));
+}
+
+export function invalidWikiLinkTarget(target: string): boolean {
+    if (!target || target.includes('\0') || target.includes('\\') || target.startsWith('/')) return true;
+    const parts = target.split('/');
+    if (parts.some(part => !part || part === '.' || part === '..')) return true;
+    return hasReservedNoteSegment(target);
+}
+
+function baseLink(
+    parsed: ParsedWikiLinkToken,
+    startOffset: number,
+): ClientWikiLinkResolution {
+    return {
+        source: 'notes-fallback',
+        sourcePath: '',
+        raw: parsed.raw,
+        target: parsed.target,
+        ...(parsed.displayText ? { displayText: parsed.displayText } : {}),
+        ...(parsed.heading ? { heading: parsed.heading } : {}),
+        line: 0,
+        column: 0,
+        startOffset,
+        endOffset: startOffset + parsed.raw.length,
+        status: 'missing',
+        reason: 'not_found',
+    };
+}
+
+function resolved(link: ClientWikiLinkResolution, path: string): ClientWikiLinkResolution {
+    const { candidatePaths: _candidatePaths, reason: _reason, ...base } = link;
+    return { ...base, status: 'resolved', resolvedPath: path };
+}
+
+function missing(
+    link: ClientWikiLinkResolution,
+    reason: 'not_found' | 'invalid_target',
+): ClientWikiLinkResolution {
+    const { candidatePaths: _candidatePaths, resolvedPath: _resolvedPath, ...base } = link;
+    return { ...base, status: 'missing', reason };
+}
+
+function ambiguous(link: ClientWikiLinkResolution, notes: readonly NotesNoteMetadata[]): ClientWikiLinkResolution {
+    const { resolvedPath: _resolvedPath, ...base } = link;
+    return {
+        ...base,
+        status: 'ambiguous',
+        reason: 'ambiguous',
+        candidatePaths: sortedPaths(notes),
+    };
+}
+
+function matchSingleOrAmbiguous(
+    link: ClientWikiLinkResolution,
+    notes: readonly NotesNoteMetadata[],
+): ClientWikiLinkResolution | null {
+    if (notes.length === 0) return null;
+    const [first] = notes;
+    if (notes.length === 1 && first) return resolved(link, first.path);
+    return ambiguous(link, notes);
+}
+
+export function resolveClientWikiLink(
+    raw: string,
+    outgoing: readonly NotesNoteLinkRef[] | undefined | null,
+    notes: readonly NotesNoteMetadata[] | undefined | null,
+    startOffset = 0,
+): ClientWikiLinkResolution | null {
+    const outgoingLink = buildOutgoingWikiLinkLookup(outgoing).get(raw);
+    if (outgoingLink) return outgoingLink;
+
+    const parsed = parseWikiLinkToken(raw);
+    if (!parsed) return null;
+    const link = baseLink(parsed, startOffset);
+    const target = parsed.target.trim();
+    if (invalidWikiLinkTarget(target)) return missing(link, 'invalid_target');
+
+    const index = buildNotesIndex(notes);
+    const exact = index.byPath.get(target);
+    if (exact) return resolved(link, exact.path);
+
+    if (!target.endsWith(NOTE_FILE_EXT)) {
+        const withExt = index.byPath.get(`${target}${NOTE_FILE_EXT}`);
+        if (withExt) return resolved(link, withExt.path);
+        const noExt = index.byPathNoExt.get(target);
+        if (noExt) return resolved(link, noExt.path);
+    }
+
+    const alias = matchSingleOrAmbiguous(link, index.byAlias.get(target) ?? []);
+    if (alias) return alias;
+
+    if (!target.includes('/')) {
+        const stem = matchSingleOrAmbiguous(link, index.byStem.get(target) ?? []);
+        if (stem) return stem;
+    }
+
+    return link;
+}
+
+export function wikiLinkDisplayText(link: Pick<NotesNoteLinkRef, 'target' | 'displayText'>, raw: string): string {
+    const parsed = parseWikiLinkToken(raw);
+    return link.displayText || parsed?.displayText || parsed?.inner || link.target || raw;
+}
+
+export function wikiLinkReasonLabel(link: Pick<NotesNoteLinkRef, 'reason'>): string {
+    if (link.reason === 'ambiguous') return 'Ambiguous link target';
+    if (link.reason === 'invalid_target') return 'Invalid link target';
+    return 'No matching note';
+}