8.5 KiB
8.5 KiB
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-shapebase 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
- Clone folkjs and explore the monorepo structure
- Build a proof-of-concept: Port
MarkdownShapeto a Folk component - Test the sync story: Can Automerge work with Folk's propagator system?
- Prototype multi-tenancy: Single deployment, community subdomains
- Create decision documents for architectural choices
Resources
- FolkJS Website
- FolkJS GitHub
- FolkJS Live 2025 Presentation
- Canvas-Website Repository
- TLdraw Documentation
Document created: 2025-12-11