@plebeiantech/lat.md 0.12.3-fork.13 → 0.12.3-fork.14

package/dist/src/view/markdown.d.ts

@@ -1,4 +1,5 @@
 import type { Root } from 'mdast';
+import type { ViewDocumentTree } from './protocol.js';
 export type WikiLinkContext = {
     line: number;
 };
@@ -19,8 +20,8 @@ export type MarkdownRenderOptions = {
     lineOffset?: number;
     rewriteMarkdownLink?: (url: string) => string;
 };
-/** Render a lat.md file as safe HTML with resolved wiki links. */
+/** Normalize a lat.md file into the safe, parser-neutral view tree. */
 export declare function renderMarkdown(markdown: string, filePath: string, resolveWikiLink?: WikiLinkResolver, options?: MarkdownRenderOptions, parsedTree?: Root): Promise<{
-    html: string;
+    tree: ViewDocumentTree;
     title: string;
 }>;

package/dist/src/view/markdown.js

@@ -1,11 +1,15 @@
 import { basename, extname } from 'node:path';
 import rehypeSanitize, { defaultSchema } from 'rehype-sanitize';
+import rehypeRaw from 'rehype-raw';
+import rehypeKatex from 'rehype-katex';
 import rehypeSlug from 'rehype-slug';
-import rehypeStringify from 'rehype-stringify';
+import remarkEmoji from 'remark-emoji';
 import remarkRehype from 'remark-rehype';
 import { unified } from 'unified';
 import { visit } from 'unist-util-visit';
 import { parse } from '../parser.js';
+import { decorateExternalSiteLinks, toViewDocumentTree, } from './document-tree.js';
+import { highlightCode } from './highlight.js';
 const CODE_LINK_CLASSES = [
     'wiki-link-code',
     'wiki-link-active',
@@ -17,19 +21,61 @@ const CODE_LINK_CLASSES = [
     'code-language-rs',
     'code-language-go',
     'code-language-c',
+    'code-language-dart',
+    'code-language-java',
 ];
 const ERROR_CLASS = 'markdown-error';
-const EXTERNAL_LINK_CLASS = 'external-link';
-const EXTERNAL_LINK_ICON_CLASS = 'external-link-icon';
 const GIT_CLASSES = ['git-added', 'git-removed'];
-function classAttributes(tag) {
+const GEOJSON_SOURCE_CLASS = 'markdown-geojson-source';
+const HIGHLIGHT_CLASS = 'hljs';
+const MERMAID_SOURCE_CLASS = 'markdown-mermaid-source';
+const MATH_DIFF_BLOCK_CLASS = 'git-math-block';
+const RICH_FENCE_SOURCE_CLASS = 'markdown-diagram-source';
+const STL_SOURCE_CLASS = 'markdown-stl-source';
+const TOPOJSON_SOURCE_CLASS = 'markdown-topojson-source';
+const ALERT_KINDS = ['note', 'tip', 'important', 'warning', 'caution'];
+const ALERT_CLASSES = [
+    'markdown-alert',
+    'markdown-alert-title',
+    ...ALERT_KINDS.map((kind) => `markdown-alert-${kind}`),
+];
+const GITHUB_CUSTOM_EMOJI = new Set([
+    'atom',
+    'basecamp',
+    'basecampy',
+    'bowtie',
+    'electron',
+    'feelsgood',
+    'finnadie',
+    'fishsticks',
+    'fu',
+    'goberserk',
+    'godmode',
+    'hurtrealbad',
+    'neckbeard',
+    'octocat',
+    'rage1',
+    'rage2',
+    'rage3',
+    'rage4',
+    'shipit',
+    'suspect',
+    'trollface',
+]);
+function classAttributes(tag, extraClasses = []) {
     const attributes = defaultSchema.attributes?.[tag] ?? [];
     const allowedClasses = attributes.flatMap((attribute) => Array.isArray(attribute) && attribute[0] === 'className'
         ? attribute.slice(1)
         : []);
     return [
         ...attributes.filter((attribute) => !(Array.isArray(attribute) && attribute[0] === 'className')),
-        ['className', ...allowedClasses, ERROR_CLASS, ...GIT_CLASSES],
+        [
+            'className',
+            ...allowedClasses,
+            ERROR_CLASS,
+            ...GIT_CLASSES,
+            ...extraClasses,
+        ],
     ];
 }
 const sanitizeSchema = {
@@ -45,50 +91,151 @@ const sanitizeSchema = {
                 'wiki-link-segmented',
                 'wiki-link-code',
                 'wiki-link-active',
-                EXTERNAL_LINK_CLASS,
                 ERROR_CLASS,
                 ...GIT_CLASSES,
             ],
         ],
         blockquote: classAttributes('blockquote'),
-        code: classAttributes('code'),
+        code: classAttributes('code', [
+            HIGHLIGHT_CLASS,
+            'math-display',
+            'math-inline',
+        ]),
         del: classAttributes('del'),
-        div: classAttributes('div'),
+        details: [...(defaultSchema.attributes?.details ?? []), ['open', true]],
+        div: classAttributes('div', [...ALERT_CLASSES, MATH_DIFF_BLOCK_CLASS]),
         h1: classAttributes('h1'),
         h2: classAttributes('h2'),
         h3: classAttributes('h3'),
         h4: classAttributes('h4'),
         h5: classAttributes('h5'),
         h6: classAttributes('h6'),
-        img: classAttributes('img'),
+        img: classAttributes('img', ['markdown-emoji']),
+        input: [...(defaultSchema.attributes?.input ?? []), ['checked', true]],
         ins: classAttributes('ins'),
         li: classAttributes('li'),
         ol: classAttributes('ol'),
-        p: classAttributes('p'),
-        pre: classAttributes('pre'),
+        p: classAttributes('p', ALERT_CLASSES),
+        pre: classAttributes('pre', [
+            GEOJSON_SOURCE_CLASS,
+            MERMAID_SOURCE_CLASS,
+            RICH_FENCE_SOURCE_CLASS,
+            STL_SOURCE_CLASS,
+            TOPOJSON_SOURCE_CLASS,
+        ]),
         span: [
             ...(defaultSchema.attributes?.span ?? []),
             'ariaHidden',
             'ariaLabel',
+            'role',
             [
                 'className',
                 'wiki-link-context',
                 'wiki-link-leaf',
                 'wiki-link-ref-count',
-                EXTERNAL_LINK_ICON_CLASS,
                 ...CODE_LINK_CLASSES.slice(2),
+                /^hljs-./,
                 ERROR_CLASS,
                 ...GIT_CLASSES,
             ],
         ],
+        table: classAttributes('table'),
+        tr: classAttributes('tr'),
         ul: classAttributes('ul'),
     },
 };
-const htmlProcessor = unified()
-    .use(remarkRehype)
+const highlightedCodeHandler = (state, rawNode) => {
+    const node = rawNode;
+    const language = node.lang?.split(/\s+/, 1)[0];
+    const richSourceClass = language?.toLowerCase() === 'mermaid'
+        ? MERMAID_SOURCE_CLASS
+        : language?.toLowerCase() === 'geojson'
+            ? GEOJSON_SOURCE_CLASS
+            : language?.toLowerCase() === 'topojson'
+                ? TOPOJSON_SOURCE_CLASS
+                : language?.toLowerCase() === 'stl'
+                    ? STL_SOURCE_CLASS
+                    : null;
+    const highlighted = language && !richSourceClass ? highlightCode(language, node.value) : null;
+    const code = {
+        type: 'element',
+        tagName: 'code',
+        properties: {
+            className: [
+                ...(language ? [`language-${language}`] : []),
+                ...(highlighted === null ? [] : [HIGHLIGHT_CLASS]),
+            ],
+        },
+        children: highlighted === null
+            ? [
+                {
+                    type: 'text',
+                    value: node.value ? `${node.value}\n` : '',
+                },
+            ]
+            : [...highlighted.children, { type: 'text', value: '\n' }],
+        ...(node.meta ? { data: { meta: node.meta } } : {}),
+    };
+    state.patch(node, code);
+    const result = state.applyData(node, code);
+    const pre = {
+        type: 'element',
+        tagName: 'pre',
+        properties: {
+            className: richSourceClass
+                ? [RICH_FENCE_SOURCE_CLASS, richSourceClass]
+                : [],
+        },
+        children: [result],
+    };
+    state.patch(node, pre);
+    return pre;
+};
+const documentTreeProcessor = unified()
+    .use(remarkRehype, {
+    allowDangerousHtml: true,
+    handlers: { code: highlightedCodeHandler },
+})
+    .use(rehypeRaw)
     .use(rehypeSanitize, sanitizeSchema)
-    .use(rehypeSlug)
-    .use(rehypeStringify);
+    .use(rehypeKatex)
+    .use(rehypeSlug);
+const emojiProcessor = unified().use(remarkEmoji, { accessible: true });
+function transformCustomEmoji(tree) {
+    visit(tree, 'text', (node, index, parent) => {
+        if (index === undefined || !parent || !node.value.includes(':'))
+            return;
+        const pattern = /:([a-z0-9_+-]+):/g;
+        const children = [];
+        let cursor = 0;
+        let match;
+        while ((match = pattern.exec(node.value))) {
+            if (!GITHUB_CUSTOM_EMOJI.has(match[1]))
+                continue;
+            if (match.index > cursor) {
+                children.push({
+                    type: 'text',
+                    value: node.value.slice(cursor, match.index),
+                });
+            }
+            children.push({
+                type: 'image',
+                url: `https://github.githubassets.com/images/icons/emoji/${match[1]}.png?v8`,
+                alt: match[0],
+                title: null,
+                data: { hProperties: { className: ['markdown-emoji'] } },
+            });
+            cursor = match.index + match[0].length;
+        }
+        if (children.length === 0)
+            return;
+        if (cursor < node.value.length) {
+            children.push({ type: 'text', value: node.value.slice(cursor) });
+        }
+        parent.children.splice(index, 1, ...children);
+        return index + children.length;
+    });
+}
 function nodeText(node) {
     if (typeof node.value === 'string')
         return node.value;
@@ -98,6 +245,38 @@ function nodeText(node) {
         .map((child) => nodeText(child))
         .join('');
 }
+function transformAlerts(tree) {
+    visit(tree, 'blockquote', (node) => {
+        const firstBlock = node.children[0];
+        if (firstBlock?.type !== 'paragraph')
+            return;
+        const firstInline = firstBlock.children[0];
+        if (firstInline?.type !== 'alertMarker')
+            return;
+        const label = firstInline.value;
+        const kind = label.toLowerCase();
+        firstBlock.children.shift();
+        if (firstBlock.children.length === 0)
+            node.children.shift();
+        node.data = {
+            ...node.data,
+            hName: 'div',
+            hProperties: {
+                ...(node.data?.hProperties ?? {}),
+                className: ['markdown-alert', `markdown-alert-${kind}`],
+            },
+        };
+        node.children.unshift({
+            type: 'paragraph',
+            data: {
+                hProperties: { className: ['markdown-alert-title'] },
+            },
+            children: [
+                { type: 'text', value: label[0] + label.slice(1).toLowerCase() },
+            ],
+        });
+    });
+}
 function wikiLinkContent(node) {
     if (node.data.alias) {
         return {
@@ -151,6 +330,10 @@ function codeLanguage(target) {
         case '.c':
         case '.h':
             return { className: 'code-language-c', label: 'C' };
+        case '.dart':
+            return { className: 'code-language-dart', label: 'DART' };
+        case '.java':
+            return { className: 'code-language-java', label: 'JAVA' };
         default:
             return null;
     }
@@ -194,22 +377,6 @@ function codeLinkContent(language, children) {
         ...rest,
     ];
 }
-function externalLinkIcon() {
-    return {
-        type: 'emphasis',
-        data: {
-            hName: 'span',
-            hProperties: {
-                ariaHidden: 'true',
-                className: [EXTERNAL_LINK_ICON_CLASS],
-            },
-        },
-        children: [],
-    };
-}
-function isExternalSiteUrl(url) {
-    return /^(?:https?:)?\/\//i.test(url);
-}
 function referenceCountBadge(count) {
     return {
         type: 'emphasis',
@@ -291,10 +458,13 @@ function markMarkdownErrors(tree, errors) {
         };
     }
 }
-/** Render a lat.md file as safe HTML with resolved wiki links. */
+/** Normalize a lat.md file into the safe, parser-neutral view tree. */
 export async function renderMarkdown(markdown, filePath, resolveWikiLink, options = {}, parsedTree) {
     const tree = parsedTree ? structuredClone(parsedTree) : parse(markdown);
     tree.children = tree.children.filter((node) => node.type !== 'yaml');
+    await emojiProcessor.run(tree);
+    transformCustomEmoji(tree);
+    transformAlerts(tree);
     if (options.errors)
         markMarkdownErrors(tree, options.errors);
     visit(tree, 'link', (node) => {
@@ -312,23 +482,11 @@ export async function renderMarkdown(markdown, filePath, resolveWikiLink, option
         if (options.rewriteMarkdownLink) {
             node.url = options.rewriteMarkdownLink(authoredUrl);
         }
-        if (!isExternalSiteUrl(node.url))
-            return;
-        const properties = node.data?.hProperties ?? {};
-        const currentClasses = properties.className;
-        const classes = Array.isArray(currentClasses)
-            ? currentClasses.map(String)
-            : currentClasses
-                ? [String(currentClasses)]
-                : [];
-        node.data = {
-            ...node.data,
-            hProperties: {
-                ...properties,
-                className: [...classes, EXTERNAL_LINK_CLASS],
-            },
-        };
-        node.children.push(externalLinkIcon());
+    });
+    visit(tree, 'image', (node) => {
+        if (options.rewriteMarkdownLink) {
+            node.url = options.rewriteMarkdownLink(node.url);
+        }
     });
     const firstHeading = tree.children.find((node) => node.type === 'heading');
     const title = firstHeading
@@ -354,7 +512,7 @@ export async function renderMarkdown(markdown, filePath, resolveWikiLink, option
         if (resolution) {
             const { href, referenceCount } = resolution;
             const content = wikiLinkContent(node);
-            const language = href.startsWith('/code/')
+            const language = href.startsWith('/code/') || href.startsWith('/external/')
                 ? codeLanguage(node.value)
                 : null;
             const classes = content.segmented ? ['wiki-link-segmented'] : [];
@@ -404,6 +562,9 @@ export async function renderMarkdown(markdown, filePath, resolveWikiLink, option
                 value: `[[${node.value}${alias}]]`,
             };
     });
-    const hast = await htmlProcessor.run(tree);
-    return { html: htmlProcessor.stringify(hast), title };
+    const hast = await documentTreeProcessor.run(tree);
+    return {
+        tree: decorateExternalSiteLinks(toViewDocumentTree(hast)),
+        title,
+    };
 }

package/dist/src/view/protocol.d.ts

@@ -2,8 +2,14 @@ export type ViewGitFileStatus = 'modified' | 'new';
 export type ViewGitState = {
     files: Record<string, ViewGitFileStatus>;
 };
+export type ViewExternalFile = {
+    handle: string;
+    path: string;
+    target: string;
+};
 export type ViewIndex = {
     files: string[];
+    externalFiles: ViewExternalFile[];
     entry: string;
     errorCounts: Record<string, number>;
     git: ViewGitState | null;
@@ -30,10 +36,36 @@ export type ViewSearchResponse = {
     query: string;
     results: ViewSearchResult[];
 };
-export type ViewProjectChange = {
+export type ViewDocumentProperty = string | number | boolean | null | (string | number)[];
+export type ViewDocumentText = {
+    type: 'text';
+    value: string;
+};
+export type ViewDocumentElement = {
+    type: 'element';
+    tagName: string;
+    properties: Record<string, ViewDocumentProperty>;
+    children: ViewDocumentNode[];
+};
+export type ViewDocumentNode = ViewDocumentText | ViewDocumentElement;
+/** Versioned, parser-neutral presentation tree sent to the browser. */
+export type ViewDocumentTree = {
+    version: 1;
+    type: 'root';
+    children: ViewDocumentNode[];
+};
+export type ViewSectionCommandOutput = {
+    output: string;
+    tree: ViewDocumentTree;
+    isError: boolean;
+};
+export type ViewProjectGeneration = {
     generation: number;
     markdownGeneration: number;
 };
+export type ViewProjectChange = ViewProjectGeneration & {
+    instanceId: string;
+};
 export type ViewGraphNodeKind = 'document' | 'source' | 'code-reference';
 export type ViewGraphNode = {
     id: string;
@@ -49,6 +81,7 @@ export type ViewGraphNode = {
     symbol?: string;
     line?: number;
     snippet?: string;
+    externalTarget?: string;
     gitStatus?: ViewGitFileStatus;
     errorCount?: number;
 };
@@ -75,8 +108,8 @@ export type ViewDocumentTocItem = {
 export type ViewDocument = {
     path: string;
     title: string;
-    html: string;
-    gitHtml: string | null;
+    tree: ViewDocumentTree;
+    gitTree: ViewDocumentTree | null;
     graphNodeIds: Record<string, string>;
     tableOfContents: ViewDocumentTocItem[];
     errors: ViewDocumentError[];
@@ -85,12 +118,23 @@ export type ViewDocument = {
         requireCodeMention: boolean;
     };
 };
+export type ViewDocumentSource = {
+    path: string;
+    content: string;
+};
+export type ViewDocumentEditRequest = {
+    baseContent: string;
+    content: string;
+};
+export type ViewDocumentEditResponse = ViewDocumentSource & {
+    merged: boolean;
+};
 export type ViewMarkdownBackReference = {
     kind: 'markdown';
     sectionId: string;
     breadcrumbs: string[];
     paragraph: string;
-    paragraphHtml: string;
+    paragraphTree: ViewDocumentTree;
     url: string;
 };
 export type ViewCodeBackReference = {
@@ -110,13 +154,13 @@ export type ViewSourceReference = {
     sectionId: string;
     breadcrumbs: string[];
     paragraph: string;
-    paragraphHtml: string;
+    paragraphTree: ViewDocumentTree;
     url: string;
 };
 export type ViewSourceDocument = {
     path: string;
     content: string;
-    highlightedHtmlLines: string[];
+    highlightedLines: ViewDocumentTree[];
     focus: {
         symbol: string;
         kind: string;
@@ -127,6 +171,15 @@ export type ViewSourceDocument = {
     context: ViewSourceReference | null;
     otherReferences: ViewSourceReference[];
 };
+export type ViewExternalDocument = {
+    kind: 'markdown';
+    target: string;
+    document: ViewDocument;
+} | {
+    kind: 'source';
+    target: string;
+    source: ViewSourceDocument;
+};
 export type ViewError = {
     error: string;
 };

package/dist/src/view/references.d.ts

@@ -1,34 +1,14 @@
-import type { Root } from 'mdast';
 import type { CodeRef } from '../code-refs.js';
-import { type Ref, type MdLink, type Section } from '../lattice.js';
+import { type Section } from '../lattice-model.js';
+import { type MarkdownFileAnalysis, type MarkdownParagraph } from '../markdown-analysis.js';
 import { type WikiLinkResolver } from './markdown.js';
 import type { ViewCodeBackReference, ViewSectionBackReferences, ViewSourceReference } from './protocol.js';
 export type SourceReferenceOrigin = {
     sectionId: string;
     line: number;
 };
-type ParagraphContent = {
-    markdown: string;
-    startLine: number;
-    text: string;
-};
-type MarkdownLink = {
-    kind: 'image' | 'link';
-    line: number;
-    url: string;
-};
-export type ViewParsedMarkdownFile = {
-    absolutePath: string;
-    content: string;
-    path: string;
-    projectPath: string;
-    tree: Root;
-    sections: Section[];
-    wikiRefs: Ref[];
-    paragraphs: Map<number, ParagraphContent>;
-    markdownLinks: MarkdownLink[];
-    validationLinks: MdLink[];
-};
+type ParagraphContent = MarkdownParagraph;
+export type ViewParsedMarkdownFile = MarkdownFileAnalysis;
 export type ViewCodeReferenceFile = {
     path: string;
     lines: string[];
@@ -48,12 +28,17 @@ export type ViewReferenceIndex = {
     incomingBySection: ReadonlyMap<string, readonly IndexedBackReference[]>;
     sourceByTarget: ReadonlyMap<string, readonly IndexedMarkdownReference[]>;
     sourceReferenceCounts: ReadonlyMap<string, number>;
+    externalByTarget: ReadonlyMap<string, readonly IndexedBackReference[]>;
 };
 /** Parse one Markdown file once into every structure needed by the view store. */
 export declare function parseViewMarkdownFile(absolutePath: string, content: string, latDir: string, projectRoot: string): ViewParsedMarkdownFile;
 export declare function linkedSection(url: string, sourcePath: string, sectionsByPath: ReadonlyMap<string, Section[]>): Section | null;
 /** Resolve cached outgoing occurrences into direct section and source indexes. */
-export declare function buildViewReferenceIndex(markdownFiles: Iterable<ViewParsedMarkdownFile>, codeFiles: Iterable<ViewCodeReferenceFile>, allSections: Section[]): ViewReferenceIndex;
+export declare function buildViewReferenceIndex(markdownFiles: Iterable<ViewParsedMarkdownFile>, codeFiles: Iterable<ViewCodeReferenceFile>, allSections: Section[], resolveExternalTarget?: (target: string) => string | null): ViewReferenceIndex;
+/** Render exact local Markdown and code backlinks for external targets. */
+export declare function renderExternalSectionBackReferences(index: ViewReferenceIndex, targets: ReadonlyMap<string, string>, latDir: string, projectRoot: string, createWikiLinkResolver?: (requestedPath: string) => Promise<WikiLinkResolver>): Promise<ViewSectionBackReferences[]>;
+/** Adapt exact external backlinks to the source context presentation. */
+export declare function renderExternalSourceReferences(index: ViewReferenceIndex, target: string, latDir: string, projectRoot: string, createWikiLinkResolver?: (requestedPath: string) => Promise<WikiLinkResolver>): Promise<ViewSourceReference[]>;
 /** Render direct reverse-index entries for the sections visible in one file. */
 export declare function renderSectionBackReferences(index: ViewReferenceIndex, visibleSections: Section[], latDir: string, projectRoot: string, createWikiLinkResolver?: (requestedPath: string) => Promise<WikiLinkResolver>): Promise<ViewSectionBackReferences[]>;
 /** Render cached Markdown occurrences that point to one source target. */