@dtudury/streamo 1.0.1 → 3.0.0

package/README.md

@@ -56,8 +56,7 @@ streamo --env-file .env
 ### Streamo — reactive append-only store
 
 ```js
-import { Streamo } from '@dtudury/streamo/public/streamo/Streamo.js'
-import { Recaller } from '@dtudury/streamo/public/streamo/utils/Recaller.js'
+import { Streamo } from '@dtudury/streamo'
 
 const store = new Streamo()
 store.set({ name: 'alice', score: 42 })
@@ -72,7 +71,7 @@ Values are encoded with a self-describing codec (strings, numbers, dates, boolea
 `Repo` wraps a `Streamo` so every `set()` becomes a commit — message, date, data address, and parent pointer. The raw commit log is what syncs over the wire.
 
 ```js
-import { Repo } from '@dtudury/streamo/public/streamo/Repo.js'
+import { Repo } from '@dtudury/streamo'
 
 const repo = new Repo()
 repo.attachSigner(signer, 'my-dataset')  // auto-sign every commit
@@ -87,8 +86,7 @@ Signature chunks travel in the byte stream automatically — peers running `regi
 ### Signer — deterministic identity
 
 ```js
-import { Signer } from '@dtudury/streamo/public/streamo/Signer.js'
-import { bytesToHex } from '@dtudury/streamo/public/streamo/utils.js'
+import { Signer, bytesToHex } from '@dtudury/streamo'
 
 const signer = new Signer('alice', 'my-password')
 const { publicKey } = await signer.keysFor('my-dataset')
@@ -100,8 +98,7 @@ Keys are derived with PBKDF2 so the same username + password always produces the
 ### RepoRegistry — multi-repo store
 
 ```js
-import { RepoRegistry } from '@dtudury/streamo/public/streamo/RepoRegistry.js'
-import { archiveSync } from '@dtudury/streamo/public/streamo/archiveSync.js'
+import { RepoRegistry, Repo, archiveSync } from '@dtudury/streamo'
 
 const registry = new RepoRegistry(async key => {
   const repo = new Repo()
@@ -115,7 +112,7 @@ const repo = await registry.open(publicKeyHex)
 ### registrySync — peer sync over WebSocket
 
 ```js
-import { registrySync } from '@dtudury/streamo/public/streamo/registrySync.js'
+import { registrySync } from '@dtudury/streamo'
 
 const session = await registrySync(registry, 'localhost', 8080, {
   // only sync repos you care about
@@ -137,9 +134,7 @@ session.announce(myKey, rootKey) // tell interested peers about your repo
 ### h + mount — reactive UI
 
 ```js
-import { h } from '@dtudury/streamo/public/streamo/h.js'
-import { mount } from '@dtudury/streamo/public/streamo/mount.js'
-import { Recaller } from '@dtudury/streamo/public/streamo/utils/Recaller.js'
+import { h, mount, Recaller } from '@dtudury/streamo'
 
 const recaller = new Recaller('app')
 
@@ -153,10 +148,13 @@ mount(h`
 
 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.
 
+> **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.
+
 Any function can be used directly as a tag — it receives `{ ...attrs, children }` and returns virtual nodes:
 
 ```js
-import { StreamoComponent, componentKey, defineComponent } from '@dtudury/streamo/public/streamo/StreamoComponent.js'
+// StreamoComponent extends HTMLElement, so it's only importable in a browser context:
+import { StreamoComponent, componentKey, defineComponent } from '@dtudury/streamo/StreamoComponent.js'
 
 function Card ({ title, children }) {
   return h`<div class="card"><h2>${title}</h2>${children}</div>`
@@ -179,17 +177,27 @@ 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
+## the all-in-one demo
+
+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:
 
 ```bash
-# start the server — its public key becomes the room key
+# start the all-in-one demo server
 STREAMO_NAME=my-chat STREAMO_USERNAME=relay STREAMO_PASSWORD=secret \
   node public/apps/chat/server.js
 
-# join from the browser
+# homepage with app cards
+open http://localhost:8080/
+
+# chat
 open http://localhost:8080/apps/chat/
 
-# join from the terminal
+# 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
 node public/streamo/chat-cli.js alice secret localhost 8080
 ```
 
@@ -198,7 +206,7 @@ Each participant owns their own message stream. The server is just another strea
 ## tests
 
 ```bash
-node --test                              # all tests
+npm test                                 # all tests
 node --test public/streamo/Repo.test.js  # single file
 ```
 

package/index.js

@@ -0,0 +1,32 @@
+// Public API. Most users want named imports from here:
+//
+//   import { Repo, Signer, registrySync } from '@dtudury/streamo'
+//
+// For advanced/internal use, subpath imports also work:
+//
+//   import { Recaller } from '@dtudury/streamo/utils/Recaller.js'
+//
+// StreamoComponent is intentionally NOT re-exported here: it extends
+// HTMLElement at module-load time and cannot be imported in Node. Browser
+// consumers should subpath-import it directly:
+//
+//   import { StreamoComponent, defineComponent } from '@dtudury/streamo/StreamoComponent.js'
+
+export { Streamo, ConflictError, changedPaths } from './public/streamo/Streamo.js'
+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 { registrySync, handleRegistryPeer } from './public/streamo/registrySync.js'
+export { archiveSync } from './public/streamo/archiveSync.js'
+export { fileSync } from './public/streamo/fileSync.js'
+export { originSync } from './public/streamo/originSync.js'
+export { outletSync, attachStreamSync } from './public/streamo/outletSync.js'
+export { s3Sync } from './public/streamo/s3Sync.js'
+export { stateFileSync } from './public/streamo/stateFileSync.js'
+export { webSync } from './public/streamo/webSync.js'
+export { StreamoServer } from './public/streamo/StreamoServer.js'
+export { h, HElement, HText } from './public/streamo/h.js'
+export { mount, dismount } from './public/streamo/mount.js'
+export { Recaller } from './public/streamo/utils/Recaller.js'
+export { bytesToHex, hexToBytes } from './public/streamo/utils.js'

package/package.json

@@ -1,15 +1,28 @@
 {
   "name": "@dtudury/streamo",
-  "version": "1.0.1",
+  "version": "3.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",
   "author": "David Tudury <david.tudury@gmail.com>",
   "license": "AGPL-3.0-only",
+  "type": "module",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js",
+    "./*": "./public/streamo/*"
+  },
+  "files": [
+    "index.js",
+    "bin/",
+    "public/",
+    "!**/*.test.js",
+    "!public/streamo/utils/testing.js",
+    "!public/streamo/utils/mockDOM.js"
+  ],
   "bin": {
     "streamo": "./bin/streamo.js"
   },
-  "type": "module",
   "dependencies": {
     "@aws-sdk/client-s3": "^3.958.0",
     "@gerhobbelt/gitignore-parser": "^0.2.0-9",
@@ -22,6 +35,7 @@
     "ws": "^8.18.3"
   },
   "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"
   }

package/public/apps/explorer/index.html

@@ -0,0 +1,118 @@
+<!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; }
+
+    /* 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; }
+
+    .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); }
+
+    .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; }
+
+    .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; }
+
+    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>