Canvas Channel

Stability 1Experimental

Backward-incompatible changes or removal may occur in any future release.

About the stability index

Reference for the experimental ahp-canvas: channel. Chat state advertises minimal canvas resource references; clients subscribe to each resource for its live presentation metadata and content URI. A client that cannot load the content URI directly reads it with resourceRead. A missing URI means the source is unavailable. Source URIs must be redacted from diagnostic logs and must not be reused from persisted state after provider or host restart.

JSON Schema: state.schema.json

State Types

CanvasReference

Stable reference to a subscribable canvas channel.

Chat state intentionally carries only this reference so the experimental canvas presentation model can evolve without changing the stable chat channel shape.

Field	Type	Description
resource	URI	Canvas channel URI. Subscribe to this resource for the full state.

CanvasState

Full state for one live canvas, returned when a client subscribes to its ahp-canvas: URI.

The client already knows the subscribed resource, so the state does not redundantly carry its channel URI.

Field	Type	Required	Description
instanceId	string	Yes	Stable caller-supplied instance identifier.
extensionId	string	Yes	Owning extension/provider identifier.
extensionName	string	No	Owning extension display name, when available.
canvasId	string	Yes	Provider-local canvas type identifier.
title	string	No	Provider-supplied title, when available.
status	string	No	Provider-supplied status text, when available.
url	URI	No	Absolute URI of the canvas's live content, typically an HTTP(S) URL; absent when the live source is unavailable. Hosts MUST clear this field when the provider becomes unavailable. A client that can't load this URI directly, for example because it is a loopback address in the host's environment or uses a scheme that the client doesn't load, reads it with resourceRead. The client resolves the relative references in its content and reads them the same way. Hosts SHOULD serve reads of this URI, and of other URLs on its origin when it is an HTTP(S) URL, to clients that can subscribe to the canvas. The provider chooses the URI, so the host decides which sources it is willing to read. Source URIs MUST be redacted from diagnostic logs and MUST NOT be reused from persisted state after a provider or host restart.

Actions

Replace CanvasState through server-authoritative actions scoped to the canvas URI via ActionEnvelope.channel.

JSON Schema: actions.schema.json

canvas/stateChanged

The presentation state for this canvas changed.

Replaces the subscribed canvas channel state entirely. Full-replacement semantics intentionally keep this early-development channel free to evolve without expanding the stable chat action surface.

Field	Type	Description
type	ActionType.CanvasStateChanged
canvas	CanvasState	New authoritative canvas state.