sh3-core 0.19.5 → 0.19.6

package/dist/api.d.ts

@@ -30,6 +30,7 @@ export { inspectActiveLayout, spliceIntoActiveLayout, dockIntoActiveLayout, focu
 export type { DocumentHandle, DocumentHandleOptions, DocumentFormat, DocumentMeta, DocumentChange, AutosaveController, } from './documents/types';
 export { PERMISSION_DOCUMENTS_BROWSE, PERMISSION_DOCUMENTS_READ, PERMISSION_DOCUMENTS_WRITE, } from './documents/types';
 export type { BrowseCapability } from './documents/browse';
+export type { DocumentPickerApi, DocumentOpenOptions, DocumentSaveOptions } from './documents/picker-api';
 export type { ContributionsApi } from './contributions/types';
 export type { SyncPolicy, SyncPolicyRule, DocStatus, ConflictFile, ConflictBranch, } from './documents/sync-types';
 export { PERMISSION_SYNC_PEER, PERMISSION_SYNC_POLICY } from './documents/sync-types';

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

@@ -0,0 +1,31 @@
+import type { DocEntry, OpenerValue, SaverValue } from '../primitives/widgets/DocumentFilePicker';
+/** Function that returns the document tree for the picker to browse. */
+export type DocListFn = () => Promise<DocEntry[]>;
+/** Options for `ctx.documentPicker.open()`. */
+export interface DocumentOpenOptions {
+    /** Element to anchor the popup to. Defaults to viewport center. */
+    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. */
+    anchor?: HTMLElement;
+}
+/** Programmatic document picker API — available on `ctx.documentPicker`. */
+export interface DocumentPickerApi {
+    /**
+     * Open the document browser in "open" mode. The user browses and selects
+     * an existing document. Returns the selected `{shardId, path}` or null
+     * if cancelled or dismissed externally.
+     */
+    open(opts?: DocumentOpenOptions): Promise<OpenerValue | null>;
+    /**
+     * Open the document browser in "save" mode. The user navigates to a
+     * folder and provides a filename. Returns the full path string or null
+     * if cancelled or dismissed externally.
+     */
+    save(opts?: DocumentSaveOptions): Promise<SaverValue | null>;
+}
+export type { OpenerValue, SaverValue };

package/dist/documents/picker-api.js

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

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

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

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

@@ -0,0 +1,132 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { sh3 } from '../sh3Runtime.svelte';
+import { createDocumentPicker } from './picker-primitive';
+vi.mock('../sh3Runtime.svelte', () => ({
+    sh3: {
+        popup: {
+            show: vi.fn(),
+        },
+    },
+}));
+const mockShow = sh3.popup.show;
+function mockPopup() {
+    let capturedCommit = null;
+    let capturedCancel = null;
+    const handle = {
+        close: vi.fn(),
+    };
+    mockShow.mockImplementation((_Content, _opts, props) => {
+        capturedCommit = props.onCommit;
+        capturedCancel = props.onCancel;
+        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();
+        },
+        handle,
+    };
+}
+beforeEach(() => {
+    vi.clearAllMocks();
+});
+describe('createDocumentPicker', () => {
+    const sampleDoc = { shardId: 'my-shard', path: 'readme.md' };
+    describe('open()', () => {
+        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 promise = picker.open();
+            await vi.waitFor(() => expect(mockShow).toHaveBeenCalledOnce());
+            popup.commit(sampleDoc);
+            const result = await promise;
+            expect(result).toEqual({ shardId: 'my-shard', path: 'readme.md' });
+        });
+        it('resolves with null when user cancels', async () => {
+            const listFn = async () => [];
+            const picker = createDocumentPicker(listFn);
+            const popup = mockPopup();
+            const promise = picker.open();
+            await vi.waitFor(() => expect(mockShow).toHaveBeenCalledOnce());
+            popup.cancel();
+            const result = await promise;
+            expect(result).toBeNull();
+        });
+        it('resolves with null when popup is dismissed externally', async () => {
+            const listFn = async () => [];
+            const picker = createDocumentPicker(listFn);
+            const popup = mockPopup();
+            const promise = picker.open();
+            await vi.waitFor(() => expect(mockShow).toHaveBeenCalledOnce());
+            popup.dismiss();
+            const result = await promise;
+            expect(result).toBeNull();
+        });
+        it('rejects when listFn fails', async () => {
+            const listFn = async () => { throw new Error('network error'); };
+            const picker = createDocumentPicker(listFn);
+            const promise = picker.open();
+            await expect(promise).rejects.toThrow('network error');
+            expect(mockShow).not.toHaveBeenCalled();
+        });
+        it('uses anchor element position when 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];
+            expect(call[1].anchor).toEqual({ x: 0, y: 0 });
+        });
+    });
+    describe('save()', () => {
+        it('resolves with SaverValue string when user commits a filename', async () => {
+            const listFn = async () => [];
+            const picker = createDocumentPicker(listFn);
+            const popup = mockPopup();
+            const promise = picker.save();
+            await vi.waitFor(() => expect(mockShow).toHaveBeenCalledOnce());
+            popup.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 promise = picker.save();
+            await vi.waitFor(() => expect(mockShow).toHaveBeenCalledOnce());
+            popup.cancel();
+            const result = await promise;
+            expect(result).toBeNull();
+        });
+        it('passes suggestedName as prop', async () => {
+            const listFn = async () => [];
+            const picker = createDocumentPicker(listFn);
+            mockPopup();
+            picker.save({ suggestedName: 'draft.txt' });
+            await vi.waitFor(() => expect(mockShow).toHaveBeenCalledOnce());
+            const call = mockShow.mock.calls[0];
+            expect(call[2].suggestedName).toBe('draft.txt');
+        });
+    });
+    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 });
+    });
+});

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

@@ -0,0 +1,7 @@
+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.
+ */
+export declare function createDocumentPicker(listFn: DocListFn): DocumentPickerApi;

package/dist/documents/picker-primitive.js

@@ -0,0 +1,58 @@
+import { sh3 } from '../sh3Runtime.svelte';
+import DocumentBrowser from '../primitives/widgets/_DocumentBrowser.svelte';
+/**
+ * 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.
+ */
+export function createDocumentPicker(listFn) {
+    function anchorOrDefault(anchor) {
+        if (anchor) {
+            const rect = anchor.getBoundingClientRect();
+            return { x: rect.left + rect.width / 2, y: rect.top };
+        }
+        return { x: window.innerWidth / 2, y: window.innerHeight / 2 };
+    }
+    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) }, {
+                mode: 'open',
+                docs,
+                onCommit: (value) => {
+                    resolve(value);
+                },
+                onCancel: () => {
+                    resolve(null);
+                },
+            });
+            const origClose = handle.close;
+            handle.close = () => {
+                origClose();
+                resolve(null);
+            };
+        });
+    }
+    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) }, {
+                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);
+            };
+        });
+    }
+    return { open, save };
+}

package/dist/primitives/widgets/_DocumentBrowser.svelte

@@ -17,18 +17,20 @@
     onCommit,
     onCancel,
     close,
+    suggestedName = '',
   }: {
     mode: 'open' | 'save';
     docs: DocEntry[];
     onCommit: (value: OpenerValue | SaverValue) => void;
     onCancel: () => void;
     close: () => void;
+    suggestedName?: string;
   } = $props();
 
   let shardId = $state<string | null>(null);
   let prefix = $state('');
   let selectedFile = $state<DocEntry | null>(null);
-  let filename = $state('');
+  let filename = $state(suggestedName);
   let activeIdx = $state(0);
   let listEl = $state<HTMLElement | undefined>(undefined);
 

package/dist/primitives/widgets/_DocumentBrowser.svelte.d.ts

@@ -5,6 +5,7 @@ type $$ComponentProps = {
     onCommit: (value: OpenerValue | SaverValue) => void;
     onCancel: () => void;
     close: () => void;
+    suggestedName?: string;
 };
 declare const DocumentBrowser: import("svelte").Component<$$ComponentProps, {}, "">;
 type DocumentBrowser = ReturnType<typeof DocumentBrowser>;

package/dist/shards/activate.svelte.js

@@ -28,6 +28,7 @@ import { createZoneManager } from '../state/manage';
 import { PERMISSION_STATE_MANAGE } from '../state/types';
 import { PERMISSION_DOCUMENTS_BROWSE, PERMISSION_DOCUMENTS_READ, PERMISSION_DOCUMENTS_WRITE, } from '../documents/types';
 import { createBrowseCapability } from '../documents/browse';
+import { createDocumentPicker } from '../documents/picker-primitive';
 import { createShardKeysApi } from '../keys/client';
 import { PERMISSION_KEYS_MINT } from '../keys/types';
 import { subscribe } from '../keys/revocation-bus.svelte';
@@ -88,7 +89,7 @@ export function registerShard(shard) {
  * @throws If the shard is not registered, if `shard.activate` throws, or if a manifest view has no factory after activation.
  */
 export async function activateShard(id, opts) {
-    var _a, _b, _c, _d, _e, _f, _g;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
     const shard = registeredShards.get(id);
     if (!shard) {
         throw new Error(`Cannot activate shard "${id}": not registered`);
@@ -143,6 +144,13 @@ export async function activateShard(id, opts) {
             return off;
         },
     };
+    const hasBrowse = (_a = shard.manifest.permissions) === null || _a === void 0 ? void 0 : _a.includes(PERMISSION_DOCUMENTS_BROWSE);
+    const browseCap = hasBrowse
+        ? createBrowseCapability(getTenantId(), getDocumentBackend(), {
+            canRead: (_c = (_b = shard.manifest.permissions) === null || _b === void 0 ? void 0 : _b.includes(PERMISSION_DOCUMENTS_READ)) !== null && _c !== void 0 ? _c : false,
+            canWrite: (_e = (_d = shard.manifest.permissions) === null || _d === void 0 ? void 0 : _d.includes(PERMISSION_DOCUMENTS_WRITE)) !== null && _e !== void 0 ? _e : false,
+        })
+        : undefined;
     const ctx = {
         state: (schema) => sh3.state(id, schema),
         registerView: (viewId, factory) => {
@@ -212,19 +220,20 @@ export async function activateShard(id, opts) {
         get tenantId() {
             return getTenantId();
         },
-        zones: ((_a = shard.manifest.permissions) === null || _a === void 0 ? void 0 : _a.includes(PERMISSION_STATE_MANAGE))
+        zones: ((_f = shard.manifest.permissions) === null || _f === void 0 ? void 0 : _f.includes(PERMISSION_STATE_MANAGE))
             ? createZoneManager()
             : undefined,
-        browse: ((_b = shard.manifest.permissions) === null || _b === void 0 ? void 0 : _b.includes(PERMISSION_DOCUMENTS_BROWSE))
-            ? createBrowseCapability(getTenantId(), getDocumentBackend(), {
-                canRead: shard.manifest.permissions.includes(PERMISSION_DOCUMENTS_READ),
-                canWrite: shard.manifest.permissions.includes(PERMISSION_DOCUMENTS_WRITE),
-            })
-            : undefined,
-        keys: ((_c = shard.manifest.permissions) === null || _c === void 0 ? void 0 : _c.includes(PERMISSION_KEYS_MINT))
+        browse: browseCap,
+        documentPicker: browseCap
+            ? createDocumentPicker(() => browseCap.listDocuments())
+            : createDocumentPicker(async () => {
+                const docs = await getDocumentBackend().list(getTenantId(), id);
+                return docs.map(d => (Object.assign(Object.assign({}, d), { shardId: id })));
+            }),
+        keys: ((_g = shard.manifest.permissions) === null || _g === void 0 ? void 0 : _g.includes(PERMISSION_KEYS_MINT))
             ? createShardKeysApi({
                 shardId: id,
-                shardPermissions: (_d = shard.manifest.permissions) !== null && _d !== void 0 ? _d : [],
+                shardPermissions: (_h = shard.manifest.permissions) !== null && _h !== void 0 ? _h : [],
             })
             : undefined,
         contributions,
@@ -241,7 +250,7 @@ export async function activateShard(id, opts) {
         sh3: makeSh3Api({
             callerKind: 'shard',
             callerShardId: id,
-            zones: ((_e = shard.manifest.permissions) === null || _e === void 0 ? void 0 : _e.includes(PERMISSION_STATE_MANAGE))
+            zones: ((_j = shard.manifest.permissions) === null || _j === void 0 ? void 0 : _j.includes(PERMISSION_STATE_MANAGE))
                 ? createZoneManager()
                 : undefined,
         }),
@@ -290,7 +299,7 @@ export async function activateShard(id, opts) {
             try {
                 void fn();
             }
-            catch (_h) {
+            catch (_m) {
                 // intentionally swallowed: original error is what matters.
             }
         }
@@ -304,7 +313,7 @@ export async function activateShard(id, opts) {
         erroredShards.set(id, {
             id,
             error: err,
-            phase: (_f = opts === null || opts === void 0 ? void 0 : opts.phase) !== null && _f !== void 0 ? _f : 'launch',
+            phase: (_k = opts === null || opts === void 0 ? void 0 : opts.phase) !== null && _k !== void 0 ? _k : 'launch',
             timestamp: Date.now(),
         });
         console.error(`[sh3] Shard "${id}" failed to activate:`, err);
@@ -312,7 +321,7 @@ export async function activateShard(id, opts) {
     }
     // Activation succeeded — clear any prior error record for this shard.
     erroredShards.delete(id);
-    void ((_g = shard.autostart) === null || _g === void 0 ? void 0 : _g.call(shard, ctx));
+    void ((_l = shard.autostart) === null || _l === void 0 ? void 0 : _l.call(shard, ctx));
 }
 /**
  * Deactivate an active shard. Calls `shard.deactivate`, flushes and disposes

package/dist/shards/types.d.ts

@@ -2,6 +2,7 @@ import type { StateZones } from '../state/zones.svelte';
 import type { ZoneSchema, ZoneManager } from '../state/types';
 import type { DocumentHandle, DocumentHandleOptions } from '../documents/types';
 import type { BrowseCapability } from '../documents/browse';
+import type { DocumentPickerApi } from '../documents/picker-api';
 import type { EnvState } from '../env/types';
 import type { Verb } from '../verbs/types';
 import type { Sh3Api } from '../verbs/types';
@@ -287,6 +288,13 @@ export interface ShardContext {
      * owning shard's own `ctx.documents()` handle.
      */
     browse?: BrowseCapability;
+    /**
+     * Programmatic document picker. Opens the DocumentBrowser popup scoped
+     * to this shard's document zone (or wider tree if the shard has the
+     * `documents:browse` permission). Returns the selected document reference
+     * or null if the user cancelled.
+     */
+    documentPicker: DocumentPickerApi;
     /**
      * Mint/list/revoke keys minted by this shard. Only available when the
      * manifest declares the `keys:mint` permission.

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Auto-generated from package.json — do not edit manually. */
-export declare const VERSION = "0.19.5";
+export declare const VERSION = "0.19.6";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Auto-generated from package.json — do not edit manually. */
-export const VERSION = '0.19.5';
+export const VERSION = '0.19.6';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sh3-core",
-  "version": "0.19.5",
+  "version": "0.19.6",
   "type": "module",
   "files": [
     "dist"