sh3-core 0.1.0 → 0.2.0

package/dist/platform/index.d.ts

@@ -0,0 +1,10 @@
+import type { Backend } from '../state/types';
+export interface PlatformBackends {
+    workspace: Backend;
+    user: Backend;
+}
+export interface PlatformResult {
+    backends: PlatformBackends | null;
+    localOwner: boolean;
+}
+export declare function resolvePlatform(): Promise<PlatformResult>;

package/dist/platform/index.js

@@ -0,0 +1,37 @@
+/*
+ * Platform detection and backend resolution.
+ *
+ * Called once at boot, before bootstrap(). Detects whether we're running
+ * inside a Tauri webview by attempting to dynamically import the Tauri
+ * store backend. If the import fails (web build, or Tauri APIs absent),
+ * falls back to default localStorage backends.
+ *
+ * Also resolves localOwner — true in Tauri (user owns the device) or
+ * when running a Vite dev server (import.meta.env.DEV). Production web
+ * builds are never local-owner.
+ *
+ * Vite code-splits the Tauri path into a separate chunk that is never
+ * loaded in web builds (the dynamic import fails at runtime).
+ */
+export async function resolvePlatform() {
+    var _a, _b;
+    try {
+        // The variable indirection prevents Vite from statically analysing
+        // the import and failing when the Tauri plugin isn't installed.
+        const path = './tauri-backend';
+        const { TauriStoreBackend } = await import(/* @vite-ignore */ path);
+        const workspace = new TauriStoreBackend('workspace');
+        const user = new TauriStoreBackend('user');
+        // Ensure stores are loaded from disk before returning.
+        await Promise.all([workspace.init(), user.init()]);
+        return { backends: { workspace, user }, localOwner: true };
+    }
+    catch (_c) {
+        // Not in Tauri — fall back to default web backends.
+        // Local-owner if running Vite dev server.
+        // import.meta.env.DEV is injected by Vite at bundle time; guard for
+        // non-Vite consumers (the cast avoids a TS error in library builds).
+        const isDev = (_b = (_a = import.meta.env) === null || _a === void 0 ? void 0 : _a.DEV) !== null && _b !== void 0 ? _b : false;
+        return { backends: null, localOwner: isDev };
+    }
+}

package/dist/platform/tauri-backend.d.ts

@@ -0,0 +1,15 @@
+import type { Backend } from '../state/types';
+export declare class TauriStoreBackend implements Backend {
+    #private;
+    constructor(zoneName: string);
+    read(shardId: string): unknown | undefined;
+    write(shardId: string, value: unknown): void;
+    delete(shardId: string): void;
+    list(): string[];
+    /**
+     * Load the store from disk into the local cache. Must be called once
+     * before read/list return meaningful data. Called by the platform
+     * resolver at boot.
+     */
+    init(): Promise<void>;
+}

package/dist/platform/tauri-backend.js

@@ -0,0 +1,58 @@
+/*
+ * TauriStoreBackend — implements the sh3 Backend interface using
+ * @tauri-apps/plugin-store. Each zone gets its own .json store file
+ * (e.g. "workspace.json", "user.json") in Tauri's app data directory.
+ *
+ * tauri-plugin-store v2 keeps an in-memory cache and flushes to disk
+ * automatically. We pre-load the full store into a local Map during
+ * init(), then serve reads/lists synchronously from that cache —
+ * matching the Backend interface contract. Writes go to both the
+ * local cache and the Tauri store (fire-and-forget async).
+ */
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _TauriStoreBackend_store, _TauriStoreBackend_cache;
+import { LazyStore } from '@tauri-apps/plugin-store';
+export class TauriStoreBackend {
+    constructor(zoneName) {
+        _TauriStoreBackend_store.set(this, void 0);
+        _TauriStoreBackend_cache.set(this, new Map());
+        __classPrivateFieldSet(this, _TauriStoreBackend_store, new LazyStore(`${zoneName}.json`, { defaults: {}, autoSave: true }), "f");
+    }
+    read(shardId) {
+        return __classPrivateFieldGet(this, _TauriStoreBackend_cache, "f").get(shardId);
+    }
+    write(shardId, value) {
+        __classPrivateFieldGet(this, _TauriStoreBackend_cache, "f").set(shardId, value);
+        // Fire-and-forget — autoSave flushes to disk.
+        __classPrivateFieldGet(this, _TauriStoreBackend_store, "f").set(shardId, value).catch((e) => console.warn('SH3: store write failed', e));
+    }
+    delete(shardId) {
+        __classPrivateFieldGet(this, _TauriStoreBackend_cache, "f").delete(shardId);
+        __classPrivateFieldGet(this, _TauriStoreBackend_store, "f").delete(shardId).catch((e) => console.warn('SH3: store delete failed', e));
+    }
+    list() {
+        return [...__classPrivateFieldGet(this, _TauriStoreBackend_cache, "f").keys()];
+    }
+    /**
+     * Load the store from disk into the local cache. Must be called once
+     * before read/list return meaningful data. Called by the platform
+     * resolver at boot.
+     */
+    async init() {
+        const entries = await __classPrivateFieldGet(this, _TauriStoreBackend_store, "f").entries();
+        for (const [key, value] of entries) {
+            __classPrivateFieldGet(this, _TauriStoreBackend_cache, "f").set(key, value);
+        }
+    }
+}
+_TauriStoreBackend_store = new WeakMap(), _TauriStoreBackend_cache = new WeakMap();

package/dist/registry/schema.js

@@ -115,6 +115,10 @@ function validatePackageVersion(data, 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'])) {
@@ -127,6 +131,7 @@ function validatePackageVersion(data, path) {
         contractVersion: obj['contractVersion'],
         bundleUrl: obj['bundleUrl'],
         integrity: obj['integrity'],
+        serverBundleUrl: typeof obj['serverBundleUrl'] === 'string' ? obj['serverBundleUrl'] : undefined,
         requires,
     };
 }

package/dist/registry/types.d.ts

@@ -92,7 +92,7 @@ export interface PackageVersion {
      */
     version: string;
     /**
-     * The `sh3-framework` contract version this bundle was built against
+     * 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.
      */
@@ -110,6 +110,13 @@ export interface PackageVersion {
      * 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.
@@ -165,7 +172,7 @@ export interface InstalledPackage {
      */
     sourceRegistry: string;
     /**
-     * The `sh3-framework` contract version the installed bundle was built
+     * The `sh3-core` contract version the installed bundle was built
      * against. Used to detect contract version mismatches after framework
      * upgrades.
      */
@@ -225,7 +232,7 @@ export interface PackageMeta {
      */
     version: string;
     /**
-     * The `sh3-framework` contract version the bundle was built against.
+     * The `sh3-core` contract version the bundle was built against.
      */
     contractVersion: string;
     /**
@@ -242,4 +249,14 @@ export interface PackageMeta {
      * 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/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 `/s/<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 `/s/<shard-id>/` — e.g. `router.get('/data', ...)`
+     * becomes `GET /s/<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 `/s/<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 {};

package/dist/shards/types.d.ts

@@ -95,6 +95,14 @@ export interface ShardManifest {
      * predate phase 8 must be updated to declare their views here.
      */
     views: ViewDeclaration[];
+    /**
+     * Optional filename of a server-side bundle for this shard. When present,
+     * sh3-server loads the bundle at boot and mounts its routes at
+     * `/s/<shard-id>/`. The server bundle runs in Node with full access.
+     * Only relevant for shards installed via the package store; framework-
+     * shipped shards do not use this field.
+     */
+    serverBundle?: string;
 }
 /**
  * Handed to `shard.activate`. The shard uses it to declare state and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sh3-core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "files": [
     "dist"