sh3-core 0.6.0

package/dist/apps/types.d.ts

@@ -0,0 +1,93 @@
+import type { LayoutNode } from '../layout/types';
+import type { ZoneSchema, ZoneManager } from '../state/types';
+import type { StateZones } from '../state/zones.svelte';
+/**
+ * Static description of an app. Declared by every app module and read by
+ * the shell launcher to populate the home screen list without running any
+ * activation code.
+ */
+export interface AppManifest {
+    /** Unique app identifier. Must match the app's registration key. */
+    id: string;
+    /** Human-readable display name shown in the launcher. */
+    label: string;
+    /** Semver string for the app package. */
+    version: string;
+    /**
+     * Shard ids this app requires. All required shards are activated at
+     * launch time (skipping any already-active from a previous launch or
+     * from self-starting). Deactivation at unload deactivates only the
+     * shards this app is the last consumer of; shared shards and self-
+     * starting shards (diagnostic, __sh3core__) stay running.
+     */
+    requiredShards: string[];
+    /**
+     * Bump to invalidate persisted layouts. On launch, a persisted blob
+     * whose version doesn't match this is discarded and `initialLayout`
+     * is used instead. Phase 8 does not migrate — version bumps reset
+     * user customization.
+     */
+    layoutVersion: number;
+    /**
+     * When true, the app is only visible on the shell home screen in
+     * admin mode. Server-side routes may still enforce their own auth
+     * independently. Defaults to false (visible to everyone).
+     */
+    admin?: boolean;
+    /**
+     * Optional permissions this app requests beyond the default sandbox.
+     * Declared in the manifest and surfaced to the user at install time
+     * by the store app. Currently recognized: `'state:manage'` — cross-
+     * shard zone access.
+     */
+    permissions?: string[];
+}
+/**
+ * Context object passed to `App.activate`. Provides app-scoped state zones
+ * that are namespaced to the app id, preventing collision with any shard
+ * that happens to share the same name.
+ */
+export interface AppContext {
+    /**
+     * App-scoped state zones. The shardId underneath is the app id, so
+     * `state({ workspace: { x: 0 } }).workspace.x = 1` persists to
+     * `sh3:workspace:<appId>` with no collision risk against any shard
+     * of the same name.
+     */
+    state<T extends ZoneSchema>(schema: T): StateZones<T>;
+    /**
+     * Cross-shard zone management API. Only present when the app's
+     * manifest declares the `'state:manage'` permission. Check with
+     * `if (ctx.zones)` before use.
+     */
+    zones?: ZoneManager;
+}
+/**
+ * An app module. An app is a composition document — it declares required
+ * shards and an initial layout blueprint, but does not register views or
+ * commands itself. The framework activates the required shards on launch,
+ * restores or applies the initial layout, and calls the optional hooks.
+ */
+export interface App {
+    /** Static manifest describing the app and its requirements. */
+    manifest: AppManifest;
+    /** Starting layout tree. Used on first launch or when the persisted layout version mismatches. */
+    initialLayout: LayoutNode;
+    /** Optional hook called after all required shards are active and the layout is attached. */
+    activate?(ctx: AppContext): void | Promise<void>;
+    /** Optional hook called before the app's shards are deactivated and the layout is detached. */
+    deactivate?(): void | Promise<void>;
+    /**
+     * Called when the user navigates to Home while the app is active. The
+     * app's shards, state, and pooled views remain alive. Return `false`
+     * (sync or async) to cancel the navigation — useful for "unsaved
+     * changes" confirmation modals.
+     */
+    suspend?(): void | false | Promise<void | false>;
+    /**
+     * Called when the app is re-entered from Home (root swap back to app).
+     * Does NOT fire on first launch — that is `activate`. Receives the
+     * same `AppContext` that `activate` received.
+     */
+    resume?(ctx: AppContext): void | Promise<void>;
+}

package/dist/apps/types.js

@@ -0,0 +1,10 @@
+/*
+ * App contract — phase 8.
+ *
+ * An app is a composition document. It declares what shards it needs
+ * and what layout to start with, plus an optional activate hook for
+ * app-internal startup work. Apps are NOT shards — they do not register
+ * contributions, do not have their own views, and do not contribute to
+ * other apps' layouts. They compose existing shard views.
+ */
+export {};

package/dist/artifact.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Static manifest file included in every SH3 artifact directory.
+ * Generated at build time from the shard/app manifest in code.
+ * This is the single source of truth for package metadata —
+ * registries, servers, and install tools read this instead of
+ * requiring manual metadata entry.
+ */
+export interface ArtifactManifest {
+    /** Unique package identifier. Matches the shard/app manifest id. */
+    id: string;
+    /** Whether this is a shard or app (or both via combo bundle). */
+    type: 'shard' | 'app' | 'combo';
+    /** Human-readable display name. */
+    label: string;
+    /** Version string (semver). */
+    version: string;
+    /** SH3 contract version this artifact was built against. */
+    contractVersion: number;
+    /** Relative path to the client bundle within the artifact directory. Omit if server-only. */
+    client?: string;
+    /** Relative path to the server bundle within the artifact directory. Omit if client-only. */
+    server?: string;
+    /** Short description (one or two sentences). */
+    description?: string;
+    /** Author name. */
+    author?: string;
+    /** Package dependencies. */
+    requires?: Array<{
+        id: string;
+        versionRange: string;
+    }>;
+}

package/dist/artifact.js

@@ -0,0 +1 @@
+export {};