feat(visual-plan): Phase 2 — diagrams, anchored comments, in-panel edit, send-back

[Ecko95]

Native Visual Plan for GITS — Phase 2

Builds on Phase 1 (#30, now merged). Phase 1 kept the panel read-only (agent writes via MCP; web only reads). Phase 2 adds the web→server write path that comments and edits both need, plus diagram rendering and send-back-to-session. Everything routes through the existing thread.visual-plan.upsert event so it round-trips through the same decider→projector→projection→WS pipeline and renders live.

The backbone: gits.visualPlan.mutate RPC

The web can't dispatch the internal thread.visual-plan.upsert directly (not in ClientOrchestrationCommand, and the MCP registry cache must stay coherent). A dedicated WS RPC merges the comment / patches / resolution into the current plan server-side and round-trips the upsert.

VisualPlanPanel (web)
  └─ optimistic local apply  +  api gits.visualPlan.mutate(threadId, {contentPatches?, addComment?, resolveCommentId?})
       → mutateVisualPlan: applyPlanPatches → upsert/resolve comment → thread.visual-plan.upsert
       → decider → event → projector → projection → WS → store → panel (reconciles by plan id)
       └─ also refreshes the MCP registry cache, so the agent's get-plan-feedback sees web comments

Included

• Contracts: moved the pure plan model (applyPlanPatches/exportPlanToMarkdown) + new comment helpers (upsertPlanComment/resolvePlanComment) into @t3tools/contracts so server write paths and the web panel's optimistic updates/export share one implementation. New VisualPlanMutateInput/Result/Error + gits.visualPlan.mutate RPC.
• Server: visualPlanWrite.ts (shared loadVisualPlanState/upsertVisualPlanState + mutateVisualPlan); http.ts (MCP) refactored to reuse it; ws.ts wires the RPC.
• Diagrams: diagram/custom-html render inert agent HTML in a fully sandboxed iframe (sandbox="", opaque origin — no script can execute, CSS can't leak). Size caps, script/handler/javascript: stripping, --wf-* theme injection (lib/visualPlanHtml.ts).
• Anchored comments: text-selection (text-quote + context anchor) and per-block comments via a composer with agent/human routing; resolve; comment list.
• In-panel edit → patch: rich-text / checklist (check/add/@dnd-kit reorder) / callout / table; each edit emits a PlanContentPatch, applied optimistically and persisted via the mutate RPC.
• Send-back-to-session: "Send to agent" exports markdown (shared exportPlanToMarkdown) and dispatches a turn via ChatView, reusing buildPlanImplementationPrompt.

Verification

• All 4 packages typecheck clean (contracts / client-runtime / server / web) on this gits base.
• Unit tests: contracts patch-ops/comment-merge (10), sanitizer (11), comment-anchor (6).
• HTTP/WS integration (server.test.ts, full suite 85 passed): web mutate adds comment+patch → lands in plan; get-plan-feedback returns it with anchor + resolutionTarget; export-visual-plan includes edits + open comments; cross-path cache coherence; clean failure when no plan.
• Panel render test: asserts the sandboxed iframe strips scripts.
• Web build green (panel stays a lazy chunk — no initial-bundle bloat); oxlint 0 errors.

Security note

Untrusted (agent-authored) diagram HTML is rendered only inside sandbox="" iframes — no allow-scripts/allow-same-origin, ever. Defence-in-depth size caps + script/handler/URL stripping on top.

Deferred (P3)

Wireframe canvas + sandboxed-iframe Alpine.js prototype; canvas/point comment anchors (schema already present).

🤖 Generated with Claude Code