mirror of
https://github.com/webstudio-is/webstudio.git
synced 2026-10-29 08:07:48 +09:00
Oleg Isonen
dde30ffb54
## 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
35 lines
1.6 KiB
Markdown
35 lines
1.6 KiB
Markdown
# Protocol
|
|
|
|
`@webstudio-is/protocol` owns Webstudio data exchange protocols.
|
|
|
|
The project bundle is the external export/import artifact used by sync, local
|
|
`.webstudio/data.json`, project import, transferred asset files, and prebuild.
|
|
This package owns the assembled bundle schemas, transfer RPC payloads, and
|
|
bundle compatibility/version helpers.
|
|
|
|
Domain models such as pages, assets, and serialized builds remain owned by
|
|
their domain packages and are composed here through schema-only entrypoints.
|
|
Do not copy those schemas into this package.
|
|
|
|
## Terminology
|
|
|
|
**Project bundle** is the authoritative external project artifact. It is used by
|
|
sync, `.webstudio/data.json`, project import, transferred asset files, and
|
|
prebuild.
|
|
|
|
**Data envelope** is a serialized single-key object whose key is a versioned
|
|
Webstudio marker, for example `{ "@webstudio/instance/v0.1": data }`. The
|
|
envelope identifies the payload version and lets consumers detect malformed
|
|
Webstudio-owned data before falling back to other formats.
|
|
|
|
**Transfer data** is the domain payload inside a data envelope. Examples include
|
|
`InstanceTransferData`, `InstancesTransferData`, and `PageTransferData`.
|
|
Transfer data is portable and detached from a project; insertion/import remaps
|
|
ids and merges it into authoritative project state. Runtime-owned transfer
|
|
formats live in `@webstudio-is/project-build/transfer`.
|
|
|
|
**Clipboard data** is a UI transport concern. Builder copy/paste may serialize
|
|
transfer data into a data envelope and place it on the browser clipboard, but
|
|
runtime and protocol code should name the reusable format as data envelope or
|
|
transfer data, not clipboard.
|