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.

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

@@ -0,0 +1,42 @@
+# Tasks — react-network-libp2p-demo
+
+## Phase 1: Scaffold
+
+- [ ] 1.1 Create `packages/react/react-network-libp2p-demo/`.
+- [ ] 1.2 `package.json` at `0.1.0`, peer-deps on `react`, `react-dom`, `@suaveplan/network-transport-libp2p`.
+- [ ] 1.3 Storybook + testing-dom configuration.
+
+## Phase 2: Component extraction
+
+- [ ] 2.1 Read upstream `libp2p-demo.tsx` (749 LOC).
+- [ ] 2.2 Split into per-concern subcomponents ≤300 LOC each (panels, tabs, controls).
+- [ ] 2.3 Sibling `.md` per component file.
+
+## Phase 3: Bootstrap-list prop
+
+- [ ] 3.1 Remove any hardcoded bootstrap defaults.
+- [ ] 3.2 Accept bootstrap list as a required React prop.
+
+## Phase 4: Storybook stories
+
+- [ ] 4.1 Port `libp2p-demo.stories.tsx`.
+- [ ] 4.2 Add `default` + `playground` + variant stories per subcomponent.
+
+## Phase 5: Tests
+
+- [ ] 5.1 Snapshot tests via `@suaveplan/testing-dom`.
+- [ ] 5.2 Interaction tests for key flows (dial, message, disconnect).
+
+## Phase 6: Verification
+
+- [ ] 6.1 `bunx turbo lint typecheck --filter=@suaveplan/react-network-libp2p-demo` green.
+- [ ] 6.2 No source file > 300 LOC.
+- [ ] 6.3 Storybook covers every subcomponent.
+- [ ] 6.4 `MANIFEST.md` regen.
+- [ ] 6.5 `STATUS.md` row added.
+
+## Pre-archive checklist
+
+- [ ] Row 1 — Phase 6 green.
+- [ ] Row 2 — Demo runs against a user-supplied bootstrap list.
+- [ ] Row 3 — Folder archived.