handoff-app 1.2.2-7 → 2.0.0-0

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

@@ -165,6 +165,7 @@ const buildComponentCss = (data, handoff) => __awaiter(void 0, void 0, void 0, f
 const buildMainCss = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
     var _a, _b, _c;
     const outputPath = (0, component_1.getComponentOutputPath)(handoff);
+    const mainCssPath = path_1.default.resolve(outputPath, exports.MAIN_COMPONENT_CSS_FILE);
     const runtimeConfig = (0, config_1.initRuntimeConfig)(handoff)[0];
     if (((_a = runtimeConfig === null || runtimeConfig === void 0 ? void 0 : runtimeConfig.entries) === null || _a === void 0 ? void 0 : _a.scss) && fs_extra_1.default.existsSync(runtimeConfig.entries.scss)) {
         const stat = yield fs_extra_1.default.stat(runtimeConfig.entries.scss);
@@ -172,6 +173,9 @@ const buildMainCss = (handoff) => __awaiter(void 0, void 0, void 0, function* ()
         if (entryPath === runtimeConfig.entries.scss || fs_extra_1.default.existsSync(entryPath)) {
             logger_1.Logger.info(`Building styles for global entry (${exports.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.
+            yield fs_extra_1.default.remove(mainCssPath);
             try {
                 const loadPaths = [
                     path_1.default.resolve(handoff.workingPath),
@@ -191,10 +195,14 @@ const buildMainCss = (handoff) => __awaiter(void 0, void 0, void 0, function* ()
                 logger_1.Logger.info(`Finished building styles for global entry (${exports.MAIN_COMPONENT_CSS_FILE}) in ${(0, duration_1.formatDurationMs)(Date.now() - startedAt)}`);
             }
             catch (_d) {
-                // buildCssBundle already logs failure for the entry path
+                // buildCssBundle already logs failure for the entry path; ensure no stale artifact remains.
+                yield fs_extra_1.default.remove(mainCssPath);
             }
         }
+        return;
     }
+    // No usable global SCSS entry: drop any stale artifact so it is not referenced as current.
+    yield fs_extra_1.default.remove(mainCssPath);
 });
 exports.buildMainCss = buildMainCss;
 exports.default = buildComponentCss;

package/dist/transformers/preview/component/javascript.d.ts

@@ -12,10 +12,16 @@ export declare const MAIN_COMPONENT_JS_FILE = "main.js";
  */
 export declare const buildComponentJs: (data: TransformComponentTokensResult, handoff: Handoff) => Promise<TransformComponentTokensResult>;
 /**
- * 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

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

@@ -30,7 +30,7 @@ exports.MAIN_COMPONENT_JS_FILE = 'main.js';
  * @param options.outputPath - The directory where the bundle will be output
  * @param options.outputFilename - The name of the output file
  */
-const buildJsBundle = (_a, handoff_1) => __awaiter(void 0, [_a, handoff_1], void 0, function* ({ entry, outputPath, outputFilename }, handoff) {
+const buildJsBundle = (_a, handoff_1) => __awaiter(void 0, [_a, handoff_1], void 0, function* ({ entry, outputPath, outputFilename, format = 'cjs', }, handoff) {
     var _b, _c, _d;
     const absEntryPath = path_1.default.resolve(entry);
     // Store the current NODE_ENV value before vite build
@@ -42,10 +42,12 @@ const buildJsBundle = (_a, handoff_1) => __awaiter(void 0, [_a, handoff_1], void
         let viteConfig = Object.assign(Object.assign({}, vite_config_1.default), { build: Object.assign(Object.assign({}, vite_config_1.default.build), { lib: {
                     entry: absEntryPath,
                     name: path_1.default.basename(outputFilename, '.js'),
-                    formats: ['cjs'],
+                    formats: [format],
                     fileName: () => outputFilename,
                 }, rollupOptions: Object.assign(Object.assign({}, (_b = vite_config_1.default.build) === null || _b === void 0 ? void 0 : _b.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 }) });
         if ((_d = (_c = handoff === null || handoff === void 0 ? void 0 : handoff.config) === null || _c === void 0 ? void 0 : _c.hooks) === null || _d === void 0 ? void 0 : _d.jsBuildConfig) {
             viteConfig = handoff.config.hooks.jsBuildConfig(viteConfig);
@@ -118,32 +120,58 @@ const buildComponentJs = (data, handoff) => __awaiter(void 0, void 0, void 0, fu
 });
 exports.buildComponentJs = buildComponentJs;
 /**
- * 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
  */
 const buildMainJS = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
     const outputPath = (0, component_1.getComponentOutputPath)(handoff);
+    const mainJsPath = path_1.default.resolve(outputPath, exports.MAIN_COMPONENT_JS_FILE);
     const runtimeConfig = (0, config_1.initRuntimeConfig)(handoff)[0];
-    if (runtimeConfig && runtimeConfig.entries.js && fs_extra_1.default.existsSync(path_1.default.resolve(runtimeConfig.entries.js))) {
-        logger_1.Logger.info(`Building script for global entry (${exports.MAIN_COMPONENT_JS_FILE})…`);
-        const startedAt = Date.now();
-        try {
-            yield buildJsBundle({
-                entry: runtimeConfig.entries.js,
-                outputPath,
-                outputFilename: exports.MAIN_COMPONENT_JS_FILE,
-            }, handoff);
+    const entry = (_a = runtimeConfig === null || runtimeConfig === void 0 ? void 0 : runtimeConfig.entries) === null || _a === void 0 ? void 0 : _a.js;
+    // No usable global JS entry: drop any stale artifact and emit nothing to reference.
+    if (!entry || !fs_extra_1.default.existsSync(path_1.default.resolve(entry))) {
+        if (entry) {
+            logger_1.Logger.warn(`Global JS entry "${entry}" was not found; removing stale ${exports.MAIN_COMPONENT_JS_FILE}.`);
+        }
+        yield fs_extra_1.default.remove(mainJsPath);
+        return;
+    }
+    logger_1.Logger.info(`Building script for global entry (${exports.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.
+    yield fs_extra_1.default.remove(mainJsPath);
+    try {
+        yield buildJsBundle({
+            entry,
+            outputPath,
+            outputFilename: exports.MAIN_COMPONENT_JS_FILE,
+            format: 'iife',
+        }, handoff);
+        if (yield fs_extra_1.default.pathExists(mainJsPath)) {
             logger_1.Logger.info(`Finished building script for global entry (${exports.MAIN_COMPONENT_JS_FILE}) in ${(0, duration_1.formatDurationMs)(Date.now() - startedAt)}`);
         }
-        catch (e) {
-            logger_1.Logger.error(`Failed to build global script (${exports.MAIN_COMPONENT_JS_FILE}):`, e);
+        else {
+            logger_1.Logger.error(`Global script build produced no ${exports.MAIN_COMPONENT_JS_FILE} from "${entry}".`);
         }
     }
+    catch (e) {
+        logger_1.Logger.error(`Failed to build global script (${exports.MAIN_COMPONENT_JS_FILE}) from "${entry}":`, e);
+        // Ensure a partial/failed build leaves no stale or broken artifact behind.
+        yield fs_extra_1.default.remove(mainJsPath);
+    }
 });
 exports.buildMainJS = buildMainJS;
 exports.default = exports.buildComponentJs;

package/dist/transformers/preview/component/shared-artifacts.d.ts

@@ -0,0 +1,83 @@
+import { ArtifactReference } from '../../../artifacts';
+import Handoff from '../../../index';
+/**
+ * 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 declare const resolveSharedArtifactPresence: (handoff: Handoff) => SharedArtifactPresence;
+/** 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 declare const getSharedArtifactReferences: (presence: SharedArtifactPresence, options?: SharedStyleOptions) => ArtifactReference[];
+/**
+ * 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 declare const renderSharedStyleLinks: (presence: SharedArtifactPresence, basePath: string, options?: SharedStyleOptions) => string;
+/**
+ * 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 declare const renderGlobalScriptTag: (presence: SharedArtifactPresence, basePath: string) => string;
+/** 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 declare const resolveComponentArtifactPresence: (handoff: Handoff, componentId: string) => ComponentArtifactPresence;
+/**
+ * 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 declare const renderComponentStyleLink: (presence: ComponentArtifactPresence, componentId: string, basePath: string) => string;
+/**
+ * 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 declare const renderComponentScriptTag: (presence: ComponentArtifactPresence, componentId: string, basePath: string) => string;

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

@@ -0,0 +1,92 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderComponentScriptTag = exports.renderComponentStyleLink = exports.resolveComponentArtifactPresence = exports.renderGlobalScriptTag = exports.renderSharedStyleLinks = exports.getSharedArtifactReferences = exports.resolveSharedArtifactPresence = void 0;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const artifacts_1 = require("../../../artifacts");
+const url_1 = require("../../../artifacts/url");
+const component_1 = require("../component");
+const css_1 = require("./css");
+const javascript_1 = require("./javascript");
+/**
+ * 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.
+ */
+const resolveSharedArtifactPresence = (handoff) => {
+    const outputPath = (0, component_1.getComponentOutputPath)(handoff);
+    return {
+        mainJs: fs_extra_1.default.existsSync(path_1.default.join(outputPath, javascript_1.MAIN_COMPONENT_JS_FILE)),
+        mainCss: fs_extra_1.default.existsSync(path_1.default.join(outputPath, css_1.MAIN_COMPONENT_CSS_FILE)),
+        sharedCss: fs_extra_1.default.existsSync(path_1.default.join(outputPath, css_1.SHARED_COMPONENT_CSS_FILE)),
+    };
+};
+exports.resolveSharedArtifactPresence = resolveSharedArtifactPresence;
+/**
+ * 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.
+ */
+const getSharedArtifactReferences = (presence, options) => {
+    const references = [];
+    if ((options === null || options === void 0 ? void 0 : options.includeSharedStyles) && presence.sharedCss) {
+        references.push({ path: artifacts_1.SHARED_STYLES_CSS_ARTIFACT_PATH, kind: 'shared', required: false, ownerKind: 'asset', ownerId: null });
+    }
+    if (presence.mainCss) {
+        references.push({ path: artifacts_1.SHARED_MAIN_CSS_ARTIFACT_PATH, kind: 'shared', required: false, ownerKind: 'asset', ownerId: null });
+    }
+    if (presence.mainJs) {
+        references.push({ path: artifacts_1.SHARED_MAIN_JS_ARTIFACT_PATH, kind: 'shared', required: false, ownerKind: 'asset', ownerId: null });
+    }
+    return references;
+};
+exports.getSharedArtifactReferences = getSharedArtifactReferences;
+/**
+ * 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.
+ */
+const renderSharedStyleLinks = (presence, basePath, options) => (0, exports.getSharedArtifactReferences)(presence, options)
+    .filter((ref) => ref.path.endsWith('.css'))
+    .map((ref) => `<link rel="stylesheet" href="${(0, url_1.buildArtifactUrl)(ref.path, basePath)}">`)
+    .join('\n');
+exports.renderSharedStyleLinks = renderSharedStyleLinks;
+/**
+ * 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.
+ */
+const renderGlobalScriptTag = (presence, basePath) => presence.mainJs ? `<script src="${(0, url_1.buildArtifactUrl)(artifacts_1.SHARED_MAIN_JS_ARTIFACT_PATH, basePath)}"></script>` : '';
+exports.renderGlobalScriptTag = renderGlobalScriptTag;
+/**
+ * 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.
+ */
+const resolveComponentArtifactPresence = (handoff, componentId) => {
+    const outputPath = (0, component_1.getComponentOutputPath)(handoff);
+    return {
+        css: fs_extra_1.default.existsSync(path_1.default.join(outputPath, `${componentId}.css`)),
+        js: fs_extra_1.default.existsSync(path_1.default.join(outputPath, `${componentId}.js`)),
+    };
+};
+exports.resolveComponentArtifactPresence = resolveComponentArtifactPresence;
+/**
+ * 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.
+ */
+const renderComponentStyleLink = (presence, componentId, basePath) => presence.css ? `<link rel="stylesheet" href="${(0, url_1.buildArtifactUrl)(`component/${componentId}.css`, basePath)}">` : '';
+exports.renderComponentStyleLink = renderComponentStyleLink;
+/**
+ * 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.
+ */
+const renderComponentScriptTag = (presence, componentId, basePath) => presence.js ? `<script src="${(0, url_1.buildArtifactUrl)(`component/${componentId}.js`, basePath)}"></script>` : '';
+exports.renderComponentScriptTag = renderComponentScriptTag;

package/dist/transformers/preview/component.js

@@ -43,9 +43,12 @@ exports.getComponentOutputPath = getComponentOutputPath;
  */
 function componentTransformer(handoff) {
     return __awaiter(this, void 0, void 0, function* () {
-        const componentData = yield (0, builder_1.default)(handoff);
-        yield (0, summary_1.default)(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.
         yield (0, javascript_1.buildMainJS)(handoff);
         yield (0, css_1.buildMainCss)(handoff);
+        const componentData = yield (0, builder_1.default)(handoff);
+        yield (0, summary_1.default)(handoff, componentData);
     });
 }

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

@@ -16,7 +16,9 @@ exports.getPatternIdsReferencingComponents = void 0;
 exports.processPatterns = processPatterns;
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
+const url_1 = require("../../../artifacts/url");
 const logger_1 = require("../../../utils/logger");
+const shared_artifacts_1 = require("../component/shared-artifacts");
 const api_1 = require("./api");
 const html_1 = require("./html");
 /**
@@ -39,7 +41,7 @@ const getPatternIdsReferencingComponents = (handoff, componentIds) => {
     return result;
 };
 exports.getPatternIdsReferencingComponents = getPatternIdsReferencingComponents;
-function buildPattern(handoff, patternId, pattern, componentOutputDir, basePath) {
+function buildPattern(handoff, patternId, pattern, componentOutputDir, basePath, sharedArtifacts) {
     return __awaiter(this, void 0, void 0, function* () {
         const fragments = [];
         let hasErrors = false;
@@ -71,6 +73,14 @@ function buildPattern(handoff, patternId, pattern, componentOutputDir, basePath)
             const html = yield fs_extra_1.default.readFile(htmlFilePath, 'utf8');
             fragments.push({ componentId: ref.id, html });
         }
+        // Resolve component-owned artifact presence for each composed component so the pattern references
+        // only the stylesheets that actually exist (no dangling references for style-less components).
+        const componentArtifacts = new Map();
+        for (const fragment of fragments) {
+            if (!componentArtifacts.has(fragment.componentId)) {
+                componentArtifacts.set(fragment.componentId, (0, shared_artifacts_1.resolveComponentArtifactPresence)(handoff, fragment.componentId));
+            }
+        }
         if (fragments.length === 0) {
             logger_1.Logger.warn(`Pattern "${patternId}" produced no fragments. Skipping.`);
             return null;
@@ -78,9 +88,9 @@ function buildPattern(handoff, patternId, pattern, componentOutputDir, basePath)
         if (hasErrors) {
             logger_1.Logger.warn(`Pattern "${patternId}" has missing components but will be composed from available fragments.`);
         }
-        const composedHtml = (0, html_1.composePatternHtml)(patternId, pattern.title, fragments, basePath);
+        const composedHtml = (0, html_1.composePatternHtml)(patternId, pattern.title, fragments, basePath, sharedArtifacts, componentArtifacts);
         const patternUrl = `${patternId}.html`;
-        const patternData = Object.assign(Object.assign({}, pattern), { id: patternId, url: patternUrl, path: `${basePath}/api/pattern/${patternId}.json` });
+        const patternData = Object.assign(Object.assign({}, pattern), { id: patternId, url: patternUrl, path: (0, url_1.buildPatternDetailUrl)(patternId, basePath) });
         yield (0, api_1.writePatternHtml)(patternId, composedHtml, handoff);
         yield (0, api_1.writePatternApi)(patternId, patternData, handoff);
         logger_1.Logger.debug(`Built pattern: ${patternId} (${fragments.length} component(s))`);
@@ -94,8 +104,14 @@ function buildPattern(handoff, patternId, pattern, componentOutputDir, basePath)
  */
 function processPatterns(handoff, options) {
     return __awaiter(this, void 0, void 0, function* () {
-        var _a, _b, _c, _d;
-        const runtimePatterns = (_c = (_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.patterns) !== null && _c !== void 0 ? _c : {};
+        var _a;
+        // Resolve the pattern set through the storage-agnostic store (v2). The filesystem store is a read
+        // view over `runtimeConfig.entries.patterns`, so these are the same records the build has always
+        // used — rebuilt into the id-keyed map the build logic below expects.
+        const runtimePatterns = {};
+        for (const pattern of yield handoff.store.patterns.list()) {
+            runtimePatterns[pattern.id] = pattern;
+        }
         const patternIds = Object.keys(runtimePatterns);
         const onlyPatternIds = options === null || options === void 0 ? void 0 : options.onlyPatternIds;
         const isPartial = onlyPatternIds !== undefined;
@@ -105,13 +121,16 @@ function processPatterns(handoff, options) {
             return [];
         }
         const componentOutputDir = path_1.default.resolve(handoff.workingPath, 'public/api/component');
-        const basePath = (_d = process.env.HANDOFF_APP_BASE_PATH) !== null && _d !== void 0 ? _d : '';
+        const basePath = (_a = process.env.HANDOFF_APP_BASE_PATH) !== null && _a !== void 0 ? _a : '';
+        // Resolve the shared/global artifacts once so composed patterns reference `component/main.css` and
+        // `component/main.js` only when present (deduplicated to a single global script per page).
+        const sharedArtifacts = (0, shared_artifacts_1.resolveSharedArtifactPresence)(handoff);
         if (!isPartial) {
             logger_1.Logger.info(`Building ${patternIds.length} pattern(s)...`);
             const result = [];
             for (const patternId of patternIds) {
                 const pattern = runtimePatterns[patternId];
-                const built = yield buildPattern(handoff, patternId, pattern, componentOutputDir, basePath);
+                const built = yield buildPattern(handoff, patternId, pattern, componentOutputDir, basePath, sharedArtifacts);
                 if (built) {
                     result.push(built);
                 }
@@ -135,7 +154,7 @@ function processPatterns(handoff, options) {
         for (const patternId of patternIds) {
             if (onlyPatternIds.has(patternId)) {
                 const pattern = runtimePatterns[patternId];
-                const built = yield buildPattern(handoff, patternId, pattern, componentOutputDir, basePath);
+                const built = yield buildPattern(handoff, patternId, pattern, componentOutputDir, basePath, sharedArtifacts);
                 if (built) {
                     existingById.set(patternId, built);
                 }
@@ -145,7 +164,7 @@ function processPatterns(handoff, options) {
             }
             else if (!existingById.has(patternId)) {
                 const pattern = runtimePatterns[patternId];
-                const built = yield buildPattern(handoff, patternId, pattern, componentOutputDir, basePath);
+                const built = yield buildPattern(handoff, patternId, pattern, componentOutputDir, basePath, sharedArtifacts);
                 if (built) {
                     existingById.set(patternId, built);
                 }

package/dist/transformers/preview/pattern/html.d.ts

@@ -1,19 +1,22 @@
+import type { ComponentArtifactPresence, SharedArtifactPresence } from '../component/shared-artifacts';
 /**
  * Composes multiple component preview HTML documents into a single-page HTML.
  *
- * Each component preview may be a React SSR document (with hydration scripts
- * and a `#root` / `#__APP_PROPS__` pair) or a static Handlebars document.
+ * Each component preview may be a React SSR document (server-rendered markup plus a `#root` /
+ * `#__APP_PROPS__` pair) or a static Handlebars document.
  *
- * This function namespaces the element ids per-fragment so multiple React
- * components can coexist and hydrate independently on the same page.
+ * React client/hydration bundles are component-owned artifacts (`component/<id>.client.js`). This
+ * composer copies no per-fragment bundle: it namespaces each fragment's root/props so multiple
+ * instances coexist, marks each root with the `data-handoff-component`/`data-handoff-props`
+ * attributes the component bundle hydrates by, and references each unique component's client artifact
+ * exactly once.
  *
- * Each hydration bundle gets its own `<script type="module">` tag for full
- * module-level isolation. This is critical because esbuild bundles React
- * into each script using module-scoped `var` declarations, and `hydrateRoot`
- * is asynchronous — sharing a single module scope would cause later bundles
- * to overwrite earlier React instances before hydration completes.
+ * Shared/global artifacts follow the shared-artifact model: `component/main.css` and
+ * `component/main.js` are referenced only when present, and the global script is emitted exactly once
+ * (deduplicated across fragments) so its top-level side effects run a single time, ahead of the
+ * per-component client bundles.
  */
 export declare const composePatternHtml: (_patternId: string, patternTitle: string, fragments: {
     componentId: string;
     html: string;
-}[], basePath: string) => string;
+}[], basePath: string, sharedArtifacts: SharedArtifactPresence, componentArtifacts: Map<string, ComponentArtifactPresence>) => string;

package/dist/transformers/preview/pattern/html.js

@@ -6,33 +6,47 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.composePatternHtml = void 0;
 const escape_1 = __importDefault(require("lodash/escape"));
 const node_html_parser_1 = require("node-html-parser");
+const artifacts_1 = require("../../../artifacts");
+const url_1 = require("../../../artifacts/url");
 /**
  * Composes multiple component preview HTML documents into a single-page HTML.
  *
- * Each component preview may be a React SSR document (with hydration scripts
- * and a `#root` / `#__APP_PROPS__` pair) or a static Handlebars document.
+ * Each component preview may be a React SSR document (server-rendered markup plus a `#root` /
+ * `#__APP_PROPS__` pair) or a static Handlebars document.
  *
- * This function namespaces the element ids per-fragment so multiple React
- * components can coexist and hydrate independently on the same page.
+ * React client/hydration bundles are component-owned artifacts (`component/<id>.client.js`). This
+ * composer copies no per-fragment bundle: it namespaces each fragment's root/props so multiple
+ * instances coexist, marks each root with the `data-handoff-component`/`data-handoff-props`
+ * attributes the component bundle hydrates by, and references each unique component's client artifact
+ * exactly once.
  *
- * Each hydration bundle gets its own `<script type="module">` tag for full
- * module-level isolation. This is critical because esbuild bundles React
- * into each script using module-scoped `var` declarations, and `hydrateRoot`
- * is asynchronous — sharing a single module scope would cause later bundles
- * to overwrite earlier React instances before hydration completes.
+ * Shared/global artifacts follow the shared-artifact model: `component/main.css` and
+ * `component/main.js` are referenced only when present, and the global script is emitted exactly once
+ * (deduplicated across fragments) so its top-level side effects run a single time, ahead of the
+ * per-component client bundles.
  */
-const composePatternHtml = (_patternId, patternTitle, fragments, basePath) => {
+const composePatternHtml = (_patternId, patternTitle, fragments, basePath, sharedArtifacts, componentArtifacts) => {
+    var _a;
     const cssHrefs = new Set();
     const bodyParts = [];
-    const scriptTags = [];
-    cssHrefs.add(`${basePath}/api/component/main.css`);
+    const clientArtifactHrefs = new Set();
+    if (sharedArtifacts.mainCss) {
+        cssHrefs.add((0, url_1.buildArtifactUrl)(artifacts_1.SHARED_MAIN_CSS_ARTIFACT_PATH, basePath));
+    }
     cssHrefs.add(`${basePath}/assets/css/preview.css`);
+    // Canonical URL of the shared global script; used to strip any per-fragment reference so the
+    // global script is emitted (and executed) exactly once for the whole composed page.
+    const globalScriptUrl = (0, url_1.buildArtifactUrl)(artifacts_1.SHARED_MAIN_JS_ARTIFACT_PATH, basePath);
     const seenComponents = new Set();
     for (let i = 0; i < fragments.length; i++) {
         const { componentId, html } = fragments[i];
         if (!seenComponents.has(componentId)) {
             seenComponents.add(componentId);
-            cssHrefs.add(`${basePath}/api/component/${componentId}.css`);
+            // Reference a component's stylesheet only when it actually exists, so a pattern never requests
+            // an absent optional artifact for a component that declares no styles.
+            if ((_a = componentArtifacts.get(componentId)) === null || _a === void 0 ? void 0 : _a.css) {
+                cssHrefs.add((0, url_1.buildArtifactUrl)(`component/${componentId}.css`, basePath));
+            }
         }
         const doc = (0, node_html_parser_1.parse)(html);
         const suffix = `_p${i}`;
@@ -40,28 +54,37 @@ const composePatternHtml = (_patternId, patternTitle, fragments, basePath) => {
         const namespacedPropsId = `__APP_PROPS__${suffix}`;
         // -- Extract props JSON (React SSR) ------------------------------------
         const propsScript = doc.querySelector('#__APP_PROPS__');
-        let propsContent = '{}';
+        let propsContent = null;
         if (propsScript) {
             propsContent = propsScript.textContent || '{}';
             propsScript.remove();
         }
-        // -- Extract and rewrite hydration scripts (React SSR) -----------------
-        // Each script becomes its own <script type="module"> for full isolation.
-        const moduleScripts = doc.querySelectorAll('script[type="module"]');
-        for (const script of moduleScripts) {
-            let code = script.textContent || '';
-            if (code.trim()) {
-                code = code
-                    .replace(/__APP_PROPS__/g, namespacedPropsId)
-                    .replace(/getElementById\(\s*["']root["']\s*\)/g, `getElementById("${namespacedRootId}")`);
-                scriptTags.push(`    <script type="module">\n${code}\n    </script>`);
-            }
+        // -- Drop the fragment's own client-artifact reference -----------------
+        // The bundle is referenced once per component for the whole page (below); a fragment must not
+        // carry its standalone-preview script tag into the composed document.
+        for (const script of doc.querySelectorAll('script[type="module"]')) {
             script.remove();
         }
+        // -- Drop the fragment's own global-script reference -------------------
+        // Static (Handlebars) fragments render the global `component/main.js` tag inside their body; left
+        // in place it would be inlined per fragment and run the global side effects multiple times. The
+        // page references the global script exactly once (below).
+        for (const script of doc.querySelectorAll('script')) {
+            if (script.getAttribute('src') === globalScriptUrl) {
+                script.remove();
+            }
+        }
         // -- Namespace the root element (React SSR) ----------------------------
+        // A React fragment exposes its mount point to the component bundle via stable data attributes.
         const rootEl = doc.querySelector('#root');
+        const isReactFragment = !!rootEl && propsContent !== null;
         if (rootEl) {
             rootEl.setAttribute('id', namespacedRootId);
+            if (isReactFragment) {
+                rootEl.setAttribute('data-handoff-component', componentId);
+                rootEl.setAttribute('data-handoff-props', namespacedPropsId);
+                clientArtifactHrefs.add((0, url_1.buildArtifactUrl)(`component/${componentId}.client.js`, basePath));
+            }
         }
         // -- Extract body content ----------------------------------------------
         const bodyEl = doc.querySelector('body');
@@ -70,14 +93,26 @@ const composePatternHtml = (_patternId, patternTitle, fragments, basePath) => {
             : rootEl
                 ? rootEl.outerHTML
                 : doc.innerHTML || '';
+        const propsScriptTag = propsContent !== null
+            ? `      <script id="${namespacedPropsId}" type="application/json">${propsContent}</script>\n`
+            : '';
         bodyParts.push(`    <div class="handoff-pattern-block" data-component="${componentId}" data-fragment="${i}">\n` +
-            `      <script id="${namespacedPropsId}" type="application/json">${propsContent}</script>\n` +
+            propsScriptTag +
             `      ${bodyContent}\n` +
             `    </div>`);
     }
     const linkTags = Array.from(cssHrefs)
         .map((href) => `    <link rel="stylesheet" href="${href}" />`)
         .join('\n');
+    // The global script is referenced once for the whole page (deduplicated across fragments) and
+    // placed before the per-component client bundles so its side effects run first and exactly once.
+    const globalScriptTag = sharedArtifacts.mainJs
+        ? `    <script src="${(0, url_1.buildArtifactUrl)(artifacts_1.SHARED_MAIN_JS_ARTIFACT_PATH, basePath)}"></script>`
+        : '';
+    const clientScriptTags = Array.from(clientArtifactHrefs)
+        .map((href) => `    <script type="module" src="${href}"></script>`)
+        .join('\n');
+    const scriptTags = [globalScriptTag, clientScriptTags].filter(Boolean).join('\n');
     return `<!DOCTYPE html>
 <html lang="en">
   <head>
@@ -87,7 +122,7 @@ ${linkTags}
   </head>
   <body>
 ${bodyParts.join('\n')}
-${scriptTags.join('\n')}
+${scriptTags}
   </body>
 </html>`;
 };