@e-llm-studio/citation 0.0.213 → 0.0.215

package/README.md

@@ -34,6 +34,7 @@
      - [ReviewPanel](#reviewpanel) [<img src="https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png" width="18" height="18">](https://github.com/Techolution/e-llm-studio-lib/blob/dev/citation/src/features/ReviewPanel/README.md)
      - [TableCitationContent](#tablecitationcontent) [<img src="https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png" width="18" height="18">](https://github.com/Techolution/e-llm-studio-lib/blob/dev/citation/src/features/TableCitation/README.md)
      - [SplitterCitationsComponent](#splittercitationscomponent) [<img src="https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png" width="18" height="18">](https://github.com/Techolution/e-llm-studio-lib/blob/dev/citation/src/features/SplitterCitations/README.md)
+     - [RuleBookCitationWrapper](#RuleBookCitationWrapper) [<img src="https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png" width="18" height="18">](https://github.com/Techolution/e-llm-studio-lib/blob/dev/citation/src/features/RuleBookCitations/README.md)
      -[ManageReminders](#ManageReminders) [<img src="https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png" width="18" height="18">](https://github.com/Techolution/e-llm-studio-lib/blob/dev/citation/src/features/ManageRemainders/README.md)
 4. [Common Use Cases](#common-use-cases)
 5. [Development & Contribution](#development--contribution)
@@ -680,31 +681,51 @@ const reasoningData = {
 
 `GptWebCitation` is a composite React component that wraps the GPT reasoning citation (`CognitiveInternalgptCoreComponent`) and adds an optional **Web Citation** view. Users can toggle between GPT and web-based citations without modifying the underlying GPT citation code.
 
-In **GPT view**, the component renders the standard GPT citation panel with a **View Web Citation** button on the left and the document source link on the right (inside the GPT citation footer). In **Web Citation view**, it shows a web snapshot (image or markdown content) with highlight navigation, relevance score, and a **View GPT Citation** toggle to switch back.
+In **GPT view**, the component renders the standard GPT citation panel with a **View Web Citation** button on the left and the document source link on the right (inside the GPT citation footer). In **Web Citation view**, it shows a screenshot snapshot of the source page (when available), a relevance score badge, visit links, and a **View GPT Citation** toggle to switch back.
+
+The component is **presentational** — it does not fetch web citations. The parent owns `webCitationData`, `webCitationStatus`, and view toggling.
 
 ### Features
 
 - **Dual citation views** — Toggle between GPT reasoning and web-based citation
 - **Non-invasive GPT integration** — Wraps `CognitiveInternalgptCoreComponent` via props; no changes to GPT citation code required
-- **Image & markdown web citations** — Supports screenshot snapshots (`imageMetadata.signed_url`) or HTML/markdown content
-- **Highlight pagination** — Navigate between highlighted anchors in web citation markdown
+- **Screenshot web citations** — Renders `imageMetadata.signed_url` when the API returns a snapshot
+- **Status-driven skeleton UI** — `"pending"` loading skeleton and `"error"` fallback with **Visit Link**
+- **`defaultCitationUrl`** — Immediate visit link while fetch is in progress (before `highlightedUrl` arrives)
+- **Visit link priority** — `highlightedUrl` from API response wins over `defaultCitationUrl` in pending/error states
 - **Relevance score badge** — Auto-extracted from web citation content (e.g. "decision strength is 85%")
-- **Loading skeleton** — Built-in loading state while web citation is being generated
 - **Expand screenshot button** — Optional full-screen image view (`showExpandImageButton`)
+- **Custom icons** — Override expand and external-link icons via `iconsConfig`
+- **Fixed height mode** — Optional `isFixedHeight` keeps GPT and web panels the same size with contained screenshots
 - **Style overrides** — Customize layout via the `styles` prop without editing component internals
 
 ### Installation / Import
 
 ```tsx
 import GptWebCitation from '@e-llm-studio/citation/GptWebCitation';
+
+// Optional utilities and types
+import {
+  mapCitationDataToDisplay,
+  getWebCitationImageUrl,
+  resolveSkeletonVisitUrl,
+  type GptWebCitationStatus,
+  type IWebCitationApiResponse,
+  type IGptWebCitationStyleOverrides,
+  type IGptWebCitationImageStyles,
+  type IGptWebCitationSkeletonStyles,
+  type IGptWebCitationVisitLinkStyles,
+  type IGptWebCitationFullScreenStyles,
+} from '@e-llm-studio/citation';
 ```
 
 ### Usage 1: Basic GPT + Web Citation Toggle
 
 ```tsx
 import { useState } from 'react';
-import { ChevronDown, ChevronUp, Maximize2, X } from 'lucide-react';
+import { ChevronDown, ChevronUp, ExternalLink, Maximize2, X } from 'lucide-react';
 import GptWebCitation from '@e-llm-studio/citation/GptWebCitation';
+import type { GptWebCitationStatus } from '@e-llm-studio/citation';
 
 const gptCitation = {
   item: {
@@ -726,31 +747,42 @@ const gptCitation = {
   previewCallback: () => window.open('/preview/document'),
 };
 
+const webCitationIcons = {
+  MaximizeIcon: Maximize2,
+  ExternalLinkIcon: ExternalLink,
+};
+
 function CitationPanel() {
   const [showWebCitation, setShowWebCitation] = useState(false);
   const [webCitationData, setWebCitationData] = useState(undefined);
-  const [isLoading, setIsLoading] = useState(false);
+  const [webCitationStatus, setWebCitationStatus] =
+    useState<GptWebCitationStatus>('pending');
 
   const handleGenerateWebCitation = async () => {
     setShowWebCitation(true);
-    setIsLoading(true);
-
-    const response = await fetch('/api/web-citation/generate');
-    const data = await response.json();
-
-    setWebCitationData(data);
-    setIsLoading(false);
+    setWebCitationStatus('pending');
+
+    try {
+      const response = await fetch('/api/web-citation/generate');
+      const data = await response.json();
+      setWebCitationData(data);
+      setWebCitationStatus('success');
+    } catch {
+      setWebCitationStatus('error');
+    }
   };
 
   return (
     <GptWebCitation
       gptCitation={gptCitation}
+      defaultCitationUrl="https://example.com/article"
       isWebCitation={true}
       webCitationData={webCitationData}
+      webCitationStatus={webCitationStatus}
       showWebCitation={showWebCitation}
-      isWebCitationLoading={isLoading}
       onGenerateWebCitation={handleGenerateWebCitation}
       onToggleCitationView={() => setShowWebCitation((prev) => !prev)}
+      iconsConfig={webCitationIcons}
     />
   );
 }
@@ -767,6 +799,8 @@ const webCitationData = {
     'The decision strength is 85% because:<ol><li>The exact <a href="https://example.com/article">valuation of SpaceX</a> fluctuates between sources.</li></ol>',
   citationType: 'web',
   citationUrl: 'https://example.com/article',
+  highlightedUrl: 'https://example.com/article#highlight',
+  message: 'Citation processed successfully',
   imageMetadata: {
     signed_url: 'https://storage.example.com/image_citations/screenshot.png',
     blob_path: 'image_citations/screenshot.png',
@@ -776,21 +810,33 @@ const webCitationData = {
 
 <GptWebCitation
   gptCitation={gptCitation}
+  defaultCitationUrl="https://example.com/article"
   isWebCitation={true}
   webCitationData={webCitationData}
+  webCitationStatus="success"
   showWebCitation={true}
 />
 ```
 
-When `imageMetadata.signed_url` is present, the component renders a screenshot snapshot. Otherwise it falls back to rendering the `content` field as markdown/HTML.
+When `imageMetadata.signed_url` is present and `webCitationStatus` is `"success"`, the component renders a screenshot snapshot. If the image is unavailable or the fetch fails, an error skeleton is shown with a **Visit Link** (using `highlightedUrl` or `defaultCitationUrl`).
+
+#### Visit link resolution
+
+| UI state | Visit link source |
+| --- | --- |
+| Pending / error skeleton | `highlightedUrl` from `webCitationData` → else `defaultCitationUrl` prop |
+| Screenshot footer (success) | `citationUrl` from `webCitationData` |
+
+Use `resolveSkeletonVisitUrl(highlightedUrl, defaultCitationUrl)` from `@e-llm-studio/citation` if you need the same logic outside the component.
 
 ### Usage 3: GPT-Only Mode (No Web Citation)
 
-Set `isWebCitation={false}` to render only the GPT citation with no toggle button:
+Set `isWebCitation={false}` to render only the GPT citation with no toggle button. `defaultCitationUrl` is still required by the prop contract but is unused in GPT-only mode:
 
 ```tsx
 <GptWebCitation
   gptCitation={gptCitation}
+  defaultCitationUrl="https://example.com/article"
   isWebCitation={false}
 />
 ```
@@ -802,8 +848,10 @@ Hide the web citation screenshot expand button:
 ```tsx
 <GptWebCitation
   gptCitation={gptCitation}
+  defaultCitationUrl="https://example.com/article"
   isWebCitation={true}
   webCitationData={webCitationData}
+  webCitationStatus="success"
   showWebCitation={true}
   showExpandImageButton={false}
 />
@@ -814,6 +862,7 @@ Hide the GPT citation header maximize/expand icon:
 ```tsx
 <GptWebCitation
   gptCitation={gptCitation}
+  defaultCitationUrl="https://example.com/article"
   isWebCitation={true}
   showGptMaximizeButton={false}
 />
@@ -823,7 +872,7 @@ You can also use `gptCitation.disableMaximize: true` directly on the GPT config.
 
 ### Usage 5: Custom Styling via Props (matched heights)
 
-Layout, borders, and heights for **both GPT and web views** can be controlled from the parent without modifying component internals:
+Layout, borders, and heights for **both GPT and web views** can be controlled from the parent without modifying component internals. Prefer **`isFixedHeight`** (Usage 6) when you only need equal panel size + contained screenshots; use `styles` when you need granular control over skeleton, image, visit-link, or full-screen elements:
 
 ```tsx
 const sharedPanelHeight = '520px';
@@ -834,9 +883,15 @@ const sharedContentHeight = '384px';
     ...gptCitation,
     bodyHeight: sharedContentHeight,
   }}
+  defaultCitationUrl="https://example.com/article"
   isWebCitation={true}
   webCitationData={webCitationData}
+  webCitationStatus="success"
   showGptMaximizeButton={true}
+  iconsConfig={{
+    MaximizeIcon: Maximize2,
+    ExternalLinkIcon: ExternalLink,
+  }}
   styles={{
     container: { maxWidth: 900 },
     gptCitation: {
@@ -877,33 +932,143 @@ const sharedContentHeight = '384px';
 | `gptCitation.footerAction` | GPT view | View Web Citation button row in footer |
 | `gptCitation.toggleButton` | GPT view | View Web Citation button styles |
 | `webCitation.panel` | Web view | Outer web citation card |
-| `webCitation.header` | Web view | Source label + pagination + score badge row |
-| `webCitation.content` | Web view | Main content area (markdown, image, skeleton) |
+| `webCitation.header` | Web view | Source label + relevance score badge row |
+| `webCitation.content` | Web view | Screenshot or loading/error skeleton |
 | `webCitation.footer` | Web view | View GPT Citation + Learned From row |
 | `webCitation.toggleButton` | Web view | View GPT Citation button styles |
 | `webCitation.learnedFrom` | Web view | "Learned From …" text styles |
+| `webCitation.visitLink.row` | Image + skeleton | Shared visit link row (merged with scoped overrides below) |
+| `webCitation.visitLink.hint` | Image + skeleton | Shared visit link hint text |
+| `webCitation.visitLink.link` | Image + skeleton | Shared visit link anchor styles |
+| `webCitation.image.wrapper` | Screenshot view | Outer image citation wrapper |
+| `webCitation.image.center` | Screenshot view | Center column (viewport or inline skeleton) |
+| `webCitation.image.viewport` | Screenshot view | Viewport around scroll container |
+| `webCitation.image.scrollContainer` | Screenshot view | Scrollable screenshot container |
+| `webCitation.image.image` | Screenshot view | Screenshot `<img>` element |
+| `webCitation.image.expandButton` | Screenshot view | Full-screen expand button |
+| `webCitation.image.visitLink.*` | Screenshot footer | Image-specific visit link overrides (merged on top of `webCitation.visitLink`) |
+| `webCitation.image.fullScreen.overlay` | Full-screen viewer | Portal overlay backdrop |
+| `webCitation.image.fullScreen.content` | Full-screen viewer | Modal content card |
+| `webCitation.image.fullScreen.closeButton` | Full-screen viewer | Close button |
+| `webCitation.image.fullScreen.imageWrapper` | Full-screen viewer | Scrollable image wrapper |
+| `webCitation.image.fullScreen.image` | Full-screen viewer | Full-screen `<img>` |
+| `webCitation.skeleton.container` | Pending/error | Outer skeleton column |
+| `webCitation.skeleton.frame` | Pending/error | Gray skeleton frame |
+| `webCitation.skeleton.shimmer` | Pending | Shimmer animation overlay |
+| `webCitation.skeleton.pending.content` | Pending | Centered pending content block |
+| `webCitation.skeleton.pending.text` | Pending | Loading message text |
+| `webCitation.skeleton.pending.actionRow` | Pending | Visit link row |
+| `webCitation.skeleton.pending.actionHint` | Pending | "to view details" hint |
+| `webCitation.skeleton.error.content` | Error | Error content block |
+| `webCitation.skeleton.error.title` | Error | "No preview available" title |
+| `webCitation.skeleton.error.message` | Error | Restriction message |
+| `webCitation.skeleton.error.actionGroup` | Error | Action row wrapper |
+| `webCitation.skeleton.error.detailsToggle` | Error | Error details expand button |
+| `webCitation.skeleton.error.detailsMessage` | Error | Expanded error details text |
+| `webCitation.skeleton.error.visitLinkGlow` | Error | Glowing visit link (merged on top of visit link styles) |
+| `webCitation.skeleton.visitLink.*` | Pending/error | Skeleton-specific visit link overrides (merged on top of `webCitation.visitLink`) |
 
 Legacy flat keys (`gptCitationWrapper`, `footerAction`, `webCitationButton`) still work for backward compatibility.
 
+#### Example: customize screenshot and pending skeleton
+
+```tsx
+<GptWebCitation
+  gptCitation={gptCitation}
+  defaultCitationUrl="https://example.com/article"
+  isWebCitation
+  webCitationData={data}
+  webCitationStatus={status}
+  styles={{
+    webCitation: {
+      visitLink: {
+        link: { backgroundColor: 'rgba(37, 99, 235, 0.08)', borderRadius: 8 },
+      },
+      image: {
+        scrollContainer: { borderRadius: 16, borderColor: '#d1d5db' },
+        image: { objectFit: 'contain', maxHeight: 360 },
+        expandButton: { backgroundColor: '#111827' },
+      },
+      skeleton: {
+        frame: { minHeight: 320, backgroundColor: '#f8fafc' },
+        pending: {
+          text: { fontSize: 14, color: '#374151' },
+        },
+        error: {
+          title: { color: '#dc2626' },
+          visitLinkGlow: { borderColor: '#dc2626' },
+        },
+      },
+    },
+  }}
+/>
+```
+
+### Usage 6: Fixed height mode (matched GPT + web panels)
+
+Set `isFixedHeight={true}` when you want GPT and web citation views to share the same panel dimensions. Screenshots use `object-fit: contain` so tall pages stay inside the box without layout shift when toggling views.
+
+```tsx
+<GptWebCitation
+  gptCitation={{
+    ...gptCitation,
+    bodyHeight: '384px', // optional — customizes inner content height
+  }}
+  defaultCitationUrl="https://example.com/article"
+  isWebCitation
+  isFixedHeight
+  webCitationData={webCitationData}
+  webCitationStatus="success"
+  showWebCitation={showWebCitation}
+  onToggleCitationView={() => setShowWeb((v) => !v)}
+/>
+```
+
+| Scenario | Panel height |
+| --- | --- |
+| `isFixedHeight` + `isWebCitation` (toggle footer present) | `520px` default, or `calc(bodyHeight + 3.25rem)` when `gptCitation.bodyHeight` is set |
+| `isFixedHeight` + `isWebCitation={false}` (GPT only) | `520px` default, or `gptCitation.bodyHeight` when set |
+
+`isFixedHeight` applies flex layout and contained images automatically. For manual per-element styling without fixed dimensions, use `styles` (Usage 5) instead.
+
 ### Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `gptCitation` | `IGptCitationConfig` | **required** | GPT citation config passed to `CognitiveInternalgptCoreComponent` (`item`, `headerTitle`, `iconsConfig`, `DocumentTitle`, `previewCallback`, etc.) |
-| `isWebCitation` | `boolean` | `false` | When `true`, enables web citation toggle and web view. When `false`, only GPT citation is shown. |
-| `webCitationData` | `IWebCitationApiResponse` | — | Web citation API response (content, image snapshot, URL) |
-| `showWebCitation` | `boolean` | — | Controls which view is active. Omit for uncontrolled internal state. |
-| `onGenerateWebCitation` | `() => void` | — | Called when user clicks **View Web Citation** and no cached web data exists yet |
-| `isWebCitationLoading` | `boolean` | `false` | Parent-controlled loading state while web citation is being fetched |
+| `gptCitation` | `IGptCitationConfig` | **required** | GPT citation config passed to `CognitiveInternalgptCoreComponent` |
+| `defaultCitationUrl` | `string` | **required** | Fallback source URL for **Visit Link** in pending/error skeletons. Used when `webCitationData.highlightedUrl` is not yet available |
+| `isWebCitation` | `boolean` | `false` | When `true`, enables web citation toggle and web view |
+| `webCitationData` | `IWebCitationApiResponse` | — | Web citation API response (screenshot metadata, URLs, optional message) |
+| `webCitationStatus` | `"pending"` \| `"success"` \| `"error"` | inferred | Lifecycle status from parent API call. Inferred from `webCitationData` when omitted |
+| `showWebCitation` | `boolean` | `true` (uncontrolled) | `false` = GPT view, `true` = web view. Omit for uncontrolled internal state |
+| `onGenerateWebCitation` | `() => void` | — | Called when web view opens and no cached screenshot exists. Parent should fetch and update status/data. Also invoked once on mount when `isWebCitation` + `showWebCitation` are true and no image is cached |
 | `onToggleCitationView` | `() => void` | — | Called when user toggles between GPT and web views |
-| `showExpandImageButton` | `boolean` | `true` | Show/hide the full-screen expand button on web citation image snapshots |
-| `showGptMaximizeButton` | `boolean` | `true` | Show/hide the GPT citation header maximize/expand icon (`gptCitation.disableMaximize: true` when `false`) |
-| `topic` | `string` | auto | Override topic label in web citation header (auto-extracted from content if omitted) |
+| `showExpandImageButton` | `boolean` | `true` | Show/hide full-screen expand on screenshot |
+| `showGptMaximizeButton` | `boolean` | `true` | Show/hide GPT header maximize icon (`gptCitation.disableMaximize: true` when `false`) |
+| `iconsConfig` | `IGptWebCitationImageIconsConfig` | — | `MaximizeIcon` and `ExternalLinkIcon` overrides for web view |
+| `topic` | `string` | auto | Override topic label in web header |
 | `sourceLabel` | `string` | auto | Override header source label in web view |
-| `relevanceScore` | `number` | auto | Override relevance/decision strength score (auto-extracted from content if omitted) |
-| `learnedFrom` | `string` | auto | Site name shown in web citation footer (auto-extracted from `citationUrl` if omitted) |
+| `relevanceScore` | `number` | auto | Override relevance/decision strength badge (%) |
+| `learnedFrom` | `string` | auto | Site name in web footer (auto-derived from `citationUrl`) |
+| `sourceModel` | `string` | — | **Deprecated.** Use `sourceLabel` instead |
+| `isFixedHeight` | `boolean` | `false` | When `true`, GPT and web panels share the same fixed height/width; screenshot uses `object-fit: contain` |
 | `styles` | `IGptWebCitationStyleOverrides` | — | Style overrides for GPT and web citation views (see Usage 5) |
 
+When `isFixedHeight` is `true`, both views use the same panel height (`520px` by default, or `gptCitation.bodyHeight` + toggle footer). Pair with `gptCitation.bodyHeight` to customize the content area (e.g. `"384px"`).
+
+#### `webCitationStatus` inference
+
+When `webCitationStatus` is omitted, the component derives it in this order:
+
+| Priority | Condition | Status |
+| --- | --- | --- |
+| 1 | Valid screenshot URL in `webCitationData` (`signed_url` or `gs_uri`) | `"success"` (always — image wins over explicit status) |
+| 2 | Explicit `webCitationStatus` prop | uses prop value |
+| 3 | `webCitationData` present but no image URL | `"error"` |
+| 4 | No `webCitationData` | `"pending"` |
+
+Pass `webCitationStatus="pending"` explicitly while your fetch is in flight (before the image URL is available).
+
 ### `IGptCitationConfig` (gptCitation prop)
 
 | Field | Type | Description |
@@ -912,35 +1077,87 @@ Legacy flat keys (`gptCitationWrapper`, `footerAction`, `webCitationButton`) sti
 | `headerTitle` | `string` | Panel header title |
 | `index` | `number` | Citation index |
 | `iconsConfig` | `object` | Icon components (`ChevronDownIcon`, `ChevronUpIcon`, `MaximizeIcon`, `CloseIcon`) |
-| `DocumentTitle` | `string` | Source document label shown in the GPT footer (right side) |
+| `DocumentTitle` | `string` | Source document label shown in the GPT footer (right side). Hidden when `isWebCitation` is true |
 | `previewCallback` | `() => void` | Called when the source link is clicked |
-| `bodyHeight` | `string` | Optional fixed GPT content body height (use with `styles.webCitation.content` to match web view height) |
+| `bodyHeight` | `string` | Optional fixed GPT content body height (pair with `styles.webCitation.content`) |
 | `disableMaximize` | `boolean` | Disable GPT header fullscreen maximize button (or use `showGptMaximizeButton={false}`) |
 
+### `IGptWebCitationImageIconsConfig` (iconsConfig prop)
+
+| Field | Type | Fallback |
+|-------|------|----------|
+| `MaximizeIcon` | `ElementType` | `gptCitation.iconsConfig.MaximizeIcon`, then `Maximize2` |
+| `ExternalLinkIcon` | `ElementType` | `ExternalLink` |
+
+### Style override types (`styles` prop)
+
+Nested under `styles.webCitation`:
+
+| Type | Keys | Purpose |
+| --- | --- | --- |
+| `IGptWebCitationVisitLinkStyles` | `row`, `hint`, `link` | Visit link row shared by image footer and skeletons |
+| `IGptWebCitationImageStyles` | `wrapper`, `center`, `viewport`, `scrollContainer`, `image`, `expandButton`, `visitLink`, `fullScreen` | Screenshot view + inline loading skeleton while image decodes |
+| `IGptWebCitationSkeletonStyles` | `container`, `frame`, `shimmer`, `pending.*`, `error.*`, `visitLink` | Pending/error skeleton UI |
+| `IGptWebCitationFullScreenStyles` | `overlay`, `content`, `closeButton`, `imageWrapper`, `image` | Full-screen screenshot modal |
+
+`webCitation.visitLink` merges with scoped `image.visitLink` or `skeleton.visitLink` overrides (scoped wins on conflict).
+
 ### `IWebCitationApiResponse` (webCitationData prop)
 
 | Field | Type | Description |
 |-------|------|-------------|
 | `citationId` | `string` | Unique citation identifier |
-| `content` | `string` | HTML/markdown web citation content |
+| `content` | `string` | HTML/markdown explanation (used for topic/score extraction) |
 | `citationType` | `string` | Citation type (e.g. `"web"`) |
-| `citationUrl` | `string` | Original source URL |
+| `citationUrl` | `string` | Original source URL (screenshot footer **Visit Link**) |
+| `highlightedUrl` | `string` | Highlighted URL from API (preferred for skeleton **Visit Link**) |
+| `message` | `string` | API status or error message |
 | `imageMetadata` | `object` | Image snapshot metadata |
-| `imageMetadata.signed_url` | `string` | Signed URL for screenshot image (preferred) |
+| `imageMetadata.signed_url` | `string` | Signed URL for screenshot (preferred) |
 | `imageMetadata.gs_uri` | `string` | GCS URI fallback for image |
 | `db` | `object` | Database metadata (`citation_id`, `blob_path`) |
 
+### Utility helpers
+
+Exported from `@e-llm-studio/citation`:
+
+| Function | Purpose |
+| --- | --- |
+| `mapCitationDataToDisplay(data)` | Normalizes API response → display fields (`topic`, `highlightedUrl`, `relevanceScore`, etc.) |
+| `getWebCitationImageUrl(data)` | Resolves screenshot URL from `imageMetadata` |
+| `resolveSkeletonVisitUrl(highlightedUrl, defaultCitationUrl)` | Visit link for pending/error skeletons |
+| `extractTopicFromContent(content)` | First anchor text from content |
+| `extractRelevanceScoreFromContent(content)` | Parses decision strength / confidence % |
+| `extractLearnedFromUrl(citationUrl)` | Hostname → site name for footer |
+| `sanitizeExternalUrl(url)` | Safe http(s) URL for links |
+
 ### View Behavior
 
 | State | What renders |
 |-------|--------------|
 | `isWebCitation={false}` | GPT citation only |
-| `isWebCitation={true}`, `showWebCitation={false}` | GPT citation + **View Web Citation** button (left footer) + source link (right footer) |
-| `isWebCitation={true}`, `showWebCitation={true}` | Web citation panel with snapshot/markdown, highlight nav, and **View GPT Citation** button |
+| `isWebCitation={true}`, `showWebCitation={false}` | GPT citation + **View Web Citation** button |
+| `isWebCitation={true}`, `showWebCitation={true}`, `webCitationStatus="pending"` | Shimmer skeleton + optional **Visit Link** (`highlightedUrl` → `defaultCitationUrl`) |
+| `isWebCitation={true}`, `showWebCitation={true}`, `webCitationStatus="success"` | Screenshot (pending skeleton while image loads) + footer **Visit Link** |
+| `isWebCitation={true}`, `showWebCitation={true}`, `webCitationStatus="error"` | Error skeleton ("No preview available") + inline **Visit Link** |
+| `isFixedHeight={true}` | GPT and web outer panels share height; screenshot `object-fit: contain`; skeleton fills content area |
+
+#### Auto-fetch
+
+When `isWebCitation` is true and the web view is open with no cached screenshot, `onGenerateWebCitation` is called:
+
+1. Once on mount (per `webCitationData.citationId`)
+2. Again when the user clicks **View Web Citation** and no image is cached
+
+The parent should set `webCitationStatus="pending"`, fetch, then update `webCitationData` and status.
+
+#### Error skeleton
+
+The error state shows a fixed title ("No preview available"), a restriction message ("This website restricts external previews"), and an inline **Visit Link** when a source URL is available.
 
 ### Local Test Component
 
-A test harness is available at `src/features/GptWebCitation/GptWebCitationTest.tsx`. Run the citation dev server with `GptWebCitationTest` mounted in `src/index.tsx` to preview the component interactively.
+A test harness is available at `src/features/GptWebCitation/GptWebCitationTest.tsx`. Run the citation dev server with `GptWebCitationTest` mounted in `src/index.tsx` to preview the component interactively. The harness uses `sampleWebCitationApiResponse` from `WebCitationSampleResponse.ts`, simulates a 2s fetch delay when **View Web Citation** is clicked, and accepts `isFixedHeight`, `webCitationStatus`, `iconsConfig`, and `styles` props for local experimentation.
 
 ---
 
@@ -2378,6 +2595,58 @@ function App() {
 
 ---
 
+## RuleBookCitationWrapper
+
+A React component used to render Rule Book citation content with highlighted citation phrases.
+
+The component fetches citation metadata, resolves the associated Rule Book file, extracts textual guideline content, and displays it using the `TextualGuideLinesComponent`.
+
+### Usage
+
+```tsx
+import { RuleBookCitationWrapper } from "<library-name>";
+
+const sourceAttachments = [
+  {
+    id: "file-001",
+    name: "RuleBook.json",
+    gcsUrl: "gs://bucket/rulebook.json",
+    is_guideline_file: true,
+  },
+];
+
+<RuleBookCitationWrapper
+  requestId="citation-request-id"
+  citationIndex={0}
+  accessToken="access-token"
+  sourceAttachments={sourceAttachments}
+/>
+```
+
+### Props
+
+### `RuleBookCitationWrapperProps`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `requestId` | `string \| null` | `undefined` | Identifier used to fetch citation metadata |
+| `citationIndex` | `number` | `0` | Index of the citation to display |
+| `accessToken` | `string` | — | Authentication token used for citation API requests |
+| `sourceAttachments` | `SourceAttachment[] \| Record<string, SourceAttachment[]>` | `[]` | Source files containing Rule Book metadata |
+
+---
+
+### SourceAttachment
+
+| Prop | Type | Description |
+|---|---|---|
+| `id` | `string` | File identifier matching citation `file_id` |
+| `gcsUrl` | `string` | GCS location of the Rule Book file |
+| `name` | `string` | Optional file name |
+| `is_guideline_file` | `boolean` | Indicates whether the file contains guideline/rule book content |
+
+---
+
 ## SplitterCitationsComponent
 
 A responsive, draggable split-pane layout component for React. Renders two panels side-by-side (horizontal) or stacked (vertical) with a draggable divider. Automatically switches to vertical layout when the container is narrower than 500 px. Supports panel collapse/expand and an optional header with a confidence score badge.

package/dist/cjs/features/GptWebCitation/GptWebCitation.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var e=require("tslib"),t=require("react/jsx-runtime"),i=require("react"),n=require("lucide-react"),a=require("../CognitiveInternalgptReasoning/CognitiveInternalgptCoreComponent.js"),o=require("./GptWebCitationImageCitation.js"),l=require("./GptWebCitationMarkdown.js"),s=require("./GptWebCitationSkeleton.js"),r=require("./utils/citationData.utils.js"),u=require("./GptWebCitation.module.css.js"),d=require("../../assests/svg/NeuralNetworkIcon.js"),c=function(i){var a=i.variant,o=i.disabled,l=i.onClick,s=i.title,r=i.style;return t.jsx("button",e.__assign({type:"button",className:u.default.webCitationButton,onClick:l,disabled:o,title:s,style:r},{children:"gpt"===a?t.jsxs(t.Fragment,{children:[t.jsx(d.default,{className:u.default.webCitationButtonIcon}),"View GPT Citation"]}):t.jsxs(t.Fragment,{children:[t.jsx(n.Globe,{size:24,className:u.default.webCitationButtonIcon}),"View Web Citation"]})}))},g=function(){return t.jsx(s.default,{})};exports.default=function(s){var d,v,p,_=s.gptCitation,b=s.isWebCitation,C=void 0!==b&&b,f=s.webCitationData,m=s.topic,x=s.sourceLabel,h=s.relevanceScore,j=s.learnedFrom,w=s.onGenerateWebCitation,y=s.isWebCitationLoading,N=void 0!==y&&y,W=s.showWebCitation,B=s.onToggleCitationView,F=s.showExpandImageButton,k=void 0===F||F,I=s.showGptMaximizeButton,q=s.styles,M=i.useMemo(function(){return function(t){var i,n,a,o,l,s,r,u,d;return{container:null==t?void 0:t.container,gptWrapper:e.__assign(e.__assign({},null===(i=null==t?void 0:t.gptCitation)||void 0===i?void 0:i.wrapper),null==t?void 0:t.gptCitationWrapper),gptFooterAction:e.__assign(e.__assign({},null===(n=null==t?void 0:t.gptCitation)||void 0===n?void 0:n.footerAction),null==t?void 0:t.footerAction),gptToggleButton:e.__assign(e.__assign({},null===(a=null==t?void 0:t.gptCitation)||void 0===a?void 0:a.toggleButton),null==t?void 0:t.webCitationButton),webPanel:e.__assign(e.__assign({},null==t?void 0:t.container),null===(o=null==t?void 0:t.webCitation)||void 0===o?void 0:o.panel),webHeader:null===(l=null==t?void 0:t.webCitation)||void 0===l?void 0:l.header,webContent:null===(s=null==t?void 0:t.webCitation)||void 0===s?void 0:s.content,webFooter:null===(r=null==t?void 0:t.webCitation)||void 0===r?void 0:r.footer,webToggleButton:e.__assign(e.__assign({},null===(u=null==t?void 0:t.webCitation)||void 0===u?void 0:u.toggleButton),null==t?void 0:t.webCitationButton),webLearnedFrom:null===(d=null==t?void 0:t.webCitation)||void 0===d?void 0:d.learnedFrom}}(q)},[q]),S=i.useMemo(function(){return e.__assign(e.__assign(e.__assign({},_),{disableMaximize:void 0!==I?!I:_.disableMaximize}),C?{DocumentTitle:void 0,previewCallback:void 0}:{})},[_,I,C]),T=i.useState(!1),D=T[0],G=T[1],z=i.useState(0),A=z[0],H=z[1],L=i.useState(0),P=L[0],E=L[1],U=null!=W?W:D,V=void 0!==W,O=i.useMemo(function(){return f?r.mapCitationDataToDisplay(f):null},[f]),R=null!==(d=null!=m?m:null==O?void 0:O.topic)&&void 0!==d?d:"Web Citation",J=null!==(v=null!=h?h:null==O?void 0:O.relevanceScore)&&void 0!==v?v:0,K=null!=j?j:null==O?void 0:O.learnedFrom,Q=null!==(p=null==O?void 0:O.content)&&void 0!==p?p:"",X=null==O?void 0:O.citationUrl,Y=r.getWebCitationImageUrl(f),Z=!!Y,$=!!Q,ee=Z||$,te=N&&!Z;i.useEffect(function(){H(0)},[Q,R,null==f?void 0:f.citationId]);var ie=i.useCallback(function(){B?B():V||G(!1)},[B,V]),ne=i.useCallback(function(){B?B():V||G(!0),ee||N||null==w||w()},[B,V,ee,N,w]),ae=i.useCallback(function(){H(function(e){return Math.min(e+1,Math.max(P-1,0))})},[P]),oe=i.useCallback(function(){H(function(e){return Math.max(e-1,0)})},[]),le=null!=x?x:"Source: Web Citation > ".concat(R),se=function(i){var n=!!S.DocumentTitle,o=n?"".concat(u.default.gptCitationWrapper," ").concat(u.default.gptCitationWrapperWithSource):u.default.gptCitationWrapper;return t.jsxs("div",e.__assign({className:o,style:M.gptWrapper},{children:[t.jsx(a.default,e.__assign({},S,{splitterCustomStyle:!0})),i&&(n?t.jsx("div",e.__assign({className:u.default.gptCitationFooterAction,style:M.gptFooterAction},{children:i})):t.jsx("div",e.__assign({className:u.default.gptCitationToggleFooter,style:M.gptFooterAction},{children:i})))]}))};return C?U?t.jsxs("div",e.__assign({className:u.default.panel,style:M.webPanel},{children:[t.jsxs("div",e.__assign({className:u.default.panelHeader,style:M.webHeader},{children:[t.jsx("span",e.__assign({className:u.default.panelSource},{children:le})),t.jsxs("div",e.__assign({className:u.default.panelHeaderActions},{children:[$&&!te&&P>0&&t.jsxs("div",e.__assign({className:u.default.pagination},{children:[t.jsx("button",e.__assign({type:"button",onClick:oe,disabled:0===A,className:u.default.paginationButton,"aria-label":"Previous highlight"},{children:t.jsx(n.ChevronUp,{size:14})})),t.jsxs("span",e.__assign({className:u.default.paginationLabel},{children:[A+1," / ",P]})),t.jsx("button",e.__assign({type:"button",onClick:ae,disabled:A>=P-1,className:u.default.paginationButton,"aria-label":"Next highlight"},{children:t.jsx(n.ChevronDown,{size:14})}))]})),J>0&&t.jsxs("div",e.__assign({className:u.default.confidenceBadge,title:"Decision strength"},{children:[t.jsx(n.Sparkles,{size:14}),J,"%"]}))]}))]})),t.jsx("div",e.__assign({className:"".concat(u.default.panelContent).concat(te||Z?" ".concat(u.default.panelContentExpanded):""),style:M.webContent},{children:te?t.jsx(g,{}):Z&&Y?t.jsx(o.default,{citationImage:Y,citationUrl:X,showExpandImageButton:k}):$?t.jsx(l.default,{content:Q,activeHighlightIndex:A,onHighlightCountChange:E}):t.jsx(g,{})})),t.jsxs("div",e.__assign({className:u.default.panelFooter,style:M.webFooter},{children:[t.jsx(c,{variant:"gpt",disabled:te,onClick:ie,style:M.webToggleButton}),K&&t.jsxs("span",e.__assign({className:u.default.learnedFrom,style:M.webLearnedFrom},{children:["Learned From ",K]}))]}))]})):t.jsx("div",e.__assign({className:u.default.overlay,style:M.container},{children:se(t.jsx(c,{variant:"web",disabled:N,onClick:ne,title:"View web-based citation for this source.",style:M.gptToggleButton}))})):t.jsx("div",e.__assign({className:u.default.overlay,style:M.container},{children:se()}))};
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var e=require("tslib"),i=require("react/jsx-runtime"),t=require("react"),n=require("lucide-react"),o=require("../CognitiveInternalgptReasoning/CognitiveInternalgptCoreComponent.js"),l=require("./GptWebCitationImageCitation.js"),a=require("./GptWebCitationSkeleton.js"),s=require("./utils/citationData.utils.js"),r=require("./utils/styleOverrides.utils.js"),u=require("./utils/fixedHeight.utils.js"),d=require("./GptWebCitation.module.css.js"),c=require("../../assests/svg/NeuralNetworkIcon.js"),g=function(t){var o=t.variant,l=t.disabled,a=t.onClick,s=t.title,r=t.style;return i.jsx("button",e.__assign({type:"button",className:d.default.webCitationButton,onClick:a,disabled:l,title:s,style:r},{children:"gpt"===o?i.jsxs(i.Fragment,{children:[i.jsx(c.default,{className:d.default.webCitationButtonIcon}),"View GPT Citation"]}):i.jsxs(i.Fragment,{children:[i.jsx(n.Globe,{size:24,className:d.default.webCitationButtonIcon}),"View Web Citation"]})}))};exports.default=function(c){var v,p,b,_=c.gptCitation,C=c.defaultCitationUrl,f=c.isWebCitation,m=void 0!==f&&f,x=c.webCitationData,w=c.topic,h=c.sourceLabel,k=c.relevanceScore,j=c.learnedFrom,y=c.webCitationStatus,F=c.onGenerateWebCitation,S=c.showWebCitation,I=c.onToggleCitationView,L=c.showExpandImageButton,W=void 0===L||L,B=c.showGptMaximizeButton,H=c.iconsConfig,N=c.isFixedHeight,M=void 0!==N&&N,V=c.styles,q=t.useMemo(function(){return function(i){var t,n,o,l,a,s,u,d,c,g,v;return{container:null==i?void 0:i.container,gptWrapper:e.__assign(e.__assign({},null===(t=null==i?void 0:i.gptCitation)||void 0===t?void 0:t.wrapper),null==i?void 0:i.gptCitationWrapper),gptFooterAction:e.__assign(e.__assign({},null===(n=null==i?void 0:i.gptCitation)||void 0===n?void 0:n.footerAction),null==i?void 0:i.footerAction),gptToggleButton:e.__assign(e.__assign({},null===(o=null==i?void 0:i.gptCitation)||void 0===o?void 0:o.toggleButton),null==i?void 0:i.webCitationButton),webPanel:e.__assign(e.__assign({},null==i?void 0:i.container),null===(l=null==i?void 0:i.webCitation)||void 0===l?void 0:l.panel),webHeader:null===(a=null==i?void 0:i.webCitation)||void 0===a?void 0:a.header,webContent:null===(s=null==i?void 0:i.webCitation)||void 0===s?void 0:s.content,webFooter:null===(u=null==i?void 0:i.webCitation)||void 0===u?void 0:u.footer,webToggleButton:e.__assign(e.__assign({},null===(d=null==i?void 0:i.webCitation)||void 0===d?void 0:d.toggleButton),null==i?void 0:i.webCitationButton),webLearnedFrom:null===(c=null==i?void 0:i.webCitation)||void 0===c?void 0:c.learnedFrom,webImage:null===(g=null==i?void 0:i.webCitation)||void 0===g?void 0:g.image,webSkeleton:null===(v=null==i?void 0:i.webCitation)||void 0===v?void 0:v.skeleton,webImageVisitLink:r.resolveWebCitationVisitLinkStyles(null==i?void 0:i.webCitation,"image"),webSkeletonVisitLink:r.resolveWebCitationVisitLinkStyles(null==i?void 0:i.webCitation,"skeleton")}}(V)},[V]),E=t.useMemo(function(){return M?u.resolveFixedHeightLayout(_.bodyHeight,m):null},[M,_.bodyHeight,m]),T=t.useMemo(function(){return E?u.getFixedPanelStyle(E.panelHeight):void 0},[E]),z=t.useMemo(function(){var e,i;return{MaximizeIcon:null!==(e=null==H?void 0:H.MaximizeIcon)&&void 0!==e?e:null===(i=_.iconsConfig)||void 0===i?void 0:i.MaximizeIcon,ExternalLinkIcon:null==H?void 0:H.ExternalLinkIcon}},[H,null===(v=_.iconsConfig)||void 0===v?void 0:v.MaximizeIcon]),U=t.useMemo(function(){return e.__assign(e.__assign(e.__assign(e.__assign({},_),M&&E?{bodyHeight:E.gptBodyHeight}:{}),{disableMaximize:void 0!==B?!B:_.disableMaximize}),m?{DocumentTitle:void 0,previewCallback:void 0}:{})},[_,B,m,M,E]),A=t.useState(!0),D=A[0],G=A[1],P=t.useRef(!1),O=null!=S?S:D,R=void 0!==S,J=t.useMemo(function(){return x?s.mapCitationDataToDisplay(x):null},[x]),K=null!==(p=null!=w?w:null==J?void 0:J.topic)&&void 0!==p?p:"Web Citation",Q=null!==(b=null!=k?k:null==J?void 0:J.relevanceScore)&&void 0!==b?b:0,X=null!=j?j:null==J?void 0:J.learnedFrom,Y=null==J?void 0:J.citationUrl,Z=s.resolveSkeletonVisitUrl(null==J?void 0:J.highlightedUrl,C),$=s.getWebCitationImageUrl(x),ee=t.useMemo(function(){return function(e,i,t){return t?"success":e||(i?"error":"pending")}(y,x,$)},[y,x,$]);t.useEffect(function(){P.current=!1},[null==x?void 0:x.citationId]),t.useEffect(function(){m&&O&&($||P.current||(P.current=!0,null==F||F()))},[m,O,$,F,null==x?void 0:x.citationId]);var ie=t.useCallback(function(){I?I():R||G(!1)},[I,R]),te=t.useCallback(function(){I?I():R||G(!0),$||"success"===ee||null==F||F()},[I,R,$,ee,F]),ne=null!=h?h:"Source: Web Citation > ".concat(K),oe=function(t){var n=!!U.DocumentTitle,l=[d.default.gptCitationWrapper,n?d.default.gptCitationWrapperWithSource:"",M?d.default.gptCitationWrapperFixedHeight:""].filter(Boolean).join(" ");return i.jsxs("div",e.__assign({className:l,style:e.__assign(e.__assign({},q.gptWrapper),T)},{children:[i.jsx(o.default,e.__assign({},U,{splitterCustomStyle:!0})),t&&(n?i.jsx("div",e.__assign({className:d.default.gptCitationFooterAction,style:q.gptFooterAction},{children:t})):i.jsx("div",e.__assign({className:[d.default.gptCitationToggleFooter,M?d.default.gptCitationToggleFooterFixedHeight:""].filter(Boolean).join(" "),style:q.gptFooterAction},{children:t})))]}))};return m?O?i.jsxs("div",e.__assign({className:[d.default.panel,M?d.default.gptCitationWrapperFixedHeight:""].filter(Boolean).join(" "),style:e.__assign(e.__assign({},q.webPanel),T)},{children:[i.jsxs("div",e.__assign({className:d.default.panelHeader,style:q.webHeader},{children:[i.jsx("span",e.__assign({className:d.default.panelSource},{children:ne})),i.jsx("div",e.__assign({className:d.default.panelHeaderActions},{children:Q>0&&i.jsxs("div",e.__assign({className:d.default.confidenceBadge,title:"Decision strength"},{children:[i.jsx(n.Sparkles,{size:14}),Q,"%"]}))}))]})),i.jsx("div",e.__assign({className:[d.default.panelContent,d.default.panelContentExpanded,M?d.default.panelContentFixedHeight:""].filter(Boolean).join(" "),style:e.__assign(e.__assign({},q.webContent),M?u.getFixedWebContentStyle():void 0)},{children:"pending"===ee?i.jsx(a.default,{status:"pending",citationUrl:Z,ExternalLinkIcon:z.ExternalLinkIcon,styles:q.webSkeleton,visitLinkStyles:q.webSkeletonVisitLink,isFixedHeight:M}):"success"===ee&&$?i.jsx(l.default,{citationImage:$,citationUrl:Y,skeletonVisitUrl:Z,showExpandImageButton:W,iconsConfig:z,styles:q.webImage,visitLinkStyles:q.webImageVisitLink,skeletonStyles:q.webSkeleton,skeletonVisitLinkStyles:q.webSkeletonVisitLink,isFixedHeight:M}):i.jsx(a.default,{status:"error",citationUrl:Z,ExternalLinkIcon:z.ExternalLinkIcon,styles:q.webSkeleton,visitLinkStyles:q.webSkeletonVisitLink,isFixedHeight:M})})),i.jsxs("div",e.__assign({className:d.default.panelFooter,style:q.webFooter},{children:[i.jsx(g,{variant:"gpt",onClick:ie,style:q.webToggleButton}),X&&i.jsxs("span",e.__assign({className:d.default.learnedFrom,style:q.webLearnedFrom},{children:["Learned From ",X]}))]}))]})):i.jsx("div",e.__assign({className:d.default.overlay,style:q.container},{children:oe(i.jsx(g,{variant:"web",onClick:te,title:"View web-based citation for this source.",style:q.gptToggleButton}))})):i.jsx("div",e.__assign({className:d.default.overlay,style:q.container},{children:oe()}))};
 //# sourceMappingURL=GptWebCitation.js.map