sh3-core 0.1.0

package/dist/registry/loader.js

@@ -0,0 +1,145 @@
+/**
+ * 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 * as api from '../api';
+import * as svelte from 'svelte';
+// @ts-expect-error — svelte/internal/client has no public type declarations
+import * as svelteInternalClient from 'svelte/internal/client';
+// ---- shim infrastructure ---------------------------------------------------
+/**
+ * Create a blob URL that re-exports every runtime key from a module
+ * previously stashed on globalThis. The shim is created once and never
+ * revoked — it must outlive every bundle that references it.
+ */
+// JS reserved words that can't appear in destructuring or as bare export names.
+const RESERVED = new Set([
+    'await', 'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger',
+    'default', 'delete', 'do', 'else', 'enum', 'export', 'extends', 'false',
+    'finally', 'for', 'function', 'if', 'import', 'in', 'instanceof', 'let',
+    'new', 'null', 'return', 'super', 'switch', 'this', 'throw', 'true', 'try',
+    'typeof', 'var', 'void', 'while', 'with', 'yield',
+]);
+function createShimUrl(globalKey, mod) {
+    const names = Object.keys(mod);
+    const safe = names.filter(n => !RESERVED.has(n));
+    const reserved = names.filter(n => RESERVED.has(n));
+    const lines = [`const __m__ = globalThis.${globalKey};`];
+    // Safe names can use destructuring.
+    if (safe.length > 0) {
+        lines.push(`export const { ${safe.join(', ')} } = __m__;`);
+    }
+    // Reserved words need individual re-exports via a renamed binding.
+    for (const name of reserved) {
+        lines.push(`const __r_${name}__ = __m__['${name}']; export { __r_${name}__ as ${name} };`);
+    }
+    lines.push(`export default __m__.default;`);
+    return URL.createObjectURL(new Blob([lines.join('\n')], { type: 'application/javascript' }));
+}
+// Expose modules on globalThis so shims can read them.
+const g = globalThis;
+g.__sh3__ = api;
+g.__sh3_svelte__ = svelte;
+g.__sh3_svelte_internal_client__ = svelteInternalClient;
+// Build shim URLs once at module load time.
+const shimUrls = {
+    'sh3-core': createShimUrl('__sh3__', api),
+    'svelte': createShimUrl('__sh3_svelte__', svelte),
+    'svelte/internal/client': createShimUrl('__sh3_svelte_internal_client__', svelteInternalClient),
+};
+// `svelte/internal/disclose-version` is a side-effect-only import (no exports).
+// Create an empty shim so the import doesn't fail.
+shimUrls['svelte/internal/disclose-version'] = URL.createObjectURL(new Blob([''], { type: 'application/javascript' }));
+// `sh3/tokens.css` — design tokens are already loaded by the host shell.
+// Bundles that import this path get a no-op so the import doesn't fail.
+shimUrls['sh3-core/tokens.css'] = URL.createObjectURL(new Blob([''], { type: 'application/javascript' }));
+// ---- bare specifier rewriting ----------------------------------------------
+/**
+ * Match bare specifier imports/re-exports:
+ *   from 'svelte/internal/client'
+ *   from "sh3-core"
+ *   import "svelte/internal/disclose-version"
+ *
+ * Captures the quote char and the specifier. Only rewrites specifiers
+ * that have a shim URL registered above.
+ */
+const BARE_IMPORT_RE = /(?:from|import)\s*(['"])(sh3-core(?:\/[^'"]*)?|svelte(?:\/[^'"]*)?)\1/g;
+function rewriteBareImports(source) {
+    return source.replace(BARE_IMPORT_RE, (match, _quote, specifier) => {
+        const shim = shimUrls[specifier];
+        if (!shim)
+            return match; // unknown specifier — leave as-is
+        // Preserve the keyword (from vs import) from the original match.
+        const keyword = match.startsWith('from') ? 'from' : 'import';
+        return `${keyword} '${shim}'`;
+    });
+}
+/**
+ * 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 async function loadBundleModule(bytes) {
+    const source = new TextDecoder().decode(bytes);
+    const rewritten = rewriteBareImports(source);
+    const blob = new Blob([rewritten], { type: 'application/javascript' });
+    const url = URL.createObjectURL(blob);
+    try {
+        const mod = await import(/* @vite-ignore */ url);
+        const result = { shards: [], apps: [] };
+        for (const value of Object.values(mod)) {
+            if (!value || typeof value !== 'object' || !('manifest' in value)) {
+                continue;
+            }
+            const candidate = value;
+            if (isShard(candidate))
+                result.shards.push(candidate);
+            else if (isApp(candidate))
+                result.apps.push(candidate);
+        }
+        if (result.shards.length === 0 && result.apps.length === 0) {
+            throw new Error('Bundle has no exports with a "manifest" property — expected at least one shard or app');
+        }
+        return result;
+    }
+    finally {
+        URL.revokeObjectURL(url);
+    }
+}
+/**
+ * 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 function isShard(mod) {
+    return ('activate' in mod &&
+        typeof mod.activate === 'function' &&
+        Array.isArray(mod.manifest.views));
+}
+/**
+ * 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 function isApp(mod) {
+    return ('initialLayout' in mod &&
+        Array.isArray(mod.manifest.requiredShards));
+}

package/dist/registry/schema.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Runtime validation for registry index JSON.
+ *
+ * No external schema library — plain runtime checks. The registry index
+ * is fetched from untrusted URLs so all fields are validated before any
+ * typed access occurs. Validation errors carry a JSON-path string so the
+ * caller can surface actionable diagnostics in the store UI.
+ *
+ * Usage:
+ * ```ts
+ * const raw = await response.json();
+ * const index = validateRegistryIndex(raw); // throws RegistryValidationError on bad input
+ * ```
+ */
+import type { RegistryIndex } from './types.js';
+/**
+ * Thrown when a registry index document fails validation.
+ *
+ * The `path` property is a JSON-path string pointing to the field that
+ * caused the failure (e.g. `"$.packages[2].versions[0].integrity"`).
+ * Consumers may display this directly in diagnostic/error UI.
+ */
+export declare class RegistryValidationError extends Error {
+    /**
+     * JSON-path of the failing field (e.g. `"$.packages[0].type"`).
+     */
+    readonly path: string;
+    /**
+     * @param path - JSON-path string of the failing field.
+     * @param message - Human-readable description of why validation failed.
+     */
+    constructor(path: string, message: string);
+}
+/**
+ * Validate an unknown value as a `RegistryIndex`.
+ *
+ * Performs a full deep validation of all required fields and their types.
+ * Returns a correctly typed `RegistryIndex` on success.
+ * Throws `RegistryValidationError` on the first validation failure.
+ *
+ * Call this immediately after `response.json()` before touching any field.
+ *
+ * @param data - The raw parsed JSON value from a registry fetch.
+ * @returns A fully validated `RegistryIndex`.
+ * @throws `RegistryValidationError` if any field is missing or has the wrong type.
+ */
+export declare function validateRegistryIndex(data: unknown): RegistryIndex;

package/dist/registry/schema.js

@@ -0,0 +1,180 @@
+/**
+ * Runtime validation for registry index JSON.
+ *
+ * No external schema library — plain runtime checks. The registry index
+ * is fetched from untrusted URLs so all fields are validated before any
+ * typed access occurs. Validation errors carry a JSON-path string so the
+ * caller can surface actionable diagnostics in the store UI.
+ *
+ * Usage:
+ * ```ts
+ * const raw = await response.json();
+ * const index = validateRegistryIndex(raw); // throws RegistryValidationError on bad input
+ * ```
+ */
+/**
+ * Thrown when a registry index document fails validation.
+ *
+ * The `path` property is a JSON-path string pointing to the field that
+ * caused the failure (e.g. `"$.packages[2].versions[0].integrity"`).
+ * Consumers may display this directly in diagnostic/error UI.
+ */
+export class RegistryValidationError extends Error {
+    /**
+     * @param path - JSON-path string of the failing field.
+     * @param message - Human-readable description of why validation failed.
+     */
+    constructor(path, message) {
+        super(`Registry validation error at ${path}: ${message}`);
+        this.name = 'RegistryValidationError';
+        this.path = path;
+    }
+}
+/**
+ * Validate an unknown value as a `RegistryIndex`.
+ *
+ * Performs a full deep validation of all required fields and their types.
+ * Returns a correctly typed `RegistryIndex` on success.
+ * Throws `RegistryValidationError` on the first validation failure.
+ *
+ * Call this immediately after `response.json()` before touching any field.
+ *
+ * @param data - The raw parsed JSON value from a registry fetch.
+ * @returns A fully validated `RegistryIndex`.
+ * @throws `RegistryValidationError` if any field is missing or has the wrong type.
+ */
+export function validateRegistryIndex(data) {
+    if (!data || typeof data !== 'object' || Array.isArray(data)) {
+        throw new RegistryValidationError('$', 'expected an object');
+    }
+    const obj = data;
+    if (obj['version'] !== 1) {
+        throw new RegistryValidationError('$.version', `expected 1, got ${JSON.stringify(obj['version'])}`);
+    }
+    if (!Array.isArray(obj['packages'])) {
+        throw new RegistryValidationError('$.packages', 'expected an array');
+    }
+    const packages = obj['packages'].map((p, i) => validatePackageEntry(p, `$.packages[${i}]`));
+    return { version: 1, packages };
+}
+/**
+ * Validate a single package entry object.
+ *
+ * @param data - Raw value from the `packages` array.
+ * @param path - JSON-path prefix used in error messages.
+ * @returns Validated `PackageEntry`.
+ * @throws `RegistryValidationError` on any field failure.
+ */
+function validatePackageEntry(data, path) {
+    if (!data || typeof data !== 'object' || Array.isArray(data)) {
+        throw new RegistryValidationError(path, 'expected an object');
+    }
+    const obj = data;
+    requireString(obj, 'id', path);
+    requireOneOf(obj, 'type', ['shard', 'app'], path);
+    requireString(obj, 'label', path);
+    requireString(obj, 'description', path);
+    // author: { name: string }
+    const authorPath = `${path}.author`;
+    if (!obj['author'] || typeof obj['author'] !== 'object' || Array.isArray(obj['author'])) {
+        throw new RegistryValidationError(authorPath, 'expected an object');
+    }
+    const author = obj['author'];
+    if (typeof author['name'] !== 'string' || author['name'].length === 0) {
+        throw new RegistryValidationError(`${authorPath}.name`, 'expected a non-empty string');
+    }
+    // versions: non-empty array
+    if (!Array.isArray(obj['versions']) || obj['versions'].length === 0) {
+        throw new RegistryValidationError(`${path}.versions`, 'expected a non-empty array');
+    }
+    const versions = obj['versions'].map((v, i) => validatePackageVersion(v, `${path}.versions[${i}]`));
+    return {
+        id: obj['id'],
+        type: obj['type'],
+        label: obj['label'],
+        description: obj['description'],
+        author: { name: author['name'] },
+        icon: typeof obj['icon'] === 'string' ? obj['icon'] : undefined,
+        versions,
+    };
+}
+/**
+ * Validate a single package version object.
+ *
+ * @param data - Raw value from a `versions` array.
+ * @param path - JSON-path prefix used in error messages.
+ * @returns Validated `PackageVersion`.
+ * @throws `RegistryValidationError` on any field failure.
+ */
+function validatePackageVersion(data, path) {
+    if (!data || typeof data !== 'object' || Array.isArray(data)) {
+        throw new RegistryValidationError(path, 'expected an object');
+    }
+    const obj = data;
+    requireString(obj, 'version', path);
+    requireString(obj, 'contractVersion', path);
+    requireString(obj, 'bundleUrl', path);
+    requireString(obj, 'integrity', path);
+    let requires;
+    if (obj['requires'] !== undefined) {
+        if (!Array.isArray(obj['requires'])) {
+            throw new RegistryValidationError(`${path}.requires`, 'expected an array');
+        }
+        requires = obj['requires'].map((r, i) => validateRequiredDependency(r, `${path}.requires[${i}]`));
+    }
+    return {
+        version: obj['version'],
+        contractVersion: obj['contractVersion'],
+        bundleUrl: obj['bundleUrl'],
+        integrity: obj['integrity'],
+        requires,
+    };
+}
+/**
+ * Validate a single dependency entry in a `requires` array.
+ *
+ * @param data - Raw value from a `requires` array.
+ * @param path - JSON-path prefix used in error messages.
+ * @returns Validated `RequiredDependency`.
+ * @throws `RegistryValidationError` on any field failure.
+ */
+function validateRequiredDependency(data, path) {
+    if (!data || typeof data !== 'object' || Array.isArray(data)) {
+        throw new RegistryValidationError(path, 'expected an object');
+    }
+    const obj = data;
+    requireString(obj, 'id', path);
+    requireString(obj, 'versionRange', path);
+    return {
+        id: obj['id'],
+        versionRange: obj['versionRange'],
+    };
+}
+/**
+ * Assert that `obj[field]` is a non-empty string.
+ *
+ * @param obj - Parent object being validated.
+ * @param field - Field name to check.
+ * @param path - JSON-path of the parent object (field name is appended on error).
+ * @throws `RegistryValidationError` if the field is missing, not a string, or empty.
+ */
+function requireString(obj, field, path) {
+    const value = obj[field];
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new RegistryValidationError(`${path}.${field}`, 'expected a non-empty string');
+    }
+}
+/**
+ * Assert that `obj[field]` is one of the allowed string values.
+ *
+ * @param obj - Parent object being validated.
+ * @param field - Field name to check.
+ * @param values - Allowed values.
+ * @param path - JSON-path of the parent object (field name is appended on error).
+ * @throws `RegistryValidationError` if the field value is not in `values`.
+ */
+function requireOneOf(obj, field, values, path) {
+    if (!values.includes(obj[field])) {
+        throw new RegistryValidationError(`${path}.${field}`, `expected one of: ${values.join(', ')}`);
+    }
+}

package/dist/registry/storage.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Package storage -- persists installed bundles and metadata.
+ *
+ * Uses IndexedDB, available in all target environments (browser, Tauri
+ * WebView, Android WebView). Two object stores:
+ *   - "bundles" -- raw ArrayBuffer keyed by package id
+ *   - "meta" -- InstalledPackage records keyed by package id
+ *
+ * Designed to be swappable: a Tauri target could later substitute a
+ * filesystem-backed implementation behind the same interface.
+ */
+import type { InstalledPackage } from './types';
+/**
+ * Persist a package bundle and its metadata.
+ * Overwrites any existing record for the same `id`.
+ */
+export declare function savePackage(id: string, bundle: ArrayBuffer, meta: InstalledPackage): Promise<void>;
+/**
+ * Load the raw bundle bytes for an installed package.
+ * Returns `null` if no bundle is stored for `id`.
+ */
+export declare function loadBundle(id: string): Promise<ArrayBuffer | null>;
+/**
+ * Load the metadata record for an installed package.
+ * Returns `null` if no metadata is stored for `id`.
+ */
+export declare function loadMeta(id: string): Promise<InstalledPackage | null>;
+/**
+ * List metadata for all installed packages.
+ * Returns an empty array when nothing has been installed yet.
+ */
+export declare function listInstalled(): Promise<InstalledPackage[]>;
+/**
+ * Remove a package's bundle and metadata from storage.
+ * No-ops silently if the package was not installed.
+ */
+export declare function removePackage(id: string): Promise<void>;

package/dist/registry/storage.js

@@ -0,0 +1,101 @@
+/**
+ * Package storage -- persists installed bundles and metadata.
+ *
+ * Uses IndexedDB, available in all target environments (browser, Tauri
+ * WebView, Android WebView). Two object stores:
+ *   - "bundles" -- raw ArrayBuffer keyed by package id
+ *   - "meta" -- InstalledPackage records keyed by package id
+ *
+ * Designed to be swappable: a Tauri target could later substitute a
+ * filesystem-backed implementation behind the same interface.
+ */
+const DB_NAME = 'sh3-packages';
+const DB_VERSION = 1;
+const BUNDLES_STORE = 'bundles';
+const META_STORE = 'meta';
+/**
+ * Opens (or creates) the sh3-packages IndexedDB database.
+ * Called internally before every storage operation.
+ */
+function openDb() {
+    return new Promise((resolve, reject) => {
+        const request = indexedDB.open(DB_NAME, DB_VERSION);
+        request.onupgradeneeded = () => {
+            const db = request.result;
+            if (!db.objectStoreNames.contains(BUNDLES_STORE)) {
+                db.createObjectStore(BUNDLES_STORE);
+            }
+            if (!db.objectStoreNames.contains(META_STORE)) {
+                db.createObjectStore(META_STORE);
+            }
+        };
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
+    });
+}
+/**
+ * Wraps a single IDBObjectStore operation in a promise.
+ * Opens a transaction on `store`, calls `fn` with the object store, and
+ * resolves with the request result or rejects on error.
+ */
+function tx(db, store, mode, fn) {
+    return new Promise((resolve, reject) => {
+        const transaction = db.transaction(store, mode);
+        const objectStore = transaction.objectStore(store);
+        const request = fn(objectStore);
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
+    });
+}
+/**
+ * Persist a package bundle and its metadata.
+ * Overwrites any existing record for the same `id`.
+ */
+export async function savePackage(id, bundle, meta) {
+    const db = await openDb();
+    await tx(db, BUNDLES_STORE, 'readwrite', (s) => s.put(bundle, id));
+    await tx(db, META_STORE, 'readwrite', (s) => s.put(meta, id));
+    db.close();
+}
+/**
+ * Load the raw bundle bytes for an installed package.
+ * Returns `null` if no bundle is stored for `id`.
+ */
+export async function loadBundle(id) {
+    const db = await openDb();
+    const result = await tx(db, BUNDLES_STORE, 'readonly', (s) => s.get(id));
+    db.close();
+    return result !== null && result !== void 0 ? result : null;
+}
+/**
+ * Load the metadata record for an installed package.
+ * Returns `null` if no metadata is stored for `id`.
+ */
+export async function loadMeta(id) {
+    var _a;
+    const db = await openDb();
+    const result = await tx(db, META_STORE, 'readonly', (s) => s.get(id));
+    db.close();
+    return (_a = result) !== null && _a !== void 0 ? _a : null;
+}
+/**
+ * List metadata for all installed packages.
+ * Returns an empty array when nothing has been installed yet.
+ */
+export async function listInstalled() {
+    var _a;
+    const db = await openDb();
+    const result = await tx(db, META_STORE, 'readonly', (s) => s.getAll());
+    db.close();
+    return (_a = result) !== null && _a !== void 0 ? _a : [];
+}
+/**
+ * Remove a package's bundle and metadata from storage.
+ * No-ops silently if the package was not installed.
+ */
+export async function removePackage(id) {
+    const db = await openDb();
+    await tx(db, BUNDLES_STORE, 'readwrite', (s) => s.delete(id));
+    await tx(db, META_STORE, 'readwrite', (s) => s.delete(id));
+    db.close();
+}