@deck-shelves/host 1.3.2 → 1.4.0

package/dist/index.d.cts

@@ -38,6 +38,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
@@ -242,6 +250,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 +348,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 ShelfSource, type ShelvesHostGlobal, type ToastOptions, getInjectedHost, isForcedOwner, readForcedOwner, readOwner };

package/dist/index.d.ts

@@ -38,6 +38,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
@@ -242,6 +250,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 +348,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 ShelfSource, type ShelvesHostGlobal, type ToastOptions, getInjectedHost, isForcedOwner, readForcedOwner, readOwner };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deck-shelves/host",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "description": "Deck Shelves host contract — the HostApi types all host adapters and the bundle build against.",
   "type": "module",
   "main": "./dist/index.cjs",