utopai-research/groups-compose

When to propose

• 3+ nodes share a clear semantic tie (same scene, same character, same beat)
• The relationship would be obvious to a reader within 2 seconds of scanning the canvas
• You can write a ≤ 30-character title that names the tie

Skip if fewer than 3 members or the tie is just generation order.

Contract

• Use canvas_layout.js to write member positions and groupFrames in one atomic sidecar update.
• Never write or edit workflow.json; never put x / y into node data.
• A layout change may move member nodes when that makes the canvas clearer.
• The frame's geometry (x, y, width, height) is a bounding box computed from the final member positions.
• A node may appear in at most one frame; evict it from old frames in the same update.
• No nested frames.
• frameId: frame_<unix_ms>. Titles ≤30 chars recommended.

Patterns

Pick the one that fits. Grouping is current canvas state; read workflow.json per the project PROJECT_AGENT.md § "Choosing context" to verify ids.

1. Scene grouping

• Triggers: 3+ prompt/note/image/video nodes around one location, beat, or plot point.
• Title: Scene <N> — <location or beat>.
• Typical size: 3–8 members.
• Members: prompt/shot/image_result/video_result plus scene-scoped notes.
• Layout: place the script/shot note on the left, then images/videos in reading order to the right. Put attached voice/audio below the source card.

2. Character-reference set

A character card + its reference images.

• Triggers: ≥2 images of the same character.
• Title: <Character name> — references.
• Typical size: 2–6 images.
• Members: any image_result nodes depicting the same character.
• Layout: hero/reference card first, variations in a compact grid, attached voice node below.

3. Act / beat grouping

• Triggers: the user framed the session at act/beat granularity ("everything for act 2", "the whole chase sequence", "opening titles").
• Title: Act <N> or beat name.
• Typical size: 8–15 members. If larger, prefer splitting into scene subgroups instead.
• Members: all nodes that belong to that act/beat, spanning multiple scenes.
• Layout: arrange scene clusters left-to-right in story order, with enough gutter that frames do not overlap.

4. Production-state grouping (opt-in)

• Use only when user explicitly sorts by quality/status: approved, draft, rejected, WIP, final.
• Title: one status word.
• Typical size: open-ended.

Recipe

1. Read ./workflow.json + ./canvas_positions.json. workflow.json gives you node ids + labels + subtypes; canvas_positions.json gives you each node's x / y AND the existing groupFrames map. Reads are unrestricted; writes go through canvas_layout.js.
2. Pick members. Identify which nodes belong in the proposed frame by looking at their ids, labels, prompts, and subtypes. Keep only ids that actually exist in nodes.
3. Plan positions. Preserve existing positions when they already read well. Otherwise move the selected nodes into a compact layout for the chosen pattern. Use these default gaps:

• horizontal card gap: 40 px
• vertical row gap: 36 px
• frame padding: 24 px

1. Evict existing frame members in the same layout JSON:

• If the old frame would still have ≥ 2 members after eviction: include it under groupFrames.upsert with memberIds minus the evictee.
• If the old frame would have < 2 members: include its id under groupFrames.delete.

1. Compute frame bboxes from final member positions with 24px padding. Fallback sizes:

• note: 280 × 420 (width hardcoded; height = NOTE_CARD_FALLBACK_HEIGHT for first paint)
• image_result: 290 × 220 (16:9 default; if data.metadata.aspect_ratio is present, scale accordingly)
• video_result: 290 × 220 (same caveat; check data.aspect or data.metadata.aspect_ratio)
• audio_result: 240 × 64
• pending / pending_generation / pending_attachment: 260 × 200

If measured heights appear in canvas_positions.json, prefer them. minX = min(node.x for each member) minY = min(node.y for each member) maxX = max(node.x + node.w for each member) maxY = max(node.y + node.h for each member) x = minX - 24 y = minY - 24 width = (maxX - minX) + 48 height = (maxY - minY) + 48

1. Decide title + hue. Default hue 200 if you have no signal.
2. Apply one layout update with all node moves and frame changes:

node "$PAI_REPO_ROOT/server/cli/canvas_layout.js" \ --layout-json '{"positions":{"note_2":{"x":120,"y":80},"image_3":{"x":440,"y":80},"video_1":{"x":760,"y":80}},"groupFrames":{"upsert":{"frame_1716579123456":{"memberIds":["note_2","image_3","video_1"],"x":96,"y":56,"width":978,"height":468,"hue":200,"title":"Scene 1 — Causeway"}},"delete":[]}}'

1. Extending an existing frame — same CLI/frameId, full new memberIds, recomputed bbox.
2. Confirm to the user in one sentence. Example: "Grouped the three Morris reference shots under their own frame."

What not to do

• Don't propose groupings proactively when there's no clear semantic tie — wait until grouping earns the frame.
• Don't use grouping as a generic tidy operation when there is no semantic tie.
• Don't write canvas_positions.json directly. Use canvas_layout.js so positions and frames apply together.
• Don't call removed workflow group ops (addGroup, updateGroup, deleteGroup).
• Don't nest (put one frame's id inside another frame's memberIds).
• Don't assign a node to two frames. Include any eviction in the same layout update.