- **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
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
- 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.
## Summary
- Add CLI project import support from synced `.webstudio/data.json` into
another project via a destination share link.
- Move project bundle import/export contract into
`@webstudio-is/protocol`, including bundle versioning, staged upload
constants, schema validation, and fixture coverage.
- Upload project bundle data through staged TUS upload before calling
the import RPC to avoid request body limits.
- Upload referenced assets as binary files through the existing asset
upload route before importing asset rows.
- Add `--skip-assets` and `--ignore-version-check` import options.
- Add retry handling for transient missing imported asset files by
re-uploading only the reported missing assets.
- Share missing-asset import error formatting/parsing through protocol
to avoid duplicated string contracts.
- Preserve browser asset upload behavior while adding API upload
support.
- Normalize schema naming across the branch to lower-case names without
`Schema` suffix.
Closes https://github.com/webstudio-is/webstudio/issues/4586
Closes https://github.com/webstudio-is/webstudio/issues/4619
## Summary
Fixes shared Slot editing so linked Slot occurrences stay consistent
across structural edits and labels.
## Changes
- Fixed moving a direct Slot child out of a Slot so the child is removed
from all linked Slot occurrences.
- Fixed unwrapping a direct Slot child so the child is removed from all
linked Slot occurrences.
- Added linked Slot label sync when renaming from Navigator or Settings
panel.
- Added/updated tests for canonical Slots, legacy Slots, nested Slot
children, keyboard moves, unwrap, reparent, and label sync.
- Simplified stale Slot detach logic that was incorrectly cloning only
the selected Slot occurrence.
## Testing
- `pnpm --filter @webstudio-is/builder test --
app/shared/instance-utils/...`
- `pnpm --filter @webstudio-is/builder test --
app/builder/shared/commands.test.ts`
- `pnpm --filter @webstudio-is/builder typecheck`
- `pnpm lint`
- `git diff --check`
Limits projects to 8 editable breakpoints, with a toast warning when
users try to add more. Pasted/imported styles that exceed the limit are
merged into the closest existing breakpoint instead of creating new
ones.
Also updates the breakpoint editor UI with required names, hover-only
trash actions, scrolling, and tighter layout polish.
Closes https://github.com/webstudio-is/webstudio/issues/4209
- Add Token class and token() helper in template package for JSX token
support
- Refactor insertFragmentWithConflictResolution to
detectFragmentTokenConflicts
- Refactor insertPageWithConflictResolution to detectPageTokenConflicts
- Move dialog display to callers for better testability
- Add conflictResolution parameter to page-utils
- Add comprehensive tests for token functionality and conflict detection
- Fix bug: remove .values() call on arrays in breakpoint handling
Fixes https://github.com/webstudio-is/webstudio/issues/5491
## Description
- When pasting an instance with tokens, we can compare the name and the
contents. If they are identical, we can choose the existing one and
avoid having any conflicts.
- When pasting a token and the name is already used, add a numeric
suffix to it.
- find duplicate tokens command that will go based on content even if
name is different
## 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
Users started to build own marketplaces. And we found paste something
copied from other browser like firefox -> chromium based app doesn't
work. This is because OSs guarantee only text/plain to be stored in
system clipboard.
Here I changed copy paste logic to copy as text/plain and paste as both
application/json and text/plain if possible.
Ref https://github.com/webstudio-is/webstudio/issues/4093
Here a few delete instance improvements
- fixed deleting resources bound to props (action in webhook form)
- rewrote all tests with jsx template
- switched from instance selector to instance path
- added slot test
Every time somebody is facing invalid constraint issue whole tree is
blocked from deleting instances except the problematic one with actual
issue.
Here rewrote detachability check to validate only ancestors and avoid
traversing potentially problematic siblings.
Here replaced a bunch boilerplaty code with more general
findClosestInsertable. This also reduced amount of explicit instance
selector calls. Prevented inserting list item into body. Refactored
tests with jsx.
Ref https://github.com/webstudio-is/webstudio/issues/4364
We need to implement universal linking of current user view. For this I
added "awareness" state which reflects terminology from collaboration
libraries.
First migrated selected page id and fixed usages.
## Description
- webflow css preset
## 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:
5de6)
- [ ] 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
Here improved page duplicate logic to support replacing old variables in
page meta and path params variable with new references.
Also improved path duplicating to preserve path params by prefixing with
`/copy-n` subpath.
Ref https://github.com/webstudio-is/webstudio/issues/2532
Here refactored insertInstancesSliceCopy to accept webstudio data
instead of creating transaction.
This let us avoid hacky callbacks in duplicate instance and duplicate
page functionalities.
Note: review with hidden whitespaces
Here refactored delete instance to accept and mutate webstudio data
instead of accessing data stores.
Now we can avoid double transaction when delete pages.
Note: review with hidden whitespaces
Here added two new types
WebstudioFragment - reusable fragment of webstudio data which can be
generated (markdown, embed template), transferred (copied or stored in
marketplace) and inserted.
WebstudioData - all available normalized data to allow composing
multiple operations within single transaction like delete instance and
then insert into other part of the page.
Ref https://github.com/webstudio-is/webstudio/issues/2532
Important constrain on the way to custom components to not use data
sources defined in other components when copy paste.
## Steps for reproduction
1. Test covers it
Use same well tested utility to slice and insert its copy for copy
paste. Moved most utilities inside of instance plugin and added more
tests for it.
## Steps for reproduction
1. play with copy paste
Ref https://github.com/webstudio-is/webstudio/issues/2532
Here added a "core" collection component to support iterating over json
arrays.
There is a lot of room for unification of all this logic though would
require building reactive tree abstraction.
Canvas automatically renders stub component for collection to make it
droppable. We can do the same for slot component.
Slot and Fragment eventually will go to "core" components too.
Added json/parameter prop types to embed template to support collection.
Fixed loosing focus while typing in json prop.
## Steps for reproduction
1. Drop collection component
2. play with it
Ref https://github.com/webstudio-is/webstudio/issues/2532
On the last discussion about bindings we agreed expression are always
bound to single prop and cannot be reused.
Here added new prop.type = 'expression' as a replacement to
dataSource.type = 'expression'.
This will let us unify expression/variable reference and avoid deep
dependencies. Expressions and actions become similar.
For now both expression prop and legacy expression data source are
supported until we migrate completely in db.
Ref https://github.com/webstudio-is/webstudio/issues/2532
Here improved copy/paste behavior.
Before variables outside of copied tree were inlined. For example
ErrorMessage were loosing its expression when duplicated within same
form.
Now expressions and variables are preserved
and variables are inlined into expressions when paste target do not have
such variable. For example ErrorMessage get `"initial" == "error"`. With
upcoming UI it will be more obvious. The main idea here to not loose all
expressions but only references to unavailable variables.
Split instances slicer into separate utility from copy paste plugin.
Will be used to duplicate pages. Along with splitting added more tests
to better cover behavior.
New version of immerhin moved global queue into store instance so we can
stop filtering and just call store.popAll().
Also replaced default store with webstudio own serverSyncStore instance.
Now auto import works much better.
We are planning to move all types necessary to represent generated site
into separate package. This way we will be able to make CLI as small as
possible.
Here moved only assets schema. Now we get rid of aws, sharp and one
prisma usage (project-build still use it)
```diff
- 99MB
+ 75MB
```
Here added action copy paste support.
When all action dependencies are scoped to copied instance new variable
nams are ussed.
When some any dependency is not scoped execution is removed from copied
prop.
Here added meta.detachable flag which allows when set to true disable
copying, dragging and deleting instances of this component without ts
parent instance.
This is necessary to constrain components based on external code and
prevent deleting hidden components user cannot add again.
Fixes https://github.com/webstudio-is/webstudio-builder/issues/1994
Here changed behavior when copy and paste without changing instance
selection. Now it works as duplicating and copy is inserted after
selection.
Added cmd+d and ctrl+d shortcut to do this with single press without
polluting clipboard.
Here fixed the case when copy pasted form looses state and give errors
on submit.
Immerhin now converted to esm to work in tests.
Added tests for instances copy paste plugin.
The new logic is copy data sources as is if they are bound to copied
instances.
The new computeExpressionsDependencies used to detect if expression
depends on data sources outside of copied instances scope.
Fixes https://github.com/webstudio-is/webstudio-builder/issues/1950
Here added new utility to compute constraints for tree when insert embed
template, paste something or reparent. I previous implementation all
constraints were merged which gave us false positives like when paste
List>ListItem we got "requiredAncestors: [List]". Here tree layout is
considered to exclude such false positives.
For testing try to copy paste List>ListItem
Oleg Isonen