@design-embed/target-react 0.1.0 → 1.0.0

package/src/index.ts

@@ -1,34 +1,25 @@
-import type { DesignEmbedConfig } from "@design-embed/config";
-import type {
-	DesignNode,
-	Diagnostic,
-	PropValue,
-	TargetEmitInput,
-	TargetEmitResult,
-	TargetEmitter,
-	TargetTestGenerateInput,
-	TargetTestGenerateResult,
-	TargetTestGenerator,
-} from "@design-embed/core";
 import {
 	applyComponentMappings,
-	matchesSelector,
-	parseInlineStyle,
-	parseSelector,
-} from "@design-embed/core";
+	type DesignEmbedConfig,
+	type DesignNode,
+	type Diagnostic,
+	type PropValue,
+	parseHtml,
+	type TargetEmitInput,
+	type TargetEmitResult,
+	type TargetEmitter,
+	type TargetTestGenerateInput,
+	type TargetTestGenerateResult,
+	type TargetTestGenerator,
+} from "design-embed";
 
-export const reactEmitter: TargetEmitter = {
+export class ReactTarget implements TargetEmitter, TargetTestGenerator {
 	emit({ nodes, css, config, diagnostics }: TargetEmitInput): TargetEmitResult {
-		const viewsDir = config?.output?.viewsDir ?? "src/generated/views";
+		const viewsDir = String(config?.output?.viewsDir ?? "src/generated/views");
 		const viewName = config?.output?.viewName ?? "DesignView";
 
 		const styleResult = transformStyles(nodes, css, config, diagnostics);
-		const transformed = applyComponentMappings(
-			styleResult.nodes,
-			config?.components ?? [],
-			diagnostics,
-		);
-		const contents = emitReactView(transformed, viewName, {
+		const contents = emitReactView(styleResult.nodes, viewName, {
 			cssModulePath: styleResult.cssModulePath,
 		});
 
@@ -41,18 +32,29 @@ export const reactEmitter: TargetEmitter = {
 				contents: styleResult.cssModule,
 			});
 		}
+		for (const split of emitComponentSplitViews(
+			styleResult.nodes,
+			viewsDir,
+			styleResult.cssModulePath,
+		)) {
+			files.push(split);
+		}
 
 		return { files };
-	},
-};
+	}
+
+	generateTests(input: TargetTestGenerateInput): TargetTestGenerateResult {
+		return reactTestGenerator.generateTests(input);
+	}
+}
 
 export const reactTestGenerator: TargetTestGenerator = {
 	generateTests({
 		html,
 		css,
 		config,
-		diagnostics,
 	}: TargetTestGenerateInput): TargetTestGenerateResult {
+		const diagnostics: Diagnostic[] = [];
 		const tests = config.tests;
 		if (tests?.runner && tests.runner !== "playwright") {
 			diagnostics.push({
@@ -60,47 +62,96 @@ export const reactTestGenerator: TargetTestGenerator = {
 				message: `Unsupported test runner: ${tests.runner}`,
 				severity: "error",
 			});
-			return { files: [] };
+			return { files: [], diagnostics };
 		}
 
-		const viewsDir = config.output?.viewsDir ?? "src/generated/views";
+		const viewsDir = String(config.output?.viewsDir ?? "src/generated/views");
 		const viewName = config.output?.viewName ?? "DesignView";
-		const outputDir = tests?.outputDir ?? "tests/generated/design-embed";
+		const outputDir = tests?.outputDir ?? `${viewsDir}/tests`;
 		const fixturePath = `${outputDir}/${viewName}.reference.html`;
 		const specPath = `${outputDir}/${viewName}.visual.spec.tsx`;
 		const referenceHtml = `${css?.trim() ? `<style>\n${css}\n</style>\n` : ""}${html}`;
 
-		return {
-			files: [
-				{
-					path: fixturePath,
-					contents: referenceHtml.endsWith("\n")
-						? referenceHtml
-						: `${referenceHtml}\n`,
-				},
-				{
-					path: specPath,
-					contents: emitReactVisualSpec({
-						viewName,
-						viewImportPath: toRelativeImport(
-							specPath,
-							`${viewsDir}/${viewName}.view`,
-						),
-						fixtureFileName: `${viewName}.reference.html`,
-						viewports: tests?.viewports ?? [
-							{ name: "default", width: 1440, height: 900 },
-						],
-						states: tests?.states ?? [{ name: "default" }],
-						assertions: {
-							screenshot: tests?.assertions?.screenshot ?? true,
-							layout: tests?.assertions?.layout ?? true,
-							layoutTolerance: tests?.assertions?.layoutTolerance ?? 0,
-							selectors: tests?.assertions?.selectors ?? [":scope", ":scope *"],
-						},
-					}),
-				},
-			],
+		const assertionDefaults = {
+			screenshot: tests?.assertions?.screenshot ?? true,
+			layout: tests?.assertions?.layout ?? true,
+			layoutTolerance: tests?.assertions?.layoutTolerance ?? 1,
+			selectors: tests?.assertions?.selectors ?? [":scope", ":scope *"],
+			screenshotThreshold: tests?.assertions?.screenshotThreshold ?? 0.2,
+			screenshotMaxDiffPixels:
+				tests?.assertions?.screenshotMaxDiffPixels ?? 500,
 		};
+		const viewportDefaults = tests?.viewports ?? [
+			{ name: "default", width: 1440, height: 900 },
+		];
+		const stateDefaults = tests?.states ?? [{ name: "default" }];
+		const referenceHtmlFileName = `${viewName}.reference.html`;
+
+		const files: Array<{ path: string; contents: string }> = [
+			{
+				path: fixturePath,
+				contents: referenceHtml.endsWith("\n")
+					? referenceHtml
+					: `${referenceHtml}\n`,
+			},
+			{
+				path: specPath,
+				contents: emitReactVisualSpec({
+					viewName,
+					viewImportPath: toRelativeImport(
+						specPath,
+						`${viewsDir}/${viewName}.view`,
+					),
+					fixtureFileName: referenceHtmlFileName,
+					viewports: viewportDefaults,
+					states: stateDefaults,
+					assertions: assertionDefaults,
+				}),
+			},
+		];
+
+		const parsedHtmlNodes = parseHtml(html);
+		const componentNodes = collectComponentNodes(
+			applyComponentMappings(parsedHtmlNodes, config.components ?? []),
+		);
+
+		for (const mapping of config.components ?? []) {
+			const componentName = mapping.component;
+			const componentSpecPath = `${outputDir}/${componentName}.visual.spec.tsx`;
+			const componentReferenceHtmlFileName = `${componentName}.reference.html`;
+			const componentFixturePath = `${outputDir}/${componentReferenceHtmlFileName}`;
+			const matchingNode = findNodeBySelector(
+				parsedHtmlNodes,
+				mapping.selector,
+			);
+			const elementHtml = matchingNode ? serializeNodeToHtml(matchingNode) : "";
+			const componentReferenceHtml = `${css?.trim() ? `<style>\n${css}\n</style>\n` : ""}${elementHtml}`;
+			const mountNode = componentNodes.get(componentName);
+			files.push({
+				path: componentFixturePath,
+				contents: componentReferenceHtml.endsWith("\n")
+					? componentReferenceHtml
+					: `${componentReferenceHtml}\n`,
+			});
+			files.push({
+				path: componentSpecPath,
+				contents: emitComponentVisualSpec({
+					componentName,
+					selector: mapping.selector,
+					mountJsx: emitComponentMount(componentName, mountNode),
+					componentImportPath: toRelativeImport(
+						componentSpecPath,
+						`${viewsDir}/${componentName}.view`,
+					),
+					referenceHtmlFileName: componentReferenceHtmlFileName,
+					viewports: viewportDefaults,
+					states: stateDefaults,
+					assertions: assertionDefaults,
+				}),
+			});
+		}
+
+		return { diagnostics, files };
 	},
 };
 
@@ -121,6 +172,8 @@ interface ReactVisualSpecInput {
 		layout: boolean;
 		layoutTolerance: number;
 		selectors: string[];
+		screenshotThreshold: number;
+		screenshotMaxDiffPixels: number;
 	};
 }
 
@@ -131,11 +184,19 @@ function emitReactVisualSpec(input: ReactVisualSpecInput): string {
 	const screenshotEnabled = JSON.stringify(input.assertions.screenshot);
 	const layoutEnabled = JSON.stringify(input.assertions.layout);
 	const layoutTolerance = JSON.stringify(input.assertions.layoutTolerance);
+	const screenshotThreshold = JSON.stringify(
+		input.assertions.screenshotThreshold,
+	);
+	const screenshotMaxDiffPixels = JSON.stringify(
+		input.assertions.screenshotMaxDiffPixels,
+	);
 
 	return `import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { expect, test } from "@playwright/experimental-ct-react";
+import pixelmatch from "pixelmatch";
+import { PNG } from "pngjs";
 import { ${input.viewName} } from "${input.viewImportPath}";
 
 const currentDir = dirname(fileURLToPath(import.meta.url));
@@ -146,6 +207,8 @@ const selectors = ${selectors};
 const screenshotEnabled = ${screenshotEnabled};
 const layoutEnabled = ${layoutEnabled};
 const layoutTolerance = ${layoutTolerance};
+const screenshotThreshold = ${screenshotThreshold};
+const screenshotMaxDiffPixels = ${screenshotMaxDiffPixels};
 
 for (const viewport of viewports) {
 \tfor (const state of states) {
@@ -165,7 +228,159 @@ for (const viewport of viewports) {
 \t\t\tconst actualLayout = layoutEnabled ? await readLayout(component, selectors) : [];
 
 \t\t\tif (screenshotEnabled) {
-\t\t\t\texpect(actualScreenshot).toEqual(expectedScreenshot);
+\t\t\t\tcompareScreenshots(actualScreenshot, expectedScreenshot, screenshotThreshold, screenshotMaxDiffPixels);
+\t\t\t}
+\t\t\tif (layoutEnabled) {
+\t\t\t\texpectLayoutToMatch(actualLayout, expectedLayout, layoutTolerance);
+\t\t\t}
+\t\t});
+\t}
+}
+
+async function applyState(page, state) {
+\tif (state.waitFor) {
+\t\tawait page.waitForSelector(state.waitFor);
+\t}
+\tif (state.hover) {
+\t\tawait page.hover(state.hover);
+\t}
+\tif (state.focus) {
+\t\tawait page.focus(state.focus);
+\t}
+\tif (state.click) {
+\t\tawait page.click(state.click);
+\t}
+}
+
+async function readLayout(root, selectorsToRead) {
+\treturn root.evaluate((element, values) => {
+\t\tconst origin = element.getBoundingClientRect();
+\t\treturn values.flatMap((selector) => {
+\t\t\tconst matches = selector === ":scope" ? [element] : Array.from(element.querySelectorAll(selector));
+\t\t\treturn matches.map((matchedElement, index) => {
+\t\t\t\tconst rect = matchedElement.getBoundingClientRect();
+\t\t\t\treturn {
+\t\t\t\t\tselector,
+\t\t\t\t\tindex,
+\t\t\t\t\ttagName: matchedElement.tagName.toLowerCase(),
+\t\t\t\t\tx: rect.x - origin.x,
+\t\t\t\t\ty: rect.y - origin.y,
+\t\t\t\t\twidth: rect.width,
+\t\t\t\t\theight: rect.height,
+\t\t\t\t};
+\t\t\t});
+\t\t});
+\t}, selectorsToRead);
+}
+
+function compareScreenshots(actual, expected, threshold, maxDiffPixels) {
+\tif (!actual || !expected) {
+\t\texpect(actual).toEqual(expected);
+\t\treturn;
+\t}
+\tconst actualPng = PNG.sync.read(actual);
+\tconst expectedPng = PNG.sync.read(expected);
+\texpect(actualPng.width, "screenshot width").toBe(expectedPng.width);
+\texpect(actualPng.height, "screenshot height").toBe(expectedPng.height);
+\tconst diffPixels = pixelmatch(actualPng.data, expectedPng.data, null, actualPng.width, actualPng.height, { threshold });
+\texpect(diffPixels, "screenshot pixels differing beyond threshold").toBeLessThanOrEqual(maxDiffPixels);
+}
+
+function expectLayoutToMatch(actual, expected, tolerance) {
+\texpect(actual.length).toBe(expected.length);
+\tfor (let index = 0; index < expected.length; index += 1) {
+\t\tconst actualRect = actual[index];
+\t\tconst expectedRect = expected[index];
+\t\texpect(actualRect.selector).toBe(expectedRect.selector);
+\t\texpect(actualRect.index).toBe(expectedRect.index);
+\t\texpect(actualRect.tagName).toBe(expectedRect.tagName);
+\t\tfor (const key of ["x", "y", "width", "height"]) {
+\t\t\tconst drift = Math.abs(actualRect[key] - expectedRect[key]);
+\t\t\texpect(drift, \`\${expectedRect.selector}[\${expectedRect.index}] \${key} drift\`).toBeLessThanOrEqual(tolerance);
+\t\t}
+\t}
+}
+`;
+}
+
+interface ComponentVisualSpecInput {
+	componentName: string;
+	selector: string;
+	mountJsx: string;
+	componentImportPath: string;
+	referenceHtmlFileName: string;
+	viewports: Array<{ name?: string; width: number; height: number }>;
+	states: Array<{
+		name: string;
+		hover?: string;
+		focus?: string;
+		click?: string;
+		waitFor?: string;
+	}>;
+	assertions: {
+		screenshot: boolean;
+		layout: boolean;
+		layoutTolerance: number;
+		selectors: string[];
+		screenshotThreshold: number;
+		screenshotMaxDiffPixels: number;
+	};
+}
+
+function emitComponentVisualSpec(input: ComponentVisualSpecInput): string {
+	const viewports = JSON.stringify(input.viewports, null, 2);
+	const states = JSON.stringify(input.states, null, 2);
+	const selectors = JSON.stringify(input.assertions.selectors, null, 2);
+	const screenshotEnabled = JSON.stringify(input.assertions.screenshot);
+	const layoutEnabled = JSON.stringify(input.assertions.layout);
+	const layoutTolerance = JSON.stringify(input.assertions.layoutTolerance);
+	const screenshotThreshold = JSON.stringify(
+		input.assertions.screenshotThreshold,
+	);
+	const screenshotMaxDiffPixels = JSON.stringify(
+		input.assertions.screenshotMaxDiffPixels,
+	);
+	const selector = JSON.stringify(input.selector);
+
+	return `import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { expect, test } from "@playwright/experimental-ct-react";
+import pixelmatch from "pixelmatch";
+import { PNG } from "pngjs";
+import { ${input.componentName} } from "${input.componentImportPath}";
+
+const currentDir = dirname(fileURLToPath(import.meta.url));
+const referenceHtml = readFileSync(resolve(currentDir, "./${input.referenceHtmlFileName}"), "utf-8");
+const selector = ${selector};
+const viewports = ${viewports};
+const states = ${states};
+const selectors = ${selectors};
+const screenshotEnabled = ${screenshotEnabled};
+const layoutEnabled = ${layoutEnabled};
+const layoutTolerance = ${layoutTolerance};
+const screenshotThreshold = ${screenshotThreshold};
+const screenshotMaxDiffPixels = ${screenshotMaxDiffPixels};
+
+for (const viewport of viewports) {
+\tfor (const state of states) {
+\t\tconst viewportName = viewport.name ?? String(viewport.width) + "x" + String(viewport.height);
+\t\ttest("${input.componentName} matches source at " + viewportName + " / " + state.name, async ({ mount, page }) => {
+\t\t\tawait page.setViewportSize({ width: viewport.width, height: viewport.height });
+
+\t\t\tawait page.setContent(referenceHtml);
+\t\t\tawait applyState(page, state);
+\t\t\tconst expectedEl = page.locator(selector).first();
+\t\t\tconst expectedScreenshot = screenshotEnabled ? await expectedEl.screenshot() : undefined;
+\t\t\tconst expectedLayout = layoutEnabled ? await readLayout(expectedEl, selectors) : [];
+
+\t\t\tconst component = await mount(${input.mountJsx});
+\t\t\tawait applyState(page, state);
+\t\t\tconst actualScreenshot = screenshotEnabled ? await component.screenshot() : undefined;
+\t\t\tconst actualLayout = layoutEnabled ? await readLayout(component, selectors) : [];
+
+\t\t\tif (screenshotEnabled) {
+\t\t\t\tcompareScreenshots(actualScreenshot, expectedScreenshot, screenshotThreshold, screenshotMaxDiffPixels);
 \t\t\t}
 \t\t\tif (layoutEnabled) {
 \t\t\t\texpectLayoutToMatch(actualLayout, expectedLayout, layoutTolerance);
@@ -191,6 +406,7 @@ async function applyState(page, state) {
 
 async function readLayout(root, selectorsToRead) {
 \treturn root.evaluate((element, values) => {
+\t\tconst origin = element.getBoundingClientRect();
 \t\treturn values.flatMap((selector) => {
 \t\t\tconst matches = selector === ":scope" ? [element] : Array.from(element.querySelectorAll(selector));
 \t\t\treturn matches.map((matchedElement, index) => {
@@ -199,8 +415,8 @@ async function readLayout(root, selectorsToRead) {
 \t\t\t\t\tselector,
 \t\t\t\t\tindex,
 \t\t\t\t\ttagName: matchedElement.tagName.toLowerCase(),
-\t\t\t\t\tx: rect.x,
-\t\t\t\t\ty: rect.y,
+\t\t\t\t\tx: rect.x - origin.x,
+\t\t\t\t\ty: rect.y - origin.y,
 \t\t\t\t\twidth: rect.width,
 \t\t\t\t\theight: rect.height,
 \t\t\t\t};
@@ -209,6 +425,19 @@ async function readLayout(root, selectorsToRead) {
 \t}, selectorsToRead);
 }
 
+function compareScreenshots(actual, expected, threshold, maxDiffPixels) {
+\tif (!actual || !expected) {
+\t\texpect(actual).toEqual(expected);
+\t\treturn;
+\t}
+\tconst actualPng = PNG.sync.read(actual);
+\tconst expectedPng = PNG.sync.read(expected);
+\texpect(actualPng.width, "screenshot width").toBe(expectedPng.width);
+\texpect(actualPng.height, "screenshot height").toBe(expectedPng.height);
+\tconst diffPixels = pixelmatch(actualPng.data, expectedPng.data, null, actualPng.width, actualPng.height, { threshold });
+\texpect(diffPixels, "screenshot pixels differing beyond threshold").toBeLessThanOrEqual(maxDiffPixels);
+}
+
 function expectLayoutToMatch(actual, expected, tolerance) {
 \texpect(actual.length).toBe(expected.length);
 \tfor (let index = 0; index < expected.length; index += 1) {
@@ -226,6 +455,307 @@ function expectLayoutToMatch(actual, expected, tolerance) {
 `;
 }
 
+function emitComponentSplitViews(
+	nodes: DesignNode[],
+	viewsDir: string,
+	cssModulePath: string | undefined,
+): Array<{ path: string; contents: string }> {
+	const seen = new Set<string>();
+	const files: Array<{ path: string; contents: string }> = [];
+
+	function visit(node: DesignNode): void {
+		if (node.kind === "component") {
+			const importName = node.importName ?? node.component ?? "";
+			const childrenProp = node.props?.children;
+			const innerChildren: DesignNode[] =
+				childrenProp?.kind === "children"
+					? childrenProp.value
+					: (node.children ?? []);
+
+			if (importName && !seen.has(importName)) {
+				seen.add(importName);
+				const funcName = toPascalCase(importName);
+				files.push({
+					path: `${viewsDir}/${importName}.view.tsx`,
+					contents: emitComponentView(node, funcName, { cssModulePath }),
+				});
+			}
+
+			for (const child of innerChildren) {
+				visit(child);
+			}
+		} else if (node.kind === "element") {
+			for (const child of node.children ?? []) {
+				visit(child);
+			}
+		}
+	}
+
+	for (const node of nodes) {
+		visit(node);
+	}
+	return files;
+}
+
+/**
+ * Emits the implementation of a mapped component. The component reconstructs
+ * the original element (tag, attributes, styles) captured in `sourceElement`,
+ * exposes the mapping's props as a typed interface, and wires `children` and
+ * `$attr.*` props into the rendered element.
+ */
+function emitComponentView(
+	node: DesignNode,
+	funcName: string,
+	options: { cssModulePath?: string } = {},
+): string {
+	const props = node.props ?? {};
+	const source = node.sourceElement;
+	const propEntries = Object.entries(props);
+
+	// Classify props into an attribute binding (attr name -> prop name), the
+	// children prop, and the destructured parameter list (props referenced by
+	// the body). Plain literal props are documented in the interface but are
+	// not destructured because they are not rendered.
+	const attributeBindings = new Map<string, string>();
+	const interfaceLines: string[] = [];
+	const destructured: string[] = [];
+	let childrenPropName: string | undefined;
+
+	for (const [propName, prop] of propEntries) {
+		if (prop.kind === "text" || prop.kind === "children") {
+			childrenPropName = propName;
+			interfaceLines.push(`\t${propName}?: ReactNode;`);
+			destructured.push(propName);
+			continue;
+		}
+		interfaceLines.push(`\t${propName}?: string;`);
+		if (prop.kind === "literal" && prop.attribute) {
+			attributeBindings.set(prop.attribute, propName);
+			destructured.push(propName);
+		}
+	}
+
+	const body = emitComponentBody(
+		node,
+		source,
+		attributeBindings,
+		childrenPropName,
+		2,
+	);
+
+	const importNodes = childrenPropName ? [] : (node.children ?? []);
+	const componentImports = collectImports(importNodes)
+		.map(
+			({ importName, importPath }) =>
+				`import { ${importName} } from "${importPath}";`,
+		)
+		.join("\n");
+	const reactImport = childrenPropName
+		? `import type { ReactNode } from "react";`
+		: "";
+	const cssModuleImport = options.cssModulePath
+		? `import styles from "./${options.cssModulePath}";`
+		: "";
+	const allImports = [reactImport, componentImports, cssModuleImport]
+		.filter(Boolean)
+		.join("\n");
+
+	const hasProps = propEntries.length > 0;
+	const interfaceBlock = hasProps
+		? `interface ${funcName}Props {\n${interfaceLines.join("\n")}\n}\n\n`
+		: "";
+	const params =
+		destructured.length > 0
+			? `{ ${destructured.join(", ")} }: ${funcName}Props`
+			: "";
+
+	return `${allImports ? `${allImports}\n\n` : ""}${interfaceBlock}export function ${funcName}(${params}) {\n\treturn (\n${body}\t);\n}\n`;
+}
+
+function emitComponentBody(
+	node: DesignNode,
+	source: DesignNode | undefined,
+	attributeBindings: Map<string, string>,
+	childrenPropName: string | undefined,
+	depth: number,
+): string {
+	const indent = "\t".repeat(depth);
+
+	if (!source) {
+		// Fall back to rendering the mapped children as a fragment when the
+		// original element was not captured.
+		const children = node.children ?? [];
+		return `${indent}<>\n${children
+			.map((child) => emitJsxNode(child, depth + 1))
+			.join("")}${indent}</>\n`;
+	}
+
+	const tagName = source.tagName ?? "div";
+	const attributes = emitJsxAttributes(
+		source.attributes ?? {},
+		source.styles ?? {},
+		source.generatedClassNames ?? [],
+		attributeBindings,
+	);
+	const openTag = attributes ? `<${tagName} ${attributes}>` : `<${tagName}>`;
+
+	if (childrenPropName) {
+		const inner = `${"\t".repeat(depth + 1)}{${childrenPropName}}\n`;
+		return `${indent}${openTag}\n${inner}${indent}</${tagName}>\n`;
+	}
+
+	const children = node.children ?? [];
+	if (children.length === 0) {
+		return `${indent}${attributes ? `<${tagName} ${attributes} />` : `<${tagName} />`}\n`;
+	}
+
+	return `${indent}${openTag}\n${children
+		.map((child) => emitJsxNode(child, depth + 1))
+		.join("")}${indent}</${tagName}>\n`;
+}
+
+/**
+ * Walks a mapped AST and returns the first component node seen for each
+ * component name, so the test generator can mount components with the same
+ * props the design supplies.
+ */
+function collectComponentNodes(nodes: DesignNode[]): Map<string, DesignNode> {
+	const map = new Map<string, DesignNode>();
+	function visit(list: DesignNode[]): void {
+		for (const node of list) {
+			if (node.kind === "component") {
+				const name = node.component ?? node.importName;
+				if (name && !map.has(name)) {
+					map.set(name, node);
+				}
+				const childrenProp = node.props?.children;
+				visit(
+					childrenProp?.kind === "children"
+						? childrenProp.value
+						: (node.children ?? []),
+				);
+			} else if (node.kind === "element") {
+				visit(node.children ?? []);
+			}
+		}
+	}
+	visit(nodes);
+	return map;
+}
+
+/**
+ * Emits the JSX used to mount a component in its visual test, forwarding the
+ * literal/attribute props as attributes and the text/children prop as the
+ * element body so the rendered component matches the source design.
+ */
+function emitComponentMount(
+	componentName: string,
+	node: DesignNode | undefined,
+): string {
+	const attributeParts: string[] = [];
+	let childrenJsx = "";
+	for (const [propName, prop] of Object.entries(node?.props ?? {})) {
+		if (prop.kind === "text") {
+			childrenJsx = escapeJsxText(prop.value);
+			continue;
+		}
+		if (prop.kind === "children") {
+			childrenJsx = prop.value.map((child) => emitInlineJsx(child)).join("");
+			continue;
+		}
+		const attribute = emitProp(propName, prop);
+		if (attribute) {
+			attributeParts.push(attribute);
+		}
+	}
+	const attributes =
+		attributeParts.length > 0 ? ` ${attributeParts.join(" ")}` : "";
+	return childrenJsx
+		? `<${componentName}${attributes}>${childrenJsx}</${componentName}>`
+		: `<${componentName}${attributes} />`;
+}
+
+/** Renders a node as single-line JSX for use inside a mount expression. */
+function emitInlineJsx(node: DesignNode): string {
+	if (node.kind === "text") {
+		return escapeJsxText(node.text ?? "");
+	}
+	if (node.kind === "component") {
+		return emitComponentMount(
+			node.component ?? node.importName ?? "Component",
+			node,
+		);
+	}
+	const tagName = node.tagName ?? "div";
+	const attributes = emitJsxAttributes(
+		node.attributes ?? {},
+		node.styles ?? {},
+		node.generatedClassNames ?? [],
+	);
+	const openTag = attributes ? `<${tagName} ${attributes}>` : `<${tagName}>`;
+	const children = (node.children ?? [])
+		.map((child) => emitInlineJsx(child))
+		.join("");
+	return `${openTag}${children}</${tagName}>`;
+}
+
+function findNodeBySelector(
+	nodes: DesignNode[],
+	selector: string,
+): DesignNode | undefined {
+	const parsedSelector = parseSelector(selector);
+	if (!parsedSelector) return undefined;
+	const ps = parsedSelector;
+	function search(list: DesignNode[]): DesignNode | undefined {
+		for (const node of list) {
+			if (matchesSelector(node, ps)) return node;
+			const found = search(node.children ?? []);
+			if (found) return found;
+		}
+		return undefined;
+	}
+	return search(nodes);
+}
+
+const VOID_ELEMENTS = new Set([
+	"area",
+	"base",
+	"br",
+	"col",
+	"embed",
+	"hr",
+	"img",
+	"input",
+	"link",
+	"meta",
+	"param",
+	"source",
+	"track",
+	"wbr",
+]);
+
+function serializeNodeToHtml(node: DesignNode): string {
+	if (node.kind === "text") return node.text ?? "";
+	if (node.kind !== "element") return "";
+	const tagName = node.tagName ?? "div";
+	const attrs = Object.entries(node.attributes ?? {})
+		.map(([name, value]) =>
+			value === "" ? name : `${name}="${value.replace(/"/g, "&quot;")}"`,
+		)
+		.join(" ");
+	const openTag = attrs ? `<${tagName} ${attrs}>` : `<${tagName}>`;
+	if (VOID_ELEMENTS.has(tagName)) return openTag;
+	const children = (node.children ?? []).map(serializeNodeToHtml).join("");
+	return `${openTag}${children}</${tagName}>`;
+}
+
+function toPascalCase(value: string): string {
+	return value
+		.split(/[-_\s]+/)
+		.map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+		.join("");
+}
+
 function toRelativeImport(fromFile: string, toFile: string): string {
 	const fromParts = fromFile.split("/").slice(0, -1);
 	const toParts = toFile.split("/");
@@ -259,7 +789,7 @@ export function emitReactView(
 		: "";
 	const allImports = [importLines, cssModuleImport].filter(Boolean).join("\n");
 	const body =
-		nodes.length === 1
+		nodes.length === 1 && nodes[0]?.kind !== "text"
 			? emitJsxNode(nodes[0], 2)
 			: `${"\t".repeat(2)}<>\n${nodes.map((node) => emitJsxNode(node, 3)).join("")}${"\t".repeat(2)}</>\n`;
 
@@ -352,6 +882,106 @@ function transformStyles(
 	return { nodes: resolvedNodes };
 }
 
+interface ParsedSelector {
+	tagName?: string;
+	id?: string;
+	classes: string[];
+	attributes: Record<string, string>;
+}
+
+function parseInlineStyle(style: string | undefined): Record<string, string> {
+	const styles: Record<string, string> = {};
+	if (!style) {
+		return styles;
+	}
+	for (const declaration of style.split(";")) {
+		const [property, ...valueParts] = declaration.split(":");
+		const value = valueParts.join(":").trim();
+		if (!property?.trim() || !value) {
+			continue;
+		}
+		styles[property.trim().toLowerCase()] = value;
+	}
+	return styles;
+}
+
+function parseSelector(selector: string): ParsedSelector | undefined {
+	const trimmed = selector.trim();
+	if (!trimmed || /[\s>+~,:]/.test(trimmed)) {
+		return undefined;
+	}
+	const parsed: ParsedSelector = { classes: [], attributes: {} };
+	let rest = trimmed;
+	const tagMatch = rest.match(/^[a-zA-Z][a-zA-Z0-9-]*/);
+	if (tagMatch?.[0]) {
+		parsed.tagName = tagMatch[0].toLowerCase();
+		rest = rest.slice(tagMatch[0].length);
+	}
+	while (rest) {
+		if (rest.startsWith(".")) {
+			const match = rest.match(/^\.([a-zA-Z_][a-zA-Z0-9_-]*)/);
+			if (!match?.[1]) {
+				return undefined;
+			}
+			parsed.classes.push(match[1]);
+			rest = rest.slice(match[0].length);
+			continue;
+		}
+		if (rest.startsWith("#")) {
+			const match = rest.match(/^#([a-zA-Z_][a-zA-Z0-9_-]*)/);
+			if (!match?.[1] || parsed.id) {
+				return undefined;
+			}
+			parsed.id = match[1];
+			rest = rest.slice(match[0].length);
+			continue;
+		}
+		if (rest.startsWith("[")) {
+			const match = rest.match(
+				/^\[([a-zA-Z_][a-zA-Z0-9_.:-]*)(?:=(?:"([^"]*)"|'([^']*)'|([^\]]+)))?\]/,
+			);
+			if (!match?.[1]) {
+				return undefined;
+			}
+			parsed.attributes[match[1]] = match[2] ?? match[3] ?? match[4] ?? "";
+			rest = rest.slice(match[0].length);
+			continue;
+		}
+		return undefined;
+	}
+	return parsed;
+}
+
+function matchesSelector(node: DesignNode, selector: ParsedSelector): boolean {
+	if (node.kind !== "element") {
+		return false;
+	}
+	const attributes = node.attributes ?? {};
+	if (selector.tagName && node.tagName !== selector.tagName) {
+		return false;
+	}
+	if (selector.id && attributes.id !== selector.id) {
+		return false;
+	}
+	const classNames = new Set(
+		(attributes.class ?? "").split(/\s+/).filter(Boolean),
+	);
+	for (const className of selector.classes) {
+		if (!classNames.has(className)) {
+			return false;
+		}
+	}
+	for (const [name, value] of Object.entries(selector.attributes)) {
+		if (!(name in attributes)) {
+			return false;
+		}
+		if (value !== "" && attributes[name] !== value) {
+			return false;
+		}
+	}
+	return true;
+}
+
 function parseCssRules(
 	css: string | undefined,
 	diagnostics: Diagnostic[],
@@ -903,6 +1533,7 @@ function emitJsxAttributes(
 	attributes: Record<string, string>,
 	styles: Record<string, string>,
 	generatedClassNames: string[] = [],
+	attributeBindings: Map<string, string> = new Map(),
 ): string {
 	const mergedAttributes = { ...attributes };
 	const classNames = [
@@ -918,6 +1549,10 @@ function emitJsxAttributes(
 		.sort(([left], [right]) => left.localeCompare(right))
 		.map(([name, value]) => {
 			const jsxName = toJsxAttributeName(name);
+			const binding = attributeBindings.get(name);
+			if (binding) {
+				return `${jsxName}={${binding}}`;
+			}
 			if (value === "") {
 				return jsxName;
 			}