Add detailed README to each example directory- chat, whiteboard, sdk-demo, hrpc-demo, data-demo, screenshare: each gets README.md- Same structure: what it does, prerequisites, how to run, usage, files, APIs, see also- Note in examples/README.md that each subdir has its own README
This commit is contained in:
Raven Scott
+1
-1
@@ -2,7 +2,7 @@
|
||||
|
||||
Open these in your browser **after** installing the BridgeSwarm extension and native host.
|
||||
|
||||
Each example lives in its own directory with separated concerns: **index.html** (structure), **style.css** (styles), **app.js** (logic). Open the directory’s **index.html** (e.g. `chat/index.html` or run a local server and go to `http://localhost:3000/chat/`).
|
||||
Each example lives in its own directory with separated concerns: **index.html** (structure), **style.css** (styles), **app.js** (logic). Open the directory’s **index.html** (e.g. `chat/index.html` or run a local server and go to `http://localhost:3000/chat/`). Each subdirectory has its own **README.md** with detailed usage, APIs, and file roles.
|
||||
|
||||
## Chat (`chat/`)
|
||||
|
||||
|
||||
@@ -0,0 +1,40 @@
|
||||
# Chat — Minimal P2P chat
|
||||
|
||||
## What this example does
|
||||
|
||||
Minimal P2P chat: join a topic, see peer count, and send and receive text messages. Uses only raw connection writes and no Protomux or Data API.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Install the [BridgeSwarm extension and native host](../../README.md#install-one-command) before opening this example.
|
||||
|
||||
## How to run
|
||||
|
||||
Open `index.html` in your browser (File → Open or drag the file in). For `file://` URLs, ensure the extension has **Allow access to file URLs** enabled, or run a local server (e.g. `npx serve .` from the `examples` folder) and open `http://localhost:3000/chat/`.
|
||||
|
||||
## Usage
|
||||
|
||||
1. Click **Join** (default topic is `bridge-swarm-demo`).
|
||||
2. Open the same page in another tab or device and join the same topic.
|
||||
3. Type a message and click **Send**; it appears in the other tab’s log.
|
||||
4. Click **Leave** when done.
|
||||
|
||||
## Files in this directory
|
||||
|
||||
- **index.html** — Page structure and elements (topic input, join/leave/send buttons, log area).
|
||||
- **style.css** — Layout and theme (dark background, inputs, buttons, log).
|
||||
- **app.js** — BridgeSwarm setup, join/leave/send logic, connection handling and message log.
|
||||
|
||||
## APIs and concepts
|
||||
|
||||
- `BridgeSwarm.ready()` — Wait for the injected API.
|
||||
- `new BridgeSwarm({ appName })` — Create a swarm (app name `bridge-swarm-chat`).
|
||||
- `swarm.join(topic)` — Join the topic.
|
||||
- `swarm.on('connection', (conn, peerInfo))` — Handle new peers.
|
||||
- `conn.on('data', fn)` — Receive messages; decode with `TextDecoder`.
|
||||
- `conn.write(data)` — Send bytes (e.g. `TextEncoder().encode(text)`).
|
||||
- `swarm.leave(topic)`, `swarm.destroy()` — Leave and tear down.
|
||||
|
||||
## See also
|
||||
|
||||
- [API reference](../../docs/API-REFERENCE.md) — Page API and host request types.
|
||||
@@ -0,0 +1,42 @@
|
||||
# Data API Demo — Hypercore, Hyperbee, Hyperdrive, Autobase, Hyperdb
|
||||
|
||||
## What this example does
|
||||
|
||||
Uses the native host Data API via `BridgeSwarm.request(type, payload)`: Hypercore (info, append, get), Hyperbee (put/get/del), Hyperdrive (put/get/list), Autobase (append, info, view), and Hyperdb (insert/get/delete/find/flush on the `records` collection). Single tab; no P2P connections required for basic operations.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Install the [BridgeSwarm extension and native host](../../README.md#install-one-command) before opening this example.
|
||||
|
||||
## How to run
|
||||
|
||||
Open `index.html` in your browser (File → Open or drag the file in). For `file://` URLs, ensure the extension has **Allow access to file URLs** enabled, or run a local server (e.g. `npx serve .` from the `examples` folder) and open `http://localhost:3000/data-demo/`.
|
||||
|
||||
## Usage
|
||||
|
||||
1. Open the page; the log shows “Data API ready” when the extension is available.
|
||||
2. Use the buttons to run each command: **Core info**, **Append**; **Put** / **Get** / **Del** for Hyperbee; **Put** / **Get** / **List /** for Hyperdrive; **Append** / **Info** / **Read view (0..4)** for Autobase; **Put** / **Get** / **Del** / **Find all** / **Flush** for Hyperdb (records).
|
||||
3. The log shows request results and errors.
|
||||
|
||||
## Files in this directory
|
||||
|
||||
- **index.html** — Page structure (sections and buttons per API, log).
|
||||
- **style.css** — Layout and theme (sections, rows, log).
|
||||
- **app.js** — BridgeSwarm.ready(), BridgeSwarm.request() for each command type, log output.
|
||||
|
||||
## APIs and concepts
|
||||
|
||||
- `BridgeSwarm.ready()` — Wait for the injected API.
|
||||
- `BridgeSwarm.request(type, payload)` — Send a command to the host. Types used:
|
||||
- **Hypercore:** `coreInfo`, `coreAppend`, `coreGet`
|
||||
- **Hyperbee:** `beeGet`, `beePut`, `beeDel`
|
||||
- **Hyperdrive:** `driveGet`, `drivePut`, `driveList`
|
||||
- **Autobase:** `autobaseAppend`, `autobaseInfo`, `autobaseViewGet`
|
||||
- **Hyperdb:** `hyperdbInsert`, `hyperdbGet`, `hyperdbDelete`, `hyperdbFindToArray`, `hyperdbFlush` (collection `records`)
|
||||
|
||||
Responses are `{ ok, ... }` or `{ ok: false, error }`; binary data is base64 in payloads.
|
||||
|
||||
## See also
|
||||
|
||||
- [Data API reference](../../docs/DATA-API.md) — Full command list and examples.
|
||||
- [API reference](../../docs/API-REFERENCE.md) — Host request types and events.
|
||||
@@ -0,0 +1,37 @@
|
||||
# HRPC Demo — Unary RPC (ping/pong) over a connection
|
||||
|
||||
## What this example does
|
||||
|
||||
HRPC on a connection: HRPC is auto-enabled when a peer connects. Either tab can use "Ping peer" to get a pong (unary RPC). No manual attach step in the UI after connect.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Install the [BridgeSwarm extension and native host](../../README.md#install-one-command) before opening this example.
|
||||
|
||||
## How to run
|
||||
|
||||
Open `index.html` in your browser (File → Open or drag the file in). For file:// URLs, ensure the extension has **Allow access to file URLs** enabled, or run a local server (e.g. `npx serve .` from the `examples` folder) and open `http://localhost:3000/hrpc-demo/`.
|
||||
|
||||
## Usage
|
||||
|
||||
1. Click **Join topic** (default `bridge-swarm-hrpc-demo`).
|
||||
2. Open the same page in another tab and join the same topic.
|
||||
3. When connected, HRPC is enabled automatically; use **Ping peer** (optionally enter a value). Use **Retry HRPC on selected connection** if the first enable is still pending.
|
||||
4. Click **Leave and destroy** when done.
|
||||
|
||||
## Files in this directory
|
||||
|
||||
- **index.html** — Page structure (topic, join/leave, connection selector, HRPC retry, ping input/button, log).
|
||||
- **style.css** — Layout and theme (sections, badges, log).
|
||||
- **app.js** — BridgeSwarm setup, auto attachHrpc on connection, hrpcInvoke(ping), connection selector and UI state.
|
||||
|
||||
## APIs and concepts
|
||||
|
||||
- Swarm/connection as in chat: BridgeSwarm.ready(), new BridgeSwarm(), swarm.join(), swarm.on('connection'), conn.connId, conn.on('end'), conn.on('error').
|
||||
- BridgeSwarm.request('attachHrpc', { connId }) — Enable HRPC on the connection (called automatically on each new connection).
|
||||
- BridgeSwarm.request('hrpcInvoke', { connId, method: 'ping', args }) — Invoke the unary ping RPC; host runs HRPC on the connection, browser only invokes ping.
|
||||
|
||||
## See also
|
||||
|
||||
- [API reference](../../docs/API-REFERENCE.md) — Page API and host request types.
|
||||
- [HRPC on the native host](../../docs/HRPC.md) — attachHrpc, commands, and build.
|
||||
@@ -0,0 +1,37 @@
|
||||
# Screenshare — P2P screen sharing (WebRTC + BridgeSwarm signaling)
|
||||
|
||||
## What this example does
|
||||
|
||||
P2P screen sharing: BridgeSwarm is used only for **signaling** (SDP offer/answer and ICE candidates). The media stream is sent via WebRTC (RTCPeerConnection). No public STUN or TURN; ICE uses host and local-network candidates only.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Install the [BridgeSwarm extension and native host](../../README.md#install-one-command) before opening this example.
|
||||
|
||||
## How to run
|
||||
|
||||
Open `index.html` in your browser (File → Open or drag the file in). For `file://` URLs, ensure the extension has **Allow access to file URLs** enabled, or run a local server (e.g. `npx serve .` from the `examples` folder) and open `http://localhost:3000/screenshare/`.
|
||||
|
||||
## Usage
|
||||
|
||||
1. **Tab 1 (sharer):** Click **Join**, then **Share my screen** and pick a screen or window. Your shared stream is sent to peers that join the same topic.
|
||||
2. **Tab 2 (viewer):** Join the same topic; the shared screen appears in the video area. Optional: use **Picture-in-Picture**.
|
||||
3. Use **Stop sharing** to end the stream, or **Leave** to leave the topic.
|
||||
|
||||
The sharer can start sharing before any viewer joins; viewers see the stream when they join the topic.
|
||||
|
||||
## Files in this directory
|
||||
|
||||
- **index.html** — Page structure (topic, join/leave, share/stop, video area, placeholder, PiP, preview).
|
||||
- **style.css** — Layout and theme (video wrap, placeholder, stream state, preview).
|
||||
- **app.js** — BridgeSwarm join/connection, signaling over conn (offer/answer/ICE), WebRTC RTCPeerConnection (sharer and viewer), getDisplayMedia, PiP.
|
||||
|
||||
## APIs and concepts
|
||||
|
||||
- Swarm/connection as in chat: `BridgeSwarm.ready()`, `new BridgeSwarm()`, `swarm.join()`, `swarm.on('connection')`, `conn.write()`, `conn.on('data')`, `conn.on('end')`.
|
||||
- Signaling: `conn.write(JSON.stringify({ type: 'webrtc-offer'|'webrtc-answer'|'webrtc-ice', sdp?, candidate? }))` and parse incoming messages to drive WebRTC.
|
||||
- Browser WebRTC: `navigator.mediaDevices.getDisplayMedia()`, `RTCPeerConnection` (no `iceServers`), `createOffer()` / `createAnswer()`, `setLocalDescription` / `setRemoteDescription`, `addIceCandidate()`, `ontrack` for remote stream.
|
||||
|
||||
## See also
|
||||
|
||||
- [API reference](../../docs/API-REFERENCE.md) — Page API and host request types.
|
||||
@@ -0,0 +1,40 @@
|
||||
# SDK Demo — Swarm, connections, raw messages, and Protomux
|
||||
|
||||
## What this example does
|
||||
|
||||
Demonstrates all core BridgeSwarm SDK features in one page: swarm lifecycle, connection events and peerInfo, raw byte messages, and Protomux (channel with string and binary messages).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Install the [BridgeSwarm extension and native host](../../README.md#install-one-command) before opening this example.
|
||||
|
||||
## How to run
|
||||
|
||||
Open `index.html` in your browser (File → Open or drag the file in). For file:// URLs, ensure the extension has **Allow access to file URLs** enabled, or run a local server (e.g. `npx serve .` from the `examples` folder) and open `http://localhost:3000/sdk-demo/`.
|
||||
|
||||
## Usage
|
||||
|
||||
1. Click **Join topic** (default `bridge-swarm-sdk-demo`).
|
||||
2. Open the same page in another tab and join the same topic.
|
||||
3. Use **Send raw** to send text as raw bytes; use **Send Protomux** to send via the Protomux channel. The log shows which path each message used.
|
||||
4. Click **Leave and destroy** when done.
|
||||
|
||||
## Files in this directory
|
||||
|
||||
- **index.html** — Page structure (topic, join/leave, raw/protomux inputs and buttons, log).
|
||||
- **style.css** — Layout and theme (sections, badges, log).
|
||||
- **app.js** — BridgeSwarm and Protomux setup, connection handling, raw and Protomux send/receive.
|
||||
|
||||
## APIs and concepts
|
||||
|
||||
- Swarm/connection as in chat: BridgeSwarm.ready(), new BridgeSwarm(), swarm.join(), swarm.on('connection'), conn.on('data'), conn.write().
|
||||
- swarm.createProtomux(conn) — Create a Protomux instance on the connection.
|
||||
- mux.createChannel with protocol 'sdk-demo/v1' — Create a channel.
|
||||
- channel.addMessage with encoding c.string or c.binary — Add string or binary message handlers; uses window.BridgeSwarmProtomux.c and b4a.
|
||||
- channel.open(), message.send() — Open channel and send.
|
||||
- Raw path: conn.write(data) and conn.on('data') for unencoded bytes.
|
||||
|
||||
## See also
|
||||
|
||||
- [API reference](../../docs/API-REFERENCE.md) — Page API and host request types.
|
||||
- [Protomux over BridgeSwarm](../../docs/PROTOMUX.md) — Protomux setup and usage.
|
||||
@@ -0,0 +1,36 @@
|
||||
# Whiteboard — Collaborative P2P whiteboard
|
||||
|
||||
## What this example does
|
||||
|
||||
Collaborative P2P whiteboard: join a topic, draw on a canvas, and strokes and “Clear board” sync to all peers in real time via JSON messages over raw connections.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Install the [BridgeSwarm extension and native host](../../README.md#install-one-command) before opening this example.
|
||||
|
||||
## How to run
|
||||
|
||||
Open `index.html` in your browser (File → Open or drag the file in). For `file://` URLs, ensure the extension has **Allow access to file URLs** enabled, or run a local server (e.g. `npx serve .` from the `examples` folder) and open `http://localhost:3000/whiteboard/`.
|
||||
|
||||
## Usage
|
||||
|
||||
1. Click **Join** (default topic is `bridge-swarm-whiteboard`).
|
||||
2. Open the same page in another tab or device and join the same topic.
|
||||
3. Draw on the canvas; strokes sync to all peers. Use **Clear board** to broadcast a clear to everyone.
|
||||
4. Click **Leave** when done.
|
||||
|
||||
## Files in this directory
|
||||
|
||||
- **index.html** — Page structure (topic input, join/leave/clear, canvas).
|
||||
- **style.css** — Layout and theme (canvas wrap, buttons, status).
|
||||
- **app.js** — BridgeSwarm setup, canvas drawing, stroke/draft/clear message protocol and broadcast.
|
||||
|
||||
## APIs and concepts
|
||||
|
||||
- Same swarm/connection pattern as chat: `BridgeSwarm.ready()`, `new BridgeSwarm()`, `swarm.join()`, `swarm.on('connection')`, `conn.on('data')`, `conn.write()`.
|
||||
- Raw JSON messages: `conn.write(JSON.stringify(msg))` and `conn.on('data')` with `JSON.parse`. Message types: `strokeStart`, `strokeDraft`, `stroke`, `clear`.
|
||||
- Canvas 2D for drawing strokes (local and from peers); draft strokes for live preview.
|
||||
|
||||
## See also
|
||||
|
||||
- [API reference](../../docs/API-REFERENCE.md) — Page API and host request types.
|
||||
Reference in New Issue
Block a user