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

package/dist/src/view/server.js

@@ -2,7 +2,7 @@ import { readFile } from 'node:fs/promises';
 import { randomUUID } from 'node:crypto';
 import { extname, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { createLatServerApp, listenLatServer, } from '@lat.md/server';
+import { createLatServerApp, listenLatServer, } from '../../vendor/lat.md-server/index.js';
 import { plainStyler } from '../context.js';
 import { sectionCommand } from '../cli/section.js';
 import { DEFAULT_VIEW_LOGO_TEXT, } from './protocol.js';
@@ -11,7 +11,7 @@ import { ViewExternalNotFoundError, ViewDocumentNotFoundError, ViewSourceNotFoun
 import { createViewSearch } from './search.js';
 import { createViewStore } from './store.js';
 import { rewriteClientAssetUrls } from './client-shell.js';
-import { documentResourcePath, documentUrl, rawDocumentPath, } from './document-route.js';
+import { documentResourcePath, documentPath, rawDocumentPath, validateDocumentRoutes, } from './document-route.js';
 const DEFAULT_HOST = '127.0.0.1';
 export const DEFAULT_VIEW_PORT = 4242;
 const MAX_DOCUMENT_EDIT_BODY_BYTES = 16 * 1024 * 1024;
@@ -98,9 +98,13 @@ async function sendClientFile(res, path, headOnly, immutable = false) {
         send(res, 404, 'text/plain; charset=utf-8', 'Not found', headOnly);
     }
 }
-async function sendClientShell(res, path, headOnly) {
+async function sendClientShell(res, path, headOnly, entry) {
     try {
-        const body = rewriteClientAssetUrls(await readFile(path, 'utf8'), '/');
+        const html = rewriteClientAssetUrls(await readFile(path, 'utf8'), '/');
+        const config = `<meta name="lat-live-entry" content="${encodeURIComponent(entry)}">`;
+        const body = html.includes('</head>')
+            ? html.replace('</head>', `${config}</head>`)
+            : `${config}${html}`;
         res.setHeader('Cache-Control', 'no-cache');
         send(res, 200, 'text/html; charset=utf-8', body, headOnly);
     }
@@ -121,6 +125,13 @@ export async function createViewApp(ctx, options = {}) {
         watch: options.watch,
         externalCa: options.externalCa,
     });
+    try {
+        validateDocumentRoutes(store.getIndex().files);
+    }
+    catch (error) {
+        await store.close();
+        throw error;
+    }
     const search = options.search ??
         createViewSearch(ctx.latDir, undefined, () => store.markdownGeneration);
     const eventClients = new Set();
@@ -153,8 +164,15 @@ export async function createViewApp(ctx, options = {}) {
                     send(res, 404, 'text/plain; charset=utf-8', 'No Markdown files found');
                     return;
                 }
-                res.statusCode = 302;
-                res.setHeader('Location', documentUrl(entry));
+                await sendClientShell(res, join(clientDir, 'index.html'), headOnly, entry);
+                return;
+            }
+            const index = store.getIndex();
+            const routePath = url.pathname.replace(/\/$/, '');
+            const markdownPath = documentPath(routePath);
+            if (markdownPath === index.entry) {
+                res.statusCode = 308;
+                res.setHeader('Location', `/${url.search}`);
                 res.end();
                 return;
             }
@@ -351,10 +369,10 @@ export async function createViewApp(ctx, options = {}) {
             }
             if (url.pathname === '/search' ||
                 url.pathname === '/graph' ||
-                url.pathname.startsWith('/docs/') ||
+                (markdownPath !== null && index.files.includes(markdownPath)) ||
                 url.pathname.startsWith('/code/') ||
                 url.pathname.startsWith('/external/')) {
-                await sendClientShell(res, join(clientDir, 'index.html'), headOnly);
+                await sendClientShell(res, join(clientDir, 'index.html'), headOnly, index.entry);
                 return;
             }
             send(res, 404, 'text/plain; charset=utf-8', 'Not found', headOnly);

package/dist/src/view/static-build.d.ts

@@ -1,9 +1,13 @@
+import { rename } from 'node:fs/promises';
 import type { CmdContext } from '../context.js';
 export type StaticViewBuildOptions = {
     basePath?: string;
     clientDir?: string;
+    codeExcludePaths?: string[];
+    force?: boolean;
     logoText?: string;
     externalCa?: string | Buffer;
+    searchApi?: string;
 };
 export type StaticViewBuildResult = {
     documents: number;
@@ -12,6 +16,17 @@ export type StaticViewBuildResult = {
 };
 export declare function normalizeStaticViewBasePath(value: string): string;
 /** Convert a live view route to its physical static-directory URL. */
-export declare function staticViewUrl(value: string, basePath: string): string;
+export declare function staticViewUrl(value: string, basePath: string, entryPath?: string): string;
+/** Refuse build targets that exist or could replace the project itself. */
+export declare function validateViewBuildOutput(outputDir: string, projectRoot: string, kind?: string, force?: boolean): Promise<void>;
+type ViewBuildMoveDependencies = {
+    move: typeof rename;
+    wait: (milliseconds: number) => Promise<void>;
+};
+/** Commit a staged build after transient filesystem locks have cleared. */
+export declare function moveViewBuildOutput(stagingDir: string, outputDir: string, dependencies?: ViewBuildMoveDependencies): Promise<void>;
+/** Remove abandoned staging after transient filesystem locks have cleared. */
+export declare function removeViewBuildStaging(stagingDir: string): Promise<void>;
 /** Build a serverless snapshot of the current read-only Lat UI. */
 export declare function buildStaticView(ctx: CmdContext, requestedOutput: string, options?: StaticViewBuildOptions): Promise<StaticViewBuildResult>;
+export {};

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

@@ -5,21 +5,24 @@ import { fileURLToPath } from 'node:url';
 import { isDocumentPath } from '../document-formats.js';
 import { DEFAULT_VIEW_LOGO_TEXT } from './protocol.js';
 import { documentTreeUrls, rewriteDocumentTreeUrls } from './document-tree.js';
-import { viewStaticSourceKey, } from './static-protocol.js';
+import { VIEW_STATIC_BOOTSTRAP_ID, viewStaticDocumentRequest, viewStaticSourceKey, } from './static-protocol.js';
 import { createViewStore } from './store.js';
 import { rewriteClientAssetUrls } from './client-shell.js';
-import { documentResourcePath, documentPath, documentUrl, rawDocumentPath, } from './document-route.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('/')
@@ -47,8 +50,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 {
@@ -59,9 +62,13 @@ export function staticViewUrl(value, basePath) {
     }
     if (url.origin !== 'http://lat.local')
         return value;
-    if (url.pathname.startsWith('/docs/')) {
+    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/')) {
@@ -77,13 +84,16 @@ 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) {
     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;
@@ -103,64 +113,67 @@ function rewriteHtmlLink(value, basePath, sourcePath, documentPaths) {
     }
     const documentPath = documentPathFromUrl(resolved);
     if (resolved.pathname.startsWith('/external/')) {
-        return staticViewUrl(`${resolved.pathname}${resolved.search}${resolved.hash}`, basePath);
+        return staticViewUrl(`${resolved.pathname}${resolved.search}${resolved.hash}`, basePath, entryPath);
     }
     if (resolved.origin !== 'http://lat.local' ||
         !documentPath ||
         !documentPaths.has(documentPath)) {
         return value;
     }
-    return staticViewUrl(`${documentUrl(documentPath)}${resolved.search}${resolved.hash}`, basePath);
+    return staticViewUrl(`${documentUrl(documentPath)}${resolved.search}${resolved.hash}`, basePath, entryPath);
 }
-function rewriteDocumentLinks(tree, basePath, sourcePath, documentPaths) {
-    return rewriteDocumentTreeUrls(tree, (value) => rewriteHtmlLink(value, basePath, sourcePath, documentPaths));
+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,
-        paragraphTree: rewriteDocumentLinks(reference.paragraphTree, 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,
-        tree: rewriteDocumentLinks(document.tree, basePath, document.path, documentPaths),
+        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,
-        paragraphTree: rewriteDocumentLinks(reference.paragraphTree, 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),
         })),
     };
 }
@@ -307,13 +320,26 @@ function sourceRequestsFromSource(source, requests) {
         }
     }
 }
-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 {
@@ -326,16 +352,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()) {
@@ -343,25 +400,44 @@ function sectionDocumentPaths(documents) {
     }
     return result;
 }
-function clientShell(html, basePath) {
+function clientShell(html, basePath, entry, searchApi) {
     const assets = rewriteClientAssetUrls(html, basePath);
-    const configValue = JSON.stringify({ basePath }).replaceAll('<', '\\u003c');
-    const config = `<script>globalThis.__LAT_STATIC_VIEW__=${configValue}</script>`;
+    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>
 `;
 }
@@ -376,11 +452,11 @@ 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 stagingDir = await mkdtemp(join(dirname(outputDir), '.lat-static-staging-'));
     const store = await createViewStore(ctx.latDir, ctx.projectRoot, {
-        codeExcludePaths: [outputDir],
+        codeExcludePaths: [outputDir, ...(options.codeExcludePaths ?? [])],
         git: false,
         watch: false,
         externalIgnoreLocal: true,
@@ -391,8 +467,9 @@ export async function buildStaticView(ctx, requestedOutput, options = {}) {
         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();
@@ -489,25 +566,28 @@ 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 rewritten = rewriteDocument(document, basePath, index.entry, sectionPaths, documentPaths);
+            manifest.documents[path] = await writeDataJson(payloadDir, 'documents', rewritten);
             const source = await store.getDocumentSource(path);
-            const rawPath = join(payloadDir, 'docs', ...path.split('/'));
+            const rawPath = join(payloadDir, ...path.split('/'));
             await mkdir(dirname(rawPath), { recursive: true });
             await writeFile(rawPath, source.content);
-            const route = `docs/${path.slice(0, -'.md'.length)}`;
-            await writeRouteShell(payloadDir, route, shell);
+            const route = path.slice(0, -'.md'.length);
+            documentBootstraps.set(route, {
+                request: viewStaticDocumentRequest(path),
+                document: rewritten,
+            });
         }
         for (const path of [...documentResources].sort()) {
             let content;
@@ -523,78 +603,96 @@ export async function buildStaticView(ctx, requestedOutput, options = {}) {
         }
         const sourceFiles = new Map();
         for (const [key, source] of sources) {
-            const rewritten = rewriteSource(source, basePath, sectionPaths, documentPaths);
+            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,
                     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 = dataFile('external-documents', target);
-                manifest.externals[target] = { kind: 'markdown', document: dataPath };
-                await writeJson(join(payloadDir, dataPath), {
+                const dataPath = await writeDataJson(payloadDir, 'external-documents', {
                     ...external,
-                    document: rewriteDocument(external.document, basePath, sectionPaths, documentPaths),
+                    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, sectionPaths, documentPaths);
+            const rewritten = rewriteSource(external.source, basePath, index.entry, sectionPaths, documentPaths);
             const { path, content, highlightedLines, ...sourceView } = rewritten;
             let fileDataPath = externalSourceFiles.get(path);
             if (!fileDataPath) {
-                fileDataPath = dataFile('external-source-files', path);
-                externalSourceFiles.set(path, fileDataPath);
-                await writeJson(join(payloadDir, fileDataPath), {
+                fileDataPath = await writeDataJson(payloadDir, 'external-source-files', {
                     path,
                     content,
                     highlightedLines,
                 });
+                externalSourceFiles.set(path, fileDataPath);
             }
-            const viewDataPath = dataFile('external-source-views', target);
-            manifest.externals[target] = {
-                kind: 'source',
-                file: fileDataPath,
-                view: viewDataPath,
-            };
             const view = {
                 kind: 'source',
                 target: external.target,
                 source: sourceView,
             };
-            await writeJson(join(payloadDir, viewDataPath), view);
+            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 writeJson(join(payloadDir, 'data/manifest.json'), manifest);
+        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, shell);
+            await writeRouteShell(payloadDir, route, genericShell);
         }
-        await writeRouteShell(payloadDir, 'graph', shell);
-        await writeJson(join(payloadDir, 'data/manifest.json'), manifest);
-        const entryRedirect = redirectShell(staticViewUrl(documentUrl(index.entry), basePath));
-        await writeFile(join(payloadDir, 'index.html'), entryRedirect);
+        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 rename(stagingDir, outputDir);
+        await moveViewBuildOutput(stagingDir, outputDir);
         return {
             documents: documents.size,
             outputDir,
@@ -602,7 +700,7 @@ export async function buildStaticView(ctx, requestedOutput, options = {}) {
         };
     }
     catch (error) {
-        await rm(stagingDir, { recursive: true, force: true });
+        await removeViewBuildStaging(stagingDir);
         throw error;
     }
     finally {

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

@@ -36,5 +36,12 @@ export type ViewStaticManifest = {
     sources: Record<string, ViewStaticSourceEntry>;
     externals: Record<string, ViewStaticExternalEntry>;
 };
+export type ViewStaticBootstrap = {
+    manifest: ViewStaticManifest;
+    responses: Record<string, object>;
+};
+export declare const VIEW_STATIC_BOOTSTRAP_ID = "lat-static-bootstrap";
+/** Match the live document endpoint key used by the static browser adapter. */
+export declare function viewStaticDocumentRequest(path: string): string;
 /** Stable lookup key shared by the static exporter and browser adapter. */
 export declare function viewStaticSourceKey(request: ViewStaticSourceRequest): string;

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

@@ -1,3 +1,8 @@
+export const VIEW_STATIC_BOOTSTRAP_ID = 'lat-static-bootstrap';
+/** Match the live document endpoint key used by the static browser adapter. */
+export function viewStaticDocumentRequest(path) {
+    return `/api/document?path=${encodeURIComponent(path)}`;
+}
 /** Stable lookup key shared by the static exporter and browser adapter. */
 export function viewStaticSourceKey(request) {
     return JSON.stringify([