@tldiagram/core-ui 1.94.5 → 1.95.1

package/dist/pages/InfiniteZoom.d.ts

@@ -1,9 +1,11 @@
+import { type ZUICameraFrame } from '../components/ZUI';
 interface Props {
     sharedToken?: string;
     shareSlot?: React.ReactNode;
 }
 export interface InfiniteZoomHandle {
     focusDiagram(viewId: number): boolean;
+    setCameraFrame(frame: ZUICameraFrame): boolean;
 }
 declare const InfiniteZoom: import("react").ForwardRefExoticComponent<Props & import("react").RefAttributes<InfiniteZoomHandle>>;
 export default InfiniteZoom;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tldiagram/core-ui",
-  "version": "1.94.5",
+  "version": "1.95.1",
   "type": "module",
   "repository": {
     "type": "git",

package/src/components/MiniZoomOnboarding.tsx

@@ -1,18 +1,13 @@
-import { Box, HStack, Text } from '@chakra-ui/react'
-import { keyframes } from '@emotion/react'
+import { Box, CloseButton, HStack, Text } from '@chakra-ui/react'
 import { ZoomInIcon } from './Icons'
 
 interface Props {
   isVisible: boolean
+  onClose?: () => void
 }
 
-const pulseGlow = keyframes`
-  0% { box-shadow: 0 0 0 0 rgba(var(--accent-rgb), 0.4); }
-  70% { box-shadow: 0 0 0 20px rgba(var(--accent-rgb), 0); }
-  100% { box-shadow: 0 0 0 0 rgba(var(--accent-rgb), 0); }
-`
 
-export default function MiniZoomOnboarding({ isVisible }: Props) {
+export default function MiniZoomOnboarding({ isVisible, onClose }: Props) {
   return (
     <Box
       position="absolute"
@@ -22,14 +17,14 @@ export default function MiniZoomOnboarding({ isVisible }: Props) {
       zIndex={100}
       opacity={isVisible ? 1 : 0}
       transition="all 0.8s cubic-bezier(0.16, 1, 0.3, 1)"
-      pointerEvents="none"
+      pointerEvents={isVisible ? 'auto' : 'none'}
     >
       <Box
         className="glass"
         px={6}
+        pr={onClose ? 11 : 6}
         py={4}
         borderRadius="12px"
-        animation={isVisible ? `${pulseGlow} 3s infinite` : 'none'}
         position="relative"
         overflow="hidden"
         border="1.5px solid rgba(var(--accent-rgb), 0.3)"
@@ -44,27 +39,39 @@ export default function MiniZoomOnboarding({ isVisible }: Props) {
           bg="var(--accent)"
           opacity={0.8}
         />
-        
+        {onClose && (
+          <CloseButton
+            aria-label="Dismiss zoom hint"
+            position="absolute"
+            top={2}
+            right={2}
+            size="sm"
+            color="whiteAlpha.700"
+            _hover={{ color: 'white', bg: 'whiteAlpha.200' }}
+            onClick={onClose}
+          />
+        )}
+
         <HStack spacing={5} pl={3}>
           <Box color="var(--accent)">
             <ZoomInIcon size={24} />
           </Box>
           <Box>
-            <Text 
-              fontSize="10px" 
-              color="var(--accent)" 
-              fontWeight="900" 
-              letterSpacing="0.15em" 
-              textTransform="uppercase" 
+            <Text
+              fontSize="10px"
+              color="var(--accent)"
+              fontWeight="900"
+              letterSpacing="0.15em"
+              textTransform="uppercase"
               mb={0.5}
               opacity={0.9}
             >
-              Pro Tip
+              Hint:
             </Text>
-            <Text 
-              fontSize="15px" 
-              color="white" 
-              fontWeight="600" 
+            <Text
+              fontSize="15px"
+              color="white"
+              fontWeight="600"
               whiteSpace="nowrap"
               letterSpacing="-0.01em"
             >

package/src/components/ZUI/ZUICanvas.tsx

@@ -38,6 +38,12 @@ import { buildVisibleProxyConnectors, collectVisibleNodeAnchors, drawVisibleProx
 export interface ZUICanvasHandle {
   fitView(): void
   focusDiagram(viewId: number): boolean
+  setCameraFrame(frame: ZUICameraFrame): boolean
+}
+
+export interface ZUICameraFrame {
+  profile: 'detail-to-overview'
+  progress: number
 }
 
 interface Props {
@@ -45,6 +51,7 @@ interface Props {
   onReady?: () => void
   onZoom?: () => void
   onPan?: () => void
+  initialCameraFrame?: ZUICameraFrame
   highlightedTags?: string[]
   highlightColor?: string
   hiddenTags?: string[]
@@ -238,7 +245,82 @@ function easeOutQuart(t: number): number {
   return 1 - Math.pow(1 - t, 4)
 }
 
-export const ZUICanvas = forwardRef<ZUICanvasHandle, Props>(function ZUICanvas({ data, onReady, onZoom, onPan, highlightedTags, highlightColor, hiddenTags, crossBranchSettings, hoverLocked = false }, ref) {
+function clamp01(value: number): number {
+  return Math.max(0, Math.min(1, value))
+}
+
+function fitWorldRect(
+  rect: { x: number; y: number; w: number; h: number },
+  canvasW: number,
+  canvasH: number,
+  maxZoom: number,
+  padding: number,
+): ZUIViewState | null {
+  const bboxW = Math.max(1, rect.w)
+  const bboxH = Math.max(1, rect.h)
+  const zoom = Math.min(
+    (canvasW * (1 - padding * 2)) / bboxW,
+    (canvasH * (1 - padding * 2)) / bboxH,
+    maxZoom,
+  )
+  if (!Number.isFinite(zoom) || zoom <= 0) return null
+
+  return {
+    x: (canvasW - bboxW * zoom) / 2 - rect.x * zoom,
+    y: (canvasH - bboxH * zoom) / 2 - rect.y * zoom,
+    zoom,
+  }
+}
+
+function findFirstExpandableNode(groups: DiagramGroupLayout[]): PathItem | null {
+  for (const group of groups) {
+    const found = findFirstExpandableNodeInTree(group.nodes, 0, 0, 1, 0, 0)
+    if (found) return found
+  }
+  return null
+}
+
+function findFirstExpandableNodeInTree(
+  nodes: DiagramGroupLayout['nodes'],
+  parentAbsX: number,
+  parentAbsY: number,
+  parentAbsScale: number,
+  parentChildOffsetX: number,
+  parentChildOffsetY: number,
+): PathItem | null {
+  for (const node of nodes) {
+    const absX = parentAbsX + (node.worldX - parentChildOffsetX) * parentAbsScale
+    const absY = parentAbsY + (node.worldY - parentChildOffsetY) * parentAbsScale
+    const absW = node.worldW * parentAbsScale
+    const absH = node.worldH * parentAbsScale
+
+    if (node.children.length > 0) {
+      return {
+        id: node.id,
+        label: node.linkedDiagramLabel || node.label,
+        type: 'node',
+        isCircular: node.isCircular,
+        absX,
+        absY,
+        absW,
+        absH,
+      }
+    }
+
+    const found = findFirstExpandableNodeInTree(
+      node.children,
+      absX,
+      absY,
+      parentAbsScale * node.childScale,
+      node.childOffsetX,
+      node.childOffsetY,
+    )
+    if (found) return found
+  }
+  return null
+}
+
+export const ZUICanvas = forwardRef<ZUICanvasHandle, Props>(function ZUICanvas({ data, onReady, onZoom, onPan, initialCameraFrame, highlightedTags, highlightColor, hiddenTags, crossBranchSettings, hoverLocked = false }, ref) {
   const canvasRef = useRef<HTMLCanvasElement>(null)
   const containerRef = useRef<HTMLDivElement>(null)
   const cameraTransitionRef = useRef<number | null>(null)
@@ -445,6 +527,68 @@ export const ZUICanvas = forwardRef<ZUICanvasHandle, Props>(function ZUICanvas({
     return true
   }, [isMobileLayout, layout.groups, maxZoom, setHoveredItem, setViewState, viewStateRef])
 
+  const setCameraFrame = useCallback((frame: ZUICameraFrame) => {
+    if (frame.profile !== 'detail-to-overview') return false
+
+    const el = containerRef.current
+    if (!el) return false
+
+    const canvasW = el.offsetWidth
+    const canvasH = el.offsetHeight
+    if (canvasW === 0 || canvasH === 0) return false
+
+    const detailTarget = findFirstExpandableNode(layout.groups)
+    const overviewTarget = layout.groups[0]
+    if (!detailTarget || !overviewTarget) return false
+
+    const detail = fitWorldRect(
+      {
+        x: detailTarget.absX,
+        y: detailTarget.absY,
+        w: detailTarget.absW,
+        h: detailTarget.absH,
+      },
+      canvasW,
+      canvasH,
+      maxZoom,
+      0.28,
+    )
+
+    const overview = fitWorldRect(
+      {
+        x: overviewTarget.worldX,
+        y: overviewTarget.worldY,
+        w: overviewTarget.worldW,
+        h: overviewTarget.worldH,
+      },
+      canvasW,
+      canvasH,
+      maxZoom,
+      0.18,
+    )
+
+    if (!detail || !overview) return false
+
+    if (cameraTransitionRef.current !== null) {
+      cancelAnimationFrame(cameraTransitionRef.current)
+      cameraTransitionRef.current = null
+    }
+
+    setHoveredItem(null, true)
+    const t = easeOutQuart(clamp01(frame.progress))
+    setViewState({
+      x: detail.x + (overview.x - detail.x) * t,
+      y: detail.y + (overview.y - detail.y) * t,
+      zoom: detail.zoom + (overview.zoom - detail.zoom) * t,
+    })
+    return true
+  }, [layout.groups, maxZoom, setHoveredItem, setViewState])
+
+  const fitInitialView = useCallback((w: number, h: number) => {
+    if (initialCameraFrame && setCameraFrame(initialCameraFrame)) return
+    fitView(w, h, layout.bbox)
+  }, [fitView, initialCameraFrame, layout.bbox, setCameraFrame])
+
   useEffect(() => {
     return () => {
       if (cameraTransitionRef.current !== null) {
@@ -462,14 +606,13 @@ export const ZUICanvas = forwardRef<ZUICanvasHandle, Props>(function ZUICanvas({
     // Only set as initialized if we have valid dimensions
     if (w > 0 && h > 0) {
       setContainerSize({ w, h })
-      fitView(w, h, layout.bbox)
+      fitInitialView(w, h)
       if (!initialized) {
         setInitialized(true)
         onReady?.()
       }
     }
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [layout, initialized, onReady])
+  }, [initialized, onReady, fitInitialView])
 
   // ── Expose fitView to parent ─────────────────────────────────────
   useImperativeHandle(
@@ -482,8 +625,9 @@ export const ZUICanvas = forwardRef<ZUICanvasHandle, Props>(function ZUICanvas({
         fitView(el.offsetWidth, el.offsetHeight, layout.bbox)
       },
       focusDiagram,
+      setCameraFrame,
     }),
-    [fitView, focusDiagram, layout.bbox, setHoveredItem],
+    [fitView, focusDiagram, layout.bbox, setCameraFrame, setHoveredItem],
   )
 
   // ── RAF render loop ──────────────────────────────────────────────
@@ -531,7 +675,7 @@ export const ZUICanvas = forwardRef<ZUICanvasHandle, Props>(function ZUICanvas({
 
       // Trigger initialization if it hasn't happened yet
       if (!initialized && w > 0 && h > 0) {
-        fitView(w, h, layout.bbox)
+        fitInitialView(w, h)
         setInitialized(true)
         onReady?.()
       }
@@ -541,7 +685,7 @@ export const ZUICanvas = forwardRef<ZUICanvasHandle, Props>(function ZUICanvas({
     ro.observe(container)
     resize()
     return () => ro.disconnect()
-  }, [initialized, layout, fitView, onReady])
+  }, [initialized, fitInitialView, onReady])
 
   useEffect(() => {
     if (!initialized) return // Don't start loop until initialized

package/src/components/ZUI/index.ts

@@ -1,3 +1,3 @@
 // src/components/ZUI/index.ts
 export { ZUICanvas } from './ZUICanvas'
-export type { ZUICanvasHandle } from './ZUICanvas'
+export type { ZUICameraFrame, ZUICanvasHandle } from './ZUICanvas'

package/src/pages/InfiniteZoom.tsx

@@ -1,6 +1,6 @@
 // src/pages/InfiniteZoom.tsx Explore page holds the ZUI feature
 import { forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState } from 'react'
-import { useNavigate, useParams } from 'react-router-dom'
+import { useLocation, useNavigate, useParams } from 'react-router-dom'
 import {
   Box,
   Button,
@@ -24,7 +24,7 @@ import { FitViewIcon as FitViewSvg, TagsIcon, EyeIcon, EyeOffIcon, FocusIcon as
 import ExploreOnboarding from '../components/ExploreOnboarding'
 import ExplorePageOnboarding from '../components/ExplorePageOnboarding'
 import MiniZoomOnboarding from '../components/MiniZoomOnboarding'
-import { ZUICanvas, type ZUICanvasHandle } from '../components/ZUI'
+import { ZUICanvas, type ZUICameraFrame, type ZUICanvasHandle } from '../components/ZUI'
 import { useCrossBranchContextSettings } from '../crossBranch/settings'
 import { primeWorkspaceGraphSnapshot } from '../crossBranch/store'
 
@@ -36,6 +36,7 @@ interface Props {
 
 export interface InfiniteZoomHandle {
   focusDiagram(viewId: number): boolean
+  setCameraFrame(frame: ZUICameraFrame): boolean
 }
 
 const MINI_ONBOARDING_KEY = 'shared_zoom_onboarding_dismissed'
@@ -43,11 +44,13 @@ const MINI_ONBOARDING_KEY = 'shared_zoom_onboarding_dismissed'
 // ── Inner component ────────────────────────────────────────────────
 function InfiniteZoomInner({ sharedToken, shareSlot }: Props, ref?: React.Ref<InfiniteZoomHandle>) {
   const navigate = useNavigate()
+  const location = useLocation()
 
   const [data, setData] = useState<ExploreData | null>(null)
   const [loading, setLoading] = useState(true)
   const [canvasReady, setCanvasReady] = useState(false)
   const [showMiniOnboarding, setShowMiniOnboarding] = useState(false)
+  const [miniOnboardingInteractionSeen, setMiniOnboardingInteractionSeen] = useState(false)
   const [tagColors] = useState<Record<string, import('../types').Tag>>({})
   const [layers, setLayers] = useState<ViewLayer[]>([])
   const [highlightedTags, setHighlightedTags] = useState<string[]>([])
@@ -58,10 +61,22 @@ function InfiniteZoomInner({ sharedToken, shareSlot }: Props, ref?: React.Ref<In
   const crossBranchSurface = sharedToken ? 'zui-shared' : 'zui'
   const { settings: crossBranchSettings, setEnabled: setCrossBranchEnabled } = useCrossBranchContextSettings(crossBranchSurface)
 
+  const cameraProfile = useMemo(() => new URLSearchParams(location.search).get('profile'), [location.search])
+  const isDetailToOverviewProfile = sharedToken && cameraProfile === 'detail-to-overview'
+
+  const initialCameraFrame = useMemo<ZUICameraFrame | undefined>(() => {
+    return isDetailToOverviewProfile
+      ? { profile: 'detail-to-overview', progress: 0 }
+      : undefined
+  }, [isDetailToOverviewProfile])
+
   useImperativeHandle(ref, () => ({
     focusDiagram(viewId: number) {
       return zuiRef.current?.focusDiagram(viewId) ?? false
     },
+    setCameraFrame(frame: ZUICameraFrame) {
+      return zuiRef.current?.setCameraFrame(frame) ?? false
+    },
   }), [])
 
   // ── No data or No content ────────────────────────────────────────
@@ -120,17 +135,32 @@ function InfiniteZoomInner({ sharedToken, shareSlot }: Props, ref?: React.Ref<In
   }, [])
 
   useEffect(() => {
+    if (isDetailToOverviewProfile) return
     if (sharedToken && canvasReady && !localStorage.getItem(MINI_ONBOARDING_KEY)) {
       setShowMiniOnboarding(true)
     }
-  }, [sharedToken, canvasReady])
+  }, [sharedToken, canvasReady, isDetailToOverviewProfile])
 
-  const handleInteraction = useCallback(() => {
+  const dismissMiniOnboarding = useCallback(() => {
     if (showMiniOnboarding) {
       setShowMiniOnboarding(false)
-      localStorage.setItem(MINI_ONBOARDING_KEY, 'true')
+      if (!isDetailToOverviewProfile) {
+        localStorage.setItem(MINI_ONBOARDING_KEY, 'true')
+      }
     }
-  }, [showMiniOnboarding])
+  }, [isDetailToOverviewProfile, showMiniOnboarding])
+
+  const showMiniOnboardingAfterCanvasInteraction = useCallback(() => {
+    if (!isDetailToOverviewProfile || miniOnboardingInteractionSeen) return
+    setMiniOnboardingInteractionSeen(true)
+    setShowMiniOnboarding(true)
+  }, [isDetailToOverviewProfile, miniOnboardingInteractionSeen])
+
+  const handleCanvasZoom = useCallback(() => {
+    setMiniOnboardingInteractionSeen(true)
+    dismissMiniOnboarding()
+  }, [dismissMiniOnboarding])
+
   useEffect(() => {
     const loader = sharedToken ? api.explore.loadShared(sharedToken) : api.explore.load()
     loader.then((d) => {
@@ -173,6 +203,24 @@ function InfiniteZoomInner({ sharedToken, shareSlot }: Props, ref?: React.Ref<In
     setCanvasReady(true)
   }, [])
 
+  useEffect(() => {
+    if (!sharedToken) return
+
+    const handleMessage = (event: MessageEvent) => {
+      const data = event.data as { type?: unknown; progress?: unknown; profile?: unknown } | null
+      if (!data || data.type !== 'tldiagram-zui-camera') return
+      if (data.profile !== 'detail-to-overview') return
+
+      const progress = Number(data.progress)
+      if (!Number.isFinite(progress)) return
+
+      zuiRef.current?.setCameraFrame({ profile: 'detail-to-overview', progress })
+    }
+
+    window.addEventListener('message', handleMessage)
+    return () => window.removeEventListener('message', handleMessage)
+  }, [sharedToken])
+
   if (!loading && (!data || (data.tree ?? []).length === 0 || !hasPlacements)) {
     const noDiagrams = !data || (data.tree ?? []).length === 0
     return (
@@ -221,8 +269,9 @@ function InfiniteZoomInner({ sharedToken, shareSlot }: Props, ref?: React.Ref<In
             ref={zuiRef}
             data={data}
             onReady={handleCanvasReady}
-            onZoom={handleInteraction}
-            onPan={handleInteraction}
+            onZoom={handleCanvasZoom}
+            onPan={showMiniOnboardingAfterCanvasInteraction}
+            initialCameraFrame={initialCameraFrame}
             highlightedTags={highlightedTags}
             highlightColor={highlightColor}
             hiddenTags={hiddenTags}
@@ -232,7 +281,7 @@ function InfiniteZoomInner({ sharedToken, shareSlot }: Props, ref?: React.Ref<In
 
           {/* Onboarding overlay */}
           {data && !sharedToken && <ExploreOnboarding hasLinkedNodes={!!(data.navigations?.length > 0)} />}
-          <MiniZoomOnboarding isVisible={showMiniOnboarding} />
+          <MiniZoomOnboarding isVisible={showMiniOnboarding} onClose={dismissMiniOnboarding} />
 
           {/* Bottom toolbar */}
           <Box