sh3-core 0.11.7 → 0.12.0

package/dist/api.js

@@ -38,7 +38,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 } from './shards/activate.svelte';
+export { registeredShards, activeShards, erroredShards } from './shards/activate.svelte';
 export { fetchRegistries, fetchBundle, buildPackageMeta } from './registry/client';
 export { validateRegistryIndex } from './registry/schema';
 // Key mint/revoke types — client shards that declare `keys:mint` get ctx.keys.

package/dist/app/store/InstalledView.svelte

@@ -278,7 +278,8 @@
   }
   .installed-update-btn {
     padding: 4px 12px;
-    background: var(--shell-warning, #ff9800);
+    background: var(--shell-warning, #fbbf24);
+    color: var(--shell-fg-on-warning, #1a1b1e);
     font-size: 0.8125rem;
   }
   .installed-update-btn:hover:not(:disabled) {

package/dist/app/store/StoreView.svelte

@@ -594,7 +594,8 @@
   }
   .store-update-btn {
     padding: 5px 14px;
-    background: var(--shell-warning, #ff9800);
+    background: var(--shell-warning, #fbbf24);
+    color: var(--shell-fg-on-warning, #1a1b1e);
     font-size: 0.8125rem;
   }
   .store-update-btn:hover:not(:disabled) {

package/dist/apps/lifecycle.d.ts

@@ -4,6 +4,13 @@
  * returned to home or no app has ever been launched.
  */
 export declare function readLastApp(): string | null;
+/**
+ * Public reset for the last-active-app user-zone slot. Used by the host's
+ * boot sequence to recover from a sticky last-app launch failure: if the
+ * auto-launch fails, this clears the slot so the next reload lands on home
+ * instead of looping into the same failure.
+ */
+export declare function clearLastApp(): void;
 /**
  * Launch an app by id. Activates all required shards (idempotent for
  * already-active shards), attaches the app's layout, calls `App.activate`,

package/dist/apps/lifecycle.js

@@ -20,6 +20,7 @@ import { PERMISSION_STATE_MANAGE } from '../state/types';
 import { setActiveApp, setUserBindings } from '../actions/state.svelte';
 import { clearSelectionUnconditional } from '../actions/selection.svelte';
 import { loadUserBindings } from '../actions/bindings-store';
+import { toastManager } from '../overlays/toast';
 // ---------- last-active-app user zone ------------------------------------
 /**
  * Framework-reserved user-zone slot storing which app to boot into on
@@ -41,6 +42,15 @@ export function readLastApp() {
 function writeLastApp(id) {
     lastAppState.user.id = id;
 }
+/**
+ * Public reset for the last-active-app user-zone slot. Used by the host's
+ * boot sequence to recover from a sticky last-app launch failure: if the
+ * auto-launch fails, this clears the slot so the next reload lands on home
+ * instead of looping into the same failure.
+ */
+export function clearLastApp() {
+    writeLastApp(null);
+}
 // ---------- app-context state factories ----------------------------------
 const appContexts = new Map();
 function getOrCreateAppContext(appId) {
@@ -72,7 +82,7 @@ function getOrCreateAppContext(appId) {
  * @throws If the app is not registered or a required shard is not registered.
  */
 export async function launchApp(id) {
-    var _a, _b, _c, _d, _e, _f, _g;
+    var _a, _b, _c, _d, _e, _f, _g, _h;
     const app = getRegisteredApp(id);
     if (!app) {
         throw new Error(`Cannot launch app "${id}": not registered`);
@@ -118,23 +128,30 @@ export async function launchApp(id) {
     attachApp(app);
     try {
         for (const shardId of app.manifest.requiredShards) {
-            await activateShard(shardId);
+            await activateShard(shardId, { phase: 'launch' });
         }
     }
     catch (err) {
         detachApp();
+        try {
+            toastManager.notify(`Couldn't launch "${(_e = app.manifest.label) !== null && _e !== void 0 ? _e : id}": ${err instanceof Error ? err.message : String(err)}`, { level: 'error', duration: 6000 });
+        }
+        catch (_j) {
+            // Toast layer not mounted (e.g. early boot, tests without Shell).
+            // Best-effort UX — original error must still propagate.
+        }
         throw err;
     }
     // Shards have registered their view factories — safe to take the
     // refcount holds on the app's slots now (pool's factory lookup
     // happens in a microtask from this call).
     acquireAppSlotHolds();
-    void ((_e = app.activate) === null || _e === void 0 ? void 0 : _e.call(app, getOrCreateAppContext(id)));
+    void ((_f = app.activate) === null || _f === void 0 ? void 0 : _f.call(app, getOrCreateAppContext(id)));
     activeApp.id = id;
-    setActiveApp(id, new Set((_f = app.manifest.requiredShards) !== null && _f !== void 0 ? _f : []));
+    setActiveApp(id, new Set((_g = app.manifest.requiredShards) !== null && _g !== void 0 ? _g : []));
     void loadUserBindings(id).then(setUserBindings);
     switchToApp();
-    void ((_g = app.onAppReady) === null || _g === void 0 ? void 0 : _g.call(app, getOrCreateAppContext(id)));
+    void ((_h = app.onAppReady) === null || _h === void 0 ? void 0 : _h.call(app, getOrCreateAppContext(id)));
     writeLastApp(id);
     breadcrumbApp.id = id;
 }

package/dist/apps/lifecycle.test.js

@@ -517,3 +517,53 @@ describe('breadcrumbAppId', () => {
         expect(getBreadcrumbAppId()).toBe('app-bc3b');
     });
 });
+// ---------------------------------------------------------------------------
+// launchApp — error toast on required-shard activation failure
+// ---------------------------------------------------------------------------
+describe('launchApp — error toast on shard failure', () => {
+    beforeEach(resetFramework);
+    it('fires an error-level toast when a required shard fails to activate', async () => {
+        const { toastManager } = await import('../overlays/toast');
+        const notifySpy = vi
+            .spyOn(toastManager, 'notify')
+            .mockImplementation(() => ({ close: () => { } }));
+        const badShard = makeShard({
+            manifest: makeShardManifest({ id: 'bad-toast' }),
+            activate: () => {
+                throw new Error('shard "other" not registered');
+            },
+        });
+        registerShard(badShard);
+        registerApp(makeApp({
+            manifest: makeAppManifest({
+                id: 'app-toast',
+                label: 'Toast App',
+                requiredShards: ['bad-toast'],
+            }),
+        }));
+        await expect(launchApp('app-toast')).rejects.toThrow('shard "other" not registered');
+        expect(notifySpy).toHaveBeenCalledTimes(1);
+        const [message, options] = notifySpy.mock.calls[0];
+        expect(message).toContain('Toast App');
+        expect(message).toContain('shard "other" not registered');
+        expect(options === null || options === void 0 ? void 0 : options.level).toBe('error');
+        notifySpy.mockRestore();
+    });
+});
+// ---------------------------------------------------------------------------
+// clearLastApp — public reset for the last-active-app user-zone slot
+// ---------------------------------------------------------------------------
+describe('clearLastApp', () => {
+    beforeEach(resetFramework);
+    it('writes null to the last-app user zone', async () => {
+        const { clearLastApp, readLastApp } = await import('./lifecycle');
+        registerShard(makeShard({ manifest: makeShardManifest({ id: 's-cla' }) }));
+        registerApp(makeApp({
+            manifest: makeAppManifest({ id: 'app-cla', requiredShards: ['s-cla'] }),
+        }));
+        await launchApp('app-cla');
+        expect(readLastApp()).toBe('app-cla');
+        clearLastApp();
+        expect(readLastApp()).toBeNull();
+    });
+});

package/dist/documents/browse.d.ts

@@ -76,6 +76,21 @@ export interface BrowseCapability {
     renameFrom?(shardId: string, oldPath: string, newPath: string, opts?: {
         newShardId?: string;
     }): Promise<void>;
+    /**
+     * Delete a document in another shard's namespace within the active
+     * tenant. Available only when the caller declares both
+     * `documents:browse` and `documents:write`. Emits a `'delete'`
+     * `DocumentChange` so other shards and the file-explorer pick up
+     * the removal. Tenant-scoped — cannot cross tenants.
+     *
+     * Idempotent: deleting a non-existent path resolves successfully
+     * and emits no change event.
+     *
+     * Absent (undefined) on the capability object when `documents:write`
+     * is not declared; feature-detect with
+     * `typeof ctx.browse.deleteFrom === 'function'`.
+     */
+    deleteFrom?(shardId: string, path: string): Promise<void>;
 }
 export interface BrowseCapabilityOptions {
     /** When true, the returned capability exposes `readFrom`. */

package/dist/documents/browse.js

@@ -59,6 +59,13 @@ export function createBrowseCapability(tenantId, backend, options = { canRead: f
                 shardId,
             });
         };
+        capability.deleteFrom = async (shardId, path) => {
+            const existed = await backend.exists(tenantId, shardId, path);
+            await backend.delete(tenantId, shardId, path);
+            if (existed) {
+                documentChanges.emit({ type: 'delete', path, tenantId, shardId });
+            }
+        };
     }
     return capability;
 }

package/dist/documents/browse.test.js

@@ -263,4 +263,45 @@ describe('BrowseCapability', () => {
                 .rejects.toThrow(/does not support resolveConflict/);
         });
     });
+    describe('deleteFrom (documents:write gate)', () => {
+        it('absent when canWrite is false', () => {
+            const be = new MemoryDocumentBackend();
+            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            expect(browse.deleteFrom).toBeUndefined();
+        });
+        it('present when canWrite is true', () => {
+            const be = new MemoryDocumentBackend();
+            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            expect(typeof browse.deleteFrom).toBe('function');
+        });
+        it('deletes from the target shard namespace and emits a delete event', async () => {
+            const be = new MemoryDocumentBackend();
+            await be.write('t1', 'target-shard', 'a.txt', 'hello');
+            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const events = [];
+            const unsub = documentChanges.subscribe((c) => events.push(c));
+            await browse.deleteFrom('target-shard', 'a.txt');
+            expect(await be.read('t1', 'target-shard', 'a.txt')).toBeNull();
+            expect(events).toEqual([
+                { type: 'delete', path: 'a.txt', tenantId: 't1', shardId: 'target-shard' },
+            ]);
+            unsub();
+        });
+        it('is idempotent on missing paths and emits no event', async () => {
+            const be = new MemoryDocumentBackend();
+            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const events = [];
+            const unsub = documentChanges.subscribe((c) => events.push(c));
+            await expect(browse.deleteFrom('target-shard', 'nope.txt')).resolves.toBeUndefined();
+            expect(events).toEqual([]);
+            unsub();
+        });
+        it('never crosses tenants: a t1 capability cannot delete t2 docs', async () => {
+            const be = new MemoryDocumentBackend();
+            await be.write('t2', 's', 'secret.txt', 'hidden');
+            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            await browse.deleteFrom('s', 'secret.txt');
+            expect(await be.read('t2', 's', 'secret.txt')).toBe('hidden');
+        });
+    });
 });

package/dist/documents/handle.js

@@ -55,8 +55,10 @@ export function createDocumentHandle(tenantId, shardId, backend, options) {
             emitChange(existed ? 'update' : 'create', path);
         },
         async delete(path) {
+            const existed = await backend.exists(tenantId, shardId, path);
             await backend.delete(tenantId, shardId, path);
-            emitChange('delete', path);
+            if (existed)
+                emitChange('delete', path);
         },
         async rename(oldPath, newPath) {
             if (!matchesExtensions(newPath)) {

package/dist/documents/handle.test.js

@@ -1,6 +1,7 @@
 import { describe, it, expect } from 'vitest';
 import { MemoryDocumentBackend } from './backends';
 import { createDocumentHandle } from './handle';
+import { documentChanges } from './notifications';
 function harness() {
     const backend = new MemoryDocumentBackend();
     const handle = createDocumentHandle('tenant1', 'shard1', backend, { format: 'text' });
@@ -141,3 +142,25 @@ describe('DocumentHandle.rename', () => {
             .rejects.toThrow(/extensions/);
     });
 });
+describe('DocumentHandle.delete()', () => {
+    it('emits a delete event when the path existed', async () => {
+        const { backend, handle } = harness();
+        await backend.write('tenant1', 'shard1', 'a.txt', 'hi');
+        const events = [];
+        const unsub = documentChanges.subscribe((c) => events.push(c));
+        await handle.delete('a.txt');
+        expect(await backend.read('tenant1', 'shard1', 'a.txt')).toBeNull();
+        expect(events).toEqual([
+            { type: 'delete', path: 'a.txt', tenantId: 'tenant1', shardId: 'shard1' },
+        ]);
+        unsub();
+    });
+    it('emits no event when the path did not exist', async () => {
+        const { handle } = harness();
+        const events = [];
+        const unsub = documentChanges.subscribe((c) => events.push(c));
+        await expect(handle.delete('nope.txt')).resolves.toBeUndefined();
+        expect(events).toEqual([]);
+        unsub();
+    });
+});

package/dist/host.js

@@ -18,7 +18,7 @@
 import { registerShard as registerShardInternal, activateShard, registeredShards, } from './shards/activate.svelte';
 import { addAutostartShard } from './actions/state.svelte';
 import { registerApp, registeredApps } from './apps/registry.svelte';
-import { launchApp, readLastApp } from './apps/lifecycle';
+import { launchApp, readLastApp, clearLastApp } from './apps/lifecycle';
 import { sh3coreShard } from './sh3core-shard/sh3coreShard.svelte';
 import { shellShard } from './shell-shard/shellShard.svelte';
 import { storeShard } from './app/store/storeShard.svelte';
@@ -77,13 +77,27 @@ export async function bootstrap(config) {
     for (const [id, shard] of registeredShards) {
         if (shard.autostart) {
             addAutostartShard(id);
-            await activateShard(id);
+            try {
+                await activateShard(id, { phase: 'autostart' });
+            }
+            catch (_a) {
+                // Already logged + recorded in erroredShards by activateShard.
+                // One bad self-starting shard must not prevent the shell from booting.
+            }
         }
     }
-    // 5. Read the last-active app from the user zone
+    // 5. Read the last-active app from the user zone. If auto-launch fails,
+    // clear the slot so the next reload lands on home instead of looping
+    // into the same failure. No toast — the user did not initiate this.
     const lastId = readLastApp();
     if (lastId && registeredApps.has(lastId)) {
-        await launchApp(lastId);
+        try {
+            await launchApp(lastId);
+        }
+        catch (err) {
+            console.error(`[sh3] Auto-launch of "${lastId}" failed:`, err);
+            clearLastApp();
+        }
     }
 }
 export { installPackage, listInstalledPackages } from './registry/installer';

package/dist/layout/LayoutRenderer.svelte

@@ -202,7 +202,11 @@
         {@const entry = tabs?.tabs[i]}
         {#if entry}
           <div class="tab-slot-wrapper">
-            <SlotContainer node={{ type: 'slot', slotId: entry.slotId, viewId: entry.viewId }} label={entry.label} />
+            <SlotContainer
+              node={{ type: 'slot', slotId: entry.slotId, viewId: entry.viewId }}
+              label={entry.label}
+              meta={entry.meta}
+            />
             <SlotDropZone {rootRef} path={path} />
           </div>
         {/if}

package/dist/layout/LayoutRenderer.test.js

@@ -119,6 +119,48 @@ describe('LayoutRenderer — C.4 tabless preset', () => {
         expect(container.querySelector('[role="tab"]')).toBeNull();
     });
 });
+describe('LayoutRenderer — C.6 TabEntry.meta threading', () => {
+    beforeEach(resetFramework);
+    it('forwards meta on a tab added post-launch (e.g. via floatManager.open)', async () => {
+        let captured;
+        registerView('test:meta-view', {
+            mount(_container, ctx) {
+                captured = ctx.meta;
+                return { unmount: () => { } };
+            },
+        });
+        // Launch with a placeholder tab — its slotId differs from the one we
+        // push later, so acquireAppSlotHolds takes no hold for the new tab.
+        // The new tab's first acquire is therefore SlotContainer's $effect,
+        // which is the gap the bug lives in.
+        registerApp(makeApp({
+            manifest: makeAppManifest({ id: 'c6' }),
+            initialLayout: [
+                {
+                    name: 'default',
+                    tree: makeTree(makeTabsNode([makeTabEntry({ slotId: 'placeholder', viewId: 'test:view' })])),
+                },
+            ],
+        }));
+        await launchApp('c6');
+        renderWithShell(LayoutRenderer, { path: [] });
+        await tick();
+        const root = layoutStore.root;
+        if ((root === null || root === void 0 ? void 0 : root.type) !== 'tabs')
+            throw new Error('expected tabs root');
+        root.tabs.push({
+            slotId: 'meta-slot',
+            viewId: 'test:meta-view',
+            label: 'M',
+            meta: { source: 'data:url', isBlob: false, label: 'pic.png' },
+        });
+        root.activeTab = 1;
+        await tick();
+        // acquireSlotHost defers factory.mount via queueMicrotask — flush it.
+        await Promise.resolve();
+        expect(captured).toEqual({ source: 'data:url', isBlob: false, label: 'pic.png' });
+    });
+});
 describe('LayoutRenderer — C.5 invalid path', () => {
     beforeEach(resetFramework);
     it('renders nothing when the path no longer resolves to a node', async () => {

package/dist/layout/SlotContainer.svelte

@@ -38,7 +38,11 @@
   import { getView } from '../shards/registry';
   import { acquireSlotHost, releaseSlotHost } from './slotHostPool.svelte';
 
-  let { node, label = '' }: { node: SlotNode; label?: string } = $props();
+  let {
+    node,
+    label = '',
+    meta,
+  }: { node: SlotNode; label?: string; meta?: Record<string, unknown> } = $props();
 
   let wrapper: HTMLDivElement | undefined = $state();
   let width = $state(0);
@@ -62,7 +66,12 @@
     //     detach if still in our wrapper" guard.
     const currentSlotId = node.slotId;
     const wrapperEl = wrapper;
-    const host = acquireSlotHost(currentSlotId, node.viewId, label || node.viewId || currentSlotId);
+    const host = acquireSlotHost(
+      currentSlotId,
+      node.viewId,
+      label || node.viewId || currentSlotId,
+      meta,
+    );
     wrapperEl.appendChild(host);
 
     // Local observer exists only to drive the placeholder's dims text;

package/dist/layout/SlotContainer.svelte.d.ts

@@ -2,6 +2,7 @@ import type { SlotNode } from './types';
 type $$ComponentProps = {
     node: SlotNode;
     label?: string;
+    meta?: Record<string, unknown>;
 };
 declare const SlotContainer: import("svelte").Component<$$ComponentProps, {}, "">;
 type SlotContainer = ReturnType<typeof SlotContainer>;

package/dist/layout/slotHostPool.svelte.js

@@ -35,6 +35,7 @@
 import { getView, __addViewRegistrationListener } from '../shards/registry';
 import { locateSlotIn } from './ops';
 import { activeLayout } from './store.svelte';
+import { scopeToString } from '../actions/scope-helpers';
 const pool = new Map();
 const pendingDestroy = new Set();
 /**
@@ -134,8 +135,10 @@ function createHost(slotId, viewId, label, meta) {
     const host = document.createElement('div');
     host.className = 'slot-host';
     host.dataset.slotId = slotId;
-    if (viewId)
+    if (viewId) {
         host.setAttribute('data-sh3-view', viewId);
+        host.setAttribute('data-sh3-scope', scopeToString(`focus:${viewId}`));
+    }
     // Position:absolute inset:0 so the host fills whichever wrapper it is
     // attached to. The wrapper is what the layout engine sizes; the host
     // just tracks it. Styles are set inline (not in a class) so consumers
@@ -220,10 +223,14 @@ export function acquireSlotHost(slotId, viewId, label, meta) {
             `but existing pooled entry has viewId "${entry.viewId}". Attribute synced; ` +
             `view handle unchanged.`);
         entry.viewId = viewId;
-        if (viewId)
+        if (viewId) {
             entry.host.setAttribute('data-sh3-view', viewId);
-        else
+            entry.host.setAttribute('data-sh3-scope', scopeToString(`focus:${viewId}`));
+        }
+        else {
             entry.host.removeAttribute('data-sh3-view');
+            entry.host.removeAttribute('data-sh3-scope');
+        }
     }
     entry.refcount++;
     return entry.host;

package/dist/layout/slotHostPool.test.js

@@ -116,3 +116,18 @@ describe('slotHostPool — D.6 data-sh3-view attribute', () => {
         releaseSlotHost('slot-2');
     });
 });
+// ─── D.7 ─────────────────────────────────────────────────────────────────────
+describe('slotHostPool — D.7 data-sh3-scope attribute', () => {
+    beforeEach(resetFramework);
+    it('pooled host has data-sh3-scope="focus:<viewId>" alongside data-sh3-view', () => {
+        const host = acquireSlotHost('slot-3', 'editor', 'Editor');
+        expect(host.getAttribute('data-sh3-view')).toBe('editor');
+        expect(host.getAttribute('data-sh3-scope')).toBe('focus:editor');
+        releaseSlotHost('slot-3');
+    });
+    it('pooled host has no data-sh3-scope when viewId is null', () => {
+        const host = acquireSlotHost('slot-4', null, 'Empty');
+        expect(host.hasAttribute('data-sh3-scope')).toBe(false);
+        releaseSlotHost('slot-4');
+    });
+});

package/dist/shards/activate-error-isolation.test.d.ts

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

package/dist/shards/activate-error-isolation.test.js

@@ -0,0 +1,98 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { MemoryDocumentBackend } from '../documents/backends';
+import { __setDocumentBackend, __setTenantId } from '../documents/config';
+import { registerShard, activateShard, registeredShards, activeShards, __resetShardRegistryForTest, erroredShards, } from './activate.svelte';
+describe('erroredShards map', () => {
+    beforeEach(() => {
+        __resetShardRegistryForTest();
+        __setDocumentBackend(new MemoryDocumentBackend());
+        __setTenantId('tenant-a');
+    });
+    it('is empty after reset', () => {
+        expect(erroredShards.size).toBe(0);
+    });
+    it('supports the Map read API used by callers', () => {
+        expect(typeof erroredShards.has).toBe('function');
+        expect(typeof erroredShards.get).toBe('function');
+        expect(erroredShards.has('anything')).toBe(false);
+    });
+});
+describe('activateShard — unwind on activation failure', () => {
+    beforeEach(() => {
+        __resetShardRegistryForTest();
+        __setDocumentBackend(new MemoryDocumentBackend());
+        __setTenantId('tenant-a');
+    });
+    it('unwinds partial state and records the error when activate throws', async () => {
+        const shard = {
+            manifest: {
+                id: 'broken',
+                label: 'Broken',
+                version: '0.0.0',
+                views: [],
+            },
+            activate(ctx) {
+                ctx.registerView('broken:view', { mount: () => ({ unmount() { } }) });
+                throw new Error('dependency missing');
+            },
+        };
+        registerShard(shard);
+        await expect(activateShard('broken')).rejects.toThrow('dependency missing');
+        expect(activeShards.has('broken')).toBe(false);
+        expect(registeredShards.has('broken')).toBe(true);
+        const entry = erroredShards.get('broken');
+        expect(entry).toBeDefined();
+        expect(entry === null || entry === void 0 ? void 0 : entry.id).toBe('broken');
+        expect(entry === null || entry === void 0 ? void 0 : entry.phase).toBe('launch');
+        expect(entry === null || entry === void 0 ? void 0 : entry.error).toBeInstanceOf(Error);
+        expect(typeof (entry === null || entry === void 0 ? void 0 : entry.timestamp)).toBe('number');
+        const { getView } = await import('./registry');
+        expect(getView('broken:view')).toBeUndefined();
+    });
+    it('records phase "autostart" when called with that option', async () => {
+        var _a;
+        const shard = {
+            manifest: { id: 'broken-auto', label: 'B', version: '0.0.0', views: [] },
+            activate() {
+                throw new Error('no');
+            },
+        };
+        registerShard(shard);
+        await expect(activateShard('broken-auto', { phase: 'autostart' })).rejects.toThrow('no');
+        expect((_a = erroredShards.get('broken-auto')) === null || _a === void 0 ? void 0 : _a.phase).toBe('autostart');
+    });
+    it('clears the error entry when the shard is re-registered', async () => {
+        const broken = {
+            manifest: { id: 'reborn', label: 'R', version: '0.0.0', views: [] },
+            activate() {
+                throw new Error('first try');
+            },
+        };
+        registerShard(broken);
+        await expect(activateShard('reborn')).rejects.toThrow('first try');
+        expect(erroredShards.has('reborn')).toBe(true);
+        const fixed = {
+            manifest: { id: 'reborn', label: 'R', version: '0.0.1', views: [] },
+            activate() { },
+        };
+        registerShard(fixed);
+        expect(erroredShards.has('reborn')).toBe(false);
+    });
+    it('clears the error entry when activation eventually succeeds', async () => {
+        let shouldFail = true;
+        const shard = {
+            manifest: { id: 'flaky', label: 'F', version: '0.0.0', views: [] },
+            activate() {
+                if (shouldFail)
+                    throw new Error('first try');
+            },
+        };
+        registerShard(shard);
+        await expect(activateShard('flaky')).rejects.toThrow('first try');
+        expect(erroredShards.has('flaky')).toBe(true);
+        shouldFail = false;
+        await activateShard('flaky');
+        expect(erroredShards.has('flaky')).toBe(false);
+        expect(activeShards.has('flaky')).toBe(true);
+    });
+});

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

@@ -9,6 +9,19 @@ import type { Shard, ShardContext } from './types';
  */
 export declare const registeredShards: Map<string, Shard>;
 export declare const activeShards: Map<string, Shard>;
+/**
+ * Reactive map of shard ids that failed to activate. Populated by
+ * `activateShard`'s catch block; cleared when the shard is successfully
+ * re-registered or activated. Read-only for shards; intended for diagnostic
+ * and admin tooling that wants to surface broken shards to the user.
+ */
+export interface ShardErrorEntry {
+    id: string;
+    error: unknown;
+    phase: 'autostart' | 'launch';
+    timestamp: number;
+}
+export declare const erroredShards: Map<string, ShardErrorEntry>;
 /**
  * Register (or re-register) a shard with the framework so it can later be
  * activated. Records the shard in `registeredShards` but does not run
@@ -20,16 +33,31 @@ export declare const activeShards: Map<string, Shard>;
  * activated on next launch.
  */
 export declare function registerShard(shard: Shard): void;
+export interface ActivateShardOpts {
+    /**
+     * Where this activation was initiated from. Determines the `phase` field
+     * recorded in `erroredShards` if activation fails. Defaults to 'launch'
+     * (the common case — required by an app being launched).
+     */
+    phase?: 'autostart' | 'launch';
+}
 /**
  * Activate a registered shard. Builds a `ShardContext`, calls `shard.activate`,
  * verifies that every view declared in the manifest received a factory, then
  * calls `shard.autostart` if defined. Idempotent — calling on an already-active
  * shard is a no-op.
  *
+ * If `shard.activate` throws, partial state (registered views, verbs,
+ * contributions, document handles, actions, env subscription) is unwound
+ * and the failure is recorded in `erroredShards` before the error is
+ * re-thrown. Callers in `host.ts` (autostart loop) and `launchApp`
+ * (required-shard loop) decide how to react.
+ *
  * @param id - The `ShardManifest.id` of the shard to activate. Must be registered.
- * @throws If the shard is not registered, or if a manifest view has no factory after activation.
+ * @param opts - Optional. `phase` is recorded in `erroredShards` on failure (default 'launch').
+ * @throws If the shard is not registered, if `shard.activate` throws, or if a manifest view has no factory after activation.
  */
-export declare function activateShard(id: string): Promise<void>;
+export declare function activateShard(id: string, opts?: ActivateShardOpts): Promise<void>;
 /**
  * Deactivate an active shard. Calls `shard.deactivate`, flushes and disposes
  * all document handles, unregisters all view factories, and removes the shard