@copilotkit/react-core 1.56.2 → 1.56.4-canary.1777529757

package/src/v2/components/chat/CopilotChatAttachmentRenderer.tsx

@@ -2,6 +2,7 @@ import React, { memo, useState } from "react";
 import type { InputContentSource } from "@copilotkit/shared";
 import { getSourceUrl, getDocumentIcon } from "@copilotkit/shared";
 import { cn } from "../../lib/utils";
+import { Lightbox, useLightbox } from "./Lightbox";
 
 interface CopilotChatAttachmentRendererProps {
   type: "image" | "audio" | "video" | "document";
@@ -18,6 +19,8 @@ const ImageAttachment = memo(function ImageAttachment({
   className?: string;
 }) {
   const [error, setError] = useState(false);
+  const { thumbnailRef, vtName, open, openLightbox, closeLightbox } =
+    useLightbox();
 
   if (error) {
     return (
@@ -33,12 +36,29 @@ const ImageAttachment = memo(function ImageAttachment({
   }
 
   return (
-    <img
-      src={src}
-      alt="Image attachment"
-      className={cn("cpk:max-w-full cpk:h-auto cpk:rounded-lg", className)}
-      onError={() => setError(true)}
-    />
+    <>
+      <img
+        ref={thumbnailRef as React.Ref<HTMLImageElement>}
+        src={src}
+        alt="Image attachment"
+        className={cn(
+          "cpk:max-w-[80px] cpk:max-h-[80px] cpk:w-auto cpk:h-auto cpk:rounded-xl cpk:object-cover cpk:cursor-pointer cpk:bg-muted",
+          className,
+        )}
+        onClick={openLightbox}
+        onError={() => setError(true)}
+      />
+      {open && (
+        <Lightbox onClose={closeLightbox}>
+          <img
+            style={{ viewTransitionName: vtName }}
+            src={src}
+            alt="Image attachment"
+            className="cpk:max-w-[90vw] cpk:max-h-[90vh] cpk:object-contain cpk:rounded-lg"
+          />
+        </Lightbox>
+      )}
+    </>
   );
 });
 

package/src/v2/components/chat/CopilotChatInput.tsx

@@ -87,6 +87,19 @@ type CopilotChatInputRestProps = {
   containerRef?: React.Ref<HTMLDivElement>;
   /** Whether to show the disclaimer. Default: true for absolute positioning, false for static */
   showDisclaimer?: boolean;
+  /**
+   * Set to `true` when the input sits at the bottom of its container as a
+   * flex-last-child (visible position is driven by layout, not CSS
+   * positioning). Triggers reservation of bottom space for the fixed
+   * CopilotKit license banner via the
+   * `--copilotkit-license-banner-offset` CSS var so the two don't overlap.
+   *
+   * Not needed when `positioning === "absolute"`; that mode already pins the
+   * input to the bottom and picks up the same reservation automatically.
+   * Leave unset (default `false`) for inputs rendered mid-layout such as the
+   * welcome screen, where the banner offset would push the input off-center.
+   */
+  bottomAnchored?: boolean;
 } & Omit<React.HTMLAttributes<HTMLDivElement>, "onChange">;
 
 type CopilotChatInputBaseProps = WithSlots<
@@ -130,6 +143,7 @@ export function CopilotChatInput({
   keyboardHeight = 0,
   containerRef,
   showDisclaimer,
+  bottomAnchored = false,
   textArea,
   sendButton,
   startTranscribeButton,
@@ -1097,6 +1111,14 @@ export function CopilotChatInput({
         transform:
           keyboardHeight > 0 ? `translateY(-${keyboardHeight}px)` : undefined,
         transition: "transform 0.2s ease-out",
+        // Reserve room when the fixed license banner is visible so it doesn't
+        // overlap the input. Applied only for bottom-anchored inputs (either
+        // `positioning === "absolute"`, or an explicitly-flagged flex-last-child
+        // input in run state). The welcome-screen input sits mid-layout and
+        // must stay still when the banner is present.
+        ...(positioning === "absolute" || bottomAnchored
+          ? { paddingBottom: "var(--copilotkit-license-banner-offset, 0px)" }
+          : {}),
       }}
       {...props}
     >

package/src/v2/components/chat/CopilotChatUserMessage.tsx

@@ -217,9 +217,8 @@ export function CopilotChatUserMessage({
       data-message-id={message.id}
       {...props}
     >
-      {BoundMessageRenderer}
       {mediaParts.length > 0 && (
-        <div className="cpk:flex cpk:flex-col cpk:items-end cpk:gap-2 cpk:mt-2">
+        <div className="cpk:flex cpk:flex-row cpk:flex-wrap cpk:justify-end cpk:gap-2 cpk:mb-2">
           {mediaParts.map((part, index) => (
             <CopilotChatAttachmentRenderer
               key={index}
@@ -230,6 +229,7 @@ export function CopilotChatUserMessage({
           ))}
         </div>
       )}
+      {BoundMessageRenderer}
       {BoundToolbar}
     </div>
   );

package/src/v2/components/chat/CopilotChatView.tsx

@@ -6,17 +6,19 @@ import React, {
   useLayoutEffect,
 } from "react";
 import { ScrollElementContext } from "./scroll-element-context";
-import { WithSlots, SlotValue, renderSlot } from "../../lib/slots";
+import type { WithSlots, SlotValue } from "../../lib/slots";
+import { renderSlot } from "../../lib/slots";
 import CopilotChatMessageView from "./CopilotChatMessageView";
-import CopilotChatInput, {
+import type {
   CopilotChatInputProps,
   CopilotChatInputMode,
 } from "./CopilotChatInput";
+import CopilotChatInput from "./CopilotChatInput";
 import CopilotChatSuggestionView, {
   CopilotChatSuggestionViewProps,
 } from "./CopilotChatSuggestionView";
-import { Suggestion } from "@copilotkit/core";
-import { Message } from "@ag-ui/core";
+import type { Suggestion } from "@copilotkit/core";
+import type { Message } from "@ag-ui/core";
 import type { Attachment } from "@copilotkit/shared";
 import { CopilotChatAttachmentQueue } from "./CopilotChatAttachmentQueue";
 import { twMerge } from "tailwind-merge";
@@ -33,9 +35,12 @@ import {
   CopilotChatDefaultLabels,
 } from "../../providers/CopilotChatConfigurationProvider";
 import { useKeyboardHeight } from "../../hooks/use-keyboard-height";
+import { normalizeAutoScroll } from "./normalize-auto-scroll";
+import type { AutoScrollMode } from "./normalize-auto-scroll";
+import { usePinToSend } from "../../hooks/use-pin-to-send";
 
-// Height of the feather gradient overlay (h-24 = 6rem = 96px)
-const FEATHER_HEIGHT = 96;
+// Vertical gap between the scroll-to-bottom button and the input container.
+const SCROLL_BUTTON_OFFSET = 16;
 
 // Forward declaration for WelcomeScreen component type
 export type WelcomeScreenProps = WithSlots<
@@ -57,7 +62,7 @@ export type CopilotChatViewProps = WithSlots<
   },
   {
     messages?: Message[];
-    autoScroll?: boolean;
+    autoScroll?: AutoScrollMode | boolean;
     isRunning?: boolean;
     suggestions?: Suggestion[];
     suggestionLoadingIndexes?: ReadonlyArray<number>;
@@ -81,6 +86,21 @@ export type CopilotChatViewProps = WithSlots<
     onDragOver?: (e: React.DragEvent) => void;
     onDragLeave?: (e: React.DragEvent) => void;
     onDrop?: (e: React.DragEvent) => void;
+    /**
+     * When `true`, suppresses the welcome screen while a thread's initial
+     * connect is in flight. Prevents the "How can I help you today?" flash
+     * that would otherwise appear between mounting an empty cloned agent and
+     * the bootstrap messages arriving from /connect.
+     */
+    isConnecting?: boolean;
+    /**
+     * When `true`, the caller has explicitly picked a thread (via `threadId`
+     * prop or `CopilotChatConfigurationProvider`). Suppresses the welcome
+     * screen unconditionally — a caller-managed thread targets a specific
+     * conversation and should render its messages (or an empty panel during
+     * connect) rather than a generic "start a new chat" greeting.
+     */
+    hasExplicitThreadId?: boolean;
     /**
      * @deprecated Use the `input` slot's `disclaimer` prop instead:
      * ```tsx
@@ -139,13 +159,25 @@ export function CopilotChatView({
   onDragOver,
   onDragLeave,
   onDrop,
+  isConnecting = false,
+  hasExplicitThreadId = false,
   // Deprecated — forwarded to input slot
   disclaimer,
   children,
   className,
   ...props
 }: CopilotChatViewProps) {
-  const inputContainerRef = useRef<HTMLDivElement>(null);
+  // Element-as-state via callback ref. The overlay wrapper only renders on the
+  // chat-view branch (the welcome-screen branch omits it), so a plain
+  // useRef + `[]` useEffect would observe `null` on mount whenever the chat
+  // starts on the welcome screen and never re-attach after the user sends
+  // their first message — leaving inputContainerHeight at 0 and the scroll
+  // content's reserved bottom padding at 32px instead of ~input height. The
+  // result is the last messages scrolling underneath the absolute-positioned
+  // input pill. Subscribing to element state lets the observer attach (and
+  // detach) reactively as the overlay mounts/unmounts.
+  const [inputContainerEl, setInputContainerEl] =
+    useState<HTMLDivElement | null>(null);
   const [inputContainerHeight, setInputContainerHeight] = useState(0);
   const [isResizing, setIsResizing] = useState(false);
   const resizeTimeoutRef = useRef<NodeJS.Timeout | null>(null);
@@ -156,8 +188,14 @@ export function CopilotChatView({
 
   // Track input container height changes
   useEffect(() => {
-    const element = inputContainerRef.current;
-    if (!element) return;
+    const element = inputContainerEl;
+    if (!element) {
+      // Reset measured height so the scroll content's paddingBottom doesn't
+      // hold a stale value if the overlay unmounts (e.g. messages cleared
+      // and the welcome screen returns).
+      setInputContainerHeight(0);
+      return;
+    }
 
     const resizeObserver = new ResizeObserver((entries) => {
       for (const entry of entries) {
@@ -196,7 +234,7 @@ export function CopilotChatView({
         clearTimeout(resizeTimeoutRef.current);
       }
     };
-  }, []);
+  }, [inputContainerEl]);
 
   const BoundMessageView = renderSlot(messageView, CopilotChatMessageView, {
     messages,
@@ -217,12 +255,23 @@ export function CopilotChatView({
     onAddFile,
     positioning: "static",
     keyboardHeight: isKeyboardOpen ? keyboardHeight : 0,
-    containerRef: inputContainerRef,
     showDisclaimer: true,
+    // The parent overlay wrapper handles absolute bottom-0 positioning.
+    // `bottomAnchored` still triggers the license-banner offset padding
+    // inside CopilotChatInput. The welcome-screen input (below) intentionally
+    // omits this flag.
+    bottomAnchored: true,
     ...(disclaimer !== undefined ? { disclaimer } : {}),
   } as CopilotChatInputProps);
 
-  const hasSuggestions = Array.isArray(suggestions) && suggestions.length > 0;
+  // Hide suggestions while a thread is connecting (mid-replay would render
+  // against a still-assembling message tree and visibly jump as each final
+  // text chunk reflows the layout). Run-in-flight is handled by the
+  // SuggestionEngine: at run start, non-"always" suggestions are cleared and
+  // only "always" ones are restored — so a non-empty `suggestions` array
+  // here already means "this is something the user opted to keep visible."
+  const hasSuggestions =
+    !isConnecting && Array.isArray(suggestions) && suggestions.length > 0;
   const BoundSuggestionView = hasSuggestions
     ? renderSlot(suggestionView, CopilotChatSuggestionView, {
         suggestions,
@@ -238,8 +287,9 @@ export function CopilotChatView({
     isResizing,
     children: (
       <div
+        data-testid="copilot-scroll-content"
         style={{
-          paddingBottom: `${hasSuggestions ? 4 : 32}px`,
+          paddingBottom: `${inputContainerHeight + (hasSuggestions ? 4 : 32)}px`,
         }}
       >
         <div className="cpk:max-w-3xl cpk:mx-auto">
@@ -258,7 +308,13 @@ export function CopilotChatView({
   const isEmpty = messages.length === 0;
   // Type assertion needed because TypeScript doesn't fully propagate `| boolean` through WithSlots
   const welcomeScreenDisabled = (welcomeScreen as unknown) === false;
-  const shouldShowWelcomeScreen = isEmpty && !welcomeScreenDisabled;
+  // Suppress the welcome screen (1) while the initial connect is in flight
+  // and (2) whenever the caller has picked a specific thread. The caller-
+  // managed case targets a conversation directly, so the generic welcome
+  // greeting is never the right thing to show — even for a thread that
+  // happens to have no messages yet.
+  const shouldShowWelcomeScreen =
+    isEmpty && !welcomeScreenDisabled && !isConnecting && !hasExplicitThreadId;
 
   if (shouldShowWelcomeScreen) {
     // Create a separate input for welcome screen with static positioning and disclaimer visible
@@ -356,17 +412,22 @@ export function CopilotChatView({
       {dragOver && <DropOverlay />}
       {BoundScrollView}
 
-      <div className="cpk:max-w-3xl cpk:mx-auto cpk:w-full">
+      <div
+        ref={setInputContainerEl}
+        data-testid="copilot-input-overlay"
+        className="cpk:absolute cpk:bottom-0 cpk:left-0 cpk:right-0 cpk:z-20 cpk:pointer-events-none"
+      >
         {attachments && attachments.length > 0 && (
-          <CopilotChatAttachmentQueue
-            attachments={attachments}
-            onRemoveAttachment={(id) => onRemoveAttachment?.(id)}
-            className="cpk:px-4"
-          />
+          <div className="cpk:max-w-3xl cpk:mx-auto cpk:w-full cpk:pointer-events-auto">
+            <CopilotChatAttachmentQueue
+              attachments={attachments}
+              onRemoveAttachment={(id) => onRemoveAttachment?.(id)}
+              className="cpk:px-4"
+            />
+          </div>
         )}
+        {BoundInput}
       </div>
-
-      {BoundInput}
     </div>
   );
 }
@@ -417,7 +478,6 @@ export namespace CopilotChatView {
             </div>
           </StickToBottom.Content>
 
-          {/* Feather gradient overlay */}
           {BoundFeather}
 
           {/* Scroll to bottom button - hidden during resize */}
@@ -425,7 +485,7 @@ export namespace CopilotChatView {
             <div
               className="cpk:absolute cpk:inset-x-0 cpk:flex cpk:justify-center cpk:z-30 cpk:pointer-events-none"
               style={{
-                bottom: `${inputContainerHeight + FEATHER_HEIGHT + 16}px`,
+                bottom: `${inputContainerHeight + SCROLL_BUTTON_OFFSET}px`,
               }}
             >
               {renderSlot(
@@ -442,9 +502,105 @@ export namespace CopilotChatView {
     );
   };
 
+  // Internal component for pin-to-send scroll behavior — not exported on CopilotChatView.
+  const PinToSendScrollContainer: React.FC<
+    React.HTMLAttributes<HTMLDivElement> & {
+      scrollRef: React.MutableRefObject<HTMLElement | null>;
+      contentRef: React.MutableRefObject<HTMLElement | null>;
+      scrollToBottom: () => void;
+      scrollToBottomButton?: SlotValue<
+        React.FC<React.ButtonHTMLAttributes<HTMLButtonElement>>
+      >;
+      feather?: SlotValue<React.FC<React.HTMLAttributes<HTMLDivElement>>>;
+      inputContainerHeight: number;
+      isResizing: boolean;
+      nonAutoScrollEl: HTMLElement | null;
+      nonAutoScrollRefCallback: (el: HTMLElement | null) => void;
+      showScrollButton: boolean;
+    }
+  > = ({
+    children,
+    scrollRef,
+    contentRef,
+    scrollToBottom,
+    scrollToBottomButton,
+    feather,
+    inputContainerHeight,
+    isResizing,
+    nonAutoScrollEl,
+    nonAutoScrollRefCallback,
+    showScrollButton,
+    className,
+    ...props
+  }) => {
+    const spacerRef = useRef<HTMLDivElement>(null);
+
+    usePinToSend({
+      scrollRef,
+      contentRef,
+      spacerRef,
+      topOffset: 16,
+    });
+
+    // The feather and scroll-to-bottom button live OUTSIDE the scroll
+    // container. `position: absolute` children of an `overflow: auto` element
+    // are positioned relative to the scroll *content*, which means they
+    // scroll away with it. Placing them as siblings of the scroll container
+    // (inside a `relative` wrapper) keeps them pinned to the viewport bottom.
+    const BoundFeather = renderSlot(feather, CopilotChatView.Feather, {});
+
+    return (
+      <ScrollElementContext.Provider value={nonAutoScrollEl}>
+        <div
+          className={cn(
+            "cpk:h-full cpk:max-h-full cpk:flex cpk:flex-col cpk:min-h-0 cpk:relative",
+            className,
+          )}
+        >
+          <div
+            ref={nonAutoScrollRefCallback}
+            className="cpk:flex-1 cpk:min-h-0 cpk:overflow-y-auto cpk:overflow-x-hidden"
+            {...props}
+          >
+            <div
+              ref={contentRef}
+              className="cpk:px-4 cpk:sm:px-0 cpk:[div[data-sidebar-chat]_&]:px-8 cpk:[div[data-popup-chat]_&]:px-6"
+            >
+              {children}
+            </div>
+            <div
+              ref={spacerRef}
+              data-pin-to-send-spacer
+              aria-hidden="true"
+              style={{ height: 0, flex: "0 0 auto" }}
+            />
+          </div>
+          {BoundFeather}
+          {/* Scroll to bottom button */}
+          {showScrollButton && !isResizing && (
+            <div
+              className="cpk:absolute cpk:inset-x-0 cpk:flex cpk:justify-center cpk:z-30 cpk:pointer-events-none"
+              style={{
+                bottom: `${inputContainerHeight + SCROLL_BUTTON_OFFSET}px`,
+              }}
+            >
+              {renderSlot(
+                scrollToBottomButton,
+                CopilotChatView.ScrollToBottomButton,
+                {
+                  onClick: () => scrollToBottom(),
+                },
+              )}
+            </div>
+          )}
+        </div>
+      </ScrollElementContext.Provider>
+    );
+  };
+
   export const ScrollView: React.FC<
     React.HTMLAttributes<HTMLDivElement> & {
-      autoScroll?: boolean;
+      autoScroll?: AutoScrollMode | boolean;
       scrollToBottomButton?: SlotValue<
         React.FC<React.ButtonHTMLAttributes<HTMLButtonElement>>
       >;
@@ -454,7 +610,7 @@ export namespace CopilotChatView {
     }
   > = ({
     children,
-    autoScroll = true,
+    autoScroll = "pin-to-bottom",
     scrollToBottomButton,
     feather,
     inputContainerHeight = 0,
@@ -462,8 +618,18 @@ export namespace CopilotChatView {
     className,
     ...props
   }) => {
+    const mode = normalizeAutoScroll(autoScroll);
     const [hasMounted, setHasMounted] = useState(false);
-    const { scrollRef, contentRef, scrollToBottom } = useStickToBottom();
+    // Plain refs for the "none" and "pin-to-send" paths. Do NOT use
+    // useStickToBottom() here — its internal effects would attach scroll-following
+    // behavior to these refs and fight pin-to-send. The "pin-to-bottom" path
+    // gets its refs via <StickToBottom> below, scoped to that branch only.
+    const scrollRef = useRef<HTMLElement | null>(null);
+    const contentRef = useRef<HTMLElement | null>(null);
+    const scrollToBottom = useCallback(() => {
+      const el = scrollRef.current;
+      if (el) el.scrollTo({ top: el.scrollHeight, behavior: "smooth" });
+    }, []);
     const [showScrollButton, setShowScrollButton] = useState(false);
     // Tracks the scroll container element for the non-autoScroll path so the
     // context value is reactive (element state, not a ref).
@@ -478,7 +644,7 @@ export namespace CopilotChatView {
         scrollRef.current = el;
         setNonAutoScrollEl(el);
       },
-      // scrollRef is a stable object from useStickToBottom; safe to omit.
+      // scrollRef is a stable ref object; safe to omit.
       // eslint-disable-next-line react-hooks/exhaustive-deps
       [],
     );
@@ -489,7 +655,7 @@ export namespace CopilotChatView {
 
     // Monitor scroll position for non-autoscroll mode
     useEffect(() => {
-      if (autoScroll) return; // Skip for autoscroll mode
+      if (mode === "pin-to-bottom") return; // Skip for autoscroll mode
 
       const scrollElement = scrollRef.current;
       if (!scrollElement) return;
@@ -514,7 +680,7 @@ export namespace CopilotChatView {
         scrollElement.removeEventListener("scroll", checkScroll);
         resizeObserver.disconnect();
       };
-    }, [scrollRef, autoScroll]);
+    }, [scrollRef, mode]);
 
     if (!hasMounted) {
       return (
@@ -526,8 +692,7 @@ export namespace CopilotChatView {
       );
     }
 
-    // When autoScroll is false, we don't use StickToBottom
-    if (!autoScroll) {
+    if (mode === "none") {
       const BoundFeather = renderSlot(feather, CopilotChatView.Feather, {});
 
       return (
@@ -549,7 +714,6 @@ export namespace CopilotChatView {
               {children}
             </div>
 
-            {/* Feather gradient overlay */}
             {BoundFeather}
 
             {/* Scroll to bottom button for manual mode */}
@@ -557,7 +721,7 @@ export namespace CopilotChatView {
               <div
                 className="cpk:absolute cpk:inset-x-0 cpk:flex cpk:justify-center cpk:z-30 cpk:pointer-events-none"
                 style={{
-                  bottom: `${inputContainerHeight + FEATHER_HEIGHT + 16}px`,
+                  bottom: `${inputContainerHeight + SCROLL_BUTTON_OFFSET}px`,
                 }}
               >
                 {renderSlot(
@@ -574,6 +738,28 @@ export namespace CopilotChatView {
       );
     }
 
+    if (mode === "pin-to-send") {
+      return (
+        <PinToSendScrollContainer
+          scrollRef={scrollRef}
+          contentRef={contentRef}
+          scrollToBottom={scrollToBottom}
+          scrollToBottomButton={scrollToBottomButton}
+          feather={feather}
+          inputContainerHeight={inputContainerHeight}
+          isResizing={isResizing}
+          nonAutoScrollEl={nonAutoScrollEl}
+          nonAutoScrollRefCallback={nonAutoScrollRefCallback}
+          showScrollButton={showScrollButton}
+          className={className}
+          {...props}
+        >
+          {children}
+        </PinToSendScrollContainer>
+      );
+    }
+
+    // mode === "pin-to-bottom" (default)
     return (
       <StickToBottom
         className={cn(
@@ -617,22 +803,14 @@ export namespace CopilotChatView {
     </Button>
   );
 
+  // Default renders an empty div — no visual, but the element is still in the
+  // tree so a slot override of the form `scrollView={{ feather: "my-class" }}`
+  // can apply classes (and any consumer with a full component override gets
+  // the className/style forwarding they expect).
   export const Feather: React.FC<React.HTMLAttributes<HTMLDivElement>> = ({
     className,
-    style,
     ...props
-  }) => (
-    <div
-      className={cn(
-        "cpk:absolute cpk:bottom-0 cpk:left-0 cpk:right-4 cpk:h-24 cpk:pointer-events-none cpk:z-10 cpk:bg-gradient-to-t",
-        "cpk:from-white cpk:via-white cpk:to-transparent",
-        "cpk:dark:from-[rgb(33,33,33)] cpk:dark:via-[rgb(33,33,33)]",
-        className,
-      )}
-      style={style}
-      {...props}
-    />
-  );
+  }) => <div className={className} {...props} />;
 
   export const WelcomeMessage: React.FC<
     React.HTMLAttributes<HTMLDivElement>

package/src/v2/components/chat/Lightbox.tsx

@@ -0,0 +1,103 @@
+import React, { useCallback, useEffect, useId, useRef, useState } from "react";
+import { createPortal, flushSync } from "react-dom";
+import { X } from "lucide-react";
+
+interface LightboxProps {
+  onClose: () => void;
+  children: React.ReactNode;
+}
+
+export function Lightbox({ onClose, children }: LightboxProps) {
+  useEffect(() => {
+    const handleKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") onClose();
+    };
+    document.addEventListener("keydown", handleKey);
+    return () => document.removeEventListener("keydown", handleKey);
+  }, [onClose]);
+
+  if (typeof document === "undefined") return null;
+
+  return createPortal(
+    <div
+      className="cpk:fixed cpk:inset-0 cpk:z-[9999] cpk:flex cpk:items-center cpk:justify-center cpk:bg-black/80 cpk:animate-fade-in"
+      onClick={onClose}
+    >
+      <button
+        onClick={onClose}
+        className="cpk:absolute cpk:top-4 cpk:right-4 cpk:text-white cpk:bg-white/10 cpk:hover:bg-white/20 cpk:rounded-full cpk:w-10 cpk:h-10 cpk:flex cpk:items-center cpk:justify-center cpk:cursor-pointer cpk:border-none cpk:z-10"
+        aria-label="Close preview"
+      >
+        <X className="cpk:w-5 cpk:h-5" />
+      </button>
+
+      <div onClick={(e) => e.stopPropagation()}>{children}</div>
+    </div>,
+    document.body,
+  );
+}
+
+type DocWithVT = Document & {
+  startViewTransition?: (cb: () => void) => { finished: Promise<void> };
+};
+
+/**
+ * Hook that manages lightbox open/close and uses the View Transition API to
+ * morph the thumbnail into fullscreen content.
+ *
+ * The trick: `view-transition-name` must live on exactly ONE element at a time.
+ * - Old state (thumbnail visible): name is on the thumbnail.
+ * - New state (lightbox visible): name moves to the lightbox content.
+ * `flushSync` ensures React commits the DOM change synchronously inside the
+ * `startViewTransition` callback so the API can snapshot old → new correctly.
+ */
+export function useLightbox() {
+  const thumbnailRef = useRef<HTMLElement>(null);
+  const [open, setOpen] = useState(false);
+  const vtName = useId();
+
+  const openLightbox = useCallback(() => {
+    const thumb = thumbnailRef.current;
+    const doc = document as DocWithVT;
+
+    if (doc.startViewTransition && thumb) {
+      thumb.style.viewTransitionName = vtName;
+
+      doc.startViewTransition(() => {
+        thumb.style.viewTransitionName = "";
+        flushSync(() => setOpen(true));
+      });
+    } else {
+      setOpen(true);
+    }
+  }, [vtName]);
+
+  const closeLightbox = useCallback(() => {
+    const thumb = thumbnailRef.current;
+    const doc = document as DocWithVT;
+
+    if (doc.startViewTransition && thumb) {
+      const transition = doc.startViewTransition(() => {
+        flushSync(() => setOpen(false));
+        thumb.style.viewTransitionName = vtName;
+      });
+      transition.finished
+        .then(() => {
+          thumb.style.viewTransitionName = "";
+        })
+        .catch(() => {
+          thumb.style.viewTransitionName = "";
+        });
+    } else {
+      setOpen(false);
+    }
+  }, [vtName]);
+
+  return {
+    thumbnailRef,
+    vtName,
+    open,
+    openLightbox,
+    closeLightbox,
+  };
+}