handoff-app 2.0.0-0 → 2.0.0-2

package/README.md

@@ -25,6 +25,7 @@ authoring locally or running a shared, deployed catalog.
 * [Building artifacts](#building-artifacts)
   * [Static site (default)](#static-site-default)
   * [Registry app](#registry-app)
+  * [Deploying](#deploying)
 * [Publishing and checkout](#publishing-and-checkout)
 * [Configuration](#configuration)
   * [The runtime block](#the-runtime-block)
@@ -144,7 +145,7 @@ my-handoff-project/
 ├─ patterns/                # multi-component compositions
 ├─ sass/                    # optional global SCSS entry
 ├─ js/                      # optional global JS entry
-├─ exported/                # generated tokens and artifacts (gitignored)
+├─ exported/                # fetched tokens and assets (commit these so clean/CI builds have data)
 └─ out/                     # build output (gitignored)
 ```
 
@@ -226,8 +227,9 @@ preview updates. The site boots at http://localhost:3000 by default.
 
 ## Building artifacts
 
-`handoff-app build` accepts a `--target` flag. The target, not `NODE_ENV`,
-decides what gets produced.
+`handoff-app build` accepts two independent flags. `--target` decides *what* is
+produced — the target, not `NODE_ENV`, drives this. The optional `--package`
+decides *how* that target is packaged for deployment.
 
 ### Static site (default)
 
@@ -240,9 +242,8 @@ The static target builds your workspace components, patterns, and tokens,
 materializes the docs read model into route-shaped static files, and runs a
 static export to `out/<projectId>` (respecting `sitesOutputDirectory`). The
 output is plain static files: it renders list, detail, preview, and inspect
-pages and loads previews through canonical artifact URLs with no live server. It
-works on a managed host like Vercel and on a plain static file server with no
-host-specific rewrites.
+pages and loads previews through canonical artifact URLs with no live server, so
+any static file server or CDN can serve it with no host-specific rewrites.
 
 The build fails clearly if a required artifact referenced by generated HTML
 cannot be materialized, and it fails if the runtime is registry-only (there is
@@ -269,17 +270,38 @@ DATABASE_URL="postgres://…" node out/registry/server.js
 ```
 
 A generated `README.md` next to the bundle documents the required env vars and
-Docker/Vercel specifics. Apply database migrations from the CLI as a controlled
-release step (e.g. in CI/CD) before deploying:
+how to run it. Apply database migrations from the CLI as a controlled release
+step (e.g. in CI/CD) before deploying:
 
 ```bash
 handoff-app db:migrate
 ```
 
 `db:migrate` reads your project config and DB env vars, applies the
-package-owned migration set, and runs independently of `build`. The database
-adapter (`pg` or `neon`) is chosen with `runtime.registry.database.adapter`, and
-both adapters ship with the package.
+package-owned migration set, and runs independently of `build`. PostgreSQL is
+the supported database; `runtime.registry.database.driver` selects the
+connection driver (`pg` or `neon`) — how to connect, not the database engine —
+and both drivers ship with the package.
+
+### Deploying
+
+* **Static** produces plain files under `out/<projectId>`. Serve them with any
+  static file server or CDN. Commit `exported/` so a clean checkout has token
+  data to build from.
+* **Registry** produces a self-contained Node bundle under `out/registry`. Run it
+  on any Node host with `node out/registry/server.js` and a `DATABASE_URL` in the
+  environment.
+
+The optional `--package` flag repackages a target without changing what it
+builds:
+
+| `--package` | Output |
+| --- | --- |
+| omitted (default) | `out/<projectId>` (static) or the `out/registry` Node bundle (registry) |
+| `vercel` | `.vercel/output`, a Vercel Build Output API bundle |
+
+`handoff-app init` can scaffold a `vercel.json` that runs a packaged build; edit
+its `buildCommand` to change the target.
 
 ## Publishing and checkout
 
@@ -304,8 +326,8 @@ HANDOFF_REGISTRY_ACCESS_TOKEN=your-registry-token
 Then push and pull entities by `id`:
 
 ```bash
-handoff-app publish component button     # build locally, upload that entity's package
-handoff-app checkout pattern hero        # pull a registry entity into this workspace
+handoff-app publish components button    # build locally, upload that entity's package
+handoff-app checkout patterns hero       # pull a registry entity into this workspace
 ```
 
 `publish` runs a fresh targeted build of the selected entity and uploads only
@@ -373,7 +395,7 @@ runtime: {
   registry: {
     databaseUrlEnv: 'DATABASE_URL',
     apiTokenEnv: 'HANDOFF_REGISTRY_API_TOKEN',
-    database: { adapter: 'pg' }, // 'pg' | 'neon'
+    database: { driver: 'pg' }, // connection driver: 'pg' | 'neon' (PostgreSQL only)
   },
 },
 ```
@@ -410,10 +432,10 @@ See [docs/api.md](docs/api.md#hooks) for hook arguments and examples.
 | `fetch` | Fetch design tokens from Figma |
 | `dev` | Start the local dev server with the live docs read API |
 | `start` | Start the dev server with file watchers for live authoring |
-| `build [--target static\|registry]` | Build the static site (default) or package the registry app |
+| `build [--target static\|registry] [--package standalone\|vercel]` | Build the static site (default) or registry app; `--package vercel` emits a Vercel Build Output bundle |
 | `build:components [component]` | Build components without building the full app |
-| `publish <component\|pattern> <id>` | Build and publish an entity to the connected registry |
-| `checkout <component\|pattern> <id>` | Pull an entity from the connected registry |
+| `publish <components\|patterns\|pages\|tokens\|assets> [id]` | Build and publish entities to the connected registry (all of the kind, or one by id) |
+| `checkout <components\|patterns\|pages\|tokens\|assets> [id]` | Pull entities from the connected registry into this workspace |
 | `db:migrate` | Run registry database migrations (Drizzle / PostgreSQL) |
 | `make:component <name>` | Scaffold a new component |
 | `make:page <name> [parent]` | Scaffold a documentation page |

package/config/docs/foundations/colors/guidelines.md

@@ -0,0 +1,9 @@
+---
+title: Color Guidelines
+description: How to apply the color palette consistently and accessibly across products.
+metaTitle: 'Color Guidelines | Handoff Design System'
+metaDescription: 'How to apply the color palette consistently and accessibly across products.'
+---
+
+This is placeholder content for the **Color Guidelines** page. Replace it with your rules for
+contrast, pairing, and semantic usage. Markdown and <b>HTML</b> are both supported.

package/config/docs/foundations/effects/guidelines.md

@@ -0,0 +1,9 @@
+---
+title: Effects Guidelines
+description: When and how to apply shadows, blurs, and elevation across the interface.
+metaTitle: 'Effects Guidelines | Handoff Design System'
+metaDescription: 'When and how to apply shadows, blurs, and elevation across the interface.'
+---
+
+This is placeholder content for the **Effects Guidelines** page. Replace it with your rules for
+elevation, depth, and motion. Markdown and <b>HTML</b> are both supported.

package/config/docs/foundations/effects/resources.md

@@ -0,0 +1,9 @@
+---
+title: Effects Resources
+description: Reference values and assets for reproducing the brand's effects in any tool.
+metaTitle: 'Effects Resources | Handoff Design System'
+metaDescription: 'Reference values and assets for reproducing effects in any tool.'
+---
+
+This is placeholder content for the **Effects Resources** page. Replace it with your shadow tokens,
+blur values, and export notes. Markdown and <b>HTML</b> are both supported.

package/config/docs/foundations/grid.md

@@ -0,0 +1,10 @@
+---
+title: Grid
+description: Layout grid and spacing system that keeps compositions aligned and balanced.
+image: hero-design
+metaTitle: 'Grid | Handoff Design System'
+metaDescription: 'Layout grid and spacing system that keeps compositions aligned and balanced.'
+---
+
+This is placeholder content for the **Grid** page. Replace it with your columns, gutters, and
+breakpoint rules. Markdown and <b>HTML</b> are both supported.

package/config/docs/foundations/icons/guidelines.md

@@ -0,0 +1,9 @@
+---
+title: Icon Guidelines
+description: Sizing, spacing, and usage rules that keep the icon set consistent.
+metaTitle: 'Icon Guidelines | Handoff Design System'
+metaDescription: 'Sizing, spacing, and usage rules that keep the icon set consistent.'
+---
+
+This is placeholder content for the **Icon Guidelines** page. Replace it with your rules for grid
+sizing, stroke, and when to use each icon. Markdown and <b>HTML</b> are both supported.

package/config/docs/foundations/images/guidelines.md

@@ -0,0 +1,9 @@
+---
+title: Image Guidelines
+description: How to select, crop, and treat imagery so it stays on brand.
+metaTitle: 'Image Guidelines | Handoff Design System'
+metaDescription: 'How to select, crop, and treat imagery so it stays on brand.'
+---
+
+This is placeholder content for the **Image Guidelines** page. Replace it with your rules for
+composition, cropping, and treatments. Markdown and <b>HTML</b> are both supported.

package/config/docs/foundations/images/resources.md

@@ -0,0 +1,9 @@
+---
+title: Image Resources
+description: Source files and downloads for approved photography and illustration.
+metaTitle: 'Image Resources | Handoff Design System'
+metaDescription: 'Source files and downloads for approved photography and illustration.'
+---
+
+This is placeholder content for the **Image Resources** page. Replace it with your image library,
+downloads, and licensing notes. Markdown and <b>HTML</b> are both supported.

package/config/docs/foundations/images.md

@@ -0,0 +1,10 @@
+---
+title: Images
+description: Photography and illustration style that shapes how the brand looks and feels.
+image: hero-design
+metaTitle: 'Images | Handoff Design System'
+metaDescription: 'Photography and illustration style that shapes how the brand looks and feels.'
+---
+
+This is placeholder content for the **Images** page. Replace it with your art direction,
+photography style, and illustration principles. Markdown and <b>HTML</b> are both supported.

package/config/docs/foundations/logo/resources.md

@@ -0,0 +1,9 @@
+---
+title: Logo Resources
+description: Downloadable logo files and everything teams need to represent the brand correctly.
+metaTitle: 'Logo Resources | Handoff Design System'
+metaDescription: 'Downloadable logo files and everything teams need to represent the brand correctly.'
+---
+
+This is placeholder content for the **Logo Resources** page. Replace it with your logo downloads,
+file formats, and usage notes. Markdown and <b>HTML</b> are both supported.

package/config/docs/foundations/typography/guidelines.md

@@ -0,0 +1,9 @@
+---
+title: Typography Guidelines
+description: Best practices for type scale, hierarchy, and readability across the system.
+metaTitle: 'Typography Guidelines | Handoff Design System'
+metaDescription: 'Best practices for type scale, hierarchy, and readability across the system.'
+---
+
+This is placeholder content for the **Typography Guidelines** page. Replace it with your rules for
+hierarchy, spacing, and responsive type. Markdown and <b>HTML</b> are both supported.

package/config/docs/foundations/typography/resources.md

@@ -0,0 +1,9 @@
+---
+title: Typography Resources
+description: Font files, licenses, and assets needed to work with the brand typography.
+metaTitle: 'Typography Resources | Handoff Design System'
+metaDescription: 'Font files, licenses, and assets needed to work with the brand typography.'
+---
+
+This is placeholder content for the **Typography Resources** page. Replace it with your font
+downloads, licensing details, and platform notes. Markdown and <b>HTML</b> are both supported.

package/config/docs/foundations.md

@@ -67,8 +67,10 @@ menu:
         title: Images
         icon: image
         menu:
-          - path: foundations/icons
-            title: Library
-          - path: foundations/icons/guidelines
+          - path: foundations/images
+            title: Overview
+          - path: foundations/images/guidelines
             title: Guidelines
+          - path: foundations/images/resources
+            title: Resources
 ---

package/dist/app-builder/build.js

@@ -1,4 +1,27 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
 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) {
@@ -13,6 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.devApp = exports.watchApp = exports.getRegistryBuildOutputPath = exports.HandoffBuildError = exports.DEFAULT_BUILD_TARGET = void 0;
+const p = __importStar(require("@clack/prompts"));
 const cross_spawn_1 = __importDefault(require("cross-spawn"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
@@ -21,7 +45,7 @@ const patterns_1 = require("../pipeline/patterns");
 const builder_1 = __importDefault(require("../transformers/preview/component/builder"));
 const css_1 = require("../transformers/preview/component/css");
 const javascript_1 = require("../transformers/preview/component/javascript");
-const adapter_1 = require("../registry/db/adapter");
+const driver_1 = require("../registry/db/driver");
 const resolve_1 = require("../registry/asset-storage/resolve");
 const logger_1 = require("../utils/logger");
 const client_config_1 = require("./client-config");
@@ -78,6 +102,51 @@ const assertStaticBuildAllowed = (handoff) => {
             'or package the registry app with `handoff-app build --target registry`.');
     }
 };
+/**
+ * Run the Next.js production build while keeping its delayed output out of the successful CLI flow.
+ * Captured output is replayed only when the child fails so compiler diagnostics remain available.
+ */
+const runNextBuild = (appPath, target, errorLabel) => __awaiter(void 0, void 0, void 0, function* () {
+    const spinner = p.spinner();
+    spinner.start('Building Next.js app...');
+    const stdout = [];
+    const stderr = [];
+    yield new Promise((resolve, reject) => {
+        var _a, _b;
+        const buildProcess = (0, cross_spawn_1.default)('npx', ['next', 'build'], {
+            cwd: appPath,
+            stdio: ['inherit', 'pipe', 'pipe'],
+            env: Object.assign(Object.assign({}, process.env), { NODE_ENV: 'production', HANDOFF_BUILD_TARGET: target }),
+        });
+        (_a = buildProcess.stdout) === null || _a === void 0 ? void 0 : _a.on('data', (chunk) => stdout.push(Buffer.from(chunk)));
+        (_b = buildProcess.stderr) === null || _b === void 0 ? void 0 : _b.on('data', (chunk) => stderr.push(Buffer.from(chunk)));
+        let settled = false;
+        const fail = (message) => {
+            if (settled)
+                return;
+            settled = true;
+            spinner.stop('Next.js app build failed');
+            logger_1.Logger.childProcessBuffer(Buffer.concat(stdout));
+            logger_1.Logger.childProcessBuffer(Buffer.concat(stderr));
+            reject(new Error(message));
+        };
+        buildProcess.once('error', (error) => {
+            fail(`${errorLabel} failed to start\nSpawn error: ${error.message}`);
+        });
+        buildProcess.once('close', (code, signal) => {
+            if (settled)
+                return;
+            if (code === 0) {
+                settled = true;
+                spinner.stop('Next.js app built successfully');
+                resolve();
+                return;
+            }
+            const reason = signal ? ` because it was terminated by signal ${signal}` : ` with exit code ${code}`;
+            fail(`${errorLabel} failed${reason}`);
+        });
+    });
+});
 /**
  * Output directory for the packaged registry app. Lives under the configurable sites output
  * directory (`sitesOutputDirectory`, default `out`) alongside the static target's `out/<projectId>`
@@ -147,9 +216,9 @@ const initializeProjectApp = (handoff_1, ...args_1) => __awaiter(void 0, [handof
     // Resolved runtime mode + registry connection inputs (names only) baked into the Next bundle so the
     // deployed registry app resolves its mode/DB env-var name without any build-machine filesystem.
     const escapedRuntimeMode = escapeForSingleQuotedJsString(runtimeMode);
-    const escapedRegistryAdapter = escapeForSingleQuotedJsString((0, adapter_1.resolveRegistryAdapter)(handoff.config));
-    const escapedDatabaseUrlEnv = escapeForSingleQuotedJsString((0, adapter_1.resolveDatabaseUrlEnv)(handoff.config));
-    const escapedApiTokenEnv = escapeForSingleQuotedJsString((0, adapter_1.resolveApiTokenEnv)(handoff.config));
+    const escapedRegistryDriver = escapeForSingleQuotedJsString((0, driver_1.resolveRegistryDriver)(handoff.config));
+    const escapedDatabaseUrlEnv = escapeForSingleQuotedJsString((0, driver_1.resolveDatabaseUrlEnv)(handoff.config));
+    const escapedApiTokenEnv = escapeForSingleQuotedJsString((0, driver_1.resolveApiTokenEnv)(handoff.config));
     // Asset storage selection baked (provider + module + env-var names + non-secret options JSON).
     const assetStorage = (0, resolve_1.resolveAssetStorageFromConfig)(handoff.config);
     const escapedAssetStorageAdapter = escapeForSingleQuotedJsString(assetStorage.adapterKind);
@@ -165,7 +234,7 @@ const initializeProjectApp = (handoff_1, ...args_1) => __awaiter(void 0, [handof
         '%HANDOFF_EXPORT_PATH%': escapedExportPath,
         '%HANDOFF_WEBSOCKET_PORT%': escapedWebsocketPort,
         '%HANDOFF_RUNTIME_MODE%': escapedRuntimeMode,
-        '%HANDOFF_REGISTRY_ADAPTER%': escapedRegistryAdapter,
+        '%HANDOFF_REGISTRY_DRIVER%': escapedRegistryDriver,
         '%HANDOFF_REGISTRY_DATABASE_URL_ENV%': escapedDatabaseUrlEnv,
         '%HANDOFF_REGISTRY_API_TOKEN_ENV%': escapedApiTokenEnv,
         '%HANDOFF_ASSET_STORAGE_ADAPTER%': escapedAssetStorageAdapter,
@@ -216,20 +285,7 @@ const buildApp = (handoff_1, ...args_1) => __awaiter(void 0, [handoff_1, ...args
     (0, static_export_1.validateReferencedArtifacts)(handoff);
     // Build app. The static target drives Next's `output: 'export'` via HANDOFF_BUILD_TARGET so the
     // export gate is tied to the resolved target, not to NODE_ENV.
-    const buildResult = cross_spawn_1.default.sync('npx', ['next', 'build'], {
-        cwd: appPath,
-        stdio: ['inherit', 'pipe', 'pipe'],
-        env: Object.assign(Object.assign({}, process.env), { NODE_ENV: 'production', HANDOFF_BUILD_TARGET: target }),
-    });
-    logger_1.Logger.childProcessBuffer(buildResult.stdout);
-    logger_1.Logger.childProcessBuffer(buildResult.stderr);
-    if (buildResult.status !== 0) {
-        let errorMsg = `Next.js build failed with exit code ${buildResult.status}`;
-        if (buildResult.error) {
-            errorMsg += `\nSpawn error: ${buildResult.error.message}`;
-        }
-        throw new Error(errorMsg);
-    }
+    yield runNextBuild(appPath, target, 'Next.js build');
     // Reproduce the docs read API (`/api/docs/*`) as route-shaped static files in the export output,
     // since `output: 'export'` disables the live API routes.
     const exportDir = path_1.default.resolve(appPath, 'out');
@@ -306,7 +362,7 @@ pipeline) before deploying new code:
 ${databaseUrlEnv}="postgres://…" handoff-app db:migrate
 \`\`\`
 
-\`db:migrate\` reads your project config + DB env vars, resolves the same database adapter the app was
+\`db:migrate\` reads your project config + DB env vars, resolves the same database driver the app was
 built with, and applies the package-owned migration set. It runs independently of \`build\` and of
 starting the server, so run it as a release/one-shot job.
 
@@ -352,15 +408,15 @@ containers, custom Node servers, and other non-Vercel hosts.
 });
 /**
  * Resolve the set of npm packages the packaged registry app must be able to `require`/`import` at
- * runtime, given the configured database adapter. `next`/`react`/`react-dom` run the server and React
+ * runtime, given the configured database driver. `next`/`react`/`react-dom` run the server and React
  * runtime; `drizzle-orm` backs both the request-time DB client and the migration runner; the driver
- * is adapter-specific (the Neon serverless driver also needs `ws` for its Node WebSocket transport).
+ * package is driver-specific (the Neon serverless driver also needs `ws` for its Node WebSocket transport).
  */
 const getRequiredRegistryRuntimeModules = (handoff) => {
     var _a;
     const base = ['next', 'react', 'react-dom', 'drizzle-orm'];
-    const adapter = (0, adapter_1.resolveRegistryAdapter)(handoff.config);
-    const driver = adapter === 'neon' ? ['@neondatabase/serverless', 'ws'] : ['pg'];
+    const driver = (0, driver_1.resolveRegistryDriver)(handoff.config);
+    const driverModules = driver === 'neon' ? ['@neondatabase/serverless', 'ws'] : ['pg'];
     // Asset-storage SDKs the deployed registry must be able to load at request time. The pre-packaged
     // Vercel Blob adapter needs `@vercel/blob`; a custom adapter may declare its installed SDK
     // package(s) via `assetStorage.options.sdkModules` so the trace/assertion covers them.
@@ -373,7 +429,7 @@ const getRequiredRegistryRuntimeModules = (handoff) => {
     if (Array.isArray(sdkModules)) {
         storage.push(...sdkModules.filter((mod) => typeof mod === 'string'));
     }
-    return [...base, ...driver, ...storage];
+    return [...base, ...driverModules, ...storage];
 };
 /**
  * Build-time guard against the empty-`node_modules` regression (the artifact would otherwise boot-fail
@@ -482,7 +538,7 @@ const assembleRegistryStandalone = (handoff, appPath, standaloneRoot, entryDir)
  *   - `vercel` → the Vercel Build Output API directory (`.vercel/output`) at the repo root: the
  *     traced bundle wrapped as a Node function plus CDN static assets and a route table.
  *
- * Mode is forced to `registry`; the database adapter is honored from config (single-sourced so build
+ * Mode is forced to `registry`; the database driver is honored from config (single-sourced so build
  * and `db:migrate` never diverge). No connection-string value is ever baked — only env-var *names*.
  */
 const buildRegistryApp = (handoff_1, ...args_1) => __awaiter(void 0, [handoff_1, ...args_1], void 0, function* (handoff, buildPackage = 'standalone') {
@@ -495,15 +551,15 @@ const buildRegistryApp = (handoff_1, ...args_1) => __awaiter(void 0, [handoff_1,
     if (sourceMode !== 'registry') {
         logger_1.Logger.info(`Source runtime.mode is "${sourceMode}"; forcing "registry" mode in the packaged registry app.`);
     }
-    // The adapter stays single-sourced from config (never flipped by the package flag), so build and
+    // The driver stays single-sourced from config (never flipped by the package flag), so build and
     // `db:migrate` always resolve the same one. `pg` uses long-lived TCP connections that pool poorly on
     // serverless; warn (non-fatally) so the operator points DATABASE_URL at a pooled endpoint or selects
-    // the Neon adapter. The connection-string value is not available at build time, so this cannot be
+    // the Neon driver. The connection-string value is not available at build time, so this cannot be
     // validated — it is guidance only and never fails the build.
-    if (buildPackage === 'vercel' && (0, adapter_1.resolveRegistryAdapter)(handoff.config) === 'pg') {
-        logger_1.Logger.warn('Registry Vercel build uses the "pg" adapter (standard TCP connections), which pools poorly on ' +
+    if (buildPackage === 'vercel' && (0, driver_1.resolveRegistryDriver)(handoff.config) === 'pg') {
+        logger_1.Logger.warn('Registry Vercel build uses the "pg" driver (standard TCP connections), which pools poorly on ' +
             'serverless and can exhaust the database connection limit. Point DATABASE_URL at a pooled endpoint ' +
-            '(PgBouncer / transaction pooling), or set runtime.registry.database.adapter: "neon" for a ' +
+            '(PgBouncer / transaction pooling), or set runtime.registry.database.driver: "neon" for a ' +
             'serverless-native HTTP/WebSocket driver. The build will continue.');
     }
     // Stage the app without any workspace-derived artifacts — the registry serves from the database.
@@ -524,20 +580,7 @@ const buildRegistryApp = (handoff_1, ...args_1) => __awaiter(void 0, [handoff_1,
     yield fs_extra_1.default.remove((0, vercel_output_1.getVercelOutputPath)(handoff));
     // Build the dynamic app. `output: 'standalone'` (driven by HANDOFF_BUILD_TARGET) traces the runtime
     // and the selected Postgres/Neon driver into a self-contained bundle — never a static export.
-    const buildResult = cross_spawn_1.default.sync('npx', ['next', 'build'], {
-        cwd: appPath,
-        stdio: ['inherit', 'pipe', 'pipe'],
-        env: Object.assign(Object.assign({}, process.env), { NODE_ENV: 'production', HANDOFF_BUILD_TARGET: 'registry' }),
-    });
-    logger_1.Logger.childProcessBuffer(buildResult.stdout);
-    logger_1.Logger.childProcessBuffer(buildResult.stderr);
-    if (buildResult.status !== 0) {
-        let errorMsg = `Registry app build failed with exit code ${buildResult.status}`;
-        if (buildResult.error) {
-            errorMsg += `\nSpawn error: ${buildResult.error.message}`;
-        }
-        throw new Error(errorMsg);
-    }
+    yield runNextBuild(appPath, 'registry', 'Registry app build');
     // Assemble the deployable package. Standalone tracing is rooted at the package (modulePath), so the
     // app's traced files land under `<relAppDir>` inside the standalone tree; static assets and public
     // files are not traced and must be copied alongside the server entry.
@@ -561,7 +604,7 @@ const buildRegistryApp = (handoff_1, ...args_1) => __awaiter(void 0, [handoff_1,
     // `handoff-app` source/CLI (`handoff-app db:migrate`) as a controlled release step (e.g. CI/CD),
     // never from the deployed bundle. See the generated README for the migrate-then-deploy flow.
     const entryRelativePath = path_1.default.relative(output, serverEntry).split(path_1.default.sep).join('/');
-    yield writeRegistryDeploymentReadme(output, entryRelativePath, (0, adapter_1.resolveDatabaseUrlEnv)(handoff.config));
+    yield writeRegistryDeploymentReadme(output, entryRelativePath, (0, driver_1.resolveDatabaseUrlEnv)(handoff.config));
     logger_1.Logger.success(`Packaged registry app at ${output} (start: \`node ${entryRelativePath}\`, migrate: \`handoff-app db:migrate\`).`);
 });
 /**

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

@@ -17,7 +17,7 @@ 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 driver_1 = require("../registry/db/driver");
 const paths_1 = require("./paths");
 /**
  * Publishes the tokens API files to the public directory.
@@ -55,7 +55,7 @@ exports.generateTokensApi = generateTokensApi;
  * 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
+ * needs the registry connection *inputs* (selected driver + 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.
  */
@@ -65,9 +65,9 @@ const buildServerRuntimeConfig = (config, modeOverride) => {
     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),
+            driver: (0, driver_1.resolveRegistryDriver)(config),
+            databaseUrlEnv: (0, driver_1.resolveDatabaseUrlEnv)(config),
+            apiTokenEnv: (0, driver_1.resolveApiTokenEnv)(config),
         },
         assetStorage: {
             adapter: assetStorage.adapterKind,

package/dist/app-builder/paths.js

@@ -50,14 +50,33 @@ 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 });
 });
+/**
+ * Copy the fetch-produced asset bundles (`exported/<id>/{collection}.zip`) into the app's public
+ * root, where the docs read API serves them at `/api/docs/assets/{collection}/{collection}.zip`.
+ * `fetch` writes these bundles, but `build`/`start` cleans and re-stages `.handoff` without them, so
+ * the download links 404 until the next fetch. Copying them here keeps the route working in workspace
+ * dev and static builds. Projects with no logos/icons have no bundles, so those 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 +88,8 @@ const syncPublicFiles = (handoff) => __awaiter(void 0, void 0, void 0, function*
         });
         yield mirrorDirectory(sourceApiPath, destinationApiPath);
     }
+    // Stage the asset bundles even when the workspace has no `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.js

@@ -176,6 +176,31 @@ const materializeDocsReadModel = (handoff, outDir) => __awaiter(void 0, void 0,
         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;
+/**
+ * Write the whole-collection asset bundles to the asset route
+ * (`api/docs/assets/{collection}/{collection}.zip`), the same URL the docs read API serves in
+ * registry mode, so the "Download" links work 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 `public/` is wiped by the build's clean+restage, so we copy them here again.
+ * Projects with no logos/icons have no bundles, so those are skipped rather than treated as 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.js

@@ -74,7 +74,7 @@ const writeStaticVercelOutput = (handoff, exportDir) => __awaiter(void 0, void 0
 });
 exports.writeStaticVercelOutput = writeStaticVercelOutput;
 /**
- * Node.js runtime identifier baked into the registry function's `.vc-config.json`. The `pg` adapter
+ * Node.js runtime identifier baked into the registry function's `.vc-config.json`. The `pg` driver
  * (and the Neon serverless driver in its Node fallback) need the Node.js runtime, not the edge
  * runtime — this is the required baseline. Vercel resolves the patch
  * version within this major; pinning the major keeps the artifact stable.
@@ -102,7 +102,7 @@ const MUTABLE_REGISTRY_PAGE_SRC_ROUTE = '/[...slug]';
  * data routes resolve the same way they do under the standalone server. `minimalMode:false` keeps
  * the function doing full in-process routing (the catch-all route forwards everything here).
  *
- * Runtime mode, adapter, and the DB env-var *name* are already baked into the resolved config the
+ * Runtime mode, driver, and the DB env-var *name* are already baked into the resolved config the
  * standalone build wrote to `.next/required-server-files.json`; the connection-string value is still
  * read from the named env var at request time, never baked.
  */

package/dist/artifacts/index.d.ts

@@ -1,2 +1,2 @@
 export { ARTIFACT_METADATA_PATH, REACT_PREVIEW_FORMAT_VERSION, SHARED_MAIN_CSS_ARTIFACT_PATH, SHARED_MAIN_JS_ARTIFACT_PATH, SHARED_STYLES_CSS_ARTIFACT_PATH, type ArtifactBuildMetadata, type ArtifactBuildStatus, type ArtifactDescriptor, type ArtifactKind, type ArtifactOwnerKind, type ArtifactReference, type ArtifactReferenceKind, type ArtifactSizeDiagnostics, } from './types';
-export { ARTIFACTS_ROUTE_SEGMENT, buildArtifactUrl, normalizeBasePath } from './url';
+export { ARTIFACTS_ROUTE_SEGMENT, ASSETS_ROUTE_SEGMENT, buildArtifactUrl, buildAssetDownloadUrl, buildAssetUrl, normalizeBasePath, } from './url';