sh3-core 0.20.2 → 0.20.3

package/dist/BrandSlot.svelte

@@ -13,7 +13,7 @@
   import { getLiveDispatcherState } from './actions/state.svelte';
   import { launchApp, returnToHome } from './apps/lifecycle';
   import { getBreadcrumbAppId, getRegisteredApp } from './apps/registry.svelte';
-  import { sessionState, setActiveProjectId } from './projects/session-state.svelte';
+  import { sessionState, switchProjectScope } from './projects/session-state.svelte';
   import { projectsState } from './projects-shard/projectsShard.svelte';
 
   const activeAppId = $derived(getLiveDispatcherState().activeAppId);
@@ -48,7 +48,7 @@
   }
 
   function exitProject() {
-    setActiveProjectId(null);
+    switchProjectScope(null);
   }
 
   function reenterProjectHome() {

package/dist/actions/ctx-actions.svelte.test.js

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach } from 'vitest';
 import { MemoryDocumentBackend } from '../documents/backends';
-import { __setDocumentBackend, __setTenantId } from '../documents/config';
+import { __setDocumentBackend, __setActiveScope } from '../documents/config';
 import { registerShard, activateShard, __resetShardRegistryForTest, } from '../shards/activate.svelte';
 import { __resetViewRegistryForTest } from '../shards/registry';
 import { __resetActionsRegistryForTest } from './registry';
@@ -14,7 +14,7 @@ describe('ShardContext.listActions / runAction (integration)', () => {
         __resetActionsRegistryForTest();
         __resetDispatcherStateForTest();
         __setDocumentBackend(new MemoryDocumentBackend());
-        __setTenantId('tenant-test');
+        __setActiveScope('tenant-test');
     });
     it('listActions enumerates actions registered by other shards', async () => {
         registerShard({

package/dist/artifact.d.ts

@@ -29,4 +29,6 @@ export interface ArtifactManifest {
         id: string;
         versionRange: string;
     }>;
+    /** Shard ids this app requires to be installed on the server. Written by sh3Artifact for app/combo bundles. */
+    requiredShards?: string[];
 }

package/dist/boot/satellitePayload.d.ts

@@ -8,10 +8,12 @@ export type SatellitePayload = {
         h: number;
     };
     activateShards: string[];
+    projectId?: string;
 } | {
     kind: 'app';
     appId: string;
     activateShards: string[];
+    projectId?: string;
 };
 export declare function encodePayload(payload: SatellitePayload): string;
 export declare function decodePayload(encoded: string): SatellitePayload;

package/dist/boot/satellitePayload.test.js

@@ -36,6 +36,25 @@ describe('satellite payload encode/decode', () => {
         const bad = btoa(JSON.stringify({ kind: 'mystery' }));
         expect(() => decodePayload(bad)).toThrow();
     });
+    it('round-trips a float payload with projectId', () => {
+        const payload = {
+            kind: 'float',
+            content: { type: 'slot', slotId: 's:1', viewId: 'foo:bar' },
+            size: { w: 800, h: 600 },
+            activateShards: ['foo'],
+            projectId: 'proj-abc',
+        };
+        expect(decodePayload(encodePayload(payload))).toEqual(payload);
+    });
+    it('round-trips an app payload with projectId', () => {
+        const payload = {
+            kind: 'app',
+            appId: 'sh3-store',
+            activateShards: ['sh3-core'],
+            projectId: 'proj-xyz',
+        };
+        expect(decodePayload(encodePayload(payload))).toEqual(payload);
+    });
     it('produces a URL-safe encoding (no + / =)', () => {
         // A long-ish payload increases the chance the underlying base64
         // would contain non-URL-safe characters from the standard alphabet.

package/dist/build.d.ts

@@ -70,10 +70,16 @@ export declare function composeArtifactVersion(pkgVersion: string, suffix: strin
  * After Vite's lib build completes, this plugin:
  *   1. Finds the entry chunk and renames it to client.js
  *   2. Optionally copies a pre-built server bundle as server.js
- *   3. Extracts manifest fields (id, label, type) from the source
+ *   3. Extracts manifest fields (id, label, type, requiredShards) from the source
  *   4. Reads `version` from `package.json.version` — the authoritative
  *      source per ADR-013. A literal `version:` in a source manifest is
  *      ignored; only `package.json.version` matters for the artifact.
  *   5. Writes manifest.json alongside the bundles
  */
+/**
+ * Extract the requiredShards array from a bundled source string.
+ * Finds the first `requiredShards: [...]` array literal and parses its string IDs.
+ * Exported for testing; used internally by sh3Artifact.
+ */
+export declare function extractRequiredShardsFromBundle(bundleSource: string): string[];
 export declare function sh3Artifact(options?: Sh3ArtifactOptions): Plugin;

package/dist/build.js

@@ -136,12 +136,28 @@ function resolveAutoBuildSuffix() {
  * After Vite's lib build completes, this plugin:
  *   1. Finds the entry chunk and renames it to client.js
  *   2. Optionally copies a pre-built server bundle as server.js
- *   3. Extracts manifest fields (id, label, type) from the source
+ *   3. Extracts manifest fields (id, label, type, requiredShards) from the source
  *   4. Reads `version` from `package.json.version` — the authoritative
  *      source per ADR-013. A literal `version:` in a source manifest is
  *      ignored; only `package.json.version` matters for the artifact.
  *   5. Writes manifest.json alongside the bundles
  */
+/**
+ * Extract the requiredShards array from a bundled source string.
+ * Finds the first `requiredShards: [...]` array literal and parses its string IDs.
+ * Exported for testing; used internally by sh3Artifact.
+ */
+export function extractRequiredShardsFromBundle(bundleSource) {
+    const arrayMatch = bundleSource.match(/\brequiredShards\s*:\s*\[([^\]]*)\]/);
+    if (!arrayMatch)
+        return [];
+    const ids = [];
+    const idRe = /["']([^"']+)["']/g;
+    let m;
+    while ((m = idRe.exec(arrayMatch[1])) !== null)
+        ids.push(m[1]);
+    return ids;
+}
 export function sh3Artifact(options = {}) {
     let outDir = '';
     let entryFileName = '';
@@ -238,14 +254,17 @@ export function sh3Artifact(options = {}) {
                     const m = block.match(pattern);
                     return m ? m[1] : '';
                 };
+                // Extract the requiredShards string-id array from the app manifest block.
+                const requiredShards = extractRequiredShardsFromBundle(block);
                 return {
                     id: get(/\bid\s*:\s*["']([^"']+)["']/),
                     label: get(/\blabel\s*:\s*["']([^"']+)["']/),
+                    requiredShards,
                 };
             }
             // App first, then Shard.
             const extracted = (_a = extractFromBlock(/\brequiredShards\s*:\s*\[/)) !== null && _a !== void 0 ? _a : extractFromBlock(/\bviews\s*:\s*\[/);
-            const { id, label } = extracted;
+            const { id, label, requiredShards } = extracted;
             // --- Optional server bundle ---
             let hasServer = false;
             if (options.serverEntry && existsSync(options.serverEntry)) {
@@ -292,7 +311,7 @@ export function sh3Artifact(options = {}) {
             if (!finalAuthor) {
                 throw new Error('[sh3-artifact] Missing "author". Add it to package.json or pass it via sh3Artifact({ manifest: { author } }).');
             }
-            const manifest = Object.assign(Object.assign(Object.assign({ id: id || 'unknown', type, label: label || id || 'unknown', version: artifactVersion, contractVersion: 1, client: 'client.js' }, (hasServer ? { server: 'server.js' } : {})), { description: finalDescription, author: finalAuthor }), overrides);
+            const manifest = Object.assign(Object.assign(Object.assign(Object.assign({ id: id || 'unknown', type, label: label || id || 'unknown', version: artifactVersion, contractVersion: 1, client: 'client.js' }, (hasServer ? { server: 'server.js' } : {})), { description: finalDescription, author: finalAuthor }), ((type === 'app' || type === 'combo') ? { requiredShards } : {})), overrides);
             writeFileSync(join(outDir, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n');
             // --- Log summary ---
             const files = ['manifest.json', 'client.js'];

package/dist/build.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { composeArtifactVersion } from './build';
+import { composeArtifactVersion, extractRequiredShardsFromBundle } from './build';
 describe('composeArtifactVersion', () => {
     it('returns pkgVersion unchanged when suffix is undefined', () => {
         expect(composeArtifactVersion('1.2.3', undefined)).toBe('1.2.3');
@@ -29,3 +29,29 @@ describe('composeArtifactVersion', () => {
         expect(() => composeArtifactVersion('1.2.3', '+42')).toThrow(/not a valid semver build-metadata identifier/);
     });
 });
+describe('extractRequiredShardsFromBundle', () => {
+    it('extracts a single shard id', () => {
+        const src = `const App = { manifest: { id: "my-app", requiredShards: ["guml.core"] } };`;
+        expect(extractRequiredShardsFromBundle(src)).toEqual(['guml.core']);
+    });
+    it('extracts multiple shard ids', () => {
+        const src = `requiredShards: ["guml.core", "sh3-file-explorer", "some-other"]`;
+        expect(extractRequiredShardsFromBundle(src)).toEqual(['guml.core', 'sh3-file-explorer', 'some-other']);
+    });
+    it('handles single-quoted ids', () => {
+        const src = `requiredShards: ['guml.core', 'sh3-files']`;
+        expect(extractRequiredShardsFromBundle(src)).toEqual(['guml.core', 'sh3-files']);
+    });
+    it('returns empty array when requiredShards is not present', () => {
+        const src = `const Shard = { manifest: { id: "my-shard", views: [] } };`;
+        expect(extractRequiredShardsFromBundle(src)).toEqual([]);
+    });
+    it('returns empty array when requiredShards is empty', () => {
+        const src = `requiredShards: []`;
+        expect(extractRequiredShardsFromBundle(src)).toEqual([]);
+    });
+    it('handles minified format without spaces', () => {
+        const src = `{id:"my-app",requiredShards:["guml.core","other-shard"]}`;
+        expect(extractRequiredShardsFromBundle(src)).toEqual(['guml.core', 'other-shard']);
+    });
+});

package/dist/createShell.js

@@ -22,11 +22,33 @@ 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 { sessionState, readPendingScope, PENDING_SCOPE_KEY } from './projects/session-state.svelte';
 import SatelliteShell from './satellite/SatelliteShell.svelte';
 export async function createShell(config) {
     var _a, _b;
     const sUrl = (_a = config === null || config === void 0 ? void 0 : config.serverUrl) !== null && _a !== void 0 ? _a : '';
+    // 0. Restore pending project scope from a reload-triggered scope switch.
+    //    Written before the previous page reload by switchProjectScope(); must
+    //    be set before bootstrap() so shards activate with the correct scope.
+    const pendingProjectId = readPendingScope();
+    if (pendingProjectId !== null) {
+        sessionState.activeProjectId = pendingProjectId;
+    }
+    // Read ?project= injected by Tauri's --project CLI arg (or any deep-link URL).
+    // Guard against overriding an in-session scope switch that wrote to sessionStorage.
+    if (typeof window !== 'undefined' && pendingProjectId === null) {
+        const urlProject = new URLSearchParams(window.location.search).get('project');
+        if (urlProject) {
+            // Mirror switchProjectScope's sessionStorage write so subsequent reloads
+            // within this tab re-enter the same project (readPendingScope will pick it up).
+            sessionStorage.setItem(PENDING_SCOPE_KEY, JSON.stringify({ projectId: urlProject }));
+            sessionState.activeProjectId = urlProject;
+            // Strip the param so it doesn't linger in bookmarks or history.
+            const cleanUrl = new URL(window.location.href);
+            cleanUrl.searchParams.delete('project');
+            history.replaceState(null, '', cleanUrl.toString());
+        }
+    }
     // 1. Platform detection
     const platform = await resolvePlatform();
     if (platform.backends) {
@@ -60,6 +82,11 @@ 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');
+        // Inherit the host's active project scope so shard activation lands in the
+        // correct tenant (satellite opens in the same project context as the host).
+        if (satellite.payload.projectId) {
+            sessionState.activeProjectId = satellite.payload.projectId;
+        }
         __setScopeResolver(() => sessionState.activeProjectId);
         __setShardScopeResolver(() => sessionState.activeProjectId ? 'project' : 'tenant');
         if (config === null || config === void 0 ? void 0 : config.shards)
@@ -138,19 +165,17 @@ export async function createShell(config) {
         for (const app of config.apps)
             registerApp(app);
     }
-    // 7. Bootstrap
+    // 7. Wire scope resolvers before bootstrap so shards activate in the correct scope.
+    __setScopeResolver(() => sessionState.activeProjectId);
+    __setShardScopeResolver(() => sessionState.activeProjectId ? 'project' : 'tenant');
+    // 8. Bootstrap
     const bootstrapConfig = {};
     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
+    // 9. Attach document-level keyboard / focus listeners
     attachGlobalListeners();
-    // 9. Mount the sh3
+    // 10. Mount the sh3
     mount(Sh3, { target });
 }
 /**

package/dist/documents/browse.d.ts

@@ -108,6 +108,26 @@ export interface BrowseCapability {
         targetShardId?: string;
         delete?: boolean;
     }): Promise<void>;
+    /**
+     * List all documents in an arbitrary tenant. Write-gated — cross-tenant
+     * enumeration is a privileged operation used by xfer -R for cross-scope recursion.
+     *
+     * Absent (undefined) when `documents:write` is not declared.
+     */
+    listDocumentsIn?(tenantId: string): Promise<Array<DocumentMeta & {
+        shardId: string;
+    }>>;
+    /**
+     * Copy or move a document between any two tenants. Neither tenant needs to
+     * be the active one. Emits documentChanges for both source (delete if
+     * opts.delete is true) and destination (create/update). Throws when src
+     * and dst are identical.
+     *
+     * Absent (undefined) when `documents:write` is not declared.
+     */
+    transferBetweenScopes?(srcTenant: string, srcShardId: string, srcPath: string, dstTenant: string, dstShardId: string, dstPath: string, opts?: {
+        delete?: boolean;
+    }): Promise<void>;
 }
 export interface BrowseCapabilityOptions {
     /** When true, the returned capability exposes `readFrom`. */

package/dist/documents/browse.js

@@ -99,6 +99,41 @@ export function createBrowseCapability(getTenantId, backend, options = { canRead
                 documentChanges.emit({ type: 'delete', path, tenantId, shardId });
             }
         };
+        capability.listDocumentsIn = (tenantId) => backend.listAllDocuments(tenantId);
+        capability.transferBetweenScopes = async (srcTenant, srcShard, srcPath, dstTenant, dstShard, dstPath, opts) => {
+            if (srcTenant === dstTenant && srcShard === dstShard && srcPath === dstPath) {
+                throw new Error('transferBetweenScopes: source and destination are identical');
+            }
+            if (backend.xfer) {
+                const { existed } = await backend.xfer(srcTenant, `${srcShard}/${srcPath}`, dstTenant, `${dstShard}/${dstPath}`, { move: opts === null || opts === void 0 ? void 0 : opts.delete });
+                documentChanges.emit({
+                    type: existed ? 'update' : 'create',
+                    path: dstPath,
+                    tenantId: dstTenant,
+                    shardId: dstShard,
+                });
+                if (opts === null || opts === void 0 ? void 0 : opts.delete) {
+                    documentChanges.emit({ type: 'delete', path: srcPath, tenantId: srcTenant, shardId: srcShard });
+                }
+                return;
+            }
+            const content = await backend.read(srcTenant, srcShard, srcPath);
+            if (content === null) {
+                throw new Error(`Document not found at ${srcShard}/${srcPath} in scope ${srcTenant}`);
+            }
+            const existed = await backend.exists(dstTenant, dstShard, dstPath);
+            await backend.write(dstTenant, dstShard, dstPath, content);
+            documentChanges.emit({
+                type: existed ? 'update' : 'create',
+                path: dstPath,
+                tenantId: dstTenant,
+                shardId: dstShard,
+            });
+            if (opts === null || opts === void 0 ? void 0 : opts.delete) {
+                await backend.delete(srcTenant, srcShard, srcPath);
+                documentChanges.emit({ type: 'delete', path: srcPath, tenantId: srcTenant, shardId: srcShard });
+            }
+        };
     }
     return capability;
 }

package/dist/documents/browse.test.js

@@ -304,4 +304,129 @@ describe('BrowseCapability', () => {
             expect(await be.read('t2', 's', 'secret.txt')).toBe('hidden');
         });
     });
+    describe('listDocumentsIn (documents:write gate)', () => {
+        it('is absent when canWrite is false', () => {
+            const be = new MemoryDocumentBackend();
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: false });
+            expect(browse.listDocumentsIn).toBeUndefined();
+        });
+        it('lists documents from an arbitrary tenant, not the active one', async () => {
+            const be = new MemoryDocumentBackend();
+            await be.write('t2', 'notes', 'a.md', 'hello');
+            await be.write('t2', 'notes', 'b.md', 'world');
+            await be.write('t1', 'notes', 'c.md', 'active');
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
+            const docs = await browse.listDocumentsIn('t2');
+            expect(docs.map((d) => d.path).sort()).toEqual(['a.md', 'b.md']);
+        });
+    });
+    describe('transferBetweenScopes (documents:write gate)', () => {
+        it('is absent when canWrite is false', () => {
+            const be = new MemoryDocumentBackend();
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: false });
+            expect(browse.transferBetweenScopes).toBeUndefined();
+        });
+        it('copies a document from one tenant to another and emits create', async () => {
+            const be = new MemoryDocumentBackend();
+            await be.write('t1', 'notes', 'draft.md', 'content');
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
+            const events = [];
+            const unsub = documentChanges.subscribe((c) => events.push(c));
+            await browse.transferBetweenScopes('t1', 'notes', 'draft.md', 't2', 'notes', 'draft.md');
+            expect(await be.read('t2', 'notes', 'draft.md')).toBe('content');
+            expect(await be.read('t1', 'notes', 'draft.md')).toBe('content'); // source intact
+            expect(events).toEqual([
+                { type: 'create', path: 'draft.md', tenantId: 't2', shardId: 'notes' },
+            ]);
+            unsub();
+        });
+        it('deletes source and emits delete when opts.delete is true', async () => {
+            const be = new MemoryDocumentBackend();
+            await be.write('t1', 'notes', 'draft.md', 'content');
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
+            const events = [];
+            const unsub = documentChanges.subscribe((c) => events.push(c));
+            await browse.transferBetweenScopes('t1', 'notes', 'draft.md', 't2', 'notes', 'draft.md', { delete: true });
+            expect(await be.read('t2', 'notes', 'draft.md')).toBe('content');
+            expect(await be.read('t1', 'notes', 'draft.md')).toBeNull();
+            expect(events).toEqual([
+                { type: 'create', path: 'draft.md', tenantId: 't2', shardId: 'notes' },
+                { type: 'delete', path: 'draft.md', tenantId: 't1', shardId: 'notes' },
+            ]);
+            unsub();
+        });
+        it('emits update (not create) when destination already exists', async () => {
+            const be = new MemoryDocumentBackend();
+            await be.write('t1', 'notes', 'draft.md', 'v1');
+            await be.write('t2', 'notes', 'draft.md', 'old');
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
+            const events = [];
+            const unsub = documentChanges.subscribe((c) => events.push(c));
+            await browse.transferBetweenScopes('t1', 'notes', 'draft.md', 't2', 'notes', 'draft.md');
+            expect(events[0].type).toBe('update');
+            unsub();
+        });
+        it('throws when source and destination are identical', async () => {
+            const be = new MemoryDocumentBackend();
+            await be.write('t1', 'notes', 'draft.md', 'x');
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
+            await expect(browse.transferBetweenScopes('t1', 'notes', 'draft.md', 't1', 'notes', 'draft.md')).rejects.toThrow('identical');
+        });
+        it('throws when source document does not exist', async () => {
+            const be = new MemoryDocumentBackend();
+            const browse = createBrowseCapability(() => 't1', be, { canRead: false, canWrite: true });
+            await expect(browse.transferBetweenScopes('t1', 'notes', 'missing.md', 't2', 'notes', 'missing.md')).rejects.toThrow('not found');
+        });
+    });
+});
+describe('transferBetweenScopes', () => {
+    it('delegates to backend.xfer when the method is present', async () => {
+        const xfer = vi.fn(async () => ({ existed: false }));
+        const be = new MemoryDocumentBackend();
+        be.xfer = xfer;
+        const browse = createBrowseCapability(() => 'alice', be, { canRead: true, canWrite: true });
+        await browse.transferBetweenScopes('alice', 'notes', 'draft.md', 'proj-1', 'notes', 'draft.md', { delete: true });
+        expect(xfer).toHaveBeenCalledWith('alice', 'notes/draft.md', 'proj-1', 'notes/draft.md', { move: true });
+    });
+    it('emits create on dst and delete on src when move=true and existed=false', async () => {
+        const changes = [];
+        const unsub = documentChanges.subscribe((c) => changes.push(c));
+        const xfer = vi.fn(async () => ({ existed: false }));
+        const be = new MemoryDocumentBackend();
+        be.xfer = xfer;
+        const browse = createBrowseCapability(() => 'alice', be, { canRead: true, canWrite: true });
+        await browse.transferBetweenScopes('alice', 'notes', 'draft.md', 'proj-1', 'notes', 'draft.md', { delete: true });
+        unsub();
+        expect(changes).toContainEqual(expect.objectContaining({ type: 'create', path: 'draft.md', tenantId: 'proj-1', shardId: 'notes' }));
+        expect(changes).toContainEqual(expect.objectContaining({ type: 'delete', path: 'draft.md', tenantId: 'alice', shardId: 'notes' }));
+    });
+    it('emits update on dst when existed=true', async () => {
+        const changes = [];
+        const unsub = documentChanges.subscribe((c) => changes.push(c));
+        const xfer = vi.fn(async () => ({ existed: true }));
+        const be = new MemoryDocumentBackend();
+        be.xfer = xfer;
+        const browse = createBrowseCapability(() => 'alice', be, { canRead: true, canWrite: true });
+        await browse.transferBetweenScopes('alice', 'notes', 'draft.md', 'proj-1', 'notes', 'draft.md', { delete: false });
+        unsub();
+        expect(changes).toContainEqual(expect.objectContaining({ type: 'update', path: 'draft.md', tenantId: 'proj-1', shardId: 'notes' }));
+    });
+    it('falls back to read+write when backend.xfer is absent', async () => {
+        const be = new MemoryDocumentBackend();
+        await be.write('alice', 'notes', 'draft.md', 'hello');
+        const browse = createBrowseCapability(() => 'alice', be, { canRead: true, canWrite: true });
+        await browse.transferBetweenScopes('alice', 'notes', 'draft.md', 'proj-1', 'notes', 'draft.md', { delete: false });
+        const copied = await be.read('proj-1', 'notes', 'draft.md');
+        expect(copied).toBe('hello');
+        const original = await be.read('alice', 'notes', 'draft.md');
+        expect(original).toBe('hello');
+    });
+    it('falls back to read+write+delete when backend.xfer is absent and delete=true', async () => {
+        const be = new MemoryDocumentBackend();
+        await be.write('alice', 'notes', 'draft.md', 'hello');
+        const browse = createBrowseCapability(() => 'alice', be, { canRead: true, canWrite: true });
+        await browse.transferBetweenScopes('alice', 'notes', 'draft.md', 'proj-1', 'notes', 'draft.md', { delete: true });
+        expect(await be.read('alice', 'notes', 'draft.md')).toBeNull();
+        expect(await be.read('proj-1', 'notes', 'draft.md')).toBe('hello');
+    });
 });

package/dist/documents/config.d.ts

@@ -6,12 +6,8 @@ export declare function __setScopeResolver(resolver: (() => string | null) | nul
 export declare function getActiveScopeId(): string;
 /** The user's base (personal) tenant id — never overridden by the project resolver. */
 export declare function getPersonalScopeId(): string;
-/** @deprecated use getActiveScopeId — kept until callers migrate. */
-export declare function getTenantId(): string;
 export declare function getDocumentBackend(): DocumentBackend;
 /** Host-only. Set the active scope id before bootstrap(). */
 export declare function __setActiveScope(id: string): void;
-/** @deprecated use __setActiveScope — kept until callers migrate. */
-export declare function __setTenantId(id: string): void;
 /** Host-only. Swap the document backend before bootstrap(). */
 export declare function __setDocumentBackend(b: DocumentBackend): void;

package/dist/documents/config.js

@@ -31,10 +31,6 @@ export function getActiveScopeId() {
 export function getPersonalScopeId() {
     return scopeId;
 }
-/** @deprecated use getActiveScopeId — kept until callers migrate. */
-export function getTenantId() {
-    return getActiveScopeId();
-}
 export function getDocumentBackend() {
     return backend;
 }
@@ -42,10 +38,6 @@ export function getDocumentBackend() {
 export function __setActiveScope(id) {
     scopeId = id;
 }
-/** @deprecated use __setActiveScope — kept until callers migrate. */
-export function __setTenantId(id) {
-    __setActiveScope(id);
-}
 /** Host-only. Swap the document backend before bootstrap(). */
 export function __setDocumentBackend(b) {
     backend = b;

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

@@ -31,6 +31,11 @@ export declare class HttpDocumentBackend implements DocumentBackend {
         origin: string;
     } | string): Promise<void>;
     readBranch(tenantId: string, shardId: string, path: string, origin: string): Promise<string | null>;
+    xfer(srcTenant: string, srcPath: string, dstTenant: string, dstPath: string, opts?: {
+        move?: boolean;
+    }): Promise<{
+        existed: boolean;
+    }>;
     rename(tenantId: string, shardId: string, oldPath: string, newPath: string): Promise<void>;
     mkdir(tenantId: string, shardId: string, path: string): Promise<void>;
     rmdir(tenantId: string, shardId: string, path: string, opts: {

package/dist/documents/http-backend.js

@@ -128,6 +128,31 @@ export class HttpDocumentBackend {
             throw new Error(`readBranch failed: ${res.status}`);
         return res.text();
     }
+    async xfer(srcTenant, srcPath, dstTenant, dstPath, opts) {
+        var _a;
+        const url = `${__classPrivateFieldGet(this, _HttpDocumentBackend_baseUrl, "f")}/api/xfer`;
+        const res = await apiFetch(url, {
+            method: 'POST',
+            headers: Object.assign(Object.assign({}, __classPrivateFieldGet(this, _HttpDocumentBackend_instances, "m", _HttpDocumentBackend_authHeaders).call(this)), { 'Content-Type': 'application/json' }),
+            body: JSON.stringify({
+                src: { scope: srcTenant, path: srcPath },
+                dst: { scope: dstTenant, path: dstPath },
+                move: (_a = opts === null || opts === void 0 ? void 0 : opts.move) !== null && _a !== void 0 ? _a : false,
+            }),
+            credentials: 'include',
+        });
+        if (!res.ok) {
+            let detail = `HTTP ${res.status}`;
+            try {
+                const b = await res.json();
+                if (b.error)
+                    detail = b.error;
+            }
+            catch ( /* not JSON */_b) { /* not JSON */ }
+            throw new Error(`xfer failed: ${detail}`);
+        }
+        return res.json();
+    }
     async rename(tenantId, shardId, oldPath, newPath) {
         const url = `${__classPrivateFieldGet(this, _HttpDocumentBackend_baseUrl, "f")}/api/docs/${tenantId}/${shardId}/${oldPath}/rename`;
         const headers = Object.assign(Object.assign({}, __classPrivateFieldGet(this, _HttpDocumentBackend_instances, "m", _HttpDocumentBackend_authHeaders).call(this)), { 'Content-Type': 'application/json' });

package/dist/documents/http-backend.test.js

@@ -129,3 +129,69 @@ describe('HttpDocumentBackend folder ops', () => {
         expect(result).toEqual(['c']);
     });
 });
+describe('HttpDocumentBackend.xfer', () => {
+    afterEach(() => {
+        globalThis.fetch = originalFetch;
+    });
+    it('POSTs to /api/xfer with src, dst, and move in the body', async () => {
+        var _a, _b;
+        const calls = [];
+        globalThis.fetch = (async (url, init) => {
+            calls.push({ url: String(url), init });
+            return new Response(JSON.stringify({ ok: true, existed: false }), { status: 200 });
+        });
+        const be = new HttpDocumentBackend('http://server', 'apikey-1');
+        const result = await be.xfer('alice', 'notes/draft.md', 'proj-1', 'notes/draft.md', { move: true });
+        expect(calls).toHaveLength(1);
+        expect(calls[0].url).toBe('http://server/api/xfer');
+        expect((_a = calls[0].init) === null || _a === void 0 ? void 0 : _a.method).toBe('POST');
+        const body = JSON.parse((_b = calls[0].init) === null || _b === void 0 ? void 0 : _b.body);
+        expect(body).toEqual({
+            src: { scope: 'alice', path: 'notes/draft.md' },
+            dst: { scope: 'proj-1', path: 'notes/draft.md' },
+            move: true,
+        });
+        expect(result).toEqual({ ok: true, existed: false });
+    });
+    it('sends move=false when opts.move is false', async () => {
+        var _a;
+        const calls = [];
+        globalThis.fetch = (async (url, init) => {
+            calls.push({ url: String(url), init });
+            return new Response(JSON.stringify({ ok: true, existed: true }), { status: 200 });
+        });
+        const be = new HttpDocumentBackend('http://server');
+        await be.xfer('alice', 'notes/a.md', 'proj-1', 'notes/a.md', { move: false });
+        const body = JSON.parse((_a = calls[0].init) === null || _a === void 0 ? void 0 : _a.body);
+        expect(body.move).toBe(false);
+    });
+    it('sends move=false when opts is omitted', async () => {
+        var _a;
+        const calls = [];
+        globalThis.fetch = (async (url, init) => {
+            calls.push({ url: String(url), init });
+            return new Response(JSON.stringify({ ok: true, existed: false }), { status: 200 });
+        });
+        const be = new HttpDocumentBackend('http://server');
+        await be.xfer('alice', 'notes/a.md', 'proj-1', 'notes/a.md');
+        const body = JSON.parse((_a = calls[0].init) === null || _a === void 0 ? void 0 : _a.body);
+        expect(body.move).toBe(false);
+    });
+    it('includes Authorization header when apiKey is set', async () => {
+        var _a;
+        const calls = [];
+        globalThis.fetch = (async (url, init) => {
+            calls.push({ url: String(url), init });
+            return new Response(JSON.stringify({ ok: true, existed: false }), { status: 200 });
+        });
+        const be = new HttpDocumentBackend('http://server', 'my-key');
+        await be.xfer('alice', 'notes/a.md', 'proj-1', 'notes/a.md');
+        const headers = (_a = calls[0].init) === null || _a === void 0 ? void 0 : _a.headers;
+        expect(headers['Authorization']).toBe('Bearer my-key');
+    });
+    it('throws with server error message on non-ok response', async () => {
+        globalThis.fetch = (async () => new Response(JSON.stringify({ error: 'Source document not found' }), { status: 404 }));
+        const be = new HttpDocumentBackend('http://server');
+        await expect(be.xfer('alice', 'notes/missing.md', 'proj-1', 'notes/missing.md')).rejects.toThrow('Source document not found');
+    });
+});

package/dist/documents/index.d.ts

@@ -3,6 +3,6 @@ export { MemoryDocumentBackend, IndexedDBDocumentBackend } from './backends';
 export { HttpDocumentBackend } from './http-backend';
 export { createDocumentHandle } from './handle';
 export { documentChanges } from './notifications';
-export { getActiveScopeId, getTenantId, getDocumentBackend, __setActiveScope, __setTenantId, __setDocumentBackend, __setScopeResolver, } from './config';
+export { getActiveScopeId, getDocumentBackend, __setActiveScope, __setDocumentBackend, __setScopeResolver, } from './config';
 export type { SyncPolicy, SyncPolicyRule, DocStatus, ConflictFile, ConflictBranch, } from './sync-types';
 export { PERMISSION_SYNC_PEER, PERMISSION_SYNC_POLICY, } from './sync-types';