handoff-app 1.2.2-7 → 2.0.0-0

package/dist/store/types.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Normalized store abstraction.
+ *
+ * Both the workspace (filesystem) store and the future registry (database) store implement one
+ * read contract, so the docs read API and other consumers are storage-agnostic.
+ * Read methods are typed `Awaitable` so the filesystem implementation can stay synchronous
+ * while a database implementation is async behind the same interface.
+ *
+ * This module is types-only and provider-agnostic.
+ */
+import type { TokenSetKind } from '../registry/tokens/sets';
+import type { ComponentListObject, PageListObject, PatternListObject } from '../transformers/preview/types';
+/** A value that may be returned directly or as a promise. */
+export type Awaitable<T> = T | Promise<T>;
+/**
+ * Kind of a text source file tracked by the store. Mirrors the registry text-file model.
+ * `declaration` is **workspace-only** — registry stores never return it
+ * and declarations are synthesized on checkout.
+ */
+export type TextFileKind = 'declaration' | 'component' | 'template' | 'style' | 'script' | 'story' | 'docs' | 'markdown' | 'schema' | 'other';
+export type RegistryTextFileKind = Exclude<TextFileKind, 'declaration'>;
+/**
+ * A normalized text source file belonging to a component or pattern. Used for checkout,
+ * inspection, and publish — never to rebuild previews during docs serving.
+ */
+export interface TextFileResource {
+    /** Registry-safe relative path of the file within the entity (e.g. `Badge.tsx`). */
+    path: string;
+    /** Absolute filesystem path the content was read from (workspace store only). */
+    absolutePath: string;
+    /** Classified file kind. */
+    kind: TextFileKind;
+    /** File content. */
+    content: string;
+    /** Content type to serve/transfer the file with. */
+    contentType: string;
+}
+export type RegistryTextFileResource = TextFileResource & {
+    kind: RegistryTextFileKind;
+};
+/**
+ * A reference to a source file resolvable by a store. For the filesystem store this is an
+ * absolute path; the contract keeps it opaque so a database store can use its own reference form.
+ */
+export interface SourceReference {
+    /** Absolute filesystem path (workspace store). */
+    absolutePath: string;
+}
+/**
+ * Read contract implemented by every component store backing. Consumers depend only on this so
+ * they never need to know whether the filesystem or a database is active.
+ */
+export interface ComponentStore {
+    /** All normalized component records, identical in shape to today's runtime records. */
+    list(): Awaitable<ComponentListObject[]>;
+    /** A single normalized component record by stable id, or `null` when absent. */
+    get(id: string): Awaitable<ComponentListObject | null>;
+    /** Read a source file by reference, or `null` when it cannot be resolved. */
+    getSource(ref: SourceReference): Awaitable<TextFileResource | null>;
+    /**
+     * The entity's declaration plus every `entries`-referenced source file, for checkout/publish.
+     * Returns an empty array when the entity is unknown.
+     */
+    getRelatedSourceFiles(id: string): Awaitable<TextFileResource[]>;
+}
+/**
+ * Read contract implemented by every pattern store backing. Same shape as {@link ComponentStore}
+ * over pattern records.
+ */
+export interface PatternStore {
+    /** All normalized pattern records, identical in shape to today's runtime records. */
+    list(): Awaitable<PatternListObject[]>;
+    /** A single normalized pattern record by stable id, or `null` when absent. */
+    get(id: string): Awaitable<PatternListObject | null>;
+    /** Read a source file by reference, or `null` when it cannot be resolved. */
+    getSource(ref: SourceReference): Awaitable<TextFileResource | null>;
+    /**
+     * The pattern's declaration plus every `entries`-referenced source file, for checkout/publish.
+     * Returns an empty array when the pattern is unknown.
+     */
+    getRelatedSourceFiles(id: string): Awaitable<TextFileResource[]>;
+}
+/**
+ * Read contract implemented by every page store backing. Same shape as {@link PatternStore} over
+ * page records. A page's single related source file is its verbatim `.md` (kind `markdown`).
+ */
+export interface PageStore {
+    /** All normalized page records. */
+    list(): Awaitable<PageListObject[]>;
+    /** A single normalized page record by stable id, or `null` when absent. */
+    get(id: string): Awaitable<PageListObject | null>;
+    /** Read a source file by reference, or `null` when it cannot be resolved. */
+    getSource(ref: SourceReference): Awaitable<TextFileResource | null>;
+    /** The page's verbatim `.md` source file, for checkout/publish. Empty when the page is unknown. */
+    getRelatedSourceFiles(id: string): Awaitable<TextFileResource[]>;
+}
+/**
+ * A logical token set as the store exposes it: its stable id, kind, and the exact extracted token
+ * slice (a `record` of `IColorObject[]`/…/`IFileComponentObject`). Consumers read the whole set and
+ * group/sort/look up in memory, so there is no individual-token accessor.
+ */
+export interface TokenSetRecord {
+    id: string;
+    kind: TokenSetKind;
+    record: unknown;
+}
+/** A generated token artifact (CSS/SCSS/Style Dictionary/types/custom output) as the store returns it. */
+export interface TokenArtifactResource {
+    /** Registry-safe relative output path under the tokens dir (e.g. `css/colors.css`). */
+    path: string;
+    /** Logical format label (`css`|`scss`|`types`|`styleDictionary`|custom). */
+    format: string;
+    content: string;
+    contentType: string;
+}
+/**
+ * Read contract implemented by every token store backing. The filesystem backing derives sets from
+ * the local `tokens.json` + generated files; the registry backing reads the `token_sets` /
+ * `token_artifacts` tables. Consumers depend only on this so token behavior is consistent across
+ * modes even though the storage differs.
+ */
+export interface TokenStore {
+    /** All logical token sets (three foundation sets + one per component). */
+    listSets(): Awaitable<TokenSetRecord[]>;
+    /** A single set by stable id, or `null` when absent. */
+    getSet(id: string): Awaitable<TokenSetRecord | null>;
+    /** Every generated artifact owned by a set. Empty when the set is unknown or has no output. */
+    getArtifacts(id: string): Awaitable<TokenArtifactResource[]>;
+    /** One generated artifact for a set by logical format, or `null` when absent. */
+    getArtifact(id: string, format: string): Awaitable<TokenArtifactResource | null>;
+}
+/**
+ * Lightweight metadata for one published asset. Collection/list reads return only this shape - never
+ * the binary body - so large collections do not produce oversized responses.
+ */
+export interface AssetMetadata {
+    /** Collection the asset belongs to (`icons`|`logos`|`fonts`). */
+    collection: string;
+    /** Registry-safe logical path within the collection (e.g. `assets/icons/add.svg`, `icons.zip`). */
+    path: string;
+    /** Human-facing asset name. */
+    name: string;
+    /** Content type to serve the asset with. */
+    contentType: string;
+    /** Byte length. */
+    size: number;
+    /** SHA-256 of the bytes (hex) - content identity + ETag. */
+    contentHash: string;
+    /** Free-form asset metadata carried from extraction (icon index, description, …). */
+    metadata?: Record<string, unknown> | null;
+}
+/**
+ * An asset's resolved content: inline bytes (filesystem store, or a DB-backed blob), or a redirect
+ * URL when an object-storage provider serves the content directly.
+ */
+export interface AssetContentResource extends AssetMetadata {
+    /** Inline bytes, when the content is served from the filesystem or an inline DB blob. */
+    body?: Buffer;
+    /** Signed/public provider URL to redirect to, when an object-storage provider serves the content. */
+    redirectUrl?: string;
+}
+/**
+ * Read contract implemented by every asset store backing. The filesystem backing derives collections
+ * from the generated `public/api` tree + archives; the registry backing reads the `assets` /
+ * `asset_collections` tables and resolves content through the configured storage provider. List
+ * methods return metadata only; content is fetched one asset at a time.
+ */
+export interface AssetStore {
+    /** All collections that have any published assets. */
+    listCollections(): Awaitable<string[]>;
+    /** Lightweight metadata for every asset in a collection (no bodies). Empty when unknown. */
+    listAssets(collection: string): Awaitable<AssetMetadata[]>;
+    /** Metadata for one asset by collection + logical path, or `null` when absent. */
+    getAsset(collection: string, path: string): Awaitable<AssetMetadata | null>;
+    /** One asset's resolved content (bytes or redirect), or `null` when absent. */
+    getAssetContent(collection: string, path: string): Awaitable<AssetContentResource | null>;
+}
+/** Convenience pairing of the stores backing one runtime. */
+export interface HandoffStore {
+    components: ComponentStore;
+    patterns: PatternStore;
+    pages: PageStore;
+    tokens: TokenStore;
+    assets: AssetStore;
+}

package/dist/store/types.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * Normalized store abstraction.
+ *
+ * Both the workspace (filesystem) store and the future registry (database) store implement one
+ * read contract, so the docs read API and other consumers are storage-agnostic.
+ * Read methods are typed `Awaitable` so the filesystem implementation can stay synchronous
+ * while a database implementation is async behind the same interface.
+ *
+ * This module is types-only and provider-agnostic.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/transformers/plugins/csf-render.js

@@ -22,7 +22,7 @@ const react_element_to_jsx_string_1 = __importDefault(require("react-element-to-
 const logger_1 = require("../../utils/logger");
 const docgen_1 = require("../docgen");
 const component_1 = require("../preview/component");
-const css_1 = require("../preview/component/css");
+const shared_artifacts_1 = require("../preview/component/shared-artifacts");
 const html_1 = require("../utils/html");
 const module_1 = require("../utils/module");
 const schema_1 = require("../utils/schema");
@@ -235,15 +235,20 @@ function buildUsageSnippet(componentName, importStatement, element, properties,
         importStatement,
     });
 }
-function createHtmlDocument(componentId, previewTitle, renderedHtml) {
-    var _a, _b, _c;
+function createHtmlDocument(componentId, previewTitle, renderedHtml, sharedArtifacts, componentArtifacts) {
+    var _a;
+    const basePath = (_a = process.env.HANDOFF_APP_BASE_PATH) !== null && _a !== void 0 ? _a : '';
+    // Shared/global and component-owned artifacts are referenced only when present, so a CSF preview
+    // never requests an absent optional artifact. CSF previews stay static; the global script runs
+    // only for its top-level side effects when a global JS entry exists.
+    const sharedStyleLinks = (0, shared_artifacts_1.renderSharedStyleLinks)(sharedArtifacts, basePath);
+    const componentStyleLink = (0, shared_artifacts_1.renderComponentStyleLink)(componentArtifacts, componentId, basePath);
+    const globalScriptTag = (0, shared_artifacts_1.renderGlobalScriptTag)(sharedArtifacts, basePath);
     return `<!DOCTYPE html>
 <html lang="en">
   <head>
-    <meta charset="UTF-8" />
-    <link rel="stylesheet" href="${(_a = process.env.HANDOFF_APP_BASE_PATH) !== null && _a !== void 0 ? _a : ''}/api/component/${css_1.MAIN_COMPONENT_CSS_FILE}" />
-    <link rel="stylesheet" href="${(_b = process.env.HANDOFF_APP_BASE_PATH) !== null && _b !== void 0 ? _b : ''}/api/component/${componentId}.css" />
-    <link rel="stylesheet" href="${(_c = process.env.HANDOFF_APP_BASE_PATH) !== null && _c !== void 0 ? _c : ''}/assets/css/preview.css" />
+    <meta charset="UTF-8" />${sharedStyleLinks ? `\n    ${sharedStyleLinks}` : ''}${componentStyleLink ? `\n    ${componentStyleLink}` : ''}
+    <link rel="stylesheet" href="${basePath}/assets/css/preview.css" />${globalScriptTag ? `\n    ${globalScriptTag}` : ''}
     <title>${previewTitle}</title>
   </head>
   <body>
@@ -359,6 +364,10 @@ function csfRenderPlugin(componentData, _documentationComponents, handoff) {
                     };
                 }
                 componentData.properties = (0, schema_1.ensureIds)(generatedProperties);
+                // Resolve which shared/global and component-owned artifacts exist so generated HTML references
+                // them only when present. These are built before component HTML, so this reflects final state.
+                const sharedArtifacts = (0, shared_artifacts_1.resolveSharedArtifactPresence)(handoff);
+                const componentArtifacts = (0, shared_artifacts_1.resolveComponentArtifactPresence)(handoff, componentId);
                 let lastHtml = '';
                 for (const [previewKey, preview] of Object.entries(componentData.previews)) {
                     const storyKey = preview.sourcePreview && storyMap[preview.sourcePreview]
@@ -367,7 +376,7 @@ function csfRenderPlugin(componentData, _documentationComponents, handoff) {
                     const storyValue = storyKey ? storyMap[storyKey] : undefined;
                     const storyArgs = preview.values || {};
                     const rendered = safeRenderToHtml(meta, storyValue, storyArgs);
-                    const html = yield (0, html_1.formatHtml)(createHtmlDocument(componentId, preview.title, rendered));
+                    const html = yield (0, html_1.formatHtml)(createHtmlDocument(componentId, preview.title, rendered, sharedArtifacts, componentArtifacts));
                     const fileName = `${componentId}-${previewKey}.html`;
                     this.emitFile({
                         type: 'asset',

package/dist/transformers/plugins/handlebars-previews.js

@@ -17,6 +17,7 @@ const fs_extra_1 = __importDefault(require("fs-extra"));
 const handlebars_1 = __importDefault(require("handlebars"));
 const path_1 = __importDefault(require("path"));
 const logger_1 = require("../../utils/logger");
+const shared_artifacts_1 = require("../preview/component/shared-artifacts");
 const handlebars_2 = require("../utils/handlebars");
 const html_1 = require("../utils/html");
 const string_1 = require("../utils/string");
@@ -61,7 +62,7 @@ function processComponentInstances(componentData, documentationComponents) {
  * @param injectFieldWrappers - Whether to inject field wrappers for inspection
  * @returns Rendered HTML string
  */
-function renderHandlebarsTemplate(template, componentData, previewData, injectFieldWrappers, handoff) {
+function renderHandlebarsTemplate(template, componentData, previewData, injectFieldWrappers, handoff, sharedArtifacts, componentArtifacts) {
     return __awaiter(this, void 0, void 0, function* () {
         var _a, _b;
         // Register Handlebars helpers with current injection state
@@ -72,6 +73,8 @@ function renderHandlebarsTemplate(template, componentData, previewData, injectFi
             title: componentData.title
         }, previewData, {
             includeSharedStyles: Boolean(componentData.sharedStyles),
+            sharedArtifacts,
+            componentArtifacts,
         });
         const compiled = handlebars_1.default.compile(template)(context);
         return yield (0, html_1.formatHtmlWithWrapper)(compiled);
@@ -143,13 +146,17 @@ function handlebarsPreviewsPlugin(componentData, documentationComponents, handof
                     };
                 }
                 const generatedPreviews = {};
+                // Resolve which shared/global and component-owned artifacts exist so generated HTML references
+                // them only when present. These are built before component HTML, so this reflects final state.
+                const sharedArtifacts = (0, shared_artifacts_1.resolveSharedArtifactPresence)(handoff);
+                const componentArtifacts = (0, shared_artifacts_1.resolveComponentArtifactPresence)(handoff, componentId);
                 // Generate previews for each variation
                 for (const previewKey in componentData.previews) {
                     try {
                         const previewData = componentData.previews[previewKey];
                         // Render both normal and inspect modes
-                        const normalModeHtml = yield renderHandlebarsTemplate(templateContent, componentData, previewData, false, handoff);
-                        const inspectModeHtml = yield renderHandlebarsTemplate(templateContent, componentData, previewData, true, handoff);
+                        const normalModeHtml = yield renderHandlebarsTemplate(templateContent, componentData, previewData, false, handoff, sharedArtifacts, componentArtifacts);
+                        const inspectModeHtml = yield renderHandlebarsTemplate(templateContent, componentData, previewData, true, handoff, sharedArtifacts, componentArtifacts);
                         // Emit preview files
                         emitPreviewFiles(componentId, previewKey, normalModeHtml, inspectModeHtml, (file) => this.emitFile(file));
                         generatedPreviews[previewKey] = normalModeHtml;

package/dist/transformers/plugins/ssr-render.js

@@ -19,9 +19,10 @@ const path_1 = __importDefault(require("path"));
 const react_1 = __importDefault(require("react"));
 const server_1 = __importDefault(require("react-dom/server"));
 const vite_1 = require("vite");
+const url_1 = require("../../artifacts/url");
 const logger_1 = require("../../utils/logger");
 const docgen_1 = require("../docgen");
-const css_1 = require("../preview/component/css");
+const shared_artifacts_1 = require("../preview/component/shared-artifacts");
 const build_1 = require("../utils/build");
 const html_1 = require("../utils/html");
 const module_1 = require("../utils/module");
@@ -40,6 +41,14 @@ const PLUGIN_CONSTANTS = {
     PROPS_SCRIPT_ID: '__APP_PROPS__',
     INSPECT_SUFFIX: '-inspect',
 };
+/**
+ * Suffix of the component-owned client/hydration artifact.
+ * One artifact per component (`component/<id>.client.js`) drives hydration for every preview of
+ * that component; it is referenced via the canonical artifact URL.
+ */
+const CLIENT_ARTIFACT_SUFFIX = 'client.js';
+/** Logical artifact path of a component's client/hydration bundle. */
+const clientArtifactPath = (componentId) => `component/${componentId}.${CLIENT_ARTIFACT_SUFFIX}`;
 /**
  * Loads and processes component schema using hierarchical approach
  * @param componentData - Component transformation data
@@ -88,43 +97,90 @@ function loadComponentSchemaAndModule(componentData, componentPath, handoff) {
     });
 }
 /**
- * Generates client-side hydration source code
+ * Generates client-side hydration source code for the component-owned client artifact.
+ *
+ * The bundle is shared by every preview of a component and is emitted once as
+ * `component/<id>.client.js`. It hydrates two shapes of mount point so the same artifact serves both
+ * a standalone preview document and a composed pattern document without per-fragment inline code:
+ *
+ *  - The standalone preview's `#${ROOT_ELEMENT_ID}` element paired with the `#${PROPS_SCRIPT_ID}`
+ *    props script (one mount per document).
+ *  - Any number of pattern mount points marked `[data-handoff-component="<id>"]`, each carrying a
+ *    `data-handoff-props` attribute naming its (namespaced) props script id. A pattern document
+ *    references this artifact once per component and the bundle hydrates every matching mount.
+ *
+ * @param componentId - Component identifier used to match pattern mount points to this bundle
  * @param componentPath - Path to the component file
  * @returns Client-side hydration source code
  */
-function generateClientHydrationSource(componentPath) {
+function generateClientHydrationSource(componentId, componentPath) {
     return `
     import React from 'react';
     import { hydrateRoot } from 'react-dom/client';
     import Component from '${(0, vite_1.normalizePath)(componentPath)}';
 
-    const raw = document.getElementById('${PLUGIN_CONSTANTS.PROPS_SCRIPT_ID}')?.textContent || '{}';
-    const props = JSON.parse(raw);
-    hydrateRoot(document.getElementById('${PLUGIN_CONSTANTS.ROOT_ELEMENT_ID}'), <Component {...props} />);
+    const parseProps = (propsId) => {
+      const raw = propsId ? document.getElementById(propsId)?.textContent : '{}';
+      try {
+        return JSON.parse(raw || '{}');
+      } catch (_) {
+        return {};
+      }
+    };
+
+    const standaloneRoot = document.getElementById('${PLUGIN_CONSTANTS.ROOT_ELEMENT_ID}');
+    if (standaloneRoot && !standaloneRoot.hasAttribute('data-handoff-component')) {
+      hydrateRoot(standaloneRoot, <Component {...parseProps('${PLUGIN_CONSTANTS.PROPS_SCRIPT_ID}')} />);
+    }
+
+    const patternMounts = document.querySelectorAll('[data-handoff-component=' + JSON.stringify('${componentId}') + ']');
+    patternMounts.forEach((mount) => {
+      hydrateRoot(mount, <Component {...parseProps(mount.getAttribute('data-handoff-props'))} />);
+    });
   `;
 }
 /**
- * Generates complete HTML document with SSR content and hydration
+ * Generates complete HTML document with SSR content and a reference to the component-owned client
+ * artifact. The preview HTML carries only document structure, server-rendered markup, preview data,
+ * stylesheets, and standard artifact references. Interactive React previews treat the client
+ * artifact as a required reference, so the script tag surfaces a clear, visible failure if the
+ * artifact cannot be loaded.
  * @param componentId - Component identifier
  * @param previewTitle - Title for the preview
  * @param renderedHtml - Server-rendered HTML content
- * @param clientJs - Client-side JavaScript bundle
  * @param props - Component props as JSON
  * @returns Complete HTML document
  */
-function generateHtmlDocument(componentId, previewTitle, renderedHtml, clientJs, props) {
-    var _a, _b, _c;
+function generateHtmlDocument(componentId, previewTitle, renderedHtml, props, sharedArtifacts, componentArtifacts) {
+    var _a;
+    const basePath = (_a = process.env.HANDOFF_APP_BASE_PATH) !== null && _a !== void 0 ? _a : '';
+    const clientArtifactUrl = (0, url_1.buildArtifactUrl)(clientArtifactPath(componentId), basePath);
+    const clientLoadErrorMessage = `Failed to load the React client artifact (${clientArtifactPath(componentId)}). This preview cannot hydrate.`;
+    // The handler is JS embedded in a double-quoted HTML attribute, so any `"` (e.g. from
+    // JSON.stringify) and `&` must be entity-encoded or the attribute terminates early and
+    // breaks HTML parsing. Browsers decode the entities before the JS engine runs the handler.
+    const clientLoadErrorHandler = `document.getElementById('${PLUGIN_CONSTANTS.ROOT_ELEMENT_ID}').setAttribute('data-handoff-client-error', '1');console.error(${JSON.stringify(clientLoadErrorMessage)});`
+        .replace(/&/g, '&amp;')
+        .replace(/"/g, '&quot;');
+    // Shared/global stylesheets (`component/main.css`) and the component's own stylesheet
+    // (`component/<id>.css`) are emitted only when present so absent optional artifacts never produce a
+    // missing-file browser request.
+    const sharedStyleLinks = (0, shared_artifacts_1.renderSharedStyleLinks)(sharedArtifacts, basePath);
+    const componentStyleLink = (0, shared_artifacts_1.renderComponentStyleLink)(componentArtifacts, componentId, basePath);
+    // The global script (`component/main.js`) is a classic tag placed before the client module so it
+    // runs before dependent component-specific scripts when present.
+    const globalScriptTag = (0, shared_artifacts_1.renderGlobalScriptTag)(sharedArtifacts, basePath);
     return `<!DOCTYPE html>
 <html lang="en">
   <head>
-    <meta charset="UTF-8" />
-    <link rel="stylesheet" href="${(_a = process.env.HANDOFF_APP_BASE_PATH) !== null && _a !== void 0 ? _a : ''}/api/component/${css_1.MAIN_COMPONENT_CSS_FILE}" />
-    <link rel="stylesheet" href="${(_b = process.env.HANDOFF_APP_BASE_PATH) !== null && _b !== void 0 ? _b : ''}/api/component/${componentId}.css" />
-    <link rel="stylesheet" href="${(_c = process.env.HANDOFF_APP_BASE_PATH) !== null && _c !== void 0 ? _c : ''}/assets/css/preview.css" />
-    <script id="${PLUGIN_CONSTANTS.PROPS_SCRIPT_ID}" type="application/json">${JSON.stringify(props)}</script>
-    <script type="module">
-      ${clientJs}
-    </script>
+    <meta charset="UTF-8" />${sharedStyleLinks ? `\n    ${sharedStyleLinks}` : ''}${componentStyleLink ? `\n    ${componentStyleLink}` : ''}
+    <link rel="stylesheet" href="${basePath}/assets/css/preview.css" />
+    <script id="${PLUGIN_CONSTANTS.PROPS_SCRIPT_ID}" type="application/json">${JSON.stringify(props)}</script>${globalScriptTag ? `\n    ${globalScriptTag}` : ''}
+    <script
+      type="module"
+      src="${clientArtifactUrl}"
+      onerror="${clientLoadErrorHandler}"
+    ></script>
     <title>${previewTitle}</title>
   </head>
   <body>
@@ -206,44 +262,55 @@ function ssrRenderPlugin(componentData, documentationComponents, handoff) {
                         }
                     }
                 }
+                // Build the component-owned client/hydration bundle once and emit it as a single
+                // `component/<id>.client.js` artifact. The hydration source only imports the component and
+                // reads props from the in-document `__APP_PROPS__` element, so it is identical across every
+                // preview of this component.
+                const clientHydrationSource = generateClientHydrationSource(componentId, componentPath);
+                const clientBuildConfig = Object.assign(Object.assign({}, build_1.DEFAULT_CLIENT_BUILD_CONFIG), { logLevel: 'silent', stdin: {
+                        contents: clientHydrationSource,
+                        resolveDir: process.cwd(),
+                        loader: 'tsx',
+                    }, plugins: [(0, build_1.createReactResolvePlugin)(handoff.workingPath, handoff.modulePath)] });
+                const finalClientBuildConfig = ((_b = (_a = handoff.config) === null || _a === void 0 ? void 0 : _a.hooks) === null || _b === void 0 ? void 0 : _b.clientBuildConfig)
+                    ? handoff.config.hooks.clientBuildConfig(clientBuildConfig)
+                    : clientBuildConfig;
+                let clientBundleJs;
+                try {
+                    const bundledClient = yield esbuild_1.default.build(finalClientBuildConfig);
+                    if (bundledClient.warnings.length > 0) {
+                        const messages = yield esbuild_1.default.formatMessages(bundledClient.warnings, { kind: 'warning', color: true });
+                        messages.forEach((msg) => logger_1.Logger.warn(msg));
+                    }
+                    clientBundleJs = bundledClient.outputFiles[0].text;
+                }
+                catch (error) {
+                    // The client artifact is a required reference for interactive React previews. If it cannot be
+                    // built, do not emit preview HTML that points at a missing artifact — fail clearly instead.
+                    logger_1.Logger.error(`Failed to build client bundle for ${componentId}`);
+                    if (error.errors) {
+                        const messages = yield esbuild_1.default.formatMessages(error.errors, { kind: 'error', color: true });
+                        messages.forEach((msg) => logger_1.Logger.error(msg));
+                    }
+                    return;
+                }
+                this.emitFile({
+                    type: 'asset',
+                    fileName: `${componentId}.${CLIENT_ARTIFACT_SUFFIX}`,
+                    source: clientBundleJs,
+                });
                 let finalHtml = '';
+                // Resolve which shared/global and component-owned artifacts exist so generated HTML references
+                // them only when present. These are built before component HTML, so this reflects final state.
+                const sharedArtifacts = (0, shared_artifacts_1.resolveSharedArtifactPresence)(handoff);
+                const componentArtifacts = (0, shared_artifacts_1.resolveComponentArtifactPresence)(handoff, componentId);
                 // Generate previews for each variation
                 for (const previewKey in componentData.previews) {
                     const previewProps = componentData.previews[previewKey].values;
                     // Server-side render the component
                     const serverRenderedHtml = server_1.default.renderToString(react_1.default.createElement(ReactComponent, previewProps));
                     const formattedHtml = yield (0, html_1.formatHtml)(serverRenderedHtml);
-                    // Generate client-side hydration code
-                    const clientHydrationSource = generateClientHydrationSource(componentPath);
-                    // Build client-side bundle
-                    const clientBuildConfig = Object.assign(Object.assign({}, build_1.DEFAULT_CLIENT_BUILD_CONFIG), { logLevel: 'silent', stdin: {
-                            contents: clientHydrationSource,
-                            resolveDir: process.cwd(),
-                            loader: 'tsx',
-                        }, plugins: [(0, build_1.createReactResolvePlugin)(handoff.workingPath, handoff.modulePath)] });
-                    // Apply user's client build config hook if provided
-                    const finalClientBuildConfig = ((_b = (_a = handoff.config) === null || _a === void 0 ? void 0 : _a.hooks) === null || _b === void 0 ? void 0 : _b.clientBuildConfig)
-                        ? handoff.config.hooks.clientBuildConfig(clientBuildConfig)
-                        : clientBuildConfig;
-                    let clientBundleJs;
-                    try {
-                        const bundledClient = yield esbuild_1.default.build(finalClientBuildConfig);
-                        if (bundledClient.warnings.length > 0) {
-                            const messages = yield esbuild_1.default.formatMessages(bundledClient.warnings, { kind: 'warning', color: true });
-                            messages.forEach((msg) => logger_1.Logger.warn(msg));
-                        }
-                        clientBundleJs = bundledClient.outputFiles[0].text;
-                    }
-                    catch (error) {
-                        logger_1.Logger.error(`Failed to build client bundle for ${componentId}`);
-                        if (error.errors) {
-                            const messages = yield esbuild_1.default.formatMessages(error.errors, { kind: 'error', color: true });
-                            messages.forEach((msg) => logger_1.Logger.error(msg));
-                        }
-                        continue;
-                    }
-                    // Generate complete HTML document
-                    finalHtml = generateHtmlDocument(componentId, componentData.previews[previewKey].title, formattedHtml, clientBundleJs, previewProps);
+                    finalHtml = generateHtmlDocument(componentId, componentData.previews[previewKey].title, formattedHtml, previewProps, sharedArtifacts, componentArtifacts);
                     // Emit preview files
                     this.emitFile({
                         type: 'asset',

package/dist/transformers/preview/component/api.js

@@ -15,6 +15,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.readComponentMetadataApi = exports.readComponentApi = exports.writeComponentApi = exports.getAPIPath = exports.sanitizeComponentApiData = void 0;
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
+const url_1 = require("../../../artifacts/url");
 const previews_1 = require("./previews");
 const sanitizeComponentApiData = (component) => {
     if (!component)
@@ -119,6 +120,7 @@ exports.readComponentApi = readComponentApi;
  * @returns The component summary or null if not found
  */
 const readComponentMetadataApi = (handoff, id) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
     const componentData = yield (0, exports.readComponentApi)(handoff, id);
     if (!componentData) {
         return null;
@@ -137,7 +139,7 @@ const readComponentMetadataApi = (handoff, id) => __awaiter(void 0, void 0, void
         tags: componentData.tags ? componentData.tags : [],
         properties: componentData.properties,
         previews: (0, previews_1.getDocumentedPreviews)(componentData.previews),
-        path: `/api/component/${id}.json`,
+        path: (0, url_1.buildComponentDetailUrl)(id, (_a = process.env.HANDOFF_APP_BASE_PATH) !== null && _a !== void 0 ? _a : ''),
     };
 });
 exports.readComponentMetadataApi = readComponentMetadataApi;

package/dist/transformers/preview/component/artifacts.js

@@ -21,6 +21,8 @@ const css_1 = require("./css");
 const javascript_1 = require("./javascript");
 const COMPONENT_JS_RESERVED_FILES = new Set([javascript_1.MAIN_COMPONENT_JS_FILE]);
 const COMPONENT_CSS_RESERVED_FILES = new Set([css_1.MAIN_COMPONENT_CSS_FILE, css_1.SHARED_COMPONENT_CSS_FILE]);
+/** Suffix of a component-owned client/hydration artifact (`<id>.client.js`), see ssr-render plugin. */
+const CLIENT_ARTIFACT_SUFFIX = '.client.js';
 const getComponentApiPath = (handoff) => path_1.default.resolve((0, api_1.getAPIPath)(handoff), 'component');
 exports.getComponentApiPath = getComponentApiPath;
 const getComponentPreviewKeys = (handoff, componentId) => __awaiter(void 0, void 0, void 0, function* () {
@@ -81,7 +83,9 @@ const syncComponentArtifacts = (handoff) => __awaiter(void 0, void 0, void 0, fu
         const parsed = path_1.default.parse(entry);
         if (parsed.ext === '.json' || parsed.ext === '.js' || parsed.ext === '.css') {
             if (!COMPONENT_JS_RESERVED_FILES.has(entry) && !COMPONENT_CSS_RESERVED_FILES.has(entry)) {
-                discoveredArtifactIds.add(parsed.name);
+                // `<id>.client.js` is owned by `<id>`, not by a phantom `<id>.client` component — strip the
+                // compound suffix so the owner id matches the real component (path.parse would yield `<id>.client`).
+                discoveredArtifactIds.add(entry.endsWith(CLIENT_ARTIFACT_SUFFIX) ? entry.slice(0, -CLIENT_ARTIFACT_SUFFIX.length) : parsed.name);
             }
         }
     }
@@ -91,6 +95,9 @@ const syncComponentArtifacts = (handoff) => __awaiter(void 0, void 0, void 0, fu
         if (yield fs_extra_1.default.pathExists(path_1.default.resolve(componentPath, `${componentId}.js`))) {
             validFiles.add(`${componentId}.js`);
         }
+        if (yield fs_extra_1.default.pathExists(path_1.default.resolve(componentPath, `${componentId}${CLIENT_ARTIFACT_SUFFIX}`))) {
+            validFiles.add(`${componentId}${CLIENT_ARTIFACT_SUFFIX}`);
+        }
         if (yield fs_extra_1.default.pathExists(path_1.default.resolve(componentPath, `${componentId}.css`))) {
             validFiles.add(`${componentId}.css`);
         }

package/dist/transformers/preview/component/builder.js

@@ -26,6 +26,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ComponentSegment = void 0;
 exports.processComponents = processComponents;
 const cloneDeep_1 = __importDefault(require("lodash/cloneDeep"));
+const url_1 = require("../../../artifacts/url");
 const cache_1 = require("../../../cache");
 const duration_1 = require("../../../utils/duration");
 const logger_1 = require("../../../utils/logger");
@@ -149,11 +150,18 @@ const createComponentBuildPlan = (segmentToProcess, existingData) => {
  */
 function processComponents(handoff, id, segmentToProcess, options) {
     return __awaiter(this, void 0, void 0, function* () {
-        var _a, _b, _c, _d, _e, _f, _g;
+        var _a, _b, _c, _d;
         const result = [];
         const documentationObject = yield handoff.getDocumentationObject();
         const components = (_a = documentationObject === null || documentationObject === void 0 ? void 0 : documentationObject.components) !== null && _a !== void 0 ? _a : {};
-        const runtimeComponents = (_d = (_c = (_b = handoff.runtimeConfig) === null || _b === void 0 ? void 0 : _b.entries) === null || _c === void 0 ? void 0 : _c.components) !== null && _d !== void 0 ? _d : {};
+        // Resolve the component set through the storage-agnostic store (v2). The filesystem store is a
+        // read view over `runtimeConfig.entries.components`, so these are the same records the build has
+        // always used — rebuilt into the id-keyed map the build logic below expects.
+        const runtimeComponents = {};
+        for (const component of yield handoff.store.components.list()) {
+            if (component)
+                runtimeComponents[component.id] = component;
+        }
         const allComponentIds = Object.keys(runtimeComponents);
         if (id && !runtimeComponents[id]) {
             yield (0, artifacts_1.removeComponentApi)(handoff, id);
@@ -188,7 +196,7 @@ function processComponents(handoff, id, segmentToProcess, options) {
                 for (const componentId of allComponentIds) {
                     const currentFileStates = yield (0, cache_1.computeComponentFileStates)(handoff, componentId);
                     componentFileStatesMap.set(componentId, currentFileStates);
-                    const cachedEntry = (_e = cache === null || cache === void 0 ? void 0 : cache.components) === null || _e === void 0 ? void 0 : _e[componentId];
+                    const cachedEntry = (_b = cache === null || cache === void 0 ? void 0 : cache.components) === null || _b === void 0 ? void 0 : _b[componentId];
                     if (!cachedEntry) {
                         logger_1.Logger.info(`Component '${componentId}': new component, will build`);
                         componentsToBuild.add(componentId);
@@ -337,7 +345,7 @@ function processComponents(handoff, id, segmentToProcess, options) {
              * Run validation if explicitly requested and a hook is configured.
              * This allows custom logic to assess the validity of the generated component data.
              */
-            if (buildPlan.validationMode && ((_g = (_f = handoff.config) === null || _f === void 0 ? void 0 : _f.hooks) === null || _g === void 0 ? void 0 : _g.validateComponent)) {
+            if (buildPlan.validationMode && ((_d = (_c = handoff.config) === null || _c === void 0 ? void 0 : _c.hooks) === null || _d === void 0 ? void 0 : _d.validateComponent)) {
                 const validationResults = yield handoff.config.hooks.validateComponent(data);
                 data.validations = validationResults;
             }
@@ -400,7 +408,7 @@ const buildComponentSummary = (id, data) => {
         tags: data.tags ? data.tags : [],
         properties: data.properties,
         previews: (0, previews_1.getDocumentedPreviews)(data.previews),
-        path: `${(_a = process.env.HANDOFF_APP_BASE_PATH) !== null && _a !== void 0 ? _a : ''}/api/component/${id}.json`,
+        path: (0, url_1.buildComponentDetailUrl)(id, (_a = process.env.HANDOFF_APP_BASE_PATH) !== null && _a !== void 0 ? _a : ''),
     };
 };
 exports.default = processComponents;