@devframes/hub 0.8.2 → 0.9.0-beta.10

package/dist/client/index.d.mts

@@ -1,7 +1,6 @@
-import { N as NavTarget, O as DevframeViewIframe, P as RemoteConnectionInfo, a as DevframeCommandEntry, g as DevframeDockEntry, h as DevframeDockEntriesGrouped, n as DevframeClientCommand, s as DevframeCommandKeybinding, t as DevframeDocksUserSettings, x as DevframeDockUserEntry, y as DevframeDockEntryIcon } from "../settings-Byh48aCd.mjs";
-import { DEFAULT_CATEGORIES_ORDER } from "../constants.mjs";
-import { w as DevframeMessagesClient, y as DevframeMessageEntryInput } from "../context-BSgzLnsu.mjs";
-import "../index-IzywMKfP.mjs";
+import { E as DevframeMessagesClient, x as DevframeMessageEntryInput } from "../context-D5TJIHwp.mjs";
+import { N as NavTarget, P as RemoteConnectionInfo, S as DevframeDockUserEntry, _ as DevframeDockEntry, a as DevframeCommandEntry, b as DevframeDockEntryIcon, g as DevframeDockEntriesGrouped, k as DevframeViewIframe, n as DevframeClientCommand, p as ClientScriptEntry, s as DevframeCommandKeybinding, t as DevframeDocksUserSettings } from "../settings-DfrRa9Wf.mjs";
+import "../index-coDmWngQ.mjs";
 import { DevframeClientRpcHost, DevframeConnection, DevframeConnectionStatus, DevframeRpcClient, DevframeRpcClientOptions, DevframeRpcContext, RpcClientEvents, RpcClientEvents as RpcClientEvents$1 } from "devframe/client";
 import { EventEmitter } from "devframe/types";
 import { SharedState } from "devframe/utils/shared-state";
@@ -11,10 +10,17 @@ export * from "devframe/client";
 /**
  * Options handed to a dock renderer when the client host mounts a dock entry.
  */
-interface DockRendererMountOptions {
+interface DockRendererMountOptions<Entry extends DevframeDockEntry = DevframeDockEntry> {
   /** The dock entry being rendered (carries the entry's serializable payload). */
-  entry: DevframeDockEntry;
-  /** The DOM element the renderer should mount into. */
+  entry: Entry;
+  /**
+   * The DOM element the renderer should mount into. It may live inside a
+   * **shadow root** (the reference viewer isolates dock content that way), so
+   * a renderer must deliver its own styles into `container.getRootNode()`
+   * rather than assume a page-level stylesheet. The viewer mirrors a live
+   * `dark` class onto this element (the theme contract), and CSS custom
+   * properties inherit across the shadow boundary for brand theming.
+   */
   container: HTMLElement;
   /** The assembled client host context (rpc, docks, commands, …). */
   context: DevframeClientContext;
@@ -26,33 +32,99 @@ interface DockRendererInstance {
 }
 /**
  * A renderer for a dock `type`. The headless hub is renderer-agnostic — a
- * host application registers renderers at boot (e.g. injecting
- * `@devframes/json-render-ui` for the `'json-render'` type). The renderer
- * owns its framework (Vue, React, …); the hub only routes a dock type to it
- * and disposes it on deactivation.
+ * host registers renderers at boot (e.g. injecting `@devframes/json-render-ui`
+ * for the `'json-render'` type) or serves them as prebuilt modules through the
+ * hub's renderer manifest (`initHub({ renderers })`). The renderer owns its
+ * framework (Vue, React, …); the hub only routes a dock type to it and
+ * disposes it on deactivation.
+ *
+ * Integration packages narrow `Entry` to export a precisely-typed contract —
+ * e.g. `@devframes/json-render/hub` exports
+ * `JsonRenderDockRenderer = DockRenderer<DevframeJsonRenderDockEntry>`.
  */
-type DockRenderer = (options: DockRendererMountOptions) => DockRendererInstance | Promise<DockRendererInstance>;
+type DockRenderer<Entry extends DevframeDockEntry = DevframeDockEntry> = (options: DockRendererMountOptions<Entry>) => DockRendererInstance | Promise<DockRendererInstance>;
+/**
+ * The outcome of {@link DockRenderersContext.mount}. A missing renderer is an
+ * expected, non-exceptional state — a viewer renders its "no renderer for this
+ * dock type" fallback from `missing-renderer`, and its error variant (with a
+ * retry affordance) from `load-error`.
+ */
+type DockRendererMountResult = {
+  status: 'mounted';
+  dispose: () => void;
+} | {
+  status: 'missing-renderer';
+} | {
+  status: 'load-error';
+  error: unknown;
+};
 /**
  * The dock-renderer registry surfaced on the client host context. A viewer
  * calls {@link DockRenderersContext.mount} to render a dock whose `type` has a
- * registered renderer into a container it owns; the host tracks the instance
- * and disposes it when the entry deactivates.
+ * renderer — registered locally at boot, or served as a prebuilt module by the
+ * hub's renderer manifest — into a container it owns; the host tracks the
+ * instance and disposes it when the entry deactivates.
  */
 interface DockRenderersContext {
-  /** Register a renderer for a dock `type`. Returns an unregister function. */
-  register: (type: string, renderer: DockRenderer) => () => void;
-  /** Look up the renderer registered for a dock `type`, if any. */
+  /**
+   * Register a renderer for a dock `type`. Returns an unregister function.
+   * Accepts a renderer narrowed to any specific entry variant (e.g. a
+   * {@link DockRenderer}<DevframeJsonRenderDockEntry> from an integration
+   * package) — the type routes only its own entries to it.
+   */
+  register: (type: string, renderer: DockRenderer<any>) => () => void;
+  /** Look up the locally-registered renderer for a dock `type`, if any. */
   get: (type: string) => DockRenderer | undefined;
-  /** Whether a renderer is registered for a dock `type`. */
+  /**
+   * Whether a renderer is available for a dock `type` — registered locally
+   * **or** provided by the hub's renderer manifest. A viewer checks this
+   * before mounting to render its missing-renderer fallback declaratively.
+   */
   has: (type: string) => boolean;
   /**
-   * Mount the entry's registered renderer into `container`. Resolves to a
-   * disposer; the same instance is also disposed automatically when the entry
-   * deactivates. Warns and resolves to a no-op disposer when no renderer is
-   * registered for the entry's type.
+   * Mount the entry's renderer into `container` and resolve the
+   * {@link DockRendererMountResult}. A local registration wins; otherwise the
+   * manifest module for the entry's type is imported (lazily, cached) and
+   * registered. The mounted instance is also disposed automatically when the
+   * entry deactivates. Resolves `missing-renderer` (with a `console.warn`)
+   * when neither source has the type, and `load-error` when the module import
+   * or the renderer itself fails — a failed import is not cached, so a retry
+   * re-imports.
    */
-  mount: (entry: DevframeDockEntry, container: HTMLElement) => Promise<() => void>;
+  mount: (entry: DevframeDockEntry, container: HTMLElement) => Promise<DockRendererMountResult>;
 }
+/**
+ * The renderer manifest published by the hub at the
+ * `devframe:dock-renderers` shared-state slot — one {@link ClientScriptEntry}
+ * per dock `type`, whose `importFrom` is a URL path the hub serves
+ * (`<base>__renderers/<type>.mjs`). Mirrors the dock client-script
+ * convention: the module's `importName` export (default `'default'`) is a
+ * ready {@link DockRenderer}.
+ */
+type DockRendererManifest = Record<string, ClientScriptEntry>;
+/** Options for {@link createDockRenderersContext}. */
+interface CreateDockRenderersContextOptions {
+  /** The assembled client context handed to renderers at mount. */
+  context: () => DevframeClientContext;
+  /** Renderers registered locally at boot — these win over manifest modules. */
+  local?: Record<string, DockRenderer<any>>;
+  /** The current {@link DockRendererManifest} (live getter). */
+  manifest?: () => DockRendererManifest;
+  /**
+   * Called with each successful mount's disposer so the caller can tie
+   * disposal to its own lifecycle (entry deactivation, host teardown). An
+   * optional returned cleanup runs exactly once when the mount is disposed —
+   * whichever side (caller or viewer) triggers it first.
+   */
+  onMounted?: (dispose: () => void, entry: DevframeDockEntry) => (() => void) | void;
+}
+/**
+ * Build the {@link DockRenderersContext} shared by every hub-aware client —
+ * `createDevframeClientHost` and viewers that assemble their own context
+ * (`@devframes/hub-ui`) both delegate here so local-first resolution, lazy
+ * manifest imports, and the typed mount result behave identically everywhere.
+ */
+declare function createDockRenderersContext(options: CreateDockRenderersContextOptions): DockRenderersContext;
 //#endregion
 //#region src/client/docks.d.ts
 interface DockPanelStorage {
@@ -62,9 +134,30 @@ interface DockPanelStorage {
   top: number;
   left: number;
   position: 'left' | 'right' | 'bottom' | 'top';
-  open: boolean;
   inactiveTimeout: number;
 }
+/**
+ * Per-tab UI state of the dock panel, distinct from the browser-shared geometry
+ * in {@link DockPanelStorage}. A viewer persists this to `sessionStorage` so a
+ * reload (or the RPC auth handshake that follows one) restores the panel to
+ * exactly where the developer left it — which dock was open, and the
+ * address-bar route of that dock's iframe. Kept `sessionStorage`-scoped (not
+ * `localStorage`) because it is per-tab navigation state: two tabs open against
+ * the same dev server each keep their own selection rather than fighting over a
+ * shared one. Every field is serializable.
+ */
+interface DockSessionStorage {
+  /** Whether the dock panel is open. */
+  open: boolean;
+  /** The currently selected dock entry id, or `null` when nothing is open. */
+  selectedDockId: string | null;
+  /**
+   * The live address-bar URL of the selected iframe dock, restored as that
+   * iframe's boot `src` on the next load so the deep-linked route survives a
+   * reload. `null` when the selected dock has no iframe route to remember.
+   */
+  selectedDockRoute: string | null;
+}
 type DockClientType = 'embedded' | 'standalone';
 interface DocksContext extends DevframeRpcContext {
   /**
@@ -124,16 +217,41 @@ interface WhenClauseContext {
 type DevframeClientContext = DocksContext;
 interface DocksPanelContext {
   store: DockPanelStorage;
+  /**
+   * Per-tab session UI state — whether the panel is open, which dock is
+   * selected, and that dock's iframe route. Restored across reloads (and the
+   * auth handshake that follows one) by a viewer that persists it to
+   * `sessionStorage`.
+   */
+  session: DockSessionStorage;
   isDragging: boolean;
   isResizing: boolean;
   readonly isVertical: boolean;
+  /**
+   * Claim the persisted {@link DockSessionStorage.selectedDockRoute boot route} for a dock
+   * id, once. Returns the saved address-bar URL only for the dock that was
+   * selected before the last reload — and only on the first call for it — so a
+   * restored iframe boots deep-linked while a later switch to a different dock
+   * (whose live route isn't reflected in {@link DockSessionStorage.selectedDockRoute} yet)
+   * doesn't reuse the stale value. Returns `null` otherwise.
+   */
+  consumeBootRoute?: (id: string) => string | null;
 }
 interface DocksEntriesContext {
   selectedId: string | null;
+  selectedRoute: string | null;
   readonly selected: DevframeDockEntry | null;
   entries: DevframeDockEntry[];
   entryToStateMap: Map<string, DockEntryState>;
   groupedEntries: DevframeDockEntriesGrouped;
+  /**
+   * The resolved top-level category ordering — `DEFAULT_CATEGORIES_ORDER`,
+   * overridden by every installed devframe's own `dock.categoryOrder`
+   * (`ConnectionMeta.configs.dock.categoryOrder`), overridden again by the
+   * host page's own `createDevframeClientHost({ categoryOrder })`. Fixed
+   * for the life of the session — resolved once at boot.
+   */
+  readonly categoryOrder: Record<string, number>;
   settings: SharedState<DevframeDocksUserSettings>;
   /**
    * Get the state of a dock entry by its ID
@@ -266,6 +384,79 @@ declare function resolveDockUrl(url: string, connection: DevframeConnection): st
 /** Resolve URL-backed dock icons while preserving Iconify names and data URLs. */
 declare function resolveDockIcon(icon: DevframeDockEntryIcon, connection: DevframeConnection): DevframeDockEntryIcon;
 //#endregion
+//#region src/client/frame-location.d.ts
+/**
+ * Live location tracking for an iframe dock.
+ *
+ * An iframe dock's address bar — and the route persisted from it into
+ * `DockSessionStorage.selectedDockRoute` — has to follow wherever the embedded
+ * app actually goes. The `load` event only covers whole-document navigations, so
+ * an SPA router moving between routes with `history.pushState()` leaves both
+ * showing the URL the frame booted with.
+ *
+ * {@link watchFrameLocation} closes that gap for a same-origin frame, reporting
+ * `location.href` on every navigation it can observe:
+ *
+ * - `popstate` / `hashchange` — back/forward and hash routing;
+ * - `history.pushState`/`replaceState`, wrapped in place (and restored on
+ *   dispose) because those two fire no event of their own;
+ * - the [Navigation API](https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API)'s
+ *   `currententrychange` where it exists, which reports post-commit and so also
+ *   catches what a wrapper structurally cannot — a router holding a reference to
+ *   `pushState` captured before this watch attached;
+ * - `load`, which also re-subscribes: a document navigation swaps the frame's
+ *   `history`/`navigation` objects, so the previous subscription dies with them.
+ *
+ * These sources overlap deliberately rather than being chosen between, since a
+ * report is deduped against the last href — the cost of hearing the same
+ * navigation twice is nothing, and the cost of missing one is a stale route.
+ *
+ * A cross-origin frame reports nothing — its location is unreadable by design,
+ * so the caller keeps the last URL it knew.
+ */
+/** The minimal `history` surface the watcher wraps. Injectable for tests. */
+interface FrameLocationHistory {
+  pushState: (...args: any[]) => void;
+  replaceState: (...args: any[]) => void;
+}
+/** The minimal frame-window surface the watcher reads and subscribes to. */
+interface FrameLocationWindow {
+  readonly location: {
+    readonly href: string;
+  };
+  readonly history?: FrameLocationHistory;
+  /** Present only where the Navigation API ships. */
+  readonly navigation?: {
+    addEventListener: (type: 'currententrychange', listener: () => void) => void;
+    removeEventListener: (type: 'currententrychange', listener: () => void) => void;
+  };
+  addEventListener: (type: 'popstate' | 'hashchange', listener: () => void) => void;
+  removeEventListener: (type: 'popstate' | 'hashchange', listener: () => void) => void;
+}
+/** The minimal iframe surface the watcher needs. Injectable for tests. */
+interface FrameLocationTarget {
+  readonly contentWindow: FrameLocationWindow | null;
+  addEventListener: (type: 'load', listener: () => void) => void;
+  removeEventListener: (type: 'load', listener: () => void) => void;
+}
+interface WatchFrameLocationOptions {
+  /** The live iframe whose location is tracked. */
+  iframe: FrameLocationTarget;
+  /** Called with the frame's `location.href` on each observed change. */
+  onChange: (href: string) => void;
+  /**
+   * The href the caller already shows, so an initial report is only made when
+   * the frame is somewhere else (a frame re-attached mid-session, say).
+   */
+  initial?: string;
+}
+/**
+ * Track a frame's location until the returned disposer is called. Disposing
+ * detaches every listener and restores any wrapped `history` method, leaving the
+ * embedded page as it was found.
+ */
+declare function watchFrameLocation(options: WatchFrameLocationOptions): () => void;
+//#endregion
 //#region src/client/frame-nav.d.ts
 /**
  * Shared-iframe soft navigation — the viewer-side half of a host↔iframe
@@ -413,8 +604,11 @@ interface DevframeClientHostOptions {
    * application injects the ones it wants (e.g.
    * `{ 'json-render': createJsonRenderDockRenderer() }` from
    * `@devframes/json-render-ui`). The hub ships none by default.
+   *
+   * Local registrations take precedence over the hub's renderer manifest
+   * (`initHub({ renderers })`) — explicit local code beats wire config.
    */
-  renderers?: Record<string, DockRenderer>;
+  renderers?: Record<string, DockRenderer<any>>;
   /**
    * Hub-wide override of the top-level dock-bar category ordering — a map of
    * category id → ordering weight (lower sorts earlier), mirroring the shape
@@ -428,7 +622,7 @@ interface DevframeClientHostOptions {
    *
    * Keys are merged over `DEFAULT_CATEGORIES_ORDER`, so the host app only
    * lists the categories it wants to move; any category absent from the map
-   * keeps its default weight (falling back to `0`).
+   * keeps its default weight.
    *
    * @example
    * ```ts
@@ -504,4 +698,4 @@ declare function parseRemoteConnection(input?: string): RemoteConnectionInfo | n
  */
 declare function connectRemoteDevframe(options?: ConnectRemoteDevframeOptions): Promise<DevframeRpcClient>;
 //#endregion
-export { CLIENT_CONTEXT_KEY, CommandsContext, ConnectRemoteDevframeOptions, DEFAULT_CATEGORIES_ORDER, DevframeClientContext, DevframeClientHost, DevframeClientHostOptions, type DevframeClientRpcHost, DockClientScriptContext, DockClientType, DockEntryState, DockEntryStateEvents, DockPanelStorage, DockRegistration, DockRenderer, DockRendererInstance, DockRendererMountOptions, DockRenderersContext, DocksConnectionContext, DocksContext, DocksEntriesContext, DocksPanelContext, FRAME_NAV_CHANNEL, FRAME_NAV_VERSION, FrameNavClient, FrameNavClientOptions, FrameNavEnvelope, FrameNavFrameMessage, FrameNavHostMessage, FrameNavHostPayload, FrameNavListenTarget, FrameTab, MessagesClientOptions, type RpcClientEvents, WhenClauseContext, attachFrameNavClient, buildRemoteDevframeUrl, connectRemoteDevframe, createDevframeClientHost, createMessagesClient, getDevframeClientContext, parseRemoteConnection, resolveDockIcon, resolveDockUrl, setDevframeClientContext, stripRemoteConnectionFromUrl };
+export { CLIENT_CONTEXT_KEY, CommandsContext, ConnectRemoteDevframeOptions, CreateDockRenderersContextOptions, DevframeClientContext, DevframeClientHost, DevframeClientHostOptions, type DevframeClientRpcHost, DockClientScriptContext, DockClientType, DockEntryState, DockEntryStateEvents, DockPanelStorage, DockRegistration, DockRenderer, DockRendererInstance, DockRendererManifest, DockRendererMountOptions, DockRendererMountResult, DockRenderersContext, DockSessionStorage, DocksConnectionContext, DocksContext, DocksEntriesContext, DocksPanelContext, FRAME_NAV_CHANNEL, FRAME_NAV_VERSION, FrameLocationHistory, FrameLocationTarget, FrameLocationWindow, FrameNavClient, FrameNavClientOptions, FrameNavEnvelope, FrameNavFrameMessage, FrameNavHostMessage, FrameNavHostPayload, FrameNavListenTarget, FrameTab, MessagesClientOptions, type RpcClientEvents, WatchFrameLocationOptions, WhenClauseContext, attachFrameNavClient, buildRemoteDevframeUrl, connectRemoteDevframe, createDevframeClientHost, createDockRenderersContext, createMessagesClient, getDevframeClientContext, parseRemoteConnection, resolveDockIcon, resolveDockUrl, setDevframeClientContext, stripRemoteConnectionFromUrl, watchFrameLocation };