sh3-core 0.19.3 → 0.19.6

package/dist/overlays/float.js

@@ -26,21 +26,58 @@
  *   in-memory fallback array is used — this is both the test environment
  *   and the pre-boot state.
  */
-import { computeMinSize, cascadePosition, generateFloatId } from '../layout/floats';
+import { computeMinSize, cascadePosition, generateFloatId, clampFloatToViewport, } from '../layout/floats';
 import { findEnclosingOverlayHost } from './parentHost';
+import { compactRootStore } from '../layout/compact/rootStore.svelte';
+import { viewportStore } from '../viewport/store.svelte';
 import { setMaximizedReactive, readMaximizedReactive, __resetMaximizedReactiveForTest, } from './floatMaximized.svelte';
 // ----- storage binding ---------------------------------------------------
 let fallbackFloats = [];
 let boundFloats = null;
 let getTreeBounds = () => ({ w: 1600, h: 900 });
+/**
+ * Float ids that have already been pulled into the viewport — either at
+ * open() time, or on the bind that first observed them as persisted.
+ * Subsequent binds (viewport-class swap, preset switch back-and-forth)
+ * skip these so a user-positioned float isn't snapped on every re-bind.
+ *
+ * Ids are time+counter unique per session, so this set never confuses a
+ * recycled id; it grows for the lifetime of the session.
+ */
+const clampedIds = new Set();
+function clampFloatRect(entry, bounds) {
+    const minSize = computeMinSize(entry.content);
+    const clamped = clampFloatToViewport({ position: entry.position, size: entry.size }, minSize, bounds);
+    entry.position.x = clamped.position.x;
+    entry.position.y = clamped.position.y;
+    entry.size.w = clamped.size.w;
+    entry.size.h = clamped.size.h;
+}
 /**
  * Bind the manager to the active LayoutTree's `floats` array. Called
  * from Sh3.svelte during boot. `getBounds` returns the current
  * tree-allocated area for cascade-position wraparound.
+ *
+ * Persisted floats observed for the first time are pulled into the
+ * supplied viewport — without this, a float whose position/size came
+ * from a larger window renders past the overlay root, which Firefox
+ * paints by growing the parent and visibly shifts the docked grid.
+ * Ids already in `clampedIds` (re-bound on viewport-class swap, etc.)
+ * are left alone.
  */
 export function bindFloatStore(floats, getBounds) {
     boundFloats = floats;
     getTreeBounds = getBounds;
+    const bounds = getBounds();
+    for (const entry of floats) {
+        if (clampedIds.has(entry.id))
+            continue;
+        clampFloatRect(entry, bounds);
+        clampedIds.add(entry.id);
+    }
+    // Active tree changed (app/preset switch) — drop any compact body
+    // selection so the user lands on the new docked tree.
+    compactRootStore.reset();
 }
 export function unbindFloatStore() {
     boundFloats = null;
@@ -53,6 +90,7 @@ export function __resetFloatManagerForTest() {
     getTreeBounds = () => ({ w: 1600, h: 900 });
     parentHosts.clear();
     maximizedRects.clear();
+    clampedIds.clear();
     __resetMaximizedReactiveForTest();
 }
 function activeStore() {
@@ -80,8 +118,16 @@ function mintFloatSlotId(viewId) {
 }
 // ----- API ---------------------------------------------------------------
 const DEFAULT_SIZE = { w: 600, h: 400 };
-function maxSize(a, b) {
-    return { w: Math.max(a.w, b.w), h: Math.max(a.h, b.h) };
+/**
+ * The default opening size: prefer DEFAULT_SIZE, but cap each axis at
+ * the current viewport so phones don't get a 600×400 float on a 360×800
+ * screen. Never shrunk below the content's computed minimum.
+ */
+function defaultOpenSize(min, bounds) {
+    return {
+        w: Math.max(min.w, Math.min(DEFAULT_SIZE.w, bounds.w)),
+        h: Math.max(min.h, Math.min(DEFAULT_SIZE.h, bounds.h)),
+    };
 }
 function openFloat(viewId, options = {}) {
     var _a, _b, _c;
@@ -118,8 +164,9 @@ function openFloat(viewId, options = {}) {
         };
     }
     const computedMin = computeMinSize(content);
-    const size = (_b = options.size) !== null && _b !== void 0 ? _b : maxSize(DEFAULT_SIZE, computedMin);
-    const position = (_c = options.position) !== null && _c !== void 0 ? _c : cascadePosition(store, getTreeBounds());
+    const bounds = getTreeBounds();
+    const size = (_b = options.size) !== null && _b !== void 0 ? _b : defaultOpenSize(computedMin, bounds);
+    const position = (_c = options.position) !== null && _c !== void 0 ? _c : cascadePosition(store, bounds);
     const entry = {
         id,
         content,
@@ -134,14 +181,26 @@ function openFloat(viewId, options = {}) {
         if (host)
             parentHosts.set(id, host);
     }
+    // Pull the chosen rect into the current viewport (handles user-supplied
+    // off-screen positions and oversized user-supplied sizes).
+    clampFloatRect(entry, bounds);
+    // Mark already-clamped so the next bind doesn't snap it again.
+    clampedIds.add(id);
     store.push(entry);
+    // Compact mode demotes non-dismissable floats from overlays to body-or-menu;
+    // a fresh open auto-switches the body to the new float so the user actually
+    // sees what they just opened. Pickers stay floating per the design.
+    if (viewportStore.current.class === 'compact' && !options.dismissable) {
+        compactRootStore.setRoot({ kind: 'float', floatId: id });
+    }
     return id;
 }
 function openFloatWithContent(options) {
     var _a;
     const store = activeStore();
     const id = generateFloatId();
-    const position = (_a = options.position) !== null && _a !== void 0 ? _a : cascadePosition(store, getTreeBounds());
+    const bounds = getTreeBounds();
+    const position = (_a = options.position) !== null && _a !== void 0 ? _a : cascadePosition(store, bounds);
     const entry = {
         id,
         content: options.content,
@@ -149,7 +208,12 @@ function openFloatWithContent(options) {
         size: options.size,
         title: options.title,
     };
+    clampFloatRect(entry, bounds);
+    clampedIds.add(id);
     store.push(entry);
+    if (viewportStore.current.class === 'compact') {
+        compactRootStore.setRoot({ kind: 'float', floatId: id });
+    }
     return id;
 }
 function closeFloat(floatId) {
@@ -160,6 +224,12 @@ function closeFloat(floatId) {
     store.splice(idx, 1);
     parentHosts.delete(floatId);
     maximizedRects.delete(floatId);
+    // If this float was the compact body, snap back to docked.
+    const cur = compactRootStore.current;
+    if (cur.kind === 'float' && cur.floatId === floatId) {
+        compactRootStore.reset();
+    }
+    clampedIds.delete(floatId);
     setMaximizedReactive(floatId, false);
 }
 function listFloats() {

package/dist/overlays/float.test.js

@@ -80,6 +80,176 @@ describe('floatManager', () => {
         expect(f.content.type).toBe('tabs');
     });
 });
+describe('bindFloatStore — clamp persisted floats to viewport', () => {
+    beforeEach(() => {
+        __resetFloatManagerForTest();
+    });
+    it('pulls an off-screen persisted float back into the bound viewport', () => {
+        // Persisted state from a previous, larger viewport: x is past the
+        // current right edge, y is past the current bottom.
+        const floats = [
+            {
+                id: 'persisted-1',
+                content: {
+                    type: 'tabs',
+                    tabs: [{ slotId: 'float:v:1', viewId: 'v', label: 'V' }],
+                    activeTab: 0,
+                },
+                position: { x: 2400, y: 1800 },
+                size: { w: 600, h: 400 },
+            },
+        ];
+        bindFloatStore(floats, () => ({ w: 1024, h: 768 }));
+        expect(floats[0].position.x).toBe(1024 - 600);
+        expect(floats[0].position.y).toBe(768 - 400);
+        expect(floats[0].size).toEqual({ w: 600, h: 400 });
+    });
+    it('shrinks an oversized persisted float to fit the bound viewport', () => {
+        const floats = [
+            {
+                id: 'persisted-2',
+                content: {
+                    type: 'tabs',
+                    tabs: [{ slotId: 'float:v:2', viewId: 'v', label: 'V' }],
+                    activeTab: 0,
+                },
+                position: { x: 0, y: 0 },
+                size: { w: 4000, h: 3000 },
+            },
+        ];
+        bindFloatStore(floats, () => ({ w: 1024, h: 768 }));
+        expect(floats[0].size).toEqual({ w: 1024, h: 768 });
+    });
+    it('leaves a float that already fits unchanged', () => {
+        const floats = [
+            {
+                id: 'persisted-3',
+                content: {
+                    type: 'tabs',
+                    tabs: [{ slotId: 'float:v:3', viewId: 'v', label: 'V' }],
+                    activeTab: 0,
+                },
+                position: { x: 100, y: 200 },
+                size: { w: 600, h: 400 },
+            },
+        ];
+        bindFloatStore(floats, () => ({ w: 1024, h: 768 }));
+        expect(floats[0].position).toEqual({ x: 100, y: 200 });
+        expect(floats[0].size).toEqual({ w: 600, h: 400 });
+    });
+    it('does not re-clamp a float on subsequent binds (e.g. viewport-class swap)', () => {
+        // Simulate a user-positioned float that's outside a smaller viewport.
+        // First bind clamps it; the user then moves it back to (700, 200);
+        // a second bind (compact ↔ desktop) must not snap it again.
+        const floats = [
+            {
+                id: 'persisted-4',
+                content: {
+                    type: 'tabs',
+                    tabs: [{ slotId: 'float:v:4', viewId: 'v', label: 'V' }],
+                    activeTab: 0,
+                },
+                position: { x: 2400, y: 0 },
+                size: { w: 600, h: 400 },
+            },
+        ];
+        bindFloatStore(floats, () => ({ w: 1024, h: 768 }));
+        // User drags it back to an out-of-bounds spot (allowed mid-session).
+        floats[0].position.x = 2400;
+        floats[0].position.y = 1800;
+        bindFloatStore(floats, () => ({ w: 1024, h: 768 }));
+        expect(floats[0].position).toEqual({ x: 2400, y: 1800 });
+    });
+});
+describe('floatManager.open — default size respects viewport', () => {
+    beforeEach(() => {
+        __resetFloatManagerForTest();
+    });
+    it('caps the default size at viewport bounds (phone-sized window)', () => {
+        bindFloatStore(layoutStore.floats, () => ({ w: 360, h: 740 }));
+        const id = floatManager.open('test:view', { title: 'Phone' });
+        const f = floatManager.list().find((e) => e.id === id);
+        expect(f.size.w).toBeLessThanOrEqual(360);
+        expect(f.size.h).toBeLessThanOrEqual(740);
+        // And the float is fully on-screen.
+        expect(f.position.x + f.size.w).toBeLessThanOrEqual(360);
+        expect(f.position.y + f.size.h).toBeLessThanOrEqual(740);
+    });
+    it('uses DEFAULT_SIZE when the viewport is large enough', () => {
+        bindFloatStore(layoutStore.floats, () => ({ w: 1280, h: 800 }));
+        const id = floatManager.open('test:view', { title: 'Desktop' });
+        const f = floatManager.list().find((e) => e.id === id);
+        expect(f.size).toEqual({ w: 600, h: 400 });
+    });
+    it('clamps a user-supplied oversized size to viewport on open', () => {
+        bindFloatStore(layoutStore.floats, () => ({ w: 360, h: 740 }));
+        const id = floatManager.open('test:view', {
+            title: 'Phone',
+            size: { w: 2000, h: 2000 },
+        });
+        const f = floatManager.list().find((e) => e.id === id);
+        expect(f.size).toEqual({ w: 360, h: 740 });
+    });
+});
+// ---------------------------------------------------------------------------
+// Compact body-root integration: floatManager auto-switches in compact mode,
+// resets on close-of-current and on bind.
+// ---------------------------------------------------------------------------
+import { compactRootStore, __resetCompactRootStoreForTest, } from '../layout/compact/rootStore.svelte';
+import { viewportStore } from '../viewport/store.svelte';
+describe('floatManager — compact body root integration', () => {
+    beforeEach(() => {
+        __resetFloatManagerForTest();
+        __resetCompactRootStoreForTest();
+        viewportStore.override(null);
+    });
+    afterEach(() => {
+        viewportStore.override(null);
+    });
+    it('open() in compact mode switches the body to the new (non-dismissable) float', () => {
+        bindFloatStore(layoutStore.floats, () => ({ w: 360, h: 740 }));
+        viewportStore.override('compact');
+        const id = floatManager.open('test:view', { title: 'Notes' });
+        expect(compactRootStore.current).toEqual({ kind: 'float', floatId: id });
+    });
+    it('open() in compact mode does NOT switch the body for dismissable pickers', () => {
+        bindFloatStore(layoutStore.floats, () => ({ w: 360, h: 740 }));
+        viewportStore.override('compact');
+        floatManager.open('picker:view', { dismissable: true });
+        expect(compactRootStore.current).toEqual({ kind: 'docked' });
+    });
+    it('open() on desktop does not touch the compact body root', () => {
+        bindFloatStore(layoutStore.floats, () => ({ w: 1280, h: 800 }));
+        viewportStore.override('desktop');
+        floatManager.open('test:view');
+        expect(compactRootStore.current).toEqual({ kind: 'docked' });
+    });
+    it('close(id) resets when the closed float is the current body', () => {
+        bindFloatStore(layoutStore.floats, () => ({ w: 360, h: 740 }));
+        viewportStore.override('compact');
+        const id = floatManager.open('test:view');
+        floatManager.close(id);
+        expect(compactRootStore.current).toEqual({ kind: 'docked' });
+    });
+    it('close(id) leaves the body root alone when closing a different float', () => {
+        bindFloatStore(layoutStore.floats, () => ({ w: 360, h: 740 }));
+        viewportStore.override('compact');
+        floatManager.open('view:a');
+        const b = floatManager.open('view:b');
+        expect(compactRootStore.current).toEqual({ kind: 'float', floatId: b });
+        floatManager.close(layoutStore.floats[0].id);
+        expect(compactRootStore.current).toEqual({ kind: 'float', floatId: b });
+    });
+    it('bindFloatStore resets the body root (covers app/preset switch)', () => {
+        bindFloatStore(layoutStore.floats, () => ({ w: 360, h: 740 }));
+        viewportStore.override('compact');
+        const id = floatManager.open('test:view');
+        expect(compactRootStore.current).toEqual({ kind: 'float', floatId: id });
+        // Re-bind (e.g. preset switch).
+        bindFloatStore([], () => ({ w: 360, h: 740 }));
+        expect(compactRootStore.current).toEqual({ kind: 'docked' });
+    });
+});
 describe('floatManager — anchor-aware parent host', () => {
     beforeEach(() => {
         __resetFloatManagerForTest();

package/dist/primitives/widgets/DocumentFilePicker.d.ts

@@ -0,0 +1,25 @@
+import type { DocumentMeta } from '../../documents/types';
+export type DocEntry = DocumentMeta & {
+    shardId: string;
+};
+export type OpenerValue = Pick<DocEntry, 'shardId' | 'path'> | null;
+export type SaverValue = string | null;
+export type FileItem = {
+    kind: 'folder';
+    name: string;
+    fullPath: string;
+} | {
+    kind: 'file';
+    name: string;
+    doc: DocEntry;
+};
+export declare function buildTree(docs: DocEntry[], shardId: string | null, prefix: string): FileItem[];
+export declare function formatSize(bytes: number): string;
+export declare function formatDate(epochMs: number): string;
+export declare function iconForFile(name: string): string;
+export declare function breadcrumbSegments(shardId: string | null, prefix: string): {
+    label: string;
+    level: number;
+    targetShard: string | null;
+    targetPrefix: string;
+}[];

package/dist/primitives/widgets/DocumentFilePicker.js

@@ -0,0 +1,74 @@
+export function buildTree(docs, shardId, prefix) {
+    if (shardId === null) {
+        const shards = [...new Set(docs.map((d) => d.shardId))].sort();
+        return shards.map((s) => ({ kind: 'folder', name: s, fullPath: s }));
+    }
+    const shardDocs = docs.filter((d) => d.shardId === shardId);
+    const folders = new Map();
+    const files = [];
+    const normPrefix = prefix ? prefix + '/' : '';
+    const plen = normPrefix.length;
+    for (const doc of shardDocs) {
+        if (!doc.path.startsWith(normPrefix))
+            continue;
+        const relative = doc.path.slice(plen);
+        const slash = relative.indexOf('/');
+        if (slash >= 0) {
+            const name = relative.slice(0, slash);
+            const full = prefix ? `${prefix}/${name}` : name;
+            if (!folders.has(name))
+                folders.set(name, full);
+        }
+        else {
+            files.push({ kind: 'file', name: relative, doc });
+        }
+    }
+    const folderItems = [...folders.entries()]
+        .map(([name, fullPath]) => ({ kind: 'folder', name, fullPath }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    const fileItems = files.sort((a, b) => a.name.localeCompare(b.name));
+    return [...folderItems, ...fileItems];
+}
+export function formatSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+export function formatDate(epochMs) {
+    const d = new Date(epochMs);
+    return d.toLocaleDateString('en-US', {
+        month: 'short',
+        day: 'numeric',
+        year: d.getFullYear() !== new Date().getFullYear() ? 'numeric' : undefined,
+    });
+}
+const EXT_ICONS = {
+    guml: '⬡', glsl: '◇', md: '≡', obj: '△', png: '▦',
+};
+export function iconForFile(name) {
+    var _a;
+    const ext = name.slice(name.lastIndexOf('.') + 1).toLowerCase();
+    return (_a = EXT_ICONS[ext]) !== null && _a !== void 0 ? _a : '▯';
+}
+export function breadcrumbSegments(shardId, prefix) {
+    const segs = [
+        { label: 'SH3', level: 0, targetShard: null, targetPrefix: '' },
+    ];
+    if (shardId) {
+        segs.push({ label: shardId, level: 1, targetShard: shardId, targetPrefix: '' });
+        if (prefix) {
+            const parts = prefix.split('/');
+            for (let i = 0; i < parts.length; i++) {
+                segs.push({
+                    label: parts[i],
+                    level: 2 + i,
+                    targetShard: shardId,
+                    targetPrefix: parts.slice(0, i + 1).join('/'),
+                });
+            }
+        }
+    }
+    return segs;
+}

package/dist/primitives/widgets/DocumentFilePicker.svelte

@@ -0,0 +1,144 @@
+<script lang="ts">
+  import type { CommitOnlyEvents } from './_contract';
+  import { sh3 } from '../../sh3Runtime.svelte';
+  import DocumentBrowser from './_DocumentBrowser.svelte';
+  import type { DocumentMeta } from '../../documents/types';
+  import type { DocEntry, OpenerValue, SaverValue } from './DocumentFilePicker';
+
+  type DocListFn = () => Promise<Array<DocumentMeta & { shardId: string }>>;
+
+  let {
+    mode,
+    value = $bindable<OpenerValue | SaverValue>(null),
+    listDocuments,
+    disabled = false,
+    invalid = false,
+    size = 'md',
+    buttonLabel = 'Choose…',
+    onchange,
+  }: {
+    mode: 'open' | 'save';
+    value?: OpenerValue | SaverValue;
+    listDocuments: DocListFn;
+    disabled?: boolean;
+    invalid?: boolean;
+    size?: 'sm' | 'md';
+    buttonLabel?: string;
+  } & CommitOnlyEvents<OpenerValue | SaverValue> = $props();
+
+  let trigger = $state<HTMLButtonElement | undefined>(undefined);
+  let openFlag = $state(false);
+
+  const displayPath = $derived(
+    value
+      ? typeof value === 'string'
+        ? value
+        : `${value.shardId}/${value.path}`
+      : null,
+  );
+
+  function handleCommit(result: OpenerValue | SaverValue) {
+    value = result;
+    onchange?.(result);
+  }
+
+  function onOpenClosed() {
+    openFlag = false;
+    trigger?.focus();
+  }
+
+  async function open() {
+    if (disabled || openFlag || !trigger) return;
+    openFlag = true;
+    let docs: DocEntry[] = [];
+    try {
+      docs = await listDocuments();
+    } catch {
+      openFlag = false;
+      return;
+    }
+
+    const popupHandle = sh3.popup.show(
+      DocumentBrowser,
+      { anchor: trigger },
+      {
+        mode,
+        docs,
+        onCommit: (result: OpenerValue | SaverValue) => {
+          handleCommit(result);
+        },
+        onCancel: () => {},
+      },
+    );
+
+    const origClose = popupHandle.close;
+    popupHandle.close = () => {
+      origClose();
+      onOpenClosed();
+    };
+  }
+</script>
+
+<label class="sh3-dfp" class:sh3-dfp--sm={size === 'sm'} class:sh3-dfp--invalid={invalid}>
+  <button
+    type="button"
+    class="sh3-dfp__btn"
+    bind:this={trigger}
+    {disabled}
+    aria-haspopup="dialog"
+    aria-expanded={openFlag}
+    onclick={open}
+  >
+    <span class="sh3-dfp__label">{buttonLabel}</span>
+    <span class="sh3-dfp__path" class:sh3-dfp__path--empty={!displayPath}>
+      {displayPath ?? (mode === 'open' ? 'no document' : 'choose path…')}
+    </span>
+    <span class="sh3-dfp__chevron" aria-hidden="true">▾</span>
+  </button>
+</label>
+
+<style>
+  .sh3-dfp { display: inline-flex; font-size: 0.8125rem; }
+  .sh3-dfp__btn {
+    display: inline-flex; align-items: stretch;
+    height: var(--sh3-field-height-md);
+    min-width: 240px;
+    border: 1px solid var(--sh3-border);
+    border-radius: var(--sh3-widget-radius);
+    background: var(--sh3-input-bg);
+    cursor: pointer;
+    font: inherit;
+    text-align: left;
+    overflow: hidden;
+    padding: 0;
+  }
+  .sh3-dfp--sm .sh3-dfp__btn { height: var(--sh3-field-height-sm); }
+  .sh3-dfp--invalid .sh3-dfp__btn { border-color: var(--sh3-error); }
+  .sh3-dfp__btn:hover { border-color: var(--sh3-input-border-focus); }
+  .sh3-dfp__btn:focus-visible { outline: none; box-shadow: var(--sh3-focus-ring); border-color: var(--sh3-input-border-focus); }
+  .sh3-dfp__btn:disabled { opacity: 0.55; cursor: not-allowed; }
+  .sh3-dfp__label {
+    display: inline-flex; align-items: center;
+    padding: 0 var(--sh3-field-pad-x);
+    background: var(--sh3-bg-elevated);
+    color: var(--sh3-fg);
+    border-right: 1px solid var(--sh3-border);
+    white-space: nowrap;
+    flex-shrink: 0;
+  }
+  .sh3-dfp__path {
+    display: inline-flex; align-items: center;
+    padding: 0 var(--sh3-field-pad-x);
+    color: var(--sh3-fg);
+    flex: 1; min-width: 0;
+    overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+    font-family: var(--sh3-font-mono); font-size: 0.75rem;
+  }
+  .sh3-dfp__path--empty { color: var(--sh3-fg-muted); font-family: inherit; font-size: 0.8125rem; font-style: italic; }
+  .sh3-dfp__chevron {
+    display: inline-flex; align-items: center;
+    padding: 0 8px;
+    color: var(--sh3-fg-muted);
+    flex-shrink: 0;
+  }
+</style>

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

@@ -0,0 +1,18 @@
+import type { CommitOnlyEvents } from './_contract';
+import type { DocumentMeta } from '../../documents/types';
+import type { OpenerValue, SaverValue } from './DocumentFilePicker';
+type DocListFn = () => Promise<Array<DocumentMeta & {
+    shardId: string;
+}>>;
+type $$ComponentProps = {
+    mode: 'open' | 'save';
+    value?: OpenerValue | SaverValue;
+    listDocuments: DocListFn;
+    disabled?: boolean;
+    invalid?: boolean;
+    size?: 'sm' | 'md';
+    buttonLabel?: string;
+} & CommitOnlyEvents<OpenerValue | SaverValue>;
+declare const DocumentFilePicker: import("svelte").Component<$$ComponentProps, {}, "value">;
+type DocumentFilePicker = ReturnType<typeof DocumentFilePicker>;
+export default DocumentFilePicker;

package/dist/primitives/widgets/DocumentOpener.svelte

@@ -0,0 +1,36 @@
+<script lang="ts">
+  import type { CommitOnlyEvents } from './_contract';
+  import DocumentFilePicker from './DocumentFilePicker.svelte';
+  import type { DocumentMeta } from '../../documents/types';
+  import type { OpenerValue } from './DocumentFilePicker';
+
+  type DocListFn = () => Promise<Array<DocumentMeta & { shardId: string }>>;
+
+  let {
+    value = $bindable<OpenerValue>(null),
+    listDocuments,
+    disabled = false,
+    invalid = false,
+    size = 'md',
+    buttonLabel = 'Open document…',
+    onchange,
+  }: {
+    value?: OpenerValue;
+    listDocuments: DocListFn;
+    disabled?: boolean;
+    invalid?: boolean;
+    size?: 'sm' | 'md';
+    buttonLabel?: string;
+  } & CommitOnlyEvents<OpenerValue> = $props();
+</script>
+
+<DocumentFilePicker
+  mode="open"
+  bind:value
+  {listDocuments}
+  {disabled}
+  {invalid}
+  {size}
+  {buttonLabel}
+  {onchange}
+/>

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

@@ -0,0 +1,17 @@
+import type { CommitOnlyEvents } from './_contract';
+import type { DocumentMeta } from '../../documents/types';
+import type { OpenerValue } from './DocumentFilePicker';
+type DocListFn = () => Promise<Array<DocumentMeta & {
+    shardId: string;
+}>>;
+type $$ComponentProps = {
+    value?: OpenerValue;
+    listDocuments: DocListFn;
+    disabled?: boolean;
+    invalid?: boolean;
+    size?: 'sm' | 'md';
+    buttonLabel?: string;
+} & CommitOnlyEvents<OpenerValue>;
+declare const DocumentOpener: import("svelte").Component<$$ComponentProps, {}, "value">;
+type DocumentOpener = ReturnType<typeof DocumentOpener>;
+export default DocumentOpener;

package/dist/primitives/widgets/DocumentSaver.svelte

@@ -0,0 +1,36 @@
+<script lang="ts">
+  import type { CommitOnlyEvents } from './_contract';
+  import DocumentFilePicker from './DocumentFilePicker.svelte';
+  import type { DocumentMeta } from '../../documents/types';
+  import type { SaverValue } from './DocumentFilePicker';
+
+  type DocListFn = () => Promise<Array<DocumentMeta & { shardId: string }>>;
+
+  let {
+    value = $bindable<SaverValue>(null),
+    listDocuments,
+    disabled = false,
+    invalid = false,
+    size = 'md',
+    buttonLabel = 'Save as…',
+    onchange,
+  }: {
+    value?: SaverValue;
+    listDocuments: DocListFn;
+    disabled?: boolean;
+    invalid?: boolean;
+    size?: 'sm' | 'md';
+    buttonLabel?: string;
+  } & CommitOnlyEvents<SaverValue> = $props();
+</script>
+
+<DocumentFilePicker
+  mode="save"
+  bind:value
+  {listDocuments}
+  {disabled}
+  {invalid}
+  {size}
+  {buttonLabel}
+  {onchange}
+/>