@deck-shelves/host 1.1.1 → 1.2.0

package/README.md

@@ -2,6 +2,10 @@
 
 <div align="center">
 
+<p>
+  <img src="assets/logo.svg" alt="@deck-shelves/host" width="352">
+</p>
+
 [![CI](https://github.com/santojon/Deck-Shelves-HOST/actions/workflows/ci.yml/badge.svg)](https://github.com/santojon/Deck-Shelves-HOST/actions/workflows/ci.yml)
 [![Release](https://github.com/santojon/Deck-Shelves-HOST/actions/workflows/release.yml/badge.svg)](https://github.com/santojon/Deck-Shelves-HOST/actions/workflows/release.yml)
 [![npm version](https://img.shields.io/npm/v/@deck-shelves/host?logo=npm&color=cb3837)](https://www.npmjs.com/package/@deck-shelves/host)
@@ -33,6 +37,12 @@ added without touching the bundle.
 > Quick Access Menu tab — lives in that host's own project, not here. This
 > package is just the interface both sides agree on.
 
+> **Coexistence.** A host with a native QAM tab may also expose its panel
+> registration on `window.__SHELVES_QAM__` (a `HostQam`), independently of the
+> full `HostApi` — so a bundle can populate that host's tab even when *another*
+> host owns the home (and `__SHELVES_HOST__` is left unset). Both globals are
+> declared in the contract.
+
 It is **not** `@deck-shelves/api` — that package is the public *extension* API
 consumed by third-party plugins (`window.deckShelves`). This one is the
 host↔bundle contract, a different audience.

package/dist/index.d.cts

@@ -128,10 +128,20 @@ interface QamPanel {
     id: string;
     /** Label / accessible name. */
     title: string;
-    /** Inline SVG markup (or a `data:` URI) used as the icon. */
-    icon: string;
-    /** Render into the host-owned container; return an optional cleanup fn. */
-    render(container: HTMLElement): void | (() => void);
+    /** Inline SVG markup (or a `data:` URI) used as the icon. Optional: a host
+     *  with a first-class tab (a permanent presence with its own icon) falls back
+     *  to that icon when omitted. */
+    icon?: string;
+    /** Render into the host-owned container; return an optional cleanup fn.
+     *  Framework-agnostic — the way any host can accept a panel. Provide exactly
+     *  one of `render` / `content`. */
+    render?(container: HTMLElement): void | (() => void);
+    /** …or a React node (or a zero-arg factory returning one) that a React-based
+     *  host renders in its OWN React tree — no nested root, so the bundle's context
+     *  providers reach the panel. Typed `unknown` to keep the contract
+     *  dependency-free (cast at the call site, as with `HostUi`). Provide exactly
+     *  one of `render` / `content`. */
+    content?: unknown;
 }
 interface HostQam {
     /**
@@ -174,6 +184,11 @@ interface HostMainMenu {
  * supports them — add optional surfaces (a Quick Access Menu tab, a Main Menu
  * entry). Optional capabilities are feature-detected: `host.qam?.…`,
  * `host.mainMenu?.…`.
+ *
+ * In *coexistence* (another loader owns the home) a host leaves `__SHELVES_HOST__`
+ * unset so it does not disturb host selection, yet MAY still surface its own QAM
+ * tab: the bundle registers into it through the host-selection-neutral
+ * `window.__SHELVES_QAM__` (see the `Window` augmentation below).
  */
 interface HostApi {
     readonly version: typeof HOST_API_VERSION;
@@ -194,6 +209,24 @@ type ShelvesHostGlobal = HostApi;
 declare global {
     interface Window {
         __SHELVES_HOST__?: ShelvesHostGlobal;
+        /**
+         * A host's QAM registration surface, exposed independently of the full
+         * `HostApi`. A host with a native QAM tab installs this even when it is NOT
+         * the bundle's selected host — i.e. in *coexistence*, where another loader
+         * owns the home and `__SHELVES_HOST__` is intentionally left unset so host
+         * selection is not disturbed. A bundle may register a panel here to populate
+         * that host's tab regardless of which host it selected; the surface takes no
+         * part in host selection. When the same host also owns the home this is the
+         * very same object as `__SHELVES_HOST__.qam`.
+         */
+        __SHELVES_QAM__?: HostQam;
+        /**
+         * Panels a bundle registered before `__SHELVES_QAM__` existed. Registration
+         * is order-independent: a bundle that boots first may push its panels here,
+         * and the host drains and clears this array the moment it installs
+         * `__SHELVES_QAM__`. Equivalent to calling `registerPanel` for each.
+         */
+        __SHELVES_QAM_PENDING__?: QamPanel[];
     }
 }
 

package/dist/index.d.ts

@@ -128,10 +128,20 @@ interface QamPanel {
     id: string;
     /** Label / accessible name. */
     title: string;
-    /** Inline SVG markup (or a `data:` URI) used as the icon. */
-    icon: string;
-    /** Render into the host-owned container; return an optional cleanup fn. */
-    render(container: HTMLElement): void | (() => void);
+    /** Inline SVG markup (or a `data:` URI) used as the icon. Optional: a host
+     *  with a first-class tab (a permanent presence with its own icon) falls back
+     *  to that icon when omitted. */
+    icon?: string;
+    /** Render into the host-owned container; return an optional cleanup fn.
+     *  Framework-agnostic — the way any host can accept a panel. Provide exactly
+     *  one of `render` / `content`. */
+    render?(container: HTMLElement): void | (() => void);
+    /** …or a React node (or a zero-arg factory returning one) that a React-based
+     *  host renders in its OWN React tree — no nested root, so the bundle's context
+     *  providers reach the panel. Typed `unknown` to keep the contract
+     *  dependency-free (cast at the call site, as with `HostUi`). Provide exactly
+     *  one of `render` / `content`. */
+    content?: unknown;
 }
 interface HostQam {
     /**
@@ -174,6 +184,11 @@ interface HostMainMenu {
  * supports them — add optional surfaces (a Quick Access Menu tab, a Main Menu
  * entry). Optional capabilities are feature-detected: `host.qam?.…`,
  * `host.mainMenu?.…`.
+ *
+ * In *coexistence* (another loader owns the home) a host leaves `__SHELVES_HOST__`
+ * unset so it does not disturb host selection, yet MAY still surface its own QAM
+ * tab: the bundle registers into it through the host-selection-neutral
+ * `window.__SHELVES_QAM__` (see the `Window` augmentation below).
  */
 interface HostApi {
     readonly version: typeof HOST_API_VERSION;
@@ -194,6 +209,24 @@ type ShelvesHostGlobal = HostApi;
 declare global {
     interface Window {
         __SHELVES_HOST__?: ShelvesHostGlobal;
+        /**
+         * A host's QAM registration surface, exposed independently of the full
+         * `HostApi`. A host with a native QAM tab installs this even when it is NOT
+         * the bundle's selected host — i.e. in *coexistence*, where another loader
+         * owns the home and `__SHELVES_HOST__` is intentionally left unset so host
+         * selection is not disturbed. A bundle may register a panel here to populate
+         * that host's tab regardless of which host it selected; the surface takes no
+         * part in host selection. When the same host also owns the home this is the
+         * very same object as `__SHELVES_HOST__.qam`.
+         */
+        __SHELVES_QAM__?: HostQam;
+        /**
+         * Panels a bundle registered before `__SHELVES_QAM__` existed. Registration
+         * is order-independent: a bundle that boots first may push its panels here,
+         * and the host drains and clears this array the moment it installs
+         * `__SHELVES_QAM__`. Equivalent to calling `registerPanel` for each.
+         */
+        __SHELVES_QAM_PENDING__?: QamPanel[];
     }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deck-shelves/host",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Deck Shelves host contract — the HostApi types all host adapters and the bundle build against.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -66,16 +66,21 @@
     "overrides": {
       "esbuild": "^0.25.0",
       "vite": "^6.4.2",
-      "form-data": "^4.0.6"
+      "form-data": "^4.0.6",
+      "brace-expansion@1": "^1.1.17",
+      "brace-expansion@5": "^5.0.9",
+      "js-yaml@4": "^4.3.1",
+      "nanoid@3": "^3.3.18",
+      "postcss@8": "^8.5.23"
     }
   },
   "devDependencies": {
-    "@typescript-eslint/parser": "^8.61.1",
-    "eslint": "^9.39.4",
+    "@typescript-eslint/parser": "^8.67.0",
+    "eslint": "^9.39.5",
     "jsdom": "^25.0.1",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
-    "vitest": "^3.2.6"
+    "vitest": "^3.2.7"
   },
   "packageManager": "pnpm@10.33.0"
 }