feat(ui): implement graph-to-API serialization for workflow canvas save/load

[geoffjay]

Add graphToWorkflows() to serialize canvas graph to CreateWorkflowRequest[], workflowsToGraph() to deserialize API responses to React Flow nodes/edges (with agent dedup), validateGraph() for pre-save validation, and localStorage layout persistence. 36 tests covering round-trips, shared agents, edge cases.

Closes #1100

[geoffjay]

This change is part of the following stack:

• feat(ui): install @xyflow/react and scaffold WorkflowCanvas base component #1107
  • feat(ui): extend TriggerConfig types to match all backend trigger variants #1108
    • feat(ui): create trigger source node components for workflow canvas #1109
      • feat(ui): create agent node and prompt template edge components #1110
        • feat(ui): implement graph-to-API serialization for workflow canvas save/load #1111 ◀
          • feat(ui): build node palette sidebar with drag-and-drop onto workflow canvas #1112
            • feat(ui): add workflow builder page with routing and persistence #1113
              • feat(ui): add read-only workflow visualization with auto-layout #1114

_{Change managed by git-spice.}

[geoffjay]

Review: feat(ui): implement graph-to-API serialization for workflow canvas save/load

Stack position: issue-1100 (#1111) stacked on issue-1098 (#1110 — also has review-agent). #1110 should be reviewed and merged first.

Overview

This PR adds the serialization layer between React Flow's node/edge graph model and the orchestrator API's CreateWorkflowRequest shape. It includes full round-trip support (graph→API and API→graph), localStorage-backed layout persistence, and a comprehensive 532-line test suite covering ~35 cases.

What looks good

• Agent deduplication is correct. workflowsToGraph uses agentNodeMap: Map<string, Node> keyed on agent-${agentId} and checks agentNodeMap.has(agentNodeId) before creating a node — agents shared across multiple workflows appear exactly once on the canvas.

• Layout key is order-independent. layoutStorageKey sorts IDs before hashing with djb2, so ['b','a'] and ['a','b'] produce the same key. The three tests for this in serialization.test.ts confirm it.

• graphToWorkflows throws, validateGraph returns. The asymmetry is intentional: callers who want a pre-flight check use validateGraph; callers who want an all-or-nothing conversion use graphToWorkflows. The tests cover both paths correctly.

• localStorage calls are guarded. Both saveLayout and loadLayout wrap localStorage access in try/catch, which correctly handles private-browsing environments and quota errors.

• Test isolation is solid. beforeEach/afterEach(() => localStorage.clear()) prevents layout tests from bleeding into each other. Test helpers (makeTriggerNode, makeAgentNode, makeEdge, makeWorkflow, makeAgent) are minimal and reusable.

Non-blocking notes

1. loadLayout casts without runtime validation (JSON.parse(raw) as CanvasLayout). If stored layout data is stale (e.g., schema changed between deploys), this will silently accept a malformed object and crash downstream when layout fields are destructured. Consider a lightweight shape-check or a try/catch around the usage site. This is consistent with the pattern in PR #1113 — worth addressing in a follow-up for both.

2. index.ts re-exports everything. The barrel export added in this PR makes all serialization internals (LAYOUT_TRIGGER_X, LAYOUT_ROW_HEIGHT, etc.) part of the public surface of the canvas module. If these constants are implementation details, consider exporting only the functions. Low urgency since this is internal UI code.

3. workflowsToGraph uses agent?.config?.model optional chaining, which silently produces undefined if the agent has no model set. This is safe for now but worth documenting — a node with an undefined model label may render oddly depending on how #1110's AgentNode renders the prop.

Verdict

No blocking issues. The serialization logic is correct, the tests are thorough, and the code follows the patterns established in the rest of the canvas module. Approving pending merge of parent #1110.