---
id: TASK-42
title: 'Implement Data Pipes: typed data flow through arrows'
status: Done
assignee: []
created_date: '2026-02-18 20:06'
updated_date: '2026-03-11 23:01'
labels:
  - feature
  - phase-1
  - ecosystem
milestone: m-1
dependencies:
  - TASK-41
references:
  - rspace-online/lib/folk-arrow.ts
  - rspace-online/lib/folk-shape.ts
  - rspace-online/lib/folk-image-gen.ts
  - rspace-online/lib/folk-prompt.ts
priority: high
---

## Description

<!-- SECTION:DESCRIPTION:BEGIN -->
Transform folk-arrow from visual-only connector into a typed data conduit between shapes.

New file lib/data-types.ts:
- DataType enum: string, number, boolean, image-url, video-url, text, json, trigger, any
- Type compatibility matrix and isCompatible() function

Add port mixin to FolkShape:
- ports map, getPort(), setPortValue(), onPortValueChanged()
- Port values stored in Automerge: doc.shapes[id].ports[name].value
- 100ms debounce on port propagation to prevent keystroke thrashing

Enhance folk-arrow:
- sourcePort/targetPort fields referencing named ports
- Listen for port-value-changed on source, push to target
- Type compatibility check before pushing
- Visual: arrows tinted by data type, flow animation when active
- Port handle UI during connect mode

Add port descriptors to AI shapes:
- folk-image-gen: input "prompt" (text), output "image" (image-url)
- folk-video-gen: input "prompt" (text), input "image" (image-url), output "video" (video-url)
- folk-prompt: input "context" (text), output "response" (text)
- folk-transcription: output "transcript" (text)

Example pipeline: Transcription →[text]→ Prompt →[text]→ ImageGen →[image-url]→ VideoGen
<!-- SECTION:DESCRIPTION:END -->

## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 DataType system with compatibility matrix works
- [x] #2 Shapes can declare input/output ports via registration
- [x] #3 setPortValue() writes to Automerge and dispatches event
- [x] #4 folk-arrow pipes data from source port to target port
- [x] #5 Type incompatible connections show warning
- [x] #6 Arrows visually indicate data type and active flow
- [x] #7 Port values sync to remote clients via Automerge
- [x] #8 100ms debounce prevents thrashing on rapid changes
<!-- AC:END -->

## Final Summary

<!-- SECTION:FINAL_SUMMARY:BEGIN -->
## Completed: Data Pipes — typed data flow through arrows

Created `lib/data-types.ts` — `DataType` union, `PortDescriptor` interface, `isCompatible()` type matrix, `dataTypeColor()` for arrow tints.

Added port mixin to `FolkShape`: static `portDescriptors`, `#ports` Map, `initPorts()`, `setPortValue()` (dispatches `port-value-changed` CustomEvent), `getPortValue()`, `setPortValueSilent()`, `getInputPorts()`, `getOutputPorts()`. `toJSON()` includes port values; `applyData()` restores silently (no event dispatch = no sync loops).

Enhanced `FolkArrow`: `sourcePort`/`targetPort` properties, `#setupPipe()` listener for `port-value-changed`, `isCompatible()` type check, 100ms debounce, arrow color tinted by `dataTypeColor()`. Listener cleanup on disconnect. `toJSON`/`fromData`/`applyData` include port fields.

AI shape port descriptors:
- `folk-prompt`: input `context` (text) → output `response` (text)
- `folk-image-gen`: input `prompt` (text) → output `image` (image-url)
- `folk-video-gen`: input `prompt` (text) + `image` (image-url) → output `video` (video-url)
- `folk-transcription`: output `transcript` (text)

Extended `ShapeData` interface with `sourcePort`, `targetPort`, `ports` fields.

Commit: c4717e3
<!-- SECTION:FINAL_SUMMARY:END -->