sh3-core 0.20.1 → 0.20.3

package/dist/documents/backends.test.js

@@ -1,5 +1,5 @@
 import 'fake-indexeddb/auto';
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, beforeEach } from 'vitest';
 import { MemoryDocumentBackend, IndexedDBDocumentBackend } from './backends';
 describe('DocumentBackend tenant-wide primitives', () => {
     it('listAllShards returns every shard that has content for a tenant', async () => {
@@ -99,3 +99,149 @@ describe('IndexedDBDocumentBackend.rename', () => {
             .rejects.toThrow(/not found/);
     });
 });
+describe('MemoryDocumentBackend folder ops', () => {
+    let backend;
+    beforeEach(() => { backend = new MemoryDocumentBackend(); });
+    it('mkdir creates an empty folder visible via listFolders', async () => {
+        await backend.mkdir('t', 's', 'a');
+        expect(await backend.listFolders('t', 's', '')).toEqual(['a']);
+    });
+    it('mkdir is a no-op if the folder already exists', async () => {
+        await backend.mkdir('t', 's', 'a');
+        await backend.mkdir('t', 's', 'a');
+        expect(await backend.listFolders('t', 's', '')).toEqual(['a']);
+    });
+    it('mkdir throws if a document occupies the path', async () => {
+        await backend.write('t', 's', 'a', 'content');
+        await expect(backend.mkdir('t', 's', 'a')).rejects.toThrow();
+    });
+    it('listFolders surfaces folders implied by document paths', async () => {
+        await backend.write('t', 's', 'sub/a.md', 'x');
+        expect(await backend.listFolders('t', 's', '')).toEqual(['sub']);
+    });
+    it('listFolders merges explicit and implicit folders without duplicates', async () => {
+        await backend.mkdir('t', 's', 'sub');
+        await backend.write('t', 's', 'sub/a.md', 'x');
+        expect(await backend.listFolders('t', 's', '')).toEqual(['sub']);
+    });
+    it('listFolders with prefix returns immediate children', async () => {
+        await backend.mkdir('t', 's', 'a/b');
+        await backend.mkdir('t', 's', 'a/c');
+        await backend.write('t', 's', 'a/d/x.md', 'x');
+        const children = await backend.listFolders('t', 's', 'a');
+        expect(children.sort()).toEqual(['b', 'c', 'd']);
+    });
+    it('rmdir on non-empty folder without recursive throws', async () => {
+        await backend.write('t', 's', 'a/x.md', 'x');
+        await expect(backend.rmdir('t', 's', 'a', { recursive: false })).rejects.toThrow();
+    });
+    it('rmdir on empty folder without recursive succeeds', async () => {
+        await backend.mkdir('t', 's', 'a');
+        await backend.rmdir('t', 's', 'a', { recursive: false });
+        expect(await backend.listFolders('t', 's', '')).toEqual([]);
+    });
+    it('rmdir recursive removes folder and all descendants', async () => {
+        await backend.write('t', 's', 'a/x.md', 'x');
+        await backend.write('t', 's', 'a/b/y.md', 'y');
+        await backend.mkdir('t', 's', 'a/empty');
+        await backend.rmdir('t', 's', 'a', { recursive: true });
+        expect(await backend.listFolders('t', 's', '')).toEqual([]);
+        expect(await backend.list('t', 's')).toEqual([]);
+    });
+    it('renameFolder rewrites all descendant doc paths', async () => {
+        await backend.write('t', 's', 'old/x.md', 'x');
+        await backend.write('t', 's', 'old/sub/y.md', 'y');
+        await backend.renameFolder('t', 's', 'old', 'new');
+        const docs = (await backend.list('t', 's')).map((d) => d.path).sort();
+        expect(docs).toEqual(['new/sub/y.md', 'new/x.md']);
+    });
+    it('renameFolder rewrites empty subfolders too', async () => {
+        await backend.mkdir('t', 's', 'old/empty');
+        await backend.renameFolder('t', 's', 'old', 'new');
+        expect((await backend.listFolders('t', 's', 'new')).sort()).toEqual(['empty']);
+    });
+    it('renameFolder throws if newPath already exists', async () => {
+        await backend.mkdir('t', 's', 'a');
+        await backend.mkdir('t', 's', 'b');
+        await expect(backend.renameFolder('t', 's', 'a', 'b')).rejects.toThrow();
+    });
+    it('renameFolder throws if oldPath does not exist', async () => {
+        await expect(backend.renameFolder('t', 's', 'missing', 'b')).rejects.toThrow();
+    });
+});
+describe('IndexedDBDocumentBackend folder ops', () => {
+    let backend;
+    let t;
+    let s;
+    beforeEach(() => {
+        backend = new IndexedDBDocumentBackend();
+        t = 'tenant_' + Math.random().toString(36).slice(2, 10);
+        s = 'shard_' + Math.random().toString(36).slice(2, 10);
+    });
+    it('mkdir creates an empty folder visible via listFolders', async () => {
+        await backend.mkdir(t, s, 'a');
+        expect(await backend.listFolders(t, s, '')).toEqual(['a']);
+    });
+    it('mkdir is a no-op if the folder already exists', async () => {
+        await backend.mkdir(t, s, 'a');
+        await backend.mkdir(t, s, 'a');
+        expect(await backend.listFolders(t, s, '')).toEqual(['a']);
+    });
+    it('mkdir throws if a document occupies the path', async () => {
+        await backend.write(t, s, 'a', 'content');
+        await expect(backend.mkdir(t, s, 'a')).rejects.toThrow();
+    });
+    it('listFolders surfaces folders implied by document paths', async () => {
+        await backend.write(t, s, 'sub/a.md', 'x');
+        expect(await backend.listFolders(t, s, '')).toEqual(['sub']);
+    });
+    it('listFolders merges explicit and implicit folders without duplicates', async () => {
+        await backend.mkdir(t, s, 'sub');
+        await backend.write(t, s, 'sub/a.md', 'x');
+        expect(await backend.listFolders(t, s, '')).toEqual(['sub']);
+    });
+    it('listFolders with prefix returns immediate children', async () => {
+        await backend.mkdir(t, s, 'a/b');
+        await backend.mkdir(t, s, 'a/c');
+        await backend.write(t, s, 'a/d/x.md', 'x');
+        const children = await backend.listFolders(t, s, 'a');
+        expect(children.sort()).toEqual(['b', 'c', 'd']);
+    });
+    it('rmdir on non-empty folder without recursive throws', async () => {
+        await backend.write(t, s, 'a/x.md', 'x');
+        await expect(backend.rmdir(t, s, 'a', { recursive: false })).rejects.toThrow();
+    });
+    it('rmdir on empty folder without recursive succeeds', async () => {
+        await backend.mkdir(t, s, 'a');
+        await backend.rmdir(t, s, 'a', { recursive: false });
+        expect(await backend.listFolders(t, s, '')).toEqual([]);
+    });
+    it('rmdir recursive removes folder and all descendants', async () => {
+        await backend.write(t, s, 'a/x.md', 'x');
+        await backend.write(t, s, 'a/b/y.md', 'y');
+        await backend.mkdir(t, s, 'a/empty');
+        await backend.rmdir(t, s, 'a', { recursive: true });
+        expect(await backend.listFolders(t, s, '')).toEqual([]);
+        expect(await backend.list(t, s)).toEqual([]);
+    });
+    it('renameFolder rewrites all descendant doc paths', async () => {
+        await backend.write(t, s, 'old/x.md', 'x');
+        await backend.write(t, s, 'old/sub/y.md', 'y');
+        await backend.renameFolder(t, s, 'old', 'new');
+        const docs = (await backend.list(t, s)).map((d) => d.path).sort();
+        expect(docs).toEqual(['new/sub/y.md', 'new/x.md']);
+    });
+    it('renameFolder rewrites empty subfolders too', async () => {
+        await backend.mkdir(t, s, 'old/empty');
+        await backend.renameFolder(t, s, 'old', 'new');
+        expect((await backend.listFolders(t, s, 'new')).sort()).toEqual(['empty']);
+    });
+    it('renameFolder throws if newPath already exists', async () => {
+        await backend.mkdir(t, s, 'a');
+        await backend.mkdir(t, s, 'b');
+        await expect(backend.renameFolder(t, s, 'a', 'b')).rejects.toThrow();
+    });
+    it('renameFolder throws if oldPath does not exist', async () => {
+        await expect(backend.renameFolder(t, s, 'missing', 'b')).rejects.toThrow();
+    });
+});

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

@@ -4,12 +4,10 @@ import type { DocumentBackend } from './types';
  *  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;
+/** The user's base (personal) tenant id — never overridden by the project resolver. */
+export declare function getPersonalScopeId(): 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

@@ -27,9 +27,9 @@ export function getActiveScopeId() {
     var _a;
     return (_a = scopeResolver === null || scopeResolver === void 0 ? void 0 : scopeResolver()) !== null && _a !== void 0 ? _a : scopeId;
 }
-/** @deprecated use getActiveScopeId — kept until callers migrate. */
-export function getTenantId() {
-    return getActiveScopeId();
+/** The user's base (personal) tenant id — never overridden by the project resolver. */
+export function getPersonalScopeId() {
+    return scopeId;
 }
 export function getDocumentBackend() {
     return backend;
@@ -38,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/handle.js

@@ -86,6 +86,46 @@ export function createDocumentHandle(tenantId, shardId, backend, options) {
                 shardId,
             });
         },
+        async mkdir(path, opts) {
+            const tid = resolveTenant(opts);
+            await backend.mkdir(tid, shardId, path);
+            documentChanges.emit({ type: 'folder-create', path, tenantId: tid, shardId });
+        },
+        async rmdir(path, opts) {
+            var _a;
+            const recursive = (_a = opts === null || opts === void 0 ? void 0 : opts.recursive) !== null && _a !== void 0 ? _a : false;
+            if (recursive) {
+                const folderPrefix = path + '/';
+                for (const ctrl of controllers) {
+                    if (ctrl.path === path || ctrl.path.startsWith(folderPrefix)) {
+                        throw new Error(`Cannot rmdir ${path}: active autosave on ${ctrl.path}; flush and dispose first`);
+                    }
+                }
+            }
+            const tid = resolveTenant(opts);
+            await backend.rmdir(tid, shardId, path, { recursive });
+            documentChanges.emit({ type: 'folder-delete', path, tenantId: tid, shardId });
+        },
+        async renameFolder(oldPath, newPath, opts) {
+            const folderPrefix = oldPath + '/';
+            for (const ctrl of controllers) {
+                if (ctrl.path === oldPath || ctrl.path.startsWith(folderPrefix)) {
+                    throw new Error(`Cannot rename folder ${oldPath}: active autosave on ${ctrl.path}; flush and dispose first`);
+                }
+            }
+            const tid = resolveTenant(opts);
+            await backend.renameFolder(tid, shardId, oldPath, newPath);
+            documentChanges.emit({
+                type: 'folder-rename',
+                path: newPath,
+                oldPath,
+                tenantId: tid,
+                shardId,
+            });
+        },
+        async listFolders(prefix, opts) {
+            return backend.listFolders(resolveTenant(opts), shardId, prefix !== null && prefix !== void 0 ? prefix : '');
+        },
         async exists(path) {
             return backend.exists(tenantId, shardId, path);
         },

package/dist/documents/handle.test.js

@@ -1,4 +1,4 @@
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, beforeEach } from 'vitest';
 import { MemoryDocumentBackend } from './backends';
 import { createDocumentHandle } from './handle';
 import { documentChanges } from './notifications';
@@ -28,6 +28,10 @@ describe('DocumentHandle.status()', () => {
             async exists() { return false; },
             async listAllShards() { return []; },
             async listAllDocuments() { return []; },
+            async mkdir() { },
+            async rmdir() { },
+            async renameFolder() { },
+            async listFolders() { return []; },
         };
         const handle = createDocumentHandle('t', 's', backend, { format: 'text' });
         await expect(handle.status('a.txt')).rejects.toThrow(/status/);
@@ -46,6 +50,10 @@ describe('DocumentHandle.resolveConflict()', () => {
             async listAllShards() { return []; },
             async listAllDocuments() { return []; },
             async resolve(t, s, p, c) { resolved.push({ t, s, p, c }); },
+            async mkdir() { },
+            async rmdir() { },
+            async renameFolder() { },
+            async listFolders() { return []; },
         };
         const handle = createDocumentHandle('tenant1', 'shard1', backend, { format: 'text' });
         await handle.resolveConflict('a.txt', 'local');
@@ -69,6 +77,10 @@ describe('DocumentHandle.readBranch()', () => {
             async listAllShards() { return []; },
             async listAllDocuments() { return []; },
             async readBranch(...args) { calls.push(args); return 'remote-content'; },
+            async mkdir() { },
+            async rmdir() { },
+            async renameFolder() { },
+            async listFolders() { return []; },
         };
         const handle = createDocumentHandle('tenant1', 'shard1', backend, { format: 'text' });
         const out = await handle.readBranch('a.txt', 'peer-1');
@@ -86,6 +98,10 @@ describe('DocumentHandle.readBranch()', () => {
             async listAllShards() { return []; },
             async listAllDocuments() { return []; },
             async readBranch() { return null; },
+            async mkdir() { },
+            async rmdir() { },
+            async renameFolder() { },
+            async listFolders() { return []; },
         };
         const handle = createDocumentHandle('t', 's', backend, { format: 'text' });
         expect(await handle.readBranch('a.txt', 'peer-1')).toBeNull();
@@ -164,3 +180,74 @@ describe('DocumentHandle.delete()', () => {
         unsub();
     });
 });
+describe('DocumentHandle folder ops', () => {
+    let backend;
+    let handle;
+    beforeEach(() => {
+        backend = new MemoryDocumentBackend();
+        handle = createDocumentHandle('t', 's', backend, { format: 'text' });
+    });
+    it('mkdir forwards to backend with bound tenant/shard', async () => {
+        await handle.mkdir('a');
+        expect(await backend.listFolders('t', 's', '')).toEqual(['a']);
+    });
+    it('rmdir defaults recursive to false', async () => {
+        await handle.write('a/x.md', 'x');
+        await expect(handle.rmdir('a')).rejects.toThrow();
+    });
+    it('rmdir({recursive:true}) cascades', async () => {
+        await handle.write('a/x.md', 'x');
+        await handle.rmdir('a', { recursive: true });
+        expect(await handle.list()).toEqual([]);
+    });
+    it('renameFolder rewrites descendant paths', async () => {
+        await handle.write('old/x.md', 'x');
+        await handle.renameFolder('old', 'new');
+        const docs = (await handle.list()).map((d) => d.path).sort();
+        expect(docs).toEqual(['new/x.md']);
+    });
+    it('renameFolder refused when an autosave controller is inside the folder', async () => {
+        const ctrl = handle.autosave('a/x.md');
+        ctrl.update('content');
+        await expect(handle.renameFolder('a', 'b')).rejects.toThrow(/autosave/i);
+        await ctrl.dispose();
+    });
+    it('rmdir(recursive) refused when an autosave controller is inside the folder', async () => {
+        const ctrl = handle.autosave('a/x.md');
+        ctrl.update('content');
+        await expect(handle.rmdir('a', { recursive: true })).rejects.toThrow(/autosave/i);
+        await ctrl.dispose();
+    });
+    it('listFolders forwards to backend', async () => {
+        await handle.mkdir('a');
+        expect(await handle.listFolders()).toEqual(['a']);
+        expect(await handle.listFolders('a')).toEqual([]);
+    });
+    it('mkdir emits folder-create change event', async () => {
+        const events = [];
+        handle.watch((c) => events.push(c));
+        await handle.mkdir('a');
+        expect(events).toEqual([
+            { type: 'folder-create', path: 'a', tenantId: 't', shardId: 's' },
+        ]);
+    });
+    it('rmdir(recursive) emits a single folder-delete event', async () => {
+        await handle.write('a/x.md', 'x');
+        await handle.write('a/y.md', 'y');
+        const events = [];
+        handle.watch((c) => events.push(c));
+        await handle.rmdir('a', { recursive: true });
+        expect(events).toEqual([
+            { type: 'folder-delete', path: 'a', tenantId: 't', shardId: 's' },
+        ]);
+    });
+    it('renameFolder emits a single folder-rename event', async () => {
+        await handle.write('old/x.md', 'x');
+        const events = [];
+        handle.watch((c) => events.push(c));
+        await handle.renameFolder('old', 'new');
+        expect(events).toEqual([
+            { type: 'folder-rename', path: 'new', oldPath: 'old', tenantId: 't', shardId: 's' },
+        ]);
+    });
+});

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

@@ -31,5 +31,16 @@ 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: {
+        recursive: boolean;
+    }): Promise<void>;
+    renameFolder(tenantId: string, shardId: string, oldPath: string, newPath: string): Promise<void>;
+    listFolders(tenantId: string, shardId: string, prefix: string): Promise<string[]>;
 }