## Summary
- accept fixed page status codes as JSON numbers from 200 through 599
- preserve dynamic status expressions and backwards-compatible numeric
strings
- remove a stored status when the Builder input is cleared, while
leaving omitted status values untouched
- advertise the correct number-or-expression contract through runtime
and MCP schemas
- update CLI guidance and examples to use numeric status values
## Testing
- `pnpm --filter @webstudio-is/project-build exec vitest run
src/runtime/pages.test.ts src/contracts/builder-runtime.test.ts
src/mcp.test.ts`
- `pnpm --filter @webstudio-is/project-build typecheck`
- `pnpm --filter webstudio typecheck`
- `pnpm lint`
- `pnpm check:package-boundaries`
- `pnpm check:generated-api`
- `pnpm check:generated-docs`
Closes#5913
## Summary
- allow dragging a single image asset from the Assets panel onto the
canvas
- insert an Image component with its source bound to the dragged asset
in one undoable mutation
- preserve asset-folder drops and canceled drags
- build the Builder once in CI and reuse the compact build artifact
across all E2E shards
## E2E timing
Recent CI showed shard test runtimes of roughly 101–145 seconds, while
every shard also repeated a roughly two-minute Builder build. The four
shards are already reasonably balanced, so a fifth shard would not
address the primary bottleneck.
The shared artifact is about 30 MB uncompressed and roughly 5 MB
compressed because checked-out public assets are excluded. This should
return individual shard jobs to the 2–3 minute range.
## Validation
- 45 focused unit tests
- image asset to canvas E2E using the prebuilt-artifact path
- image asset to folder regression E2E
- Builder typecheck
- lint
- package-boundary validation
- workflow YAML validation
- shell syntax validation
## Summary
- center the reusable “Drop files here” state against the full
empty-folder area
- keep the Back thumbnail independently positioned and interactive
- add regression coverage for empty folders with additional content
- add a fourth builder E2E shard and split the serial asset-folder
workflows using measured CI durations
## Root cause
The Back thumbnail participated in the same column flow as the drop
state, reducing the drop state’s available height and shifting its
center downward.
The asset-folder E2E module also accumulated ten serial workflows and
became shard 1’s 214-second bottleneck.
## User impact
Empty folders now align the drop message consistently with the root
empty state and full-panel drag overlay.
The E2E split reduces shard 1’s measured workload from about 230 seconds
to a projected 113 seconds, with shard 4 at about 100 seconds.
## Validation
- focused asset tests: 62 passed
- E2E shard discovery test
- shard 1 and shard 4 module loading
- builder typecheck
- workspace typechecks
- lint
- package boundaries
- generated API and docs checks
- fixtures
- full workspace tests; three CLI subprocess tests initially timed out
under concurrent load and passed when rerun in isolation
## What changed
- documents `extract-slot.instanceSelector` as a leaf-to-root occurrence
path
- provides valid examples for sections directly under Body and nested in
a page wrapper
- exposes those examples through `meta.get_more_tools`
- makes invalid parent ordering errors explain how to recover using
`list-instances` IDs and `parentId`
- regenerates the public runtime schema with the selector contract
## Why
Agents could discover `extract-slot` but could not determine the
selector ordering expected by the runtime. Plausible selectors failed
with a generic direct-parent error, and focused MCP discovery returned
no working example.
## User impact
Agents can now reliably convert existing sections into shared Slots
without guessing the Navigator path format. Invalid selectors return
enough context to correct the call instead of repeatedly probing the
project.
## Verification
- project-build slot and MCP tests: 108 passed
- protocol operation docs and operation tests: 17 passed
- CLI MCP tests: 35 passed
- project-build, protocol, and CLI typechecks
- repository lint
- package-boundary check
- generated API and documentation checks
## Summary
- use the design-system native scroll area and auto-scroll long asset
lists during internal drag operations
- add a shared **Move** action to thumbnail and context menus for
individual and multiselected assets and folders
- add a folder-only move dialog that excludes invalid descendant
destinations
- consolidate bulk move, duplicate, delete, and clipboard behavior into
shared asset-manager operations with undo/redo coverage
- simplify dialog state, folder exclusion traversal, and long-list E2E
setup
## User impact
Users can drag assets or folders to destinations outside the currently
visible part of a long panel, and can move one or many selected items
through an explicit folder picker.
## Validation
- `pnpm --filter @webstudio-is/builder test
app/builder/shared/asset-manager` — 126 tests passed
- `pnpm --filter @webstudio-is/builder typecheck`
- `pnpm lint`
- `pnpm check:package-boundaries`
- focused builder E2E: dragging auto-scrolls a long folder list
- focused builder E2E: multiselected assets move from the context menu
## Review note
The current validation prevents missing destinations and folder cycles.
A small follow-up is still needed to disable moves when every selected
item is already in the chosen destination, avoiding a no-op mutation and
announcement.
## What changed
- Allow template-less component parts to be inserted when the target
parent explicitly permits them through `children`.
- Honor component parts permitted by an ancestor through `descendants`.
- Keep invalid standalone insertion blocked.
- Support legacy instances without a `children` field while resolving
ancestor selectors.
- Add regression coverage for Text Animation, Stagger Animation, nested
Radix parts, and legacy instances.
## Why
Text Animation and Stagger Animation were valid direct children of
Animation Group according to their content models, but the runtime
rejected every template-less component with `contentModel.category:
"none"` before considering its target parent.
The registry audit also found that hidden base and Radix component parts
could hit the same rejection through direct internal or MCP insertion,
even when an ancestor explicitly allowed them.
## Impact
Text Animation and Stagger Animation can now be inserted into Animation
Group. Programmatic insertion of hidden component parts also follows the
same content-model rules consistently.
## Validation
- `pnpm --filter @webstudio-is/project-build test` — 1,984 tests passed
- `pnpm --filter @webstudio-is/project-build typecheck`
- `pnpm lint`
- `pnpm check:package-boundaries`
- Formatting and diff checks
Closes https://github.com/webstudio-is/webstudio/issues/5877
Closes https://github.com/webstudio-is/webstudio/issues/4775
- Organize assets into nested folders.
- Navigate folders with breadcrumbs and Back controls.
- Select and manage multiple assets and folders at once.
- Drag, copy, cut, paste, duplicate, move, and delete items.
- Use context menus and familiar keyboard shortcuts for common actions.
- Search and sort assets and folders, with folders grouped first.
- Upload files directly into the active folder.
- Manage folder placement from asset and folder settings.
- Automate asset and folder management through MCP.
- **Restore points for agent work**: Create named restore points before
major edits, review changes with a dry run, and safely revert project
content if needed.
- **Shared Slot authoring**: Agents can turn existing sections into
shared Slots and insert linked copies across pages, including valid
nested Slots.
- **DTCG and Figma token imports**: Import design tokens and CSS
variables through CLI, MCP, or direct paste, with aliases, modes,
composite values, and mappings supported.
- **Consistent token conflict handling**: Every paste workflow now
offers the same preserve, rename, or merge choices instead of silently
overwriting existing design tokens.
- **Draft-page previews**: Agents can generate and inspect previews of
draft pages without publishing them or exposing drafts in production
builds.
- **Safer MCP mutations**: Destructive operations require explicit
confirmation, invalid raw patches and invented record IDs are rejected,
and restore operations commit atomically.
- **More dependable agent contracts**: New tools have complete runtime
schemas, clearer validation errors, and consistent behavior across CLI,
MCP, Builder, and server APIs.
## Summary
- remove the misleading **Connect your agent** section from Builder
Project Settings
- make the CLI the sole owner of MCP client configuration
- verify the linked project endpoint and credential before changing
client configuration
- safely merge Webstudio into existing Claude Code, Cursor, and VS Code
MCP files
- print the explicit global registration command for Codex instead of
editing its global configuration silently
- document the agent-led setup flow and safe handling of editable share
links
## Why
Builder runs in the browser and cannot configure files or global
settings on a user's local machine. The previous Project Settings UI
duplicated client definitions in the protocol package, exposed a setup
command containing the project credential, and could appear successful
without proving that the local agent was connected.
This moves local-client concerns into the CLI, removes the browser-only
setup surface, and makes configuration success depend on a valid,
reachable project link.
## User impact
A user can ask their agent to connect the current folder to Webstudio.
The agent links and synchronizes the project, runs `webstudio connect
<client>`, reloads the client, and verifies the connection by listing
project pages.
Invalid or stale links fail before any client file is changed, with a
credential-safe recovery message.
## Validation
- full CLI suite: 50 files, 786 tests
- full Builder suite: 163 files, 2,148 tests
- protocol suite: 73 tests
- CLI, Builder, and protocol typechecks
- root lint and package-boundary checks
- generated API and documentation checks
- real VS Code MCP handshake against a saved project: 156 tools
discovered
- fresh weak-model subagent test: repeated connection remained
idempotent and `meta.index` returned `ok: true`
## Summary
This combines the three reported MCP improvements into one release-ready
change:
- Safer mutation planning and confirmation for destructive operations.
- Much smaller MCP handshake and default discovery responses.
- Better agent workflows for checkpoints, multi-project work, and page
duplication.
## Safer destructive operations
- Exposes `dryRun` in MCP schemas for every local-capable mutation.
- Returns planned transactions through `meta.session.transaction`.
- Requires a two-step confirmation flow for destructive semantic
operations.
- Returns a short-lived token bound to the project, build version,
input, and exact generated patch plan.
- Rejects expired tokens, altered inputs, changed versions, and changed
plans.
- Sets `destructiveHint: true` only for operations that actually require
confirmation.
- Explicitly protects destructive operations whose names do not begin
with delete or replace, including replacing all redirects and clearing
all styles from a style source.
## Smaller, focused MCP context
- Defers oversized tool input schemas from the initial MCP handshake.
- Keeps complete focused schemas available through `meta.get_more_tools`
and CLI schema inspection.
- Makes template registry lists compact while preserving complete
payloads through focused get calls.
- Makes component summaries compact by default and supports paginated
component details.
- Replaces placeholder operation descriptions with useful command
descriptions.
- Constrains previously untyped JSON schema fields so clients can
validate inputs earlier.
- Keeps runtime output schemas compatible with strict MCP clients.
## Better agent workflows
- Allows read-only discovery and inspection while a workflow checkpoint
is awaiting acknowledgement.
- Continues blocking mutations until the checkpoint is acknowledged.
- Checks persisted checkpoints before every workflow call rather than
only the first call.
- Adds `--project` support so saved projects can be selected without
relinking the current directory.
- Isolates project sessions and checkpoints by selected project.
- Adds atomic `duplicate-page` substitutions for copied fixed text and
copied variable values.
- Prevents substitutions from modifying source content or global root
state.
- Rejects ambiguous or missing copied variables without leaving a
partial duplicate.
## Realistic agent verification
Minimal-context tests used a weak agent against the local packaged CLI
and stdio MCP:
- Planned a page deletion, stopped for explicit user confirmation,
committed the unchanged plan, and verified the page was absent.
- Tried to reuse a confirmation token with altered input; Webstudio
returned `DESTRUCTIVE_CONFIRMATION_INVALID` and preserved both pages.
- Verified compact handshake schemas and focused retrieval of the
complete oversized schema.
- Verified compact template and component discovery responses.
- Selected a saved project explicitly without relying on the directory
link.
- Verified checkpointed workflows permit reads but block mutations.
- Duplicated a London page into a Paris page with atomic text and
variable substitutions.
- Verified source content remained London, copied content became Paris,
and temporary pages were removed.
## Validation
- Project-build focused suites: 188 tests passed.
- CLI focused suites: 183 tests passed.
- Protocol focused suites: 21 tests passed.
- CLI, project-build, and protocol typechecks passed.
- Repository lint passed with zero warnings.
- Package-boundary validation passed.
- Generated runtime operation contracts were regenerated from source.
- Real local CLI/MCP tests passed against a running Builder server.
Closes#5887Closes#5888Closes#5889
## What changed
- Remap pasted breakpoint IDs when the same ID already belongs to a
different breakpoint in the destination project.
- Carry the remapped ID into pasted style declarations.
- Add a regression test for inserting a fragment whose breakpoint ID
conflicts with an existing project breakpoint.
## Why
HTML and Tailwind conversion uses compact fragment-local breakpoint IDs
such as `"0"` and `"1"`. In non-empty projects, one of those IDs can
already identify a different breakpoint. The fragment copy path
previously retained the incoming ID, causing the runtime to reject the
mutation with `Generated record id "1" already exists`.
## Impact
Pasting HTML with Tailwind classes now works in existing projects even
when generated fragment breakpoint IDs overlap project breakpoint IDs.
Matching breakpoints continue to be reused.
## Validation
- `pnpm --filter @webstudio-is/project-build test --
src/runtime/components.test.ts`
- `pnpm --filter @webstudio-is/project-build test --
src/runtime/fragment.test.tsx src/runtime/breakpoints.test.ts`
- `pnpm --filter @webstudio-is/project-build typecheck`
- `pnpm exec oxlint packages/project-build/src/runtime/fragment.ts
packages/project-build/src/runtime/components.test.ts`
- `pnpm exec oxfmt --check
packages/project-build/src/runtime/fragment.ts
packages/project-build/src/runtime/components.test.ts`
- `git diff --check`
## Description
`builder_backend_wait_for_db` checks readiness by running `psql` inside
the `db` container, which connects over the **unix socket**. The
official `postgres` image's entrypoint starts a temporary server with
`listen_addresses=''` (socket only) while it runs its init phase. During
that window the socket probe succeeds, but host-side clients (prisma
migrate, postgrest) connecting over TCP still get `connection refused` .
so the wait can return before the database is actually reachable.
It's a timing race: it rarely bites with a fast init, but it's
reproducible with slower images/machines (we hit it consistently in our
fork's CI, which uses a pg image with a longer init phase).
Fix: make the readiness probe connect the same way real clients do. Over
TCP (`psql -h 127.0.0.1`). `PGPASSWORD` is needed because host
connections use password auth, unlike the socket which is `trust`.
Same one-line change to the probe in `builder_backend_wait_for_db`;
behavior is otherwise identical.
## Steps for reproduction
1. `docker compose down -v` in `apps/builder` (force a fresh initdb)
2. run `dev/run-local.sh` (or anything using
`builder_backend_wait_for_db`)
3. on a slow machine the wait returns during the init phase and the
following `prisma migrate` / postgrest startup fails with `connection
refused`; with this patch the wait only returns once TCP is accepting
connections
## Code Review
- [ ] hi @kof, I need you to do
- detailed review (it's a one-line probe change in `dev/backend.sh`)
## Before requesting a review
- [x] made a self-review
- [x] added inline comments where things may be not obvious (the "why",
not "what")
## Before merging
- [ ] tested locally and on preview environment (preview dev login:
0000)
- [ ] updated test cases document n/a (dev tooling only)
- [ ] added tests -> n/a (shell dev script)
- [x] if any new env variables are added, added them to `.env` file ->
none added
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
## What changed
- mark published Head Slot descendants with an internal context
- portal JSON-LD scripts nested in Head Slot into `document.head`
- preserve page-flow rendering for JSON-LD used outside Head Slot
- add browser-DOM regression coverage for both placements
## Root cause
React hoists `title`, `meta`, and `link` elements rendered by Head Slot,
but it does not hoist inline `script type="application/ld+json"`
elements. As a result, JSON-LD nested in Head Slot remained under the
page body.
## Impact
JSON-LD placed in Head Slot now appears in the document head after the
published page mounts. JSON-LD intentionally placed outside Head Slot
remains in its original page position.
## Validation
- `pnpm --filter @webstudio-is/sdk-components-react test`
- `pnpm --filter @webstudio-is/sdk-components-react typecheck`
- targeted oxlint on changed files
- `pnpm --filter @webstudio-is/sdk-components-react build`
- `pnpm build`
## Summary
This improves how coding agents discover, author, verify, and audit
Webstudio projects through the CLI and MCP. The work focuses on making
agents more reliable with less context, while keeping edits semantic and
Builder-editable.
## What changes for users
- Agents can verify dynamic bindings after authoring and receive
actionable diagnostics when expressions, resources, scopes, or component
props do not line up.
- Agents can create complete resource-backed runtime UI through a
semantic operation instead of coordinating fragile low-level edits.
- MCP discovery and command output are compact by default, with
pagination and focused verbose detail when an agent needs more context.
- Asset, style, token, font, page, and component inspection provides
stronger usage context so agents can preserve the existing design
system.
- Rendered audits provide better evidence for responsive behavior,
geometry, contrast, generated-build size, and large-project runs.
- Cross-project MCP workflows can run from a manifest with explicit
mutation approval, isolated failures, resumable progress, and persistent
checkpoints.
- Project-specific agent onboarding is clearer and does not add
telemetry.
- Packaged CLI releases gain stronger smoke verification for install,
MCP startup, authoring, preview, screenshots, and audits.
## Reliability and architecture
- Runtime operation output schemas are generated from the runtime
registry and remain client-compatible.
- Project-build exports are consolidated around architectural boundaries
instead of feature-by-feature convenience entry points.
- HTTP, preview, screenshot, and project-session paths are hardened for
longer autonomous workflows.
- Craft compatibility work is read-only and provenance-aware; it does
not silently opt ordinary projects into Craft behavior.
- A minimal-context evaluation harness exercises key workflows with a
weaker model and stores bounded, privacy-safe evidence.
## Validation
- Rebased on the latest `origin/main`.
- `pnpm lint`
- Repository-wide `oxfmt --check`
- CLI typecheck and full test suite: 773 tests passed.
- Project-build typecheck and full test suite: 1,866 tests passed.
- Protocol typecheck and full test suite: 83 tests passed.
- HTTP client tests: 23 passed.
- CSS data tests: 3,620 passed, 1 skipped.
- Focused Builder tests: 67 passed.
- Package-boundary, generated API, and generated documentation checks
passed.
- Minimal-context agent evaluations passed for authenticated
resource-backed UI and design-system-aware responsive authoring.
Closes https://github.com/webstudio-is/webstudio/issues/3036
## Summary
- add an optional page-level draft state with a presentation-only
`[Draft]` prefix in Builder
- add **Mark as draft** and **Stage for publish** actions to the Page
details header menu
- keep drafts editable, previewable, linkable, duplicable, and
path-reserving in Builder
- exclude drafts from generated routes, public page collections, sitemap
output, staging, and production builds
- expose draft state and usage guidance through the runtime API, HTTP
client, CLI docs, and MCP contracts
## Why
Pages need a way to remain unfinished inside Builder without being
included in the next site deployment. Draft is an exclusion flag, not a
separate revision or publishing workflow state.
## Behavior and fixes
- home and `/*` catch-all pages cannot be drafts
- draft pages must be staged before becoming the home page
- restricted features used only on draft pages no longer block
publishing the publishable site
- **Stage for publish** only clears draft state; it does not deploy the
site
- missing or explicit `false` draft state remains backward-compatible
and publishable
## Validation
- 5,179 package tests passed across SDK, migrations, project-build, CLI,
and Builder
- targeted Builder browser E2E passed for draft/stage actions,
persistence, home-page guidance, copy, duplicate, delete, and
generated-app build behavior
- all affected package typechecks passed
- lint and package-boundary checks passed
- generated runtime contracts and CLI docs are reproducible
- `git diff --check` passed
## Summary
This improves how agents discover, author, inspect, and verify Webstudio
projects while reducing unnecessary MCP context usage.
## What changed
- Adds an **Agents** section to Project Settings with ready-to-run setup
commands and client configuration for Claude Code, Codex, Cursor, and VS
Code.
- Makes large list and schema responses compact and paginated by
default, with **verbose** available when complete records or diagnostics
are needed.
- Applies consistent compact output to assets, instances, styles, design
tokens, CLI schemas, and project-session metadata.
- Returns actionable expression warnings for props, resources, and
Collection bindings, including unknown variables and risky render-time
mutation resources.
- Improves Collection expression guidance so agents can bind array items
with the correct scoped variables.
- Reports rendered audit outcomes explicitly as complete, partial,
confirmation-required, or failed.
- Expands runtime output schemas so MCP clients can validate responses
reliably.
- Strengthens the packaged CLI smoke workflow with a realistic
seven-page stdio MCP scenario.
## Architecture
- Consolidates `project-build` from 65 file-oriented entrypoints to 11
architecture-owned surfaces.
- Separates the core model, contracts, runtime authoring, transfer,
state, project sessions, MCP, visual tooling, persistence codecs, and
authenticated server services.
- Isolates Node-only JSX evaluation from browser-safe transfer utilities
and authenticated server modules.
- Keeps persistence codecs independent from authenticated database
services, preventing unrelated module initialization.
- Defines shared instance-path types once and reuses them across runtime
modules.
- Preserves Immer initialization through explicit package side-effect
metadata.
- Adds package tests that prevent a return to source-file entrypoints or
generic exposure of Node-only surfaces.
## Validation
- Full repository checks, tests, typechecks, generated-file checks, and
fixtures
- All 163 Builder test files and 2,141 tests
- All 71 project-build test files and 1,794 tests
- Lint and package-boundary validation
- Full packed CLI release smoke test, including install, preview, agent
setup, seven-page stdio MCP workflow, rendered audit, and structured
commands
## What changed\n\n- Define concrete output schemas for every public
runtime operation.\n- Expose output schemas through generated runtime
contracts and MCP tool discovery.\n- Validate runtime results against
their declared schemas, including mutation result envelopes.\n- Add
output contracts for project-session status, refresh, reset, Collection
insertion, and generated-preview tools.\n- Make every advertised MCP
output schema explicitly object-shaped for strict clients.\n- Keep
generated schema definitions at the correct root so local references
resolve during tool discovery.\n- Report the correct session operation
metadata for refresh and reset.\n- Preserve local workspace package
resolution when the local CLI builds a generated React Router
preview.\n\n## Why\n\nAgents could discover input requirements, but
several tools did not describe their returned data. Strict MCP clients
could also reject the complete tool catalog during reconnect because
output schemas were not consistently object-shaped or contained
unresolved local references.\n\n## User impact\n\n- Agents can plan
calls from complete input and output contracts.\n- MCP clients can fetch
the full Webstudio tool catalog without schema-validation failures.\n-
Agents can reliably parse and validate command results.\n- Local
generated previews continue to work for visual verification.\n\n##
Validation\n\n- Every public runtime operation has an output schema.\n-
Every advertised MCP output schema is object-shaped and has resolvable
local references.\n- A real stdio MCP client connected through the local
CLI and fetched 154 tools, including 119 valid output schemas.\n-
Runtime output contracts validate representative query and mutation
results.\n- A fresh subagent refreshed a real project session, built and
started the generated site, captured the target route with HTTP 200,
checked preview status, and stopped the server.\n- Focused project-build
tests, project-build and CLI typechecks, lint, formatting, and
generated-doc checks passed.\n
## What changed
- Return structured validation issues with stable codes, complete field
paths, constraints, and minimal correction examples.
- Preserve validation details through the Builder API, CLI, MCP, local
project sessions, and tRPC errors.
- Explain invalid expressions, JSX fragments, page selectors, component
inputs, asset updates, and project settings in terms an agent can act
on.
- Remove stack frames and credentials from parser details before
exposing them.
- Keep concise human-readable errors while making the complete
structured issues available to agents.
## Why
Agents previously received vague errors without enough information to
repair a request. They could repeat the same invalid call or require
manual intervention.
## User impact
CLI and MCP agents can now identify the exact invalid field, understand
the constraint, see a valid example, and retry with a corrected request.
## Validation
- Focused runtime, MCP, CLI, API, and tRPC validation tests.
- Structured error propagation tests across local and server execution.
- Typechecks and generated contract verification.
## What changed
- Add an `insert-collection` MCP and CLI operation for creating repeated
UI from array or object data.
- Create the Collection, iterable binding, current-item/current-key
parameters, repeated item structure, and descendant bindings atomically.
- Accept literal JSON data or expressions backed by project variables
and resource results.
- Support `collectionItem` and `collectionItemKey` expressions inside
the repeated Webstudio JSX item.
- Return the created Collection, item root, and parameter IDs for
immediate inspection and follow-up edits.
- Document when agents should use Collection for lists, grids, cards,
rows, options, tabs, and other repeated content.
## Why
Building a data-driven list previously required several low-level
operations and manual handling of Collection's internal parameters. A
missed step could leave a partially configured or incorrectly scoped
Collection.
## User impact
Agents can turn resource or variable data into a correctly bound
repeated layout in one operation, then inspect and refine the result
normally.
## Validation
- Real-world local CLI test created and rendered a three-product
Collection from project data.
- Tests cover literal arrays, objects, resource expressions, item/key
bindings, malformed fragments, ID conflicts, server execution, and
project-session behavior.
- 176 focused tests, project-build typecheck, and generated-doc checks
pass after rebasing onto current `main`.
Fixes three MCP issues that could cause misleading mutation results,
unstable instance ordering, and project settings that disappeared after
refresh.
## Changes
- Prevents committed mutations from returning `PROJECT_SESSION_BUSY`.
- Ensures retrying after a reported failure cannot silently create
duplicate instances.
- Reconciles the local project session after a mutation commits
remotely.
- Adds deterministic append behavior with `position: "end"`.
- Preserves the requested order when moving multiple instances.
- Makes project settings updates persist across refreshes.
- Reports no-op project settings updates accurately.
- Updates MCP documentation and generated contracts for the new
behavior.
## Verification
- Reproduced and retested all three user reports with a subagent against
a real local project.
- Verified overlapping duplicate operations commit exactly once.
- Verified ordered moves remain correct after refresh.
- Verified project settings survive refresh.
- Passed all project-build tests: 1,745 tests.
- Passed all CLI tests: 720 tests.
- Passed type checks and lint.
This update helps AI agents understand, audit, and visually verify
Webstudio projects more reliably. It also adds clearer guidance for
expressions, Collections, screenshots, and responsive rendered audits.
### Audit complete projects
- Run one `audit` command across accessibility, SEO, security, assets,
styles, and performance.
- Audit the whole project or focus on a specific page, scope, or
severity.
- Receive stable findings with locations, explanations, and recommended
fixes.
- Continue large result sets through pagination without repeating
general guidance.
### Audit the rendered website
- Build and inspect the generated website, rather than relying only on
stored project data.
- Check every static page at representative mobile, tablet, and desktop
widths.
- Use one suitable viewport inside each configured breakpoint range.
- Reuse the same browser and resize pages between captures for
substantially faster audits.
- Process multiple pages concurrently while keeping resource use
bounded.
- Supply concrete examples for dynamic routes such as blog posts.
- Review and confirm unusually large screenshot plans before they run.
### Find visual and performance problems
Rendered audits can detect:
- Horizontal page overflow.
- Broken images.
- Images loaded eagerly below the fold.
- Images that are much larger than their rendered size.
- Render-blocking resources.
- Legacy font formats.
- Pages that fail to load or redirect somewhere unexpected.
- Pages captured before their layout becomes stable.
Detailed screenshots, measurements, failures, and timing evidence are
saved locally for further inspection.
### Capture generated pages directly
- Capture a project route with `webstudio screenshot --path /route`.
- Automatically generate and start a temporary production-style preview.
- Stop the temporary preview after the screenshot is captured.
- Return navigation, responsive layout, and page-size evidence with JSON
output.
- Allow external image domains needed by the generated preview.
### Reuse generated previews
- Cache generated preview builds when the project has not changed.
- Reuse preview dependencies across regenerations.
- Keep preview dependencies isolated from the user’s project
dependencies.
- Surface preview build and startup failures with useful diagnostic
output.
- Include local project assets in generated previews.
### Author Collections correctly
- Explain when Collection is required for arrays and objects.
- Guide agents to bind the complete iterable instead of one item or the
response wrapper.
- Explain how Collection repeats its children for every entry.
- Explain current-item and current-key scope.
- Preserve Webstudio’s generated Collection parameters.
- Guide agents to use stable values for repeated interactive components.
### Write expressions with fewer mistakes
- Add a dedicated `webstudio://project/expressions` reference.
- Document expression scope, supported syntax, and supported methods.
- Explain how resources, variables, Collections, actions, and `system`
values are accessed.
- Distinguish fixed values from runtime expressions.
- Provide valid examples for text, props, resource URLs, headers, query
parameters, and bodies.
- Warn agents that valid syntax does not guarantee that runtime data has
the expected shape.
### Improve agent discovery
- Make Collection and expression workflows discoverable through
`meta.guide`.
- Return Collection-specific instructions through `components.get`.
- Point relevant command schemas to the expression reference.
- Keep detailed guidance available without placing it in every tool
response.
### Improve audit reliability
- Report which rendered captures passed, found issues, failed, or were
skipped.
- Distinguish planning, preview, capture, and cleanup failures.
- Include actionable retry instructions with rendered failures.
- Preserve completed evidence when part of an audit fails.
- Detect stale or conflicting preview servers more clearly.
- Support cancellation and bounded capture timeouts.
### Improve packaged CLI verification
- Add a release-shaped CLI smoke test.
- Install the packed CLI in an isolated temporary project.
- Fail on peer-dependency warning floods.
- Verify preview, screenshots, MCP calls, rendered audits, and generated
assets.
- Confirm that generic React Router previews do not include Docker-only
image dependencies.
- Keep CLI and MCP stdout machine-readable while progress remains on
stderr.
## User Impact
Agents can now audit a real rendered Webstudio site, inspect responsive
behavior, find concrete visual and performance problems, and provide
evidence for their conclusions. They also receive much clearer
instructions when turning API data into repeated content or writing
dynamic expressions.
Improves CLI and MCP reliability across project synchronization, asset
editing, imports, audits, and clipboard workflows.
## Changes
- Keeps asset filename and description updates after session refresh.
- Prevents intermittent Immer patch errors during consecutive MCP
mutations.
- Prevents false edit conflicts caused by stale local session state.
- Preserves asset uploads without treating them as redundant metadata
updates.
- Exposes editable asset filenames consistently through MCP.
- Imports project assets correctly when copying projects between
environments.
- Supports refreshing partially available project snapshots.
- Keeps MCP operations working when optional project data is
unavailable.
- Produces clearer compatibility errors when the API and CLI versions
differ.
- Makes rendered audits more resilient when individual screenshots fail.
- Prevents rendered audits from hanging while starting browser captures.
- Handles denied clipboard permissions without uncaught browser errors.
- Improves copy and paste reliability for pages, components, styles, and
animations.
## Verification
- Asset uploader tests and typechecking pass.
- Focused asset workflow E2E passes.
- Complete E2E shard 1 passes.
- Realistic MCP subagent test confirms:
- Asset filename and description persist after refresh.
- Consecutive mutations work without manual refresh.
- No Immer patch error occurs.
- No false conflict occurs.
- Original asset values can be restored successfully.
## Summary
This update adds new MCP and CLI capabilities for project auditing,
structured data, project-specific agent instructions, focused project
search, safer bulk editing, image descriptions, font discovery, visual
verification, and external registry inspection.
## New Capabilities
### Audit projects
- Run a single `audit` command across accessibility, SEO, security,
assets, styles, and performance.
- Limit an audit to selected scopes, pages, or severity levels.
- Receive stable findings with locations and suggested fixes.
- Run rendered audits across desktop, mobile, and Builder breakpoint
widths.
- Detect horizontal overflow, broken images, oversized images, eager
below-fold images, render-blocking resources, and legacy font formats.
- Identify unused assets, tokens, CSS variables, local styles, and
breakpoints.
- Identify duplicate token declarations.
- Detect accessibility issues involving names, labels, headings,
landmarks, IDs, keyboard focus, ARIA, iframes, and autoplaying media.
- Detect SEO issues involving titles, descriptions, language, social
images, and structured data.
- Detect unsafe new-tab links and write resources exposed during page
rendering.
### Search an entire project
- Search project text, labels, props, resources, assets, and styles
through `search-project`.
- Find relevant records without downloading and reparsing the full
project snapshot.
- Scope searches to the relevant project-data areas.
### Add validated JSON-LD
- Add structured data with a dedicated JSON-LD component.
- Place JSON-LD inside the page Head Slot.
- Edit JSON in a purpose-built code editor.
- Prevent structurally invalid JSON-LD from being saved.
- Validate Schema.org types, properties, and values.
- Find invalid, missing, unknown, deprecated, or incompatible structured
data through the SEO audit.
- Let agents discover the correct JSON-LD workflow without using page
custom metadata or a generic HTML embed.
### Configure project-specific agent instructions
- Add AI-agent instructions from the new **Agents** section in Project
Settings.
- Synchronize those instructions into a managed root `AGENTS.md`.
- Update or remove the managed file automatically during project sync.
- Protect existing user-owned `AGENTS.md` files from being overwritten.
- Share the instructions with authenticated CLI and MCP agents.
- Keep agent instructions out of publicly readable production bundles.
### Generate and manage image descriptions
- Audit image assets for missing descriptions.
- Let a vision-capable agent inspect each image in its rendered context.
- Save generated descriptions to multiple image assets in one operation.
- Mark images as intentionally decorative.
- Reuse the saved asset description wherever the image is used.
- Re-run the audit to verify that missing-description findings are
resolved.
### Perform bounded bulk replacements
- Replace matching literal text across selected pages with
`replace-text`.
- Replace matching fixed prop text with `replace-prop-text`.
- Replace matching resource names or URLs with `replace-resource-text`.
- Restrict replacements by page, instance, prop, resource, field, match
mode, and maximum change count.
- Leave dynamic expressions unchanged.
### Inspect element ancestry
- Return an element’s direct parent in instance listings.
- Request the complete ancestor chain when inspecting an element.
- Understand tree placement without rebuilding the instance hierarchy
from raw project data.
### Discover available fonts
- List uploaded font families through `list-fonts`.
- Discover available system font stacks.
- Inspect font family, style, weight, format, and associated asset
information before applying typography.
### Inspect external component registries
- Inspect a local or remote shadcn-style registry item.
- Read its description, files, dependencies, targets, and documentation.
- Receive an explicit Webstudio compatibility report.
- Inspect registry metadata without installing or executing external
code.
### Capture generated project routes directly
- Run `webstudio screenshot --path /route` against the configured
project.
- Generate a temporary production-style preview automatically.
- Capture the requested route.
- Stop the temporary preview after capture.
- Avoid manually building and starting a preview for a single
screenshot.
### Assert visual changes
- Add expected text to screenshot comparisons.
- Set maximum pixel mismatch limits.
- Set minimum or maximum changed-region counts.
- Assert whether overall brightness or a color channel moved in the
expected direction.
- Use these assertions as pass/fail evidence for visual changes.
### Require compatible CLI versions
- Send the project-bundle contract version with CLI synchronization
requests.
- Stop incompatible CLI versions before they receive incomplete project
data.
- Tell users exactly how to update the CLI or run the latest version
once.
- Prevent older clients from silently dropping project settings.
## Upgrade Note
This branch introduces a new synchronized project-bundle contract. Older
CLI versions must update before synchronizing against the new API.
```sh
npm install -g webstudio@latest
```
Or run the latest version once:
```sh
npx webstudio@latest <command>
```
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
## prettier -> oxfmt (0.58.0)
- .oxfmtrc.json generated with `oxfmt --migrate=prettier`: trailingComma
es5, printWidth 80 (oxfmt defaults to 100), sortPackageJson disabled,
.prettierignore patterns folded in (file deleted).
- ignorePatterns additionally exclude yml/yaml/toml/jsonc and
packages/cli/templates/** so oxfmt covers exactly the file set prettier
used to format (ts,tsx,js,json,css,md) and never touches user-facing
scaffolding artifacts.
- root `format` script, nano-staged pre-commit hook and the CI check
(`pnpm oxfmt --check`, replacing `prettier --cache --check` and its
actions/cache step — oxfmt checks the whole repo in ~0.7s) now run
oxfmt.
- every generator script that ran `prettier --write` on __generated__
output now runs `oxfmt` (css-data, icons, html-data, postgrest, sdk,
sdk-components-*, apps/builder tailwind preflight).
- the four scripts that used prettier's JS `format()` API write raw
source instead and their package.json scripts pipe the generated file
through the oxfmt CLI: project-build generate-docs +
generate-runtime-operation-contracts, cli generate-docs, apps/builder
generate-server-only-api-metadata. oxfmt rejects paths containing "..",
so cross-package generated files are formatted via a subshell cd into
the owning package.
- one-time reformat: oxfmt's canonical output differs from prettier on 8
repo source files (binary-operator continuation indent, import() call
wrapping, sub-pixel spacing of empty for-clauses); oxfmt honors existing
`// prettier-ignore` comments so intentional layouts are kept.
- prettier remains ONLY as a cli devDependency for the
prettier/standalone HTML normalizer inside html-to-jsx.test.ts, and
inside fixtures/ + packages/cli/templates/ (ships to scaffolded user
projects; out of scope here).
- editor config switched from esbenp.prettier-vscode to oxc.oxc-vscode
(devcontainer extension list, .vscode editor.defaultFormatter).
## oxlint 1.56 -> 1.73
- oxlint 1.73 rules-of-hooks special-cases hooks NAMED useEffectEvent:
their results may only be called from effects. Our
app/shared/hook-utils/effect-event.ts is a stable-callback helper
(useEvent pattern), intentionally called from event handlers and passed
as props. The rule is disabled via .oxlintrc.json overrides for the five
files doing this (product code untouched); note those files lose
hook-order linting entirely until the rule becomes configurable.
## TypeScript 5.8.2 -> 7.0.2 (native compiler)
- `tsc` is now the Go-based native binary; all `tsgo` script usages
(workspace packages and fixtures) renamed back to `tsc` and
@typescript/native-preview removed (the package is being phased out).
- fixes for TS7 changed defaults and stricter checks:
- `types` now defaults to [] -> base tsconfig sets "types": ["node"]
(restores the implicit-@types/node behavior of TS5).
- `rootDir` now defaults to ./ -> every tsconfig.dts.json sets
"rootDir": "./src" (TS5011 otherwise).
- import assertions removed -> cli/src/cli.ts uses `with { type: "json"
}` (TS2880).
- stricter isolatedDeclarations inference -> explicit annotations in
css-data bin/property-filter.ts (TS9010) and image image-dev.stories.tsx
(TS9013).
- declaration serialization limit -> project-build builder-runtime.ts
runtimeOperationContracts gets an explicit type (TS7056); the annotation
preserves the narrow RuntimeOperationId union.
- TS7 ships no stable programmatic API:
- react-sdk (component-generator tests drive the compiler API) aliases
its typescript devDependency to @typescript/typescript6@^6.0.2; its bin
is `tsc6`, so the package's typecheck still runs native TS7 tsc from the
workspace root.
- generate-arg-types keeps typescript 5.8.2 for react-docgen-typescript.
- fixtures/ and packages/cli/templates/ keep typescript 5.8.2
(user-facing); fixture scripts still work because plain `tsc` resolves
to their local dependency.
## vite -> rolldown-vite 7.3.1 (oxc bundler)
- global pnpm override `"vite": "npm:rolldown-vite@^7.3.1"`: the builder
app (remix v2 vite plugin works unmodified), every package vite build
and the storybook build now bundle on rolldown/oxc.
- vitest is scoped BACK to vanilla vite via `vitest>vite`,
`vite-node>vite` and `@vitest/mocker>vite` overrides because vitest
3.1's runner does not understand rolldown's SSR transform
(__vite_ssr_exportName__ ReferenceError in every suite).
- those overrides pin vite EXACTLY to 6.3.4: letting ^6.3.4 float to
6.4.3 breaks cli prebuild tests (dynamic import of a generated
app/routes/$.tsx fails to resolve under 6.4.3's loader).
## unrelated cleanup requested during review
- apps/builder commands.ts imports duplicate-tokens-group statically
instead of via dynamic import. The circular dependency the dynamic
import guarded against only exists through the command-panel barrel
(command-panel.tsx > groups/index.ts > commands-group.tsx >
commands.ts); importing the group module directly is cycle-free
(verified with madge), matching the neighboring wrap-group and
convert-group imports.
## verification
- pnpm lint, oxfmt --check: clean.
- pnpm -r typecheck (TS7 native) and pnpm dts: clean.
- pnpm -r test: all suites pass (builder 2093 tests, cli 630, react-sdk
45, project-build 11, ...).
- builder app build, full workspace build, cli build and storybook build
all succeed on rolldown-vite.
## Description
1. What is this PR about (link the issue and add a short description)
## Steps for reproduction
1. click button
2. expect xyz
## Code Review
- [ ] hi @kof, I need you to do
- conceptual review (architecture, feature-correctness)
- detailed review (read every line)
- test it on preview
## Before requesting a review
- [ ] made a self-review
- [ ] added inline comments where things may be not obvious (the "why",
not "what")
## Before merging
- [ ] tested locally and on preview environment (preview dev login:
0000)
- [ ] updated [test
cases](https://github.com/webstudio-is/webstudio/blob/main/apps/builder/docs/test-cases.md)
document
- [ ] added tests
- [ ] if any new env variables are added, added them to `.env` file
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
- Fix publish sync for empty JSON data variables
- Retry transient asset downloads once with shared sync-client backoff
- Fix Builder paste handling for Webstudio transfer data
- Add transfer/data-envelope terminology and colocated runtime
data-format modules
- Rename page clipboard runtime operation to page transfer semantics
- Report malformed Webstudio/Webflow paste data through paste results
instead of inserting it as text
- Add browser-level E2E coverage for instance, page, folder, template,
generic plugin, malformed data, native input, and content-mode paste
flows
## Details
- Allows empty JSON data variables to sync/publish correctly.
- Adds asset download retry coverage and uses shared backoff logic.
- Introduces runtime `data-formats` modules for data envelopes, instance
transfer data, and page transfer data.
- Removes stale clipboard aliases and `validateTemplateStructure`.
- Keeps clipboard as a Builder UI transport concern while
runtime/protocol use transfer-data terminology.
- Changes paste plugins to return expressive success/error results so
callers can show toast errors and stop fallback insertion.
- Prevents malformed Webstudio transfer payloads from falling through to
text/HTML/markdown insertion.
- Handles malformed Webflow-owned paste data without throwing.
- Adds shared copy-paste fragment insertion helpers to reduce duplicated
breakpoint-warning/fragment-data logic.
This PR expands Webstudio MCP and CLI into a more complete agent
authoring interface. Agents can discover project capabilities, edit real
Webstudio content, use data/resources, verify visual output, and report
useful issues when workflows fail.
## MCP User Capabilities
- Create, update, duplicate, reorder, and delete pages.
- Create pages from templates and manage reusable page templates.
- Inspect project pages, instances, props, styles, assets, variables,
resources, and metadata.
- Insert Webstudio components and authored JSX fragments into pages.
- Edit text, props, styles, breakpoints, design tokens, and CSS
variables.
- Update page metadata, SEO fields, redirects, marketplace metadata, and
project settings.
- Create and use static data variables.
- Create and use dynamic resources fetched over HTTP.
- Use REST, GraphQL, and built-in system resources in authored pages.
- Bind data variables and resources to visible page content.
- Create resource-backed pages such as sitemap XML, structured SEO data,
and API-driven content sections.
- Preview current project state without requiring a publish step.
- Capture screenshots for visual verification.
- Verify responsive designs across desktop, tablet, and mobile
breakpoints.
- Use screenshot diff and OCR-style checks to inspect rendered output.
- Reset and refresh local MCP project state when needed.
- Discover available CLI/MCP commands from generated manuals.
- Use clearer examples for resources, data variables, JSX authoring,
previewing, and visual checks.
- Read marketplace product metadata without requiring a full project
snapshot.
- Get safer guidance when using low-level patch tools.
- Get a ready-to-copy Discord report template when MCP/CLI behavior is
confusing or broken.
1. fix the issue with expressions requiring string when expression, this
is an issue not only for meta in page settings but for any field that
supports bindings
2. make sure llm knows when to use bindings and when to just set the
string value, test it with a subagent without additional context
Oleg Isonen