@deck-shelves/host 1.1.0 → 1.1.1

package/README.md

@@ -22,18 +22,15 @@
 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:
+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.
 
-- 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.
-
-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.
 
 It is **not** `@deck-shelves/api` — that package is the public *extension* API

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;
 }
@@ -134,14 +134,46 @@ interface QamPanel {
     render(container: HTMLElement): void | (() => void);
 }
 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?.…`.
  */
 interface HostApi {
     readonly version: typeof HOST_API_VERSION;
@@ -153,6 +185,9 @@ 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;
@@ -162,4 +197,4 @@ declare global {
     }
 }
 
-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;
 }
@@ -134,14 +134,46 @@ interface QamPanel {
     render(container: HTMLElement): void | (() => void);
 }
 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?.…`.
  */
 interface HostApi {
     readonly version: typeof HOST_API_VERSION;
@@ -153,6 +185,9 @@ 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;
@@ -162,4 +197,4 @@ declare global {
     }
 }
 
-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.1.1",
   "description": "Deck Shelves host contract — the HostApi types all host adapters and the bundle build against.",
   "type": "module",
   "main": "./dist/index.cjs",