@dtudury/streamo 3.0.0 → 4.0.1

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,31 +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 |
 
-## the all-in-one demo
+## what `npm run dev` actually starts
 
-The chat server is also the website server. Run it once and you get the
-homepage, chat app, **and** the repo explorer all on the same origin:
+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.
 
-```bash
-# start the all-in-one demo server
-STREAMO_NAME=my-chat STREAMO_USERNAME=relay STREAMO_PASSWORD=secret \
-  node public/apps/chat/server.js
+Useful URLs once it's running:
 
-# homepage with app cards
-open http://localhost:8080/
+- `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)
 
-# chat
-open http://localhost:8080/apps/chat/
+To join chat from a terminal instead of the browser:
 
-# repo explorer — leave it open in another tab to watch commits roll in
-# as you chat
-open http://localhost:8080/apps/explorer/
-
-# join chat from the terminal
+```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": "3.0.0",
+  "version": "4.0.1",
   "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

@@ -13,8 +13,10 @@ function fmt (ts) {
 }
 
 function Msg ({ name, text, at, mine }) {
+  // +at coerces both Date and number to ms — stable key across old (number)
+  // and new (Date) message records as we transition.
   return h`
-    <div class=${['msg', mine ? 'mine' : 'theirs']} data-key=${at}>
+    <div class=${['msg', mine ? 'mine' : 'theirs']} data-key=${+at}>
       ${!mine ? h`<div class="sender">${name}</div>` : null}
       <div class="text">${text}</div>
       <div class="time">${fmt(at)}</div>
@@ -43,16 +45,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,7 +129,9 @@ joinBtn.onclick = async () => {
       if (!text) return
       inputEl.value = ''
       const messages = myRepo.get('messages') ?? []
-      myRepo.set({ name: username, messages: [...messages, { text, at: Date.now() }] })
+      const preview = text.length > 50 ? text.slice(0, 50).trim() + '…' : text
+      myRepo.defaultMessage = `"${preview}" (web)`
+      myRepo.set({ name: username, messages: [...messages, { text, at: new Date() }] })
     }
 
     sendBtn.onclick = sendMessage

package/public/apps/explorer/index.html

@@ -31,9 +31,11 @@
     .row + .row { border-top-color: var(--rule); }
     .row:hover + .row { border-top-color: transparent; }
 
-    /* signature rows show 4 columns: kind, range, hex, addr */
-    .row.signature { grid-template-columns: 4rem 1fr 1fr 6rem; }
-    .row.commit    { grid-template-columns: 4rem 1fr 12rem 6rem; }
+    /* 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); }
@@ -49,8 +51,115 @@
       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.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.signed-commit.unsigned .kind { color: var(--ink-dim); border-color: var(--ink-dim); }
+
+    /* 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; }
+
+    /* Detached card — same layout as the head-card but neutral styling.
+       Shown as the selector summary when the current address isn't a sig
+       (you've drilled into raw memory). The dropdown body is still the
+       way back — pick a real commit and you re-attach. */
+    .row.signed-commit.detached-card {
+      border: 1.5px dashed var(--rule);
+      background: transparent;
+      padding: 0.85rem;
+      cursor: pointer;
+    }
+    .row.signed-commit.detached-card .kind {
+      color: var(--ink-dim);
+      border-color: var(--ink-dim);
+    }
+    .row.signed-commit.detached-card .msg { font-size: 0.95rem; }
+
+    /* 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); }
+
+    /* "What this is" banner — top of every value tab. Default neutral
+       border for storage codecs; green .verified for commits or sigs
+       backed by a valid signature; dim .unsigned for commits awaiting
+       a signature. */
+    .kind-banner {
+      display: flex; align-items: center; gap: 0.5rem;
+      padding: 0.65rem 0.85rem; margin: 0.5rem 0 1rem;
+      border: 1.5px solid var(--rule); border-radius: var(--radius);
+    }
+    .kind-banner.verified {
+      border-color: #16a34a;
+      background: rgba(22, 163, 74, 0.06);
+    }
+    .kind-banner.unsigned { border-style: dashed; }
+    .kind-banner .kind-label {
+      font-size: 0.7rem; text-transform: uppercase; letter-spacing: 0.08em;
+      font-weight: 600; color: var(--ink-dim);
+    }
+    .kind-banner.verified .kind-label { 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; }
 
@@ -87,11 +196,111 @@
     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-family: monospace; font-size: 0.78rem; color: var(--ink-dim); word-break: break-all; }
+    .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;