composing-grid-canvases

# 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. ## The resolution ladder: configure, fork, build 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. ## Building a component 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](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: ```json { "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. ## Composing a whole canvas 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. ## Canvas comments 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. ## Editing a grid 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`. ## The placement lifecycle 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. ## Validation you will hit 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.