@devframes/hub 0.9.0-beta.9 → 0.9.0

package/dist/client/index.d.mts

@@ -134,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 {
   /**
@@ -196,12 +217,29 @@ 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>;
@@ -346,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
@@ -587,4 +698,4 @@ declare function parseRemoteConnection(input?: string): RemoteConnectionInfo | n
  */
 declare function connectRemoteDevframe(options?: ConnectRemoteDevframeOptions): Promise<DevframeRpcClient>;
 //#endregion
-export { CLIENT_CONTEXT_KEY, CommandsContext, ConnectRemoteDevframeOptions, CreateDockRenderersContextOptions, DevframeClientContext, DevframeClientHost, DevframeClientHostOptions, type DevframeClientRpcHost, DockClientScriptContext, DockClientType, DockEntryState, DockEntryStateEvents, DockPanelStorage, DockRegistration, DockRenderer, DockRendererInstance, DockRendererManifest, DockRendererMountOptions, DockRendererMountResult, 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, createDockRenderersContext, 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 };

package/dist/client/index.mjs

@@ -69,6 +69,88 @@ function resolveDockIcon(icon, connection) {
 	};
 }
 //#endregion
+//#region src/client/frame-location.ts
+/**
+* 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.
+*/
+function watchFrameLocation(options) {
+	const { iframe, onChange } = options;
+	let lastReported = options.initial;
+	let detach;
+	let disposed = false;
+	/**
+	* The frame's window, or `null` when its location can't be read. Touching
+	* `location.href` is the cross-origin probe — it throws for a foreign
+	* document, where there is nothing to observe.
+	*/
+	function readableWindow() {
+		try {
+			const win = iframe.contentWindow;
+			return win && typeof win.location.href === "string" ? win : null;
+		} catch {
+			return null;
+		}
+	}
+	function report() {
+		const href = readableWindow()?.location.href;
+		if (!href || href === "about:blank" || href === lastReported) return;
+		lastReported = href;
+		onChange(href);
+	}
+	function subscribe() {
+		const win = readableWindow();
+		if (!win) return;
+		const listeners = [];
+		win.addEventListener("popstate", report);
+		win.addEventListener("hashchange", report);
+		listeners.push(() => {
+			win.removeEventListener("popstate", report);
+			win.removeEventListener("hashchange", report);
+		});
+		const { navigation, history } = win;
+		if (navigation) {
+			navigation.addEventListener("currententrychange", report);
+			listeners.push(() => navigation.removeEventListener("currententrychange", report));
+		}
+		if (history) {
+			const originals = {
+				pushState: history.pushState,
+				replaceState: history.replaceState
+			};
+			for (const method of ["pushState", "replaceState"]) history[method] = function(...args) {
+				originals[method].apply(this, args);
+				report();
+			};
+			listeners.push(() => {
+				history.pushState = originals.pushState;
+				history.replaceState = originals.replaceState;
+			});
+		}
+		detach = () => {
+			for (const off of listeners) off();
+		};
+	}
+	function onLoad() {
+		if (disposed) return;
+		detach?.();
+		detach = void 0;
+		subscribe();
+		report();
+	}
+	iframe.addEventListener("load", onLoad);
+	subscribe();
+	report();
+	return () => {
+		if (disposed) return;
+		disposed = true;
+		iframe.removeEventListener("load", onLoad);
+		detach?.();
+		detach = void 0;
+	};
+}
+//#endregion
 //#region src/client/frame-nav.ts
 /**
 * Shared-iframe soft navigation — the viewer-side half of a host↔iframe
@@ -462,7 +544,7 @@ async function createDevframeClientHost(options = {}) {
 		when: { get context() {
 			return {
 				clientType,
-				dockOpen: panel.store.open,
+				dockOpen: panel.session.open,
 				paletteOpen: commands.paletteOpen,
 				dockSelectedId: selectedId ?? ""
 			};
@@ -584,7 +666,11 @@ async function createDevframeClientHost(options = {}) {
 		}
 		docks.entries = entries;
 		docks.groupedEntries = groupByCategory(entries, categoryOrder);
-		if (selectedId && !entryToStateMap.has(selectedId)) selectedId = null;
+		if (selectedId && !entryToStateMap.has(selectedId)) {
+			selectedId = null;
+			panel.session.selectedDockId = null;
+			panel.session.selectedDockRoute = null;
+		}
 	}
 	function createDocksContext() {
 		return {
@@ -594,6 +680,12 @@ async function createDevframeClientHost(options = {}) {
 			set selectedId(id) {
 				switchEntry(id);
 			},
+			get selectedRoute() {
+				return panel.session.selectedDockRoute;
+			},
+			set selectedRoute(route) {
+				panel.session.selectedDockRoute = route;
+			},
 			get selected() {
 				return selectedId && entryToStateMap.get(selectedId)?.entryMeta || null;
 			},
@@ -638,6 +730,8 @@ async function createDevframeClientHost(options = {}) {
 		if (next !== null && !entryToStateMap.has(next)) return false;
 		const previous = selectedId;
 		selectedId = next;
+		panel.session.selectedDockId = next;
+		if (next === null || entryToStateMap.get(next)?.entryMeta.type !== "iframe") panel.session.selectedDockRoute = null;
 		if (previous) entryToStateMap.get(previous)?.events.emit("entry:deactivated");
 		if (next) entryToStateMap.get(next)?.events.emit("entry:activated");
 		return true;
@@ -734,11 +828,15 @@ function createPanelContext(clientType) {
 		top: 0,
 		left: 0,
 		position: "right",
-		open: clientType === "standalone",
 		inactiveTimeout: 0
 	};
 	return {
 		store,
+		session: {
+			open: clientType === "standalone",
+			selectedDockId: null,
+			selectedDockRoute: null
+		},
 		isDragging: false,
 		isResizing: false,
 		get isVertical() {
@@ -869,4 +967,4 @@ async function connectRemoteDevframe(options = {}) {
 	});
 }
 //#endregion
-export { CLIENT_CONTEXT_KEY, FRAME_NAV_CHANNEL, FRAME_NAV_VERSION, attachFrameNavClient, buildRemoteDevframeUrl, connectRemoteDevframe, createDevframeClientHost, createDockRenderersContext, createMessagesClient, getDevframeClientContext, parseRemoteConnection, resolveDockIcon, resolveDockUrl, setDevframeClientContext, stripRemoteConnectionFromUrl };
+export { CLIENT_CONTEXT_KEY, FRAME_NAV_CHANNEL, FRAME_NAV_VERSION, attachFrameNavClient, buildRemoteDevframeUrl, connectRemoteDevframe, createDevframeClientHost, createDockRenderersContext, createMessagesClient, getDevframeClientContext, parseRemoteConnection, resolveDockIcon, resolveDockUrl, setDevframeClientContext, stripRemoteConnectionFromUrl, watchFrameLocation };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@devframes/hub",
   "type": "module",
-  "version": "0.9.0-beta.9",
+  "version": "0.9.0",
   "description": "Hub layer that orchestrates devframe docks, terminals, messages, and commands on any host.",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",
@@ -34,7 +34,7 @@
     "dist"
   ],
   "peerDependencies": {
-    "devframe": "0.9.0-beta.9"
+    "devframe": "0.9.0"
   },
   "dependencies": {
     "@standard-schema/spec": "^1.1.0",
@@ -52,7 +52,7 @@
     "mlly": "^1.8.2",
     "tsdown": "^0.22.14",
     "valibot": "^1.4.2",
-    "devframe": "0.9.0-beta.9"
+    "devframe": "0.9.0"
   },
   "scripts": {
     "build": "tsdown",