refactor: zinc palette migration, docs sync, and deployment fixes

docs/agents/branding.md

@@ -68,8 +68,8 @@ Treat this amber as a **difference-revealing accent** and a small part of the De
 |----------|---------|-------|
 | `--dc-popover-width` | `480px` | Popover container width |
 | `--dc-keyhole-strip-height` | `120px` | Evidence keyhole strip height |
-| `--dc-document-canvas-bg-light` | `rgb(243 244 246)` | Light-mode proof image background |
-| `--dc-document-canvas-bg-dark` | `rgb(31 41 55)` | Dark-mode proof image background |
+| `--dc-document-canvas-bg-light` | `rgb(244 244 245)` | Light-mode proof image background |
+| `--dc-document-canvas-bg-dark` | `rgb(39 39 42)` | Dark-mode proof image background |
 | `--dc-guard-max-width` | `calc(100dvw - 2rem)` | Viewport-constrained max width |
 
 ### Surface Alignment Considerations
@@ -118,7 +118,7 @@ For the SDK, these are **reference surfaces, not defaults**:
 
 **React component (declarative):**
 ```tsx
-import { DeepCitationTheme } from "deepcitation";
+import { DeepCitationTheme } from "deepcitation/react";
 
 <DeepCitationTheme
   theme={{ background: "#fdfbf7", border: "#e2e0dc", verified: "#0d9488" }}

docs/agents/canonical-exports.md

@@ -68,14 +68,8 @@ Open this file when importing symbols from deepcitation to find the correct cano
 | `getUrlAccessExplanation()` | `src/react/urlAccessExplanation.ts` | URL access failure explanation mapping |
 | `UrlAccessExplanationSection` | `src/react/DefaultPopoverContent.tsx` | URL access failure display component (private) |
 | `CitationErrorBoundary` | `src/react/CitationErrorBoundary.tsx` | Error boundary for citation components |
-| `SearchAnalysisSummary` | `src/react/SearchAnalysisSummary.tsx` | Search attempt display component |
-| `citationContainerVariants()` | `src/react/citationVariants.cva.ts` | Variant → container class resolver |
-| `citationHoverVariants()` | `src/react/citationVariants.cva.ts` | Status + opacity → hover class resolver |
-| `LINTER_STYLES` | `src/react/citationVariants.cva.ts` | Linter underline CSS by status |
-| `LINTER_HOVER_CLASSES` | `src/react/citationVariants.cva.ts` | Linter hover classes by status |
-| `BADGE_HOVER_CLASSES` | `src/react/citationVariants.cva.ts` | Badge hover classes by status |
-| `resolveStatusKey()` | `src/react/citationVariants.cva.ts` | Boolean flags → status key |
-| `SUPERSCRIPT_STYLE` | `src/react/citationVariants.cva.ts` | Superscript inline styles |
+| `SearchAnalysisSummary` | `src/react/EvidenceTray.tsx` | Search attempt display component |
+| `SUPERSCRIPT_STYLE` | `src/react/constants.ts` | Superscript inline styles |
 | `handleImageError()` | `src/react/imageUtils.ts` | Shared image error handler (`display: "none"`) |
 | `handleImageErrorOpacity()` | `src/react/imageUtils.ts` | Shared image error handler (`opacity: "0"`, preserves layout) |
 | `HIDE_SCROLLBAR_STYLE` | `src/react/constants.ts` | Scrollbar-hiding CSS (`scrollbarWidth: "none"`) |
@@ -91,18 +85,11 @@ Open this file when importing symbols from deepcitation to find the correct cano
 | `DRAWER_DRAG_CLOSE_THRESHOLD_PX` | `src/react/constants.ts` | Drag distance threshold for drawer close (80px) |
 | `HITBOX_EXTEND_8` | `src/react/constants.ts` | Invisible hit-box extender — uniform 8px |
 | `HITBOX_EXTEND_8x14` | `src/react/constants.ts` | Invisible hit-box extender — 8px horizontal, 14px vertical |
-| `usePopoverDismiss()` | `src/react/hooks/usePopoverDismiss.ts` | Platform-aware outside-click dismiss |
-| `usePopoverPosition()` | `src/react/hooks/usePopoverPosition.ts` | Expanded-page side offset calculation |
-| `useCitationTelemetry()` | `src/react/hooks/useCitationTelemetry.ts` | Popover timing + spinner staging |
-| `useZoomControls()` | `src/react/hooks/useZoomControls.ts` | Zoom state with clamping and steps |
-| `useCitationData()` | `src/react/hooks/useCitationData.ts` | Citation key, instance ID, status derivation |
-| `useCitationEvents()` | `src/react/hooks/useCitationEvents.ts` | Click/hover/keyboard event handlers |
 | `useExpandedPageSideOffset()` | `src/react/hooks/useExpandedPageSideOffset.ts` | Expanded-page popover vertical offset |
 | `usePopoverAlignOffset()` | `src/react/hooks/usePopoverAlignOffset.ts` | Horizontal viewport clamping (replaces shift middleware) |
 | `useViewportBoundaryGuard()` | `src/react/hooks/useViewportBoundaryGuard.ts` | Hard viewport boundary guard (Layer 3 safety net) |
 | `VIEWPORT_MARGIN_PX` | `src/react/constants.ts` | Viewport edge margin for popover positioning (16px) |
 | `useAnimatedHeight()` | `src/react/hooks/useAnimatedHeight.ts` | Imperative height animation for viewState transitions |
-| `useAnimationState()` | `src/react/hooks/useAnimationState.ts` | Enter/exit animation lifecycle |
 | `usePopoverViewState()` | `src/react/hooks/usePopoverViewState.ts` | Popover view-state machine (haptics, VT, scroll lock, escape) |
 | `useWheelZoom()` | `src/react/hooks/useWheelZoom.ts` | Wheel/trackpad zoom with gesture anchor |
 | `buildSearchNarrative()` | `src/react/searchNarrative.ts` | SearchAttempt[] → display-ready narrative for VerificationLog |

docs/agents/package-reference.md

@@ -61,6 +61,7 @@ High-level package areas:
 - `src/react`: citation components, hooks, variants, UI behavior.
 - `src/rendering`: Slack/GitHub/HTML/terminal rendering targets.
 - `src/utils`: security and safety utilities.
+- `src/vanilla`: framework-agnostic vanilla JS/TS runtime and rendering.
 - `src/types`: shared TypeScript models.
 
 ## API Endpoints

docs/styling.md

@@ -43,8 +43,8 @@ Override these CSS variables to theme all DeepCitation components at once:
   --dc-popover-width: 384px;      /* Popover container width */
 
   /* Proof image canvas (keyhole + expanded page + drawer) */
-  --dc-document-canvas-bg-light: #f3f4f6; /* Light-mode neutral canvas */
-  --dc-document-canvas-bg-dark: #1f2937;  /* Dark-mode neutral canvas */
+  --dc-document-canvas-bg-light: #f4f4f5; /* Light-mode neutral canvas (zinc-100) */
+  --dc-document-canvas-bg-dark: #27272a;  /* Dark-mode neutral canvas (zinc-800) */
 }
 ```
 
@@ -61,8 +61,8 @@ Override these CSS variables to theme all DeepCitation components at once:
     --dc-linter-warning: #fbbf24;
     --dc-linter-error: #d47d7c;
     --dc-linter-pending: #6b7280;
-    --dc-document-canvas-bg-light: #f3f4f6;
-    --dc-document-canvas-bg-dark: #1f2937;
+    --dc-document-canvas-bg-light: #f4f4f5;
+    --dc-document-canvas-bg-dark: #27272a;
   }
 }
 
@@ -72,8 +72,8 @@ Override these CSS variables to theme all DeepCitation components at once:
   --dc-partial: #fbbf24;
   --dc-destructive: #f87171;
   --dc-pending: #6b7280;
-  --dc-document-canvas-bg-light: #f3f4f6;
-  --dc-document-canvas-bg-dark: #1f2937;
+  --dc-document-canvas-bg-light: #f4f4f5;
+  --dc-document-canvas-bg-dark: #27272a;
 }
 ```
 

docs/types.md

@@ -22,28 +22,51 @@ TypeScript interfaces for the DeepCitation SDK and React components.
 
 ## Citation Types
 
-DeepCitation supports two citation shapes.
+DeepCitation supports three citation shapes, discriminated by `type`.
 
 ```typescript
-interface DocumentCitation {
-  type?: "document";
+interface CitationBase {
   attachmentId?: string;
-  pageNumber?: number | null;
-  fullPhrase?: string | null;
-  anchorText?: string | null;
-  lineIds?: number[] | null;
+  pageNumber?: number;
+  lineIds?: number[];
+  startPageId?: string;
+  fullPhrase?: string;
+  anchorText?: string;
+  citationNumber?: number;
+  reasoning?: string;
 }
 
-interface UrlCitation {
+interface DocumentCitation extends CitationBase {
+  type: "document";
+}
+
+interface UrlCitation extends CitationBase {
   type: "url";
   url?: string;
   domain?: string;
   title?: string;
-  fullPhrase?: string | null;
-  anchorText?: string | null;
+  description?: string;
+  faviconUrl?: string;
+  sourceType?: SourceType;
+  platform?: string;
+  siteName?: string;
+  author?: string;
+  publishedAt?: string;
+  imageUrl?: string;
+  accessedAt?: string;
 }
 
-type Citation = DocumentCitation | UrlCitation;
+interface AudioVideoCitation extends CitationBase {
+  type: "audio" | "video";
+  timestamps?: { startTime?: string; endTime?: string };
+}
+
+type Citation = DocumentCitation | UrlCitation | AudioVideoCitation;
+
+type SourceType =
+  | "web" | "pdf" | "document" | "social" | "video"
+  | "news" | "academic" | "code" | "forum" | "commerce"
+  | "reference" | "unknown";
 ```
 
 ---
@@ -54,30 +77,62 @@ Request body for `/verifyCitations`.
 
 ```typescript
 interface VerifyCitationRequest {
-  attachmentId: string;
+  attachmentId?: string;
+  sha256?: string;
   citations: { [key: string]: Citation };
-  outputImageFormat?: "jpeg" | "png" | "avif";
+  outputImageFormat?: "jpeg" | "png" | "avif" | "webp";
   apiKey?: string;
+  endUserId?: string;
 }
 ```
 
 ---
 
 ## Verification (SDK)
 
-The SDK normalizes backend responses into this shape.
+The SDK normalizes backend responses into this shape. Access the status directly as `verification.status`, not via a nested `searchState` object.
 
 ```typescript
 interface Verification {
-  status?: SearchStatus | null;
-  verifiedMatchSnippet?: string | null;
-  searchAttempts?: SearchAttempt[];
+  // Identity
   attachmentId?: string | null;
+  label?: string;
   citation?: Citation;
 
-  evidence?: EvidenceImage;
+  // Search results
+  status?: SearchStatus;
+  searchAttempts?: SearchAttempt[];
+  highlightColor?: string;
+
+  // Verified text
+  verifiedFullPhrase?: string;
+  verifiedAnchorText?: string;
+  verifiedMatchSnippet?: string;
+  verifiedTimestamps?: { startTime?: string; endTime?: string };
+  verifiedAt?: string;
+
+  // Type-specific results
   document?: DocumentVerificationResult;
   url?: UrlVerificationResult;
+
+  // Evidence image (keyhole crop)
+  evidence?: EvidenceImage;
+
+  // Timing
+  timeToCertaintyMs?: number;
+
+  // Attachment assets (also present on Verification for convenience)
+  pageImages?: PageImage[];
+  originalDownload?: FileDownload;
+  convertedDownload?: FileDownload;
+
+  // Ambiguity detection
+  ambiguity?: {
+    totalOccurrences: number;
+    occurrencesOnExpectedPage: number;
+    confidence: "high" | "medium" | "low";
+    note: string;
+  };
 }
 
 type SearchStatus =
@@ -125,24 +180,24 @@ interface SearchAttempt {
   searchScope?: "line" | "page" | "document";
   expectedLocation?: { page: number; line?: number };
   foundLocation?: { page: number; line?: number };
-  matchedVariation?:
-    | "exact_full_phrase"
-    | "normalized_full_phrase"
-    | "exact_anchor_text"
-    | "normalized_anchor_text"
-    | "partial_full_phrase"
-    | "partial_anchor_text"
-    | "first_word_only";
+  matchedVariation?: MatchedVariation;
   matchedText?: string;
   deepTextItems?: DeepTextItem[];
-  matchScore?: number;
-  matchSnippet?: string;
   note?: string;
   durationMs?: number;
   variationType?: "exact" | "normalized" | "currency" | "date" | "numeric" | "symbol" | "accent";
   occurrencesFound?: number;
   matchedExpectedOccurrence?: boolean;
 }
+
+type MatchedVariation =
+  | "exact_full_phrase"
+  | "normalized_full_phrase"
+  | "exact_anchor_text"
+  | "normalized_anchor_text"
+  | "partial_full_phrase"
+  | "partial_anchor_text"
+  | "first_word_only";
 ```
 
 ---
@@ -153,20 +208,21 @@ Artifacts are split by purpose so evidence (crop), page images, and source downl
 
 ```typescript
 interface EvidenceImage {
-  src: string | null;
-  dimensions?: { width: number; height: number } | null;
-}
-
-interface WebCaptureAsset {
-  src?: string | null;
-  capturedAt?: Date | string | null;
+  src: string;
+  dimensions?: { width: number; height: number };
+  textItems?: DeepTextItem[];
 }
 
 interface PageImage {
   pageNumber: number;
   dimensions: { width: number; height: number };
   imageUrl: string;
   thumbnailUrl?: string;
+  expiresAt?: string;
+  isMatchPage?: boolean;
+  highlightBox?: ScreenBox;
+  renderScale?: { x: number; y: number };
+  textItems?: DeepTextItem[];
 }
 ```
 
@@ -209,8 +265,8 @@ interface PreparedAttachment {
 
 ## Verify Response
 
-`verifyAttachment()` / `verify()` responses contain only verification results.
-File download artifacts are on the attachment, not the verification.
+`verifyAttachment()` / `verify()` responses contain verification results.
+Download artifacts are available on both the attachment and each verification.
 
 ```typescript
 interface VerifyCitationResponse {
@@ -251,29 +307,3 @@ Override per request on:
 - `prepareConvertedFile(options)`
 - `prepareAttachments([{ ... }])`
 
----
-
-## React Download Policy (`CitationComponent`)
-
-`CitationComponent` separates source-file download behavior from proof/evidence image download behavior.
-
-```typescript
-type CitationDownloadPolicy = "original_only" | "original_plus_url_pdf" | "original_plus_all_pdf";
-```
-
-Relevant props:
-
-```typescript
-interface CitationComponentProps {
-  originalDownload?: FileDownload;   // file as received
-  convertedDownload?: FileDownload;  // PDF rendition / URL PDF capture
-  downloadPolicy?: CitationDownloadPolicy; // default: "original_plus_url_pdf"
-  onSourceDownload?: (citation: Citation) => void;
-}
-```
-
-Default UI behavior:
-
-- `original_plus_url_pdf`: show `originalDownload` when present; for URL inputs (no `originalDownload`), show `convertedDownload`
-- `original_plus_all_pdf`: show `originalDownload` when present, else show `convertedDownload`
-- `original_only`: show `originalDownload` only, never `convertedDownload`

examples/langchain-rag-chat/vercel.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "framework": "nextjs",
+  "ignoreCommand": "git diff --quiet HEAD^ HEAD -- .",
+  "github": {
+    "enabled": true,
+    "silent": true
+  }
+}