@zhin.js/client 1.1.5 → 1.1.6

package/README.md

@@ -17,24 +17,22 @@ Peer：`react >= 18`（`createPluginRegisterHostApi` 需要 React 引用）。
 | 导出 | 用途 |
 |------|------|
 | `loadConsoleEntries` | 拉 `GET /entries`、动态 import 各 entry、调用 `register(hostApi)` |
-| `createPluginRegisterHostApi` | 由壳层的 `React` / `addRoute` / `addTool` 构造 `PluginRegisterHostApi` |
+| `createConsoleClient` | 创建一个拥有路由、工具、运行时环境与网络连接的 Console 实例 |
+| `ConsoleClientProvider` | 将 Console 实例提供给 `useConsoleTransport` 等 React hooks |
 | `apiFetch` | 相对 Host API Base 的 `fetch`，自动附加 `Authorization: Bearer` |
 | `getApiBase` / `getToken` | 读取登录页写入 `localStorage` 的 API Base 与 Token |
-| `app` | 路由与工具注册单例（`addRoute`、`addTool` 等） |
-| `configureConsole` / `getRuntimeEnv` | 运行时环境（development / production） |
 | `createRegistryStore` / `useRegistry` | 可选 registry store |
 | `ENDPOINT_RPC` / `INBOX_RPC` / `SIDE_EVENT_RPC` / `SIDE_EVENT_PUSH` | `@zhin.js/console-protocol` 的规范 RPC 与推送名称 |
-| `normalizeConsolePushType` / `normalizeConsolePushMessage` | 在 SDK 边界兼容旧 `endpoint:*` 推送并输出规范事件与 payload |
-| `parseConsoleInboxEvent` | 一次完成 Inbox 推送名称、身份别名和 message/request/notice 分类 |
+| `parseConsoleInboxEvent` | 校验并分类 canonical message/request/notice 推送 |
 | `ConsoleEndpointSummary` / `EndpointManagementCapability` | Host 与 Remote Console 共享的 Endpoint wire 类型 |
 | `fetchConsoleEventHistory` | 按 `(runtimeId, eventId)` 拉取有界事件历史 |
-| `WebSocketManager.onConsoleEvent` | 订阅带 `live/history` 投递来源的强类型事件 |
-| `WebSocketManager.onConsoleEventRecoveryGap` | 观察不可续接游标并触发领域全量重同步 |
+| `ConsoleTransport.onConsoleEvent` | 订阅带 `live/history` 投递来源的强类型事件 |
+| `ConsoleTransport.onConsoleEventRecoveryGap` | 观察不可续接游标并触发领域全量重同步 |
 | `ConsoleInboxNoticesQuery` / `ConsoleInboxNoticesResult` | 以 `unreadOnly` 从持久 Inbox 重建未读通知 |
 
 类型与 Entry 契约来自 `@zhin.js/contract`。
 
-业务 UI 应使用 SDK 导出的协议常量和 Endpoint 类型，不要硬编码旧 `endpoint:list`、`endpoint:sendMessage` 等名称，也不要复制 `EndpointInfo`。SDK 会把旧 Host 推送别名归一化为 `message.receive` / `request.receive` / `notice.receive`，并统一 `endpointId`、`channelId` 字段。
+业务 UI 应使用 SDK 导出的协议常量和 Endpoint 类型，不要复制 RPC 字符串或 `EndpointInfo`。请求使用顶层 camelCase payload，Host 推送使用 `message.receive` / `request.receive` / `notice.receive` 和 canonical `adapter`、`endpointKey`、`channelId` 字段。
 
 ## 启动：加载插件 Console Entry
 
@@ -43,16 +41,15 @@ Remote Console 壳层在登录后调用：
 ```tsx
 import React from "react";
 import {
-  app,
-  createPluginRegisterHostApi,
+  ConsoleClientProvider,
+  createConsoleClient,
   loadConsoleEntries,
 } from "@zhin.js/client";
 
-const hostApi = createPluginRegisterHostApi({
-  React,
-  addRoute: app.addRoute.bind(app),
-  addTool: app.addTool.bind(app),
+const client = createConsoleClient({
+  getRuntimeEnv: () => import.meta.env.DEV ? "development" : "production",
 });
+const hostApi = client.createPluginRegisterHostApi(React);
 
 await loadConsoleEntries({
   hostApi,
@@ -64,6 +61,12 @@ await loadConsoleEntries({
   onFetchError: (status) => console.error("entries fetch failed", status),
   onEmpty: () => console.warn("no console entries"),
 });
+
+// 壳层根组件必须为 hooks 提供同一个 client 所有者。
+export function ConsoleRoot({ children }: { children: React.ReactNode }) {
+  React.useEffect(() => () => client.dispose(), []);
+  return <ConsoleClientProvider client={client}>{children}</ConsoleClientProvider>;
+}
 ```
 
 `loadConsoleEntries` 内部：`fetchConsoleEntries` → `registerConsolePluginsFromEntries` → 各 entry 模块的 `register` 或 `default.register`。
@@ -99,18 +102,21 @@ const res = await apiFetch("/api/console/request", {
 
 401 时清除 Token 并派发 `zhin:auth-required`。
 
-辅助：`resolveApiUrl`、`resolveWebSocketUrl`（SSE `/api/events` 等）。
+辅助：`resolveApiUrl`。
 
 Client 在连接 `/api/events` 前先补拉 `/api/events/history`，再携带最新游标进入 SSE；Host 会原子重放 HTTP 与订阅之间产生的事件。游标只在 Inbox 持久化成功后推进，重复的 history/live 投递按 `(runtimeId, eventId)` 幂等写入 IndexedDB。`gap` 不会被吞掉，页面可订阅恢复缺口并改走领域 HTTP 全量投影。
 
-## `createPluginRegisterHostApi`
+## Console 实例所有权
 
-将壳层已有的 React 与路由/工具注册函数适配为契约中的 `PluginRegisterHostApi`（含 `addPage` 别名 → `addRoute`）：
+每个 Remote Console mount 创建一个 `ConsoleClient`。插件注册、React hooks 和卸载必须使用同一个实例，多个 mount 之间不会共享路由、工具、运行时环境或连接状态：
 
 ```ts
-import { createPluginRegisterHostApi } from "@zhin.js/client";
+import React from "react";
+import { createConsoleClient } from "@zhin.js/client";
 
-const hostApi = createPluginRegisterHostApi({ React, addRoute, addTool });
+const client = createConsoleClient();
+const hostApi = client.createPluginRegisterHostApi(React);
+await loadConsoleEntries({ hostApi });
 ```
 
 ## 低级 API

package/client/app.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createConsoleApp } from './app.js';
+
+describe('ConsoleApp', () => {
+  it('isolates registrations and subscriptions by application owner', () => {
+    const first = createConsoleApp();
+    const second = createConsoleApp();
+    const listener = vi.fn();
+    first.subscribe(listener);
+
+    first.addRoute({ path: '/first', name: 'First', element: 'first' });
+    first.addTool({ id: 'first', name: 'First' });
+
+    expect(listener).toHaveBeenCalledTimes(2);
+    expect(first.getRoutes()).toHaveLength(1);
+    expect(first.getToolTree()).toHaveLength(1);
+    expect(second.getRoutes()).toEqual([]);
+    expect(second.getToolTree()).toEqual([]);
+    expect(second.getVersion()).toBe(0);
+  });
+
+  it('releases all registrations and listeners on disposal', () => {
+    const app = createConsoleApp();
+    const listener = vi.fn();
+    app.subscribe(listener);
+    app.addRoute({ path: '/route', name: 'Route', element: 'route' });
+    app.addTool({ id: 'tool', name: 'Tool' });
+
+    app.dispose();
+
+    expect(listener).toHaveBeenCalledTimes(2);
+    expect(app.getRoutes()).toEqual([]);
+    expect(app.getToolTree()).toEqual([]);
+    expect(() => app.addRoute({ path: '/next', name: 'Next', element: 'next' }))
+      .toThrow('ConsoleApp has been disposed');
+  });
+});

package/client/app.ts

@@ -1,28 +1,11 @@
 import * as React from "react";
+import type {
+  PluginAddRouteInput,
+  PluginAddToolInput,
+} from '@zhin.js/contract';
 
-export type AddRouteInput = {
-  path: string;
-  name: string;
-  element: React.ReactNode;
-  parent?: string | null;
-  icon?: React.ReactNode | string;
-  requiredPermissions?: string[];
-  requiredRoles?: string[];
-  meta?: {
-    hideInMenu?: boolean;
-    order?: number;
-    group?: string;
-    fullWidth?: boolean;
-  };
-};
-
-export type AddToolInput = {
-  id?: string;
-  name: string;
-  icon?: React.ReactNode;
-  parent?: string | null;
-  path?: string;
-};
+export type AddRouteInput = PluginAddRouteInput;
+export type AddToolInput = PluginAddToolInput;
 
 export type ConsoleRouteRecord = {
   path: string;
@@ -51,33 +34,10 @@ export type InternalToolRecord = {
 export type RouteTreeNode = ConsoleRouteRecord & { children: RouteTreeNode[] };
 export type ToolTreeNode = InternalToolRecord & { children: ToolTreeNode[] };
 
-type SidebarRenderer = (options: { routes: RouteTreeNode[] }) => React.ReactNode;
-type ToolbarRenderer = (options: { tools: ToolTreeNode[] }) => React.ReactNode;
+export type SidebarRenderer = (options: { routes: RouteTreeNode[] }) => React.ReactNode;
+export type ToolbarRenderer = (options: { tools: ToolTreeNode[] }) => React.ReactNode;
 export type ConsoleRouteRenderer = (route: ConsoleRouteRecord) => React.ReactNode;
 
-const listeners = new Set<() => void>();
-let version = 0;
-
-function bump() {
-  version++;
-  for (const l of listeners) l();
-}
-
-function subscribe(listener: () => void) {
-  listeners.add(listener);
-  return () => listeners.delete(listener);
-}
-
-function getVersion() {
-  return version;
-}
-
-let routes: ConsoleRouteRecord[] = [];
-let tools: InternalToolRecord[] = [];
-let sidebarRenderer: SidebarRenderer | null = null;
-let toolbarRenderer: ToolbarRenderer | null = null;
-let routeRenderer: ConsoleRouteRenderer | null = null;
-
 function slugId(name: string) {
   return (
     name
@@ -130,99 +90,131 @@ function buildToolTree(flatTools: InternalToolRecord[]): ToolTreeNode[] {
   }
   return roots;
 }
+/** Owner-scoped registry for one mounted Remote Console application. */
+export class ConsoleApp {
+  readonly #listeners = new Set<() => void>();
+  #version = 0;
+  #routes: ConsoleRouteRecord[] = [];
+  #tools: InternalToolRecord[] = [];
+  #sidebarRenderer: SidebarRenderer | null = null;
+  #toolbarRenderer: ToolbarRenderer | null = null;
+  #routeRenderer: ConsoleRouteRenderer | null = null;
+  #disposed = false;
+
+  readonly subscribe = (listener: () => void): (() => void) => {
+    this.#assertActive();
+    this.#listeners.add(listener);
+    return () => this.#listeners.delete(listener);
+  };
 
-function renderRouteElement(route: ConsoleRouteRecord): React.ReactNode {
-  if (routeRenderer) return routeRenderer(route);
-  return route.element;
-}
+  readonly getVersion = (): number => this.#version;
 
-function createConsoleApp() {
-  return {
-    subscribe,
-    getVersion,
-
-    defineSidebar(render: SidebarRenderer) {
-      sidebarRenderer = render;
-      bump();
-    },
-
-    defineToolbar(render: ToolbarRenderer) {
-      toolbarRenderer = render;
-      bump();
-    },
-
-    defineRouter(render: ConsoleRouteRenderer) {
-      routeRenderer = render;
-      bump();
-    },
-
-    addRoute(input: AddRouteInput) {
-      const next = routes.filter((r) => r.path !== input.path);
-      next.push({
-        path: input.path,
+  defineSidebar(render: SidebarRenderer): void {
+    this.#assertActive();
+    this.#sidebarRenderer = render;
+    this.#bump();
+  }
+
+  defineToolbar(render: ToolbarRenderer): void {
+    this.#assertActive();
+    this.#toolbarRenderer = render;
+    this.#bump();
+  }
+
+  defineRouter(render: ConsoleRouteRenderer): void {
+    this.#assertActive();
+    this.#routeRenderer = render;
+    this.#bump();
+  }
+
+  addRoute(input: AddRouteInput): void {
+    this.#assertActive();
+    const next = this.#routes.filter((route) => route.path !== input.path);
+    next.push({
+      path: input.path,
+      name: input.name,
+      element: input.element,
+      parent: input.parent ?? null,
+      icon: input.icon,
+      requiredPermissions: input.requiredPermissions,
+      requiredRoles: input.requiredRoles,
+      meta: input.meta,
+    });
+    this.#routes = next;
+    this.#bump();
+  }
+
+  removeRoute(path: string): void {
+    this.#assertActive();
+    this.#routes = this.#routes.filter((route) => route.path !== path);
+    this.#bump();
+  }
+
+  addTool(input: AddToolInput): string {
+    this.#assertActive();
+    const id = input.id ?? `${slugId(input.name)}-${Math.random().toString(36).slice(2, 8)}`;
+    if (this.#tools.some((tool) => tool.id === id)) {
+      throw new Error(`[zhin-console] addTool: id already exists: ${id}`);
+    }
+    this.#tools = [
+      ...this.#tools,
+      {
+        id,
         name: input.name,
-        element: input.element,
-        parent: input.parent ?? null,
         icon: input.icon,
-        requiredPermissions: input.requiredPermissions,
-        requiredRoles: input.requiredRoles,
-        meta: input.meta,
-      });
-      routes = next;
-      bump();
-    },
-
-    removeRoute(path: string) {
-      routes = routes.filter((r) => r.path !== path);
-      bump();
-    },
-
-    addTool(input: AddToolInput): string {
-      const id =
-        input.id ?? `${slugId(input.name)}-${Math.random().toString(36).slice(2, 8)}`;
-      if (tools.some((t) => t.id === id)) {
-        throw new Error(`[zhin-console] addTool: id already exists: ${id}`);
-      }
-      tools = [
-        ...tools,
-        {
-          id,
-          name: input.name,
-          icon: input.icon,
-          parent: input.parent ?? null,
-          path: input.path,
-        },
-      ];
-      bump();
-      return id;
-    },
-
-    getRouteTree(): RouteTreeNode[] {
-      return buildRouteTree(routes);
-    },
-
-    getToolTree(): ToolTreeNode[] {
-      return buildToolTree(tools);
-    },
-
-    _getRoutes(): readonly ConsoleRouteRecord[] {
-      return routes;
-    },
-
-    _getSidebarRenderer(): SidebarRenderer | null {
-      return sidebarRenderer;
-    },
-
-    _getToolbarRenderer(): ToolbarRenderer | null {
-      return toolbarRenderer;
-    },
-
-    _renderRouteElement(route: ConsoleRouteRecord): React.ReactNode {
-      return renderRouteElement(route);
-    },
-  };
-}
+        parent: input.parent ?? null,
+        path: input.path,
+      },
+    ];
+    this.#bump();
+    return id;
+  }
+
+  getRouteTree(): RouteTreeNode[] {
+    return buildRouteTree(this.#routes);
+  }
 
-export type ConsoleApp = ReturnType<typeof createConsoleApp>;
+  getToolTree(): ToolTreeNode[] {
+    return buildToolTree(this.#tools);
+  }
 
-export const app = createConsoleApp();
+  getRoutes(): readonly ConsoleRouteRecord[] {
+    return this.#routes;
+  }
+
+  getSidebarRenderer(): SidebarRenderer | null {
+    return this.#sidebarRenderer;
+  }
+
+  getToolbarRenderer(): ToolbarRenderer | null {
+    return this.#toolbarRenderer;
+  }
+
+  renderRouteElement(route: ConsoleRouteRecord): React.ReactNode {
+    return this.#routeRenderer ? this.#routeRenderer(route) : route.element;
+  }
+
+  dispose(): void {
+    if (this.#disposed) return;
+    this.#disposed = true;
+    this.#listeners.clear();
+    this.#routes = [];
+    this.#tools = [];
+    this.#sidebarRenderer = null;
+    this.#toolbarRenderer = null;
+    this.#routeRenderer = null;
+  }
+
+  #bump(): void {
+    this.#version += 1;
+    for (const listener of this.#listeners) listener();
+  }
+
+  #assertActive(): void {
+    if (this.#disposed) throw new Error('ConsoleApp has been disposed');
+  }
+}
+
+export function createConsoleApp(): ConsoleApp {
+  return new ConsoleApp();
+}

package/client/bootstrap/loadConsoleEntries.test.ts

@@ -1,6 +1,5 @@
 import { describe, expect, it, vi } from "vitest";
 import {
-  createPluginRegisterHostApi,
   getRegisterFn,
   resolveEntryRegister,
 } from "./loadConsoleEntries.js";
@@ -32,7 +31,6 @@ describe("console entries bootstrap", () => {
     register!({
       React: { createElement } as any,
       addRoute,
-      addPage: addRoute,
       addTool: vi.fn(),
     });
     expect(addRoute).toHaveBeenCalledWith(expect.objectContaining({
@@ -42,17 +40,4 @@ describe("console entries bootstrap", () => {
     }));
     expect(createElement).toHaveBeenCalledWith(Page);
   });
-
-  it("creates a host API with addPage aliased to addRoute", () => {
-    const React = {} as any;
-    const addRoute = vi.fn();
-    const addTool = vi.fn(() => "tool-id");
-    const api = createPluginRegisterHostApi({ React, addRoute, addTool });
-
-    api.addPage({ path: "/x", name: "x", element: "page" as any });
-    api.addRoute({ path: "/y", name: "y", element: "route" as any });
-    expect(api.React).toBe(React);
-    expect(addRoute).toHaveBeenCalledTimes(2);
-    expect(api.addTool({ id: "t", name: "T" })).toBe("tool-id");
-  });
 });

package/client/bootstrap/loadConsoleEntries.ts

@@ -17,24 +17,6 @@ export type LoadConsoleEntriesOptions = FetchConsoleEntriesOptions & {
   onEntryError?: (entry: ConsoleClientEntry, error: unknown) => void;
 };
 
-export type CreatePluginRegisterHostApiOptions = {
-  React: PluginRegisterHostApi["React"];
-  addRoute: PluginRegisterHostApi["addRoute"];
-  addTool: PluginRegisterHostApi["addTool"];
-};
-
-export function createPluginRegisterHostApi(
-  options: CreatePluginRegisterHostApiOptions,
-): PluginRegisterHostApi {
-  const addRoute = options.addRoute;
-  return {
-    React: options.React,
-    addRoute,
-    addPage: addRoute,
-    addTool: options.addTool,
-  };
-}
-
 const CONSOLE_API_BASE_STORAGE_KEY = "zhin_api_base";
 
 function resolveStoredApiBase(): string {
@@ -112,7 +94,7 @@ export function resolveEntryRegister(
     ? entry.route
     : `/${entry.id}`;
   const meta = mod["meta"] && typeof mod["meta"] === "object"
-    ? mod["meta"] as { title?: string; icon?: unknown; hideInNav?: boolean }
+    ? mod["meta"] as { title?: string; icon?: string; hideInNav?: boolean }
     : undefined;
   const name = (typeof meta?.title === "string" && meta.title)
     || (typeof entry.title === "string" && entry.title)
@@ -178,4 +160,3 @@ export async function loadConsoleEntries(options: LoadConsoleEntriesOptions): Pr
     options.assetOrigin,
   );
 }
-

package/client/console-client-context.ts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+import type { ConsoleClient } from './console-client.js';
+
+const ConsoleClientContext = React.createContext<ConsoleClient | null>(null);
+
+export interface ConsoleClientProviderProps {
+  readonly client: ConsoleClient;
+  readonly children?: React.ReactNode;
+}
+
+export function ConsoleClientProvider({
+  client,
+  children,
+}: ConsoleClientProviderProps): React.ReactElement {
+  return React.createElement(ConsoleClientContext.Provider, { value: client }, children);
+}
+
+export function useConsoleClient(): ConsoleClient {
+  const client = React.useContext(ConsoleClientContext);
+  if (!client) {
+    throw new Error('Console hooks require a ConsoleClientProvider');
+  }
+  return client;
+}

package/client/console-client.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it, vi } from 'vitest';
+import * as React from 'react';
+import { createConsoleClient } from './console-client.js';
+import { ConsoleTransport } from './transport/console-transport.js';
+
+describe('ConsoleClient', () => {
+  it('owns application, transport, and runtime environment state', () => {
+    const first = createConsoleClient({ getRuntimeEnv: () => 'development' });
+    const second = createConsoleClient();
+
+    first.app.addRoute({ path: '/first', name: 'First', element: 'first' });
+
+    expect(first.getRuntimeEnv()).toBe('development');
+    expect(second.getRuntimeEnv()).toBe('production');
+    expect(first.app.getRoutes()).toHaveLength(1);
+    expect(second.app.getRoutes()).toEqual([]);
+    expect(first.transport).not.toBe(second.transport);
+  });
+
+  it('binds plugin registration to its owned application', () => {
+    const client = createConsoleClient();
+    const hostApi = client.createPluginRegisterHostApi(React);
+
+    hostApi.addRoute({ path: '/plugin', name: 'Plugin', element: 'plugin' });
+    hostApi.addTool({ id: 'plugin', name: 'Plugin' });
+
+    expect(client.app.getRoutes().map((route) => route.path)).toEqual(['/plugin']);
+    expect(client.app.getToolTree().map((tool) => tool.id)).toEqual(['plugin']);
+  });
+
+  it('disconnects its transport and clears its application on disposal', () => {
+    const transport = new ConsoleTransport();
+    const dispose = vi.spyOn(transport, 'dispose');
+    const client = createConsoleClient({ transport });
+    client.app.addRoute({ path: '/route', name: 'Route', element: 'route' });
+
+    client.dispose();
+
+    expect(dispose).toHaveBeenCalledOnce();
+    expect(client.app.getRoutes()).toEqual([]);
+    expect(() => client.connect()).toThrow('ConsoleClient has been disposed');
+
+    client.dispose();
+    expect(dispose).toHaveBeenCalledOnce();
+  });
+});

package/client/console-client.ts

@@ -0,0 +1,70 @@
+import type {
+  PluginRegisterHostApi,
+  RuntimeEnv,
+} from '@zhin.js/contract';
+import type * as React from 'react';
+import { ConsoleApp, createConsoleApp } from './app.js';
+import { ConsoleTransport } from './transport/console-transport.js';
+import type {
+  ConsoleTransportCallbacks,
+  ConsoleTransportConfig,
+} from './transport/types.js';
+
+export interface ConsoleClientOptions {
+  readonly getRuntimeEnv?: () => RuntimeEnv;
+  readonly app?: ConsoleApp;
+  readonly transport?: ConsoleTransport;
+  readonly transportConfig?: ConsoleTransportConfig;
+  readonly transportCallbacks?: ConsoleTransportCallbacks;
+}
+
+/** Owns all mutable browser-side state for one Remote Console mount. */
+export class ConsoleClient {
+  readonly app: ConsoleApp;
+  readonly transport: ConsoleTransport;
+  readonly #getRuntimeEnv: () => RuntimeEnv;
+  #disposed = false;
+
+  constructor(options: ConsoleClientOptions = {}) {
+    this.app = options.app ?? createConsoleApp();
+    this.transport = options.transport ?? new ConsoleTransport(
+      options.transportConfig,
+      options.transportCallbacks,
+    );
+    this.#getRuntimeEnv = options.getRuntimeEnv ?? (() => 'production');
+  }
+
+  getRuntimeEnv(): RuntimeEnv {
+    this.#assertActive();
+    return this.#getRuntimeEnv();
+  }
+
+  createPluginRegisterHostApi(ReactRuntime: typeof React): PluginRegisterHostApi {
+    this.#assertActive();
+    return {
+      React: ReactRuntime,
+      addRoute: (input) => this.app.addRoute(input),
+      addTool: (input) => this.app.addTool(input),
+    };
+  }
+
+  connect(): void {
+    this.#assertActive();
+    this.transport.connect();
+  }
+
+  dispose(): void {
+    if (this.#disposed) return;
+    this.#disposed = true;
+    this.transport.dispose();
+    this.app.dispose();
+  }
+
+  #assertActive(): void {
+    if (this.#disposed) throw new Error('ConsoleClient has been disposed');
+  }
+}
+
+export function createConsoleClient(options?: ConsoleClientOptions): ConsoleClient {
+  return new ConsoleClient(options);
+}

package/client/console-events.ts

@@ -2,10 +2,11 @@ import type {
   ConsoleEventHistoryPage,
   ConsoleEventHistoryQuery,
 } from '@zhin.js/console-protocol';
-import { getStoredToken, resolveApiUrl } from './websocket/remote-settings.js';
+import { getToken, resolveApiUrl } from './console-utils/remoteApi.js';
 
 export interface FetchConsoleEventHistoryOptions {
   readonly signal?: AbortSignal;
+  readonly fetch?: typeof globalThis.fetch;
 }
 
 /** Read a typed page from the Host's bounded Console event journal. */
@@ -17,11 +18,11 @@ export async function fetchConsoleEventHistory(
   if (query.runtimeId) params.set('runtimeId', query.runtimeId);
   if (query.after !== undefined) params.set('after', String(query.after));
   if (query.limit !== undefined) params.set('limit', String(query.limit));
-  const token = getStoredToken();
+  const token = getToken();
   const headers: Record<string, string> = { Accept: 'application/json' };
   if (token) headers.Authorization = `Bearer ${token}`;
   const suffix = params.size ? `?${params}` : '';
-  const response = await fetch(resolveApiUrl(`/api/events/history${suffix}`), {
+  const response = await (options.fetch ?? globalThis.fetch)(resolveApiUrl(`/api/events/history${suffix}`), {
     headers,
     signal: options.signal,
   });

package/client/console-utils/remoteApi.ts

@@ -28,13 +28,6 @@ export function resolveApiUrl(path: string): string {
   return `${base}${p}`;
 }
 
-export function resolveWebSocketUrl(path: string): string {
-  const httpUrl = resolveApiUrl(path);
-  const url = new URL(httpUrl);
-  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
-  return url.href;
-}
-
 /** fetch with Bearer token; relative paths resolve against {@link getApiBase}. */
 export async function apiFetch(
   input: RequestInfo | URL,