Asset workspace architecture

Each directory in packages/assets owns one editable format. Its src/asset/ code defines the kind, stored state, codec integration, and asset dependencies. Its src/network/ code defines the edit protocol and client sync. A format can keep other domain code elsewhere, such as voxel-model's src/model/.

Each kind keeps two files in src/asset/. <kind>.ts holds what an editor may import: the kind constants, the descriptor and the file builders. <kind>AssetKind.ts holds what only the server loads: the state, the file decoder and the kind handler. Decoders check stored files with the kind's zod schemas through SchemaParser from @jolly-pixel/network, and stay out of the client entry point. A malformed file throws InvalidAssetFileError from @jolly-pixel/asset-server, so the server can tell corrupt content from a handler bug.

The server owns rooms, the catalog, event history, and persistence. Each asset workspace supplies format-specific state and commands through an asset kind handler. The catalog room handles creation, rename, and deletion; an asset room handles edits to one open asset.

From edit to stored asset

The server replays recorded commands to restore live state and writes serialized snapshots after editing. A kind's apply function is the sole writer of its authoritative state; arbitration is committed after the event append succeeds. The author has already applied its command, so a refused, narrowed or unappended command is followed by a message to the author alone: a correction that restores only the refused part when the kind can build one (pixel-art and blockset pixel commands, voxel-map cell writes), otherwise a snapshot.

See the asset server architecture for the server contract. Asset source architecture describes the storage boundary. Format-specific rules live in the pixel-art, voxel-map, voxel-model, and voxel-animation architecture pages.