sh3-core 0.20.3 → 0.21.2

package/dist/registry/archive.d.ts

@@ -0,0 +1,12 @@
+import type { ArtifactManifest } from '../artifact.js';
+export declare class ArchiveValidationError extends Error {
+    constructor(message: string);
+}
+export declare function validateArchive(bytes: Uint8Array): void;
+export declare function readManifestFromArchive(bytes: Uint8Array): ArtifactManifest;
+export declare function readFileFromArchive(bytes: Uint8Array, filename: string): ArrayBuffer | null;
+export declare function createArchive(entries: {
+    manifest: ArtifactManifest;
+    client?: Uint8Array;
+    server?: Uint8Array;
+}): Uint8Array;

package/dist/registry/archive.js

@@ -0,0 +1,80 @@
+import { unzipSync, zipSync, strToU8 } from 'fflate';
+export class ArchiveValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ArchiveValidationError';
+    }
+}
+export function validateArchive(bytes) {
+    let files;
+    try {
+        files = unzipSync(bytes);
+    }
+    catch (_a) {
+        throw new ArchiveValidationError('Invalid ZIP archive');
+    }
+    if (!files['manifest.json']) {
+        throw new ArchiveValidationError('Archive missing manifest.json');
+    }
+    if (!('client.js' in files) && !('server.js' in files)) {
+        throw new ArchiveValidationError('Archive must contain at least one of client.js or server.js');
+    }
+}
+export function readManifestFromArchive(bytes) {
+    let files;
+    try {
+        files = unzipSync(bytes);
+    }
+    catch (_a) {
+        throw new ArchiveValidationError('Invalid ZIP archive');
+    }
+    const raw = files['manifest.json'];
+    if (!raw)
+        throw new ArchiveValidationError('Archive missing manifest.json');
+    let manifest;
+    try {
+        manifest = JSON.parse(new TextDecoder().decode(raw));
+    }
+    catch (_b) {
+        throw new ArchiveValidationError('manifest.json is not valid JSON');
+    }
+    assertManifestShape(manifest);
+    return manifest;
+}
+function assertManifestShape(m) {
+    if (!m || typeof m !== 'object' || Array.isArray(m)) {
+        throw new ArchiveValidationError('manifest.json must be a JSON object');
+    }
+    const obj = m;
+    for (const field of ['id', 'type', 'version', 'contractVersion']) {
+        if (obj[field] == null) {
+            throw new ArchiveValidationError(`manifest.json missing required field: ${field}`);
+        }
+    }
+}
+export function readFileFromArchive(bytes, filename) {
+    let files;
+    try {
+        files = unzipSync(bytes);
+    }
+    catch (_a) {
+        return null;
+    }
+    const data = files[filename];
+    if (!data)
+        return null;
+    return data.slice().buffer;
+}
+export function createArchive(entries) {
+    if (!entries.client && !entries.server) {
+        throw new ArchiveValidationError('Archive must contain at least one of client or server');
+    }
+    const files = {
+        'manifest.json': strToU8(JSON.stringify(entries.manifest, null, 2)),
+    };
+    if (entries.client)
+        files['client.js'] = entries.client;
+    if (entries.server)
+        files['server.js'] = entries.server;
+    return zipSync(files);
+}

package/dist/registry/archive.test.d.ts

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

package/dist/registry/archive.test.js

@@ -0,0 +1,84 @@
+import { describe, it, expect } from 'vitest';
+import { zipSync, strToU8 } from 'fflate';
+import { ArchiveValidationError, validateArchive, readManifestFromArchive, readFileFromArchive, createArchive, } from './archive.js';
+const MANIFEST = {
+    id: 'test-shard',
+    type: 'shard',
+    label: 'Test Shard',
+    version: '1.0.0',
+    contractVersion: 1,
+};
+function makeZip(files) {
+    const entries = {};
+    for (const [k, v] of Object.entries(files))
+        entries[k] = strToU8(v);
+    return zipSync(entries);
+}
+describe('validateArchive', () => {
+    it('accepts archive with client.js', () => {
+        const zip = makeZip({ 'manifest.json': JSON.stringify(MANIFEST), 'client.js': 'export default {}' });
+        expect(() => validateArchive(zip)).not.toThrow();
+    });
+    it('accepts archive with server.js only', () => {
+        const zip = makeZip({ 'manifest.json': JSON.stringify(MANIFEST), 'server.js': 'export default {}' });
+        expect(() => validateArchive(zip)).not.toThrow();
+    });
+    it('accepts archive with both client.js and server.js', () => {
+        const zip = makeZip({ 'manifest.json': JSON.stringify(MANIFEST), 'client.js': 'x', 'server.js': 'y' });
+        expect(() => validateArchive(zip)).not.toThrow();
+    });
+    it('rejects non-ZIP bytes', () => {
+        expect(() => validateArchive(new Uint8Array([1, 2, 3]))).toThrow(ArchiveValidationError);
+    });
+    it('rejects archive missing manifest.json', () => {
+        const zip = makeZip({ 'client.js': 'x' });
+        expect(() => validateArchive(zip)).toThrow(ArchiveValidationError);
+    });
+    it('rejects archive with no JS files', () => {
+        const zip = makeZip({ 'manifest.json': JSON.stringify(MANIFEST) });
+        expect(() => validateArchive(zip)).toThrow(/at least one/);
+    });
+});
+describe('readManifestFromArchive', () => {
+    it('extracts and parses manifest.json', () => {
+        const zip = makeZip({ 'manifest.json': JSON.stringify(MANIFEST), 'client.js': '' });
+        const result = readManifestFromArchive(zip);
+        expect(result.id).toBe('test-shard');
+        expect(result.contractVersion).toBe(1);
+    });
+    it('throws if required field is missing', () => {
+        const bad = { id: 'x', type: 'shard', version: '1.0.0' }; // missing contractVersion
+        const zip = makeZip({ 'manifest.json': JSON.stringify(bad), 'client.js': '' });
+        expect(() => readManifestFromArchive(zip)).toThrow(ArchiveValidationError);
+    });
+    it('throws if manifest.json is not valid JSON', () => {
+        const zip = makeZip({ 'manifest.json': 'not json {{{', 'client.js': '' });
+        expect(() => readManifestFromArchive(zip)).toThrow(ArchiveValidationError);
+    });
+});
+describe('readFileFromArchive', () => {
+    it('returns bytes for a present file', () => {
+        const zip = makeZip({ 'manifest.json': JSON.stringify(MANIFEST), 'client.js': 'hello' });
+        const result = readFileFromArchive(zip, 'client.js');
+        expect(result).not.toBeNull();
+        expect(new TextDecoder().decode(new Uint8Array(result))).toBe('hello');
+    });
+    it('returns null for an absent file', () => {
+        const zip = makeZip({ 'manifest.json': JSON.stringify(MANIFEST), 'client.js': '' });
+        expect(readFileFromArchive(zip, 'server.js')).toBeNull();
+    });
+});
+describe('createArchive', () => {
+    it('round-trips the manifest', () => {
+        const archive = createArchive({ manifest: MANIFEST, client: strToU8('export default {}') });
+        expect(readManifestFromArchive(archive).id).toBe('test-shard');
+    });
+    it('includes client.js when provided', () => {
+        const archive = createArchive({ manifest: MANIFEST, client: strToU8('console.log(1)') });
+        const bytes = readFileFromArchive(archive, 'client.js');
+        expect(new TextDecoder().decode(new Uint8Array(bytes))).toBe('console.log(1)');
+    });
+    it('throws when neither client nor server is provided', () => {
+        expect(() => createArchive({ manifest: MANIFEST })).toThrow(ArchiveValidationError);
+    });
+});

package/dist/registry/client.d.ts

@@ -1,13 +1,13 @@
 /**
  * Registry client -- fetches and merges registry indices, resolves
- * packages, and downloads bundles with integrity verification.
+ * packages, and downloads archives with integrity verification.
  *
  * Typical usage:
  * ```ts
  * const packages = await fetchRegistries(['https://example.com/registry.json']);
  * const pkg = packages.find(p => p.entry.id === 'my-shard');
  * if (pkg) {
- *   const data = await fetchBundle(pkg.latest);
+ *   const archive = await fetchArchive(pkg.latest, pkg.sourceRegistry);
  *   const meta = buildPackageMeta(pkg, pkg.latest);
  * }
  * ```
@@ -44,36 +44,16 @@ export interface ResolvedPackage {
  */
 export declare function fetchRegistries(urls: string[]): Promise<ResolvedPackage[]>;
 /**
- * Download a bundle and verify its SRI integrity hash.
+ * Download a .sh3pkg archive and verify its SRI integrity hash.
  *
- * Fetches `version.bundleUrl`, reads the response as an `ArrayBuffer`, then
- * calls `verifyIntegrity` before returning. Throws on any network error,
- * non-OK HTTP status, or integrity mismatch — the caller must not execute
- * a bundle for which this function threw.
+ * Resolves relative `archiveUrl` values against `sourceRegistry`.
+ * Throws on network error, non-OK HTTP status, or integrity mismatch.
  *
- * If `bundleUrl` is relative (starts with `/`), it is resolved against
- * `sourceRegistry` so cross-origin installs hit the correct server.
- *
- * @param version - The `PackageVersion` describing the bundle to download.
- * @param sourceRegistry - The registry URL this package came from (used to resolve relative bundle paths).
- * @returns Raw bundle bytes, verified against `version.integrity`.
- * @throws If the fetch fails, the server returns a non-OK status, or the integrity check fails.
- */
-export declare function fetchBundle(version: PackageVersion, sourceRegistry?: string): Promise<ArrayBuffer>;
-/**
- * Download a server-side bundle and optionally verify its SRI integrity.
- *
- * Mirrors `fetchBundle` except `serverIntegrity` is optional in contract v1
- * (see ADR-015 proposal). When absent, the download is returned without
- * verification and a warning is logged so operators notice provisional
- * registries. When present, an integrity mismatch throws.
- *
- * @param version - The `PackageVersion` describing the server bundle.
- * @param sourceRegistry - The registry URL (used to resolve relative paths).
- * @returns Raw server bundle bytes.
- * @throws If `serverBundleUrl` is absent, the fetch fails, or an integrity mismatch occurs.
+ * @param version - PackageVersion describing the archive to fetch.
+ * @param sourceRegistry - Registry URL used to resolve relative archiveUrl.
+ * @returns Verified archive bytes.
  */
-export declare function fetchServerBundle(version: PackageVersion, sourceRegistry?: string): Promise<ArrayBuffer>;
+export declare function fetchArchive(version: PackageVersion, sourceRegistry?: string): Promise<Uint8Array>;
 /**
  * Build a `PackageMeta` record from a resolved package and a chosen version.
  *

package/dist/registry/client.js

@@ -1,13 +1,13 @@
 /**
  * Registry client -- fetches and merges registry indices, resolves
- * packages, and downloads bundles with integrity verification.
+ * packages, and downloads archives with integrity verification.
  *
  * Typical usage:
  * ```ts
  * const packages = await fetchRegistries(['https://example.com/registry.json']);
  * const pkg = packages.find(p => p.entry.id === 'my-shard');
  * if (pkg) {
- *   const data = await fetchBundle(pkg.latest);
+ *   const archive = await fetchArchive(pkg.latest, pkg.sourceRegistry);
  *   const meta = buildPackageMeta(pkg, pkg.latest);
  * }
  * ```
@@ -65,71 +65,27 @@ export async function fetchRegistries(urls) {
     return results;
 }
 /**
- * Download a bundle and verify its SRI integrity hash.
+ * Download a .sh3pkg archive and verify its SRI integrity hash.
  *
- * Fetches `version.bundleUrl`, reads the response as an `ArrayBuffer`, then
- * calls `verifyIntegrity` before returning. Throws on any network error,
- * non-OK HTTP status, or integrity mismatch — the caller must not execute
- * a bundle for which this function threw.
+ * Resolves relative `archiveUrl` values against `sourceRegistry`.
+ * Throws on network error, non-OK HTTP status, or integrity mismatch.
  *
- * If `bundleUrl` is relative (starts with `/`), it is resolved against
- * `sourceRegistry` so cross-origin installs hit the correct server.
- *
- * @param version - The `PackageVersion` describing the bundle to download.
- * @param sourceRegistry - The registry URL this package came from (used to resolve relative bundle paths).
- * @returns Raw bundle bytes, verified against `version.integrity`.
- * @throws If the fetch fails, the server returns a non-OK status, or the integrity check fails.
- */
-export async function fetchBundle(version, sourceRegistry) {
-    if (!version.bundleUrl || !version.integrity) {
-        throw new Error('fetchBundle called on a version with no client bundle');
-    }
-    let url = version.bundleUrl;
-    if (sourceRegistry && !/^https?:\/\//i.test(url)) {
-        url = new URL(url, sourceRegistry).href;
-    }
-    const response = await fetch(url);
-    if (!response.ok) {
-        throw new Error(`Bundle fetch failed: HTTP ${response.status} ${response.statusText} from ${url}`);
-    }
-    const data = await response.arrayBuffer();
-    await verifyIntegrity(data, version.integrity);
-    return data;
-}
-/**
- * Download a server-side bundle and optionally verify its SRI integrity.
- *
- * Mirrors `fetchBundle` except `serverIntegrity` is optional in contract v1
- * (see ADR-015 proposal). When absent, the download is returned without
- * verification and a warning is logged so operators notice provisional
- * registries. When present, an integrity mismatch throws.
- *
- * @param version - The `PackageVersion` describing the server bundle.
- * @param sourceRegistry - The registry URL (used to resolve relative paths).
- * @returns Raw server bundle bytes.
- * @throws If `serverBundleUrl` is absent, the fetch fails, or an integrity mismatch occurs.
+ * @param version - PackageVersion describing the archive to fetch.
+ * @param sourceRegistry - Registry URL used to resolve relative archiveUrl.
+ * @returns Verified archive bytes.
  */
-export async function fetchServerBundle(version, sourceRegistry) {
-    if (!version.serverBundleUrl) {
-        throw new Error('fetchServerBundle called on a version with no serverBundleUrl');
-    }
-    let url = version.serverBundleUrl;
+export async function fetchArchive(version, sourceRegistry) {
+    let url = version.archiveUrl;
     if (sourceRegistry && !/^https?:\/\//i.test(url)) {
         url = new URL(url, sourceRegistry).href;
     }
     const response = await fetch(url);
     if (!response.ok) {
-        throw new Error(`Server bundle fetch failed: HTTP ${response.status} ${response.statusText} from ${url}`);
-    }
-    const data = await response.arrayBuffer();
-    if (version.serverIntegrity) {
-        await verifyIntegrity(data, version.serverIntegrity);
-    }
-    else {
-        console.warn(`[sh3] Server bundle at ${url} has no serverIntegrity declared — skipping SRI check. `
-            + 'This will become an error once the formal registry spec (ADR-015) lands.');
+        throw new Error(`Archive fetch failed: HTTP ${response.status} from ${url}`);
     }
-    return data;
+    const buffer = await response.arrayBuffer();
+    await verifyIntegrity(buffer, version.integrity);
+    return new Uint8Array(buffer);
 }
 /**
  * Build a `PackageMeta` record from a resolved package and a chosen version.
@@ -151,7 +107,5 @@ export function buildPackageMeta(resolved, version) {
         sourceRegistry: resolved.sourceRegistry,
         integrity: version.integrity,
         requires: version.requires,
-        hasServerBundle: Boolean(version.serverBundleUrl),
-        serverIntegrity: version.serverIntegrity,
     };
 }

package/dist/registry/client.test.js

@@ -1,5 +1,5 @@
-import { describe, it, expect } from 'vitest';
-import { buildPackageMeta } from './client.js';
+import { describe, it, expect, vi } from 'vitest';
+import { buildPackageMeta, fetchArchive } from './client.js';
 function makeResolved(version) {
     return {
         entry: {
@@ -15,40 +15,50 @@ function makeResolved(version) {
     };
 }
 describe('buildPackageMeta', () => {
-    it('sets hasServerBundle false when no serverBundleUrl', () => {
+    it('builds meta from a resolved package and version', () => {
         const v = {
             version: '1.0.0',
             contractVersion: '0.1.0',
-            bundleUrl: '/b.js',
+            archiveUrl: 'https://example.com/pkg-1.0.0.sh3pkg',
             integrity: 'sha384-xxx',
         };
         const meta = buildPackageMeta(makeResolved(v), v);
-        expect(meta.hasServerBundle).toBe(false);
-        expect(meta.serverIntegrity).toBeUndefined();
+        expect(meta.id).toBe('test-pkg');
+        expect(meta.version).toBe('1.0.0');
+        expect(meta.integrity).toBe('sha384-xxx');
+        expect(meta.sourceRegistry).toBe('https://example.com/registry.json');
     });
-    it('sets hasServerBundle true and propagates serverIntegrity when present', () => {
+    it('propagates requires when present', () => {
         const v = {
             version: '1.0.0',
             contractVersion: '0.1.0',
-            bundleUrl: '/b.js',
+            archiveUrl: 'https://example.com/pkg-1.0.0.sh3pkg',
             integrity: 'sha384-xxx',
-            serverBundleUrl: '/s.js',
-            serverIntegrity: 'sha384-yyy',
+            requires: [{ id: 'dep', versionRange: '^1.0.0' }],
         };
         const meta = buildPackageMeta(makeResolved(v), v);
-        expect(meta.hasServerBundle).toBe(true);
-        expect(meta.serverIntegrity).toBe('sha384-yyy');
+        expect(meta.requires).toEqual([{ id: 'dep', versionRange: '^1.0.0' }]);
     });
-    it('sets hasServerBundle true even when serverIntegrity is missing', () => {
-        const v = {
+});
+describe('fetchArchive', () => {
+    it('fetches and returns archive bytes', async () => {
+        const mockBytes = new Uint8Array([1, 2, 3]);
+        const hashBuffer = await crypto.subtle.digest('SHA-384', mockBytes.buffer);
+        const b64 = btoa(String.fromCharCode(...new Uint8Array(hashBuffer)));
+        const integrity = `sha384-${b64}`;
+        const version = {
             version: '1.0.0',
-            contractVersion: '0.1.0',
-            bundleUrl: '/b.js',
-            integrity: 'sha384-xxx',
-            serverBundleUrl: '/s.js',
+            contractVersion: '1',
+            archiveUrl: 'https://example.com/pkg-1.0.0.sh3pkg',
+            integrity,
         };
-        const meta = buildPackageMeta(makeResolved(v), v);
-        expect(meta.hasServerBundle).toBe(true);
-        expect(meta.serverIntegrity).toBeUndefined();
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
+            ok: true,
+            arrayBuffer: () => Promise.resolve(mockBytes.buffer),
+        }));
+        const result = await fetchArchive(version);
+        expect(result).toBeInstanceOf(Uint8Array);
+        expect(result.length).toBe(3);
+        vi.unstubAllGlobals();
     });
 });

package/dist/registry/index.d.ts

@@ -5,9 +5,9 @@
  * schema validation, integrity verification, client functions, and the
  * install API.
  */
-export type { RegistryIndex, PackageEntry, PackageVersion, RequiredDependency, InstalledPackage, InstallResult, PackageMeta, } from './types';
+export type { RegistryIndex, PackageEntry, PackageVersion, RequiredDependency, InstalledPackage, InstallResult, PackageMeta, RemoteInstallRequest, } from './types';
 export { RegistryValidationError, validateRegistryIndex } from './schema';
 export { verifyIntegrity, computeIntegrity } from './integrity';
 export type { ResolvedPackage } from './client';
-export { fetchRegistries, fetchBundle, buildPackageMeta } from './client';
+export { fetchRegistries, fetchArchive, buildPackageMeta } from './client';
 export { installPackage, uninstallPackage, listInstalledPackages, loadInstalledPackages, } from './installer';

package/dist/registry/index.js

@@ -9,6 +9,6 @@
 export { RegistryValidationError, validateRegistryIndex } from './schema';
 // Integrity verification.
 export { verifyIntegrity, computeIntegrity } from './integrity';
-export { fetchRegistries, fetchBundle, buildPackageMeta } from './client';
+export { fetchRegistries, fetchArchive, buildPackageMeta } from './client';
 // Install API.
 export { installPackage, uninstallPackage, listInstalledPackages, loadInstalledPackages, } from './installer';

package/dist/registry/installer.d.ts

@@ -50,10 +50,10 @@ export declare function uninstallPackage(id: string): Promise<void>;
  */
 export declare function listInstalledPackages(): Promise<InstalledPackage[]>;
 /**
- * Load all installed packages from IndexedDB and register them.
+ * Sync installed packages against the server list and load all into the framework.
  *
- * Called once at boot by `bootstrap()`, before any glob-discovered shards
- * or the sh3 shard are registered. Individual package failures are logged
- * as warnings but do not prevent the sh3 from booting.
+ * Server list is authoritative. Packages on server but missing from IndexedDB
+ * are fetched from the server's /packages/:id/client.js endpoint and cached.
+ * Packages in IndexedDB but absent from the server are evicted.
  */
 export declare function loadInstalledPackages(): Promise<void>;

package/dist/registry/installer.js

@@ -16,11 +16,11 @@
  */
 import { loadBundleModule } from './loader';
 import { savePackage, loadBundle, listInstalled, removePackage } from './storage';
-import { verifyIntegrity } from './integrity';
 import { deactivateShard } from '../shards/activate.svelte';
 import { unregisterApp } from '../apps/lifecycle';
 import { registerLoadedBundle } from './register';
 import { extractBundlePermissions } from './permission-descriptions';
+import { fetchServerPackages } from '../env/client';
 /**
  * Install a package from raw bundle bytes and metadata.
  *
@@ -35,25 +35,8 @@ import { extractBundlePermissions } from './permission-descriptions';
  * @returns Result object indicating success/failure and hot-load status.
  */
 export async function installPackage(bundle, meta, options) {
-    // 1. Verify bundle integrity before executing any code.
-    if (!meta.integrity) {
-        return {
-            success: false,
-            hotLoaded: false,
-            error: 'Missing integrity hash — refusing to install unverified bundle',
-        };
-    }
-    try {
-        await verifyIntegrity(bundle, meta.integrity);
-    }
-    catch (err) {
-        return {
-            success: false,
-            hotLoaded: false,
-            error: `Integrity check failed: ${err instanceof Error ? err.message : String(err)}`,
-        };
-    }
-    // 2. Load the module from verified bytes (or reuse the caller's copy).
+    // 1. Load the module from bytes (or reuse the caller's copy).
+    // Archive integrity is verified upstream in fetchArchive() before extraction.
     let loaded;
     if (options === null || options === void 0 ? void 0 : options.loaded) {
         loaded = options.loaded;
@@ -160,40 +143,86 @@ export async function listInstalledPackages() {
     return listInstalled();
 }
 /**
- * Load all installed packages from IndexedDB and register them.
+ * Sync installed packages against the server list and load all into the framework.
  *
- * Called once at boot by `bootstrap()`, before any glob-discovered shards
- * or the sh3 shard are registered. Individual package failures are logged
- * as warnings but do not prevent the sh3 from booting.
+ * Server list is authoritative. Packages on server but missing from IndexedDB
+ * are fetched from the server's /packages/:id/client.js endpoint and cached.
+ * Packages in IndexedDB but absent from the server are evicted.
  */
 export async function loadInstalledPackages() {
-    let packages;
+    let serverPackages = [];
     try {
-        packages = await listInstalled();
+        serverPackages = await fetchServerPackages();
     }
     catch (err) {
-        console.warn('[sh3] Failed to read installed packages from storage:', err instanceof Error ? err.message : err);
+        console.warn('[sh3] Could not reach server for package sync, loading from local cache:', err instanceof Error ? err.message : err);
+        const fallback = await listInstalled().catch(() => []);
+        for (const pkg of fallback) {
+            await _loadFromIndexedDB(pkg);
+        }
         return;
     }
-    for (const pkg of packages) {
-        try {
-            const bytes = await loadBundle(pkg.id);
-            if (!bytes) {
-                console.warn(`[sh3] No bundle found for installed package "${pkg.id}", skipping`);
-                continue;
-            }
-            const loaded = await loadBundleModule(bytes);
-            registerLoadedBundle(loaded, {
-                version: pkg.version,
-                sourceRegistry: pkg.sourceRegistry,
-                contractVersion: pkg.contractVersion,
-            });
-            if (loaded.shards.length === 0 && loaded.apps.length === 0) {
-                console.warn(`[sh3] Package "${pkg.id}" contains no valid shards or apps, skipping`);
-            }
+    const serverIds = new Set(serverPackages.map(p => p.id));
+    let localPackages = [];
+    try {
+        localPackages = await listInstalled();
+    }
+    catch ( /* treat as empty */_a) { /* treat as empty */ }
+    const localIds = new Set(localPackages.map(p => p.id));
+    // Evict packages no longer on the server
+    for (const pkg of localPackages) {
+        if (!serverIds.has(pkg.id)) {
+            await removePackage(pkg.id).catch(() => { });
         }
-        catch (err) {
-            console.warn(`[sh3] Failed to load installed package "${pkg.id}":`, err instanceof Error ? err.message : err);
+    }
+    // Load packages from server — use IndexedDB cache if available, else fetch from server
+    for (const serverPkg of serverPackages) {
+        if (localIds.has(serverPkg.id)) {
+            const localPkg = localPackages.find(p => p.id === serverPkg.id);
+            await _loadFromIndexedDB(localPkg);
+        }
+        else {
+            await _fetchAndCacheFromServer(serverPkg);
+        }
+    }
+}
+async function _loadFromIndexedDB(pkg) {
+    try {
+        const bytes = await loadBundle(pkg.id);
+        if (!bytes) {
+            console.warn(`[sh3] No bundle in IndexedDB for "${pkg.id}", skipping`);
+            return;
+        }
+        const loaded = await loadBundleModule(bytes);
+        registerLoadedBundle(loaded, { version: pkg.version, sourceRegistry: pkg.sourceRegistry, contractVersion: pkg.contractVersion });
+    }
+    catch (err) {
+        console.warn(`[sh3] Failed to load "${pkg.id}" from cache:`, err instanceof Error ? err.message : err);
+    }
+}
+async function _fetchAndCacheFromServer(serverPkg) {
+    var _a, _b;
+    try {
+        const res = await fetch(serverPkg.bundleUrl);
+        if (!res.ok) {
+            console.warn(`[sh3] Failed to fetch bundle for "${serverPkg.id}": HTTP ${res.status}`);
+            return;
         }
+        const bundle = await res.arrayBuffer();
+        const record = {
+            id: serverPkg.id,
+            type: serverPkg.type,
+            version: serverPkg.version,
+            sourceRegistry: (_a = serverPkg.sourceRegistry) !== null && _a !== void 0 ? _a : '',
+            contractVersion: (_b = serverPkg.contractVersion) !== null && _b !== void 0 ? _b : '',
+            installedAt: new Date().toISOString(),
+            permissions: [],
+        };
+        await savePackage(serverPkg.id, bundle, record);
+        const loaded = await loadBundleModule(bundle);
+        registerLoadedBundle(loaded, { version: record.version, sourceRegistry: record.sourceRegistry, contractVersion: record.contractVersion });
+    }
+    catch (err) {
+        console.warn(`[sh3] Failed to fetch/cache "${serverPkg.id}" from server:`, err instanceof Error ? err.message : err);
     }
 }