@wippy-fe/types-global-proxy 0.0.22 → 0.0.23

package/index.d.ts

@@ -25,12 +25,23 @@ declare namespace PageApi {
         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;
+        /**
+         * Optional Vue-Router-4 path that claims a top-level URL for this page.
+         * v1 canonical form: `/<literal>/:part(.*)*` (e.g. `/keeper/:part(.*)*`, `/:part(.*)*`).
+         * When set, the FE registers a dynamic route that renders this page at the claimed URL.
+         */
+        mountRoute?: string;
     }
     interface PagesResponse {
         count: number;
         pages: Page[];
         success: boolean;
     }
+    interface PagesRoutesResponse {
+        count: number;
+        routes: Record<string, string>;
+        success: boolean;
+    }
     interface PageContentResponse {
         content: string;
         success: boolean;
@@ -77,6 +88,7 @@ interface ApiRoutes {
     };
     pages: {
         list: string;
+        routes: string;
         get: string;
         content: string;
         baseUrl: string;
@@ -257,7 +269,6 @@ interface HostConfig {
             allowHtml: boolean;
         };
     };
-    apiRoutes?: ApiRoutesOverride;
     stateCache?: {
         maxPages?: number;
         maxSizePerPage?: number;
@@ -274,6 +285,8 @@ interface AppContext {
     route?: string;
     parentResourceId?: string;
     nestingDepth?: number;
+    /** This iframe is the navigation owner of its parent level. */
+    isNavOwner?: boolean;
     layoutPanelId?: string;
     layoutId?: string;
     extensions?: Record<string, unknown>;
@@ -289,6 +302,7 @@ interface AppConfig {
     env: AppEnv;
     axiosDefaults?: Partial<AxiosDefaults>;
     routePrefix?: string;
+    apiRoutes?: ApiRoutesOverride;
     theming: {
         global?: ThemingScope;
         host?: HostThemingScope;
@@ -297,17 +311,19 @@ interface AppConfig {
     hostConfig: HostConfig;
     context: AppContext;
 }
-interface ChildAppConfig {
-    $schema: string;
-    auth: AppAuthConfig;
-    env: AppEnv;
-    axiosDefaults?: Partial<AxiosDefaults>;
-    routePrefix?: string;
-    apiRoutes?: ApiRoutesOverride;
-    customization: AppCustomization;
-    context: AppContext;
-    configOverrides?: AppConfigOverrides;
-}
+type ChildAppConfig = Omit<AppConfig, 'hostConfig'> & {
+    /**
+     * This iframe's own pageId. Used by the link classifier to exclude
+     * self from mount route matching (prevents self-match on root mounts).
+     */
+    selfPageId?: string;
+    /**
+     * Map of mountRoute pattern → pageId for host-level routes claimed by view pages.
+     * Used by child iframes' link classifier to detect host-nav links and relay them
+     * via postMessage instead of triggering in-child navigation.
+     */
+    mountRoutes?: Record<string, string>;
+};
 interface AppConfigOverrides {
     customization?: Partial<AppCustomization>;
     axiosDefaults?: Partial<AxiosDefaults>;
@@ -324,7 +340,7 @@ interface ProxyConfig {
             primevue: boolean;
             markdown: boolean;
             customCss: boolean;
-            customVariabled: boolean;
+            customVariables: boolean;
         };
         tailwindConfig: boolean;
         resizeObserver: boolean;
@@ -759,6 +775,7 @@ type Events = {
     /** Emitted when pages are updated */
     '@history': (data: {
         path: string;
+        navId?: number;
     }) => void;
     '@visibility': (visible: boolean) => void;
     '@message': (data: WsMessage) => void;
@@ -771,6 +788,36 @@ type Events = {
 };
 declare function createEvents(): <T extends string>(topicPattern: T, callback: T extends KnownTopics ? Events[T] : Events["@message"]) => nanoevents.Unsubscribe;
 
+/**
+ * Link classifier — decides whether an href targets:
+ *   - `host-nav`    host-level route claimed by a view page or system route
+ *   - `child-nav`   internal route belonging to the subapp's own router
+ *   - `external`    different origin / mailto / tel / ftp / file / javascript
+ *   - `ignore`      empty href, pure hash
+ *
+ * Pure function, framework-agnostic. Used by:
+ *   - `prevent-clicks.ts`                       fallback handler for raw <a> clicks
+ *   - `ProxyApiInstance.host.classifyLink(href)` exposed to vanilla subapp code
+ *   - `@wippy-fe/router` RouterLink wrapper     transparent host-nav relay
+ *
+ * Matching strategy for host-nav:
+ *   1. Compare the path's first literal segment against known system routes
+ *      (`/chat`, `/c`, `/web`, `/page`, `/keeper`, `/login`, `/logout`)
+ *   2. Compare against mountRoute top literal segments from ChildAppConfig.mountRoutes
+ *   3. Root-mount fallback — if a view page claimed `/:part(.*)*`, it catches
+ *      everything not otherwise matched
+ */
+type LinkKind = 'ignore' | 'external' | 'host-nav' | 'child-nav';
+interface LinkClassification {
+    kind: LinkKind;
+    /** The original href the caller passed in (echoed for convenience) */
+    href: string;
+    /** Path after origin + routePrefix stripping, when applicable */
+    normalizedPath?: string;
+    /** For host-nav matched to a mountRoute, the page id of the target */
+    targetPageId?: string;
+}
+
 declare const LogLevel: {
     readonly Emergency: 0;
     readonly Alert: 1;
@@ -876,7 +923,7 @@ interface ProxyApiInstance {
             target: 'modal' | 'sidebar';
         }) => void;
         navigate: (url: string) => void;
-        onRouteChanged: (internalRoute: string) => void;
+        onRouteChanged: (internalRoute: string, navId?: number) => void;
         handleError: (code: ('auth-expired' | 'other'), error: Record<string, unknown>) => void;
         setContext: (context: Record<string, unknown>, sessionUUID?: string, source?: {
             type: 'page' | 'artifact';
@@ -884,6 +931,12 @@ interface ProxyApiInstance {
             instanceUUID?: string;
         }) => void;
         formatUrl: (relativeUrl: string) => string;
+        /**
+         * Classify a link href as `host-nav` / `child-nav` / `external` / `ignore`.
+         * Uses mountRoutes and routePrefix from the child's ChildAppConfig plus baked-in
+         * system route segments. Pure function — safe to call anywhere.
+         */
+        classifyLink: (href: string | null | undefined) => LinkClassification;
         logout: () => void;
     };
     api: AxiosInstance;
@@ -892,6 +945,16 @@ interface ProxyApiInstance {
         get: () => Promise<FormState>;
         submit: (data: FormData | Record<string, unknown>) => Promise<FormResult>;
     };
+    /**
+     * Subscribe to events. Returns an unsubscribe function that MUST be called
+     * on component unmount to prevent subscription leaks.
+     *
+     * ```ts
+     * const unsub = instance.on('session:*:message:*', (msg) => { ... })
+     * // Later, on unmount:
+     * unsub()
+     * ```
+     */
     on: ReturnType<typeof createEvents>;
     logger: LoggerApi;
     state: StateApi;
@@ -901,7 +964,6 @@ interface ProxyApiInstance {
 
 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 {
@@ -909,7 +971,6 @@ declare global {
         [GLOBAL_CONFIG_VAR]: AppConfig | ChildAppConfig;
         [GLOBAL_API_PROVIDER]: ProxyApiInstance;
         [GLOBAL_PROXY_CONFIG_VAR]?: ProxyConfig;
-        [GLOBAL_CONFIG_OVERRIDES_VAR]?: AppConfigOverrides;
         [GLOBAL_WEB_COMPONENT_CACHE]: Record<string, {
             usedAt: number;
             data: string;

package/package.json

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