@devframes/hub 0.5.0 → 0.5.2

package/dist/client/index.d.mts

@@ -0,0 +1,174 @@
+import { L as DevframeMessagesClient, T as RemoteConnectionInfo, d as DevframeDockEntriesGrouped, f as DevframeDockEntry, g as DevframeDockUserEntry } from "../context-BGXfnFEd.mjs";
+import { i as DevframeCommandEntry, n as DevframeClientCommand, o as DevframeCommandKeybinding, t as DevframeDocksUserSettings } from "../settings-Bp5Ax6Os.mjs";
+import { DevframeClientRpcHost, DevframeRpcClient, DevframeRpcClientOptions, DevframeRpcContext, RpcClientEvents } from "devframe/client";
+import { EventEmitter } from "devframe/types";
+import { SharedState } from "devframe/utils/shared-state";
+import { WhenContext } from "devframe/utils/when";
+export * from "devframe/client";
+
+//#region src/client/docks.d.ts
+interface DockPanelStorage {
+  mode: 'float' | 'edge';
+  width: number;
+  height: number;
+  top: number;
+  left: number;
+  position: 'left' | 'right' | 'bottom' | 'top';
+  open: boolean;
+  inactiveTimeout: number;
+}
+type DockClientType = 'embedded' | 'standalone';
+interface DocksContext extends DevframeRpcContext {
+  /**
+   * Type of the client environment
+   *
+   * 'embedded' - running inside an embedded floating panel
+   * 'standalone' - running inside a standalone window (no user app)
+   */
+  readonly clientType: 'embedded' | 'standalone';
+  /**
+   * The panel context
+   */
+  readonly panel: DocksPanelContext;
+  /**
+   * The docks entries context
+   */
+  readonly docks: DocksEntriesContext;
+  /**
+   * The commands context for command palette and shortcuts
+   */
+  readonly commands: CommandsContext;
+  /**
+   * The when-clause context for conditional visibility
+   */
+  readonly when: WhenClauseContext;
+}
+interface WhenClauseContext {
+  /**
+   * Get the current when-clause context snapshot.
+   * Returns a reactive object with built-in variables and any custom plugin variables.
+   */
+  readonly context: WhenContext;
+}
+type DevframeClientContext = DocksContext;
+interface DocksPanelContext {
+  store: DockPanelStorage;
+  isDragging: boolean;
+  isResizing: boolean;
+  readonly isVertical: boolean;
+}
+interface DocksEntriesContext {
+  selectedId: string | null;
+  readonly selected: DevframeDockEntry | null;
+  entries: DevframeDockEntry[];
+  entryToStateMap: Map<string, DockEntryState>;
+  groupedEntries: DevframeDockEntriesGrouped;
+  settings: SharedState<DevframeDocksUserSettings>;
+  /**
+   * Get the state of a dock entry by its ID
+   */
+  getStateById: (id: string) => DockEntryState | undefined;
+  /**
+   * Switch to the selected dock entry, pass `null` to clear the selection
+   *
+   * @returns Whether the selection was changed successfully
+   */
+  switchEntry: (id?: string | null) => Promise<boolean>;
+  /**
+   * Toggle the selected dock entry
+   *
+   * @returns Whether the selection was changed successfully
+   */
+  toggleEntry: (id: string) => Promise<boolean>;
+}
+interface DockEntryState {
+  entryMeta: DevframeDockEntry;
+  readonly isActive: boolean;
+  domElements: {
+    iframe?: HTMLIFrameElement | null;
+    panel?: HTMLDivElement | null;
+  };
+  events: EventEmitter<DockEntryStateEvents>;
+}
+interface DockEntryStateEvents {
+  'entry:activated': () => void;
+  'entry:deactivated': () => void;
+  'entry:updated': (newMeta: DevframeDockUserEntry) => void;
+  'dom:panel:mounted': (panel: HTMLDivElement) => void;
+  'dom:iframe:mounted': (iframe: HTMLIFrameElement) => void;
+}
+interface CommandsContext {
+  /**
+   * All commands (server + client)
+   */
+  readonly commands: DevframeCommandEntry[];
+  /**
+   * Palette-visible commands only (filtered by `showInPalette !== false`)
+   */
+  readonly paletteCommands: DevframeCommandEntry[];
+  /**
+   * Register client-side command(s). Returns cleanup function.
+   */
+  register: (cmd: DevframeClientCommand | DevframeClientCommand[]) => () => void;
+  /**
+   * Execute a command by ID. Delegates to RPC for server commands.
+   */
+  execute: (id: string, ...args: any[]) => Promise<unknown>;
+  /**
+   * Get effective keybindings for a command (defaults merged with overrides)
+   */
+  getKeybindings: (id: string) => DevframeCommandKeybinding[];
+  /**
+   * User settings store (persisted, includes command shortcuts)
+   */
+  settings: SharedState<DevframeDocksUserSettings>;
+  /**
+   * Whether the command palette is open
+   */
+  paletteOpen: boolean;
+}
+//#endregion
+//#region src/client/client-script.d.ts
+/**
+ * Context for client scripts running in dock entries
+ */
+interface DockClientScriptContext extends DocksContext {
+  /**
+   * The state of the current dock entry
+   */
+  current: DockEntryState;
+  /**
+   * Messages client scoped to this dock entry's source
+   */
+  messages: DevframeMessagesClient;
+}
+//#endregion
+//#region src/client/context.d.ts
+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;
+//#endregion
+//#region src/client/remote.d.ts
+type ConnectRemoteDevframeOptions = Omit<DevframeRpcClientOptions, 'connectionMeta' | 'authToken'>;
+/**
+ * Parse a {@link RemoteConnectionInfo} descriptor from the current page's URL
+ * (or a provided URL/string). Checks the URL fragment first, then the query.
+ *
+ * Returns `null` if no descriptor is present.
+ * Throws if the descriptor is malformed or its schema version is unsupported.
+ */
+declare function parseRemoteConnection(input?: string): RemoteConnectionInfo | null;
+/**
+ * One-liner for a hosted Devframe page: reads the connection descriptor from
+ * the current URL and returns a connected {@link DevframeRpcClient}.
+ *
+ * Pairs with `remote: true` on a `DevframeViewIframe` registered on the node
+ * side — the hub injects the descriptor into the iframe URL.
+ *
+ * @throws if no descriptor is present in the URL.
+ */
+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 };

package/dist/client/index.mjs

@@ -0,0 +1,98 @@
+import { REMOTE_CONNECTION_KEY } from "devframe/constants";
+import { getDevframeRpcClient } from "devframe/client";
+export * from "devframe/client";
+//#region src/client/context.ts
+const CLIENT_CONTEXT_KEY = "__DEVFRAME_HUB_CLIENT_CONTEXT__";
+/**
+* Get the global Devframe client context, or `undefined` if not yet initialized.
+*/
+function getDevframeClientContext() {
+	return globalThis[CLIENT_CONTEXT_KEY];
+}
+//#endregion
+//#region src/client/remote.ts
+function base64UrlDecode(value) {
+	const padLen = (4 - value.length % 4) % 4;
+	const padded = value.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat(padLen);
+	const binary = atob(padded);
+	const bytes = new Uint8Array(binary.length);
+	for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+	return new TextDecoder().decode(bytes);
+}
+function extractKeyFromFragment(hash) {
+	if (!hash) return null;
+	const raw = hash.startsWith("#") ? hash.slice(1) : hash;
+	const queryIdx = raw.indexOf("?");
+	if (queryIdx !== -1) {
+		const value = new URLSearchParams(raw.slice(queryIdx + 1)).get(REMOTE_CONNECTION_KEY);
+		if (value) return value;
+	}
+	for (const part of raw.split("&")) {
+		const [k, v = ""] = part.split("=");
+		if (k === REMOTE_CONNECTION_KEY) return decodeURIComponent(v);
+	}
+	return null;
+}
+function extractKeyFromQuery(search) {
+	if (!search) return null;
+	return new URLSearchParams(search.startsWith("?") ? search.slice(1) : search).get(REMOTE_CONNECTION_KEY);
+}
+/**
+* Parse a {@link RemoteConnectionInfo} descriptor from the current page's URL
+* (or a provided URL/string). Checks the URL fragment first, then the query.
+*
+* Returns `null` if no descriptor is present.
+* Throws if the descriptor is malformed or its schema version is unsupported.
+*/
+function parseRemoteConnection(input) {
+	let hash = "";
+	let search = "";
+	if (input === void 0) {
+		if (typeof location === "undefined") return null;
+		hash = location.hash;
+		search = location.search;
+	} else try {
+		const parsed = new URL(input, "http://_");
+		hash = parsed.hash;
+		search = parsed.search;
+	} catch {
+		if (input.startsWith("#")) hash = input;
+		else if (input.startsWith("?")) search = input;
+		else return null;
+	}
+	const encoded = extractKeyFromFragment(hash) ?? extractKeyFromQuery(search);
+	if (!encoded) return null;
+	let payload;
+	try {
+		payload = JSON.parse(base64UrlDecode(encoded));
+	} catch (cause) {
+		throw new Error("[@devframes/hub] Failed to decode remote connection descriptor.", { cause });
+	}
+	if (!payload || typeof payload !== "object") throw new Error("[@devframes/hub] Remote connection descriptor must be an object.");
+	const info = payload;
+	if (info.v !== 1) throw new Error(`[@devframes/hub] Unsupported remote connection descriptor version: ${String(info.v)}`);
+	if (info.backend !== "websocket" || typeof info.websocket !== "string" || !info.websocket) throw new Error("[@devframes/hub] Remote connection descriptor must carry a websocket URL.");
+	if (typeof info.authToken !== "string" || !info.authToken) throw new Error("[@devframes/hub] Remote connection descriptor must carry an auth token.");
+	if (typeof info.origin !== "string") throw new Error("[@devframes/hub] Remote connection descriptor must carry an origin.");
+	return info;
+}
+/**
+* One-liner for a hosted Devframe page: reads the connection descriptor from
+* the current URL and returns a connected {@link DevframeRpcClient}.
+*
+* Pairs with `remote: true` on a `DevframeViewIframe` registered on the node
+* side — the hub injects the descriptor into the iframe URL.
+*
+* @throws if no descriptor is present in the URL.
+*/
+async function connectRemoteDevframe(options = {}) {
+	const info = parseRemoteConnection();
+	if (!info) throw new Error("[@devframes/hub] No remote connection descriptor found in the URL. Open this page through a hub-registered dock with `remote: true`.");
+	return getDevframeRpcClient({
+		...options,
+		connectionMeta: info,
+		authToken: info.authToken
+	});
+}
+//#endregion
+export { CLIENT_CONTEXT_KEY, connectRemoteDevframe, getDevframeClientContext, parseRemoteConnection };

package/dist/constants.d.mts

@@ -0,0 +1,8 @@
+import { t as DevframeDocksUserSettings } from "./settings-Bp5Ax6Os.mjs";
+export * from "devframe/constants";
+
+//#region src/constants.d.ts
+declare const DEFAULT_CATEGORIES_ORDER: Record<string, number>;
+declare const DEFAULT_STATE_USER_SETTINGS: () => DevframeDocksUserSettings;
+//#endregion
+export { DEFAULT_CATEGORIES_ORDER, DEFAULT_STATE_USER_SETTINGS };

package/dist/constants.mjs

@@ -0,0 +1,21 @@
+export * from "devframe/constants";
+//#region src/constants.ts
+const DEFAULT_CATEGORIES_ORDER = {
+	"default": 0,
+	"app": 100,
+	"framework": 200,
+	"web": 300,
+	"advanced": 400,
+	"~builtin": 1e3
+};
+const DEFAULT_STATE_USER_SETTINGS = () => ({
+	docksHidden: [],
+	docksCategoriesHidden: [],
+	docksPinned: [],
+	docksCustomOrder: {},
+	showIframeAddressBar: false,
+	closeOnOutsideClick: false,
+	commandShortcuts: {}
+});
+//#endregion
+export { DEFAULT_CATEGORIES_ORDER, DEFAULT_STATE_USER_SETTINGS };