Add blueprints library to agentic UI

[katinthehatsite]

Related issues

Fixes STU-2321/

How AI was used in this PR

It was used to port the feature from the classic UI.

Proposed Changes

This PR brings the blueprints library to the agentic UI:

Testing Instructions

• Pull the changes from this branch
• Start Studio with npm start
• Enable the agentic UI
• Click on Create site and confirm that you can see the options to do it with blueprint.
• Select qny option to either select one of the blueprints from the blueprints library or what you have the option to upload a file

Pre-merge Checklist

• Have you checked for TypeScript, React or other console errors?

[wpmobilebot]

📊 Performance Test Results

Comparing 8704d13 vs trunk

app-size

Metric	trunk	8704d13	Diff	Change
App Size (Mac)	1425.56 MB	1425.60 MB	+0.03 MB	⚪ 0.0%

site-editor

Metric	trunk	8704d13	Diff	Change
load	1217 ms	1214 ms	3 ms	⚪ 0.0%

site-startup

Metric	trunk	8704d13	Diff	Change
siteCreation	7508 ms	7562 ms	+54 ms	🔴 0.7%
siteStartup	3376 ms	3370 ms	6 ms	⚪ 0.0%

---

Results are median values from multiple test runs.

Legend: 🟢 Improvement (faster) | 🔴 Regression (slower) | ⚪ No change (<50ms diff)

[gcsecsey]

While testing, I ran into an issue both while trying to select a blueprint from the gallery, and when trying to upload a blueprint.

I got this error for the gallery:

[2026-08-27T16:18:14.660Z][erro][main] Error occurred in handler for 'createSite': CliCommandError: [Last error message] Failed to start WordPress server: Path referenced in the Blueprint was not found in the execution context: ./kentwood.zip
  [Base message] Failed to create site
  [stdout] Would have recorded Tracks event: studio_site_start {
  platform: 'darwin',
  arch: 'arm64',
  app_version: '1.19.0',
  is_a11n: false,
  channel: 'studio-ui',
  ui_version: 'v2',
  success: false,
  failure_reason: 'unknown',
  time_ms: 1321
}
  [Exit code] 1

And this one for the blueprint upload:

[2026-08-27T16:19:27.049Z][erro][main] Error occurred in handler for 'createSite': CliCommandError: [Last error message] Failed to start WordPress server: Invalid Blueprint v1 provided. See the validation errors below:
Blueprint root["steps"][0]["pluginData"]:
Value did not match any of the allowed shapes: FileReference, DirectoryReference.
Property "resource" must be one of [vfs, literal, wordpress.org/themes, wordpress.org/plugins, url, bundled], but it was "git:directory".
  [Base message] Failed to create site
  [stdout] Would have recorded Tracks event: studio_site_start {
  platform: 'darwin',
  arch: 'arm64',
  app_version: '1.19.0',
  is_a11n: false,
  channel: 'studio-ui',
  ui_version: 'v2',
  success: false,
  failure_reason: 'unknown',
  time_ms: 1016
}
  [Exit code] 1

I'll investigate these further and push a fix if I found the root cause.

[katinthehatsite]

Thanks for testing @gcsecsey - I saw some errors as well but it was not these ones so I disabled some blueprints that threw other errors 👍 Maybe it does not take bundled blueprint or something?

[Poliuk]

@katinthehatsite, where are we pulling the blueprints from? We need to curate them to make sure every blueprint that we show is great

[katinthehatsite]

@Poliuk they are coming from https://blueprintlibrary.wordpress.com/ through the API but some of them are not enabled because of the error they were throwing. The ones meant for Studio have Studio category. Some of them are also set to drafts: https://blueprintlibrary.wordpress.com/wp-admin/edit.php?post_type=blueprint

It is fairly easy to disable them as they come from the client side. They can be turned off and on within seconds through that site if something does not work.

[katinthehatsite]

@gcsecsey it should not be resolve, the issue was related to processing bundleUrls that come from the blueprints library. Would you be able to give it another test?

[katinthehatsite]

@shaunandrews any feedback for the UI is also welcome 🙇 feel free to make direct changes to this PR

[katinthehatsite]

@gcsecsey Just a note is that I resolve the issue with the University website blueprint (the one resolved through the library) and I tested with blueprint file (attached to this message) and no longer saw the issues.

If you still see the issue with the blueprint file you shared, could you please paste it here and I can take a look? thanks!

[gcsecsey]

Thanks for the changes @katinthehatsite! I tested again with a couple blueprints from the gallery, and it's working well.

University	Photo gallery

Sorry I forgot to share earlier that I got the validation error when trying to upload the Cookbook blueprint.

For that I'm still getting the same error when trying to create the site. I checked that when we upload the Blueprint, at the selector we validate against the schema from @wp-playground/blueprints. But then when the site is created, blueprints.phar has a different schema.

I also tested with the blocky formats blueprint, which causes a validation error at the selector.

Selector error	Site creation error

I think it'd be worth unifying in a follow-up, but the user will get the same validation error, so this is just about when to surface it.

[shaunandrews]

Could we add these below the existing create a site screen instead of introducing a new option and screen?

[gavande1]

@katinthehatsite Would you be able to finish this, or would you like me to take it forward?

[gavande1]

I am taking over this task.

[gavande1]

@shaunandrews I removed the separate Blueprint screen. The Blueprints now sit on the Add a site screen below the four options, and uploading your own is one of the tiles there. Let me know if you would rather see them below the create site form instead.

cc @katinthehatsite

[shaunandrews]

Thanks! Gave this a spin and have a few suggestions. These are all fixed/updated in #4748 so you can cherry pick and split as you see fit.

--

The grid lines are showing through the blueprint cards. We should give the cards a fill; I think the main three cards (Create, Connect, Import) use a blur/transparent effect that we could reuse/copy.

--

If there's only a few blueprints (like now it seems less than 20) maybe we don't need the search input. So either we remove it and add it back, or make it's display conditional on having more blueprints.

--

We should hide the WordPress adminbar in the thumbnails. And it might be nice to add a subtle animation, sightly scaling the thumbnail on hover.

--

I can appreciate that the UI avoids creating an awkward layout by truncating longer descriptions, but I think we should shorten the descriptions, and allow for three lines as I suspect that will be more common with translated text.

We could also explore hiding the description, and show it as a floating tip while hovering/focusing the thumbnail.

--

I've always found these options a bit confusing, the WordPress Dev one especially (this is all wp dev). I'm wondering if we have any data around these options in the current UI; I managed to find the studio_site_created Tracks event, but I can't seem to find out data about specific blueprints used. Any ideas?

A few things I think might be worth trying:

1. Rename "WordPress Dev" to "Theme & plugin dev"
2. Move the WordPress.com, Theme & plugin dev, and WooCommerce options into the normal grid of blueprints.
3. Move the upload to a button, next to Search (or where Search would be).
4. Remove the line between sections, and use whitespace to help define the grouping.

--

--

We should also look to add more information about the selected/uploaded blueprint on the site settings screen:

[gavande1]

Thanks @shaunandrews, I merged #4748 and added two follow-ups on top.

The hover zoom was already there, but its transition was set to 8s, so the scale was not perceptible. It is now set to 0.4s. The upload button was transparent because the outline variant resolves to a fully transparent background token, so the grid lines showed through it. It now uses the same opaque surface token as the search input and stays consistent with the other outline buttons in the app.

@shaunandrews @gcsecsey requesting a final review when you get a chance.

[gcsecsey]

Thanks @gavande1 for iterating on this!

I tested it and it mostly looks and works great.

Step	Light mode LTR	Dark mode RTL
Add a new site
Create a new site

I found some smaller visual issues that I think we could still address before merging.

[wojtekn]

The UI looks good. I would consider dropping the threshold to always display the search field, or at least reducing it.

I tried using two blueprints and both failed:

Wedding RSVP	WordPress.com Blueprint

[gavande1]

Thanks @wojtekn for testing. I lowered the threshold to eight as requested in 839c677, so the search field shows with the twelve Blueprints we have today.

The both failures seems to be a download timeout rather than a Blueprint issue. The timeout is set inside the Blueprint runner, so we cannot change it from Studio. I would probably like to track that separately. Filed linear issue STU-2405.

[nightnei]

@shaunandrews , just personal feeling, so feel free to ignore - in the screenshot from the description, I see that we initially had the titles Add a site … “Or start from a blueprint which, in my opinion, worked really well. It allowed users to understand at a glance that Blueprints is a separate flow, so they should either chose one from three options or go with Blueprints option:

On trunk, the UX feels feels like "chose one of three options and ADDITIONALLY add a blueprint":

I would propose bringing back the wording “OR start from a blueprint” and centering it horizontally:

[nightnei]

Functionality-wise it works well 👍

[gavande1]

Let's follow up if any adjustments are required.