# 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.