@deck-shelves/host 1.3.2 → 1.4.1

package/dist/index.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
 // src/contract/index.ts
-var HOST_API_VERSION = "1.2.0";
+var HOST_API_VERSION = "1.3.0";
 var INJECTED_HOST_GLOBAL = "__SHELVES_HOST__";
 var FORCE_OWNER_GLOBAL = "__SHELVES_FORCE_OWNER__";
 var OWNER_GLOBAL = "__DECK_SHELVES_OWNER__";

package/dist/index.d.cts

@@ -23,9 +23,11 @@
  * npm release version. Bump semver here on shape changes: MINOR for additive,
  * backward-compatible members (a new optional namespace / field); MAJOR on a
  * breaking change. 1.2.0 added the optional `updates` namespace and the
- * optional `React`/`ReactDOM`/`jsx` UI-surface members.
+ * optional `React`/`ReactDOM`/`jsx` UI-surface members. 1.3.0 added the optional
+ * `api.handshake()` + `HostHandshake`, `lifecycle.teardown()`, and the
+ * `routes.addPatch`/`removePatch` route-patch members.
  */
-declare const HOST_API_VERSION: "1.2.0";
+declare const HOST_API_VERSION: "1.3.0";
 interface PluginDescriptor {
     name: string;
     version: string;
@@ -38,6 +40,14 @@ interface HostLifecycle {
     register(plugin: PluginDescriptor): Disposable;
     onMount(cb: () => void): void;
     onUnmount(cb: () => void): void;
+    /**
+     * Dispose the CURRENT bundle instance: runs every `onUnmount` handler once and
+     * clears them. The host calls this before it hot-swaps a new bundle in place, so
+     * two instances never both own the Home. Optional (feature-detected) — a bundle
+     * needing clean re-eval should register real teardown in `onUnmount`.
+     * Returns the number of handlers run.
+     */
+    teardown?(): number;
 }
 /** Generic RPC channel into the host backend. Each host routes it to the
  *  plugin's data backend through its own transport (an in-process bridge, a
@@ -45,9 +55,30 @@ interface HostLifecycle {
 interface HostRpc {
     call<Req = unknown, Res = unknown>(method: string, args?: Req): Promise<Res>;
 }
+/**
+ * Transforms an existing route's props. Receives a shallow copy of the route's
+ * props and returns a partial override (today only `children` is honored); a
+ * missing/void return leaves the route untouched.
+ */
+type RoutePatch = (props: {
+    path?: string;
+    children?: unknown;
+    [key: string]: unknown;
+}) => {
+    children?: unknown;
+} | void;
 interface HostRoutes {
     /** Register a full-page route; returns a disposer that removes it. */
     register(path: string, component: () => unknown): Disposable;
+    /**
+     * Patch an existing route (the host's own or a coexisting loader's) in place —
+     * e.g. wrap the Home to inject shelves. Returns the same `patch` so the caller
+     * can pair it with `removePatch`. Optional (feature-detected): hosts on a
+     * contract below 1.3.0 do not implement it.
+     */
+    addPatch?(path: string, patch: RoutePatch): RoutePatch;
+    /** Remove a patch previously added with {@link addPatch}. Optional. */
+    removePatch?(path: string, patch: RoutePatch): RoutePatch;
 }
 interface ToastOptions {
     title?: string;
@@ -242,6 +273,22 @@ interface HostApi {
     /** Optional self-update surface; present only on hosts that can obtain and
      *  apply an update themselves (see `HostUpdates`). */
     readonly updates?: HostUpdates;
+    /** Optional handshake: identifies the host and the capabilities it implements,
+     *  so a bundle can adapt (and skip feature-detecting each member). Present on
+     *  hosts that support it; absent hosts are read via direct feature detection. */
+    handshake?(): HostHandshake;
+}
+/** What {@link HostApi.handshake} reports: who is hosting, its versions, and a
+ *  flat map of capability flags the bundle can branch on. `hostKind` is an opaque
+ *  host-chosen label (see {@link HostOwnerKind}); the contract names no host. */
+interface HostHandshake {
+    readonly hostKind: HostOwnerKind;
+    /** The host's own product version (e.g. the daemon version). */
+    readonly hostVersion: string;
+    /** The contract version the host implements ({@link HOST_API_VERSION}). */
+    readonly hostApiVersion: string;
+    /** Feature flags, e.g. `{ teardown: true, selfUpdate: true, nativeQam: true }`. */
+    readonly capabilities: Readonly<Record<string, boolean>>;
 }
 /** An owner label is an opaque, host-chosen string; the contract never enumerates
     concrete names (that would bake a host/loader identity into the boundary). */
@@ -324,4 +371,4 @@ declare global {
     }
 }
 
-export { type Disposable, FORCE_OWNER_GLOBAL, HOST_API_VERSION, type HostApi, type HostLifecycle, type HostMainMenu, type HostNotifications, type HostOwnerKind, type HostOwnerMetadata, type HostQam, type HostRoutes, type HostRpc, type HostUi, type HostUpdates, INJECTED_HOST_GLOBAL, type MainMenuEntry, OWNER_GLOBAL, OWNER_METADATA_GLOBAL, type PlatformApi, type PlatformAppMeta, type PlatformCollection, type PlatformTab, type PluginDescriptor, type QamPanel, type ShelfSource, type ShelvesHostGlobal, type ToastOptions, getInjectedHost, isForcedOwner, readForcedOwner, readOwner };
+export { type Disposable, FORCE_OWNER_GLOBAL, HOST_API_VERSION, type HostApi, type HostHandshake, type HostLifecycle, type HostMainMenu, type HostNotifications, type HostOwnerKind, type HostOwnerMetadata, type HostQam, type HostRoutes, type HostRpc, type HostUi, type HostUpdates, INJECTED_HOST_GLOBAL, type MainMenuEntry, OWNER_GLOBAL, OWNER_METADATA_GLOBAL, type PlatformApi, type PlatformAppMeta, type PlatformCollection, type PlatformTab, type PluginDescriptor, type QamPanel, type RoutePatch, type ShelfSource, type ShelvesHostGlobal, type ToastOptions, getInjectedHost, isForcedOwner, readForcedOwner, readOwner };

package/dist/index.d.ts

@@ -23,9 +23,11 @@
  * npm release version. Bump semver here on shape changes: MINOR for additive,
  * backward-compatible members (a new optional namespace / field); MAJOR on a
  * breaking change. 1.2.0 added the optional `updates` namespace and the
- * optional `React`/`ReactDOM`/`jsx` UI-surface members.
+ * optional `React`/`ReactDOM`/`jsx` UI-surface members. 1.3.0 added the optional
+ * `api.handshake()` + `HostHandshake`, `lifecycle.teardown()`, and the
+ * `routes.addPatch`/`removePatch` route-patch members.
  */
-declare const HOST_API_VERSION: "1.2.0";
+declare const HOST_API_VERSION: "1.3.0";
 interface PluginDescriptor {
     name: string;
     version: string;
@@ -38,6 +40,14 @@ interface HostLifecycle {
     register(plugin: PluginDescriptor): Disposable;
     onMount(cb: () => void): void;
     onUnmount(cb: () => void): void;
+    /**
+     * Dispose the CURRENT bundle instance: runs every `onUnmount` handler once and
+     * clears them. The host calls this before it hot-swaps a new bundle in place, so
+     * two instances never both own the Home. Optional (feature-detected) — a bundle
+     * needing clean re-eval should register real teardown in `onUnmount`.
+     * Returns the number of handlers run.
+     */
+    teardown?(): number;
 }
 /** Generic RPC channel into the host backend. Each host routes it to the
  *  plugin's data backend through its own transport (an in-process bridge, a
@@ -45,9 +55,30 @@ interface HostLifecycle {
 interface HostRpc {
     call<Req = unknown, Res = unknown>(method: string, args?: Req): Promise<Res>;
 }
+/**
+ * Transforms an existing route's props. Receives a shallow copy of the route's
+ * props and returns a partial override (today only `children` is honored); a
+ * missing/void return leaves the route untouched.
+ */
+type RoutePatch = (props: {
+    path?: string;
+    children?: unknown;
+    [key: string]: unknown;
+}) => {
+    children?: unknown;
+} | void;
 interface HostRoutes {
     /** Register a full-page route; returns a disposer that removes it. */
     register(path: string, component: () => unknown): Disposable;
+    /**
+     * Patch an existing route (the host's own or a coexisting loader's) in place —
+     * e.g. wrap the Home to inject shelves. Returns the same `patch` so the caller
+     * can pair it with `removePatch`. Optional (feature-detected): hosts on a
+     * contract below 1.3.0 do not implement it.
+     */
+    addPatch?(path: string, patch: RoutePatch): RoutePatch;
+    /** Remove a patch previously added with {@link addPatch}. Optional. */
+    removePatch?(path: string, patch: RoutePatch): RoutePatch;
 }
 interface ToastOptions {
     title?: string;
@@ -242,6 +273,22 @@ interface HostApi {
     /** Optional self-update surface; present only on hosts that can obtain and
      *  apply an update themselves (see `HostUpdates`). */
     readonly updates?: HostUpdates;
+    /** Optional handshake: identifies the host and the capabilities it implements,
+     *  so a bundle can adapt (and skip feature-detecting each member). Present on
+     *  hosts that support it; absent hosts are read via direct feature detection. */
+    handshake?(): HostHandshake;
+}
+/** What {@link HostApi.handshake} reports: who is hosting, its versions, and a
+ *  flat map of capability flags the bundle can branch on. `hostKind` is an opaque
+ *  host-chosen label (see {@link HostOwnerKind}); the contract names no host. */
+interface HostHandshake {
+    readonly hostKind: HostOwnerKind;
+    /** The host's own product version (e.g. the daemon version). */
+    readonly hostVersion: string;
+    /** The contract version the host implements ({@link HOST_API_VERSION}). */
+    readonly hostApiVersion: string;
+    /** Feature flags, e.g. `{ teardown: true, selfUpdate: true, nativeQam: true }`. */
+    readonly capabilities: Readonly<Record<string, boolean>>;
 }
 /** An owner label is an opaque, host-chosen string; the contract never enumerates
     concrete names (that would bake a host/loader identity into the boundary). */
@@ -324,4 +371,4 @@ declare global {
     }
 }
 
-export { type Disposable, FORCE_OWNER_GLOBAL, HOST_API_VERSION, type HostApi, type HostLifecycle, type HostMainMenu, type HostNotifications, type HostOwnerKind, type HostOwnerMetadata, type HostQam, type HostRoutes, type HostRpc, type HostUi, type HostUpdates, INJECTED_HOST_GLOBAL, type MainMenuEntry, OWNER_GLOBAL, OWNER_METADATA_GLOBAL, type PlatformApi, type PlatformAppMeta, type PlatformCollection, type PlatformTab, type PluginDescriptor, type QamPanel, type ShelfSource, type ShelvesHostGlobal, type ToastOptions, getInjectedHost, isForcedOwner, readForcedOwner, readOwner };
+export { type Disposable, FORCE_OWNER_GLOBAL, HOST_API_VERSION, type HostApi, type HostHandshake, type HostLifecycle, type HostMainMenu, type HostNotifications, type HostOwnerKind, type HostOwnerMetadata, type HostQam, type HostRoutes, type HostRpc, type HostUi, type HostUpdates, INJECTED_HOST_GLOBAL, type MainMenuEntry, OWNER_GLOBAL, OWNER_METADATA_GLOBAL, type PlatformApi, type PlatformAppMeta, type PlatformCollection, type PlatformTab, type PluginDescriptor, type QamPanel, type RoutePatch, type ShelfSource, type ShelvesHostGlobal, type ToastOptions, getInjectedHost, isForcedOwner, readForcedOwner, readOwner };

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/contract/index.ts
-var HOST_API_VERSION = "1.2.0";
+var HOST_API_VERSION = "1.3.0";
 var INJECTED_HOST_GLOBAL = "__SHELVES_HOST__";
 var FORCE_OWNER_GLOBAL = "__SHELVES_FORCE_OWNER__";
 var OWNER_GLOBAL = "__DECK_SHELVES_OWNER__";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deck-shelves/host",
-  "version": "1.3.2",
+  "version": "1.4.1",
   "description": "Deck Shelves host contract — the HostApi types all host adapters and the bundle build against.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -32,12 +32,14 @@
     "lint:fix": "eslint --fix \"src/**/*.ts\"",
     "test": "vitest run",
     "test:watch": "vitest",
+    "api:check": "pnpm run build && node scripts/check-api.mjs check",
+    "api:update": "pnpm run build && node scripts/check-api.mjs update",
     "check": "pnpm run typecheck && pnpm run lint && pnpm run test",
     "dev:check": "pnpm run check",
     "clean": "node scripts/clean.mjs",
-    "release:dry": "pnpm run clean && pnpm run check && pnpm run build && pnpm pack --dry-run",
-    "release:local": "pnpm run clean && pnpm run check && pnpm run build && pnpm pack",
-    "prepublishOnly": "pnpm run clean && pnpm run check && pnpm run build"
+    "release:dry": "pnpm run clean && pnpm run check && pnpm run build && node scripts/check-api.mjs check && pnpm pack --dry-run",
+    "release:local": "pnpm run clean && pnpm run check && pnpm run build && node scripts/check-api.mjs check && pnpm pack",
+    "prepublishOnly": "pnpm run clean && pnpm run check && pnpm run build && node scripts/check-api.mjs check"
   },
   "keywords": [
     "deck-shelves",