sh3-core 0.15.2 → 0.15.3

package/dist/api.d.ts

@@ -18,6 +18,9 @@ export { listRegisteredApps, getActiveApp } from './apps/registry.svelte';
 export { launchApp, returnToHome, unregisterApp } from './apps/lifecycle';
 export { pushNavEntry } from './navigation';
 export type { NavEntry, NavEntryHandle } from './navigation';
+export { spawnSatellite } from './shellApi/window';
+export type { SpawnSatelliteOptions } from './shellApi/window';
+export type { SatellitePayload } from './boot/satellitePayload';
 export { inspectActiveLayout, spliceIntoActiveLayout, dockIntoActiveLayout, focusTab, focusView, collapseChild, expandChild, closeTab, popoutView, dockFloat, locateSlot, } from './layout/inspection';
 export type { DocumentHandle, DocumentHandleOptions, DocumentFormat, DocumentMeta, DocumentChange, AutosaveController, } from './documents/types';
 export { PERMISSION_DOCUMENTS_BROWSE, PERMISSION_DOCUMENTS_READ, PERMISSION_DOCUMENTS_WRITE, } from './documents/types';
@@ -46,7 +49,7 @@ export declare const capabilities: {
     readonly hotInstall: boolean;
 };
 export type { ServerShard, ServerShardContext, TenantDocumentAPI } from './server-shard/types';
-export type { Verb, VerbContext, ShellApi, VerbSchema, PortableJSONSchema, } from './verbs/types';
+export type { Verb, VerbContext, ShellApi, VerbSchema, PortableJSONSchema, DispatchToTerminalResult, } 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';

package/dist/api.js

@@ -29,6 +29,8 @@ export { listRegisteredApps, getActiveApp } from './apps/registry.svelte';
 export { launchApp, returnToHome, unregisterApp } from './apps/lifecycle';
 // Navigation — apps push in-app nav entries; framework drives back/forward.
 export { pushNavEntry } from './navigation';
+// Multi-window — spawn a satellite native window from the host shell.
+export { spawnSatellite } from './shellApi/window';
 // Layout inspection / mutation for advanced shards (diagnostic, etc.).
 export { inspectActiveLayout, spliceIntoActiveLayout, dockIntoActiveLayout, focusTab, focusView, collapseChild, expandChild, closeTab, popoutView, dockFloat, locateSlot, } from './layout/inspection';
 export { PERMISSION_DOCUMENTS_BROWSE, PERMISSION_DOCUMENTS_READ, PERMISSION_DOCUMENTS_WRITE, } from './documents/types';

package/dist/apps/lifecycle.d.ts

@@ -11,6 +11,21 @@ export declare function readLastApp(): string | null;
  * instead of looping into the same failure.
  */
 export declare function clearLastApp(): void;
+/**
+ * Options for `launchApp`. Both flags are primarily intended for satellite
+ * mode (Task 8) where the satellite window manages its own persistence and
+ * starts from an empty layout rather than a home view.
+ */
+export interface LaunchAppOptions {
+    /** When true, do not persist this launch as the lastApp slot. */
+    skipLastApp?: boolean;
+    /**
+     * When true, do not call switchToHome() before attaching the new app.
+     * Use this when the satellite's layout is already empty and there is no
+     * "home" view to return to first.
+     */
+    skipSwitchToHome?: boolean;
+}
 /**
  * Launch an app by id. Activates all required shards (idempotent for
  * already-active shards), attaches the app's layout, calls `App.activate`,
@@ -21,17 +36,21 @@ export declare function clearLastApp(): void;
  * back from the home view if needed.
  *
  * @param id - The `AppManifest.id` of the app to launch. Must be registered.
+ * @param opts - Optional launch flags (see {@link LaunchAppOptions}).
  * @throws If the app is not registered or a required shard is not registered.
  */
-export declare function launchApp(id: string): Promise<void>;
+export declare function launchApp(id: string, opts?: LaunchAppOptions): Promise<void>;
 /**
  * Unload an active app. Calls `App.deactivate`, detaches the layout, and
  * deactivates the app's non-self-starting required shards. Switches the
  * rendered root to home. No-op if the app is not currently active.
  *
  * @param id - The `AppManifest.id` of the app to unload.
+ * @param skipSwitchToHome - When true, skip the switchToHome() call. Used by
+ *   launchApp when the caller has opted out of the home transition (e.g.
+ *   satellite mode).
  */
-export declare function unloadApp(id: string): void;
+export declare function unloadApp(id: string, skipSwitchToHome?: boolean): void;
 /**
  * Unregister an app and remove it from the registry.
  *

package/dist/apps/lifecycle.js

@@ -77,7 +77,6 @@ function getOrCreateAppContext(appId, scopeId) {
     }
     return ctx;
 }
-// ---------- launch --------------------------------------------------------
 /**
  * Launch an app by id. Activates all required shards (idempotent for
  * already-active shards), attaches the app's layout, calls `App.activate`,
@@ -88,9 +87,10 @@ function getOrCreateAppContext(appId, scopeId) {
  * back from the home view if needed.
  *
  * @param id - The `AppManifest.id` of the app to launch. Must be registered.
+ * @param opts - Optional launch flags (see {@link LaunchAppOptions}).
  * @throws If the app is not registered or a required shard is not registered.
  */
-export async function launchApp(id) {
+export async function launchApp(id, opts = {}) {
     var _a, _b, _c, _d, _e, _f, _g, _h;
     const app = getRegisteredApp(id);
     if (!app) {
@@ -101,7 +101,7 @@ export async function launchApp(id) {
     // we only swap the rendered root back to 'app' in case the user was
     // on home.
     if (activeApp.id && activeApp.id !== id) {
-        unloadApp(activeApp.id);
+        unloadApp(activeApp.id, opts.skipSwitchToHome);
     }
     else if (activeApp.id === id) {
         // Re-entering the same app from Home — fire resume hooks.
@@ -114,7 +114,8 @@ 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);
+        if (!opts.skipLastApp)
+            writeLastApp(id);
         breadcrumbApp.id = id;
         setActiveApp(id, new Set((_d = app.manifest.requiredShards) !== null && _d !== void 0 ? _d : []));
         void loadUserBindings(id).then(setUserBindings);
@@ -161,7 +162,8 @@ export async function launchApp(id) {
     void loadUserBindings(id).then(setUserBindings);
     switchToApp();
     void ((_h = app.onAppReady) === null || _h === void 0 ? void 0 : _h.call(app, getOrCreateAppContext(id)));
-    writeLastApp(id);
+    if (!opts.skipLastApp)
+        writeLastApp(id);
     breadcrumbApp.id = id;
 }
 // ---------- unload --------------------------------------------------------
@@ -171,8 +173,11 @@ export async function launchApp(id) {
  * rendered root to home. No-op if the app is not currently active.
  *
  * @param id - The `AppManifest.id` of the app to unload.
+ * @param skipSwitchToHome - When true, skip the switchToHome() call. Used by
+ *   launchApp when the caller has opted out of the home transition (e.g.
+ *   satellite mode).
  */
-export function unloadApp(id) {
+export function unloadApp(id, skipSwitchToHome = false) {
     var _a;
     if (activeApp.id !== id)
         return;
@@ -184,7 +189,8 @@ export function unloadApp(id) {
     // the next microtask for any slots that no longer have a renderer).
     // Switch to home first so LayoutRenderer stops reading the app's
     // tree before detachApp drops its references.
-    switchToHome();
+    if (!skipSwitchToHome)
+        switchToHome();
     detachApp();
     // Deactivate this app's required shards IF no other consumer needs
     // them. Phase 8 has at most one app active at a time, so "no other

package/dist/apps/lifecycle.test.js

@@ -612,3 +612,21 @@ describe('lifecycle — clears nav entries', () => {
         expect(onPop).not.toHaveBeenCalled();
     });
 });
+// ---------------------------------------------------------------------------
+// Scenario D.1 — launchApp opts.skipLastApp suppresses lastApp persistence
+// ---------------------------------------------------------------------------
+describe('launchApp — scenario D.1 skipLastApp option', () => {
+    beforeEach(resetFramework);
+    it('does NOT persist lastApp when skipLastApp: true', async () => {
+        const { readLastApp } = await import('./lifecycle');
+        registerApp(makeApp({ manifest: makeAppManifest({ id: 'app-skip-last' }) }));
+        await launchApp('app-skip-last', { skipLastApp: true });
+        expect(readLastApp()).toBeNull();
+    });
+    it('DOES persist lastApp by default (regression guard)', async () => {
+        const { readLastApp } = await import('./lifecycle');
+        registerApp(makeApp({ manifest: makeAppManifest({ id: 'app-default-last' }) }));
+        await launchApp('app-default-last');
+        expect(readLastApp()).toBe('app-default-last');
+    });
+});

package/dist/boot/satelliteMode.d.ts

@@ -0,0 +1,7 @@
+import { type SatellitePayload } from './satellitePayload';
+export type SatelliteDetection = null | {
+    payload: SatellitePayload;
+} | {
+    error: string;
+};
+export declare function detectSatelliteMode(): SatelliteDetection;

package/dist/boot/satelliteMode.js

@@ -0,0 +1,22 @@
+/*
+ * Satellite mode detection — runs once during createShell() before zone
+ * initialization. Reads location.search; returns null for main mode,
+ * { payload } for valid satellite, { error } for malformed.
+ */
+import { decodePayload } from './satellitePayload';
+export function detectSatelliteMode() {
+    if (typeof window === 'undefined')
+        return null;
+    const params = new URLSearchParams(window.location.search);
+    if (params.get('mode') !== 'satellite')
+        return null;
+    const payload = params.get('payload');
+    if (!payload)
+        return { error: 'Satellite mode requires payload param' };
+    try {
+        return { payload: decodePayload(payload) };
+    }
+    catch (err) {
+        return { error: err.message };
+    }
+}

package/dist/boot/satelliteMode.test.d.ts

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

package/dist/boot/satelliteMode.test.js

@@ -0,0 +1,55 @@
+import { describe, it, expect } from 'vitest';
+import { detectSatelliteMode } from './satelliteMode';
+import { encodePayload } from './satellitePayload';
+function withSearch(search, fn) {
+    const original = window.location.search;
+    Object.defineProperty(window.location, 'search', {
+        value: search,
+        configurable: true,
+    });
+    try {
+        fn();
+    }
+    finally {
+        Object.defineProperty(window.location, 'search', {
+            value: original,
+            configurable: true,
+        });
+    }
+}
+describe('detectSatelliteMode', () => {
+    it('returns null for empty search', () => {
+        withSearch('', () => {
+            expect(detectSatelliteMode()).toBeNull();
+        });
+    });
+    it('returns null when mode is not satellite', () => {
+        withSearch('?mode=other', () => {
+            expect(detectSatelliteMode()).toBeNull();
+        });
+    });
+    it('returns null when satellite mode without payload', () => {
+        withSearch('?mode=satellite', () => {
+            expect(detectSatelliteMode()).toEqual({
+                error: 'Satellite mode requires payload param',
+            });
+        });
+    });
+    it('returns the decoded payload on a well-formed URL', () => {
+        const payload = {
+            kind: 'app',
+            appId: 'sh3-store',
+            activateShards: [],
+        };
+        withSearch(`?mode=satellite&payload=${encodePayload(payload)}`, () => {
+            const result = detectSatelliteMode();
+            expect(result).toEqual({ payload });
+        });
+    });
+    it('returns an error object on malformed payload', () => {
+        withSearch('?mode=satellite&payload=!!!notbase64!!!', () => {
+            const result = detectSatelliteMode();
+            expect(result).toMatchObject({ error: expect.stringContaining('Invalid') });
+        });
+    });
+});

package/dist/boot/satellitePayload.d.ts

@@ -0,0 +1,17 @@
+import type { LayoutNode } from '../layout/types';
+export type SatellitePayload = {
+    kind: 'float';
+    content: LayoutNode;
+    title?: string;
+    size: {
+        w: number;
+        h: number;
+    };
+    activateShards: string[];
+} | {
+    kind: 'app';
+    appId: string;
+    activateShards: string[];
+};
+export declare function encodePayload(payload: SatellitePayload): string;
+export declare function decodePayload(encoded: string): SatellitePayload;

package/dist/boot/satellitePayload.js

@@ -0,0 +1,60 @@
+/*
+ * Satellite payload — what a host shell tells a freshly-spawned satellite
+ * window to render. Encoded as URL-safe base64 JSON in the `payload` query
+ * param of the satellite's URL.
+ */
+export function encodePayload(payload) {
+    // URL-safe base64: replace +/= with -_  and strip padding so the result
+    // can be embedded in a query string without further percent-encoding.
+    // Plain btoa() output uses + which URLSearchParams decodes as space.
+    return btoa(JSON.stringify(payload))
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=+$/, '');
+}
+export function decodePayload(encoded) {
+    let json;
+    try {
+        const restored = encoded.replace(/-/g, '+').replace(/_/g, '/');
+        json = atob(restored);
+    }
+    catch (err) {
+        throw new Error(`Invalid satellite payload encoding: ${err.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch (err) {
+        throw new Error(`Invalid satellite payload JSON: ${err.message}`);
+    }
+    return validate(parsed);
+}
+function validate(value) {
+    if (!value || typeof value !== 'object') {
+        throw new Error('Satellite payload must be an object');
+    }
+    const v = value;
+    if (v.kind === 'float') {
+        if (!v.content || typeof v.content !== 'object') {
+            throw new Error('Float payload missing content');
+        }
+        if (!v.size || typeof v.size !== 'object') {
+            throw new Error('Float payload missing size');
+        }
+        if (!Array.isArray(v.activateShards)) {
+            throw new Error('Float payload missing activateShards');
+        }
+        return v;
+    }
+    if (v.kind === 'app') {
+        if (typeof v.appId !== 'string') {
+            throw new Error('App payload missing appId');
+        }
+        if (!Array.isArray(v.activateShards)) {
+            throw new Error('App payload missing activateShards');
+        }
+        return v;
+    }
+    throw new Error(`Unknown satellite payload kind: ${String(v.kind)}`);
+}

package/dist/boot/satellitePayload.test.d.ts

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

package/dist/boot/satellitePayload.test.js

@@ -0,0 +1,53 @@
+import { describe, it, expect } from 'vitest';
+import { encodePayload, decodePayload, } from './satellitePayload';
+describe('satellite payload encode/decode', () => {
+    it('round-trips a float payload', () => {
+        const payload = {
+            kind: 'float',
+            content: { type: 'slot', slotId: 's:1', viewId: 'foo:bar' },
+            title: 'Hello',
+            size: { w: 800, h: 600 },
+            activateShards: ['foo'],
+        };
+        const enc = encodePayload(payload);
+        expect(typeof enc).toBe('string');
+        expect(decodePayload(enc)).toEqual(payload);
+    });
+    it('round-trips an app payload', () => {
+        const payload = {
+            kind: 'app',
+            appId: 'sh3-store',
+            activateShards: ['sh3-core', 'sh3-store'],
+        };
+        expect(decodePayload(encodePayload(payload))).toEqual(payload);
+    });
+    it('throws on garbage input', () => {
+        expect(() => decodePayload('!!!not-base64!!!')).toThrow();
+    });
+    it('throws on a base64 string that is not valid JSON', () => {
+        const notJson = btoa('hello world');
+        expect(() => decodePayload(notJson)).toThrow();
+    });
+    it('throws when decoded JSON is missing required fields', () => {
+        const bad = btoa(JSON.stringify({ kind: 'float' }));
+        expect(() => decodePayload(bad)).toThrow();
+    });
+    it('throws on unknown kind', () => {
+        const bad = btoa(JSON.stringify({ kind: 'mystery' }));
+        expect(() => decodePayload(bad)).toThrow();
+    });
+    it('produces a URL-safe encoding (no + / =)', () => {
+        // A long-ish payload increases the chance the underlying base64
+        // would contain non-URL-safe characters from the standard alphabet.
+        const payload = {
+            kind: 'float',
+            content: { type: 'slot', slotId: 's:111', viewId: 'foo:bar' },
+            title: '????>>>~~~`',
+            size: { w: 1234, h: 567 },
+            activateShards: ['some.long.shard.id', 'another-shard', 'third_shard'],
+        };
+        const encoded = encodePayload(payload);
+        expect(encoded).not.toMatch(/[+/=]/);
+        expect(decodePayload(encoded)).toEqual(payload);
+    });
+});

package/dist/createShell.js

@@ -8,7 +8,7 @@
  */
 import { mount, unmount } from 'svelte';
 import { Shell } from './index';
-import { registerShard, registerApp, bootstrap, __setBackend, setLocalOwner, } from './host';
+import { registerShard, registerApp, bootstrap, bootstrapSatellite, __setBackend, setLocalOwner, } from './host';
 import { resolvePlatform } from './platform/index';
 import { hydrateTokenOverrides } from './theme';
 import { __setEnvServerUrl } from './env/index';
@@ -18,8 +18,11 @@ import SignInWall from './auth/SignInWall.svelte';
 import { loadBundleModule } from './registry/loader';
 import { registerLoadedBundle } from './registry/register';
 import { attachGlobalListeners } from './actions/listeners';
+import { detectSatelliteMode } from './boot/satelliteMode';
+import { MemoryBackend } from './state/backends';
+import SatelliteShell from './satellite/SatelliteShell.svelte';
 export async function createShell(config) {
-    var _a, _b, _c, _d, _e;
+    var _a, _b;
     const sUrl = (_a = config === null || config === void 0 ? void 0 : config.serverUrl) !== null && _a !== void 0 ? _a : '';
     // 1. Platform detection
     const platform = await resolvePlatform();
@@ -39,6 +42,41 @@ export async function createShell(config) {
     if (!target) {
         throw new Error('SH3: mount target not found');
     }
+    // 2b. Satellite-mode short-circuit. A Tauri webview opened by the host's
+    // sh3_spawn_satellite command lands here via ?mode=satellite&payload=...
+    // and skips auth, boot config, framework autostart, and lastApp launch.
+    // The host's workspace zone is forced to MemoryBackend so the satellite's
+    // layout/floats are isolated; user and document zones stay shared so
+    // theme prefs and document data follow the user across windows.
+    const satellite = detectSatelliteMode();
+    if (satellite) {
+        if ('error' in satellite) {
+            target.textContent = `Invalid satellite payload: ${satellite.error}`;
+            return;
+        }
+        __setBackend('workspace', new MemoryBackend());
+        // Document zone needs a scope; in localOwner (Tauri/dev) it's 'local'
+        // matching the host. Web satellites would need a tenant from /api/boot,
+        // but pop-out is currently a Tauri-only POC so we don't fetch it.
+        if (platform.localOwner)
+            __setActiveScope('local');
+        if (config === null || config === void 0 ? void 0 : config.shards)
+            for (const shard of config.shards)
+                registerShard(shard);
+        if (config === null || config === void 0 ? void 0 : config.apps)
+            for (const app of config.apps)
+                registerApp(app);
+        // Server-discovered packages must be loaded here too — apps installed
+        // via /api/packages aren't in IndexedDB on the satellite's view of the
+        // world unless we fetch and register them, same as the main path.
+        await loadDiscoveredPackages(config === null || config === void 0 ? void 0 : config.discoveredPackages);
+        await bootstrapSatellite({
+            activateShardIds: satellite.payload.activateShards,
+        });
+        attachGlobalListeners();
+        mount(SatelliteShell, { target, props: { payload: satellite.payload } });
+        return;
+    }
     // 3. Fetch boot config (skip for local-owner platforms like Tauri/dev)
     let bootConfig = null;
     if (!platform.localOwner) {
@@ -48,7 +86,7 @@ export async function createShell(config) {
                 bootConfig = await res.json();
             }
         }
-        catch (_f) {
+        catch (_c) {
             // Server unreachable — boot without auth (offline mode)
         }
     }
@@ -75,28 +113,7 @@ export async function createShell(config) {
         }
     }
     // 5. Load server-discovered packages
-    if ((_c = config === null || config === void 0 ? void 0 : config.discoveredPackages) === null || _c === void 0 ? void 0 : _c.length) {
-        for (const pkg of config.discoveredPackages) {
-            try {
-                const res = await fetch(pkg.bundleUrl);
-                if (!res.ok) {
-                    console.warn(`[sh3] Failed to fetch discovered package "${pkg.id}": HTTP ${res.status}`);
-                    continue;
-                }
-                const bytes = await res.arrayBuffer();
-                const loaded = await loadBundleModule(bytes);
-                registerLoadedBundle(loaded, {
-                    version: pkg.version,
-                    sourceRegistry: (_d = pkg.sourceRegistry) !== null && _d !== void 0 ? _d : '',
-                    contractVersion: (_e = pkg.contractVersion) !== null && _e !== void 0 ? _e : '',
-                });
-                console.log(`[sh3] Loaded discovered package: ${pkg.id}`);
-            }
-            catch (err) {
-                console.warn(`[sh3] Failed to load discovered package "${pkg.id}":`, err);
-            }
-        }
-    }
+    await loadDiscoveredPackages(config === null || config === void 0 ? void 0 : config.discoveredPackages);
     // 6. Register consumer-provided shards and apps
     if (config === null || config === void 0 ? void 0 : config.shards) {
         for (const shard of config.shards)
@@ -116,6 +133,36 @@ export async function createShell(config) {
     // 9. Mount the shell
     mount(Shell, { target });
 }
+/**
+ * Fetch and register every package the server reported via /api/packages.
+ * Shared by main-mode boot and the satellite-mode short-circuit so popped-out
+ * windows see the same installed apps as the host.
+ */
+async function loadDiscoveredPackages(packages) {
+    var _a, _b;
+    if (!(packages === null || packages === void 0 ? void 0 : packages.length))
+        return;
+    for (const pkg of packages) {
+        try {
+            const res = await fetch(pkg.bundleUrl);
+            if (!res.ok) {
+                console.warn(`[sh3] Failed to fetch discovered package "${pkg.id}": HTTP ${res.status}`);
+                continue;
+            }
+            const bytes = await res.arrayBuffer();
+            const loaded = await loadBundleModule(bytes);
+            registerLoadedBundle(loaded, {
+                version: pkg.version,
+                sourceRegistry: (_a = pkg.sourceRegistry) !== null && _a !== void 0 ? _a : '',
+                contractVersion: (_b = pkg.contractVersion) !== null && _b !== void 0 ? _b : '',
+            });
+            console.log(`[sh3] Loaded discovered package: ${pkg.id}`);
+        }
+        catch (err) {
+            console.warn(`[sh3] Failed to load discovered package "${pkg.id}":`, err);
+        }
+    }
+}
 /**
  * Show the sign-in wall and wait until the user authenticates.
  * Returns a promise that resolves after successful login.

package/dist/host.d.ts

@@ -12,4 +12,17 @@ export interface BootstrapConfig {
     excludeShards?: string[];
 }
 export declare function bootstrap(config?: BootstrapConfig): Promise<void>;
+export interface BootstrapSatelliteConfig {
+    /** Shard ids the satellite needs activated to render its payload. */
+    activateShardIds: string[];
+}
+/**
+ * Boot the satellite path: register the same framework shards and apps as
+ * the host, load installed packages, then activate exactly the shards the
+ * caller requested. Skips the host-only steps:
+ *   - workspace zone migrations (host already ran them; we use MemoryBackend anyway)
+ *   - autostart sweep (we activate exactly what the payload requires)
+ *   - lastApp auto-launch (satellites have no last-app concept)
+ */
+export declare function bootstrapSatellite(config: BootstrapSatelliteConfig): Promise<void>;
 export { installPackage, listInstalledPackages } from './registry/installer';

package/dist/host.js

@@ -122,4 +122,40 @@ export async function bootstrap(config) {
         installWebEmitter();
     }
 }
+/**
+ * Boot the satellite path: register the same framework shards and apps as
+ * the host, load installed packages, then activate exactly the shards the
+ * caller requested. Skips the host-only steps:
+ *   - workspace zone migrations (host already ran them; we use MemoryBackend anyway)
+ *   - autostart sweep (we activate exactly what the payload requires)
+ *   - lastApp auto-launch (satellites have no last-app concept)
+ */
+export async function bootstrapSatellite(config) {
+    // 1. Framework-owned shards (same list as bootstrap, no excludes for satellites)
+    const frameworkShards = [sh3coreShard, shellShard, storeShard, adminShard, projectsShard, appearanceShard, layoutsShard];
+    for (const shard of frameworkShards) {
+        registerShardInternal(shard);
+    }
+    // 2. Framework-shipped apps
+    const frameworkApps = [storeApp, adminApp];
+    for (const app of frameworkApps) {
+        registerApp(app);
+    }
+    // 3. Load any packages installed in a previous session from IndexedDB
+    await loadInstalledPackages();
+    // 4. Activate exactly the requested shards.
+    for (const id of config.activateShardIds) {
+        if (registeredShards.has(id)) {
+            try {
+                await activateShard(id, { phase: 'satellite' });
+            }
+            catch (err) {
+                console.error(`[sh3] satellite activation of "${id}" failed:`, err);
+            }
+        }
+        else {
+            console.warn(`[sh3] satellite requested shard "${id}" but it is not registered`);
+        }
+    }
+}
 export { installPackage, listInstalledPackages } from './registry/installer';

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

@@ -77,6 +77,17 @@ export declare const layoutStore: {
     readonly tree: LayoutTree;
     readonly floats: FloatEntry[];
 };
+/**
+ * Satellite-mode layout seed. Replaces the HOME_TREE's docked node with
+ * the supplied LayoutNode so that `layoutStore.root` (and LayoutRenderer)
+ * immediately reflects the satellite payload's content without going through
+ * the workspace-zone-backed app attach path.
+ *
+ * Only for float payloads — app payloads call `launchApp` which handles the
+ * full attach/switch lifecycle itself. Must be called before LayoutRenderer
+ * mounts (i.e. at component instantiation time in SatelliteShell).
+ */
+export declare function seedSatelliteLayout(node: LayoutNode): void;
 /**
  * Test-only reset. Restores the layout store to its boot state: no app
  * attached, active root = 'home'. Not exported from `src/index.ts` —

package/dist/layout/store.svelte.js

@@ -318,6 +318,21 @@ export const layoutStore = {
         return activeTree.floats;
     },
 };
+/**
+ * Satellite-mode layout seed. Replaces the HOME_TREE's docked node with
+ * the supplied LayoutNode so that `layoutStore.root` (and LayoutRenderer)
+ * immediately reflects the satellite payload's content without going through
+ * the workspace-zone-backed app attach path.
+ *
+ * Only for float payloads — app payloads call `launchApp` which handles the
+ * full attach/switch lifecycle itself. Must be called before LayoutRenderer
+ * mounts (i.e. at component instantiation time in SatelliteShell).
+ */
+export function seedSatelliteLayout(node) {
+    HOME_TREE.docked = node;
+    HOME_TREE.floats = [];
+    activeRoot = 'home';
+}
 /**
  * Test-only reset. Restores the layout store to its boot state: no app
  * attached, active root = 'home'. Not exported from `src/index.ts` —