sh3-core 0.1.0

package/dist/registry/types.d.ts

@@ -0,0 +1,245 @@
+/**
+ * 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';
+    /**
+     * 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-framework` 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;
+    /**
+     * 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';
+    /**
+     * 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-framework` 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';
+    /**
+     * The version being installed. Matches `PackageVersion.version`.
+     */
+    version: string;
+    /**
+     * The `sh3-framework` 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[];
+}

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 {};