@e-llm-studio/citation 0.0.214 → 0.0.216

package/README.md

@@ -681,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: {
@@ -727,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}
     />
   );
 }
@@ -768,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',
@@ -777,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}
 />
 ```
@@ -803,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}
 />
@@ -815,6 +862,7 @@ Hide the GPT citation header maximize/expand icon:
 ```tsx
 <GptWebCitation
   gptCitation={gptCitation}
+  defaultCitationUrl="https://example.com/article"
   isWebCitation={true}
   showGptMaximizeButton={false}
 />
@@ -824,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';
@@ -835,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: {
@@ -878,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 |
@@ -913,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.
 
 ---