@dtudury/streamo 2.0.0 → 4.0.0

package/README.md

@@ -11,18 +11,35 @@ Streamo is a peer-to-peer sync library built around a simple promise: **no serve
 - **Every write is provably yours** — commits are signed with your keypair and append-only. History is permanent and can't be forged; peers reject unsigned or mis-signed data.
 - **Content-addressed** — data is identified by what it is, not where it lives. The same value always lands at the same address; deduplication and diffing are structural.
 
-## install
+## three ways to use streamo
 
-```bash
-npm install @dtudury/streamo
-```
+There are basically three audiences. Pick the one that's you:
+
+**1. As a library** — `npm install @dtudury/streamo` and import the pieces
+you want. See the *javascript api* section below for what's exported.
 
-Or run the CLI directly:
+**2. As a CLI** — `npx @dtudury/streamo --help` runs the streamo CLI
+without cloning anything. You bring credentials, point at files or peers,
+and get a personal streamo node. See the *cli* section.
+
+**3. As a reference / contributor** — clone this repo, then:
 
 ```bash
-npx @dtudury/streamo --help
+npm install
+npm run dev      # starts the all-in-one demo on port 8080
 ```
 
+`npm run dev` runs the chat-room server (`public/apps/chat/server.js`) with
+the checked-in dev credentials in `.env.dev`. That one server hosts the
+homepage, chat app, **and** the repo explorer at `localhost:8080`. Modify
+any file, refresh, see the change.
+
+For production deployment, your real `.env.prod` lives only on the
+production host, and `npm run prod` boots the same server against that
+env.
+
+`npm test` runs the test suite.
+
 ## cli
 
 ```bash
@@ -177,21 +194,29 @@ For hot-reloading, `componentKey(prefix, address)` and `defineComponent(name, fn
 | `s3Sync` | replicate chunks to S3-compatible object storage |
 | `stateFileSync` | write repo state as JSON on every change |
 
-## chat example
+## what `npm run dev` actually starts
 
-```bash
-# start the server — its public key becomes the room key
-STREAMO_NAME=my-chat STREAMO_USERNAME=relay STREAMO_PASSWORD=secret \
-  node public/apps/chat/server.js
+The chat-room server. It's the all-in-one demo: the homepage, chat app,
+and repo explorer are all served by the same process on port 8080. The
+"server" is just another streamo node — it holds the room's member list
+in its own repo and auto-accepts anyone who announces to it. Its public
+key is the room address. No special authority, no hidden state.
+
+Useful URLs once it's running:
 
-# join from the browser
-open http://localhost:8080/apps/chat/
+- `http://localhost:8080/` — homepage with app cards
+- `http://localhost:8080/apps/chat/` — chat
+- `http://localhost:8080/apps/explorer/` — repo explorer (leave it open in
+  another tab to watch commits roll in as you chat)
 
-# join from the terminal
+To join chat from a terminal instead of the browser:
+
+```bash
 node public/streamo/chat-cli.js alice secret localhost 8080
 ```
 
-Each participant owns their own message stream. The server is just another streamo node — it holds the member list in its own repo and auto-accepts anyone who announces to it. Its public key is the room address. No special authority, no hidden state.
+Each participant owns their own message stream. Same data structure,
+different transport.
 
 ## tests
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dtudury/streamo",
-  "version": "2.0.0",
+  "version": "4.0.0",
   "description": "peer-to-peer sync where your data and identity belong to you, not the server",
   "keywords": ["p2p", "peer-to-peer", "sync", "reactive", "content-addressed", "websocket", "signed", "append-only", "offline-first", "cryptographic", "identity"],
   "repository": "git@github.com:dtudury/streamo.git",
@@ -36,7 +36,7 @@
   },
   "scripts": {
     "test": "node --test",
-    "serve": "node bin/streamo.js --env-file .env.dev --web 3000 --interactive",
-    "chat": "node public/apps/chat/server.js --env-file .env.dev"
+    "dev":  "node public/apps/chat/server.js --env-file .env.dev",
+    "prod": "node public/apps/chat/server.js --env-file .env.prod"
   }
 }

package/public/apps/chat/main.js

@@ -43,16 +43,31 @@ joinBtn.onclick = async () => {
     const myKey   = bytesToHex(publicKey)
     const registry = new RepoRegistry()
 
+    // Track who we've already announced ourselves back to, so we don't
+    // ping-pong forever. Without this set, every peer-back ricochets into
+    // another peer-back and so on.
+    const announcedTo = new Set()
     const session = await registrySync(registry, location.hostname, Number(location.port) || 80, {
       filter:     k => k === rootKey,
       follow:     (keyHex, repo, subscribe) => {
                     for (const memberKey of repo.get('members') ?? []) subscribe(memberKey)
                   },
-      onAnnounce: key => session.subscribe(key)
+      // When a peer announces, subscribe to them AND announce ourselves
+      // back so they learn we exist — this makes peer discovery work
+      // through pure real-time fan-out, no server-side member tracking
+      // required. Late-joiner sees us, we see late-joiner.
+      onAnnounce: key => {
+        session.subscribe(key)
+        if (!announcedTo.has(key)) {
+          announcedTo.add(key)
+          session.announce(myKey, rootKey)
+        }
+      }
     })
 
     const myRepo = await registry.open(myKey)
     myRepo.attachSigner(signer, 'chat')
+    myRepo.defaultMessage = `joined as ${username} (web)`
 
     session.interest(rootKey)
     session.announce(myKey, rootKey)
@@ -112,6 +127,8 @@ joinBtn.onclick = async () => {
       if (!text) return
       inputEl.value = ''
       const messages = myRepo.get('messages') ?? []
+      const preview = text.length > 50 ? text.slice(0, 50).trim() + '…' : text
+      myRepo.defaultMessage = `"${preview}" (web)`
       myRepo.set({ name: username, messages: [...messages, { text, at: Date.now() }] })
     }
 

package/public/apps/explorer/index.html

@@ -0,0 +1,303 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>streamo explorer</title>
+  <link rel="stylesheet" href="/apps/styles/proto.css">
+  <style>
+    body { max-width: 60rem; margin: 0 auto; padding: 2rem 1.25rem; }
+
+    .header  { display: flex; align-items: baseline; gap: 0.75rem; margin-bottom: 0.25rem; }
+    .wordmark { font-size: 1.6rem; letter-spacing: -0.02em; }
+    .crumbs  { font-size: 0.85rem; color: var(--ink-dim); }
+    .back    { cursor: pointer; color: var(--ink-dim); font-size: 0.85rem; display: inline-block; margin-bottom: 1rem; }
+    .back:hover { color: var(--ink); }
+
+    h2 { font-size: 1.05rem; font-weight: 600; margin: 1.25rem 0 0.5rem; }
+    h2 .dim { font-weight: 400; font-size: 0.9rem; }
+
+    .row {
+      display: grid;
+      grid-template-columns: 1fr 12rem 14rem;
+      gap: 0.75rem;
+      align-items: baseline;
+      padding: 0.55rem 0.75rem;
+      border: 1.5px solid transparent;
+      border-radius: var(--radius);
+      cursor: pointer;
+    }
+    .row:hover { border-color: var(--ink); background: rgba(254, 240, 138, 0.4); }
+    .row + .row { border-top-color: var(--rule); }
+    .row:hover + .row { border-top-color: transparent; }
+
+    /* signed-commit + unsigned-commit + commit + signature rows share the same
+       column template so the page doesn't visually jitter as you scan a mixed
+       list. cols: kind | message | date | addr. */
+    .row.signed-commit, .row.unsigned-commit,
+    .row.commit, .row.signature { grid-template-columns: 6rem 1fr 14rem 6rem; }
+
+    .row .mono { font-size: 0.85rem; }
+    .row .when { font-size: 0.78rem; color: var(--ink-dim); }
+    .row .msg  { font-size: 0.85rem; }
+    .row .kind {
+      font-size: 0.7rem;
+      text-transform: uppercase;
+      letter-spacing: 0.08em;
+      color: var(--ink-dim);
+      border: 1px solid var(--rule);
+      border-radius: 999px;
+      padding: 0.05rem 0.5rem;
+      text-align: center;
+      align-self: center;
+    }
+    .row.commit .kind          { color: var(--accent); border-color: var(--accent); }
+    .row.signature .kind       { color: var(--warn);   border-color: var(--warn); }
+    .row.signed-commit .kind   { color: #16a34a;       border-color: #16a34a; }
+    .row.unsigned-commit .kind { color: var(--warn);   border-color: var(--warn); }
+
+    /* HEAD card — the most-recent signed commit, prominent and self-orienting. */
+    .row.signed-commit.head-card {
+      border: 1.5px solid #16a34a;
+      background: rgba(22, 163, 74, 0.05);
+      padding: 0.85rem;
+    }
+    .row.signed-commit.head-card .msg { font-size: 1rem; font-weight: 500; }
+
+    /* Commit selector: a real dropdown widget. Summary = currently-selected
+       commit (HEAD by default), styled as the green head-card. Body =
+       full list of signed commits, with the selected one marked. */
+    details.commit-selector { margin: 0.5rem 0 1rem; }
+    details.commit-selector > summary {
+      cursor: pointer;
+      list-style: none;
+      padding: 0;
+    }
+    details.commit-selector > summary::-webkit-details-marker { display: none; }
+    details.commit-selector > summary::marker { display: none; }
+    details.commit-selector > summary::after {
+      content: '▾';
+      float: right;
+      margin: 0.5rem 0.85rem;
+      color: #16a34a;
+      font-size: 0.85rem;
+    }
+    details.commit-selector[open] > summary::after { content: '▴'; }
+    details.commit-selector .dropdown-body {
+      margin-top: 0.25rem;
+      border: 1px solid var(--rule);
+      border-radius: var(--radius);
+      padding: 0.25rem;
+    }
+    details.commit-selector .dropdown-body .row { padding: 0.45rem 0.6rem; }
+    details.commit-selector .dropdown-body .row.selected {
+      background: rgba(22, 163, 74, 0.07);
+    }
+    details.commit-selector .dropdown-body .row.selected .kind::after {
+      content: ' ●';
+      color: #16a34a;
+    }
+
+    /* Tucked-away secondary "storage chunks" list at the bottom of the
+       repo view — a click away when you want to see the bytes underneath. */
+    details.other-storage {
+      margin: 1.25rem 0 0.5rem;
+      border-top: 1px solid var(--rule);
+      padding-top: 0.5rem;
+    }
+    details.other-storage > summary {
+      cursor: pointer;
+      font-size: 0.85rem;
+      color: var(--ink-dim);
+      padding: 0.35rem 0.25rem;
+    }
+    details.other-storage[open] > summary { color: var(--ink); }
+
+    /* Polished signed-commit detail view (AtView SIGNATURE branch). */
+    .signed-commit-banner {
+      display: flex; align-items: center; gap: 0.5rem;
+      padding: 0.65rem 0.85rem; margin: 0.5rem 0 1rem;
+      border: 1.5px solid #16a34a; border-radius: var(--radius);
+      background: rgba(22, 163, 74, 0.06);
+    }
+    .signed-commit-banner .signed-label {
+      font-size: 0.7rem; text-transform: uppercase; letter-spacing: 0.08em;
+      font-weight: 600; color: #16a34a;
+    }
+    .commit-card {
+      padding: 0.6rem 0.85rem; margin: 0.4rem 0;
+      border: 1px solid var(--rule); border-radius: var(--radius);
+    }
+    .commit-card .commit-msg { font-size: 0.95rem; margin-bottom: 0.25rem; }
+    .commit-card .commit-meta { font-size: 0.8rem; }
+
+    .verify-badge { font-weight: 700; padding-left: 0.35em; font-size: 0.95em; }
+    .verify-badge.valid   { color: #16a34a; }
+    .verify-badge.invalid { color: #dc2626; }
+    .verify-badge.pending { color: var(--ink-dim); font-weight: 400; }
+    .verify-badge.error   { color: #ca8a04; }
+
+    .empty { color: var(--ink-dim); padding: 0.5rem 0.75rem; font-size: 0.9rem; }
+
+    /* key/value table for the at-view */
+    .kv { width: 100%; border-collapse: collapse; font-size: 0.85rem; margin: 0.75rem 0; }
+    .kv td { padding: 0.4rem 0.6rem; vertical-align: top; }
+    .kv tr + tr td { border-top: 1px dashed var(--rule); }
+    .kv td:first-child {
+      color: var(--ink-dim);
+      width: 8rem;
+      font-size: 0.78rem;
+      text-transform: uppercase;
+      letter-spacing: 0.06em;
+    }
+
+    /* clickable variant — whole row is the click target */
+    .kv.clickable tr { cursor: pointer; }
+    .kv.clickable tr:hover td { background: rgba(254, 240, 138, 0.4); }
+    .kv.clickable td:last-child { color: var(--accent); text-align: right; }
+
+    .addr-link {
+      font-family: monospace;
+      font-size: 0.85rem;
+      color: var(--accent);
+      cursor: pointer;
+      text-decoration: underline dotted;
+    }
+    .addr-link:hover { background: var(--flash); text-decoration-style: solid; }
+
+    .paths { list-style: none; padding: 0; }
+    .paths li { padding: 0.2rem 0.5rem; font-size: 0.85rem; }
+    .paths li + li { border-top: 1px dashed var(--rule); }
+
+    h3 { font-size: 0.9rem; font-weight: 600; margin: 1.25rem 0 0.5rem; }
+    h3 .dim { font-weight: 400; font-size: 0.85rem; }
+
+    .explainer {
+      font-size: 0.85rem;
+      line-height: 1.55;
+      color: var(--ink-dim);
+      border-left: 2px solid var(--rule);
+      padding: 0.4rem 0 0.4rem 0.85rem;
+      margin: 0.6rem 0 0.9rem;
+    }
+    .explainer strong { color: var(--ink); }
+
+    .conn { font-size: 0.75rem; color: var(--ink-dim); margin-bottom: 1.5rem; }
+    .conn.ok  { color: #16a34a; }
+    .conn.err { color: #dc2626; }
+
+    .keyfull { font-size: 0.78rem; color: var(--ink-dim); word-break: break-all; }
+    .keyfull .mono { font-family: monospace; }
+    .repo-link {
+      font-family: monospace;
+      color: var(--accent);
+      cursor: pointer;
+      text-decoration: underline dotted;
+    }
+    .repo-link:hover { background: var(--flash); text-decoration-style: solid; }
+
+    /* Byte stream — zoomed strip in a horizontally-scrollable container,
+       click-drag-to-pan inside for "look around" navigation. */
+    .byte-strip-container {
+      width: 100%;
+      overflow-x: auto;
+      background: #faf9f4;
+      border: 1.5px solid var(--rule);
+      border-radius: var(--radius);
+      margin: 0.4rem 0 1rem;
+      cursor: grab;
+    }
+    .byte-strip-container.dragging { cursor: grabbing; user-select: none; }
+    .byte-strip-container.dragging .chunk { cursor: grabbing; }
+    .byte-strip { display: block; }
+
+    .byte-map {
+      display: block;
+    }
+    .byte-map .chunk {
+      cursor: pointer;
+      stroke: rgba(0, 0, 0, 0.15);
+      stroke-width: 0.4;
+      transition: stroke-width 0.08s, fill-opacity 0.08s;
+    }
+    .byte-map .chunk:hover { stroke: var(--ink); stroke-width: 1.5; }
+    .byte-map .chunk.current { stroke: var(--ink); stroke-width: 2; }
+    .byte-map .chunk.hovered { fill-opacity: 0.55; }
+
+    /* codec category palette — used in both the legend and the SVG fills */
+    .cat-commit    { fill: #f59e0b; background: #f59e0b; }
+    .cat-sig       { fill: #ef4444; background: #ef4444; }
+    .cat-composite { fill: #3b82f6; background: #3b82f6; }
+    .cat-duple     { fill: #a855f7; background: #a855f7; }
+    .cat-string    { fill: #10b981; background: #10b981; }
+    .cat-bytes     { fill: #84cc16; background: #84cc16; }
+    .cat-num       { fill: #64748b; background: #64748b; }
+    .cat-var       { fill: #fbbf24; background: #fbbf24; }
+    .cat-other     { fill: #cbd5e1; background: #cbd5e1; }
+
+    .byte-map-legend {
+      display: flex;
+      gap: 0.5rem;
+      flex-wrap: wrap;
+      font-size: 0.7rem;
+      color: var(--ink-dim);
+      margin-top: 0.5rem;
+    }
+    .byte-map-legend span {
+      display: inline-flex;
+      align-items: center;
+      gap: 0.3rem;
+      padding: 0.05rem 0.45rem 0.05rem 0.3rem;
+      border-radius: 999px;
+      color: #fff;
+      font-weight: 500;
+      letter-spacing: 0.02em;
+    }
+
+    /* Tab strip — hand-drawn underline aesthetic to match proto.css */
+    .tabs {
+      display: flex;
+      gap: 1.25rem;
+      border-bottom: 1.5px solid var(--rule);
+      margin: 1.25rem 0 1rem;
+    }
+    .tab {
+      padding: 0.45rem 0.1rem;
+      margin-bottom: -1.5px;
+      border-bottom: 2px solid transparent;
+      cursor: pointer;
+      font-size: 0.85rem;
+      color: var(--ink-dim);
+      letter-spacing: 0.04em;
+      text-transform: lowercase;
+    }
+    .tab:hover { color: var(--ink); }
+    .tab.active {
+      color: var(--ink);
+      border-bottom-color: var(--ink);
+      font-weight: 600;
+    }
+
+    pre.value {
+      font-family: monospace;
+      font-size: 0.8rem;
+      background: var(--rule);
+      border-radius: var(--radius);
+      padding: 1rem;
+      overflow-x: auto;
+      white-space: pre-wrap;
+      word-break: break-word;
+    }
+  </style>
+</head>
+<body>
+  <div class="header">
+    <div class="wordmark">streamo</div>
+    <div class="crumbs">explorer</div>
+  </div>
+  <div id="conn" class="conn">connecting…</div>
+  <div id="app"></div>
+
+  <script type="module" src="./main.js"></script>
+</body>
+</html>