@deck-shelves/host 1.3.0 → 1.3.2

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

@@ -2,5 +2,45 @@
 
 // src/contract/index.ts
 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;
+}
+function readOwnerString(name) {
+  try {
+    const v = ownershipScope()[name];
+    return typeof v === "string" && v.length > 0 ? v : null;
+  } catch {
+    return null;
+  }
+}
+function getInjectedHost() {
+  try {
+    return ownershipScope()[INJECTED_HOST_GLOBAL] ?? null;
+  } catch {
+    return null;
+  }
+}
+function readForcedOwner() {
+  return readOwnerString(FORCE_OWNER_GLOBAL);
+}
+function readOwner() {
+  return readOwnerString(OWNER_GLOBAL);
+}
+function isForcedOwner() {
+  return readForcedOwner() != null;
+}
 
+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;
+exports.readOwner = readOwner;

package/dist/index.d.cts

@@ -243,6 +243,31 @@ interface HostApi {
      *  apply an update themselves (see `HostUpdates`). */
     readonly updates?: HostUpdates;
 }
+/** 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). */
+type HostOwnerKind = string;
+/** Renderer global NAMES (augmented on `Window` below). */
+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. */
+declare function readForcedOwner(): string | null;
+/** The renderer's single-owner claim, or null when still unclaimed. */
+declare function readOwner(): string | null;
+/** True when a host stamped a forced-owner claim. Only the injected neutral host
+    does this, so `isForcedOwner() && getInjectedHost()` means "the injected host
+    was forced to own" (cooperative ownership) without naming any host: the loader
+    keeps the renderer + its other plugins, and the bundle binds to the injected
+    host — waiting via {@link getInjectedHost} if the loader booted it first. */
+declare function isForcedOwner(): boolean;
 /** Shape of the runtime global the host installs in the renderer. */
 type ShelvesHostGlobal = HostApi;
 declare global {
@@ -278,7 +303,25 @@ declare global {
          * both vanishing. Unset means no host has claimed the tab.
          */
         __SHELVES_QAM_OWNER__?: string;
+        /**
+         * Forced-owner handshake. A host stamps its own (opaque) owner label here to
+         * claim the renderer even alongside a loader (cooperative ownership): the
+         * loader keeps owning the renderer and its other plugins, but the bundle binds
+         * to the injected host (`__SHELVES_HOST__`) — waiting for it to appear if the
+         * loader booted the bundle first — instead of the loader that launched it.
+         * Only the injected host stamps this, so presence (not the label's value) is
+         * what the bundle keys on.
+         */
+        __SHELVES_FORCE_OWNER__?: HostOwnerKind;
+        /**
+         * The renderer's single-owner claim. The first host/bundle to claim writes
+         * its kind; a second instance reads it and stands down (no home patch, no
+         * 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, HOST_API_VERSION, type HostApi, type HostLifecycle, type HostMainMenu, type HostNotifications, type HostQam, type HostRoutes, type HostRpc, type HostUi, type HostUpdates, type MainMenuEntry, type PlatformApi, type PlatformAppMeta, type PlatformCollection, type PlatformTab, type PluginDescriptor, type QamPanel, type ShelfSource, type ShelvesHostGlobal, type ToastOptions };
+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 };

package/dist/index.d.ts

@@ -243,6 +243,31 @@ interface HostApi {
      *  apply an update themselves (see `HostUpdates`). */
     readonly updates?: HostUpdates;
 }
+/** 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). */
+type HostOwnerKind = string;
+/** Renderer global NAMES (augmented on `Window` below). */
+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. */
+declare function readForcedOwner(): string | null;
+/** The renderer's single-owner claim, or null when still unclaimed. */
+declare function readOwner(): string | null;
+/** True when a host stamped a forced-owner claim. Only the injected neutral host
+    does this, so `isForcedOwner() && getInjectedHost()` means "the injected host
+    was forced to own" (cooperative ownership) without naming any host: the loader
+    keeps the renderer + its other plugins, and the bundle binds to the injected
+    host — waiting via {@link getInjectedHost} if the loader booted it first. */
+declare function isForcedOwner(): boolean;
 /** Shape of the runtime global the host installs in the renderer. */
 type ShelvesHostGlobal = HostApi;
 declare global {
@@ -278,7 +303,25 @@ declare global {
          * both vanishing. Unset means no host has claimed the tab.
          */
         __SHELVES_QAM_OWNER__?: string;
+        /**
+         * Forced-owner handshake. A host stamps its own (opaque) owner label here to
+         * claim the renderer even alongside a loader (cooperative ownership): the
+         * loader keeps owning the renderer and its other plugins, but the bundle binds
+         * to the injected host (`__SHELVES_HOST__`) — waiting for it to appear if the
+         * loader booted the bundle first — instead of the loader that launched it.
+         * Only the injected host stamps this, so presence (not the label's value) is
+         * what the bundle keys on.
+         */
+        __SHELVES_FORCE_OWNER__?: HostOwnerKind;
+        /**
+         * The renderer's single-owner claim. The first host/bundle to claim writes
+         * its kind; a second instance reads it and stands down (no home patch, no
+         * 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, HOST_API_VERSION, type HostApi, type HostLifecycle, type HostMainMenu, type HostNotifications, type HostQam, type HostRoutes, type HostRpc, type HostUi, type HostUpdates, type MainMenuEntry, type PlatformApi, type PlatformAppMeta, type PlatformCollection, type PlatformTab, type PluginDescriptor, type QamPanel, type ShelfSource, type ShelvesHostGlobal, type ToastOptions };
+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 };

package/dist/index.js

@@ -1,4 +1,36 @@
 // src/contract/index.ts
 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;
+}
+function readOwnerString(name) {
+  try {
+    const v = ownershipScope()[name];
+    return typeof v === "string" && v.length > 0 ? v : null;
+  } catch {
+    return null;
+  }
+}
+function getInjectedHost() {
+  try {
+    return ownershipScope()[INJECTED_HOST_GLOBAL] ?? null;
+  } catch {
+    return null;
+  }
+}
+function readForcedOwner() {
+  return readOwnerString(FORCE_OWNER_GLOBAL);
+}
+function readOwner() {
+  return readOwnerString(OWNER_GLOBAL);
+}
+function isForcedOwner() {
+  return readForcedOwner() != null;
+}
 
-export { HOST_API_VERSION };
+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.0",
+  "version": "1.3.2",
   "description": "Deck Shelves host contract — the HostApi types all host adapters and the bundle build against.",
   "type": "module",
   "main": "./dist/index.cjs",