# FolkJS + Canvas-Website → rSpace.online Migration

## Overview

This document outlines the architectural strategy for migrating canvas-website's tldraw-based features to FolkJS infrastructure, deployable as community spaces on rSpace.online.

---

## The Fundamental Paradigm Shift

### TLdraw (current canvas-website)
- Canvas is an **isolated drawing surface** separate from the DOM
- Shapes are custom React components rendered into a canvas coordinate system
- State lives in a TLStore, synced via Automerge CRDT
- The canvas is an *application* you load

### FolkJS
- Spatial relationships are **native web primitives**
- HTML documents *become* spatial canvases seamlessly
- Elements communicate through **proximity-based connections**
- The web itself is the canvas - you can annotate, re-layout, and program *any* existing webpage
- "Folk programs" blur document/application boundaries

---

## Current Canvas-Website Features

| Category | Features |
|----------|----------|
| **AI Generation** | ImageGen (SD/SDXL), VideoGen (Wan2.1), Prompt (LLM) |
| **Collaboration** | Automerge CRDT, WebSocket sync, presence awareness |
| **Knowledge Management** | Obsidian integration, Fathom notes, Markdown editing |
| **Communication** | Video chat (Daily.co), transcription (Whisper) |
| **Data Visualization** | HolonShape (H3 hexagonal), MapShape (OSM), graph layouts |
| **Privacy/Sovereignty** | PrivateWorkspaceShape, CryptID auth, per-board permissions |
| **23 Custom Shapes** | Each with StandardizedToolWrapper, theming, pinning |

---

## Migration Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                     rSpace.online Architecture                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────────┐    ┌──────────────────────────────────┐   │
│  │   FolkJS Core    │    │    Canvas-Website Features       │   │
│  ├──────────────────┤    ├──────────────────────────────────┤   │
│  │ • HTML↔Canvas    │    │ • 23 Custom Shapes               │   │
│  │   transformation │    │ • AI Orchestrator                │   │
│  │ • Proximity-     │ +  │ • Automerge CRDT Sync            │   │
│  │   based relations│    │ • Obsidian/Fathom Integration    │   │
│  │ • Web            │    │ • Video/Audio/Transcription      │   │
│  │   augmentation   │    │ • Privacy Workspaces             │   │
│  │ • Propagators    │    │ • Permission System              │   │
│  └────────┬─────────┘    └──────────────┬───────────────────┘   │
│           │                             │                        │
│           └─────────────┬───────────────┘                        │
│                         ▼                                        │
│           ┌─────────────────────────────┐                        │
│           │   Deployable Community      │                        │
│           │        Spaces               │                        │
│           ├─────────────────────────────┤                        │
│           │ • Per-community instances   │                        │
│           │ • Custom shape libraries    │                        │
│           │ • Themed experiences        │                        │
│           │ • Federated identity        │                        │
│           └─────────────────────────────┘                        │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

---

## Key Advantages of FolkJS Foundation

### 1. Web-Native Spatial Primitives
- Shapes become *actual HTML custom elements* that work anywhere
- `<folk-imagegen>`, `<folk-videoconf>`, `<folk-obsidian-note>`
- Embeddable in any webpage, not just your canvas

### 2. Progressive Enhancement
- Communities start with simple HTML pages
- Gradually add spatial capabilities without migration
- Existing web content becomes annotatable/programmable

### 3. LLM Integration Path
- FolkJS explicitly explores "LLM capabilities across any webpage"
- AI orchestrator could power Folk programs that intelligently compose interfaces

### 4. Lower Barrier to Entry
- Folk programs are "authored entirely in HTML"
- Communities create custom tools without deep React/TypeScript knowledge

---

## Migration Phases

### Phase 1: Core Infrastructure
- Port Automerge sync layer to work with FolkJS's propagator system
- Create `folk-shape` base class that mirrors StandardizedToolWrapper behavior
- Implement proximity-based connections between shapes

### Phase 2: Shape Migration
Convert high-value shapes first:
- `ImageGenShape` → `<folk-imagegen>`
- `MarkdownShape` → `<folk-markdown>`
- `ObsNoteShape` → `<folk-obsidian>`
- Preserve AI orchestrator integration

### Phase 3: Community Deployment
- Multi-tenant architecture on rSpace.online
- Per-community shape libraries (enable/disable features)
- Federated identity (CryptID across spaces)
- Community-specific themes and layouts

### Phase 4: Web Augmentation
- Enable communities to annotate *any* webpage spatially
- "Save to rSpace" browser extension
- Collaborative annotation layers over external sites

---

## Technical Decisions

### What to Keep from Canvas-Website
- **Automerge CRDT** - Superior offline-first sync
- **AI Orchestrator** - Local/cloud routing (RS8000 + RunPod)
- **R2 asset storage** - Cloudflare integration pattern
- **Permission system** - Board-level access control
- **CryptID auth** - Self-sovereign identity

### What FolkJS Provides
- Spatial primitives as web components
- Proximity/relation system
- HTML↔Canvas fluidity
- Propagator event system
- Simulation/physics for layout

### What Needs New Development
- Multi-tenant deployment infrastructure
- Community management dashboard
- Shape marketplace/library system
- Cross-space federation protocol

---

## rSpace.online Vision

```
https://mycofi.rspace.online     → MycoFi community space
https://commons.rspace.online    → Commons Stack community
https://token.rspace.online      → Token Engineering community
https://custom.rspace.online     → Any community's custom space

Each space:
├── FolkJS foundation (spatial web primitives)
├── Canvas-website shapes (AI, collab, knowledge)
├── Community-specific shapes (custom tools)
├── Shared identity (CryptID federation)
└── Configurable feature flags
```

---

## Risks & Mitigations

| Risk | Mitigation |
|------|------------|
| FolkJS is pre-1.0, unstable | Fork and stabilize core primitives needed |
| Learning curve for team | Start with simple shapes, migrate incrementally |
| Performance at scale | Benchmark early, optimize relation system |
| Loss of tldraw features | Keep tldraw as optional rendering backend |

---

## Next Steps

1. **Clone folkjs** and explore the monorepo structure
2. **Build a proof-of-concept**: Port `MarkdownShape` to a Folk component
3. **Test the sync story**: Can Automerge work with Folk's propagator system?
4. **Prototype multi-tenancy**: Single deployment, community subdomains
5. **Create decision documents** for architectural choices

---

## Resources

- [FolkJS Website](https://folkjs.org)
- [FolkJS GitHub](https://github.com/folk-canvas/folk-canvas)
- [FolkJS Live 2025 Presentation](https://folkjs.org/live-2025/)
- [Canvas-Website Repository](/home/jeffe/Github/canvas-website)
- [TLdraw Documentation](https://tldraw.dev)

---

*Document created: 2025-12-11*