pager-widget 1.0.11-alpha.9 → 1.0.13

package/docs/prd/0001-iframe-resize-scroll-through.md

@@ -1,333 +0,0 @@
-# PRD: iframe Container Resize for Page Scroll-Through
-
----
-
-## Problem Statement
-
-The Pager Widget is embedded inside an `<iframe>` to bypass SharePoint's Content-Security-Policy. The iframe is styled as `position: fixed; width: 100%; height: 100%; bottom: 0; right: 0; z-index: 9999` — covering the entire viewport.
-
-This creates a critical UX bug:
-
-- The iframe captures **all** pointer events on the page, even though the visible widget occupies only a small area (a launcher button when collapsed, or a chat panel when open).
-- Users **cannot scroll** the host page.
-- Users **cannot click** links, buttons, or any other interactive elements on the page behind the iframe.
-- The page is effectively frozen except for interaction with the widget itself.
-
-The widget is supposed to be a floating assistant, not a page takeover.
-
----
-
-## Architecture (Two-Tier Iframe Model)
-
-Replace the full-viewport iframe with a two-tier iframe pattern:
-
-```
-Customer's SharePoint page
-  │
-  └── <iframe src="https://.../embed/{widget_id}">      ← outer iframe (small, sized to content)
-        │
-        └── server.html (CONTAINER PAGE, served by backend)
-              │
-              ├── div#pager-widget-container
-              │     position:fixed; bottom:right; min 60×60px
-              │     dynamically resized via postMessage
-              │     │
-              │     └── <iframe src="https://.../wgt-hook/embed/...">  ← inner iframe
-              │           │
-              │           └── Widget React App
-              │                 └── useWidgetResize (ResizeObserver → postMessage)
-              │
-              └── Message listener: resizes div#pager-widget-container
-```
-
-The outer iframe is sized by SharePoint's web part to match however the
-back end decides to size it.  The container page (`server.html`) contains
-a fixed-position container div that starts at launcher size and is
-dynamically resized when the widget reports its actual dimensions.
-
-**Result:**
-- The outer iframe is small (matches widget's visible area) → 99% of the SharePoint page is free for scrolling/clicks.
-- When the widget is **collapsed** → container is ~60×60px → only the launcher is visible.
-- When the widget is **open** → container is ~448×637px → only the chat panel area captures events.
-- The page is never blocked from scrolling or clicking outside the widget's visible area.
-
----
-
-## User Stories
-
-1. As a page visitor, I want to scroll the content behind the widget launcher or chat panel, so that I can read long articles, forms, or product pages without the widget blocking me.
-
-2. As a page visitor, I want to click on links, buttons, and form fields on the page while the widget is present (even when open in a corner), so that I can interact with the page normally.
-
-3. As a page visitor, I want to click the widget's launcher button to open the chat, so that I can talk to the AI assistant when I choose to.
-
-4. As a page visitor, I want to click outside the chat panel (or hit close) to collapse the widget and return to full page interaction, so that I'm not stuck in the chat.
-
-5. As a developer, I want the widget to tell the parent page its current dimensions, so that the iframe container can be resized precisely to match what the user sees.
-
-6. As a developer, I want the resize logic to be in one place (the toggle handler), so that it's simple to maintain and debug.
-
-7. As a developer, I want the embed snippet to work for any customer without requiring them to write custom JavaScript, so that adoption is seamless.
-
----
-
-## Implementation Decisions
-
-### Module 1: Widget Frontend — ResizeObserver-based Hook
-
-**File**: `src/hooks/useWidgetResize.ts`
-
-**Purpose**: Send the widget's current rendered dimensions to the parent page whenever the widget's DOM size changes — toggle, expand, window resize, or any layout shift.
-
-**Behavior**:
-
-```typescript
-// src/hooks/useWidgetResize.ts
-import { useEffect } from 'react'
-
-export function useWidgetResize() {
-  useEffect(() => {
-    const el = document.querySelector('.pager-widget-root')
-    if (!el || window.parent === window) return
-
-    let rafId: number | null = null
-    const observer = new ResizeObserver(([entry]) => {
-      if (rafId) return // throttle to one rAF at a time
-      rafId = requestAnimationFrame(() => {
-        rafId = null
-        const { width, height } = entry.contentRect
-        if (width === 0 || height === 0) return
-        window.parent.postMessage(
-          {
-            type: 'widgetResize',
-            width: Math.ceil(width),
-            height: Math.ceil(height),
-          },
-          '*'
-        )
-      })
-    })
-    observer.observe(el)
-
-    // Fire initial size on mount
-    requestAnimationFrame(() => {
-      const rect = el.getBoundingClientRect()
-      if (rect.width > 0 && rect.height > 0) {
-        window.parent.postMessage(
-          {
-            type: 'widgetResize',
-            width: Math.ceil(rect.width),
-            height: Math.ceil(rect.height),
-          },
-          '*'
-        )
-      }
-    })
-
-    return () => {
-      observer.disconnect()
-      if (rafId) cancelAnimationFrame(rafId)
-    }
-  }, [])
-}
-```
-
-**Integration point**: Call this hook in `widget.tsx` where the toggle state lives, or in `App.tsx`:
-
-```typescript
-// src/widget.tsx
-export const Widget = (widgetConfig: WidgetConfigProps) => {
-  const [chatWindowStatus, toggleChatWindow] = useWidgetToggle(...)
-  useWidgetResize()
-  // ...
-}
-```
-
-**Why ResizeObserver instead of state-based**:
-- Catches ALL size changes (toggle, expand `DEFAULT`/`EXPANDED`/`FULLSCREEN`, window resize, content growth).
-- No need to track which state variable caused the resize — the DOM is the source of truth.
-- Reuses the same ResizeObserver pattern already used in `BotMain.tsx` (lines 70-81).
-- Eliminates the `setTimeout(50ms)` race condition — the observer fires after layout.
-- `requestAnimationFrame` throttling prevents flooding while staying responsive.
-
-**Edge cases handled**:
-- **Not in iframe**: Skip entirely — `window.parent === window`.
-- **Zero dimensions**: Skip if measured width or height is 0 (DOM not ready).
-- **Initial render**: Fires once on mount after the first rAF.
-- **Flood protection**: One message per animation frame via `rafId` guard.
-
-### Module 2: Backend Container Page — `server.html`
-
-**File**: `server.html` (updated)
-
-The backend serves a container page at `/embed/{widget_id}` that wraps the widget
-in a resizable container using HubSpot's pattern. Customers embed this page as an
-outer iframe on their SharePoint site.
-
-**Updated `server.html`**:
-
-```html
-<!doctype html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Pager Widget</title>
-  <style>
-    body { margin: 0; overflow: hidden; }
-  </style>
-</head>
-<body>
-<div id="pager-widget-container"
-     style="position:fixed;bottom:0;right:0;z-index:9999;min-height:60px;min-width:60px">
-  <iframe id="pager-widget-iframe"
-    src="https://dev.pagergpt.ai/wgt-hook/embed/ae320291-260f-48fc-a069-68ab73858664?v=1.0.10&SYS_FirstName=John&SYS_UserEmail=john@example.com"
-    style="position:absolute;width:100%!important;height:100%!important;border:none!important;bottom:0!important;right:0!important;background:transparent!important"
-    title="Pager Widget">
-  </iframe>
-</div>
-<script>
-(function() {
-  var container = document.getElementById('pager-widget-container');
-  var iframe = document.getElementById('pager-widget-iframe');
-
-  // Listen for resize messages from the widget
-  window.addEventListener('message', function(event) {
-    if (event.data && event.data.type === 'widgetResize') {
-      container.style.width = event.data.width + 'px';
-      container.style.height = event.data.height + 'px';
-    }
-  });
-
-  // Send user details to the inner widget iframe
-  iframe.addEventListener('load', function() {
-    iframe.contentWindow.postMessage({
-      type: 'userDetails',
-      data: {
-        SYS_FirstName: "{{firstName}}",
-        SYS_LastName: "{{lastName}}",
-        SYS_UserEmail: "{{email}}",
-        SYS_Location: "{{location}}",
-        SYS_Timezone: Intl.DateTimeFormat().resolvedOptions().timeZone
-      }
-    }, 'https://dev.pagergpt.ai');
-  });
-})();
-</script>
-</body>
-</html>
-```
-
-**Container CSS breakdown**:
-
-| Property | Value | Purpose |
-|---|---|---|
-| `position: fixed` | bottom; right | Anchors widget to viewport corner, scrolls with page |
-| `z-index: 9999` | high value | Stays above page content |
-| `min-height: 60px` | launcher button height | Prevents collapse to zero before first message |
-| `min-width: 60px` | launcher button width | Prevents collapse to zero before first message |
-| `width` / `height` | set dynamically | Updated by message listener |
-
-**Inner iframe CSS breakdown**:
-
-| Property | Value | Purpose |
-|---|---|---|
-| `position: absolute` | — | Fills the container, not the viewport |
-| `width: 100% !important` | — | Matches container width |
-| `height: 100% !important` | — | Matches container height |
-| `border: none !important` | — | No visible border |
-| `background: transparent !important` | — | No white flash behind the widget |
-
-**Security**: The `postMessage` listener does not check `event.origin` since different customers have different SharePoint domains. The widget side uses `targetOrigin: '*'`. This can be hardened later with a known-allowlist of customer origins.
-
-### Module 3: Backend iframe HTML Template
-
-**File**: `src/public/public.router.ts` (existing — no changes to the router)
-
-The backend route `GET /embed/:widget_id` continues to serve `server.html`.
-The template variables (`{{firstName}}`, `{{email}}`, etc.) are filled in by
-the backend. No router changes are needed — only the template file itself
-is updated (Module 2).
-
----
-
-## Testing Decisions
-
-### What makes a good test
-
-- Test the **contract**: when the widget toggles state, a `postMessage` with the correct shape is dispatched.
-- Test **edge cases**: not in iframe (skip), zero dimensions (skip), DOM not ready (skip).
-- Do NOT test the parent page's resize behavior — that requires a browser/DOM environment and is covered by manual QA.
-
-### Tests for Module 1 (useWidgetResize hook)
-
-**File**: `src/__tests__/useWidgetResize.test.ts`
-
-| Test | Input | Expected |
-|---|---|---|
-| ResizeObserver fires on size change | Mock ResizeObserver with 400×600 rect | `postMessage` called with `{ type: 'widgetResize', width: 400, height: 600 }` |
-| Skip if not in iframe | `window.parent === window` | `postMessage` NOT called |
-| Skip if dimensions are zero | Mock ResizeObserver with 0×0 rect | `postMessage` NOT called |
-| Initial mount fires one message | Simulate mount + rAF | `postMessage` called with actual dimensions |
-| Cleanup on unmount | Disconnect observer + cancel rAF | Observer.disconnect() called |
-
-### Prior art
-
-No existing tests in `poc-pager-widget` — this is the first. `vitest` must be installed as a devDependency along with `jsdom` environment.
-
-```bash
-npm install -D vitest jsdom
-```
-
----
-
-## Integration Points
-
-### Where to connect
-
-```
-server.html (served at /embed/{widget_id})
-  │
-  ├── Container div (fixed, bottom-right, min 60×60)
-  │   └── Inner iframe → Widget React App
-  │         │
-  │         ├── widget.tsx
-  │         │   ├── useWidgetToggle()         ← existing
-  │         │   ├── useWidgetResize()          ← NEW (ResizeObserver)
-  │         │   └── <WidgetToggleButton ... />
-  │         │
-  │         └── ResizeObserver fires → postMessage({ type: 'widgetResize', width, height })
-  │
-  └── Message listener receives postMessage
-      └── container.style.width = ...px
-      └── container.style.height = ...px
-```
-
-### Where is the toggle state?
-
-The widget already has a way to toggle open/collapsed. Find the existing open/close state — likely one of:
-- `widgetStore.ts` — the main xstate store
-- `widgetControlstore.ts` — widget control state
-- `WidgetToggleButton.tsx` — the toggle button component
-
-The hook needs to read this state. The exact store/state key needs to be identified during implementation.
-
----
-
-## Out of Scope
-
-- **Animation or transitions**: Container resize is instant. CSS `transition` on the container can be added later.
-- **Responsive dimensions**: The widget does not need to send resize events on window resize — ResizeObserver handles this automatically.
-- **Multiple widget instances**: Only one widget per page is supported.
-- **Mobile considerations**: The same pattern works on mobile. The dimensions sent will naturally be smaller due to viewport size. No special mobile handling needed.
-- **origin validation**: The parent page listens unconditionally. If needed later, the widget can harden `targetOrigin` or validate `event.origin`.
-
----
-
-## Further Notes
-
-- HubSpot's own widget uses exactly the container-resize pattern. Their container starts at minimum size and gets resized dynamically. This is a proven pattern used at scale.
-- The initial `min-height: 60px; min-width: 60px` matches the approximate launcher button size. When the widget first loads and sends its first `widgetResize` message, the container is resized to the actual rendered dimensions.
-- If the widget fails to send the initial resize message (e.g., JS error), the container stays at 60×60px — users will see a tiny square but the page remains fully functional. This is a safe failure mode.
-- The ResizeObserver fires for ANY size change: toggle open/close, expand (DEFAULT/EXPANDED/FULLSCREEN), window resize, or content growth. This is more robust than state-based triggers.
-- The widget URL (`https://dev.pagergpt.ai/wgt-hook/embed/{widget_id}?v={version}`) that the inner iframe loads is unaffected by this change — only `server.html` (the outer container page) is updated.

package/test-iframe-resize.html

@@ -1,74 +0,0 @@
-<!doctype html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Iframe Resize Test</title>
-  <style>
-    body { margin: 0; min-height: 200vh; background: #f5f5f5; font-family: sans-serif; }
-    .page-content { padding: 40px; max-width: 600px; }
-    h1 { color: #333; }
-    p { color: #666; line-height: 1.6; margin-bottom: 20px; }
-    .debug-panel {
-      position: fixed; top: 10px; left: 10px; z-index: 99999;
-      background: rgba(0,0,0,0.8); color: #0f0; padding: 10px 14px;
-      border-radius: 8px; font-size: 13px; font-family: monospace;
-      max-width: 300px;
-    }
-    .debug-panel div { margin: 2px 0; }
-  </style>
-</head>
-<body>
-  <div class="page-content">
-    <h1>Pager Widget — Iframe Resize Test</h1>
-    <p>This page simulates the container pattern from <code>server.html</code>.</p>
-    <p>The widget loads inside an iframe that is contained within a fixed-position
-       container div. The container starts at 60×60px and gets resized dynamically
-       when the widget sends <code>widgetResize</code> postMessages.</p>
-    <p><strong>Test checklist:</strong></p>
-    <ul>
-      <li>Page should be scrollable at all times (not blocked by iframe)</li>
-      <li>Widget launcher should be clickable</li>
-      <li>Opening the widget should resize the container (watch debug panel)</li>
-      <li>Clicking the X should collapse the widget and shrink the container</li>
-      <li>Clicking expand buttons (EXPANDED / FULLSCREEN) should resize container</li>
-      <li>Page content behind the widget should remain clickable</li>
-    </ul>
-    <p style="margin-top: 60vh;">↓ Scroll down (should work even with widget open)</p>
-    <p style="margin-top: 40vh;">Bottom of page. Scrolling worked!</p>
-  </div>
-
-  <!-- Container div with iframe (mimics server.html pattern) -->
-  <div id="pager-widget-container"
-       style="position:fixed;bottom:0;right:0;z-index:9999;min-height:60px;min-width:60px">
-    <iframe id="pager-widget-iframe"
-      src="http://localhost:8000/embed/ae320291-260f-48fc-a069-68ab73858664?v=1.0.11-alpha.7&SYS_FirstName=John&SYS_UserEmail=john@example.com"
-      style="position:absolute;width:100%;height:100%;border:none;background:transparent"
-      title="Pager Widget">
-    </iframe>
-  </div>
-
-  <script>
-    (function() {
-      var container = document.getElementById('pager-widget-container');
-
-      // Debug panel
-      var debug = document.createElement('div');
-      debug.className = 'debug-panel';
-      debug.innerHTML = '<div><strong>Resize Debug</strong></div><div id="debug-size">waiting...</div>';
-      document.body.appendChild(debug);
-      var debugSize = document.getElementById('debug-size');
-
-      window.addEventListener('message', function(event) {
-         console.log(event.data, "from inside iframe");
-        if (event.data && event.data.type === 'widgetResize') {
-          container.style.width = (Number(event.data.width) + 100) + 'px';
-          container.style.height = (Number(event.data.height) + 200) + 'px';
-          debugSize.textContent = event.data.width + ' x ' + event.data.height;
-          console.log('[widgetResize]', event.data.width, 'x', event.data.height);
-        }
-      });
-    })();
-  </script>
-</body>
-</html>