handoff-app 2.0.0-0 → 2.0.0-1

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.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;
+/**
+ * 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/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';

package/dist/artifacts/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.normalizeBasePath = exports.buildArtifactUrl = exports.ARTIFACTS_ROUTE_SEGMENT = exports.SHARED_STYLES_CSS_ARTIFACT_PATH = exports.SHARED_MAIN_JS_ARTIFACT_PATH = exports.SHARED_MAIN_CSS_ARTIFACT_PATH = exports.REACT_PREVIEW_FORMAT_VERSION = exports.ARTIFACT_METADATA_PATH = void 0;
+exports.normalizeBasePath = exports.buildAssetUrl = exports.buildAssetDownloadUrl = exports.buildArtifactUrl = exports.ASSETS_ROUTE_SEGMENT = exports.ARTIFACTS_ROUTE_SEGMENT = exports.SHARED_STYLES_CSS_ARTIFACT_PATH = exports.SHARED_MAIN_JS_ARTIFACT_PATH = exports.SHARED_MAIN_CSS_ARTIFACT_PATH = exports.REACT_PREVIEW_FORMAT_VERSION = exports.ARTIFACT_METADATA_PATH = void 0;
 var types_1 = require("./types");
 Object.defineProperty(exports, "ARTIFACT_METADATA_PATH", { enumerable: true, get: function () { return types_1.ARTIFACT_METADATA_PATH; } });
 Object.defineProperty(exports, "REACT_PREVIEW_FORMAT_VERSION", { enumerable: true, get: function () { return types_1.REACT_PREVIEW_FORMAT_VERSION; } });
@@ -9,5 +9,8 @@ Object.defineProperty(exports, "SHARED_MAIN_JS_ARTIFACT_PATH", { enumerable: tru
 Object.defineProperty(exports, "SHARED_STYLES_CSS_ARTIFACT_PATH", { enumerable: true, get: function () { return types_1.SHARED_STYLES_CSS_ARTIFACT_PATH; } });
 var url_1 = require("./url");
 Object.defineProperty(exports, "ARTIFACTS_ROUTE_SEGMENT", { enumerable: true, get: function () { return url_1.ARTIFACTS_ROUTE_SEGMENT; } });
+Object.defineProperty(exports, "ASSETS_ROUTE_SEGMENT", { enumerable: true, get: function () { return url_1.ASSETS_ROUTE_SEGMENT; } });
 Object.defineProperty(exports, "buildArtifactUrl", { enumerable: true, get: function () { return url_1.buildArtifactUrl; } });
+Object.defineProperty(exports, "buildAssetDownloadUrl", { enumerable: true, get: function () { return url_1.buildAssetDownloadUrl; } });
+Object.defineProperty(exports, "buildAssetUrl", { enumerable: true, get: function () { return url_1.buildAssetUrl; } });
 Object.defineProperty(exports, "normalizeBasePath", { enumerable: true, get: function () { return url_1.normalizeBasePath; } });

package/dist/artifacts/url.d.ts

@@ -17,6 +17,8 @@
 export declare const ARTIFACTS_ROUTE_SEGMENT = "api/docs/artifacts";
 /** Route prefix for docs read API metadata (`.json`) reads. */
 export declare const DOCS_ROUTE_SEGMENT = "api/docs";
+/** Canonical route prefix all asset content URLs are served under (mode-independent). */
+export declare 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
@@ -47,3 +49,19 @@ export declare const buildComponentDetailUrl: (id: string, basePath?: string | n
  * (`{basePath}/api/docs/patterns/{id}.json`). The id is URL-encoded; `basePath` is preserved.
  */
 export declare const buildPatternDetailUrl: (id: string, basePath?: string | null) => string;
+/**
+ * Build the canonical, basePath-aware content URL for one asset within 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 individually encoded and traversal segments are rejected,
+ * mirroring {@link buildArtifactUrl}.
+ *
+ * @throws If the collection or logical path has no usable segments, or contains a `.`/`..` segment.
+ */
+export declare const buildAssetUrl: (collection: string, logicalPath: string, basePath?: string | null) => string;
+/**
+ * Build the canonical download URL for a collection's whole-collection zip bundle
+ * (`{basePath}/api/docs/assets/{collection}/{collection}.zip`) — the default target for the docs
+ * "Download" links, overridable via `assets_zip_links`.
+ */
+export declare const buildAssetDownloadUrl: (collection: string, basePath?: string | null) => string;

package/dist/artifacts/url.js

@@ -15,11 +15,13 @@
  * Next app can both import it.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildPatternDetailUrl = exports.buildComponentDetailUrl = exports.buildArtifactUrl = exports.normalizeBasePath = exports.DOCS_ROUTE_SEGMENT = exports.ARTIFACTS_ROUTE_SEGMENT = void 0;
+exports.buildAssetDownloadUrl = exports.buildAssetUrl = exports.buildPatternDetailUrl = exports.buildComponentDetailUrl = exports.buildArtifactUrl = exports.normalizeBasePath = exports.ASSETS_ROUTE_SEGMENT = exports.DOCS_ROUTE_SEGMENT = exports.ARTIFACTS_ROUTE_SEGMENT = void 0;
 /** Canonical route prefix all artifact URLs are served under. */
 exports.ARTIFACTS_ROUTE_SEGMENT = 'api/docs/artifacts';
 /** Route prefix for docs read API metadata (`.json`) reads. */
 exports.DOCS_ROUTE_SEGMENT = 'api/docs';
+/** Canonical route prefix all asset content URLs are served under (mode-independent). */
+exports.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
@@ -84,3 +86,31 @@ exports.buildComponentDetailUrl = buildComponentDetailUrl;
  */
 const buildPatternDetailUrl = (id, basePath) => `${(0, exports.normalizeBasePath)(basePath)}/${exports.DOCS_ROUTE_SEGMENT}/patterns/${encodeURIComponent(id)}.json`;
 exports.buildPatternDetailUrl = buildPatternDetailUrl;
+/**
+ * Build the canonical, basePath-aware content URL for one asset within 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 individually encoded and traversal segments are rejected,
+ * mirroring {@link buildArtifactUrl}.
+ *
+ * @throws If the collection or logical path has no usable segments, or contains a `.`/`..` segment.
+ */
+const buildAssetUrl = (collection, logicalPath, basePath) => {
+    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 `${(0, exports.normalizeBasePath)(basePath)}/${exports.ASSETS_ROUTE_SEGMENT}/${encoded}`;
+};
+exports.buildAssetUrl = buildAssetUrl;
+/**
+ * Build the canonical download URL for a collection's whole-collection zip bundle
+ * (`{basePath}/api/docs/assets/{collection}/{collection}.zip`) — the default target for the docs
+ * "Download" links, overridable via `assets_zip_links`.
+ */
+const buildAssetDownloadUrl = (collection, basePath) => (0, exports.buildAssetUrl)(collection, `${collection}.zip`, basePath);
+exports.buildAssetDownloadUrl = buildAssetDownloadUrl;

package/dist/types/config.d.ts

@@ -214,18 +214,18 @@ export interface Config {
      */
     entries?: ConfigEntries;
     /**
-     * Configuration for asset zip file download links
-     * @default { icons: "/icons.zip", logos: "/logos.zip" }
+     * Override URLs for the asset zip download links. When unset, each link defaults to the canonical,
+     * basePath-aware asset route `{basePath}/api/docs/assets/{collection}/{collection}.zip`, served by
+     * the docs read API in every runtime mode (from the DB in registry mode, from statically
+     * materialized files in a static export).
      */
     assets_zip_links?: {
         /**
-         * Path to the icons zip file
-         * @default "/icons.zip"
+         * Override URL for the icons zip. Defaults to `/api/docs/assets/icons/icons.zip` (basePath-aware).
          */
         icons?: string;
         /**
-         * Path to the logos zip file
-         * @default "/logos.zip"
+         * Override URL for the logos zip. Defaults to `/api/docs/assets/logos/logos.zip` (basePath-aware).
          */
         logos?: string;
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handoff-app",
-  "version": "2.0.0-0",
+  "version": "2.0.0-1",
   "description": "Automated documentation toolchain for building client side documentation from figma",
   "author ": {
     "name": "Convertiv",

package/src/app/components/Foundations/DisplayLogo.tsx

@@ -2,11 +2,17 @@ import React from 'react';
 import type { DisplayableAsset } from '../util/useCollectionAssets';
 
 export const DisplayLogo: React.FC<{ logo: DisplayableAsset; content?: string; correct?: boolean }> = ({ logo, content }) => {
-  // Registry serves the individual asset content URL; workspace/static serves the mirrored file.
+  // Workspace/static ships the SVG body inline in tokens.json (`data`) — render it directly so the
+  // logo has no dependency on the fetch-only `/api/assets/logos/*` files (absent on a static host).
+  // Registry has no inline body; it falls back to the individual asset content URL (`src`).
   const src = logo.src ?? `${process.env.HANDOFF_APP_BASE_PATH ?? ''}/api/assets/logos/${logo.path}`;
   return (
     <div className="flex flex-col gap-5">
-      <img src={src} alt="Usage Cards" className="rounded-3xl" />
+      {logo.data ? (
+        <div className="rounded-3xl" dangerouslySetInnerHTML={{ __html: logo.data }} />
+      ) : (
+        <img src={src} alt={logo.name} className="rounded-3xl" />
+      )}
       <div className="flex flex-row gap-4">
         <img src={`${process.env.HANDOFF_APP_BASE_PATH ?? ''}/assets/images/check-circle.svg`} alt="Do" className="h-6 w-6" />
         <p className="leading-normal text-gray-500">

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/[name]/index.tsx

@@ -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/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';
 
@@ -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/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/paths.ts

@@ -41,14 +41,36 @@ const mirrorDirectory = async (sourcePath: string, destinationPath: string): Pro
   await fs.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 = 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 +84,8 @@ export const syncPublicFiles = async (handoff: Handoff): Promise<void> => {
 
     await 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.
+  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.`
   );
+}
+
+/**
+ * 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 = 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/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';
 
+/** Canonical route prefix all asset content URLs are served under (mode-independent). */
+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 canonical, basePath-aware content URL for one asset within 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 individually encoded and traversal segments are rejected,
+ * mirroring {@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 canonical download URL for a collection's whole-collection zip bundle
+ * (`{basePath}/api/docs/assets/{collection}/{collection}.zip`) — the default target for the docs
+ * "Download" links, overridable via `assets_zip_links`.
+ */
+export const buildAssetDownloadUrl = (collection: string, basePath?: string | null): string =>
+  buildAssetUrl(collection, `${collection}.zip`, basePath);

package/src/types/config.ts

@@ -214,18 +214,18 @@ export interface Config {
    */
   entries?: ConfigEntries;
   /**
-   * Configuration for asset zip file download links
-   * @default { icons: "/icons.zip", logos: "/logos.zip" }
+   * Override URLs for the asset zip download links. When unset, each link defaults to the canonical,
+   * basePath-aware asset route `{basePath}/api/docs/assets/{collection}/{collection}.zip`, served by
+   * the docs read API in every runtime mode (from the DB in registry mode, from statically
+   * materialized files in a static export).
    */
   assets_zip_links?: {
     /**
-     * Path to the icons zip file
-     * @default "/icons.zip"
+     * Override URL for the icons zip. Defaults to `/api/docs/assets/icons/icons.zip` (basePath-aware).
      */
     icons?: string;
     /**
-     * Path to the logos zip file
-     * @default "/logos.zip"
+     * Override URL for the logos zip. Defaults to `/api/docs/assets/logos/logos.zip` (basePath-aware).
      */
     logos?: string;
   };