sh3-core 0.11.8 → 0.12.0

package/dist/actions/listeners.js

@@ -13,6 +13,7 @@ import { buildContextMenuModel, buildContextMenuSubmenu } from './contextMenuMod
 import ActionPanel from './ActionPanel.svelte';
 import CommandPalette from './CommandPalette.svelte';
 import { buildPaletteCandidates } from './paletteModel';
+import { parseScopeString } from './scope-helpers';
 import { shell } from '../shellRuntime.svelte';
 let attached = false;
 function viewIdOfEl(el) {
@@ -23,10 +24,24 @@ function viewIdOfEl(el) {
     return (_a = host === null || host === void 0 ? void 0 : host.getAttribute('data-sh3-view')) !== null && _a !== void 0 ? _a : null;
 }
 function resolveAnchor(args) {
+    var _a, _b;
     if (args.explicit !== undefined)
         return args.explicit;
-    if (args.event && args.event.target) {
-        const viewId = viewIdOfEl(args.event.target);
+    const target = (_a = args.event) === null || _a === void 0 ? void 0 : _a.target;
+    if (target instanceof Element) {
+        // Preferred path: data-sh3-scope carries the literal AtomicScope encoding
+        // (see ADR-021 amendment 2026-05-01). Walked first so a sub-region
+        // overrides its enclosing slot host's auto-stamped focus:<viewId>.
+        const scopeHost = target.closest('[data-sh3-scope]');
+        if (scopeHost) {
+            const parsed = parseScopeString((_b = scopeHost.getAttribute('data-sh3-scope')) !== null && _b !== void 0 ? _b : '');
+            if (parsed)
+                return parsed;
+        }
+        // Fallback: data-sh3-view alone still maps to focus:<viewId>. Defensive
+        // for stub views and external callers that haven't adopted the new
+        // attribute; framework-stamped slot hosts now carry both.
+        const viewId = viewIdOfEl(target);
         if (viewId)
             return `focus:${viewId}`;
     }

package/dist/actions/listeners.test.js

@@ -149,6 +149,52 @@ describe('global contextmenu listener', () => {
         expect(labels).toEqual(['App']);
         target.remove();
     });
+    it('right-click inside data-sh3-scope="element:..." anchors to that element atom', async () => {
+        setActiveApp('app.a', new Set(['shard.x']));
+        setMountedViewIds(new Set(['editor']));
+        registerAction({ id: 'el-only', label: 'El', scope: { element: 'svg-designer:layer' }, contextItem: true, run: () => { } }, 'shard.x');
+        registerAction({ id: 'view-only', label: 'View', scope: 'focus:editor', contextItem: true, run: () => { } }, 'shard.x');
+        // Slot-host shape: framework auto-stamps both attributes. The inner div
+        // overrides scope only — viewId identity is unchanged. closest('[data-sh3-scope]')
+        // from the click target finds the inner div first.
+        const slotHost = document.createElement('div');
+        slotHost.setAttribute('data-sh3-view', 'editor');
+        slotHost.setAttribute('data-sh3-scope', 'focus:editor');
+        document.body.appendChild(slotHost);
+        const inner = document.createElement('div');
+        inner.setAttribute('data-sh3-scope', 'element:svg-designer:layer');
+        slotHost.appendChild(inner);
+        const target = document.createElement('button');
+        inner.appendChild(target);
+        const ev = new MouseEvent('contextmenu', { clientX: 10, clientY: 20, bubbles: true, cancelable: true });
+        Object.defineProperty(ev, 'target', { value: target });
+        target.dispatchEvent(ev);
+        await Promise.resolve();
+        const labels = [...document.querySelectorAll('.sh3-context-menu [role="menuitem"] .sh3-ctx-label')]
+            .map((n) => n.textContent);
+        expect(labels).toEqual(['El']);
+        slotHost.remove();
+    });
+    it('right-click outside any data-sh3-scope override falls back to focus:<viewId>', async () => {
+        setActiveApp('app.a', new Set(['shard.x']));
+        setMountedViewIds(new Set(['editor']));
+        registerAction({ id: 'view-only', label: 'View', scope: 'focus:editor', contextItem: true, run: () => { } }, 'shard.x');
+        registerAction({ id: 'el-only', label: 'El', scope: { element: 'cell' }, contextItem: true, run: () => { } }, 'shard.x');
+        const slotHost = document.createElement('div');
+        slotHost.setAttribute('data-sh3-view', 'editor');
+        slotHost.setAttribute('data-sh3-scope', 'focus:editor');
+        document.body.appendChild(slotHost);
+        const target = document.createElement('button');
+        slotHost.appendChild(target);
+        const ev = new MouseEvent('contextmenu', { clientX: 10, clientY: 20, bubbles: true, cancelable: true });
+        Object.defineProperty(ev, 'target', { value: target });
+        target.dispatchEvent(ev);
+        await Promise.resolve();
+        const labels = [...document.querySelectorAll('.sh3-context-menu [role="menuitem"] .sh3-ctx-label')]
+            .map((n) => n.textContent);
+        expect(labels).toEqual(['View']);
+        slotHost.remove();
+    });
     it('openContextMenu({scope}) uses the explicit anchor', async () => {
         registerAction({ id: 'cell.copy', label: 'Copy Cell', scope: { element: 'cell' }, contextItem: true, run: () => { } }, 'shard.x');
         registerAction({ id: 'home.x', label: 'Home', scope: 'home', contextItem: true, run: () => { } }, 'shard.x');

package/dist/actions/scope-helpers.d.ts

@@ -15,3 +15,20 @@ export declare function innermostActiveScope(scope: ActionScope, state: Dispatch
  * atom is never equal to an element atom.
  */
 export declare function scopeEquals(a: AtomicScope, b: AtomicScope): boolean;
+/**
+ * Canonical string encoding of an `AtomicScope` for transport over surfaces
+ * that can only carry strings — most notably `data-sh3-scope` DOM attribute
+ * values. String atoms (`home`, `app`, `view:<id>`, `focus:<id>`) pass
+ * through unchanged; element atoms encode as `element:<type>`. The element
+ * type itself may contain colons (e.g. `shard:type`) — only the leading
+ * `element:` is reserved by the encoding.
+ */
+export declare function scopeToString(scope: AtomicScope): string;
+/**
+ * Inverse of `scopeToString`. Returns `null` for inputs that do not parse to
+ * a valid `AtomicScope` so callers (e.g. the contextmenu listener reading
+ * `data-sh3-scope` from arbitrary DOM) can fall back gracefully without
+ * throwing on a malformed attribute. Empty bodies after a known prefix
+ * (`view:`, `focus:`, `element:`) also return null.
+ */
+export declare function parseScopeString(s: string): AtomicScope | null;

package/dist/actions/scope-helpers.js

@@ -59,3 +59,40 @@ export function scopeEquals(a, b) {
         return a === b;
     return a.element === b.element;
 }
+/**
+ * Canonical string encoding of an `AtomicScope` for transport over surfaces
+ * that can only carry strings — most notably `data-sh3-scope` DOM attribute
+ * values. String atoms (`home`, `app`, `view:<id>`, `focus:<id>`) pass
+ * through unchanged; element atoms encode as `element:<type>`. The element
+ * type itself may contain colons (e.g. `shard:type`) — only the leading
+ * `element:` is reserved by the encoding.
+ */
+export function scopeToString(scope) {
+    if (typeof scope === 'string')
+        return scope;
+    return `element:${scope.element}`;
+}
+/**
+ * Inverse of `scopeToString`. Returns `null` for inputs that do not parse to
+ * a valid `AtomicScope` so callers (e.g. the contextmenu listener reading
+ * `data-sh3-scope` from arbitrary DOM) can fall back gracefully without
+ * throwing on a malformed attribute. Empty bodies after a known prefix
+ * (`view:`, `focus:`, `element:`) also return null.
+ */
+export function parseScopeString(s) {
+    if (s === 'home' || s === 'app')
+        return s;
+    if (s.startsWith('view:')) {
+        const rest = s.slice('view:'.length);
+        return rest.length > 0 ? s : null;
+    }
+    if (s.startsWith('focus:')) {
+        const rest = s.slice('focus:'.length);
+        return rest.length > 0 ? s : null;
+    }
+    if (s.startsWith('element:')) {
+        const rest = s.slice('element:'.length);
+        return rest.length > 0 ? { element: rest } : null;
+    }
+    return null;
+}

package/dist/actions/scope-helpers.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { scopeToTier, normalizeScope, scopeBadge, innermostActiveScope, scopeEquals, } from './scope-helpers';
+import { scopeToTier, normalizeScope, scopeBadge, innermostActiveScope, scopeEquals, scopeToString, parseScopeString, } from './scope-helpers';
 const mkState = (o = {}) => (Object.assign({ activeAppId: null, activeAppRequiredShards: new Set(), autostartShards: new Set(), mountedViewIds: new Set(), focusedViewId: null, selection: null, bindings: {}, platform: 'other' }, o));
 describe('scopeToTier', () => {
     it('maps atoms to tier names', () => {
@@ -83,3 +83,35 @@ describe('scopeEquals', () => {
         expect(scopeEquals({ element: 'cell' }, 'home')).toBe(false);
     });
 });
+describe('scopeToString / parseScopeString', () => {
+    const cases = [
+        'home',
+        'app',
+        'view:editor',
+        'focus:pane-1',
+        { element: 'cell' },
+        // Element type containing a colon — common shape (e.g. shard:type).
+        { element: 'svg-designer:layer' },
+    ];
+    it('round-trips every AtomicScope kind', () => {
+        for (const s of cases) {
+            const parsed = parseScopeString(scopeToString(s));
+            expect(parsed).toEqual(s);
+        }
+    });
+    it('encodes element atoms with the element: prefix', () => {
+        expect(scopeToString({ element: 'cell' })).toBe('element:cell');
+        expect(scopeToString({ element: 'svg-designer:layer' })).toBe('element:svg-designer:layer');
+    });
+    it('passes string atoms through unchanged', () => {
+        expect(scopeToString('home')).toBe('home');
+        expect(scopeToString('focus:pane-1')).toBe('focus:pane-1');
+    });
+    it('returns null on unknown / malformed inputs', () => {
+        expect(parseScopeString('')).toBeNull();
+        expect(parseScopeString('bogus')).toBeNull();
+        expect(parseScopeString('element:')).toBeNull();
+        expect(parseScopeString('view:')).toBeNull();
+        expect(parseScopeString('focus:')).toBeNull();
+    });
+});

package/dist/api.d.ts

@@ -27,7 +27,8 @@ 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 } from './shards/activate.svelte';
+export { registeredShards, activeShards, erroredShards } from './shards/activate.svelte';
+export type { ShardErrorEntry } from './shards/activate.svelte';
 export type { RegistryIndex, PackageEntry, PackageVersion, RequiredDependency, InstalledPackage, InstallResult, PackageMeta, } from './registry/types';
 export type { ResolvedPackage } from './registry/client';
 export { fetchRegistries, fetchBundle, buildPackageMeta } from './registry/client';

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/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

package/dist/shards/activate.svelte.js

@@ -47,6 +47,7 @@ export const registeredShards = $state(new Map());
  */
 const active = new Map();
 export const activeShards = $state(new Map());
+export const erroredShards = $state(new Map());
 /**
  * Register (or re-register) a shard with the framework so it can later be
  * activated. Records the shard in `registeredShards` but does not run
@@ -63,6 +64,9 @@ export function registerShard(shard) {
         deactivateShard(id);
     }
     registeredShards.set(id, shard);
+    // Re-registering wipes any prior error: the new shard module gets a
+    // clean slate, and a hot-reload of a fixed shard removes the stale entry.
+    erroredShards.delete(id);
 }
 /**
  * Activate a registered shard. Builds a `ShardContext`, calls `shard.activate`,
@@ -70,11 +74,18 @@ export function registerShard(shard) {
  * 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 async function activateShard(id) {
-    var _a, _b, _c, _d, _e;
+export async function activateShard(id, opts) {
+    var _a, _b, _c, _d, _e, _f;
     const shard = registeredShards.get(id);
     if (!shard) {
         throw new Error(`Cannot activate shard "${id}": not registered`);
@@ -201,24 +212,57 @@ export async function activateShard(id) {
     }
     active.set(id, entry);
     activeShards.set(id, shard);
-    await shard.activate(ctx);
-    for (const view of shard.manifest.views) {
-        if (!entry.viewIds.has(view.id)) {
-            throw new Error(`Shard "${id}" declared view "${view.id}" in its manifest but registered no factory for it.`);
+    try {
+        await shard.activate(ctx);
+        for (const view of shard.manifest.views) {
+            if (!entry.viewIds.has(view.id)) {
+                throw new Error(`Shard "${id}" declared view "${view.id}" in its manifest but registered no factory for it.`);
+            }
         }
-    }
-    // Hydrate env state if the shard declared it via ctx.env().
-    if (envState.proxy && envState.defaults) {
-        try {
-            const stored = await fetchEnvState(id);
-            const merged = Object.assign({}, envState.defaults, stored);
-            Object.assign(envState.proxy, merged);
+        // Hydrate env state if the shard declared it via ctx.env().
+        if (envState.proxy && envState.defaults) {
+            try {
+                const stored = await fetchEnvState(id);
+                const merged = Object.assign({}, envState.defaults, stored);
+                Object.assign(envState.proxy, merged);
+            }
+            catch (err) {
+                console.warn(`[sh3] Failed to hydrate env state for shard "${id}":`, err instanceof Error ? err.message : err);
+            }
         }
-        catch (err) {
-            console.warn(`[sh3] Failed to hydrate env state for shard "${id}":`, err instanceof Error ? err.message : err);
+    }
+    catch (err) {
+        // Unwind partial state. Mirror deactivateShard's body, minus the
+        // shard.deactivate?.() call — the shard never finished activating.
+        // Each cleanup fn runs inside its own swallow so a teardown failure
+        // cannot mask the original activation error.
+        for (const fn of entry.cleanupFns) {
+            try {
+                void fn();
+            }
+            catch (_g) {
+                // intentionally swallowed: original error is what matters.
+            }
         }
+        for (const name of entry.verbNames)
+            fwUnregisterVerb(name);
+        for (const viewId of entry.viewIds)
+            unregisterView(viewId);
+        clearSelectionForShard(id);
+        active.delete(id);
+        activeShards.delete(id);
+        erroredShards.set(id, {
+            id,
+            error: err,
+            phase: (_e = opts === null || opts === void 0 ? void 0 : opts.phase) !== null && _e !== void 0 ? _e : 'launch',
+            timestamp: Date.now(),
+        });
+        console.error(`[sh3] Shard "${id}" failed to activate:`, err);
+        throw err;
     }
-    void ((_e = shard.autostart) === null || _e === void 0 ? void 0 : _e.call(shard, ctx));
+    // Activation succeeded — clear any prior error record for this shard.
+    erroredShards.delete(id);
+    void ((_f = shard.autostart) === null || _f === void 0 ? void 0 : _f.call(shard, ctx));
 }
 /**
  * Deactivate an active shard. Calls `shard.deactivate`, flushes and disposes
@@ -288,4 +332,5 @@ export function __resetShardRegistryForTest() {
     active.clear();
     activeShards.clear();
     registeredShards.clear();
+    erroredShards.clear();
 }

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Auto-generated from package.json — do not edit manually. */
-export declare const VERSION = "0.11.8";
+export declare const VERSION = "0.12.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Auto-generated from package.json — do not edit manually. */
-export const VERSION = '0.11.8';
+export const VERSION = '0.12.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sh3-core",
-  "version": "0.11.8",
+  "version": "0.12.0",
   "type": "module",
   "files": [
     "dist"