mesh-common

MIT v0.11.2 WebRTC ยท Yjs ยท TypeScript

Shared scaffolding and runtime for the baditaflorin/mesh-* family of rootless, peer-to-peer browser apps. WebRTC mesh via Yjs, settings drawer, self-referential footer, clock sync, commit-reveal โ€” everything the 134 live apps share, factored into one package.

๐Ÿ’ก This framework is designed for the Rootless Computing paradigm. Rootless applications have no origin server, run entirely in the browser, store data locally, and coordinate directly with peers using WebRTC and Yjs.

Core modules

createMeshConfig
One-call config factory: app name, accent, version, commit, signaling/TURN/PayPal defaults.
MeshShell
Top-level chrome: โš™ FAB โ†’ settings drawer, self-referential footer (source / tip / version).
useYRoom
React hook โ†’ { doc, provider, peerId, peerCount } for a given room ID.
clockSync
NTP-over-Yjs offset โ†’ mesh-median time, stable to ~10โ€“30 ms.
commitReveal
SHA-256 commit/reveal for anonymous votes, fair RNG, and role assignment.
identity โญ
Ed25519 keypair generation, persistence, sign/verify, useIdentity hook (~32 KB).
tofuRegistry โญ
Y.Map<peerId, signed pubkey record> with first-use trust pinning.
moderator โญ
Signed first-claim-wins role, 30-min auto-expire, partition-aware tiebreak.
PersonalQR / useQRScanner
Inline-SVG QR (real-URL payload) + camera scanner + paste-fallback widget.
useDirectedEdges / shortestPath
Append-only Y.Array<Edge> + graph helpers for social-graph apps.
MeshErrorBoundary NEW
Drop-in crash containment: "try again", "copy diagnostics", "reload page". Accepts fallback render-prop and onError.
useMeshLink NEW
Type-safe encoder + parser for the #r=โ€ฆ&p=โ€ฆ&x=โ€ฆ deep-link fragment. Wire-format versioned via &v=.
useAwareness NEW
Typed wrapper around y-protocols/awareness โ€” presence, cursors, typing indicators with one hook.
PeerAvatar NEW
Deterministic inline-SVG avatar from a peerId. Zero network, zero PII.
usePresenceCursors NEW
Figma-style live cursors via useAwareness, throttled to ~30 Hz with auto-coloring per peerId.
useRoomSeal NEW
Room-wide AES-GCM seal via PBKDF2(passphrase, roomId). Opt-in E2E with no key-exchange UX.
useTypedMap / useTypedArray NEW
Zod-validated Y.Map / Y.Array โ€” invalid writes from old/hostile peers filtered at the edge.
useFileShare NEW
Chunked file share through the Yjs transport (5 MB cap). Receiver gets download(fileId) + blobOf(fileId).
useVoiceActivity NEW
VAD by RMS energy + zero-crossing rate. Pure Web Audio, ~100 lines, no ML payload.
SafeMarkdown NEW
Markdown via marked + allow-list sanitizer. No raw HTML pass-through.
useMultiRoom NEW
Run several Yjs rooms in one tab โ€” facilitator dashboards, embeds, side-by-side mesh apps.
CrdtInspector NEW
Dev-only overlay (?inspect=1): shared types, sizes, updates/sec, peer count, peerId.

Quick start

# in a mesh-* app sibling folder npm install file:../mesh-common

import { createMeshConfig, MeshShell, useYRoom } from '@baditaflorin/mesh-common'; const config = createMeshConfig({ appName: 'my-app', accent: '#6f42c1', version: '0.1.0', }); export default function App() { const { doc, provider, peerCount } = useYRoom(config.roomId); return <MeshShell config={config}>โ€ฆ</MeshShell>; }

Or scaffold a new app in one command:

bash scaffold/create-mesh-app.sh my-new-app

Links