handoff-app 1.2.2-7 → 2.0.0-0

package/dist/pipeline/styles.js

@@ -18,6 +18,7 @@ const handoff_core_1 = require("handoff-core");
 const lodash_1 = require("lodash");
 const path_1 = __importDefault(require("path"));
 const archive_1 = require("./archive");
+const token_transformers_1 = require("./token-transformers");
 /**
  * Build just the custom fonts — zips font directories and copies them to the export folder.
  */
@@ -49,39 +50,10 @@ exports.buildCustomFonts = buildCustomFonts;
  * Builds design token style files using core and user-configured transformers.
  */
 const buildStyles = (handoff, documentationObject) => __awaiter(void 0, void 0, void 0, function* () {
-    var _a, _b, _c, _d;
-    // Core transformers that should always be included
-    const coreTransformers = [
-        {
-            transformer: handoff_core_1.Transformers.ScssTransformer,
-            outDir: 'sass',
-            format: 'scss',
-        },
-        {
-            transformer: handoff_core_1.Transformers.ScssTypesTransformer,
-            outDir: 'types',
-            format: 'scss',
-        },
-        {
-            transformer: handoff_core_1.Transformers.CssTransformer,
-            outDir: 'css',
-            format: 'css',
-        },
-    ];
-    // Get user-configured transformers
-    const userTransformers = ((_b = (_a = handoff.config) === null || _a === void 0 ? void 0 : _a.pipeline) === null || _b === void 0 ? void 0 : _b.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 ? Object.assign(Object.assign({}, 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);
-        }
-    });
+    var _a, _b;
+    // 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 = (0, token_transformers_1.resolveTokenTransformers)(handoff);
     const baseDir = handoff.getVariablesFilePath();
     const runner = yield handoff.getRunner();
     // Create transformer instances and transform documentation object
@@ -100,7 +72,7 @@ const buildStyles = (handoff, documentationObject) => __awaiter(void 0, void 0,
     // Special case for SD tokens components directory
     const sdTransformer = transformers.find((t) => t.transformer === handoff_core_1.Transformers.StyleDictionaryTransformer);
     if (sdTransformer) {
-        const sdFiles = (_c = transformedFiles.find((t) => t.transformer === handoff_core_1.Transformers.StyleDictionaryTransformer)) === null || _c === void 0 ? void 0 : _c.files;
+        const sdFiles = (_a = transformedFiles.find((t) => t.transformer === handoff_core_1.Transformers.StyleDictionaryTransformer)) === null || _a === void 0 ? void 0 : _a.files;
         if (sdFiles === null || sdFiles === void 0 ? void 0 : sdFiles.components) {
             yield Promise.all(Object.keys(sdFiles.components).map((name) => fs_extra_1.default.ensureDir(path_1.default.join(baseDir, sdTransformer.outDir, name))));
         }
@@ -125,7 +97,7 @@ const buildStyles = (handoff, documentationObject) => __awaiter(void 0, void 0,
         return [...componentPromises, ...designPromises];
     });
     // Generate tokens-map.json
-    const mapFiles = (_d = transformedFiles.find((t) => t.transformer === handoff_core_1.Transformers.MapTransformer)) === null || _d === void 0 ? void 0 : _d.files;
+    const mapFiles = (_b = transformedFiles.find((t) => t.transformer === handoff_core_1.Transformers.MapTransformer)) === null || _b === void 0 ? void 0 : _b.files;
     if (mapFiles) {
         const tokensMapContent = JSON.stringify(Object.entries(mapFiles.components || {}).reduce((acc, [_, data]) => (Object.assign(Object.assign({}, acc), JSON.parse(data))), Object.assign(Object.assign(Object.assign({}, JSON.parse(mapFiles.design.colors)), JSON.parse(mapFiles.design.typography)), JSON.parse(mapFiles.design.effects))), null, 2);
         writePromises.push(fs_extra_1.default.writeFile(path_1.default.join(handoff.getOutputPath(), 'tokens-map.json'), tokensMapContent));

package/dist/pipeline/token-transformers.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 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;
+}
+/**
+ * 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 declare const resolveTokenTransformers: (context: TokenTransformerContext) => ResolvedTokenTransformer[];
+/** 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 declare const tokenArtifactPathsForSet: (transformers: ResolvedTokenTransformer[], setName: string, isComponent: boolean) => TokenArtifactLayout[];

package/dist/pipeline/token-transformers.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tokenArtifactPathsForSet = exports.resolveTokenTransformers = void 0;
+const handoff_core_1 = require("handoff-core");
+/** The three core transformers Handoff always runs, matching the historical `buildStyles` defaults. */
+const CORE_TRANSFORMERS = [
+    { transformer: handoff_core_1.Transformers.ScssTransformer, outDir: 'sass', format: 'scss', label: 'scss' },
+    { transformer: handoff_core_1.Transformers.ScssTypesTransformer, outDir: 'types', format: 'scss', label: 'types' },
+    { transformer: handoff_core_1.Transformers.CssTransformer, outDir: 'css', format: 'css', label: 'css' },
+];
+/** Logical label for a transformer factory: known core/SD labels, else the custom transformer's outDir. */
+const labelForTransformer = (transformer, outDir) => {
+    if (transformer === handoff_core_1.Transformers.ScssTransformer)
+        return 'scss';
+    if (transformer === handoff_core_1.Transformers.ScssTypesTransformer)
+        return 'types';
+    if (transformer === handoff_core_1.Transformers.CssTransformer)
+        return 'css';
+    if (transformer === handoff_core_1.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`.
+ */
+const resolveTokenTransformers = (context) => {
+    var _a, _b;
+    const userTransformers = ((_b = (_a = context.config) === null || _a === void 0 ? void 0 : _a.pipeline) === null || _b === void 0 ? void 0 : _b.transformers) || [];
+    const transformers = 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) }
+            : Object.assign({}, 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;
+};
+exports.resolveTokenTransformers = resolveTokenTransformers;
+/**
+ * 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>`.
+ */
+const tokenArtifactPathsForSet = (transformers, setName, isComponent) => 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 };
+});
+exports.tokenArtifactPathsForSet = tokenArtifactPathsForSet;

package/dist/registry/asset-storage/adapters/vercel-blob.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 declare const createVercelBlobStorage: (params: {
+    tokenEnv: string;
+    options: Record<string, unknown>;
+}) => AssetStorage;

package/dist/registry/asset-storage/adapters/vercel-blob.js

@@ -0,0 +1,87 @@
+"use strict";
+/**
+ * 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.
+ */
+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) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createVercelBlobStorage = void 0;
+/** Build a Vercel Blob storage adapter bound to a token env-var name + non-secret options. */
+const createVercelBlobStorage = (params) => {
+    const prefix = typeof params.options.prefix === 'string' && params.options.prefix.trim() ? params.options.prefix.trim() : 'handoff/assets';
+    const resolveToken = () => {
+        var _a;
+        const token = (_a = process.env[params.tokenEnv]) === null || _a === void 0 ? void 0 : _a.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 {
+        put(_a) {
+            return __awaiter(this, arguments, void 0, function* ({ hash, bytes, contentType }) {
+                const { put } = yield Promise.resolve().then(() => __importStar(require('@vercel/blob')));
+                // Content-addressed pathname + no random suffix so the same bytes map to a stable, dedupable key.
+                const result = yield put(`${prefix}/${hash}`, bytes, {
+                    access: 'public',
+                    token: resolveToken(),
+                    contentType,
+                    addRandomSuffix: false,
+                });
+                return { storageRef: result.url };
+            });
+        },
+        get(storageRef) {
+            return __awaiter(this, void 0, void 0, function* () {
+                // Public blob URLs are directly fetchable; redirect the client to avoid proxying bytes.
+                return { kind: 'redirect', url: storageRef };
+            });
+        },
+        delete(storageRef) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const { del } = yield Promise.resolve().then(() => __importStar(require('@vercel/blob')));
+                yield del(storageRef, { token: resolveToken() });
+            });
+        },
+    };
+};
+exports.createVercelBlobStorage = createVercelBlobStorage;

package/dist/registry/asset-storage/define.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 declare function defineAssetStorage(adapter: AssetStorage): AssetStorage;
+export declare function defineAssetStorage(factory: AssetStorageFactory): AssetStorageFactory;

package/dist/registry/asset-storage/define.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineAssetStorage = defineAssetStorage;
+function defineAssetStorage(input) {
+    return input;
+}

package/dist/registry/asset-storage/resolve.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 declare const DEFAULT_ASSET_STORAGE_ADAPTER: AssetStorageAdapterKind;
+/** Default env-var name holding the Vercel Blob read/write token. */
+export declare 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 declare const DEFAULT_MAX_INLINE_BYTES: number;
+/** 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>;
+}
+/** Resolve raw asset storage settings into a fully-defaulted shape. */
+export declare const resolveAssetStorageSettings: (settings: AssetStorageSettings | null | undefined) => ResolvedAssetStorage;
+/** Resolve the active asset storage settings from a loaded config (CLI/build side). */
+export declare const resolveAssetStorageFromConfig: (config: Config | null | undefined) => ResolvedAssetStorage;

package/dist/registry/asset-storage/resolve.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveAssetStorageFromConfig = exports.resolveAssetStorageSettings = exports.DEFAULT_MAX_INLINE_BYTES = exports.DEFAULT_BLOB_TOKEN_ENV = exports.DEFAULT_ASSET_STORAGE_ADAPTER = void 0;
+/** Default adapter when none is configured. */
+exports.DEFAULT_ASSET_STORAGE_ADAPTER = 'database';
+/** Default env-var name holding the Vercel Blob read/write token. */
+exports.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). */
+exports.DEFAULT_MAX_INLINE_BYTES = 4 * 1024 * 1024;
+/** The stable provider id recorded on blobs for a custom adapter (single custom provider at a time). */
+const customProviderId = (options) => {
+    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. */
+const resolveAssetStorageSettings = (settings) => {
+    var _a, _b, _c, _d;
+    const adapterKind = (_a = settings === null || settings === void 0 ? void 0 : settings.adapter) !== null && _a !== void 0 ? _a : exports.DEFAULT_ASSET_STORAGE_ADAPTER;
+    const options = (_b = settings === null || settings === void 0 ? void 0 : settings.options) !== null && _b !== void 0 ? _b : {};
+    const tokenEnv = ((_c = settings === null || settings === void 0 ? void 0 : settings.tokenEnv) === null || _c === void 0 ? void 0 : _c.trim()) || exports.DEFAULT_BLOB_TOKEN_ENV;
+    const maxInlineBytes = typeof (settings === null || settings === void 0 ? void 0 : settings.maxInlineBytes) === 'number' && settings.maxInlineBytes > 0 ? settings.maxInlineBytes : exports.DEFAULT_MAX_INLINE_BYTES;
+    const provider = adapterKind === 'vercel-blob' ? 'vercel-blob' : adapterKind === 'custom' ? customProviderId(options) : 'database';
+    return { adapterKind, provider, module: ((_d = settings === null || settings === void 0 ? void 0 : settings.module) === null || _d === void 0 ? void 0 : _d.trim()) || undefined, tokenEnv, maxInlineBytes, options };
+};
+exports.resolveAssetStorageSettings = resolveAssetStorageSettings;
+/** Resolve the active asset storage settings from a loaded config (CLI/build side). */
+const resolveAssetStorageFromConfig = (config) => { var _a, _b; return (0, exports.resolveAssetStorageSettings)((_b = (_a = config === null || config === void 0 ? void 0 : config.runtime) === null || _a === void 0 ? void 0 : _a.registry) === null || _b === void 0 ? void 0 : _b.assetStorage); };
+exports.resolveAssetStorageFromConfig = resolveAssetStorageFromConfig;

package/dist/registry/asset-storage/types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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/dist/registry/asset-storage/types.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/registry/assets/layout.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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.
+ */
+/** 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 declare const resolveAssetPhysicalPath: (logicalPath: string, roots: AssetPhysicalRoots) => string;

package/dist/registry/assets/layout.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveAssetPhysicalPath = void 0;
+const path_1 = require("../path");
+/** Resolve a collection-relative logical asset path to its absolute workspace location. */
+const resolveAssetPhysicalPath = (logicalPath, roots) => {
+    if (!(0, path_1.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 = (0, path_1.resolvePathWithin)(root, logicalPath);
+    if (!resolved) {
+        throw new Error(`Asset path "${logicalPath}" escapes its workspace root.`);
+    }
+    return resolved;
+};
+exports.resolveAssetPhysicalPath = resolveAssetPhysicalPath;

package/dist/registry/assets/sets.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 declare const ASSET_COLLECTIONS: readonly ["icons", "logos", "fonts"];
+/** Whether a string is a supported asset collection. */
+export declare const isAssetCollection: (value: string) => value is AssetCollection;
+/** Resolve the content type to serve/transfer an asset with, keyed by its logical path extension. */
+export declare const assetContentType: (logicalPath: string) => string;

package/dist/registry/assets/sets.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assetContentType = exports.isAssetCollection = exports.ASSET_COLLECTIONS = void 0;
+/** The supported collections, in deterministic order. */
+exports.ASSET_COLLECTIONS = ['icons', 'logos', 'fonts'];
+/** Whether a string is a supported asset collection. */
+const isAssetCollection = (value) => exports.ASSET_COLLECTIONS.includes(value);
+exports.isAssetCollection = isAssetCollection;
+/** File extension of a logical path, lower-cased and including the leading dot (`''` when none). */
+const extnameOf = (filePath) => {
+    var _a;
+    const base = (_a = filePath.replace(/\\/g, '/').split('/').pop()) !== null && _a !== void 0 ? _a : '';
+    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 = {
+    '.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. */
+const assetContentType = (logicalPath) => { var _a; return (_a = CONTENT_TYPE_BY_EXT[extnameOf(logicalPath)]) !== null && _a !== void 0 ? _a : 'application/octet-stream'; };
+exports.assetContentType = assetContentType;

package/dist/registry/assets/transfer.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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;
+}

package/dist/registry/assets/transfer.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });