@wippy-fe/types-global-proxy 0.0.15 → 0.0.17

package/README.md

@@ -0,0 +1,39 @@
+# @wippy-fe/types-global-proxy
+
+TypeScript ambient declarations for the Wippy iframe proxy globals.
+
+## Installation
+
+```bash
+npm install -D @wippy-fe/types-global-proxy
+```
+
+## What it declares
+
+- `window.getWippyApi()` — returns `Promise<ProxyApiInstance>`
+- `window.$W.*` — lazy async accessors for `config`, `api`, `host`, `on`, `state`, `ws`, `loadWebComponent`
+- `window.__WIPPY_APP_CONFIG__` — `AppConfig`
+- `window.__WIPPY_APP_API__` — `ProxyApiInstance`
+- `window.__WIPPY_PROXY_CONFIG__` — `ProxyConfig`
+
+## Exported types
+
+`ProxyApiInstance`, `AppConfig`, `AppFeatures`, `AppCustomization`, `StateApi`, `ProxyWsApi`, `WsMessage`, `WsCommand`, `Artifact`, `PageApi`, `UploadApi`, `ApiRoutes`, and all WebSocket message/topic types.
+
+## Usage
+
+Add to your `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["@wippy-fe/types-global-proxy"]
+  }
+}
+```
+
+Or use a triple-slash reference:
+
+```typescript
+/// <reference types="@wippy-fe/types-global-proxy" />
+```

package/index.d.ts

@@ -4,6 +4,286 @@ import { ConfirmationOptions } from 'primevue/confirmationoptions';
 import { ToastMessageOptions } from 'primevue/toast';
 import * as tailwindcss_types_config from 'tailwindcss/types/config';
 
+var session = {
+	type: "non-persistent"
+};
+var history = "browser";
+var env = {
+	APP_API_URL: "",
+	APP_AUTH_API_URL: "",
+	APP_WEBSOCKET_URL: ""
+};
+var featureRS = {
+	session: session,
+	history: history,
+	env: env
+};
+
+var chat = {
+	emptyState: {
+		title: "No chat session selected",
+		description: "Please select a session from the dropdown above or start a new conversation.",
+		goToHome: "Go to Home Page",
+		loadingAgents: "Loading agents...",
+		selectAgent: "Select Agent",
+		startChat: "Start Chat",
+		startChatError: "Failed to start chat",
+		noAgents: "No agents available. Please contact your administrator.",
+		dropFiles: "Drop files here to upload"
+	}
+};
+var customPage = {
+	loading: {
+		title: "Loading page content..."
+	},
+	error: {
+		title: "Failed to load page content"
+	}
+};
+var home = {
+	loading: "Application is Loading",
+	error: {
+		title: "Error Loading Application"
+	},
+	noHomePage: {
+		title: "No Home Page Detected",
+		message: "Probably backend configuration is malformed"
+	}
+};
+var app = {
+	title: "Wippy App",
+	appName: "Wippy",
+	icon: "wippy:logo"
+};
+var login = {
+	error: {
+		title: "Session Token Expired",
+		description: "Your session has expired or is no longer valid. Please close this window and log in again to continue."
+	}
+};
+var logout = {
+	title: "Logout",
+	description: "Logging out..."
+};
+var keeper = {
+	controls: {
+		newChat: "New Chat",
+		searchAgents: "Search agents...",
+		undo: "Undo",
+		redo: "Redo",
+		download: "Registry To File System",
+		upload: "File System To Registry",
+		codeAssistant: "Wippy Code Assistant",
+		syncControls: "Sync Controls",
+		confirmUpload: {
+			title: "Confirm Upload",
+			message: "Do you wish to upload file system changes to registry? This will overwrite current state",
+			cancel: "Cancel",
+			upload: "Upload",
+			cancelled: {
+				title: "Upload cancelled",
+				message: "The upload operation was cancelled"
+			}
+		}
+	},
+	version: {
+		label: "Version:",
+		tooltip: "Version {{version}}"
+	}
+};
+var textRS = {
+	chat: chat,
+	customPage: customPage,
+	home: home,
+	app: app,
+	login: login,
+	logout: logout,
+	keeper: keeper
+};
+
+type I18NFeatureTypes = typeof featureRS;
+type I18NTextTypes = typeof textRS;
+
+/**
+ * All API route templates, grouped by domain.
+ * Dynamic path segments use `{paramName}` placeholders (OpenAPI-style).
+ * Each leaf value is a flat, fully-formed route — no concatenation needed at call site.
+ *
+ * Internally, routes use `@/…` shorthand that resolves against the group's `@prefix`.
+ * Resolution happens once inside `getApiRoutes()`, so consumers always receive clean strings.
+ *
+ * Base URL resolution:
+ * - HTTP routes: `getEnv().APP_API_URL` + route  (handled by axios baseURL)
+ * - WebSocket:   `getEnv().APP_WEBSOCKET_URL` + `getApiRoutes().ws.join`  (composed in ws/client.ts)
+ */
+interface ApiRoutes {
+    agents: {
+        list: string;
+        details: string;
+        byName: string;
+    };
+    sessions: {
+        list: string;
+        get: string;
+        messages: string;
+    };
+    models: {
+        list: string;
+        byName: string;
+    };
+    uploads: {
+        list: string;
+        get: string;
+        create: string;
+    };
+    artifacts: {
+        get: string;
+        content: string;
+        state: string;
+        baseUrl: string;
+    };
+    pages: {
+        list: string;
+        get: string;
+        content: string;
+        baseUrl: string;
+    };
+    registry: {
+        namespaces: string;
+        entries: string;
+        entry: string;
+        entryCreate: string;
+        entryEditors: string;
+        versions: string;
+        versionApply: string;
+    };
+    keeperSync: {
+        state: string;
+        download: string;
+        upload: string;
+        undo: string;
+        redo: string;
+    };
+    components: {
+        list: string;
+    };
+    tools: {
+        byName: string;
+    };
+    ws: {
+        join: string;
+    };
+}
+/**
+ * Override type for `AppConfig.feature.apiRoutes`.
+ *
+ * Each group is optional and partially overridable.
+ * Set `@prefix` to rebase all `@/…` routes in that group at once,
+ * or override individual routes with absolute paths.
+ */
+type ApiRoutesOverride = {
+    [K in keyof ApiRoutes]?: Partial<ApiRoutes[K]> & {
+        '@prefix'?: string;
+    };
+};
+
+interface AppFeatures extends I18NFeatureTypes {
+    /**
+     * If to remember auth details or not
+     */
+    session: {
+        type: 'non-persistent' | 'cookie';
+    };
+    history: 'browser' | 'hash';
+    env: {
+        APP_API_URL: string;
+        APP_AUTH_API_URL: string;
+        APP_WEBSOCKET_URL: string;
+    };
+    axiosDefaults?: Partial<AxiosDefaults>;
+    routePrefix?: string;
+    showAdmin?: boolean;
+    allowSelectModel?: boolean;
+    startNavOpen?: boolean;
+    hideNavBar?: boolean;
+    disableRightPanel?: boolean;
+    /**
+     * Hide the session selector dropdown in chat views
+     * @default false
+     */
+    hideSessionSelector?: boolean;
+    additionalNavItems?: Array<PageApi.Page>;
+    chat?: {
+        convertPasteToFile?: {
+            enabled: boolean;
+            minFileSize: number;
+            allowHtml: boolean;
+        };
+    };
+    apiRoutes?: ApiRoutesOverride;
+    /**
+     * Additional HTML tags to whitelist in the sanitizer.
+     * Map of tag name to allowed attribute names.
+     * 'class' is always implicitly allowed for every tag.
+     */
+    allowAdditionalTags?: Record<string, string[]>;
+    /**
+     * LRU cache configuration for child iframe state preservation.
+     * @default { maxPages: 50, maxSizePerPage: 2097152 }
+     */
+    stateCache?: {
+        /** Maximum number of page/artifact state buckets to keep. @default 50 */
+        maxPages?: number;
+        /** Maximum JSON-serialized size per page in bytes. @default 2097152 (2 MB) */
+        maxSizePerPage?: number;
+    };
+}
+interface AppAuthConfig {
+    token: string;
+    expiresAt: string;
+}
+interface CssVariablesMap {
+    [key: string]: string | Record<string, string> | undefined;
+    '@dark'?: Record<string, string>;
+    '@light'?: Record<string, string>;
+}
+interface AppCustomization {
+    customCSS?: string;
+    cssVariables?: CssVariablesMap;
+    i18n?: Partial<I18NTextTypes>;
+    icons?: Record<string, {
+        body: string;
+        width: number;
+        height: number;
+    }>;
+}
+type DeepPartial<T> = T extends object ? {
+    [P in keyof T]?: DeepPartial<T[P]>;
+} : T;
+interface AppConfigOverrides {
+    customization?: Partial<AppCustomization>;
+    feature?: DeepPartial<AppFeatures>;
+}
+interface AppConfig {
+    artifactId?: string;
+    /**
+     * Starting app or artifact/page path
+     */
+    path?: string;
+    /**
+     * App features like history mode, session type, etc.
+     */
+    feature?: AppFeatures;
+    /**
+     * Auth configuration
+     */
+    auth: AppAuthConfig;
+    /**
+     * App customization like i18n texts, css variables, custom css, etc.
+     */
+    customization?: AppCustomization;
+}
+
 declare namespace PageApi {
     interface Page {
         icon: string;
@@ -23,6 +303,8 @@ declare namespace PageApi {
         content_version?: string;
         /** The content of the page artifact, which can be HTML, Markdown, or JSON with wippy specific package.json info */
         content_type?: 'text/html' | 'text/markdown' | 'application/json';
+        /** Per-page config overrides — merged into AppConfig before CSS injection. Populated from registry entry config_overrides. */
+        configOverrides?: AppConfigOverrides;
     }
     interface PagesResponse {
         count: number;
@@ -207,507 +489,300 @@ interface WsTopicTypes {
     /**
      * Upload was created or updated
      */
-    Upload: `${typeof WsTopicPrefixes.Upload}:${string}`;
-}
-type WsTopic = WsTopicTypes[keyof WsTopicTypes];
-declare enum WsMessageType {
-    /** Contains the actual content of the message */
-    CONTENT = "content",
-    /** Contains content of the message to append to current one */
-    CHUNK = "chunk",
-    /** User message with contents */
-    USER = "received",
-    /** Response started, can create a message placeholder */
-    RESPONSE_STARTED = "response_started",
-    /** Kill the message */
-    INVALIDATE = "invalidate",
-    /** from to agent, get agent names */
-    DELEGATION = "delegation",
-    /** Tool/fn was called */
-    TOOL_CALL = "tool_call",
-    FUNCTION_CALL = "function_call",
-    /** Tool/fn was succesfull */
-    TOOL_SUCCESS = "tool_success",
-    FUNCTION_SUCCESS = "function_success",
-    /** Tool/fn failed */
-    TOOL_ERROR = "tool_error",
-    FUNCTION_ERROR = "function_error",
-    /** Error */
-    ERROR = "error",
-    /** Error */
-    ARTIFACT = "artifact"
-}
-interface WsMessageBase {
-    topic: WsTopic;
-    data?: {
-        request_id?: string;
-    };
-}
-interface WsMessage_Welcome extends WsMessageBase {
-    topic: WsTopicTypes['Welcome'];
-    data: {
-        request_id?: string;
-        active_session_ids: Array<string>;
-        active_sessions: number;
-        client_count: number;
-        user_id: string;
-    };
-}
-interface WsMessage_Action extends WsMessageBase {
-    topic: WsTopicTypes['Action'];
-    data: {
-        request_id?: string;
-        artifact_uuid?: string;
-        artifact_content_type?: string;
-        session_uuid?: string;
-        path?: string;
-    };
-}
-interface WsMessage_Registry extends WsMessageBase {
-    topic: WsTopicTypes['Registry'];
-    data: {
-        request_id?: string;
-    };
-}
-interface WsMessage_RegistryEntry extends WsMessageBase {
-    topic: WsTopicTypes['RegistryEntry'];
-    data: {
-        request_id?: string;
-        content_version?: string;
-    };
-}
-interface WsMessage_Pages extends WsMessageBase {
-    topic: WsTopicTypes['Pages'];
-}
-interface WsMessage_Page extends WsMessageBase {
-    topic: WsTopicTypes['Page'];
-    data: PageApi.Page & {
-        request_id?: string;
-    };
-}
-interface WsMessage_SessionOpen extends WsMessageBase {
-    topic: WsTopicTypes['SessionOpened'];
-    data: {
-        request_id?: string;
-        active_session_ids: Array<string>;
-        session_id: string;
-    };
-}
-interface WsMessage_Error extends WsMessageBase {
-    topic: WsTopicTypes['Error'];
-    data: {
-        request_id?: string;
-        error: string;
-        message: string;
-    };
-}
-interface WsMessage_SessionClosed extends WsMessageBase {
-    topic: WsTopicTypes['SessionClosed'];
-    data: {
-        request_id?: string;
-        active_session_ids: Array<string>;
-        session_id: string;
-    };
-}
-interface WsMessageDataBase {
-    type: WsMessageType;
-}
-interface WsMessageDataChunk extends WsMessageDataBase {
-    type: WsMessageType.CHUNK;
-    content: string;
-}
-interface WsMessageDataContent extends WsMessageDataBase {
-    type: WsMessageType.CONTENT;
-    content: string;
-    message_id: MessageUUID;
-    file_uuids?: string[];
-}
-interface WsMessageDataUser extends WsMessageDataBase {
-    type: WsMessageType.USER;
-    text: string;
-    message_id: MessageUUID;
-    file_uuids?: string[];
-}
-interface WsMessageDataDelegation extends WsMessageDataBase {
-    type: WsMessageType.DELEGATION;
-    from: string;
-    to: string;
-}
-interface WsMessageDataInvalidate extends WsMessageDataBase {
-    type: WsMessageType.INVALIDATE;
-}
-interface WsMessageDataStarted extends WsMessageDataBase {
-    type: WsMessageType.RESPONSE_STARTED;
-    message_id: MessageUUID;
-}
-interface WsMessageDataToolCall extends WsMessageDataBase {
-    type: WsMessageType.TOOL_CALL | WsMessageType.FUNCTION_CALL;
-    function_name: string;
-    artifact_id?: string;
-}
-interface WsMessageDataArtifact extends WsMessageDataBase {
-    type: WsMessageType.ARTIFACT;
-    artifact_id?: string;
-}
-interface WsMessageDataToolSuccess extends WsMessageDataBase {
-    type: WsMessageType.TOOL_SUCCESS | WsMessageType.FUNCTION_SUCCESS;
-    function_name: string;
-    artifact_id?: string;
-}
-interface WsMessageDataToolError extends WsMessageDataBase {
-    type: WsMessageType.TOOL_ERROR | WsMessageType.FUNCTION_ERROR;
-    function_name: string;
-    artifact_id?: string;
-}
-interface WsMessageDataError extends WsMessageDataBase {
-    type: WsMessageType.ERROR;
-    message: string;
-    code: string;
+    Upload: `${typeof WsTopicPrefixes.Upload}:${string}`;
 }
-interface WsMessage_SessionMessage extends WsMessageBase {
-    topic: WsTopicTypes['SessionMessage'];
-    data: (WsMessageDataUser | WsMessageDataContent | WsMessageDataChunk | WsMessageDataDelegation | WsMessageDataToolCall | WsMessageDataError | WsMessageDataInvalidate | WsMessageDataStarted | WsMessageDataToolSuccess | WsMessageDataArtifact | WsMessageDataToolError) & {
+type WsTopic = WsTopicTypes[keyof WsTopicTypes];
+declare enum WsMessageType {
+    /** Contains the actual content of the message */
+    CONTENT = "content",
+    /** Contains content of the message to append to current one */
+    CHUNK = "chunk",
+    /** User message with contents */
+    USER = "received",
+    /** Response started, can create a message placeholder */
+    RESPONSE_STARTED = "response_started",
+    /** Kill the message */
+    INVALIDATE = "invalidate",
+    /** from to agent, get agent names */
+    DELEGATION = "delegation",
+    /** Tool/fn was called */
+    TOOL_CALL = "tool_call",
+    FUNCTION_CALL = "function_call",
+    /** Tool/fn was succesfull */
+    TOOL_SUCCESS = "tool_success",
+    FUNCTION_SUCCESS = "function_success",
+    /** Tool/fn failed */
+    TOOL_ERROR = "tool_error",
+    FUNCTION_ERROR = "function_error",
+    /** Error */
+    ERROR = "error",
+    /** Error */
+    ARTIFACT = "artifact"
+}
+interface WsMessageBase {
+    topic: WsTopic;
+    data?: {
         request_id?: string;
     };
 }
-interface WsMessage_Session extends WsMessageBase {
-    topic: WsTopicTypes['Session'];
+interface WsMessage_Welcome extends WsMessageBase {
+    topic: WsTopicTypes['Welcome'];
     data: {
         request_id?: string;
-        agent?: string;
-        last_message_date?: number;
-        model?: string;
-        status?: string;
-        title?: string;
-        type: 'update';
-        public_meta?: Array<{
-            icon?: string;
-            id: string;
-            title: string;
-            url?: string;
-        }>;
+        active_session_ids: Array<string>;
+        active_sessions: number;
+        client_count: number;
+        user_id: string;
     };
 }
-interface WsMessage_Artifact extends WsMessageBase {
-    topic: WsTopicTypes['Artifact'];
-    data: Partial<Artifact> & {
+interface WsMessage_Action extends WsMessageBase {
+    topic: WsTopicTypes['Action'];
+    data: {
         request_id?: string;
+        artifact_uuid?: string;
+        artifact_content_type?: string;
+        session_uuid?: string;
+        path?: string;
     };
 }
-interface WsMessage_Upload extends WsMessageBase {
-    topic: WsTopicTypes['Upload'];
-    data: UploadApi.Upload & {
+interface WsMessage_Registry extends WsMessageBase {
+    topic: WsTopicTypes['Registry'];
+    data: {
         request_id?: string;
     };
 }
-type WsMessage = WsMessage_Welcome | WsMessage_Pages | WsMessage_Page | WsMessage_SessionMessage | WsMessage_Session | WsMessage_SessionClosed | WsMessage_Error | WsMessage_Artifact | WsMessage_SessionOpen | WsMessage_Action | WsMessage_Registry | WsMessage_RegistryEntry | WsMessage_Upload;
-
-type KnownTopics = '@history' | '@visibility' | '@message' | '@state-error';
-type Events = {
-    /** Emitted when pages are updated */
-    '@history': (data: {
-        path: string;
-    }) => void;
-    '@visibility': (visible: boolean) => void;
-    '@message': (data: WsMessage) => void;
-    '@state-error': (data: {
-        error: string;
-        key?: string;
-    }) => void;
-} & {
-    [K in string as K extends KnownTopics ? never : K]: (data: WsMessage) => void;
-};
-declare function createEvents(): <T extends string>(topicPattern: T, callback: T extends KnownTopics ? Events[T] : Events["@message"]) => nanoevents.Unsubscribe;
-
-interface StateApiOptions {
-    /** Override the default page-level scope. Used by web components with persist-key or nested artifacts. */
-    scope?: string;
-}
-interface StateApi {
-    get: <T = unknown>(key: string, options?: StateApiOptions) => Promise<T | null>;
-    set: (key: string, value: unknown, options?: StateApiOptions) => Promise<void>;
-    remove: (key: string, options?: StateApiOptions) => Promise<void>;
-    clear: (options?: StateApiOptions) => Promise<void>;
-    getAll: (options?: StateApiOptions) => Promise<Record<string, unknown>>;
-}
-
-var session = {
-	type: "non-persistent"
-};
-var history = "browser";
-var env = {
-	APP_API_URL: "",
-	APP_AUTH_API_URL: "",
-	APP_WEBSOCKET_URL: ""
-};
-var featureRS = {
-	session: session,
-	history: history,
-	env: env
-};
-
-var chat = {
-	emptyState: {
-		title: "No chat session selected",
-		description: "Please select a session from the dropdown above or start a new conversation.",
-		goToHome: "Go to Home Page",
-		loadingAgents: "Loading agents...",
-		selectAgent: "Select Agent",
-		startChat: "Start Chat",
-		startChatError: "Failed to start chat",
-		noAgents: "No agents available. Please contact your administrator.",
-		dropFiles: "Drop files here to upload"
-	}
-};
-var customPage = {
-	loading: {
-		title: "Loading page content..."
-	},
-	error: {
-		title: "Failed to load page content"
-	}
-};
-var home = {
-	loading: "Application is Loading",
-	error: {
-		title: "Error Loading Application"
-	},
-	noHomePage: {
-		title: "No Home Page Detected",
-		message: "Probably backend configuration is malformed"
-	}
-};
-var app = {
-	title: "Wippy App",
-	appName: "Wippy",
-	icon: "wippy:logo"
-};
-var login = {
-	error: {
-		title: "Session Token Expired",
-		description: "Your session has expired or is no longer valid. Please close this window and log in again to continue."
-	}
-};
-var logout = {
-	title: "Logout",
-	description: "Logging out..."
-};
-var keeper = {
-	controls: {
-		newChat: "New Chat",
-		searchAgents: "Search agents...",
-		undo: "Undo",
-		redo: "Redo",
-		download: "Registry To File System",
-		upload: "File System To Registry",
-		codeAssistant: "Wippy Code Assistant",
-		syncControls: "Sync Controls",
-		confirmUpload: {
-			title: "Confirm Upload",
-			message: "Do you wish to upload file system changes to registry? This will overwrite current state",
-			cancel: "Cancel",
-			upload: "Upload",
-			cancelled: {
-				title: "Upload cancelled",
-				message: "The upload operation was cancelled"
-			}
-		}
-	},
-	version: {
-		label: "Version:",
-		tooltip: "Version {{version}}"
-	}
-};
-var textRS = {
-	chat: chat,
-	customPage: customPage,
-	home: home,
-	app: app,
-	login: login,
-	logout: logout,
-	keeper: keeper
-};
-
-type I18NFeatureTypes = typeof featureRS;
-type I18NTextTypes = typeof textRS;
-
-/**
- * All API route templates, grouped by domain.
- * Dynamic path segments use `{paramName}` placeholders (OpenAPI-style).
- * Each leaf value is a flat, fully-formed route — no concatenation needed at call site.
- *
- * Internally, routes use `@/…` shorthand that resolves against the group's `@prefix`.
- * Resolution happens once inside `getApiRoutes()`, so consumers always receive clean strings.
- *
- * Base URL resolution:
- * - HTTP routes: `getEnv().APP_API_URL` + route  (handled by axios baseURL)
- * - WebSocket:   `getEnv().APP_WEBSOCKET_URL` + `getApiRoutes().ws.join`  (composed in ws/client.ts)
- */
-interface ApiRoutes {
-    agents: {
-        list: string;
-        details: string;
-        byName: string;
-    };
-    sessions: {
-        list: string;
-        get: string;
-        messages: string;
-    };
-    models: {
-        list: string;
-        byName: string;
-    };
-    uploads: {
-        list: string;
-        get: string;
-        create: string;
-    };
-    artifacts: {
-        get: string;
-        content: string;
-        state: string;
-        baseUrl: string;
-    };
-    pages: {
-        list: string;
-        get: string;
-        content: string;
-        baseUrl: string;
-    };
-    registry: {
-        namespaces: string;
-        entries: string;
-        entry: string;
-        entryCreate: string;
-        entryEditors: string;
-        versions: string;
-        versionApply: string;
+interface WsMessage_RegistryEntry extends WsMessageBase {
+    topic: WsTopicTypes['RegistryEntry'];
+    data: {
+        request_id?: string;
+        content_version?: string;
     };
-    keeperSync: {
-        state: string;
-        download: string;
-        upload: string;
-        undo: string;
-        redo: string;
+}
+interface WsMessage_Pages extends WsMessageBase {
+    topic: WsTopicTypes['Pages'];
+}
+interface WsMessage_Page extends WsMessageBase {
+    topic: WsTopicTypes['Page'];
+    data: PageApi.Page & {
+        request_id?: string;
     };
-    components: {
-        list: string;
+}
+interface WsMessage_SessionOpen extends WsMessageBase {
+    topic: WsTopicTypes['SessionOpened'];
+    data: {
+        request_id?: string;
+        active_session_ids: Array<string>;
+        session_id: string;
     };
-    tools: {
-        byName: string;
+}
+interface WsMessage_Error extends WsMessageBase {
+    topic: WsTopicTypes['Error'];
+    data: {
+        request_id?: string;
+        error: string;
+        message: string;
     };
-    ws: {
-        join: string;
+}
+interface WsMessage_SessionClosed extends WsMessageBase {
+    topic: WsTopicTypes['SessionClosed'];
+    data: {
+        request_id?: string;
+        active_session_ids: Array<string>;
+        session_id: string;
     };
 }
-/**
- * Override type for `AppConfig.feature.apiRoutes`.
- *
- * Each group is optional and partially overridable.
- * Set `@prefix` to rebase all `@/…` routes in that group at once,
- * or override individual routes with absolute paths.
- */
-type ApiRoutesOverride = {
-    [K in keyof ApiRoutes]?: Partial<ApiRoutes[K]> & {
-        '@prefix'?: string;
+interface WsMessageDataBase {
+    type: WsMessageType;
+}
+interface WsMessageDataChunk extends WsMessageDataBase {
+    type: WsMessageType.CHUNK;
+    content: string;
+}
+interface WsMessageDataContent extends WsMessageDataBase {
+    type: WsMessageType.CONTENT;
+    content: string;
+    message_id: MessageUUID;
+    file_uuids?: string[];
+}
+interface WsMessageDataUser extends WsMessageDataBase {
+    type: WsMessageType.USER;
+    text: string;
+    message_id: MessageUUID;
+    file_uuids?: string[];
+}
+interface WsMessageDataDelegation extends WsMessageDataBase {
+    type: WsMessageType.DELEGATION;
+    from: string;
+    to: string;
+}
+interface WsMessageDataInvalidate extends WsMessageDataBase {
+    type: WsMessageType.INVALIDATE;
+}
+interface WsMessageDataStarted extends WsMessageDataBase {
+    type: WsMessageType.RESPONSE_STARTED;
+    message_id: MessageUUID;
+}
+interface WsMessageDataToolCall extends WsMessageDataBase {
+    type: WsMessageType.TOOL_CALL | WsMessageType.FUNCTION_CALL;
+    function_name: string;
+    artifact_id?: string;
+}
+interface WsMessageDataArtifact extends WsMessageDataBase {
+    type: WsMessageType.ARTIFACT;
+    artifact_id?: string;
+}
+interface WsMessageDataToolSuccess extends WsMessageDataBase {
+    type: WsMessageType.TOOL_SUCCESS | WsMessageType.FUNCTION_SUCCESS;
+    function_name: string;
+    artifact_id?: string;
+}
+interface WsMessageDataToolError extends WsMessageDataBase {
+    type: WsMessageType.TOOL_ERROR | WsMessageType.FUNCTION_ERROR;
+    function_name: string;
+    artifact_id?: string;
+}
+interface WsMessageDataError extends WsMessageDataBase {
+    type: WsMessageType.ERROR;
+    message: string;
+    code: string;
+}
+interface WsMessage_SessionMessage extends WsMessageBase {
+    topic: WsTopicTypes['SessionMessage'];
+    data: (WsMessageDataUser | WsMessageDataContent | WsMessageDataChunk | WsMessageDataDelegation | WsMessageDataToolCall | WsMessageDataError | WsMessageDataInvalidate | WsMessageDataStarted | WsMessageDataToolSuccess | WsMessageDataArtifact | WsMessageDataToolError) & {
+        request_id?: string;
     };
-};
-
-interface AppFeatures extends I18NFeatureTypes {
-    /**
-     * If to remember auth details or not
-     */
-    session: {
-        type: 'non-persistent' | 'cookie';
+}
+interface WsMessage_Session extends WsMessageBase {
+    topic: WsTopicTypes['Session'];
+    data: {
+        request_id?: string;
+        agent?: string;
+        last_message_date?: number;
+        model?: string;
+        status?: string;
+        title?: string;
+        type: 'update';
+        public_meta?: Array<{
+            icon?: string;
+            id: string;
+            title: string;
+            url?: string;
+        }>;
     };
-    history: 'browser' | 'hash';
-    env: {
-        APP_API_URL: string;
-        APP_AUTH_API_URL: string;
-        APP_WEBSOCKET_URL: string;
+}
+interface WsMessage_Artifact extends WsMessageBase {
+    topic: WsTopicTypes['Artifact'];
+    data: Partial<Artifact> & {
+        request_id?: string;
     };
-    axiosDefaults?: Partial<AxiosDefaults>;
-    routePrefix?: string;
-    showAdmin?: boolean;
-    allowSelectModel?: boolean;
-    startNavOpen?: boolean;
-    hideNavBar?: boolean;
-    disableRightPanel?: boolean;
-    /**
-     * Hide the session selector dropdown in chat views
-     * @default false
-     */
-    hideSessionSelector?: boolean;
-    additionalNavItems?: Array<PageApi.Page>;
-    chat?: {
-        convertPasteToFile?: {
-            enabled: boolean;
-            minFileSize: number;
-            allowHtml: boolean;
-        };
+}
+interface WsMessage_Upload extends WsMessageBase {
+    topic: WsTopicTypes['Upload'];
+    data: UploadApi.Upload & {
+        request_id?: string;
     };
-    apiRoutes?: ApiRoutesOverride;
-    /**
-     * Additional HTML tags to whitelist in the sanitizer.
-     * Map of tag name to allowed attribute names.
-     * 'class' is always implicitly allowed for every tag.
-     */
-    allowAdditionalTags?: Record<string, string[]>;
+}
+type WsMessage = WsMessage_Welcome | WsMessage_Pages | WsMessage_Page | WsMessage_SessionMessage | WsMessage_Session | WsMessage_SessionClosed | WsMessage_Error | WsMessage_Artifact | WsMessage_SessionOpen | WsMessage_Action | WsMessage_Registry | WsMessage_RegistryEntry | WsMessage_Upload;
+
+interface BaseWsCommand {
+    type: string;
     /**
-     * LRU cache configuration for child iframe state preservation.
-     * @default { maxPages: 50, maxSizePerPage: 2097152 }
+     * If used, WsService will await a response with the same request_id
      */
-    stateCache?: {
-        /** Maximum number of page/artifact state buckets to keep. @default 50 */
-        maxPages?: number;
-        /** Maximum JSON-serialized size per page in bytes. @default 2097152 (2 MB) */
-        maxSizePerPage?: number;
+    request_id?: string;
+}
+interface SessionOpenCommand extends BaseWsCommand {
+    type: 'session_open';
+    session_id?: string;
+    start_token?: string;
+}
+interface SessionCloseCommand extends BaseWsCommand {
+    type: 'session_close';
+    session_id: string;
+}
+interface SessionMessageCommand extends BaseWsCommand {
+    type: 'session_message';
+    session_id: string;
+    message_id: string;
+    data: {
+        text: string;
+        file_uuids?: string[];
     };
 }
-interface AppAuthConfig {
-    token: string;
-    expiresAt: string;
+interface SessionCommandCommand extends BaseWsCommand {
+    type: 'session_command';
+    session_id: string;
+    data: StopCommand | ModelCommand | OtherCommand | AgentCommand;
 }
-interface CssVariablesMap {
-    [key: string]: string | Record<string, string> | undefined;
-    '@dark'?: Record<string, string>;
-    '@light'?: Record<string, string>;
+interface StopCommand {
+    command: 'stop';
 }
-interface AppCustomization {
-    customCSS?: string;
-    cssVariables?: CssVariablesMap;
-    i18n?: Partial<I18NTextTypes>;
-    icons?: Record<string, {
-        body: string;
-        width: number;
-        height: number;
-    }>;
+interface ModelCommand {
+    command: 'model';
+    name: string;
 }
-interface AppConfig {
-    artifactId?: string;
-    /**
-     * Starting app or artifact/page path
-     */
-    path?: string;
+interface AgentCommand {
+    command: 'agent';
+    name: string;
+}
+interface ExternalEventCommand extends BaseWsCommand {
+    type: string;
+    data: Record<string, unknown>;
+}
+interface OtherCommand {
+    command: string;
+    [key: string]: unknown;
+}
+type WsCommand = SessionOpenCommand | SessionCloseCommand | SessionMessageCommand | SessionCommandCommand | ExternalEventCommand;
+
+type KnownTopics = '@history' | '@visibility' | '@message' | '@state-error';
+type Events = {
+    /** Emitted when pages are updated */
+    '@history': (data: {
+        path: string;
+    }) => void;
+    '@visibility': (visible: boolean) => void;
+    '@message': (data: WsMessage) => void;
+    '@state-error': (data: {
+        error: string;
+        key?: string;
+    }) => void;
+} & {
+    [K in string as K extends KnownTopics ? never : K]: (data: WsMessage) => void;
+};
+declare function createEvents(): <T extends string>(topicPattern: T, callback: T extends KnownTopics ? Events[T] : Events["@message"]) => nanoevents.Unsubscribe;
+
+interface StateApiOptions {
+    /** Override the default page-level scope. Used by web components with persist-key or nested artifacts. */
+    scope?: string;
+}
+interface StateApi {
+    get: <T = unknown>(key: string, options?: StateApiOptions) => Promise<T | null>;
+    set: (key: string, value: unknown, options?: StateApiOptions) => Promise<void>;
+    remove: (key: string, options?: StateApiOptions) => Promise<void>;
+    clear: (options?: StateApiOptions) => Promise<void>;
+    getAll: (options?: StateApiOptions) => Promise<Record<string, unknown>>;
+}
+
+interface ProxyWsApi {
     /**
-     * App features like history mode, session type, etc.
+     * Send a raw WebSocket command through the host's WebSocket connection.
+     * Fire-and-forget — responses arrive via `on()` event subscriptions.
      */
-    feature?: AppFeatures;
+    send: (command: WsCommand) => void;
     /**
-     * Auth configuration
+     * Send a WebSocket command and wait for the server's response.
+     * The command is sent with a `request_id`; the promise resolves when the server echoes it back.
+     * Times out after 30 seconds.
      */
-    auth: AppAuthConfig;
+    sendWithResponse: (command: WsCommand) => Promise<WsMessage>;
     /**
-     * App customization like i18n texts, css variables, custom css, etc.
+     * Convenience method to send a session command (stop, model, agent, etc.)
      */
-    customization?: AppCustomization;
-    externalEvents?: {
-        enabled: boolean;
-        wsType: string;
-        allowedOrigins: string[];
-        allowedTypes: string[];
-    };
+    sendCommand: (sessionId: string, data: {
+        command: string;
+        [key: string]: unknown;
+    }) => void;
 }
 
 interface FormState {
@@ -769,6 +844,7 @@ interface ProxyApiInstance {
     };
     on: ReturnType<typeof createEvents>;
     state: StateApi;
+    ws: ProxyWsApi;
     loadWebComponent: (componentId: string, tagName?: string) => Promise<void>;
 }
 
@@ -795,6 +871,7 @@ interface ProxyConfig {
 
 declare const GLOBAL_CONFIG_VAR: "__WIPPY_APP_CONFIG__";
 declare const GLOBAL_PROXY_CONFIG_VAR: "__WIPPY_PROXY_CONFIG__";
+declare const GLOBAL_CONFIG_OVERRIDES_VAR: "__WIPPY_CONFIG_OVERRIDES__";
 declare const GLOBAL_API_PROVIDER: "__WIPPY_APP_API__";
 declare const GLOBAL_WEB_COMPONENT_CACHE: "__WIPPY_WEB_COMPONENT_CACHE__";
 declare global {
@@ -802,6 +879,7 @@ declare global {
         [GLOBAL_CONFIG_VAR]: AppConfig;
         [GLOBAL_API_PROVIDER]: ProxyApiInstance;
         [GLOBAL_PROXY_CONFIG_VAR]?: ProxyConfig;
+        [GLOBAL_CONFIG_OVERRIDES_VAR]?: AppConfigOverrides;
         [GLOBAL_WEB_COMPONENT_CACHE]: Record<string, {
             usedAt: number;
             data: string;
@@ -823,6 +901,9 @@ declare const _default: {
                     info: Record<string, string>;
                     help: Record<string, string>;
                     accent: Record<string, string>;
+                    surface: {
+                        850: string;
+                    };
                 };
             };
         };
@@ -852,6 +933,7 @@ declare global {
             iframe: () => Promise<ProxyApiInstance['host']>;
             on: () => Promise<ProxyApiInstance['on']>;
             state: () => Promise<ProxyApiInstance['state']>;
+            ws: () => Promise<ProxyApiInstance['ws']>;
             loadWebComponent: () => Promise<ProxyApiInstance['loadWebComponent']>;
         };
         tailwind?: {

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@wippy-fe/types-global-proxy",
-  "version": "0.0.15",
+  "version": "0.0.17",
   "description": "Global type declarations for Wippy iframe proxy (window.getWippyApi, $W, etc.)",
+  "license": "UNLICENSED",
   "types": "index.d.ts"
 }