dignity.js 0.4.0 → 0.5.1

package/docs/chess/src/lib/localGames.js

@@ -0,0 +1,160 @@
+const SESSIONS_KEY = 'dignity-chess-sessions';
+const COLLECTION = 'chess-matches';
+const DB_NAME = 'dignity';
+const STORE_NAME = 'records';
+
+export function loadLocalGameSessions() {
+  try {
+    const raw = localStorage.getItem(SESSIONS_KEY);
+    const parsed = raw ? JSON.parse(raw) : [];
+    return Array.isArray(parsed) ? parsed : [];
+  } catch (error) {
+    return [];
+  }
+}
+
+export function saveLocalGameSession(session) {
+  if (!session?.gameId || !session?.roomKey) {
+    return;
+  }
+
+  const sessions = loadLocalGameSessions();
+  const index = sessions.findIndex((entry) => entry.gameId === session.gameId);
+  const next = {
+    ...sessions[index],
+    ...session,
+    updatedAt: session.updatedAt || Date.now()
+  };
+
+  if (index >= 0) {
+    sessions[index] = next;
+  } else {
+    sessions.unshift(next);
+  }
+
+  const trimmed = sessions
+    .sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0))
+    .slice(0, 40);
+
+  localStorage.setItem(SESSIONS_KEY, JSON.stringify(trimmed));
+}
+
+function loadChessRecordsFromIndexedDB() {
+  if (typeof indexedDB === 'undefined') {
+    return Promise.resolve([]);
+  }
+
+  return new Promise((resolve) => {
+    const request = indexedDB.open(DB_NAME, 1);
+
+    request.onerror = () => resolve([]);
+    request.onsuccess = () => {
+      const db = request.result;
+      if (!db.objectStoreNames.contains(STORE_NAME)) {
+        db.close();
+        resolve([]);
+        return;
+      }
+
+      const transaction = db.transaction(STORE_NAME, 'readonly');
+      const store = transaction.objectStore(STORE_NAME);
+      const getAll = store.getAll();
+
+      getAll.onsuccess = () => {
+        const records = (getAll.result || []).filter(
+          (record) => record.collection === COLLECTION && !record.deletedAt
+        );
+        resolve(records);
+        db.close();
+      };
+
+      getAll.onerror = () => {
+        resolve([]);
+        db.close();
+      };
+    };
+  });
+}
+
+function mergeSessionWithRecord(session, record) {
+  if (!record?.data) {
+    return session;
+  }
+
+  return {
+    ...session,
+    status: record.data.status || session.status || 'waiting',
+    winner: record.data.winner ?? session.winner ?? null,
+    moveCount: Array.isArray(record.data.moveHistory) ? record.data.moveHistory.length : session.moveCount || 0,
+    whitePlayerId: record.data.whitePlayerId || session.whitePlayerId || null,
+    blackPlayerId: record.data.blackPlayerId || session.blackPlayerId || null,
+    updatedAt: record.updatedAt || session.updatedAt || Date.now()
+  };
+}
+
+export async function listLocalGames() {
+  const sessions = loadLocalGameSessions();
+  const records = await loadChessRecordsFromIndexedDB();
+  const recordById = new Map(records.map((record) => [record.id, record]));
+
+  const merged = sessions.map((session) => mergeSessionWithRecord(session, recordById.get(session.gameId)));
+
+  const active = merged.filter((game) => game.status === 'waiting' || game.status === 'playing');
+  const finished = merged.filter((game) => game.status === 'finished');
+
+  return { active, finished };
+}
+
+export function sessionResumeHash(session) {
+  const role = session.role === 'host' ? 'host' : 'resume';
+  const params = new URLSearchParams({
+    game: session.gameId,
+    room: session.roomKey,
+    role,
+    resume: session.resumeToken || ''
+  });
+
+  if (session.hostPeer) {
+    params.set('host', session.hostPeer);
+  }
+  if (session.role === 'host' && session.joinToken) {
+    params.set('join', session.joinToken);
+  }
+  if (session.role === 'host' && session.watchToken) {
+    params.set('watch', session.watchToken);
+  }
+
+  return params.toString();
+}
+
+export function formatGameStatus(game) {
+  if (game.status === 'waiting') {
+    return 'Waiting for opponent';
+  }
+  if (game.status === 'playing') {
+    return `${game.moveCount || 0} move(s) · in progress`;
+  }
+  if (game.winner === 'draw') {
+    return 'Draw';
+  }
+  if (game.winner === 'w') {
+    return 'White wins';
+  }
+  if (game.winner === 'b') {
+    return 'Black wins';
+  }
+  return 'Finished';
+}
+
+export function formatRoleLabel(game) {
+  if (game.role === 'host') {
+    return 'You · White (host)';
+  }
+  if (game.role === 'join') {
+    return 'You · Black';
+  }
+  if (game.role === 'watch') {
+    return 'Spectator';
+  }
+  return 'Resume';
+}

package/docs/chess/src/lib/p2pDebug.js

@@ -0,0 +1,192 @@
+const PREFIX = '[chess-p2p]';
+
+function ts() {
+  return new Date().toISOString().slice(11, 23);
+}
+
+export function p2pLog(label, detail) {
+  if (detail === undefined) {
+    console.log(`${PREFIX} ${ts()} ${label}`);
+    return;
+  }
+  console.log(`${PREFIX} ${ts()} ${label}`, detail);
+}
+
+export function p2pWarn(label, detail) {
+  if (detail === undefined) {
+    console.warn(`${PREFIX} ${ts()} ${label}`);
+    return;
+  }
+  console.warn(`${PREFIX} ${ts()} ${label}`, detail);
+}
+
+export function p2pError(label, detail) {
+  if (detail === undefined) {
+    console.error(`${PREFIX} ${ts()} ${label}`);
+    return;
+  }
+  console.error(`${PREFIX} ${ts()} ${label}`, detail);
+}
+
+export function connectionSnapshot(node) {
+  const adapter = node?.networkAdapter;
+  if (!adapter) {
+    return { adapter: 'none' };
+  }
+
+  const openIds = [];
+  if (adapter.connections instanceof Map) {
+    for (const [peerId, conn] of adapter.connections.entries()) {
+      if (conn?.open) {
+        openIds.push(peerId);
+      }
+    }
+  }
+
+  return {
+    signalingUrl: adapter.url || null,
+    localPeerId: adapter.nodeId || node?.nodeId || null,
+    openConnectionCount: node?.getConnectionStats?.()?.openCount ?? adapter.getOpenConnectionCount?.() ?? openIds.length,
+    openPeerIds: node?.getConnectionStats?.()?.peerIds ?? openIds,
+    peerJsReady: Boolean(adapter.peer)
+  };
+}
+
+export function attachNodeDebugListeners(node, context = {}) {
+  if (!node || node.__chessDebugAttached) {
+    return () => undefined;
+  }
+
+  node.__chessDebugAttached = true;
+  const role = context.role || '?';
+
+  p2pLog(`debug attached (${role})`, {
+    nodeId: node.nodeId,
+    scope: context.scope,
+    gameId: context.gameId
+  });
+
+  const handlers = {
+    warning: (event) => p2pWarn('node warning', event),
+    securityerror: (event) => p2pError('security error', {
+      senderId: event?.senderId,
+      code: event?.error?.code,
+      message: event?.error?.message
+    }),
+    messageignored: (event) => p2pWarn('message ignored', event),
+    peerdiscovered: (event) => p2pLog('peer discovered', event),
+    peerleft: (event) => p2pLog('peer left', event),
+    peerbanned: (event) => p2pError('peer banned', event),
+    conflict: (event) => p2pWarn('sync conflict', event),
+    change: (event) => {
+      if (event?.collection === context.collection) {
+        p2pLog('game record changed', {
+          id: event.id,
+          kind: event.kind,
+          version: event.version
+        });
+      }
+    },
+    message: (event) => {
+      if (event?.type === 'claim-seat' || event?.type === 'operation') {
+        p2pLog('incoming message', {
+          type: event.type,
+          senderId: event.senderId,
+          payload: event.payload
+        });
+      }
+    }
+  };
+
+  for (const [eventName, handler] of Object.entries(handlers)) {
+    node.on(eventName, handler);
+  }
+
+  if (node.networkAdapter?.peer) {
+    const peer = node.networkAdapter.peer;
+    peer.on('error', (err) => {
+      p2pError('PeerJS error', {
+        type: err?.type,
+        message: err?.message || String(err)
+      });
+    });
+    peer.on('disconnected', () => p2pWarn('PeerJS disconnected from signaling server'));
+    peer.on('close', () => p2pWarn('PeerJS peer closed'));
+    peer.on('connection', (conn) => {
+      p2pLog('PeerJS inbound connection', { from: conn.peer });
+      conn.on('open', () => p2pLog('PeerJS data channel open (inbound)', { peer: conn.peer }));
+      conn.on('close', () => p2pWarn('PeerJS data channel closed (inbound)', { peer: conn.peer }));
+      conn.on('error', (err) => p2pError('PeerJS data channel error (inbound)', {
+        peer: conn.peer,
+        message: err?.message || String(err)
+      }));
+    });
+  }
+
+  return () => {
+    for (const [eventName, handler] of Object.entries(handlers)) {
+      node.off(eventName, handler);
+    }
+    delete node.__chessDebugAttached;
+  };
+}
+
+export function dumpJoinState({
+  route,
+  node,
+  nodeId,
+  scope,
+  status,
+  error,
+  joined,
+  roomConnected,
+  connectionCount,
+  remoteHostPeer,
+  peers,
+  game,
+  myColor
+}) {
+  const snap = connectionSnapshot(node);
+  const payload = {
+    role: route.role,
+    localNodeId: nodeId,
+    nodeRunningId: node?.nodeId,
+    hostPeerTarget: remoteHostPeer,
+    routeHostParam: route.hostPeer,
+    gameId: route.gameId,
+    scope,
+    dignityStatus: status,
+    dignityError: error?.message || null,
+    joinedDiscovery: joined,
+    roomConnected,
+    connectionCount,
+    peerJs: snap,
+    peers: peers.map((p) => ({
+      peerId: p.peerId,
+      role: p.metadata?.role,
+      nickname: p.metadata?.nickname,
+      joinToken: p.metadata?.joinToken ? `${p.metadata.joinToken.slice(0, 6)}…` : null
+    })),
+    game: game ? {
+      status: game.data?.status,
+      whitePlayerId: game.data?.whitePlayerId,
+      blackPlayerId: game.data?.blackPlayerId,
+      joinTokenUsed: game.data?.joinTokenUsed,
+      joinTokenMatch: route.joinToken === game.data?.joinToken,
+      version: game.version
+    } : null,
+    myColor,
+    webrtc: typeof RTCPeerConnection !== 'undefined' ? 'available' : 'missing'
+  };
+
+  p2pLog('STATE SNAPSHOT', payload);
+  return payload;
+}
+
+export function installGlobalDebug(dumpFn) {
+  if (typeof window === 'undefined') {
+    return;
+  }
+  window.__chessP2pDump = dumpFn;
+  p2pLog('manual dump: run __chessP2pDump() in console');
+}

package/docs/chess/src/main.jsx

@@ -0,0 +1,5 @@
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import App from './App.jsx';
+
+createRoot(document.getElementById('root')).render(<App />);

package/docs/index.html

@@ -3,8 +3,10 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <meta name="description" content="dignity.js v0.4.0 — REST-like P2P object API for decentralized JavaScript applications." />
+    <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" />
@@ -14,11 +16,12 @@
       <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.4.0</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>
@@ -46,6 +49,7 @@
             <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">
@@ -621,7 +625,7 @@ npm run example:chess</code></pre>
 
           <footer class="site-footer">
             <p>
-              dignity.js v0.4.0 ·
+              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>

package/docs/openapi-like.json

@@ -1,28 +1,44 @@
 {
   "name": "dignity.js",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "REST-like object API over peer-to-peer replication",
   "resources": {
     "collections/{collection}/{id}": {
       "create": {
         "method": "create(collection, data, options)",
-        "owner": "actor that creates the object"
+        "owner": "actor that creates the object",
+        "options": {
+          "id": "optional stable id",
+          "collaborators": "optional peer id list",
+          "broadcastScope": "scoped broadcast password namespace",
+          "connectToPeers": "optional; defaults to collaborators on PeerJS mesh"
+        }
       },
       "read": {
         "method": "read(collection, id)"
       },
       "update": {
         "method": "update(collection, id, patch, options)",
-        "authorization": "owner-only",
+        "authorization": "owner or collaborator",
         "options": {
           "expectedVersion": "optional number; throws VERSION_CONFLICT when mismatched",
-          "broadcastScope": "optional scoped broadcast password namespace"
+          "broadcastScope": "optional scoped broadcast password namespace",
+          "collaborators": "owner may replace collaborator list",
+          "connectToPeers": "optional; defaults to owner + collaborators"
         }
       },
       "updateWithRetry": {
         "method": "updateWithRetry(collection, id, patchFn, options)",
         "description": "read-modify-write helper with automatic retry on version conflicts"
       },
+      "pushRecordSnapshot": {
+        "method": "pushRecordSnapshot(collection, id, options)",
+        "description": "broadcast full record for late joiners who missed the initial create"
+      },
+      "getRecordPeerIds": {
+        "method": "getRecordPeerIds(collection, id, options)",
+        "description": "returns owner + collaborator peer ids for connectToPeers"
+      },
       "delete": {
         "method": "remove(collection, id)",
         "authorization": "owner-only"
@@ -32,11 +48,19 @@
       "list": {
         "method": "list(collection, options)"
       }
+    },
+    "peers": {
+      "connectToPeer": "open PeerJS data channel to peer id",
+      "getConnectionStats": "{ openCount, peerIds }",
+      "ensureConnectedToPeers": "connect to many peers before broadcast",
+      "joinDiscovery": "scoped presence; options.bootstrapPeerIds connects before announce",
+      "broadcastMessage": "custom app messages; options.connectToPeers"
     }
   },
   "events": {
-    "change": "object create/update/delete applied",
+    "change": "object create/update/delete/snapshot applied",
     "conflict": "local or remote version mismatch",
+    "warning": "orphan-operation, peer-connect-failed, presence failures",
     "peerdiscovered": "peer joined discovery scope",
     "peerleft": "peer left or timed out",
     "message": "custom decrypted message received"
@@ -56,7 +80,12 @@
     "hooks": [
       "useDignity",
       "useCollection",
-      "usePeers"
+      "useObject",
+      "usePeers",
+      "useDiscovery",
+      "useConnectionStats",
+      "useRoom",
+      "useMessages"
     ]
   },
   "signaling": {

package/examples/decentralized-chess-lite.js

@@ -11,6 +11,7 @@ function initialBoard() {
 
 async function runDemo() {
   const hub = new InMemoryNetworkHub();
+  const scope = 'room:chess-lite';
 
   const host = new DignityP2P({
     nodeId: 'host',
@@ -21,8 +22,27 @@ async function runDemo() {
     }
   });
 
-  const observer = new DignityP2P({
-    nodeId: 'observer',
+  await host.start();
+  await host.joinDiscovery(scope, {
+    metadata: { nickname: 'host', role: 'owner' },
+    heartbeatIntervalMs: 100000,
+    ttlMs: 30000
+  });
+
+  // Host creates before joiner is online — joiner never receives the create op.
+  await host.create(
+    'matches',
+    {
+      type: 'chess-lite',
+      board: initialBoard(),
+      moveHistory: [],
+      status: 'waiting'
+    },
+    { id: 'match-1', broadcastScope: scope }
+  );
+
+  const joiner = new DignityP2P({
+    nodeId: 'joiner',
     networkAdapter: new InMemoryNetworkAdapter(hub),
     security: {
       appPassword: 'demo-shared-password',
@@ -30,38 +50,40 @@ async function runDemo() {
     }
   });
 
-  await host.start();
-  await observer.start();
-  await host.joinDiscovery('room:chess-lite', {
-    metadata: { nickname: 'host', role: 'owner' },
-    heartbeatIntervalMs: 100000,
-    ttlMs: 30000
-  });
-  await observer.joinDiscovery('room:chess-lite', {
-    metadata: { nickname: 'observer', role: 'viewer' },
+  await joiner.start();
+  await joiner.joinDiscovery(scope, {
+    metadata: { nickname: 'joiner', role: 'player' },
+    bootstrapPeerIds: ['host'],
     heartbeatIntervalMs: 100000,
     ttlMs: 30000
   });
 
-  console.log(
-    '\nPeers visible from host in room:chess-lite:',
-    host.listPeers('room:chess-lite', { includeSelf: false }).map((peer) => peer.peerId)
-  );
+  console.log('\nJoiner before snapshot:', joiner.read('matches', 'match-1'));
 
-  await host.create(
+  const warnings = [];
+  joiner.on('warning', (event) => warnings.push(event));
+
+  await host.update(
     'matches',
+    'match-1',
+    { status: 'playing', blackPlayerId: 'joiner' },
     {
-      type: 'chess-lite',
-      board: initialBoard(),
-      moveHistory: []
-    },
-    { id: 'match-1', broadcastScope: 'room:chess-lite' }
+      broadcastScope: scope,
+      collaborators: ['host', 'joiner']
+    }
   );
 
+  console.log('\nJoiner after update (still missing create):', joiner.read('matches', 'match-1'));
+  console.log('Orphan warnings:', warnings.filter((event) => event.type === 'orphan-operation').length);
+
+  await host.pushRecordSnapshot('matches', 'match-1', {
+    broadcastScope: scope,
+    connectToPeers: ['joiner']
+  });
+
   const scriptedMoves = [
     { from: 'a2', to: 'a4', piece: 'whitePawnA' },
-    { from: 'a7', to: 'a5', piece: 'blackPawnA' },
-    { from: 'e1', to: 'e2', piece: 'whiteKing' }
+    { from: 'a7', to: 'a5', piece: 'blackPawnA' }
   ];
 
   for (const move of scriptedMoves) {
@@ -77,23 +99,23 @@ async function runDemo() {
         moveHistory,
         lastMove: move
       },
-      { broadcastScope: 'room:chess-lite' }
+      { broadcastScope: scope }
     );
   }
 
   const hostState = host.read('matches', 'match-1');
-  const observerState = observer.read('matches', 'match-1');
+  const joinerState = joiner.read('matches', 'match-1');
 
   console.log('\nHost state:');
   console.log(JSON.stringify(hostState.data, null, 2));
 
-  console.log('\nObserver replicated state:');
-  console.log(JSON.stringify(observerState.data, null, 2));
+  console.log('\nJoiner replicated state (after snapshot + moves):');
+  console.log(JSON.stringify(joinerState.data, null, 2));
 
-  await host.leaveDiscovery('room:chess-lite');
-  await observer.leaveDiscovery('room:chess-lite');
+  await host.leaveDiscovery(scope);
+  await joiner.leaveDiscovery(scope);
   await host.stop();
-  await observer.stop();
+  await joiner.stop();
 }
 
 runDemo().catch((error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dignity.js",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "P2P object API for decentralized JavaScript applications",
   "main": "dist/dignity.cjs.js",
   "module": "dist/dignity.esm.js",
@@ -31,8 +31,13 @@
     "test:cloudflare-live": "RUN_CLOUDFLARE_LIVE_TESTS=1 jest tests/integration/cloudflare-signaling-live.test.js --runInBand",
     "test:pow-calibrate": "jest tests/unit/sloth-vdf-timing.test.js --runInBand",
     "build": "node scripts/build.js",
-    "docs:serve": "npx http-server docs -p 4173 -o",
-    "docs:check": "node -e \"const fs=require('fs');['docs/index.html','docs/assets/highlight/highlight.min.js','docs/assets/highlight/github.min.css','docs/assets/highlight/github-dark.min.css'].forEach(p=>fs.accessSync(p));\"",
+    "build:chess": "node scripts/build-chess-demo.js",
+    "docs:favicon": "node scripts/generate-favicon.js",
+    "docs:build": "npm run build:chess",
+    "docs:dev": "node scripts/serve-docs.js",
+    "docs:serve": "node scripts/serve-docs.js",
+    "docs:stop": "node scripts/stop-docs.js",
+    "docs:check": "node -e \"const fs=require('fs');['docs/index.html','docs/favicon.ico','docs/chess/index.html','docs/chess/favicon.ico','docs/assets/favicon.svg','docs/chess/assets/chess-app.js','docs/assets/highlight/highlight.min.js','docs/assets/highlight/github.min.css','docs/assets/highlight/github-dark.min.css'].forEach(p=>fs.accessSync(p));\"",
     "example:tictactoe": "node examples/decentralized-tictactoe.js",
     "example:chess": "node examples/decentralized-chess-lite.js",
     "prepublishOnly": "npm test && npm run build"
@@ -55,12 +60,15 @@
   },
   "devDependencies": {
     "@testing-library/react": "^16.3.0",
+    "chess.js": "^1.4.0",
     "esbuild": "^0.28.0",
     "fake-indexeddb": "^6.0.0",
+    "http-server": "^14.1.1",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
     "react": "^19.1.0",
-    "react-dom": "^19.1.0"
+    "react-dom": "^19.1.0",
+    "three": "^0.184.0"
   },
   "dependencies": {
     "peerjs": "^1.5.5",