@deck-shelves/host 1.3.1 → 1.4.0

package/README.md

@@ -11,7 +11,7 @@
 [![npm version](https://img.shields.io/npm/v/@deck-shelves/host?logo=npm&color=cb3837)](https://www.npmjs.com/package/@deck-shelves/host)
 [![npm downloads](https://img.shields.io/npm/dt/@deck-shelves/host?label=downloads&logo=npm&color=blue)](https://www.npmjs.com/package/@deck-shelves/host)
 [![npm monthly](https://img.shields.io/npm/dm/@deck-shelves/host?label=monthly&logo=npm&color=blue)](https://www.npmjs.com/package/@deck-shelves/host)
-[![Tests](https://img.shields.io/badge/tests-7%20passed-brightgreen?logo=vitest&logoColor=white)](src/contract/index.test.ts)
+[![Tests](https://img.shields.io/badge/tests-8%20passed-brightgreen?logo=vitest&logoColor=white)](src/contract/index.test.ts)
 [![Types](https://img.shields.io/npm/types/@deck-shelves/host?logo=typescript&logoColor=white)](src/contract/index.ts)
 [![Bundle size](https://img.shields.io/bundlephobia/minzip/@deck-shelves/host?label=minzip&color=blue)](https://bundlephobia.com/package/@deck-shelves/host)
 [![License](https://img.shields.io/npm/l/@deck-shelves/host?color=blue)](LICENSE)

package/dist/index.cjs

@@ -5,6 +5,7 @@ var HOST_API_VERSION = "1.2.0";
 var INJECTED_HOST_GLOBAL = "__SHELVES_HOST__";
 var FORCE_OWNER_GLOBAL = "__SHELVES_FORCE_OWNER__";
 var OWNER_GLOBAL = "__DECK_SHELVES_OWNER__";
+var OWNER_METADATA_GLOBAL = "__DECK_SHELVES_OWNER_META__";
 function ownershipScope() {
   const g = globalThis;
   return g.window ?? g;
@@ -38,6 +39,7 @@ exports.FORCE_OWNER_GLOBAL = FORCE_OWNER_GLOBAL;
 exports.HOST_API_VERSION = HOST_API_VERSION;
 exports.INJECTED_HOST_GLOBAL = INJECTED_HOST_GLOBAL;
 exports.OWNER_GLOBAL = OWNER_GLOBAL;
+exports.OWNER_METADATA_GLOBAL = OWNER_METADATA_GLOBAL;
 exports.getInjectedHost = getInjectedHost;
 exports.isForcedOwner = isForcedOwner;
 exports.readForcedOwner = readForcedOwner;

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). */
@@ -250,6 +274,12 @@ type HostOwnerKind = string;
 declare const INJECTED_HOST_GLOBAL: "__SHELVES_HOST__";
 declare const FORCE_OWNER_GLOBAL: "__SHELVES_FORCE_OWNER__";
 declare const OWNER_GLOBAL: "__DECK_SHELVES_OWNER__";
+declare const OWNER_METADATA_GLOBAL: "__DECK_SHELVES_OWNER_META__";
+/** Version identity published by the bundle that currently owns the renderer. */
+interface HostOwnerMetadata {
+    host: HostOwnerKind;
+    dsVersion: string;
+}
 /** The injected host runtime, or null when no neutral host is present. */
 declare function getInjectedHost(): ShelvesHostGlobal | null;
 /** The forced-owner label a host stamped, or null when none. */
@@ -313,7 +343,9 @@ declare global {
          * settings writes) so there is exactly one injector and one writer.
          */
         __DECK_SHELVES_OWNER__?: HostOwnerKind;
+        /** Version identity of the bundle that currently owns the renderer. */
+        __DECK_SHELVES_OWNER_META__?: HostOwnerMetadata;
     }
 }
 
-export { type Disposable, FORCE_OWNER_GLOBAL, HOST_API_VERSION, type HostApi, type HostLifecycle, type HostMainMenu, type HostNotifications, type HostOwnerKind, type HostQam, type HostRoutes, type HostRpc, type HostUi, type HostUpdates, INJECTED_HOST_GLOBAL, type MainMenuEntry, OWNER_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). */
@@ -250,6 +274,12 @@ type HostOwnerKind = string;
 declare const INJECTED_HOST_GLOBAL: "__SHELVES_HOST__";
 declare const FORCE_OWNER_GLOBAL: "__SHELVES_FORCE_OWNER__";
 declare const OWNER_GLOBAL: "__DECK_SHELVES_OWNER__";
+declare const OWNER_METADATA_GLOBAL: "__DECK_SHELVES_OWNER_META__";
+/** Version identity published by the bundle that currently owns the renderer. */
+interface HostOwnerMetadata {
+    host: HostOwnerKind;
+    dsVersion: string;
+}
 /** The injected host runtime, or null when no neutral host is present. */
 declare function getInjectedHost(): ShelvesHostGlobal | null;
 /** The forced-owner label a host stamped, or null when none. */
@@ -313,7 +343,9 @@ declare global {
          * settings writes) so there is exactly one injector and one writer.
          */
         __DECK_SHELVES_OWNER__?: HostOwnerKind;
+        /** Version identity of the bundle that currently owns the renderer. */
+        __DECK_SHELVES_OWNER_META__?: HostOwnerMetadata;
     }
 }
 
-export { type Disposable, FORCE_OWNER_GLOBAL, HOST_API_VERSION, type HostApi, type HostLifecycle, type HostMainMenu, type HostNotifications, type HostOwnerKind, type HostQam, type HostRoutes, type HostRpc, type HostUi, type HostUpdates, INJECTED_HOST_GLOBAL, type MainMenuEntry, OWNER_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.js

@@ -3,6 +3,7 @@ var HOST_API_VERSION = "1.2.0";
 var INJECTED_HOST_GLOBAL = "__SHELVES_HOST__";
 var FORCE_OWNER_GLOBAL = "__SHELVES_FORCE_OWNER__";
 var OWNER_GLOBAL = "__DECK_SHELVES_OWNER__";
+var OWNER_METADATA_GLOBAL = "__DECK_SHELVES_OWNER_META__";
 function ownershipScope() {
   const g = globalThis;
   return g.window ?? g;
@@ -32,4 +33,4 @@ function isForcedOwner() {
   return readForcedOwner() != null;
 }
 
-export { FORCE_OWNER_GLOBAL, HOST_API_VERSION, INJECTED_HOST_GLOBAL, OWNER_GLOBAL, getInjectedHost, isForcedOwner, readForcedOwner, readOwner };
+export { FORCE_OWNER_GLOBAL, HOST_API_VERSION, INJECTED_HOST_GLOBAL, OWNER_GLOBAL, OWNER_METADATA_GLOBAL, getInjectedHost, isForcedOwner, readForcedOwner, readOwner };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deck-shelves/host",
-  "version": "1.3.1",
+  "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",