Initial Commit

openspec/archive/2026-05-12-react-network-libp2p-demo/proposal.md

@@ -0,0 +1,76 @@
+# OpenSpec Change: react-network-libp2p-demo
+
+- **Change ID**: react-network-libp2p-demo
+- **Package**: `@suaveplan/react-network-libp2p-demo`
+- **Category**: react (browser, React-tier)
+- **Target path**: `packages/react/react-network-libp2p-demo`
+- **Status**: PROPOSED
+- **Date**: 2026-05-11
+- **Parent**: `network-transport-family` (2026-05-11) — Wave 7
+- **Related**: `network-transport-libp2p` (Wave 4) — this package extracts the upstream `libp2p-demo.tsx` so the transport package can stay React-free.
+
+---
+
+## Summary
+
+Net-new genesis package that houses the React demo UI for `@suaveplan/network-transport-libp2p`. Upstream `network-libp2p` shipped a 749-LOC `libp2p-demo.tsx` plus Storybook story inside the transport package; per CLAUDE.md the transport must stay React-free, so the demo migrates here.
+
+---
+
+## Why a separate package
+
+The upstream `network-libp2p` package mixes a universal-tier `Libp2pTransport` class with a 749-line React component, breaking the tier-isolation rule. Two options:
+
+- **Delete the demo** — clean but loses a useful runnable example.
+- **Extract to its own package** — preserves the demo as a working reference, keeps the transport React-free.
+
+This proposal chooses extraction. The demo lives in `packages/react/react-network-libp2p-demo/` and the transport package's parity checklist marks the demo as "🚫 dropped → migrated separately here".
+
+---
+
+## Current-state audit
+
+Upstream source:
+
+- `../suaveplan/packages/browser/network-libp2p/src/lib/libp2p-demo.tsx` (749 LOC) — over 300-line cap, needs splitting
+- `../suaveplan/packages/browser/network-libp2p/src/lib/libp2p-demo.stories.tsx` (211 LOC)
+
+---
+
+## Parity Checklist
+
+| Capability | Upstream | Migrated | Notes |
+|---|---|---|---|
+| `Libp2pDemo` component | ✅ | ✅ | Split into per-concern subcomponents ≤300 LOC each. |
+| Storybook stories | ✅ | ✅ | Default + playground + variants per CLAUDE.md. |
+| React runtime dep | ✅ | ✅ | Belongs at this tier. |
+| Direct libp2p import | upstream-bundled | ⬆️ | Consume via `@suaveplan/network-transport-libp2p` ✅ (Wave 4). |
+| Hardcoded bootstrap | check | 🚫 | Demo accepts bootstrap list as a prop; no public defaults. |
+| Storybook docs | partial | ⬆️ | Story descriptions cover use case + caveats. |
+| Test coverage | low (it's a demo) | partial | Snapshot tests + interaction tests via `@suaveplan/testing-dom`; not 100% (per CLAUDE.md demos are stories-not-tests). |
+
+---
+
+## Available workspace deps on genesis
+
+- `@suaveplan/network-transport-libp2p` ⬅ Wave 4 (required)
+- `@suaveplan/network` ✅
+- `@suaveplan/testing-dom` ✅
+- External: `react`, `react-dom`, `@react-three/fiber` (only if demo uses 3D).
+
+---
+
+## Acceptance gate
+
+1. `bunx turbo lint typecheck --filter=@suaveplan/react-network-libp2p-demo` green.
+2. Every source file ≤300 LOC.
+3. Storybook stories cover every subcomponent.
+4. Demo runs locally against a user-supplied bootstrap list (no hardcoded public defaults).
+5. `STATUS.md` row added with `❌` (net-new) → flipped to `✅` on landing.
+
+---
+
+## Out of scope
+
+- Hosting the demo as a standalone site (deployment).
+- Production-grade UI polish — it's a reference demo.