@dtudury/streamo 4.0.1 → 4.0.2

package/README.md

@@ -126,6 +126,29 @@ const registry = new RepoRegistry(async key => {
 const repo = await registry.open(publicKeyHex)
 ```
 
+### bridgeRegistry — connect a multi-repo registry to your app's Recaller
+
+Each `Repo` owns its own `Recaller` (so it can do fine-grained tracking on its
+own internal keys), and your app uses a separate `Recaller` for its `mount()`
+slots. Reading `repo.byteLength` inside a slot registers a dep on the *repo's*
+recaller, not the app's, so without an explicit bridge the slot would never
+re-run when chunks arrive. `bridgeRegistry` is that bridge:
+
+```js
+import { Recaller, bridgeRegistry, h, mount } from '@dtudury/streamo'
+
+const recaller = new Recaller('app')
+const { dep, fire } = bridgeRegistry(registry, recaller)
+
+mount(h`${() => {
+  dep()
+  for (const [k, r] of registry) ...   // freely read any repo's state
+}}`, appEl, recaller)
+
+// Non-repo state changes (route, async results) — call fire() to force a re-render.
+window.addEventListener('hashchange', fire)
+```
+
 ### registrySync — peer sync over WebSocket
 
 ```js
@@ -163,7 +186,7 @@ mount(h`
 `, document.body, recaller)
 ```
 
-Functions interpolated as `${() => ...}` are reactive cells — they re-run automatically whenever the data they read changes. No virtual DOM diffing; only the exact DOM nodes bound to changed data update. Elements are recycled across re-renders by `data-key` (or tag as a fallback), so user input and focus survive list reorders. SVG namespaces propagate automatically — `` h`<svg><path d="..."/></svg>` `` works without any extra wiring. `class` accepts an array (`['btn', isActive && 'active']`) or an object (`{btn: true, active: false}`); falsy entries are filtered out.
+Functions interpolated as `${() => ...}` are reactive cells — they re-run automatically whenever the data they read changes. Only the exact DOM nodes bound to changed data update. Elements with stable `data-key` are recycled across re-renders so the outer element's identity and document position survive (helpful for animations or external DOM references). The recycled element's inner content is rebuilt from the new vnode on each re-render, so static interpolations (`${value}`) reflect current state. SVG namespaces propagate automatically — `` h`<svg><path d="..."/></svg>` `` works without any extra wiring. `class` accepts an array (`['btn', isActive && 'active']`) or an object (`{btn: true, active: false}`); falsy entries are filtered out.
 
 > **For lists that can reorder**, always set `data-key` on each item — the unkeyed positional fallback will recycle elements by tag in document order, which can attach the wrong DOM node (and any user focus/input on it) to the wrong vnode after a reorder.
 

package/index.js

@@ -17,6 +17,7 @@ export { Repo } from './public/streamo/Repo.js'
 export { Signer, verifySignature } from './public/streamo/Signer.js'
 export { Signature } from './public/streamo/Signature.js'
 export { RepoRegistry } from './public/streamo/RepoRegistry.js'
+export { bridgeRegistry } from './public/streamo/bridgeRegistry.js'
 export { registrySync, handleRegistryPeer } from './public/streamo/registrySync.js'
 export { archiveSync } from './public/streamo/archiveSync.js'
 export { fileSync } from './public/streamo/fileSync.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dtudury/streamo",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "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",

package/public/apps/chat/main.js

@@ -4,6 +4,7 @@ import { Recaller } from '../../streamo/utils/Recaller.js'
 import { Signer } from '../../streamo/Signer.js'
 import { RepoRegistry } from '../../streamo/RepoRegistry.js'
 import { registrySync } from '../../streamo/registrySync.js'
+import { bridgeRegistry } from '../../streamo/bridgeRegistry.js'
 import { bytesToHex } from '../../streamo/utils.js'
 
 const { primaryKeyHex: rootKey } = await fetch('/api/info').then(r => r.json())
@@ -81,30 +82,25 @@ joinBtn.onclick = async () => {
     // ── Reactive message list ──────────────────────────────────────────────
     //
     // Each repo has its own internal Recaller, so repo.get() inside a mount
-    // slot won't automatically re-trigger mount's recaller. Bridge via
-    // reportKey*: repo.watch() calls reportKeyMutation when data changes;
-    // the slot calls reportKeyAccess to register the dependency.
+    // slot doesn't automatically re-trigger mount's recaller. bridgeRegistry
+    // wires every repo (existing and future) into a single signal on the
+    // chat recaller; dep() inside the slot subscribes to it. See design.md
+    // §6 for the cross-recaller pattern.
 
     const recaller = new Recaller('chat')
-    const signal   = {}
-
-    function triggerRender () {
-      recaller.reportKeyMutation(signal, 'data')
+    const { dep } = bridgeRegistry(registry, recaller, 'chat')
+
+    // Auto-scroll to the bottom whenever any chunk arrives. Subscribing
+    // via the same `dep` keeps it in lockstep with the mount slot — both
+    // re-run when the bridge fires, the slot updates the DOM, and this
+    // watcher schedules a post-layout scroll.
+    recaller.watch('chat-scroll', () => {
+      dep()
       requestAnimationFrame(() => { msgsEl.scrollTop = msgsEl.scrollHeight })
-    }
-
-    function watchRepo (keyHex, repo) {
-      repo.watch(`chat:${keyHex}`, () => {
-        repo.byteLength  // register 'length' dep → re-fires on every commit and incoming sync chunk
-        triggerRender()
-      })
-    }
-
-    for (const [k, r] of registry) watchRepo(k, r)
-    registry.onOpen((keyHex, repo) => { watchRepo(keyHex, repo); triggerRender() })
+    })
 
     mount(h`${function messages () {
-      recaller.reportKeyAccess(signal, 'data')
+      dep()
       const all = []
       for (const [keyHex, repo] of registry) {
         if (keyHex === rootKey) continue

package/public/apps/explorer/index.html

@@ -4,6 +4,7 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>streamo explorer</title>
+  <link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 16 16%22><text y=%2214%22 font-size=%2214%22>🌊</text></svg>">
   <link rel="stylesheet" href="/apps/styles/proto.css">
   <style>
     body { max-width: 60rem; margin: 0 auto; padding: 2rem 1.25rem; }
@@ -248,6 +249,33 @@
     .byte-map .chunk.current { stroke: var(--ink); stroke-width: 2; }
     .byte-map .chunk.hovered { fill-opacity: 0.55; }
 
+    /* Streamo-typed value pills — every value gets a type-specific visual
+       identity instead of flattening through JSON.stringify. Colors echo
+       the byte-strip codec palette below so the visual language carries
+       across the page. */
+    .tv {
+      display: inline-flex;
+      align-items: center;
+      gap: 0.25rem;
+      padding: 0.05rem 0.4rem;
+      border-radius: var(--radius);
+      font-size: 0.85rem;
+      max-width: 100%;
+      vertical-align: baseline;
+    }
+    .tv-string { color: #047857; background: rgba(16, 185, 129, 0.10); font-family: monospace; }
+    .tv-string .tv-quote { color: #10b981; opacity: 0.7; font-weight: 600; }
+    .tv-num    { color: #475569; background: rgba(100, 116, 139, 0.10); font-family: monospace; }
+    .tv-date   { color: #475569; background: rgba(100, 116, 139, 0.10); }
+    .tv-date .tv-glyph { font-size: 0.75rem; }
+    .tv-date time { font-variant-numeric: tabular-nums; }
+    .tv-bool.tv-true   { color: #15803d; background: rgba(22, 163, 74, 0.10); font-family: monospace; }
+    .tv-bool.tv-false  { color: #b91c1c; background: rgba(220, 38, 38, 0.10); font-family: monospace; }
+    .tv-null, .tv-undefined { color: var(--ink-dim); background: transparent; font-style: italic; font-family: monospace; }
+    .tv-bytes  { color: #4d7c0f; background: rgba(132, 204, 22, 0.10); font-family: monospace; }
+    .tv-array, .tv-object { color: #1e40af; background: rgba(59, 130, 246, 0.10); }
+    .tv-duple  { color: #6b21a8; background: rgba(168, 85, 247, 0.10); }
+
     /* codec category palette — used in both the legend and the SVG fills */
     .cat-commit    { fill: #f59e0b; background: #f59e0b; }
     .cat-sig       { fill: #ef4444; background: #ef4444; }

package/public/apps/explorer/main.js

@@ -13,15 +13,16 @@
 // storage chunks tucked into a <details>). Otherwise it's storage
 // drilling — value/storage tabs for that chunk, no selector.
 //
-// State lives in plain JS variables; reactivity is bridged from each Repo's
-// internal Recaller into the app-level Recaller via the `signal` pattern
-// (see chat/main.js for the same approach).
+// Reactivity is bridged from each Repo's internal Recaller into the
+// app-level Recaller via bridgeRegistry — see design.md §6 for why
+// each Repo has its own Recaller and how the bridge connects them.
 
 import { h } from '../../streamo/h.js'
 import { mount } from '../../streamo/mount.js'
 import { Recaller } from '../../streamo/utils/Recaller.js'
 import { RepoRegistry } from '../../streamo/RepoRegistry.js'
 import { registrySync } from '../../streamo/registrySync.js'
+import { bridgeRegistry } from '../../streamo/bridgeRegistry.js'
 import { changedPaths } from '../../streamo/Streamo.js'
 import { hexToBytes } from '../../streamo/utils.js'
 
@@ -44,36 +45,18 @@ try {
 // ── App-level reactivity ──────────────────────────────────────────────────
 
 const recaller = new Recaller('explorer')
-const signal = {}
-const dep = () => recaller.reportKeyAccess(signal, 'data')
+const { dep, fire: bridgeFire } = bridgeRegistry(registry, recaller, 'explorer')
 
-const schedule = typeof requestAnimationFrame !== 'undefined'
-  ? fn => requestAnimationFrame(fn)
-  : fn => queueMicrotask(fn)
-let scheduled = false
+// Wrap bridgeFire to also schedule the byte-strip pin-to-HEAD side effect
+// after the next render. Reactive mutation is synchronous (so the slot
+// re-runs at next tick); only the post-render DOM peek goes through rAF.
+let stripSyncScheduled = false
 function fire () {
-  if (scheduled) return
-  scheduled = true
-  schedule(() => {
-    scheduled = false
-    recaller.reportKeyMutation(signal, 'data')
-    // After mount has updated the DOM, sync byte-strip viewport indicators
-    // and (if appropriate) keep them pinned to HEAD on live updates.
-    syncByteStrips()
-  })
-}
-
-const watched = new Set()
-function watchRepo (key, repo) {
-  if (watched.has(key)) return
-  watched.add(key)
-  repo.watch(`explorer:${key}`, () => {
-    repo.byteLength
-    fire()
-  })
+  bridgeFire()
+  if (stripSyncScheduled) return
+  stripSyncScheduled = true
+  requestAnimationFrame(() => { stripSyncScheduled = false; syncByteStrips() })
 }
-for (const [k, r] of registry) watchRepo(k, r)
-registry.onOpen((k, r) => { watchRepo(k, r); fire() })
 
 // ── Hash routing ──────────────────────────────────────────────────────────
 
@@ -298,11 +281,18 @@ function RegistryView () {
       dep()
       const rows = []
       for (const [keyHex, repo] of registry) {
+        // No claims about state we can't verify — show the date when we
+        // resolve a commit, otherwise show the byte count. byteLength
+        // is honest: it's what we actually have on hand. The watcher
+        // fires as more chunks land and the row settles to a date once
+        // the commit chunk resolves at the end of the stream.
         const last = repo.lastCommit
+        const len = repo.byteLength
+        const when = last ? fmtDate(last.date) : `${len} b`
         rows.push(h`
           <div class="row" data-key=${keyHex} data-action="open-repo">
             <span class="mono">${truncKey(keyHex)}</span>
-            <span class="when">${last ? fmtDate(last.date) : '(no commits)'}</span>
+            <span class=${['when', last ? null : 'dim']}>${when}</span>
             <span class="msg dim">${last?.message || ''}</span>
           </div>
         `)
@@ -407,7 +397,7 @@ function repoExtras (repo, keyHex) {
             <tr data-key=${`o${e.address}`} data-action="open-at"
                 data-keyhex=${keyHex} data-addr=${e.address}>
               <td class="mono dim">${e.codecType}</td>
-              <td>${(() => { try { return previewValue(repo.decode(e.address)) } catch { return '' } })()}</td>
+              <td>${(() => { try { return typedValue(repo.decode(e.address)) } catch { return '' } })()}</td>
               <td class="mono dim">@${e.address}</td>
             </tr>
           `)}
@@ -507,13 +497,13 @@ function AtView ({ keyHex, address }) {
                   return h`
                     <tr>
                       <td class="mono">${k}</td>
-                      <td>${previewValue(inlineValue)}</td>
+                      <td>${typedValue(inlineValue)}</td>
                       <td class="dim">(inline)</td>
                     </tr>
                   `
                 }
                 let preview = ''
-                try { preview = previewValue(repo.decode(childAddr)) }
+                try { preview = typedValue(repo.decode(childAddr)) }
                 catch { preview = '(error)' }
                 return h`
                   <tr data-key=${k} data-action="open-at"
@@ -605,8 +595,8 @@ function AtView ({ keyHex, address }) {
           </p>
           <table class="kv">
             <tbody>
-              <tr><td class="mono">v[0]</td><td>${previewValue(decoded.v[0])}</td></tr>
-              <tr><td class="mono">v[1]</td><td>${previewValue(decoded.v[1])}</td></tr>
+              <tr><td class="mono">v[0]</td><td>${typedValue(decoded.v[0])}</td></tr>
+              <tr><td class="mono">v[1]</td><td>${typedValue(decoded.v[1])}</td></tr>
             </tbody>
           </table>
         `
@@ -802,7 +792,7 @@ function outgoingReferencesSection (repo, keyHex, address) {
           try {
             const childCode = repo.resolve(childAddr)
             codecType = repo.footerToCodec[childCode.at(-1)]?.type || '?'
-            preview = previewValue(repo.decode(childAddr))
+            preview = typedValue(repo.decode(childAddr))
           } catch { preview = '(error)' }
           return h`
             <tr data-key=${`out${i}@${childAddr}`} data-action="open-at"
@@ -840,7 +830,7 @@ function referrersSection (repo, keyHex, address) {
       <tbody>
         ${refs.map(r => {
           let preview = ''
-          try { preview = previewValue(repo.decode(r.address)) }
+          try { preview = typedValue(repo.decode(r.address)) }
           catch { preview = '(error)' }
           return h`
             <tr data-key=${`r${r.address}`} data-action="open-at"
@@ -863,19 +853,44 @@ function isDuple (v) {
   return v && typeof v === 'object' && Array.isArray(v.v) && v.v.length === 2 && Object.keys(v).length === 1
 }
 
-function previewValue (v, depth = 0) {
-  if (v == null) return String(v)
-  if (typeof v === 'string') return v.length > 60 ? JSON.stringify(v.slice(0, 60)) + '…' : JSON.stringify(v)
-  if (typeof v === 'number' || typeof v === 'boolean') return String(v)
-  if (v instanceof Date) return v.toISOString()
-  if (v instanceof Uint8Array) return `Uint8Array(${v.length})`
+// Streamo-typed value renderer — every value gets a visual identity
+// matching its underlying codec, instead of being flattened through
+// JSON.stringify. Primitives render with type-specific styling
+// (string → quoted mono in green frame, date → <time> with calendar
+// chip, number → number chip, etc.); composites currently render as
+// count chips ({ N fields } / [ N elements ]) — depth-controlled
+// expansion is the next step in this thread (see THREADS.md).
+function typedValue (v, depth = 0) {
+  if (v === null) return h`<span class="tv tv-null">null</span>`
+  if (v === undefined) return h`<span class="tv tv-undefined">undefined</span>`
+  if (typeof v === 'boolean') {
+    return h`<span class=${['tv', 'tv-bool', v ? 'tv-true' : 'tv-false']}>${v ? '✓' : '✗'} ${String(v)}</span>`
+  }
+  if (typeof v === 'string') {
+    const display = v.length > 60 ? v.slice(0, 60) + '…' : v
+    return h`<span class="tv tv-string"><span class="tv-quote">“</span>${display}<span class="tv-quote">”</span></span>`
+  }
+  if (typeof v === 'number') {
+    return h`<span class="tv tv-num">${String(v)}</span>`
+  }
+  if (v instanceof Date) {
+    return h`<span class="tv tv-date"><span class="tv-glyph">📅</span><time datetime=${v.toISOString()}>${v.toLocaleString()}</time></span>`
+  }
+  if (v instanceof Uint8Array) {
+    return h`<span class="tv tv-bytes">Uint8Array(${v.length})</span>`
+  }
   if (isDuple(v)) {
-    if (depth > 2) return 'Duple(…)'
-    return `Duple(${previewValue(v.v[0], depth + 1)}, ${previewValue(v.v[1], depth + 1)})`
+    if (depth > 1) return h`<span class="tv tv-duple">Duple(…)</span>`
+    return h`<span class="tv tv-duple">Duple(${typedValue(v.v[0], depth + 1)}, ${typedValue(v.v[1], depth + 1)})</span>`
+  }
+  if (Array.isArray(v)) {
+    return h`<span class="tv tv-array">[ ${v.length} ${v.length === 1 ? 'element' : 'elements'} ]</span>`
+  }
+  if (typeof v === 'object') {
+    const n = Object.keys(v).length
+    return h`<span class="tv tv-object">{ ${n} ${n === 1 ? 'field' : 'fields'} }</span>`
   }
-  if (Array.isArray(v)) return `[…] (${v.length})`
-  if (typeof v === 'object') return `{…} (${Object.keys(v).length})`
-  return String(v)
+  return h`<span class="tv">${String(v)}</span>`
 }
 
 function safeGet (f) { try { return f() } catch { return undefined } }

package/public/streamo/bridgeRegistry.js

@@ -0,0 +1,64 @@
+/**
+ * @file bridgeRegistry — connect a multi-repo registry to an app Recaller.
+ *
+ * Each Repo has its own Recaller so it can track fine-grained dependencies
+ * on its own internal keys. An app that uses many Repos has its own
+ * different Recaller for its mount() slots. Reading repo.byteLength inside
+ * a slot registers a dep on the *repo's* recaller, not the app's, so
+ * without an explicit bridge the slot would never re-run when chunks
+ * arrive at the repo.
+ *
+ * bridgeRegistry sets up that bridge once: it watches every repo in the
+ * registry (existing and future) for chunk arrivals and forwards them as
+ * a single signal on the app recaller. The returned `dep` function is
+ * what slots call to register on that signal — call it inside any
+ * reactive cell that should re-run on any-repo-changed.
+ *
+ *   const recaller = new Recaller('app')
+ *   const { dep, fire } = bridgeRegistry(registry, recaller)
+ *
+ *   mount(h`${() => {
+ *     dep()
+ *     for (const [k, r] of registry) ...   // freely read any repo's state
+ *   }}`, appEl, recaller)
+ *
+ *   // Non-repo state changes (route, async results, etc.) — call fire()
+ *   // to force a re-render; the slot re-runs at next tick.
+ *   window.addEventListener('hashchange', fire)
+ *
+ * Mutation is synchronous so multiple mutations in a tick coalesce via the
+ * Recaller's own nextTick flush — one slot re-run per tick regardless of
+ * how many chunks arrive. Don't wrap fire() in requestAnimationFrame:
+ * when the tab loses focus, queued rAFs throttle and the display freezes
+ * (we learned this the hard way; see the design.md cross-recaller note).
+ *
+ * @param {import('./RepoRegistry.js').RepoRegistry} registry
+ * @param {import('./utils/Recaller.js').Recaller} recaller
+ * @param {string} [name='bridge']  used in watch names for debugging
+ * @returns {{dep: () => void, fire: () => void}}
+ *   `dep()` registers the calling reactive cell as depending on bridge state.
+ *   `fire()` forces the slot to re-run at next tick — useful for app-level
+ *   state changes (route, async results, tab switches) that aren't repo
+ *   mutations the bridge already forwards.
+ */
+export function bridgeRegistry (registry, recaller, name = 'bridge') {
+  const signal = {}
+  const watched = new Set()
+
+  const fire = () => recaller.reportKeyMutation(signal, 'data')
+  const dep  = () => recaller.reportKeyAccess(signal, 'data')
+
+  function watchRepo (keyHex, repo) {
+    if (watched.has(keyHex)) return
+    watched.add(keyHex)
+    repo.watch(`${name}:${keyHex}`, () => {
+      repo.byteLength  // register 'length' dep — fires on every chunk
+      fire()
+    })
+  }
+
+  for (const [k, r] of registry) watchRepo(k, r)
+  registry.onOpen((k, r) => { watchRepo(k, r); fire() })
+
+  return { dep, fire }
+}

package/public/streamo/mount.js

@@ -192,11 +192,30 @@ function reconcileSlot (start, end, newVNodes, recaller, ns = HTML_NS) {
     old.remove()
   }
 
-  // Reinsert recycled elements (static attrs patched) and mount fresh ones, in order
+  // Reinsert recycled elements and mount fresh ones, in order. For
+  // recycled elements we re-mount: clean up the existing subtree's
+  // watchers, clear inner DOM and any attributes set on the outer
+  // element, then apply fresh attrs and mount fresh children. The
+  // OUTER node identity is preserved (so document position and DOM
+  // references survive), but inner state (focus, scroll, slot
+  // anchors) is rebuilt — a static `${value}` child captured at
+  // first mount would otherwise be stale on every re-render.
+  // Inputs that need focus preservation across re-renders should
+  // be kept in their own data-keyed slot so reconcileSlot's matcher
+  // recycles them in place separately from this outer rebuild.
   for (const vnode of newVNodes) {
     const recycled = vnodeToEl.get(vnode)
     if (recycled) {
-      patchElement(recycled, vnode)
+      cleanupNode(recycled, recaller)
+      while (recycled.firstChild) recycled.firstChild.remove()
+      // Clear all attributes (snapshot the names — removeAttribute mutates the live list)
+      const oldAttrNames = Array.from(recycled.attributes, a => a.name)
+      for (const name of oldAttrNames) recycled.removeAttribute(name)
+      for (const attr of vnode.attrs) {
+        if (attr == null) continue
+        applyAttr(recycled, attr, recaller)
+      }
+      mount(vnode.children, recycled, recaller, ns)
       end.before(recycled)
     } else {
       const frag = document.createDocumentFragment()
@@ -206,18 +225,6 @@ function reconcileSlot (start, end, newVNodes, recaller, ns = HTML_NS) {
   }
 }
 
-// Update static attributes on a recycled element.
-// Reactive (function/array) attrs are already self-updating via their existing watchers.
-function patchElement (el, vnode) {
-  for (const attr of vnode.attrs) {
-    if (attr == null) continue
-    if (typeof attr === 'object' && !attr.name) continue // spread — skip
-    if (typeof attr.value === 'function' || Array.isArray(attr.value)) continue // reactive — skip
-    if (attr.value !== undefined) setAttr(el, attr.name, attr.value)
-    else el.toggleAttribute(attr.name, true)
-  }
-}
-
 // ── Function components ───────────────────────────────────────────────────
 //
 // When an HElement's tag is a function, call it with a props object instead