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.

1. 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.

1. 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; 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:

  {
    "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 h-screen so it fills the placement iframe's

viewport, and 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-full on the root: 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, anchored to its conversation task. 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.