handoff-app 1.2.2-7 → 2.0.0-1

package/dist/app-builder/client-config.d.ts

@@ -1,9 +1,22 @@
 import Handoff from '..';
+import type { RuntimeMode } from '../types/config';
 /**
  * Publishes the tokens API files to the public directory.
  */
 export declare const generateTokensApi: (handoff: Handoff) => Promise<void>;
+/** Options for {@link persistClientConfig}. */
+export interface PersistClientConfigOptions {
+    /**
+     * Force the runtime mode persisted to both `client.config.json` and `runtime.server.json`,
+     * irrespective of the source project's `runtime.mode`. The registry build sets this to `registry`
+     * so the packaged artifact reports registry mode (badge + DB-backed reads) even when built from a
+     * workspace-mode project.
+     */
+    runtimeModeOverride?: RuntimeMode;
+}
 /**
- * Persists the client config to a JSON file.
+ * Persists the app's resolved config to disk: the browser-facing `client.config.json` and the
+ * server-only `runtime.server.json` the docs read API resolves the active mode + registry
+ * connection inputs from. Both are always written together so they never drift.
  */
-export declare const persistClientConfig: (handoff: Handoff) => Promise<void>;
+export declare const persistClientConfig: (handoff: Handoff, options?: PersistClientConfigOptions) => Promise<void>;

package/dist/app-builder/client-config.js

@@ -16,6 +16,8 @@ exports.persistClientConfig = exports.generateTokensApi = void 0;
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
 const config_1 = require("../config");
+const resolve_1 = require("../registry/asset-storage/resolve");
+const adapter_1 = require("../registry/db/adapter");
 const paths_1 = require("./paths");
 /**
  * Publishes the tokens API files to the public directory.
@@ -50,13 +52,50 @@ const generateTokensApi = (handoff) => __awaiter(void 0, void 0, void 0, functio
 });
 exports.generateTokensApi = generateTokensApi;
 /**
- * Persists the client config to a JSON file.
+ * Build the server-only runtime config consumed by the docs read API.
+ *
+ * The browser-facing `client.config.json` carries only the resolved mode; the server additionally
+ * needs the registry connection *inputs* (selected adapter + the *name* of the database-URL env
+ * var) to back the registry-mode docs read API. These are non-secret — the connection-string value
+ * itself is never persisted, only resolved from the env var at request time.
  */
-const persistClientConfig = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
+const buildServerRuntimeConfig = (config, modeOverride) => {
+    var _a, _b;
+    const assetStorage = (0, resolve_1.resolveAssetStorageFromConfig)(config);
+    return {
+        mode: (_b = modeOverride !== null && modeOverride !== void 0 ? modeOverride : (_a = config === null || config === void 0 ? void 0 : config.runtime) === null || _a === void 0 ? void 0 : _a.mode) !== null && _b !== void 0 ? _b : 'workspace',
+        registry: {
+            adapter: (0, adapter_1.resolveRegistryAdapter)(config),
+            databaseUrlEnv: (0, adapter_1.resolveDatabaseUrlEnv)(config),
+            apiTokenEnv: (0, adapter_1.resolveApiTokenEnv)(config),
+        },
+        assetStorage: {
+            adapter: assetStorage.adapterKind,
+            module: assetStorage.module,
+            tokenEnv: assetStorage.tokenEnv,
+            maxInlineBytes: assetStorage.maxInlineBytes,
+            options: assetStorage.options,
+        },
+    };
+};
+/**
+ * Persists the app's resolved config to disk: the browser-facing `client.config.json` and the
+ * server-only `runtime.server.json` the docs read API resolves the active mode + registry
+ * connection inputs from. Both are always written together so they never drift.
+ */
+const persistClientConfig = (handoff_1, ...args_1) => __awaiter(void 0, [handoff_1, ...args_1], void 0, function* (handoff, options = {}) {
     const appPath = (0, paths_1.getAppPath)(handoff);
-    const destination = path_1.default.resolve(appPath, 'client.config.json');
     // Ensure directory exists
     yield fs_extra_1.default.ensureDir(appPath);
-    yield fs_extra_1.default.writeJson(destination, { config: (0, config_1.getClientConfig)(handoff.config) }, { spaces: 2 });
+    const clientConfig = (0, config_1.getClientConfig)(handoff.config);
+    if (options.runtimeModeOverride) {
+        // A forced registry mode (the registry build target) is never a connected workspace, so the
+        // baked client config must report `connected: false` even when packaged from a connected
+        // workspace project.
+        const connected = options.runtimeModeOverride === 'registry' ? false : clientConfig.runtime.connected;
+        clientConfig.runtime = Object.assign(Object.assign({}, clientConfig.runtime), { mode: options.runtimeModeOverride, connected });
+    }
+    yield fs_extra_1.default.writeJson(path_1.default.resolve(appPath, 'client.config.json'), { config: clientConfig }, { spaces: 2 });
+    yield fs_extra_1.default.writeJson(path_1.default.resolve(appPath, 'runtime.server.json'), buildServerRuntimeConfig(handoff.config, options.runtimeModeOverride), { spaces: 2 });
 });
 exports.persistClientConfig = persistClientConfig;

package/dist/app-builder/config-diff/snapshot.d.ts

@@ -1,11 +1,6 @@
 /** outerKey -> Map<innerKey, serializedValue> */
 export type MapSnapshot = Map<string, Map<string, string>>;
-/**
- * Deterministic JSON serializer that sorts object keys at every nesting level.
- * Prevents false-positive diffs when identical values are constructed with
- * different key insertion order across reloads.
- */
-export declare const stableStringify: (value: unknown) => string;
+export { stableStringify } from '../../utils/stable-stringify';
 /**
  * Compares two MapSnapshots and returns the outer keys where the inner maps
  * differ (added, removed, or values changed).

package/dist/app-builder/config-diff/snapshot.js

@@ -1,15 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.diffMapSnapshots = exports.stableStringify = void 0;
-/**
- * Deterministic JSON serializer that sorts object keys at every nesting level.
- * Prevents false-positive diffs when identical values are constructed with
- * different key insertion order across reloads.
- */
-const stableStringify = (value) => JSON.stringify(value, (_, v) => v && typeof v === 'object' && !Array.isArray(v)
-    ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => a.localeCompare(b)))
-    : v);
-exports.stableStringify = stableStringify;
+var stable_stringify_1 = require("../../utils/stable-stringify");
+Object.defineProperty(exports, "stableStringify", { enumerable: true, get: function () { return stable_stringify_1.stableStringify; } });
 /**
  * Compares two MapSnapshots and returns the outer keys where the inner maps
  * differ (added, removed, or values changed).

package/dist/app-builder/index.d.ts

@@ -1,2 +1,2 @@
 export { buildComponents } from '../pipeline/components';
-export { default, devApp, watchApp } from './build';
+export { default, devApp, watchApp, HandoffBuildError, DEFAULT_BUILD_TARGET, type BuildPackage, type BuildTarget } from './build';

package/dist/app-builder/index.js

@@ -3,10 +3,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.watchApp = exports.devApp = exports.default = exports.buildComponents = void 0;
+exports.DEFAULT_BUILD_TARGET = exports.HandoffBuildError = exports.watchApp = exports.devApp = exports.default = exports.buildComponents = void 0;
 var components_1 = require("../pipeline/components");
 Object.defineProperty(exports, "buildComponents", { enumerable: true, get: function () { return components_1.buildComponents; } });
 var build_1 = require("./build");
 Object.defineProperty(exports, "default", { enumerable: true, get: function () { return __importDefault(build_1).default; } });
 Object.defineProperty(exports, "devApp", { enumerable: true, get: function () { return build_1.devApp; } });
 Object.defineProperty(exports, "watchApp", { enumerable: true, get: function () { return build_1.watchApp; } });
+Object.defineProperty(exports, "HandoffBuildError", { enumerable: true, get: function () { return build_1.HandoffBuildError; } });
+Object.defineProperty(exports, "DEFAULT_BUILD_TARGET", { enumerable: true, get: function () { return build_1.DEFAULT_BUILD_TARGET; } });

package/dist/app-builder/nav-shell.d.ts

@@ -0,0 +1,23 @@
+import Handoff from '..';
+/**
+ * Relative path (within the staged Next app) of the baked navigation shell. The docs read API
+ * (`pages/api/docs/nav.json.ts`) imports this statically so it is bundled into the route chunk and
+ * available at runtime without any filesystem read — see `src/utils/menu-shell.ts` for why the
+ * markdown-driven shell must be frozen at build time for the Vercel registry function.
+ */
+export declare const NAV_SHELL_RELATIVE_PATH: string;
+/** Baked package-default markdown used as the registry catch-all's runtime fallback. */
+export declare const DEFAULT_PAGES_RELATIVE_PATH: string;
+/**
+ * Bake package-default docs into the staged app so registry fallback renders do not depend on the
+ * build machine's absolute module path. The static JSON import is traced into every deployment.
+ */
+export declare const generateDefaultPages: (handoff: Handoff, appPath: string) => Promise<void>;
+/**
+ * Bake the markdown-driven navigation shell into the staged app as `generated/nav-shell.json`.
+ *
+ * Must run BEFORE `next build` so Next inlines the JSON import into the API route chunk. Generated
+ * for every build target (workspace dev/start, static export, registry) so the static import never
+ * fails to resolve; only registry-mode clients actually fetch and use it.
+ */
+export declare const generateNavShell: (handoff: Handoff, appPath: string, includeWorkspacePages?: boolean) => Promise<void>;

package/dist/app-builder/nav-shell.js

@@ -0,0 +1,80 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateNavShell = exports.generateDefaultPages = exports.DEFAULT_PAGES_RELATIVE_PATH = exports.NAV_SHELL_RELATIVE_PATH = void 0;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const gray_matter_1 = __importDefault(require("gray-matter"));
+const path_1 = __importDefault(require("path"));
+const menu_shell_1 = require("../utils/menu-shell");
+const logger_1 = require("../utils/logger");
+/**
+ * Relative path (within the staged Next app) of the baked navigation shell. The docs read API
+ * (`pages/api/docs/nav.json.ts`) imports this statically so it is bundled into the route chunk and
+ * available at runtime without any filesystem read — see `src/utils/menu-shell.ts` for why the
+ * markdown-driven shell must be frozen at build time for the Vercel registry function.
+ */
+exports.NAV_SHELL_RELATIVE_PATH = path_1.default.join('generated', 'nav-shell.json');
+/** Baked package-default markdown used as the registry catch-all's runtime fallback. */
+exports.DEFAULT_PAGES_RELATIVE_PATH = path_1.default.join('generated', 'default-pages.json');
+/** Recursively collect package docs (except dedicated index routes) by their catch-all id. */
+const collectDefaultPages = (root, relativeParts = []) => {
+    if (!fs_extra_1.default.existsSync(root))
+        return {};
+    const pages = {};
+    for (const entry of fs_extra_1.default.readdirSync(root)) {
+        const absolutePath = path_1.default.join(root, entry);
+        if (fs_extra_1.default.lstatSync(absolutePath).isDirectory()) {
+            Object.assign(pages, collectDefaultPages(absolutePath, [...relativeParts, entry]));
+        }
+        else if (entry.endsWith('.md') && entry !== 'index.md') {
+            const id = [...relativeParts, entry.replace(/\.md$/, '')].join('/');
+            const { data, content } = (0, gray_matter_1.default)(fs_extra_1.default.readFileSync(absolutePath, 'utf8'));
+            pages[id] = { metadata: data, content };
+        }
+    }
+    return pages;
+};
+/**
+ * Bake package-default docs into the staged app so registry fallback renders do not depend on the
+ * build machine's absolute module path. The static JSON import is traced into every deployment.
+ */
+const generateDefaultPages = (handoff, appPath) => __awaiter(void 0, void 0, void 0, function* () {
+    const pages = collectDefaultPages(path_1.default.join(handoff.modulePath, 'config', 'docs'));
+    const target = path_1.default.resolve(appPath, exports.DEFAULT_PAGES_RELATIVE_PATH);
+    yield fs_extra_1.default.ensureDir(path_1.default.dirname(target));
+    yield fs_extra_1.default.writeJson(target, pages);
+});
+exports.generateDefaultPages = generateDefaultPages;
+/**
+ * Bake the markdown-driven navigation shell into the staged app as `generated/nav-shell.json`.
+ *
+ * Must run BEFORE `next build` so Next inlines the JSON import into the API route chunk. Generated
+ * for every build target (workspace dev/start, static export, registry) so the static import never
+ * fails to resolve; only registry-mode clients actually fetch and use it.
+ */
+const generateNavShell = (handoff_1, appPath_1, ...args_1) => __awaiter(void 0, [handoff_1, appPath_1, ...args_1], void 0, function* (handoff, appPath, includeWorkspacePages = true) {
+    var _a, _b, _c;
+    const docRoot = path_1.default.join(handoff.modulePath, 'config', 'docs');
+    // A registry serves only what is in its database, so workspace `pages/` present at build time must
+    // NOT be frozen into the shell (same rule as components/patterns). Published pages are merged into
+    // the shell at request time by `/api/docs/nav.json`; the package's own `config/docs` stays baked.
+    const workingPagesDir = includeWorkspacePages ? path_1.default.resolve(handoff.workingPath, 'pages') : undefined;
+    const basePath = (_c = (_b = (_a = handoff.config) === null || _a === void 0 ? void 0 : _a.app) === null || _b === void 0 ? void 0 : _b.base_path) !== null && _c !== void 0 ? _c : '';
+    const shell = (0, menu_shell_1.buildMenuShell)({ docRoot, workingPagesDir, basePath });
+    const target = path_1.default.resolve(appPath, exports.NAV_SHELL_RELATIVE_PATH);
+    yield fs_extra_1.default.ensureDir(path_1.default.dirname(target));
+    yield fs_extra_1.default.writeJson(target, shell, { spaces: 2 });
+    logger_1.Logger.info(`Baked navigation shell (${shell.length} sections) to ${exports.NAV_SHELL_RELATIVE_PATH}.`);
+});
+exports.generateNavShell = generateNavShell;

package/dist/app-builder/paths.js

@@ -50,14 +50,35 @@ const mirrorDirectory = (sourcePath, destinationPath) => __awaiter(void 0, void
     yield fs_extra_1.default.ensureDir(path_1.default.dirname(destinationPath));
     yield fs_extra_1.default.copy(sourcePath, destinationPath, { overwrite: true });
 });
+/**
+ * Stage the fetch-produced asset download bundles (`exported/<id>/{collection}.zip`) into the app
+ * public root, where the docs read API's workspace asset store serves them at
+ * `/api/docs/assets/{collection}/{collection}.zip` (the canonical download URL). `fetch` writes these
+ * bundles, but a plain `build`/`start` cleans and re-stages `.handoff` without carrying them, so the
+ * download links would 404 until a fetch happened to run. Copying the committed export bundles here
+ * makes the route resolve deterministically in workspace dev and static builds. Absent bundles (a
+ * project with no logos/icons) are skipped.
+ */
+const stageAssetDownloadBundles = (handoff, destinationPublicPath) => __awaiter(void 0, void 0, void 0, function* () {
+    const bundles = [
+        { src: handoff.getLogosZipFilePath(), name: 'logos.zip' },
+        { src: handoff.getIconsZipFilePath(), name: 'icons.zip' },
+    ];
+    for (const { src, name } of bundles) {
+        if (fs_extra_1.default.existsSync(src) && fs_extra_1.default.statSync(src).isFile()) {
+            yield fs_extra_1.default.ensureDir(destinationPublicPath);
+            yield fs_extra_1.default.copy(src, path_1.default.resolve(destinationPublicPath, name), { overwrite: true });
+        }
+    }
+});
 /**
  * Copy the public dir from the working dir to the module dir.
  */
 const syncPublicFiles = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
     const appPath = (0, exports.getAppPath)(handoff);
+    const destinationPublicPath = path_1.default.resolve(appPath, 'public');
     const workingPublicPath = (0, exports.getWorkingPublicPath)(handoff);
     if (workingPublicPath) {
-        const destinationPublicPath = path_1.default.resolve(appPath, 'public');
         const sourceApiPath = path_1.default.resolve(workingPublicPath, 'api');
         const destinationApiPath = path_1.default.resolve(destinationPublicPath, 'api');
         yield fs_extra_1.default.copy(workingPublicPath, destinationPublicPath, {
@@ -69,5 +90,8 @@ const syncPublicFiles = (handoff) => __awaiter(void 0, void 0, void 0, function*
         });
         yield mirrorDirectory(sourceApiPath, destinationApiPath);
     }
+    // Stage the asset download bundles regardless of whether the workspace has a `public/` dir — they
+    // come from the fetch output, not the workspace public tree.
+    yield stageAssetDownloadBundles(handoff, destinationPublicPath);
 });
 exports.syncPublicFiles = syncPublicFiles;

package/dist/app-builder/static-export.d.ts

@@ -0,0 +1,17 @@
+import Handoff from '..';
+/**
+ * Validate that every artifact referenced by generated HTML can be materialized — i.e. the
+ * referenced file exists under the artifact root. Required references (e.g. a React preview's
+ * `component/<id>.client.js`) are always emitted, so a missing one fails the static build *before*
+ * export rather than producing a site with broken previews.
+ *
+ * @throws When any generated HTML references an artifact that is not present on disk.
+ */
+export declare const validateReferencedArtifacts: (handoff: Handoff) => void;
+/**
+ * Materialize the docs read model into route-shaped static files under `outDir` (the Next export
+ * output). Produces the canonical artifact tree plus the list/detail metadata reads, matching the
+ * shapes the live docs read API returns so the exported site is byte-for-byte interchangeable with
+ * the dev server's responses.
+ */
+export declare const materializeDocsReadModel: (handoff: Handoff, outDir: string) => Promise<void>;

package/dist/app-builder/static-export.js

@@ -0,0 +1,206 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.materializeDocsReadModel = exports.validateReferencedArtifacts = void 0;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const url_1 = require("../artifacts/url");
+const logger_1 = require("../utils/logger");
+const paths_1 = require("./paths");
+/**
+ * Absolute path of the generated artifact root for the running app — the same
+ * `.handoff/{projectId}/public/api` directory the docs read API resolves artifacts from.
+ */
+const getStaticArtifactRoot = (handoff) => path_1.default.resolve((0, paths_1.getAppPath)(handoff), 'public', 'api');
+const readJsonArray = (absolutePath) => {
+    try {
+        if (!fs_extra_1.default.existsSync(absolutePath) || !fs_extra_1.default.statSync(absolutePath).isFile()) {
+            return [];
+        }
+        const parsed = JSON.parse(fs_extra_1.default.readFileSync(absolutePath, 'utf8'));
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch (_a) {
+        return [];
+    }
+};
+/** Whether the entity's primary detail artifact was generated (drives `current` vs `missing`). */
+const detailArtifactExists = (artifactRoot, relativePath) => {
+    const absolutePath = path_1.default.resolve(artifactRoot, relativePath);
+    return fs_extra_1.default.existsSync(absolutePath) && fs_extra_1.default.statSync(absolutePath).isFile();
+};
+const deriveBuildStatus = (artifactRoot, detailRelativePath) => detailArtifactExists(artifactRoot, detailRelativePath) ? 'current' : 'missing';
+/**
+ * Suffix of a component-owned React client/hydration bundle (`<id>.client.js`). Interactive React
+ * previews treat this artifact as a *required* reference: the
+ * preview cannot hydrate without it, so a missing one is a genuine build failure.
+ */
+const CLIENT_ARTIFACT_SUFFIX = '.client.js';
+/**
+ * Whether a referenced artifact is *required* — i.e. the referencing HTML cannot render correctly
+ * without it. Only the React client bundle qualifies. Component-owned styles/scripts
+ * (`<id>.css`/`<id>.js`) and shared/global artifacts (`main.css`/`main.js`/`shared.css`) are
+ * optional: the renderers emit `<id>.css`/`<id>.js` optimistically and a component that produces no
+ * stylesheet/script simply has none, so an absent optional artifact must not fail the build.
+ */
+const isRequiredReference = (artifactPath) => artifactPath.endsWith(CLIENT_ARTIFACT_SUFFIX);
+/**
+ * Extract the logical artifact paths a generated HTML document references through the canonical
+ * artifact route. References are read from the emitted `href`/`src` URLs (the build's structured
+ * references are realized as these tags); this is a build-time integrity check, not the runtime
+ * dependency-resolution path.
+ */
+const extractReferencedArtifactPaths = (html) => {
+    // Only `href`/`src` attribute values are treated as references, so artifact-shaped strings that
+    // happen to appear in embedded preview content are not mistaken for real dependencies.
+    const pattern = new RegExp(`(?:href|src)=["'][^"']*?${url_1.ARTIFACTS_ROUTE_SEGMENT}/([^"']+)["']`, 'g');
+    const paths = new Set();
+    let match;
+    while ((match = pattern.exec(html)) !== null) {
+        const encoded = match[1].split(/[?#]/)[0];
+        const segments = encoded.split('/').filter(Boolean);
+        try {
+            const decoded = segments.map((segment) => decodeURIComponent(segment));
+            if (decoded.length > 0) {
+                paths.add(decoded.join('/'));
+            }
+        }
+        catch (_a) {
+            // A reference that cannot be decoded is treated as missing below by failing to resolve.
+            paths.add(encoded);
+        }
+    }
+    return Array.from(paths);
+};
+/** Recursively collect every file under a directory as paths relative to it. */
+const collectFilesRelative = (root) => {
+    const results = [];
+    const walk = (current) => {
+        for (const entry of fs_extra_1.default.readdirSync(current, { withFileTypes: true })) {
+            const absolute = path_1.default.join(current, entry.name);
+            if (entry.isDirectory()) {
+                walk(absolute);
+            }
+            else if (entry.isFile()) {
+                results.push(path_1.default.relative(root, absolute));
+            }
+        }
+    };
+    if (fs_extra_1.default.existsSync(root)) {
+        walk(root);
+    }
+    return results;
+};
+/**
+ * Validate that every artifact referenced by generated HTML can be materialized — i.e. the
+ * referenced file exists under the artifact root. Required references (e.g. a React preview's
+ * `component/<id>.client.js`) are always emitted, so a missing one fails the static build *before*
+ * export rather than producing a site with broken previews.
+ *
+ * @throws When any generated HTML references an artifact that is not present on disk.
+ */
+const validateReferencedArtifacts = (handoff) => {
+    const artifactRoot = getStaticArtifactRoot(handoff);
+    if (!fs_extra_1.default.existsSync(artifactRoot)) {
+        return;
+    }
+    const htmlFiles = collectFilesRelative(artifactRoot).filter((relative) => relative.toLowerCase().endsWith('.html'));
+    const missing = new Map();
+    for (const htmlRelative of htmlFiles) {
+        const html = fs_extra_1.default.readFileSync(path_1.default.resolve(artifactRoot, htmlRelative), 'utf8');
+        for (const referenced of extractReferencedArtifactPaths(html)) {
+            // Only required references gate the build; absent optional artifacts (component-owned
+            // styles/scripts, shared/global artifacts) are tolerated.
+            if (!isRequiredReference(referenced)) {
+                continue;
+            }
+            const target = path_1.default.resolve(artifactRoot, ...referenced.split('/'));
+            const contained = !path_1.default.relative(artifactRoot, target).startsWith('..');
+            if (!contained || !fs_extra_1.default.existsSync(target) || !fs_extra_1.default.statSync(target).isFile()) {
+                if (!missing.has(referenced)) {
+                    missing.set(referenced, new Set());
+                }
+                missing.get(referenced).add(htmlRelative);
+            }
+        }
+    }
+    if (missing.size > 0) {
+        const details = Array.from(missing.entries())
+            .map(([artifactPath, referrers]) => `  - ${artifactPath} (referenced by ${Array.from(referrers).join(', ')})`)
+            .join('\n');
+        throw new Error(`Static build aborted: ${missing.size} required artifact(s) referenced by generated HTML could not be materialized:\n${details}`);
+    }
+};
+exports.validateReferencedArtifacts = validateReferencedArtifacts;
+/**
+ * Materialize the docs read model into route-shaped static files under `outDir` (the Next export
+ * output). Produces the canonical artifact tree plus the list/detail metadata reads, matching the
+ * shapes the live docs read API returns so the exported site is byte-for-byte interchangeable with
+ * the dev server's responses.
+ */
+const materializeDocsReadModel = (handoff, outDir) => __awaiter(void 0, void 0, void 0, function* () {
+    const artifactRoot = getStaticArtifactRoot(handoff);
+    if (!fs_extra_1.default.existsSync(artifactRoot)) {
+        logger_1.Logger.warn('No generated artifacts found to materialize for the static build.');
+        return;
+    }
+    const docsRoot = path_1.default.join(outDir, 'api', 'docs');
+    const artifactsOut = path_1.default.join(docsRoot, 'artifacts');
+    // Canonical artifact route: every generated artifact, addressable at `/api/docs/artifacts/{path}`.
+    yield fs_extra_1.default.ensureDir(artifactsOut);
+    yield fs_extra_1.default.copy(artifactRoot, artifactsOut, { overwrite: true });
+    const components = readJsonArray(path_1.default.resolve(artifactRoot, 'components.json'));
+    const patterns = readJsonArray(path_1.default.resolve(artifactRoot, 'patterns.json'));
+    yield fs_extra_1.default.ensureDir(docsRoot);
+    yield fs_extra_1.default.writeJson(path_1.default.join(docsRoot, 'components.json'), components);
+    yield fs_extra_1.default.writeJson(path_1.default.join(docsRoot, 'patterns.json'), patterns);
+    // Detail metadata reads, each carrying the artifact-derived build state.
+    yield fs_extra_1.default.ensureDir(path_1.default.join(docsRoot, 'components'));
+    for (const component of components) {
+        const detail = Object.assign(Object.assign({}, component), { build: { status: deriveBuildStatus(artifactRoot, path_1.default.join('component', `${component.id}.json`)) } });
+        yield fs_extra_1.default.writeJson(path_1.default.join(docsRoot, 'components', `${component.id}.json`), detail);
+    }
+    yield fs_extra_1.default.ensureDir(path_1.default.join(docsRoot, 'patterns'));
+    for (const pattern of patterns) {
+        const detail = Object.assign(Object.assign({}, pattern), { build: { status: deriveBuildStatus(artifactRoot, path_1.default.join('pattern', `${pattern.id}.json`)) } });
+        yield fs_extra_1.default.writeJson(path_1.default.join(docsRoot, 'patterns', `${pattern.id}.json`), detail);
+    }
+    yield materializeAssetDownloads(handoff, docsRoot);
+    logger_1.Logger.success(`Materialized docs read model (${components.length} component(s), ${patterns.length} pattern(s)) for static export.`);
+});
+exports.materializeDocsReadModel = materializeDocsReadModel;
+/**
+ * Materialize the whole-collection asset download bundles at the canonical asset route
+ * (`api/docs/assets/{collection}/{collection}.zip`) — the same URL the docs read API serves in
+ * registry mode, so the "Download" links resolve identically on a static host. The bundles come from
+ * the fetch output (`exported/<id>/{collection}.zip`); `next build` never re-creates them, and the
+ * fetch-time copy into the app `public/` is wiped by the build's clean+restage, so they are copied
+ * here. Absent bundles (a project with no logos/icons) are skipped, not an error.
+ */
+const materializeAssetDownloads = (handoff, docsRoot) => __awaiter(void 0, void 0, void 0, function* () {
+    const bundles = [
+        { collection: 'logos', src: handoff.getLogosZipFilePath() },
+        { collection: 'icons', src: handoff.getIconsZipFilePath() },
+    ];
+    let copied = 0;
+    for (const { collection, src } of bundles) {
+        if (fs_extra_1.default.existsSync(src) && fs_extra_1.default.statSync(src).isFile()) {
+            yield fs_extra_1.default.copy(src, path_1.default.join(docsRoot, 'assets', collection, `${collection}.zip`), { overwrite: true });
+            copied += 1;
+        }
+    }
+    if (copied > 0) {
+        logger_1.Logger.info(`Materialized ${copied} asset download bundle(s) for static export.`);
+    }
+});

package/dist/app-builder/vercel-output.d.ts

@@ -0,0 +1,39 @@
+import Handoff from '..';
+/** Absolute path of the `.vercel/output` directory at the repo root. */
+export declare const getVercelOutputPath: (handoff: Handoff) => string;
+/**
+ * Lay a materialized static export under `.vercel/output/static/` and write a minimal Build Output
+ * API v3 `config.json` carrying the app's `trailingSlash` and resolved `basePath`. Pure CDN files —
+ * no functions, no database.
+ *
+ * @param exportDir Absolute path of the materialized static export (the same content the static
+ *   target writes to `out/<projectId>`).
+ */
+export declare const writeStaticVercelOutput: (handoff: Handoff, exportDir: string) => Promise<void>;
+/**
+ * Options for {@link writeRegistryVercelOutput}. The build module owns the standalone assembly (entry
+ * flattening + static/public/config layout) and passes it in, keeping this seam free of any
+ * standalone-layout knowledge and avoiding a circular import.
+ */
+export interface RegistryVercelOutputOptions {
+    /** Absolute path of the staged Next app (source of `.next/static` + `public`). */
+    appPath: string;
+    /** Absolute path of the Next `standalone` build root (`<appPath>/.next/standalone`). */
+    standaloneRoot: string;
+    /**
+     * Lay the standalone bundle out under the given entry dir (flatten the server entry, copy static
+     * assets, public tree, and runtime config beside it) and return the absolute server-entry path.
+     * Shared with the standalone deliverable so both layouts stay identical.
+     */
+    assembleStandalone: (handoff: Handoff, appPath: string, standaloneRoot: string, entryDir: string) => Promise<string>;
+}
+/**
+ * Package the dynamic registry app as the Vercel Build Output API directory. Lays the traced
+ * standalone bundle into a single Node function (`functions/index.func/`)
+ * wrapping the Next standalone server, copies the immutable static assets + public tree under
+ * `static/` for the Edge CDN, and writes a route table that serves static files first and routes
+ * everything else (SSR pages, the docs read API, the registry API) to the function.
+ *
+ * Hard constraint: `.vercel/output` lives at the repo root with that exact name (see module header).
+ */
+export declare const writeRegistryVercelOutput: (handoff: Handoff, options: RegistryVercelOutputOptions) => Promise<void>;