handoff-app 1.2.2-7 → 2.0.0-0

package/src/transformers/plugins/ssr-render.ts

@@ -6,6 +6,7 @@ import React from 'react';
 import ReactDOMServer from 'react-dom/server';
 import { Plugin, normalizePath } from 'vite';
 import Handoff from '../..';
+import { buildArtifactUrl } from '../../artifacts/url';
 import { Logger } from '../../utils/logger';
 import {
     enrichPropertiesWithDocgen,
@@ -14,7 +15,15 @@ import {
     getPropertiesFromGeneratedDocs,
 } from '../docgen';
 import { SlotMetadata } from '../preview/component';
-import { MAIN_COMPONENT_CSS_FILE } from '../preview/component/css';
+import {
+  renderComponentStyleLink,
+  renderGlobalScriptTag,
+  renderSharedStyleLinks,
+  resolveComponentArtifactPresence,
+  resolveSharedArtifactPresence,
+  type ComponentArtifactPresence,
+  type SharedArtifactPresence,
+} from '../preview/component/shared-artifacts';
 import { TransformComponentTokensResult } from '../preview/types';
 import { DEFAULT_CLIENT_BUILD_CONFIG, createReactResolvePlugin } from '../utils/build';
 import { formatHtml, trimPreview } from '../utils/html';
@@ -41,6 +50,16 @@ const PLUGIN_CONSTANTS = {
   INSPECT_SUFFIX: '-inspect',
 } as const;
 
+/**
+ * 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: string): string => `component/${componentId}.${CLIENT_ARTIFACT_SUFFIX}`;
+
 /**
  * Loads and processes component schema using hierarchical approach
  * @param componentData - Component transformation data
@@ -95,43 +114,99 @@ async function loadComponentSchemaAndModule(
 }
 
 /**
- * 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: string): string {
+function generateClientHydrationSource(componentId: string, componentPath: string): string {
   return `
     import React from 'react';
     import { hydrateRoot } from 'react-dom/client';
     import Component from '${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: string, previewTitle: string, renderedHtml: string, clientJs: string, props: any): string {
+function generateHtmlDocument(
+  componentId: string,
+  previewTitle: string,
+  renderedHtml: string,
+  props: any,
+  sharedArtifacts: SharedArtifactPresence,
+  componentArtifacts: ComponentArtifactPresence
+): string {
+  const basePath = process.env.HANDOFF_APP_BASE_PATH ?? '';
+  const clientArtifactUrl = 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 = renderSharedStyleLinks(sharedArtifacts, basePath);
+  const componentStyleLink = 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 = renderGlobalScriptTag(sharedArtifacts, basePath);
   return `<!DOCTYPE html>
 <html lang="en">
   <head>
-    <meta charset="UTF-8" />
-    <link rel="stylesheet" href="${process.env.HANDOFF_APP_BASE_PATH ?? ''}/api/component/${MAIN_COMPONENT_CSS_FILE}" />
-    <link rel="stylesheet" href="${process.env.HANDOFF_APP_BASE_PATH ?? ''}/api/component/${componentId}.css" />
-    <link rel="stylesheet" href="${process.env.HANDOFF_APP_BASE_PATH ?? ''}/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>
@@ -225,8 +300,58 @@ export function ssrRenderPlugin(
         }
       }
 
+      // 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 = {
+        ...DEFAULT_CLIENT_BUILD_CONFIG,
+        logLevel: 'silent' as const,
+        stdin: {
+          contents: clientHydrationSource,
+          resolveDir: process.cwd(),
+          loader: 'tsx' as const,
+        },
+        plugins: [createReactResolvePlugin(handoff.workingPath, handoff.modulePath)],
+      };
+
+      const finalClientBuildConfig = handoff.config?.hooks?.clientBuildConfig
+        ? handoff.config.hooks.clientBuildConfig(clientBuildConfig)
+        : clientBuildConfig;
+
+      let clientBundleJs: string;
+      try {
+        const bundledClient = await esbuild.build(finalClientBuildConfig);
+        if (bundledClient.warnings.length > 0) {
+          const messages = await esbuild.formatMessages(bundledClient.warnings, { kind: 'warning', color: true });
+          messages.forEach((msg) => Logger.warn(msg));
+        }
+        clientBundleJs = bundledClient.outputFiles[0].text;
+      } catch (error: any) {
+        // 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.error(`Failed to build client bundle for ${componentId}`);
+        if (error.errors) {
+          const messages = await esbuild.formatMessages(error.errors, { kind: 'error', color: true });
+          messages.forEach((msg) => 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 = resolveSharedArtifactPresence(handoff);
+      const componentArtifacts = resolveComponentArtifactPresence(handoff, componentId);
+
       // Generate previews for each variation
       for (const previewKey in componentData.previews) {
         const previewProps = componentData.previews[previewKey].values;
@@ -235,50 +360,13 @@ export function ssrRenderPlugin(
         const serverRenderedHtml = ReactDOMServer.renderToString(React.createElement(ReactComponent, previewProps));
         const formattedHtml = await formatHtml(serverRenderedHtml);
 
-        // Generate client-side hydration code
-        const clientHydrationSource = generateClientHydrationSource(componentPath);
-
-        // Build client-side bundle
-        const clientBuildConfig = {
-          ...DEFAULT_CLIENT_BUILD_CONFIG,
-          logLevel: 'silent' as const,
-          stdin: {
-            contents: clientHydrationSource,
-            resolveDir: process.cwd(),
-            loader: 'tsx' as const,
-          },
-          plugins: [createReactResolvePlugin(handoff.workingPath, handoff.modulePath)],
-        };
-
-        // Apply user's client build config hook if provided
-        const finalClientBuildConfig = handoff.config?.hooks?.clientBuildConfig
-          ? handoff.config.hooks.clientBuildConfig(clientBuildConfig)
-          : clientBuildConfig;
-
-        let clientBundleJs: string;
-        try {
-          const bundledClient = await esbuild.build(finalClientBuildConfig);
-          if (bundledClient.warnings.length > 0) {
-            const messages = await esbuild.formatMessages(bundledClient.warnings, { kind: 'warning', color: true });
-            messages.forEach((msg) => Logger.warn(msg));
-          }
-          clientBundleJs = bundledClient.outputFiles[0].text;
-        } catch (error: any) {
-          Logger.error(`Failed to build client bundle for ${componentId}`);
-          if (error.errors) {
-            const messages = await esbuild.formatMessages(error.errors, { kind: 'error', color: true });
-            messages.forEach((msg) => Logger.error(msg));
-          }
-          continue;
-        }
-
-        // Generate complete HTML document
         finalHtml = generateHtmlDocument(
           componentId,
           componentData.previews[previewKey].title,
           formattedHtml,
-          clientBundleJs,
-          previewProps
+          previewProps,
+          sharedArtifacts,
+          componentArtifacts
         );
 
         // Emit preview files

package/src/transformers/preview/component/api.ts

@@ -1,5 +1,6 @@
 import fs from 'fs-extra';
 import path from 'path';
+import { buildComponentDetailUrl } from '../../../artifacts/url';
 import Handoff from '../../../index';
 import { ComponentListObject, TransformComponentTokensResult } from '../types';
 import { getDocumentedPreviews } from './previews';
@@ -148,7 +149,7 @@ export const readComponentMetadataApi = async (handoff: Handoff, id: string): Pr
     tags: componentData.tags ? componentData.tags : [],
     properties: componentData.properties,
     previews: getDocumentedPreviews(componentData.previews),
-    path: `/api/component/${id}.json`,
+    path: buildComponentDetailUrl(id, process.env.HANDOFF_APP_BASE_PATH ?? ''),
   };
 };
 export default writeComponentApi;

package/src/transformers/preview/component/artifacts.ts

@@ -10,6 +10,9 @@ import { MAIN_COMPONENT_JS_FILE } from './javascript';
 const COMPONENT_JS_RESERVED_FILES = new Set([MAIN_COMPONENT_JS_FILE]);
 const COMPONENT_CSS_RESERVED_FILES = new Set([MAIN_COMPONENT_CSS_FILE, 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';
+
 export const getComponentApiPath = (handoff: Handoff) => path.resolve(getAPIPath(handoff), 'component');
 
 const getComponentPreviewKeys = async (handoff: Handoff, componentId: string): Promise<Set<string>> => {
@@ -77,7 +80,9 @@ export const syncComponentArtifacts = async (handoff: Handoff): Promise<void> =>
     const parsed = path.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);
       }
     }
   }
@@ -90,6 +95,10 @@ export const syncComponentArtifacts = async (handoff: Handoff): Promise<void> =>
       validFiles.add(`${componentId}.js`);
     }
 
+    if (await fs.pathExists(path.resolve(componentPath, `${componentId}${CLIENT_ARTIFACT_SUFFIX}`))) {
+      validFiles.add(`${componentId}${CLIENT_ARTIFACT_SUFFIX}`);
+    }
+
     if (await fs.pathExists(path.resolve(componentPath, `${componentId}.css`))) {
       validFiles.add(`${componentId}.css`);
     }

package/src/transformers/preview/component/builder.ts

@@ -1,5 +1,6 @@
 import { Types as CoreTypes } from 'handoff-core';
 import cloneDeep from 'lodash/cloneDeep';
+import { buildComponentDetailUrl } from '../../../artifacts/url';
 import {
   BuildCache,
   checkOutputExists,
@@ -178,7 +179,13 @@ export async function processComponents(
 
   const documentationObject = await handoff.getDocumentationObject();
   const components = documentationObject?.components ?? ({} as CoreTypes.IDocumentationObject['components']);
-  const runtimeComponents = handoff.runtimeConfig?.entries?.components ?? {};
+  // 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: Record<string, ComponentListObject> = {};
+  for (const component of await handoff.store.components.list()) {
+    if (component) runtimeComponents[component.id] = component;
+  }
   const allComponentIds = Object.keys(runtimeComponents);
 
   if (id && !runtimeComponents[id]) {
@@ -458,7 +465,7 @@ const buildComponentSummary = (id: string, data: TransformComponentTokensResult)
     tags: data.tags ? data.tags : [],
     properties: data.properties,
     previews: getDocumentedPreviews(data.previews),
-    path: `${process.env.HANDOFF_APP_BASE_PATH ?? ''}/api/component/${id}.json`,
+    path: buildComponentDetailUrl(id, process.env.HANDOFF_APP_BASE_PATH ?? ''),
   };
 };
 

package/src/transformers/preview/component/css.ts

@@ -183,6 +183,7 @@ const buildComponentCss = async (data: TransformComponentTokensResult, handoff:
  */
 export const buildMainCss = async (handoff: Handoff): Promise<void> => {
   const outputPath = getComponentOutputPath(handoff);
+  const mainCssPath = path.resolve(outputPath, MAIN_COMPONENT_CSS_FILE);
   const runtimeConfig = initRuntimeConfig(handoff)[0];
 
   if (runtimeConfig?.entries?.scss && fs.existsSync(runtimeConfig.entries.scss)) {
@@ -192,6 +193,9 @@ export const buildMainCss = async (handoff: Handoff): Promise<void> => {
     if (entryPath === runtimeConfig.entries.scss || fs.existsSync(entryPath)) {
       Logger.info(`Building styles for global entry (${MAIN_COMPONENT_CSS_FILE})…`);
       const startedAt = Date.now();
+      // Drop the previous artifact so a failed/empty rebuild cannot preserve stale global CSS that
+      // would still be referenced as current.
+      await fs.remove(mainCssPath);
       try {
         const loadPaths = [
           path.resolve(handoff.workingPath),
@@ -212,10 +216,15 @@ export const buildMainCss = async (handoff: Handoff): Promise<void> => {
         });
         Logger.info(`Finished building styles for global entry (${MAIN_COMPONENT_CSS_FILE}) in ${formatDurationMs(Date.now() - startedAt)}`);
       } catch {
-        // buildCssBundle already logs failure for the entry path
+        // buildCssBundle already logs failure for the entry path; ensure no stale artifact remains.
+        await fs.remove(mainCssPath);
       }
     }
+    return;
   }
+
+  // No usable global SCSS entry: drop any stale artifact so it is not referenced as current.
+  await fs.remove(mainCssPath);
 };
 
 export default buildComponentCss;

package/src/transformers/preview/component/javascript.ts

@@ -20,7 +20,12 @@ export const MAIN_COMPONENT_JS_FILE = 'main.js';
  * @param options.outputFilename - The name of the output file
  */
 const buildJsBundle = async (
-  { entry, outputPath, outputFilename }: { entry: string; outputPath: string; outputFilename: string },
+  {
+    entry,
+    outputPath,
+    outputFilename,
+    format = 'cjs',
+  }: { entry: string; outputPath: string; outputFilename: string; format?: 'cjs' | 'iife' },
   handoff: Handoff
 ) => {
   const absEntryPath = path.resolve(entry);
@@ -39,13 +44,15 @@ const buildJsBundle = async (
         lib: {
           entry: absEntryPath,
           name: path.basename(outputFilename, '.js'),
-          formats: ['cjs'],
+          formats: [format],
           fileName: () => outputFilename,
         },
         rollupOptions: {
           ...viteBaseConfig.build?.rollupOptions,
           output: {
-            exports: 'named',
+            // The global IIFE bundle is frequently side-effect-only; `auto` lets a bundle with no
+            // exports emit cleanly while `named` preserves the existing component-JS (cjs) behavior.
+            exports: format === 'iife' ? 'auto' : 'named',
           },
         },
         outDir: outputPath,
@@ -127,34 +134,62 @@ export const buildComponentJs = async (data: TransformComponentTokensResult, han
 };
 
 /**
- * Builds the main JavaScript bundle for the component preview.
+ * Builds the global preview script artifact (`component/main.js`) from the configured workspace JS
+ * entry.
  *
- * This function checks if there's a main JavaScript bundle defined in the runtime config,
- * and if the file exists, it builds the bundle and outputs it to the component's output path.
+ * The artifact is optional: when no global JS entry is configured, or the configured entry no longer
+ * exists, or the build fails/produces no output, any stale `main.js` is removed so a failed rebuild
+ * never leaves global JS that appears current. Generated HTML references `main.js` only when this
+ * function leaves a fresh artifact on disk, so an omitted artifact yields no dangling reference.
+ *
+ * Output uses the browser-compatible IIFE format so the artifact can load as a classic script ahead
+ * of dependent component scripts while preserving intentional top-level side effects.
  *
  * @param handoff - The Handoff configuration object containing build settings
  * @returns A Promise that resolves when the build process is complete
  */
 export const buildMainJS = async (handoff: Handoff): Promise<void> => {
   const outputPath = getComponentOutputPath(handoff);
+  const mainJsPath = path.resolve(outputPath, MAIN_COMPONENT_JS_FILE);
   const runtimeConfig = initRuntimeConfig(handoff)[0];
+  const entry = runtimeConfig?.entries?.js;
 
-  if (runtimeConfig && runtimeConfig.entries.js && fs.existsSync(path.resolve(runtimeConfig.entries.js))) {
-    Logger.info(`Building script for global entry (${MAIN_COMPONENT_JS_FILE})…`);
-    const startedAt = Date.now();
-    try {
-      await buildJsBundle(
-        {
-          entry: runtimeConfig.entries.js,
-          outputPath,
-          outputFilename: MAIN_COMPONENT_JS_FILE,
-        },
-        handoff
-      );
+  // No usable global JS entry: drop any stale artifact and emit nothing to reference.
+  if (!entry || !fs.existsSync(path.resolve(entry))) {
+    if (entry) {
+      Logger.warn(`Global JS entry "${entry}" was not found; removing stale ${MAIN_COMPONENT_JS_FILE}.`);
+    }
+    await fs.remove(mainJsPath);
+    return;
+  }
+
+  Logger.info(`Building script for global entry (${MAIN_COMPONENT_JS_FILE})…`);
+  const startedAt = Date.now();
+
+  // Remove the previous artifact before rebuilding so a failed or empty build cannot silently
+  // preserve stale global JS that would still be referenced as current.
+  await fs.remove(mainJsPath);
+
+  try {
+    await buildJsBundle(
+      {
+        entry,
+        outputPath,
+        outputFilename: MAIN_COMPONENT_JS_FILE,
+        format: 'iife',
+      },
+      handoff
+    );
+
+    if (await fs.pathExists(mainJsPath)) {
       Logger.info(`Finished building script for global entry (${MAIN_COMPONENT_JS_FILE}) in ${formatDurationMs(Date.now() - startedAt)}`);
-    } catch (e) {
-      Logger.error(`Failed to build global script (${MAIN_COMPONENT_JS_FILE}):`, e);
+    } else {
+      Logger.error(`Global script build produced no ${MAIN_COMPONENT_JS_FILE} from "${entry}".`);
     }
+  } catch (e) {
+    Logger.error(`Failed to build global script (${MAIN_COMPONENT_JS_FILE}) from "${entry}":`, e);
+    // Ensure a partial/failed build leaves no stale or broken artifact behind.
+    await fs.remove(mainJsPath);
   }
 };
 

package/src/transformers/preview/component/shared-artifacts.ts

@@ -0,0 +1,146 @@
+import fs from 'fs-extra';
+import path from 'path';
+import {
+  ArtifactReference,
+  SHARED_MAIN_CSS_ARTIFACT_PATH,
+  SHARED_MAIN_JS_ARTIFACT_PATH,
+  SHARED_STYLES_CSS_ARTIFACT_PATH,
+} from '../../../artifacts';
+import { buildArtifactUrl } from '../../../artifacts/url';
+import Handoff from '../../../index';
+import { getComponentOutputPath } from '../component';
+import { MAIN_COMPONENT_CSS_FILE, SHARED_COMPONENT_CSS_FILE } from './css';
+import { MAIN_COMPONENT_JS_FILE } from './javascript';
+
+/**
+ * Centralized shared/global artifact model for generated preview HTML.
+ *
+ * The shared artifacts (`component/main.css`, `component/main.js`, `component/shared.css`) are
+ * optional: each is emitted only when a corresponding source entry is configured and builds
+ * successfully. Generated HTML must reference a shared artifact only when it actually exists, so a
+ * failed or absent global build never leaves a dangling reference the browser would request.
+ *
+ * This module is the single place that decides which shared artifacts are present and turns that
+ * decision into structured references and the `<link>`/`<script>` tags every renderer emits — so
+ * dependency resolution is driven by the artifact model, never by parsing HTML.
+ */
+
+/** Which shared/global artifacts currently exist in the component output directory. */
+export interface SharedArtifactPresence {
+  /** `component/main.js` — the global preview script built from the configured JS entry. */
+  mainJs: boolean;
+  /** `component/main.css` — the global stylesheet built from the configured SCSS entry. */
+  mainCss: boolean;
+  /** `component/shared.css` — shared component styles extracted by the SCSS split marker. */
+  sharedCss: boolean;
+}
+
+/**
+ * Resolve which shared/global artifacts are present on disk. Global artifacts are built before
+ * component/pattern HTML is generated, so an existence check here reflects whether the artifact can
+ * be referenced without producing a missing-file browser request.
+ */
+export const resolveSharedArtifactPresence = (handoff: Handoff): SharedArtifactPresence => {
+  const outputPath = getComponentOutputPath(handoff);
+  return {
+    mainJs: fs.existsSync(path.join(outputPath, MAIN_COMPONENT_JS_FILE)),
+    mainCss: fs.existsSync(path.join(outputPath, MAIN_COMPONENT_CSS_FILE)),
+    sharedCss: fs.existsSync(path.join(outputPath, SHARED_COMPONENT_CSS_FILE)),
+  };
+};
+
+/** Options controlling which shared style references a renderer participates in. */
+export interface SharedStyleOptions {
+  /**
+   * Whether the rendered component opts into the shared-styles split (`component/shared.css`).
+   * Only renderers that consume shared styles (Handlebars) set this; it is still gated on the
+   * artifact actually existing.
+   */
+  includeSharedStyles?: boolean;
+}
+
+/**
+ * Build the structured shared-artifact references a preview/inspect document depends on, filtered to
+ * the artifacts that actually exist. Shared/global artifacts are optional references (`required:
+ * false`) owned by no entity (`ownerKind: 'asset'`, `ownerId: null`). Stylesheet references precede
+ * the script reference so consumers preserve the documented load order.
+ */
+export const getSharedArtifactReferences = (
+  presence: SharedArtifactPresence,
+  options?: SharedStyleOptions
+): ArtifactReference[] => {
+  const references: ArtifactReference[] = [];
+
+  if (options?.includeSharedStyles && presence.sharedCss) {
+    references.push({ path: SHARED_STYLES_CSS_ARTIFACT_PATH, kind: 'shared', required: false, ownerKind: 'asset', ownerId: null });
+  }
+  if (presence.mainCss) {
+    references.push({ path: SHARED_MAIN_CSS_ARTIFACT_PATH, kind: 'shared', required: false, ownerKind: 'asset', ownerId: null });
+  }
+  if (presence.mainJs) {
+    references.push({ path: SHARED_MAIN_JS_ARTIFACT_PATH, kind: 'shared', required: false, ownerKind: 'asset', ownerId: null });
+  }
+
+  return references;
+};
+
+/**
+ * Render the `<link rel="stylesheet">` tags for the present shared stylesheet artifacts
+ * (`component/shared.css` then `component/main.css`), in load order. Returns the tags joined by a
+ * newline, or an empty string when no shared stylesheet exists.
+ */
+export const renderSharedStyleLinks = (
+  presence: SharedArtifactPresence,
+  basePath: string,
+  options?: SharedStyleOptions
+): string =>
+  getSharedArtifactReferences(presence, options)
+    .filter((ref) => ref.path.endsWith('.css'))
+    .map((ref) => `<link rel="stylesheet" href="${buildArtifactUrl(ref.path, basePath)}">`)
+    .join('\n');
+
+/**
+ * Render the global preview script tag for `component/main.js` when present, or an empty string when
+ * absent. The global script is a classic (non-deferred) tag so it executes before dependent
+ * component-specific scripts and preserves intentional top-level side effects.
+ */
+export const renderGlobalScriptTag = (presence: SharedArtifactPresence, basePath: string): string =>
+  presence.mainJs ? `<script src="${buildArtifactUrl(SHARED_MAIN_JS_ARTIFACT_PATH, basePath)}"></script>` : '';
+
+/** Which of a component's own optional artifacts exist in the component output directory. */
+export interface ComponentArtifactPresence {
+  /** `component/<id>.css` — built only when the component declares an SCSS/CSS entry. */
+  css: boolean;
+  /** `component/<id>.js` — built only when the component declares a JS entry. */
+  js: boolean;
+}
+
+/**
+ * Resolve which of a component's own css/js artifacts exist on disk. A component's styles and
+ * scripts are built (or removed when their entry is absent) before its preview HTML is generated, so
+ * an existence check here reflects whether the artifact can be referenced without producing a
+ * missing-file browser request. Like the shared artifacts, these references are optional.
+ */
+export const resolveComponentArtifactPresence = (handoff: Handoff, componentId: string): ComponentArtifactPresence => {
+  const outputPath = getComponentOutputPath(handoff);
+  return {
+    css: fs.existsSync(path.join(outputPath, `${componentId}.css`)),
+    js: fs.existsSync(path.join(outputPath, `${componentId}.js`)),
+  };
+};
+
+/**
+ * Render the `<link rel="stylesheet">` tag for a component's own stylesheet (`component/<id>.css`)
+ * when it exists, or an empty string when the component declares no styles — so generated HTML never
+ * references an absent optional artifact.
+ */
+export const renderComponentStyleLink = (presence: ComponentArtifactPresence, componentId: string, basePath: string): string =>
+  presence.css ? `<link rel="stylesheet" href="${buildArtifactUrl(`component/${componentId}.css`, basePath)}">` : '';
+
+/**
+ * Render the `<script>` tag for a component's own script (`component/<id>.js`) when it exists, or an
+ * empty string when the component declares no script. The component script is a classic tag loaded
+ * after the global script so global side effects run first.
+ */
+export const renderComponentScriptTag = (presence: ComponentArtifactPresence, componentId: string, basePath: string): string =>
+  presence.js ? `<script src="${buildArtifactUrl(`component/${componentId}.js`, basePath)}"></script>` : '';

package/src/transformers/preview/component.ts

@@ -86,8 +86,11 @@ export const getComponentOutputPath = (handoff: Handoff) => path.resolve(getAPIP
  * @returns
  */
 export async function componentTransformer(handoff: Handoff) {
-  const componentData = await processComponents(handoff);
-  await writeComponentSummaryAPI(handoff, componentData);
+  // Build the shared/global artifacts first so component/pattern preview HTML can reference them
+  // only when they actually exist. A failed/absent global build therefore never produces a dangling
+  // reference in generated HTML.
   await buildMainJS(handoff);
   await buildMainCss(handoff);
+  const componentData = await processComponents(handoff);
+  await writeComponentSummaryAPI(handoff, componentData);
 }