sh3-core 0.7.3 → 0.8.0

package/dist/__test__/fixtures.d.ts

@@ -0,0 +1,12 @@
+import type { App, AppManifest } from '../apps/types';
+import type { Shard, ShardManifest } from '../shards/types';
+import type { LayoutNode, LayoutTree, SplitNode, TabsNode, SlotNode, TabEntry } from '../layout/types';
+export declare function makeAppManifest(overrides?: Partial<AppManifest>): AppManifest;
+export declare function makeApp(overrides?: Partial<App>): App;
+export declare function makeShardManifest(overrides?: Partial<ShardManifest>): ShardManifest;
+export declare function makeShard(overrides?: Partial<Shard>): Shard;
+export declare function makeSlotNode(slotId?: string, viewId?: string): SlotNode;
+export declare function makeTabEntry(overrides?: Partial<TabEntry>): TabEntry;
+export declare function makeTabsNode(tabs?: TabEntry[], overrides?: Partial<TabsNode>): TabsNode;
+export declare function makeSplitNode(children: LayoutNode[], overrides?: Partial<SplitNode>): SplitNode;
+export declare function makeTree(docked: LayoutNode): LayoutTree;

package/dist/__test__/fixtures.js

@@ -0,0 +1,62 @@
+let seq = 0;
+const uid = (prefix) => `${prefix}-${++seq}`;
+export function makeAppManifest(overrides = {}) {
+    var _a, _b, _c, _d, _e;
+    return Object.assign({ id: (_a = overrides.id) !== null && _a !== void 0 ? _a : uid('app'), label: (_b = overrides.label) !== null && _b !== void 0 ? _b : 'Test App', version: (_c = overrides.version) !== null && _c !== void 0 ? _c : '1.0.0', requiredShards: (_d = overrides.requiredShards) !== null && _d !== void 0 ? _d : [], layoutVersion: (_e = overrides.layoutVersion) !== null && _e !== void 0 ? _e : 1 }, overrides);
+}
+export function makeApp(overrides = {}) {
+    var _a;
+    const manifest = makeAppManifest(overrides.manifest);
+    return {
+        manifest,
+        initialLayout: (_a = overrides.initialLayout) !== null && _a !== void 0 ? _a : [
+            { name: 'default', tree: makeTree(makeSlotNode('sh3core.home')) },
+        ],
+        activate: overrides.activate,
+        deactivate: overrides.deactivate,
+        suspend: overrides.suspend,
+        resume: overrides.resume,
+        onAppReady: overrides.onAppReady,
+    };
+}
+export function makeShardManifest(overrides = {}) {
+    var _a, _b, _c, _d;
+    return Object.assign({ id: (_a = overrides.id) !== null && _a !== void 0 ? _a : uid('shard'), label: (_b = overrides.label) !== null && _b !== void 0 ? _b : 'Test Shard', version: (_c = overrides.version) !== null && _c !== void 0 ? _c : '1.0.0', views: (_d = overrides.views) !== null && _d !== void 0 ? _d : [] }, overrides);
+}
+export function makeShard(overrides = {}) {
+    var _a;
+    return Object.assign({ manifest: makeShardManifest(overrides.manifest), activate: (_a = overrides.activate) !== null && _a !== void 0 ? _a : (() => { }), deactivate: overrides.deactivate }, overrides);
+}
+export function makeSlotNode(slotId, viewId) {
+    const id = slotId !== null && slotId !== void 0 ? slotId : uid('slot');
+    return { type: 'slot', slotId: id, viewId: viewId !== null && viewId !== void 0 ? viewId : 'test:view' };
+}
+export function makeTabEntry(overrides = {}) {
+    var _a, _b, _c;
+    const slotId = (_a = overrides.slotId) !== null && _a !== void 0 ? _a : uid('tab');
+    return {
+        slotId,
+        viewId: (_b = overrides.viewId) !== null && _b !== void 0 ? _b : 'test:view',
+        label: (_c = overrides.label) !== null && _c !== void 0 ? _c : slotId,
+        icon: overrides.icon,
+        meta: overrides.meta,
+    };
+}
+export function makeTabsNode(tabs = [makeTabEntry()], overrides = {}) {
+    var _a;
+    return Object.assign({ type: 'tabs', tabs, activeTab: (_a = overrides.activeTab) !== null && _a !== void 0 ? _a : 0, persistent: overrides.persistent, emptyRenderer: overrides.emptyRenderer }, overrides);
+}
+export function makeSplitNode(children, overrides = {}) {
+    var _a, _b;
+    return {
+        type: 'split',
+        direction: (_a = overrides.direction) !== null && _a !== void 0 ? _a : 'horizontal',
+        sizes: (_b = overrides.sizes) !== null && _b !== void 0 ? _b : children.map(() => 1 / children.length),
+        pinned: overrides.pinned,
+        collapsed: overrides.collapsed,
+        children,
+    };
+}
+export function makeTree(docked) {
+    return { docked, floats: [] };
+}

package/dist/__test__/render.d.ts

@@ -0,0 +1,3 @@
+import type { RenderResult } from '@testing-library/svelte';
+import type { Component, ComponentImport } from '@testing-library/svelte-core/types';
+export declare function renderWithShell<C extends Component>(ComponentToRender: ComponentImport<C>, props?: Record<string, unknown>): RenderResult<C>;

package/dist/__test__/render.js

@@ -0,0 +1,11 @@
+// packages/sh3-core/src/__test__/render.ts
+import { render } from '@testing-library/svelte';
+export function renderWithShell(ComponentToRender, props = {}) {
+    const host = document.createElement('div');
+    host.classList.add('sh3-shell-host');
+    host.style.position = 'relative';
+    host.style.width = '1024px';
+    host.style.height = '768px';
+    document.body.appendChild(host);
+    return render(ComponentToRender, { props, target: host });
+}

package/dist/__test__/reset.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Return the framework to a deterministic boot state for tests.
+ *
+ * Order rationale:
+ *  1. Overlays and presets unbind first — they hold references into the
+ *     layout store.
+ *  2. Drag state is cleared (also removes global pointer listeners).
+ *  3. Layout store clears appEntry and root — pool teardown can now run
+ *     safely.
+ *  4. Slot-host pool drops all hosts.
+ *  5. View/shard/app registries empty last — shards may have contributed
+ *     views.
+ */
+export declare function resetFramework(): void;

package/dist/__test__/reset.js

@@ -0,0 +1,34 @@
+// packages/sh3-core/src/__test__/reset.ts
+// Central reset orchestrator. Every new test file calls this in
+// beforeEach. Order matters — see the in-line comments.
+import { __resetFloatManagerForTest } from '../overlays/float';
+import { __resetPresetManagerForTest } from '../overlays/presets';
+import { __resetDragStateForTest } from '../layout/drag.svelte';
+import { __resetLayoutStoreForTest } from '../layout/store.svelte';
+import { resetSlotHostPool } from '../layout/slotHostPool.svelte';
+import { __resetViewRegistryForTest } from '../shards/registry';
+import { __resetShardRegistryForTest } from '../shards/activate.svelte';
+import { __resetAppRegistryForTest } from '../apps/registry.svelte';
+/**
+ * Return the framework to a deterministic boot state for tests.
+ *
+ * Order rationale:
+ *  1. Overlays and presets unbind first — they hold references into the
+ *     layout store.
+ *  2. Drag state is cleared (also removes global pointer listeners).
+ *  3. Layout store clears appEntry and root — pool teardown can now run
+ *     safely.
+ *  4. Slot-host pool drops all hosts.
+ *  5. View/shard/app registries empty last — shards may have contributed
+ *     views.
+ */
+export function resetFramework() {
+    __resetFloatManagerForTest();
+    __resetPresetManagerForTest();
+    __resetDragStateForTest();
+    __resetLayoutStoreForTest();
+    resetSlotHostPool();
+    __resetViewRegistryForTest();
+    __resetShardRegistryForTest();
+    __resetAppRegistryForTest();
+}

package/dist/__test__/setup-dom.d.ts

@@ -0,0 +1 @@
+import '@testing-library/jest-dom/vitest';

package/dist/__test__/setup-dom.js

@@ -0,0 +1,26 @@
+import '@testing-library/jest-dom/vitest';
+/**
+ * happy-dom creates per-window Comment subclasses (via WindowContextClassExtender)
+ * but actually instantiates nodes from the base CommentImplementation class. This
+ * breaks Svelte 5's `instanceof Comment` check in `first_child` (operations.js),
+ * which it uses to detect and skip Svelte anchor comment nodes in templates.
+ *
+ * When `instanceof Comment` fails, `first_child` returns the anchor comment itself
+ * instead of skipping it, causing template traversal to land on the wrong sibling
+ * nodes. This cascades into split-pane snippets receiving a `null` anchor, which
+ * triggers Svelte's `invalid_snippet_arguments` error.
+ *
+ * Fix: override `Symbol.hasInstance` on the per-window `Comment` class so it falls
+ * back to a nodeType check (8 = COMMENT_NODE) when the prototype chain check fails.
+ * This is safe because nodeType 8 is exclusively Comment nodes in the DOM spec.
+ */
+if (typeof globalThis.Comment === 'function') {
+    Object.defineProperty(globalThis.Comment, Symbol.hasInstance, {
+        value(instance) {
+            if (instance == null)
+                return false;
+            return instance.nodeType === 8;
+        },
+        configurable: true,
+    });
+}

package/dist/__test__/smoke.test.d.ts

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

package/dist/__test__/smoke.test.js

@@ -0,0 +1,28 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { resetFramework } from './reset';
+import { registeredApps, activeApp } from '../apps/registry.svelte';
+import { registeredShards, activeShards } from '../shards/activate.svelte';
+import { layoutStore } from '../layout/store.svelte';
+import { makeApp, makeShard } from './fixtures';
+import { registerApp } from '../apps/registry.svelte';
+import { registerShard } from '../shards/activate.svelte';
+describe('resetFramework', () => {
+    beforeEach(resetFramework);
+    it('returns all registries and the layout store to boot state', () => {
+        registerApp(makeApp());
+        registerShard(makeShard());
+        activeApp.id = 'dirty';
+        expect(registeredApps.size).toBeGreaterThan(0);
+        expect(registeredShards.size).toBeGreaterThan(0);
+        resetFramework();
+        expect(registeredApps.size).toBe(0);
+        expect(registeredShards.size).toBe(0);
+        expect(activeShards.size).toBe(0);
+        expect(activeApp.id).toBeNull();
+        expect(layoutStore.root).toEqual({
+            type: 'slot',
+            slotId: 'sh3core.home',
+            viewId: 'sh3core:home',
+        });
+    });
+});

package/dist/api.d.ts

@@ -3,16 +3,26 @@ export type { Shell } from './shellRuntime.svelte';
 export type { Shard, ShardManifest, SourceShard, SourceShardManifest, ShardContext, ViewDeclaration, ViewFactory, ViewHandle, MountContext, } from './shards/types';
 export type { LayoutNode, SplitNode, TabsNode, SlotNode, TabEntry, SplitDirection, SizeMode, LayoutTree, FloatEntry, LayoutPreset, CanonicalPreset, } from './layout/types';
 export type { FloatManager, FloatOptions } from './overlays/float';
+export type { ModalManager } from './overlays/modal';
+export type { PopupManager } from './overlays/popup';
+export type { ToastManager } from './overlays/toast';
 export type { PresetManager } from './overlays/presets';
+export type { OverlayHandle, ModalHandle, ModalOptions, PopupHandle, PopupOptions, PopupPlacement, ToastHandle, ToastOptions, ToastLevel, } from './overlays/types';
 export type { ZoneSchema, ZoneName, ZoneManager } from './state/types';
 export { PERMISSION_STATE_MANAGE } from './state/types';
 export type { StateZones } from './state/zones.svelte';
 export type { EnvState } from './env/types';
 export type { App, AppManifest, SourceApp, SourceAppManifest, AppContext, } from './apps/types';
 export { listRegisteredApps, getActiveApp } from './apps/registry.svelte';
-export { launchApp, returnToHome } from './apps/lifecycle';
+export { launchApp, returnToHome, unregisterApp } from './apps/lifecycle';
 export { inspectActiveLayout, spliceIntoActiveLayout, dockIntoActiveLayout, focusTab, focusView, collapseChild, expandChild, closeTab, } from './layout/inspection';
 export type { DocumentHandle, DocumentHandleOptions, DocumentFormat, DocumentMeta, DocumentChange, AutosaveController, } from './documents/types';
+export type { SyncHandle, SyncScope, ManifestEntry, ApplyEntry, ApplyOpts, ApplyOutcome, ApplyBatchResult, ConflictPolicy, ConflictResolution, ConflictContext, JournalEntry, ChangePage, GrantRecord, } from './documents/sync/types';
+export { PERMISSION_DOCUMENTS_SYNC, ScopeNotGrantedError, ScopeRevokedError, TenantMismatchError, } from './documents/sync/types';
+export { createSyncRegistry } from './documents/sync/registry';
+export type { SyncRegistry } from './documents/sync/registry';
+export { default as SyncGrantPicker } from './documents/sync/components/SyncGrantPicker.svelte';
+export { default as DocumentSyncExplorer } from './documents/sync/components/DocumentSyncExplorer.svelte';
 export { registeredShards, activeShards } from './shards/activate.svelte';
 export type { RegistryIndex, PackageEntry, PackageVersion, RequiredDependency, InstalledPackage, InstallResult, PackageMeta, } from './registry/types';
 export type { ResolvedPackage } from './registry/client';
@@ -26,7 +36,10 @@ export declare const capabilities: {
     readonly hotInstall: boolean;
 };
 export type { ServerShard, ServerShardContext } from './server-shard/types';
-export type { Verb } from './verbs/types';
+export type { Verb, VerbContext, ShellApi } from './verbs/types';
+export type { Scrollback } from './shell-shard/scrollback.svelte';
+export type { SessionClient } from './shell-shard/session-client.svelte';
 export { listVerbs } from './shards/registry';
 export { VERSION } from './version';
+export declare const FRAMEWORK_SHARD_IDS: readonly string[];
 export { setTokenOverrides, clearTokenOverrides, getTokenOverrides, } from './theme';

package/dist/api.js

@@ -26,9 +26,13 @@ export { shell } from './shellRuntime.svelte';
 export { PERMISSION_STATE_MANAGE } from './state/types';
 // Host actions callable from inside views (shell home, status bar, etc.).
 export { listRegisteredApps, getActiveApp } from './apps/registry.svelte';
-export { launchApp, returnToHome } from './apps/lifecycle';
+export { launchApp, returnToHome, unregisterApp } from './apps/lifecycle';
 // Layout inspection / mutation for advanced shards (diagnostic, etc.).
 export { inspectActiveLayout, spliceIntoActiveLayout, dockIntoActiveLayout, focusTab, focusView, collapseChild, expandChild, closeTab, } from './layout/inspection';
+export { PERMISSION_DOCUMENTS_SYNC, ScopeNotGrantedError, ScopeRevokedError, TenantMismatchError, } from './documents/sync/types';
+export { createSyncRegistry } from './documents/sync/registry';
+export { default as SyncGrantPicker } from './documents/sync/components/SyncGrantPicker.svelte';
+export { default as DocumentSyncExplorer } from './documents/sync/components/DocumentSyncExplorer.svelte';
 // Shard introspection — read-only reactive maps exposing which shards are
 // known to the host and which are currently active. Intended for diagnostic
 // and tooling shards that need to visualize framework state. Phase 9
@@ -47,5 +51,13 @@ export const capabilities = {
 export { listVerbs } from './shards/registry';
 // Package version.
 export { VERSION } from './version';
+// Framework shard IDs — shards that are always present (built-in to sh3-core).
+// Used by the store UI to skip dependency checks for these well-known shards.
+export const FRAMEWORK_SHARD_IDS = [
+    '__sh3core__',
+    'shell',
+    'sh3-store',
+    'sh3-admin',
+];
 // Theme token override API (shell-level theming support).
 export { setTokenOverrides, clearTokenOverrides, getTokenOverrides, } from './theme';

package/dist/app/store/StoreView.svelte

@@ -13,6 +13,7 @@
   import { contract } from '../../contract';
   import type { ResolvedPackage } from '../../registry/client';
   import type { InstalledPackage } from '../../registry/types';
+  import { FRAMEWORK_SHARD_IDS } from '../../api';
 
   let search = $state('');
   let typeFilter = $state<'all' | 'shard' | 'app'>('all');
@@ -75,6 +76,16 @@
     return ctx.state.ephemeral.installed.find((p: InstalledPackage) => p.id === id)?.version ?? '';
   }
 
+  function missingShards(pkg: ResolvedPackage, installed: InstalledPackage[]): string[] {
+    const required = pkg.latest.requires?.map((r) => r.id) ?? [];
+    if (required.length === 0) return [];
+    const known = new Set<string>(FRAMEWORK_SHARD_IDS);
+    for (const p of installed) {
+      if (p.type === 'shard' || p.type === 'combo') known.add(p.id);
+    }
+    return required.filter((id: string) => !known.has(id));
+  }
+
   async function handleUpdate(id: string) {
     if (updatingIds.has(id)) return;
 
@@ -118,6 +129,7 @@
         version: meta.version,
         contractVersion: meta.contractVersion,
         sourceRegistry: meta.sourceRegistry,
+        requiredShards: pkg.latest.requires?.map((r) => r.id) ?? [],
         installedAt: new Date().toISOString(),
       };
       const serverResult = await serverInstallPackage(manifest, bundle, serverBundle);
@@ -215,6 +227,7 @@
       {@const installing = installingIds.has(pkg.entry.id)}
       {@const updatable = hasUpdate(pkg.entry.id)}
       {@const updating = updatingIds.has(pkg.entry.id)}
+      {@const missing = missingShards(pkg, ctx.state.ephemeral.installed)}
       <div class="store-card">
         <div class="store-card-header">
           <div class="store-card-icon">
@@ -253,13 +266,19 @@
           {:else if installed}
             <span class="store-installed-label">Installed</span>
           {:else}
-            <button
-              class="store-install-btn"
-              onclick={() => handleInstall(pkg)}
-              disabled={installing}
-            >
-              {installing ? 'Installing...' : 'Install'}
-            </button>
+            <div class="store-install-wrap">
+              <button
+                class="store-install-btn"
+                onclick={() => handleInstall(pkg)}
+                disabled={installing || missing.length > 0}
+                title={missing.length > 0 ? `Missing required shards: ${missing.join(', ')}` : undefined}
+              >
+                {installing ? 'Installing...' : 'Install'}
+              </button>
+              {#if missing.length > 0}
+                <span class="store-card-missing">requires: {missing.join(', ')}</span>
+              {/if}
+            </div>
           {/if}
         </div>
       </div>
@@ -449,6 +468,16 @@
     color: var(--shell-success, #4caf50);
     font-weight: 600;
   }
+  .store-install-wrap {
+    display: flex;
+    flex-direction: column;
+    align-items: flex-end;
+    gap: 4px;
+  }
+  .store-card-missing {
+    font-size: 0.75rem;
+    color: var(--shell-warning, #ff9800);
+  }
   .store-update-btn {
     padding: 5px 14px;
     background: var(--shell-warning, #ff9800);

package/dist/app/store/storeShard.svelte.js

@@ -134,7 +134,7 @@ export const storeShard = {
             await ctx.envUpdate({ registries });
         }
         async function updatePackage(id) {
-            var _a, _b;
+            var _a, _b, _c, _d;
             const catalogEntry = state.ephemeral.updatable[id];
             if (!catalogEntry)
                 return;
@@ -160,10 +160,16 @@ export const storeShard = {
                 contractVersion: meta.contractVersion,
                 sourceRegistry: meta.sourceRegistry,
                 installedAt: new Date().toISOString(),
+                requiredShards: (_b = (_a = catalogEntry.latest.requires) === null || _a === void 0 ? void 0 : _a.map((r) => r.id)) !== null && _b !== void 0 ? _b : [],
             };
             const serverResult = await serverInstallPackage(manifest, bundle, serverBundle);
             if (!serverResult.ok) {
-                throw new Error((_a = serverResult.error) !== null && _a !== void 0 ? _a : 'Server update failed');
+                let message = (_c = serverResult.error) !== null && _c !== void 0 ? _c : 'Server update failed';
+                if (serverResult.code === 'missing-shards' && serverResult.missing) {
+                    const ids = serverResult.missing.map((m) => m.id).join(', ');
+                    message = `missing required shard(s): ${ids}`;
+                }
+                throw new Error(message);
             }
             // 4. Install locally (overwrites IndexedDB + re-registers).
             const result = await installPackage(bundle, meta);
@@ -177,7 +183,7 @@ export const storeShard = {
                         console.warn(`[sh3-store] Rollback failed for "${id}":`, rollbackErr instanceof Error ? rollbackErr.message : rollbackErr);
                     }
                 }
-                throw new Error((_b = result.error) !== null && _b !== void 0 ? _b : 'Local install failed during update');
+                throw new Error((_d = result.error) !== null && _d !== void 0 ? _d : 'Local install failed during update');
             }
             await refreshInstalled();
         }

package/dist/app/store/verbs.js

@@ -19,7 +19,7 @@ export const installVerb = {
     name: 'install',
     summary: 'Install a package by id from the catalog.',
     async run(ctx, args) {
-        var _a;
+        var _a, _b, _c;
         const id = args[0];
         if (!id) {
             ctx.scrollback.push({
@@ -71,12 +71,18 @@ export const installVerb = {
                 contractVersion: meta.contractVersion,
                 sourceRegistry: meta.sourceRegistry,
                 installedAt: new Date().toISOString(),
+                requiredShards: (_b = (_a = pkg.latest.requires) === null || _a === void 0 ? void 0 : _a.map((r) => r.id)) !== null && _b !== void 0 ? _b : [],
             };
             const serverResult = await serverInstallPackage(manifest, bundle, serverBundle);
             if (!serverResult.ok) {
+                let text = `install failed: ${(_c = serverResult.error) !== null && _c !== void 0 ? _c : 'server error'}`;
+                if (serverResult.code === 'missing-shards' && serverResult.missing) {
+                    const ids = serverResult.missing.map((m) => m.id).join(', ');
+                    text = `install failed: missing required shard(s): ${ids}`;
+                }
                 ctx.scrollback.push({
                     kind: 'status',
-                    text: `install failed: ${(_a = serverResult.error) !== null && _a !== void 0 ? _a : 'server error'}`,
+                    text,
                     level: 'error',
                     ts: Date.now(),
                 });

package/dist/apps/lifecycle.d.ts

@@ -25,6 +25,17 @@ export declare function launchApp(id: string): Promise<void>;
  * @param id - The `AppManifest.id` of the app to unload.
  */
 export declare function unloadApp(id: string): void;
+/**
+ * Unregister an app and remove it from the registry.
+ *
+ * If the app is currently active, force-closes (android-style): calls
+ * `App.deactivate`, detaches the layout, and deactivates required shards,
+ * then clears the active-app pointer. Unlike `returnToHome` this does not
+ * run suspend hooks and cannot be cancelled.
+ *
+ * No-op if the id is not registered.
+ */
+export declare function unregisterApp(id: string): void;
 /**
  * Return to the shell home view without unloading the active app. The
  * app's shards stay running, its layout proxy stays attached with its

package/dist/apps/lifecycle.js

@@ -13,8 +13,8 @@
  */
 import { createStateZones } from '../state/zones.svelte';
 import { activateShard, deactivateShard, getShardContext, registeredShards, } from '../shards/activate.svelte';
-import { attachApp, detachApp, switchToApp, switchToHome, } from '../layout/store.svelte';
-import { activeApp, getRegisteredApp } from './registry.svelte';
+import { attachApp, acquireAppSlotHolds, detachApp, switchToApp, switchToHome, } from '../layout/store.svelte';
+import { activeApp, getRegisteredApp, registeredApps } from './registry.svelte';
 import { createZoneManager } from '../state/manage';
 import { PERMISSION_STATE_MANAGE } from '../state/types';
 // ---------- last-active-app user zone ------------------------------------
@@ -69,7 +69,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;
+    var _a, _b, _c, _d, _e;
     const app = getRegisteredApp(id);
     if (!app) {
         throw new Error(`Cannot launch app "${id}": not registered`);
@@ -91,25 +91,42 @@ export async function launchApp(id) {
         }
         void ((_b = app.resume) === null || _b === void 0 ? void 0 : _b.call(app, getOrCreateAppContext(id)));
         switchToApp();
+        void ((_c = app.onAppReady) === null || _c === void 0 ? void 0 : _c.call(app, getOrCreateAppContext(id)));
         writeLastApp(id);
         return;
     }
-    // Activate every required shard. `activateShard` is idempotent for
-    // already-active shards (self-starting shards, or shards shared with
-    // a previous app that stayed resident) so this is safe to call
-    // unconditionally.
+    // Validate required shards are registered before attaching anything,
+    // so we don't half-attach and leave presetManager bound to a blob for
+    // an app whose shards we can't even find.
     for (const shardId of app.manifest.requiredShards) {
         if (!registeredShards.has(shardId)) {
             throw new Error(`App "${id}" requires shard "${shardId}" which is not registered`);
         }
-        await activateShard(shardId);
     }
-    // Attach the layout (creates the workspace-zone proxy with version
-    // gate) and run the app's optional activate hook.
+    // Attach the layout before activating shards so `presetManager` is
+    // bound to this app's AppLayoutBlob during shard activation. Shards
+    // legitimately read/switch presets from their activate() hook; the
+    // previous order (shards first, attach after) made any such call
+    // throw "no app attached". If shard activation fails below, we
+    // detach to keep the preset manager state consistent.
     attachApp(app);
-    void ((_c = app.activate) === null || _c === void 0 ? void 0 : _c.call(app, getOrCreateAppContext(id)));
+    try {
+        for (const shardId of app.manifest.requiredShards) {
+            await activateShard(shardId);
+        }
+    }
+    catch (err) {
+        detachApp();
+        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 ((_d = app.activate) === null || _d === void 0 ? void 0 : _d.call(app, getOrCreateAppContext(id)));
     activeApp.id = id;
     switchToApp();
+    void ((_e = app.onAppReady) === null || _e === void 0 ? void 0 : _e.call(app, getOrCreateAppContext(id)));
     writeLastApp(id);
 }
 // ---------- unload --------------------------------------------------------
@@ -152,6 +169,26 @@ export function unloadApp(id) {
     activeApp.id = null;
     appContexts.delete(id);
 }
+// ---------- unregister -------------------------------------------------------
+/**
+ * Unregister an app and remove it from the registry.
+ *
+ * If the app is currently active, force-closes (android-style): calls
+ * `App.deactivate`, detaches the layout, and deactivates required shards,
+ * then clears the active-app pointer. Unlike `returnToHome` this does not
+ * run suspend hooks and cannot be cancelled.
+ *
+ * No-op if the id is not registered.
+ */
+export function unregisterApp(id) {
+    if (!registeredApps.has(id))
+        return;
+    if (activeApp.id === id) {
+        unloadApp(id);
+        writeLastApp(null);
+    }
+    registeredApps.delete(id);
+}
 // ---------- return to home -----------------------------------------------
 /**
  * Return to the shell home view without unloading the active app. The

package/dist/apps/lifecycle.test.d.ts

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