mesh-browser: Instructions file for Claude Code

CLAUDE.md

AI assistant context for MeshBrowser development.

Project Overview

MeshBrowser is an Electron-based desktop browser for decentralized protocols. It currently speaks two Reticulum protocols: rweb:// (rserver pages) and nomadnet:// (Nomad Network pages, rendered from micron). Future protocols include IPFS and Hypercore.

Reticulum is spoken directly from the Electron main process using reticulum-js (@reticulum/core + @reticulum/node), attached to a locally running rnsd shared instance.

Key Goals:

• Web-like browsing experience over mesh networks
• Familiar browser interface (address bar, navigation, status indicators)
• No per-site configuration - mesh routing is handled by rnsd
• Extensible architecture for multiple decentralized protocols

Architecture

High-Level Design

Electron Main Process (reticulum-js) ↔ local socket ↔ rnsd

Single process, no sidecar. The rweb:// protocol handler calls the Reticulum client in-process; the client attaches to a running rnsd shared instance via LocalClientInterface, which is what actually owns the radios and TCP links.

• Frontend: Electron with electron-vite and TypeScript, custom protocol handlers for rweb:// URLs
• Networking: reticulum-js in the main process (@reticulum/node uses node:net, so it must never be imported from a renderer)
• Transport: rnsd, which the user runs separately

File Structure

Top level is split by process, because that is the boundary that decides what can run at all: @reticulum/node uses node:net, so everything under main/ is unavailable to a renderer. Feature folders live one level down.

src/
├── main/                        # Electron main process (Node)
│   ├── main.ts                 # App entry, lifecycle, shutdown ordering
│   ├── config.ts               # Tunable settings (future config-file home)
│   ├── html.ts                 # escapeHtml + the shared transport-failure page
│   ├── theme.ts                # Content-view colours mirroring theme.css
│   ├── lifecycle.ts            # Startable / Stoppable / Lifecycle contracts
│   ├── paths.ts                # Renderer URLs, preload + icon paths (environment-derived)
│   ├── windows.ts              # Window/view creation, IPC handlers, view events
│   ├── protocols/               # Protocol layer: schemes, clients, handlers
│   │   ├── protocols.ts        # Three lifecycle phases; owns the stack and clients
│   │   ├── rweb.ts             # rweb:// scheme and handler factory
│   │   └── nomadnet.ts         # nomadnet:// scheme, handler, micron render pipeline
│   └── reticulum/               # Reticulum networking
│       ├── stack.ts            # The single Reticulum instance + lifecycle
│       ├── destination.ts      # Path discovery, Destination, configured links
│       ├── destination-hash.ts # Destination hash validation (pure)
│       ├── async.ts            # Semaphore, deadline helpers (no RNS dependency)
│       ├── bz2.ts              # bz2 codec injected into links
│       ├── rserver/            # The rserver protocol
│       │   ├── client.ts       # Fetch orchestration over pooled links
│       │   ├── link-pool.ts    # One-request-per-link pool (see §3)
│       │   ├── rserver.ts      # The rserver request/response wire protocol
│       │   ├── url.ts          # rweb:// URL parsing (pure)
│       │   └── response.ts     # HTTP-like response parsing (pure)
│       └── nomadnet/           # The NomadNet protocol
│           ├── client.ts       # Fetch orchestration; returns micron source
│           ├── node-link.ts    # One warm link per node, many requests (see §3)
│           ├── url.ts          # nomadnet:// URL parsing (pure)
│           └── micron/         # Micron markup -> HTML (pure, no network)
│               ├── parse.ts        # Source -> block tree (state machine)
│               ├── link-target.ts  # Micron link targets -> URLs
│               ├── render.ts       # Block tree -> HTML fragment
│               └── page.ts         # Fragment -> document (CSP + stylesheet)
├── preload/
│   └── preload.ts              # Context bridge for renderer ↔ main IPC (built as CJS)
├── renderer/                    # Browser chrome only - NOT the browsed page
│   ├── navigation/             # Address bar + nav buttons
│   ├── status/                 # Status indicators
│   ├── shared/                 # Common styles, assets
│   └── types/
│       └── window.d.ts         # BrowserAPI type declarations
├── shared/
│   └── ipc.ts                  # main ↔ renderer message contract (types only)
└── types/
    └── seek-bzip.d.ts          # Ambient types for seek-bzip, which ships none