sh3-core 0.19.6 → 0.20.2

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

@@ -32,4 +32,10 @@ export declare class HttpDocumentBackend implements DocumentBackend {
     } | string): Promise<void>;
     readBranch(tenantId: string, shardId: string, path: string, origin: string): Promise<string | null>;
     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[]>;
 }

package/dist/documents/http-backend.js

@@ -52,8 +52,16 @@ export class HttpDocumentBackend {
         const url = `${__classPrivateFieldGet(this, _HttpDocumentBackend_baseUrl, "f")}/api/docs/${tenantId}/${shardId}/${path}`;
         const headers = Object.assign(Object.assign({}, __classPrivateFieldGet(this, _HttpDocumentBackend_instances, "m", _HttpDocumentBackend_authHeaders).call(this)), { 'Content-Type': typeof content === 'string' ? 'text/plain' : 'application/octet-stream' });
         const res = await apiFetch(url, { method: 'PUT', headers, body: content, credentials: 'include' });
-        if (!res.ok)
-            throw new Error(`Document write failed: ${res.status}`);
+        if (!res.ok) {
+            let detail = `HTTP ${res.status}`;
+            try {
+                const b = await res.json();
+                if (b.error)
+                    detail = b.error;
+            }
+            catch ( /* body not JSON */_a) { /* body not JSON */ }
+            throw new Error(`Document write failed: ${detail}`);
+        }
     }
     async delete(tenantId, shardId, path) {
         const url = `${__classPrivateFieldGet(this, _HttpDocumentBackend_baseUrl, "f")}/api/docs/${tenantId}/${shardId}/${path}`;
@@ -139,6 +147,67 @@ export class HttpDocumentBackend {
             throw new Error(`Document rename failed: ${res.status}`);
         }
     }
+    async mkdir(tenantId, shardId, path) {
+        const url = `${__classPrivateFieldGet(this, _HttpDocumentBackend_baseUrl, "f")}/api/docs/${tenantId}/${shardId}/${path}/mkdir`;
+        const res = await apiFetch(url, {
+            method: 'POST',
+            headers: __classPrivateFieldGet(this, _HttpDocumentBackend_instances, "m", _HttpDocumentBackend_authHeaders).call(this),
+            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 */_a) { /* not JSON */ }
+            throw new Error(`mkdir failed: ${detail}`);
+        }
+    }
+    async rmdir(tenantId, shardId, path, opts) {
+        const url = `${__classPrivateFieldGet(this, _HttpDocumentBackend_baseUrl, "f")}/api/docs/${tenantId}/${shardId}/${path}/rmdir`;
+        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({ recursive: opts.recursive }),
+            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 */_a) { /* not JSON */ }
+            throw new Error(`rmdir failed: ${detail}`);
+        }
+    }
+    async renameFolder(tenantId, shardId, oldPath, newPath) {
+        const url = `${__classPrivateFieldGet(this, _HttpDocumentBackend_baseUrl, "f")}/api/docs/${tenantId}/${shardId}/${oldPath}/rename-folder`;
+        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({ to: newPath }),
+            credentials: 'include',
+        });
+        if (res.status === 404)
+            throw new Error(`Folder not found at ${oldPath}`);
+        if (res.status === 409)
+            throw new Error(`Folder already exists at ${newPath}`);
+        if (!res.ok)
+            throw new Error(`renameFolder failed: ${res.status}`);
+    }
+    async listFolders(tenantId, shardId, prefix) {
+        const base = prefix
+            ? `${__classPrivateFieldGet(this, _HttpDocumentBackend_baseUrl, "f")}/api/docs/${tenantId}/${shardId}/${prefix}?folders=1`
+            : `${__classPrivateFieldGet(this, _HttpDocumentBackend_baseUrl, "f")}/api/docs/${tenantId}/${shardId}?folders=1`;
+        const res = await apiFetch(base, { credentials: 'include' });
+        if (!res.ok)
+            throw new Error(`listFolders failed: ${res.status}`);
+        return res.json();
+    }
 }
 _HttpDocumentBackend_baseUrl = new WeakMap(), _HttpDocumentBackend_apiKey = new WeakMap(), _HttpDocumentBackend_instances = new WeakSet(), _HttpDocumentBackend_authHeaders = function _HttpDocumentBackend_authHeaders() {
     if (!__classPrivateFieldGet(this, _HttpDocumentBackend_apiKey, "f"))

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

@@ -1,4 +1,4 @@
-import { describe, it, expect, afterEach } from 'vitest';
+import { describe, it, expect, afterEach, vi } from 'vitest';
 import { HttpDocumentBackend } from './http-backend';
 const originalFetch = globalThis.fetch;
 describe('HttpDocumentBackend.readBranch', () => {
@@ -79,3 +79,53 @@ describe('HttpDocumentBackend.rename', () => {
             .rejects.toThrow(/rename failed/i);
     });
 });
+describe('HttpDocumentBackend folder ops', () => {
+    afterEach(() => {
+        globalThis.fetch = originalFetch;
+    });
+    it('mkdir POSTs to /:path/mkdir', async () => {
+        const fetchMock = vi.fn().mockResolvedValue(new Response(JSON.stringify({ ok: true }), { status: 200 }));
+        globalThis.fetch = fetchMock;
+        const backend = new HttpDocumentBackend('http://server');
+        await backend.mkdir('t', 's', 'a/b');
+        expect(fetchMock).toHaveBeenCalledWith('http://server/api/docs/t/s/a/b/mkdir', expect.objectContaining({ method: 'POST' }));
+    });
+    it('rmdir POSTs to /:path/rmdir with recursive flag', async () => {
+        const fetchMock = vi.fn().mockResolvedValue(new Response(JSON.stringify({ ok: true }), { status: 200 }));
+        globalThis.fetch = fetchMock;
+        const backend = new HttpDocumentBackend('http://server');
+        await backend.rmdir('t', 's', 'a', { recursive: true });
+        const call = fetchMock.mock.calls[0];
+        expect(call[0]).toBe('http://server/api/docs/t/s/a/rmdir');
+        const body = JSON.parse(call[1].body);
+        expect(body).toEqual({ recursive: true });
+    });
+    it('rmdir throws on 409', async () => {
+        globalThis.fetch = vi.fn().mockResolvedValue(new Response(JSON.stringify({ error: 'not empty' }), { status: 409 }));
+        const backend = new HttpDocumentBackend('http://server');
+        await expect(backend.rmdir('t', 's', 'a', { recursive: false })).rejects.toThrow();
+    });
+    it('renameFolder POSTs to /:path/rename-folder with { to }', async () => {
+        const fetchMock = vi.fn().mockResolvedValue(new Response(JSON.stringify({ ok: true }), { status: 200 }));
+        globalThis.fetch = fetchMock;
+        const backend = new HttpDocumentBackend('http://server');
+        await backend.renameFolder('t', 's', 'old', 'new');
+        const call = fetchMock.mock.calls[0];
+        expect(call[0]).toBe('http://server/api/docs/t/s/old/rename-folder');
+        expect(JSON.parse(call[1].body)).toEqual({ to: 'new' });
+    });
+    it('listFolders at root uses ?folders=1 on the shard list URL', async () => {
+        globalThis.fetch = vi.fn().mockResolvedValue(new Response(JSON.stringify(['a', 'b']), { status: 200 }));
+        const backend = new HttpDocumentBackend('http://server');
+        const result = await backend.listFolders('t', 's', '');
+        expect(globalThis.fetch).toHaveBeenCalledWith('http://server/api/docs/t/s?folders=1', expect.any(Object));
+        expect(result).toEqual(['a', 'b']);
+    });
+    it('listFolders with prefix uses ?folders=1 on the path URL', async () => {
+        globalThis.fetch = vi.fn().mockResolvedValue(new Response(JSON.stringify(['c']), { status: 200 }));
+        const backend = new HttpDocumentBackend('http://server');
+        const result = await backend.listFolders('t', 's', 'a');
+        expect(globalThis.fetch).toHaveBeenCalledWith('http://server/api/docs/t/s/a?folders=1', expect.any(Object));
+        expect(result).toEqual(['c']);
+    });
+});

package/dist/documents/index.d.ts

@@ -1,8 +1,8 @@
-export type { DocumentFormat, DocumentHandleOptions, DocumentMeta, DocumentChange, DocumentBackend, DocumentHandle, AutosaveController, } from './types';
+export type { DocumentFormat, DocumentHandleOptions, DocumentMeta, DocumentChange, DocumentBackend, DocumentHandle, AutosaveController, ScopeOption, } from './types';
 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, } from './config';
+export { getActiveScopeId, getTenantId, getDocumentBackend, __setActiveScope, __setTenantId, __setDocumentBackend, __setScopeResolver, } from './config';
 export type { SyncPolicy, SyncPolicyRule, DocStatus, ConflictFile, ConflictBranch, } from './sync-types';
 export { PERMISSION_SYNC_PEER, PERMISSION_SYNC_POLICY, } from './sync-types';

package/dist/documents/index.js

@@ -5,5 +5,5 @@ 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, } from './config';
+export { getActiveScopeId, getTenantId, getDocumentBackend, __setActiveScope, __setTenantId, __setDocumentBackend, __setScopeResolver, } from './config';
 export { PERMISSION_SYNC_PEER, PERMISSION_SYNC_POLICY, } from './sync-types';

package/dist/documents/picker-api.d.ts

@@ -3,14 +3,16 @@ import type { DocEntry, OpenerValue, SaverValue } from '../primitives/widgets/Do
 export type DocListFn = () => Promise<DocEntry[]>;
 /** Options for `ctx.documentPicker.open()`. */
 export interface DocumentOpenOptions {
-    /** Element to anchor the popup to. Defaults to viewport center. */
+    /** When set, the browser opens as a popup anchored to this element.
+     *  When omitted (default), the browser opens as a centered modal. */
     anchor?: HTMLElement;
 }
 /** Options for `ctx.documentPicker.save()`. */
 export interface DocumentSaveOptions {
     /** Pre-fill the filename input in the save dialog. */
     suggestedName?: string;
-    /** Element to anchor the popup to. Defaults to viewport center. */
+    /** When set, the browser opens as a popup anchored to this element.
+     *  When omitted (default), the browser opens as a centered modal. */
     anchor?: HTMLElement;
 }
 /** Programmatic document picker API — available on `ctx.documentPicker`. */

package/dist/documents/picker-api.test.d.ts

@@ -1 +1 @@
-export {};
+import '../sh3Runtime.svelte';

package/dist/documents/picker-api.test.js

@@ -1,35 +1,41 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { sh3 } from '../sh3Runtime.svelte';
+import '../sh3Runtime.svelte'; // intercepted by vi.mock below
 import { createDocumentPicker } from './picker-primitive';
+const { mockPopupShow, mockModalOpen } = vi.hoisted(() => ({
+    mockPopupShow: vi.fn(),
+    mockModalOpen: vi.fn(),
+}));
 vi.mock('../sh3Runtime.svelte', () => ({
     sh3: {
-        popup: {
-            show: vi.fn(),
-        },
+        popup: { show: mockPopupShow },
+        modal: { open: mockModalOpen },
     },
 }));
-const mockShow = sh3.popup.show;
 function mockPopup() {
-    let capturedCommit = null;
-    let capturedCancel = null;
-    const handle = {
-        close: vi.fn(),
+    let captured = null;
+    const handle = { close: vi.fn() };
+    mockPopupShow.mockImplementation((_Content, _opts, props) => {
+        captured = props;
+        return handle;
+    });
+    return {
+        commit: (v) => { captured === null || captured === void 0 ? void 0 : captured.onCommit(v); },
+        cancel: () => { captured === null || captured === void 0 ? void 0 : captured.onCancel(); },
+        dismiss: () => { handle.close(); },
+        handle,
     };
-    mockShow.mockImplementation((_Content, _opts, props) => {
-        capturedCommit = props.onCommit;
-        capturedCancel = props.onCancel;
+}
+function mockModal() {
+    let captured = null;
+    const handle = { close: vi.fn() };
+    mockModalOpen.mockImplementation((_Content, props) => {
+        captured = props;
         return handle;
     });
     return {
-        commit: (v) => {
-            capturedCommit === null || capturedCommit === void 0 ? void 0 : capturedCommit(v);
-        },
-        cancel: () => {
-            capturedCancel === null || capturedCancel === void 0 ? void 0 : capturedCancel();
-        },
-        dismiss: () => {
-            handle.close();
-        },
+        commit: (v) => { captured === null || captured === void 0 ? void 0 : captured.onCommit(v); },
+        cancel: () => { captured === null || captured === void 0 ? void 0 : captured.onCancel(); },
+        dismiss: () => { handle.close(); },
         handle,
     };
 }
@@ -37,35 +43,36 @@ beforeEach(() => {
     vi.clearAllMocks();
 });
 describe('createDocumentPicker', () => {
-    const sampleDoc = { shardId: 'my-shard', path: 'readme.md' };
-    describe('open()', () => {
+    const sampleDoc = { shardId: 'my-shard', path: 'readme.md', kind: 'file' };
+    describe('open() — modal (no anchor)', () => {
         it('resolves with OpenerValue when user commits', async () => {
             const listFn = async () => [{ shardId: 'my-shard', path: 'readme.md', size: 100, lastModified: 0 }];
             const picker = createDocumentPicker(listFn);
-            const popup = mockPopup();
+            const modal = mockModal();
             const promise = picker.open();
-            await vi.waitFor(() => expect(mockShow).toHaveBeenCalledOnce());
-            popup.commit(sampleDoc);
+            await vi.waitFor(() => expect(mockModalOpen).toHaveBeenCalledOnce());
+            modal.commit(sampleDoc);
             const result = await promise;
-            expect(result).toEqual({ shardId: 'my-shard', path: 'readme.md' });
+            expect(result).toEqual({ shardId: 'my-shard', path: 'readme.md', kind: 'file' });
+            expect(mockPopupShow).not.toHaveBeenCalled();
         });
         it('resolves with null when user cancels', async () => {
             const listFn = async () => [];
             const picker = createDocumentPicker(listFn);
-            const popup = mockPopup();
+            const modal = mockModal();
             const promise = picker.open();
-            await vi.waitFor(() => expect(mockShow).toHaveBeenCalledOnce());
-            popup.cancel();
+            await vi.waitFor(() => expect(mockModalOpen).toHaveBeenCalledOnce());
+            modal.cancel();
             const result = await promise;
             expect(result).toBeNull();
         });
-        it('resolves with null when popup is dismissed externally', async () => {
+        it('resolves with null when modal is dismissed externally', async () => {
             const listFn = async () => [];
             const picker = createDocumentPicker(listFn);
-            const popup = mockPopup();
+            const modal = mockModal();
             const promise = picker.open();
-            await vi.waitFor(() => expect(mockShow).toHaveBeenCalledOnce());
-            popup.dismiss();
+            await vi.waitFor(() => expect(mockModalOpen).toHaveBeenCalledOnce());
+            modal.dismiss();
             const result = await promise;
             expect(result).toBeNull();
         });
@@ -74,59 +81,82 @@ describe('createDocumentPicker', () => {
             const picker = createDocumentPicker(listFn);
             const promise = picker.open();
             await expect(promise).rejects.toThrow('network error');
-            expect(mockShow).not.toHaveBeenCalled();
+            expect(mockModalOpen).not.toHaveBeenCalled();
+            expect(mockPopupShow).not.toHaveBeenCalled();
         });
-        it('uses anchor element position when provided', async () => {
+        it('passes mode and dismissOnBackdrop to modal', async () => {
+            const listFn = async () => [];
+            const picker = createDocumentPicker(listFn);
+            mockModal();
+            picker.open();
+            await vi.waitFor(() => expect(mockModalOpen).toHaveBeenCalledOnce());
+            const call = mockModalOpen.mock.calls[0];
+            expect(call[1].mode).toBe('open');
+            expect(call[2]).toEqual({ dismissOnBackdrop: true, boxStyle: 'max-width: min(800px, 95vw);' });
+        });
+    });
+    describe('open() — popup (with anchor)', () => {
+        it('uses popup when anchor element is provided', async () => {
             const listFn = async () => [];
             const picker = createDocumentPicker(listFn);
             mockPopup();
             const el = document.createElement('div');
             picker.open({ anchor: el });
-            await vi.waitFor(() => expect(mockShow).toHaveBeenCalledOnce());
-            const call = mockShow.mock.calls[0];
+            await vi.waitFor(() => expect(mockPopupShow).toHaveBeenCalledOnce());
+            expect(mockModalOpen).not.toHaveBeenCalled();
+            const call = mockPopupShow.mock.calls[0];
             expect(call[1].anchor).toEqual({ x: 0, y: 0 });
         });
     });
-    describe('save()', () => {
+    describe('save() — modal (no anchor)', () => {
         it('resolves with SaverValue string when user commits a filename', async () => {
             const listFn = async () => [];
             const picker = createDocumentPicker(listFn);
-            const popup = mockPopup();
+            const modal = mockModal();
             const promise = picker.save();
-            await vi.waitFor(() => expect(mockShow).toHaveBeenCalledOnce());
-            popup.commit('my-shard/report.txt');
+            await vi.waitFor(() => expect(mockModalOpen).toHaveBeenCalledOnce());
+            modal.commit('my-shard/report.txt');
             const result = await promise;
             expect(result).toBe('my-shard/report.txt');
         });
         it('resolves with null when user cancels', async () => {
             const listFn = async () => [];
             const picker = createDocumentPicker(listFn);
-            const popup = mockPopup();
+            const modal = mockModal();
             const promise = picker.save();
-            await vi.waitFor(() => expect(mockShow).toHaveBeenCalledOnce());
-            popup.cancel();
+            await vi.waitFor(() => expect(mockModalOpen).toHaveBeenCalledOnce());
+            modal.cancel();
             const result = await promise;
             expect(result).toBeNull();
         });
         it('passes suggestedName as prop', async () => {
             const listFn = async () => [];
             const picker = createDocumentPicker(listFn);
-            mockPopup();
+            mockModal();
             picker.save({ suggestedName: 'draft.txt' });
-            await vi.waitFor(() => expect(mockShow).toHaveBeenCalledOnce());
-            const call = mockShow.mock.calls[0];
-            expect(call[2].suggestedName).toBe('draft.txt');
+            await vi.waitFor(() => expect(mockModalOpen).toHaveBeenCalledOnce());
+            const call = mockModalOpen.mock.calls[0];
+            expect(call[1].suggestedName).toBe('draft.txt');
+        });
+        it('passes mode to modal', async () => {
+            const listFn = async () => [];
+            const picker = createDocumentPicker(listFn);
+            mockModal();
+            picker.save();
+            await vi.waitFor(() => expect(mockModalOpen).toHaveBeenCalledOnce());
+            const call = mockModalOpen.mock.calls[0];
+            expect(call[1].mode).toBe('save');
         });
     });
-    it('defaults anchor to viewport center when not provided', async () => {
-        const listFn = async () => [];
-        const picker = createDocumentPicker(listFn);
-        mockPopup();
-        const w = window.innerWidth;
-        const h = window.innerHeight;
-        picker.open();
-        await vi.waitFor(() => expect(mockShow).toHaveBeenCalledOnce());
-        const call = mockShow.mock.calls[0];
-        expect(call[1].anchor).toEqual({ x: w / 2, y: h / 2 });
+    describe('save() — popup (with anchor)', () => {
+        it('uses popup when anchor element is provided', async () => {
+            const listFn = async () => [];
+            const picker = createDocumentPicker(listFn);
+            mockPopup();
+            const el = document.createElement('div');
+            picker.save({ anchor: el });
+            await vi.waitFor(() => expect(mockPopupShow).toHaveBeenCalledOnce());
+            expect(mockModalOpen).not.toHaveBeenCalled();
+        });
     });
 });

package/dist/documents/picker-primitive.d.ts

@@ -3,5 +3,9 @@ import type { DocumentPickerApi, DocListFn } from './picker-api';
  * Create a document picker API bound to a document listing function.
  * The listFn is derived from the shard's document zone + browse permission
  * and baked in at construction time so callers don't pass their own scope.
+ *
+ * When an `anchor` element is provided the browser opens as a popup
+ * (anchored near the element). Without an anchor it opens as a centered
+ * modal (the expected default for file-browser dialogs).
  */
 export declare function createDocumentPicker(listFn: DocListFn): DocumentPickerApi;

package/dist/documents/picker-primitive.js

@@ -1,57 +1,55 @@
 import { sh3 } from '../sh3Runtime.svelte';
 import DocumentBrowser from '../primitives/widgets/_DocumentBrowser.svelte';
+const BOX_STYLE = 'max-width: min(800px, 95vw);';
+const MODAL_OPTS = { dismissOnBackdrop: true, boxStyle: BOX_STYLE };
 /**
  * Create a document picker API bound to a document listing function.
  * The listFn is derived from the shard's document zone + browse permission
  * and baked in at construction time so callers don't pass their own scope.
+ *
+ * When an `anchor` element is provided the browser opens as a popup
+ * (anchored near the element). Without an anchor it opens as a centered
+ * modal (the expected default for file-browser dialogs).
  */
 export function createDocumentPicker(listFn) {
-    function anchorOrDefault(anchor) {
+    /** Resolve handle for either popup (anchored) or modal (centered) path. */
+    function openBrowser(browserProps, anchor) {
         if (anchor) {
             const rect = anchor.getBoundingClientRect();
-            return { x: rect.left + rect.width / 2, y: rect.top };
+            return sh3.popup.show(DocumentBrowser, { anchor: { x: rect.left + rect.width / 2, y: rect.top } }, browserProps);
         }
-        return { x: window.innerWidth / 2, y: window.innerHeight / 2 };
+        return sh3.modal.open(DocumentBrowser, browserProps, MODAL_OPTS);
+    }
+    function wrapHandle(handle, resolve) {
+        const origClose = handle.close;
+        handle.close = () => {
+            origClose();
+            resolve(null);
+        };
     }
     async function open(opts) {
         const docs = await listFn();
         return new Promise((resolve) => {
-            const handle = sh3.popup.show(DocumentBrowser, { anchor: anchorOrDefault(opts === null || opts === void 0 ? void 0 : opts.anchor) }, {
+            const handle = openBrowser({
                 mode: 'open',
                 docs,
-                onCommit: (value) => {
-                    resolve(value);
-                },
-                onCancel: () => {
-                    resolve(null);
-                },
-            });
-            const origClose = handle.close;
-            handle.close = () => {
-                origClose();
-                resolve(null);
-            };
+                onCommit: (value) => { resolve(value); },
+                onCancel: () => { resolve(null); },
+            }, opts === null || opts === void 0 ? void 0 : opts.anchor);
+            wrapHandle(handle, resolve);
         });
     }
     async function save(opts) {
         const docs = await listFn();
         return new Promise((resolve) => {
-            const handle = sh3.popup.show(DocumentBrowser, { anchor: anchorOrDefault(opts === null || opts === void 0 ? void 0 : opts.anchor) }, {
+            const handle = openBrowser({
                 mode: 'save',
                 docs,
                 suggestedName: opts === null || opts === void 0 ? void 0 : opts.suggestedName,
-                onCommit: (value) => {
-                    resolve(value);
-                },
-                onCancel: () => {
-                    resolve(null);
-                },
-            });
-            const origClose = handle.close;
-            handle.close = () => {
-                origClose();
-                resolve(null);
-            };
+                onCommit: (value) => { resolve(value); },
+                onCancel: () => { resolve(null); },
+            }, opts === null || opts === void 0 ? void 0 : opts.anchor);
+            wrapHandle(handle, resolve);
         });
     }
     return { open, save };