sh3-core 0.22.5 → 0.24.0

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

@@ -0,0 +1,9 @@
+import type { CommitOnlyEvents } from './_contract';
+type $$ComponentProps = {
+    value?: string[];
+    disabled?: boolean;
+    size?: 'sm' | 'md';
+} & CommitOnlyEvents<string[]>;
+declare const ShardPicker: import("svelte").Component<$$ComponentProps, {}, "value">;
+type ShardPicker = ReturnType<typeof ShardPicker>;
+export default ShardPicker;

package/dist/primitives/widgets/_DocumentBrowser.svelte

@@ -26,6 +26,8 @@
     listFolders,
     handle,
     readOnlyShard,
+    initialShardId = null,
+    lockToShard = false,
   }: {
     mode: 'open' | 'save';
     docs: DocEntry[];
@@ -43,6 +45,8 @@
       delete: (shardId: string, path: string) => Promise<void>;
     };
     readOnlyShard?: (shardId: string) => boolean;
+    initialShardId?: string | null;
+    lockToShard?: boolean;
   } = $props();
 
   type Selected =
@@ -50,12 +54,11 @@
     | { kind: 'folder'; fullPath: string; name: string }
     | null;
 
-  let shardId = $state<string | null>(null);
+  let shardId = $state<string | null>(untrack(() => initialShardId));
   let prefix = $state('');
   let selected = $state<Selected>(null);
   let filename = $state(untrack(() => suggestedName));
   let activeIdx = $state(0);
-  let listEl = $state<HTMLElement | undefined>(undefined);
 
   // Folder state loaded via listFolders
   let folders = $state<string[]>([]);
@@ -76,7 +79,11 @@
   });
 
   const items = $derived(buildTree(docs, folders, shardId, prefix));
-  const crumbs = $derived(breadcrumbSegments(shardId, prefix));
+  const crumbs = $derived(
+    lockToShard
+      ? breadcrumbSegments(shardId, prefix).filter((c) => c.level > 0)
+      : breadcrumbSegments(shardId, prefix),
+  );
 
   $effect(() => {
     items;
@@ -352,7 +359,7 @@
           parts.pop();
           prefix = parts.join('/');
           activeIdx = 0;
-        } else if (shardId) {
+        } else if (shardId && !lockToShard) {
           e.preventDefault();
           shardId = null;
           activeIdx = 0;
@@ -451,11 +458,12 @@
     </div>
   {/if}
 
-  <div class="sh3-doc-browser__list" bind:this={listEl}>
+  <div class="sh3-doc-browser__list">
     {#if confirmDelete}
-      {@const childCount = confirmDelete.kind === 'folder'
+      {@const folderPath = confirmDelete.kind === 'folder' ? confirmDelete.fullPath : null}
+      {@const childCount = folderPath
         ? docs.filter((d) =>
-            d.shardId === shardId && d.path.startsWith(confirmDelete!.fullPath + '/'),
+            d.shardId === shardId && d.path.startsWith(folderPath + '/'),
           ).length
         : 0}
       <div class="sh3-doc-browser__confirm-overlay">

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

@@ -18,6 +18,8 @@ type $$ComponentProps = {
         delete: (shardId: string, path: string) => Promise<void>;
     };
     readOnlyShard?: (shardId: string) => boolean;
+    initialShardId?: string | null;
+    lockToShard?: boolean;
 };
 declare const DocumentBrowser: import("svelte").Component<$$ComponentProps, {}, "">;
 type DocumentBrowser = ReturnType<typeof DocumentBrowser>;

package/dist/projects/scope-gate.d.ts

@@ -0,0 +1,4 @@
+import type { App } from '../apps/types';
+import type { ProjectRecord } from '../projects-shard/projectsApi';
+import type { ShardManifest } from '../shards/types';
+export declare function resolveAllowedShardIds(project: ProjectRecord | null, apps: ReadonlyMap<string, App>, shardManifests: readonly ShardManifest[]): Set<string> | null;

package/dist/projects/scope-gate.js

@@ -0,0 +1,51 @@
+/*
+ * Project-scope register() gate — pure resolution of the shard ids that
+ * may register at boot under a given project's allowlist. Mirrors the
+ * server-side `project-allowlist` middleware so client and server agree
+ * on the closure.
+ *
+ * Returns `null` (no gating) only when the project is null (personal scope)
+ * OR when both `appAllowlist` and `shardAllowlist` are empty. Otherwise the
+ * allowed set is the union of:
+ *   - system-kind shards (always allowed)
+ *   - the resolved `requiredShards`/`bundledShards` of each allowlisted app
+ *   - service-kind shards listed in `project.shardAllowlist`
+ *
+ * The set of system-kind shards is derived at call time from the
+ * registered-shards map; mark framework shards with `kind: 'system'` in
+ * their manifest to keep them reachable inside any project.
+ */
+export function resolveAllowedShardIds(project, apps, shardManifests) {
+    var _a;
+    if (!project)
+        return null;
+    if (project.appAllowlist.length === 0 && project.shardAllowlist.length === 0)
+        return null;
+    const allowed = new Set();
+    const systemShardIds = new Set();
+    const serviceShardIds = new Set();
+    for (const m of shardManifests) {
+        if (m.kind === 'system') {
+            allowed.add(m.id);
+            systemShardIds.add(m.id);
+        }
+        else if (m.kind === 'service') {
+            serviceShardIds.add(m.id);
+        }
+    }
+    for (const appId of project.appAllowlist) {
+        const app = apps.get(appId);
+        if (!app)
+            continue;
+        allowed.add(appId);
+        for (const s of app.manifest.requiredShards)
+            allowed.add(s);
+        for (const s of (_a = app.manifest.bundledShards) !== null && _a !== void 0 ? _a : [])
+            allowed.add(s);
+    }
+    for (const shardId of project.shardAllowlist) {
+        if (serviceShardIds.has(shardId))
+            allowed.add(shardId);
+    }
+    return allowed;
+}

package/dist/projects/scope-gate.test.d.ts

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

package/dist/projects/scope-gate.test.js

@@ -0,0 +1,92 @@
+import { describe, it, expect } from 'vitest';
+import { resolveAllowedShardIds } from './scope-gate';
+function makeApp(id, requiredShards = [], bundledShards) {
+    const manifest = Object.assign({ id, label: id, version: '0.0.0', requiredShards, layoutVersion: 1 }, (bundledShards ? { bundledShards } : {}));
+    return { manifest, initialLayout: { kind: 'leaf', viewId: 'x' } };
+}
+function makeProject(appAllowlist, shardAllowlist = []) {
+    return {
+        id: 'acme-1234',
+        name: 'Acme',
+        members: ['u1'],
+        appAllowlist,
+        shardAllowlist,
+        createdBy: 'u1',
+        createdAt: 0,
+        updatedAt: 0,
+    };
+}
+const SYSTEM_SHARDS = [
+    { id: 'shell', label: 'Shell', version: '0', kind: 'system', views: [] },
+    { id: '__sh3core__', label: 'SH3 Core', version: '0', kind: 'system', views: [] },
+];
+describe('resolveAllowedShardIds', () => {
+    it('returns null (no gating) when project is null', () => {
+        expect(resolveAllowedShardIds(null, new Map(), SYSTEM_SHARDS)).toBeNull();
+    });
+    it('returns null (no gating) when both allowlists are empty', () => {
+        const project = makeProject([], []);
+        expect(resolveAllowedShardIds(project, new Map(), SYSTEM_SHARDS)).toBeNull();
+    });
+    it('returns system-kind shards only when allowlist contains no resolvable apps', () => {
+        const project = makeProject(['ghost-app']);
+        const apps = new Map();
+        const allowed = resolveAllowedShardIds(project, apps, SYSTEM_SHARDS);
+        expect(allowed.has('shell')).toBe(true);
+        expect(allowed.has('__sh3core__')).toBe(true);
+        expect(allowed.has('ghost-app')).toBe(false);
+    });
+    it('includes app id + requiredShards for each resolved app, plus system shards', () => {
+        const project = makeProject(['notes']);
+        const apps = new Map([
+            ['notes', makeApp('notes', ['notes-shard', 'editor'])],
+        ]);
+        const allowed = resolveAllowedShardIds(project, apps, SYSTEM_SHARDS);
+        expect(allowed.has('shell')).toBe(true);
+        expect(allowed.has('__sh3core__')).toBe(true);
+        expect(allowed.has('notes')).toBe(true);
+        expect(allowed.has('notes-shard')).toBe(true);
+        expect(allowed.has('editor')).toBe(true);
+    });
+    it('includes bundledShards when the app declares them', () => {
+        const project = makeProject(['guml-ide']);
+        const apps = new Map([
+            ['guml-ide', makeApp('guml-ide', ['guml.core'], ['guml.preview'])],
+        ]);
+        const allowed = resolveAllowedShardIds(project, apps, SYSTEM_SHARDS);
+        expect(allowed.has('guml.core')).toBe(true);
+        expect(allowed.has('guml.preview')).toBe(true);
+    });
+    it('unions across multiple allowlisted apps', () => {
+        const project = makeProject(['notes', 'files']);
+        const apps = new Map([
+            ['notes', makeApp('notes', ['notes-shard'])],
+            ['files', makeApp('files', ['files-shard'])],
+        ]);
+        const allowed = resolveAllowedShardIds(project, apps, SYSTEM_SHARDS);
+        expect(allowed.has('notes-shard')).toBe(true);
+        expect(allowed.has('files-shard')).toBe(true);
+    });
+    it('includes service-kind shards listed in shardAllowlist', () => {
+        const project = makeProject([], ['svc-a']);
+        const manifests = [
+            ...SYSTEM_SHARDS,
+            { id: 'svc-a', label: 'Svc A', version: '0', kind: 'service', views: [] },
+            { id: 'svc-b', label: 'Svc B', version: '0', kind: 'service', views: [] },
+        ];
+        const allowed = resolveAllowedShardIds(project, new Map(), manifests);
+        expect(allowed.has('svc-a')).toBe(true);
+        expect(allowed.has('svc-b')).toBe(false);
+        expect(allowed.has('shell')).toBe(true);
+    });
+    it('ignores shardAllowlist entries that are not service-kind', () => {
+        const project = makeProject([], ['not-a-service']);
+        const manifests = [
+            ...SYSTEM_SHARDS,
+            { id: 'not-a-service', label: 'X', version: '0', views: [] },
+        ];
+        const allowed = resolveAllowedShardIds(project, new Map(), manifests);
+        expect(allowed.has('not-a-service')).toBe(false);
+        expect(allowed.has('shell')).toBe(true);
+    });
+});

package/dist/projects-shard/ProjectManage.svelte

@@ -13,7 +13,9 @@
   import { refreshProjects } from './projectsShard.svelte';
   import { getUser } from '../auth/auth.svelte';
   import AppPicker from '../primitives/widgets/AppPicker.svelte';
+  import ShardPicker from '../primitives/widgets/ShardPicker.svelte';
   import UserPicker from '../primitives/widgets/UserPicker.svelte';
+  import { listRegisteredShards } from '../shards/lifecycle.svelte';
   import TabbedPanel from '../primitives/TabbedPanel.svelte';
   import { modalManager } from '../overlays/modal';
   import DeleteProjectDialog from './DeleteProjectDialog.svelte';
@@ -50,6 +52,9 @@
   let appAllowlist = $state<string[]>(
     untrack(() => (project ? [...project.appAllowlist] : [])),
   );
+  let shardAllowlist = $state<string[]>(
+    untrack(() => (project ? [...(project.shardAllowlist ?? [])] : [])),
+  );
   let saving = $state(false);
   let error = $state<string | null>(null);
   let activeTab = $state(0);
@@ -58,6 +63,9 @@
   let mountsLoading = $state(true);
   let mountsLoadError = $state<string | null>(null);
   let baselineApps = $state<string[]>(untrack(() => (project ? [...project.appAllowlist] : [])));
+  let baselineShards = $state<string[]>(
+    untrack(() => (project ? [...(project.shardAllowlist ?? [])] : [])),
+  );
   let baselineMembers = $state<string[]>(
     untrack(() => {
       if (project) return [...project.members];
@@ -80,9 +88,16 @@
   }
 
   const appsDirty = $derived(!arrayEq(appAllowlist, baselineApps));
+  const shardsDirty = $derived(!arrayEq(shardAllowlist, baselineShards));
   const membersDirty = $derived(!arrayEq(members, baselineMembers));
   const mountsDirty = $derived(!setEq(mountAttached, baselineMounts));
 
+  const systemShards = $derived(
+    listRegisteredShards()
+      .filter((m) => m.kind === 'system')
+      .sort((a, b) => a.label.localeCompare(b.label)),
+  );
+
   async function save() {
     if (!name.trim()) {
       error = 'Name is required';
@@ -95,6 +110,7 @@
       description: description.trim() || undefined,
       members,
       appAllowlist,
+      shardAllowlist,
     };
     try {
       const saved = isEdit && project
@@ -234,10 +250,10 @@
 
   <div class="tabs">
     <TabbedPanel
-      labels={['Apps', 'Users', 'Mounts']}
+      labels={['Apps', 'Shards', 'Users', 'Mounts']}
       {activeTab}
       onActiveChange={(i) => (activeTab = i)}
-      dirty={[appsDirty, membersDirty, mountsDirty]}
+      dirty={[appsDirty, shardsDirty, membersDirty, mountsDirty]}
       body={tabBody}
     />
   </div>
@@ -265,6 +281,19 @@
         <AppPicker bind:value={appAllowlist} disabled={saving} />
       </label>
     {:else if i === 1}
+      <label class="field">
+        <span>Services</span>
+        <ShardPicker bind:value={shardAllowlist} disabled={saving} />
+      </label>
+      <details class="system-block">
+        <summary>System (always allowed)</summary>
+        <ul class="system-list">
+          {#each systemShards as m (m.id)}
+            <li><span class="system-label">{m.label}</span><span class="system-id">{m.id}</span></li>
+          {/each}
+        </ul>
+      </details>
+    {:else if i === 2}
       <label class="field">
         <span>Members</span>
         <UserPicker bind:value={members} disabled={saving} />
@@ -385,4 +414,15 @@
   }
   .actions button.danger { margin-left: auto; color: var(--sh3-error, #c33); }
   .actions button:disabled { opacity: 0.5; cursor: not-allowed; }
+  .system-block { margin-top: 16px; font-size: 13px; }
+  .system-block summary {
+    cursor: pointer;
+    color: var(--sh3-fg-muted);
+    padding: 4px 0;
+    user-select: none;
+  }
+  .system-list { list-style: none; margin: 4px 0 0; padding: 0; display: flex; flex-direction: column; gap: 2px; }
+  .system-list li { display: flex; justify-content: space-between; gap: 8px; color: var(--sh3-fg-muted); padding: 4px 0; }
+  .system-id { font-size: 11px; font-family: var(--sh3-font-mono, monospace); }
+  .system-label { font-weight: 500; }
 </style>

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

@@ -18,7 +18,6 @@
   import { makeSelectionApi } from '../actions/selection.svelte';
   import { getAppearance } from '../app-appearance';
   import iconsUrl from '../assets/icons.svg';
-  import { manifest } from '../shell-shard/manifest';
 
   const homeSelection = makeSelectionApi('__sh3core__');
 
@@ -93,7 +92,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 +118,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)}