sh3-core 0.6.0

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

@@ -0,0 +1,218 @@
+/*
+ * Store shard — framework-shipped shard for browsing and managing
+ * installed packages.
+ *
+ * Contributes two views:
+ *   - `sh3-store:browse`    — searchable/filterable catalog of available packages
+ *   - `sh3-store:installed` — list of installed packages with uninstall
+ *
+ * Uses env state for registries (server-authoritative, admin-writable) and
+ * an ephemeral zone for the live catalog / installed list / loading / error state.
+ *
+ * `.svelte.ts` because mounting Svelte components requires rune access.
+ */
+import { mount, unmount } from 'svelte';
+import StoreView from './StoreView.svelte';
+import InstalledView from './InstalledView.svelte';
+import { fetchRegistries, fetchBundle, buildPackageMeta } from '../../registry/client';
+import { installPackage, listInstalledPackages } from '../../registry/installer';
+import { loadBundle, savePackage } from '../../registry/storage';
+import { serverInstallPackage, fetchServerPackages } from '../../env/client';
+/**
+ * Compare two semver-like version strings.
+ * Returns true only if `available` is strictly greater than `installed`.
+ * Compares major.minor.patch left-to-right as integers.
+ * Non-numeric segments are treated as 0.
+ */
+function isNewerVersion(available, installed) {
+    var _a, _b;
+    const a = available.split('.').map((s) => parseInt(s, 10) || 0);
+    const b = installed.split('.').map((s) => parseInt(s, 10) || 0);
+    const len = Math.max(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+        const av = (_a = a[i]) !== null && _a !== void 0 ? _a : 0;
+        const bv = (_b = b[i]) !== null && _b !== void 0 ? _b : 0;
+        if (av > bv)
+            return true;
+        if (av < bv)
+            return false;
+    }
+    return false;
+}
+/**
+ * Module-level context set during activate(). Imported by the Svelte
+ * view components so they can read/write store state and trigger refreshes.
+ */
+export let storeContext = undefined;
+export const storeShard = {
+    manifest: {
+        id: 'sh3-store',
+        label: 'Package Store',
+        version: '0.2.1',
+        views: [
+            { id: 'sh3-store:browse', label: 'Store' },
+            { id: 'sh3-store:installed', label: 'Installed' },
+        ],
+    },
+    activate(ctx) {
+        const env = ctx.env({ registries: [] });
+        const state = ctx.state({
+            ephemeral: {
+                catalog: [],
+                installed: [],
+                updatable: {},
+                loading: false,
+                error: null,
+            },
+        });
+        function recomputeUpdatable() {
+            const result = {};
+            for (const pkg of state.ephemeral.installed) {
+                const catalogEntry = state.ephemeral.catalog.find((c) => c.entry.id === pkg.id);
+                if (catalogEntry && isNewerVersion(catalogEntry.latest.version, pkg.version)) {
+                    result[pkg.id] = catalogEntry;
+                }
+            }
+            state.ephemeral.updatable = result;
+        }
+        async function refreshCatalog() {
+            state.ephemeral.loading = true;
+            state.ephemeral.error = null;
+            try {
+                const results = await fetchRegistries(env.registries);
+                state.ephemeral.catalog = results;
+                recomputeUpdatable();
+            }
+            catch (err) {
+                state.ephemeral.error =
+                    err instanceof Error ? err.message : String(err);
+            }
+            finally {
+                state.ephemeral.loading = false;
+            }
+        }
+        async function refreshInstalled() {
+            try {
+                const serverPkgs = await fetchServerPackages();
+                state.ephemeral.installed = serverPkgs.map((p) => {
+                    var _a, _b, _c;
+                    return ({
+                        id: p.id,
+                        type: p.type,
+                        version: p.version,
+                        sourceRegistry: (_a = p.sourceRegistry) !== null && _a !== void 0 ? _a : '',
+                        contractVersion: (_b = p.contractVersion) !== null && _b !== void 0 ? _b : '',
+                        installedAt: (_c = p.installedAt) !== null && _c !== void 0 ? _c : '',
+                    });
+                });
+                recomputeUpdatable();
+            }
+            catch (err) {
+                console.warn('[sh3-store] Failed to list installed packages:', err instanceof Error ? err.message : err);
+                // Fall back to local list.
+                try {
+                    const packages = await listInstalledPackages();
+                    state.ephemeral.installed = packages;
+                    recomputeUpdatable();
+                }
+                catch (_a) {
+                    // Nothing to show.
+                }
+            }
+        }
+        async function addRegistry(url) {
+            const registries = [...env.registries];
+            if (registries.includes(url))
+                return;
+            registries.push(url);
+            await ctx.envUpdate({ registries });
+        }
+        async function removeRegistry(url) {
+            const registries = env.registries.filter((r) => r !== url);
+            await ctx.envUpdate({ registries });
+        }
+        async function updatePackage(id) {
+            var _a, _b;
+            const catalogEntry = state.ephemeral.updatable[id];
+            if (!catalogEntry)
+                return;
+            const installedRecord = state.ephemeral.installed.find((p) => p.id === id);
+            if (!installedRecord)
+                return;
+            // 1. Fetch new bundle.
+            const bundle = await fetchBundle(catalogEntry.latest, catalogEntry.sourceRegistry);
+            const meta = buildPackageMeta(catalogEntry, catalogEntry.latest);
+            // 2. Snapshot current state for rollback.
+            const oldBundle = await loadBundle(id);
+            const oldRecord = Object.assign({}, installedRecord);
+            // 3. Push to server.
+            const manifest = {
+                id: meta.id,
+                type: meta.type,
+                label: catalogEntry.entry.label,
+                version: meta.version,
+                contractVersion: meta.contractVersion,
+                sourceRegistry: meta.sourceRegistry,
+                installedAt: new Date().toISOString(),
+            };
+            const serverResult = await serverInstallPackage(manifest, bundle);
+            if (!serverResult.ok) {
+                throw new Error((_a = serverResult.error) !== null && _a !== void 0 ? _a : 'Server update failed');
+            }
+            // 4. Install locally (overwrites IndexedDB + re-registers).
+            const result = await installPackage(bundle, meta);
+            if (!result.success) {
+                // Rollback: restore old bundle and metadata.
+                if (oldBundle) {
+                    try {
+                        await savePackage(id, oldBundle, oldRecord);
+                    }
+                    catch (rollbackErr) {
+                        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');
+            }
+            await refreshInstalled();
+        }
+        storeContext = {
+            env,
+            state,
+            get isAdmin() { return ctx.isAdmin; },
+            refreshCatalog,
+            refreshInstalled,
+            updatePackage,
+            addRegistry,
+            removeRegistry,
+        };
+        // --- View factories ---
+        const browseFactory = {
+            mount(container, _context) {
+                const instance = mount(StoreView, { target: container });
+                return {
+                    unmount() {
+                        unmount(instance);
+                    },
+                };
+            },
+        };
+        const installedFactory = {
+            mount(container, _context) {
+                const instance = mount(InstalledView, { target: container });
+                return {
+                    unmount() {
+                        unmount(instance);
+                    },
+                };
+            },
+        };
+        ctx.registerView('sh3-store:browse', browseFactory);
+        ctx.registerView('sh3-store:installed', installedFactory);
+        // refreshInstalled can run immediately (hits server, no env needed).
+        refreshInstalled();
+    },
+    autostart() {
+        // Runs after env hydration, so registries are populated.
+        storeContext.refreshCatalog();
+    },
+};

package/dist/apps/lifecycle.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Read the id of the last-launched app from the user state zone. Used at
+ * boot to decide whether to auto-launch. Returns null if the user last
+ * returned to home or no app has ever been launched.
+ */
+export declare function readLastApp(): string | null;
+/**
+ * Launch an app by id. Activates all required shards (idempotent for
+ * already-active shards), attaches the app's layout, calls `App.activate`,
+ * and switches the rendered root to the app tree.
+ *
+ * If a different app is already active, it is unloaded first. Launching the
+ * same app that is already active is a no-op on shards — it only switches
+ * back from the home view if needed.
+ *
+ * @param id - The `AppManifest.id` of the app to launch. Must be registered.
+ * @throws If the app is not registered or a required shard is not registered.
+ */
+export declare function launchApp(id: string): 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.
+ */
+export declare function unloadApp(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
+ * refcount hold intact, and its view containers stay alive in the pool.
+ * Launching the same app again is a root swap only.
+ *
+ * Fires `suspend` hooks on all required shards (in order), then on the
+ * app itself. Any hook returning `false` cancels navigation — the user
+ * stays in the app. Returns `true` if navigation succeeded, `false` if
+ * cancelled.
+ *
+ * Writes `null` to `__sh3core__:last-app` so reloading the page while on
+ * home lands on home, not on the formerly-active app.
+ */
+export declare function returnToHome(): Promise<boolean>;

package/dist/apps/lifecycle.js

@@ -0,0 +1,184 @@
+/*
+ * App lifecycle — launch, unload, return-to-home.
+ *
+ * All three functions operate on the shared apps registry and the layout
+ * manager. `launchApp` is public (shell home calls it); `unloadApp` is
+ * internal (called from launchApp when replacing a different app);
+ * `returnToHome` is public (shell UI calls it).
+ *
+ * "Last active app" is persisted in the user state zone under the
+ * reserved shardId `__sh3core__:last-app`. The value shape is simply
+ * `{ id: string | null }`. Writing happens on launch (id) and on
+ * return-to-home (null). Boot reads it to decide whether to auto-launch.
+ */
+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 { createZoneManager } from '../state/manage';
+import { PERMISSION_STATE_MANAGE } from '../state/types';
+// ---------- last-active-app user zone ------------------------------------
+/**
+ * Framework-reserved user-zone slot storing which app to boot into on
+ * the next session. Keyed under `__sh3core__:last-app` to avoid collision
+ * with any real shard. Reading/writing uses the same zones machinery as
+ * any shard — nothing special.
+ */
+const lastAppState = createStateZones('__sh3core__:last-app', {
+    user: { id: null },
+});
+/**
+ * Read the id of the last-launched app from the user state zone. Used at
+ * boot to decide whether to auto-launch. Returns null if the user last
+ * returned to home or no app has ever been launched.
+ */
+export function readLastApp() {
+    return lastAppState.user.id;
+}
+function writeLastApp(id) {
+    lastAppState.user.id = id;
+}
+// ---------- app-context state factories ----------------------------------
+const appContexts = new Map();
+function getOrCreateAppContext(appId) {
+    var _a;
+    let ctx = appContexts.get(appId);
+    if (!ctx) {
+        const app = getRegisteredApp(appId);
+        ctx = {
+            state: (schema) => createStateZones(`__app__:${appId}`, schema),
+            zones: ((_a = app === null || app === void 0 ? void 0 : app.manifest.permissions) === null || _a === void 0 ? void 0 : _a.includes(PERMISSION_STATE_MANAGE))
+                ? createZoneManager()
+                : undefined,
+        };
+        appContexts.set(appId, ctx);
+    }
+    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`,
+ * and switches the rendered root to the app tree.
+ *
+ * If a different app is already active, it is unloaded first. Launching the
+ * same app that is already active is a no-op on shards — it only switches
+ * back from the home view if needed.
+ *
+ * @param id - The `AppManifest.id` of the app to launch. Must be registered.
+ * @throws If the app is not registered or a required shard is not registered.
+ */
+export async function launchApp(id) {
+    var _a, _b, _c;
+    const app = getRegisteredApp(id);
+    if (!app) {
+        throw new Error(`Cannot launch app "${id}": not registered`);
+    }
+    // If a different app is already active, unload it first. Relaunching
+    // the same app (while it's active) is a no-op on shards and layout;
+    // 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);
+    }
+    else if (activeApp.id === id) {
+        // Re-entering the same app from Home — fire resume hooks.
+        for (const shardId of app.manifest.requiredShards) {
+            const shard = registeredShards.get(shardId);
+            const shardCtx = getShardContext(shardId);
+            if (shard && shardCtx)
+                void ((_a = shard.resume) === null || _a === void 0 ? void 0 : _a.call(shard, shardCtx));
+        }
+        void ((_b = app.resume) === null || _b === void 0 ? void 0 : _b.call(app, getOrCreateAppContext(id)));
+        switchToApp();
+        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.
+    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.
+    attachApp(app);
+    void ((_c = app.activate) === null || _c === void 0 ? void 0 : _c.call(app, getOrCreateAppContext(id)));
+    activeApp.id = id;
+    switchToApp();
+    writeLastApp(id);
+}
+// ---------- unload --------------------------------------------------------
+/**
+ * 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.
+ */
+export function unloadApp(id) {
+    var _a;
+    if (activeApp.id !== id)
+        return;
+    const app = getRegisteredApp(id);
+    if (!app)
+        return;
+    void ((_a = app.deactivate) === null || _a === void 0 ? void 0 : _a.call(app));
+    // Detach layout (releases the refcount holds; pool cleanup runs on
+    // 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();
+    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
+    // consumer" reduces to "not self-starting AND not required by any
+    // other registered app that happens to already be active" — but we
+    // don't run multiple apps, so the only survivors are self-starters.
+    // The simple rule: deactivate a required shard unless it was
+    // self-starting (has an `autostart` field defined).
+    for (const shardId of app.manifest.requiredShards) {
+        const shard = registeredShards.get(shardId);
+        if (!shard)
+            continue;
+        if (shard.autostart)
+            continue; // self-starter stays running
+        deactivateShard(shardId);
+    }
+    activeApp.id = null;
+    appContexts.delete(id);
+}
+// ---------- return to home -----------------------------------------------
+/**
+ * Return to the shell home view without unloading the active app. The
+ * app's shards stay running, its layout proxy stays attached with its
+ * refcount hold intact, and its view containers stay alive in the pool.
+ * Launching the same app again is a root swap only.
+ *
+ * Fires `suspend` hooks on all required shards (in order), then on the
+ * app itself. Any hook returning `false` cancels navigation — the user
+ * stays in the app. Returns `true` if navigation succeeded, `false` if
+ * cancelled.
+ *
+ * Writes `null` to `__sh3core__:last-app` so reloading the page while on
+ * home lands on home, not on the formerly-active app.
+ */
+export async function returnToHome() {
+    const app = activeApp.id ? getRegisteredApp(activeApp.id) : null;
+    if (app) {
+        for (const shardId of app.manifest.requiredShards) {
+            const shard = registeredShards.get(shardId);
+            if ((shard === null || shard === void 0 ? void 0 : shard.suspend) && (await shard.suspend()) === false)
+                return false;
+        }
+        if (app.suspend && (await app.suspend()) === false)
+            return false;
+    }
+    switchToHome();
+    writeLastApp(null);
+    return true;
+}

package/dist/apps/registry.svelte.d.ts

@@ -0,0 +1,40 @@
+import type { App, AppManifest } from './types';
+/**
+ * Reactive map of all registered apps keyed by `AppManifest.id`. Populated
+ * once at boot by the host's glob-discovery loop via `registerApp`. A future
+ * runtime loader may append entries at runtime.
+ */
+export declare const registeredApps: Map<string, App>;
+/**
+ * Reactive slot tracking the currently-active app id. Null when the shell is
+ * showing the home screen or no app has been launched yet. Phase 8 allows at
+ * most one active app at a time.
+ */
+export declare const activeApp: {
+    id: string | null;
+};
+/**
+ * Register (or re-register) an app with the framework.
+ *
+ * If an app with the same id already exists it is silently replaced,
+ * which is the expected path during package updates — the new bundle is
+ * loaded and re-registered without requiring a full page reload.
+ *
+ * @param app - The app module to register.
+ */
+export declare function registerApp(app: App): void;
+/**
+ * Reactive snapshot of all registered app manifests. Shell home iterates
+ * this to populate its launcher list. Returns only manifests so callers
+ * don't reach into app bodies (initialLayout, activate hook) — those are
+ * launch-time concerns.
+ */
+export declare function listRegisteredApps(): AppManifest[];
+/** Reactive current-app manifest (or null when none is active). */
+export declare function getActiveApp(): AppManifest | null;
+/**
+ * Lookup for framework-internal use — returns the full App (not just the
+ * manifest) so lifecycle code can reach into `initialLayout` and the
+ * activate hook. Not re-exported through `api.ts`.
+ */
+export declare function getRegisteredApp(id: string): App | undefined;

package/dist/apps/registry.svelte.js

@@ -0,0 +1,59 @@
+/*
+ * App registry — reactive record of every registered app, plus the
+ * single slot for the currently-active app.
+ *
+ * Registration is called from the host (main.ts glob loop or a future
+ * runtime loader). The shell home view reads `listRegisteredApps()`
+ * reactively so newly-registered apps appear in the list without
+ * reboot. `activeApp` tracks which app (if any) is currently launched;
+ * phase 8 allows at most one.
+ */
+/**
+ * Reactive map of all registered apps keyed by `AppManifest.id`. Populated
+ * once at boot by the host's glob-discovery loop via `registerApp`. A future
+ * runtime loader may append entries at runtime.
+ */
+export const registeredApps = $state(new Map());
+/**
+ * Reactive slot tracking the currently-active app id. Null when the shell is
+ * showing the home screen or no app has been launched yet. Phase 8 allows at
+ * most one active app at a time.
+ */
+export const activeApp = $state({ id: null });
+/**
+ * Register (or re-register) an app with the framework.
+ *
+ * If an app with the same id already exists it is silently replaced,
+ * which is the expected path during package updates — the new bundle is
+ * loaded and re-registered without requiring a full page reload.
+ *
+ * @param app - The app module to register.
+ */
+export function registerApp(app) {
+    registeredApps.set(app.manifest.id, app);
+}
+/**
+ * Reactive snapshot of all registered app manifests. Shell home iterates
+ * this to populate its launcher list. Returns only manifests so callers
+ * don't reach into app bodies (initialLayout, activate hook) — those are
+ * launch-time concerns.
+ */
+export function listRegisteredApps() {
+    return Array.from(registeredApps.values()).map((a) => a.manifest);
+}
+/** Reactive current-app manifest (or null when none is active). */
+export function getActiveApp() {
+    var _a, _b;
+    const id = activeApp.id;
+    if (!id)
+        return null;
+    return (_b = (_a = registeredApps.get(id)) === null || _a === void 0 ? void 0 : _a.manifest) !== null && _b !== void 0 ? _b : null;
+}
+/**
+ * Lookup for framework-internal use — returns the full App (not just the
+ * manifest) so lifecycle code can reach into `initialLayout` and the
+ * activate hook. Not re-exported through `api.ts`.
+ */
+export function getRegisteredApp(id) {
+    return registeredApps.get(id);
+}

package/dist/apps/terminal/manifest.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Terminal app manifest.
+ *
+ * Framework-shipped: registered in host.ts during bootstrap.
+ * Requires the `shell` shard which provides the `shell:terminal` view.
+ */
+import type { AppManifest } from '../../apps/types';
+export declare const manifest: AppManifest;

package/dist/apps/terminal/manifest.js

@@ -0,0 +1,13 @@
+/**
+ * Terminal app manifest.
+ *
+ * Framework-shipped: registered in host.ts during bootstrap.
+ * Requires the `shell` shard which provides the `shell:terminal` view.
+ */
+export const manifest = {
+    id: 'terminal',
+    label: 'Terminal',
+    version: '0.1.0',
+    requiredShards: ['shell'],
+    layoutVersion: 1,
+};

package/dist/apps/terminal/terminal-app.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Built-in Terminal app — mounts the `shell:terminal` view in a single slot.
+ *
+ * Framework-shipped: registered in host.ts during bootstrap.
+ */
+import type { App } from '../../apps/types';
+export declare const terminalApp: App;

package/dist/apps/terminal/terminal-app.js

@@ -0,0 +1,14 @@
+/**
+ * Built-in Terminal app — mounts the `shell:terminal` view in a single slot.
+ *
+ * Framework-shipped: registered in host.ts during bootstrap.
+ */
+import { manifest } from './manifest';
+export const terminalApp = {
+    manifest,
+    initialLayout: {
+        type: 'slot',
+        slotId: 'terminal.main',
+        viewId: 'shell:terminal',
+    },
+};