sh3-core 0.21.2 → 0.22.1

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

@@ -0,0 +1,108 @@
+import type { Shard, ShardContext } from './types';
+/**
+ * Reactive registry of every shard known to the host. Keys are shard ids.
+ * Populated by `registerShard`.
+ */
+export declare const registeredShards: Map<string, Shard>;
+/**
+ * Reactive map of shard ids that failed during the lifecycle. Populated
+ * by registerAllShards and related operations.
+ */
+export interface ShardErrorEntry {
+    id: string;
+    error: unknown;
+    phase: 'register' | 'launch' | 'satellite';
+    timestamp: number;
+}
+export declare const erroredShards: Map<string, ShardErrorEntry>;
+/** Read the app id currently bound to this shard, or null. */
+export declare function getShardBinding(shardId: string): string | null;
+/**
+ * Update which app's namespace this shard's `ctx.documents` resolves to.
+ * Pass `appId` to bind, `null` to unbind. Internal — only the lifecycle
+ * module and `apps/lifecycle.ts` call this.
+ */
+export declare function rotateShardDocumentNamespace(shardId: string, appId: string | null): void;
+export interface ShardEntry {
+    shard: Shard;
+    ctx: ShardContext;
+    viewIds: Set<string>;
+    verbNames: Set<string>;
+    /** Cleanup fns from things registered inside `register()`. Disposed only on shard re-register or framework teardown. */
+    bootCleanupFns: (() => Promise<void> | void)[];
+    /** Per-(shardId, appId) cleanup bags for things registered inside `onAppActivate`. Keyed by appId. */
+    appCleanupBags: Map<string, (() => Promise<void> | void)[]>;
+    /** Active appId during `onAppActivate` invocation, so register sites can route disposers to the right bag. */
+    activeAppId: string | null;
+}
+export declare function __setScopeResolver(resolver: (() => 'tenant' | 'project') | null): void;
+/**
+ * Build a ShardContext for the given shard. The ctx is permanent for the
+ * shard's lifetime; the same instance is passed to `register`, every
+ * `onAppActivate`/`onAppDeactivate`, and every auxiliary hook.
+ *
+ * `entry` tracks cleanup bags. When the shard is inside an `onAppActivate`
+ * call, register sites route disposers to the per-app bag (keyed by
+ * `entry.activeAppId`); otherwise they go to the boot bag.
+ */
+export declare function buildShardContext(shard: Shard, entry: ShardEntry): ShardContext;
+export declare const shardEntries: Map<string, ShardEntry>;
+export declare const activeShards: Map<string, Shard>;
+/**
+ * Run `register(ctx)` on every registered shard. Idempotent — calling on
+ * an already-entered shard is a no-op. Errors are recorded in
+ * `erroredShards` with phase 'register'; one failure does not block others.
+ */
+export declare function registerAllShards(): Promise<void>;
+export declare function runAppActivate(shardId: string, appId: string): Promise<void>;
+export declare function runAppDeactivate(shardId: string, appId: string): Promise<void>;
+/**
+ * Tear down the active entry for a shard and rebuild it from the current
+ * `registeredShards.get(id)` value. Used by `registerShard` when replacing
+ * an existing shard with a fresh module (package update, dev hot-reload).
+ *
+ * Fires `onAppDeactivate` for every bound app, calls `deactivate?.()`,
+ * flushes all cleanup bags, builds a fresh ctx, then re-runs `register()`.
+ * Caller is responsible for re-invoking `runAppActivate` for any apps
+ * currently active that require this shard.
+ */
+export declare function rebuildShardEntry(shardId: string): Promise<void>;
+/**
+ * Register (or re-register) a shard. Records the shard in `registeredShards`.
+ * If the shard is already active (in `shardEntries`), triggers a hot-swap
+ * via `rebuildShardEntry` so the new module replaces the old one cleanly.
+ */
+export declare function registerShard(shard: Shard): void;
+/** True if the shard has been registered AND its register() has run. */
+export declare function isActive(id: string): boolean;
+/** Return the ShardContext for an active shard, or undefined. */
+export declare function getShardContext(id: string): ShardContext | undefined;
+/**
+ * Enumerate every view declared as `standalone` across the currently
+ * registered/active shards.
+ */
+export declare function listStandaloneViews(): Array<{
+    shardId: string;
+    viewId: string;
+    label: string;
+}>;
+/** Test-only reset. */
+export declare function __resetLifecycleForTest(): void;
+/**
+ * Test-only reset for the full shard registry. Wipes all live entries,
+ * registered shards, and error records.
+ */
+export declare function __resetShardRegistryForTest(): void;
+/**
+ * @deprecated v2 compat shim — use `registerAllShards()` to run register
+ * for every registered shard. This shim activates a single shard by
+ * invoking its register hook directly. Retained for test fixtures during
+ * the migration; Phase 7 sweeps callers.
+ */
+export declare function activateShard(id: string): Promise<void>;
+/**
+ * @deprecated v2 compat shim — in v3, shards stay alive for the whole
+ * session. This shim performs a full teardown of the entry (for tests
+ * that explicitly want to verify cleanup paths).
+ */
+export declare function deactivateShard(id: string): void;

package/dist/shards/lifecycle.svelte.js

@@ -0,0 +1,551 @@
+/*
+ * Shard lifecycle (v3) — the only entry the framework uses to bring
+ * shards online and bind them to apps. Replaces shards/activate.svelte.ts
+ * and shards/app-binding.svelte.ts.
+ *
+ * See docs/superpowers/specs/2026-05-18-shard-contract-v3-design.md
+ * and ADR-027 for the design rationale.
+ */
+import { sh3 } from '../sh3Runtime.svelte';
+import { registerView, registerVerb as fwRegisterVerb } from './registry';
+import { createDocumentHandle, getDocumentBackend, getActiveScopeId } from '../documents';
+import { getEnvServerUrl } from '../env/index';
+import { apiFetch } from '../transport/apiFetch';
+import { isAdmin as checkIsAdmin } from '../auth/index';
+import { createZoneManager } from '../state/manage';
+import { PERMISSION_STATE_MANAGE } from '../state/types';
+import { PERMISSION_DOCUMENTS_BROWSE, PERMISSION_DOCUMENTS_READ, PERMISSION_DOCUMENTS_WRITE, } from '../documents/types';
+import { createBrowseCapability } from '../documents/browse';
+import { createDocumentPicker } from '../documents/picker-primitive';
+import { createShardKeysApi } from '../keys/client';
+import { PERMISSION_KEYS_MINT } from '../keys/types';
+import { makeSh3Api } from '../sh3Api/headless';
+import { register as contributionsRegister, list as contributionsList, listPoints as contributionsListPoints, onChange as contributionsOnChange, onAnyChange as contributionsOnAnyChange, } from '../contributions';
+import { registerAction } from '../actions/registry';
+import { makeSelectionApi } from '../actions/selection.svelte';
+import { openContextMenu as sh3OpenContextMenu, openPalette as sh3OpenPalette, } from '../actions/listeners';
+import { unregisterView, unregisterVerb as fwUnregisterVerb } from './registry';
+import { clearSelectionForShard } from '../actions/selection.svelte';
+import { fetchEnvState } from '../env/client';
+import { subscribe as subscribeKeyRevocation } from '../keys/revocation-bus.svelte';
+const shardAppBindings = $state(new Map());
+/**
+ * Reactive registry of every shard known to the host. Keys are shard ids.
+ * Populated by `registerShard`.
+ */
+export const registeredShards = $state(new Map());
+export const erroredShards = $state(new Map());
+/** Read the app id currently bound to this shard, or null. */
+export function getShardBinding(shardId) {
+    var _a;
+    return (_a = shardAppBindings.get(shardId)) !== null && _a !== void 0 ? _a : null;
+}
+/**
+ * Update which app's namespace this shard's `ctx.documents` resolves to.
+ * Pass `appId` to bind, `null` to unbind. Internal — only the lifecycle
+ * module and `apps/lifecycle.ts` call this.
+ */
+export function rotateShardDocumentNamespace(shardId, appId) {
+    if (appId === null)
+        shardAppBindings.delete(shardId);
+    else
+        shardAppBindings.set(shardId, appId);
+}
+let scopeResolver = null;
+export function __setScopeResolver(resolver) {
+    scopeResolver = resolver;
+}
+/**
+ * Build a ShardContext for the given shard. The ctx is permanent for the
+ * shard's lifetime; the same instance is passed to `register`, every
+ * `onAppActivate`/`onAppDeactivate`, and every auxiliary hook.
+ *
+ * `entry` tracks cleanup bags. When the shard is inside an `onAppActivate`
+ * call, register sites route disposers to the per-app bag (keyed by
+ * `entry.activeAppId`); otherwise they go to the boot bag.
+ */
+export function buildShardContext(shard, entry) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+    const id = shard.manifest.id;
+    function trackDisposer(fn) {
+        var _a;
+        if (entry.activeAppId !== null) {
+            const bag = (_a = entry.appCleanupBags.get(entry.activeAppId)) !== null && _a !== void 0 ? _a : [];
+            bag.push(fn);
+            entry.appCleanupBags.set(entry.activeAppId, bag);
+        }
+        else {
+            entry.bootCleanupFns.push(fn);
+        }
+    }
+    // envState must be declared at top level for Svelte 5 runes.
+    const envState = $state({
+        proxy: null,
+        defaults: null,
+    });
+    const contributions = {
+        register(pointId, descriptor, contribOpts) {
+            var _a;
+            let stored = descriptor;
+            if (pointId === 'sh3.controllable-field') {
+                const owner = { shardId: id };
+                if (((_a = contribOpts === null || contribOpts === void 0 ? void 0 : contribOpts.scope) === null || _a === void 0 ? void 0 : _a.slotId) !== undefined) {
+                    owner.slotId = contribOpts.scope.slotId;
+                }
+                stored = { owner, descriptor };
+            }
+            const dispose = contributionsRegister(pointId, stored, contribOpts);
+            trackDisposer(() => dispose());
+            return dispose;
+        },
+        list(pointId) {
+            return contributionsList(pointId);
+        },
+        listPoints() {
+            return contributionsListPoints();
+        },
+        onChange(pointId, cb) {
+            const off = contributionsOnChange(pointId, cb);
+            trackDisposer(() => off());
+            return off;
+        },
+        onAnyChange(cb) {
+            const off = contributionsOnAnyChange(cb);
+            trackDisposer(() => off());
+            return off;
+        },
+    };
+    const hasBrowse = (_a = shard.manifest.permissions) === null || _a === void 0 ? void 0 : _a.includes(PERMISSION_DOCUMENTS_BROWSE);
+    const browseCap = hasBrowse
+        ? createBrowseCapability(getActiveScopeId, getDocumentBackend(), {
+            canRead: (_c = (_b = shard.manifest.permissions) === null || _b === void 0 ? void 0 : _b.includes(PERMISSION_DOCUMENTS_READ)) !== null && _c !== void 0 ? _c : false,
+            canWrite: (_e = (_d = shard.manifest.permissions) === null || _d === void 0 ? void 0 : _d.includes(PERMISSION_DOCUMENTS_WRITE)) !== null && _e !== void 0 ? _e : false,
+        })
+        : undefined;
+    // Pre-mint exactly one document handle per shard. The handle's
+    // namespace resolves lazily on every operation via `getShardBinding`.
+    const documents = createDocumentHandle(getActiveScopeId, () => { var _a; return (_a = getShardBinding(id)) !== null && _a !== void 0 ? _a : id; }, getDocumentBackend());
+    entry.bootCleanupFns.push(() => documents.dispose());
+    // Internal expose so registerAllShards can hydrate env state after register().
+    const exposedEnv = envState;
+    const ctx = {
+        state: (schema) => sh3.state(id, schema),
+        registerView: (viewId, factory) => {
+            registerView(viewId, factory, shard.manifest.id);
+            entry.viewIds.add(viewId);
+        },
+        registerVerb: (verb) => {
+            var _a;
+            let prefixed;
+            if (id === 'shell') {
+                prefixed = verb.name;
+            }
+            else {
+                const ns = (_a = shard.manifest.verbNamespace) !== null && _a !== void 0 ? _a : id;
+                prefixed = `${ns}:${verb.name}`;
+            }
+            if (fwRegisterVerb(prefixed, Object.assign(Object.assign({}, verb), { name: prefixed }), id)) {
+                entry.verbNames.add(prefixed);
+            }
+        },
+        documents,
+        fetch(path, init) {
+            return apiFetch(this.resolveUrl(path), init);
+        },
+        get serverUrl() {
+            return getEnvServerUrl();
+        },
+        resolveUrl(path) {
+            const isAbsolute = path.startsWith('http://') || path.startsWith('https://');
+            if (isAbsolute)
+                return path;
+            const base = getEnvServerUrl();
+            const sep = path.startsWith('/') ? '' : '/';
+            return `${base}${sep}${path}`;
+        },
+        env(defaults) {
+            if (envState.proxy) {
+                console.warn(`[sh3] Shard "${id}" called ctx.env() more than once; extra calls are ignored.`);
+                return envState.proxy;
+            }
+            envState.defaults = defaults;
+            envState.proxy = Object.assign({}, defaults);
+            return envState.proxy;
+        },
+        async envUpdate(patch) {
+            if (!envState.proxy || !envState.defaults) {
+                throw new Error(`Shard "${id}" called envUpdate() without declaring env state`);
+            }
+            const { putEnvState } = await import('../env/client');
+            const previous = $state.snapshot(envState.proxy);
+            Object.assign(envState.proxy, patch);
+            try {
+                const snapshot = $state.snapshot(envState.proxy);
+                await putEnvState(id, snapshot);
+            }
+            catch (err) {
+                Object.assign(envState.proxy, previous);
+                throw err;
+            }
+        },
+        get isAdmin() {
+            return checkIsAdmin();
+        },
+        get tenantId() {
+            return getActiveScopeId();
+        },
+        getScope: () => { var _a; return (_a = scopeResolver === null || scopeResolver === void 0 ? void 0 : scopeResolver()) !== null && _a !== void 0 ? _a : 'tenant'; },
+        zones: ((_f = shard.manifest.permissions) === null || _f === void 0 ? void 0 : _f.includes(PERMISSION_STATE_MANAGE))
+            ? createZoneManager()
+            : undefined,
+        browse: browseCap,
+        documentPicker: browseCap
+            ? createDocumentPicker(() => browseCap.listDocuments())
+            : createDocumentPicker(async () => {
+                const docs = await getDocumentBackend().list(getActiveScopeId(), id);
+                return docs.map(d => (Object.assign(Object.assign({}, d), { shardId: id })));
+            }),
+        keys: ((_g = shard.manifest.permissions) === null || _g === void 0 ? void 0 : _g.includes(PERMISSION_KEYS_MINT))
+            ? createShardKeysApi({
+                shardId: id,
+                shardPermissions: (_h = shard.manifest.permissions) !== null && _h !== void 0 ? _h : [],
+            })
+            : undefined,
+        contributions,
+        actions: {
+            register(action) {
+                const dispose = registerAction(action, id);
+                trackDisposer(() => dispose());
+                return dispose;
+            },
+            selection: makeSelectionApi(id),
+            openContextMenu(opts) { sh3OpenContextMenu(opts); },
+            openPalette(opts) { sh3OpenPalette(opts); },
+        },
+        sh3: makeSh3Api({
+            callerKind: 'shard',
+            callerShardId: id,
+            zones: ((_j = shard.manifest.permissions) === null || _j === void 0 ? void 0 : _j.includes(PERMISSION_STATE_MANAGE))
+                ? createZoneManager()
+                : undefined,
+        }),
+    };
+    // Stash env state on the ctx for registerAllShards' hydration step.
+    ctx.__envState = exposedEnv;
+    return ctx;
+}
+export const shardEntries = $state(new Map());
+export const activeShards = $state(new Map());
+/**
+ * Run `register(ctx)` on every registered shard. Idempotent — calling on
+ * an already-entered shard is a no-op. Errors are recorded in
+ * `erroredShards` with phase 'register'; one failure does not block others.
+ */
+export async function registerAllShards() {
+    for (const [id, shard] of registeredShards) {
+        if (shardEntries.has(id))
+            continue;
+        const entry = {
+            shard,
+            ctx: undefined,
+            viewIds: new Set(),
+            verbNames: new Set(),
+            bootCleanupFns: [],
+            appCleanupBags: new Map(),
+            activeAppId: null,
+        };
+        const ctx = buildShardContext(shard, entry);
+        entry.ctx = ctx;
+        shardEntries.set(id, entry);
+        activeShards.set(id, shard);
+        try {
+            await shard.register(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.`);
+                }
+            }
+            // Wire onKeyRevoked subscription per shard at register time. Only
+            // shards that declare the hook incur the subscription overhead.
+            if (shard.onKeyRevoked) {
+                const off = subscribeKeyRevocation(id, async (keyId) => {
+                    try {
+                        await shard.onKeyRevoked(ctx, keyId);
+                    }
+                    catch (err) {
+                        console.error(`[sh3] onKeyRevoked failed in "${id}":`, err);
+                    }
+                });
+                entry.bootCleanupFns.push(() => off());
+            }
+            // Env hydrate parity with v2.
+            const envState = ctx.__envState;
+            if ((envState === null || envState === void 0 ? void 0 : 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);
+                }
+            }
+            erroredShards.delete(id);
+        }
+        catch (err) {
+            for (const fn of entry.bootCleanupFns) {
+                try {
+                    void fn();
+                }
+                catch ( /* swallow */_a) { /* swallow */ }
+            }
+            for (const name of entry.verbNames)
+                fwUnregisterVerb(name);
+            for (const viewId of entry.viewIds)
+                unregisterView(viewId);
+            clearSelectionForShard(id);
+            shardEntries.delete(id);
+            activeShards.delete(id);
+            erroredShards.set(id, { id, error: err, phase: 'register', timestamp: Date.now() });
+            console.error(`[sh3] Shard "${id}" failed to register:`, err);
+        }
+    }
+}
+export async function runAppActivate(shardId, appId) {
+    const entry = shardEntries.get(shardId);
+    if (!entry)
+        return;
+    rotateShardDocumentNamespace(shardId, appId);
+    if (entry.shard.onAppActivate) {
+        entry.activeAppId = appId;
+        try {
+            await entry.shard.onAppActivate(entry.ctx, appId);
+        }
+        finally {
+            entry.activeAppId = null;
+        }
+    }
+}
+export async function runAppDeactivate(shardId, appId) {
+    const entry = shardEntries.get(shardId);
+    if (!entry)
+        return;
+    if (entry.shard.onAppDeactivate) {
+        try {
+            await entry.shard.onAppDeactivate(entry.ctx, appId);
+        }
+        catch (err) {
+            console.error(`[sh3] onAppDeactivate for "${shardId}" / "${appId}" threw:`, err);
+        }
+    }
+    const bag = entry.appCleanupBags.get(appId);
+    if (bag) {
+        for (const fn of bag) {
+            try {
+                await fn();
+            }
+            catch (err) {
+                console.error(`[sh3] app-cleanup disposer threw:`, err);
+            }
+        }
+        entry.appCleanupBags.delete(appId);
+    }
+    rotateShardDocumentNamespace(shardId, null);
+}
+/**
+ * Tear down the active entry for a shard and rebuild it from the current
+ * `registeredShards.get(id)` value. Used by `registerShard` when replacing
+ * an existing shard with a fresh module (package update, dev hot-reload).
+ *
+ * Fires `onAppDeactivate` for every bound app, calls `deactivate?.()`,
+ * flushes all cleanup bags, builds a fresh ctx, then re-runs `register()`.
+ * Caller is responsible for re-invoking `runAppActivate` for any apps
+ * currently active that require this shard.
+ */
+export async function rebuildShardEntry(shardId) {
+    var _a, _b;
+    const old = shardEntries.get(shardId);
+    if (old) {
+        for (const appId of old.appCleanupBags.keys()) {
+            await runAppDeactivate(shardId, appId);
+        }
+        try {
+            await ((_b = (_a = old.shard).deactivate) === null || _b === void 0 ? void 0 : _b.call(_a));
+        }
+        catch (err) {
+            console.error(err);
+        }
+        for (const fn of old.bootCleanupFns) {
+            try {
+                await fn();
+            }
+            catch ( /* swallow */_c) { /* swallow */ }
+        }
+        for (const name of old.verbNames)
+            fwUnregisterVerb(name);
+        for (const viewId of old.viewIds)
+            unregisterView(viewId);
+        clearSelectionForShard(shardId);
+        shardEntries.delete(shardId);
+        activeShards.delete(shardId);
+    }
+    const fresh = registeredShards.get(shardId);
+    if (!fresh)
+        return;
+    const entry = {
+        shard: fresh,
+        ctx: undefined,
+        viewIds: new Set(),
+        verbNames: new Set(),
+        bootCleanupFns: [],
+        appCleanupBags: new Map(),
+        activeAppId: null,
+    };
+    entry.ctx = buildShardContext(fresh, entry);
+    shardEntries.set(shardId, entry);
+    activeShards.set(shardId, fresh);
+    await fresh.register(entry.ctx);
+}
+/**
+ * Register (or re-register) a shard. Records the shard in `registeredShards`.
+ * If the shard is already active (in `shardEntries`), triggers a hot-swap
+ * via `rebuildShardEntry` so the new module replaces the old one cleanly.
+ */
+export function registerShard(shard) {
+    const id = shard.manifest.id;
+    const wasActive = shardEntries.has(id);
+    registeredShards.set(id, shard);
+    erroredShards.delete(id);
+    if (wasActive) {
+        void rebuildShardEntry(id);
+    }
+}
+/** True if the shard has been registered AND its register() has run. */
+export function isActive(id) {
+    return shardEntries.has(id);
+}
+/** Return the ShardContext for an active shard, or undefined. */
+export function getShardContext(id) {
+    var _a;
+    return (_a = shardEntries.get(id)) === null || _a === void 0 ? void 0 : _a.ctx;
+}
+/**
+ * Enumerate every view declared as `standalone` across the currently
+ * registered/active shards.
+ */
+export function listStandaloneViews() {
+    const out = [];
+    for (const shard of activeShards.values()) {
+        for (const view of shard.manifest.views) {
+            if (view.standalone) {
+                out.push({ shardId: shard.manifest.id, viewId: view.id, label: view.label });
+            }
+        }
+    }
+    return out;
+}
+/** Test-only reset. */
+export function __resetLifecycleForTest() {
+    shardAppBindings.clear();
+    shardEntries.clear();
+    activeShards.clear();
+}
+/**
+ * Test-only reset for the full shard registry. Wipes all live entries,
+ * registered shards, and error records.
+ */
+export function __resetShardRegistryForTest() {
+    shardAppBindings.clear();
+    shardEntries.clear();
+    activeShards.clear();
+    registeredShards.clear();
+    erroredShards.clear();
+}
+/**
+ * @deprecated v2 compat shim — use `registerAllShards()` to run register
+ * for every registered shard. This shim activates a single shard by
+ * invoking its register hook directly. Retained for test fixtures during
+ * the migration; Phase 7 sweeps callers.
+ */
+export async function activateShard(id) {
+    if (shardEntries.has(id))
+        return;
+    const shard = registeredShards.get(id);
+    if (!shard)
+        throw new Error(`Cannot activate shard "${id}": not registered`);
+    const entry = {
+        shard,
+        ctx: undefined,
+        viewIds: new Set(),
+        verbNames: new Set(),
+        bootCleanupFns: [],
+        appCleanupBags: new Map(),
+        activeAppId: null,
+    };
+    const ctx = buildShardContext(shard, entry);
+    entry.ctx = ctx;
+    shardEntries.set(id, entry);
+    activeShards.set(id, shard);
+    try {
+        await shard.register(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.`);
+            }
+        }
+        if (shard.onKeyRevoked) {
+            const off = subscribeKeyRevocation(id, async (keyId) => {
+                try {
+                    await shard.onKeyRevoked(ctx, keyId);
+                }
+                catch (err) {
+                    console.error(`[sh3] onKeyRevoked failed in "${id}":`, err);
+                }
+            });
+            entry.bootCleanupFns.push(() => off());
+        }
+        erroredShards.delete(id);
+    }
+    catch (err) {
+        for (const fn of entry.bootCleanupFns) {
+            try {
+                void fn();
+            }
+            catch ( /* swallow */_a) { /* swallow */ }
+        }
+        for (const name of entry.verbNames)
+            fwUnregisterVerb(name);
+        for (const viewId of entry.viewIds)
+            unregisterView(viewId);
+        clearSelectionForShard(id);
+        shardEntries.delete(id);
+        activeShards.delete(id);
+        erroredShards.set(id, { id, error: err, phase: 'register', timestamp: Date.now() });
+        throw err;
+    }
+}
+/**
+ * @deprecated v2 compat shim — in v3, shards stay alive for the whole
+ * session. This shim performs a full teardown of the entry (for tests
+ * that explicitly want to verify cleanup paths).
+ */
+export function deactivateShard(id) {
+    var _a, _b;
+    const entry = shardEntries.get(id);
+    if (!entry)
+        return;
+    void ((_b = (_a = entry.shard).deactivate) === null || _b === void 0 ? void 0 : _b.call(_a));
+    for (const fn of entry.bootCleanupFns) {
+        try {
+            void fn();
+        }
+        catch ( /* swallow */_c) { /* swallow */ }
+    }
+    for (const name of entry.verbNames)
+        fwUnregisterVerb(name);
+    for (const viewId of entry.viewIds)
+        unregisterView(viewId);
+    clearSelectionForShard(id);
+    shardEntries.delete(id);
+    activeShards.delete(id);
+}