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

bunx turbo lint typecheck --filter=@suaveplan/react-network-libp2p-demo green.
Every source file ≤300 LOC.
Storybook stories cover every subcomponent.
Demo runs locally against a user-supplied bootstrap list (no hardcoded public defaults).
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.

3.1 KiB Raw Blame History