handoff-app 2.0.0-0 → 2.0.0-2

package/src/app/lib/registry-api/transfer.ts

@@ -432,6 +432,35 @@ const upsertBuildMetadata = async (db: RegistryDatabase, kind: TransferEntityKin
     .onConflictDoUpdate({ target: [buildMetadata.entityKind, buildMetadata.entityId], set: values as any });
 };
 
+/**
+ * Handles `GET /api/registry/transfer/{component|pattern|page}`. Lists summaries for one kind of
+ * entity: each id plus its build hashes and status. A connected workspace uses these to skip
+ * unchanged entities on a bulk publish and to enumerate published ids for a bulk checkout. The read
+ * is unauthenticated; only the registry-runtime and method guards apply.
+ */
+export const handleEntitySummaryRoute = (req: NextApiRequest, res: NextApiResponse, kind: TransferEntityKind): Promise<void> =>
+  handleRegistryRoute(req, res, ['GET'], async ({ db }) => {
+    const table = ENTITY[kind].table;
+    const rows = await db
+      .select({
+        id: table.id,
+        status: buildMetadata.status,
+        artifactHash: buildMetadata.artifactHash,
+        sourceHash: buildMetadata.sourceHash,
+      })
+      .from(table)
+      .leftJoin(buildMetadata, and(eq(buildMetadata.entityKind, kind), eq(buildMetadata.entityId, table.id)));
+
+    const entities = rows.map((row) => ({
+      id: row.id,
+      kind,
+      status: row.status ?? undefined,
+      artifactHash: row.artifactHash ?? undefined,
+      sourceHash: row.sourceHash ?? undefined,
+    }));
+    sendRegistryData(res, 200, { entities }, buildMeta());
+  });
+
 /**
  * Handle `GET /api/registry/transfer/{component|pattern}/:id` — checkout read. Returns the
  * normalized record plus its registry-safe source files so a connected workspace can reconstruct

package/src/app/lib/registry-connection.ts

@@ -7,7 +7,7 @@ import { getServerRuntimeConfig } from './docs-api/runtime-config';
  * Both the registry-mode docs read API and the registry management API resolve their database
  * through this single helper so one connection pool backs the whole registry runtime rather than
  * one pool per consumer. The connection string is read from the configured env var *name* at
- * request time — never persisted in config — and the selected adapter comes from the server runtime
+ * request time — never persisted in config — and the selected driver comes from the server runtime
  * config baked at build time.
  *
  * Server-only: imported exclusively by registry-mode API route helpers, which are themselves only
@@ -48,7 +48,7 @@ export const getRegistryConnection = (): Promise<RegistryDbConnection> => {
       )
     );
   }
-  connectionPromise = createRegistryDbConnection({ adapter: registry.adapter, connectionString }).catch((error) => {
+  connectionPromise = createRegistryDbConnection({ driver: registry.driver, connectionString }).catch((error) => {
     connectionPromise = null;
     // TODO: Route server errors through the shared logger.
     console.error('Registry database connection failed.', error);

package/src/app/next.config.mjs

@@ -95,7 +95,7 @@ const nextConfig = {
     // config-only — these are derived from `runtime.*`, not inferred from env at runtime. The DB
     // connection string itself is read from the named env var at request time (deployment-supplied).
     HANDOFF_RUNTIME_MODE: '%HANDOFF_RUNTIME_MODE%',
-    HANDOFF_REGISTRY_ADAPTER: '%HANDOFF_REGISTRY_ADAPTER%',
+    HANDOFF_REGISTRY_DRIVER: '%HANDOFF_REGISTRY_DRIVER%',
     HANDOFF_REGISTRY_DATABASE_URL_ENV: '%HANDOFF_REGISTRY_DATABASE_URL_ENV%',
     HANDOFF_REGISTRY_API_TOKEN_ENV: '%HANDOFF_REGISTRY_API_TOKEN_ENV%',
     // Asset storage selection (provider + non-secret options + env-var names). Secret values (Blob

package/src/app/pages/api/registry/transfer/[kind]/index.ts

@@ -0,0 +1,21 @@
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { singleQueryValue } from '@/lib/api/query';
+import { handleRegistryRoute, sendRegistryError } from '@/lib/registry-api';
+import { handleEntitySummaryRoute } from '@/lib/registry-api/transfer';
+
+/**
+ * `GET /api/registry/transfer/{component|pattern|page}`. Lists the registry's published entity
+ * summaries for one kind (id, build hashes, status) so a connected workspace can skip unchanged
+ * entities on a bulk publish and enumerate published ids for a bulk checkout. Registry-runtime only,
+ * enforced by the guard stack. The `tokens` and `assets` summaries have their own static routes,
+ * which Next resolves before this dynamic segment.
+ */
+export default function handler(req: NextApiRequest, res: NextApiResponse): Promise<void> {
+  const kind = singleQueryValue(req.query.kind);
+  if (kind !== 'component' && kind !== 'pattern' && kind !== 'page') {
+    return handleRegistryRoute(req, res, ['GET'], async () => {
+      sendRegistryError(res, 'not_found', `Unknown transfer entity kind "${kind ?? ''}".`);
+    });
+  }
+  return handleEntitySummaryRoute(req, res, kind);
+}

package/src/app/pages/assets/logos.tsx

@@ -6,6 +6,7 @@ import rehypeRaw from 'rehype-raw';
 import remarkGfm from 'remark-gfm';
 import Footer from '../../components/Footer';
 import { MarkdownComponents, remarkCodeMeta } from '../../components/Markdown/MarkdownComponents';
+import { buildAssetDownloadUrl } from '@handoff/artifacts/url';
 import Header from '../../components/old/Header';
 import { DocumentationProps, fetchDocPageMarkdown, getClientRuntimeConfig } from '../../components/util';
 
@@ -52,7 +53,9 @@ const AssetsLogosPage = ({ content, menu, metadata, config }: DocumentationProps
                 <h4>{config?.app?.client} Logo</h4>
                 <p>Vector files of approved {config?.app?.client} logos.</p>
                 <p>
-                  <a href={config?.assets_zip_links?.logos ?? '/logos.zip'}>Download Logos</a>
+                  <a href={config?.assets_zip_links?.logos ?? buildAssetDownloadUrl('logos', process.env.HANDOFF_APP_BASE_PATH)} download>
+                    Download Logos
+                  </a>
                 </p>
               </div>
             </div>

package/src/app/pages/foundations/icons/index.tsx

@@ -12,6 +12,7 @@ import { MarkdownComponents, remarkCodeMeta } from '../../../components/Markdown
 import HeadersType from '../../../components/Typography/Headers';
 import { buttonVariants } from '../../../components/ui/button';
 import { Input } from '../../../components/ui/input';
+import { buildAssetDownloadUrl } from '@handoff/artifacts/url';
 import { AssetDocumentationProps, buildTimeAssets, fetchDocPageMarkdown, getClientRuntimeConfig } from '../../../components/util';
 import { useCollectionAssets, type DisplayableAsset } from '../../../components/util/useCollectionAssets';
 
@@ -35,13 +36,13 @@ export const DisplayIcon: React.FC<{ icon: DisplayableAsset }> = ({ icon }) => {
 
   return (
     <div className="flex flex-col gap-2">
-      <Link href={`/foundations/icons/${icon.icon}`}>
+      <Link href={`/foundations/icons/library/${icon.icon}`}>
         <div className="flex flex-col items-center gap-6 rounded-lg border border-gray-100/80 bg-gray-100/80 py-12 transition-all hover:border-gray-300 hover:bg-gray-100 dark:border-gray-800 dark:bg-gray-900 dark:hover:border-gray-700 dark:hover:bg-gray-900">
           {/* Workspace/static: inline SVG body. Registry: the individual asset content URL. */}
           {icon.data ? <div dangerouslySetInnerHTML={{ __html: htmlData }} /> : <img className="o-icon h-6 w-6" src={icon.src} alt={icon.name} />}
         </div>
       </Link>
-      <Link href={`/foundations/icons/${icon.icon}`}>
+      <Link href={`/foundations/icons/library/${icon.icon}`}>
         <p className="font-mono text-[11px]">{icon.icon}</p>
       </Link>
     </div>
@@ -94,12 +95,13 @@ const IconsPage = ({ content, menu, metadata, current, config, assets }: AssetDo
         <HeadersType.H1>{metadata.title}</HeadersType.H1>
         <p className="max-w-[800px] text-lg font-light text-gray-500 dark:text-gray-300">{metadata.description}</p>
         <div className="mt-3 flex flex-row gap-3">
-          <Link
+          <a
             className={buttonVariants({ variant: 'outline', size: 'sm' }) + ' font-normal [&_svg]:size-3!'}
-            href={config?.assets_zip_links?.icons ?? '/icons.zip'}
+            href={config?.assets_zip_links?.icons ?? buildAssetDownloadUrl('icons', process.env.HANDOFF_APP_BASE_PATH)}
+            download
           >
             Download Icons <Download strokeWidth={1.5} />
-          </Link>
+          </a>
         </div>
       </div>
       <hr className="mb-10" />

package/src/app/pages/foundations/icons/{[name] → library/[name]}/index.tsx

@@ -5,12 +5,12 @@ import { GetStaticProps } from 'next';
 import Link from 'next/link';
 import { useRouter } from 'next/router';
 import * as React from 'react';
-import Footer from '../../../../components/Footer';
-import Layout from '../../../../components/Layout/Main';
-import HeadersType from '../../../../components/Typography/Headers';
-import { buttonVariants } from '../../../../components/ui/button';
-import { AssetDocumentationProps, buildTimeAssets, fetchDocPageMarkdown, getClientRuntimeConfig, getTokens, isRegistryRuntime } from '../../../../components/util';
-import { useSingleAsset, type DisplayableAsset } from '../../../../components/util/useCollectionAssets';
+import Footer from '../../../../../components/Footer';
+import Layout from '../../../../../components/Layout/Main';
+import HeadersType from '../../../../../components/Typography/Headers';
+import { buttonVariants } from '../../../../../components/ui/button';
+import { AssetDocumentationProps, buildTimeAssets, fetchDocPageMarkdown, getClientRuntimeConfig, getTokens, isRegistryRuntime } from '../../../../../components/util';
+import { useSingleAsset, type DisplayableAsset } from '../../../../../components/util/useCollectionAssets';
 
 const DisplayIcon: React.FC<{ icon: DisplayableAsset }> = ({ icon }) => {
   const htmlData = React.useMemo(() => {
@@ -124,13 +124,13 @@ export default function SingleIcon({ menu, metadata, current, config, assets }:
                 Copy SVG <Code strokeWidth={1.5} />
               </Link>
 
-              <Link
+              <a
                 href={icon.src ?? 'data:text/plain;charset=utf-8,' + encodeURIComponent(icon.data ?? '')}
                 download={icon.name}
                 className={buttonVariants({ variant: 'outline', size: 'sm' }) + ' font-normal [&_svg]:size-3!'}
               >
                 Download SVG <Download strokeWidth={1.5} />
-              </Link>
+              </a>
             </div>
           </div>
 

package/src/app/pages/foundations/logo.tsx

@@ -1,6 +1,6 @@
 import type { GetStaticProps } from 'next';
-import Link from 'next/link';
 
+import { buildAssetDownloadUrl } from '@handoff/artifacts/url';
 import { AssetDocumentationProps, buildTimeAssets, fetchDocPageMarkdown, getClientRuntimeConfig } from '../../components/util';
 import { useCollectionAssets } from '../../components/util/useCollectionAssets';
 
@@ -56,12 +56,13 @@ const LogoPage = ({ content, menu, metadata, current, config, assets }: AssetDoc
         <HeadersType.H1>{metadata.title}</HeadersType.H1>
         <p className="text-lg leading-relaxed text-gray-600 dark:text-gray-300">{metadata.description}</p>
         <div className="mt-3 flex flex-row gap-3">
-          <Link
+          <a
             className={buttonVariants({ variant: 'outline', size: 'sm' }) + ' font-normal [&_svg]:size-3!'}
-            href={config?.assets_zip_links?.logos ?? '/logos.zip'}
+            href={config?.assets_zip_links?.logos ?? buildAssetDownloadUrl('logos', process.env.HANDOFF_APP_BASE_PATH)}
+            download
           >
             Download Logos <Download strokeWidth={1.5} />
-          </Link>
+          </a>
         </div>
       </div>
 

package/src/app-builder/build.ts

@@ -1,3 +1,4 @@
+import * as p from '@clack/prompts';
 import spawn from 'cross-spawn';
 import fs from 'fs-extra';
 import path from 'path';
@@ -7,7 +8,7 @@ import { buildPatterns } from '../pipeline/patterns';
 import processComponents from '../transformers/preview/component/builder';
 import { buildMainCss } from '../transformers/preview/component/css';
 import { buildMainJS } from '../transformers/preview/component/javascript';
-import { resolveApiTokenEnv, resolveDatabaseUrlEnv, resolveRegistryAdapter } from '../registry/db/adapter';
+import { resolveApiTokenEnv, resolveDatabaseUrlEnv, resolveRegistryDriver } from '../registry/db/driver';
 import { resolveAssetStorageFromConfig } from '../registry/asset-storage/resolve';
 import type { RuntimeMode } from '../types/config';
 import { Logger } from '../utils/logger';
@@ -104,6 +105,63 @@ const assertStaticBuildAllowed = (handoff: Handoff): void => {
   }
 };
 
+/**
+ * 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 = async (appPath: string, target: BuildTarget, errorLabel: string): Promise<void> => {
+  const spinner = p.spinner();
+  spinner.start('Building Next.js app...');
+
+  const stdout: Buffer[] = [];
+  const stderr: Buffer[] = [];
+
+  await new Promise<void>((resolve, reject) => {
+    const buildProcess = spawn('npx', ['next', 'build'], {
+      cwd: appPath,
+      stdio: ['inherit', 'pipe', 'pipe'],
+      env: {
+        ...process.env,
+        NODE_ENV: 'production',
+        HANDOFF_BUILD_TARGET: target,
+      },
+    });
+
+    buildProcess.stdout?.on('data', (chunk: Buffer) => stdout.push(Buffer.from(chunk)));
+    buildProcess.stderr?.on('data', (chunk: Buffer) => stderr.push(Buffer.from(chunk)));
+
+    let settled = false;
+
+    const fail = (message: string): void => {
+      if (settled) return;
+      settled = true;
+
+      spinner.stop('Next.js app build failed');
+      Logger.childProcessBuffer(Buffer.concat(stdout));
+      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>`
@@ -198,7 +256,7 @@ const initializeProjectApp = async (handoff: Handoff, options: InitializeProject
   // 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(resolveRegistryAdapter(handoff.config));
+  const escapedRegistryDriver = escapeForSingleQuotedJsString(resolveRegistryDriver(handoff.config));
   const escapedDatabaseUrlEnv = escapeForSingleQuotedJsString(resolveDatabaseUrlEnv(handoff.config));
   const escapedApiTokenEnv = escapeForSingleQuotedJsString(resolveApiTokenEnv(handoff.config));
   // Asset storage selection baked (provider + module + env-var names + non-secret options JSON).
@@ -216,7 +274,7 @@ const initializeProjectApp = async (handoff: Handoff, options: InitializeProject
     '%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,
@@ -283,26 +341,7 @@ const buildApp = async (
 
   // 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 = spawn.sync('npx', ['next', 'build'], {
-    cwd: appPath,
-    stdio: ['inherit', 'pipe', 'pipe'],
-    env: {
-      ...process.env,
-      NODE_ENV: 'production',
-      HANDOFF_BUILD_TARGET: target,
-    },
-  });
-
-  Logger.childProcessBuffer(buildResult.stdout);
-  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);
-  }
+  await 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.
@@ -390,7 +429,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.
 
@@ -437,14 +476,14 @@ 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: Handoff): string[] => {
   const base = ['next', 'react', 'react-dom', 'drizzle-orm'];
-  const adapter = resolveRegistryAdapter(handoff.config);
-  const driver = adapter === 'neon' ? ['@neondatabase/serverless', 'ws'] : ['pg'];
+  const driver = 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.
@@ -457,7 +496,7 @@ const getRequiredRegistryRuntimeModules = (handoff: Handoff): string[] => {
   if (Array.isArray(sdkModules)) {
     storage.push(...sdkModules.filter((mod): mod is string => typeof mod === 'string'));
   }
-  return [...base, ...driver, ...storage];
+  return [...base, ...driverModules, ...storage];
 };
 
 /**
@@ -584,7 +623,7 @@ const assembleRegistryStandalone = async (
  *   - `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 = async (handoff: Handoff, buildPackage: BuildPackage = 'standalone'): Promise<void> => {
@@ -597,16 +636,16 @@ const buildRegistryApp = async (handoff: Handoff, buildPackage: BuildPackage = '
     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' && resolveRegistryAdapter(handoff.config) === 'pg') {
+  if (buildPackage === 'vercel' && resolveRegistryDriver(handoff.config) === 'pg') {
     Logger.warn(
-      'Registry Vercel build uses the "pg" adapter (standard TCP connections), which pools poorly on ' +
+      '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.'
     );
   }
@@ -632,26 +671,7 @@ const buildRegistryApp = async (handoff: Handoff, buildPackage: BuildPackage = '
 
   // 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 = spawn.sync('npx', ['next', 'build'], {
-    cwd: appPath,
-    stdio: ['inherit', 'pipe', 'pipe'],
-    env: {
-      ...process.env,
-      NODE_ENV: 'production',
-      HANDOFF_BUILD_TARGET: 'registry',
-    },
-  });
-
-  Logger.childProcessBuffer(buildResult.stdout);
-  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);
-  }
+  await 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

package/src/app-builder/client-config.ts

@@ -3,7 +3,7 @@ import path from 'path';
 import Handoff from '..';
 import { getClientConfig } from '../config';
 import { resolveAssetStorageFromConfig } from '../registry/asset-storage/resolve';
-import { resolveApiTokenEnv, resolveDatabaseUrlEnv, resolveRegistryAdapter } from '../registry/db/adapter';
+import { resolveApiTokenEnv, resolveDatabaseUrlEnv, resolveRegistryDriver } from '../registry/db/driver';
 import type { Config, RuntimeMode } from '../types/config';
 import { getAppPath } from './paths';
 
@@ -48,7 +48,7 @@ export const generateTokensApi = async (handoff: Handoff) => {
  * 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.
  */
@@ -57,7 +57,7 @@ const buildServerRuntimeConfig = (config: Config, modeOverride?: RuntimeMode) =>
   return {
     mode: modeOverride ?? config?.runtime?.mode ?? 'workspace',
     registry: {
-      adapter: resolveRegistryAdapter(config),
+      driver: resolveRegistryDriver(config),
       databaseUrlEnv: resolveDatabaseUrlEnv(config),
       apiTokenEnv: resolveApiTokenEnv(config),
     },

package/src/app-builder/paths.ts

@@ -41,14 +41,34 @@ const mirrorDirectory = async (sourcePath: string, destinationPath: string): Pro
   await fs.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 = async (handoff: Handoff, destinationPublicPath: string): Promise<void> => {
+  const bundles: Array<{ src: string; name: string }> = [
+    { src: handoff.getLogosZipFilePath(), name: 'logos.zip' },
+    { src: handoff.getIconsZipFilePath(), name: 'icons.zip' },
+  ];
+  for (const { src, name } of bundles) {
+    if (fs.existsSync(src) && fs.statSync(src).isFile()) {
+      await fs.ensureDir(destinationPublicPath);
+      await fs.copy(src, path.resolve(destinationPublicPath, name), { overwrite: true });
+    }
+  }
+};
+
 /**
  * Copy the public dir from the working dir to the module dir.
  */
 export const syncPublicFiles = async (handoff: Handoff): Promise<void> => {
   const appPath = getAppPath(handoff);
+  const destinationPublicPath = path.resolve(appPath, 'public');
   const workingPublicPath = getWorkingPublicPath(handoff);
   if (workingPublicPath) {
-    const destinationPublicPath = path.resolve(appPath, 'public');
     const sourceApiPath = path.resolve(workingPublicPath, 'api');
     const destinationApiPath = path.resolve(destinationPublicPath, 'api');
 
@@ -62,4 +82,8 @@ export const syncPublicFiles = async (handoff: Handoff): Promise<void> => {
 
     await 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.
+  await stageAssetDownloadBundles(handoff, destinationPublicPath);
 };

package/src/app-builder/static-export.ts

@@ -209,7 +209,34 @@ export const materializeDocsReadModel = async (handoff: Handoff, outDir: string)
     await fs.writeJson(path.join(docsRoot, 'patterns', `${pattern.id}.json`), detail);
   }
 
+  await materializeAssetDownloads(handoff, docsRoot);
+
   Logger.success(
     `Materialized docs read model (${components.length} component(s), ${patterns.length} pattern(s)) for static export.`
   );
+}
+
+/**
+ * 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 = async (handoff: Handoff, docsRoot: string): Promise<void> => {
+  const bundles: Array<{ collection: string; src: string }> = [
+    { collection: 'logos', src: handoff.getLogosZipFilePath() },
+    { collection: 'icons', src: handoff.getIconsZipFilePath() },
+  ];
+  let copied = 0;
+  for (const { collection, src } of bundles) {
+    if (fs.existsSync(src) && fs.statSync(src).isFile()) {
+      await fs.copy(src, path.join(docsRoot, 'assets', collection, `${collection}.zip`), { overwrite: true });
+      copied += 1;
+    }
+  }
+  if (copied > 0) {
+    Logger.info(`Materialized ${copied} asset download bundle(s) for static export.`);
+  }
 };

package/src/app-builder/vercel-output.ts

@@ -66,7 +66,7 @@ export const writeStaticVercelOutput = async (handoff: Handoff, exportDir: strin
 };
 
 /**
- * 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.
@@ -98,7 +98,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/src/artifacts/index.ts

@@ -14,4 +14,11 @@ export {
   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';

package/src/artifacts/url.ts

@@ -20,6 +20,9 @@ export const ARTIFACTS_ROUTE_SEGMENT = 'api/docs/artifacts';
 /** Route prefix for docs read API metadata (`.json`) reads. */
 export const DOCS_ROUTE_SEGMENT = 'api/docs';
 
+/** Route prefix all asset content URLs are served under, regardless of runtime mode. */
+export const ASSETS_ROUTE_SEGMENT = 'api/docs/assets';
+
 /**
  * Normalize a configured basePath to either an empty string or a single-leading-slash,
  * no-trailing-slash form. Mirrors the Next app's `resolveBasePath` so builder output composes
@@ -88,3 +91,32 @@ export const buildComponentDetailUrl = (id: string, basePath?: string | null): s
  */
 export const buildPatternDetailUrl = (id: string, basePath?: string | null): string =>
   `${normalizeBasePath(basePath)}/${DOCS_ROUTE_SEGMENT}/patterns/${encodeURIComponent(id)}.json`;
+
+/**
+ * Build the basePath-aware content URL for a single asset in a collection
+ * (`{basePath}/api/docs/assets/{collection}/{logicalPath}`). This is the same route the docs read API
+ * serves in every runtime mode: from the database in registry mode, and from statically materialized
+ * files in a static export. Each segment is encoded on its own and traversal segments are rejected,
+ * matching {@link buildArtifactUrl}.
+ *
+ * @throws If the collection or logical path has no usable segments, or contains a `.`/`..` segment.
+ */
+export const buildAssetUrl = (collection: string, logicalPath: string, basePath?: string | null): string => {
+  const segments = [...toArtifactSegments(collection), ...toArtifactSegments(logicalPath)];
+  if (segments.length < 2) {
+    throw new Error(`Cannot build asset URL: empty collection ("${collection}") or path ("${logicalPath}").`);
+  }
+  if (segments.some(isTraversalSegment)) {
+    throw new Error(`Cannot build asset URL: path traversal is not allowed in "${collection}/${logicalPath}".`);
+  }
+  const encoded = segments.map((segment) => encodeURIComponent(segment)).join('/');
+  return `${normalizeBasePath(basePath)}/${ASSETS_ROUTE_SEGMENT}/${encoded}`;
+};
+
+/**
+ * Build the download URL for a collection's zip bundle
+ * (`{basePath}/api/docs/assets/{collection}/{collection}.zip`). This is the default target for the
+ * docs "Download" links and can be overridden via `assets_zip_links`.
+ */
+export const buildAssetDownloadUrl = (collection: string, basePath?: string | null): string =>
+  buildAssetUrl(collection, `${collection}.zip`, basePath);