@devframes/hub 0.5.4 → 0.6.0-beta.1

package/dist/client/index.d.mts

@@ -1,5 +1,5 @@
-import { E as RemoteConnectionInfo, R as DevframeMessagesClient, d as DevframeDockEntriesGrouped, f as DevframeDockEntry, g as DevframeDockUserEntry } from "../context-Dox-G9vt.mjs";
-import { i as DevframeCommandEntry, n as DevframeClientCommand, o as DevframeCommandKeybinding, t as DevframeDocksUserSettings } from "../settings-Bp5Ax6Os.mjs";
+import { b as DevframeMessagesClient, h as DevframeMessageEntryInput } from "../context-DVh4gk8f.mjs";
+import { O as RemoteConnectionInfo, i as DevframeCommandEntry, m as DevframeDockEntry, n as DevframeClientCommand, o as DevframeCommandKeybinding, p as DevframeDockEntriesGrouped, t as DevframeDocksUserSettings, v as DevframeDockUserEntry } from "../settings-B9YjSEcl.mjs";
 import { DevframeClientRpcHost, DevframeRpcClient, DevframeRpcClientOptions, DevframeRpcContext, RpcClientEvents } from "devframe/client";
 import { EventEmitter } from "devframe/types";
 import { SharedState } from "devframe/utils/shared-state";
@@ -138,7 +138,8 @@ interface DockClientScriptContext extends DocksContext {
    */
   current: DockEntryState;
   /**
-   * Messages client scoped to this dock entry's source
+   * Messages client scoped to this dock entry — messages it adds default
+   * their `category` to the entry id, so the feed can attribute them.
    */
   messages: DevframeMessagesClient;
 }
@@ -149,6 +150,69 @@ declare const CLIENT_CONTEXT_KEY = "__DEVFRAME_HUB_CLIENT_CONTEXT__";
  * Get the global Devframe client context, or `undefined` if not yet initialized.
  */
 declare function getDevframeClientContext(): DevframeClientContext | undefined;
+/**
+ * Publish the global Devframe client context (or clear it with `undefined`).
+ * Called by {@link import('./host').createDevframeClientHost}; a dock client
+ * script or a viewer reads it back with {@link getDevframeClientContext}.
+ */
+declare function setDevframeClientContext(ctx: DevframeClientContext | undefined): void;
+//#endregion
+//#region src/client/host.d.ts
+interface DevframeClientHostOptions {
+  /**
+   * An already-connected RPC client. When omitted, one is created via
+   * `connectDevframe(connect)` — pass `connect.baseURL` to point at the hub's
+   * connection-meta mount (e.g. `/__hub/`).
+   */
+  rpc?: DevframeRpcClient;
+  /** Options forwarded to `connectDevframe` when `rpc` is not supplied. */
+  connect?: DevframeRpcClientOptions;
+  /**
+   * Environment the host runs in.
+   * - `'standalone'` (default) — the runtime owns the whole page (a hub UI).
+   * - `'embedded'` — the runtime lives inside a user app alongside a panel.
+   */
+  clientType?: DockClientType;
+  /**
+   * Import and run the client scripts declared on dock entries (`action`,
+   * `custom-render`, and iframe `clientScript`). Default `true`.
+   */
+  loadClientScripts?: boolean;
+}
+interface DevframeClientHost {
+  /** The assembled, globally-registered client host context. */
+  context: DevframeClientContext;
+  /** Tear down listeners and stop tracking newly-registered client scripts. */
+  dispose: () => void;
+}
+/**
+ * Boot the framework-level client host: connect RPC, assemble the full
+ * {@link DevframeClientContext} (panel, docks, commands, when) from the hub's
+ * shared state, publish it at `__DEVFRAME_HUB_CLIENT_CONTEXT__`, and load every
+ * dock entry's client script into this page — the devframe equivalent of the
+ * runtime `@vitejs/devtools-kit` injects into a host app.
+ *
+ * A viewer keeps rendering its own dock UI (reading the same shared state); this
+ * runtime is what gives plugin client scripts a live host context to run in.
+ */
+declare function createDevframeClientHost(options?: DevframeClientHostOptions): Promise<DevframeClientHost>;
+//#endregion
+//#region src/client/messages.d.ts
+interface MessagesClientOptions {
+  /**
+   * Default fields merged beneath every `add()` input — the client host passes
+   * `{ category: entry.id }` to scope a dock client script's messages to its
+   * entry. Fields set on the input itself win.
+   */
+  defaults?: Partial<DevframeMessageEntryInput>;
+}
+/**
+ * Build a browser-side {@link DevframeMessagesClient} that writes into the
+ * hub's messages subsystem over the `hub:messages:*` built-in RPCs. The handle
+ * returned by `add` proxies `update`/`dismiss` back through the same RPCs, so a
+ * dock client script reports into the very feed the server writes to.
+ */
+declare function createMessagesClient(rpc: DevframeRpcClient, options?: MessagesClientOptions): DevframeMessagesClient;
 //#endregion
 //#region src/client/remote.d.ts
 type ConnectRemoteDevframeOptions = Omit<DevframeRpcClientOptions, 'connectionMeta' | 'authToken'>;
@@ -171,4 +235,4 @@ declare function parseRemoteConnection(input?: string): RemoteConnectionInfo | n
  */
 declare function connectRemoteDevframe(options?: ConnectRemoteDevframeOptions): Promise<DevframeRpcClient>;
 //#endregion
-export { CLIENT_CONTEXT_KEY, CommandsContext, ConnectRemoteDevframeOptions, DevframeClientContext, type DevframeClientRpcHost, DockClientScriptContext, DockClientType, DockEntryState, DockEntryStateEvents, DockPanelStorage, DocksContext, DocksEntriesContext, DocksPanelContext, type RpcClientEvents, WhenClauseContext, connectRemoteDevframe, getDevframeClientContext, parseRemoteConnection };
+export { CLIENT_CONTEXT_KEY, CommandsContext, ConnectRemoteDevframeOptions, DevframeClientContext, DevframeClientHost, DevframeClientHostOptions, type DevframeClientRpcHost, DockClientScriptContext, DockClientType, DockEntryState, DockEntryStateEvents, DockPanelStorage, DocksContext, DocksEntriesContext, DocksPanelContext, MessagesClientOptions, type RpcClientEvents, WhenClauseContext, connectRemoteDevframe, createDevframeClientHost, createMessagesClient, getDevframeClientContext, parseRemoteConnection, setDevframeClientContext };

package/dist/client/index.mjs

@@ -1,5 +1,8 @@
+import { DEFAULT_CATEGORIES_ORDER, DEFAULT_STATE_USER_SETTINGS } from "../constants.mjs";
 import { REMOTE_CONNECTION_KEY } from "devframe/constants";
-import { getDevframeRpcClient } from "devframe/client";
+import { connectDevframe, getDevframeRpcClient } from "devframe/client";
+import { createEventEmitter } from "devframe/utils/events";
+import { destr } from "destr";
 export * from "devframe/client";
 //#region src/client/context.ts
 const CLIENT_CONTEXT_KEY = "__DEVFRAME_HUB_CLIENT_CONTEXT__";
@@ -9,6 +12,282 @@ const CLIENT_CONTEXT_KEY = "__DEVFRAME_HUB_CLIENT_CONTEXT__";
 function getDevframeClientContext() {
 	return globalThis[CLIENT_CONTEXT_KEY];
 }
+/**
+* Publish the global Devframe client context (or clear it with `undefined`).
+* Called by {@link import('./host').createDevframeClientHost}; a dock client
+* script or a viewer reads it back with {@link getDevframeClientContext}.
+*/
+function setDevframeClientContext(ctx) {
+	globalThis[CLIENT_CONTEXT_KEY] = ctx;
+}
+//#endregion
+//#region src/client/messages.ts
+/**
+* Build a browser-side {@link DevframeMessagesClient} that writes into the
+* hub's messages subsystem over the `hub:messages:*` built-in RPCs. The handle
+* returned by `add` proxies `update`/`dismiss` back through the same RPCs, so a
+* dock client script reports into the very feed the server writes to.
+*/
+function createMessagesClient(rpc, options = {}) {
+	const call = rpc.call;
+	function makeHandle(entry) {
+		let current = entry;
+		return {
+			get entry() {
+				return current;
+			},
+			get id() {
+				return current.id;
+			},
+			async update(patch) {
+				const updated = await call("hub:messages:update", current.id, patch);
+				if (updated) current = updated;
+				return updated;
+			},
+			dismiss: () => call("hub:messages:remove", current.id)
+		};
+	}
+	async function add(input) {
+		return makeHandle(await call("hub:messages:add", {
+			...options.defaults,
+			...input
+		}));
+	}
+	function levelShortcut(level) {
+		return (message, extra) => add({
+			...extra,
+			message,
+			level
+		});
+	}
+	return {
+		add,
+		remove: (id) => call("hub:messages:remove", id),
+		clear: () => call("hub:messages:clear"),
+		info: levelShortcut("info"),
+		warn: levelShortcut("warn"),
+		error: levelShortcut("error"),
+		success: levelShortcut("success"),
+		debug: levelShortcut("debug")
+	};
+}
+//#endregion
+//#region src/client/host.ts
+const DOCKS_STATE_KEY = "devframe:docks";
+const COMMANDS_STATE_KEY = "devframe:commands";
+const USER_SETTINGS_STATE_KEY = "devframe:user-settings";
+/**
+* Boot the framework-level client host: connect RPC, assemble the full
+* {@link DevframeClientContext} (panel, docks, commands, when) from the hub's
+* shared state, publish it at `__DEVFRAME_HUB_CLIENT_CONTEXT__`, and load every
+* dock entry's client script into this page — the devframe equivalent of the
+* runtime `@vitejs/devtools-kit` injects into a host app.
+*
+* A viewer keeps rendering its own dock UI (reading the same shared state); this
+* runtime is what gives plugin client scripts a live host context to run in.
+*/
+async function createDevframeClientHost(options = {}) {
+	const clientType = options.clientType ?? "standalone";
+	const rpc = options.rpc ?? await connectDevframe(options.connect);
+	const [docksState, commandsState, settings] = await Promise.all([
+		rpc.sharedState.get(DOCKS_STATE_KEY, { initialValue: [] }),
+		rpc.sharedState.get(COMMANDS_STATE_KEY, { initialValue: [] }),
+		rpc.sharedState.get(USER_SETTINGS_STATE_KEY, { initialValue: DEFAULT_STATE_USER_SETTINGS() })
+	]);
+	let selectedId = null;
+	const entryToStateMap = /* @__PURE__ */ new Map();
+	const panel = createPanelContext(clientType);
+	const docks = createDocksContext();
+	const commands = createCommandsContext();
+	const context = {
+		rpc,
+		clientType,
+		panel,
+		docks,
+		commands,
+		when: { get context() {
+			return {
+				clientType,
+				dockOpen: panel.store.open,
+				paletteOpen: commands.paletteOpen,
+				dockSelectedId: selectedId ?? ""
+			};
+		} }
+	};
+	const disposers = [];
+	reconcileEntries();
+	disposers.push(docksState.on("updated", reconcileEntries));
+	if (getDevframeClientContext()) console.warn("[@devframes/hub] A client host context is already published on this page — replacing it. Boot createDevframeClientHost() once per page (e.g. HTML injection combined with a manual import boots it twice).");
+	setDevframeClientContext(context);
+	const loadedScripts = /* @__PURE__ */ new Set();
+	if (options.loadClientScripts ?? true) {
+		loadClientScripts();
+		disposers.push(docksState.on("updated", loadClientScripts));
+	}
+	return {
+		context,
+		dispose() {
+			for (const off of disposers.splice(0)) off();
+			if (getDevframeClientContext() === context) setDevframeClientContext(void 0);
+		}
+	};
+	function createDockEntryState(entryMeta) {
+		return {
+			entryMeta,
+			get isActive() {
+				return selectedId === entryMeta.id;
+			},
+			domElements: {},
+			events: createEventEmitter()
+		};
+	}
+	function reconcileEntries() {
+		const entries = docksState.value();
+		const seen = /* @__PURE__ */ new Set();
+		for (const meta of entries) {
+			seen.add(meta.id);
+			const existing = entryToStateMap.get(meta.id);
+			if (!existing) entryToStateMap.set(meta.id, createDockEntryState(meta));
+			else if (existing.entryMeta !== meta) {
+				existing.entryMeta = meta;
+				existing.events.emit("entry:updated", meta);
+			}
+		}
+		for (const id of [...entryToStateMap.keys()]) if (!seen.has(id)) entryToStateMap.delete(id);
+		docks.entries = entries;
+		docks.groupedEntries = groupByCategory(entries);
+		if (selectedId && !entryToStateMap.has(selectedId)) selectedId = null;
+	}
+	function createDocksContext() {
+		return {
+			get selectedId() {
+				return selectedId;
+			},
+			set selectedId(id) {
+				switchEntry(id);
+			},
+			get selected() {
+				return selectedId && entryToStateMap.get(selectedId)?.entryMeta || null;
+			},
+			entries: [],
+			entryToStateMap,
+			groupedEntries: [],
+			settings,
+			getStateById: (id) => entryToStateMap.get(id),
+			switchEntry,
+			toggleEntry: (id) => selectedId === id ? switchEntry(null) : switchEntry(id)
+		};
+	}
+	async function switchEntry(id) {
+		const next = id ?? null;
+		if (next === selectedId) return false;
+		if (next !== null && !entryToStateMap.has(next)) return false;
+		const previous = selectedId;
+		selectedId = next;
+		if (previous) entryToStateMap.get(previous)?.events.emit("entry:deactivated");
+		if (next) entryToStateMap.get(next)?.events.emit("entry:activated");
+		return true;
+	}
+	function createCommandsContext() {
+		const clientCommands = /* @__PURE__ */ new Map();
+		function allCommands() {
+			return [...commandsState.value(), ...clientCommands.values()];
+		}
+		return {
+			get commands() {
+				return allCommands();
+			},
+			get paletteCommands() {
+				return allCommands().filter((c) => c.showInPalette !== false);
+			},
+			register(input) {
+				const list = Array.isArray(input) ? input : [input];
+				for (const cmd of list) clientCommands.set(cmd.id, cmd);
+				return () => {
+					for (const cmd of list) clientCommands.delete(cmd.id);
+				};
+			},
+			async execute(id, ...args) {
+				const client = clientCommands.get(id);
+				if (client?.action) return client.action(...args);
+				return rpc.call("hub:commands:execute", id, ...args);
+			},
+			getKeybindings(id) {
+				const override = settings.value().commandShortcuts?.[id];
+				if (override) return override;
+				return allCommands().find((c) => c.id === id)?.keybindings ?? [];
+			},
+			settings,
+			paletteOpen: false
+		};
+	}
+	function clientScriptOf(entry) {
+		return entry.action ?? entry.renderer ?? entry.clientScript;
+	}
+	function loadClientScripts() {
+		for (const entry of docksState.value()) {
+			const script = clientScriptOf(entry);
+			if (!script?.importFrom || loadedScripts.has(entry.id)) continue;
+			loadedScripts.add(entry.id);
+			runClientScript(entry.id, script);
+		}
+	}
+	async function runClientScript(entryId, script) {
+		try {
+			const fn = (await import(
+				/* @vite-ignore */
+				/* webpackIgnore: true */
+				/* turbopackIgnore: true */
+				script.importFrom
+))[script.importName ?? "default"];
+			if (typeof fn !== "function") return;
+			const current = entryToStateMap.get(entryId);
+			if (!current) return;
+			const messages = createMessagesClient(rpc, { defaults: { category: entryId } });
+			await fn({
+				...context,
+				current,
+				messages
+			});
+		} catch (error) {
+			loadedScripts.delete(entryId);
+			console.error(`[@devframes/hub] failed to load client script for "${entryId}" from ${script.importFrom}`, error);
+		}
+	}
+}
+function createPanelContext(clientType) {
+	const store = {
+		mode: "edge",
+		width: 480,
+		height: 360,
+		top: 0,
+		left: 0,
+		position: "right",
+		open: clientType === "standalone",
+		inactiveTimeout: 0
+	};
+	return {
+		store,
+		isDragging: false,
+		isResizing: false,
+		get isVertical() {
+			return store.position === "left" || store.position === "right";
+		}
+	};
+}
+function groupByCategory(entries) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const entry of entries) {
+		const category = entry.category ?? "default";
+		let list = groups.get(category);
+		if (!list) {
+			list = [];
+			groups.set(category, list);
+		}
+		list.push(entry);
+	}
+	return [...groups.entries()].sort(([a], [b]) => (DEFAULT_CATEGORIES_ORDER[a] ?? 0) - (DEFAULT_CATEGORIES_ORDER[b] ?? 0));
+}
 //#endregion
 //#region src/client/remote.ts
 function base64UrlDecode(value) {
@@ -64,7 +343,7 @@ function parseRemoteConnection(input) {
 	if (!encoded) return null;
 	let payload;
 	try {
-		payload = JSON.parse(base64UrlDecode(encoded));
+		payload = destr(base64UrlDecode(encoded), { strict: true });
 	} catch (cause) {
 		throw new Error("[@devframes/hub] Failed to decode remote connection descriptor.", { cause });
 	}
@@ -95,4 +374,4 @@ async function connectRemoteDevframe(options = {}) {
 	});
 }
 //#endregion
-export { CLIENT_CONTEXT_KEY, connectRemoteDevframe, getDevframeClientContext, parseRemoteConnection };
+export { CLIENT_CONTEXT_KEY, connectRemoteDevframe, createDevframeClientHost, createMessagesClient, getDevframeClientContext, parseRemoteConnection, setDevframeClientContext };

package/dist/constants.d.mts

@@ -1,4 +1,4 @@
-import { t as DevframeDocksUserSettings } from "./settings-Bp5Ax6Os.mjs";
+import { t as DevframeDocksUserSettings } from "./settings-B9YjSEcl.mjs";
 export * from "devframe/constants";
 
 //#region src/constants.d.ts