sh3-core 0.6.0

package/dist/registry/schema.js

@@ -0,0 +1,185 @@
+/**
+ * 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', 'combo'], 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);
+    // Optional server bundle URL
+    if ('serverBundleUrl' in obj && obj.serverBundleUrl !== undefined) {
+        requireString(obj, 'serverBundleUrl', 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'],
+        serverBundleUrl: typeof obj['serverBundleUrl'] === 'string' ? obj['serverBundleUrl'] : undefined,
+        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();
+}

package/dist/registry/types.d.ts

@@ -0,0 +1,262 @@
+/**
+ * Registry protocol types.
+ *
+ * A registry is any static HTTP endpoint serving a `registry.json` index
+ * and pre-built ESM bundle files. These types define the wire format for
+ * the index document and the local metadata stored after installation.
+ *
+ * Registry flow:
+ * 1. Client fetches `<registryUrl>/registry.json` → `RegistryIndex`
+ * 2. User picks a `PackageEntry` and a `PackageVersion`
+ * 3. Client downloads `bundleUrl`, verifies `integrity`, hot-loads the ESM bundle
+ * 4. On success the client writes an `InstalledPackage` record to local storage
+ */
+/**
+ * Top-level registry index document.
+ *
+ * Served as static JSON at the root of any SH3 registry endpoint.
+ * The `version` field gates forward compatibility — clients that do not
+ * recognise the version must refuse to load the index.
+ */
+export interface RegistryIndex {
+    /**
+     * Protocol version discriminator. Currently always `1`.
+     * Future breaking changes increment this number.
+     */
+    version: 1;
+    /**
+     * All packages published to this registry.
+     * Order is not defined by the protocol; store UI should sort as needed.
+     */
+    packages: PackageEntry[];
+}
+/**
+ * A single package (shard or app) listed in the registry.
+ *
+ * A package has a stable `id` and may publish multiple `versions`. The
+ * store UI displays `label`, `description`, `author`, and optional `icon`.
+ */
+export interface PackageEntry {
+    /**
+     * Unique, stable identifier for this package.
+     * Convention: `@author/package-name` or `plain-name`.
+     * Must not change across versions.
+     */
+    id: string;
+    /**
+     * Whether this package is a shard (module that contributes views/commands)
+     * or an app (composition document that wires shards into a layout).
+     */
+    type: 'shard' | 'app' | 'combo';
+    /**
+     * Human-readable display name shown in the store UI.
+     * Should be short (under 40 characters).
+     */
+    label: string;
+    /**
+     * Short description shown in the store UI.
+     * Should be one or two sentences, plain text.
+     */
+    description: string;
+    /**
+     * Author information. Extended fields (email, url) may be added
+     * in future protocol versions.
+     */
+    author: {
+        /** Human-readable author name. */
+        name: string;
+    };
+    /**
+     * Optional URL to a square icon image (PNG or SVG recommended).
+     * Displayed in the store package card. If omitted the store shows
+     * a generic placeholder.
+     */
+    icon?: string;
+    /**
+     * All published versions of this package, newest-first by convention.
+     * Must contain at least one entry.
+     */
+    versions: PackageVersion[];
+}
+/**
+ * A specific published version of a package.
+ *
+ * Each version ships a self-contained pre-built ESM bundle at `bundleUrl`.
+ * The `integrity` field is an SRI hash (sha384 recommended) used to verify
+ * the download before execution.
+ */
+export interface PackageVersion {
+    /**
+     * Semver version string (e.g. `"1.2.3"`).
+     * Must be unique within a `PackageEntry.versions` array.
+     */
+    version: string;
+    /**
+     * The `sh3-core` contract version this bundle was built against
+     * (e.g. `"0.1.0"`). The install API checks this against the running
+     * framework version and may warn or block on mismatch.
+     */
+    contractVersion: string;
+    /**
+     * Absolute or registry-relative URL to the pre-built ESM bundle.
+     * The client fetches this URL and verifies the download against `integrity`
+     * before executing.
+     */
+    bundleUrl: string;
+    /**
+     * SRI integrity hash for the bundle file.
+     * Format: `"<algorithm>-<base64digest>"` (e.g. `"sha384-abc123..."`).
+     * Algorithms: sha256, sha384 (recommended), sha512.
+     * See: https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity
+     */
+    integrity: string;
+    /**
+     * Optional URL to the server-side bundle for shards that have a backend
+     * component. Same resolution rules as `bundleUrl` (absolute or registry-
+     * relative). Only present when the shard declares `serverBundle` in its
+     * manifest.
+     */
+    serverBundleUrl?: string;
+    /**
+     * Other shards that must be installed and active before this package
+     * can be loaded. Optional — omit if the package has no dependencies.
+     *
+     * For apps: lists the shards the app's layout references.
+     * For shards: lists shards this shard imports from at runtime.
+     * Version ranges follow semver (e.g. `"^2.0.0"`, `">=1.0.0 <2.0.0"`).
+     */
+    requires?: RequiredDependency[];
+}
+/**
+ * A declared dependency on another shard with a semver version range.
+ *
+ * The install API resolves and validates all dependencies before loading
+ * the bundle, refusing to install if a dependency is missing or incompatible.
+ */
+export interface RequiredDependency {
+    /**
+     * The shard id that must be present.
+     * Must match a `PackageEntry.id` in some available registry.
+     */
+    id: string;
+    /**
+     * Semver range the installed shard version must satisfy.
+     * Examples: `"^1.0.0"`, `">=2.0.0 <3.0.0"`, `"1.2.x"`.
+     * Uses standard semver range notation.
+     */
+    versionRange: string;
+}
+/**
+ * Metadata for an installed package, persisted in local storage.
+ *
+ * Written by the install API on successful installation. Used to show
+ * installed/update-available status in the store UI, and to reconstruct
+ * the package registry after a page reload without re-fetching remote indices.
+ */
+export interface InstalledPackage {
+    /**
+     * Package id. Matches the `PackageEntry.id` from the registry.
+     */
+    id: string;
+    /**
+     * Whether this is a shard or an app.
+     */
+    type: 'shard' | 'app' | 'combo';
+    /**
+     * The version that was installed.
+     */
+    version: string;
+    /**
+     * URL of the registry this package was fetched from.
+     * Stored so the store UI can check for updates from the same source.
+     */
+    sourceRegistry: string;
+    /**
+     * The `sh3-core` contract version the installed bundle was built
+     * against. Used to detect contract version mismatches after framework
+     * upgrades.
+     */
+    contractVersion: string;
+    /**
+     * ISO 8601 timestamp of when the package was installed.
+     * Example: `"2026-04-06T12:34:56.789Z"`.
+     */
+    installedAt: string;
+}
+/**
+ * Result of an install operation.
+ *
+ * Returned by the framework install API after attempting to download,
+ * verify, and hot-load a package bundle.
+ */
+export interface InstallResult {
+    /**
+     * Whether the installation succeeded.
+     * On `false`, inspect `error` for the reason.
+     */
+    success: boolean;
+    /**
+     * The `InstalledPackage` record written to local storage on success.
+     * Undefined on failure.
+     */
+    package?: InstalledPackage;
+    /**
+     * Whether the package was activated in the current session without
+     * requiring a page reload. `false` means the user must reload before
+     * the package is usable.
+     */
+    hotLoaded: boolean;
+    /**
+     * Human-readable error message on failure.
+     * Undefined on success.
+     */
+    error?: string;
+}
+/**
+ * Metadata passed to the install API alongside the raw bundle bytes.
+ *
+ * Carries the provenance information needed to write an `InstalledPackage`
+ * record and to verify the download's integrity before execution.
+ */
+export interface PackageMeta {
+    /**
+     * Package id. Matches `PackageEntry.id`.
+     */
+    id: string;
+    /**
+     * Whether this is a shard or an app.
+     */
+    type: 'shard' | 'app' | 'combo';
+    /**
+     * The version being installed. Matches `PackageVersion.version`.
+     */
+    version: string;
+    /**
+     * The `sh3-core` contract version the bundle was built against.
+     */
+    contractVersion: string;
+    /**
+     * URL of the registry this package was fetched from.
+     */
+    sourceRegistry: string;
+    /**
+     * SRI hash to verify the downloaded bundle against before executing.
+     * Must match `PackageVersion.integrity`.
+     */
+    integrity: string;
+    /**
+     * Declared shard dependencies. Mirrors `PackageVersion.requires`.
+     * Undefined if no dependencies.
+     */
+    requires?: RequiredDependency[];
+    /**
+     * SRI hash for the server bundle. Only present when the package has a
+     * server component.
+     */
+    serverIntegrity?: string;
+    /**
+     * Whether this package includes a server bundle that needs to be pushed
+     * to the server after client-side installation.
+     */
+    hasServerBundle?: boolean;
+}

package/dist/registry/types.js

@@ -0,0 +1,14 @@
+/**
+ * Registry protocol types.
+ *
+ * A registry is any static HTTP endpoint serving a `registry.json` index
+ * and pre-built ESM bundle files. These types define the wire format for
+ * the index document and the local metadata stored after installation.
+ *
+ * Registry flow:
+ * 1. Client fetches `<registryUrl>/registry.json` → `RegistryIndex`
+ * 2. User picks a `PackageEntry` and a `PackageVersion`
+ * 3. Client downloads `bundleUrl`, verifies `integrity`, hot-loads the ESM bundle
+ * 4. On success the client writes an `InstalledPackage` record to local storage
+ */
+export {};

package/dist/server-shard/types.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Server-side shard contract.
+ *
+ * A server shard is the optional backend counterpart to a client shard.
+ * It runs in Node inside sh3-server and declares routes that are mounted
+ * under `/api/<shard-id>/`. Server shards have full Node access — filesystem,
+ * child_process, network, etc. — and are trusted by the admin who installed
+ * them.
+ *
+ * The server bundle is a separate ESM file whose default export conforms
+ * to the `ServerShard` interface.
+ */
+/**
+ * Context provided by sh3-server when mounting a server shard's routes.
+ */
+export interface ServerShardContext {
+    /** The shard id this server bundle belongs to. */
+    shardId: string;
+    /**
+     * Scoped filesystem directory for this shard's persistent data.
+     * Created automatically before `routes()` is called.
+     * Path: `<dataDir>/shards/<shard-id>/`
+     */
+    dataDir: string;
+    /**
+     * Hono middleware that rejects non-admin callers.
+     * Apply per-route to protect mutation endpoints. Public read routes
+     * should not use this.
+     *
+     * Usage: `router.post('/publish', ctx.adminOnly, handler)`
+     */
+    adminOnly: MiddlewareHandler;
+}
+/**
+ * The interface a server shard bundle must default-export.
+ */
+export interface ServerShard {
+    /** Must match the client shard's `manifest.id`. */
+    id: string;
+    /**
+     * Called once at mount time. Register Hono routes on the provided router.
+     * Routes are relative to `/api/<shard-id>/` — e.g. `router.get('/data', ...)`
+     * becomes `GET /api/<shard-id>/data`.
+     *
+     * May be async if the shard needs to initialise resources before serving.
+     */
+    routes: (router: HonoLike, context: ServerShardContext) => void | Promise<void>;
+}
+/**
+ * Hono MiddlewareHandler type — duplicated here to avoid importing hono
+ * in the framework package (which is browser-targeted). The actual
+ * implementation is provided by sh3-server at runtime.
+ */
+type MiddlewareHandler = (c: unknown, next: () => Promise<void>) => Promise<void | Response>;
+/**
+ * Hono app type — simplified stand-in. The actual Hono instance is
+ * provided by sh3-server.
+ */
+type HonoLike = {
+    get(path: string, ...handlers: unknown[]): unknown;
+    post(path: string, ...handlers: unknown[]): unknown;
+    put(path: string, ...handlers: unknown[]): unknown;
+    patch(path: string, ...handlers: unknown[]): unknown;
+    delete(path: string, ...handlers: unknown[]): unknown;
+    use(path: string, ...handlers: unknown[]): unknown;
+};
+export {};

package/dist/server-shard/types.js

@@ -0,0 +1,13 @@
+/**
+ * Server-side shard contract.
+ *
+ * A server shard is the optional backend counterpart to a client shard.
+ * It runs in Node inside sh3-server and declares routes that are mounted
+ * under `/api/<shard-id>/`. Server shards have full Node access — filesystem,
+ * child_process, network, etc. — and are trusted by the admin who installed
+ * them.
+ *
+ * The server bundle is a separate ESM file whose default export conforms
+ * to the `ServerShard` interface.
+ */
+export {};