sh3-core 0.8.0 → 0.8.2

package/dist/Shell.svelte

@@ -25,6 +25,8 @@
   import { isAuthenticated, isLocalOwner, getUser, logout } from './auth/index';
   import iconsUrl from './assets/icons.svg';
   import GuestBanner from './auth/GuestBanner.svelte';
+  import ConsentDialog from './keys/ConsentDialog.svelte';
+  import { startServerSideStream } from './keys/revocation-bus.svelte';
 
   const authenticated = $derived(isAuthenticated());
   const user = $derived(getUser());
@@ -97,6 +99,15 @@
     }));
     return () => unbindFloatStore();
   });
+
+  // Open the server-sent events stream for key revocations.
+  // Forwards server-side revocations to the local revocation bus so that
+  // onKeyRevoked fires on the owning shard even when the user revokes from
+  // the Keys & Peers shell view (not via the shard's own ctx.keys.revoke).
+  $effect(() => {
+    const stop = startServerSideStream();
+    return stop;
+  });
 </script>
 
 <div class="shell">
@@ -165,6 +176,14 @@
       </div>
     {/each}
   </div>
+
+  <!--
+    Shell-owned consent dialog for ctx.keys.mint().
+    Mounted unconditionally so the listener is always registered; it renders
+    nothing until a shard calls ctx.keys.mint().
+    z-index 9999 (inline in the component) keeps it above all overlay layers.
+  -->
+  <ConsentDialog />
 </div>
 
 <style>

package/dist/api.d.ts

@@ -17,9 +17,10 @@ export { listRegisteredApps, getActiveApp } from './apps/registry.svelte';
 export { launchApp, returnToHome, unregisterApp } from './apps/lifecycle';
 export { inspectActiveLayout, spliceIntoActiveLayout, dockIntoActiveLayout, focusTab, focusView, collapseChild, expandChild, closeTab, } from './layout/inspection';
 export type { DocumentHandle, DocumentHandleOptions, DocumentFormat, DocumentMeta, DocumentChange, AutosaveController, } from './documents/types';
+export { PERMISSION_DOCUMENTS_BROWSE } from './documents/types';
+export type { BrowseCapability } from './documents/browse';
 export type { SyncHandle, SyncScope, ManifestEntry, ApplyEntry, ApplyOpts, ApplyOutcome, ApplyBatchResult, ConflictPolicy, ConflictResolution, ConflictContext, JournalEntry, ChangePage, GrantRecord, } from './documents/sync/types';
 export { PERMISSION_DOCUMENTS_SYNC, ScopeNotGrantedError, ScopeRevokedError, TenantMismatchError, } from './documents/sync/types';
-export { createSyncRegistry } from './documents/sync/registry';
 export type { SyncRegistry } from './documents/sync/registry';
 export { default as SyncGrantPicker } from './documents/sync/components/SyncGrantPicker.svelte';
 export { default as DocumentSyncExplorer } from './documents/sync/components/DocumentSyncExplorer.svelte';
@@ -28,6 +29,9 @@ export type { RegistryIndex, PackageEntry, PackageVersion, RequiredDependency, I
 export type { ResolvedPackage } from './registry/client';
 export { fetchRegistries, fetchBundle, buildPackageMeta } from './registry/client';
 export { validateRegistryIndex } from './registry/schema';
+export { PERMISSION_KEYS_MINT, ScopeEscalationError, ConsentDeniedError, type ShardContextKeys, type ApiKeyPublic, type MintOpts, } from './keys/types';
+export { registerConsentListener, resolveConsent, type ConsentRequest } from './keys/consent.svelte';
+export { subscribe as subscribeKeyRevocation } from './keys/revocation-bus.svelte';
 export { isAdmin, isAuthenticated, isGuest, getUser, getAuthHeader } from './auth/index';
 export type { AuthUser, AuthSession, BootConfig } from './auth/types';
 /** Runtime feature flags for target-dependent behavior. */

package/dist/api.js

@@ -29,8 +29,8 @@ export { listRegisteredApps, getActiveApp } from './apps/registry.svelte';
 export { launchApp, returnToHome, unregisterApp } from './apps/lifecycle';
 // Layout inspection / mutation for advanced shards (diagnostic, etc.).
 export { inspectActiveLayout, spliceIntoActiveLayout, dockIntoActiveLayout, focusTab, focusView, collapseChild, expandChild, closeTab, } from './layout/inspection';
+export { PERMISSION_DOCUMENTS_BROWSE } from './documents/types';
 export { PERMISSION_DOCUMENTS_SYNC, ScopeNotGrantedError, ScopeRevokedError, TenantMismatchError, } from './documents/sync/types';
-export { createSyncRegistry } from './documents/sync/registry';
 export { default as SyncGrantPicker } from './documents/sync/components/SyncGrantPicker.svelte';
 export { default as DocumentSyncExplorer } from './documents/sync/components/DocumentSyncExplorer.svelte';
 // Shard introspection — read-only reactive maps exposing which shards are
@@ -41,6 +41,11 @@ export { default as DocumentSyncExplorer } from './documents/sync/components/Doc
 export { registeredShards, activeShards } from './shards/activate.svelte';
 export { fetchRegistries, fetchBundle, buildPackageMeta } from './registry/client';
 export { validateRegistryIndex } from './registry/schema';
+// Key mint/revoke types — client shards that declare `keys:mint` get ctx.keys.
+export { PERMISSION_KEYS_MINT, ScopeEscalationError, ConsentDeniedError, } from './keys/types';
+export { registerConsentListener, resolveConsent } from './keys/consent.svelte';
+// Revocation bus — subscribe to key revocation events (for advanced integrations).
+export { subscribe as subscribeKeyRevocation } from './keys/revocation-bus.svelte';
 // Admin mode (framework-internal components read admin status).
 export { isAdmin, isAuthenticated, isGuest, getUser, getAuthHeader } from './auth/index';
 /** Runtime feature flags for target-dependent behavior. */

package/dist/app/admin/ApiKeysView.svelte

@@ -3,14 +3,13 @@
    * Admin API Keys view — list, create, reveal, revoke API keys.
    */
 
-  interface ApiKey {
+  interface ApiKeyPublic {
     id: string;
-    key: string;
     label: string;
     createdAt: string;
   }
 
-  let keys = $state<ApiKey[]>([]);
+  let keys = $state<ApiKeyPublic[]>([]);
   let loading = $state(true);
   let error = $state<string | null>(null);
 
@@ -19,8 +18,9 @@
   let newLabel = $state('');
   let createError = $state<string | null>(null);
 
-  // Reveal state — tracks which key ids have been revealed
-  let revealed = $state<Set<string>>(new Set());
+  // Just-created key — the raw bearer value is returned once by the server.
+  // Displayed until the admin dismisses it, then never recoverable.
+  let justCreated = $state<{ id: string; key: string } | null>(null);
 
   // Delete confirmation
   let confirmingId = $state<string | null>(null);
@@ -53,9 +53,8 @@
         createError = body.error || 'Failed to create key';
         return;
       }
-      const created: ApiKey = await res.json();
-      revealed.add(created.id);
-      revealed = new Set(revealed);
+      const created: { id: string; key: string } = await res.json();
+      justCreated = { id: created.id, key: created.key };
       newLabel = '';
       showCreate = false;
       await fetchKeys();
@@ -64,15 +63,6 @@
     }
   }
 
-  function toggleReveal(id: string) {
-    if (revealed.has(id)) {
-      revealed.delete(id);
-    } else {
-      revealed.add(id);
-    }
-    revealed = new Set(revealed);
-  }
-
   async function revokeKey(id: string) {
     confirmingId = null;
     try {
@@ -80,8 +70,7 @@
         method: 'DELETE',
         credentials: 'include',
       });
-      revealed.delete(id);
-      revealed = new Set(revealed);
+      if (justCreated?.id === id) justCreated = null;
       await fetchKeys();
     } catch { /* ignore */ }
   }
@@ -92,10 +81,6 @@
     });
   }
 
-  function maskKey(key: string): string {
-    return key.slice(0, 8) + '\u2026' + key.slice(-4);
-  }
-
   fetchKeys();
 </script>
 
@@ -107,6 +92,14 @@
     </button>
   </div>
 
+  {#if justCreated}
+    <div class="admin-key-created">
+      <div class="admin-key-created-label">New key — copy now, it won't be shown again:</div>
+      <code class="admin-key-value">{justCreated.key}</code>
+      <button type="button" class="admin-btn-secondary" onclick={() => { justCreated = null; }}>Dismiss</button>
+    </div>
+  {/if}
+
   {#if showCreate}
     <form class="admin-create-form" onsubmit={(e) => { e.preventDefault(); createKey(); }}>
       <input class="admin-input" type="text" placeholder="Key label" bind:value={newLabel} />
@@ -128,12 +121,8 @@
           <div class="admin-key-info">
             <span class="admin-key-label">{k.label}</span>
             <span class="admin-key-meta">{k.id} &middot; {formatDate(k.createdAt)}</span>
-            <code class="admin-key-value">{revealed.has(k.id) ? k.key : maskKey(k.key)}</code>
           </div>
           <div class="admin-key-actions">
-            <button type="button" class="admin-btn-secondary" onclick={() => toggleReveal(k.id)}>
-              {revealed.has(k.id) ? 'Hide' : 'Reveal'}
-            </button>
             {#if confirmingId === k.id}
               <button type="button" class="admin-btn-danger" onclick={() => revokeKey(k.id)}>Confirm</button>
               <button type="button" class="admin-btn-secondary" onclick={() => { confirmingId = null; }}>Cancel</button>

package/dist/app/admin/SystemView.svelte

@@ -1,12 +1,38 @@
 <script lang="ts">
   /**
-   * Admin System view — server status and restart.
+   * Admin System view — server status, restart, and package-bundle cache policy.
    */
 
+  const SNAP_POINTS: Array<{ value: number; label: string }> = [
+    { value: 0, label: 'Off (no-store)' },
+    { value: 5, label: '5s (dev)' },
+    { value: 60, label: '1 min' },
+    { value: 3600, label: '1 hour' },
+    { value: 86400, label: '1 day' },
+    { value: 31536000, label: '1 year' },
+  ];
+
   let version = $state('...');
   let restarting = $state(false);
   let restartError = $state<string | null>(null);
 
+  let cacheMaxAge = $state(31536000);
+  let loadedMaxAge = $state(31536000);
+  let savingCache = $state(false);
+  let cacheError = $state<string | null>(null);
+
+  const dirty = $derived(cacheMaxAge !== loadedMaxAge);
+  const humanized = $derived(humanize(cacheMaxAge));
+
+  function humanize(sec: number): string {
+    if (sec === 0) return '0 seconds (off — browsers never cache)';
+    if (sec < 60) return `${sec} seconds`;
+    if (sec < 3600) return `${Math.round(sec / 60)} minutes`;
+    if (sec < 86400) return `${Math.round(sec / 3600)} hours`;
+    if (sec < 31536000) return `${Math.round(sec / 86400)} days`;
+    return `${Math.round(sec / 31536000)} years`;
+  }
+
   async function fetchVersion() {
     try {
       const res = await fetch('/api/version');
@@ -17,6 +43,43 @@
     } catch { /* ignore */ }
   }
 
+  async function fetchSettings() {
+    try {
+      const res = await fetch('/api/admin/settings', { credentials: 'include' });
+      if (res.ok) {
+        const body = await res.json();
+        const age = body.packages?.cacheMaxAge ?? 31536000;
+        cacheMaxAge = age;
+        loadedMaxAge = age;
+      }
+    } catch { /* ignore */ }
+  }
+
+  async function saveCache() {
+    savingCache = true;
+    cacheError = null;
+    try {
+      const res = await fetch('/api/admin/settings', {
+        method: 'PUT',
+        credentials: 'include',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ packages: { cacheMaxAge } }),
+      });
+      if (!res.ok) {
+        const body = await res.json().catch(() => ({}));
+        cacheError = body.error || 'Save failed';
+      } else {
+        const body = await res.json();
+        loadedMaxAge = body.packages?.cacheMaxAge ?? cacheMaxAge;
+        cacheMaxAge = loadedMaxAge;
+      }
+    } catch {
+      cacheError = 'Network error';
+    } finally {
+      savingCache = false;
+    }
+  }
+
   async function restart() {
     restarting = true;
     restartError = null;
@@ -38,6 +101,7 @@
   }
 
   fetchVersion();
+  fetchSettings();
 </script>
 
 <div class="admin-system">
@@ -50,24 +114,98 @@
     </div>
   </div>
 
-  <div class="admin-system-actions">
-    <button type="button" class="admin-btn-danger" onclick={restart} disabled={restarting}>
-      {restarting ? 'Restarting...' : 'Restart server'}
-    </button>
-    {#if restartError}
-      <div class="admin-error">{restartError}</div>
-    {/if}
-  </div>
+  <section class="admin-system-section">
+    <h3>Package bundle cache</h3>
+    <p class="admin-system-hint">
+      Controls the <code>Cache-Control</code> header on <code>/packages/:id/client.js</code>.
+      Set to <strong>0</strong> during development so drop-in bundle replacements take effect on F5.
+      Use a long value in production.
+    </p>
+
+    <input
+      type="range"
+      min="0"
+      max="31536000"
+      step="1"
+      bind:value={cacheMaxAge}
+      disabled={savingCache}
+    />
+    <div class="admin-system-readout">
+      <code>{cacheMaxAge}</code> — {humanized}
+    </div>
+
+    <div class="admin-system-snaps">
+      {#each SNAP_POINTS as snap (snap.value)}
+        <button
+          type="button"
+          class="admin-snap"
+          class:active={cacheMaxAge === snap.value}
+          onclick={() => (cacheMaxAge = snap.value)}
+          disabled={savingCache}
+        >
+          {snap.label}
+        </button>
+      {/each}
+    </div>
+
+    <div class="admin-system-actions">
+      <button
+        type="button"
+        class="admin-btn"
+        onclick={saveCache}
+        disabled={!dirty || savingCache}
+      >
+        {savingCache ? 'Saving...' : 'Save'}
+      </button>
+      <button
+        type="button"
+        class="admin-btn-ghost"
+        onclick={() => (cacheMaxAge = loadedMaxAge)}
+        disabled={!dirty || savingCache}
+      >
+        Reset
+      </button>
+      {#if cacheError}
+        <div class="admin-error">{cacheError}</div>
+      {/if}
+    </div>
+  </section>
+
+  <section class="admin-system-section">
+    <h3>Server control</h3>
+    <div class="admin-system-actions">
+      <button type="button" class="admin-btn-danger" onclick={restart} disabled={restarting}>
+        {restarting ? 'Restarting...' : 'Restart server'}
+      </button>
+      {#if restartError}
+        <div class="admin-error">{restartError}</div>
+      {/if}
+    </div>
+  </section>
 </div>
 
 <style>
   .admin-system { padding: 24px; font-family: system-ui, sans-serif; color: var(--shell-fg); }
   .admin-system h2 { margin: 0 0 16px; font-size: 18px; }
+  .admin-system h3 { margin: 0 0 8px; font-size: 14px; text-transform: uppercase; letter-spacing: 0.05em; color: var(--shell-fg-subtle); }
   .admin-system-info { margin-bottom: 24px; }
   .admin-system-row { display: flex; gap: 12px; padding: 8px 0; border-bottom: 1px solid var(--shell-border, #3a3a5c); font-size: 13px; }
   .admin-system-label { color: var(--shell-fg-subtle); min-width: 140px; }
-  .admin-system-actions { display: flex; flex-direction: column; gap: 8px; align-items: flex-start; }
-  .admin-btn-danger { padding: 8px 16px; background: transparent; color: var(--shell-error, #d32f2f); border: 1px solid var(--shell-error, #d32f2f); font-weight: 600; }
+  .admin-system-section { margin-bottom: 24px; padding-bottom: 16px; border-bottom: 1px solid var(--shell-border, #3a3a5c); }
+  .admin-system-section:last-child { border-bottom: none; }
+  .admin-system-hint { font-size: 13px; color: var(--shell-fg-subtle); margin: 0 0 12px; }
+  .admin-system-readout { font-size: 13px; margin: 8px 0 12px; }
+  .admin-system-snaps { display: flex; flex-wrap: wrap; gap: 6px; margin-bottom: 12px; }
+  .admin-snap { padding: 4px 10px; font-size: 12px; background: transparent; border: 1px solid var(--shell-border, #3a3a5c); color: var(--shell-fg); cursor: pointer; border-radius: var(--shell-radius-sm, 3px); }
+  .admin-snap.active { background: var(--shell-accent, #4a7bd4); color: var(--shell-bg); border-color: var(--shell-accent, #4a7bd4); }
+  .admin-snap:disabled { opacity: 0.5; cursor: not-allowed; }
+  .admin-system-actions { display: flex; flex-direction: row; gap: 8px; align-items: center; flex-wrap: wrap; }
+  .admin-btn { padding: 8px 16px; background: var(--shell-accent, #4a7bd4); color: var(--shell-bg); border: 1px solid var(--shell-accent, #4a7bd4); font-weight: 600; cursor: pointer; border-radius: var(--shell-radius-sm, 3px); }
+  .admin-btn:disabled { opacity: 0.5; cursor: not-allowed; }
+  .admin-btn-ghost { padding: 8px 16px; background: transparent; color: var(--shell-fg); border: 1px solid var(--shell-border, #3a3a5c); cursor: pointer; border-radius: var(--shell-radius-sm, 3px); }
+  .admin-btn-ghost:disabled { opacity: 0.5; cursor: not-allowed; }
+  .admin-btn-danger { padding: 8px 16px; background: transparent; color: var(--shell-error, #d32f2f); border: 1px solid var(--shell-error, #d32f2f); font-weight: 600; cursor: pointer; border-radius: var(--shell-radius-sm, 3px); }
   .admin-btn-danger:disabled { opacity: 0.6; cursor: not-allowed; }
   .admin-error { color: var(--shell-error, #d32f2f); font-size: 13px; }
+  input[type="range"] { width: 100%; max-width: 480px; }
 </style>

package/dist/documents/backends.d.ts

@@ -6,6 +6,10 @@ export declare class MemoryDocumentBackend implements DocumentBackend {
     delete(tenantId: string, shardId: string, path: string): Promise<void>;
     list(tenantId: string, shardId: string): Promise<DocumentMeta[]>;
     exists(tenantId: string, shardId: string, path: string): Promise<boolean>;
+    listAllShards(tenantId: string): Promise<string[]>;
+    listAllDocuments(tenantId: string): Promise<Array<DocumentMeta & {
+        shardId: string;
+    }>>;
 }
 export declare class IndexedDBDocumentBackend implements DocumentBackend {
     #private;
@@ -14,4 +18,8 @@ export declare class IndexedDBDocumentBackend implements DocumentBackend {
     delete(tenantId: string, shardId: string, path: string): Promise<void>;
     list(tenantId: string, shardId: string): Promise<DocumentMeta[]>;
     exists(tenantId: string, shardId: string, path: string): Promise<boolean>;
+    listAllShards(tenantId: string): Promise<string[]>;
+    listAllDocuments(tenantId: string): Promise<Array<DocumentMeta & {
+        shardId: string;
+    }>>;
 }

package/dist/documents/backends.js

@@ -62,6 +62,36 @@ export class MemoryDocumentBackend {
     async exists(tenantId, shardId, path) {
         return __classPrivateFieldGet(this, _MemoryDocumentBackend_store, "f").has(compositeKey(tenantId, shardId, path));
     }
+    async listAllShards(tenantId) {
+        const prefix = `${tenantId}/`;
+        const shards = new Set();
+        for (const key of __classPrivateFieldGet(this, _MemoryDocumentBackend_store, "f").keys()) {
+            if (!key.startsWith(prefix))
+                continue;
+            const rest = key.slice(prefix.length);
+            const slash = rest.indexOf('/');
+            if (slash < 0)
+                continue;
+            shards.add(rest.slice(0, slash));
+        }
+        return [...shards];
+    }
+    async listAllDocuments(tenantId) {
+        const prefix = `${tenantId}/`;
+        const out = [];
+        for (const [key, entry] of __classPrivateFieldGet(this, _MemoryDocumentBackend_store, "f")) {
+            if (!key.startsWith(prefix))
+                continue;
+            const rest = key.slice(prefix.length);
+            const slash = rest.indexOf('/');
+            if (slash < 0)
+                continue;
+            const shardId = rest.slice(0, slash);
+            const path = rest.slice(slash + 1);
+            out.push({ shardId, path, size: entry.size, lastModified: entry.lastModified });
+        }
+        return out;
+    }
 }
 _MemoryDocumentBackend_store = new WeakMap();
 // ---------------------------------------------------------------------------
@@ -126,6 +156,63 @@ export class IndexedDBDocumentBackend {
         const result = await __classPrivateFieldGet(this, _IndexedDBDocumentBackend_instances, "m", _IndexedDBDocumentBackend_tx).call(this, 'readonly', (s) => s.getKey(key));
         return result !== undefined;
     }
+    async listAllShards(tenantId) {
+        const prefix = `${tenantId}/`;
+        const db = await __classPrivateFieldGet(this, _IndexedDBDocumentBackend_instances, "m", _IndexedDBDocumentBackend_db).call(this);
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(IDB_STORE, 'readonly');
+            const store = tx.objectStore(IDB_STORE);
+            const range = IDBKeyRange.bound(prefix, prefix + '\uffff', false, false);
+            const req = store.openKeyCursor(range);
+            const shards = new Set();
+            req.onsuccess = () => {
+                const cursor = req.result;
+                if (cursor) {
+                    const rest = cursor.key.slice(prefix.length);
+                    const slash = rest.indexOf('/');
+                    if (slash >= 0)
+                        shards.add(rest.slice(0, slash));
+                    cursor.continue();
+                }
+                else {
+                    resolve([...shards]);
+                }
+            };
+            req.onerror = () => reject(req.error);
+        });
+    }
+    async listAllDocuments(tenantId) {
+        const prefix = `${tenantId}/`;
+        const db = await __classPrivateFieldGet(this, _IndexedDBDocumentBackend_instances, "m", _IndexedDBDocumentBackend_db).call(this);
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(IDB_STORE, 'readonly');
+            const store = tx.objectStore(IDB_STORE);
+            const range = IDBKeyRange.bound(prefix, prefix + '\uffff', false, false);
+            const req = store.openCursor(range);
+            const out = [];
+            req.onsuccess = () => {
+                const cursor = req.result;
+                if (cursor) {
+                    const rest = cursor.key.slice(prefix.length);
+                    const slash = rest.indexOf('/');
+                    if (slash >= 0) {
+                        const entry = cursor.value;
+                        out.push({
+                            shardId: rest.slice(0, slash),
+                            path: rest.slice(slash + 1),
+                            size: entry.size,
+                            lastModified: entry.lastModified,
+                        });
+                    }
+                    cursor.continue();
+                }
+                else {
+                    resolve(out);
+                }
+            };
+            req.onerror = () => reject(req.error);
+        });
+    }
 }
 _IndexedDBDocumentBackend_dbPromise = new WeakMap(), _IndexedDBDocumentBackend_instances = new WeakSet(), _IndexedDBDocumentBackend_db = function _IndexedDBDocumentBackend_db() {
     if (!__classPrivateFieldGet(this, _IndexedDBDocumentBackend_dbPromise, "f")) {

package/dist/documents/backends.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/documents/backends.test.js

@@ -0,0 +1,33 @@
+import { describe, it, expect } from 'vitest';
+import { MemoryDocumentBackend } from './backends';
+describe('DocumentBackend tenant-wide primitives', () => {
+    it('listAllShards returns every shard that has content for a tenant', async () => {
+        const be = new MemoryDocumentBackend();
+        await be.write('t1', 'shard-a', 'x.txt', 'a');
+        await be.write('t1', 'shard-b', 'y.txt', 'b');
+        await be.write('t1', 'shard-b', 'nested/z.txt', 'bb');
+        await be.write('t2', 'shard-c', 'z.txt', 'c');
+        const shards = await be.listAllShards('t1');
+        expect(shards.sort()).toEqual(['shard-a', 'shard-b']);
+        const other = await be.listAllShards('t2');
+        expect(other).toEqual(['shard-c']);
+    });
+    it('listAllDocuments returns docs with shardId attached across the tenant', async () => {
+        const be = new MemoryDocumentBackend();
+        await be.write('t1', 'shard-a', 'x.txt', 'a');
+        await be.write('t1', 'shard-b', 'nested/y.txt', 'bb');
+        await be.write('t2', 'shard-c', 'z.txt', 'c');
+        const docs = await be.listAllDocuments('t1');
+        expect(docs).toHaveLength(2);
+        expect(docs.map((d) => `${d.shardId}/${d.path}`).sort()).toEqual([
+            'shard-a/x.txt',
+            'shard-b/nested/y.txt',
+        ]);
+    });
+    it('listAllDocuments returns an empty array for an unknown tenant', async () => {
+        const be = new MemoryDocumentBackend();
+        await be.write('t1', 'shard-a', 'x.txt', 'a');
+        expect(await be.listAllDocuments('ghost')).toEqual([]);
+        expect(await be.listAllShards('ghost')).toEqual([]);
+    });
+});

package/dist/documents/browse.d.ts

@@ -0,0 +1,12 @@
+import type { DocumentBackend, DocumentChange, DocumentMeta } from './types';
+export interface BrowseCapability {
+    /** Every document in the tenant across all shards, each tagged with its owning shardId. */
+    listDocuments(): Promise<Array<DocumentMeta & {
+        shardId: string;
+    }>>;
+    /** Subscribe to tenant-wide document changes. Returns an unsubscribe. */
+    watchDocuments(callback: (change: DocumentChange) => void): () => void;
+    /** Enumerate shard ids with at least one document in the tenant. */
+    listShards(): Promise<string[]>;
+}
+export declare function createBrowseCapability(tenantId: string, backend: DocumentBackend): BrowseCapability;

package/dist/documents/browse.js

@@ -0,0 +1,19 @@
+/*
+ * BrowseCapability — tenant-wide document observation surface.
+ *
+ * Exposed on ShardContext as `ctx.browse` when the shard declares the
+ * 'documents:browse' permission. Read-only: writes still flow through
+ * the owning shard's own ctx.documents() handle.
+ */
+import { documentChanges } from './notifications';
+export function createBrowseCapability(tenantId, backend) {
+    return {
+        listDocuments: () => backend.listAllDocuments(tenantId),
+        listShards: () => backend.listAllShards(tenantId),
+        watchDocuments: (callback) => documentChanges.subscribe((change) => {
+            if (change.tenantId !== tenantId)
+                return;
+            callback(change);
+        }),
+    };
+}

package/dist/documents/browse.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/documents/browse.test.js

@@ -0,0 +1,41 @@
+import { describe, it, expect, vi } from 'vitest';
+import { MemoryDocumentBackend } from './backends';
+import { createBrowseCapability } from './browse';
+import { documentChanges } from './notifications';
+describe('BrowseCapability', () => {
+    it('lists documents tenant-wide with shardId attached', async () => {
+        const be = new MemoryDocumentBackend();
+        await be.write('t1', 'a', 'x.txt', '1');
+        await be.write('t1', 'b', 'y.txt', '22');
+        const browse = createBrowseCapability('t1', be);
+        const docs = await browse.listDocuments();
+        expect(docs.map((d) => d.shardId).sort()).toEqual(['a', 'b']);
+    });
+    it('listShards enumerates tenant shards', async () => {
+        const be = new MemoryDocumentBackend();
+        await be.write('t1', 'a', 'x.txt', '1');
+        await be.write('t1', 'b', 'y.txt', '2');
+        const browse = createBrowseCapability('t1', be);
+        expect((await browse.listShards()).sort()).toEqual(['a', 'b']);
+    });
+    it('watchDocuments fires with shardId on tenant-wide emits; filters other tenants', () => {
+        const be = new MemoryDocumentBackend();
+        const browse = createBrowseCapability('t1', be);
+        const cb = vi.fn();
+        const unsub = browse.watchDocuments(cb);
+        documentChanges.emit({ type: 'create', path: 'f.txt', tenantId: 't1', shardId: 's1' });
+        documentChanges.emit({ type: 'create', path: 'g.txt', tenantId: 't2', shardId: 's2' });
+        expect(cb).toHaveBeenCalledTimes(1);
+        expect(cb).toHaveBeenCalledWith(expect.objectContaining({ shardId: 's1', path: 'f.txt', tenantId: 't1' }));
+        unsub();
+    });
+    it('watchDocuments unsubscribe stops callbacks', () => {
+        const be = new MemoryDocumentBackend();
+        const browse = createBrowseCapability('t1', be);
+        const cb = vi.fn();
+        const unsub = browse.watchDocuments(cb);
+        unsub();
+        documentChanges.emit({ type: 'create', path: 'f.txt', tenantId: 't1', shardId: 's1' });
+        expect(cb).not.toHaveBeenCalled();
+    });
+});

package/dist/documents/http-backend.d.ts

@@ -19,4 +19,8 @@ export declare class HttpDocumentBackend implements DocumentBackend {
     delete(tenantId: string, shardId: string, path: string): Promise<void>;
     list(tenantId: string, shardId: string): Promise<DocumentMeta[]>;
     exists(tenantId: string, shardId: string, path: string): Promise<boolean>;
+    listAllShards(tenantId: string): Promise<string[]>;
+    listAllDocuments(tenantId: string): Promise<Array<DocumentMeta & {
+        shardId: string;
+    }>>;
 }

package/dist/documents/http-backend.js

@@ -70,6 +70,20 @@ export class HttpDocumentBackend {
         const res = await fetch(url, { method: 'HEAD' });
         return res.ok;
     }
+    async listAllShards(tenantId) {
+        const url = `${__classPrivateFieldGet(this, _HttpDocumentBackend_baseUrl, "f")}/api/docs/${tenantId}/_shards`;
+        const res = await fetch(url);
+        if (!res.ok)
+            throw new Error(`listAllShards failed: ${res.status}`);
+        return res.json();
+    }
+    async listAllDocuments(tenantId) {
+        const url = `${__classPrivateFieldGet(this, _HttpDocumentBackend_baseUrl, "f")}/api/docs/${tenantId}/_all`;
+        const res = await fetch(url);
+        if (!res.ok)
+            throw new Error(`listAllDocuments failed: ${res.status}`);
+        return res.json();
+    }
 }
 _HttpDocumentBackend_baseUrl = new WeakMap(), _HttpDocumentBackend_apiKey = new WeakMap(), _HttpDocumentBackend_instances = new WeakSet(), _HttpDocumentBackend_authHeaders = function _HttpDocumentBackend_authHeaders() {
     if (!__classPrivateFieldGet(this, _HttpDocumentBackend_apiKey, "f"))