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

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([

package/dist/src/view/store.js

@@ -99,8 +99,8 @@ async function scanCodeState(projectRoot, excludedPaths = []) {
         scope,
     };
 }
-function viewIndex(latDir, paths, diagnostics, git, references, external) {
-    const files = [...paths].sort();
+function viewIndex(latDir, markdownFiles, diagnostics, git, references, external) {
+    const files = [...markdownFiles.keys()].sort();
     const externalFiles = new Map();
     for (const target of references.externalByTarget.keys()) {
         try {
@@ -123,8 +123,18 @@ function viewIndex(latDir, paths, diagnostics, git, references, external) {
     const indexName = directoryName.endsWith('.md')
         ? directoryName
         : `${directoryName}.md`;
+    const directoryOrder = Object.fromEntries([...markdownFiles].flatMap(([path, file]) => {
+        const separator = path.lastIndexOf('/');
+        const directory = separator === -1 ? '' : path.slice(0, separator);
+        const name = directory ? basename(directory) : directoryName;
+        const filename = name.endsWith('.md') ? name : `${name}.md`;
+        if (path.slice(separator + 1) !== filename)
+            return [];
+        return [[directory, file.indexEntries]];
+    }));
     return {
         files,
+        directoryOrder,
         externalFiles: [...externalFiles.values()].sort((left, right) => left.handle.localeCompare(right.handle) ||
             left.path.localeCompare(right.path)),
         entry: files.includes(indexName) ? indexName : (files[0] ?? ''),
@@ -162,10 +172,10 @@ async function buildSnapshot(latDir, projectRoot, markdownFiles, codeFiles, git,
         files,
         allSections,
         references,
-        graph: buildViewGraph(files.values(), codeFiles.values(), allSections, diagnostics, git, generation, external),
+        graph: buildViewGraph(files.values(), codeFiles.values(), allSections, diagnostics, git, generation, references, external),
         diagnostics,
         git,
-        index: viewIndex(latDir, [...files.keys()], diagnostics, git, references, external),
+        index: viewIndex(latDir, files, diagnostics, git, references, external),
         external,
     };
 }

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

@@ -0,0 +1,24 @@
+type FileTraceResult = {
+    fileList: Set<string>;
+    warnings: Set<Error>;
+};
+export type VercelBuildDependencies = {
+    traceFiles: (files: string[], options: {
+        base: string;
+        conditions: string[];
+        exportsOnly: boolean;
+        processCwd: string;
+    }) => Promise<FileTraceResult>;
+};
+export type VercelBuildOptions = {
+    force?: boolean;
+    warn?: (message: string) => void;
+};
+export type VercelBuildResult = {
+    files: number;
+    functionPath: string;
+    outputDir: string;
+};
+/** Convert an installed portable Lat UI server into Vercel Build Output API v3. */
+export declare function buildVercelOutput(requestedArtifact: string, requestedOutput?: string, options?: VercelBuildOptions, dependencies?: VercelBuildDependencies): Promise<VercelBuildResult>;
+export {};