@plebeiantech/lat.md 0.12.3-fork.9 → 0.13.4-fork.2

package/dist/src/view/static-build.js

@@ -1,22 +1,29 @@
+import { createPublicationPolicy } from './publication.js';
 import { createHash } from 'node:crypto';
 import { cp, lstat, mkdir, mkdtemp, readFile, rename, rm, writeFile, } from 'node:fs/promises';
 import { dirname, join, parse, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { isDocumentPath } from '@plebeiantech/lat.md-core/document-formats';
 import { DEFAULT_VIEW_LOGO_TEXT } from './protocol.js';
-import { viewStaticSourceKey, } from './static-protocol.js';
+import { documentTreeUrls, rewriteDocumentTreeUrls } from './document-tree.js';
+import { VIEW_STATIC_BOOTSTRAP_ID, viewStaticDocumentRequest, viewStaticSourceKey, } from './static-protocol.js';
 import { createViewStore } from './store.js';
-const BUILD_MARKER = '.lat-ui-build';
+import { rewriteClientAssetUrls } from './client-shell.js';
+import { documentResourcePath, documentPath, documentUrl, rawDocumentPath, validateDocumentRoutes, } from './document-route.js';
 const defaultClientDir = fileURLToPath(new URL('./client/', import.meta.url));
+const VIEW_BUILD_MOVE_MAX_RETRIES = 10;
+const VIEW_BUILD_MOVE_RETRY_DELAY_MS = 150;
 function isInside(parent, child) {
     const rel = relative(parent, child);
     return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`));
 }
 export function normalizeStaticViewBasePath(value) {
-    const parsed = new URL(value || '/', 'http://lat.local');
+    const path = value.startsWith('/') ? value : `/${value}`;
+    const parsed = new URL(path, 'http://lat.local');
     if (parsed.origin !== 'http://lat.local' ||
         parsed.search ||
         parsed.hash ||
-        !value.startsWith('/')) {
+        value.includes('://')) {
         throw new Error('Static UI base path must be an absolute URL path');
     }
     return parsed.pathname.endsWith('/')
@@ -44,8 +51,8 @@ function decodeHtmlUrlAttribute(value) {
     return value.replace(/&(amp|#38|#x26);/gi, '&');
 }
 /** Convert a live view route to its physical static-directory URL. */
-export function staticViewUrl(value, basePath) {
-    if (!value || value.startsWith('#'))
+export function staticViewUrl(value, basePath, entryPath) {
+    if (!value || !value.startsWith('/') || value.startsWith('//'))
         return value;
     let url;
     try {
@@ -56,7 +63,20 @@ export function staticViewUrl(value, basePath) {
     }
     if (url.origin !== 'http://lat.local')
         return value;
-    for (const prefix of ['/docs/', '/code/']) {
+    const markdownPath = documentPath(url.pathname.replace(/\/$/, ''));
+    if (markdownPath || rawDocumentPath(url.pathname)) {
+        const route = url.pathname.slice(1).replace(/\/+$/, '');
+        const suffix = `${url.search}${url.hash}`;
+        if (entryPath && markdownPath === entryPath) {
+            return `${basePath}${suffix}`;
+        }
+        return `${basePath}${route}${suffix}`;
+    }
+    if (url.pathname.startsWith('/resources/')) {
+        const route = url.pathname.slice(1);
+        return `${basePath}${route}${url.search}${url.hash}`;
+    }
+    for (const prefix of ['/code/', '/external/']) {
         if (!url.pathname.startsWith(prefix))
             continue;
         const route = url.pathname.slice(1).replace(/\/+$/, '');
@@ -65,96 +85,96 @@ export function staticViewUrl(value, basePath) {
     if (url.pathname === '/graph') {
         return `${basePath}graph/${url.search}${url.hash}`;
     }
+    if (url.pathname === '/' || url.pathname === '/search') {
+        return `${basePath}${url.pathname.slice(1)}${url.search}${url.hash}`;
+    }
     return value;
 }
 function documentPathFromUrl(value) {
-    if (!value.pathname.startsWith('/docs/'))
-        return null;
-    try {
-        return value.pathname
-            .slice('/docs/'.length)
-            .split('/')
-            .map(decodeURIComponent)
-            .join('/');
-    }
-    catch {
-        return null;
-    }
+    return documentPath(value.pathname) ?? rawDocumentPath(value.pathname);
 }
-function rewriteHtmlLink(value, basePath, sourcePath, documentPaths) {
-    const direct = staticViewUrl(value, basePath);
+function rewriteHtmlLink(value, basePath, entryPath, sourcePath, documentPaths) {
+    const direct = staticViewUrl(value, basePath, entryPath);
     if (direct !== value || !sourcePath || value.startsWith('#'))
         return direct;
     let resolved;
     try {
-        const currentPath = sourcePath.split('/').map(encodeURIComponent).join('/');
-        resolved = new URL(decodeHtmlUrlAttribute(value), `http://lat.local/docs/${currentPath}`);
+        const externalAt = sourcePath.indexOf(':');
+        const currentRoute = externalAt > 0 && !documentPaths.has(sourcePath)
+            ? `/external/${encodeURIComponent(sourcePath.slice(0, externalAt))}/${sourcePath
+                .slice(externalAt + 1)
+                .split('/')
+                .map(encodeURIComponent)
+                .join('/')}`
+            : documentUrl(sourcePath);
+        resolved = new URL(decodeHtmlUrlAttribute(value), `http://lat.local${currentRoute}`);
     }
     catch {
         return value;
     }
     const documentPath = documentPathFromUrl(resolved);
+    if (resolved.pathname.startsWith('/external/')) {
+        return staticViewUrl(`${resolved.pathname}${resolved.search}${resolved.hash}`, basePath, entryPath);
+    }
     if (resolved.origin !== 'http://lat.local' ||
         !documentPath ||
         !documentPaths.has(documentPath)) {
         return value;
     }
-    return staticViewUrl(`${resolved.pathname}${resolved.search}${resolved.hash}`, basePath);
+    return staticViewUrl(`${documentUrl(documentPath)}${resolved.search}${resolved.hash}`, basePath, entryPath);
 }
-function rewriteHtmlLinks(html, basePath, sourcePath, documentPaths) {
-    return html.replace(/href="([^"]*)"/g, (attribute, value) => {
-        const rewritten = rewriteHtmlLink(value, basePath, sourcePath, documentPaths);
-        if (rewritten === value)
-            return attribute;
-        return `href="${rewritten.replaceAll('&', '&').replaceAll('"', '"')}"`;
-    });
+function rewriteDocumentLinks(tree, basePath, entryPath, sourcePath, documentPaths) {
+    return rewriteDocumentTreeUrls(tree, (value) => rewriteHtmlLink(value, basePath, entryPath, sourcePath, documentPaths));
 }
-function rewriteMarkdownReference(reference, basePath, sourcePath, documentPaths) {
+function rewriteMarkdownReference(reference, basePath, entryPath, sourcePath, documentPaths) {
     return {
         ...reference,
-        paragraphHtml: rewriteHtmlLinks(reference.paragraphHtml, basePath, sourcePath, documentPaths),
-        url: staticViewUrl(reference.url, basePath),
+        paragraphTree: rewriteDocumentLinks(reference.paragraphTree, basePath, entryPath, sourcePath, documentPaths),
+        url: staticViewUrl(reference.url, basePath, entryPath),
     };
 }
-function rewriteBackReference(reference, basePath, sectionPaths, documentPaths) {
+function rewriteBackReference(reference, basePath, entryPath, sectionPaths, documentPaths) {
     return reference.kind === 'markdown'
-        ? rewriteMarkdownReference(reference, basePath, sectionPaths.get(reference.sectionId.split('#', 1)[0]) ?? null, documentPaths)
-        : { ...reference, url: staticViewUrl(reference.url, basePath) };
+        ? rewriteMarkdownReference(reference, basePath, entryPath, sectionPaths.get(reference.sectionId.split('#', 1)[0]) ?? null, documentPaths)
+        : {
+            ...reference,
+            url: staticViewUrl(reference.url, basePath, entryPath),
+        };
 }
-function rewriteDocument(document, basePath, sectionPaths, documentPaths) {
+function rewriteDocument(document, basePath, entryPath, sectionPaths, documentPaths) {
     return {
         ...document,
-        html: rewriteHtmlLinks(document.html, basePath, document.path, documentPaths),
-        gitHtml: null,
+        tree: rewriteDocumentLinks(document.tree, basePath, entryPath, document.path, documentPaths),
+        gitTree: null,
         backReferences: document.backReferences.map((section) => ({
             ...section,
-            references: section.references.map((reference) => rewriteBackReference(reference, basePath, sectionPaths, documentPaths)),
+            references: section.references.map((reference) => rewriteBackReference(reference, basePath, entryPath, sectionPaths, documentPaths)),
         })),
     };
 }
-function rewriteSourceReference(reference, basePath, sectionPaths, documentPaths) {
+function rewriteSourceReference(reference, basePath, entryPath, sectionPaths, documentPaths) {
     const sectionPath = reference.sectionId.split('#', 1)[0];
     return {
         ...reference,
-        paragraphHtml: rewriteHtmlLinks(reference.paragraphHtml, basePath, sectionPaths.get(sectionPath) ?? null, documentPaths),
-        url: staticViewUrl(reference.url, basePath),
+        paragraphTree: rewriteDocumentLinks(reference.paragraphTree, basePath, entryPath, sectionPaths.get(sectionPath) ?? null, documentPaths),
+        url: staticViewUrl(reference.url, basePath, entryPath),
     };
 }
-function rewriteSource(source, basePath, sectionPaths, documentPaths) {
+function rewriteSource(source, basePath, entryPath, sectionPaths, documentPaths) {
     return {
         ...source,
         context: source.context
-            ? rewriteSourceReference(source.context, basePath, sectionPaths, documentPaths)
+            ? rewriteSourceReference(source.context, basePath, entryPath, sectionPaths, documentPaths)
             : null,
-        otherReferences: source.otherReferences.map((reference) => rewriteSourceReference(reference, basePath, sectionPaths, documentPaths)),
+        otherReferences: source.otherReferences.map((reference) => rewriteSourceReference(reference, basePath, entryPath, sectionPaths, documentPaths)),
     };
 }
-function rewriteGraph(graph, basePath) {
+function rewriteGraph(graph, basePath, entryPath) {
     return {
         ...graph,
         nodes: graph.nodes.map(({ gitStatus: _gitStatus, ...node }) => ({
             ...node,
-            url: staticViewUrl(node.url, basePath),
+            url: staticViewUrl(node.url, basePath, entryPath),
         })),
     };
 }
@@ -163,8 +183,14 @@ function positiveInteger(value) {
     return Number.isInteger(parsed) && parsed > 0 ? parsed : 0;
 }
 function sourceRequest(value) {
-    const url = new URL(decodeHtmlUrlAttribute(value), 'http://lat.local');
-    if (!url.pathname.startsWith('/code/'))
+    let url;
+    try {
+        url = new URL(decodeHtmlUrlAttribute(value), 'http://lat.local');
+    }
+    catch {
+        return null;
+    }
+    if (url.origin !== 'http://lat.local' || !url.pathname.startsWith('/code/'))
         return null;
     let path;
     let symbol;
@@ -174,6 +200,14 @@ function sourceRequest(value) {
             .split('/')
             .map(decodeURIComponent)
             .join('/');
+        if (path.split('/').some((part) => !part || part === '.' || part === '..') ||
+            path.includes('\\') ||
+            path.includes('\0') ||
+            /^[a-z]:/i.test(path))
+            return null;
+        // Encoded separators cannot create extra route components after decoding.
+        if (/%(?:2f|5c)/i.test(url.pathname))
+            return null;
         symbol = decodeURIComponent(url.hash.slice(1));
     }
     catch {
@@ -187,21 +221,104 @@ function sourceRequest(value) {
         at: positiveInteger(url.searchParams.get('at')),
     };
 }
+function externalRequest(value, external) {
+    let url;
+    try {
+        url = new URL(decodeHtmlUrlAttribute(value), 'http://lat.local');
+    }
+    catch {
+        return null;
+    }
+    if (url.origin !== 'http://lat.local' ||
+        !url.pathname.startsWith('/external/'))
+        return null;
+    try {
+        const parts = url.pathname
+            .slice('/external/'.length)
+            .split('/')
+            .map(decodeURIComponent);
+        const handle = parts.shift() ?? '';
+        const path = parts.join('/');
+        if (!handle || !path)
+            return null;
+        const fragment = decodeURIComponent(url.hash.slice(1));
+        const target = `${handle}:${path}${fragment ? `#${fragment}` : ''}`;
+        const parsed = external?.parse(target);
+        if (parsed) {
+            if (!isDocumentPath(parsed.resolvedPath)) {
+                return parsed.identity;
+            }
+            const hash = parsed.identity.indexOf('#');
+            return hash === -1 ? parsed.identity : parsed.identity.slice(0, hash);
+        }
+        return `${handle}:${path}${isDocumentPath(path) || !fragment ? '' : `#${fragment}`}`;
+    }
+    catch {
+        return null;
+    }
+}
+function externalRequestsFromDocument(document, requests, external, externalBase) {
+    const add = (value) => {
+        let candidate = value;
+        if (externalBase && !value.startsWith('#')) {
+            try {
+                const colon = externalBase.indexOf(':');
+                const base = `/external/${encodeURIComponent(externalBase.slice(0, colon))}/${externalBase
+                    .slice(colon + 1)
+                    .split('/')
+                    .map(encodeURIComponent)
+                    .join('/')}`;
+                const resolved = new URL(decodeHtmlUrlAttribute(value), `http://lat.local${base}`);
+                if (resolved.origin === 'http://lat.local') {
+                    candidate = `${resolved.pathname}${resolved.hash}`;
+                }
+            }
+            catch {
+                // Leave malformed links to the renderer rather than exporting them.
+            }
+        }
+        const request = externalRequest(candidate, external);
+        if (request)
+            requests.add(request);
+    };
+    for (const value of documentTreeUrls(document.tree))
+        add(value);
+    for (const section of document.backReferences) {
+        for (const reference of section.references) {
+            add(reference.url);
+            if (reference.kind === 'markdown') {
+                for (const value of documentTreeUrls(reference.paragraphTree))
+                    add(value);
+            }
+        }
+    }
+}
+function externalRequestsFromSource(source, requests, external) {
+    for (const reference of [
+        ...(source.context ? [source.context] : []),
+        ...source.otherReferences,
+    ]) {
+        for (const value of documentTreeUrls(reference.paragraphTree)) {
+            const request = externalRequest(value, external);
+            if (request)
+                requests.add(request);
+        }
+    }
+}
 function sourceRequestsFromDocument(document, requests) {
     const add = (value) => {
         const request = sourceRequest(value);
         if (request)
             requests.set(viewStaticSourceKey(request), request);
     };
-    for (const match of document.html.matchAll(/href="([^"]*)"/g))
-        add(match[1]);
+    for (const value of documentTreeUrls(document.tree))
+        add(value);
     for (const section of document.backReferences) {
         for (const reference of section.references) {
             add(reference.url);
             if (reference.kind === 'markdown') {
-                for (const match of reference.paragraphHtml.matchAll(/href="([^"]*)"/g)) {
-                    add(match[1]);
-                }
+                for (const value of documentTreeUrls(reference.paragraphTree))
+                    add(value);
             }
         }
     }
@@ -212,20 +329,33 @@ function sourceRequestsFromSource(source, requests) {
         ...source.otherReferences,
     ];
     for (const reference of references) {
-        for (const match of reference.paragraphHtml.matchAll(/href="([^"]*)"/g)) {
-            const request = sourceRequest(match[1]);
+        for (const value of documentTreeUrls(reference.paragraphTree)) {
+            const request = sourceRequest(value);
             if (request)
                 requests.set(viewStaticSourceKey(request), request);
         }
     }
 }
-function dataFile(kind, key) {
-    const digest = createHash('sha256').update(key).digest('hex').slice(0, 20);
+function serializeJson(value) {
+    return `${JSON.stringify(value)}\n`;
+}
+function dataFile(kind, content) {
+    const digest = createHash('sha256')
+        .update(content)
+        .digest('hex')
+        .slice(0, 20);
     return `data/${kind}/${digest}.json`;
 }
 async function writeJson(path, value) {
     await mkdir(dirname(path), { recursive: true });
-    await writeFile(path, `${JSON.stringify(value)}\n`);
+    await writeFile(path, serializeJson(value));
+}
+async function writeDataJson(outputDir, kind, value) {
+    const content = serializeJson(value);
+    const path = dataFile(kind, content);
+    await mkdir(dirname(join(outputDir, path)), { recursive: true });
+    await writeFile(join(outputDir, path), content);
+    return path;
 }
 async function outputExists(path) {
     try {
@@ -238,16 +368,47 @@ async function outputExists(path) {
         throw error;
     }
 }
-async function validateOutput(outputDir, projectRoot) {
+/** Refuse build targets that exist or could replace the project itself. */
+export async function validateViewBuildOutput(outputDir, projectRoot, kind = 'Static', force = false) {
     if (outputDir === parse(outputDir).root ||
         outputDir === projectRoot ||
         isInside(outputDir, projectRoot)) {
-        throw new Error('Static UI output must not contain the project root');
+        throw new Error(`${kind} UI output must not contain the project root`);
     }
-    if (await outputExists(outputDir)) {
-        throw new Error(`Static UI output already exists: ${outputDir}`);
+    if (!force && (await outputExists(outputDir))) {
+        throw new Error(`${kind} UI output already exists: ${outputDir}. Use --force to replace it.`);
     }
 }
+const defaultViewBuildMoveDependencies = {
+    move: rename,
+    wait: (milliseconds) => new Promise((resolveWait) => setTimeout(resolveWait, milliseconds)),
+};
+/** Commit a staged build after transient filesystem locks have cleared. */
+export async function moveViewBuildOutput(stagingDir, outputDir, dependencies = defaultViewBuildMoveDependencies) {
+    for (let retries = 0;; retries += 1) {
+        try {
+            await dependencies.move(stagingDir, outputDir);
+            return;
+        }
+        catch (error) {
+            const code = error.code;
+            if (retries >= VIEW_BUILD_MOVE_MAX_RETRIES ||
+                (code !== 'EBUSY' && code !== 'EPERM' && code !== 'ENOTEMPTY')) {
+                throw error;
+            }
+            await dependencies.wait(VIEW_BUILD_MOVE_RETRY_DELAY_MS);
+        }
+    }
+}
+/** Remove abandoned staging after transient filesystem locks have cleared. */
+export async function removeViewBuildStaging(stagingDir) {
+    await rm(stagingDir, {
+        recursive: true,
+        force: true,
+        maxRetries: VIEW_BUILD_MOVE_MAX_RETRIES,
+        retryDelay: VIEW_BUILD_MOVE_RETRY_DELAY_MS,
+    });
+}
 function sectionDocumentPaths(documents) {
     const result = new Map();
     for (const path of documents.keys()) {
@@ -255,30 +416,65 @@ function sectionDocumentPaths(documents) {
     }
     return result;
 }
-function clientShell(html, basePath) {
-    const assets = html.replace(/(["'])\/assets\//g, (_match, quote) => `${quote}${basePath}assets/`);
-    const configValue = JSON.stringify({ basePath }).replaceAll('<', '\\u003c');
-    const config = `<script>globalThis.__LAT_STATIC_VIEW__=${configValue}</script>`;
+function clientShell(html, basePath, entry, searchApi) {
+    const assets = rewriteClientAssetUrls(html, basePath);
+    const configValue = encodeURIComponent(JSON.stringify({ basePath, entry, searchApi }));
+    const config = `<meta name="lat-static-view" content="${configValue}">`;
     return assets.includes('</head>')
         ? assets.replace('</head>', `  ${config}\n  </head>`)
         : `${config}\n${assets}`;
 }
-function redirectShell(target) {
+function bootstrapShell(shell, manifest, responses = {}) {
+    const bootstrap = { manifest, responses };
+    const value = JSON.stringify(bootstrap).replaceAll('<', '\\u003c');
+    const data = `<script id="${VIEW_STATIC_BOOTSTRAP_ID}" type="application/json">${value}</script>`;
+    return shell.includes('</head>')
+        ? shell.replace('</head>', `  ${data}\n  </head>`)
+        : `${data}\n${shell}`;
+}
+const REDIRECT_SCRIPT_PATH = 'data/redirect.js';
+const REDIRECT_SCRIPT = `const meta = document.querySelector('meta[name="lat-redirect"]');
+if (meta) {
+  try {
+    window.location.replace(decodeURIComponent(meta.content) + window.location.search + window.location.hash);
+  } catch {}
+}
+`;
+function redirectShell(target, basePath) {
     const escaped = target.replaceAll('&', '&amp;').replaceAll('"', '&quot;');
-    const scriptTarget = JSON.stringify(target).replaceAll('<', '\\u003c');
+    const scriptUrl = `${basePath}${REDIRECT_SCRIPT_PATH}`
+        .replaceAll('&', '&amp;')
+        .replaceAll('"', '&quot;');
     return `<!doctype html>
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta http-equiv="refresh" content="0;url=${escaped}" />
+    <meta name="lat-redirect" content="${encodeURIComponent(target)}" />
     <title>lat.md</title>
+    <script src="${scriptUrl}" defer></script>
   </head>
-  <body><script>window.location.replace(${scriptTarget} + window.location.hash)</script></body>
+  <body><a href="${escaped}">Open lat.md</a></body>
 </html>
 `;
 }
+/** All authored route writes must remain strictly below the payload root. */
+function publicationOutputPath(root, ...parts) {
+    if (parts.some((part) => part.includes('\\') ||
+        part.includes('\0') ||
+        part.split('/').some((segment) => segment === '..' || segment === '.')))
+        throw new Error('Unsafe export route');
+    const path = resolve(root, ...parts);
+    const rel = relative(root, path);
+    if (!rel ||
+        rel.startsWith(`..${sep}`) ||
+        rel === '..' ||
+        /^[a-z]:/i.test(rel) ||
+        rel.startsWith(sep))
+        throw new Error('Export route is outside the output directory');
+    return path;
+}
 async function writeRouteShell(outputDir, route, shell) {
-    const path = join(outputDir, ...route.split('/'), 'index.html');
+    const path = publicationOutputPath(outputDir, route, 'index.html');
     await mkdir(dirname(path), { recursive: true });
     await writeFile(path, shell);
 }
@@ -288,27 +484,56 @@ export async function buildStaticView(ctx, requestedOutput, options = {}) {
     const basePath = normalizeStaticViewBasePath(options.basePath ?? '/');
     const clientDir = options.clientDir ?? defaultClientDir;
     const logoText = options.logoText ?? DEFAULT_VIEW_LOGO_TEXT;
-    await validateOutput(outputDir, ctx.projectRoot);
+    await validateViewBuildOutput(outputDir, ctx.projectRoot, 'Static', options.force);
     await mkdir(dirname(outputDir), { recursive: true });
-    const stagingDir = await mkdtemp(join(dirname(outputDir), '.lat-ui-build-'));
-    const store = await createViewStore(ctx.latDir, ctx.projectRoot, {
-        codeExcludePaths: [outputDir],
-        git: false,
-        watch: false,
-    });
+    const stagingDir = await mkdtemp(join(dirname(outputDir), '.lat-static-staging-'));
+    let store;
     try {
+        store = await createViewStore(ctx.latDir, ctx.projectRoot, {
+            codeExcludePaths: [outputDir, ...(options.codeExcludePaths ?? [])],
+            git: false,
+            watch: false,
+            externalIgnoreLocal: true,
+            externalCa: options.externalCa,
+            publishable: await createPublicationPolicy(ctx.projectRoot),
+        });
         const clientHtml = await readFile(join(clientDir, 'index.html'), 'utf8');
         const payloadDir = staticViewPayloadDir(stagingDir, basePath);
         await mkdir(payloadDir, { recursive: true });
         await cp(clientDir, payloadDir, { recursive: true });
-        const shell = clientShell(clientHtml, basePath);
         const index = { ...store.getIndex(), git: null, logoText };
+        validateDocumentRoutes(index.files);
+        const shell = clientShell(clientHtml, basePath, index.entry, options.searchApi);
         const documents = new Map();
+        const documentResources = new Set();
         const sourceRequests = new Map();
-        for (const path of index.files) {
+        const externalRequests = new Set();
+        for (const file of index.externalFiles) {
+            externalRequests.add(file.target);
+        }
+        const pendingDocuments = new Set(index.files);
+        for (const path of pendingDocuments) {
             const document = await store.getDocument(path);
             documents.set(path, document);
+            for (const url of documentTreeUrls(document.tree)) {
+                let parsed;
+                try {
+                    parsed = new URL(url, 'http://lat.local');
+                }
+                catch {
+                    continue;
+                }
+                if (parsed.origin !== 'http://lat.local')
+                    continue;
+                const previewPath = documentPath(parsed.pathname);
+                if (previewPath?.startsWith('@/'))
+                    pendingDocuments.add(previewPath);
+                const resourcePath = documentResourcePath(parsed.pathname);
+                if (resourcePath)
+                    documentResources.add(resourcePath);
+            }
             sourceRequestsFromDocument(document, sourceRequests);
+            externalRequestsFromDocument(document, externalRequests, store.snapshot.external);
         }
         const documentPaths = new Set(documents.keys());
         const sectionPaths = sectionDocumentPaths(documents);
@@ -317,6 +542,37 @@ export async function buildStaticView(ctx, requestedOutput, options = {}) {
             const request = sourceRequest(node.url);
             if (request)
                 sourceRequests.set(viewStaticSourceKey(request), request);
+            if (node.externalTarget)
+                externalRequests.add(node.externalTarget);
+        }
+        const externals = new Map();
+        const pendingExternal = [...externalRequests];
+        for (let index = 0; index < pendingExternal.length; index++) {
+            const target = pendingExternal[index];
+            if (externals.has(target))
+                continue;
+            let external;
+            try {
+                external = await store.getExternal(target);
+            }
+            catch (error) {
+                throw new Error(`Could not export external source ${target}: ${error.message}`);
+            }
+            externals.set(target, external);
+            const before = externalRequests.size;
+            if (external.kind === 'markdown') {
+                externalRequestsFromDocument(external.document, externalRequests, store.snapshot.external, external.document.path);
+            }
+            else {
+                externalRequestsFromSource(external.source, externalRequests, store.snapshot.external);
+            }
+            if (externalRequests.size > before) {
+                for (const next of externalRequests) {
+                    if (!externals.has(next) && !pendingExternal.includes(next)) {
+                        pendingExternal.push(next);
+                    }
+                }
+            }
         }
         const sources = new Map();
         const pending = [...sourceRequests.keys()];
@@ -346,63 +602,146 @@ export async function buildStaticView(ctx, requestedOutput, options = {}) {
                 }
             }
         }
+        const rewrittenGraph = rewriteGraph(graph, basePath, index.entry);
         const manifest = {
             version: 1,
             index,
-            graph: 'data/graph.json',
+            graph: await writeDataJson(payloadDir, 'graphs', rewrittenGraph),
             documents: {},
             sources: {},
+            externals: {},
         };
-        await writeJson(join(payloadDir, manifest.graph), rewriteGraph(graph, basePath));
+        const documentBootstraps = new Map();
         for (const [path, document] of documents) {
-            const dataPath = dataFile('documents', path);
-            manifest.documents[path] = dataPath;
-            await writeJson(join(payloadDir, dataPath), rewriteDocument(document, basePath, sectionPaths, documentPaths));
-            const route = `docs/${path}`;
-            await writeRouteShell(payloadDir, route, shell);
+            const rewritten = rewriteDocument(document, basePath, index.entry, sectionPaths, documentPaths);
+            manifest.documents[path] = await writeDataJson(payloadDir, 'documents', rewritten);
+            if (!path.startsWith('@/')) {
+                const source = await store.getDocumentSource(path);
+                const rawPath = publicationOutputPath(payloadDir, path);
+                await mkdir(dirname(rawPath), { recursive: true });
+                await writeFile(rawPath, source.content);
+            }
+            const route = path.startsWith('@/') ? path : path.slice(0, -'.md'.length);
+            documentBootstraps.set(route, {
+                request: viewStaticDocumentRequest(path),
+                document: rewritten,
+            });
+        }
+        for (const path of [...documentResources].sort()) {
+            let content;
+            try {
+                content = await store.getDocumentResource(path);
+            }
+            catch (error) {
+                throw new Error(`Could not export document resource ${path}: ${error.message}`);
+            }
+            const outputPath = publicationOutputPath(payloadDir, 'resources', path);
+            await mkdir(dirname(outputPath), { recursive: true });
+            await writeFile(outputPath, content);
         }
         const sourceFiles = new Map();
         for (const [key, source] of sources) {
-            const rewritten = rewriteSource(source, basePath, sectionPaths, documentPaths);
-            const { path, content, highlightedHtmlLines, ...view } = rewritten;
+            const rewritten = rewriteSource(source, basePath, index.entry, sectionPaths, documentPaths);
+            const { path, content, highlightedLines, ...view } = rewritten;
             let fileDataPath = sourceFiles.get(path);
             if (!fileDataPath) {
-                fileDataPath = dataFile('source-files', path);
-                sourceFiles.set(path, fileDataPath);
-                await writeJson(join(payloadDir, fileDataPath), {
+                fileDataPath = await writeDataJson(payloadDir, 'source-files', {
                     path,
                     content,
-                    highlightedHtmlLines,
+                    highlightedLines,
                 });
+                sourceFiles.set(path, fileDataPath);
             }
-            const viewDataPath = dataFile('source-views', key);
+            const viewDataPath = await writeDataJson(payloadDir, 'source-views', view);
             manifest.sources[key] = { file: fileDataPath, view: viewDataPath };
-            await writeJson(join(payloadDir, viewDataPath), view);
         }
-        for (const path of sourceFiles.keys()) {
-            const route = `code/${path}`;
-            await writeRouteShell(payloadDir, route, shell);
+        const externalSourceFiles = new Map();
+        const externalRoutes = new Set();
+        for (const [target, external] of externals) {
+            if (external.kind === 'markdown') {
+                const dataPath = await writeDataJson(payloadDir, 'external-documents', {
+                    ...external,
+                    document: rewriteDocument(external.document, basePath, index.entry, sectionPaths, documentPaths),
+                });
+                manifest.externals[target] = { kind: 'markdown', document: dataPath };
+                const colon = external.document.path.indexOf(':');
+                externalRoutes.add(`external/${external.document.path.slice(0, colon)}/${external.document.path.slice(colon + 1)}`);
+                continue;
+            }
+            const rewritten = rewriteSource(external.source, basePath, index.entry, sectionPaths, documentPaths);
+            const { path, content, highlightedLines, ...sourceView } = rewritten;
+            let fileDataPath = externalSourceFiles.get(path);
+            if (!fileDataPath) {
+                fileDataPath = await writeDataJson(payloadDir, 'external-source-files', {
+                    path,
+                    content,
+                    highlightedLines,
+                });
+                externalSourceFiles.set(path, fileDataPath);
+            }
+            const view = {
+                kind: 'source',
+                target: external.target,
+                source: sourceView,
+            };
+            const viewDataPath = await writeDataJson(payloadDir, 'external-source-views', view);
+            manifest.externals[target] = {
+                kind: 'source',
+                file: fileDataPath,
+                view: viewDataPath,
+            };
+            const colon = path.indexOf(':');
+            externalRoutes.add(`external/${path.slice(0, colon)}/${path.slice(colon + 1)}`);
         }
-        await writeRouteShell(payloadDir, 'graph', shell);
         await writeJson(join(payloadDir, 'data/manifest.json'), manifest);
-        const entryRedirect = redirectShell(staticViewUrl(`/docs/${index.entry}`, basePath));
-        await writeFile(join(payloadDir, 'index.html'), entryRedirect);
+        const entryRoute = index.entry.slice(0, -'.md'.length);
+        const entryBootstrap = documentBootstraps.get(entryRoute);
+        if (!entryBootstrap) {
+            throw new Error(`Static UI entry document is missing: ${index.entry}`);
+        }
+        for (const [route, initial] of documentBootstraps) {
+            if (route === entryRoute)
+                continue;
+            await writeRouteShell(payloadDir, route, bootstrapShell(shell, manifest, {
+                [initial.request]: initial.document,
+            }));
+        }
+        const genericShell = bootstrapShell(shell, manifest);
+        for (const path of sourceFiles.keys()) {
+            await writeRouteShell(payloadDir, `code/${path}`, genericShell);
+        }
+        for (const route of externalRoutes) {
+            await writeRouteShell(payloadDir, route, genericShell);
+        }
+        await writeRouteShell(payloadDir, 'graph', bootstrapShell(shell, manifest, { '/api/graph': rewrittenGraph }));
+        if (options.searchApi) {
+            await writeRouteShell(payloadDir, 'search', genericShell);
+        }
+        const redirectScriptPath = join(payloadDir, REDIRECT_SCRIPT_PATH);
+        await mkdir(dirname(redirectScriptPath), { recursive: true });
+        await writeFile(redirectScriptPath, REDIRECT_SCRIPT);
+        await writeFile(join(payloadDir, 'index.html'), bootstrapShell(shell, manifest, {
+            [entryBootstrap.request]: entryBootstrap.document,
+        }));
+        await writeRouteShell(payloadDir, entryRoute, redirectShell(basePath, basePath));
         if (payloadDir !== stagingDir) {
-            await writeFile(join(stagingDir, 'index.html'), entryRedirect);
+            await writeFile(join(stagingDir, 'index.html'), redirectShell(basePath, basePath));
+        }
+        if (options.force) {
+            await rm(outputDir, { recursive: true, force: true });
         }
-        await writeFile(join(stagingDir, BUILD_MARKER), `${JSON.stringify({ version: 1 })}\n`);
-        await rename(stagingDir, outputDir);
+        await moveViewBuildOutput(stagingDir, outputDir);
         return {
             documents: documents.size,
             outputDir,
-            sources: sources.size,
+            sources: sources.size + externals.size,
         };
     }
     catch (error) {
-        await rm(stagingDir, { recursive: true, force: true });
+        await removeViewBuildStaging(stagingDir);
         throw error;
     }
     finally {
-        await store.close();
+        await store?.close();
     }
 }