@tensnap/protocol 0.2.0 → 0.2.1

package/dist/protocol-types.md

@@ -0,0 +1,1342 @@
+# TenSnap Protocol Type Definitions
+
+This file is generated from the runtime Zod schemas. Edit `src/*.ts`, not this file.
+
+## Package Metadata
+
+| Field | Value |
+| --- | --- |
+| Package | `@tensnap/protocol` |
+| Version | `0.2.1` |
+| Description | Canonical TenSnap renderer/simulator protocol payload types, schemas, and codecs. |
+| License | `MIT` |
+| Generated At | `2026-07-09T18:05:00.513Z` |
+| Source Files | `packages/protocol/src/asset.ts`, `packages/protocol/src/chart.ts`, `packages/protocol/src/controls.ts`, `packages/protocol/src/layers.ts`, `packages/protocol/src/schemas.ts`, `packages/protocol/src/types.ts` |
+
+## Payload Schemas
+
+### MetadataUpdatePayload
+
+Schema: `MetadataUpdatePayloadSchema` (schemas.ts)
+
+`metadata_update` carries scenario-wide metadata, including the current
+simulation time. It replaces the old split between time-step start and end
+events, and may carry additional simulator-defined metadata fields.
+
+```ts
+export type MetadataUpdatePayload = {
+    time?: number | undefined;
+    [x: string]: unknown;
+};
+```
+
+### StateSyncBoundaryPayload
+
+Schema: `StateSyncBoundaryPayloadSchema` (schemas.ts)
+
+`state_sync_begin` and `state_sync_end` bracket a simulator replay triggered
+by `state_sync`. When present, `request_id` is generated by the renderer and
+echoed by the simulator so initial sync and reconnect transactions can be
+correlated without making Scenario transport-aware.
+
+```ts
+export type StateSyncBoundaryPayload = {
+    request_id?: string | undefined;
+};
+```
+
+### TickTimingBreakdown
+
+Schema: `TickTimingBreakdownSchema` (schemas.ts)
+
+Optional per-action timing buckets used for tick diagnostics.
+
+```ts
+export type TickTimingBreakdown = {
+    simulate_ms?: number | undefined;
+    communicate_ms?: number | undefined;
+    render_ms?: number | undefined;
+    [x: string]: number;
+};
+```
+
+### ActionEndPayload
+
+Schema: `ActionEndPayloadSchema` (schemas.ts)
+
+`action_end` signals completion of one simulator action execution. Simulators
+should emit state mutations caused by the action before the matching
+`action_end`. For continuous actions, explicit `continue: false` stops the
+renderer-driven loop; `tick_id` should echo the renderer-supplied id.
+
+```ts
+export type ActionEndPayload = {
+    id: string;
+    tick_id?: string | undefined;
+    continue?: boolean | undefined;
+    timings?: TickTimingBreakdown | undefined;
+};
+```
+
+### ActionDeletePayload
+
+Schema: `ActionDeletePayloadSchema` (schemas.ts)
+
+`action_delete` removes a renderer-visible action by id.
+
+```ts
+export type ActionDeletePayload = {
+    id: string;
+};
+```
+
+### EnvCreatePayload
+
+Schema: `EnvCreatePayloadSchema` (schemas.ts)
+
+`env_create` creates a scenario environment container. `2d` covers grid-like
+and graph-like scenes; rendering semantics are expressed by layers.
+
+```ts
+export type EnvCreatePayload = {
+    id: string;
+    type: "uniform" | "2d";
+};
+```
+
+### EnvDeletePayload
+
+Schema: `EnvDeletePayloadSchema` (schemas.ts)
+
+`env_delete` removes a scenario environment container by id.
+
+```ts
+export type EnvDeletePayload = {
+    id: string;
+};
+```
+
+### EnvLayerCreatePayload
+
+Schema: `EnvLayerCreatePayloadSchema` (schemas.ts)
+
+`env_layer_create` creates an environment-local layer with fixed topology and
+optional metadata. `dependency_layer_ids` is create-time topology; simulators
+should recreate the layer or environment if dependencies need to change.
+
+```ts
+export type EnvLayerCreatePayload = {
+    env_id: string;
+    layer_id: string;
+    layer_type: string;
+    dependency_layer_ids?: {
+        [key: string]: string;
+    } | undefined;
+    data?: {
+        [key: string]: unknown;
+    } | undefined;
+};
+```
+
+### EnvLayerUpdatePayload
+
+Schema: `EnvLayerUpdatePayloadSchema` (schemas.ts)
+
+`env_layer_update` replaces layer metadata as a whole object. It is not an
+item diff channel and must not be used to mutate dependency topology.
+
+```ts
+export type EnvLayerUpdatePayload = {
+    env_id: string;
+    layer_id: string;
+    data: {
+        [key: string]: unknown;
+    };
+};
+```
+
+### EnvLayerDeletePayload
+
+Schema: `EnvLayerDeletePayloadSchema` (schemas.ts)
+
+`env_layer_delete` removes one layer from an environment.
+
+```ts
+export type EnvLayerDeletePayload = {
+    env_id: string;
+    layer_id: string;
+};
+```
+
+### ItemCreatePayload
+
+Schema: `ItemCreatePayloadSchema` (schemas.ts)
+
+`item_create` creates layer-owned items. The exact item schema and primary
+key are provided by the layer registry entry for the target layer type.
+
+```ts
+export type ItemCreatePayload = {
+    env_id: string;
+    layer_id: string;
+    items: ItemRecord[];
+};
+```
+
+### ItemUpdatePayload
+
+Schema: `ItemUpdatePayloadSchema` (schemas.ts)
+
+`item_update` carries field-level diffs for existing layer-owned items.
+Diffs must include the layer registry primary key fields so the renderer can
+identify each target item.
+
+```ts
+export type ItemUpdatePayload = {
+    env_id: string;
+    layer_id: string;
+    items: ItemDiff[];
+};
+```
+
+### ItemDeletePayload
+
+Schema: `ItemDeletePayloadSchema` (schemas.ts)
+
+`item_delete` removes layer-owned items. Single-key layers may delete by
+primitive id; multi-key layers, such as edge layers keyed by source/target,
+delete by object keys matching the registry primary key fields.
+
+```ts
+export type ItemDeletePayload = {
+    env_id: string;
+    layer_id: string;
+    items: PrimitiveItemKey[] | ItemKey[];
+};
+```
+
+### ParameterDeletePayload
+
+Schema: `ParameterDeletePayloadSchema` (schemas.ts)
+
+`param_delete` removes a renderer-visible parameter by id.
+
+```ts
+export type ParameterDeletePayload = {
+    id: string;
+};
+```
+
+### ParameterSyncPayload
+
+Schema: `ParameterSyncPayloadSchema` (schemas.ts)
+
+`param_sync` pushes a simulator-side value correction after an optimistic
+renderer edit. A simulator should not emit `param_sync` for every accepted
+`param_change`; it should emit one only when it rejects the edit or coerces it
+to a different canonical value. Definition changes, including enum option or
+label-list changes, are sent with full `param_update` payloads instead.
+
+```ts
+export type ParameterSyncPayload = {
+    id: string;
+    value: unknown;
+};
+```
+
+### ChartDeletePayload
+
+Schema: `ChartDeletePayloadSchema` (schemas.ts)
+
+`chart_delete` removes a chart or chart series by id.
+
+```ts
+export type ChartDeletePayload = {
+    id: string;
+};
+```
+
+### ChartUpdatePayload
+
+Schema: `ChartUpdatePayloadSchema` (schemas.ts)
+
+`chart_update` carries incremental data points and chart operations such as
+`clear`. Chart metadata is maintained separately through `chart_create`.
+
+```ts
+export type ChartUpdatePayload = {
+    updates?: ChartUpdateData[] | undefined;
+    operations?: ChartUpdateOperation[] | undefined;
+};
+```
+
+### LogPayload
+
+Schema: `LogPayloadSchema` (schemas.ts)
+
+`log` is a diagnostic event emitted by either runtime side.
+
+```ts
+export type LogPayload = {
+    message: string;
+    level?: LogLevel | undefined;
+    target?: string | undefined;
+    timestamp?: number | undefined;
+    data?: unknown | undefined;
+};
+```
+
+### ErrorPayload
+
+Schema: `ErrorPayloadSchema` (schemas.ts)
+
+`error` reports a protocol-level or runtime error.
+
+```ts
+export type ErrorPayload = {
+    error: string;
+};
+```
+
+### AssetMetaPayload
+
+Schema: `AssetMetaPayloadSchema` (schemas.ts)
+
+`asset_meta` announces cacheable asset descriptors without sending bytes.
+
+```ts
+export type AssetMetaPayload = {
+    assets: AssetMeta[];
+};
+```
+
+### AssetDataPayload
+
+Schema: `AssetDataPayloadSchema` (schemas.ts)
+
+`asset_data` sends one asset's bytes. JSON transports carry base64/data URL
+strings, while binary transports may carry raw `Uint8Array` values.
+
+```ts
+export type AssetDataPayload = {
+    id: string;
+    hash: string;
+    mime: string;
+    data: string | Uint8Array;
+};
+```
+
+### AssetDeletePayload
+
+Schema: `AssetDeletePayloadSchema` (schemas.ts)
+
+`asset_delete` removes cached renderer-side assets by id.
+
+```ts
+export type AssetDeletePayload = {
+    ids: string[];
+};
+```
+
+### AssetSyncPayload
+
+Schema: `AssetSyncPayloadSchema` (schemas.ts)
+
+`asset_sync` reports the renderer's currently held asset hashes.
+
+```ts
+export type AssetSyncPayload = {
+    assets: {
+        [key: string]: string;
+    };
+};
+```
+
+### ScreenshotRequestPayload
+
+Schema: `ScreenshotRequestPayloadSchema` (schemas.ts)
+
+`screenshot_request` asks the renderer to capture an environment or chart.
+Exactly one of `env_id` or `chart_id` should identify the target. `format`
+defaults to `png`; `quality` is a 0-1 JPEG hint.
+
+```ts
+export type ScreenshotRequestPayload = {
+    request_id: string;
+    env_id?: string | undefined;
+    chart_id?: string | undefined;
+    format?: ("png" | "jpeg") | undefined;
+    quality?: number | undefined;
+};
+```
+
+### ScreenshotResponsePayload
+
+Schema: `ScreenshotResponsePayloadSchema` (schemas.ts)
+
+`screenshot_response` returns a captured image or an error to the simulator.
+JSON mode uses base64/data URL strings; binary mode may use raw bytes.
+
+```ts
+export type ScreenshotResponsePayload = {
+    request_id: string;
+    data?: (string | Uint8Array) | undefined;
+    mime?: string | undefined;
+    error?: string | undefined;
+};
+```
+
+### StateSyncRequest
+
+Schema: `StateSyncRequestSchema` (schemas.ts)
+
+`state_sync` is sent by the renderer on connect or reconnect. It summarizes
+renderer-held definitions so the simulator can replay create, update, and
+delete messages between `state_sync_begin` and `state_sync_end`; simulators
+do not answer with a reverse `state_sync`.
+
+```ts
+export type StateSyncRequest = {
+    request_id?: string | undefined;
+    parameters: Parameter[];
+    actions: Action[];
+    envs: {
+        id: string;
+        type: string;
+        layers: {
+            layer_id: string;
+            layer_type: string;
+        }[];
+    }[];
+    charts: ChartMetadata[];
+};
+```
+
+### ParameterChangePayload
+
+Schema: `ParameterChangePayloadSchema` (schemas.ts)
+
+`param_change` is a renderer-side optimistic parameter edit. The simulator is
+expected to apply accepted values without emitting any sync message. If the
+edit is rejected or normalized to a different value, the simulator sends
+`param_sync`; if the parameter definition changes, such as enum options, it
+sends a full `param_update`.
+
+```ts
+export type ParameterChangePayload = {
+    id: string;
+    value: unknown;
+};
+```
+
+### ActionStartPayload
+
+Schema: `ActionStartPayloadSchema` (schemas.ts)
+
+`action_start` starts one action execution. `continuous` requests a
+renderer-driven loop, and `tick_id` lets the renderer correlate the eventual
+`action_end` with one in-flight dispatch.
+
+```ts
+export type ActionStartPayload = {
+    id: string;
+    tick_id?: string | undefined;
+    continuous?: boolean | undefined;
+};
+```
+
+## Message Envelopes
+
+### SimulatorToRendererMessage
+
+Schema: `SimulatorToRendererMessageSchema` (schemas.ts)
+
+Simulator-to-renderer messages mutate renderer-owned Scenario state or ask
+renderer-side facilities, such as asset cache and screenshots, to do work.
+
+```ts
+export type SimulatorToRendererMessage = {
+    type: "metadata_update" | "state_sync_begin" | "state_sync_end" | "action_end" | "action_create" | "action_update" | "action_delete" | "env_create" | "env_delete" | "env_layer_create" | "env_layer_update" | "env_layer_delete" | "item_create" | "item_update" | "item_delete" | "param_create" | "param_update" | "param_delete" | "param_sync" | "chart_create" | "chart_update" | "chart_delete" | "asset_meta" | "asset_data" | "asset_delete" | "screenshot_request" | "log" | "error";
+    payload: unknown;
+    timestamp?: number | undefined;
+};
+```
+
+### RendererToSimulatorMessage
+
+Schema: `RendererToSimulatorMessageSchema` (schemas.ts)
+
+Renderer-to-simulator messages express renderer intent, renderer state
+summary, or renderer-generated output.
+
+```ts
+export type RendererToSimulatorMessage = {
+    type: "state_sync" | "param_change" | "action_start" | "asset_sync" | "screenshot_response" | "error";
+    payload: unknown;
+    timestamp?: number | undefined;
+};
+```
+
+### AnyProtocolMessage
+
+Schema: `AnyProtocolMessageSchema` (schemas.ts)
+
+No schema comment is defined.
+
+```ts
+export type AnyProtocolMessage = SimulatorToRendererMessage | RendererToSimulatorMessage;
+```
+
+## Built-in Layer Schemas
+
+### BuiltinLayerType
+
+Schema: `BuiltinLayerTypeSchema` (layers.ts)
+
+The five layer types built into the default TenSnap renderer registry.
+Third-party layer types may still use open `layer_type` strings in the
+generic protocol payloads.
+
+```ts
+export type BuiltinLayerType = "background" | "grid" | "edge" | "trajectory" | "agent";
+```
+
+### AgentId
+
+Schema: `AgentIdSchema` (layers.ts)
+
+Agent ids are stable layer item keys and may be strings or numbers.
+
+```ts
+export type AgentId = string | number;
+```
+
+### BuiltinAgentIcon
+
+Schema: `BuiltinAgentIconSchema` (layers.ts)
+
+Built-in symbolic agent icons rendered by the default agent layer.
+
+```ts
+export type BuiltinAgentIcon = "arrow" | "circle" | "square" | "triangle" | "diamond" | "star" | "hexagon" | "cross" | "plus" | "pentagon";
+```
+
+### AssetAgentIcon
+
+Schema: `AssetAgentIconSchema` (layers.ts)
+
+Asset-backed icons use the `asset:<asset_id>` reference form.
+
+```ts
+export type AssetAgentIcon = `asset:${string}`;
+```
+
+### AgentIcon
+
+Schema: `AgentIconSchema` (layers.ts)
+
+No schema comment is defined.
+
+```ts
+export type AgentIcon = BuiltinAgentIcon | AssetAgentIcon;
+```
+
+### BaseLayerMetadata
+
+Schema: `BaseLayerMetadataSchema` (layers.ts)
+
+Common metadata accepted by all built-in layers. Dependencies are create-time
+topology and live on `env_layer_create.dependency_layer_ids`, not in metadata.
+
+```ts
+export type BaseLayerMetadata = {
+    dependency_layer_ids?: never | undefined;
+    z_index?: number | undefined;
+    [x: string]: unknown;
+};
+```
+
+### AgentLayerMetadata
+
+Schema: `AgentLayerMetadataSchema` (layers.ts)
+
+Agent layer metadata. `coord_offset` selects integer grid-cell coordinates or
+floating scene coordinates for x/y agent positions.
+
+```ts
+export type AgentLayerMetadata = {
+    dependency_layer_ids?: never | undefined;
+    z_index?: number | undefined;
+    width?: number | undefined;
+    height?: number | undefined;
+    coord_offset?: ("int" | "float") | undefined;
+    [x: string]: unknown;
+};
+```
+
+### AgentItem
+
+Schema: `AgentItemSchema` (layers.ts)
+
+Agent items are keyed by `id`. They can represent grid agents or graph nodes;
+graph-force fields (`vx`, `vy`, `fx`, `fy`) are renderer-maintained hints.
+
+```ts
+export type AgentItem = {
+    id: AgentId;
+    color?: string | undefined;
+    icon?: AgentIcon | undefined;
+    size?: number | undefined;
+    x?: number | undefined;
+    y?: number | undefined;
+    vx?: number | undefined;
+    vy?: number | undefined;
+    fx?: (number | null) | undefined;
+    fy?: (number | null) | undefined;
+    heading?: number | undefined;
+    data?: {
+        [key: string]: unknown;
+    } | undefined;
+    [x: string]: unknown;
+};
+```
+
+### AgentItemDiff
+
+Schema: `AgentItemDiffSchema` (layers.ts)
+
+Agent item updates are keyed by `id` and may carry any changed fields.
+
+```ts
+export type AgentItemDiff = {
+    id: AgentId;
+    [x: string]: unknown;
+};
+```
+
+### EdgeLayerMetadata
+
+Schema: `EdgeLayerMetadataSchema` (layers.ts)
+
+Edge layer metadata configures graph layout forces and edge rendering
+defaults. Edge layers depend on an agent layer through dependency key
+`agent`.
+
+```ts
+export type EdgeLayerMetadata = {
+    dependency_layer_ids?: never | undefined;
+    z_index?: number | undefined;
+    link_distance?: number | undefined;
+    charge_strength?: number | undefined;
+    centering_strength?: number | undefined;
+    collision_radius?: number | undefined;
+    max_component_distance?: number | undefined;
+    component_spacing?: number | undefined;
+    [x: string]: unknown;
+};
+```
+
+### EdgeItem
+
+Schema: `EdgeItemSchema` (layers.ts)
+
+Edge items are keyed by the ordered pair (`source`, `target`).
+
+```ts
+export type EdgeItem = {
+    source: AgentId;
+    target: AgentId;
+    directed?: boolean | undefined;
+    style?: ("solid" | "dashed" | "dotted") | undefined;
+    width?: number | undefined;
+    color?: string | undefined;
+    [x: string]: unknown;
+};
+```
+
+### EdgeItemDiff
+
+Schema: `EdgeItemDiffSchema` (layers.ts)
+
+Edge item updates are keyed by `source` and `target`.
+
+```ts
+export type EdgeItemDiff = {
+    source: AgentId;
+    target: AgentId;
+    [x: string]: unknown;
+};
+```
+
+### EdgeItemKey
+
+Schema: `EdgeItemKeySchema` (layers.ts)
+
+Delete key for one edge item.
+
+```ts
+export type EdgeItemKey = {
+    source: AgentId;
+    target: AgentId;
+};
+```
+
+### TrajectoryLayerMetadata
+
+Schema: `TrajectoryLayerMetadataSchema` (layers.ts)
+
+Trajectory layer metadata sets defaults for per-agent trajectory traces.
+Trajectory layers depend on an agent layer through dependency key `agent`.
+
+```ts
+export type TrajectoryLayerMetadata = {
+    dependency_layer_ids?: never | undefined;
+    z_index?: number | undefined;
+    length?: number | undefined;
+    width?: number | undefined;
+    color?: string | undefined;
+    [x: string]: unknown;
+};
+```
+
+### TrajectoryItem
+
+Schema: `TrajectoryItemSchema` (layers.ts)
+
+Per-agent trajectory config items are keyed by agent `id`.
+
+```ts
+export type TrajectoryItem = {
+    id: AgentId;
+    length?: number | undefined;
+    width?: number | undefined;
+    color?: string | undefined;
+    [x: string]: unknown;
+};
+```
+
+### TrajectoryItemDiff
+
+Schema: `TrajectoryItemDiffSchema` (layers.ts)
+
+Trajectory item updates are keyed by `id`.
+
+```ts
+export type TrajectoryItemDiff = {
+    id: AgentId;
+    [x: string]: unknown;
+};
+```
+
+### TrajectoryPoint
+
+Schema: `TrajectoryPointSchema` (layers.ts)
+
+One historical trajectory sample stored by the renderer.
+
+```ts
+export type TrajectoryPoint = {
+    x: number;
+    y: number;
+    time: number;
+    color?: string | undefined;
+};
+```
+
+### GridLayerMetadata
+
+Schema: `GridLayerMetadataSchema` (layers.ts)
+
+Grid layer metadata controls parametric grid lines and optional scene size.
+
+```ts
+export type GridLayerMetadata = {
+    dependency_layer_ids?: never | undefined;
+    z_index?: number | undefined;
+    width?: number | undefined;
+    height?: number | undefined;
+    x_origin?: number | undefined;
+    x_unit?: number | undefined;
+    x_interval?: number | undefined;
+    x_ratio?: number | undefined;
+    y_origin?: number | undefined;
+    y_unit?: number | undefined;
+    y_interval?: number | undefined;
+    y_ratio?: number | undefined;
+    stroke_color?: string | undefined;
+    [x: string]: unknown;
+};
+```
+
+### BackgroundInterpolation
+
+Schema: `BackgroundInterpolationSchema` (layers.ts)
+
+No schema comment is defined.
+
+```ts
+export type BackgroundInterpolation = "nearest" | "linear";
+```
+
+### BackgroundAssetReference
+
+Schema: `BackgroundAssetReferenceSchema` (layers.ts)
+
+Background image references point to a previously announced protocol asset.
+
+```ts
+export type BackgroundAssetReference = {
+    asset_id: string;
+    interpolation?: BackgroundInterpolation | undefined;
+};
+```
+
+### BackgroundSource
+
+Schema: `BackgroundSourceSchema` (layers.ts)
+
+Raw background source accepted by the built-in background layer metadata.
+
+```ts
+export type BackgroundSource = string | Uint8Array | BackgroundAssetReference;
+```
+
+### BackgroundLayerMetadata
+
+Schema: `BackgroundLayerMetadataSchema` (layers.ts)
+
+Background layer metadata stores color/image/asset source and interpolation.
+
+```ts
+export type BackgroundLayerMetadata = {
+    dependency_layer_ids?: never | undefined;
+    z_index?: number | undefined;
+    background?: BackgroundSource | undefined;
+    interpolation?: BackgroundInterpolation | undefined;
+    [x: string]: unknown;
+};
+```
+
+### AgentDependencyLayerIds
+
+Schema: `AgentDependencyLayerIdsSchema` (layers.ts)
+
+Dependency map shape used by edge and trajectory layers.
+
+```ts
+export type AgentDependencyLayerIds = {
+    agent: string;
+    [x: string]: unknown;
+};
+```
+
+### AgentLayerCreatePayload
+
+Schema: `AgentLayerCreatePayloadSchema` (layers.ts)
+
+Built-in `agent` layer create payload. Agent layers do not require dependency layers.
+
+```ts
+export type AgentLayerCreatePayload = {
+    env_id: string;
+    layer_id: string;
+    layer_type: "agent";
+    data?: AgentLayerMetadata | undefined;
+};
+```
+
+### EdgeLayerCreatePayload
+
+Schema: `EdgeLayerCreatePayloadSchema` (layers.ts)
+
+Built-in `edge` layer create payload. `dependency_layer_ids.agent` names the source agent layer.
+
+```ts
+export type EdgeLayerCreatePayload = {
+    env_id: string;
+    layer_id: string;
+    layer_type: "edge";
+    dependency_layer_ids: AgentDependencyLayerIds;
+    data?: EdgeLayerMetadata | undefined;
+};
+```
+
+### TrajectoryLayerCreatePayload
+
+Schema: `TrajectoryLayerCreatePayloadSchema` (layers.ts)
+
+Built-in `trajectory` layer create payload. `dependency_layer_ids.agent` names the traced agent layer.
+
+```ts
+export type TrajectoryLayerCreatePayload = {
+    env_id: string;
+    layer_id: string;
+    layer_type: "trajectory";
+    dependency_layer_ids: AgentDependencyLayerIds;
+    data?: TrajectoryLayerMetadata | undefined;
+};
+```
+
+### GridLayerCreatePayload
+
+Schema: `GridLayerCreatePayloadSchema` (layers.ts)
+
+Built-in `grid` layer create payload. Grid layers use metadata only and do not accept item messages.
+
+```ts
+export type GridLayerCreatePayload = {
+    env_id: string;
+    layer_id: string;
+    layer_type: "grid";
+    data?: GridLayerMetadata | undefined;
+};
+```
+
+### BackgroundLayerCreatePayload
+
+Schema: `BackgroundLayerCreatePayloadSchema` (layers.ts)
+
+Built-in `background` layer create payload. Background layers use metadata only and do not accept item messages.
+
+```ts
+export type BackgroundLayerCreatePayload = {
+    env_id: string;
+    layer_id: string;
+    layer_type: "background";
+    data?: BackgroundLayerMetadata | undefined;
+};
+```
+
+### BuiltinLayerCreatePayload
+
+Schema: `BuiltinLayerCreatePayloadSchema` (layers.ts)
+
+Union of the five built-in layer create payload specializations.
+
+```ts
+export type BuiltinLayerCreatePayload = BackgroundLayerCreatePayload | GridLayerCreatePayload | EdgeLayerCreatePayload | TrajectoryLayerCreatePayload | AgentLayerCreatePayload;
+```
+
+### AgentItemCreatePayload
+
+Schema: `AgentItemCreatePayloadSchema` (layers.ts)
+
+`item_create` payload specialization for built-in agent layers.
+
+```ts
+export type AgentItemCreatePayload = {
+    env_id: string;
+    layer_id: string;
+    items: AgentItem[];
+};
+```
+
+### AgentItemUpdatePayload
+
+Schema: `AgentItemUpdatePayloadSchema` (layers.ts)
+
+`item_update` payload specialization for built-in agent layers.
+
+```ts
+export type AgentItemUpdatePayload = {
+    env_id: string;
+    layer_id: string;
+    items: AgentItemDiff[];
+};
+```
+
+### AgentItemDeletePayload
+
+Schema: `AgentItemDeletePayloadSchema` (layers.ts)
+
+`item_delete` payload specialization for built-in agent layers, keyed by agent id.
+
+```ts
+export type AgentItemDeletePayload = {
+    env_id: string;
+    layer_id: string;
+    items: AgentId[];
+};
+```
+
+### EdgeItemCreatePayload
+
+Schema: `EdgeItemCreatePayloadSchema` (layers.ts)
+
+`item_create` payload specialization for built-in edge layers.
+
+```ts
+export type EdgeItemCreatePayload = {
+    env_id: string;
+    layer_id: string;
+    items: EdgeItem[];
+};
+```
+
+### EdgeItemUpdatePayload
+
+Schema: `EdgeItemUpdatePayloadSchema` (layers.ts)
+
+`item_update` payload specialization for built-in edge layers.
+
+```ts
+export type EdgeItemUpdatePayload = {
+    env_id: string;
+    layer_id: string;
+    items: EdgeItemDiff[];
+};
+```
+
+### EdgeItemDeletePayload
+
+Schema: `EdgeItemDeletePayloadSchema` (layers.ts)
+
+`item_delete` payload specialization for built-in edge layers, keyed by source/target pairs.
+
+```ts
+export type EdgeItemDeletePayload = {
+    env_id: string;
+    layer_id: string;
+    items: EdgeItemKey[];
+};
+```
+
+### TrajectoryItemCreatePayload
+
+Schema: `TrajectoryItemCreatePayloadSchema` (layers.ts)
+
+`item_create` payload specialization for built-in trajectory layers.
+
+```ts
+export type TrajectoryItemCreatePayload = {
+    env_id: string;
+    layer_id: string;
+    items: TrajectoryItem[];
+};
+```
+
+### TrajectoryItemUpdatePayload
+
+Schema: `TrajectoryItemUpdatePayloadSchema` (layers.ts)
+
+`item_update` payload specialization for built-in trajectory layers.
+
+```ts
+export type TrajectoryItemUpdatePayload = {
+    env_id: string;
+    layer_id: string;
+    items: TrajectoryItemDiff[];
+};
+```
+
+### TrajectoryItemDeletePayload
+
+Schema: `TrajectoryItemDeletePayloadSchema` (layers.ts)
+
+`item_delete` payload specialization for built-in trajectory layers, keyed by agent id.
+
+```ts
+export type TrajectoryItemDeletePayload = {
+    env_id: string;
+    layer_id: string;
+    items: AgentId[];
+};
+```
+
+### BuiltinLayerItemCreatePayload
+
+Schema: `BuiltinLayerItemCreatePayloadSchema` (layers.ts)
+
+Union of built-in layer `item_create` payload specializations. Grid and background layers have no items.
+
+```ts
+export type BuiltinLayerItemCreatePayload = AgentItemCreatePayload | EdgeItemCreatePayload | TrajectoryItemCreatePayload;
+```
+
+### BuiltinLayerItemUpdatePayload
+
+Schema: `BuiltinLayerItemUpdatePayloadSchema` (layers.ts)
+
+Union of built-in layer `item_update` payload specializations. Grid and background layers have no items.
+
+```ts
+export type BuiltinLayerItemUpdatePayload = AgentItemUpdatePayload | EdgeItemUpdatePayload | TrajectoryItemUpdatePayload;
+```
+
+### BuiltinLayerItemDeletePayload
+
+Schema: `BuiltinLayerItemDeletePayloadSchema` (layers.ts)
+
+Union of built-in layer `item_delete` payload specializations. Grid and background layers have no items.
+
+```ts
+export type BuiltinLayerItemDeletePayload = AgentItemDeletePayload | EdgeItemDeletePayload | TrajectoryItemDeletePayload;
+```
+
+## Controls, Charts, And Assets
+
+### AssetId
+
+Schema: `AssetIdSchema` (asset.ts)
+
+Asset identifiers and metadata are protocol payloads, not renderer cache
+objects. Renderers may resolve them into blob URLs or local buffers, but the
+wire contract stays content-addressed by id plus hash.
+
+```ts
+export type AssetId = string;
+```
+
+### AssetMeta
+
+Schema: `AssetMetaSchema` (asset.ts)
+
+No schema comment is defined.
+
+```ts
+export type AssetMeta = {
+    id: AssetId;
+    hash: string;
+    mime: string;
+    size: number;
+    label?: string | undefined;
+};
+```
+
+### ChartMetadata
+
+Schema: `ChartMetadataSchema` (chart.ts)
+
+Protocol-level chart types describe series identity and updates only. Chart
+rendering config, layouts, and UI-specific storage live in renderer packages.
+
+```ts
+export type ChartMetadata = {
+    id: string;
+    label: string;
+    color?: string | undefined;
+};
+```
+
+### ChartGroupMetadata
+
+Schema: `ChartGroupMetadataSchema` (chart.ts)
+
+No schema comment is defined.
+
+```ts
+export type ChartGroupMetadata = {
+    id: string;
+    label: string;
+    color?: string | undefined;
+    dataList?: ChartMetadata[] | undefined;
+};
+```
+
+### ChartUpdateData
+
+Schema: `ChartUpdateDataSchema` (chart.ts)
+
+No schema comment is defined.
+
+```ts
+export type ChartUpdateData = {
+    id: string;
+    time?: number | undefined;
+    value: unknown;
+};
+```
+
+### ChartUpdateOperation
+
+Schema: `ChartUpdateOperationSchema` (chart.ts)
+
+No schema comment is defined.
+
+```ts
+export type ChartUpdateOperation = {
+    id: string;
+    operation: "clear";
+};
+```
+
+### ParameterType
+
+Schema: `ParameterTypeSchema` (controls.ts)
+
+Parameters describe mutable simulator configuration exposed to the renderer.
+Actions are intentionally separate in protocol v0.2: they have their own
+lifecycle and renderer-driven continuous loop semantics.
+
+```ts
+export type ParameterType = "number" | "enum" | "boolean" | "string";
+```
+
+### ParameterBase
+
+Schema: `ParameterBaseSchema` (controls.ts)
+
+No schema comment is defined.
+
+```ts
+export type ParameterBase = {
+    id: string;
+    type: ParameterType;
+    label: string;
+    allowRuntimeChange?: boolean | undefined;
+};
+```
+
+### NumberParameter
+
+Schema: `NumberParameterSchema` (controls.ts)
+
+No schema comment is defined.
+
+```ts
+export type NumberParameter = {
+    id: string;
+    type: "number";
+    label: string;
+    allowRuntimeChange?: boolean | undefined;
+    value: number;
+    min?: number | undefined;
+    max?: number | undefined;
+    step?: number | undefined;
+};
+```
+
+### EnumParameter
+
+Schema: `EnumParameterSchema` (controls.ts)
+
+No schema comment is defined.
+
+```ts
+export type EnumParameter = {
+    id: string;
+    type: "enum";
+    label: string;
+    allowRuntimeChange?: boolean | undefined;
+    value: string;
+    options: string[];
+    labels?: {
+        [key: string]: string;
+    } | undefined;
+};
+```
+
+### BooleanParameter
+
+Schema: `BooleanParameterSchema` (controls.ts)
+
+No schema comment is defined.
+
+```ts
+export type BooleanParameter = {
+    id: string;
+    type: "boolean";
+    label: string;
+    allowRuntimeChange?: boolean | undefined;
+    value: boolean;
+};
+```
+
+### StringParameter
+
+Schema: `StringParameterSchema` (controls.ts)
+
+No schema comment is defined.
+
+```ts
+export type StringParameter = {
+    id: string;
+    type: "string";
+    label: string;
+    allowRuntimeChange?: boolean | undefined;
+    value: string;
+};
+```
+
+### Parameter
+
+Schema: `ParameterSchema` (controls.ts)
+
+No schema comment is defined.
+
+```ts
+export type Parameter = NumberParameter | EnumParameter | BooleanParameter | StringParameter;
+```
+
+### Action
+
+Schema: `ActionSchema` (controls.ts)
+
+No schema comment is defined.
+
+```ts
+export type Action = {
+    id: string;
+    label: string;
+    continuous?: boolean | undefined;
+    allowRuntimeChange?: boolean | undefined;
+};
+```
+
+## Supporting Schemas
+
+### ItemRecord
+
+Schema: `ItemSchema` (schemas.ts)
+
+No schema comment is defined.
+
+```ts
+export type ItemRecord = {
+    [key: string]: unknown;
+};
+```
+
+### ItemDiff
+
+Schema: `ItemDiffSchema` (schemas.ts)
+
+No schema comment is defined.
+
+```ts
+export type ItemDiff = {
+    [key: string]: unknown;
+};
+```
+
+### ItemKey
+
+Schema: `ItemKeySchema` (schemas.ts)
+
+No schema comment is defined.
+
+```ts
+export type ItemKey = {
+    [key: string]: unknown;
+};
+```
+
+### PrimitiveItemKey
+
+Schema: `PrimitiveItemKeySchema` (schemas.ts)
+
+No schema comment is defined.
+
+```ts
+export type PrimitiveItemKey = string | number;
+```
+
+### LogLevel
+
+Schema: `LogLevelSchema` (schemas.ts)
+
+No schema comment is defined.
+
+```ts
+export type LogLevel = "debug" | "info" | "warning" | "error" | "critical";
+```