- // synchronously before the VT callback, so reading it during the
- // flushSync render is deterministic and safe.
- ...(!annotationVtRect ||
- (typeof document !== "undefined" && "dcPageExpand" in document.documentElement.dataset)
- ? { viewTransitionName: DC_EVIDENCE_VT_NAME }
- : {}),
+ ...(!annotationVtRect ? { viewTransitionName: DC_EVIDENCE_VT_NAME } : {}),
...(fill ? {} : { maxHeight: "min(600px, 80dvh)" }),
overscrollBehavior: "none",
cursor: isDragging ? "move" : "zoom-out",
@@ -2030,13 +2179,18 @@ export function InlineExpandedImage({
{annotationVtRect && (
diff --git a/src/react/constants.ts b/src/react/constants.ts
index bf76529d..78cf91f8 100644
--- a/src/react/constants.ts
+++ b/src/react/constants.ts
@@ -545,6 +545,8 @@ export const EXPANDED_POPOVER_HEIGHT = "calc(100dvh - 2rem)";
/** Duration (ms) for evidence image expand VT (keyhole → expanded). ANIM_STANDARD_MS tier. */
export const VT_EVIDENCE_EXPAND_MS = 180;
+/** Duration (ms) for the page-expand ghost animation (summary/preview → expanded page). ANIM_MEASURED_MS tier (250ms). */
+export const VT_EVIDENCE_PAGE_EXPAND_MS = 250;
/** Duration (ms) for evidence image collapse VT (expanded → keyhole). ANIM_FAST_MS tier. */
export const VT_EVIDENCE_COLLAPSE_MS = 120;
/**
@@ -554,6 +556,57 @@ export const VT_EVIDENCE_COLLAPSE_MS = 120;
*/
export const VT_EVIDENCE_DIP_OPACITY = 0.45;
+// Page-expand ghost animation keyframe tuning.
+//
+// Mirrors the collapse's "dip-then-reveal" structure:
+// Collapse: old 1.0 → 0.45 (30%) → 0 / new 0 → 0 (60%) → 1
+// Expand: ghost dominates first 60% / page near-invisible until ghost lands
+//
+// The ghost is the "old snapshot equivalent" — the thing the eye tracks.
+// It must be opaque enough to dominate over the dimmed page beneath.
+// The page is the "new snapshot equivalent" — stays hidden, then reveals sharply.
+/** Ghost initial opacity — clearly visible "card" from click origin. */
+export const GHOST_OPACITY_START = 0.55;
+/** Ghost opacity at early interpolation (18% progress) — building dominance. */
+export const GHOST_OPACITY_EARLY = 0.75;
+/** Ghost opacity at mid interpolation (42% progress) — peak visibility, mid-motion. */
+export const GHOST_OPACITY_MID = 0.88;
+/** Ghost opacity at late interpolation (68% progress) — near-peak, approaching target. */
+export const GHOST_OPACITY_LATE = 0.92;
+/** Ghost near-peak opacity before final fade-out (92% progress). */
+export const GHOST_OPACITY_PEAK = 0.88;
+
+// Page-expand ghost motion blur.
+// CSS `filter: blur()` masks the non-uniform scale distortion (squashed text)
+// mid-flight and reads as cinematic motion blur. GPU-composited, no layout cost.
+/** Ghost blur (px) at start — sharp at source position. */
+export const GHOST_BLUR_START_PX = 1;
+/** Ghost blur (px) at early interpolation — motion building. */
+export const GHOST_BLUR_EARLY_PX = 4;
+/** Ghost blur (px) at mid interpolation — peak distortion zone. */
+export const GHOST_BLUR_MID_PX = 8;
+/** Ghost blur (px) at late interpolation — clearing as ghost nears target. */
+export const GHOST_BLUR_LATE_PX = 5;
+/** Ghost blur (px) at near-peak — nearly clear before fade-out. */
+export const GHOST_BLUR_PEAK_PX = 2;
+
+/** Page content initial opacity during page-expand — nearly invisible.
+ * Must be very low so the ghost dominates the first 60% of the animation
+ * (mirroring how the collapse keeps new content at 0 until 60%). */
+export const PAGE_EXPAND_CONTENT_OPACITY_START = 0.03;
+/** Ghost keyframe offset: early interpolation. */
+export const GHOST_OFFSET_EARLY = 0.18;
+/** Ghost keyframe offset: mid interpolation. */
+export const GHOST_OFFSET_MID = 0.42;
+/** Ghost keyframe offset: late interpolation. */
+export const GHOST_OFFSET_LATE = 0.68;
+/** Ghost keyframe offset: near-peak before fade-out. */
+export const GHOST_OFFSET_PEAK = 0.92;
+/** Debug outline color for page-expand source phase. */
+export const DEBUG_PAGE_EXPAND_SOURCE_COLOR = "#ef4444";
+/** Debug outline color for page-expand target phase. */
+export const DEBUG_PAGE_EXPAND_TARGET_COLOR = "#22c55e";
+
// =============================================================================
// ANIMATION & TRANSITION TIMINGS
// =============================================================================
diff --git a/src/react/viewTransition.ts b/src/react/viewTransition.ts
index a58b13e2..ed3174b2 100644
--- a/src/react/viewTransition.ts
+++ b/src/react/viewTransition.ts
@@ -1,4 +1,28 @@
import { flushSync } from "react-dom";
+import { BOX_PADDING, SPOTLIGHT_PADDING } from "../drawing/citationDrawing.js";
+import {
+ BLINK_ENTER_EASING,
+ DEBUG_PAGE_EXPAND_SOURCE_COLOR,
+ DEBUG_PAGE_EXPAND_TARGET_COLOR,
+ EASE_COLLAPSE,
+ GHOST_BLUR_EARLY_PX,
+ GHOST_BLUR_LATE_PX,
+ GHOST_BLUR_MID_PX,
+ GHOST_BLUR_PEAK_PX,
+ GHOST_BLUR_START_PX,
+ GHOST_OFFSET_EARLY,
+ GHOST_OFFSET_LATE,
+ GHOST_OFFSET_MID,
+ GHOST_OFFSET_PEAK,
+ GHOST_OPACITY_EARLY,
+ GHOST_OPACITY_LATE,
+ GHOST_OPACITY_MID,
+ GHOST_OPACITY_PEAK,
+ GHOST_OPACITY_START,
+ isValidProofImageSrc,
+ PAGE_EXPAND_CONTENT_OPACITY_START,
+ VT_EVIDENCE_PAGE_EXPAND_MS,
+} from "./constants.js";
/**
* View-transition name applied to evidence image elements (keyhole strip,
@@ -18,10 +42,24 @@ export const DC_EVIDENCE_VT_NAME = "dc-evidence";
* prematurely unguarding the second.
*/
let _transitionDepth = 0;
+let _primedPageExpandSource: HTMLElement | null = null;
+let _primedPageExpandSourceTime = 0;
+/** Max age (ms) before the primed source is considered stale and discarded. */
+const _PRIMED_SOURCE_MAX_AGE_MS = 500;
export function isViewTransitioning(): boolean {
return _transitionDepth > 0;
}
+/**
+ * Primes the source element for the next page-expand transition.
+ * Callers must invoke `startEvidencePageExpandTransition` immediately after —
+ * the primed ref is cleared on read or after `_PRIMED_SOURCE_MAX_AGE_MS`.
+ */
+export function primeEvidencePageExpandSource(sourceEl: HTMLElement | null): void {
+ _primedPageExpandSource = sourceEl;
+ _primedPageExpandSourceTime = Date.now();
+}
+
/**
* Wraps a state update in a View Transition so the browser morphs the
* geometry + cross-fades between the old and new evidence image elements.
@@ -76,3 +114,682 @@ export function startEvidenceViewTransition(
};
transition.finished.then(cleanup).catch(cleanup);
}
+
+type GhostSnapshot = {
+ viewportRect: DOMRect;
+ imageSrc: string;
+ imageOffsetLeft: number;
+ imageOffsetTop: number;
+ imageWidth: number;
+ imageHeight: number;
+ imageNaturalWidth: number;
+ imageNaturalHeight: number;
+ sourceKind: "summary-keyhole" | "expanded-keyhole" | null;
+ sourceAnchorX: number;
+ sourceAnchorY: number;
+ borderRadius: string;
+};
+
+function isVisibleRect(rect: DOMRect): boolean {
+ return rect.width > 0.5 && rect.height > 0.5;
+}
+
+type DebugPhase = "source" | "target" | "both" | null;
+
+function getPageExpandDebugPhase(): DebugPhase {
+ if (typeof document === "undefined") return null;
+ const phase = document.documentElement.dataset.dcPageExpandDebugPhase;
+ if (phase === "source" || phase === "target" || phase === "both") return phase;
+ return null;
+}
+
+/** Remove all debug overlays from the DOM. */
+function clearDebugOverlays(): void {
+ if (typeof document === "undefined") return;
+ document.querySelectorAll("[data-dc-debug-overlay]").forEach(el => el.remove());
+}
+
+/** Shared font for debug labels. */
+const DEBUG_LABEL_FONT = "10px/1.2 ui-monospace, SFMono-Regular, monospace";
+
+/** Create a debug overlay box at the given rect with a colored outline and label. */
+function createDebugOverlay(rect: DOMRect, color: string, label: string, sublabel?: string): HTMLDivElement {
+ const el = document.createElement("div");
+ el.setAttribute("aria-hidden", "true");
+ el.dataset.dcDebugOverlay = "";
+ el.style.position = "fixed";
+ el.style.left = `${rect.left}px`;
+ el.style.top = `${rect.top}px`;
+ el.style.width = `${rect.width}px`;
+ el.style.height = `${rect.height}px`;
+ el.style.outline = `2px solid ${color}`;
+ el.style.outlineOffset = "-1px";
+ el.style.backgroundColor = `${color}22`;
+ el.style.pointerEvents = "none";
+ el.style.zIndex = "2147483647";
+ el.style.overflow = "visible";
+
+ // Label badge
+ const badge = document.createElement("div");
+ badge.style.position = "absolute";
+ badge.style.top = "-18px";
+ badge.style.left = "0";
+ badge.style.background = color;
+ badge.style.color = "#fff";
+ badge.style.font = DEBUG_LABEL_FONT;
+ badge.style.padding = "1px 5px";
+ badge.style.borderRadius = "3px 3px 0 0";
+ badge.style.whiteSpace = "nowrap";
+ badge.textContent = label;
+ el.appendChild(badge);
+
+ // Dimensions sub-label
+ const dims = document.createElement("div");
+ dims.style.position = "absolute";
+ dims.style.bottom = "-16px";
+ dims.style.left = "0";
+ dims.style.font = DEBUG_LABEL_FONT;
+ dims.style.color = color;
+ dims.style.whiteSpace = "nowrap";
+ dims.style.textShadow = "0 0 3px #000, 0 0 3px #000";
+ const dimText = `${Math.round(rect.width)}×${Math.round(rect.height)} @ (${Math.round(rect.left)}, ${Math.round(rect.top)})`;
+ dims.textContent = sublabel ? `${dimText} — ${sublabel}` : dimText;
+ el.appendChild(dims);
+
+ document.body.appendChild(el);
+ return el;
+}
+
+function takePrimedPageExpandSource(root: ParentNode): HTMLElement | null {
+ const sourceEl = _primedPageExpandSource;
+ _primedPageExpandSource = null;
+ if (!sourceEl) return null;
+ // Discard stale primed sources to prevent leaked refs from accumulating.
+ if (Date.now() - _primedPageExpandSourceTime > _PRIMED_SOURCE_MAX_AGE_MS) return null;
+ if ("contains" in root && typeof root.contains === "function" && !root.contains(sourceEl)) {
+ return null;
+ }
+ const rect = sourceEl.getBoundingClientRect();
+ return isVisibleRect(rect) ? sourceEl : null;
+}
+
+function capturePageExpandSource(root: ParentNode): GhostSnapshot | null {
+ const primedSource = takePrimedPageExpandSource(root);
+ const candidates = primedSource
+ ? [primedSource]
+ : Array.from(root.querySelectorAll
("[data-dc-page-expand-source]"));
+ for (const sourceEl of candidates) {
+ const rect = sourceEl.getBoundingClientRect();
+ if (!isVisibleRect(rect)) continue;
+ const img = sourceEl.querySelector("img");
+ const imageRect = img?.getBoundingClientRect();
+ const imageSrc = img?.currentSrc || img?.src;
+ if (!img || !imageRect || !imageSrc || !isVisibleRect(imageRect)) continue;
+ const sourceAnchorXRaw = Number.parseFloat(sourceEl.dataset.dcSourceAnchorX ?? "");
+ const sourceAnchorYRaw = Number.parseFloat(sourceEl.dataset.dcSourceAnchorY ?? "");
+ return {
+ viewportRect: rect,
+ imageSrc,
+ imageOffsetLeft: imageRect.left - rect.left,
+ imageOffsetTop: imageRect.top - rect.top,
+ imageWidth: imageRect.width,
+ imageHeight: imageRect.height,
+ imageNaturalWidth: img.naturalWidth,
+ imageNaturalHeight: img.naturalHeight,
+ sourceKind:
+ sourceEl.dataset.dcPageExpandSourceKind === "summary-keyhole" ||
+ sourceEl.dataset.dcPageExpandSourceKind === "expanded-keyhole"
+ ? sourceEl.dataset.dcPageExpandSourceKind
+ : null,
+ sourceAnchorX:
+ Number.isFinite(sourceAnchorXRaw) && sourceAnchorXRaw >= 0 && sourceAnchorXRaw <= 1 ? sourceAnchorXRaw : 0.5,
+ sourceAnchorY:
+ Number.isFinite(sourceAnchorYRaw) && sourceAnchorYRaw >= 0 && sourceAnchorYRaw <= 1 ? sourceAnchorYRaw : 0.5,
+ borderRadius: getComputedStyle(sourceEl).borderRadius || "0px",
+ };
+ }
+ return null;
+}
+
+type PageExpandTarget = {
+ markerRect: DOMRect;
+ ghostRect: DOMRect;
+};
+
+function buildGhostTargetRect(_snapshot: GhostSnapshot, targetEl: HTMLElement, markerRect: DOMRect): DOMRect {
+ // The ghost lands on the annotation spotlight — the "light area" cutout in
+ // the dimming overlay (annotation rect + SPOTLIGHT_PADDING). This is the
+ // visual focal point of the expanded page, sized to give surrounding context
+ // without covering the full page (which would create a giant flash).
+ const spotlight = targetEl.parentElement?.querySelector("[data-dc-spotlight]");
+ if (spotlight) {
+ const spotRect = spotlight.getBoundingClientRect();
+ if (isVisibleRect(spotRect)) return spotRect;
+ }
+ // Overlay dismissed or not yet rendered — synthesize the spotlight rect from
+ // the annotation marker + padding. The spotlight is the annotation bounding
+ // box expanded by (BOX_PADDING + SPOTLIGHT_PADDING) in natural image pixels,
+ // scaled to the rendered image size.
+ const img = targetEl.parentElement?.querySelector("img");
+ if (img && img.naturalWidth > 0 && targetEl.parentElement) {
+ const containerRect = targetEl.parentElement.getBoundingClientRect();
+ const scale = containerRect.width / img.naturalWidth;
+ const pad = (BOX_PADDING + SPOTLIGHT_PADDING) * scale;
+ return new DOMRect(
+ markerRect.left - pad,
+ markerRect.top - pad,
+ markerRect.width + 2 * pad,
+ markerRect.height + 2 * pad,
+ );
+ }
+ return markerRect;
+}
+
+/**
+ * Fallback ghost target for miss/not_found states where no annotation marker
+ * exists. Maps the keyhole's visible viewport onto the expanded page's visible
+ * image area — the ghost lands on whatever region the user was already viewing.
+ */
+function buildGhostTargetFromViewport(root: ParentNode): PageExpandTarget | null {
+ // Only match containers that have no annotation data (miss/not_found).
+ // data-dc-no-annotation is set by InlineExpandedImage when fill=true and
+ // scrollTarget is null — derived from props, not layout measurements, so
+ // it's available immediately after flushSync (no useEffect timing issues).
+ const containers = root.querySelectorAll("[data-dc-inline-expanded][data-dc-no-annotation]");
+ for (const container of containers) {
+ const containerRect = container.getBoundingClientRect();
+ if (!isVisibleRect(containerRect)) continue;
+ const img = container.querySelector("img");
+ if (!img) continue;
+ const imgRect = img.getBoundingClientRect();
+ if (!isVisibleRect(imgRect)) continue;
+ // Ghost target = intersection of the container viewport and the image rect
+ // (the visible portion of the page image on screen).
+ const left = Math.max(containerRect.left, imgRect.left);
+ const top = Math.max(containerRect.top, imgRect.top);
+ const right = Math.min(containerRect.right, imgRect.right);
+ const bottom = Math.min(containerRect.bottom, imgRect.bottom);
+ if (right <= left || bottom <= top) continue;
+ const visibleRect = new DOMRect(left, top, right - left, bottom - top);
+ return { markerRect: visibleRect, ghostRect: visibleRect };
+ }
+ return null;
+}
+
+function findPageExpandTarget(root: ParentNode, snapshot: GhostSnapshot): PageExpandTarget | null {
+ const candidates = Array.from(root.querySelectorAll("[data-dc-page-expand-target]"));
+ for (const targetEl of candidates) {
+ if (targetEl.dataset.dcPageExpandReady !== "true") continue;
+ const rect = targetEl.getBoundingClientRect();
+ if (!isVisibleRect(rect)) continue;
+ return { markerRect: rect, ghostRect: buildGhostTargetRect(snapshot, targetEl, rect) };
+ }
+ // Annotation target elements exist but aren't ready yet — keep polling.
+ if (candidates.length > 0) return null;
+ // No annotation target at all (miss/not_found without annotation data).
+ // Fall back to the visible viewport of the expanded page image.
+ // The ready-attribute selector in buildGhostTargetFromViewport ensures we
+ // don't fire prematurely — pageExpandReady is only set after the component's
+ // useEffect has run and (for success states) annotation targets are rendered.
+ return buildGhostTargetFromViewport(root);
+}
+
+function createPageExpandGhost(snapshot: GhostSnapshot): HTMLDivElement | null {
+ // Defensive re-validation: the source image was already validated before
+ // rendering, but a DOM mutation (e.g. browser extension) could have changed it.
+ if (!isValidProofImageSrc(snapshot.imageSrc)) return null;
+ const ghost = document.createElement("div");
+ ghost.setAttribute("aria-hidden", "true");
+ ghost.dataset.dcPageExpandGhost = "";
+ ghost.style.position = "fixed";
+ ghost.style.left = `${snapshot.viewportRect.left}px`;
+ ghost.style.top = `${snapshot.viewportRect.top}px`;
+ ghost.style.width = `${snapshot.viewportRect.width}px`;
+ ghost.style.height = `${snapshot.viewportRect.height}px`;
+ ghost.style.overflow = "hidden";
+ ghost.style.pointerEvents = "none";
+ ghost.style.zIndex = "2147483646";
+ ghost.style.borderRadius = snapshot.borderRadius;
+ ghost.style.transformOrigin = "0 0";
+ ghost.style.willChange = "transform, opacity";
+ const debugPhase = getPageExpandDebugPhase();
+ if (debugPhase && debugPhase !== "both") {
+ ghost.style.outline =
+ debugPhase === "source"
+ ? `2px solid ${DEBUG_PAGE_EXPAND_SOURCE_COLOR}`
+ : `2px solid ${DEBUG_PAGE_EXPAND_TARGET_COLOR}`;
+ ghost.style.outlineOffset = "0";
+ }
+
+ const img = document.createElement("img");
+ img.src = snapshot.imageSrc;
+ img.alt = "";
+ img.draggable = false;
+ img.style.position = "absolute";
+ img.style.left = `${snapshot.imageOffsetLeft}px`;
+ img.style.top = `${snapshot.imageOffsetTop}px`;
+ img.style.width = `${snapshot.imageWidth}px`;
+ img.style.height = `${snapshot.imageHeight}px`;
+ img.style.maxWidth = "none";
+ img.style.userSelect = "none";
+ img.style.pointerEvents = "none";
+ ghost.appendChild(img);
+ document.body.appendChild(ghost);
+ return ghost;
+}
+
+function applyGhostRect(ghost: HTMLDivElement, rect: DOMRect): void {
+ ghost.style.left = `${rect.left}px`;
+ ghost.style.top = `${rect.top}px`;
+ ghost.style.width = `${rect.width}px`;
+ ghost.style.height = `${rect.height}px`;
+}
+
+function runPageExpandGhostAnimation(
+ ghost: HTMLDivElement,
+ snapshot: GhostSnapshot,
+ target: PageExpandTarget,
+ popoverRoot: HTMLElement | null,
+): void {
+ const { ghostRect } = target;
+ const debugPhase = getPageExpandDebugPhase();
+ if (debugPhase === "source") {
+ return;
+ }
+ if (debugPhase === "target") {
+ applyGhostRect(ghost, ghostRect);
+ return;
+ }
+ if (debugPhase === "both") {
+ // "both" mode: hide the real ghost, draw persistent debug overlays for both rects
+ ghost.remove();
+ clearDebugOverlays();
+ const kindLabel =
+ snapshot.sourceKind === "summary-keyhole"
+ ? "summary keyhole"
+ : snapshot.sourceKind === "expanded-keyhole"
+ ? "expanded keyhole"
+ : "source";
+ createDebugOverlay(
+ snapshot.viewportRect,
+ DEBUG_PAGE_EXPAND_SOURCE_COLOR,
+ `SOURCE (${kindLabel})`,
+ `anchor: (${snapshot.sourceAnchorX.toFixed(2)}, ${snapshot.sourceAnchorY.toFixed(2)})`,
+ );
+ createDebugOverlay(ghostRect, DEBUG_PAGE_EXPAND_TARGET_COLOR, "TARGET (ghost destination)");
+ createDebugOverlay(target.markerRect, "#3b82f6", "MARKER (annotation VT rect)");
+ if (process.env.NODE_ENV !== "production") {
+ console.groupCollapsed("[DC debug] page-expand geometry");
+ console.table({
+ source: {
+ left: snapshot.viewportRect.left,
+ top: snapshot.viewportRect.top,
+ width: snapshot.viewportRect.width,
+ height: snapshot.viewportRect.height,
+ },
+ ghostTarget: {
+ left: ghostRect.left,
+ top: ghostRect.top,
+ width: ghostRect.width,
+ height: ghostRect.height,
+ },
+ marker: {
+ left: target.markerRect.left,
+ top: target.markerRect.top,
+ width: target.markerRect.width,
+ height: target.markerRect.height,
+ },
+ });
+ console.log("snapshot:", snapshot);
+ console.groupEnd();
+ }
+ return;
+ }
+
+ // Animate using transform (translate + scale) + opacity so the compositor
+ // handles the interpolation without triggering layout on every frame.
+ // The ghost is positioned at the source rect; we compute the transform needed
+ // to move and scale it to the target rect.
+ const src = snapshot.viewportRect;
+ const scaleX = ghostRect.width / src.width;
+ const scaleY = ghostRect.height / src.height;
+ const translateX = ghostRect.left - src.left;
+ const translateY = ghostRect.top - src.top;
+
+ // Helper: build a transform string at a given interpolation fraction t ∈ [0, 1].
+ const tfAt = (t: number) =>
+ `translate(${translateX * t}px, ${translateY * t}px) scale(${1 + (scaleX - 1) * t}, ${1 + (scaleY - 1) * t})`;
+
+ // Helper: build a blur filter string at a given blur radius.
+ const blurAt = (px: number) => (px > 0 ? `blur(${px}px)` : "none");
+
+ // Large-travel expand: EASE_COLLAPSE intentional (>200px travel, per BRANDING.md large-motion rule)
+ // Motion blur (filter: blur) masks the non-uniform scale distortion (squashed text)
+ // and reads as cinematic motion blur. Peaks mid-flight, clears near landing.
+ const keyframes: Keyframe[] = [
+ { transform: tfAt(0), opacity: GHOST_OPACITY_START, filter: blurAt(GHOST_BLUR_START_PX) },
+ {
+ transform: tfAt(GHOST_OFFSET_EARLY),
+ opacity: GHOST_OPACITY_EARLY,
+ filter: blurAt(GHOST_BLUR_EARLY_PX),
+ offset: GHOST_OFFSET_EARLY,
+ },
+ {
+ transform: tfAt(GHOST_OFFSET_MID),
+ opacity: GHOST_OPACITY_MID,
+ filter: blurAt(GHOST_BLUR_MID_PX),
+ offset: GHOST_OFFSET_MID,
+ },
+ {
+ transform: tfAt(GHOST_OFFSET_LATE),
+ opacity: GHOST_OPACITY_LATE,
+ filter: blurAt(GHOST_BLUR_LATE_PX),
+ offset: GHOST_OFFSET_LATE,
+ },
+ { transform: tfAt(1), opacity: GHOST_OPACITY_PEAK, filter: blurAt(GHOST_BLUR_PEAK_PX), offset: GHOST_OFFSET_PEAK },
+ { transform: tfAt(1), opacity: 0, filter: blurAt(0) },
+ ];
+
+ const animation = ghost.animate(keyframes, {
+ duration: VT_EVIDENCE_PAGE_EXPAND_MS,
+ easing: EASE_COLLAPSE,
+ fill: "both",
+ });
+
+ // Coordinated popover content fade-in — dims the ENTIRE popover (header,
+ // status section, image, toolbar — everything) so the ghost is the only
+ // visible element during the first 55% of the animation.
+ //
+ // Mirrors the collapse's "dip-then-reveal":
+ // Collapse: new content stays at 0 until 60%, then reveals sharply 0→1.
+ // Expand: popover stays near-invisible while ghost dominates,
+ // then reveals sharply in the last ~40%.
+ //
+ // Previously we only dimmed [data-dc-inline-expanded] (the image container),
+ // leaving Zone 1 (header) and Zone 2 (status/claim) at full opacity — which
+ // made the expand look like "the page popped in" despite the image being dimmed.
+ if (popoverRoot) {
+ const contentAnim = popoverRoot.animate(
+ [
+ { opacity: PAGE_EXPAND_CONTENT_OPACITY_START },
+ { opacity: 0.03, offset: 0.45 },
+ { opacity: 0.08, offset: 0.58 },
+ { opacity: 0.35, offset: 0.72 },
+ { opacity: 0.8, offset: 0.88 },
+ { opacity: 1 },
+ ],
+ { duration: VT_EVIDENCE_PAGE_EXPAND_MS, easing: BLINK_ENTER_EASING, fill: "forwards" },
+ );
+ contentAnim.finished
+ .catch(() => {})
+ .finally(() => {
+ // Cancel removes the WAAPI animation layer so its fill: "forwards"
+ // no longer overrides inline styles on subsequent transitions.
+ contentAnim.cancel();
+ popoverRoot.style.opacity = "";
+ popoverRoot.style.transition = "";
+ });
+ }
+
+ animation.finished
+ .catch(() => {})
+ .finally(() => {
+ ghost.remove();
+ });
+}
+
+function waitForPageExpandTarget(
+ root: ParentNode,
+ snapshot: GhostSnapshot,
+ callback: (target: PageExpandTarget | null) => void,
+ attemptsLeft = 12,
+ previousStableRect: DOMRect | null = null,
+ stableFrames = 0,
+): void {
+ requestAnimationFrame(() => {
+ const target = findPageExpandTarget(root, snapshot);
+ const targetRect = target?.markerRect ?? null;
+ const debugPhase = getPageExpandDebugPhase();
+ if (
+ targetRect &&
+ isVisibleRect(targetRect) &&
+ targetRect.bottom > 0 &&
+ targetRect.right > 0 &&
+ targetRect.top < window.innerHeight &&
+ targetRect.left < window.innerWidth
+ ) {
+ if (debugPhase === "target" || debugPhase === "both") {
+ callback(target);
+ return;
+ }
+ const isStable =
+ previousStableRect &&
+ Math.abs(targetRect.left - previousStableRect.left) <= 1 &&
+ Math.abs(targetRect.top - previousStableRect.top) <= 1 &&
+ Math.abs(targetRect.width - previousStableRect.width) <= 1 &&
+ Math.abs(targetRect.height - previousStableRect.height) <= 1;
+ if (isStable && stableFrames >= 0) {
+ callback(target);
+ return;
+ }
+ if (attemptsLeft <= 1) {
+ callback(target);
+ return;
+ }
+ waitForPageExpandTarget(root, snapshot, callback, attemptsLeft - 1, targetRect, isStable ? stableFrames + 1 : 0);
+ return;
+ }
+ if (attemptsLeft <= 1) {
+ callback(target);
+ return;
+ }
+ waitForPageExpandTarget(root, snapshot, callback, attemptsLeft - 1, null, 0);
+ });
+}
+
+export function startEvidencePageExpandTransition(
+ update: () => void,
+ options?: { root?: ParentNode | null; skipAnimation?: boolean },
+): void {
+ const root = options?.root ?? null;
+ if (options?.skipAnimation || typeof document === "undefined" || !root) {
+ // Guard the transition depth even in the synchronous fallback so dismiss
+ // handlers see a consistent in-flight state during the state update.
+ _transitionDepth++;
+ try {
+ update();
+ } finally {
+ _transitionDepth = Math.max(0, _transitionDepth - 1);
+ }
+ return;
+ }
+
+ const debugPhase = getPageExpandDebugPhase();
+ // Clear stale debug overlays from a previous transition / popover session
+ // so every page-expand attempt starts fresh.
+ if (debugPhase) clearDebugOverlays();
+
+ // Resolve root to an HTMLElement for style manipulation. The root is
+ // popoverContentRef.current — always an HTMLElement at runtime.
+ const rootEl = root instanceof HTMLElement ? root : null;
+
+ // Commit the state update and run the ghost transition in a microtask.
+ // This matches the timing of the View Transition API (which defers its
+ // callback), and avoids mutating the DOM via flushSync while the browser
+ // is still processing the click event that triggered the expand — React
+ // can lose track of the event target when it's replaced mid-handler.
+ //
+ // queueMicrotask typically fires before the next paint (within the same
+ // task frame during React event batching), so the pre-dim + flushSync
+ // + ghost creation all complete within the same visual frame.
+ const commitAndAnimate = () => {
+ _transitionDepth++;
+ const source = capturePageExpandSource(root);
+
+ // Pre-dim the ENTIRE popover content BEFORE flushSync. This ensures that
+ // when flushSync makes the expanded-page slot visible, the whole popover
+ // (header, status, image — everything) appears already dimmed.
+ //
+ // CRITICAL: Disable CSS transitions first. The PopoverContent element has
+ // `transition: opacity 60ms ...` from getBlinkContainerMotionStyle("steady").
+ // Without disabling transitions, the opacity change animates from 1 → 0.03
+ // over ~60ms — the first paint frame shows the expanded page at ~50% opacity,
+ // which reads as a full-page flash before the ghost animation begins.
+ if (rootEl) {
+ // Cancel any lingering WAAPI animations from a previous page-expand.
+ // `fill: "forwards"` on the content fade-in holds opacity: 1 indefinitely
+ // at a higher cascade priority than inline styles — without cancelling,
+ // the inline opacity: 0.03 below would be silently overridden.
+ for (const anim of rootEl.getAnimations()) anim.cancel();
+ rootEl.style.transition = "none";
+ rootEl.style.opacity = String(PAGE_EXPAND_CONTENT_OPACITY_START);
+ }
+
+ flushSync(update);
+
+ if (!source) {
+ if (rootEl) {
+ rootEl.style.opacity = "";
+ rootEl.style.transition = "";
+ }
+ if (debugPhase) {
+ clearDebugOverlays();
+ const primedEls = root.querySelectorAll?.("[data-dc-page-expand-source]");
+ console.warn(
+ "[DC debug] source capture FAILED — no visible source element found.",
+ `${primedEls?.length ?? 0} [data-dc-page-expand-source] elements in root.`,
+ );
+ }
+ _transitionDepth = Math.max(0, _transitionDepth - 1);
+ return;
+ }
+ const ghost = createPageExpandGhost(source);
+ if (!ghost) {
+ if (rootEl) {
+ rootEl.style.opacity = "";
+ rootEl.style.transition = "";
+ }
+ if (debugPhase) {
+ console.warn("[DC debug] ghost creation FAILED — image validation rejected:", source.imageSrc);
+ }
+ _transitionDepth = Math.max(0, _transitionDepth - 1);
+ return;
+ }
+ waitForPageExpandTarget(root, source, target => {
+ _transitionDepth = Math.max(0, _transitionDepth - 1);
+ if (!target) {
+ ghost.remove();
+ if (rootEl) {
+ rootEl.style.opacity = "";
+ rootEl.style.transition = "";
+ }
+ if (debugPhase) {
+ clearDebugOverlays();
+ const targetEls = root.querySelectorAll?.("[data-dc-page-expand-target]");
+ const readyEls = root.querySelectorAll?.('[data-dc-page-expand-ready="true"]');
+ const kindLabel =
+ source.sourceKind === "summary-keyhole"
+ ? "summary keyhole"
+ : source.sourceKind === "expanded-keyhole"
+ ? "expanded keyhole"
+ : "source";
+ createDebugOverlay(
+ source.viewportRect,
+ DEBUG_PAGE_EXPAND_SOURCE_COLOR,
+ `SOURCE (${kindLabel}) — TARGET NOT FOUND`,
+ `anchor: (${source.sourceAnchorX.toFixed(2)}, ${source.sourceAnchorY.toFixed(2)})`,
+ );
+ console.warn(
+ "[DC debug] target NOT FOUND after 12 rAF polls.",
+ `\n [data-dc-page-expand-target] elements: ${targetEls?.length ?? 0}`,
+ `\n [data-dc-page-expand-ready="true"] elements: ${readyEls?.length ?? 0}`,
+ "\n This usually means annotationVtRect is null (no text match on the page — not_found/miss state).",
+ "\n Source snapshot:",
+ source,
+ );
+ }
+ return;
+ }
+ runPageExpandGhostAnimation(ghost, source, target, rootEl);
+ });
+ };
+
+ queueMicrotask(commitAndAnimate);
+}
+
+// =============================================================================
+// CONSOLE DEBUG API
+// =============================================================================
+//
+// Usage from browser DevTools:
+// __dcDebugPageExpand("both") — show source + target + marker overlays
+// __dcDebugPageExpand("source") — freeze ghost at source rect
+// __dcDebugPageExpand("target") — freeze ghost at target rect
+// __dcDebugPageExpand(null) — disable debug mode
+// __dcDebugPageExpand() — toggle: off → "both" → "source" → "target" → off
+// __dcDebugPageExpand.clear() — remove debug overlays without changing mode
+
+if (typeof window !== "undefined") {
+ const CYCLE: DebugPhase[] = ["both", "source", "target", null];
+
+ const api = (phase?: DebugPhase | undefined) => {
+ if (phase === undefined) {
+ // Cycle through modes
+ const current = getPageExpandDebugPhase();
+ const idx = CYCLE.indexOf(current);
+ const next = CYCLE[(idx + 1) % CYCLE.length];
+ return api(next ?? null);
+ }
+ if (phase === null) {
+ delete document.documentElement.dataset.dcPageExpandDebugPhase;
+ clearDebugOverlays();
+ console.log("[DC debug] page-expand debug OFF");
+ } else {
+ document.documentElement.dataset.dcPageExpandDebugPhase = phase;
+ if (phase !== "both") clearDebugOverlays();
+ console.log(
+ `[DC debug] page-expand debug: %c${phase}`,
+ `color: ${phase === "source" ? DEBUG_PAGE_EXPAND_SOURCE_COLOR : phase === "target" ? DEBUG_PAGE_EXPAND_TARGET_COLOR : "#3b82f6"}; font-weight: bold`,
+ "— click a page pill / View Page to trigger",
+ );
+ }
+ return phase;
+ };
+ api.clear = () => {
+ clearDebugOverlays();
+ console.log("[DC debug] overlays cleared");
+ };
+
+ /** Scan the live DOM and outline all page-expand source/target elements without triggering a transition. */
+ api.scan = () => {
+ clearDebugOverlays();
+ const sources = document.querySelectorAll("[data-dc-page-expand-source]");
+ const targets = document.querySelectorAll("[data-dc-page-expand-target]");
+ let sourceCount = 0;
+ let targetCount = 0;
+ sources.forEach(el => {
+ const rect = el.getBoundingClientRect();
+ if (!isVisibleRect(rect)) return;
+ sourceCount++;
+ const kind = el.dataset.dcPageExpandSourceKind ?? "unknown";
+ const anchorX = el.dataset.dcSourceAnchorX ?? "—";
+ const anchorY = el.dataset.dcSourceAnchorY ?? "—";
+ createDebugOverlay(rect, DEBUG_PAGE_EXPAND_SOURCE_COLOR, `SOURCE (${kind})`, `anchor: (${anchorX}, ${anchorY})`);
+ });
+ targets.forEach(el => {
+ const rect = el.getBoundingClientRect();
+ if (!isVisibleRect(rect)) return;
+ targetCount++;
+ const ready = el.dataset.dcPageExpandReady;
+ const color = ready === "true" ? DEBUG_PAGE_EXPAND_TARGET_COLOR : "#f59e0b";
+ createDebugOverlay(rect, color, `TARGET (ready=${ready ?? "?"})`);
+ });
+ console.log(
+ `[DC debug] scan: ${sourceCount} visible source(s), ${targetCount} visible target(s)`,
+ `\n Total in DOM: ${sources.length} source(s), ${targets.length} target(s)`,
+ );
+ return { sources: sourceCount, targets: targetCount };
+ };
+
+ (window as unknown as Record).__dcDebugPageExpand = api;
+}
diff --git a/tests/playwright/specs/PageExpandGeometryCitation.tsx b/tests/playwright/specs/PageExpandGeometryCitation.tsx
new file mode 100644
index 00000000..08fa67d0
--- /dev/null
+++ b/tests/playwright/specs/PageExpandGeometryCitation.tsx
@@ -0,0 +1,105 @@
+import { useMemo } from "react";
+import { CitationComponent } from "../../../src/react/Citation";
+import type { Citation } from "../../../src/types/citation";
+import type { Verification } from "../../../src/types/verification";
+
+const baseCitation: Citation = {
+ type: "document",
+ attachmentId: "att-page-expand-geometry",
+ citationNumber: 1,
+ anchorText: "Collision installation",
+ fullPhrase:
+ 'At YC we use the term "Collision installation" for the technique they invented. More diffident founders ask "Will you try our beta?"',
+ pageNumber: 5,
+};
+
+function createCanvasDataUrl(width: number, height: number, label: string): string {
+ if (typeof document === "undefined") {
+ return "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mO8cuXKfwYGBgYGAAi7Av7W3NgAAAAASUVORK5CYII=";
+ }
+ const canvas = document.createElement("canvas");
+ canvas.width = width;
+ canvas.height = height;
+ const ctx = canvas.getContext("2d");
+ if (!ctx) {
+ return "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mO8cuXKfwYGBgYGAAi7Av7W3NgAAAAASUVORK5CYII=";
+ }
+ ctx.fillStyle = "#f3f4f6";
+ ctx.fillRect(0, 0, width, height);
+ ctx.fillStyle = "#111827";
+ ctx.font = `${Math.max(16, Math.floor(height * 0.18))}px sans-serif`;
+ ctx.fillText(label, 20, Math.max(30, Math.floor(height * 0.45)));
+ ctx.strokeStyle = "#2563eb";
+ ctx.lineWidth = 4;
+ ctx.strokeRect(12, 12, width - 24, height - 24);
+ return canvas.toDataURL("image/png");
+}
+
+export function PageExpandGeometryCitation() {
+ const pageSrc = useMemo(
+ () =>
+ createCanvasDataUrl(
+ 800,
+ 1600,
+ 'At YC we use the term "Collision installation" for the technique they invented.',
+ ),
+ [],
+ );
+ const evidenceSrc = useMemo(() => createCanvasDataUrl(560, 120, '"Collision installation"'), []);
+
+ const verification = useMemo(
+ () => ({
+ status: "found",
+ attachmentId: "att-page-expand-geometry",
+ verifiedMatchSnippet: 'At YC we use the term "Collision installation" for the technique they invented.',
+ verifiedAnchorText: "Collision installation",
+ verifiedFullPhrase:
+ 'At YC we use the term "Collision installation" for the technique they invented. More diffident founders ask "Will you try our beta?"',
+ document: {
+ verifiedPageNumber: 5,
+ phraseMatchDeepItem: {
+ x: 140,
+ y: 1280,
+ width: 460,
+ height: 34,
+ text: 'At YC we use the term "Collision installation" for the technique they invented.',
+ },
+ anchorTextMatchDeepItems: [
+ {
+ x: 330,
+ y: 1280,
+ width: 170,
+ height: 34,
+ text: "Collision installation",
+ },
+ ],
+ renderScale: { x: 1, y: 1 },
+ },
+ evidence: {
+ src: evidenceSrc,
+ dimensions: { width: 560, height: 120 },
+ },
+ }),
+ [evidenceSrc],
+ );
+
+ const pageImagesByAttachmentId = useMemo(
+ () => ({
+ "att-page-expand-geometry": [
+ {
+ pageNumber: 5,
+ dimensions: { width: 800, height: 1600 },
+ imageUrl: pageSrc,
+ isMatchPage: true,
+ },
+ ],
+ }),
+ [pageSrc],
+ );
+
+ return (
+
+
+
+ );
+}
diff --git a/tests/playwright/specs/citationPopoverInteractions.spec.tsx b/tests/playwright/specs/citationPopoverInteractions.spec.tsx
index 76d2a7ad..16d5c795 100644
--- a/tests/playwright/specs/citationPopoverInteractions.spec.tsx
+++ b/tests/playwright/specs/citationPopoverInteractions.spec.tsx
@@ -237,7 +237,7 @@ test.describe("Citation Popover - Click-to-Close Behavior", () => {
// Click the page pill to switch to expanded-page view (another internal transition)
const pagePill = popover.getByRole("button", { name: /full page/i }).first();
if (await pagePill.isVisible()) {
- await pagePill.dispatchEvent("click");
+ await pagePill.click();
await page.waitForTimeout(100);
}
@@ -445,7 +445,8 @@ test.describe("Citation Popover - Click-to-Close Behavior", () => {
await expect(toPageButton).toBeVisible();
// keyhole -> expanded-page
- await toPageButton.dispatchEvent("click");
+ // Use click() instead of dispatchEvent to ensure React handles the event
+ await toPageButton.click();
const pageExpandSamples = await page.evaluate(async () => {
const dialog = document.querySelector("[role='dialog']") as HTMLElement | null;
if (!dialog) return { inlineOpacity: [] as number[] };
@@ -477,7 +478,7 @@ test.describe("Citation Popover - Click-to-Close Behavior", () => {
// expanded-page -> keyhole
const backToKeyholeButton = popover.getByRole("button", { name: /Close (page|image)/i }).first();
await expect(backToKeyholeButton).toBeVisible();
- await backToKeyholeButton.dispatchEvent("click");
+ await backToKeyholeButton.click();
const pageCollapseSamples = await page.evaluate(async () => {
const dialog = document.querySelector("[role='dialog']") as HTMLElement | null;
if (!dialog) return { maxTransitionSeconds: 0 };
diff --git a/tests/playwright/specs/pageExpandGeometry.spec.tsx b/tests/playwright/specs/pageExpandGeometry.spec.tsx
new file mode 100644
index 00000000..344d8b3c
--- /dev/null
+++ b/tests/playwright/specs/pageExpandGeometry.spec.tsx
@@ -0,0 +1,166 @@
+import { expect, test } from "@playwright/experimental-ct-react";
+import { PageExpandGeometryCitation } from "./PageExpandGeometryCitation";
+
+async function openSummaryPopover(page: import("@playwright/test").Page) {
+ await page.locator("[data-citation-id]").click();
+ const popover = page.locator("[data-dc-popover-wrapper]");
+ await expect(popover).toBeVisible();
+ return popover;
+}
+
+async function freezeSummaryToPageTransition(
+ page: import("@playwright/test").Page,
+ phase: "source" | "target",
+ popover?: import("@playwright/test").Locator,
+) {
+ await page.evaluate(currentPhase => {
+ document.documentElement.dataset.dcPageExpandDebugPhase = currentPhase;
+ }, phase);
+ const activePopover = popover ?? (await openSummaryPopover(page));
+ const expandButton = activePopover.getByLabel(/Expand to full page/).first();
+ await expect(expandButton).toBeVisible();
+ await expandButton.click();
+ const ghost = page.locator("[data-dc-page-expand-ghost]");
+ await expect(ghost).toBeVisible();
+ return { popover: activePopover, ghost };
+}
+
+test.describe("Page Expand Geometry Debug", () => {
+ test.afterEach(async ({ page }) => {
+ await page.evaluate(() => {
+ delete document.documentElement.dataset.dcPageExpandDebugPhase;
+ });
+ });
+
+ test("source phase starts from the visible summary keyhole box", async ({ mount, page }) => {
+ await mount();
+ const popover = await openSummaryPopover(page);
+ const source = popover.locator("[data-dc-page-expand-source]").filter({ visible: true }).first();
+ const sourceBox = await source.boundingBox();
+ expect(sourceBox).toBeTruthy();
+ await page.evaluate(() => {
+ delete document.documentElement.dataset.dcPageExpandDebugPhase;
+ });
+
+ const { ghost } = await freezeSummaryToPageTransition(page, "source", popover);
+ const ghostBox = await ghost.boundingBox();
+ expect(ghostBox).toBeTruthy();
+
+ expect(Math.abs(ghostBox!.x - sourceBox!.x)).toBeLessThanOrEqual(2);
+ expect(Math.abs(ghostBox!.y - sourceBox!.y)).toBeLessThanOrEqual(2);
+ // Width tolerance 5px: ghost includes SPOTLIGHT_PADDING around the source keyhole
+ expect(Math.abs(ghostBox!.width - sourceBox!.width)).toBeLessThanOrEqual(5);
+ expect(Math.abs(ghostBox!.height - sourceBox!.height)).toBeLessThanOrEqual(2);
+ });
+
+ test("target phase lands near the settled expanded-page target and stays on-screen", async ({ mount, page }) => {
+ await mount();
+ const { ghost } = await freezeSummaryToPageTransition(page, "target");
+ // The ghost lands on the spotlight (annotation + SPOTLIGHT_PADDING), not the
+ // bare annotation marker. Use [data-dc-spotlight] as the reference rect.
+ // Fall back to [data-dc-page-expand-target] if no spotlight is rendered.
+ const spotlight = page.locator("[data-dc-spotlight]").first();
+ const target = page.locator("[data-dc-page-expand-target][data-dc-page-expand-ready='true']").first();
+ await expect(target).toBeVisible();
+
+ // Prefer spotlight if it exists; fall back to the annotation marker.
+ // Resolve the reference element inside the poll so we pick up the spotlight
+ // even if it paints after the initial count check.
+ await expect
+ .poll(
+ async () => {
+ const referenceEl = (await spotlight.count()) > 0 ? spotlight : target;
+ const referenceBox = await referenceEl.boundingBox();
+ const ghostBox = await ghost.boundingBox();
+ if (!ghostBox || !referenceBox) return Number.POSITIVE_INFINITY;
+ return Math.max(
+ Math.abs(ghostBox.x - referenceBox.x),
+ Math.abs(ghostBox.y - referenceBox.y),
+ Math.abs(ghostBox.width - referenceBox.width),
+ Math.abs(ghostBox.height - referenceBox.height),
+ );
+ },
+ { timeout: 1500 },
+ )
+ .toBeLessThanOrEqual(5);
+ // Re-sample after the poll has confirmed convergence.
+ const referenceEl = (await spotlight.count()) > 0 ? spotlight : target;
+ const referenceBox = await referenceEl.boundingBox();
+ const ghostBox = await ghost.boundingBox();
+ const viewport = page.viewportSize()!;
+ expect(ghostBox).toBeTruthy();
+ expect(referenceBox).toBeTruthy();
+
+ expect(Math.abs(ghostBox!.x - referenceBox!.x)).toBeLessThanOrEqual(5);
+ expect(Math.abs(ghostBox!.y - referenceBox!.y)).toBeLessThanOrEqual(5);
+ expect(Math.abs(ghostBox!.width - referenceBox!.width)).toBeLessThanOrEqual(5);
+ expect(Math.abs(ghostBox!.height - referenceBox!.height)).toBeLessThanOrEqual(5);
+ expect(ghostBox!.x).toBeGreaterThanOrEqual(-2);
+ expect(ghostBox!.y).toBeGreaterThanOrEqual(-2);
+ expect(ghostBox!.x + ghostBox!.width).toBeLessThanOrEqual(viewport.width + 2);
+ expect(ghostBox!.y + ghostBox!.height).toBeLessThanOrEqual(viewport.height + 2);
+ });
+
+ test("both phase renders source, target, and marker debug overlays", async ({ mount, page }) => {
+ await mount();
+ const popover = await openSummaryPopover(page);
+
+ // Set "both" debug phase — ghost is replaced by three persistent overlays
+ await page.evaluate(() => {
+ document.documentElement.dataset.dcPageExpandDebugPhase = "both";
+ });
+ const expandButton = popover.getByLabel(/Expand to full page/).first();
+ await expect(expandButton).toBeVisible();
+ await expandButton.click();
+
+ // Ghost should NOT be in the DOM (removed in "both" mode)
+ const ghost = page.locator("[data-dc-page-expand-ghost]");
+ await expect(ghost).toBeHidden({ timeout: 1500 });
+
+ // Three debug overlays should be visible
+ const overlays = page.locator("[data-dc-debug-overlay]");
+ await expect(overlays).toHaveCount(3, { timeout: 1500 });
+
+ // All overlays should be on-screen
+ const viewport = page.viewportSize()!;
+ for (let i = 0; i < 3; i++) {
+ const box = await overlays.nth(i).boundingBox();
+ expect(box).toBeTruthy();
+ expect(box!.width).toBeGreaterThan(1);
+ expect(box!.height).toBeGreaterThan(1);
+ // At least partially on-screen
+ expect(box!.x + box!.width).toBeGreaterThan(0);
+ expect(box!.y + box!.height).toBeGreaterThan(0);
+ expect(box!.x).toBeLessThan(viewport.width);
+ expect(box!.y).toBeLessThan(viewport.height);
+ }
+ });
+
+ test("scan() outlines live source/target elements without triggering a transition", async ({ mount, page }) => {
+ await mount();
+ await openSummaryPopover(page);
+
+ const result = await page.evaluate(() => {
+ const api = (window as unknown as Record { sources: number; targets: number } }>)
+ .__dcDebugPageExpand;
+ return api.scan();
+ });
+ // Summary popover should have at least one source element
+ expect(result.sources).toBeGreaterThanOrEqual(1);
+ // Overlays should be in the DOM
+ const overlays = page.locator("[data-dc-debug-overlay]");
+ expect(await overlays.count()).toBeGreaterThanOrEqual(1);
+ });
+
+ test("ghost is removed from the DOM after the animation completes", async ({ mount, page }) => {
+ await mount();
+ const popover = await openSummaryPopover(page);
+ const expandButton = popover.getByLabel(/Expand to full page/).first();
+ await expect(expandButton).toBeVisible();
+ await expandButton.click();
+ const ghost = page.locator("[data-dc-page-expand-ghost]");
+ // Ghost should appear then be removed after animation (250ms + buffer)
+ await expect(ghost).toBeHidden({ timeout: 2000 });
+ expect(await ghost.count()).toBe(0);
+ });
+});