sh3-core 0.19.5 → 0.20.1

package/dist/chrome/MenuSheet.svelte.d.ts

@@ -1,6 +1,5 @@
 type $$ComponentProps = {
-    open: boolean;
-    onClose: () => void;
+    close: () => void;
 };
 declare const MenuSheet: import("svelte").Component<$$ComponentProps, {}, "">;
 type MenuSheet = ReturnType<typeof MenuSheet>;

package/dist/chrome/MenuSheet.svelte.test.js

@@ -1,8 +1,8 @@
 /*
- * DOM smoke for MenuSheet — verifies open/closed rendering. The
- * container/item resolution is exercised via the same model functions
- * MenuBar uses; their unit tests cover the resolution semantics so
- * this test only asserts the wrapper structure.
+ * DOM smoke for MenuSheet — verifies the push-navigation modal card
+ * renders correctly. The container/item resolution is exercised via
+ * the same model functions MenuBar uses; their unit tests cover the
+ * resolution semantics so this test only asserts the wrapper structure.
  */
 import { describe, it, expect, afterEach } from 'vitest';
 import { mount, unmount, flushSync } from 'svelte';
@@ -21,26 +21,38 @@ afterEach(() => {
     }
 });
 describe('MenuSheet (dom)', () => {
-    it('renders nothing when closed', () => {
+    it('renders the menu sheet region with a title "Menu" when no actions registered', () => {
         host = document.createElement('div');
         document.body.appendChild(host);
         mounted = mount(MenuSheetAny, {
             target: host,
-            props: { open: false, onClose: () => { } },
+            props: { close: () => { } },
         });
         flushSync();
-        expect(host.querySelector('[data-sh3-region="menu-sheet"]')).toBeNull();
+        const sheet = host.querySelector('[data-sh3-region="menu-sheet"]');
+        expect(sheet).not.toBeNull();
+        expect(sheet.querySelector('.title').textContent).toContain('Menu');
     });
-    it('renders a sheet with a Cancel button when open', () => {
+    it('does not show back button at root level', () => {
         host = document.createElement('div');
         document.body.appendChild(host);
         mounted = mount(MenuSheetAny, {
             target: host,
-            props: { open: true, onClose: () => { } },
+            props: { close: () => { } },
         });
         flushSync();
-        const sheet = host.querySelector('[data-sh3-region="menu-sheet"]');
-        expect(sheet).not.toBeNull();
-        expect(sheet.querySelector('.cancel').textContent).toContain('Cancel');
+        const backBtn = host.querySelector('button[aria-label="Back"]');
+        expect(backBtn).toBeNull();
+    });
+    it('renders empty state when no items available', () => {
+        host = document.createElement('div');
+        document.body.appendChild(host);
+        mounted = mount(MenuSheetAny, {
+            target: host,
+            props: { close: () => { } },
+        });
+        flushSync();
+        const empty = host.querySelector('.empty');
+        expect(empty).not.toBeNull();
     });
 });

package/dist/createShell.js

@@ -13,7 +13,8 @@ import { resolvePlatform } from './platform/index';
 import { apiFetch } from './transport/apiFetch';
 import { hydrateTokenOverrides } from './theme';
 import { __setEnvServerUrl, getEnvServerUrl } from './env/index';
-import { __setActiveScope } from './documents/config';
+import { __setActiveScope, __setScopeResolver } from './documents/config';
+import { __setScopeResolver as __setShardScopeResolver } from './shards/activate.svelte';
 import { initFromBoot } from './auth/index';
 import SignInWall from './auth/SignInWall.svelte';
 import { loadBundleModule } from './registry/loader';
@@ -21,6 +22,7 @@ import { registerLoadedBundle } from './registry/register';
 import { attachGlobalListeners } from './actions/listeners';
 import { detectSatelliteMode } from './boot/satelliteMode';
 import { MemoryBackend } from './state/backends';
+import { sessionState } from './projects/session-state.svelte';
 import SatelliteShell from './satellite/SatelliteShell.svelte';
 export async function createShell(config) {
     var _a, _b;
@@ -31,9 +33,6 @@ export async function createShell(config) {
         __setBackend('workspace', platform.backends.workspace);
         __setBackend('user', platform.backends.user);
     }
-    if (platform.localOwner) {
-        setLocalOwner();
-    }
     __setEnvServerUrl(sUrl);
     hydrateTokenOverrides();
     // 2. Resolve mount target early (needed for both sign-in wall and sh3)
@@ -61,6 +60,8 @@ export async function createShell(config) {
         // but pop-out is currently a Tauri-only POC so we don't fetch it.
         if (platform.localOwner)
             __setActiveScope('local');
+        __setScopeResolver(() => sessionState.activeProjectId);
+        __setShardScopeResolver(() => sessionState.activeProjectId ? 'project' : 'tenant');
         if (config === null || config === void 0 ? void 0 : config.shards)
             for (const shard of config.shards)
                 registerShard(shard);
@@ -84,33 +85,38 @@ export async function createShell(config) {
         mount(SatelliteShell, { target, props: { payload: satellite.payload } });
         return;
     }
-    // 3. Fetch boot config (skip for purely-local owners; remoteAuth
-    //    forces it for cross-origin Tauri clients).
+    // 3. Fetch boot config. Always fetched — local-owner (Tauri sidecar)
+    //    needs the real sh3s_ session token minted by /api/boot.
     let bootConfig = null;
-    const useServerAuth = !platform.localOwner || (config === null || config === void 0 ? void 0 : config.remoteAuth) === true;
-    if (useServerAuth) {
-        try {
-            const res = await apiFetch(`${sUrl}/api/boot`);
-            if (res.ok) {
-                bootConfig = await res.json();
-            }
-        }
-        catch (_c) {
-            // Server unreachable — boot without auth (offline mode)
+    try {
+        const res = await apiFetch(`${sUrl}/api/boot`);
+        if (res.ok) {
+            bootConfig = await res.json();
         }
     }
+    catch (_c) {
+        // Server unreachable — boot without auth (offline mode)
+    }
     // 4. Auth decision point
     if (platform.localOwner && !(config === null || config === void 0 ? void 0 : config.remoteAuth)) {
-        // Local-owner (Tauri/dev): no auth, no sign-in, scope is 'local'.
-        // setLocalOwner() already called above — admin is assumed.
-        __setActiveScope('local');
+        // Local-owner (Tauri sidecar): boot minted a real sh3s_ session.
+        // initFromBoot stores the token; fall back to synthetic local if
+        // the server was unreachable (should never happen in sidecar mode).
+        if (bootConfig) {
+            initFromBoot(sUrl, bootConfig);
+            __setActiveScope(bootConfig.tenantId);
+        }
+        else {
+            setLocalOwner();
+            __setActiveScope('local');
+        }
     }
     else if (bootConfig) {
         initFromBoot(sUrl, bootConfig);
         __setActiveScope(bootConfig.tenantId);
         const { auth, session } = bootConfig;
-        // Hard gate: no session, auth required, no guest allowed → sign-in wall
-        if (!session && auth.required && !auth.guestAllowed) {
+        // Hard gate: no session and no guest allowed → sign-in wall
+        if (!session && !auth.guestAllowed) {
             await showSignInWall(target, bootConfig);
             // After successful sign-in, re-fetch boot config
             const res = await apiFetch(`${sUrl}/api/boot`);
@@ -137,6 +143,11 @@ export async function createShell(config) {
     if (config === null || config === void 0 ? void 0 : config.excludeShards)
         bootstrapConfig.excludeShards = config.excludeShards;
     await bootstrap(bootstrapConfig);
+    // 7b. Wire the document zone's scope resolver to the active project.
+    // When the user enters a project, getActiveScopeId() returns the project
+    // id so all document operations use the project's virtual tenant.
+    __setScopeResolver(() => sessionState.activeProjectId);
+    __setShardScopeResolver(() => sessionState.activeProjectId ? 'project' : 'tenant');
     // 8. Attach document-level keyboard / focus listeners
     attachGlobalListeners();
     // 9. Mount the sh3

package/dist/createShell.remoteAuth.test.js

@@ -48,11 +48,17 @@ describe('createShell remoteAuth flag', () => {
         }
         expect(calls.some(u => u === 'https://remote.example.com/api/boot')).toBe(true);
     });
-    it('keeps the legacy localOwner short-circuit when remoteAuth is absent', async () => {
+    it('fetches /api/boot in localOwner mode (sidecar needs the real sh3s_ token)', async () => {
         const calls = [];
         globalThis.fetch = vi.fn(async (input) => {
             calls.push(String(input));
-            return new Response('ok');
+            return new Response(JSON.stringify({
+                version: '0.20.0',
+                tenantId: 'local',
+                auth: { guestAllowed: false, selfRegistration: false },
+                session: { token: 'sh3s_abc', userId: 'local', role: 'admin', expiresAt: Number.MAX_SAFE_INTEGER },
+                user: { id: 'local', username: 'local', displayName: 'Local Owner', role: 'admin', createdAt: '', updatedAt: '' },
+            }), { status: 200, headers: { 'Content-Type': 'application/json' } });
         });
         vi.doMock('./platform/index', () => ({
             resolvePlatform: async () => ({ backends: null, localOwner: true }),
@@ -66,6 +72,6 @@ describe('createShell remoteAuth flag', () => {
         catch (_a) {
             // ignore — assertion below is the contract.
         }
-        expect(calls.some(u => u.endsWith('/api/boot'))).toBe(false);
+        expect(calls.some(u => u.endsWith('/api/boot'))).toBe(true);
     });
 });

package/dist/documents/browse.d.ts

@@ -91,6 +91,23 @@ export interface BrowseCapability {
      * `typeof ctx.browse.deleteFrom === 'function'`.
      */
     deleteFrom?(shardId: string, path: string): Promise<void>;
+    /**
+     * Copy or move a document from the active tenant to another scope.
+     * Available only when the caller declares both `documents:browse` and
+     * `documents:write`. Used for transferring documents between a user's
+     * personal scope and a project scope (or vice versa).
+     *
+     * When `opts.delete` is true, the source document is removed after
+     * copying (effectively a move/transfer). Default: false (copy only).
+     *
+     * Absent (undefined) on the capability object when `documents:write`
+     * is not declared; feature-detect with
+     * `typeof ctx.browse.transferToScope === 'function'`.
+     */
+    transferToScope?(shardId: string, path: string, targetScope: string, opts?: {
+        targetShardId?: string;
+        delete?: boolean;
+    }): Promise<void>;
 }
 export interface BrowseCapabilityOptions {
     /** When true, the returned capability exposes `readFrom`. */
@@ -98,4 +115,4 @@ export interface BrowseCapabilityOptions {
     /** When true, the returned capability exposes `writeTo`. */
     canWrite: boolean;
 }
-export declare function createBrowseCapability(tenantId: string, backend: DocumentBackend, options?: BrowseCapabilityOptions): BrowseCapability;
+export declare function createBrowseCapability(getTenantId: () => string, backend: DocumentBackend, options?: BrowseCapabilityOptions): BrowseCapability;

package/dist/documents/browse.js

@@ -4,33 +4,39 @@
  * 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.
+ *
+ * Tenant id is resolved lazily via a callback so that the browse
+ * capability automatically follows the active scope (personal tenant
+ * vs. active project). The callback is wired by the framework at
+ * shard activation time.
  */
 import { documentChanges } from './notifications';
-export function createBrowseCapability(tenantId, backend, options = { canRead: false, canWrite: false }) {
+export function createBrowseCapability(getTenantId, backend, options = { canRead: false, canWrite: false }) {
     const capability = {
-        listDocuments: () => backend.listAllDocuments(tenantId),
-        listShards: () => backend.listAllShards(tenantId),
+        listDocuments: () => backend.listAllDocuments(getTenantId()),
+        listShards: () => backend.listAllShards(getTenantId()),
         watchDocuments: (callback) => documentChanges.subscribe((change) => {
-            if (change.tenantId !== tenantId)
+            if (change.tenantId !== getTenantId())
                 return;
             callback(change);
         }),
     };
     if (options.canRead) {
-        capability.readFrom = (shardId, path) => backend.read(tenantId, shardId, path);
+        capability.readFrom = (shardId, path) => backend.read(getTenantId(), shardId, path);
         capability.statusFrom = async (shardId, path) => {
             if (!backend.readMeta)
                 return null;
-            return backend.readMeta(tenantId, shardId, path);
+            return backend.readMeta(getTenantId(), shardId, path);
         };
         capability.readBranchFrom = async (shardId, path, origin) => {
             if (!backend.readBranch)
                 return null;
-            return backend.readBranch(tenantId, shardId, path, origin);
+            return backend.readBranch(getTenantId(), shardId, path, origin);
         };
     }
     if (options.canWrite) {
         capability.writeTo = async (shardId, path, content) => {
+            const tenantId = getTenantId();
             const existed = await backend.exists(tenantId, shardId, path);
             await backend.write(tenantId, shardId, path, content);
             documentChanges.emit({
@@ -43,6 +49,7 @@ export function createBrowseCapability(tenantId, backend, options = { canRead: f
         capability.resolveConflictFrom = async (shardId, path, choice) => {
             if (!backend.resolve)
                 throw new Error('Backend does not support resolveConflict');
+            const tenantId = getTenantId();
             await backend.resolve(tenantId, shardId, path, choice);
             documentChanges.emit({ type: 'update', path, tenantId, shardId });
         };
@@ -50,6 +57,7 @@ export function createBrowseCapability(tenantId, backend, options = { canRead: f
             if ((opts === null || opts === void 0 ? void 0 : opts.newShardId) !== undefined) {
                 throw new Error('Cross-shard move is not yet supported (ADR-018 amendment 2026-04-27)');
             }
+            const tenantId = getTenantId();
             await backend.rename(tenantId, shardId, oldPath, newPath);
             documentChanges.emit({
                 type: 'rename',
@@ -60,12 +68,37 @@ export function createBrowseCapability(tenantId, backend, options = { canRead: f
             });
         };
         capability.deleteFrom = async (shardId, path) => {
+            const tenantId = getTenantId();
             const existed = await backend.exists(tenantId, shardId, path);
             await backend.delete(tenantId, shardId, path);
             if (existed) {
                 documentChanges.emit({ type: 'delete', path, tenantId, shardId });
             }
         };
+        capability.transferToScope = async (shardId, path, targetScope, opts) => {
+            var _a;
+            const tenantId = getTenantId();
+            if (targetScope === tenantId) {
+                throw new Error('targetScope must differ from the active tenant');
+            }
+            const targetShard = (_a = opts === null || opts === void 0 ? void 0 : opts.targetShardId) !== null && _a !== void 0 ? _a : shardId;
+            const content = await backend.read(tenantId, shardId, path);
+            if (content === null) {
+                throw new Error(`Document not found at ${shardId}/${path} in scope ${tenantId}`);
+            }
+            const existed = await backend.exists(targetScope, targetShard, path);
+            await backend.write(targetScope, targetShard, path, content);
+            documentChanges.emit({
+                type: existed ? 'update' : 'create',
+                path,
+                tenantId: targetScope,
+                shardId: targetShard,
+            });
+            if (opts === null || opts === void 0 ? void 0 : opts.delete) {
+                await backend.delete(tenantId, shardId, path);
+                documentChanges.emit({ type: 'delete', path, tenantId, shardId });
+            }
+        };
     }
     return capability;
 }

package/dist/documents/browse.test.js

@@ -7,7 +7,7 @@ describe('BrowseCapability', () => {
         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 browse = createBrowseCapability(() => 't1', be);
         const docs = await browse.listDocuments();
         expect(docs.map((d) => d.shardId).sort()).toEqual(['a', 'b']);
     });
@@ -15,12 +15,12 @@ describe('BrowseCapability', () => {
         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);
+        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 browse = createBrowseCapability(() => 't1', be);
         const cb = vi.fn();
         const unsub = browse.watchDocuments(cb);
         documentChanges.emit({ type: 'create', path: 'f.txt', tenantId: 't1', shardId: 's1' });
@@ -31,7 +31,7 @@ describe('BrowseCapability', () => {
     });
     it('watchDocuments unsubscribe stops callbacks', () => {
         const be = new MemoryDocumentBackend();
-        const browse = createBrowseCapability('t1', be);
+        const browse = createBrowseCapability(() => 't1', be);
         const cb = vi.fn();
         const unsub = browse.watchDocuments(cb);
         unsub();
@@ -41,46 +41,46 @@ describe('BrowseCapability', () => {
     describe('readFrom (documents:read gate)', () => {
         it('is absent when canRead is false', () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: false });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: false });
             expect(browse.readFrom).toBeUndefined();
         });
         it('is present when canRead is true', () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: true, canWrite: false });
             expect(typeof browse.readFrom).toBe('function');
         });
         it('reads content from a foreign shard namespace', async () => {
             const be = new MemoryDocumentBackend();
             await be.write('t1', 'other', 'notes/ideas.md', 'hello');
-            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: true, canWrite: false });
             expect(await browse.readFrom('other', 'notes/ideas.md')).toBe('hello');
         });
         it('returns null when the foreign document does not exist', async () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: true, canWrite: false });
             expect(await browse.readFrom('other', 'nope.txt')).toBeNull();
         });
         it('never crosses tenants: a t1 capability cannot read t2 docs', async () => {
             const be = new MemoryDocumentBackend();
             await be.write('t2', 's', 'secret.txt', 'hidden');
-            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: true, canWrite: false });
             expect(await browse.readFrom('s', 'secret.txt')).toBeNull();
         });
     });
     describe('writeTo (documents:write gate)', () => {
         it('is absent when canWrite is false', () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: false });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: false });
             expect(browse.writeTo).toBeUndefined();
         });
         it('is present when canWrite is true', () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
             expect(typeof browse.writeTo).toBe('function');
         });
         it('writes into the target shard namespace and emits a create change', async () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
             const events = [];
             const unsub = documentChanges.subscribe((c) => events.push(c));
             await browse.writeTo('target-shard', 'notes/ideas.md', 'hello');
@@ -93,7 +93,7 @@ describe('BrowseCapability', () => {
         it('emits update (not create) when overwriting an existing document', async () => {
             const be = new MemoryDocumentBackend();
             await be.write('t1', 'target-shard', 'a.txt', 'v1');
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
             const events = [];
             const unsub = documentChanges.subscribe((c) => events.push(c));
             await browse.writeTo('target-shard', 'a.txt', 'v2');
@@ -105,7 +105,7 @@ describe('BrowseCapability', () => {
         });
         it('never crosses tenants: cannot be tricked into writing into tenant b', async () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
             await browse.writeTo('s', 'a.txt', 'x');
             expect(await be.read('t1', 's', 'a.txt')).toBe('x');
             expect(await be.read('t2', 's', 'a.txt')).toBeNull();
@@ -114,7 +114,7 @@ describe('BrowseCapability', () => {
     describe('read + write combined', () => {
         it('round-trips content through readFrom after writeTo', async () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: true });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: true, canWrite: true });
             await browse.writeTo('shard-x', 'doc.txt', 'roundtrip');
             expect(await browse.readFrom('shard-x', 'doc.txt')).toBe('roundtrip');
         });
@@ -122,13 +122,13 @@ describe('BrowseCapability', () => {
     describe('statusFrom / readBranchFrom (documents:read gate)', () => {
         it('absent when canRead is false', () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: false });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: false });
             expect(browse.statusFrom).toBeUndefined();
             expect(browse.readBranchFrom).toBeUndefined();
         });
         it('present when canRead is true', () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: true, canWrite: false });
             expect(typeof browse.statusFrom).toBe('function');
             expect(typeof browse.readBranchFrom).toBe('function');
         });
@@ -144,13 +144,13 @@ describe('BrowseCapability', () => {
                 listAllDocuments: vi.fn(async () => []),
                 readMeta: vi.fn(async (...args) => { calls.push(args); return null; }),
             };
-            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: true, canWrite: false });
             await browse.statusFrom('other', 'a.txt');
             expect(calls[0]).toEqual(['t1', 'other', 'a.txt']);
         });
         it('statusFrom returns null when backend has no readMeta', async () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: true, canWrite: false });
             expect(await browse.statusFrom('other', 'a.txt')).toBeNull();
         });
         it('readBranchFrom delegates to backend.readBranch with tenant baked in', async () => {
@@ -165,32 +165,32 @@ describe('BrowseCapability', () => {
                 listAllDocuments: vi.fn(async () => []),
                 readBranch: vi.fn(async (...args) => { calls.push(args); return 'x'; }),
             };
-            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: true, canWrite: false });
             const out = await browse.readBranchFrom('other', 'a.txt', 'peer-1');
             expect(out).toBe('x');
             expect(calls[0]).toEqual(['t1', 'other', 'a.txt', 'peer-1']);
         });
         it('readBranchFrom returns null when backend has no readBranch', async () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: true, canWrite: false });
             expect(await browse.readBranchFrom('other', 'a.txt', 'peer-1')).toBeNull();
         });
     });
     describe('renameFrom (documents:write gate)', () => {
         it('absent when canWrite is false', () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: false });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: false });
             expect(browse.renameFrom).toBeUndefined();
         });
         it('present when canWrite is true', () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
             expect(typeof browse.renameFrom).toBe('function');
         });
         it('renames in the target shard namespace and emits a rename event', async () => {
             const be = new MemoryDocumentBackend();
             await be.write('t1', 'target-shard', 'old.txt', 'hello');
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
             const events = [];
             const unsub = documentChanges.subscribe((c) => events.push(c));
             await browse.renameFrom('target-shard', 'old.txt', 'new.txt');
@@ -210,7 +210,7 @@ describe('BrowseCapability', () => {
         it('never crosses tenants: cannot be tricked into renaming in tenant b', async () => {
             const be = new MemoryDocumentBackend();
             await be.write('t2', 's', 'old.txt', 'hidden');
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
             await expect(browse.renameFrom('s', 'old.txt', 'new.txt'))
                 .rejects.toThrow(/not found/);
             expect(await be.read('t2', 's', 'old.txt')).toBe('hidden');
@@ -218,7 +218,7 @@ describe('BrowseCapability', () => {
         it('throws when opts.newShardId is provided (cross-shard move reserved)', async () => {
             const be = new MemoryDocumentBackend();
             await be.write('t1', 's1', 'old.txt', 'hello');
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
             await expect(browse.renameFrom('s1', 'old.txt', 'new.txt', { newShardId: 's2' })).rejects.toThrow(/Cross-shard move is not yet supported/);
             expect(await be.read('t1', 's1', 'old.txt')).toBe('hello');
         });
@@ -226,12 +226,12 @@ describe('BrowseCapability', () => {
     describe('resolveConflictFrom (documents:write gate)', () => {
         it('absent when canWrite is false', () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: true, canWrite: false });
             expect(browse.resolveConflictFrom).toBeUndefined();
         });
         it('present when canWrite is true', () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
             expect(typeof browse.resolveConflictFrom).toBe('function');
         });
         it('delegates to backend.resolve with tenant baked in and emits an update', async () => {
@@ -246,7 +246,7 @@ describe('BrowseCapability', () => {
                 listAllDocuments: vi.fn(async () => []),
                 resolve: vi.fn(async (...args) => { calls.push(args); }),
             };
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
             const events = [];
             const unsub = documentChanges.subscribe((e) => events.push(e));
             await browse.resolveConflictFrom('other', 'a.txt', { origin: 'peer-1' });
@@ -258,7 +258,7 @@ describe('BrowseCapability', () => {
         });
         it('throws if backend does not support resolve', async () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
             await expect(browse.resolveConflictFrom('other', 'a.txt', { origin: 'peer-1' }))
                 .rejects.toThrow(/does not support resolveConflict/);
         });
@@ -266,18 +266,18 @@ describe('BrowseCapability', () => {
     describe('deleteFrom (documents:write gate)', () => {
         it('absent when canWrite is false', () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: true, canWrite: false });
             expect(browse.deleteFrom).toBeUndefined();
         });
         it('present when canWrite is true', () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
             expect(typeof browse.deleteFrom).toBe('function');
         });
         it('deletes from the target shard namespace and emits a delete event', async () => {
             const be = new MemoryDocumentBackend();
             await be.write('t1', 'target-shard', 'a.txt', 'hello');
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
             const events = [];
             const unsub = documentChanges.subscribe((c) => events.push(c));
             await browse.deleteFrom('target-shard', 'a.txt');
@@ -289,7 +289,7 @@ describe('BrowseCapability', () => {
         });
         it('is idempotent on missing paths and emits no event', async () => {
             const be = new MemoryDocumentBackend();
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
             const events = [];
             const unsub = documentChanges.subscribe((c) => events.push(c));
             await expect(browse.deleteFrom('target-shard', 'nope.txt')).resolves.toBeUndefined();
@@ -299,7 +299,7 @@ describe('BrowseCapability', () => {
         it('never crosses tenants: a t1 capability cannot delete t2 docs', async () => {
             const be = new MemoryDocumentBackend();
             await be.write('t2', 's', 'secret.txt', 'hidden');
-            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
             await browse.deleteFrom('s', 'secret.txt');
             expect(await be.read('t2', 's', 'secret.txt')).toBe('hidden');
         });

package/dist/documents/config.d.ts

@@ -1,4 +1,8 @@
 import type { DocumentBackend } from './types';
+/** Host-only. Register a callback that resolves the active project scope.
+ *  When non-null and returns a string, that string overrides the static
+ *  scopeId for all document operations. Wired by createShell after bootstrap. */
+export declare function __setScopeResolver(resolver: (() => string | null) | null): void;
 export declare function getActiveScopeId(): string;
 /** @deprecated use getActiveScopeId — kept until callers migrate. */
 export declare function getTenantId(): string;