@zhin.js/client 1.1.4 → 1.1.6

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,5 +1,8 @@
 import { describe, expect, it, vi } from "vitest";
-import { createPluginRegisterHostApi, getRegisterFn } from "./loadConsoleEntries.js";
+import {
+  getRegisterFn,
+  resolveEntryRegister,
+} from "./loadConsoleEntries.js";
 
 describe("console entries bootstrap", () => {
   it("resolves named register export", () => {
@@ -16,17 +19,25 @@ describe("console entries bootstrap", () => {
     expect(getRegisterFn({ default: {} })).toBeNull();
   });
 
-  it("creates a host API with addPage aliased to addRoute", () => {
-    const React = {} as any;
+  it("synthesizes register from default component + entry.route", () => {
+    const Page = () => null;
+    const register = resolveEntryRegister(
+      { default: Page, meta: { title: "Sandbox", icon: "Box" } },
+      { id: "sandbox", resolvedModule: "/assets/client/sandbox.js", route: "/p-sandbox" } as any,
+    );
+    expect(typeof register).toBe("function");
     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");
+    const createElement = vi.fn((c: unknown) => ({ type: c }));
+    register!({
+      React: { createElement } as any,
+      addRoute,
+      addTool: vi.fn(),
+    });
+    expect(addRoute).toHaveBeenCalledWith(expect.objectContaining({
+      path: "/p-sandbox",
+      name: "Sandbox",
+      icon: "Box",
+    }));
+    expect(createElement).toHaveBeenCalledWith(Page);
   });
 });
-

package/client/bootstrap/loadConsoleEntries.ts

@@ -1,10 +1,5 @@
-import type {
-  ConsoleClientEntry,
-  ConsoleEntriesResponse,
-  ConsolePluginRegister,
-  PluginRegisterHostApi,
-} from "@zhin.js/console-types";
-import { DEFAULT_CONSOLE_BASE_PATH } from "@zhin.js/console-types";
+import { DEFAULT_CONSOLE_BASE_PATH, type ConsoleClientEntry, type ConsoleEntriesResponse, type ConsolePluginRegister, type PluginRegisterHostApi } from '@zhin.js/contract';
+import type * as React from 'react';
 
 export type FetchConsoleEntriesOptions = {
   entriesUrl?: string;
@@ -22,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 {
@@ -97,6 +74,43 @@ export function getRegisterFn(mod: Record<string, unknown> | null | undefined):
   return null;
 }
 
+/**
+ * Convention pages (ADR 0046) export a React component as `default` + optional `meta`,
+ * without a legacy `register(api)`. Synthesize register from entry.route / entry meta
+ * so Remote Console can still mount them.
+ */
+export function resolveEntryRegister(
+  mod: Record<string, unknown> | null | undefined,
+  entry: ConsoleClientEntry & { readonly route?: string; readonly title?: string },
+): ConsolePluginRegister | null {
+  const named = getRegisterFn(mod);
+  if (named) return named;
+  if (!mod) return null;
+  const Component = mod["default"];
+  if (typeof Component !== "function" && !(Component && typeof Component === "object")) {
+    return null;
+  }
+  const path = typeof entry.route === "string" && entry.route
+    ? entry.route
+    : `/${entry.id}`;
+  const meta = mod["meta"] && typeof mod["meta"] === "object"
+    ? mod["meta"] as { title?: string; icon?: string; hideInNav?: boolean }
+    : undefined;
+  const name = (typeof meta?.title === "string" && meta.title)
+    || (typeof entry.title === "string" && entry.title)
+    || entry.meta?.name
+    || entry.id;
+  return (api) => {
+    api.addRoute({
+      path,
+      name,
+      element: api.React.createElement(Component as React.ComponentType),
+      ...(meta?.icon != null ? { icon: meta.icon } : {}),
+      meta: { hideInMenu: meta?.hideInNav === true },
+    });
+  };
+}
+
 export async function registerConsolePluginsFromEntries(
   entries: ConsoleClientEntry[],
   hostApi: PluginRegisterHostApi,
@@ -109,7 +123,7 @@ export async function registerConsolePluginsFromEntries(
       try {
         const specifier = resolvePluginImportUrl(entry.resolvedModule, assetOrigin);
         const mod = (await import(/* @vite-ignore */ specifier)) as Record<string, unknown>;
-        const register = getRegisterFn(mod);
+        const register = resolveEntryRegister(mod, entry);
         if (register) await register(hostApi);
         else throw new Error(`entry "${entry.id}" has no register export`);
       } catch (error) {
@@ -146,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

@@ -0,0 +1,38 @@
+import type {
+  ConsoleEventHistoryPage,
+  ConsoleEventHistoryQuery,
+} from '@zhin.js/console-protocol';
+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. */
+export async function fetchConsoleEventHistory(
+  query: ConsoleEventHistoryQuery = {},
+  options: FetchConsoleEventHistoryOptions = {},
+): Promise<ConsoleEventHistoryPage> {
+  const params = new URLSearchParams();
+  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 = getToken();
+  const headers: Record<string, string> = { Accept: 'application/json' };
+  if (token) headers.Authorization = `Bearer ${token}`;
+  const suffix = params.size ? `?${params}` : '';
+  const response = await (options.fetch ?? globalThis.fetch)(resolveApiUrl(`/api/events/history${suffix}`), {
+    headers,
+    signal: options.signal,
+  });
+  const body = await response.json() as {
+    success?: boolean;
+    data?: ConsoleEventHistoryPage;
+    error?: string;
+  };
+  if (!response.ok || body.success !== true || !body.data) {
+    throw new Error(body.error ?? `Console event history failed: HTTP ${response.status}`);
+  }
+  return body.data;
+}