composing-grid-canvases

A grid canvas is a composition, not an app: a grid of placements, each rendering a component canvas (a reusable widget with its own source, build, and placement contract). The user's home canvas is an ordinary grid canvas in their personal channel. Layout is data — publishing or patching one is live immediately, with no build.

Three canvas kinds share one lifecycle:

• freeform — a standalone app (the building-canvases skill owns these).
• component — a reusable widget. Same source/build pipeline as freeform, plus a placement contract. Visibility rides its channel: personal channel = private, team channel = shared.
• grid — a layout of placements referencing components. No file source; layout only.

When a grid placement needs content ("a weather widget here", "a kanban of my tasks"), resolve in this order — placing an existing component beats authoring a duplicate:

1. Search the store: canvas-list with kind=component and search=<what the widget shows>. A component is placeable when both component_meta and published_build_id are set. If its configSchema can express the request ("weather for Lisbon" → existing weather component with config: {"location": "Lisbon"}), place and configure it — write no code.
2. Fork when a component is close but its config cannot express the ask: read its source (canvas-source-retrieve), create a new component (canvas-create with kind=component), adapt, publish. Name the difference in the new component's description.
3. Build new when nothing fits — see "Building a component" below.

New components land in the channel you create them in. Create them in the same channel as the grid they serve unless the user asks to share them more widely.

A component is authored exactly like a freeform canvas — load building-react-quill-canvases (or building-html-canvases) plus querying-canvas-data and validating-and-publishing-canvases — with three additions. A component that shows PostHog data follows the same verifiability rule as any canvas: an insight-backed figure links its saved insight, an ad-hoc query exposes the exact query that ran (see "Verifiability" in querying-canvas-data). Start from the complete, buildable project in references/component-example.md; its envelope, placement contract, capability declarations, and defensive ph.state access are the parts that break when improvised.

• Create with kind=component and a description written for store search: say what the widget shows and what its config controls. Future placements are found by this text.

• Declare the placement contract in the project's top-level component key:

  Copy

  {
    "component": {
      "size": { "defaultW": 2, "defaultH": 1, "minW": 1, "minH": 1, "maxW": 4 },
      "configSchema": {
        "type": "object",
        "properties": { "location": { "type": "string", "description": "City to show weather for" } }
      }
    }
  }

  Size is in grid units (widths 1–12, heights 1–40); minW <= defaultW <= maxW. The range is advisory: users may resize a placement to any size, so it informs defaults and warnings, never rejections. The config schema vocabulary is an allowlist — type, title, description, default, properties, required, additionalProperties, items, enum, const, minimum, maximum, minLength, maxLength, minItems, maxItems, format. No $ref, no pattern — validation rejects them.

• Design responsively. Give the component's root min-h-screen so it fills the placement iframe's viewport and grows past it as content demands. Adapt the layout to any size the user drags: a 2×1 placement is a glanceable tile; a 6×4 is a full app surface. Do not use h-screen on the root: a fixed viewport height caps a flex column, so tall children shrink and clip instead of scrolling. Do not use h-full on the root either: a published component's artifact shell gives its html, body, and #root elements no explicit height, so height: 100% collapses to the content height. Render usefully at minW×minH, and treat config as the only per-placement input.

Publish and wait for the build like any canvas — a component with no ready build cannot go live on a grid.

A whole-canvas ask ("a home canvas that summarizes my work in progress") usually means several widgets, not one. Plan the full set first — one placement per concern — then resolve each with the ladder above. Lay them out together: no overlaps, sizes matched to what each widget shows, the grid filled deliberately rather than tiles scattered in a corner. Batch the layout writes (one publish for an initial layout, surgical patches after) instead of one write per widget, and finish with every placement live or failed — never generating.

Users leave feedback as comment threads on the canvas. List them with the task comment tools (tasks-comments-list, tasks-comments-retrieve) on your task before and after changing the canvas, and address the open ones — a comment naming a broken widget is your brief for fixing it.

The loop is read → patch, guarded exactly as validating-and-publishing-canvases describes for source publishes — with canvas-layout-get in place of canvas-source-retrieve, and canvas-layout-patch (surgical ops, guard required) or canvas-layout-publish (complete document, for an initial layout or full restructure) as the write. On a 409, re-read the layout, re-apply your change, and patch again.

Operations:

• add_placement — a new box: {id, status, x, y, w, h, ...}. Placements must not overlap or extend past grid.columns.
• update_placement — merge changes into the placement with id. Filling a drawn box is {"op": "update_placement", "id": "p1", "changes": {"status": "live", "component": "<component canvas id>", "config": {...}}}.
• remove_placement, set_grid.

A placement's status tells the renderer what to show:

• pending — the user drew a box but hasn't described it (or the prompt awaits dispatch).
• generating — an agent task is filling it; generationTaskId links the task and prompt records the ask. Set this when you start working on a placement from a task.
• live — renders its component at version ("latest" by default; a pinned version id is allowed). Requires the component to be published and visible to the acting user.
• failed — generation failed; keep the prompt so the user can retry or re-describe.

When a task asks you to fill a placement, its prompt and the box's size are your brief: honor the drawn w×h and keep the placement's prompt intact for provenance.

Layout publishes validate atomically; every error names its placement. The common ones:

• component_not_found — the id is wrong, deleted, not a component, or not visible to the acting user (a component in someone else's personal channel is not placeable).
• component_not_published — the component has never published a placement contract.
• placement_config_invalid — config does not match the component's configSchema.
• placement_size_out_of_contract — a warning, not an error: the box's w/h is outside the component's suggested range. The publish still succeeds; the component must render responsively.
• placements_overlap / invalid_placement — geometry; fix coordinates rather than removing the other widget.

End your reply by linking the grid canvas with the url field the canvas tools return — never construct a canvas URL yourself.