@wippy-fe/types-global-proxy 0.0.26 → 0.0.28

package/index.d.ts

@@ -1,8 +1,9 @@
-import { PanelTree, ModalSize, PanelTarget } from '@wippy-fe/layout';
+import { PanelTree, ModalSize, SizeValue, 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 { GLOBAL_CONFIG_VAR, GLOBAL_API_PROVIDER, GLOBAL_PROXY_CONFIG_VAR, GLOBAL_WEB_COMPONENT_CACHE } from '@wippy-fe/shared';
 import * as tailwindcss_types_config from 'tailwindcss/types/config';
 
 /**
@@ -15,7 +16,7 @@ import * as tailwindcss_types_config from 'tailwindcss/types/config';
  *  - `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 (@HOST/nav-sidebar / @HOST/chat-wrapper / @HOST/artifact-viewer / @HOST/session-selector)
+ *  - `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`.
@@ -25,6 +26,14 @@ interface HostPanelBase {
     title?: string;
     icon?: string;
     props?: Record<string, unknown>;
+    /**
+     * Drawer open state for panels whose active layout slot has
+     * `display: 'drawer-*'`. Surfaced in the snapshot wire so subscribed
+     * iframes can react to open/close. Mutated via
+     * `host.layout.openDrawer / closeDrawer / toggleDrawer` (or any
+     * `updatePanel` patch).
+     */
+    drawerOpen?: boolean;
 }
 interface HostPagePanelDef extends HostPanelBase {
     kind: 'page';
@@ -39,6 +48,12 @@ interface HostComponentPanelDef extends HostPanelBase {
     kind: 'component';
     tagName: string;
 }
+/**
+ * Built-in panel ids shipped by gen-2-chat. The `@HOST/` prefix marks
+ * them as framework-owned so consumers can later plug in their own
+ * `kind: 'builtin'` ids without colliding (and so the declaration
+ * shows ownership at a glance).
+ */
 type HostBuiltinId = '@HOST/nav-sidebar' | '@HOST/chat-wrapper' | '@HOST/artifact-viewer' | '@HOST/session-selector';
 interface HostBuiltinPanelDef extends HostPanelBase {
     kind: 'builtin';
@@ -100,14 +115,37 @@ type HostFloatingDef = HostOverlayContent & HostOverlayBase & {
 /**
  * Modal def — centered overlay. Size is either a single `ModalSize`
  * or a breakpoint-keyed map (desktop centered / mobile fullscreen).
+ *
+ * `useNativeDialog` defaults to `true` — the modal renders via
+ * `<dialog showModal()>` (top-layer stacking, focus trap, inert
+ * propagation). Set `false` to opt back into the legacy div-overlay
+ * implementation while consumers migrate; the legacy path is
+ * `@deprecated` and will be removed in the next major.
  */
 type HostModalDef = HostOverlayContent & HostOverlayBase & {
     size?: ModalSize | Record<string, ModalSize>;
+    useNativeDialog?: boolean;
+};
+/**
+ * Coordinator def — headless coordinator app. Same content kinds as
+ * panels/floating/modals (page → iframe, artifact → iframe, component
+ * → web component, builtin → Vue), but mounted in a hidden host div
+ * with no slot / position / size. Use case: a custom app that wires
+ * cross-cutting glue — subscribes to WS topics, listens on the layout
+ * bus, dispatches `host.layout.updatePanel` / `expandPanel` /
+ * `navigate`. Display panels stay focused on rendering.
+ */
+type HostCoordinatorDef = HostOverlayContent & {
+    props?: Record<string, unknown>;
 };
 /**
  * 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.
+ *
+ * **Status: Draft 1 (preview).** Shipped but not yet validated against
+ * a production consumer. Field names and validation rules may still
+ * change between minor releases. See `managed-layout.md`.
  */
 interface HostLayoutDeclaration {
     layouts: Record<string, PanelTree> & {
@@ -117,8 +155,27 @@ interface HostLayoutDeclaration {
     panels: Record<string, HostPanelDef>;
     floating?: Record<string, HostFloatingDef>;
     modals?: Record<string, HostModalDef>;
+    /**
+     * Headless coordinator apps. Mounted in a hidden host div, get the
+     * full proxy API, never appear in any layout slot. Validated with the
+     * same kind/builtin-id checks as panels.
+     */
+    coordinators?: Record<string, HostCoordinatorDef>;
     dragEnabled?: boolean;
 }
+/**
+ * The envelope every subscriber receives. `sourcePanelId` is the
+ * publisher's panelId (null when published from outside any registered
+ * panel — e.g. a grand-child relay whose panel boundary fell off the
+ * map, or system events). `targetPanelId` is non-null only for
+ * `send(target, ...)` calls; `broadcast()` leaves it null.
+ */
+interface BroadcastEnvelope {
+    channel: string;
+    payload: unknown;
+    sourcePanelId: string | null;
+    targetPanelId: string | null;
+}
 
 declare namespace PageApi {
     interface Page {
@@ -399,6 +456,19 @@ interface HostConfig {
      * Ignored by `iframe.html` / `chat-iframe.html` shells.
      */
     layout?: HostLayoutDeclaration;
+    /**
+     * Lazy WebSocket connection: defer the WS handshake until the first
+     * `useSubscription()` registers, and disconnect when the last
+     * subscriber unmounts. Saves a connection (and the matching server
+     * resource) for shells that don't actually consume push events at
+     * boot — chat-only iframes and panels that page through artifacts
+     * via REST.
+     *
+     * Apps that call `wsClient.sendMessage(...)` directly without
+     * subscribing first should NOT enable this — sendMessage will throw
+     * "WebSocket is not connected". Default is `false` (eager connect).
+     */
+    lazyWS?: boolean;
 }
 interface AppContext {
     resourceId: string;
@@ -920,6 +990,15 @@ interface LayoutSnapshot {
     activeBreakpoint?: string;
     dragEnabled?: boolean;
 }
+/**
+ * Child-iframe handle on the host's managed-layout shell.
+ *
+ * **Status: Draft 1 (preview).** Shipped but not yet driven by a
+ * production consumer. Field names, defaults, and validation rules may
+ * still change between minor releases. Pin to an exact CDN version
+ * until this label is removed. See `managed-layout.md` for guidance,
+ * worked examples, and the three-tier "where state lives" rule.
+ */
 interface LayoutApi {
     /**
      * Current layout snapshot — sync property getter, never waits. Returns
@@ -929,20 +1008,92 @@ interface LayoutApi {
      * 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;
+    /**
+     * Resize a panel in the active breakpoint layout. `size` follows the
+     * GoldenLayout-style grammar — `'auto' | 'Nfr' | 'Npx' | 'N%'`.
+     * Anything else is rejected at the host's `validateLayout` boundary
+     * (silent no-op for unknown panelId; `LayoutValidationError` for bad
+     * size).
+     */
+    resizePanel: (panelId: string, size: SizeValue) => void;
     /** Collapse a panel (no-op if not `collapsible`). */
     collapsePanel: (panelId: string) => void;
     /** Expand a collapsed panel. */
     expandPanel: (panelId: string) => void;
+    /**
+     * Open a panel's drawer overlay. Only meaningful when the panel's
+     * active layout slot has `display: 'drawer-*'`. For inline slots,
+     * this sets `panel.drawerOpen` but has no visible effect (the engine
+     * ignores it on inline slots). The same panel can switch between
+     * inline and drawer display across breakpoints — iframe state is
+     * preserved across the transition.
+     */
+    openDrawer: (panelId: string) => void;
+    /** Close a panel's drawer overlay. */
+    closeDrawer: (panelId: string) => void;
+    /** Flip a panel's drawer open state. */
+    toggleDrawer: (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;
+    /**
+     * Patch an existing panel's def at runtime — swap content kind / id /
+     * tagName, replace `route` / `title` / `icon`, or shallow-merge `props`.
+     * Unknown panelId is a silent no-op. Same merge semantics as the
+     * host-side `updatePanelLiveState`: `props` shallow-merges, other
+     * top-level fields replace wholesale.
+     */
+    updatePanel: (panelId: string, def: Partial<HostPanelDef>) => void;
+    /**
+     * Open a modal at runtime. The author's tagged-union content shape
+     * (`kind: 'page' | 'artifact' | 'component' | 'builtin'`) is mirrored
+     * into the host declaration so the modal's component / props can be
+     * resolved from the host side. Re-opening an already-open id is a
+     * silent no-op (matches host-side `manager.openModal`'s thrown
+     * `LayoutValidationError`, but downgraded for cross-boundary callers).
+     *
+     * Defaults to `<dialog showModal()>` rendering for top-layer stacking,
+     * focus trap, and inert propagation. Pass `def.useNativeDialog: false`
+     * to opt back into the legacy div-overlay path during migration.
+     */
+    openModal: (id: string, def: HostModalDef) => void;
     /** Close a currently-open modal by id. */
     closeModal: (modalId: string) => void;
+    /** Add a floating panel at runtime. Existing id is overwritten. */
+    addFloating: (id: string, def: HostFloatingDef) => void;
     /** Remove a floating panel by id. */
     removeFloating: (floatingId: string) => void;
+    /**
+     * Publish on the in-tab layout bus to every OTHER subscribed iframe
+     * panel and to host-mounted subscribers (components, services). The
+     * sender's own window is excluded from the iframe fan-out (the host
+     * receiver skips `w === source`); host-mounted handlers attached to
+     * the same panel still fire via the in-process LocalBus mirror.
+     * Subscribe via `host.layout.on(channel, handler)`.
+     */
+    broadcast: (channel: string, payload: unknown) => void;
+    /**
+     * Send to a specific panel only (1:1). Unknown target panelIds are
+     * silent no-ops on the iframe fan-out (matches `updatePanel`).
+     * `target = self` IS delivered: the receiver routes by `panelId →
+     * windows` without a source-equality check, so addressing your own
+     * panel loops the message back through `host.layout.on(...)`. Use
+     * this for the documented loop-through-coordinator pattern. Passing
+     * a non-string `target` throws — use `broadcast()` for 1:N.
+     */
+    send: (target: string, channel: string, payload: unknown) => void;
+    /**
+     * Subscribe to a layout-bus channel. Returns an `off()` function. The
+     * handler receives the full envelope including `sourcePanelId` (who
+     * published, `null` if from host system) and `targetPanelId` (who was
+     * addressed, `null` for 1:N broadcasts).
+     *
+     * Layout-bus channels are deliberately separate from WS topics — they
+     * never cross to other browser tabs and are scoped to the host page's
+     * lifetime.
+     */
+    on: (channel: string, handler: (env: BroadcastEnvelope) => void) => () => void;
 }
 
 type KnownTopics = '@history' | '@visibility' | '@message' | '@state-error' | '@layout-change' | '@layout-breakpoint';
@@ -1148,10 +1299,6 @@ interface ProxyApiInstance {
     loadWebComponent: (componentId: string, tagName?: string) => Promise<void>;
 }
 
-declare const GLOBAL_CONFIG_VAR: "__WIPPY_APP_CONFIG__";
-declare const GLOBAL_PROXY_CONFIG_VAR: "__WIPPY_PROXY_CONFIG__";
-declare const GLOBAL_API_PROVIDER: "__WIPPY_APP_API__";
-declare const GLOBAL_WEB_COMPONENT_CACHE: "__WIPPY_WEB_COMPONENT_CACHE__";
 declare global {
     interface Window {
         [GLOBAL_CONFIG_VAR]: AppConfig | ChildAppConfig;
@@ -1220,3 +1367,31 @@ declare global {
         [GLOBAL_PROXY_CONFIG_VAR]?: ProxyConfig;
     }
 }
+
+// Augment axios's request config so consumers can opt out of the proxy
+// api's default auth handling on a per-request basis. The proxy's createApi
+// reads `skipDefaultAuth` in both the request and response interceptors;
+// see `gen-2-chat:src/proxy/shared/api.ts` for the runtime semantics.
+declare module 'axios' {
+    interface AxiosRequestConfig {
+        /**
+         * Skip the proxy api's default auth handling for THIS request.
+         *
+         * When `true`:
+         *   - the request interceptor will NOT attach `Authorization: Bearer <token>`
+         *   - the response interceptor will NOT call `host.handleError('auth-expired')` on 401
+         *
+         * Use for:
+         *   - calls to a backend that uses a different auth domain
+         *   - calls that legitimately probe an unauthenticated endpoint
+         *   - calls where a 401 is meaningful but should not log the user out
+         *
+         * Cross-origin requests (URL with a different origin from the api's
+         * `baseURL`) auto-skip the Wippy default regardless of this flag.
+         */
+        skipDefaultAuth?: boolean;
+    }
+    interface InternalAxiosRequestConfig {
+        skipDefaultAuth?: boolean;
+    }
+}

package/package.json

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