sh3-core 0.22.5 → 0.23.2

package/dist/projects-shard/ProjectManage.svelte.test.js

@@ -6,7 +6,7 @@ let host;
 let cmp = null;
 let originalFetch;
 function makeProject(overrides = {}) {
-    return Object.assign({ id: 'acme-1234', name: 'Acme', description: '', members: ['user-1'], appAllowlist: [], createdBy: 'user-1', createdAt: 0, updatedAt: 0 }, overrides);
+    return Object.assign({ id: 'acme-1234', name: 'Acme', description: '', members: ['user-1'], appAllowlist: [], shardAllowlist: [], createdBy: 'user-1', createdAt: 0, updatedAt: 0 }, overrides);
 }
 beforeEach(() => {
     __resetAdminUsersForTest();
@@ -33,14 +33,14 @@ afterEach(() => {
     globalThis.fetch = originalFetch;
 });
 describe('ProjectManage tabs', () => {
-    it('renders three tabs: Apps, Users, Mounts', async () => {
+    it('renders four tabs: Apps, Shards, Users, Mounts', async () => {
         cmp = mount(ProjectManage, {
             target: host,
             props: { project: makeProject(), onClose: () => { } },
         });
         await tick();
         const labels = Array.from(host.querySelectorAll('[role="tab"]')).map((el) => { var _a, _b; return (_b = (_a = el.textContent) === null || _a === void 0 ? void 0 : _a.trim()) !== null && _b !== void 0 ? _b : ''; });
-        expect(labels).toEqual(['Apps', 'Users', 'Mounts']);
+        expect(labels).toEqual(['Apps', 'Shards', 'Users', 'Mounts']);
     });
 });
 describe('ProjectManage mount fetch', () => {
@@ -119,7 +119,7 @@ describe('ProjectManage mount list', () => {
         await new Promise((r) => setTimeout(r, 0));
         await tick();
         const tabs = host.querySelectorAll('[role="tab"]');
-        tabs[2].click();
+        tabs[3].click();
         await tick();
         const rows = host.querySelectorAll('[data-mount-row]');
         expect(rows.length).toBe(2);
@@ -150,7 +150,7 @@ describe('ProjectManage mount list', () => {
         await new Promise((r) => setTimeout(r, 0));
         await tick();
         const tabs = host.querySelectorAll('[role="tab"]');
-        tabs[2].click();
+        tabs[3].click();
         await tick();
         const cb = host.querySelector('[data-mount-row="assets"] input[type="checkbox"]');
         expect(cb.checked).toBe(false);
@@ -183,15 +183,16 @@ describe('ProjectManage dirty indicators', () => {
         await tick();
         const tabs = host.querySelectorAll('[role="tab"]');
         expect(host.querySelectorAll('.tab-dirty').length).toBe(0);
-        tabs[2].click();
+        tabs[3].click();
         await tick();
         const cb = host.querySelector('[data-mount-row="assets"] input[type="checkbox"]');
         cb.click();
         await tick();
-        const dirtyDot = tabs[2].querySelector('.tab-dirty');
+        const dirtyDot = tabs[3].querySelector('.tab-dirty');
         expect(dirtyDot).not.toBeNull();
         expect(tabs[0].querySelector('.tab-dirty')).toBeNull();
         expect(tabs[1].querySelector('.tab-dirty')).toBeNull();
+        expect(tabs[2].querySelector('.tab-dirty')).toBeNull();
     });
 });
 describe('ProjectManage save mount diff', () => {
@@ -235,7 +236,7 @@ describe('ProjectManage save mount diff', () => {
         await new Promise((r) => setTimeout(r, 0));
         await tick();
         const tabs = host.querySelectorAll('[role="tab"]');
-        tabs[2].click();
+        tabs[3].click();
         await tick();
         host.querySelector('[data-mount-row="assets"] input').click();
         await tick();
@@ -313,7 +314,7 @@ describe('ProjectManage mount empty state', () => {
         await new Promise((r) => setTimeout(r, 0));
         await tick();
         const tabs = host.querySelectorAll('[role="tab"]');
-        tabs[2].click();
+        tabs[3].click();
         await tick();
         expect(host.textContent).toContain('No mounts configured. Create mounts first.');
     });

package/dist/projects-shard/projectsApi.d.ts

@@ -4,6 +4,7 @@ export interface ProjectRecord {
     description?: string;
     members: string[];
     appAllowlist: string[];
+    shardAllowlist: string[];
     createdBy: string;
     createdAt: number;
     updatedAt: number;
@@ -12,8 +13,8 @@ export declare const projectsApi: {
     list(): Promise<ProjectRecord[]>;
     listAll(): Promise<ProjectRecord[]>;
     get(id: string): Promise<ProjectRecord>;
-    create(input: Pick<ProjectRecord, "name" | "description" | "members" | "appAllowlist">): Promise<ProjectRecord>;
-    update(id: string, patch: Partial<Pick<ProjectRecord, "name" | "description" | "members" | "appAllowlist">>): Promise<ProjectRecord>;
+    create(input: Pick<ProjectRecord, "name" | "description" | "members" | "appAllowlist" | "shardAllowlist">): Promise<ProjectRecord>;
+    update(id: string, patch: Partial<Pick<ProjectRecord, "name" | "description" | "members" | "appAllowlist" | "shardAllowlist">>): Promise<ProjectRecord>;
     delete(id: string, opts?: {
         wipeData?: boolean;
     }): Promise<void>;

package/dist/projects-shard/projectsApi.test.js

@@ -27,7 +27,7 @@ describe('projectsApi', () => {
             ok: true,
             json: async () => ({ id: 'x-1234', name: 'X', members: [], appAllowlist: [], createdBy: 'admin', createdAt: 0, updatedAt: 0 }),
         });
-        const project = await projectsApi.create({ name: 'X', members: [], appAllowlist: [] });
+        const project = await projectsApi.create({ name: 'X', members: [], appAllowlist: [], shardAllowlist: [] });
         expect(globalThis.fetch).toHaveBeenCalledWith('/api/projects', expect.objectContaining({ method: 'POST' }));
         expect(project.id).toBe('x-1234');
     });

package/dist/projects-shard/projectsShard.svelte.js

@@ -54,6 +54,7 @@ export const projectsShard = {
         id: '__projects__',
         label: 'Projects',
         version: VERSION,
+        kind: 'system',
         views: [{ id: PROJECTS_MANAGE_VIEW, label: 'Project Manager' }],
     },
     register(ctx) {

package/dist/runtime/runVerb.d.ts

@@ -1,7 +1,16 @@
 import { type ScrollbackEntry } from '../shell-shard/scrollback.svelte';
+import type { BrowseCapability } from '../documents/browse';
 export interface RunVerbOpts {
     signal?: AbortSignal;
     structured?: unknown;
+    /**
+     * BrowseCapability to expose at `ctx.sh3.docs` inside the invoked verb.
+     * Callers (Sh3Api.runVerb closures) pass their own capability so the
+     * verb inherits the caller's documents:* gating. Undefined means no
+     * docs access — the document-touching verbs will print
+     * "document capability not available".
+     */
+    docs?: BrowseCapability;
 }
 export interface RunVerbResult {
     result: unknown;

package/dist/runtime/runVerb.js

@@ -51,9 +51,9 @@ export async function runVerbProgrammatic(shardId, name, args, opts) {
     return { result, scrollback: captured };
 }
 async function buildProgrammaticContext(b) {
-    var _a, _b;
+    var _a, _b, _c;
     const ctx = {
-        sh3: makeSh3Api({ callerKind: 'verb' }),
+        sh3: makeSh3Api({ callerKind: 'verb', docs: (_a = b.opts) === null || _a === void 0 ? void 0 : _a.docs }),
         scrollback: b.sinkScrollback,
         session: makeStubSession(),
         cwd: '/',
@@ -73,8 +73,8 @@ async function buildProgrammaticContext(b) {
             const innerCtx = Object.assign(Object.assign({}, ctx), { structuredArgs: undefined });
             await resolved.verb.run(innerCtx, parts);
         },
-        structuredArgs: (_a = b.opts) === null || _a === void 0 ? void 0 : _a.structured,
-        signal: (_b = b.opts) === null || _b === void 0 ? void 0 : _b.signal,
+        structuredArgs: (_b = b.opts) === null || _b === void 0 ? void 0 : _b.structured,
+        signal: (_c = b.opts) === null || _c === void 0 ? void 0 : _c.signal,
     };
     return ctx;
 }

package/dist/runtime/runVerb.test.js

@@ -146,4 +146,33 @@ describe('runVerbProgrammatic', () => {
             error: 'no-active-context',
         });
     });
+    it('propagates opts.docs into ctx.sh3.docs for the invoked verb', async () => {
+        let seenDocs = 'untouched';
+        registerShard({
+            manifest: { id: 'docs-probe', label: 'D', version: '0.0.0', views: [] },
+            register(ctx) {
+                ctx.registerVerb(makeVerb('peek', true, async (vctx) => {
+                    seenDocs = vctx.sh3.docs;
+                }));
+            },
+        });
+        await activateShard('docs-probe');
+        const fakeBrowse = { tag: 'fake-browse' };
+        await runVerbProgrammatic('docs-probe', 'docs-probe:peek', [], { docs: fakeBrowse });
+        expect(seenDocs).toBe(fakeBrowse);
+    });
+    it('leaves ctx.sh3.docs undefined when opts.docs is not provided', async () => {
+        let seenDocs = 'untouched';
+        registerShard({
+            manifest: { id: 'docs-probe-2', label: 'D2', version: '0.0.0', views: [] },
+            register(ctx) {
+                ctx.registerVerb(makeVerb('peek', true, async (vctx) => {
+                    seenDocs = vctx.sh3.docs;
+                }));
+            },
+        });
+        await activateShard('docs-probe-2');
+        await runVerbProgrammatic('docs-probe-2', 'docs-probe-2:peek', []);
+        expect(seenDocs).toBeUndefined();
+    });
 });

package/dist/sh3Api/headless.d.ts

@@ -1,11 +1,18 @@
 import type { Sh3Api } from '../shell-shard/registry';
 import type { ZoneManager } from '../state/types';
+import type { BrowseCapability } from '../documents/browse';
 export interface MakeSh3ApiOpts {
     callerKind: 'shard' | 'verb';
     /** Present when callerKind === 'shard' (used by future permission gates). */
     callerShardId?: string;
     /** Cross-shard zone manager — passed in by ShardContext when permitted. */
     zones?: ZoneManager;
+    /**
+     * Tenant-wide BrowseCapability for the calling shard, minted at the call
+     * site from `shard.manifest.permissions`. The factory does not gate; the
+     * caller decides whether to mint and pass one in.
+     */
+    docs?: BrowseCapability;
 }
 export declare function makeSh3Api(opts?: MakeSh3ApiOpts): Sh3Api;
 /** @deprecated Renamed to makeSh3Api(opts?). Kept for one minor cycle. */

package/dist/sh3Api/headless.js

@@ -52,6 +52,7 @@ export function makeSh3Api(opts) {
     void (opts === null || opts === void 0 ? void 0 : opts.callerKind);
     void (opts === null || opts === void 0 ? void 0 : opts.callerShardId);
     const zones = opts === null || opts === void 0 ? void 0 : opts.zones;
+    const docs = opts === null || opts === void 0 ? void 0 : opts.docs;
     function listViewsImpl() {
         try {
             const { root } = inspectActiveLayout();
@@ -298,7 +299,7 @@ export function makeSh3Api(opts) {
             return programmaticOnly ? out.filter((v) => v.programmatic === true) : out;
         },
         async runVerb(shardId, name, args, runOpts) {
-            return runVerbProgrammatic(shardId, name, args, runOpts);
+            return runVerbProgrammatic(shardId, name, args, Object.assign(Object.assign({}, runOpts), { docs }));
         },
         listActions(actionOpts) {
             const all = listActionsFromEntries(listActionEntriesFromRegistry(), getLiveDispatcherState());
@@ -327,6 +328,7 @@ export function makeSh3Api(opts) {
         listProjects() {
             return projectsState.projects.map((p) => ({ id: p.id, name: p.name }));
         },
+        docs,
     };
 }
 /** @deprecated Renamed to makeSh3Api(opts?). Kept for one minor cycle. */

package/dist/sh3Api/headless.svelte.test.js

@@ -101,3 +101,45 @@ describe('sh3Api listActions submenu filter', () => {
         expect(ids).toEqual(['p:a']);
     });
 });
+describe('sh3Api docs capability', () => {
+    it('exposes docs capability when passed via opts', () => {
+        const fakeBrowse = {
+            listDocuments: async () => [],
+            listShards: async () => [],
+            watchDocuments: () => () => { },
+        };
+        const api = makeSh3Api({ callerKind: 'shard', callerShardId: 'x', docs: fakeBrowse });
+        expect(api.docs).toBe(fakeBrowse);
+    });
+    it('leaves docs undefined when opts.docs is omitted', () => {
+        const api = makeSh3Api({ callerKind: 'verb' });
+        expect(api.docs).toBeUndefined();
+    });
+    it('forwards opts.docs through Sh3Api.runVerb into the invoked verb', async () => {
+        const { registerShard, activateShard, __resetShardRegistryForTest } = await import('../shards/lifecycle.svelte');
+        const { __resetViewRegistryForTest } = await import('../shards/registry');
+        const { MemoryDocumentBackend } = await import('../documents/backends');
+        const { __setDocumentBackend, __setActiveScope } = await import('../documents/config');
+        __resetShardRegistryForTest();
+        __resetViewRegistryForTest();
+        __setDocumentBackend(new MemoryDocumentBackend());
+        __setActiveScope('tenant-test');
+        let seenDocs = 'untouched';
+        registerShard({
+            manifest: { id: 'docs-via-api', label: 'D', version: '0.0.0', views: [] },
+            register(ctx) {
+                ctx.registerVerb({
+                    name: 'peek',
+                    summary: 'peek',
+                    programmatic: true,
+                    async run(vctx) { seenDocs = vctx.sh3.docs; },
+                });
+            },
+        });
+        await activateShard('docs-via-api');
+        const fakeBrowse = { tag: 'forwarded' };
+        const api = makeSh3Api({ callerKind: 'shard', callerShardId: 'docs-via-api', docs: fakeBrowse });
+        await api.runVerb('docs-via-api', 'docs-via-api:peek', []);
+        expect(seenDocs).toBe(fakeBrowse);
+    });
+});

package/dist/sh3core-shard/Sh3Home.svelte

@@ -93,7 +93,7 @@
           <button
             type="button"
             class="sh3-home-card"
-            class:sh3-home-card--tinted={appearance?.color}
+            class:sh3-home-card--tinted={appearance?.color ?? manifest.color}
             style:--card-color={appearance?.color ?? manifest.color ?? 'transparent'}
             data-sh3-scope="element:app"
             onclick={() => launchApp(manifest.id)}
@@ -119,8 +119,8 @@
           <button
             type="button"
             class="sh3-home-card"
-            class:sh3-home-card--tinted={appearance?.color}
-            style:--card-color={appearance?.color ?? 'transparent'}
+            class:sh3-home-card--tinted={appearance?.color ?? manifest.color}
+            style:--card-color={appearance?.color ?? manifest.color ?? 'transparent'}
             data-sh3-scope="element:app"
             onclick={() => launchApp(manifest.id)}
             oncontextmenu={(e) => openAppContextMenu(e, manifest.id)}

package/dist/sh3core-shard/sh3coreShard.svelte.js

@@ -60,6 +60,7 @@ export const sh3coreShard = {
         id: '__sh3core__',
         label: 'SH3 Core',
         version: VERSION,
+        kind: 'system',
         views: [
             { id: 'sh3core:home', label: 'Home' },
             { id: 'sh3:keys-and-peers', label: 'Keys & Peers' },

package/dist/shards/lifecycle.svelte.d.ts

@@ -1,9 +1,15 @@
-import type { Shard, ShardContext } from './types';
+import type { Shard, ShardContext, ShardManifest } from './types';
 /**
  * Reactive registry of every shard known to the host. Keys are shard ids.
  * Populated by `registerShard`.
  */
 export declare const registeredShards: Map<string, Shard>;
+/**
+ * Reactive snapshot of every registered shard's manifest. Mirrors
+ * `listRegisteredApps()` — used by project manage UI / ShardPicker to
+ * enumerate service-kind shards.
+ */
+export declare function listRegisteredShards(): ShardManifest[];
 /**
  * Reactive map of shard ids that failed during the lifecycle. Populated
  * by registerAllShards and related operations.
@@ -53,7 +59,7 @@ export declare const activeShards: Map<string, Shard>;
  * an already-entered shard is a no-op. Errors are recorded in
  * `erroredShards` with phase 'register'; one failure does not block others.
  */
-export declare function registerAllShards(): Promise<void>;
+export declare function registerAllShards(allowed?: Set<string> | null): Promise<void>;
 export declare function runAppActivate(shardId: string, appId: string): Promise<void>;
 export declare function runAppDeactivate(shardId: string, appId: string): Promise<void>;
 /**

package/dist/shards/lifecycle.svelte.js

@@ -17,6 +17,7 @@ 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 { documentChanges } from '../documents/notifications';
 import { createShardKeysApi } from '../keys/client';
 import { PERMISSION_KEYS_MINT } from '../keys/types';
 import { makeSh3Api } from '../sh3Api/headless';
@@ -29,11 +30,65 @@ import { clearSelectionForShard } from '../actions/selection.svelte';
 import { fetchEnvState } from '../env/client';
 import { subscribe as subscribeKeyRevocation } from '../keys/revocation-bus.svelte';
 const shardAppBindings = $state(new Map());
+/**
+ * Build the picker-primitive options for a shard: backend-backed
+ * `listFolders` so empty folders surface in the modal, a mutation `handle`
+ * that emits the right documentChanges events, and a `readOnlyShard`
+ * predicate that blocks cross-shard mutations unless the caller holds
+ * `documents:write`.
+ */
+function makePickerOptions(callerShardId, permissions, lockToShard) {
+    const backend = getDocumentBackend();
+    const hasWrite = permissions.includes(PERMISSION_DOCUMENTS_WRITE);
+    return {
+        listFolders: (sid, prefix) => backend.listFolders(getActiveScopeId(), sid, prefix),
+        handle: {
+            mkdir: async (sid, path) => {
+                const tid = getActiveScopeId();
+                await backend.mkdir(tid, sid, path);
+                documentChanges.emit({ type: 'folder-create', path, tenantId: tid, shardId: sid });
+            },
+            rmdir: async (sid, path, opts) => {
+                const tid = getActiveScopeId();
+                await backend.rmdir(tid, sid, path, opts);
+                documentChanges.emit({ type: 'folder-delete', path, tenantId: tid, shardId: sid });
+            },
+            renameFolder: async (sid, oldPath, newPath) => {
+                const tid = getActiveScopeId();
+                await backend.renameFolder(tid, sid, oldPath, newPath);
+                documentChanges.emit({ type: 'folder-rename', path: newPath, oldPath, tenantId: tid, shardId: sid });
+            },
+            rename: async (sid, oldPath, newPath) => {
+                const tid = getActiveScopeId();
+                await backend.rename(tid, sid, oldPath, newPath);
+                documentChanges.emit({ type: 'rename', path: newPath, oldPath, tenantId: tid, shardId: sid });
+            },
+            delete: async (sid, path) => {
+                const tid = getActiveScopeId();
+                const existed = await backend.exists(tid, sid, path);
+                await backend.delete(tid, sid, path);
+                if (existed)
+                    documentChanges.emit({ type: 'delete', path, tenantId: tid, shardId: sid });
+            },
+        },
+        readOnlyShard: (sid) => sid !== callerShardId && !hasWrite,
+        initialShardId: callerShardId,
+        lockToShard,
+    };
+}
 /**
  * Reactive registry of every shard known to the host. Keys are shard ids.
  * Populated by `registerShard`.
  */
 export const registeredShards = $state(new Map());
+/**
+ * Reactive snapshot of every registered shard's manifest. Mirrors
+ * `listRegisteredApps()` — used by project manage UI / ShardPicker to
+ * enumerate service-kind shards.
+ */
+export function listRegisteredShards() {
+    return Array.from(registeredShards.values()).map((s) => s.manifest);
+}
 export const erroredShards = $state(new Map());
 /** Read the app id currently bound to this shard, or null. */
 export function getShardBinding(shardId) {
@@ -65,7 +120,7 @@ export function __setScopeResolver(resolver) {
  * `entry.activeAppId`); otherwise they go to the boot bag.
  */
 export function buildShardContext(shard, entry) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
     const id = shard.manifest.id;
     function trackDisposer(fn) {
         var _a;
@@ -200,15 +255,15 @@ export function buildShardContext(shard, entry) {
             : undefined,
         browse: browseCap,
         documentPicker: browseCap
-            ? createDocumentPicker(() => browseCap.listDocuments())
+            ? createDocumentPicker(() => browseCap.listDocuments(), makePickerOptions(id, (_g = shard.manifest.permissions) !== null && _g !== void 0 ? _g : [], false))
             : createDocumentPicker(async () => {
                 const docs = await getDocumentBackend().list(getActiveScopeId(), 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))
+            }, makePickerOptions(id, (_h = shard.manifest.permissions) !== null && _h !== void 0 ? _h : [], true)),
+        keys: ((_j = shard.manifest.permissions) === null || _j === void 0 ? void 0 : _j.includes(PERMISSION_KEYS_MINT))
             ? createShardKeysApi({
                 shardId: id,
-                shardPermissions: (_h = shard.manifest.permissions) !== null && _h !== void 0 ? _h : [],
+                shardPermissions: (_k = shard.manifest.permissions) !== null && _k !== void 0 ? _k : [],
             })
             : undefined,
         contributions,
@@ -225,9 +280,10 @@ export function buildShardContext(shard, entry) {
         sh3: makeSh3Api({
             callerKind: 'shard',
             callerShardId: id,
-            zones: ((_j = shard.manifest.permissions) === null || _j === void 0 ? void 0 : _j.includes(PERMISSION_STATE_MANAGE))
+            zones: ((_l = shard.manifest.permissions) === null || _l === void 0 ? void 0 : _l.includes(PERMISSION_STATE_MANAGE))
                 ? createZoneManager()
                 : undefined,
+            docs: browseCap,
         }),
     };
     // Stash env state on the ctx for registerAllShards' hydration step.
@@ -241,10 +297,12 @@ export const activeShards = $state(new Map());
  * an already-entered shard is a no-op. Errors are recorded in
  * `erroredShards` with phase 'register'; one failure does not block others.
  */
-export async function registerAllShards() {
+export async function registerAllShards(allowed = null) {
     for (const [id, shard] of registeredShards) {
         if (shardEntries.has(id))
             continue;
+        if (allowed !== null && !allowed.has(id))
+            continue;
         const entry = {
             shard,
             ctx: undefined,

package/dist/shards/lifecycle.test.js

@@ -1,6 +1,14 @@
 import { describe, it, expect, beforeEach } from 'vitest';
-import { getShardBinding, rotateShardDocumentNamespace, __resetLifecycleForTest, registerAllShards, runAppActivate, runAppDeactivate, rebuildShardEntry, shardEntries, } from './lifecycle.svelte';
+import { __setActiveScope, __setDocumentBackend } from '../documents/config';
+import { MemoryDocumentBackend } from '../documents/backends';
+import { getShardBinding, rotateShardDocumentNamespace, __resetLifecycleForTest, registerAllShards, runAppActivate, runAppDeactivate, rebuildShardEntry, shardEntries, listRegisteredShards, } from './lifecycle.svelte';
 import { registerShard, __resetShardRegistryForTest, erroredShards } from './lifecycle.svelte';
+function makeShard(id, registerFn) {
+    return {
+        manifest: { id, label: id, version: '0.0.0', views: [] },
+        register: registerFn,
+    };
+}
 describe('shards/lifecycle — binding map', () => {
     beforeEach(() => __resetLifecycleForTest());
     it('returns null for an unbound shard', () => {
@@ -137,3 +145,104 @@ describe('hot-swap on re-register', () => {
         expect((_c = shardEntries.get('hot-s')) === null || _c === void 0 ? void 0 : _c.shard.manifest.version).toBe('0.0.1');
     });
 });
+describe('registerAllShards with allowed-set gate', () => {
+    beforeEach(() => {
+        __resetLifecycleForTest();
+        __resetShardRegistryForTest();
+    });
+    it('skips shards not in the allowed set when one is provided', async () => {
+        const calls = [];
+        const a = makeShard('shard-a', () => { calls.push('a'); });
+        const b = makeShard('shard-b', () => { calls.push('b'); });
+        const c = makeShard('shard-c', () => { calls.push('c'); });
+        registerShard(a);
+        registerShard(b);
+        registerShard(c);
+        await registerAllShards(new Set(['shard-a', 'shard-c']));
+        expect(calls).toEqual(['a', 'c']);
+        expect(shardEntries.has('shard-a')).toBe(true);
+        expect(shardEntries.has('shard-b')).toBe(false);
+        expect(shardEntries.has('shard-c')).toBe(true);
+    });
+    it('registers everything when allowed-set is null', async () => {
+        const calls = [];
+        const a = makeShard('shard-a', () => { calls.push('a'); });
+        const b = makeShard('shard-b', () => { calls.push('b'); });
+        registerShard(a);
+        registerShard(b);
+        await registerAllShards(null);
+        expect(calls).toEqual(['a', 'b']);
+    });
+    it('registers everything when allowed-set arg is omitted (back-compat)', async () => {
+        const calls = [];
+        const a = makeShard('shard-a', () => { calls.push('a'); });
+        registerShard(a);
+        await registerAllShards();
+        expect(calls).toEqual(['a']);
+    });
+});
+describe('listRegisteredShards', () => {
+    beforeEach(() => {
+        __resetLifecycleForTest();
+        __resetShardRegistryForTest();
+    });
+    it('returns the manifest of every registered shard', () => {
+        var _a;
+        const a = {
+            manifest: { id: 'a', label: 'A', version: '1.0.0', views: [] },
+            register: () => { },
+        };
+        const b = {
+            manifest: { id: 'b', label: 'B', version: '1.0.0', views: [], kind: 'service' },
+            register: () => { },
+        };
+        registerShard(a);
+        registerShard(b);
+        const manifests = listRegisteredShards();
+        expect(manifests.map((m) => m.id).sort()).toEqual(['a', 'b']);
+        expect((_a = manifests.find((m) => m.id === 'b')) === null || _a === void 0 ? void 0 : _a.kind).toBe('service');
+    });
+});
+describe('shards/lifecycle — ctx.sh3.docs wiring', () => {
+    beforeEach(() => {
+        __resetLifecycleForTest();
+        __resetShardRegistryForTest();
+        __setDocumentBackend(new MemoryDocumentBackend());
+        __setActiveScope('tenant-test');
+    });
+    it('mirrors ctx.browse onto ctx.sh3.docs for browse-permitted shards', async () => {
+        let captured = { sh3Docs: 'untouched', ctxBrowse: 'untouched' };
+        const shard = {
+            manifest: {
+                id: 'browse-test',
+                label: 'Browse Test',
+                version: '0.0.1',
+                views: [],
+                permissions: ['documents:browse', 'documents:read', 'documents:write'],
+            },
+            register(ctx) {
+                captured = { sh3Docs: ctx.sh3.docs, ctxBrowse: ctx.browse };
+            },
+        };
+        registerShard(shard);
+        await registerAllShards();
+        expect(captured.sh3Docs).toBeDefined();
+        expect(captured.sh3Docs).toBe(captured.ctxBrowse);
+    });
+    it('leaves ctx.sh3.docs undefined when shard lacks documents:browse', async () => {
+        let docsRef = 'untouched';
+        const shard = {
+            manifest: {
+                id: 'no-browse-test',
+                label: 'No Browse',
+                version: '0.0.1',
+                views: [],
+                permissions: [],
+            },
+            register(ctx) { docsRef = ctx.sh3.docs; },
+        };
+        registerShard(shard);
+        await registerAllShards();
+        expect(docsRef).toBeUndefined();
+    });
+});

package/dist/shards/types.d.ts

@@ -176,6 +176,19 @@ export interface ShardManifest {
      * by sh3-validate at build time.
      */
     verbNamespace?: string;
+    /**
+     * Project-allowlist classification.
+     *   - 'system'  : always allowed in every project scope. The shard is part
+     *                 of the framework/OS surface (e.g. shell-shard). Surfaced
+     *                 read-only in the project manage view.
+     *   - 'service' : opt-in per project. Appears in the Shards tab of the
+     *                 project manage view; admin ticks it to grant write access.
+     *   - omitted   : regular shard. Reached only via an app's
+     *                 requiredShards / bundledShards (existing behavior).
+     *
+     * Apps never set this — shard-only.
+     */
+    kind?: 'system' | 'service';
 }
 /**
  * Source-declared shape of a shard manifest — what external package authors

package/dist/shell-shard/Terminal.svelte

@@ -28,7 +28,6 @@
   import BusySlot from './toolbar/slots/BusySlot.svelte';
   import { registerTerminalView, mintTerminalId, type TerminalHandle } from './terminal-registry';
   import { makeDispatchToTerminal } from './dispatch-to-terminal';
-  import type { BrowseCapability } from '../documents/browse';
 
   interface Props {
     shell: Sh3Api;
@@ -36,9 +35,8 @@
     userId: string;
     role: ShellRole;
     contributions: ContributionsApi;
-    docs?: BrowseCapability;
   }
-  let { shell, wsUrl, userId, role, contributions, docs }: Props = $props();
+  let { shell, wsUrl, userId, role, contributions }: Props = $props();
 
   // Per-mode buffer map. Each ModeBuffer bundles a Scrollback + history +
   // locked flag and is materialized lazily on first switch into that mode.
@@ -252,7 +250,6 @@
     session,
     sh3: shellWithModes,
     fs,
-    docs,
     cwd: () => session.cwd,
     busy: acquireBusy,
     customMode: (id: string) => contributedModes.find((d) => d.id === id) ?? null,

package/dist/shell-shard/Terminal.svelte.d.ts

@@ -1,14 +1,12 @@
 import { type Sh3Api } from './registry';
 import type { ShellRole } from './modes/types';
 import type { ContributionsApi } from '../contributions/types';
-import type { BrowseCapability } from '../documents/browse';
 interface Props {
     shell: Sh3Api;
     wsUrl: string;
     userId: string;
     role: ShellRole;
     contributions: ContributionsApi;
-    docs?: BrowseCapability;
 }
 declare const Terminal: import("svelte").Component<Props, {}, "">;
 type Terminal = ReturnType<typeof Terminal>;