feat(ai-agent): canvas-aware generation with roles, async edges and repair

[Suharshit]

Stacked on #25 (#21 → #22 → #23 → #25 → this). The base is feat/ai-agent-cards, so this diff shows step 5 only. After the PR below it merges, change this PR's base to main.

Why

The design agent drew every request from scratch. A follow-up like "add a cache" could redraw existing components or float the new ones unconnected. Generated nodes also used the legacy dark palette instead of the paper fills, role labels and dashed async links the starter templates use. This is step 5 of the AI sessions plan: generation quality.

What

• Canvas context:

  • Every turn reads the room (read-only).
  • lib/ai/canvas-summary.ts lists the components with short refs (ex-1…), their kind and used connection points, plus the connections and text notes. The listing is capped for large canvases.
  • Analyze treats a request as a change to the existing design, the plan lists only components to add, and generate connects new components to existing ones by ref.

• Richer output:

  • The generation schema replaces the legacy colorId with role (entry, compute, messaging, data, output → paper fill) and a kicker.
  • Edges get delivery: sync | async, and async edges are dashed.
  • The role → fill map and SHAPE_KICKERS now live in types/canvas.ts, and the starter templates use them.

• buildCanvasGraph with an existing canvas:

  • refs resolve to the existing node ids
  • a node that repeats an existing label isn't drawn again, and its edges attach to the existing node
  • repeated labels fold into the first node
  • unknown endpoints, self-loops and repeated links are dropped
  • connection points are assigned with existing edges counted

• Validate and repair: lib/ai/graph-validation.ts flags:

  • components already on the canvas
  • duplicate labels or ids
  • unknown refs
  • self-loops
  • repeated links
  • more than 4 connections on a component (existing ones counted)
  • unconnected new components
  • plan components missing from the diagram

  If anything is flagged, the model gets one repair call with those problems, and the attempt with fewer problems is used. If the repair call fails, the first attempt is kept.

• Robustness:

  • When writing, the task uses the live room for layout and connection points and ignores refs to components deleted since the read.
  • Plan text shown to users no longer includes internal refs like "(ex-7)"; a live run showed the model copying them.

Verification

• pnpm typecheck and pnpm lint pass.
• 39 offline checks (no model calls):
  • the canvas summary
  • every validation rule
  • buildCanvasGraph onto an existing canvas: role fills, kickers, dashed async edges, refs and folded duplicates, dropped bad links, connection points avoiding used sides
  • all 13 starter templates still on paper fills
  • refs stripped from plan text
• Live run through the Trigger worker (gemini-3.5-flash-lite), on a room seeded with the Microservices template (8 nodes, 8 edges). Request: "Add a Redis cache in front of the user database, and a notification service that consumes order events."
  • The plan (12.4s) listed only the 3 new components.
  • Generate (12.6s) added User Cache, Event Broker and Notification Service with role labels and paper fills.
  • It connected them to the existing design: User Service → User Cache → User DB, and Order Service → Event Broker → Notification Service, with both order-event links dashed.
  • Existing nodes were untouched, nothing was redrawn, and no connection point was overloaded. 0 failures, 0 warnings.
• Browser: step 4's cards were checked by hand with a detailed prompt answered fully and with a skipped low-detail prompt. This PR's changes haven't been clicked through in a browser.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
draftly	Ready	Preview	Sep 15, 2026 7:20pm UTC

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 3ce0a839-270b-4d46-93bb-fa4c11b8c205

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}