refactor use node for bg img underlay

Author: avidrucker

src/App.jsx

@@ -64,7 +64,7 @@ import { appStateReducer, initialAppState, ACTION_TYPES } from "./appStateReduce
 import { ZOOM_TO_SELECTION, DEBUG_LOGGING, DEV_MODE, GRAYSCALE_IMAGES, CAMERA_INFO_HIDDEN } from "./config/features.js";
 import { handleLoadFromCdn, setCdnBaseUrl, getCdnBaseUrl } from "./utils/cdnHelpers.js"; // getMapUrlFromQuery, clearQueryParams
 import BgImageModal from "./components/BgImageModal.jsx";
-import BgImageLayer from "./bg/BgImageLayer";
+// import BgImageLayer from "./bg/BgImageLayer";
 import { useBgImageState } from "./bg/useBgImageState";
 // import { loadImageWithFallback } from "./utils/imageLoader.js";
 // import { dataUrlOrBlobToWebpDataUrl } from "./utils/imageUtils.js"
@@ -1124,22 +1124,6 @@ useEffect(() => {
             </div>
         </div>
 
-        {/* Background image underlay */}
-        {bgImage.imageUrl && bgImage.visible && (
-          <BgImageLayer
-            url={bgImage.imageUrl}
-            visible={bgImage.visible}
-            opacity={bgImage.opacity}
-            pan={livePan}              // 🔴 live pan (every frame)
-            zoom={liveZoom}            // 🔴 live zoom (every frame)
-            calibration={ bgCalibration
-              // keep your existing semantics: scale is a percentage
-              // tx: bgImage.x,                  // world offset X (same units as node positions)
-              // ty: bgImage.y,                  // world offset Y
-              // s: (bgImage.scale ?? 100) / 100 // world units per image pixel
-            }
-          />
-        )}
 
         {canEdit && (
           <GraphControls
@@ -1346,6 +1330,14 @@ useEffect(() => {
           showNoteCountOverlay={showNoteCountOverlay}
           notes={memoNotes}
           visited={visited} /* pass visited to drive unseen badges */
+          // Background node integration
+          bgNodeProps={{
+            imageUrl: bgImage?.imageUrl || '',
+            visible: !!bgImage?.visible,
+            opacity: Number.isFinite(bgImage?.opacity) ? bgImage.opacity : 100,
+            calibration: bgCalibration || { tx: 0, ty: 0, s: 1 }
+          }}
+        
         />
 
         {compassVisible && (

src/components/CytoscapeGraph.jsx

@@ -33,6 +33,7 @@ import { setNoteCountsVisible, refreshPositions as refreshOverlayPositions } fro
 import { printDebug, printError, printWarn } from "../utils/debug.js";
 import { TEST_ICON_SVG } from "../constants/testAssets.js";
 import { GRAYSCALE_IMAGES } from "../config/features.js";
+import { ensureBgNode, removeBgNode } from "../graph/bgNodeAdapter.js";
 
 function CytoscapeGraph({
   nodes = [],
@@ -65,7 +66,8 @@ function CytoscapeGraph({
   showNoteCountOverlay = false,
   notes = {},
   visited = { nodes: new Set(), edges: new Set() },
-  onCytoscapeInstanceReady
+  onCytoscapeInstanceReady,
+  bgNodeProps = { imageUrl: '', visible: false, opacity: 100, calibration: { tx: 0, ty: 0, s: 1 } }
 }) {
 
   const containerRef = useRef(null);
@@ -212,6 +214,7 @@ function CytoscapeGraph({
         if (cy._eventCleanup) cy._eventCleanup();
         if (cy._edgeCountCleanup) cy._edgeCountCleanup();
         if (cy._viewportCleanup) cy._viewportCleanup();
+        try { removeBgNode(cy); } catch { /* noop */ }
 
         cy.destroy();
       } catch {
@@ -222,6 +225,34 @@ function CytoscapeGraph({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []); // mount once
 
+  // ------------------- Background image node sync -------------------
+  useEffect(() => {
+    const cy = cyRef.current;
+    if (!cy) return;
+    const { imageUrl, visible, opacity, calibration } = bgNodeProps || {};
+
+    // Create/update or remove the background node
+    ensureBgNode(cy, {
+      imageUrl,
+      visible,
+      opacity,
+      calibration
+    });
+
+    // Nothing special required on cleanup; node is removed when invisible.
+    // Still, if component unmounts while visible, clean it up.
+    return () => {
+      // Only remove on unmount (don’t fight with other effects)
+      if (cy?.destroyed && !cy.destroyed()) {
+        // noop (we remove on visibility false in ensureBgNode)
+      }
+    };
+    // Include a stable calibration dep (stringify small object is fine here)
+  }, [
+    cyRef,
+    bgNodeProps
+  ]);
+
   // ------------------- Re-wire events when handlers/mode change -------------------
   useEffect(() => {
     printDebug(`🔌 [CytoscapeGraph] Event handlers changed, re-wiring events`);
@@ -373,6 +404,7 @@ function CytoscapeGraph({
 
       // Optional: refresh layout on large changes
       if (updatedCount > 0 && majorChange) {
+        
         syncElements(cy, { nodes, edges, mapName, cdnBaseUrl }, { mode });
         try { updateOverlays(cy, notesRef.current, showNoteCountOverlay, visitedRef.current, mode); } catch {
           printWarn('Failed to update edge count node positions after major position-only update');

src/cytoscapeStyles.js

@@ -383,9 +383,32 @@ const badgeRules = [
   ...unseenBadgeRules
 ];
 
+// Background image node - giant locked node that renders behind everything
+const backgroundImageNodeRule = {
+  selector: 'node.background-image-node',
+  style: {
+    'shape': 'rectangle',
+    'background-image': 'data(imageUrl)',
+    'background-fit': 'contain',
+    // Draw ONLY the image; no solid fill behind it
+    'background-opacity': 0,
+    // Keep element fully opaque; control alpha via image
+    'opacity': 1,
+    // Single source of truth for alpha (0..1)
+    'background-image-opacity': 'data(bgAlpha)',
+    'border-width': 0,
+    'label': '',
+    'z-index-compare': 'manual',
+    'z-index': -1, // Below everything
+    'events': 'no', // Not interactive
+    'overlay-opacity': 0 // No selection overlay
+  }
+};
+
 const cytoscapeStyles = [
   { selector: 'node.entry-parent', style: entryParentBase },
   { selector: 'node.entry', style: entryNodeBase },
+  backgroundImageNodeRule,
   ...sizeRules,
   ...colorRules,
   ...parentSelectionRules,