sh3-core 0.22.5 → 0.24.0

package/dist/Sh3.svelte

@@ -79,19 +79,19 @@
 
     const edgePointers = new Set<number>();
 
-    function onPointerDown(e: PointerEvent): void {
+    const onPointerDown = (e: PointerEvent): void => {
       const rect = el.getBoundingClientRect();
       const local = e.clientX - rect.left;
       if (local >= EDGE_PX && local <= rect.width - EDGE_PX) return;
       const granted = claim(e.pointerId, { ownerId: 'sh3:edge', axis: 'x', priority: 'edge', depth: 0 });
       if (granted) edgePointers.add(e.pointerId);
-    }
+    };
 
-    function onPointerEnd(e: PointerEvent): void {
+    const onPointerEnd = (e: PointerEvent): void => {
       if (!edgePointers.has(e.pointerId)) return;
       revoke(e.pointerId, 'sh3:edge');
       edgePointers.delete(e.pointerId);
-    }
+    };
 
     el.addEventListener('pointerdown', onPointerDown);
     el.addEventListener('pointerup', onPointerEnd);

package/dist/actions/listActive.js

@@ -50,6 +50,7 @@ export function listActionsFromEntries(entries, state) {
             ownerShardId: entry.ownerShardId,
             paletteItem: entry.action.paletteItem !== false,
             contextItem: entry.action.contextItem !== false,
+            aiInvocable: entry.action.aiInvocable,
             submenu: entry.action.submenu,
             submenuOf: entry.action.submenuOf,
             active,

package/dist/actions/listActive.test.js

@@ -57,6 +57,19 @@ describe('listActiveFromEntries', () => {
         expect(out[0].paletteItem).toBe(false);
         expect(out[0].contextItem).toBe(true); // defaults to true
     });
+    it('propagates aiInvocable from the registered action, preserving undefined', () => {
+        const entries = [
+            mkEntry({ id: 'opt-out', scope: 'home', aiInvocable: false }),
+            mkEntry({ id: 'opt-in', scope: 'home', aiInvocable: true }),
+            mkEntry({ id: 'unset', scope: 'home' }),
+        ];
+        const out = listActiveFromEntries(entries, mkState());
+        const byId = Object.fromEntries(out.map((d) => [d.id, d]));
+        expect(byId['opt-out'].aiInvocable).toBe(false);
+        expect(byId['opt-in'].aiInvocable).toBe(true);
+        // `undefined` is significant — consumers filter `=== false`, not falsy.
+        expect(byId['unset'].aiInvocable).toBeUndefined();
+    });
     it('dedupes by action id', () => {
         const entries = [
             mkEntry({ id: 'dup', scope: 'home' }, 'shard.a'),

package/dist/actions/types.d.ts

@@ -14,6 +14,14 @@ export interface Action {
     scope: ActionScope;
     contextItem?: boolean;
     paletteItem?: boolean;
+    /**
+     * Opt-out flag for AI tool catalogs. Set `false` to hide this action
+     * from LLM-facing surfaces (e.g. `sh3-ai`'s action→tool adapter) — use
+     * for palette-only actions that need a UI picker and are meaningless
+     * to invoke programmatically. Defaults to `undefined` (catalog
+     * inclusion decided by the consumer).
+     */
+    aiInvocable?: boolean;
     /**
      * Optional menu container id. When set and the active app's declared
      * (or canonical fallback) menu list contains this id, the action
@@ -148,6 +156,8 @@ export interface ActiveActionDescriptor {
     ownerShardId: string;
     paletteItem: boolean;
     contextItem: boolean;
+    /** Carried through from the registered action; see `Action.aiInvocable`. */
+    aiInvocable?: boolean;
     /** True when this action is a submenu parent (children opened by drill). */
     submenu?: true;
     /** Parent action id when this action is a submenu child. */
@@ -187,6 +197,8 @@ export interface ActionDescriptor {
     ownerShardId: string;
     paletteItem: boolean;
     contextItem: boolean;
+    /** Carried through from the registered action; see `Action.aiInvocable`. */
+    aiInvocable?: boolean;
     /** True when this action is a submenu parent (children opened by drill). */
     submenu?: true;
     /** Parent action id when this action is a submenu child. */

package/dist/api.d.ts

@@ -38,7 +38,7 @@ export type { ConflictItem, ConflictBranch as ConflictManagerBranch, ResolveOpti
 export { CONFLICT_RENDERER_POINT, ConflictPermissionError, ConflictSessionOrphanedError, } from './conflicts/api';
 export type { ColorPickOptions, ColorContribution, ColorApi, } from './color/api';
 export { COLOR_PICKER_POINT } from './color/api';
-export { registeredShards, activeShards, erroredShards } from './shards/lifecycle.svelte';
+export { registeredShards, activeShards, erroredShards, listRegisteredShards } from './shards/lifecycle.svelte';
 export type { ShardErrorEntry } from './shards/lifecycle.svelte';
 export type { RegistryIndex, PackageEntry, PackageVersion, RequiredDependency, InstalledPackage, InstallResult, PackageMeta, RemoteInstallRequest, } from './registry/types';
 export type { ResolvedPackage } from './registry/client';
@@ -65,6 +65,8 @@ export type { RunVerbOpts, RunVerbResult } from './runtime';
 export { registerShellMode } from './shell-shard/registerShellMode';
 export type { ShellModeDescriptor, ShellModeOutput, ShellModeDispatchHandler, ShellModeDispatchInput, ShellModeRunsOn, RichEntryHandle, StreamHandle, } from './shell-shard/contract';
 export { SHELL_MODE_CONTRIBUTION_POINT } from './shell-shard/contract';
+export { CONTEXT_SOURCE_POINT_ID } from './contributions/contextSource';
+export type { ContextSource } from './contributions/contextSource';
 export type { GestureRegistry, GestureHandle } from './gestures';
 export type { GestureType, Axis, ClaimPriority, ClaimEntry, PanEvent, ScrollEvent, ButtonEvent, PanOptions, DragOptions, ButtonOptions, ScrollOptions, } from './gestures/types';
 export { VERSION } from './version';

package/dist/api.js

@@ -42,7 +42,7 @@ export { COLOR_PICKER_POINT } from './color/api';
 // and tooling shards that need to visualize framework state. Phase 9
 // addition: diagnostic used to reach `activate.svelte` directly via $lib;
 // the package boundary requires routing through the public surface.
-export { registeredShards, activeShards, erroredShards } from './shards/lifecycle.svelte';
+export { registeredShards, activeShards, erroredShards, listRegisteredShards } from './shards/lifecycle.svelte';
 export { fetchRegistries, fetchArchive, buildPackageMeta } from './registry/client';
 export { validateRegistryIndex } from './registry/schema';
 // Key mint/revoke types — client shards that declare `keys:mint` get ctx.keys.
@@ -65,6 +65,8 @@ export { runVerbProgrammatic } from './runtime';
 // Sh3 mode contributions (external shards extend the sh3 with new modes).
 export { registerShellMode } from './shell-shard/registerShellMode';
 export { SHELL_MODE_CONTRIBUTION_POINT } from './shell-shard/contract';
+// Context-source contributions (publishers register entries; consumers like sh3-ai pick them up).
+export { CONTEXT_SOURCE_POINT_ID } from './contributions/contextSource';
 // Package version.
 export { VERSION } from './version';
 // Framework shard IDs — shards that are always present (built-in to sh3-core).

package/dist/app/admin/adminApp.js

@@ -8,6 +8,8 @@ export const adminApp = {
     manifest: {
         id: 'sh3-admin-app',
         label: 'Admin',
+        icon: 'cpu',
+        color: '#D16F19',
         version: VERSION,
         requiredShards: ['sh3-admin'],
         layoutVersion: 1,

package/dist/app/admin/adminShard.svelte.js

@@ -24,6 +24,7 @@ export const adminShard = {
         id: 'sh3-admin',
         label: 'Admin',
         version: VERSION,
+        kind: 'system',
         permissions: ['documents:mount'],
         views: [
             { id: 'sh3-admin:users', label: 'Users' },

package/dist/app/store/StoreView.svelte

@@ -8,7 +8,7 @@
 
   import { storeContext } from './storeShard.svelte';
   import { fetchArchive, buildPackageMeta } from '../../registry/client';
-  import { readFileFromArchive, readManifestFromArchive } from '../../registry/archive';
+  import { readFileFromArchive } from '../../registry/archive';
   import { installPackage } from '../../registry/installer';
   import { loadBundleModule, type LoadedBundle } from '../../registry/loader';
   import { extractBundlePermissions } from '../../registry/permission-descriptions';

package/dist/app/store/storeApp.js

@@ -10,7 +10,9 @@ import { VERSION } from '../../version';
 export const storeApp = {
     manifest: {
         id: 'sh3-store-app',
-        label: 'Package Store',
+        label: 'Package Manager',
+        icon: 'file-archive',
+        color: '#D16F19',
         version: VERSION,
         requiredShards: ['sh3-store'],
         layoutVersion: 1,

package/dist/app/store/storeShard.svelte.js

@@ -65,6 +65,7 @@ export const storeShard = {
         id: 'sh3-store',
         label: 'Package Store',
         version: VERSION,
+        kind: 'system',
         views: [
             { id: 'sh3-store:browse', label: 'Store' },
         ],

package/dist/app-appearance/appearanceShard.svelte.js

@@ -47,6 +47,7 @@ export const appearanceShard = {
         id: '__app-appearance__',
         label: 'App Appearance',
         version: VERSION,
+        kind: 'system',
         views: [],
     },
     register(ctx) {

package/dist/apps/lifecycle.js

@@ -11,11 +11,13 @@
  * `{ id: string | null }`. Writing happens on launch (id) and on
  * return-to-home (null). Boot reads it to decide whether to auto-launch.
  */
+import { flushSync } from 'svelte';
 import { createStateZones } from '../state/zones.svelte';
 import { createGestureRegistry } from '../gestures';
 import { registeredShards, } from '../shards/lifecycle.svelte';
 import { shardEntries, runAppActivate, runAppDeactivate, registerAllShards, erroredShards } from '../shards/lifecycle.svelte';
 import { attachApp, acquireAppSlotHolds, detachApp, switchToApp, switchToHome, getActiveAppTree, } from '../layout/store.svelte';
+import { flushPendingDestroys } from '../layout/slotHostPool.svelte';
 import { activeApp, breadcrumbApp, getRegisteredApp, registeredApps } from './registry.svelte';
 import { createZoneManager } from '../state/manage';
 import { PERMISSION_STATE_MANAGE } from '../state/types';
@@ -227,19 +229,29 @@ export function unloadApp(id, skipSwitchToHome = false) {
     if (!app)
         return;
     void ((_a = app.deactivate) === null || _a === void 0 ? void 0 : _a.call(app));
-    // v3: call runAppDeactivate for every required shard. The shard stays
-    // active (its register() output is intact); only its per-app bindings
-    // and per-app contribution registrations are torn down.
-    for (const shardId of app.manifest.requiredShards) {
-        void runAppDeactivate(shardId, id);
-    }
-    // Detach layout (releases the refcount holds; pool cleanup runs on
-    // the next microtask for any slots that no longer have a renderer).
-    // Switch to home first so LayoutRenderer stops reading the app's
-    // tree before detachApp drops its references.
+    // Teardown order is load-bearing. Views must be fully unmounted before
+    // any shard's onAppDeactivate runs, so shards can safely close stores /
+    // nullify reactive state in onAppDeactivate without tripping leaked
+    // $derived references in still-mounted views (the leaked-pool bug).
+    //
+    // 1) switchToHome flips the rendered root so LayoutRenderer stops
+    //    reading the app's tree. SlotContainer cleanups are scheduled.
+    // 2) flushSync forces Svelte to run those cleanups now (drops the
+    //    renderer's refcount on every app slot).
+    // 3) detachApp releases the per-app refcount holds. Pool entries for
+    //    the app's slots are now at refcount 0 and queued in pendingDestroy.
+    // 4) flushPendingDestroys synchronously runs the destroy body for
+    //    those entries — the Svelte components for the app's views are
+    //    unmounted now, not on a deferred microtask.
+    // 5) Only now do we call runAppDeactivate on each required shard.
     if (!skipSwitchToHome)
         switchToHome();
+    flushSync();
     detachApp();
+    flushPendingDestroys();
+    for (const shardId of app.manifest.requiredShards) {
+        void runAppDeactivate(shardId, id);
+    }
     activeApp.id = null;
     setActiveApp(null, new Set());
     clearSelectionUnconditional();

package/dist/apps/lifecycle.test.js

@@ -1,7 +1,7 @@
 import { describe, it, expect, beforeEach, vi } from 'vitest';
 import { resetFramework } from '../__test__/reset';
 import { makeApp, makeShard, makeAppManifest, makeShardManifest, makeTabsNode, makeTabEntry, makeSlotNode, makeTree, } from '../__test__/fixtures';
-import { launchApp, returnToHome, unregisterApp } from './lifecycle';
+import { launchApp, returnToHome, unloadApp, unregisterApp } from './lifecycle';
 import { registerApp } from './registry.svelte';
 import { registerShard } from '../shards/lifecycle.svelte';
 import { presetManager } from '../overlays/presets';
@@ -703,6 +703,58 @@ describe('unloadApp — onAppDeactivate hook', () => {
         expect(deactivated).toEqual(['deact-app']);
     });
 });
+describe('unloadApp — view unmount happens before onAppDeactivate', () => {
+    beforeEach(resetFramework);
+    it('unmounts all of the app\'s pooled views before any shard\'s onAppDeactivate fires', async () => {
+        const order = [];
+        const shard = makeShard({
+            manifest: makeShardManifest({ id: 'order-shard' }),
+            register() { },
+            onAppDeactivate() { order.push('onAppDeactivate'); },
+        });
+        registerShard(shard);
+        // Register two views so the assertion covers an active slot AND an
+        // inactive-but-held slot. Both must unmount before deactivate.
+        registerView('order:view-a', {
+            mount: () => ({ unmount: () => order.push('view-a:unmount') }),
+        });
+        registerView('order:view-b', {
+            mount: () => ({ unmount: () => order.push('view-b:unmount') }),
+        });
+        const app = makeApp({
+            manifest: makeAppManifest({ id: 'order-app', requiredShards: ['order-shard'] }),
+            initialLayout: [
+                {
+                    name: 'default',
+                    tree: makeTree({
+                        type: 'split',
+                        direction: 'horizontal',
+                        children: [
+                            makeSlotNode('a-slot', 'order:view-a'),
+                            makeSlotNode('b-slot', 'order:view-b'),
+                        ],
+                        sizes: [0.5, 0.5],
+                    }),
+                },
+            ],
+        });
+        registerApp(app);
+        await launchApp('order-app');
+        // Let the mount microtasks settle so factories have run.
+        await Promise.resolve();
+        await Promise.resolve();
+        unloadApp('order-app');
+        // Both views must have unmounted BEFORE onAppDeactivate ran.
+        const deactivateIdx = order.indexOf('onAppDeactivate');
+        const unmountAIdx = order.indexOf('view-a:unmount');
+        const unmountBIdx = order.indexOf('view-b:unmount');
+        expect(deactivateIdx).toBeGreaterThanOrEqual(0);
+        expect(unmountAIdx).toBeGreaterThanOrEqual(0);
+        expect(unmountBIdx).toBeGreaterThanOrEqual(0);
+        expect(unmountAIdx).toBeLessThan(deactivateIdx);
+        expect(unmountBIdx).toBeLessThan(deactivateIdx);
+    });
+});
 describe('launchApp — onLayoutWillRestore / onLayoutRestored hooks', () => {
     beforeEach(resetFramework);
     it('calls onLayoutWillRestore before slot acquisition and onLayoutRestored after switchToApp', async () => {

package/dist/apps/types.d.ts

@@ -46,6 +46,15 @@ export interface AppManifest {
      * starting shards (diagnostic, __sh3core__) stay running.
      */
     requiredShards: string[];
+    /**
+     * Optional list of shard ids that ship in the same bundle as this app
+     * (combo packages). Mirrors the server-side `project-allowlist`
+     * middleware's resolution rule — these are part of the project-scope
+     * closure when the app is allowlisted, but they are NOT activated
+     * automatically (use `requiredShards` for that). Defaults to empty
+     * when omitted.
+     */
+    bundledShards?: string[];
     /**
      * Bump to invalidate persisted layouts. On launch, a persisted blob
      * whose version doesn't match this is discarded and `initialLayout`

package/dist/chrome/CompactChrome.svelte

@@ -89,16 +89,20 @@
   function toggleFloatsSheet() {
     if (floatsOpen) return;
     floatsOpen = true;
-    const handle = sh3.modal.open(
+    sh3.modal.open(
       FloatsSheet,
       {},
-      { dismissOnBackdrop: true, boxStyle: 'max-width: 320px;' },
+      {
+        dismissOnBackdrop: true,
+        boxStyle: 'max-width: 320px;',
+        // Reset on every dismissal path. Wrapping handle.close after
+        // open() returns doesn't work — ModalFrame captured the close
+        // reference at mount and bypasses any later monkey-patch.
+        onClose: () => {
+          floatsOpen = false;
+        },
+      },
     );
-    const origClose = handle.close;
-    handle.close = () => {
-      origClose();
-      floatsOpen = false;
-    };
   }
 
   function toggleDrawer(anchor: DrawerAnchor) {

package/dist/chrome/MenuSheet.svelte

@@ -15,7 +15,6 @@
     resolveMenuContainers,
     resolveMenuItems,
     resolveSubmenuItems,
-    type MenuBarItem,
   } from '../actions/menuBarModel';
   import { listActions } from '../actions/registry';
   import { getLiveDispatcherState } from '../actions/state.svelte';
@@ -54,7 +53,16 @@
   }
 
   // --- derived items for current nav level ---------------------------
-  const currentItems = $derived.by(() => {
+  interface SheetItem {
+    id: string;
+    label: string;
+    isContainer: boolean;
+    isSubmenu: boolean;
+    shortcut: string | null;
+    disabled: boolean;
+  }
+
+  const currentItems = $derived.by<SheetItem[]>(() => {
     const entries = listActions();
     const nav = currentNav;
 
@@ -65,7 +73,10 @@
         .map((c) => ({
           id: c.id,
           label: c.label,
-          isContainer: true as const,
+          isContainer: true,
+          isSubmenu: false,
+          shortcut: null,
+          disabled: false,
         }));
     }
 
@@ -74,8 +85,9 @@
       return items.map((item) => ({
         id: item.id,
         label: item.label,
-        shortcut: item.shortcut,
+        isContainer: false,
         isSubmenu: item.submenu === true,
+        shortcut: item.shortcut,
         disabled: item.disabled,
       }));
     }
@@ -85,14 +97,15 @@
     return items.map((item) => ({
       id: item.id,
       label: item.label,
+      isContainer: false,
+      isSubmenu: item.submenu === true,
       shortcut: item.shortcut,
       disabled: item.disabled,
-      isSubmenu: item.submenu === true,
     }));
   });
 
   // --- actions --------------------------------------------------------
-  function handleTap(entry: { id: string; isContainer?: boolean; isSubmenu?: boolean }) {
+  function handleTap(entry: SheetItem) {
     if (entry.isContainer) {
       const c = containers.find((x) => x.id === entry.id);
       if (c) push({ kind: 'container', containerId: c.id, label: c.label });

package/dist/contributions/contextSource.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Contribution point id: shards register `ContextSource` descriptors here.
+ * Each registration adds one pickable entry in any consuming UI (e.g. the
+ * "SOURCES" section of the AI Edit modal when sh3-ai is installed) and may
+ * be picked up by future consumers. Lifecycle is publisher-owned — register
+ * when content becomes relevant (app activation, project load, selection),
+ * dispose when it stops being relevant.
+ */
+export declare const CONTEXT_SOURCE_POINT_ID = "sh3.contextSource";
+/** A single context-source contribution. */
+export interface ContextSource {
+    /**
+     * Globally unique. Convention: `<shardId>:<slug>`. Used as the picker
+     * selection key, so it must be stable across re-renders. Re-registering
+     * with an existing id silently replaces — generally dispose the prior
+     * registration first when swapping content.
+     */
+    id: string;
+    /** Short display name shown in the picker row and the chip body. */
+    label: string;
+    /**
+     * Tooltip in any consuming UI. Consumers may also surface this to
+     * downstream tools (e.g. as the description sh3-ai exposes when
+     * chat-side context tools land).
+     */
+    description?: string;
+    /**
+     * Drives prompt formatting (when consumed by sh3-ai) and the chip kind tag.
+     *  - `text` (default): value coerced to string, dumped raw.
+     *  - `markdown`: value coerced to string, wrapped in fenced ```markdown``` block.
+     *  - `json`: value `JSON.stringify`-ed with 2-space indent, wrapped in fenced ```json``` block.
+     */
+    kind?: 'text' | 'markdown' | 'json';
+    /**
+     * Sub-header under the picker's SOURCES section (e.g. the consuming
+     * shard's display name). Entries without a group fall under an "Other"
+     * sub-header.
+     */
+    group?: string;
+    /**
+     * Lazy fetcher. Called when the user picks the chip (for the expand
+     * preview pane) and again at consume time. May be sync or async.
+     * Returning null/undefined signals "no content available right now" —
+     * entry is silently omitted but the chip remains. Throwing/rejecting
+     * surfaces a toast and skips the entry.
+     */
+    get(): unknown | Promise<unknown>;
+}

package/dist/contributions/contextSource.js

@@ -0,0 +1,21 @@
+/*
+ * Public contract for context-source contributions. Shards register
+ * `ContextSource` descriptors at `CONTEXT_SOURCE_POINT_ID` via the
+ * standard `ctx.contributions.register` API; consumers (sh3-ai today,
+ * potentially inspectors / hover previews / chat-side context tools
+ * tomorrow) enumerate them via `ctx.contributions.list`.
+ *
+ * v1 has a single consumer (sh3-ai). The descriptor shape is hosted
+ * here so publisher shards do not need a devDependency on sh3-ai to
+ * contribute. Lifecycle is consumer-owned — see the JSDoc on
+ * `CONTEXT_SOURCE_POINT_ID` below.
+ */
+/**
+ * Contribution point id: shards register `ContextSource` descriptors here.
+ * Each registration adds one pickable entry in any consuming UI (e.g. the
+ * "SOURCES" section of the AI Edit modal when sh3-ai is installed) and may
+ * be picked up by future consumers. Lifecycle is publisher-owned — register
+ * when content becomes relevant (app activation, project load, selection),
+ * dispose when it stops being relevant.
+ */
+export const CONTEXT_SOURCE_POINT_ID = 'sh3.contextSource';

package/dist/createShell.js

@@ -23,6 +23,9 @@ import { attachGlobalListeners } from './actions/listeners';
 import { detectSatelliteMode } from './boot/satelliteMode';
 import { MemoryBackend } from './state/backends';
 import { sessionState, readPendingScope, PENDING_SCOPE_KEY } from './projects/session-state.svelte';
+import { projectsApi } from './projects-shard/projectsApi';
+import { projectsState } from './projects-shard/projectsShard.svelte';
+import { toastManager } from './overlays/toast';
 import SatelliteShell from './satellite/SatelliteShell.svelte';
 export async function createShell(config) {
     var _a, _b;
@@ -87,6 +90,19 @@ export async function createShell(config) {
         if (satellite.payload.projectId) {
             sessionState.activeProjectId = satellite.payload.projectId;
         }
+        // Mirror main-mode: eager-fetch the active project so the register
+        // gate computed in bootstrapSatellite has the allowlist. Fail-closed
+        // identically — drop to personal scope on error.
+        if (sessionState.activeProjectId !== null) {
+            try {
+                const record = await projectsApi.get(sessionState.activeProjectId);
+                projectsState.projects = [record];
+            }
+            catch (err) {
+                console.warn(`[sh3] Satellite: failed to load project "${sessionState.activeProjectId}"; dropping to personal scope:`, err instanceof Error ? err.message : err);
+                sessionState.activeProjectId = null;
+            }
+        }
         __setScopeResolver(() => sessionState.activeProjectId);
         __setShardScopeResolver(() => sessionState.activeProjectId ? 'project' : 'tenant');
         if (config === null || config === void 0 ? void 0 : config.shards)
@@ -154,6 +170,30 @@ export async function createShell(config) {
             }
         }
     }
+    // 4b. Eager-fetch the active project record so the register gate
+    //     (computed in bootstrap()) has the appAllowlist available.
+    //     Fail-closed: a failed fetch drops us to personal scope rather
+    //     than booting with no gate (which would leak shards into the
+    //     project). The user sees a toast on next paint.
+    if (sessionState.activeProjectId !== null) {
+        try {
+            const record = await projectsApi.get(sessionState.activeProjectId);
+            projectsState.projects = [record];
+        }
+        catch (err) {
+            console.warn(`[sh3] Failed to load project "${sessionState.activeProjectId}"; dropping to personal scope:`, err instanceof Error ? err.message : err);
+            sessionState.activeProjectId = null;
+            if (typeof sessionStorage !== 'undefined') {
+                sessionStorage.removeItem(PENDING_SCOPE_KEY);
+            }
+            queueMicrotask(() => {
+                try {
+                    toastManager.notify('Could not load that project; dropped to personal scope.', { level: 'error', duration: 6000 });
+                }
+                catch ( /* overlay not ready; swallow */_a) { /* overlay not ready; swallow */ }
+            });
+        }
+    }
     // 5. Load server-discovered packages
     await loadDiscoveredPackages(config === null || config === void 0 ? void 0 : config.discoveredPackages);
     // 6. Register consumer-provided shards and apps

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

@@ -44,6 +44,46 @@ beforeEach(() => {
 });
 describe('createDocumentPicker', () => {
     const sampleDoc = { shardId: 'my-shard', path: 'readme.md', kind: 'file' };
+    describe('options forwarding to browser modal', () => {
+        it('threads listFolders/handle/readOnlyShard/initialShardId into the modal props', async () => {
+            const listFn = async () => [];
+            const listFolders = vi.fn(async () => ['empty']);
+            const handle = {
+                mkdir: vi.fn(async () => { }),
+                rmdir: vi.fn(async () => { }),
+                renameFolder: vi.fn(async () => { }),
+                rename: vi.fn(async () => { }),
+                delete: vi.fn(async () => { }),
+            };
+            const readOnlyShard = vi.fn(() => false);
+            const picker = createDocumentPicker(listFn, {
+                listFolders, handle, readOnlyShard,
+                initialShardId: 'svg-designer', lockToShard: true,
+            });
+            mockModal();
+            picker.save();
+            await vi.waitFor(() => expect(mockModalOpen).toHaveBeenCalledOnce());
+            const props = mockModalOpen.mock.calls[0][1];
+            expect(props.listFolders).toBe(listFolders);
+            expect(props.handle).toBe(handle);
+            expect(props.readOnlyShard).toBe(readOnlyShard);
+            expect(props.initialShardId).toBe('svg-designer');
+            expect(props.lockToShard).toBe(true);
+        });
+        it('omits options when none provided (backward-compatible single-arg call)', async () => {
+            const listFn = async () => [];
+            const picker = createDocumentPicker(listFn);
+            mockModal();
+            picker.open();
+            await vi.waitFor(() => expect(mockModalOpen).toHaveBeenCalledOnce());
+            const props = mockModalOpen.mock.calls[0][1];
+            expect(props.listFolders).toBeUndefined();
+            expect(props.handle).toBeUndefined();
+            expect(props.readOnlyShard).toBeUndefined();
+            expect(props.initialShardId).toBeUndefined();
+            expect(props.lockToShard).toBeUndefined();
+        });
+    });
     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 }];

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

@@ -1,11 +1,40 @@
 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).
+ * Folder mutation surface forwarded to the document browser modal.
+ * Mirrors the `handle` prop of `_DocumentBrowser.svelte`.
  */
-export declare function createDocumentPicker(listFn: DocListFn): DocumentPickerApi;
+export interface PickerHandleOps {
+    mkdir: (shardId: string, path: string) => Promise<void>;
+    rmdir: (shardId: string, path: string, opts: {
+        recursive: boolean;
+    }) => Promise<void>;
+    renameFolder: (shardId: string, oldPath: string, newPath: string) => Promise<void>;
+    rename: (shardId: string, oldPath: string, newPath: string) => Promise<void>;
+    delete: (shardId: string, path: string) => Promise<void>;
+}
+/**
+ * Construction-time options for `createDocumentPicker`. All optional —
+ * absent values fall back to a read-only listing of `listFn`.
+ */
+export interface DocumentPickerOptions {
+    /** Enumerates immediate child folders of `prefix` in `shardId`. When set,
+     *  empty folders (with no documents underneath) appear in the browser. */
+    listFolders?: (shardId: string, prefix: string) => Promise<string[]>;
+    /** Folder/file mutation surface. When set, the browser exposes a toolbar
+     *  with new-folder / rename / delete actions (gated per shard by
+     *  `readOnlyShard`). */
+    handle?: PickerHandleOps;
+    /** Returns true for shards the caller cannot mutate. The browser hides
+     *  the edit toolbar while navigated into such shards. */
+    readOnlyShard?: (shardId: string) => boolean;
+    /** When set, the browser opens pre-navigated into this shard's namespace
+     *  instead of the (often empty) tenant-wide shard list. The "SH3" crumb
+     *  still lets the user back out — useful in browse mode. */
+    initialShardId?: string;
+    /** When true, the browser is hard-scoped to `initialShardId`: the "SH3"
+     *  breadcrumb is hidden and Backspace at the shard root is a no-op.
+     *  Use this for non-browse shards that can only ever work within their
+     *  own namespace, so the user can't navigate into a dead-end root. */
+    lockToShard?: boolean;
+}
+export declare function createDocumentPicker(listFn: DocListFn, options?: DocumentPickerOptions): DocumentPickerApi;