From 77c6a5a3bfbe94cfd7423edef8b0a8103fc27a46 Mon Sep 17 00:00:00 2001
From: michael <operations@dangerousthings.com>
Date: Wed, 15 Apr 2026 12:42:10 -0700
Subject: [PATCH] feat(DTGallery): add optional activeIndex prop for external
 control

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 packages/react/src/components/DTGallery.tsx | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/packages/react/src/components/DTGallery.tsx b/packages/react/src/components/DTGallery.tsx
index c5d2d10..f2a578b 100644
--- a/packages/react/src/components/DTGallery.tsx
+++ b/packages/react/src/components/DTGallery.tsx
@@ -41,6 +41,9 @@ export type DTGalleryItem =
 
 interface DTGalleryProps {
   items: DTGalleryItem[];
+  /** Externally-controlled active index. When this value changes, the gallery
+   *  jumps to the corresponding item. Thumbnail clicks still work normally. */
+  activeIndex?: number;
   /** Color variant @default 'normal' */
   variant?: DTVariant;
   /** Aspect ratio (width / height) for the display area @default 1 */
@@ -85,12 +88,20 @@ const fillStyle: CSSProperties = {
 
 export function DTGallery({
   items,
+  activeIndex: activeIndexProp,
   variant = 'normal',
   aspectRatio = 1,
   className,
   style,
 }: DTGalleryProps) {
-  const [activeIndex, setActiveIndex] = useState(0);
+  const [activeIndex, setActiveIndex] = useState(activeIndexProp ?? 0);
+
+  // Sync external activeIndex prop to internal state when it changes
+  useEffect(() => {
+    if (activeIndexProp != null && activeIndexProp >= 0 && activeIndexProp < items.length) {
+      setActiveIndex(activeIndexProp);
+    }
+  }, [activeIndexProp, items.length]);
 
   const hasModel = items.some((i) => i.type === 'model3d');
   useModelViewerScript(hasModel);