composing-grid-canvases

Adding a widget follows a resolution ladder: first search the component store with canvas-list filtered by kind=component, then configure an existing component if its configSchema fits, fork it if close, or build a new one. The placement is then written via canvas-layout-patch with an add_placement or update_placement operation.

Create a canvas with kind=component and declare a placement contract in the project's top-level component key, including size bounds and a configSchema. Author the source like a freeform canvas, give the root h-screen so it fills the placement iframe, publish it, and wait for the build before placing it on a grid.

A placement's status tells the renderer what to show: pending means a box was drawn but not described, generating means an agent task is filling it, live means it renders a published component at a version, and failed means generation failed with the prompt kept for retry.

component_not_found means the component id is wrong, deleted, not a component, or not visible to the acting user. placement_config_invalid means the config does not match the component's configSchema; fix the config values rather than the layout geometry.

Yes. The size contract is advisory: placement_size_out_of_contract is a warning, not an error, and the publish still succeeds. Components must render responsively at any size the user drags, from a glanceable tile to a full app surface.

The config schema vocabulary is an allowlist: type, title, description, default, properties, required, additionalProperties, items, enum, const, minimum, maximum, minLength, maxLength, minItems, maxItems, and format. Validation rejects $ref and pattern.