handoff-app 1.2.2-7 → 2.0.0-0

package/src/nav/workspace.ts

@@ -0,0 +1,87 @@
+import * as fs from 'fs';
+import matter from 'gray-matter';
+import path from 'path';
+import { buildMenuShell, buildTokensFoundationsMenu } from '../utils/menu-shell';
+import type { NavData, NavEntity, NavLoad, NavPageRecord, NavTokenSet } from '.';
+import { getNavData } from './resolver';
+
+type Awaitable<T> = T | Promise<T>;
+
+export interface WorkspaceNavLoaders {
+  components: () => Awaitable<NavEntity[]>;
+  patterns: () => Awaitable<NavEntity[]>;
+  pages: () => Awaitable<NavPageRecord[]>;
+  tokenSets: () => Awaitable<NavTokenSet[]>;
+}
+
+export interface WorkspaceNavAdapterOptions {
+  docRoot: string;
+  workingPagesDir?: string;
+  basePath?: string;
+  load?: NavLoad;
+  loaders: WorkspaceNavLoaders;
+}
+
+const safeLoad = async <T>(load: () => Awaitable<T[]>): Promise<T[]> => {
+  try {
+    return (await load()) ?? [];
+  } catch {
+    return [];
+  }
+};
+
+const markdownTitle = (id: string, docRoot: string, workingPagesDir?: string): string | undefined => {
+  const candidates = [
+    workingPagesDir ? path.resolve(workingPagesDir, 'system', `${id}.md`) : '',
+    path.resolve(docRoot, 'system', `${id}.md`),
+  ];
+  for (const candidate of candidates) {
+    if (!candidate || !fs.existsSync(candidate)) continue;
+    const title = matter(fs.readFileSync(candidate, 'utf8')).data.title;
+    if (typeof title === 'string' && title.trim()) return title;
+  }
+  return undefined;
+};
+
+/** Workspace/static adapter: live filesystem shell plus best-effort local snapshot loaders. */
+export const getWorkspaceNavData = async (options: WorkspaceNavAdapterOptions): Promise<NavData> => {
+  const [loadedComponents, patterns, pages, loadedTokenSets] = await Promise.all([
+    safeLoad(options.loaders.components),
+    safeLoad(options.loaders.patterns),
+    safeLoad(options.loaders.pages),
+    safeLoad(options.loaders.tokenSets),
+  ]);
+  const components = loadedComponents.map((component) => ({
+    ...component,
+    title: component.title || markdownTitle(component.id, options.docRoot, options.workingPagesDir),
+  }));
+  const componentById = new Map(components.map((component) => [component.id, component]));
+  const tokenSets = loadedTokenSets.map((set) => {
+    const id = set.id.startsWith('component/') ? set.id.slice('component/'.length) : set.id;
+    const component = componentById.get(id);
+    return {
+      ...set,
+      title: set.title || component?.title || markdownTitle(id, options.docRoot, options.workingPagesDir),
+      group: set.group ?? component?.group,
+    };
+  });
+  const normalizedBasePath = options.basePath ? `${options.basePath.replace(/^\/+|\/+$/g, '')}/` : '';
+
+  return getNavData({
+    mode: 'workspace',
+    load: options.load ?? 'refresh',
+    sources: {
+      shell: buildMenuShell({
+        docRoot: options.docRoot,
+        workingPagesDir: options.workingPagesDir,
+        basePath: options.basePath,
+      }),
+      components,
+      patterns,
+      pages,
+      tokenSets,
+      tokenFoundations: buildTokensFoundationsMenu(normalizedBasePath),
+      basePath: options.basePath,
+    },
+  });
+};

package/src/pipeline/styles.ts

@@ -5,6 +5,7 @@ import path from 'path';
 import Handoff from '..';
 import { FontFamily } from '../types/font';
 import { zip } from './archive';
+import { resolveTokenTransformers } from './token-transformers';
 
 /**
  * Build just the custom fonts — zips font directories and copies them to the export folder.
@@ -41,41 +42,9 @@ export const buildCustomFonts = async (handoff: Handoff, documentationObject: Ha
  * Builds design token style files using core and user-configured transformers.
  */
 export const buildStyles = async (handoff: Handoff, documentationObject: HandoffTypes.IDocumentationObject) => {
-  // Core transformers that should always be included
-  const coreTransformers = [
-    {
-      transformer: Transformers.ScssTransformer,
-      outDir: 'sass',
-      format: 'scss',
-    },
-    {
-      transformer: Transformers.ScssTypesTransformer,
-      outDir: 'types',
-      format: 'scss',
-    },
-    {
-      transformer: Transformers.CssTransformer,
-      outDir: 'css',
-      format: 'css',
-    },
-  ];
-
-  // Get user-configured transformers
-  const userTransformers = handoff.config?.pipeline?.transformers || [];
-
-  // Merge core transformers with user transformers
-  // If a user transformer matches a core transformer, use user's outDir and format
-  const transformers = coreTransformers.map((coreTransformer) => {
-    const userTransformer = userTransformers.find((t) => t.transformer === coreTransformer.transformer);
-    return userTransformer ? { ...coreTransformer, outDir: userTransformer.outDir, format: userTransformer.format } : coreTransformer;
-  });
-
-  // Add any additional user transformers that aren't core transformers
-  userTransformers.forEach((userTransformer) => {
-    if (!coreTransformers.some((core) => core.transformer === userTransformer.transformer)) {
-      transformers.push(userTransformer);
-    }
-  });
+  // Resolve the merged core + user-configured transformer list (single source of truth, shared with
+  // the registry publish packaging so the on-disk layout never drifts).
+  const transformers = resolveTokenTransformers(handoff);
 
   const baseDir = handoff.getVariablesFilePath();
   const runner = await handoff.getRunner();

package/src/pipeline/token-transformers.ts

@@ -0,0 +1,97 @@
+/**
+ * Shared resolution of the design-token style transformers and their on-disk layout.
+ *
+ * Both {@link import('./styles').buildStyles} (which writes the generated token files) and the
+ * registry publish packaging (which reads them back byte-for-byte) must agree on exactly which
+ * transformers run, their output directories/formats, and the path each set's files land at. This
+ * module is the single source of that layout so the two never drift.
+ */
+
+import { Transformers } from 'handoff-core';
+import type { TransformerConfig } from '../types/config';
+
+/** Minimal shape needed to resolve transformers: just the pipeline transformer config. */
+export interface TokenTransformerContext {
+  config?: { pipeline?: { transformers?: TransformerConfig[] } | null } | null;
+}
+
+/** A resolved token transformer: the factory plus its output directory, file format, and logical label. */
+export interface ResolvedTokenTransformer {
+  transformer: any;
+  outDir: string;
+  format: string;
+  /** Stable logical label for the output (`css`|`scss`|`types`|`styleDictionary`|custom `outDir`). */
+  label: string;
+}
+
+/** The three core transformers Handoff always runs, matching the historical `buildStyles` defaults. */
+const CORE_TRANSFORMERS = [
+  { transformer: Transformers.ScssTransformer, outDir: 'sass', format: 'scss', label: 'scss' },
+  { transformer: Transformers.ScssTypesTransformer, outDir: 'types', format: 'scss', label: 'types' },
+  { transformer: Transformers.CssTransformer, outDir: 'css', format: 'css', label: 'css' },
+] as const;
+
+/** Logical label for a transformer factory: known core/SD labels, else the custom transformer's outDir. */
+const labelForTransformer = (transformer: any, outDir: string): string => {
+  if (transformer === Transformers.ScssTransformer) return 'scss';
+  if (transformer === Transformers.ScssTypesTransformer) return 'types';
+  if (transformer === Transformers.CssTransformer) return 'css';
+  if (transformer === Transformers.StyleDictionaryTransformer) return 'styleDictionary';
+  return outDir;
+};
+
+/**
+ * Resolve the merged transformer list (core + user-configured). A user transformer matching a core
+ * transformer overrides its `outDir`/`format`; other user transformers (e.g. Style Dictionary or a
+ * fully custom transformer) are appended. Mirrors the historical inline logic in `buildStyles`.
+ */
+export const resolveTokenTransformers = (context: TokenTransformerContext): ResolvedTokenTransformer[] => {
+  const userTransformers = context.config?.pipeline?.transformers || [];
+
+  const transformers: ResolvedTokenTransformer[] = CORE_TRANSFORMERS.map((core) => {
+    const override = userTransformers.find((t) => t.transformer === core.transformer);
+    return override
+      ? { transformer: core.transformer, outDir: override.outDir, format: override.format, label: labelForTransformer(core.transformer, override.outDir) }
+      : { ...core };
+  });
+
+  userTransformers.forEach((userTransformer) => {
+    if (!CORE_TRANSFORMERS.some((core) => core.transformer === userTransformer.transformer)) {
+      transformers.push({
+        transformer: userTransformer.transformer,
+        outDir: userTransformer.outDir,
+        format: userTransformer.format,
+        label: labelForTransformer(userTransformer.transformer, userTransformer.outDir),
+      });
+    }
+  });
+
+  return transformers;
+};
+
+/** A generated token artifact expected for a set: its registry-safe relative path + logical label. */
+export interface TokenArtifactLayout {
+  /** Path relative to `getVariablesFilePath()`, e.g. `css/colors.css` or `sd/button/button.tokens.json`. */
+  path: string;
+  /** Logical format label (`css`|`scss`|`types`|`styleDictionary`|custom). */
+  format: string;
+}
+
+/**
+ * Compute the registry-safe relative paths (under `getVariablesFilePath()`) a single set's generated
+ * files land at, across every resolved transformer. Honors the Style Dictionary nesting special-case
+ * (`buildStyles`): SD component tokens go to `<outDir>/<name>/<name>.tokens.json`, SD foundation
+ * tokens to `<outDir>/<name>.tokens.json`; every other transformer writes `<outDir>/<name>.<format>`.
+ */
+export const tokenArtifactPathsForSet = (
+  transformers: ResolvedTokenTransformer[],
+  setName: string,
+  isComponent: boolean
+): TokenArtifactLayout[] =>
+  transformers.map(({ outDir, format, label }) => {
+    if (label === 'styleDictionary') {
+      const path = isComponent ? `${outDir}/${setName}/${setName}.tokens.json` : `${outDir}/${setName}.tokens.json`;
+      return { path, format: label };
+    }
+    return { path: `${outDir}/${setName}.${format}`, format: label };
+  });

package/src/registry/asset-storage/adapters/vercel-blob.ts

@@ -0,0 +1,51 @@
+/**
+ * Pre-packaged Vercel Blob asset storage adapter.
+ *
+ * Ships with Handoff and is selected via `runtime.registry.assetStorage.adapter: "vercel-blob"`. The
+ * read/write token is read from `process.env[tokenEnv]` at request time (never persisted in config).
+ * Blobs are stored public and content-addressed by hash, so reads resolve to a direct provider URL
+ * (a `redirect` result), keeping large payloads out of the serverless function body/response.
+ *
+ * The `@vercel/blob` SDK is loaded lazily so it is only pulled into memory (and traced into the
+ * registry bundle) when this adapter is actually used.
+ */
+
+import type { AssetStorage } from '../types';
+
+/** Build a Vercel Blob storage adapter bound to a token env-var name + non-secret options. */
+export const createVercelBlobStorage = (params: { tokenEnv: string; options: Record<string, unknown> }): AssetStorage => {
+  const prefix = typeof params.options.prefix === 'string' && params.options.prefix.trim() ? params.options.prefix.trim() : 'handoff/assets';
+
+  const resolveToken = (): string => {
+    const token = process.env[params.tokenEnv]?.trim();
+    if (!token) {
+      throw new Error(
+        `Vercel Blob storage is configured but the token env var "${params.tokenEnv}" is not set. ` +
+          'Set it to a Blob read/write token, or change runtime.registry.assetStorage.tokenEnv.'
+      );
+    }
+    return token;
+  };
+
+  return {
+    async put({ hash, bytes, contentType }) {
+      const { put } = await import('@vercel/blob');
+      // Content-addressed pathname + no random suffix so the same bytes map to a stable, dedupable key.
+      const result = await put(`${prefix}/${hash}`, bytes, {
+        access: 'public',
+        token: resolveToken(),
+        contentType,
+        addRandomSuffix: false,
+      });
+      return { storageRef: result.url };
+    },
+    async get(storageRef) {
+      // Public blob URLs are directly fetchable; redirect the client to avoid proxying bytes.
+      return { kind: 'redirect', url: storageRef };
+    },
+    async delete(storageRef) {
+      const { del } = await import('@vercel/blob');
+      await del(storageRef, { token: resolveToken() });
+    },
+  };
+};

package/src/registry/asset-storage/define.ts

@@ -0,0 +1,15 @@
+/**
+ * Typed identity helper for custom asset storage adapters (mirrors `defineComponent`): a consumer
+ * default-exports its result from a **server-only** module and points
+ * `runtime.registry.assetStorage.module` at it. It must be its own module (not an inline
+ * `defineConfig` function) so the build can trace it into the deployed registry. The default export
+ * may be the adapter object, or a factory `(context) => AssetStorage` when it needs its options/env.
+ */
+
+import type { AssetStorage, AssetStorageFactory } from './types';
+
+export function defineAssetStorage(adapter: AssetStorage): AssetStorage;
+export function defineAssetStorage(factory: AssetStorageFactory): AssetStorageFactory;
+export function defineAssetStorage(input: AssetStorage | AssetStorageFactory): AssetStorage | AssetStorageFactory {
+  return input;
+}

package/src/registry/asset-storage/resolve.ts

@@ -0,0 +1,72 @@
+/**
+ * Asset storage settings resolution.
+ *
+ * `runtime.registry.assetStorage` selects the active provider for **new** uploads: the built-in
+ * `database` inline default, the pre-packaged `vercel-blob` adapter, or a `custom` module. Mirrors
+ * {@link import('../db/adapter')}: only provider selection, module location, non-secret options, and
+ * env-var *names* are ever persisted; secret *values* are read from `process.env` at request time.
+ */
+
+import type { Config } from '../../types/config';
+import type { AssetStorageProvider } from '../db/schema';
+
+/** Which adapter implementation is active. */
+export type AssetStorageAdapterKind = 'database' | 'vercel-blob' | 'custom';
+
+/** The raw, authored settings block (a structural copy of the config type, resolvable from bake). */
+export interface AssetStorageSettings {
+  adapter?: AssetStorageAdapterKind;
+  module?: string;
+  tokenEnv?: string;
+  maxInlineBytes?: number;
+  options?: Record<string, unknown>;
+}
+
+/** Default adapter when none is configured. */
+export const DEFAULT_ASSET_STORAGE_ADAPTER: AssetStorageAdapterKind = 'database';
+
+/** Default env-var name holding the Vercel Blob read/write token. */
+export const DEFAULT_BLOB_TOKEN_ENV = 'BLOB_READ_WRITE_TOKEN';
+
+/** Default max bytes kept inline in Postgres `bytea` (4 MB, under Vercel's ~4.5 MB function limit). */
+export const DEFAULT_MAX_INLINE_BYTES = 4 * 1024 * 1024;
+
+/** Fully resolved asset storage settings. */
+export interface ResolvedAssetStorage {
+  /** The active adapter implementation. */
+  adapterKind: AssetStorageAdapterKind;
+  /** Provider id recorded on blob rows written by the active adapter (drives read resolution). */
+  provider: AssetStorageProvider;
+  /** For `custom`: the server-only adapter module path. */
+  module?: string;
+  /** For `vercel-blob`: the env-var name holding the token. */
+  tokenEnv: string;
+  /** For `database`: the inline-content size ceiling. */
+  maxInlineBytes: number;
+  /** Non-secret adapter options. */
+  options: Record<string, unknown>;
+}
+
+/** The stable provider id recorded on blobs for a custom adapter (single custom provider at a time). */
+const customProviderId = (options: Record<string, unknown>): AssetStorageProvider => {
+  const id = typeof options.providerId === 'string' && options.providerId.trim() ? options.providerId.trim() : 'custom';
+  return id;
+};
+
+/** Resolve raw asset storage settings into a fully-defaulted shape. */
+export const resolveAssetStorageSettings = (settings: AssetStorageSettings | null | undefined): ResolvedAssetStorage => {
+  const adapterKind = settings?.adapter ?? DEFAULT_ASSET_STORAGE_ADAPTER;
+  const options = settings?.options ?? {};
+  const tokenEnv = settings?.tokenEnv?.trim() || DEFAULT_BLOB_TOKEN_ENV;
+  const maxInlineBytes =
+    typeof settings?.maxInlineBytes === 'number' && settings.maxInlineBytes > 0 ? settings.maxInlineBytes : DEFAULT_MAX_INLINE_BYTES;
+
+  const provider: AssetStorageProvider =
+    adapterKind === 'vercel-blob' ? 'vercel-blob' : adapterKind === 'custom' ? customProviderId(options) : 'database';
+
+  return { adapterKind, provider, module: settings?.module?.trim() || undefined, tokenEnv, maxInlineBytes, options };
+};
+
+/** Resolve the active asset storage settings from a loaded config (CLI/build side). */
+export const resolveAssetStorageFromConfig = (config: Config | null | undefined): ResolvedAssetStorage =>
+  resolveAssetStorageSettings(config?.runtime?.registry?.assetStorage);

package/src/registry/asset-storage/types.ts

@@ -0,0 +1,46 @@
+/**
+ * Server-only asset storage contract for object-backed providers (Vercel Blob + custom
+ * {@link defineAssetStorage} modules), so callers need no provider-specific logic. The built-in
+ * `database` provider is the inline default: bytes live in the `asset_blobs.content` bytea column,
+ * read/written directly by the registry, so it needs no adapter. Object providers record a
+ * `storageRef` + provider id so reads resolve back through whichever provider stored the blob.
+ */
+
+/** Input for storing one content-addressed blob. */
+export interface AssetStorageInput {
+  /** SHA-256 of the bytes (hex), the content identity, usable as a stable object key. */
+  hash: string;
+  bytes: Buffer;
+  contentType: string;
+  size: number;
+}
+
+/**
+ * How a provider returns stored content: raw bytes, a readable stream, or a signed/redirect URL the
+ * client can fetch directly (used to avoid routing large payloads through the serverless function).
+ */
+export type AssetStorageReadResult =
+  | { kind: 'bytes'; bytes: Buffer; contentType?: string }
+  | { kind: 'stream'; stream: NodeJS.ReadableStream; contentType?: string }
+  | { kind: 'redirect'; url: string };
+
+/** The pluggable storage adapter contract for object-backed asset providers. */
+export interface AssetStorage {
+  /** Store one blob and return the reference to persist on its `asset_blobs` row. */
+  put(input: AssetStorageInput): Promise<{ storageRef: string }>;
+  /** Resolve stored content by its `storageRef`. */
+  get(storageRef: string): Promise<AssetStorageReadResult>;
+  /** Delete stored content by its `storageRef`. Should be retryable/idempotent. */
+  delete(storageRef: string): Promise<void>;
+}
+
+/** Context passed to a custom adapter factory: its non-secret config options + the process env. */
+export interface AssetStorageContext {
+  /** Non-secret options from `runtime.registry.assetStorage.options` (bucket env-var names, region, …). */
+  options: Record<string, unknown>;
+  /** The process environment. Read secret *values* here by the env-var *names* carried in options. */
+  env: NodeJS.ProcessEnv;
+}
+
+/** A custom adapter may export the adapter directly or a factory that builds it from its context. */
+export type AssetStorageFactory = (context: AssetStorageContext) => AssetStorage | Promise<AssetStorage>;

package/src/registry/assets/layout.ts

@@ -0,0 +1,38 @@
+/**
+ * Workspace physical layout for asset logical paths.
+ *
+ * A collection's logical paths are portable (no project id): icon/logo bodies + the collection JSON +
+ * the sprite live under `public/api`, the downloadable ZIP archives live at the generated output
+ * root, and font archives live under the workspace `fonts/` dir. Both the filesystem store (reading
+ * for publish) and checkout (writing restored files) resolve through this one mapping so they never
+ * drift.
+ */
+
+import { isSafeRelativePath, resolvePathWithin } from '../path';
+
+/** The absolute roots a logical asset path can resolve against. */
+export interface AssetPhysicalRoots {
+  /** `<workingPath>/public/api`: icon/logo bodies, collection JSON, sprite + manifest. */
+  apiPath: string;
+  /** Absolute path of `icons.zip` (`Handoff.getIconsZipFilePath()`). */
+  iconsZip: string;
+  /** Absolute path of `logos.zip` (`Handoff.getLogosZipFilePath()`). */
+  logosZip: string;
+  /** Workspace root, holding the `fonts/` dir. */
+  workingPath: string;
+}
+
+/** Resolve a collection-relative logical asset path to its absolute workspace location. */
+export const resolveAssetPhysicalPath = (logicalPath: string, roots: AssetPhysicalRoots): string => {
+  if (!isSafeRelativePath(logicalPath)) {
+    throw new Error(`Unsafe asset path "${logicalPath}".`);
+  }
+  if (logicalPath === 'icons.zip') return roots.iconsZip;
+  if (logicalPath === 'logos.zip') return roots.logosZip;
+  const root = logicalPath.startsWith('fonts/') ? roots.workingPath : roots.apiPath;
+  const resolved = resolvePathWithin(root, logicalPath);
+  if (!resolved) {
+    throw new Error(`Asset path "${logicalPath}" escapes its workspace root.`);
+  }
+  return resolved;
+};

package/src/registry/assets/sets.ts

@@ -0,0 +1,48 @@
+/**
+ * Logical asset-collection identity: the pure, dependency-light boundary shared by the store,
+ * publish, checkout, server ingestion, and the DB schema.
+ *
+ * Assets are organized into named **collections**. Unlike token sets (a single JSON slice), each
+ * collection is a set of individually addressed files (icons/logos SVGs, the icon sprite + manifest,
+ * downloadable ZIP archives, font archives). File discovery + the workspace physical layout live in
+ * the filesystem asset store; this module only owns the stable collection vocabulary and the
+ * content-type mapping, so it stays free of fs/DB/React dependencies.
+ */
+
+/** A named asset collection. */
+export type AssetCollection = 'icons' | 'logos' | 'fonts';
+
+/** The supported collections, in deterministic order. */
+export const ASSET_COLLECTIONS = ['icons', 'logos', 'fonts'] as const;
+
+/** Whether a string is a supported asset collection. */
+export const isAssetCollection = (value: string): value is AssetCollection =>
+  (ASSET_COLLECTIONS as readonly string[]).includes(value);
+
+/** File extension of a logical path, lower-cased and including the leading dot (`''` when none). */
+const extnameOf = (filePath: string): string => {
+  const base = filePath.replace(/\\/g, '/').split('/').pop() ?? '';
+  const dot = base.lastIndexOf('.');
+  return dot > 0 ? base.slice(dot).toLowerCase() : '';
+};
+
+/** Content type for an asset by extension. Binary-first (assets are SVG/PNG/ZIP/font/JSON). */
+const CONTENT_TYPE_BY_EXT: Record<string, string> = {
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.json': 'application/json; charset=utf-8',
+  '.zip': 'application/zip',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.otf': 'font/otf',
+  '.eot': 'application/vnd.ms-fontobject',
+};
+
+/** Resolve the content type to serve/transfer an asset with, keyed by its logical path extension. */
+export const assetContentType = (logicalPath: string): string =>
+  CONTENT_TYPE_BY_EXT[extnameOf(logicalPath)] ?? 'application/octet-stream';

package/src/registry/assets/transfer.ts

@@ -0,0 +1,50 @@
+/**
+ * Transfer payload contract for asset collections, shared by the connected-workspace publish/checkout
+ * client and the registry-side asset ingestion endpoints.
+ *
+ * Assets are their own transfer concern: a collection is a set of individually addressed binary files
+ * whose bytes travel as content-addressed **blobs** (uploaded/downloaded one at a time so a large
+ * collection never becomes one oversized request), while the collection **manifest** carries only
+ * metadata. Types only, no behavior.
+ */
+
+import type { AssetCollection } from './sets';
+import type { ArtifactBuildStatus } from '../../artifacts/types';
+import type { TransferBuild } from '../transfer';
+
+/** One asset's metadata in a collection manifest (never the binary body). */
+export interface AssetManifestEntry {
+  /** Registry-safe logical path within the collection. */
+  path: string;
+  /** Human-facing asset name. */
+  name: string;
+  contentType: string;
+  size: number;
+  /** SHA-256 of the bytes (hex), the blob identity this entry references. */
+  contentHash: string;
+  /** Free-form asset metadata carried from extraction. */
+  metadata?: Record<string, unknown> | null;
+}
+
+/**
+ * The collection publish package uploaded to `PUT /api/registry/transfer/assets/:collection` after
+ * its blobs have been uploaded: the full manifest and build metadata keyed by `sourceHash`.
+ */
+export interface AssetCollectionTransferPackage {
+  collection: AssetCollection;
+  build: TransferBuild;
+  assets: AssetManifestEntry[];
+}
+
+/** The checkout payload returned by `GET /api/registry/transfer/assets/:collection`. */
+export interface AssetCollectionCheckoutPayload {
+  collection: AssetCollection;
+  assets: AssetManifestEntry[];
+}
+
+/** A lightweight collection summary (`GET /api/registry/transfer/assets`) driving skip-unchanged / bulk checkout. */
+export interface AssetCollectionSummary {
+  collection: AssetCollection;
+  sourceHash: string | null;
+  status: ArtifactBuildStatus | null;
+}