[Blueprint editor] Blueprint Validation (#2967)

## Motivation for the change, related issues

Adds validation to the Blueprint editor to surface errors as they come
up. Before this PR, the user would have to try running the Blueprint
first:

<img width="2174" height="1632" alt="CleanShot 2025-11-30 at 01 10
23@2x"
src="https://github.com/user-attachments/assets/dcc83e81-89c1-4fe5-8eb5-0eaa70c85759"
/>

Author: adamziel

packages/playground/blueprints/src/index.ts

@@ -21,6 +21,7 @@ export {
 	runBlueprintV1Steps,
 	InvalidBlueprintError,
 	BlueprintStepExecutionError,
+	validateBlueprint,
 
 	// BC:
 	compileBlueprintV1 as compileBlueprint,
@@ -32,6 +33,7 @@ export type {
 	CompiledBlueprintV1,
 	CompiledV1Step,
 	OnStepCompleted,
+	BlueprintValidationResult,
 } from './lib/v1/compile';
 export type {
 	CachedResource,

packages/playground/blueprints/src/lib/v1/compile.ts

@@ -352,15 +352,14 @@ function compileBlueprintJson(
 		});
 	}
 
-	const { valid, errors } = validateBlueprint(blueprint);
-	if (!valid) {
-		const formattedErrors = formatValidationErrors(blueprint, errors ?? []);
+	const validationResult = validateBlueprint(blueprint);
+	if (!validationResult.valid) {
+		const { errors } = validationResult;
+		const formattedErrors = formatValidationErrors(blueprint, errors);
 
 		throw new InvalidBlueprintError(
 			`Invalid Blueprint: The Blueprint does not conform to the schema.\n\n` +
-				`Found ${
-					errors!.length
-				} validation error(s):\n\n${formattedErrors}\n\n` +
+				`Found ${errors.length} validation error(s):\n\n${formattedErrors}\n\n` +
 				`Please review your Blueprint and fix these issues. ` +
 				`Learn more about the Blueprint format: https://wordpress.github.io/wordpress-playground/blueprints/data-format`,
 			errors
@@ -543,7 +542,13 @@ function formatValidationErrors(
 		.join('\n\n');
 }
 
-export function validateBlueprint(blueprintMaybe: object) {
+export type BlueprintValidationResult =
+	| { valid: true }
+	| { valid: false; errors: ErrorObject[] };
+
+export function validateBlueprint(
+	blueprintMaybe: object
+): BlueprintValidationResult {
 	const valid = blueprintValidator(blueprintMaybe);
 	if (valid) {
 		return { valid };
@@ -568,16 +573,18 @@ export function validateBlueprint(blueprintMaybe: object) {
 			hasErrorsDifferentThanAnyOf.add(error.instancePath);
 		}
 	}
-	const errors = blueprintValidator.errors?.filter(
-		(error) =>
-			!(
-				error.schemaPath.startsWith('#/properties/steps/items/anyOf') &&
-				hasErrorsDifferentThanAnyOf.has(error.instancePath)
-			)
-	);
+	const errors =
+		blueprintValidator.errors?.filter(
+			(error) =>
+				!(
+					error.schemaPath.startsWith(
+						'#/properties/steps/items/anyOf'
+					) && hasErrorsDifferentThanAnyOf.has(error.instancePath)
+				)
+		) ?? [];
 
 	return {
-		valid,
+		valid: false,
 		errors,
 	};
 }

packages/playground/website/src/components/blueprint-editor/BlueprintBundleEditor.tsx

@@ -9,7 +9,10 @@ import {
 import { logger } from '@php-wasm/logger';
 import { Button, Icon, Notice } from '@wordpress/components';
 import { download } from '@wordpress/icons';
-import { resolveRuntimeConfiguration } from '@wp-playground/blueprints';
+import {
+	resolveRuntimeConfiguration,
+	type BlueprintValidationResult,
+} from '@wp-playground/blueprints';
 import type { AsyncWritableFilesystem } from '@wp-playground/storage';
 import { BlobWriter, Uint8ArrayReader, ZipWriter } from '@zip.js/zip.js';
 import classNames from 'classnames';
@@ -32,6 +35,7 @@ import {
 	getStringNodeAtPosition,
 	jsonSchemaCompletion,
 } from './json-schema-editor/jsonSchemaCompletion';
+import { createBlueprintLinter } from './json-schema-editor/blueprint-linter';
 import {
 	inferLanguageFromBlueprint,
 	type SupportedLanguage,
@@ -45,10 +49,42 @@ import { sitesSlice } from '../../lib/state/redux/slice-sites';
 import { useAppDispatch } from '../../lib/state/redux/store';
 import styles from '../site-manager/site-file-browser/style.module.css';
 import hideRootStyles from './hide-root.module.css';
+import validationStyles from './validation-panel.module.css';
 import type { EventedFilesystem } from '@wp-playground/storage';
 
 const BLUEPRINT_JSON_PATH = '/blueprint.json';
 
+/**
+ * Format a validation error into a human-readable message for the error panel
+ */
+function formatValidationError(error: {
+	keyword: string;
+	message?: string;
+	params?: Record<string, unknown>;
+	instancePath: string;
+}): string {
+	// Provide better messages based on error type
+	if (error.keyword === 'additionalProperties' && error.params) {
+		const prop = error.params.additionalProperty;
+		return `Unknown property "${prop}"`;
+	}
+	if (error.keyword === 'required' && error.params) {
+		const prop = error.params.missingProperty;
+		return `Missing required property "${prop}"`;
+	}
+	if (error.keyword === 'enum' && error.params) {
+		const allowed = error.params.allowedValues;
+		if (Array.isArray(allowed)) {
+			return `Value must be one of: ${allowed.join(', ')}`;
+		}
+	}
+	if (error.keyword === 'type' && error.params) {
+		const expected = error.params.type;
+		return `Expected ${expected}`;
+	}
+	return error.message || 'Validation error';
+}
+
 interface StringEditorState {
 	isOpen: boolean;
 	initialValue: string;
@@ -248,6 +284,8 @@ export const BlueprintBundleEditor = forwardRef<
 	>(null);
 	const [displayPath, setDisplayPath] = useState<string | null>(null);
 	const [isRecreating, setIsRecreating] = useState(false);
+	const [validationResult, setValidationResult] =
+		useState<BlueprintValidationResult | null>(null);
 	const [stringEditorState, setStringEditorState] =
 		useState<StringEditorState>({
 			isOpen: false,
@@ -467,13 +505,21 @@ export const BlueprintBundleEditor = forwardRef<
 		[]
 	);
 
+	const handleValidationChange = useCallback(
+		(result: BlueprintValidationResult | null) => {
+			setValidationResult(result);
+		},
+		[]
+	);
+
 	const blueprintSchemaExtensions = useMemo(
 		() => [
 			autocompletion({
 				override: [jsonSchemaCompletion],
 				activateOnTyping: true,
 				closeOnBlur: false,
 			}),
+			createBlueprintLinter(handleValidationChange),
 			// Capture the EditorView reference for string editor operations
 			EditorView.updateListener.of((update) => {
 				cmViewRef.current = update.view;
@@ -489,9 +535,12 @@ export const BlueprintBundleEditor = forwardRef<
 			// String editor toolbar tooltip
 			createStringEditorTooltip(openStringEditor),
 		],
-		[openStringEditor]
+		[handleValidationChange, openStringEditor]
 	);
 
+	const hasValidationErrors =
+		validationResult !== null && !validationResult.valid;
+
 	const handleDownloadBundle = useCallback(async () => {
 		try {
 			const zipWriter = new ZipWriter(new BlobWriter('application/zip'));
@@ -542,7 +591,7 @@ export const BlueprintBundleEditor = forwardRef<
 		[handleDownloadBundle, filesystem, handleRecreateFromBlueprint]
 	);
 
-	const disableRunButton = isRecreating || !site;
+	const disableRunButton = isRecreating || !site || hasValidationErrors;
 	return (
 		<>
 			<div className={classNames(styles.container, className)}>
@@ -612,10 +661,21 @@ export const BlueprintBundleEditor = forwardRef<
 								{!readOnly && (
 									<Button
 										variant="primary"
-										className={styles.editorToolbarButton}
+										className={classNames(
+											styles.editorToolbarButton,
+											{
+												[validationStyles.runButtonDisabled]:
+													hasValidationErrors,
+											}
+										)}
 										onClick={handleRecreateFromBlueprint}
 										isBusy={isRecreating}
 										disabled={disableRunButton}
+										title={
+											hasValidationErrors
+												? 'Fix validation errors before running'
+												: undefined
+										}
 									>
 										<PlayIcon
 											className={
@@ -640,19 +700,94 @@ export const BlueprintBundleEditor = forwardRef<
 									{messageContent}
 								</div>
 							) : (
-								<CodeEditor
-									ref={editorRef}
-									code={code}
-									onChange={handleCodeChange}
-									currentPath={currentPath}
-									className={styles.editor}
-									readOnly={readOnly}
-									additionalExtensions={
-										currentPath === BLUEPRINT_JSON_PATH
-											? blueprintSchemaExtensions
-											: undefined
-									}
-								/>
+								<>
+									<CodeEditor
+										ref={editorRef}
+										code={code}
+										onChange={handleCodeChange}
+										currentPath={currentPath}
+										className={styles.editor}
+										readOnly={readOnly}
+										additionalExtensions={
+											currentPath === BLUEPRINT_JSON_PATH
+												? blueprintSchemaExtensions
+												: undefined
+										}
+									/>
+									{currentPath === BLUEPRINT_JSON_PATH &&
+										hasValidationErrors &&
+										!validationResult.valid && (
+											<div
+												className={
+													validationStyles.validationPanel
+												}
+											>
+												<div
+													className={
+														validationStyles.validationHeader
+													}
+												>
+													<span
+														className={
+															validationStyles.validationIcon
+														}
+													>
+														<svg
+															viewBox="0 0 20 20"
+															fill="currentColor"
+														>
+															<path
+																fillRule="evenodd"
+																d="M18 10a8 8 0 11-16 0 8 8 0 0116 0zm-7 4a1 1 0 11-2 0 1 1 0 012 0zm-1-9a1 1 0 00-1 1v4a1 1 0 102 0V6a1 1 0 00-1-1z"
+																clipRule="evenodd"
+															/>
+														</svg>
+													</span>
+													{validationResult.errors
+														.length === 1
+														? '1 validation error'
+														: `${validationResult.errors.length} validation errors`}
+												</div>
+												<ul
+													className={
+														validationStyles.validationErrors
+													}
+												>
+													{validationResult.errors.map(
+														(error, index) => (
+															<li
+																key={index}
+																className={
+																	validationStyles.validationError
+																}
+															>
+																{error.instancePath && (
+																	<span
+																		className={
+																			validationStyles.errorPath
+																		}
+																	>
+																		{
+																			error.instancePath
+																		}
+																	</span>
+																)}
+																<span
+																	className={
+																		validationStyles.errorMessage
+																	}
+																>
+																	{formatValidationError(
+																		error
+																	)}
+																</span>
+															</li>
+														)
+													)}
+												</ul>
+											</div>
+										)}
+								</>
 							)
 						) : (
 							<div className={styles.placeholder}>