Agentic UI: Create blank or Blueprint sites (#4177)

## Related issues

<!--
Link a related issue to this PR. If the PR does not immediately resolve
the issue,
for example, it requires a separate deployment to production, avoid
using the "Fixes" keyword and use "Related to" instead.
-->

- First product increment from #3941

## How AI was used in this PR

<!--
Help reviewers understand what to look for and verify that you have
reviewed the code yourself.
-->

Codex helped compare the original umbrella PR with current trunk,
implement the scoped first increment, and add focused coverage. The
resulting behavior, cleanup paths, and tests were manually reviewed. The
updated visual design still needs human review in both color schemes.

## Proposed Changes

<!--
Explain the intent of this PR:
- What problem does it solve, or what need does it address?
- How does it affect the user (new capability, fix, performance,
accessibility, etc.)?
- Note any user-visible behavior changes or trade-offs.

Focus on the why and the user impact. Avoid listing modified files or
describing implementation mechanics — the diff already shows that.
-->

- Give users one Create flow for blank sites and uploaded JSON or ZIP
Blueprints, including full-window drop, replacement, removal, reset of
prior untouched suggestions, and Blueprint deep-link handoff.
- Preserve user-entered values while applying Blueprint suggestions only
to pristine fields, and retain the existing path and WordPress-version
reliability behavior.
- Keep temporary uploads safe across selection, replacement,
cancellation, creation, and failure recovery.
- Make creation progress accessible, prevent route interaction and
closing while creation is active, restore the flow after failure, and
manage focus between onboarding routes.
- Simplify onboarding around the currently working Create and Import
jobs, redirect the legacy Blueprint route into Create, and remove the
unused gallery surface.
- Bring the updated onboarding design into the reduced flow with the
animated dot-grid backdrop, illustrated job cards, frosted panels,
responsive layouts, persistent footer actions, and compact Blueprint
picker.

## Testing Instructions

<!--
Add as many details as possible to help others reproduce the issue and
test the fix.
"Before / After" screenshots can also be very helpful when the change is
visual.
-->

1. Open onboarding and confirm the home screen shows the dot-grid
backdrop, illustrated Create and Import cards, and persistent Back
action when existing sites are present. Start Create and create a blank
site.
2. Select JSON and ZIP Blueprints using the inline picker and
full-window drop target. Confirm the selected file can be replaced or
removed and that ZIP-relative assets still resolve during creation.
3. Edit the site name or path before selecting a Blueprint. Confirm
suggestions fill pristine fields without overwriting dirty fields.
4. Open a Blueprint deep link and confirm it hands the uploaded
Blueprint to `/onboarding/create`.
5. During creation, confirm the visible status is announced, route
content is inert, Close is disabled, and route headings receive focus.
Force a failure and confirm the form recovers.
6. Confirm uploaded and extracted temporary files are cleaned after
invalid uploads, stale selections, replacement, removal, success, and
failure.
7. Check the Create flow, selected Blueprint state, drop overlay,
advanced settings, and progress state in both light and dark color
schemes.

## Pre-merge Checklist

<!--
Complete applicable items on this checklist **before** merging into
trunk. Inapplicable items can be left unchecked.

Both the PR author and reviewer are responsible for ensuring the
checklist is completed.
-->

- [x] Have you checked for TypeScript, React or other console errors?

Author: bcotrim

apps/local/src/index.ts

@@ -50,7 +50,7 @@ import { createJsonResponse, fetchSiteRest } from '@studio/common/lib/wordpress-
 import { isWordPressDevVersion } from '@studio/common/lib/wordpress-version-utils';
 import {
 	cleanupBlueprintTempDir,
-	extractBlueprintBundle,
+	extractBlueprintUpload,
 } from '@studio/common/sites/blueprint-extract';
 import { buildSiteCreateArgs, type SiteCreateOptions } from '@studio/common/sites/create';
 import { buildSiteSetArgs } from '@studio/common/sites/edit';
@@ -535,30 +535,36 @@ export async function startLocalServer( options: LocalServerOptions ): Promise<
 			const siteId = crypto.randomUUID();
 			// Build the create args with the same shared helper the desktop uses, so
 			// Blueprints (and --wp dev→nightly, etc.) are handled identically.
-			const { args, cleanup } = buildSiteCreateArgs( {
-				path: body.path,
-				name: body.name,
-				siteId,
-				wpVersion: body.wpVersion,
-				phpVersion: body.phpVersion,
-				customDomain: body.customDomain,
-				enableHttps: body.enableHttps,
-				adminUsername: body.adminUsername,
-				adminPassword: body.adminPassword,
-				adminEmail: body.adminEmail,
-				blueprint: body.blueprint?.blueprint,
-				originalBlueprintPath: body.blueprint?.filePath,
-			} );
-
+			let cleanupCreateArgs: () => void = () => undefined;
 			try {
+				const { args, cleanup } = buildSiteCreateArgs( {
+					path: body.path,
+					name: body.name,
+					siteId,
+					wpVersion: body.wpVersion,
+					phpVersion: body.phpVersion,
+					customDomain: body.customDomain,
+					enableHttps: body.enableHttps,
+					adminUsername: body.adminUsername,
+					adminPassword: body.adminPassword,
+					adminEmail: body.adminEmail,
+					blueprint: body.blueprint?.blueprint,
+					originalBlueprintPath: body.blueprint?.filePath,
+				} );
+				cleanupCreateArgs = cleanup;
 				await new Promise< void >( ( resolve, reject ) => {
 					const [ emitter ] = execute( args, { output: 'capture' } );
 					emitter.on( 'success', () => resolve() );
 					emitter.on( 'failure', ( { error } ) => reject( error ) );
 					emitter.on( 'error', ( { error } ) => reject( error ) );
 				} );
 			} finally {
-				cleanup();
+				cleanupCreateArgs();
+				if ( body.blueprint?.filePath ) {
+					await cleanupBlueprintTempDir( path.dirname( body.blueprint.filePath ) ).catch(
+						() => undefined
+					);
+				}
 			}
 
 			const created = ( await listSites( execute ) ).find( ( s ) => s.id === siteId );
@@ -790,24 +796,10 @@ export async function startLocalServer( options: LocalServerOptions ): Promise<
 		} )
 	);
 
-	// Extract an uploaded Blueprint ZIP (the path comes from /uploads) and return
-	// its parsed blueprint.json — the shared extractor the desktop uses.
 	api.post(
 		'/blueprints/extract',
 		asyncHandler( async ( req: Request, res: Response ) => {
-			const zipFilePath = req.body?.zipFilePath;
-			if ( typeof zipFilePath !== 'string' || ! zipFilePath ) {
-				res.status( 400 ).json( { error: 'Missing zipFilePath' } );
-				return;
-			}
-			// The zip is always an upload under the OS temp dir (via /uploads);
-			// reject anything else so this can't be used to read arbitrary files.
-			const resolvedZip = path.resolve( zipFilePath );
-			if ( ! ( resolvedZip + path.sep ).startsWith( path.resolve( os.tmpdir() ) + path.sep ) ) {
-				res.status( 400 ).json( { error: 'zipFilePath must be an uploaded file' } );
-				return;
-			}
-			res.json( await extractBlueprintBundle( resolvedZip ) );
+			res.json( await extractBlueprintUpload( req ) );
 		} )
 	);
 

apps/studio/src/hooks/use-add-site.ts

@@ -3,6 +3,11 @@ import { DEFAULT_PHP_VERSION, DEFAULT_WORDPRESS_VERSION } from '@studio/common/c
 import { updateBlueprintWithFormValues } from '@studio/common/lib/blueprint-settings';
 import { generateCustomDomainFromSiteName } from '@studio/common/lib/domains';
 import { type SiteFileAccess } from '@studio/common/lib/site-file-access';
+import {
+	validateProposedSitePath,
+	validateSelectedSitePath,
+	type PathValidationResult,
+} from '@studio/common/lib/site-path-validation';
 import { type SiteRuntime } from '@studio/common/lib/site-runtime';
 import { SupportedPHPVersion } from '@studio/common/types/php-versions';
 import { useI18n } from '@wordpress/react-i18n';
@@ -38,16 +43,7 @@ export interface CreateSiteFormValues {
 	adminEmail?: string;
 }
 
-/**
- * Result from path selection or site name change validation
- */
-export interface PathValidationResult {
-	path: string;
-	name?: string;
-	isEmpty: boolean;
-	isWordPress: boolean;
-	error?: string;
-}
+export type { PathValidationResult } from '@studio/common/lib/site-path-validation';
 
 export function useAddSite() {
 	const { __ } = useI18n();
@@ -147,38 +143,7 @@ export function useAddSite() {
 				return null;
 			}
 
-			const { path, name, isEmpty, isWordPress } = response;
-
-			if ( await checkPathExists( path ) ) {
-				return {
-					path,
-					name: name ?? undefined,
-					isEmpty,
-					isWordPress,
-					error: __(
-						'The directory is already associated with another Studio site. Please choose a different custom local path.'
-					),
-				};
-			}
-
-			if ( ! isEmpty && ! isWordPress ) {
-				return {
-					path,
-					name: name ?? undefined,
-					isEmpty,
-					isWordPress,
-					error: __(
-						'This directory is not empty. Please select an empty directory or an existing WordPress folder.'
-					),
-				};
-			}
-
-			return {
-				path,
-				name: name ?? undefined,
-				isEmpty,
-				isWordPress,
-			};
+			return validateSelectedSitePath( response, await checkPathExists( response.path ) );
 		},
 		[ __, checkPathExists ]
 	);
@@ -188,43 +153,10 @@ export function useAddSite() {
 	 */
 	const generateProposedPath = useCallback(
 		async ( siteName: string ): Promise< PathValidationResult > => {
-			const { path, isEmpty, isWordPress, isNameTooLong } =
-				await getIpcApi().generateProposedSitePath( siteName );
-
-			if ( isNameTooLong ) {
-				return {
-					path,
-					isEmpty,
-					isWordPress,
-					error: __( 'The site name is too long. Please choose a shorter site name.' ),
-				};
-			}
-
-			if ( await checkPathExists( path ) ) {
-				return {
-					path,
-					isEmpty,
-					isWordPress,
-					error: __(
-						'The directory is already associated with another Studio site. Please choose a different site name or a custom local path.'
-					),
-				};
-			}
-
-			if ( ! isEmpty && ! isWordPress ) {
-				return {
-					path,
-					isEmpty,
-					isWordPress,
-					error: __(
-						'This directory is not empty. Please select an empty directory or an existing WordPress folder.'
-					),
-				};
-			}
-
-			return { path, isEmpty, isWordPress };
+			const result = await getIpcApi().generateProposedSitePath( siteName );
+			return validateProposedSitePath( result, await checkPathExists( result.path ) );
 		},
-		[ __, checkPathExists ]
+		[ checkPathExists ]
 	);
 
 	/**

apps/studio/src/ipc-handlers.ts

@@ -2269,8 +2269,12 @@ export async function readBlueprintFile(
 		throw new Error( 'Blueprint file path must be within the allowed directory' );
 	}
 
-	const fileContents = await fsPromises.readFile( resolvedPath, 'utf-8' );
-	return JSON.parse( fileContents );
+	try {
+		const fileContents = await fsPromises.readFile( resolvedPath, 'utf-8' );
+		return JSON.parse( fileContents );
+	} finally {
+		await fsPromises.rm( resolvedPath, { force: true } );
+	}
 }
 
 export async function extractBlueprintBundle(

apps/studio/src/modules/add-site/components/blueprints.tsx

@@ -1,5 +1,4 @@
-import { generateDefaultBlueprintDescription } from '@studio/common/lib/blueprint-settings';
-import { BlueprintValidationWarning } from '@studio/common/lib/blueprint-validation';
+import { prepareBlueprint } from '@studio/common/lib/blueprint-selection';
 import {
 	__experimentalVStack as VStack,
 	__experimentalHStack as HStack,
@@ -20,6 +19,7 @@ import { cx } from 'src/lib/cx';
 import { getIpcApi } from 'src/lib/get-ipc-api';
 import { useI18nLocale } from 'src/stores';
 import { useGetBlueprints } from 'src/stores/wpcom-api';
+import type { BlueprintValidationWarning } from '@studio/common/lib/blueprint-validation';
 
 import './blueprints.css';
 
@@ -193,45 +193,28 @@ export function AddSiteBlueprintSelector( {
 		blueprint: Blueprint;
 		warnings: BlueprintValidationWarning[] | undefined;
 	} | null > => {
-		const meta = blueprintJson as {
-			version?: number;
-			meta?: { title?: string; description?: string };
-		};
-
-		if ( meta.version === 2 ) {
-			setValidationError(
-				__( 'Blueprint v2 format is not supported yet. Please use Blueprint v1 format.' )
-			);
-			onCleanup?.();
-			return null;
-		}
-
-		const validation = await getIpcApi().validateBlueprint( blueprintJson );
-		if ( ! validation.valid ) {
-			setValidationError( validation.error || __( 'Invalid Blueprint format' ) );
+		const prepared = await prepareBlueprint( blueprintJson, {
+			fallbackTitle: fileName.replace( /\.(json|zip)$/i, '' ),
+			validate: ( candidate ) =>
+				getIpcApi().validateBlueprint( candidate as Blueprint[ 'blueprint' ] ),
+		} );
+		if ( ! prepared.valid ) {
+			setValidationError( prepared.error );
 			onCleanup?.();
 			return null;
 		}
 
-		const warnings =
-			validation.warnings && validation.warnings.length > 0 ? validation.warnings : undefined;
-
-		const baseName = fileName.replace( /\.(json|zip)$/, '' );
 		const blueprint: Blueprint = {
 			slug: `file:${ fileName }`,
-			title: meta.meta?.title || baseName,
-			excerpt:
-				meta.meta?.description ||
-				generateDefaultBlueprintDescription(
-					blueprintJson as Parameters< typeof generateDefaultBlueprintDescription >[ 0 ]
-				),
+			title: prepared.title,
+			excerpt: prepared.excerpt,
 			image: '',
 			playground_url: '',
-			blueprint: blueprintJson,
+			blueprint: prepared.blueprint as Blueprint[ 'blueprint' ],
 			filePath,
 		};
 
-		return { blueprint, warnings };
+		return { blueprint, warnings: prepared.warnings };
 	};
 
 	const handleFileSelect = async ( event: React.ChangeEvent< HTMLInputElement > ) => {

apps/studio/src/modules/add-site/components/upload-blueprint-button.tsx

@@ -1,4 +1,4 @@
-import { generateDefaultBlueprintDescription } from '@studio/common/lib/blueprint-settings';
+import { prepareBlueprint } from '@studio/common/lib/blueprint-selection';
 import { Button as WpButton } from '@wordpress/components';
 import { sprintf } from '@wordpress/i18n';
 import { useI18n } from '@wordpress/react-i18n';
@@ -58,34 +58,23 @@ export function UploadBlueprintButton( {
 				return;
 			}
 
-			const meta = blueprintJson as {
-				version?: number;
-				meta?: { title?: string; description?: string };
-			};
-
-			if ( meta.version === 2 ) {
-				onError( __( 'Blueprint v2 format is not supported yet. Please use v1.' ) );
-				return;
-			}
-
-			const validation = await getIpcApi().validateBlueprint( blueprintJson );
-			if ( ! validation.valid ) {
-				onError( validation.error || __( 'Invalid Blueprint format' ) );
+			const prepared = await prepareBlueprint( blueprintJson, {
+				fallbackTitle: file.name.replace( /\.(json|zip)$/i, '' ),
+				validate: ( candidate ) =>
+					getIpcApi().validateBlueprint( candidate as Blueprint[ 'blueprint' ] ),
+			} );
+			if ( ! prepared.valid ) {
+				onError( prepared.error );
 				return;
 			}
 
-			const baseName = file.name.replace( /\.(json|zip)$/, '' );
 			const fileBlueprint: Blueprint = {
 				slug: `file:${ file.name }`,
-				title: meta.meta?.title || baseName,
-				excerpt:
-					meta.meta?.description ||
-					generateDefaultBlueprintDescription(
-						blueprintJson as Parameters< typeof generateDefaultBlueprintDescription >[ 0 ]
-					),
+				title: prepared.title,
+				excerpt: prepared.excerpt,
 				image: '',
 				playground_url: '',
-				blueprint: blueprintJson,
+				blueprint: prepared.blueprint as Blueprint[ 'blueprint' ],
 				filePath,
 			};
 

apps/studio/src/modules/add-site/hooks/use-blueprint-deeplink.ts

@@ -1,16 +1,12 @@
-import { generateDefaultBlueprintDescription } from '@studio/common/lib/blueprint-settings';
+import { getBlueprintDisplayDetails } from '@studio/common/lib/blueprint-selection';
 import { BlueprintPreferredVersions } from '@studio/common/lib/blueprint-validation';
 import { SupportedPHPVersion } from '@studio/common/types/php-versions';
 import { useCallback } from 'react';
 import { useIpcListener } from 'src/hooks/use-ipc-listener';
 import { getIpcApi } from 'src/lib/get-ipc-api';
 import { Blueprint } from 'src/stores/wpcom-api';
 import { applyBlueprintFormValues } from '../lib/apply-blueprint-form-values';
-
-type BlueprintMetadata = {
-	title?: string;
-	description?: string;
-};
+import type { BlueprintV1Declaration } from '@wp-playground/blueprints';
 
 interface UseBlueprintDeeplinkOptions {
 	isAnySiteProcessing: boolean;
@@ -58,13 +54,12 @@ export function useBlueprintDeeplink( options: UseBlueprintDeeplinkOptions ): vo
 				try {
 					const blueprintJson = await getIpcApi().readBlueprintFile( blueprintPath );
 					const fileName = blueprintPath.split( /[/\\]/ ).pop() || 'blueprint.json';
-					const blueprintMeta = blueprintJson.meta as BlueprintMetadata | undefined;
+					const details = getBlueprintDisplayDetails( blueprintJson as BlueprintV1Declaration, '' );
 
 					const fileBlueprint: Blueprint = {
 						slug: `file:${ fileName }`,
-						title: blueprintMeta?.title || '',
-						excerpt:
-							blueprintMeta?.description || generateDefaultBlueprintDescription( blueprintJson ),
+						title: details.title,
+						excerpt: details.excerpt,
 						image: '',
 						playground_url: '',
 						blueprint: blueprintJson,