#server.src.pixelweaver.protocol

#server.src.pixelweaver.protocol

Pydantic models for the PixelWeaver WebSocket JSON protocol.

Client -> Server message types: command -- dispatch a drawing/editing command sync_request -- request full state snapshot undo -- undo last command redo -- redo last undone command

Server -> Client message types: command_ack -- command accepted command_reject -- command rejected with reason error -- generic error

A sync_request is answered with a state_patch carrying a single authoritative-replace full_state patch (see websocket._handle_sync_request), not a bespoke message type.

#CommandPayload

The inner command object sent by the client.

#CommandMessage

Client dispatches a command for execution.

#SyncRequestMessage

Client requests a full state snapshot.

#UndoMessage

Client requests undo of the last command.

command_id (optional) is the id of the command the CLIENT just undid locally. When present, the server verifies it matches the id at the top of its command history before reverting -- a mismatch means the client and server histories have diverged and the undo is rejected loudly rather than silently reverting the wrong command.

#RedoMessage

Client requests redo of the last undone command.

command_id (optional) is verified against the top of the server's redo stack; a mismatch is rejected (see UndoMessage).

#CommandAckMessage

Server confirms a command was accepted and executed.

#CommandRejectMessage

Server rejects a command with a reason.

#ErrorMessage

Generic error message.

#StatePatch

Base for all state patches.

#PixelPatch

A patch to pixel data on a specific layer/frame.

plane is the EXPLICIT payload discriminator: "rgba" carries flat RGBA bytes (wh4), "role" carries role-plane bytes (w*h, 0xFF sentinel = transparent). Never inferred from byte length -- sizes can coincide.

#LayerPatch

A patch to the layer tree structure.

#CanvasPatch

A patch to canvas dimensions.

#FramePatch

A patch to frame structure (add/remove/reorder/set_duration).

#FullStatePatch

A full state replacement (initial sync or large MCP operations).

#PatchMessage

Wrapper message broadcast via WebSocket carrying one or more patches.

#parse_client_message

def parse_client_message(raw: dict[str, Any]) -> ClientMessage

Parse a raw dict into one of the client message types.

Raises ValueError if the message is malformed or has an unknown type.