handoff-app 1.1.3 → 1.2.0-1

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

@@ -19,6 +19,16 @@ const logger_1 = require("../../../utils/logger");
 const plugins_1 = require("../../plugins");
 const vite_config_1 = __importDefault(require("../../vite-config"));
 const component_1 = require("../component");
+const resolveRenderer = (data) => {
+    var _a, _b, _c;
+    const templatePath = ((_a = data.entries) === null || _a === void 0 ? void 0 : _a.template) || '';
+    return (data.renderer ||
+        (((_b = data.entries) === null || _b === void 0 ? void 0 : _b.story) || templatePath.match(/\.stories\.(jsx|tsx|js|ts)$/) ? 'csf' : undefined) ||
+        (((_c = data.entries) === null || _c === void 0 ? void 0 : _c.component) || (templatePath.includes('.tsx') && !templatePath.match(/\.stories\.(jsx|tsx|js|ts)$/))
+            ? 'react'
+            : undefined) ||
+        (templatePath.includes('.hbs') ? 'handlebars' : undefined));
+};
 /**
  * Builds previews for components using Vite and Handlebars.
  *
@@ -37,13 +47,12 @@ const buildPreviews = (data, handoff, components) => __awaiter(void 0, void 0, v
     var _a, _b, _c;
     if (!((_a = data.entries) === null || _a === void 0 ? void 0 : _a.template))
         return data;
+    const resolvedRenderer = resolveRenderer(data);
     const plugins = [
         ...(vite_config_1.default.plugins || []),
-        ...(data.entries.template.includes('.hbs') ? [(0, plugins_1.handlebarsPreviewsPlugin)(data, components, handoff)] : []),
-        ...(data.entries.template.match(/\.stories\.(jsx|tsx)$/) ? [(0, plugins_1.csfRenderPlugin)(data, components, handoff)] : []),
-        ...(data.entries.template.includes('.tsx') && !data.entries.template.match(/\.stories\.(jsx|tsx)$/)
-            ? [(0, plugin_react_1.default)(), (0, plugins_1.ssrRenderPlugin)(data, components, handoff)]
-            : []),
+        ...(resolvedRenderer === 'handlebars' ? [(0, plugins_1.handlebarsPreviewsPlugin)(data, components, handoff)] : []),
+        ...(resolvedRenderer === 'csf' ? [(0, plugins_1.csfRenderPlugin)(data, components, handoff)] : []),
+        ...(resolvedRenderer === 'react' ? [(0, plugin_react_1.default)(), (0, plugins_1.ssrRenderPlugin)(data, components, handoff)] : []),
     ];
     // Store the current NODE_ENV value before vite build
     // This is necessary because viteBuild forcibly sets NODE_ENV to 'production'

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

@@ -18,7 +18,6 @@ export declare const buildComponentJs: (data: TransformComponentTokensResult, ha
  *
  * @param handoff - The Handoff configuration object containing build settings
  * @returns A Promise that resolves when the build process is complete
- * @throws May throw an error if the build process fails
  */
 export declare const buildMainJS: (handoff: Handoff) => Promise<void>;
 export default buildComponentJs;

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

@@ -17,6 +17,7 @@ const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
 const vite_1 = require("vite");
 const config_1 = require("../../../config");
+const duration_1 = require("../../../utils/duration");
 const logger_1 = require("../../../utils/logger");
 const vite_config_1 = __importDefault(require("../../vite-config"));
 const component_1 = require("../component");
@@ -50,9 +51,6 @@ const buildJsBundle = (_a, handoff_1) => __awaiter(void 0, [_a, handoff_1], void
         }
         yield (0, vite_1.build)(viteConfig);
     }
-    catch (e) {
-        logger_1.Logger.error(`Failed to build JS for "${outputFilename}":`, e);
-    }
     finally {
         // Restore the original NODE_ENV value after vite build completes
         // This prevents interference with Next.js app building/running processes
@@ -83,11 +81,17 @@ const buildComponentJs = (data, handoff) => __awaiter(void 0, void 0, void 0, fu
     const outputPath = (0, component_1.getComponentOutputPath)(handoff);
     try {
         const js = yield fs_extra_1.default.readFile(path_1.default.resolve(entry), 'utf8');
-        yield buildJsBundle({
-            entry,
-            outputPath,
-            outputFilename: `${id}.js`,
-        }, handoff);
+        try {
+            yield buildJsBundle({
+                entry,
+                outputPath,
+                outputFilename: `${id}.js`,
+            }, handoff);
+        }
+        catch (e) {
+            logger_1.Logger.error(`Failed to bundle JS for component "${id}" (${id}.js):`, e);
+            return data;
+        }
         data.js = js;
         const compiled = yield fs_extra_1.default.readFile(path_1.default.resolve(outputPath, `${id}.js`), 'utf8');
         data['jsCompiled'] = compiled;
@@ -106,17 +110,24 @@ exports.buildComponentJs = buildComponentJs;
  *
  * @param handoff - The Handoff configuration object containing build settings
  * @returns A Promise that resolves when the build process is complete
- * @throws May throw an error if the build process fails
  */
 const buildMainJS = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
     const outputPath = (0, component_1.getComponentOutputPath)(handoff);
     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))) {
-        yield buildJsBundle({
-            entry: runtimeConfig.entries.js,
-            outputPath,
-            outputFilename: 'main.js',
-        }, handoff);
+        logger_1.Logger.info(`Building script for global entry (main.js)…`);
+        const startedAt = Date.now();
+        try {
+            yield buildJsBundle({
+                entry: runtimeConfig.entries.js,
+                outputPath,
+                outputFilename: 'main.js',
+            }, handoff);
+            logger_1.Logger.info(`Finished building script for global entry (main.js) in ${(0, duration_1.formatDurationMs)(Date.now() - startedAt)}`);
+        }
+        catch (e) {
+            logger_1.Logger.error(`Failed to build global script (main.js):`, e);
+        }
     }
 });
 exports.buildMainJS = buildMainJS;

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

@@ -0,0 +1,9 @@
+import type { OptionalPreviewRender } from '../types';
+/**
+ * Returns previews exposed in docs/API; synthetic pattern previews (`__pattern_*`) are omitted.
+ */
+export declare const getDocumentedPreviews: (previews?: {
+    [key: string]: OptionalPreviewRender;
+}) => {
+    [key: string]: OptionalPreviewRender;
+};

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

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDocumentedPreviews = void 0;
+/**
+ * Returns previews exposed in docs/API; synthetic pattern previews (`__pattern_*`) are omitted.
+ */
+const getDocumentedPreviews = (previews) => {
+    return Object.fromEntries(Object.entries(previews || {}).filter(([key]) => !key.startsWith('__pattern_')));
+};
+exports.getDocumentedPreviews = getDocumentedPreviews;

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

@@ -0,0 +1,11 @@
+import Handoff from '../../../index';
+import { PatternListObject, PatternObject } from '../types';
+export declare const getPatternAPIPath: (handoff: Handoff) => string;
+export declare const writePatternApi: (id: string, pattern: PatternObject, handoff: Handoff) => Promise<void>;
+export declare const writePatternHtml: (id: string, html: string, handoff: Handoff) => Promise<void>;
+export declare const writePatternSummaryApi: (handoff: Handoff, patterns: PatternListObject[]) => Promise<void>;
+/**
+ * Reads the pattern list summary when present (used for partial pattern rebuilds).
+ */
+export declare const readPatternSummaryApi: (handoff: Handoff) => Promise<PatternListObject[] | null>;
+export declare const syncPatternArtifacts: (handoff: Handoff, validIds: Iterable<string>) => Promise<void>;

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

@@ -0,0 +1,79 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.syncPatternArtifacts = exports.readPatternSummaryApi = exports.writePatternSummaryApi = exports.writePatternHtml = exports.writePatternApi = exports.getPatternAPIPath = void 0;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const getPatternAPIPath = (handoff) => {
+    const patternPath = path_1.default.resolve(handoff.workingPath, 'public/api/pattern');
+    if (!fs_extra_1.default.existsSync(patternPath)) {
+        fs_extra_1.default.mkdirSync(patternPath, { recursive: true });
+    }
+    return patternPath;
+};
+exports.getPatternAPIPath = getPatternAPIPath;
+const writePatternApi = (id, pattern, handoff) => __awaiter(void 0, void 0, void 0, function* () {
+    const outputDir = (0, exports.getPatternAPIPath)(handoff);
+    const outputFilePath = path_1.default.resolve(outputDir, `${id}.json`);
+    yield fs_extra_1.default.writeFile(outputFilePath, JSON.stringify(pattern, null, 2));
+});
+exports.writePatternApi = writePatternApi;
+const writePatternHtml = (id, html, handoff) => __awaiter(void 0, void 0, void 0, function* () {
+    const outputDir = (0, exports.getPatternAPIPath)(handoff);
+    const outputFilePath = path_1.default.resolve(outputDir, `${id}.html`);
+    yield fs_extra_1.default.writeFile(outputFilePath, html);
+});
+exports.writePatternHtml = writePatternHtml;
+const writePatternSummaryApi = (handoff, patterns) => __awaiter(void 0, void 0, void 0, function* () {
+    const apiPath = path_1.default.resolve(handoff.workingPath, 'public/api');
+    if (!fs_extra_1.default.existsSync(apiPath)) {
+        fs_extra_1.default.mkdirSync(apiPath, { recursive: true });
+    }
+    patterns.sort((a, b) => a.title.localeCompare(b.title));
+    yield fs_extra_1.default.writeFile(path_1.default.resolve(apiPath, 'patterns.json'), JSON.stringify(patterns, null, 2));
+});
+exports.writePatternSummaryApi = writePatternSummaryApi;
+/**
+ * Reads the pattern list summary when present (used for partial pattern rebuilds).
+ */
+const readPatternSummaryApi = (handoff) => __awaiter(void 0, void 0, void 0, function* () {
+    const summaryPath = path_1.default.resolve(handoff.workingPath, 'public/api/patterns.json');
+    if (!fs_extra_1.default.existsSync(summaryPath)) {
+        return null;
+    }
+    try {
+        const raw = yield fs_extra_1.default.readFile(summaryPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : null;
+    }
+    catch (_a) {
+        return null;
+    }
+});
+exports.readPatternSummaryApi = readPatternSummaryApi;
+const syncPatternArtifacts = (handoff, validIds) => __awaiter(void 0, void 0, void 0, function* () {
+    const validIdSet = new Set(validIds);
+    const patternPath = (0, exports.getPatternAPIPath)(handoff);
+    const entries = yield fs_extra_1.default.readdir(patternPath);
+    for (const entry of entries) {
+        const parsed = path_1.default.parse(entry);
+        const isPatternArtifact = parsed.ext === '.json' || parsed.ext === '.html';
+        if (!isPatternArtifact)
+            continue;
+        if (!validIdSet.has(parsed.name)) {
+            yield fs_extra_1.default.remove(path_1.default.resolve(patternPath, entry));
+        }
+    }
+});
+exports.syncPatternArtifacts = syncPatternArtifacts;

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

@@ -0,0 +1,17 @@
+import Handoff from '../../../index';
+import { PatternListObject } from '../types';
+export type ProcessPatternsOptions = {
+    /** When set, only these pattern ids are recomposed; others keep existing artifacts. */
+    onlyPatternIds?: Set<string>;
+};
+/**
+ * Returns pattern ids whose declarations reference any of the given component ids.
+ */
+export declare const getPatternIdsReferencingComponents: (handoff: Handoff, componentIds: string[]) => string[];
+/**
+ * Process all pattern declarations and compose their HTML from pre-built
+ * component preview files. This function must run AFTER buildComponents
+ * so that all component preview HTML files already exist on disk.
+ */
+export declare function processPatterns(handoff: Handoff, options?: ProcessPatternsOptions): Promise<PatternListObject[]>;
+export default processPatterns;

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

@@ -0,0 +1,167 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPatternIdsReferencingComponents = void 0;
+exports.processPatterns = processPatterns;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const logger_1 = require("../../../utils/logger");
+const api_1 = require("./api");
+const html_1 = require("./html");
+/**
+ * Returns pattern ids whose declarations reference any of the given component ids.
+ */
+const getPatternIdsReferencingComponents = (handoff, componentIds) => {
+    var _a, _b, _c, _d;
+    if (componentIds.length === 0) {
+        return [];
+    }
+    const idSet = new Set(componentIds);
+    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 : {};
+    const result = [];
+    for (const patternId of Object.keys(runtimePatterns)) {
+        const pattern = runtimePatterns[patternId];
+        if ((_d = pattern.components) === null || _d === void 0 ? void 0 : _d.some((ref) => idSet.has(ref.id))) {
+            result.push(patternId);
+        }
+    }
+    return result;
+};
+exports.getPatternIdsReferencingComponents = getPatternIdsReferencingComponents;
+function buildPattern(handoff, patternId, pattern, componentOutputDir, basePath) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const fragments = [];
+        let hasErrors = false;
+        for (let i = 0; i < pattern.components.length; i++) {
+            const ref = pattern.components[i];
+            if (ref.resolved === false && !ref.resolvedPreview) {
+                hasErrors = true;
+                continue;
+            }
+            const previewKey = ref.resolvedPreview || ref.preview;
+            if (!previewKey) {
+                const error = `Pattern "${patternId}" component[${i}] ("${ref.id}") has no resolved preview key. Skipping.`;
+                logger_1.Logger.warn(error);
+                ref.resolved = false;
+                hasErrors = true;
+                continue;
+            }
+            const htmlFileName = `${ref.id}-${previewKey}.html`;
+            const htmlFilePath = path_1.default.resolve(componentOutputDir, htmlFileName);
+            if (!fs_extra_1.default.existsSync(htmlFilePath)) {
+                const error = `Pattern "${patternId}" component[${i}] ("${ref.id}") preview file not found: ${htmlFileName}. ` +
+                    `Ensure the component has a preview named "${previewKey}".`;
+                logger_1.Logger.warn(error);
+                ref.resolved = false;
+                hasErrors = true;
+                continue;
+            }
+            ref.resolved = true;
+            const html = yield fs_extra_1.default.readFile(htmlFilePath, 'utf8');
+            fragments.push({ componentId: ref.id, html });
+        }
+        if (fragments.length === 0) {
+            logger_1.Logger.warn(`Pattern "${patternId}" produced no fragments. Skipping.`);
+            return null;
+        }
+        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 patternUrl = `${patternId}.html`;
+        const patternData = Object.assign(Object.assign({}, pattern), { id: patternId, url: patternUrl, path: `${basePath}/api/pattern/${patternId}.json` });
+        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))`);
+        return patternData;
+    });
+}
+/**
+ * Process all pattern declarations and compose their HTML from pre-built
+ * component preview files. This function must run AFTER buildComponents
+ * so that all component preview HTML files already exist on disk.
+ */
+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 : {};
+        const patternIds = Object.keys(runtimePatterns);
+        const onlyPatternIds = options === null || options === void 0 ? void 0 : options.onlyPatternIds;
+        const isPartial = onlyPatternIds !== undefined;
+        if (patternIds.length === 0) {
+            yield (0, api_1.syncPatternArtifacts)(handoff, []);
+            yield (0, api_1.writePatternSummaryApi)(handoff, []);
+            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 : '';
+        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);
+                if (built) {
+                    result.push(built);
+                }
+            }
+            yield (0, api_1.syncPatternArtifacts)(handoff, result.map((p) => p.id));
+            yield (0, api_1.writePatternSummaryApi)(handoff, result);
+            logger_1.Logger.info(`Finished building ${result.length} pattern(s).`);
+            return result;
+        }
+        if (onlyPatternIds.size === 0) {
+            const existing = yield (0, api_1.readPatternSummaryApi)(handoff);
+            return existing !== null && existing !== void 0 ? existing : [];
+        }
+        const existingList = yield (0, api_1.readPatternSummaryApi)(handoff);
+        if (!existingList) {
+            logger_1.Logger.warn('Partial pattern rebuild requested but patterns.json is missing; rebuilding all patterns.');
+            return processPatterns(handoff);
+        }
+        const existingById = new Map(existingList.map((p) => [p.id, p]));
+        logger_1.Logger.info(`Rebuilding ${onlyPatternIds.size} of ${patternIds.length} pattern(s) (incremental)...`);
+        for (const patternId of patternIds) {
+            if (onlyPatternIds.has(patternId)) {
+                const pattern = runtimePatterns[patternId];
+                const built = yield buildPattern(handoff, patternId, pattern, componentOutputDir, basePath);
+                if (built) {
+                    existingById.set(patternId, built);
+                }
+                else {
+                    existingById.delete(patternId);
+                }
+            }
+            else if (!existingById.has(patternId)) {
+                const pattern = runtimePatterns[patternId];
+                const built = yield buildPattern(handoff, patternId, pattern, componentOutputDir, basePath);
+                if (built) {
+                    existingById.set(patternId, built);
+                }
+            }
+        }
+        const merged = [];
+        for (const patternId of patternIds) {
+            const entry = existingById.get(patternId);
+            if (entry) {
+                merged.push(entry);
+            }
+        }
+        yield (0, api_1.syncPatternArtifacts)(handoff, merged.map((p) => p.id));
+        yield (0, api_1.writePatternSummaryApi)(handoff, merged);
+        logger_1.Logger.info(`Finished incremental pattern build (${onlyPatternIds.size} recomposed).`);
+        return merged;
+    });
+}
+exports.default = processPatterns;

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

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ *
+ * This function namespaces the element ids per-fragment so multiple React
+ * components can coexist and hydrate independently on the same page.
+ *
+ * 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.
+ */
+export declare const composePatternHtml: (_patternId: string, patternTitle: string, fragments: {
+    componentId: string;
+    html: string;
+}[], basePath: string) => string;

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

@@ -0,0 +1,94 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+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");
+/**
+ * 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.
+ *
+ * This function namespaces the element ids per-fragment so multiple React
+ * components can coexist and hydrate independently on the same page.
+ *
+ * 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.
+ */
+const composePatternHtml = (_patternId, patternTitle, fragments, basePath) => {
+    const cssHrefs = new Set();
+    const bodyParts = [];
+    const scriptTags = [];
+    cssHrefs.add(`${basePath}/api/component/main.css`);
+    cssHrefs.add(`${basePath}/assets/css/preview.css`);
+    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`);
+        }
+        const doc = (0, node_html_parser_1.parse)(html);
+        const suffix = `_p${i}`;
+        const namespacedRootId = `root${suffix}`;
+        const namespacedPropsId = `__APP_PROPS__${suffix}`;
+        // -- Extract props JSON (React SSR) ------------------------------------
+        const propsScript = doc.querySelector('#__APP_PROPS__');
+        let propsContent = '{}';
+        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>`);
+            }
+            script.remove();
+        }
+        // -- Namespace the root element (React SSR) ----------------------------
+        const rootEl = doc.querySelector('#root');
+        if (rootEl) {
+            rootEl.setAttribute('id', namespacedRootId);
+        }
+        // -- Extract body content ----------------------------------------------
+        const bodyEl = doc.querySelector('body');
+        const bodyContent = bodyEl
+            ? bodyEl.innerHTML.trim()
+            : rootEl
+                ? rootEl.outerHTML
+                : doc.innerHTML || '';
+        bodyParts.push(`    <div class="handoff-pattern-block" data-component="${componentId}" data-fragment="${i}">\n` +
+            `      <script id="${namespacedPropsId}" type="application/json">${propsContent}</script>\n` +
+            `      ${bodyContent}\n` +
+            `    </div>`);
+    }
+    const linkTags = Array.from(cssHrefs)
+        .map((href) => `    <link rel="stylesheet" href="${href}" />`)
+        .join('\n');
+    return `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+${linkTags}
+    <title>${(0, escape_1.default)(patternTitle)}</title>
+  </head>
+  <body>
+${bodyParts.join('\n')}
+${scriptTags.join('\n')}
+  </body>
+</html>`;
+};
+exports.composePatternHtml = composePatternHtml;

package/dist/transformers/preview/types.d.ts

@@ -1,5 +1,6 @@
 import type { GeneratedDocs } from 'handoff-docgen';
 import { Card } from '../../app/components/Component/Cards';
+import type { RendererKind } from '../../declarations/types';
 import { ValidationResult } from '../../types/preview';
 import { Filter } from '../../utils/filter';
 import { SlotMetadata } from './component';
@@ -93,7 +94,17 @@ export type ComponentObject = {
         scss?: string;
         /** Optional path to component template file (if available) */
         template?: string;
+        /** Optional path to React component source for preview rendering */
+        component?: string;
+        /** Optional path to CSF story file */
+        story?: string;
+        /** Optional path to schema file (if available) */
+        schema?: string;
+        /** Optional path to templates directory */
+        templates?: string;
     };
+    /** Optional explicit renderer id */
+    renderer?: RendererKind;
     /** Schema describing the expected properties (props/slots) for the component */
     properties: {
         [key: string]: SlotMetadata;
@@ -102,10 +113,18 @@ export type ComponentObject = {
     previews: {
         [key: string]: OptionalPreviewRender;
     };
+    /** Internal previews generated only for pattern composition, not public docs */
+    internalPatternPreviews?: {
+        [key: string]: OptionalPreviewRender;
+    };
     /** Optional array of high-level categories for search/filtering */
     categories?: string[];
     /** Optional array of tags for search/filtering (e.g. "primary", "interactive") */
     tags?: string[];
+    /** Optional markdown strings describing recommended usage patterns */
+    should_do?: string[];
+    /** Optional markdown strings describing anti-patterns to avoid */
+    should_not_do?: string[];
     /** Optional source Figma file or node URL for the component */
     figma?: string;
     /** Optional canonical Figma component name or ID (used for matching back to design tokens) */
@@ -138,11 +157,15 @@ export type TransformComponentTokensResult = {
     css?: string;
     sass?: string;
     sharedStyles?: string;
+    usage?: string;
     title?: string;
     description?: string;
     previews?: {
         [key: string]: OptionalPreviewRender;
     };
+    internalPatternPreviews?: {
+        [key: string]: OptionalPreviewRender;
+    };
     properties?: {
         [key: string]: SlotMetadata;
     };
@@ -151,8 +174,12 @@ export type TransformComponentTokensResult = {
         js?: string;
         scss?: string;
         template?: string;
+        component?: string;
+        story?: string;
         schema?: string;
+        templates?: string;
     };
+    renderer?: RendererKind;
     options?: {
         preview?: {
             groupBy?: string;
@@ -168,7 +195,34 @@ export type OptionalPreviewRender = {
         [key: string]: string | string[] | any;
     };
     url: string;
+    usage?: string;
+    /** Optional source preview/story key used to derive this preview */
+    sourcePreview?: string;
 };
 export interface TransformedPreviewComponents {
     [key: string]: TransformComponentTokensResult[];
 }
+export type PatternComponentEntry = {
+    /** Component id reference */
+    id: string;
+    /** Named preview variant to use (optional if args provided) */
+    preview?: string;
+    /** Arg overrides (optional if preview provided) */
+    args?: Record<string, any>;
+    /** Preview key resolved during injectPatternPreviews (set at build time) */
+    resolvedPreview?: string;
+    /** Whether the pattern entry resolved to a usable component preview */
+    resolved?: boolean;
+};
+export type PatternObject = {
+    title: string;
+    description?: string;
+    group?: string;
+    tags?: string[];
+    components: PatternComponentEntry[];
+    url?: string;
+};
+export type PatternListObject = {
+    id: string;
+    path: string;
+} & PatternObject;

package/dist/transformers/utils/csf.d.ts

@@ -0,0 +1,16 @@
+import { OptionalPreviewRender } from '../preview/types';
+export type StoryObject = {
+    name?: string;
+    args?: Record<string, any>;
+    argTypes?: Record<string, any>;
+    render?: (args: Record<string, any>) => any;
+};
+export type CsfMeta = {
+    title?: string;
+    component?: any;
+    args?: Record<string, any>;
+    argTypes?: Record<string, any>;
+    render?: (args: Record<string, any>) => any;
+};
+export declare function getCsfStoryEntries(moduleExports: Record<string, any>): Array<[string, StoryObject]>;
+export declare function createCsfStoryPreviews(moduleExports: Record<string, any>): Record<string, OptionalPreviewRender>;