npm - dignity.js - Versions diffs - 0.3.0 → 0.5.1 - Mend

dignity.js 0.3.0 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (43) hide show

package/README.md +142 -4
package/dist/dignity.cjs.js +768 -20
package/dist/dignity.cjs.js.map +4 -4
package/dist/dignity.esm.js +768 -20
package/dist/dignity.esm.js.map +3 -3
package/dist/dignity.min.js +18 -18
package/docs/assets/dignity.esm.js +11205 -0
package/docs/assets/docs.js +47 -0
package/docs/assets/favicon.svg +8 -0
package/docs/assets/highlight/github-dark.min.css +10 -0
package/docs/assets/highlight/github.min.css +10 -0
package/docs/assets/highlight/highlight.min.js +1244 -0
package/docs/assets/styles.css +449 -38
package/docs/chess/assets/chess-app.js +58022 -0
package/docs/chess/assets/chess-app.js.map +7 -0
package/docs/chess/assets/chess.css +584 -0
package/docs/chess/favicon.ico +0 -0
package/docs/chess/index.html +16 -0
package/docs/chess/src/App.jsx +128 -0
package/docs/chess/src/components/Board3D.jsx +364 -0
package/docs/chess/src/components/GameView.jsx +847 -0
package/docs/chess/src/components/JoinGate.jsx +68 -0
package/docs/chess/src/components/LinkPanel.jsx +132 -0
package/docs/chess/src/components/Lobby.jsx +154 -0
package/docs/chess/src/components/MovePanel.jsx +123 -0
package/docs/chess/src/lib/audio.js +50 -0
package/docs/chess/src/lib/dignitySetup.js +42 -0
package/docs/chess/src/lib/links.js +124 -0
package/docs/chess/src/lib/localGames.js +160 -0
package/docs/chess/src/lib/p2pDebug.js +192 -0
package/docs/chess/src/main.jsx +5 -0
package/docs/favicon.ico +0 -0
package/docs/index.html +605 -81
package/docs/openapi-like.json +74 -7
package/examples/decentralized-chess-lite.js +52 -30
package/package.json +30 -4
package/src/core/dignity-p2p.js +466 -15
package/src/index.js +8 -0
package/src/network/peerjs-network.js +234 -0
package/src/persistence/indexeddb-persistence.js +184 -0
package/src/react/index.js +256 -0
package/src/signaling/parse-peerjs-url.js +24 -0
package/src/signaling/peerjs-signaling-provider.js +2 -8

package/docs/index.html CHANGED Viewed

@@ -3,27 +3,111 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>dignity.js v0.1.0 docs</title>
+    <meta name="description" content="dignity.js v0.5.1 — REST-like P2P object API for decentralized JavaScript applications." />
+    <title>dignity.js · Documentation</title>
+    <link rel="icon" href="./assets/favicon.svg" type="image/svg+xml" />
+    <link rel="icon" href="./favicon.ico" sizes="32x32" />
+    <link rel="stylesheet" href="./assets/highlight/github.min.css" media="(prefers-color-scheme: light)" />
+    <link rel="stylesheet" href="./assets/highlight/github-dark.min.css" media="(prefers-color-scheme: dark)" />
     <link rel="stylesheet" href="./assets/styles.css" />
   </head>
   <body>
-    <main>
-      <h1>dignity.js documentation</h1>
-      <p class="subtitle">Version 0.1.0 - P2P object API for decentralized JavaScript applications</p>
-      <section>
-        <h2>Professional docs layout (recommended)</h2>
-        <ul>
-          <li><strong>Monorepo style:</strong> <code>apps/docs</code> (Next.js/Nextra or Docusaurus) + versioned routes.</li>
-          <li><strong>Library style:</strong> top-level <code>docs/</code> for public docs and examples.</li>
-          <li><strong>API reference:</strong> generated from source comments and published online.</li>
-          <li><strong>Examples:</strong> runnable samples under <code>examples/</code> or linked demos.</li>
-        </ul>
-      </section>
-      <section>
-        <h2>Quick start</h2>
-        <pre><code>const {
+    <header class="site-header">
+      <a class="site-header__brand" href="#overview">
+        <img src="./assets/dignity-logo.svg" alt="" width="344" height="80" />
+        <!-- <span>dignity.js</span> -->
+        <span class="site-header__version">v0.5.1</span>
+      </a>
+      <div class="site-header__links">
+        <a href="https://www.npmjs.com/package/dignity.js" target="_blank" rel="noopener noreferrer">npm</a>
+        <a href="https://github.com/jose-compu/dignity.js" target="_blank" rel="noopener noreferrer">GitHub</a>
+        <a href="./chess/index.html">3D Chess</a>
+        <a href="./openapi-like.json">API JSON</a>
+      </div>
+      <button class="menu-toggle" type="button" aria-label="Toggle navigation">Menu</button>
+    </header>
+    <div class="layout">
+      <aside class="sidebar">
+        <div class="sidebar__group">
+          <div class="sidebar__label">Getting started</div>
+          <nav>
+            <a href="#overview">Overview</a>
+            <a href="#installation">Installation</a>
+            <a href="#quick-start">Quick start</a>
+            <a href="#browser">Browser usage</a>
+          </nav>
+        </div>
+        <div class="sidebar__group">
+          <div class="sidebar__label">Guide</div>
+          <nav>
+            <a href="#object-api">Object API</a>
+            <a href="#discovery">Room discovery</a>
+            <a href="#messaging">Direct messaging</a>
+            <a href="#concurrency">Concurrency</a>
+            <a href="#security">Security model</a>
+            <a href="#persistence">IndexedDB persistence</a>
+            <a href="#react">React hooks</a>
+            <a href="#signaling">Signaling</a>
+            <a href="./chess/index.html">3D Chess demo</a>
+          </nav>
+        </div>
+        <div class="sidebar__group">
+          <div class="sidebar__label">Reference</div>
+          <nav>
+            <a href="#api-reference">API reference</a>
+            <a href="#events">Events</a>
+            <a href="#exports">Package exports</a>
+            <a href="#examples">Examples</a>
+            <a href="#development">Development</a>
+          </nav>
+        </div>
+      </aside>
+      <main class="content">
+        <div class="content__inner">
+          <section id="overview" class="section">
+            <h1 class="page-title">Documentation</h1>
+            <p class="lead">
+              <strong>dignity.js</strong> is a REST-like P2P object API for decentralized JavaScript
+              applications. Synchronize shared objects across browsers with owner authorization,
+              scoped broadcast encryption, and built-in anti-abuse controls.
+            </p>
+            <div class="card-grid">
+              <article class="card">
+                <h3>Object CRUD</h3>
+                <p><code>create</code>, <code>read</code>, <code>list</code>, <code>update</code>, <code>remove</code> over P2P replication.</p>
+              </article>
+              <article class="card">
+                <h3>Security default-on</h3>
+                <p>Signing, encryption, Sloth VDF proof-of-work, and automatic peer bans.</p>
+              </article>
+              <article class="card">
+                <h3>Browser-first</h3>
+                <p>IIFE, ESM, and CJS bundles. Optional IndexedDB persistence and React hooks.</p>
+              </article>
+            </div>
+          </section>
+          <section id="installation" class="section">
+            <h2>Installation</h2>
+            <div class="code-block">
+              <span class="code-block__label">npm</span>
+              <pre><code class="language-bash">npm install dignity.js</code></pre>
+            </div>
+            <p>For React hooks, install React 18+ as a peer dependency:</p>
+            <div class="code-block">
+              <pre><code class="language-bash">npm install dignity.js react react-dom</code></pre>
+            </div>
+          </section>
+          <section id="quick-start" class="section">
+            <h2>Quick start</h2>
+            <p>Create a node, join a room, and replicate an object between two peers:</p>
+            <div class="code-block">
+              <span class="code-block__label">Node.js / ESM</span>
+              <pre><code class="language-javascript">const {
   DignityP2P,
   InMemoryNetworkHub,
   InMemoryNetworkAdapter
@@ -33,52 +117,342 @@ const hub = new InMemoryNetworkHub();
 const alice = new DignityP2P({
   nodeId: 'alice',
-  networkAdapter: new InMemoryNetworkAdapter(hub)
+  networkAdapter: new InMemoryNetworkAdapter(hub),
+  security: {
+    appPassword: 'shared-out-of-band-password',
+    powSteps: 22
+  }
+});
+const bob = new DignityP2P({
+  nodeId: 'bob',
+  networkAdapter: new InMemoryNetworkAdapter(hub),
+  security: {
+    appPassword: 'shared-out-of-band-password',
+    powSteps: 22
+  }
 });
 await alice.start();
-await alice.create('notes', { title: 'hello world' }, { id: 'note-1' });
-const note = alice.read('notes', 'note-1');</code></pre>
-      </section>
-      <section>
-        <h2>REST-like object API</h2>
-        <ul>
-          <li><code>create(collection, data, options)</code> -> owner is the creator.</li>
-          <li><code>read(collection, id)</code> -> returns object or <code>null</code>.</li>
-          <li><code>list(collection, options)</code> -> list active objects (or include deleted markers).</li>
-          <li><code>update(collection, id, patch)</code> -> only object owner can update.</li>
-          <li><code>remove(collection, id)</code> -> only object owner can delete.</li>
-        </ul>
-      </section>
-      <section>
-        <h2>Room / team discovery</h2>
-        <pre><code>await node.joinDiscovery('team:red', {\n  metadata: { nickname: 'alice' },\n  heartbeatIntervalMs: 15000,\n  ttlMs: 45000\n});\n\nconst peers = node.listPeers('team:red', { includeSelf: false });\nawait node.leaveDiscovery('team:red');</code></pre>
-      </section>
-      <section>
-        <h2>Security defaults (enabled)</h2>
-        <ul>
-          <li><strong>Signing:</strong> every message is signed by sender keypair.</li>
-          <li><strong>Broadcast encryption:</strong> encrypted using shared <code>appPassword</code>.</li>
-          <li><strong>Direct encryption:</strong> encrypted with recipient public key.</li>
-          <li><strong>PoW:</strong> Sloth VDF proof per message, default <code>powSteps: 22</code> (~1000ms on this machine).</li>
-          <li><strong>Peer bans:</strong> invalid signature or invalid PoW bans sender for 48h by default.</li>
-        </ul>
-        <pre><code>const node = new DignityP2P({\n  nodeId: 'alice',\n  networkAdapter,\n  security: {\n    appPassword: 'shared-out-of-band-password',\n    powTargetMs: 1000,\n    signingEnabled: true,\n    encryptionEnabled: true,\n    powEnabled: true\n  }\n});</code></pre>
-        <pre><code>const coopNode = new DignityP2P({\n  nodeId: 'alice',\n  networkAdapter,\n  security: {\n    appPassword: 'global-fallback-password',\n    broadcastPasswords: {\n      'coop:red': 'red-team-password',\n      'coop:blue': 'blue-team-password'\n    }\n  }\n});\n\nawait coopNode.create('matches', { mode: 'coop' }, {\n  id: 'match-1',\n  broadcastScope: 'coop:red'\n});</code></pre>
-      </section>
-      <section>
-        <h2>Signaling defaults and customization</h2>
-        <pre><code>const {
+await bob.start();
+await alice.joinDiscovery('main', { metadata: { nickname: 'alice' } });
+await bob.joinDiscovery('main', { metadata: { nickname: 'bob' } });
+await alice.create('notes', { title: 'hello decentralized world' }, {
+  id: 'note-1',
+  broadcastScope: 'main'
+});
+console.log(bob.read('notes', 'note-1'));
+await alice.leaveDiscovery('main');
+await bob.leaveDiscovery('main');
+await alice.stop();
+await bob.stop();</code></pre>
+            </div>
+            <div class="callout">
+              <strong>In-memory adapter</strong>
+              <code>InMemoryNetworkAdapter</code> is for tests and local demos. Production browser apps use a WebRTC network adapter (see project issues for the browser transport roadmap).
+            </div>
+          </section>
+          <section id="browser" class="section">
+            <h2>Browser usage</h2>
+            <p>Pre-built bundles are published to npm and available via CDN:</p>
+            <div class="code-block">
+              <span class="code-block__label">IIFE (global <code>DignityJS</code>)</span>
+              <pre><code class="language-xml">&lt;script src="https://unpkg.com/dignity.js/dist/dignity.min.js"&gt;&lt;/script&gt;
+&lt;script&gt;
+  const { DignityP2P } = DignityJS;
+&lt;/script&gt;</code></pre>
+            </div>
+            <div class="table-wrap">
+              <table>
+                <thead>
+                  <tr>
+                    <th>Bundle</th>
+                    <th>Path</th>
+                    <th>Format</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  <tr>
+                    <td>Minified browser</td>
+                    <td><code>dist/dignity.min.js</code></td>
+                    <td>IIFE</td>
+                  </tr>
+                  <tr>
+                    <td>ES modules</td>
+                    <td><code>dist/dignity.esm.js</code></td>
+                    <td>ESM</td>
+                  </tr>
+                  <tr>
+                    <td>Node / CommonJS</td>
+                    <td><code>dist/dignity.cjs.js</code></td>
+                    <td>CJS</td>
+                  </tr>
+                </tbody>
+              </table>
+            </div>
+          </section>
+          <section id="object-api" class="section">
+            <h2>Object API</h2>
+            <p>
+              The core API mirrors REST semantics. Each object belongs to a <strong>collection</strong>.
+              The peer that creates an object becomes its <strong>owner</strong> — only the owner may update or delete it.
+            </p>
+            <div class="table-wrap">
+              <table>
+                <thead>
+                  <tr>
+                    <th>Method</th>
+                    <th>Description</th>
+                    <th>Authorization</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  <tr>
+                    <td><code>create(collection, data, options?)</code></td>
+                    <td>Create a new object. Returns the normalized record.</td>
+                    <td>Creator becomes owner</td>
+                  </tr>
+                  <tr>
+                    <td><code>read(collection, id)</code></td>
+                    <td>Read one object, or <code>null</code> if missing/deleted.</td>
+                    <td>—</td>
+                  </tr>
+                  <tr>
+                    <td><code>list(collection, options?)</code></td>
+                    <td>List objects. Set <code>includeDeleted: true</code> for tombstones.</td>
+                    <td>—</td>
+                  </tr>
+                  <tr>
+                    <td><code>update(collection, id, patch, options?)</code></td>
+                    <td>Merge <code>patch</code> into object data and increment version.</td>
+                    <td>Owner only</td>
+                  </tr>
+                  <tr>
+                    <td><code>updateWithRetry(collection, id, patchFn, options?)</code></td>
+                    <td>Read-modify-write with automatic retry on version conflicts.</td>
+                    <td>Owner only</td>
+                  </tr>
+                  <tr>
+                    <td><code>remove(collection, id, options?)</code></td>
+                    <td>Soft-delete the object (tombstone).</td>
+                    <td>Owner only</td>
+                  </tr>
+                </tbody>
+              </table>
+            </div>
+            <h3>Scoped broadcast</h3>
+            <p>Pass <code>broadcastScope</code> on create/update to select a team or room password namespace:</p>
+            <div class="code-block">
+              <pre><code class="language-javascript">await node.create('matches', { mode: 'coop' }, {
+  id: 'm-1',
+  broadcastScope: 'coop:red'
+});</code></pre>
+            </div>
+            <p>Configure per-scope passwords via <code>security.broadcastPasswords</code>.</p>
+          </section>
+          <section id="discovery" class="section">
+            <h2>Room / team discovery</h2>
+            <p>Discover active peers in a named scope (room, team, raid, etc.):</p>
+            <div class="code-block">
+              <pre><code class="language-javascript">await node.joinDiscovery('team:red', {
+  metadata: { nickname: 'alice' },
+  heartbeatIntervalMs: 15000,
+  ttlMs: 45000
+});
+const peers = node.listPeers('team:red', { includeSelf: false });
+await node.leaveDiscovery('team:red');</code></pre>
+            </div>
+          </section>
+          <section id="messaging" class="section">
+            <h2>Direct secure messaging</h2>
+            <p>Send end-to-end encrypted messages to a specific peer:</p>
+            <div class="code-block">
+              <pre><code class="language-javascript">alice.registerPeerPublicKey('bob', bob.getPublicKey());
+bob.registerPeerPublicKey('alice', alice.getPublicKey());
+await alice.sendDirectMessage('bob', 'dm', { text: 'private payload' });</code></pre>
+            </div>
+          </section>
+          <section id="concurrency" class="section">
+            <h2>Optimistic concurrency</h2>
+            <p>
+              Every update carries a monotonic <code>version</code>. Stale operations are rejected when
+              <code>baseVersion</code> does not match. Listen for <code>conflict</code> events or use
+              built-in helpers:
+            </p>
+            <div class="code-block">
+              <pre><code class="language-javascript">node.on('conflict', (event) => {
+  // event.phase: 'local' | 'remote'
+  console.log(event.expectedVersion, event.currentVersion);
+});
+// Fail fast on stale local writes
+await node.update('games', 'g1', { score: 10 }, { expectedVersion: 3 });
+// Automatic retry for read-modify-write loops
+await node.updateWithRetry('games', 'g1', (current) => ({
+  score: current.data.score + 1
+}));</code></pre>
+            </div>
+          </section>
+          <section id="security" class="section">
+            <h2>Security model</h2>
+            <p>All security features are enabled by default. Configure via the <code>security</code> constructor option.</p>
+            <div class="table-wrap">
+              <table>
+                <thead>
+                  <tr>
+                    <th>Feature</th>
+                    <th>Default</th>
+                    <th>Details</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  <tr>
+                    <td>Signing</td>
+                    <td>On</td>
+                    <td>Ed25519 signature on every message</td>
+                  </tr>
+                  <tr>
+                    <td>Broadcast encryption</td>
+                    <td>On</td>
+                    <td>AES secretbox; PBKDF2-SHA256 key from <code>appPassword</code> (100k iterations)</td>
+                  </tr>
+                  <tr>
+                    <td>Direct encryption</td>
+                    <td>On</td>
+                    <td>NaCl box (X25519) — true E2E to recipient public key</td>
+                  </tr>
+                  <tr>
+                    <td>Proof-of-work</td>
+                    <td>On</td>
+                    <td>Sloth VDF; default <code>powSteps: 22</code> (~1s on reference hardware)</td>
+                  </tr>
+                  <tr>
+                    <td>Peer bans</td>
+                    <td>On</td>
+                    <td>Invalid signature or PoW → 48h ban (configurable)</td>
+                  </tr>
+                </tbody>
+              </table>
+            </div>
+            <div class="callout callout--warn">
+              <strong>Broadcast mode is not E2E</strong>
+              All peers that know the scope password can decrypt broadcast traffic. Use direct mode for sensitive per-peer data.
+            </div>
+            <h3>Security configuration</h3>
+            <div class="code-block">
+              <pre><code class="language-javascript">const node = new DignityP2P({
+  nodeId: 'alice',
+  networkAdapter,
+  security: {
+    appPassword: 'shared-out-of-band-password',
+    broadcastPasswords: {
+      'coop:red': 'red-team-secret',
+      'coop:blue': 'blue-team-secret'
+    },
+    powSteps: 22,
+    kdfIterations: 100000,
+    banDurationMs: 48 * 60 * 60 * 1000
+  }
+});</code></pre>
+            </div>
+          </section>
+          <section id="persistence" class="section">
+            <h2>IndexedDB persistence</h2>
+            <p>Survive page reloads by persisting replicated object state to IndexedDB:</p>
+            <div class="code-block">
+              <pre><code class="language-javascript">const { DignityP2P, IndexedDBPersistence } = require('dignity.js');
+const node = new DignityP2P({ nodeId, networkAdapter, security });
+const persistence = new IndexedDBPersistence({
+  dbName: 'my-app',
+  collections: ['games', 'matches']  // omit to persist all collections
+});
+await node.start();
+await persistence.attach(node);
+// Later
+await persistence.detach();</code></pre>
+            </div>
+          </section>
+          <section id="react" class="section">
+            <h2>React hooks</h2>
+            <p>Optional integration via <code>dignity.js/react</code> (requires React ≥ 18):</p>
+            <div class="code-block">
+              <pre><code class="language-javascript">import { useDignity, useCollection, usePeers } from 'dignity.js/react';
+function Room() {
+  const { node, status, error } = useDignity(config);
+  const games = useCollection(node, 'games');
+  const peers = usePeers(node, 'room:chess', { includeSelf: false });
+  if (status === 'starting') return &lt;p&gt;Connecting…&lt;/p&gt;;
+  if (error) return &lt;p&gt;Error: {error.message}&lt;/p&gt;;
+  return (
+    &lt;pre&gt;{JSON.stringify({ status, games, peers }, null, 2)}&lt;/pre&gt;
+  );
+}</code></pre>
+            </div>
+            <div class="table-wrap">
+              <table>
+                <thead>
+                  <tr>
+                    <th>Hook</th>
+                    <th>Returns</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  <tr>
+                    <td><code>useDignity(config)</code></td>
+                    <td><code>{ node, status, error }</code> — starts/stops node on mount/unmount</td>
+                  </tr>
+                  <tr>
+                    <td><code>useCollection(node, name)</code></td>
+                    <td>Reactive array from <code>node.list(name)</code></td>
+                  </tr>
+                  <tr>
+                    <td><code>usePeers(node, scope, options?)</code></td>
+                    <td>Reactive peer list from discovery</td>
+                  </tr>
+                </tbody>
+              </table>
+            </div>
+          </section>
+          <section id="signaling" class="section">
+            <h2>Signaling</h2>
+            <p>Default PeerJS-compatible signaling endpoints are included. Customize with <code>createDefaultSignalingPool</code>:</p>
+            <div class="code-block">
+              <pre><code class="language-javascript">const {
   createDefaultSignalingPool,
   WebSocketSignalingProvider
 } = require('dignity.js');
 const pool = createDefaultSignalingPool({
-  cloudflareUrls: ['wss://your-cloudflare-endpoint.example'],
+  cloudflareUrls: ['wss://your-endpoint.example/peerjs?key=peerjs'],
   fallbackUrls: ['wss://relay-a.example', 'wss://relay-b.example'],
   customProviders: [
     new WebSocketSignalingProvider({
@@ -88,30 +462,180 @@ const pool = createDefaultSignalingPool({
     })
   ]
 });</code></pre>
-        <p>
-          Machine-readable API metadata is available in
-          <a href="./openapi-like.json">openapi-like.json</a>.
-        </p>
-      </section>
-      <section>
-        <h2>Minimal examples</h2>
-        <ul>
-          <li><code>examples/decentralized-tictactoe.js</code> - replicated board state and owner authorization.</li>
-          <li><code>examples/decentralized-chess-lite.js</code> - replicated move history with a compact board model.</li>
-        </ul>
-        <pre><code>npm run example:tictactoe\nnpm run example:chess</code></pre>
-      </section>
-      <section>
-        <h2>Publish-ready browser bundles</h2>
-        <ul>
-          <li><code>dist/dignity.min.js</code> - minified browser IIFE bundle (global <code>DignityJS</code>).</li>
-          <li><code>dist/dignity.esm.js</code> - browser ESM bundle.</li>
-          <li><code>dist/dignity.cjs.js</code> - Node/CommonJS bundle.</li>
-        </ul>
-        <pre><code>npm test\nnpm run build\nnpm publish --access public</code></pre>
-      </section>
-    </main>
+            </div>
+            <p>Default public endpoints:</p>
+            <ul>
+              <li><code>wss://peerjs.92k.de/peerjs?key=peerjs</code></li>
+              <li><code>wss://0.peerjs.com/peerjs?key=peerjs</code></li>
+            </ul>
+          </section>
+          <section id="api-reference" class="section">
+            <h2>API reference</h2>
+            <p>Primary class: <code>DignityP2P</code></p>
+            <h3>Constructor</h3>
+            <div class="code-block">
+              <pre><code class="language-javascript">new DignityP2P({
+  nodeId,           // required — unique peer identifier
+  networkAdapter,   // required — transport implementation
+  security,         // optional — MessageSecurityService options
+  now,              // optional — clock injection (tests)
+  idGenerator       // optional — custom operation id factory
+})</code></pre>
+            </div>
+            <h3>Lifecycle</h3>
+            <div class="table-wrap">
+              <table>
+                <thead>
+                  <tr>
+                    <th>Method</th>
+                    <th>Description</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  <tr><td><code>start()</code></td><td>Connect adapter and begin receiving messages</td></tr>
+                  <tr><td><code>stop()</code></td><td>Leave discovery scopes and disconnect</td></tr>
+                  <tr><td><code>getPublicKey()</code></td><td>Return this node's public key bundle</td></tr>
+                  <tr><td><code>registerPeerPublicKey(id, key)</code></td><td>Trust a remote peer's keys</td></tr>
+                </tbody>
+              </table>
+            </div>
+            <p>
+              Machine-readable metadata:
+              <a href="./openapi-like.json">openapi-like.json</a>
+            </p>
+          </section>
+          <section id="events" class="section">
+            <h2>Events</h2>
+            <p><code>DignityP2P</code> extends <code>EventEmitter</code>. Common events:</p>
+            <div class="table-wrap">
+              <table>
+                <thead>
+                  <tr>
+                    <th>Event</th>
+                    <th>Payload</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  <tr>
+                    <td><span class="tag tag--event">change</span></td>
+                    <td><code>{ kind, collection, id }</code> — object created, updated, or deleted</td>
+                  </tr>
+                  <tr>
+                    <td><span class="tag tag--event">conflict</span></td>
+                    <td><code>{ kind, collection, id, expectedVersion, currentVersion, phase }</code></td>
+                  </tr>
+                  <tr>
+                    <td><span class="tag tag--event">peerdiscovered</span></td>
+                    <td><code>{ scope, peerId, metadata }</code></td>
+                  </tr>
+                  <tr>
+                    <td><span class="tag tag--event">peerleft</span></td>
+                    <td><code>{ scope, peerId, reason }</code></td>
+                  </tr>
+                  <tr>
+                    <td><span class="tag tag--event">message</span></td>
+                    <td><code>{ senderId, targetId, type, payload }</code> — custom decrypted messages</td>
+                  </tr>
+                  <tr>
+                    <td><span class="tag tag--event">securityerror</span></td>
+                    <td><code>{ senderId, error }</code></td>
+                  </tr>
+                  <tr>
+                    <td><span class="tag tag--event">warning</span></td>
+                    <td><code>{ type, ... }</code> — non-fatal issues (heartbeat, persistence, etc.)</td>
+                  </tr>
+                </tbody>
+              </table>
+            </div>
+          </section>
+          <section id="exports" class="section">
+            <h2>Package exports</h2>
+            <div class="table-wrap">
+              <table>
+                <thead>
+                  <tr>
+                    <th>Import path</th>
+                    <th>Exports</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  <tr>
+                    <td><code>dignity.js</code></td>
+                    <td><code>DignityP2P</code>, <code>IndexedDBPersistence</code>, signaling providers, in-memory adapters, security utilities</td>
+                  </tr>
+                  <tr>
+                    <td><code>dignity.js/react</code></td>
+                    <td><code>useDignity</code>, <code>useCollection</code>, <code>usePeers</code></td>
+                  </tr>
+                </tbody>
+              </table>
+            </div>
+          </section>
+          <section id="examples" class="section">
+            <h2>Examples</h2>
+            <div class="table-wrap">
+              <table>
+                <thead>
+                  <tr>
+                    <th>Script</th>
+                    <th>Description</th>
+                    <th>Run</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  <tr>
+                    <td><code>examples/decentralized-tictactoe.js</code></td>
+                    <td>Replicated board state and owner authorization</td>
+                    <td><code>npm run example:tictactoe</code></td>
+                  </tr>
+                  <tr>
+                    <td><code>examples/decentralized-chess-lite.js</code></td>
+                    <td>Replicated move history with compact board model</td>
+                    <td><code>npm run example:chess</code></td>
+                  </tr>
+                </tbody>
+              </table>
+            </div>
+          </section>
+          <section id="development" class="section">
+            <h2>Development</h2>
+            <div class="code-block">
+              <pre><code class="language-bash"># Run tests (177+ passing, ~99.5% line coverage)
+npm test
+# Build browser + Node bundles
+npm run build
+# Serve docs locally
+npm run docs:serve
+# Run examples
+npm run example:tictactoe
+npm run example:chess</code></pre>
+            </div>
+          </section>
+          <footer class="site-footer">
+            <p>
+              dignity.js v0.5.1 ·
+              <a href="https://github.com/jose-compu/dignity.js/blob/main/LICENSE">Apache 2.0</a> ·
+              <a href="https://github.com/jose-compu/dignity.js">GitHub</a> ·
+              <a href="https://www.npmjs.com/package/dignity.js">npm</a>
+            </p>
+          </footer>
+        </div>
+      </main>
+    </div>
+    <script src="./assets/highlight/highlight.min.js"></script>
+    <script src="./assets/docs.js"></script>
   </body>
 </html>