sh3-core 0.1.0

package/dist/primitives/TabbedPanel.svelte.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Controller plugged in by a layout-aware parent to turn tab drags
+ * into layout mutations. The primitive itself is layout-agnostic:
+ * it just calls `onPointerDown` when a tab is grabbed, and asks the
+ * controller to hit-test the strip during a drag via `onStripHover`.
+ */
+export interface TabDragController {
+    onPointerDown(index: number, event: PointerEvent, element: HTMLElement): void;
+    onStripHover(stripRect: DOMRect, pointerX: number, pointerY: number, tabRects: DOMRect[]): number | null;
+    onStripLeave(): void;
+    readonly isDragging: boolean;
+}
+/**
+ * Pure helper: given an insert index and the tab button rects,
+ * compute the indicator's position in strip-local coordinates.
+ */
+export declare function computeIndicatorRect(insertIndex: number, tabEls: (HTMLButtonElement | undefined)[], stripEl: HTMLDivElement | undefined): {
+    left: number;
+    top: number;
+    height: number;
+} | null;
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    labels: string[];
+    icons?: (string | undefined)[];
+    /** Snippet invoked once per tab with its index. */
+    body: Snippet<[number]>;
+    activeTab: number;
+    /** Called when the user picks a different tab. The parent is
+     *  expected to write the new value back into whatever it is
+     *  storing activeTab in. We use a callback rather than a
+     *  $bindable prop because the parent's activeTab typically lives
+     *  inside a larger $state object (a LayoutNode), and `bind:` on a
+     *  sub-property trips Svelte 5's ownership warning. */
+    onActiveChange?: (index: number) => void;
+    dragController?: TabDragController;
+    /** Optional: called by the tab click handler; if it returns true,
+     *  the click is ignored. Used to swallow the synthetic click that
+     *  fires on the source tab after a drag commit. */
+    clickGuard?: () => boolean;
+    /** Per-tab closability. True if the tab can be closed. */
+    closable?: (boolean | undefined)[];
+    /** Per-tab dirty state. True if the tab has unsaved changes. */
+    dirty?: (boolean | undefined)[];
+    /** Called when the user clicks a tab's close button. */
+    onClose?: (index: number) => void;
+};
+declare const TabbedPanel: import("svelte").Component<$$ComponentProps, {}, "">;
+type TabbedPanel = ReturnType<typeof TabbedPanel>;
+export default TabbedPanel;

package/dist/registry/client.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Registry client -- fetches and merges registry indices, resolves
+ * packages, and downloads bundles 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 meta = buildPackageMeta(pkg, pkg.latest);
+ * }
+ * ```
+ */
+import type { PackageEntry, PackageVersion, PackageMeta } from './types.js';
+/**
+ * A `PackageEntry` annotated with its source registry URL and resolved latest version.
+ *
+ * Returned by `fetchRegistries` so callers can display package cards and
+ * initiate installs without needing to re-parse the raw index document.
+ */
+export interface ResolvedPackage {
+    /** The raw package entry from the registry index. */
+    entry: PackageEntry;
+    /**
+     * The latest version of this package.
+     * By convention this is `entry.versions[0]` — registries publish newest-first.
+     */
+    latest: PackageVersion;
+    /** URL of the registry index this package was found in. */
+    sourceRegistry: string;
+}
+/**
+ * Fetch and merge multiple registry indices into a single package catalog.
+ *
+ * Registries are fetched in order. If the same package id appears in more
+ * than one registry, the first registry wins (left-to-right priority).
+ * Fetch or validation failures for individual registries are logged as
+ * warnings and skipped — the function always returns the packages that
+ * could be resolved successfully.
+ *
+ * @param urls - Ordered list of `registry.json` URLs to fetch.
+ * @returns Merged list of resolved packages, deduplicated by package id.
+ */
+export declare function fetchRegistries(urls: string[]): Promise<ResolvedPackage[]>;
+/**
+ * Download a bundle 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.
+ *
+ * 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>;
+/**
+ * Build a `PackageMeta` record from a resolved package and a chosen version.
+ *
+ * Combines identity fields from the `PackageEntry` with provenance and
+ * integrity fields from the selected `PackageVersion`. The result is passed
+ * to the framework install API alongside the raw bundle bytes.
+ *
+ * @param resolved - The resolved package, as returned by `fetchRegistries`.
+ * @param version - The specific version to install (e.g. `resolved.latest`).
+ * @returns A `PackageMeta` ready to be handed to the install API.
+ */
+export declare function buildPackageMeta(resolved: ResolvedPackage, version: PackageVersion): PackageMeta;

package/dist/registry/client.js

@@ -0,0 +1,118 @@
+/**
+ * Registry client -- fetches and merges registry indices, resolves
+ * packages, and downloads bundles 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 meta = buildPackageMeta(pkg, pkg.latest);
+ * }
+ * ```
+ */
+import { validateRegistryIndex } from './schema.js';
+import { verifyIntegrity } from './integrity.js';
+/**
+ * Fetch and merge multiple registry indices into a single package catalog.
+ *
+ * Registries are fetched in order. If the same package id appears in more
+ * than one registry, the first registry wins (left-to-right priority).
+ * Fetch or validation failures for individual registries are logged as
+ * warnings and skipped — the function always returns the packages that
+ * could be resolved successfully.
+ *
+ * @param urls - Ordered list of `registry.json` URLs to fetch.
+ * @returns Merged list of resolved packages, deduplicated by package id.
+ */
+export async function fetchRegistries(urls) {
+    const seen = new Set();
+    const results = [];
+    for (const url of urls) {
+        let raw;
+        try {
+            const response = await fetch(url);
+            if (!response.ok) {
+                console.warn(`[sh3] Registry fetch failed for ${url}: HTTP ${response.status}`);
+                continue;
+            }
+            raw = await response.json();
+        }
+        catch (err) {
+            console.warn(`[sh3] Registry ${url}: ${err instanceof Error ? err.message : String(err)}`);
+            continue;
+        }
+        let index;
+        try {
+            index = validateRegistryIndex(raw);
+        }
+        catch (err) {
+            console.warn(`[sh3] Registry ${url} failed validation: ${err instanceof Error ? err.message : String(err)}`);
+            continue;
+        }
+        for (const entry of index.packages) {
+            if (seen.has(entry.id))
+                continue;
+            seen.add(entry.id);
+            results.push({
+                entry,
+                latest: entry.versions[0],
+                sourceRegistry: url,
+            });
+        }
+    }
+    return results;
+}
+/**
+ * Download a bundle 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.
+ *
+ * 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) {
+    let url = version.bundleUrl;
+    if (sourceRegistry && url.startsWith('/')) {
+        const base = new URL(sourceRegistry);
+        url = `${base.origin}${url}`;
+    }
+    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;
+}
+/**
+ * Build a `PackageMeta` record from a resolved package and a chosen version.
+ *
+ * Combines identity fields from the `PackageEntry` with provenance and
+ * integrity fields from the selected `PackageVersion`. The result is passed
+ * to the framework install API alongside the raw bundle bytes.
+ *
+ * @param resolved - The resolved package, as returned by `fetchRegistries`.
+ * @param version - The specific version to install (e.g. `resolved.latest`).
+ * @returns A `PackageMeta` ready to be handed to the install API.
+ */
+export function buildPackageMeta(resolved, version) {
+    return {
+        id: resolved.entry.id,
+        type: resolved.entry.type,
+        version: version.version,
+        contractVersion: version.contractVersion,
+        sourceRegistry: resolved.sourceRegistry,
+        integrity: version.integrity,
+        requires: version.requires,
+    };
+}

package/dist/registry/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Registry module barrel export.
+ *
+ * Re-exports the public surface of the registry subsystem: protocol types,
+ * schema validation, integrity verification, client functions, and the
+ * install API.
+ */
+export type { RegistryIndex, PackageEntry, PackageVersion, RequiredDependency, InstalledPackage, InstallResult, PackageMeta, } from './types';
+export { RegistryValidationError, validateRegistryIndex } from './schema';
+export { verifyIntegrity, computeIntegrity } from './integrity';
+export type { ResolvedPackage } from './client';
+export { fetchRegistries, fetchBundle, buildPackageMeta } from './client';
+export { installPackage, uninstallPackage, listInstalledPackages, loadInstalledPackages, } from './installer';

package/dist/registry/index.js

@@ -0,0 +1,14 @@
+/**
+ * Registry module barrel export.
+ *
+ * Re-exports the public surface of the registry subsystem: protocol types,
+ * schema validation, integrity verification, client functions, and the
+ * install API.
+ */
+// Schema validation.
+export { RegistryValidationError, validateRegistryIndex } from './schema';
+// Integrity verification.
+export { verifyIntegrity, computeIntegrity } from './integrity';
+export { fetchRegistries, fetchBundle, buildPackageMeta } from './client';
+// Install API.
+export { installPackage, uninstallPackage, listInstalledPackages, loadInstalledPackages, } from './installer';

package/dist/registry/installer.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Package installer -- coordinates storing, loading, and registering packages.
+ *
+ * This is the bridge between the store shard (which fetches and verifies
+ * bundles) and the framework (which registers shards/apps). The install API
+ * is host-only; shards and apps must not import from here.
+ *
+ * Flow:
+ *   1. `installPackage(bundle, meta)` -- load module from bytes, verify
+ *      declared type matches actual type, persist to IndexedDB, register
+ *      with framework.
+ *   2. `uninstallPackage(id)` -- deactivate if active, remove from storage.
+ *   3. `loadInstalledPackages()` -- called at boot, re-loads all installed
+ *      packages from IndexedDB and registers them.
+ */
+import type { InstalledPackage, InstallResult, PackageMeta } from './types';
+/**
+ * Install a package from raw bundle bytes and metadata.
+ *
+ * Loads the ESM module, verifies the declared type matches the actual module
+ * shape, persists to IndexedDB, and registers with the framework. If
+ * registration fails (e.g. duplicate id from a shard that was already
+ * glob-discovered), the package is still persisted but `hotLoaded` is false.
+ *
+ * @param bundle - Raw verified ESM bundle bytes.
+ * @param meta - Provenance metadata for the install record.
+ * @returns Result object indicating success/failure and hot-load status.
+ */
+export declare function installPackage(bundle: ArrayBuffer, meta: PackageMeta): Promise<InstallResult>;
+/**
+ * Uninstall a package by id.
+ *
+ * If the package is a shard and currently active, deactivates it first.
+ * Removes both the bundle and metadata from IndexedDB.
+ *
+ * @param id - The package id to uninstall.
+ */
+export declare function uninstallPackage(id: string): Promise<void>;
+/**
+ * List all installed packages.
+ *
+ * Delegates directly to the storage layer. Returns metadata records only,
+ * not the bundle bytes.
+ */
+export declare function listInstalledPackages(): Promise<InstalledPackage[]>;
+/**
+ * Load all installed packages from IndexedDB and register them.
+ *
+ * Called once at boot by `bootstrap()`, before any glob-discovered shards
+ * or the shell shard are registered. Individual package failures are logged
+ * as warnings but do not prevent the shell from booting.
+ */
+export declare function loadInstalledPackages(): Promise<void>;

package/dist/registry/installer.js

@@ -0,0 +1,170 @@
+/**
+ * Package installer -- coordinates storing, loading, and registering packages.
+ *
+ * This is the bridge between the store shard (which fetches and verifies
+ * bundles) and the framework (which registers shards/apps). The install API
+ * is host-only; shards and apps must not import from here.
+ *
+ * Flow:
+ *   1. `installPackage(bundle, meta)` -- load module from bytes, verify
+ *      declared type matches actual type, persist to IndexedDB, register
+ *      with framework.
+ *   2. `uninstallPackage(id)` -- deactivate if active, remove from storage.
+ *   3. `loadInstalledPackages()` -- called at boot, re-loads all installed
+ *      packages from IndexedDB and registers them.
+ */
+import { loadBundleModule } from './loader';
+import { savePackage, loadBundle, listInstalled, removePackage } from './storage';
+import { verifyIntegrity } from './integrity';
+import { registerShard, deactivateShard } from '../shards/activate.svelte';
+import { registerApp } from '../apps/registry.svelte';
+/**
+ * Install a package from raw bundle bytes and metadata.
+ *
+ * Loads the ESM module, verifies the declared type matches the actual module
+ * shape, persists to IndexedDB, and registers with the framework. If
+ * registration fails (e.g. duplicate id from a shard that was already
+ * glob-discovered), the package is still persisted but `hotLoaded` is false.
+ *
+ * @param bundle - Raw verified ESM bundle bytes.
+ * @param meta - Provenance metadata for the install record.
+ * @returns Result object indicating success/failure and hot-load status.
+ */
+export async function installPackage(bundle, meta) {
+    // 1. Verify bundle integrity before executing any code.
+    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.
+    let loaded;
+    try {
+        loaded = await loadBundleModule(bundle);
+    }
+    catch (err) {
+        return {
+            success: false,
+            hotLoaded: false,
+            error: `Failed to load bundle: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    // 3. Verify the bundle contains the declared type.
+    if (meta.type === 'shard' && loaded.shards.length === 0) {
+        return {
+            success: false,
+            hotLoaded: false,
+            error: `Package "${meta.id}" declared type "shard" but bundle contains no valid shard`,
+        };
+    }
+    if (meta.type === 'app' && loaded.apps.length === 0) {
+        return {
+            success: false,
+            hotLoaded: false,
+            error: `Package "${meta.id}" declared type "app" but bundle contains no valid app`,
+        };
+    }
+    // 4. Persist to IndexedDB.
+    const record = {
+        id: meta.id,
+        type: meta.type,
+        version: meta.version,
+        sourceRegistry: meta.sourceRegistry,
+        contractVersion: meta.contractVersion,
+        installedAt: new Date().toISOString(),
+    };
+    try {
+        await savePackage(meta.id, bundle, record);
+    }
+    catch (err) {
+        return {
+            success: false,
+            hotLoaded: false,
+            error: `Failed to persist package: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    // 5. Register all shards and apps from the bundle.
+    let hotLoaded = true;
+    try {
+        for (const shard of loaded.shards)
+            registerShard(shard);
+        for (const app of loaded.apps)
+            registerApp(app);
+    }
+    catch (err) {
+        // Registration failure (e.g. duplicate id) -- the package is persisted
+        // but not usable until reload. Log and continue.
+        console.warn(`[sh3] Package "${meta.id}" installed but registration failed (will retry on next boot):`, err instanceof Error ? err.message : err);
+        hotLoaded = false;
+    }
+    return { success: true, package: record, hotLoaded };
+}
+/**
+ * Uninstall a package by id.
+ *
+ * If the package is a shard and currently active, deactivates it first.
+ * Removes both the bundle and metadata from IndexedDB.
+ *
+ * @param id - The package id to uninstall.
+ */
+export async function uninstallPackage(id) {
+    // Attempt deactivation (no-op if not active or not a shard).
+    try {
+        deactivateShard(id);
+    }
+    catch (_a) {
+        // Ignore -- may not be a shard, or may not be active.
+    }
+    await removePackage(id);
+}
+/**
+ * List all installed packages.
+ *
+ * Delegates directly to the storage layer. Returns metadata records only,
+ * not the bundle bytes.
+ */
+export async function listInstalledPackages() {
+    return listInstalled();
+}
+/**
+ * Load all installed packages from IndexedDB and register them.
+ *
+ * Called once at boot by `bootstrap()`, before any glob-discovered shards
+ * or the shell shard are registered. Individual package failures are logged
+ * as warnings but do not prevent the shell from booting.
+ */
+export async function loadInstalledPackages() {
+    let packages;
+    try {
+        packages = await listInstalled();
+    }
+    catch (err) {
+        console.warn('[sh3] Failed to read installed packages from storage:', err instanceof Error ? err.message : err);
+        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);
+            for (const shard of loaded.shards)
+                registerShard(shard);
+            for (const app of loaded.apps)
+                registerApp(app);
+            if (loaded.shards.length === 0 && loaded.apps.length === 0) {
+                console.warn(`[sh3] Package "${pkg.id}" contains no valid shards or apps, skipping`);
+            }
+        }
+        catch (err) {
+            console.warn(`[sh3] Failed to load installed package "${pkg.id}":`, err instanceof Error ? err.message : err);
+        }
+    }
+}

package/dist/registry/integrity.d.ts

@@ -0,0 +1,32 @@
+/**
+ * SRI integrity verification for downloaded bundles.
+ *
+ * Uses the Web Crypto API (available in browsers and Tauri WebView).
+ * Accepts "sha384-<base64>" format matching the W3C SRI spec.
+ * See: https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity
+ */
+/**
+ * Verify that `data` matches the expected SRI integrity string.
+ *
+ * Uses the Web Crypto API to compute the digest and compares it against the
+ * base64 hash in `integrity`. Throws with a descriptive message on any
+ * mismatch, invalid format, or unsupported algorithm.
+ *
+ * @param data - Raw bytes of the downloaded bundle.
+ * @param integrity - SRI hash string, e.g. `"sha384-abc123..."`.
+ * @returns Resolves on success; throws on mismatch or bad format.
+ * @throws If the format is invalid, the algorithm is unsupported, or the hash does not match.
+ */
+export declare function verifyIntegrity(data: ArrayBuffer, integrity: string): Promise<void>;
+/**
+ * Compute an SRI hash for the given data.
+ *
+ * Useful for publishing tools that need to generate the `integrity` field
+ * for a `registry.json` entry. Defaults to `sha384`, which is the recommended
+ * algorithm for the SH3 registry protocol.
+ *
+ * @param data - Raw bytes of the bundle to hash.
+ * @param algorithm - Hash algorithm to use. Defaults to `"sha384"`.
+ * @returns SRI string in the form `"<algorithm>-<base64hash>"`.
+ */
+export declare function computeIntegrity(data: ArrayBuffer, algorithm?: 'sha256' | 'sha384' | 'sha512'): Promise<string>;

package/dist/registry/integrity.js

@@ -0,0 +1,92 @@
+/**
+ * SRI integrity verification for downloaded bundles.
+ *
+ * Uses the Web Crypto API (available in browsers and Tauri WebView).
+ * Accepts "sha384-<base64>" format matching the W3C SRI spec.
+ * See: https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity
+ */
+const SUPPORTED_ALGORITHMS = ['sha256', 'sha384', 'sha512'];
+/**
+ * Parse an SRI integrity string into its algorithm and base64 hash components.
+ *
+ * @param integrity - SRI string in the form `"<algorithm>-<base64hash>"`.
+ * @returns Object with `algorithm` and `hash` fields.
+ * @throws If the format is invalid or the algorithm is not supported.
+ */
+function parseSri(integrity) {
+    const dashIndex = integrity.indexOf('-');
+    if (dashIndex === -1) {
+        throw new Error(`Invalid SRI format: ${integrity}`);
+    }
+    const algorithm = integrity.slice(0, dashIndex);
+    const hash = integrity.slice(dashIndex + 1);
+    if (!SUPPORTED_ALGORITHMS.includes(algorithm)) {
+        throw new Error(`Unsupported SRI algorithm: ${algorithm}. Supported: ${SUPPORTED_ALGORITHMS.join(', ')}`);
+    }
+    if (!hash) {
+        throw new Error(`Empty hash in SRI: ${integrity}`);
+    }
+    return { algorithm, hash };
+}
+/**
+ * Map an SRI algorithm name to its Web Crypto API equivalent.
+ *
+ * @param alg - SRI algorithm name (`"sha256"`, `"sha384"`, `"sha512"`).
+ * @returns Web Crypto algorithm name (e.g. `"SHA-384"`).
+ */
+function algorithmToWebCrypto(alg) {
+    return `SHA-${alg.slice(3)}`;
+}
+/**
+ * Encode an `ArrayBuffer` as a base64 string.
+ *
+ * @param buffer - Raw bytes to encode.
+ * @returns Base64 string representation of `buffer`.
+ */
+function bufferToBase64(buffer) {
+    const bytes = new Uint8Array(buffer);
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+}
+/**
+ * Verify that `data` matches the expected SRI integrity string.
+ *
+ * Uses the Web Crypto API to compute the digest and compares it against the
+ * base64 hash in `integrity`. Throws with a descriptive message on any
+ * mismatch, invalid format, or unsupported algorithm.
+ *
+ * @param data - Raw bytes of the downloaded bundle.
+ * @param integrity - SRI hash string, e.g. `"sha384-abc123..."`.
+ * @returns Resolves on success; throws on mismatch or bad format.
+ * @throws If the format is invalid, the algorithm is unsupported, or the hash does not match.
+ */
+export async function verifyIntegrity(data, integrity) {
+    const { algorithm, hash: expectedHash } = parseSri(integrity);
+    const webCryptoAlg = algorithmToWebCrypto(algorithm);
+    const digest = await crypto.subtle.digest(webCryptoAlg, data);
+    const actualHash = bufferToBase64(digest);
+    if (actualHash !== expectedHash) {
+        throw new Error(`Integrity check failed for ${algorithm}. ` +
+            `Expected: ${expectedHash}, got: ${actualHash}`);
+    }
+}
+/**
+ * Compute an SRI hash for the given data.
+ *
+ * Useful for publishing tools that need to generate the `integrity` field
+ * for a `registry.json` entry. Defaults to `sha384`, which is the recommended
+ * algorithm for the SH3 registry protocol.
+ *
+ * @param data - Raw bytes of the bundle to hash.
+ * @param algorithm - Hash algorithm to use. Defaults to `"sha384"`.
+ * @returns SRI string in the form `"<algorithm>-<base64hash>"`.
+ */
+export async function computeIntegrity(data, algorithm = 'sha384') {
+    const webCryptoAlg = algorithmToWebCrypto(algorithm);
+    const digest = await crypto.subtle.digest(webCryptoAlg, data);
+    const hash = bufferToBase64(digest);
+    return `${algorithm}-${hash}`;
+}

package/dist/registry/loader.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Runtime loader -- loads a pre-built ESM bundle from raw bytes via blob URL.
+ *
+ * The install API hands us an ArrayBuffer (the verified bundle), we wrap it
+ * in a blob URL, dynamic-import it, then immediately revoke the URL so the
+ * blob can be GC'd. The module's default export must carry a `manifest`
+ * field; we use duck-typing to distinguish shards from apps.
+ *
+ * Bare specifier rewriting: bundles are built with external dependencies
+ * (`sh3`, `svelte`, `svelte/internal/client`, etc.). Blob URLs can't
+ * resolve bare specifiers, so we expose each dependency's runtime exports
+ * at a stable blob URL (a "shim") and rewrite bare specifiers in the
+ * bundle source before loading.
+ */
+import type { Shard } from '../shards/types';
+import type { App } from '../apps/types';
+/**
+ * Result of loading a bundle — may contain a shard, an app, or both.
+ * Combo bundles (one shard + its companion app) are a supported pattern.
+ */
+export interface LoadedBundle {
+    shards: Shard[];
+    apps: App[];
+}
+/**
+ * Load a pre-built ESM bundle from raw bytes.
+ *
+ * Scans all module exports (default + named) for objects with a `manifest`
+ * property and classifies each as a shard or app. Combo bundles that export
+ * both a shard and its companion app are supported.
+ *
+ * @param bytes - Raw bundle bytes (the verified ESM file contents).
+ * @returns All shards and apps found in the module's exports.
+ * @throws If the blob URL cannot be created or the import fails.
+ */
+export declare function loadBundleModule(bytes: ArrayBuffer): Promise<LoadedBundle>;
+/**
+ * Type guard: returns true if the loaded module is a shard.
+ *
+ * A shard has an `activate` function and `manifest.views` array. An app
+ * has neither — it has `initialLayout` and `manifest.requiredShards`.
+ */
+export declare function isShard(mod: Shard | App): mod is Shard;
+/**
+ * Type guard: returns true if the loaded module is an app.
+ *
+ * An app has `initialLayout` and `manifest.requiredShards`. A shard has
+ * `activate` and `manifest.views` instead.
+ */
+export declare function isApp(mod: Shard | App): mod is App;