@almadar/ui 2.51.0 → 2.52.0

package/dist/avl/index.cjs

@@ -19388,13 +19388,13 @@ var MapViewImpl = React125.lazy(async () => {
     shadowSize: [41, 41]
   });
   L.Marker.prototype.options.icon = defaultIcon;
-  const { useEffect: useEffect87, useRef: useRef87, useCallback: useCallback124, useState: useState124 } = React125__namespace.default;
+  const { useEffect: useEffect88, useRef: useRef88, useCallback: useCallback124, useState: useState124 } = React125__namespace.default;
   const { Typography: Typography2 } = await Promise.resolve().then(() => (init_Typography(), Typography_exports));
   const { useEventBus: useEventBus3 } = await Promise.resolve().then(() => (init_useEventBus(), useEventBus_exports));
   function MapUpdater({ centerLat, centerLng, zoom }) {
     const map = useMap();
-    const prevRef = useRef87({ centerLat, centerLng, zoom });
-    useEffect87(() => {
+    const prevRef = useRef88({ centerLat, centerLng, zoom });
+    useEffect88(() => {
       const prev = prevRef.current;
       if (prev.centerLat !== centerLat || prev.centerLng !== centerLng || prev.zoom !== zoom) {
         map.setView([centerLat, centerLng], zoom);
@@ -19405,7 +19405,7 @@ var MapViewImpl = React125.lazy(async () => {
   }
   function MapClickHandler({ onMapClick }) {
     const map = useMap();
-    useEffect87(() => {
+    useEffect88(() => {
       if (!onMapClick) return;
       const handler = (e) => {
         onMapClick(e.latlng.lat, e.latlng.lng);
@@ -47775,12 +47775,18 @@ var OrbPreviewNodeInner = (props) => {
       el = el.parentElement;
       if (!el || el === contentRef.current) break;
     }
+    const containerNode = {
+      orbitalName: data.orbitalName,
+      traitName: data.traitName,
+      transitionEvent: data.transitionEvent
+    };
     const containerPath = el?.dataset?.patternPath;
     if (!containerPath) {
-      eventBus.emit("UI:PATTERN_INSERT", {
+      eventBus.emit("UI:PATTERN_DROP", {
         parentPath: "root",
         patternType: payload.data.type,
-        index: 0
+        index: 0,
+        containerNode
       });
       return;
     }
@@ -47797,12 +47803,13 @@ var OrbPreviewNodeInner = (props) => {
         break;
       }
     }
-    eventBus.emit("UI:PATTERN_INSERT", {
+    eventBus.emit("UI:PATTERN_DROP", {
       parentPath: containerPath,
       patternType: payload.data.type,
-      index: insertIndex
+      index: insertIndex,
+      containerNode
     });
-  }, [eventBus]);
+  }, [eventBus, data.orbitalName, data.traitName, data.transitionEvent]);
   const handlePreviewDragOver = React125.useCallback((e) => {
     if (!e.dataTransfer.types.includes(ALMADAR_DND_MIME)) return;
     e.preventDefault();
@@ -48713,6 +48720,7 @@ function FlowCanvasInner({
   onNodeClick,
   onLevelChange,
   onOrbitalDoubleClick,
+  cosmicEntryLevel = "expanded",
   initialOrbital,
   initialLevel,
   initialSelectedNode,
@@ -48786,19 +48794,24 @@ function FlowCanvasInner({
     }
     if (level === "overview") {
       const d = node.data;
-      setExpandedOrbital(d.orbitalName ?? node.id);
+      const orbitalName = d.orbitalName ?? node.id;
+      if (onOrbitalDoubleClick && (cosmicEntryLevel === "overview" || cosmicEntryLevel === "both")) {
+        onOrbitalDoubleClick(orbitalName);
+        return;
+      }
+      setExpandedOrbital(orbitalName);
       setLevel("expanded");
-      onLevelChange?.("expanded", d.orbitalName ?? node.id);
+      onLevelChange?.("expanded", orbitalName);
       return;
     }
     if (level === "expanded") {
       const d = node.data;
       const orbitalName = d.orbitalName ?? node.id;
-      if (orbitalName && onOrbitalDoubleClick) {
+      if (orbitalName && onOrbitalDoubleClick && (cosmicEntryLevel === "expanded" || cosmicEntryLevel === "both")) {
         onOrbitalDoubleClick(orbitalName);
       }
     }
-  }, [level, onLevelChange, onOrbitalDoubleClick, atBehaviorLevel, composeLevel]);
+  }, [level, onLevelChange, onOrbitalDoubleClick, cosmicEntryLevel, atBehaviorLevel, composeLevel]);
   const handleNodeClick = React125.useCallback((_, node) => {
     const nodeData = node.data;
     if (level === "expanded") {
@@ -49334,7 +49347,10 @@ var AvlOrbitalsCosmicZoom = ({
   animated = true,
   width = "100%",
   height = 450,
-  highlightedOrbital
+  highlightedOrbital,
+  onOrbitalSelect,
+  minZoom = 0.4,
+  maxZoom = 3
 }) => {
   const parsedSchema = React125.useMemo(() => {
     if (typeof schemaProp === "string") return JSON.parse(schemaProp);
@@ -49365,10 +49381,83 @@ var AvlOrbitalsCosmicZoom = ({
   );
   const [selected, setSelected] = React125.useState(null);
   const handleSelect = React125.useCallback(
-    (name) => setSelected((prev) => prev === name ? null : name),
-    []
+    (name) => {
+      setSelected((prev) => prev === name ? null : name);
+      onOrbitalSelect?.(name);
+    },
+    [onOrbitalSelect]
   );
   const selectedView = orbitalViews.find((o) => o.name === selected);
+  const [zoom, setZoom] = React125.useState(1);
+  const [pan, setPan] = React125.useState({ x: 0, y: 0 });
+  const dragStateRef = React125.useRef(null);
+  const transformWrapperRef = React125.useRef(null);
+  const clampZoom = React125.useCallback(
+    (z) => Math.max(minZoom, Math.min(maxZoom, z)),
+    [minZoom, maxZoom]
+  );
+  const handlePointerDown = React125.useCallback((e) => {
+    if (e.target.closest("[data-orbital-tile]")) return;
+    dragStateRef.current = {
+      startX: e.clientX,
+      startY: e.clientY,
+      panX: pan.x,
+      panY: pan.y
+    };
+    e.target.setPointerCapture(e.pointerId);
+  }, [pan]);
+  const handlePointerMove = React125.useCallback((e) => {
+    const drag = dragStateRef.current;
+    if (!drag) return;
+    setPan({
+      x: drag.panX + (e.clientX - drag.startX),
+      y: drag.panY + (e.clientY - drag.startY)
+    });
+  }, []);
+  const handlePointerUp = React125.useCallback((e) => {
+    if (!dragStateRef.current) return;
+    dragStateRef.current = null;
+    try {
+      e.target.releasePointerCapture(e.pointerId);
+    } catch {
+    }
+  }, []);
+  const panRef = React125.useRef(pan);
+  const zoomRef = React125.useRef(zoom);
+  React125.useEffect(() => {
+    panRef.current = pan;
+  }, [pan]);
+  React125.useEffect(() => {
+    zoomRef.current = zoom;
+  }, [zoom]);
+  React125.useEffect(() => {
+    const wrapper = transformWrapperRef.current;
+    if (!wrapper) return;
+    const wheelListener = (e) => {
+      e.preventDefault();
+      const rect = wrapper.getBoundingClientRect();
+      const cursorX = e.clientX - rect.left;
+      const cursorY = e.clientY - rect.top;
+      const currentZoom = zoomRef.current;
+      const currentPan = panRef.current;
+      const worldX = (cursorX - currentPan.x) / currentZoom;
+      const worldY = (cursorY - currentPan.y) / currentZoom;
+      const delta = e.deltaY > 0 ? -0.1 : 0.1;
+      const nextZoom = clampZoom(currentZoom * (1 + delta));
+      const nextPanX = cursorX - worldX * nextZoom;
+      const nextPanY = cursorY - worldY * nextZoom;
+      setZoom(nextZoom);
+      setPan({ x: nextPanX, y: nextPanY });
+    };
+    wrapper.addEventListener("wheel", wheelListener, { passive: false });
+    return () => wrapper.removeEventListener("wheel", wheelListener);
+  }, [clampZoom]);
+  const zoomIn = React125.useCallback(() => setZoom((z) => clampZoom(z * 1.2)), [clampZoom]);
+  const zoomOut = React125.useCallback(() => setZoom((z) => clampZoom(z / 1.2)), [clampZoom]);
+  const resetZoom = React125.useCallback(() => {
+    setZoom(1);
+    setPan({ x: 0, y: 0 });
+  }, []);
   return /* @__PURE__ */ jsxRuntime.jsxs(
     Box,
     {
@@ -49378,65 +49467,115 @@ var AvlOrbitalsCosmicZoom = ({
       style: { width, height: containerH },
       children: [
         /* @__PURE__ */ jsxRuntime.jsx(
-          EventWireOverlay,
+          "div",
           {
-            orbitalViews,
-            crossLinks,
-            color,
-            animated,
-            containerW,
-            containerH
-          }
-        ),
-        orbitalViews.map((view) => {
-          const isHighlighted = view.name === highlightedOrbital;
-          return /* @__PURE__ */ jsxRuntime.jsx(
-            Box,
-            {
-              role: "button",
-              tabIndex: 0,
-              onClick: () => handleSelect(view.name),
-              onKeyDown: (e) => {
-                if (e.key === "Enter" || e.key === " ") handleSelect(view.name);
-              },
-              "aria-label": `Orbital: ${view.name}${isHighlighted ? " (highlighted)" : ""}`,
+            ref: transformWrapperRef,
+            onPointerDown: handlePointerDown,
+            onPointerMove: handlePointerMove,
+            onPointerUp: handlePointerUp,
+            onPointerCancel: handlePointerUp,
+            style: {
               position: "absolute",
-              style: {
-                left: view.cx - UNIT_DISPLAY_W / 2,
-                top: view.cy - UNIT_DISPLAY_H / 2,
-                width: UNIT_DISPLAY_W,
-                height: UNIT_DISPLAY_H,
-                cursor: "pointer",
-                transition: "transform 0.2s ease, filter 0.2s ease, box-shadow 0.3s ease",
-                transform: selected === view.name ? "scale(1.05)" : "scale(1)",
-                filter: selected && selected !== view.name ? "opacity(0.5)" : "none",
-                // GAP-52: persistent highlight ring (independent from user selection)
-                boxShadow: isHighlighted ? `0 0 0 3px ${color}, 0 0 24px 4px ${color}` : "none",
-                borderRadius: isHighlighted ? "12px" : void 0,
-                zIndex: isHighlighted ? 11 : selected === view.name ? 10 : 1
-              },
-              children: /* @__PURE__ */ jsxRuntime.jsx(
-                AvlOrbitalUnit,
-                {
-                  entityName: view.entityName,
-                  fields: view.fieldCount,
-                  persistence: view.persistence,
-                  traits: view.traits,
-                  pages: view.pages,
-                  color,
-                  animated: animated && (selected === view.name || isHighlighted)
-                }
-              )
+              inset: 0,
+              overflow: "hidden",
+              cursor: dragStateRef.current ? "grabbing" : "grab",
+              touchAction: "none"
             },
-            view.name
-          );
-        }),
-        selectedView && /* @__PURE__ */ jsxRuntime.jsx(
-          InfoPanel,
+            children: /* @__PURE__ */ jsxRuntime.jsxs(
+              "div",
+              {
+                style: {
+                  position: "absolute",
+                  inset: 0,
+                  transform: `translate(${pan.x}px, ${pan.y}px) scale(${zoom})`,
+                  transformOrigin: "0 0"
+                },
+                children: [
+                  /* @__PURE__ */ jsxRuntime.jsx(
+                    EventWireOverlay,
+                    {
+                      orbitalViews,
+                      crossLinks,
+                      color,
+                      animated,
+                      containerW,
+                      containerH
+                    }
+                  ),
+                  orbitalViews.map((view) => {
+                    const isHighlighted = view.name === highlightedOrbital;
+                    return /* @__PURE__ */ jsxRuntime.jsx(
+                      Box,
+                      {
+                        role: "button",
+                        tabIndex: 0,
+                        "data-orbital-tile": "true",
+                        onClick: () => handleSelect(view.name),
+                        onKeyDown: (e) => {
+                          if (e.key === "Enter" || e.key === " ") handleSelect(view.name);
+                        },
+                        "aria-label": `Orbital: ${view.name}${isHighlighted ? " (highlighted)" : ""}`,
+                        position: "absolute",
+                        style: {
+                          left: view.cx - UNIT_DISPLAY_W / 2,
+                          top: view.cy - UNIT_DISPLAY_H / 2,
+                          width: UNIT_DISPLAY_W,
+                          height: UNIT_DISPLAY_H,
+                          cursor: "pointer",
+                          transition: "transform 0.2s ease, filter 0.2s ease, box-shadow 0.3s ease",
+                          transform: selected === view.name ? "scale(1.05)" : "scale(1)",
+                          filter: selected && selected !== view.name ? "opacity(0.5)" : "none",
+                          // GAP-52: persistent highlight ring (independent from user selection)
+                          boxShadow: isHighlighted ? `0 0 0 3px ${color}, 0 0 24px 4px ${color}` : "none",
+                          borderRadius: isHighlighted ? "12px" : void 0,
+                          zIndex: isHighlighted ? 11 : selected === view.name ? 10 : 1
+                        },
+                        children: /* @__PURE__ */ jsxRuntime.jsx(
+                          AvlOrbitalUnit,
+                          {
+                            entityName: view.entityName,
+                            fields: view.fieldCount,
+                            persistence: view.persistence,
+                            traits: view.traits,
+                            pages: view.pages,
+                            color,
+                            animated: animated && (selected === view.name || isHighlighted)
+                          }
+                        )
+                      },
+                      view.name
+                    );
+                  }),
+                  selectedView && /* @__PURE__ */ jsxRuntime.jsx(
+                    InfoPanel,
+                    {
+                      view: selectedView,
+                      crossLinks,
+                      color
+                    }
+                  )
+                ]
+              }
+            )
+          }
+        ),
+        /* @__PURE__ */ jsxRuntime.jsxs(
+          Box,
           {
-            view: selectedView,
-            crossLinks,
-            color
+            position: "absolute",
+            style: {
+              top: 12,
+              right: 12,
+              display: "flex",
+              flexDirection: "column",
+              gap: 4,
+              zIndex: 30
+            },
+            children: [
+              /* @__PURE__ */ jsxRuntime.jsx(Button, { variant: "secondary", size: "sm", onClick: zoomIn, title: "Zoom in", action: "COSMIC_ZOOM_IN", children: /* @__PURE__ */ jsxRuntime.jsx(Icon, { name: "plus", size: "sm" }) }),
+              /* @__PURE__ */ jsxRuntime.jsx(Button, { variant: "secondary", size: "sm", onClick: zoomOut, title: "Zoom out", action: "COSMIC_ZOOM_OUT", children: /* @__PURE__ */ jsxRuntime.jsx(Icon, { name: "minus", size: "sm" }) }),
+              /* @__PURE__ */ jsxRuntime.jsx(Button, { variant: "secondary", size: "sm", onClick: resetZoom, title: "Reset", action: "COSMIC_ZOOM_RESET", children: /* @__PURE__ */ jsxRuntime.jsx(Icon, { name: "maximize", size: "sm" }) })
+            ]
           }
         )
       ]

package/dist/avl/index.d.cts

@@ -1211,15 +1211,29 @@ interface FlowCanvasProps {
     }) => void;
     onLevelChange?: (level: ViewLevel, orbital?: string) => void;
     /**
-     * GAP-52: fired when the user double-clicks an orbital while ALREADY at
-     * `level === 'expanded'`. Consumers (e.g. the builder workspace) use this as
-     * the trigger to enter cosmic mode (`AvlOrbitalsCosmicZoom`) for the focused
-     * orbital. This does NOT replace the existing overview→expanded drill —
-     * that path still fires `onLevelChange('expanded', ...)` as before.
-     * The callback runs unconditionally; persona / permission gating is the
+     * GAP-52: fired when the user double-clicks an orbital. Consumers (e.g. the
+     * builder workspace) use this as the trigger to enter cosmic mode
+     * (`AvlOrbitalsCosmicZoom`) for the focused orbital.
+     *
+     * The level at which this fires is controlled by `cosmicEntryLevel` (default
+     * `'expanded'`). At `'expanded'` the existing overview→expanded drill is
+     * preserved — the callback fires only on the second double-click. At
+     * `'overview'` the callback fires on the FIRST double-click and the existing
+     * drill is suppressed for that interaction. `'both'` fires at either level.
+     *
+     * The callback runs unconditionally — persona / permission gating is the
      * consumer's responsibility.
      */
     onOrbitalDoubleClick?: (orbital: string) => void;
+    /**
+     * GAP-53: which level the `onOrbitalDoubleClick` callback fires at.
+     * - `'expanded'` (default, non-breaking) — fires only at L2 expanded; the
+     *   first overview double-click still drills overview→expanded.
+     * - `'overview'` — fires at L1 overview on the FIRST double-click. The
+     *   overview→expanded drill is suppressed when the callback is provided.
+     * - `'both'` — fires at either level.
+     */
+    cosmicEntryLevel?: 'expanded' | 'overview' | 'both';
     initialOrbital?: string;
     /** Start at Level 2 (expanded) when initialOrbital is set. Default: 'overview'. */
     initialLevel?: ViewLevel;
@@ -1385,6 +1399,22 @@ interface AvlOrbitalsCosmicZoomProps {
      * highlighted while the user can still click any other orbital to select it.
      */
     highlightedOrbital?: string;
+    /**
+     * GAP-55: fired when the user clicks an orbital tile. Consumers (e.g. the
+     * builder workspace) use this as the trigger to drill INTO the clicked
+     * orbital — typically by switching back to the canvas tab and opening the
+     * clicked orbital at L2 expanded. Local `selected` toggle (visual highlight +
+     * info panel) still fires regardless of whether the callback is provided.
+     */
+    onOrbitalSelect?: (orbital: string) => void;
+    /**
+     * GAP-54: minimum zoom factor when scroll-wheel zooming. Default 0.4.
+     */
+    minZoom?: number;
+    /**
+     * GAP-54: maximum zoom factor when scroll-wheel zooming. Default 3.
+     */
+    maxZoom?: number;
 }
 declare const AvlOrbitalsCosmicZoom: React__default.FC<AvlOrbitalsCosmicZoomProps>;
 

package/dist/avl/index.js

@@ -19342,13 +19342,13 @@ var MapViewImpl = lazy(async () => {
     shadowSize: [41, 41]
   });
   L.Marker.prototype.options.icon = defaultIcon;
-  const { useEffect: useEffect87, useRef: useRef87, useCallback: useCallback124, useState: useState124 } = React125__default;
+  const { useEffect: useEffect88, useRef: useRef88, useCallback: useCallback124, useState: useState124 } = React125__default;
   const { Typography: Typography2 } = await Promise.resolve().then(() => (init_Typography(), Typography_exports));
   const { useEventBus: useEventBus3 } = await Promise.resolve().then(() => (init_useEventBus(), useEventBus_exports));
   function MapUpdater({ centerLat, centerLng, zoom }) {
     const map = useMap();
-    const prevRef = useRef87({ centerLat, centerLng, zoom });
-    useEffect87(() => {
+    const prevRef = useRef88({ centerLat, centerLng, zoom });
+    useEffect88(() => {
       const prev = prevRef.current;
       if (prev.centerLat !== centerLat || prev.centerLng !== centerLng || prev.zoom !== zoom) {
         map.setView([centerLat, centerLng], zoom);
@@ -19359,7 +19359,7 @@ var MapViewImpl = lazy(async () => {
   }
   function MapClickHandler({ onMapClick }) {
     const map = useMap();
-    useEffect87(() => {
+    useEffect88(() => {
       if (!onMapClick) return;
       const handler = (e) => {
         onMapClick(e.latlng.lat, e.latlng.lng);
@@ -47729,12 +47729,18 @@ var OrbPreviewNodeInner = (props) => {
       el = el.parentElement;
       if (!el || el === contentRef.current) break;
     }
+    const containerNode = {
+      orbitalName: data.orbitalName,
+      traitName: data.traitName,
+      transitionEvent: data.transitionEvent
+    };
     const containerPath = el?.dataset?.patternPath;
     if (!containerPath) {
-      eventBus.emit("UI:PATTERN_INSERT", {
+      eventBus.emit("UI:PATTERN_DROP", {
         parentPath: "root",
         patternType: payload.data.type,
-        index: 0
+        index: 0,
+        containerNode
       });
       return;
     }
@@ -47751,12 +47757,13 @@ var OrbPreviewNodeInner = (props) => {
         break;
       }
     }
-    eventBus.emit("UI:PATTERN_INSERT", {
+    eventBus.emit("UI:PATTERN_DROP", {
       parentPath: containerPath,
       patternType: payload.data.type,
-      index: insertIndex
+      index: insertIndex,
+      containerNode
     });
-  }, [eventBus]);
+  }, [eventBus, data.orbitalName, data.traitName, data.transitionEvent]);
   const handlePreviewDragOver = useCallback((e) => {
     if (!e.dataTransfer.types.includes(ALMADAR_DND_MIME)) return;
     e.preventDefault();
@@ -48667,6 +48674,7 @@ function FlowCanvasInner({
   onNodeClick,
   onLevelChange,
   onOrbitalDoubleClick,
+  cosmicEntryLevel = "expanded",
   initialOrbital,
   initialLevel,
   initialSelectedNode,
@@ -48740,19 +48748,24 @@ function FlowCanvasInner({
     }
     if (level === "overview") {
       const d = node.data;
-      setExpandedOrbital(d.orbitalName ?? node.id);
+      const orbitalName = d.orbitalName ?? node.id;
+      if (onOrbitalDoubleClick && (cosmicEntryLevel === "overview" || cosmicEntryLevel === "both")) {
+        onOrbitalDoubleClick(orbitalName);
+        return;
+      }
+      setExpandedOrbital(orbitalName);
       setLevel("expanded");
-      onLevelChange?.("expanded", d.orbitalName ?? node.id);
+      onLevelChange?.("expanded", orbitalName);
       return;
     }
     if (level === "expanded") {
       const d = node.data;
       const orbitalName = d.orbitalName ?? node.id;
-      if (orbitalName && onOrbitalDoubleClick) {
+      if (orbitalName && onOrbitalDoubleClick && (cosmicEntryLevel === "expanded" || cosmicEntryLevel === "both")) {
         onOrbitalDoubleClick(orbitalName);
       }
     }
-  }, [level, onLevelChange, onOrbitalDoubleClick, atBehaviorLevel, composeLevel]);
+  }, [level, onLevelChange, onOrbitalDoubleClick, cosmicEntryLevel, atBehaviorLevel, composeLevel]);
   const handleNodeClick = useCallback((_, node) => {
     const nodeData = node.data;
     if (level === "expanded") {
@@ -49288,7 +49301,10 @@ var AvlOrbitalsCosmicZoom = ({
   animated = true,
   width = "100%",
   height = 450,
-  highlightedOrbital
+  highlightedOrbital,
+  onOrbitalSelect,
+  minZoom = 0.4,
+  maxZoom = 3
 }) => {
   const parsedSchema = useMemo(() => {
     if (typeof schemaProp === "string") return JSON.parse(schemaProp);
@@ -49319,10 +49335,83 @@ var AvlOrbitalsCosmicZoom = ({
   );
   const [selected, setSelected] = useState(null);
   const handleSelect = useCallback(
-    (name) => setSelected((prev) => prev === name ? null : name),
-    []
+    (name) => {
+      setSelected((prev) => prev === name ? null : name);
+      onOrbitalSelect?.(name);
+    },
+    [onOrbitalSelect]
   );
   const selectedView = orbitalViews.find((o) => o.name === selected);
+  const [zoom, setZoom] = useState(1);
+  const [pan, setPan] = useState({ x: 0, y: 0 });
+  const dragStateRef = useRef(null);
+  const transformWrapperRef = useRef(null);
+  const clampZoom = useCallback(
+    (z) => Math.max(minZoom, Math.min(maxZoom, z)),
+    [minZoom, maxZoom]
+  );
+  const handlePointerDown = useCallback((e) => {
+    if (e.target.closest("[data-orbital-tile]")) return;
+    dragStateRef.current = {
+      startX: e.clientX,
+      startY: e.clientY,
+      panX: pan.x,
+      panY: pan.y
+    };
+    e.target.setPointerCapture(e.pointerId);
+  }, [pan]);
+  const handlePointerMove = useCallback((e) => {
+    const drag = dragStateRef.current;
+    if (!drag) return;
+    setPan({
+      x: drag.panX + (e.clientX - drag.startX),
+      y: drag.panY + (e.clientY - drag.startY)
+    });
+  }, []);
+  const handlePointerUp = useCallback((e) => {
+    if (!dragStateRef.current) return;
+    dragStateRef.current = null;
+    try {
+      e.target.releasePointerCapture(e.pointerId);
+    } catch {
+    }
+  }, []);
+  const panRef = useRef(pan);
+  const zoomRef = useRef(zoom);
+  useEffect(() => {
+    panRef.current = pan;
+  }, [pan]);
+  useEffect(() => {
+    zoomRef.current = zoom;
+  }, [zoom]);
+  useEffect(() => {
+    const wrapper = transformWrapperRef.current;
+    if (!wrapper) return;
+    const wheelListener = (e) => {
+      e.preventDefault();
+      const rect = wrapper.getBoundingClientRect();
+      const cursorX = e.clientX - rect.left;
+      const cursorY = e.clientY - rect.top;
+      const currentZoom = zoomRef.current;
+      const currentPan = panRef.current;
+      const worldX = (cursorX - currentPan.x) / currentZoom;
+      const worldY = (cursorY - currentPan.y) / currentZoom;
+      const delta = e.deltaY > 0 ? -0.1 : 0.1;
+      const nextZoom = clampZoom(currentZoom * (1 + delta));
+      const nextPanX = cursorX - worldX * nextZoom;
+      const nextPanY = cursorY - worldY * nextZoom;
+      setZoom(nextZoom);
+      setPan({ x: nextPanX, y: nextPanY });
+    };
+    wrapper.addEventListener("wheel", wheelListener, { passive: false });
+    return () => wrapper.removeEventListener("wheel", wheelListener);
+  }, [clampZoom]);
+  const zoomIn = useCallback(() => setZoom((z) => clampZoom(z * 1.2)), [clampZoom]);
+  const zoomOut = useCallback(() => setZoom((z) => clampZoom(z / 1.2)), [clampZoom]);
+  const resetZoom = useCallback(() => {
+    setZoom(1);
+    setPan({ x: 0, y: 0 });
+  }, []);
   return /* @__PURE__ */ jsxs(
     Box,
     {
@@ -49332,65 +49421,115 @@ var AvlOrbitalsCosmicZoom = ({
       style: { width, height: containerH },
       children: [
         /* @__PURE__ */ jsx(
-          EventWireOverlay,
+          "div",
           {
-            orbitalViews,
-            crossLinks,
-            color,
-            animated,
-            containerW,
-            containerH
-          }
-        ),
-        orbitalViews.map((view) => {
-          const isHighlighted = view.name === highlightedOrbital;
-          return /* @__PURE__ */ jsx(
-            Box,
-            {
-              role: "button",
-              tabIndex: 0,
-              onClick: () => handleSelect(view.name),
-              onKeyDown: (e) => {
-                if (e.key === "Enter" || e.key === " ") handleSelect(view.name);
-              },
-              "aria-label": `Orbital: ${view.name}${isHighlighted ? " (highlighted)" : ""}`,
+            ref: transformWrapperRef,
+            onPointerDown: handlePointerDown,
+            onPointerMove: handlePointerMove,
+            onPointerUp: handlePointerUp,
+            onPointerCancel: handlePointerUp,
+            style: {
               position: "absolute",
-              style: {
-                left: view.cx - UNIT_DISPLAY_W / 2,
-                top: view.cy - UNIT_DISPLAY_H / 2,
-                width: UNIT_DISPLAY_W,
-                height: UNIT_DISPLAY_H,
-                cursor: "pointer",
-                transition: "transform 0.2s ease, filter 0.2s ease, box-shadow 0.3s ease",
-                transform: selected === view.name ? "scale(1.05)" : "scale(1)",
-                filter: selected && selected !== view.name ? "opacity(0.5)" : "none",
-                // GAP-52: persistent highlight ring (independent from user selection)
-                boxShadow: isHighlighted ? `0 0 0 3px ${color}, 0 0 24px 4px ${color}` : "none",
-                borderRadius: isHighlighted ? "12px" : void 0,
-                zIndex: isHighlighted ? 11 : selected === view.name ? 10 : 1
-              },
-              children: /* @__PURE__ */ jsx(
-                AvlOrbitalUnit,
-                {
-                  entityName: view.entityName,
-                  fields: view.fieldCount,
-                  persistence: view.persistence,
-                  traits: view.traits,
-                  pages: view.pages,
-                  color,
-                  animated: animated && (selected === view.name || isHighlighted)
-                }
-              )
+              inset: 0,
+              overflow: "hidden",
+              cursor: dragStateRef.current ? "grabbing" : "grab",
+              touchAction: "none"
             },
-            view.name
-          );
-        }),
-        selectedView && /* @__PURE__ */ jsx(
-          InfoPanel,
+            children: /* @__PURE__ */ jsxs(
+              "div",
+              {
+                style: {
+                  position: "absolute",
+                  inset: 0,
+                  transform: `translate(${pan.x}px, ${pan.y}px) scale(${zoom})`,
+                  transformOrigin: "0 0"
+                },
+                children: [
+                  /* @__PURE__ */ jsx(
+                    EventWireOverlay,
+                    {
+                      orbitalViews,
+                      crossLinks,
+                      color,
+                      animated,
+                      containerW,
+                      containerH
+                    }
+                  ),
+                  orbitalViews.map((view) => {
+                    const isHighlighted = view.name === highlightedOrbital;
+                    return /* @__PURE__ */ jsx(
+                      Box,
+                      {
+                        role: "button",
+                        tabIndex: 0,
+                        "data-orbital-tile": "true",
+                        onClick: () => handleSelect(view.name),
+                        onKeyDown: (e) => {
+                          if (e.key === "Enter" || e.key === " ") handleSelect(view.name);
+                        },
+                        "aria-label": `Orbital: ${view.name}${isHighlighted ? " (highlighted)" : ""}`,
+                        position: "absolute",
+                        style: {
+                          left: view.cx - UNIT_DISPLAY_W / 2,
+                          top: view.cy - UNIT_DISPLAY_H / 2,
+                          width: UNIT_DISPLAY_W,
+                          height: UNIT_DISPLAY_H,
+                          cursor: "pointer",
+                          transition: "transform 0.2s ease, filter 0.2s ease, box-shadow 0.3s ease",
+                          transform: selected === view.name ? "scale(1.05)" : "scale(1)",
+                          filter: selected && selected !== view.name ? "opacity(0.5)" : "none",
+                          // GAP-52: persistent highlight ring (independent from user selection)
+                          boxShadow: isHighlighted ? `0 0 0 3px ${color}, 0 0 24px 4px ${color}` : "none",
+                          borderRadius: isHighlighted ? "12px" : void 0,
+                          zIndex: isHighlighted ? 11 : selected === view.name ? 10 : 1
+                        },
+                        children: /* @__PURE__ */ jsx(
+                          AvlOrbitalUnit,
+                          {
+                            entityName: view.entityName,
+                            fields: view.fieldCount,
+                            persistence: view.persistence,
+                            traits: view.traits,
+                            pages: view.pages,
+                            color,
+                            animated: animated && (selected === view.name || isHighlighted)
+                          }
+                        )
+                      },
+                      view.name
+                    );
+                  }),
+                  selectedView && /* @__PURE__ */ jsx(
+                    InfoPanel,
+                    {
+                      view: selectedView,
+                      crossLinks,
+                      color
+                    }
+                  )
+                ]
+              }
+            )
+          }
+        ),
+        /* @__PURE__ */ jsxs(
+          Box,
           {
-            view: selectedView,
-            crossLinks,
-            color
+            position: "absolute",
+            style: {
+              top: 12,
+              right: 12,
+              display: "flex",
+              flexDirection: "column",
+              gap: 4,
+              zIndex: 30
+            },
+            children: [
+              /* @__PURE__ */ jsx(Button, { variant: "secondary", size: "sm", onClick: zoomIn, title: "Zoom in", action: "COSMIC_ZOOM_IN", children: /* @__PURE__ */ jsx(Icon, { name: "plus", size: "sm" }) }),
+              /* @__PURE__ */ jsx(Button, { variant: "secondary", size: "sm", onClick: zoomOut, title: "Zoom out", action: "COSMIC_ZOOM_OUT", children: /* @__PURE__ */ jsx(Icon, { name: "minus", size: "sm" }) }),
+              /* @__PURE__ */ jsx(Button, { variant: "secondary", size: "sm", onClick: resetZoom, title: "Reset", action: "COSMIC_ZOOM_RESET", children: /* @__PURE__ */ jsx(Icon, { name: "maximize", size: "sm" }) })
+            ]
           }
         )
       ]

package/dist/components/organisms/avl/AvlOrbitalsCosmicZoom.d.ts

@@ -34,5 +34,21 @@ export interface AvlOrbitalsCosmicZoomProps {
      * highlighted while the user can still click any other orbital to select it.
      */
     highlightedOrbital?: string;
+    /**
+     * GAP-55: fired when the user clicks an orbital tile. Consumers (e.g. the
+     * builder workspace) use this as the trigger to drill INTO the clicked
+     * orbital — typically by switching back to the canvas tab and opening the
+     * clicked orbital at L2 expanded. Local `selected` toggle (visual highlight +
+     * info panel) still fires regardless of whether the callback is provided.
+     */
+    onOrbitalSelect?: (orbital: string) => void;
+    /**
+     * GAP-54: minimum zoom factor when scroll-wheel zooming. Default 0.4.
+     */
+    minZoom?: number;
+    /**
+     * GAP-54: maximum zoom factor when scroll-wheel zooming. Default 3.
+     */
+    maxZoom?: number;
 }
 export declare const AvlOrbitalsCosmicZoom: React.FC<AvlOrbitalsCosmicZoomProps>;

package/dist/components/organisms/avl/FlowCanvas.d.ts

@@ -29,15 +29,29 @@ export interface FlowCanvasProps {
     }) => void;
     onLevelChange?: (level: ViewLevel, orbital?: string) => void;
     /**
-     * GAP-52: fired when the user double-clicks an orbital while ALREADY at
-     * `level === 'expanded'`. Consumers (e.g. the builder workspace) use this as
-     * the trigger to enter cosmic mode (`AvlOrbitalsCosmicZoom`) for the focused
-     * orbital. This does NOT replace the existing overview→expanded drill —
-     * that path still fires `onLevelChange('expanded', ...)` as before.
-     * The callback runs unconditionally; persona / permission gating is the
+     * GAP-52: fired when the user double-clicks an orbital. Consumers (e.g. the
+     * builder workspace) use this as the trigger to enter cosmic mode
+     * (`AvlOrbitalsCosmicZoom`) for the focused orbital.
+     *
+     * The level at which this fires is controlled by `cosmicEntryLevel` (default
+     * `'expanded'`). At `'expanded'` the existing overview→expanded drill is
+     * preserved — the callback fires only on the second double-click. At
+     * `'overview'` the callback fires on the FIRST double-click and the existing
+     * drill is suppressed for that interaction. `'both'` fires at either level.
+     *
+     * The callback runs unconditionally — persona / permission gating is the
      * consumer's responsibility.
      */
     onOrbitalDoubleClick?: (orbital: string) => void;
+    /**
+     * GAP-53: which level the `onOrbitalDoubleClick` callback fires at.
+     * - `'expanded'` (default, non-breaking) — fires only at L2 expanded; the
+     *   first overview double-click still drills overview→expanded.
+     * - `'overview'` — fires at L1 overview on the FIRST double-click. The
+     *   overview→expanded drill is suppressed when the callback is provided.
+     * - `'both'` — fires at either level.
+     */
+    cosmicEntryLevel?: 'expanded' | 'overview' | 'both';
     initialOrbital?: string;
     /** Start at Level 2 (expanded) when initialOrbital is set. Default: 'overview'. */
     initialLevel?: ViewLevel;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/ui",
-  "version": "2.51.0",
+  "version": "2.52.0",
   "description": "React UI components, hooks, and providers for Almadar",
   "type": "module",
   "main": "./dist/components/index.js",