@bitpub/cli 2.0.5 → 2.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitpub/cli",
-  "version": "2.0.5",
+  "version": "2.1.1",
   "description": "BitPub CLI — local-first shared memory for AI agents. Six daily verbs (save/load/list/find/sync/delete), zero-config private namespace, encrypted client-side.",
   "bin": {
     "bitpub": "./bin/bitpub.js"

package/src/commands/browser.js

@@ -17,7 +17,7 @@ const http = require('http');
 const path = require('path');
 const fs = require('fs');
 const os = require('os');
-const { exec } = require('child_process');
+const { exec, spawn } = require('child_process');
 const { readConfig, BITPUB_DIR } = require('../config');
 const { getSyncedNamespaces, initCache } = require('../db/cache');
 const { isPrivateHcu, decrypt, isEncrypted } = require('../crypto');
@@ -108,6 +108,396 @@ const ASSET_MIME = {
   '.webm': 'video/webm',
 };
 
+/* ── Bridge (apps → local CLI) ──────────────────────────────────────
+ *
+ * Sandboxed app iframes (default-src 'none', no allow-same-origin)
+ * cannot fetch, but they CAN postMessage to the parent window. The
+ * parent is the BitPub Browser shell; it forwards approved calls to
+ * this CLI process, which spawns a child and streams stdout/stderr
+ * back over Server-Sent Events.
+ *
+ * Security floor for v1:
+ *   - Only functions listed in FUNCTIONS are runnable. Apps cannot
+ *     execute arbitrary shell.
+ *   - Arguments are typed and validated per function — no string
+ *     interpolation into the shell.
+ *   - The HTTP server binds to localhost only (default port 4141),
+ *     so the surface is the same trust boundary as the CLI itself:
+ *     anyone with shell access already has more power than the bridge.
+ *   - The next layer (permission grants per app + audit log) is a
+ *     console.html responsibility, not the CLI's.
+ *
+ * Functions in v1 are hardcoded here. The end state — functions
+ * resolved from slices, e.g. bitpub://group:tollbit.com/Functions/<id>
+ * — needs the same permission UX and a small sandbox for the script,
+ * so we ship the registry shape first and back-fill the resolver.
+ */
+const FUNCTIONS = {
+  'granola.ingest': {
+    description: 'Pull new Granola meetings into your private namespace.',
+    build(args) {
+      const limit = clampInt(args && args.limit, 1, 200, 5);
+      const script =
+        'set -e; ' +
+        'bitpub load bitpub://group:tollbit.com/Agents/granola-ingest/script > "$T" && ' +
+        `python3 "$T" --limit ${limit}`;
+      return {
+        cmd: 'bash',
+        args: ['-lc', script],
+        env: { T: path.join(os.tmpdir(), `.bitpub-fn-granola-ingest.py`) },
+      };
+    },
+  },
+
+  // Orchestration script for sales_brief.generate lives as a slice at
+  // bitpub://private:.../Apps/sales-brief-generator/orchestrator so the
+  // logic can be iterated without restarting the CLI. The function below
+  // is the thin entry point that loads + runs it.
+  'sales_brief.generate': {
+    description: 'Synthesize a bespoke sales brief PDF from selected call transcripts.',
+    build(args) {
+      const a = args || {};
+      const transcriptHcus = Array.isArray(a.transcript_hcus) ? a.transcript_hcus.slice(0, 25) : [];
+      const template = String(a.template || 'discovery').slice(0, 32).replace(/[^a-z_]/gi, '');
+      const customer = String(a.customer || '').slice(0, 120);
+      const dealStage = String(a.deal_stage || '').slice(0, 80);
+      const extraNotes = String(a.extra_notes || '').slice(0, 2000);
+      const outputDir = path.join(os.homedir(), 'Downloads', 'Briefs');
+
+      if (transcriptHcus.length === 0) {
+        throw new Error('no transcripts selected');
+      }
+
+      const payload = JSON.stringify({
+        transcript_hcus: transcriptHcus,
+        template,
+        customer,
+        deal_stage: dealStage,
+        extra_notes: extraNotes,
+        output_dir: outputDir,
+      });
+
+      const script =
+        'set -e; ' +
+        'bitpub load bitpub://private:agent_ewim9gf01nq3/Apps/sales-brief-generator/orchestrator > "$ORCH" && ' +
+        'python3 "$ORCH"';
+
+      return {
+        cmd: 'bash',
+        args: ['-lc', script],
+        env: {
+          ORCH: path.join(os.tmpdir(), '.bitpub-fn-sales-brief.py'),
+          BRIEF_PAYLOAD: payload,
+        },
+      };
+    },
+  },
+
+  'sales_brief.open': {
+    description: 'Open a generated PDF in the default viewer.',
+    build(args) {
+      const p = String((args && args.path) || '');
+      if (!p || !p.startsWith('/') || p.includes('"')) throw new Error('invalid path');
+      return { cmd: 'bash', args: ['-lc', `open "${p}"`] };
+    },
+  },
+
+  'sales_brief.reveal': {
+    description: 'Reveal a generated PDF in Finder.',
+    build(args) {
+      const p = String((args && args.path) || '');
+      if (!p || !p.startsWith('/') || p.includes('"')) throw new Error('invalid path');
+      return { cmd: 'bash', args: ['-lc', `open -R "${p}"`] };
+    },
+  },
+
+  // ── GitHub Pack ────────────────────────────────────────────
+  // The orchestrator slice lives at a GROUP address so every teammate
+  // in the group can load the same logic — they don't fork it. Each
+  // entry point injects BITPUB_OWNER from local config so the script
+  // writes to *the running user's* private namespace, not the author's.
+  //
+  // Auth model: orchestrator probes (1) macOS keychain entry from
+  // GitHub Desktop, (2) gh CLI, (3) BitPub-managed token. Tokens are
+  // never passed through args/URLs — child reads them itself so
+  // secrets never traverse the bridge.
+
+  'github.check_auth': {
+    description: 'Detect available GitHub credentials (Desktop keychain, gh CLI, BitPub-managed token).',
+    build() {
+      return {
+        cmd: 'bash',
+        args: ['-lc',
+          'set -e; ' +
+          'bitpub load bitpub://group:tollbit.com/Apps/github/orchestrator > "$T" && ' +
+          'python3 "$T"',
+        ],
+        env: {
+          T: path.join(os.tmpdir(), '.bitpub-fn-github-authcheck.py'),
+          BITPUB_GH_ACTION: 'auth_check',
+          BITPUB_OWNER: (readConfig() || {}).owner || '',
+        },
+      };
+    },
+  },
+
+  'github.ingest': {
+    description: 'Mirror your GitHub PRs, issues, and recent activity into your namespace.',
+    build(args) {
+      const a = args || {};
+      const recipes = Array.isArray(a.recipes) && a.recipes.length
+        ? a.recipes.filter(r => typeof r === 'string' && /^[a-z_]+$/.test(r)).slice(0, 8)
+        : ['prs_review_requested', 'prs_mine', 'prs_org_recent', 'issues_assigned', 'activity_recent'];
+      return {
+        cmd: 'bash',
+        args: ['-lc',
+          'set -e; ' +
+          'bitpub load bitpub://group:tollbit.com/Apps/github/orchestrator > "$T" && ' +
+          'python3 "$T"',
+        ],
+        env: {
+          T: path.join(os.tmpdir(), '.bitpub-fn-github-ingest.py'),
+          BITPUB_GH_RECIPES: recipes.join(','),
+          BITPUB_OWNER: (readConfig() || {}).owner || '',
+        },
+      };
+    },
+  },
+
+  'github.open': {
+    description: 'Open a GitHub URL in the default browser.',
+    build(args) {
+      const url = String((args && args.url) || '');
+      if (!/^https:\/\/github\.com\//.test(url) || url.includes('"')) {
+        throw new Error('invalid github url');
+      }
+      return { cmd: 'bash', args: ['-lc', `open "${url}"`] };
+    },
+  },
+
+  'github.open_clone': {
+    description: 'Open a repo\'s local clone in Finder (or VS Code if "in" === "vscode").',
+    build(args) {
+      const repo = String((args && args.repo) || '');
+      const where = String((args && args.in) || 'finder');
+      if (!/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/.test(repo)) {
+        throw new Error('invalid repo "owner/name"');
+      }
+      const opener = where === 'vscode' ? 'code' :
+                     where === 'iterm'  ? `open -a iTerm` :
+                                          'open';
+      // Search common project roots for a directory whose `git remote -v`
+      // points at this repo. Local-first move: we surface the user's
+      // clone if they have one, instead of dumping them at github.com.
+      const script = `
+set -e
+REPO='${repo}'
+ROOTS=(~/projects ~/code ~/dev ~/src ~/Documents/projects ~/work)
+for root in "\${ROOTS[@]}"; do
+  [ -d "$root" ] || continue
+  while IFS= read -r dir; do
+    if (cd "$dir" && git remote -v 2>/dev/null) | grep -qiE "[:/]\${REPO}(\\.git)?( |\\\$)"; then
+      echo "found clone: $dir"
+      ${opener} "$dir"
+      exit 0
+    fi
+  done < <(find "$root" -mindepth 1 -maxdepth 3 -type d -name .git -prune -exec dirname {} \\; 2>/dev/null)
+done
+echo "no local clone of $REPO found in common roots — opening on github.com instead"
+open "https://github.com/$REPO"
+`;
+      return { cmd: 'bash', args: ['-lc', script] };
+    },
+  },
+
+  'github.summarize_pr': {
+    description: 'Summarize a PR with claude (the only LLM-in-the-loop step).',
+    build(args) {
+      const hcu = String((args && args.hcu) || '');
+      // Any private namespace, as long as it's pointed at GitHub/PRs/.
+      // We constrain the shape so an app can't trick the bridge into
+      // pulling arbitrary slices through claude.
+      if (!/^bitpub:\/\/private:[a-z0-9_-]+\/GitHub\/PRs\//i.test(hcu) || hcu.includes('"')) {
+        throw new Error('invalid PR hcu');
+      }
+      // Deterministic read (bitpub load) -> single LLM call (claude -p) ->
+      // structured text back to the UI. No MCP, no network round-trip for
+      // the data — only for the synthesis.
+      const script =
+        'set -e; ' +
+        `bitpub load "${hcu}" > "$T" && ` +
+        'claude -p "$(printf \'%s\\n\\nSummarize this GitHub PR in 3 short bullets: what it does, who it affects, anything risky. Be concrete.\' "$(cat "$T")")" ' +
+        '--output-format text --permission-mode bypassPermissions';
+      return {
+        cmd: 'bash',
+        args: ['-lc', script],
+        env: { T: path.join(os.tmpdir(), `.bitpub-fn-github-summarize.md`) },
+      };
+    },
+  },
+
+  'github.action.approve': {
+    description: 'Approve a pull request via the GitHub API (uses inherited credentials).',
+    build(args) {
+      const repo   = String((args && args.repo) || '');
+      const number = parseInt((args && args.number), 10);
+      const body   = String((args && args.body) || '');
+      if (!/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/.test(repo)) throw new Error('invalid repo');
+      if (!Number.isFinite(number) || number <= 0) throw new Error('invalid PR number');
+      return {
+        cmd: 'bash',
+        args: ['-lc',
+          'set -e; ' +
+          'bitpub load bitpub://group:tollbit.com/Apps/github/orchestrator > "$T" && ' +
+          'python3 "$T"',
+        ],
+        env: {
+          T: path.join(os.tmpdir(), '.bitpub-fn-github-action.py'),
+          BITPUB_GH_ACTION: 'approve',
+          BITPUB_GH_REPO: repo,
+          BITPUB_GH_PR: String(number),
+          BITPUB_GH_BODY: body,
+          BITPUB_OWNER: (readConfig() || {}).owner || '',
+        },
+      };
+    },
+  },
+};
+
+function clampInt(value, lo, hi, dflt) {
+  const n = parseInt(value, 10);
+  if (!Number.isFinite(n)) return dflt;
+  return Math.max(lo, Math.min(hi, n));
+}
+
+/**
+ * Test whether an HCU matches a simple prefix pattern.
+ *
+ * Two pattern shapes are supported, which is enough for the
+ * "deterministic read against a namespace folder" idiom that apps use:
+ *
+ *   - exact:  bitpub://private:tp/Apps/foo
+ *   - prefix: bitpub://private:tp/Transcripts/Raw/*
+ *
+ * The trailing `/*` means "any direct or transitive descendant," which
+ * matches how `bitpub list <folder>` already behaves and what apps want
+ * when they say "give me all my transcripts."
+ */
+function hcuMatchesPattern(hcu, pattern) {
+  if (!hcu || !pattern) return false;
+  if (pattern.endsWith('/*')) {
+    return hcu.startsWith(pattern.slice(0, -2) + '/') || hcu === pattern.slice(0, -2);
+  }
+  return hcu === pattern;
+}
+
+/* Compact list of functions for the bridge router to advertise. */
+function listFunctions() {
+  return Object.entries(FUNCTIONS).map(([id, fn]) => ({
+    id,
+    description: fn.description,
+  }));
+}
+
+/**
+ * Stream a function execution to the response as an SSE stream.
+ *
+ * Wire format:
+ *   event: started   data: { functionId }
+ *   event: stdout    data: { line }
+ *   event: stderr    data: { line }
+ *   event: error     data: { message }
+ *   event: exit      data: { code }      ← terminal; connection closes
+ *
+ * Lines are flushed by newline so the UI shows progress as it happens
+ * instead of waiting for the whole stdout buffer to drain at exit.
+ */
+function handleBridgeRun(req, res, url) {
+  const functionId = url.searchParams.get('functionId') || '';
+  const argsParam = url.searchParams.get('args') || '{}';
+  let args = {};
+  try { args = JSON.parse(argsParam); } catch { /* ignore — treat as no args */ }
+
+  const fn = FUNCTIONS[functionId];
+  if (!fn) {
+    res.statusCode = 404;
+    res.setHeader('Content-Type', 'application/json');
+    res.end(JSON.stringify({ error: 'unknown_function', functionId }));
+    return;
+  }
+
+  res.statusCode = 200;
+  res.setHeader('Content-Type', 'text/event-stream');
+  res.setHeader('Cache-Control', 'no-cache, no-transform');
+  res.setHeader('Connection', 'keep-alive');
+  // Defeat any reverse-proxy buffering between us and the parent.
+  res.setHeader('X-Accel-Buffering', 'no');
+
+  function send(event, payload) {
+    if (res.writableEnded) return;
+    res.write(`event: ${event}\n`);
+    res.write(`data: ${JSON.stringify(payload)}\n\n`);
+  }
+
+  send('started', { functionId });
+
+  let spec;
+  try {
+    spec = fn.build(args || {});
+  } catch (err) {
+    send('error', { message: `bad arguments: ${err.message}` });
+    send('exit', { code: 2 });
+    res.end();
+    return;
+  }
+
+  let child;
+  try {
+    child = spawn(spec.cmd, spec.args, {
+      env: { ...process.env, ...(spec.env || {}) },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch (err) {
+    send('error', { message: `spawn failed: ${err.message}` });
+    send('exit', { code: 1 });
+    res.end();
+    return;
+  }
+
+  // Buffer per-stream so we can emit one event per line — keeps the
+  // log readable and avoids splitting multi-byte UTF-8 sequences.
+  function lineSink(streamName) {
+    let buf = '';
+    return (chunk) => {
+      buf += chunk.toString('utf-8');
+      let i;
+      while ((i = buf.indexOf('\n')) >= 0) {
+        const line = buf.slice(0, i).replace(/\r$/, '');
+        buf = buf.slice(i + 1);
+        send(streamName, { line });
+      }
+    };
+  }
+  child.stdout.on('data', lineSink('stdout'));
+  child.stderr.on('data', lineSink('stderr'));
+
+  child.on('error', (err) => {
+    send('error', { message: err.message });
+  });
+
+  child.on('close', (code) => {
+    send('exit', { code });
+    res.end();
+  });
+
+  // If the parent navigates away or the user cancels, reap the child.
+  req.on('close', () => {
+    if (child && !child.killed) {
+      try { child.kill('SIGTERM'); } catch { /* already gone */ }
+    }
+  });
+}
+
 function openInBrowser(url) {
   const cmd = process.platform === 'darwin' ? 'open' :
     process.platform === 'win32' ? 'start' : 'xdg-open';
@@ -177,6 +567,86 @@ function startBrowserServer(opts = {}) {
         return;
       }
 
+      // Bridge: who is this BitPub installation? Apps that ship via a
+      // group/public namespace can't hardcode an owner ID — they need to
+      // know "what is the current user's private prefix" at runtime so
+      // their namespace.list() / save() calls hit the right cache.
+      // Returns the minimum info needed: owner id, the domain (for
+      // display), and the canonical private namespace prefix.
+      if (url.pathname === '/bridge/identity') {
+        res.setHeader('Content-Type', 'application/json');
+        const owner = (cfg && cfg.owner) || null;
+        const domain = (cfg && cfg.domain) || null;
+        res.end(JSON.stringify({
+          owner,
+          domain,
+          private_prefix: owner ? `bitpub://private:${owner}` : null,
+        }));
+        return;
+      }
+
+      // Bridge: list registered functions (for the permission UI to
+      // describe what an app is about to run).
+      if (url.pathname === '/bridge/functions') {
+        res.setHeader('Content-Type', 'application/json');
+        res.end(JSON.stringify({ functions: listFunctions() }));
+        return;
+      }
+
+      // Bridge: stream a function execution to the console as SSE.
+      // Console.html forwards the events back to the requesting app
+      // iframe via postMessage. See FUNCTIONS above for the registry.
+      if (url.pathname === '/bridge/run') {
+        handleBridgeRun(req, res, url);
+        return;
+      }
+
+      // Bridge: deterministic namespace read. Apps call this to fetch
+      // any slices that match an HCU pattern (exact or prefix-with-/*).
+      // No LLM, no MCP, no auth in the loop — this is the read path
+      // that the ingest/read split makes free. Returns full decrypted
+      // payload + metadata for each matching slice, capped to a sane
+      // limit so a runaway pattern doesn't ship the whole cache.
+      if (url.pathname === '/bridge/namespace/list') {
+        res.setHeader('Content-Type', 'application/json');
+        const pattern = url.searchParams.get('pattern') || '';
+        const limit = clampInt(url.searchParams.get('limit'), 1, 1000, 200);
+        const fields = (url.searchParams.get('fields') || 'preview').toLowerCase();
+        if (!pattern || !/^bitpub:\/\//.test(pattern)) {
+          res.statusCode = 400;
+          res.end(JSON.stringify({ error: 'bad_pattern', pattern }));
+          return;
+        }
+        const matched = [];
+        for (const raw of getAllSlices()) {
+          if (!hcuMatchesPattern(raw.hcu, pattern)) continue;
+          const slice = (cfg && cfg.api_key) ? decryptSlice(raw, cfg.api_key) : raw;
+          let content = '';
+          try {
+            const payload = typeof slice.payload === 'string' ? JSON.parse(slice.payload) : slice.payload;
+            content = (payload && typeof payload.content === 'string') ? payload.content : '';
+          } catch { /* leave content blank if payload is malformed */ }
+          const item = {
+            hcu: slice.hcu,
+            version: slice.version,
+            last_synced: slice.last_synced,
+            author: slice.author,
+            byte_size: content.length,
+          };
+          if (fields === 'full') {
+            item.content = content;
+          } else {
+            // 'preview' = first 480 chars, lets the picker render a
+            // useful snippet without shipping every transcript body.
+            item.preview = content.slice(0, 480);
+          }
+          matched.push(item);
+          if (matched.length >= limit) break;
+        }
+        res.end(JSON.stringify({ pattern, count: matched.length, slices: matched }));
+        return;
+      }
+
       if (url.pathname === '/' || url.pathname === '/index.html') {
         res.setHeader('Content-Type', 'text/html; charset=utf-8');
         res.end(loadHtml());

package/static/console.html

@@ -473,7 +473,11 @@ svg { flex-shrink: 0; }
 .file-row .f-when { font-size: 11px; color: var(--text-subtle); white-space: nowrap; font-variant-numeric: tabular-nums; }
 
 /* ── Slice panel (blob) ─────────────────────────────── */
-.blob-wrap { }
+/* Slice-view wrapper. Slimmer top/bottom padding than the default
+ * .panel so the framed content (especially app iframes) sits closer
+ * to both edges of the main area. Top and bottom padding are kept
+ * equal so the visible margins around the framed window match. */
+.blob-wrap { padding-top: 12px; padding-bottom: 12px; }
 .blob-meta { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; padding: 0 2px 12px; font-size: 12px; color: var(--text-muted); }
 .blob-meta .sep { color: var(--border-strong); }
 
@@ -490,7 +494,28 @@ svg { flex-shrink: 0; }
 .encrypted-note svg { color: var(--scope-private); }
 .encrypted-note code { font-family: var(--mono); font-size: 12px; background: var(--bg-card); padding: 1px 5px; border-radius: 3px; border: 1px solid var(--border); }
 
-.blob-container { background: var(--bg-card); border: 1px solid var(--border); border-radius: var(--radius); overflow: hidden; }
+/* Blob container — acts as a "browser window" framing whatever's
+ * inside (markdown / source / sandboxed iframe). For app slices we
+ * add .is-app so the container stretches to claim most of the viewport
+ * and reads like a real OS window. For markdown/raw content the
+ * container hugs its content as before. */
+.blob-container {
+  background: var(--bg-card);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  overflow: hidden;
+  display: flex; flex-direction: column;
+  box-shadow: 0 1px 2px rgba(20,20,20,.03), 0 6px 16px rgba(20,20,20,.04);
+}
+/* Container height math (so top/bottom margins around the iframe
+ * read as symmetric): viewport - (addressbar 52 + snapshot-banner ~38
+ * + 12 top pad + 12 bottom pad + ~6 safety) ≈ viewport - 120. The
+ * safety pixels prevent the page from showing a scrollbar when the
+ * snapshot-banner wraps to a second line on narrow widths. */
+.blob-container.is-app { min-height: calc(100vh - 120px); }
+.blob-container.is-app > .app-frame,
+.blob-container.is-app > .content-body,
+.blob-container.is-app > .content-raw { flex: 1; min-height: 0; }
 .blob-toolbar { padding: 8px 12px; background: var(--bg-canvas); border-bottom: 1px solid var(--border); display: flex; align-items: center; gap: 8px; flex-wrap: wrap; }
 .blob-toolbar .info { font-size: 11px; color: var(--text-subtle); font-variant-numeric: tabular-nums; }
 .blob-toolbar .spacer { flex: 1; }
@@ -743,9 +768,14 @@ svg { flex-shrink: 0; }
 }
 .cell-state.deleted .pip { background: #b91c1c; text-decoration: none; }
 
-/* ── Snapshot banner (slice view) ───────────────────── */
+/* ── Snapshot banner (slice view) ─────────────────────
+ *   Acts as the "title bar" above the content/iframe. Carries the
+ *   "Latest value v#" label plus the consolidated identity chips
+ *   (scope, mutability, last-write freshness, author, tags) that used
+ *   to live in a separate row. Reads as one strip on top of the
+ *   browser-window-style container below. */
 .snapshot-banner {
-  display: flex; align-items: center; gap: 10px;
+  display: flex; align-items: center; gap: 8px;
   padding: 9px 14px;
   background: var(--bg-canvas);
   border: 1px solid var(--border);
@@ -756,8 +786,12 @@ svg { flex-shrink: 0; }
 }
 .snapshot-banner .title { color: var(--text); font-weight: 600; letter-spacing: -.005em; }
 .snapshot-banner .ver { font-family: var(--mono); color: var(--text-muted); }
-.snapshot-banner .caveat { margin-left: auto; font-size: 11px; color: var(--text-subtle); display: inline-flex; align-items: center; gap: 5px; }
-.snapshot-banner .caveat svg { color: var(--text-subtle); }
+.snapshot-banner .meta-text { color: var(--text-muted); }
+.snapshot-banner .sep { color: var(--border-strong); }
+.snapshot-banner .scope-pill,
+.snapshot-banner .cell-state,
+.snapshot-banner .agent-chip,
+.snapshot-banner .pill { flex-shrink: 0; }
 .blob-container.has-banner { border-top-left-radius: 0; border-top-right-radius: 0; }
 
 /* ── Write guide (slice view) ───────────────────────── */
@@ -835,9 +869,14 @@ svg { flex-shrink: 0; }
    frame fills the blob container's horizontal space and grows to a
    workable default height (the app can be taller; the user scrolls
    the main pane to follow). */
+/* The iframe itself stretches to fill its (flex-sized) parent. The
+ * parent .blob-container's min-height drives the visible size, so this
+ * just makes sure the iframe occupies it fully and a long app scrolls
+ * inside the frame rather than expanding the outer page. */
 .app-frame {
   display: block;
   width: 100%;
+  flex: 1;
   min-height: 480px;
   border: 0;
   background: var(--bg-page);
@@ -1176,20 +1215,41 @@ async function pollData() {
     const k = s.hcu + '|' + (s.last_synced || '');
     if (!oldKey.has(k)) arrivals.add(s.hcu);
   }
+
+  // Nothing changed → skip the re-render entirely. Previously we
+  // unconditionally called renderAll() every 30s, which tore down and
+  // rebuilt the main pane — including any sandboxed iframe and the
+  // state inside it (live bridge runs, scroll position, form input).
+  if (arrivals.size === 0) {
+    // Boot-race recovery still needs to fire on every tick: if the
+    // welcome slice appears via some other path, navigate to it.
+    maybeOpenWelcomeSlice();
+    return;
+  }
+
   S.slices = nextSlices;
   S.mode = data.mode || S.mode;
   S.tree = buildTree(S.slices);
   S.stats = computeStats(S.slices);
   S.lastUpdated = maxTs(S.slices);
-  if (arrivals.size) {
-    S.newArrivals = arrivals;
-    triggerLivePulse();
-    setTimeout(() => { S.newArrivals = new Set(); }, 2500);
-  }
-  // Boot-race recovery: if install.sh opened us with ?welcome=1 before
-  // the welcome push had synced down, the slice may show up here on the
-  // first poll. Take the user to it as soon as it appears.
+  S.newArrivals = arrivals;
+  triggerLivePulse();
+  setTimeout(() => { S.newArrivals = new Set(); }, 2500);
   maybeOpenWelcomeSlice();
+
+  // If we're currently viewing a slice and *that* slice didn't change,
+  // only refresh the surrounding chrome (sidebar tree, address bar).
+  // The main pane (which holds the iframe) is left alone so the app
+  // keeps its DOM and runtime state.
+  const viewedSliceChanged = S.view === 'slice' && S.selectedHcu && arrivals.has(S.selectedHcu);
+  if (S.view === 'slice' && !viewedSliceChanged) {
+    renderModeBadge();
+    renderAddress();
+    renderTree();
+    $('clear-filter-btn').classList.toggle('hidden', !filterActive());
+    return;
+  }
+
   renderAll();
 }
 
@@ -1553,8 +1613,18 @@ function renderBranch(scope, children, path) {
 
   let html = '';
 
-  // Aggregated direct-leaf entry for this level
-  if (directLeaves.length > 0) {
+  // Direct leaves: render by name when small enough to be useful as a
+  // package contents listing (e.g. an Apps/github folder showing its
+  // `orchestrator` child by name). Aggregate into a single "N context
+  // slices" summary above a threshold so very large folders (282
+  // transcripts, hundreds of PRs) don't blow up the tree.
+  const LEAF_NAME_THRESHOLD = 8;
+  if (directLeaves.length > 0 && directLeaves.length <= LEAF_NAME_THRESHOLD) {
+    const sorted = [...directLeaves].sort((a, b) => a.name.localeCompare(b.name));
+    for (const { name, slice } of sorted) {
+      html += renderLeaf(slice, name);
+    }
+  } else if (directLeaves.length > LEAF_NAME_THRESHOLD) {
     const mostRecent = directLeaves.reduce(
       (a, b) => ((a.slice.last_synced || '') > (b.slice.last_synced || '') ? a : b)
     );
@@ -1563,7 +1633,11 @@ function renderBranch(scope, children, path) {
     const pathArg = JSON.stringify(path).replace(/"/g, '&quot;');
     const isActiveSummary = S.view === 'namespace' && S.currentScope === scope && arrayEq(S.currentPath, path);
     const when = mostRecent.slice.last_synced ? timeAgo(mostRecent.slice.last_synced) : '';
-    html += `<div class="tree-leaf tree-summary${isActiveSummary ? ' active' : ''}" onclick="navigateTo('${escAttr(scope)}', ${pathArg})" title="View ${directLeaves.length} slice${directLeaves.length !== 1 ? 's' : ''} at this level">
+    // Aggregated summary goes to the namespace listing (not the self-slice).
+    // Calls navigateToNamespace to bypass the directory-index resolution in
+    // navigateTo() — clicking "47 PRs" should show the listing, not whatever
+    // happens to live at the parent address.
+    html += `<div class="tree-leaf tree-summary${isActiveSummary ? ' active' : ''}" onclick="navigateToNamespace('${escAttr(scope)}', ${pathArg})" title="View ${directLeaves.length} slice${directLeaves.length !== 1 ? 's' : ''} at this level">
       <span class="fresh-dot ${freshClass}"></span>
       <span class="tree-label">${directLeaves.length} context slice${directLeaves.length !== 1 ? 's' : ''}</span>
       <span class="tree-badge">${esc(when)}</span>
@@ -1874,6 +1948,24 @@ function goRoot() {
 }
 
 function navigateTo(scope, path) {
+  const segs = Array.isArray(path) ? path : [];
+  // Directory-index semantics: if a slice exists AT this folder address
+  // (e.g. an HTML app at `Apps/github` that also has `Apps/github/orchestrator`
+  // as a child), render the slice as the primary view — same as a
+  // browser serving /foo/index.html when you visit /foo/. Children stay
+  // reachable via the tree chevron and named-leaf entries underneath.
+  const selfHcu = `bitpub://${scope}` + (segs.length ? '/' + segs.join('/') : '');
+  const self = S.slices.find(s => s.hcu === selfHcu);
+  if (self) { selectSlice(selfHcu); return; }
+
+  navigateToNamespace(scope, segs);
+}
+
+// Explicit "show me the folder listing" navigation. Used by the
+// aggregated "N context slices" summary in the tree, and anywhere
+// else we want to skip the directory-index check (e.g. "see all in
+// this namespace" links).
+function navigateToNamespace(scope, path) {
   S.view = 'namespace';
   S.currentScope = scope;
   S.currentPath = Array.isArray(path) ? path : [];
@@ -2334,25 +2426,11 @@ function renderSlice(sl) {
   //  same info is now shown in the address bar at the top of the window
   //  — keeping it in the panel was redundant.)
 
-  // Meta strip — identity + mutability signal
-  html += '<div class="blob-meta">';
-  html += renderScopePill(type, scope);
-  html += renderCellState(sl);
-  html += `<span class="fresh-dot ${freshClass}" title="${fresh}" style="width:7px;height:7px"></span><span>last write ${sl.last_synced ? timeAgo(sl.last_synced) : '—'}</span>`;
-  html += `<span class="sep">·</span>`;
-  html += `<span>by</span> ${renderAgentChip(author)}`;
-  if (tags.length) {
-    html += `<span class="sep">·</span>`;
-    for (const t of tags) {
-      const active = S.filter.tags.has(t);
-      html += `<span class="pill tag${active ? ' active' : ''}" onclick="toggleTag('${escAttr(t)}')">${esc(t)}${active ? '<span class="x">×</span>' : ''}</span>`;
-    }
-  }
-  html += '</div>';
-
-  // Write-guide + neighbors surfaced above the content so they're visible
-  // without scrolling — long slices can push them far offscreen otherwise.
-  html += renderWriteGuide(sl);
+  // Sibling navigation still goes above the content. The write-guide
+  // (push/append/safe-write CLI snippets) is intentionally hidden in
+  // this view — it's geek-only and the non-technical audience doesn't
+  // need to see CLI invocations next to their app. A future "developer
+  // mode" toggle can bring it back behind an opt-in.
   html += renderSiblingsPanel(sl);
 
   // Encrypted note when remote + private
@@ -2362,11 +2440,26 @@ function renderSlice(sl) {
     </div>`;
   }
 
-  // Snapshot banner — reminds this is the current value, not a finished doc
-  html += `<div class="snapshot-banner" style="margin-top:${isEncryptedRemote ? '0' : '16px'}">
+  // Snapshot banner — now also carries the identity/mutability chips
+  // that used to live in a separate `.blob-meta` row above. Consolidating
+  // saves a row and reads as one continuous strip above the iframe,
+  // closer to a browser-tab metadata bar than two stacked headers.
+  const tagsHtml = tags.map(t => {
+    const active = S.filter.tags.has(t);
+    return `<span class="pill tag${active ? ' active' : ''}" onclick="toggleTag('${escAttr(t)}')">${esc(t)}${active ? '<span class="x">×</span>' : ''}</span>`;
+  }).join('');
+  html += `<div class="snapshot-banner" style="margin-top:${isEncryptedRemote ? '0' : '12px'}">
     <span class="title">Latest value</span>
     <span class="ver">v${ver}</span>
-    <span class="caveat">${ICON.info}<span>Next push to this address replaces this slice in place.</span></span>
+    <span class="sep">·</span>
+    ${renderScopePill(type, scope)}
+    ${renderCellState(sl)}
+    <span class="sep">·</span>
+    <span class="fresh-dot ${freshClass}" title="${fresh}" style="width:7px;height:7px"></span>
+    <span class="meta-text">last write ${sl.last_synced ? timeAgo(sl.last_synced) : '—'}</span>
+    <span class="sep">·</span>
+    <span class="meta-text">by</span> ${renderAgentChip(author)}
+    ${tagsHtml ? '<span class="sep">·</span>' + tagsHtml : ''}
   </div>`;
 
   // Content-type dispatcher. The payload's declared format is the
@@ -2379,7 +2472,7 @@ function renderSlice(sl) {
   // the v1 cut from product discussion.
   const canRenderAsApp = kind === 'html' && (type === 'private' || type === 'group');
 
-  html += '<div class="blob-container has-banner">';
+  html += `<div class="blob-container has-banner${canRenderAsApp ? ' is-app' : ''}">`;
   html += '<div class="blob-toolbar">';
   html += '<div class="btn-group">';
   const previewLabel = canRenderAsApp ? 'App' : 'Preview';
@@ -2454,14 +2547,22 @@ function detectContentKind(sl, content) {
  *   - referrerpolicy="no-referrer" so even allowed sub-resources can't
  *     leak the user's location.
  *
- * No bridge to bitpub is exposed yet — apps in v1 can render but cannot
- * read from or write to the user's namespaces. The bridge is the next
- * milestone and will be opt-in per Pack via a declared manifest.
+ * Bridge (added in this version):
+ *   - A small inline shim defines `window.bitpub.run(id, args, cb)`
+ *     and `window.bitpub.watch(...)`. Calls postMessage the parent;
+ *     parent (this console.html) forwards approved invocations to the
+ *     local CLI's /bridge/run SSE endpoint and streams events back.
+ *   - The iframe never reaches the network itself — only the parent
+ *     does. CSP can stay locked down (default-src 'none').
  */
 function renderHtmlAppFrame(html) {
   const csp = `<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data: blob:; font-src data:; base-uri 'none'; form-action 'none'">`;
   const baseTag = `<base target="_blank">`;
-  const headInject = `${csp}${baseTag}`;
+  // The shim tag uses \x73 + escaped slash so the closing pattern can't
+  // be detected by the outer HTML parser. The escapes are transparent to
+  // the JS parser but defeat the HTML scanner's greedy script-end match.
+  const shim = `<\x73cript>${BRIDGE_SHIM_SOURCE}<\/script>`;
+  const headInject = `${csp}${baseTag}${shim}`;
 
   let doc;
   if (/<head[\s>]/i.test(html)) {
@@ -2480,6 +2581,340 @@ function renderHtmlAppFrame(html) {
   return `<iframe class="app-frame" sandbox="allow-scripts" referrerpolicy="no-referrer" srcdoc="${srcdoc}"></iframe>`;
 }
 
+/**
+ * Source of the in-iframe bridge shim. Kept as a template-literal so
+ * we can embed it verbatim in the srcdoc above. The shim's only job is
+ * to round-trip postMessage between the app code and the parent
+ * window — it neither validates inputs nor reaches the network. The
+ * parent (handleBridgeMessage below) is the trust boundary.
+ *
+ * The shim exposes a deliberately small callback-based API:
+ *
+ *   window.bitpub.run(functionId, args, {
+ *     onStart(payload)   // bridge accepted the call
+ *     onStdout(line)     // one line of stdout
+ *     onStderr(line)     // one line of stderr
+ *     onError({message}) // bridge or spawn-level error
+ *     onExit(code)       // terminal — handler removed after this
+ *   })
+ *
+ * Returns the requestId so the app can cancel later (not yet wired).
+ */
+const BRIDGE_SHIM_SOURCE = String.raw`
+(function () {
+  if (window.bitpub) return;
+  var nextId = 0;
+  var runHandlers = new Map();
+  var readHandlers = new Map();
+  window.addEventListener('message', function (e) {
+    var d = e.data;
+    if (!d || d.__bitpub !== true) return;
+    if (d.type === 'bitpub.event') {
+      var h = runHandlers.get(d.requestId);
+      if (!h) return;
+      var p = d.payload || {};
+      if (d.event === 'started' && h.onStart)  h.onStart(p);
+      else if (d.event === 'stdout' && h.onStdout) h.onStdout(p.line || '');
+      else if (d.event === 'stderr' && h.onStderr) h.onStderr(p.line || '');
+      else if (d.event === 'error'  && h.onError)  h.onError(p);
+      else if (d.event === 'exit') {
+        if (h.onExit) h.onExit(typeof p.code === 'number' ? p.code : null);
+        runHandlers.delete(d.requestId);
+      }
+    } else if (d.type === 'bitpub.namespace.list.result') {
+      var rh = readHandlers.get(d.requestId);
+      if (!rh) return;
+      readHandlers.delete(d.requestId);
+      if (d.ok) rh.resolve({ slices: d.slices || [], count: d.count || 0, pattern: d.pattern || '' });
+      else rh.reject(new Error(d.error || 'namespace read failed'));
+    } else if (d.type === 'bitpub.identity.result') {
+      var ih = readHandlers.get(d.requestId);
+      if (!ih) return;
+      readHandlers.delete(d.requestId);
+      if (d.ok) ih.resolve({
+        owner: d.owner,
+        domain: d.domain,
+        private_prefix: d.private_prefix,
+      });
+      else ih.reject(new Error(d.error || 'identity lookup failed'));
+    }
+  });
+  window.bitpub = {
+    run: function (functionId, args, callbacks) {
+      var requestId = ++nextId;
+      runHandlers.set(requestId, callbacks || {});
+      window.parent.postMessage({
+        __bitpub: true,
+        type: 'bitpub.run',
+        requestId: requestId,
+        functionId: String(functionId),
+        args: args || {}
+      }, '*');
+      return requestId;
+    },
+    namespace: {
+      // list(pattern, { fields, limit })
+      //   pattern  bitpub://... or bitpub://.../*  (folder + descendants)
+      //   fields   'preview' (first ~480 chars) | 'full'   default 'preview'
+      //   limit    max slices returned                     default 200
+      // Returns Promise<{ slices, count, pattern }>.
+      // This is the deterministic-read path: no LLM, no MCP, no auth
+      // dance. Apps that need to render data already in the user's
+      // namespace should use this, not bitpub.run.
+      list: function (pattern, opts) {
+        return new Promise(function (resolve, reject) {
+          var requestId = ++nextId;
+          readHandlers.set(requestId, { resolve: resolve, reject: reject });
+          window.parent.postMessage({
+            __bitpub: true,
+            type: 'bitpub.namespace.list',
+            requestId: requestId,
+            pattern: String(pattern || ''),
+            fields: (opts && opts.fields) || 'preview',
+            limit: (opts && opts.limit) || 200
+          }, '*');
+          setTimeout(function () {
+            if (!readHandlers.has(requestId)) return;
+            readHandlers.delete(requestId);
+            reject(new Error('namespace.list timed out'));
+          }, 10000);
+        });
+      }
+    },
+    navigate: function (hcu) {
+      // Hand off to another slice in the parent BitPub Browser
+      // (e.g. discovery page → installed app). HCU must be a
+      // bitpub:// address; everything else is dropped silently.
+      window.parent.postMessage({
+        __bitpub: true,
+        type: 'bitpub.navigate',
+        hcu: String(hcu || ''),
+      }, '*');
+    },
+    identity: {
+      // me() -> Promise<{ owner, domain, private_prefix }>
+      //   owner          e.g. "agent_ewim9gf01nq3"
+      //   domain         e.g. "tollbit.com"
+      //   private_prefix e.g. "bitpub://private:agent_ewim9gf01nq3"
+      //
+      // Lets apps that are distributed via a group/public namespace
+      // construct addresses that point at the *running user's* private
+      // data without hardcoding an owner ID. Use this if your app ships
+      // to other people.
+      me: function () {
+        return new Promise(function (resolve, reject) {
+          var requestId = ++nextId;
+          readHandlers.set(requestId, { resolve: resolve, reject: reject });
+          window.parent.postMessage({
+            __bitpub: true,
+            type: 'bitpub.identity.me',
+            requestId: requestId,
+          }, '*');
+          setTimeout(function () {
+            if (!readHandlers.has(requestId)) return;
+            readHandlers.delete(requestId);
+            reject(new Error('identity.me timed out'));
+          }, 5000);
+        });
+      }
+    }
+  };
+})();
+`;
+
+/* ── Bridge router (parent side) ─────────────────────────────────────
+ * Receives postMessages from rendered app iframes and forwards the
+ * approved `bitpub.run(...)` calls to the local CLI's SSE endpoint at
+ * /bridge/run. Each SSE event is reformatted as a `bitpub.event`
+ * postMessage and sent back to the originating iframe so the app's
+ * onStdout / onStderr / onExit callbacks fire.
+ *
+ * Trust model for v1:
+ *   - The iframe is at an opaque (null) origin, so we can't whitelist
+ *     by origin string. Instead we validate the message shape and
+ *     trust the in-process renderHtmlAppFrame to only mint iframes
+ *     for slices we already render (private + group scopes).
+ *   - The CLI enforces the function whitelist + argument types, so a
+ *     malformed message just gets rejected with HTTP 404 / SSE error.
+ *   - First UX iteration shows a non-blocking "Running" badge in the
+ *     chrome while at least one bridge call is active. Permission
+ *     banners with per-app grants come next iteration.
+ */
+const BRIDGE_RUNS = new Map();  // requestId → { es, source, functionId }
+let BRIDGE_RUN_COUNT = 0;
+
+function ensureBridgeBadge() {
+  let el = document.getElementById('bridge-badge');
+  if (el) return el;
+  el = document.createElement('div');
+  el.id = 'bridge-badge';
+  el.style.cssText = [
+    'position:fixed', 'bottom:14px', 'right:14px', 'z-index:9999',
+    'background:#1A1A19', 'color:#fff', 'padding:8px 12px',
+    'border-radius:8px', 'font:500 12.5px -apple-system,BlinkMacSystemFont,sans-serif',
+    'box-shadow:0 6px 24px rgba(0,0,0,.18), 0 2px 6px rgba(0,0,0,.12)',
+    'display:none', 'align-items:center', 'gap:8px',
+  ].join(';');
+  el.innerHTML = '<span style="width:8px;height:8px;border-radius:50%;background:#7ee787;display:inline-block;box-shadow:0 0 0 0 rgba(126,231,135,.6);animation:bp-pulse 1.6s ease-out infinite"></span><span id="bridge-badge-text">Running</span>';
+  const style = document.createElement('style');
+  style.textContent = '@keyframes bp-pulse{0%{box-shadow:0 0 0 0 rgba(126,231,135,.6)}70%{box-shadow:0 0 0 8px rgba(126,231,135,0)}100%{box-shadow:0 0 0 0 rgba(126,231,135,0)}}';
+  document.head.appendChild(style);
+  document.body.appendChild(el);
+  return el;
+}
+
+function updateBridgeBadge() {
+  const el = ensureBridgeBadge();
+  if (BRIDGE_RUN_COUNT <= 0) { el.style.display = 'none'; return; }
+  const label = BRIDGE_RUN_COUNT === 1
+    ? Array.from(BRIDGE_RUNS.values()).map(r => r.functionId).filter(Boolean)[0]
+    : `${BRIDGE_RUN_COUNT} functions running`;
+  document.getElementById('bridge-badge-text').textContent = `Running ${label}`;
+  el.style.display = 'inline-flex';
+}
+
+function bridgeForward(source, requestId, event, payload) {
+  if (!source) return;
+  try {
+    source.postMessage({
+      __bitpub: true,
+      type: 'bitpub.event',
+      requestId, event, payload,
+    }, '*');
+  } catch (_) { /* iframe gone */ }
+}
+
+function handleBridgeRunMessage(source, msg) {
+  const { requestId, functionId, args } = msg;
+  if (typeof requestId !== 'number' || !functionId) return;
+
+  const qs = new URLSearchParams({
+    functionId: String(functionId),
+    args: JSON.stringify(args || {}),
+  });
+
+  let es;
+  try {
+    es = new EventSource(`/bridge/run?${qs.toString()}`);
+  } catch (err) {
+    bridgeForward(source, requestId, 'error', { message: err.message });
+    bridgeForward(source, requestId, 'exit',  { code: 1 });
+    return;
+  }
+
+  BRIDGE_RUNS.set(requestId, { es, source, functionId });
+  BRIDGE_RUN_COUNT++;
+  updateBridgeBadge();
+
+  function relay(name) {
+    es.addEventListener(name, (ev) => {
+      let payload = {};
+      try { payload = JSON.parse(ev.data); } catch { /* ignore malformed */ }
+      bridgeForward(source, requestId, name, payload);
+    });
+  }
+  relay('started');
+  relay('stdout');
+  relay('stderr');
+  relay('error');
+
+  es.addEventListener('exit', (ev) => {
+    let payload = {};
+    try { payload = JSON.parse(ev.data); } catch { /* ignore */ }
+    bridgeForward(source, requestId, 'exit', payload);
+    es.close();
+    BRIDGE_RUNS.delete(requestId);
+    BRIDGE_RUN_COUNT--;
+    updateBridgeBadge();
+  });
+
+  es.onerror = () => {
+    // Connection loss / endpoint down. The bridge already emits an
+    // explicit `exit` for graceful termination, so reaching here means
+    // an unexpected drop — surface it and clean up.
+    if (!BRIDGE_RUNS.has(requestId)) return;
+    bridgeForward(source, requestId, 'error', { message: 'bridge stream closed unexpectedly' });
+    bridgeForward(source, requestId, 'exit',  { code: -1 });
+    try { es.close(); } catch (_) {}
+    BRIDGE_RUNS.delete(requestId);
+    BRIDGE_RUN_COUNT--;
+    updateBridgeBadge();
+  };
+}
+
+async function handleBridgeNamespaceListMessage(source, msg) {
+  const { requestId, pattern, fields, limit } = msg;
+  if (typeof requestId !== 'number' || !pattern) return;
+  const reply = (extra) => {
+    try {
+      source.postMessage({
+        __bitpub: true,
+        type: 'bitpub.namespace.list.result',
+        requestId, pattern,
+        ...extra,
+      }, '*');
+    } catch (_) { /* iframe gone */ }
+  };
+  try {
+    const qs = new URLSearchParams({
+      pattern: String(pattern),
+      fields: String(fields || 'preview'),
+      limit: String(limit || 200),
+    });
+    const r = await fetch(`/bridge/namespace/list?${qs.toString()}`);
+    const body = await r.json();
+    if (!r.ok) {
+      reply({ ok: false, error: body && body.error || `http ${r.status}` });
+      return;
+    }
+    reply({ ok: true, slices: body.slices || [], count: body.count || 0 });
+  } catch (err) {
+    reply({ ok: false, error: err && err.message || 'fetch failed' });
+  }
+}
+
+async function handleBridgeIdentityMessage(source, msg) {
+  const { requestId } = msg;
+  if (typeof requestId !== 'number') return;
+  const reply = (extra) => {
+    try {
+      source.postMessage({
+        __bitpub: true,
+        type: 'bitpub.identity.result',
+        requestId,
+        ...extra,
+      }, '*');
+    } catch (_) { /* iframe gone */ }
+  };
+  try {
+    const r = await fetch('/bridge/identity');
+    const body = await r.json();
+    if (!r.ok) { reply({ ok: false, error: `http ${r.status}` }); return; }
+    reply({ ok: true, owner: body.owner, domain: body.domain, private_prefix: body.private_prefix });
+  } catch (err) {
+    reply({ ok: false, error: err && err.message || 'fetch failed' });
+  }
+}
+
+function handleBridgeNavigateMessage(_source, msg) {
+  // Apps can hand off to another slice in the running user's Browser.
+  // We only allow bitpub:// addresses (no http:, no javascript:), and
+  // we route through submitAddress() which already does all the
+  // existing scope/path parsing.
+  const hcu = String((msg && msg.hcu) || '').trim();
+  if (!/^bitpub:\/\/[^\s]+$/.test(hcu)) return;
+  try { submitAddress(hcu); } catch (_) { /* ignore */ }
+}
+
+window.addEventListener('message', (e) => {
+  const d = e.data;
+  if (!d || typeof d !== 'object' || d.__bitpub !== true) return;
+  if (d.type === 'bitpub.run') handleBridgeRunMessage(e.source, d);
+  else if (d.type === 'bitpub.namespace.list') handleBridgeNamespaceListMessage(e.source, d);
+  else if (d.type === 'bitpub.identity.me') handleBridgeIdentityMessage(e.source, d);
+  else if (d.type === 'bitpub.navigate' || d.type === 'navigate') handleBridgeNavigateMessage(e.source, d);
+});
+
 function renderWriteGuide(sl) {
   const addr = sl.hcu;
   const ver = sl.metadata.version || 1;