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

package/index.d.ts

@@ -1,9 +1,125 @@
+import { PanelTree, ModalSize, PanelTarget } from '@wippy-fe/layout';
 import { AxiosDefaults, AxiosInstance } from 'axios';
 import { ConfirmationOptions } from 'primevue/confirmationoptions';
 import { ToastMessageOptions } from 'primevue/toast';
 import * as nanoevents from 'nanoevents';
 import * as tailwindcss_types_config from 'tailwindcss/types/config';
 
+/**
+ * Host-side layout types (Wippy-flavored wrapper around `@wippy-fe/layout`).
+ *
+ * The pure package speaks in `PanelDef = { component: Component, props? }` —
+ * bring-your-own Vue component. The host layer replaces that with a
+ * tagged-union where `kind` picks a content resolver:
+ *
+ *  - `page`      → renders a Wippy page (WPage double-buffer for `main: true`, single-instance otherwise)
+ *  - `artifact`  → renders a Wippy artifact (WPage with type='artifact')
+ *  - `component` → renders a registered web component via `tagName`
+ *  - `builtin`   → renders host chrome (nav-sidebar / chat-wrapper / artifact-viewer / session-selector)
+ *
+ * The host resolver converts this into `@wippy-fe/layout`'s `PanelDef` at
+ * construction time and passes it into a `LayoutManager`.
+ */
+
+interface HostPanelBase {
+    title?: string;
+    icon?: string;
+    props?: Record<string, unknown>;
+}
+interface HostPagePanelDef extends HostPanelBase {
+    kind: 'page';
+    id: string;
+    route?: string;
+}
+interface HostArtifactPanelDef extends HostPanelBase {
+    kind: 'artifact';
+    id: string;
+}
+interface HostComponentPanelDef extends HostPanelBase {
+    kind: 'component';
+    tagName: string;
+}
+type HostBuiltinId = 'nav-sidebar' | 'chat-wrapper' | 'artifact-viewer' | 'session-selector';
+interface HostBuiltinPanelDef extends HostPanelBase {
+    kind: 'builtin';
+    id: HostBuiltinId;
+}
+type HostPanelDef = HostPagePanelDef | HostArtifactPanelDef | HostComponentPanelDef | HostBuiltinPanelDef;
+/**
+ * Overlay content shape — what kind of thing to render. Mirrors
+ * HostPanelDef's discriminant exactly so the same resolver dispatch
+ * works for both inline panels and overlays. This makes floating
+ * panels and modals declarable in pure JSON config (no Vue component
+ * references in the declaration).
+ */
+type HostOverlayContent = {
+    kind: 'page';
+    id: string;
+    route?: string;
+} | {
+    kind: 'artifact';
+    id: string;
+} | {
+    kind: 'component';
+    tagName: string;
+} | {
+    kind: 'builtin';
+    id: HostBuiltinId;
+};
+interface HostOverlayBase {
+    title?: string;
+    icon?: string;
+    props?: Record<string, unknown>;
+    dismissable?: boolean;
+}
+/**
+ * Floating window def — absolute-positioned, draggable, resizable.
+ * Composition: content kind + window chrome properties.
+ */
+type HostFloatingDef = HostOverlayContent & HostOverlayBase & {
+    position: {
+        x: number;
+        y: number;
+    };
+    size: {
+        width: number;
+        height: number;
+    };
+    minSize?: {
+        width: number;
+        height: number;
+    };
+    maxSize?: {
+        width: number;
+        height: number;
+    };
+    minimizable?: boolean;
+    maximizable?: boolean;
+    zIndex?: number;
+};
+/**
+ * Modal def — centered overlay. Size is either a single `ModalSize`
+ * or a breakpoint-keyed map (desktop centered / mobile fullscreen).
+ */
+type HostModalDef = HostOverlayContent & HostOverlayBase & {
+    size?: ModalSize | Record<string, ModalSize>;
+};
+/**
+ * The root layout declaration stored in `AppConfig.hostConfig.layout`.
+ * Shape mirrors `@wippy-fe/layout`'s `LayoutDeclaration` but replaces
+ * `panels` with a tagged-union `HostPanelDef` map.
+ */
+interface HostLayoutDeclaration {
+    layouts: Record<string, PanelTree> & {
+        default: PanelTree;
+    };
+    breakpoints?: Record<string, number>;
+    panels: Record<string, HostPanelDef>;
+    floating?: Record<string, HostFloatingDef>;
+    modals?: Record<string, HostModalDef>;
+    dragEnabled?: boolean;
+}
+
 declare namespace PageApi {
     interface Page {
         icon: string;
@@ -25,12 +141,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 +204,7 @@ interface ApiRoutes {
     };
     pages: {
         list: string;
+        routes: string;
         get: string;
         content: string;
         baseUrl: string;
@@ -257,7 +385,6 @@ interface HostConfig {
             allowHtml: boolean;
         };
     };
-    apiRoutes?: ApiRoutesOverride;
     stateCache?: {
         maxPages?: number;
         maxSizePerPage?: number;
@@ -267,6 +394,11 @@ interface HostConfig {
         type: 'non-persistent' | 'cookie';
     };
     history?: 'browser' | 'hash';
+    /**
+     * Declarative multi-panel layout for the `managed-layout.html` entry point.
+     * Ignored by `iframe.html` / `chat-iframe.html` shells.
+     */
+    layout?: HostLayoutDeclaration;
 }
 interface AppContext {
     resourceId: string;
@@ -274,8 +406,20 @@ interface AppContext {
     route?: string;
     parentResourceId?: string;
     nestingDepth?: number;
+    /** This iframe is the navigation owner of its parent level. */
+    isNavOwner?: boolean;
     layoutPanelId?: string;
     layoutId?: string;
+    /**
+     * Initial layout snapshot baked into the child payload by the
+     * managed-layout host. Child proxies seed `host.layout.snapshot` from
+     * this at boot — so `host.layout.snapshot` is NEVER null inside a
+     * managed-layout host, and consumers never have to wait for a
+     * round-trip. `undefined` outside a managed-layout host.
+     *
+     * Updates arrive asynchronously via the `@layout-change` proxy topic.
+     */
+    layout?: unknown;
     extensions?: Record<string, unknown>;
 }
 interface AppEnv {
@@ -289,6 +433,7 @@ interface AppConfig {
     env: AppEnv;
     axiosDefaults?: Partial<AxiosDefaults>;
     routePrefix?: string;
+    apiRoutes?: ApiRoutesOverride;
     theming: {
         global?: ThemingScope;
         host?: HostThemingScope;
@@ -297,17 +442,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 +471,7 @@ interface ProxyConfig {
             primevue: boolean;
             markdown: boolean;
             customCss: boolean;
-            customVariabled: boolean;
+            customVariables: boolean;
         };
         tailwindConfig: boolean;
         resizeObserver: boolean;
@@ -754,11 +901,56 @@ interface OtherCommand {
 }
 type WsCommand = SessionOpenCommand | SessionCloseCommand | SessionMessageCommand | SessionCommandCommand | ExternalEventCommand;
 
-type KnownTopics = '@history' | '@visibility' | '@message' | '@state-error';
+/**
+ * Read-only mirror of the current host `HostLayoutDeclaration`, minus
+ * Vue-component references (those can't cross the postMessage boundary).
+ * Child iframes use this to reason about the tree — e.g. which panels
+ * exist, what their current sizes/collapsed state / routes are — without
+ * being coupled to the host's component registry.
+ *
+ * `null` outside a managed-layout host (compat mode, `iframe.html`, or
+ * any standalone/headless entry point).
+ */
+interface LayoutSnapshot {
+    layouts: Record<string, unknown>;
+    panels: Record<string, unknown>;
+    breakpoints?: Record<string, number>;
+    floating?: Record<string, unknown>;
+    modals?: Record<string, unknown>;
+    activeBreakpoint?: string;
+    dragEnabled?: boolean;
+}
+interface LayoutApi {
+    /**
+     * Current layout snapshot — sync property getter, never waits. Returns
+     * `null` when the child is NOT inside a managed-layout host. Updates
+     * arrive via the `@layout-change` proxy topic; read the property
+     * directly inside an `@layout-change` handler to see the fresh value,
+     * or subscribe reactively via `@wippy-fe/vue-host`'s `useWippyLayout`.
+     */
+    readonly snapshot: LayoutSnapshot | null;
+    /** Resize a panel in the active breakpoint layout. */
+    resizePanel: (panelId: string, size: string) => void;
+    /** Collapse a panel (no-op if not `collapsible`). */
+    collapsePanel: (panelId: string) => void;
+    /** Expand a collapsed panel. */
+    expandPanel: (panelId: string) => void;
+    /** Move a panel to a new position in the active layout. */
+    movePanel: (panelId: string, target: PanelTarget) => void;
+    /** Remove a panel from all breakpoint layouts + panels map. */
+    removePanel: (panelId: string) => void;
+    /** Close a currently-open modal by id. */
+    closeModal: (modalId: string) => void;
+    /** Remove a floating panel by id. */
+    removeFloating: (floatingId: string) => void;
+}
+
+type KnownTopics = '@history' | '@visibility' | '@message' | '@state-error' | '@layout-change' | '@layout-breakpoint';
 type Events = {
     /** Emitted when pages are updated */
     '@history': (data: {
         path: string;
+        navId?: number;
     }) => void;
     '@visibility': (visible: boolean) => void;
     '@message': (data: WsMessage) => void;
@@ -766,11 +958,46 @@ type Events = {
         error: string;
         key?: string;
     }) => void;
+    '@layout-change': (snapshot: LayoutSnapshot) => void;
+    '@layout-breakpoint': (data: {
+        name: string;
+        width: number;
+    }) => 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;
 
+/**
+ * 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 +1103,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 +1111,18 @@ 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;
+        /**
+         * Declarative multi-panel layout control (managed-layout entry point only).
+         * Calls from child iframes not embedded inside a `managed-layout.html`
+         * host will be dropped silently by the parent.
+         */
+        layout: LayoutApi;
         logout: () => void;
     };
     api: AxiosInstance;
@@ -892,6 +1131,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 +1150,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 +1157,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.25",
   "description": "Global type declarations for Wippy iframe proxy (window.getWippyApi, $W, etc.)",
   "license": "UNLICENSED",
   "types": "index.d.ts"