@deck-shelves/host 1.1.0 → 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)
@@ -22,20 +26,23 @@
 The **host contract** for [Deck Shelves](https://github.com/santojon/Deck-Shelves) —
 the `HostApi` types that both host implementations and the bundle build against.
 
-It is the boundary between a *host* and the Deck Shelves bundle:
-
-- the plugin's **Decky** adapter (`runtime/host/decky.ts`), and
-- the standalone adapter (`runtime/host/standalone.ts`),
-which wraps the loader-injected `window.__SHELVES_HOST__` runtime.
+It is the boundary between a *host* and the Deck Shelves bundle. Each host
+ships its own adapter in the plugin — one file per host,
+`runtime/host/<host>.ts` — and every adapter fulfils this same contract, so
+the bundle's call sites never depend on a specific host and new hosts can be
+added without touching the bundle.
 
-Both fulfil the same contract, so the bundle's call sites never depend on a
-specific host.
-
-> **Types only.** The standalone host *runtime* — the injected
+> **Types only.** A host's *runtime* — for external hosts, the injected
 > `window.__SHELVES_HOST__` that locates Steam's UI components and adds the
-> Quick Access Menu tab — lives in the **Shelves Loader**, not here. This
+> 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

@@ -1,18 +1,19 @@
 /**
- * @deck-shelves/host — HostApi contract (v1.1.0).
+ * @deck-shelves/host — HostApi contract.
  *
- * The single source of truth for the boundary between a *host* (the plugin's
- * host adapter OR the standalone Shelves Loader) and the Deck Shelves bundle.
- * Both host adapters fulfil this shape, so the bundle's call sites depend only
- * on it and never on a specific host's UI library directly.
+ * The single source of truth for the boundary between a *host* and the Deck
+ * Shelves bundle. Every host ships its own adapter (one per host), and every
+ * adapter fulfils this shape, so the bundle's call sites depend only on it
+ * and never on a specific host's UI library directly.
  *
- * Additive-only after 1.0.0. `qam` was added in 1.1.0 as an optional, additive
- * namespace (only the standalone host implements it today).
+ * Additive-only Optional UI-surface capabilities are additive
+ * namespaces a host implements *if it can* and the bundle feature-detects:
+ *   - `qam`      — a Quick Access Menu tab.
+ *   - `mainMenu` — an entry in the Steam Main Menu / left rail.
+ * The contract names no concrete host; a host may implement any, all, or none.
  *
  * Dependency-free by design (mirrors `@deck-shelves/api`): supporting data
- * types are inlined. Members annotated "reconciled in Batch 5" are placeholders
- * that get tightened against the plugin's `src/types.ts` / `runtime/platform.ts`
- * when the contract formally supersedes the two divergent in-repo copies.
+ * types are inlined.
  */
 declare const HOST_API_VERSION: "1.1.0";
 interface PluginDescriptor {
@@ -28,9 +29,9 @@ interface HostLifecycle {
     onMount(cb: () => void): void;
     onUnmount(cb: () => void): void;
 }
-/** Generic RPC channel into the host backend. On the plugin host this routes
- *  through the host's backend bridge; on standalone through the loader's HTTP
- *  RPC server, which proxies to the plugin's Python backend. */
+/** 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
+ *  local HTTP server that proxies to the backend process, …). */
 interface HostRpc {
     call<Req = unknown, Res = unknown>(method: string, args?: Req): Promise<Res>;
 }
@@ -47,10 +48,10 @@ interface HostNotifications {
     toast(opts: ToastOptions): void;
 }
 /**
- * Steam UI primitives the bundle renders with. On the plugin host these come
- * from its UI library; on the standalone host the injected runtime locates the
- * SAME Steam webpack components (via the Shelves Loader's injected runtime) — we do not
- * reimplement the widgets, we find Steam's own and provide fallbacks.
+ * Steam UI primitives the bundle renders with. Every host resolves the SAME
+ * Steam webpack components through its own mechanism (a UI library, an
+ * injected runtime, …) — we do not reimplement the widgets, we find Steam's
+ * own and provide fallbacks.
  *
  * Typed as `unknown` to stay framework-agnostic and dependency-free; the bundle
  * casts each to its React component / handler type at the call site.
@@ -76,7 +77,6 @@ interface HostUi {
     showContextMenu: (menu: unknown) => void;
     showModal: (modal: unknown) => void;
 }
-/** Opaque until reconciled in Batch 5 with the plugin's `ShelfSource` union. */
 type ShelfSource = unknown;
 interface PlatformCollection {
     id: string;
@@ -118,7 +118,7 @@ interface PlatformApi {
     getAppMetaBatch?(appids: number[]): Promise<Map<number, PlatformAppMeta>>;
     navigateToApp(appid: number): void;
     navigateToShelfSource?(source: ShelfSource, title?: string): void;
-    /** Host/OS info folded in from the standalone loader's original contract. */
+    /** Optional host/OS information a host may expose. */
     getOSVersion?(): string;
     checkCompatibility?(): boolean;
 }
@@ -128,20 +128,67 @@ 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 {
-    /** Register a QAM panel; returns an unregister function. */
+    /**
+     * Register a QAM panel; returns an unregister function. A host may keep its
+     * QAM tab visible at all times (a first-class presence), even before any
+     * panel is registered.
+     */
     registerPanel(panel: QamPanel): () => void;
 }
+/**
+ * An entry in the Steam Main Menu (the left navigation rail). Navigational by
+ * nature: it selects a route or runs a callback (unlike a QAM panel, which
+ * renders content in place).
+ */
+interface MainMenuEntry {
+    /** Stable id — re-registering with the same id replaces the entry. */
+    id: string;
+    /** Label / accessible name. */
+    title: string;
+    /** Inline SVG markup (or a `data:` URI) used as the icon. */
+    icon: string;
+    /** Navigate to this registered route on selection… */
+    route?: string;
+    /** …or run this callback (exactly one of `route` / `onSelect` is required). */
+    onSelect?(): void;
+}
+interface HostMainMenu {
+    /**
+     * Register a Main Menu entry; returns an unregister function. Unlike the QAM
+     * tab, a host MUST NOT inject or show a Main Menu entry unless there is
+     * content to show — i.e. only while at least one entry is registered. No
+     * entries → nothing added to the Main Menu.
+     */
+    registerEntry(entry: MainMenuEntry): () => void;
+}
 /**
  * What the host process provides to the Deck Shelves bundle. The bundle receives
  * this at startup as `window.__SHELVES_HOST__` and uses it to register itself,
- * invoke host methods, add routes, render Steam-native UI, and (on the
- * standalone host) add Quick Access Menu panels.
+ * invoke host methods, add routes, render Steam-native UI, and — where the host
+ * 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;
@@ -153,13 +200,34 @@ interface HostApi {
     readonly platform: PlatformApi;
     /** Optional so hosts without a QAM surface still satisfy the shape. */
     readonly qam?: HostQam;
+    /** Optional Main Menu (left-rail) surface; present only on hosts that
+     *  support it. Injected/shown only while it has content (see `HostMainMenu`). */
+    readonly mainMenu?: HostMainMenu;
 }
 /** Shape of the runtime global the host installs in the renderer. */
 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[];
     }
 }
 
-export { type Disposable, HOST_API_VERSION, type HostApi, type HostLifecycle, type HostNotifications, type HostQam, type HostRoutes, type HostRpc, type HostUi, type PlatformApi, type PlatformAppMeta, type PlatformCollection, type PlatformTab, type PluginDescriptor, type QamPanel, type ShelfSource, type ShelvesHostGlobal, type ToastOptions };
+export { type Disposable, HOST_API_VERSION, type HostApi, type HostLifecycle, type HostMainMenu, type HostNotifications, type HostQam, type HostRoutes, type HostRpc, type HostUi, type MainMenuEntry, type PlatformApi, type PlatformAppMeta, type PlatformCollection, type PlatformTab, type PluginDescriptor, type QamPanel, type ShelfSource, type ShelvesHostGlobal, type ToastOptions };

package/dist/index.d.ts

@@ -1,18 +1,19 @@
 /**
- * @deck-shelves/host — HostApi contract (v1.1.0).
+ * @deck-shelves/host — HostApi contract.
  *
- * The single source of truth for the boundary between a *host* (the plugin's
- * host adapter OR the standalone Shelves Loader) and the Deck Shelves bundle.
- * Both host adapters fulfil this shape, so the bundle's call sites depend only
- * on it and never on a specific host's UI library directly.
+ * The single source of truth for the boundary between a *host* and the Deck
+ * Shelves bundle. Every host ships its own adapter (one per host), and every
+ * adapter fulfils this shape, so the bundle's call sites depend only on it
+ * and never on a specific host's UI library directly.
  *
- * Additive-only after 1.0.0. `qam` was added in 1.1.0 as an optional, additive
- * namespace (only the standalone host implements it today).
+ * Additive-only Optional UI-surface capabilities are additive
+ * namespaces a host implements *if it can* and the bundle feature-detects:
+ *   - `qam`      — a Quick Access Menu tab.
+ *   - `mainMenu` — an entry in the Steam Main Menu / left rail.
+ * The contract names no concrete host; a host may implement any, all, or none.
  *
  * Dependency-free by design (mirrors `@deck-shelves/api`): supporting data
- * types are inlined. Members annotated "reconciled in Batch 5" are placeholders
- * that get tightened against the plugin's `src/types.ts` / `runtime/platform.ts`
- * when the contract formally supersedes the two divergent in-repo copies.
+ * types are inlined.
  */
 declare const HOST_API_VERSION: "1.1.0";
 interface PluginDescriptor {
@@ -28,9 +29,9 @@ interface HostLifecycle {
     onMount(cb: () => void): void;
     onUnmount(cb: () => void): void;
 }
-/** Generic RPC channel into the host backend. On the plugin host this routes
- *  through the host's backend bridge; on standalone through the loader's HTTP
- *  RPC server, which proxies to the plugin's Python backend. */
+/** 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
+ *  local HTTP server that proxies to the backend process, …). */
 interface HostRpc {
     call<Req = unknown, Res = unknown>(method: string, args?: Req): Promise<Res>;
 }
@@ -47,10 +48,10 @@ interface HostNotifications {
     toast(opts: ToastOptions): void;
 }
 /**
- * Steam UI primitives the bundle renders with. On the plugin host these come
- * from its UI library; on the standalone host the injected runtime locates the
- * SAME Steam webpack components (via the Shelves Loader's injected runtime) — we do not
- * reimplement the widgets, we find Steam's own and provide fallbacks.
+ * Steam UI primitives the bundle renders with. Every host resolves the SAME
+ * Steam webpack components through its own mechanism (a UI library, an
+ * injected runtime, …) — we do not reimplement the widgets, we find Steam's
+ * own and provide fallbacks.
  *
  * Typed as `unknown` to stay framework-agnostic and dependency-free; the bundle
  * casts each to its React component / handler type at the call site.
@@ -76,7 +77,6 @@ interface HostUi {
     showContextMenu: (menu: unknown) => void;
     showModal: (modal: unknown) => void;
 }
-/** Opaque until reconciled in Batch 5 with the plugin's `ShelfSource` union. */
 type ShelfSource = unknown;
 interface PlatformCollection {
     id: string;
@@ -118,7 +118,7 @@ interface PlatformApi {
     getAppMetaBatch?(appids: number[]): Promise<Map<number, PlatformAppMeta>>;
     navigateToApp(appid: number): void;
     navigateToShelfSource?(source: ShelfSource, title?: string): void;
-    /** Host/OS info folded in from the standalone loader's original contract. */
+    /** Optional host/OS information a host may expose. */
     getOSVersion?(): string;
     checkCompatibility?(): boolean;
 }
@@ -128,20 +128,67 @@ 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 {
-    /** Register a QAM panel; returns an unregister function. */
+    /**
+     * Register a QAM panel; returns an unregister function. A host may keep its
+     * QAM tab visible at all times (a first-class presence), even before any
+     * panel is registered.
+     */
     registerPanel(panel: QamPanel): () => void;
 }
+/**
+ * An entry in the Steam Main Menu (the left navigation rail). Navigational by
+ * nature: it selects a route or runs a callback (unlike a QAM panel, which
+ * renders content in place).
+ */
+interface MainMenuEntry {
+    /** Stable id — re-registering with the same id replaces the entry. */
+    id: string;
+    /** Label / accessible name. */
+    title: string;
+    /** Inline SVG markup (or a `data:` URI) used as the icon. */
+    icon: string;
+    /** Navigate to this registered route on selection… */
+    route?: string;
+    /** …or run this callback (exactly one of `route` / `onSelect` is required). */
+    onSelect?(): void;
+}
+interface HostMainMenu {
+    /**
+     * Register a Main Menu entry; returns an unregister function. Unlike the QAM
+     * tab, a host MUST NOT inject or show a Main Menu entry unless there is
+     * content to show — i.e. only while at least one entry is registered. No
+     * entries → nothing added to the Main Menu.
+     */
+    registerEntry(entry: MainMenuEntry): () => void;
+}
 /**
  * What the host process provides to the Deck Shelves bundle. The bundle receives
  * this at startup as `window.__SHELVES_HOST__` and uses it to register itself,
- * invoke host methods, add routes, render Steam-native UI, and (on the
- * standalone host) add Quick Access Menu panels.
+ * invoke host methods, add routes, render Steam-native UI, and — where the host
+ * 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;
@@ -153,13 +200,34 @@ interface HostApi {
     readonly platform: PlatformApi;
     /** Optional so hosts without a QAM surface still satisfy the shape. */
     readonly qam?: HostQam;
+    /** Optional Main Menu (left-rail) surface; present only on hosts that
+     *  support it. Injected/shown only while it has content (see `HostMainMenu`). */
+    readonly mainMenu?: HostMainMenu;
 }
 /** Shape of the runtime global the host installs in the renderer. */
 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[];
     }
 }
 
-export { type Disposable, HOST_API_VERSION, type HostApi, type HostLifecycle, type HostNotifications, type HostQam, type HostRoutes, type HostRpc, type HostUi, type PlatformApi, type PlatformAppMeta, type PlatformCollection, type PlatformTab, type PluginDescriptor, type QamPanel, type ShelfSource, type ShelvesHostGlobal, type ToastOptions };
+export { type Disposable, HOST_API_VERSION, type HostApi, type HostLifecycle, type HostMainMenu, type HostNotifications, type HostQam, type HostRoutes, type HostRpc, type HostUi, type MainMenuEntry, type PlatformApi, type PlatformAppMeta, type PlatformCollection, type PlatformTab, type PluginDescriptor, type QamPanel, type ShelfSource, type ShelvesHostGlobal, type ToastOptions };

package/package.json

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