@deck-shelves/host 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonathan Santos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# @deck-shelves/host
+
+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.
+
+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
+> `window.__SHELVES_HOST__` that locates Steam's UI components and adds the
+> Quick Access Menu tab — lives in the **Shelves Loader**, 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
+consumed by third-party plugins (`window.deckShelves`). This one is the
+host↔bundle contract, a different audience.
+
+## What's inside
+
+| Path | What it is |
+|---|---|
+| `src/contract/` | **`HostApi` types** (`HOST_API_VERSION`, `lifecycle`, `rpc`, `ui`, `routes`, `notifications`, `platform`, optional `qam`). The single source of truth both hosts and the bundle build against. |
+
+## Usage
+
+```ts
+import { HOST_API_VERSION, type HostApi } from "@deck-shelves/host";
+```
+
+## Build
+
+```
+pnpm install
+pnpm build      # tsup → dist/index.{js,cjs,d.ts}
+pnpm check      # typecheck + lint + test
+```
+
+## License
+
+[MIT](LICENSE) © [santojon](https://github.com/santojon)

package/dist/index.cjs

@@ -0,0 +1,6 @@
+'use strict';
+
+// src/contract/index.ts
+var HOST_API_VERSION = "1.1.0";
+
+exports.HOST_API_VERSION = HOST_API_VERSION;

package/dist/index.d.cts

@@ -0,0 +1,165 @@
+/**
+ * @deck-shelves/host — HostApi contract (v1.1.0).
+ *
+ * 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.
+ *
+ * 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).
+ *
+ * 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.
+ */
+declare const HOST_API_VERSION: "1.1.0";
+interface PluginDescriptor {
+    name: string;
+    version: string;
+}
+interface Disposable {
+    dispose(): void;
+}
+interface HostLifecycle {
+    /** Call once at bundle mount. Returns a disposer that unregisters. */
+    register(plugin: PluginDescriptor): Disposable;
+    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. */
+interface HostRpc {
+    call<Req = unknown, Res = unknown>(method: string, args?: Req): Promise<Res>;
+}
+interface HostRoutes {
+    /** Register a full-page route; returns a disposer that removes it. */
+    register(path: string, component: () => unknown): Disposable;
+}
+interface ToastOptions {
+    title?: string;
+    body: string;
+    durationMs?: number;
+}
+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.
+ *
+ * Typed as `unknown` to stay framework-agnostic and dependency-free; the bundle
+ * casts each to its React component / handler type at the call site.
+ */
+interface HostUi {
+    ConfirmModal: unknown;
+    DialogBody: unknown;
+    DialogButton: unknown;
+    DialogControlsSection: unknown;
+    Dropdown: unknown;
+    DropdownItem: unknown;
+    Field: unknown;
+    Focusable: unknown;
+    GamepadButton: unknown;
+    Menu: unknown;
+    MenuItem: unknown;
+    Navigation: unknown;
+    SliderField: unknown;
+    Spinner: unknown;
+    Tabs: unknown;
+    TextField: unknown;
+    ToggleField: unknown;
+    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;
+    name: string;
+}
+interface PlatformTab {
+    id: string;
+    name: string;
+    source?: ShelfSource;
+}
+interface PlatformAppMeta {
+    appid: number;
+    name: string;
+    heroUrl?: string;
+    portraitUrl?: string;
+    logoUrl?: string;
+    iconUrl?: string;
+    installed?: boolean;
+    isSteam?: boolean;
+    deckCompatCategory?: number;
+    playtimeMinutes?: number;
+    addedTimestamp?: number;
+    updatePending?: boolean;
+    description?: string;
+    fullDescription?: string;
+    releaseTimestamp?: number;
+    metacriticScore?: number;
+    diskUsageBytes?: number;
+}
+interface PlatformApi {
+    listCollections(): Promise<PlatformCollection[]>;
+    listLibraryTabs(): Promise<PlatformTab[]>;
+    resolveShelfAppIds(source: ShelfSource, limit: number, sort?: string | string[], shelfId?: string, sortReverse?: boolean | boolean[], options?: {
+        hiddenAppIds?: number[];
+        dedupeByName?: boolean;
+    }): Promise<number[]>;
+    getAppName(appid: number): Promise<string>;
+    getAppMeta(appid: number): Promise<PlatformAppMeta>;
+    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. */
+    getOSVersion?(): string;
+    checkCompatibility?(): boolean;
+}
+/** A dedicated panel + icon shown in the Steam Quick Access Menu. */
+interface QamPanel {
+    /** Stable id — re-registering with the same id replaces the panel. */
+    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);
+}
+interface HostQam {
+    /** Register a QAM panel; returns an unregister function. */
+    registerPanel(panel: QamPanel): () => 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.
+ */
+interface HostApi {
+    readonly version: typeof HOST_API_VERSION;
+    readonly lifecycle: HostLifecycle;
+    readonly rpc: HostRpc;
+    readonly ui: HostUi;
+    readonly routes: HostRoutes;
+    readonly notifications?: HostNotifications;
+    readonly platform: PlatformApi;
+    /** Optional so hosts without a QAM surface still satisfy the shape. */
+    readonly qam?: HostQam;
+}
+/** Shape of the runtime global the host installs in the renderer. */
+type ShelvesHostGlobal = HostApi;
+declare global {
+    interface Window {
+        __SHELVES_HOST__?: ShelvesHostGlobal;
+    }
+}
+
+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 };

package/dist/index.d.ts

@@ -0,0 +1,165 @@
+/**
+ * @deck-shelves/host — HostApi contract (v1.1.0).
+ *
+ * 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.
+ *
+ * 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).
+ *
+ * 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.
+ */
+declare const HOST_API_VERSION: "1.1.0";
+interface PluginDescriptor {
+    name: string;
+    version: string;
+}
+interface Disposable {
+    dispose(): void;
+}
+interface HostLifecycle {
+    /** Call once at bundle mount. Returns a disposer that unregisters. */
+    register(plugin: PluginDescriptor): Disposable;
+    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. */
+interface HostRpc {
+    call<Req = unknown, Res = unknown>(method: string, args?: Req): Promise<Res>;
+}
+interface HostRoutes {
+    /** Register a full-page route; returns a disposer that removes it. */
+    register(path: string, component: () => unknown): Disposable;
+}
+interface ToastOptions {
+    title?: string;
+    body: string;
+    durationMs?: number;
+}
+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.
+ *
+ * Typed as `unknown` to stay framework-agnostic and dependency-free; the bundle
+ * casts each to its React component / handler type at the call site.
+ */
+interface HostUi {
+    ConfirmModal: unknown;
+    DialogBody: unknown;
+    DialogButton: unknown;
+    DialogControlsSection: unknown;
+    Dropdown: unknown;
+    DropdownItem: unknown;
+    Field: unknown;
+    Focusable: unknown;
+    GamepadButton: unknown;
+    Menu: unknown;
+    MenuItem: unknown;
+    Navigation: unknown;
+    SliderField: unknown;
+    Spinner: unknown;
+    Tabs: unknown;
+    TextField: unknown;
+    ToggleField: unknown;
+    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;
+    name: string;
+}
+interface PlatformTab {
+    id: string;
+    name: string;
+    source?: ShelfSource;
+}
+interface PlatformAppMeta {
+    appid: number;
+    name: string;
+    heroUrl?: string;
+    portraitUrl?: string;
+    logoUrl?: string;
+    iconUrl?: string;
+    installed?: boolean;
+    isSteam?: boolean;
+    deckCompatCategory?: number;
+    playtimeMinutes?: number;
+    addedTimestamp?: number;
+    updatePending?: boolean;
+    description?: string;
+    fullDescription?: string;
+    releaseTimestamp?: number;
+    metacriticScore?: number;
+    diskUsageBytes?: number;
+}
+interface PlatformApi {
+    listCollections(): Promise<PlatformCollection[]>;
+    listLibraryTabs(): Promise<PlatformTab[]>;
+    resolveShelfAppIds(source: ShelfSource, limit: number, sort?: string | string[], shelfId?: string, sortReverse?: boolean | boolean[], options?: {
+        hiddenAppIds?: number[];
+        dedupeByName?: boolean;
+    }): Promise<number[]>;
+    getAppName(appid: number): Promise<string>;
+    getAppMeta(appid: number): Promise<PlatformAppMeta>;
+    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. */
+    getOSVersion?(): string;
+    checkCompatibility?(): boolean;
+}
+/** A dedicated panel + icon shown in the Steam Quick Access Menu. */
+interface QamPanel {
+    /** Stable id — re-registering with the same id replaces the panel. */
+    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);
+}
+interface HostQam {
+    /** Register a QAM panel; returns an unregister function. */
+    registerPanel(panel: QamPanel): () => 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.
+ */
+interface HostApi {
+    readonly version: typeof HOST_API_VERSION;
+    readonly lifecycle: HostLifecycle;
+    readonly rpc: HostRpc;
+    readonly ui: HostUi;
+    readonly routes: HostRoutes;
+    readonly notifications?: HostNotifications;
+    readonly platform: PlatformApi;
+    /** Optional so hosts without a QAM surface still satisfy the shape. */
+    readonly qam?: HostQam;
+}
+/** Shape of the runtime global the host installs in the renderer. */
+type ShelvesHostGlobal = HostApi;
+declare global {
+    interface Window {
+        __SHELVES_HOST__?: ShelvesHostGlobal;
+    }
+}
+
+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 };

package/dist/index.js

@@ -0,0 +1,4 @@
+// src/contract/index.ts
+var HOST_API_VERSION = "1.1.0";
+
+export { HOST_API_VERSION };

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@deck-shelves/host",
+  "version": "0.1.0",
+  "description": "Deck Shelves host contract — the HostApi types all host adapters and the bundle build against.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "upgrade": "node scripts/upgrade-pnpm.cjs && pnpm --version",
+    "update": "pnpm update --latest && pnpm install",
+    "update:check": "pnpm outdated || true",
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint \"src/**/*.ts\"",
+    "lint:fix": "eslint --fix \"src/**/*.ts\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "check": "pnpm run typecheck && pnpm run lint && pnpm run test",
+    "dev:check": "pnpm run check",
+    "clean": "node scripts/clean.mjs",
+    "release:dry": "pnpm run clean && pnpm run check && pnpm run build && pnpm pack --dry-run",
+    "release:local": "pnpm run clean && pnpm run check && pnpm run build && pnpm pack",
+    "prepublishOnly": "pnpm run clean && pnpm run check && pnpm run build"
+  },
+  "keywords": [
+    "deck-shelves",
+    "steam-deck",
+    "steam",
+    "host"
+  ],
+  "author": "Jonathan Santos",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/santojon/Deck-Shelves-HOST.git"
+  },
+  "bugs": {
+    "url": "https://github.com/santojon/Deck-Shelves-HOST/issues"
+  },
+  "homepage": "https://github.com/santojon/Deck-Shelves-HOST#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ],
+    "overrides": {
+      "esbuild": "^0.25.0",
+      "vite": "^6.4.2",
+      "form-data": "^4.0.6"
+    }
+  },
+  "devDependencies": {
+    "@typescript-eslint/parser": "^8.61.1",
+    "eslint": "^9.39.4",
+    "jsdom": "^25.0.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.6"
+  },
+  "packageManager": "pnpm@10.33.0"
+}