Allow for multiple Lighter instances

app/packages/core/package.json

@@ -12,6 +12,7 @@
         "@fiftyone/components": "*",
         "@fiftyone/feature-flags": "*",
         "@fiftyone/flashlight": "*",
+        "@fiftyone/lighter": "*",
         "@fiftyone/looker": "*",
         "@fiftyone/map": "*",
         "@fiftyone/operators": "*",

app/packages/core/src/components/Actions/Selected/Modal.tsx

@@ -25,7 +25,7 @@ export default ({
 }: {
   anchorRef: MutableRefObject<HTMLDivElement | null>;
   close: () => void;
-  lookerRef: MutableRefObject<Lookers | undefined>;
+  lookerRef?: MutableRefObject<Lookers | undefined>;
 }) => {
   const selected = useRecoilValue(fos.selectedSamples);
   const clearSelection = useClearSampleSelection(close);
@@ -34,7 +34,7 @@ export default ({
   const isRoot = useRecoilValue(fos.isRootView);
   const isVideo = useRecoilValue(fos.isVideoDataset) && isRoot;
   const visibleFrameLabels =
-    lookerRef.current instanceof VideoLooker
+    lookerRef?.current instanceof VideoLooker
       ? lookerRef.current.getCurrentFrameLabels()
       : new Array<fos.State.SelectedLabel>();
 
@@ -45,7 +45,7 @@ export default ({
       lookerRef.current.pause();
   });
 
-  fos.useEventHandler(lookerRef.current, "play", close);
+  fos.useEventHandler(lookerRef?.current, "play", close);
 
   const closeAndCall = (callback) => {
     return useCallback(() => {

app/packages/core/src/components/Actions/Selected/hooks.ts

@@ -97,12 +97,12 @@ export const useSelectVisible = (
 };
 
 export const useVisibleSampleLabels = (
-  lookerRef: MutableRefObject<Lookers>
+  lookerRef?: MutableRefObject<Lookers | undefined>
 ) => {
   const isGroup = useRecoilValue(fos.isGroup);
   const activeLabels = useRecoilValue(fos.activeLabels({}));
 
-  const currentSampleLabels = lookerRef.current
+  const currentSampleLabels = lookerRef?.current
     ? lookerRef.current.getCurrentSampleLabels()
     : [];
 

app/packages/core/src/components/Actions/Selected/index.tsx

@@ -80,7 +80,7 @@ export default ({
         data-cy="action-manage-selected"
       />
       {open &&
-        (modal && lookerRef?.current ? (
+        (modal ? (
           <Modal
             anchorRef={ref}
             close={() => setOpen(false)}

app/packages/core/src/components/Modal/Actions/index.tsx

@@ -1,6 +1,7 @@
 import { OperatorPlacements, types } from "@fiftyone/operators";
 import * as fos from "@fiftyone/state";
 import DragIndicatorIcon from "@mui/icons-material/DragIndicator";
+import { useAtomValue } from "jotai";
 import React, { useMemo } from "react";
 import Draggable from "react-draggable";
 import { useRecoilValue } from "recoil";
@@ -87,6 +88,7 @@ export default () => {
     0,
     false
   );
+  const isAnnotating = useAtomValue(fos.modalMode) === "annotate";
 
   return (
     <Draggable
@@ -100,10 +102,10 @@ export default () => {
       <Container $isFullScreen={isFullScreen}>
         <DragActionsRow />
         <HiddenLabels modal />
-        <Selected modal lookerRef={activeLookerRef} />
+        {!isAnnotating && <Selected modal lookerRef={activeLookerRef} />}
         <ColorScheme modal />
-        <Similarity modal />
-        <Tag modal lookerRef={activeLookerRef} />
+        {!isAnnotating && <Similarity modal />}
+        {!isAnnotating && <Tag modal lookerRef={activeLookerRef} />}
         <Options modal />
         {isGroup && <GroupVisibility />}
         <BrowseOperations modal />

app/packages/core/src/components/Modal/Lighter/LighterSampleRenderer.tsx

@@ -1,22 +1,25 @@
 /**
  * Copyright 2017-2025, Voxel51, Inc.
  */
+import type { ImageOptions, ImageOverlay, SceneAtom } from "@fiftyone/lighter";
 import {
-  ImageOptions,
-  ImageOverlay,
+  defaultLighterSceneAtom,
   overlayFactory,
   useLighter,
   useLighterSetupWithPixi,
 } from "@fiftyone/lighter";
 import type { Sample } from "@fiftyone/state";
 import * as fos from "@fiftyone/state";
 import { getSampleSrc } from "@fiftyone/state";
+import type { RefObject } from "react";
 import React, { useEffect, useLayoutEffect, useRef, useState } from "react";
 import { useRecoilValue } from "recoil";
-import { singletonCanvas } from "./SharedCanvas";
+import { defaultCanvas } from "./ReusableCanvas";
 import { useBridge } from "./useBridge";
 
 export interface LighterSampleRendererProps {
+  /** Scene atom */
+  atom: SceneAtom;
   /** Custom CSS class name */
   className?: string;
   /** Sample to display */
@@ -27,12 +30,11 @@ export interface LighterSampleRendererProps {
  * Lighter unit sample renderer with PixiJS renderer.
  */
 export const LighterSampleRenderer = ({
+  atom = defaultLighterSceneAtom,
   className = "",
   sample,
 }: LighterSampleRendererProps) => {
   const containerRef = useRef<HTMLDivElement>(null);
-  // unique scene id allows us to destroy/recreate scenes reliably
-  const [sceneId, setSceneId] = useState<string | null>(null);
 
   // we have this hack to force a re-render on layout effect, so that containerRef.current is defined
   // this is to allow stable singleton canvas to bind to new containers
@@ -43,7 +45,7 @@ export const LighterSampleRenderer = ({
   }, []);
 
   // Get access to the lighter instance
-  const { scene, isReady, addOverlay } = useLighter();
+  const { scene, isReady, addOverlay } = useLighter(atom);
 
   // use a ref for the sample data, effects do not run solely because the
   // sample changed
@@ -77,14 +79,6 @@ export const LighterSampleRenderer = ({
     }
   }, [isReady, addOverlay, scene]);
 
-  useEffect(() => {
-    // sceneId should be deterministic, but unique for a given sample snapshot
-    const sample = sampleRef.current;
-    setSceneId(
-      `${sample?.sample?._id}-${sample?.sample?.last_modified_at?.datetime}`
-    );
-  }, []);
-
   return (
     <div
       ref={containerRef}
@@ -98,26 +92,26 @@ export const LighterSampleRenderer = ({
         flexDirection: "column",
       }}
     >
-      {containerRef.current && sceneId && (
-        <LighterSetupImpl containerRef={containerRef} sceneId={sceneId} />
+      {containerRef.current && (
+        <LighterSetupImpl atom={atom} containerRef={containerRef} />
       )}
     </div>
   );
 };
 
 const LighterSetupImpl = (props: {
-  containerRef: React.RefObject<HTMLDivElement>;
-  sceneId: string;
+  atom: SceneAtom;
+  containerRef: RefObject<HTMLDivElement>;
 }) => {
-  const { containerRef, sceneId } = props;
+  const { atom, containerRef } = props;
 
   const options = useRecoilValue(
     fos.lookerOptions({ modal: true, withFilter: false })
   );
 
-  const canvas = singletonCanvas.getCanvas(containerRef.current);
+  const canvas = defaultCanvas.getCanvas(containerRef.current);
 
-  const { scene } = useLighterSetupWithPixi(canvas, options, sceneId);
+  const { scene } = useLighterSetupWithPixi(canvas, options, atom);
 
   // This is the bridge between FiftyOne state management system and Lighter
   useBridge(scene);

app/packages/core/src/components/Modal/Lighter/ReusableCanvas.ts

@@ -0,0 +1,66 @@
+/**
+ * Copyright 2017-2025, Voxel51, Inc.
+ */
+
+/**
+ * A reusable canvas manager that creates and maintains a persistent canvas
+ * element.
+ *
+ * A ReusableCanvas and a SharedPixiApplication allows a single WebGL context
+ * to be maintained across Lighter scenes.
+ */
+class ReusabledCanvas {
+  private canvas: HTMLCanvasElement;
+
+  constructor(id = "default") {
+    this.canvas = document.createElement("canvas");
+    this.canvas.id = `lighter-canvas-${id}`;
+    this.canvas.setAttribute("data-cy", `lighter-sample-renderer-canvas-${id}`);
+    this.canvas.style.display = "block";
+    this.canvas.style.flex = "1";
+  }
+
+  /**
+   * Get the canvas
+   *
+   * If a container is provided, the canvas will be attached to it.
+   */
+  getCanvas(container: null | HTMLElement) {
+    if (!container || container === this.canvas.parentNode) {
+      return this.canvas;
+    }
+
+    this.canvas.remove();
+    container.appendChild(this.canvas);
+
+    return this.canvas;
+  }
+
+  /**
+   * Detach the canvas from its current container.
+   * The canvas element itself is preserved for reuse.
+   */
+  detach() {
+    if (this.isCanvasAttached()) {
+      this.canvas.remove();
+    }
+  }
+
+  /**
+   * Get the current canvas element without attaching to a container.
+   */
+  getCanvasElement() {
+    return this.canvas;
+  }
+
+  /**
+   * Check if the canvas is currently attached to a container.
+   */
+  isCanvasAttached() {
+    return !!this.canvas.parentNode;
+  }
+}
+
+export default ReusabledCanvas;
+
+export const defaultCanvas = new ReusabledCanvas();

app/packages/core/src/components/Modal/ModalLooker.tsx

@@ -29,12 +29,6 @@ export const useClearSelectedLabels = () => {
 
 interface LookerProps {
   sample: fos.ModalSample;
-
-  // note: this is a hack we're using while migrating to lighter
-  // a lot of components depend on lighterRef being defined (see `useVisibleSampleLabels` for example)
-  // we'll remove this once we've migrated to lighter
-  // `ghost` means looker will render but with width and height set to 0
-  ghost?: boolean;
 }
 
 const ModalLookerNoTimeline = React.memo((props: LookerProps) => {
@@ -49,8 +43,8 @@ const ModalLookerNoTimeline = React.memo((props: LookerProps) => {
       id={id}
       data-cy="modal-looker-container"
       style={{
-        width: props.ghost ? 0 : "100%",
-        height: props.ghost ? 0 : "100%",
+        width: "100%",
+        height: "100%",
         background: theme.background.level2,
         position: "relative",
       }}
@@ -91,11 +85,10 @@ export const ModalLooker = React.memo(
     if (
       isNativeMediaType(sample.sample.media_type ?? sample.sample._media_type)
     ) {
-      return (
-        <>
-          {mode === "annotate" && <LighterSampleRenderer sample={sample} />}
-          <ModalLookerNoTimeline sample={sample} ghost={mode === "annotate"} />
-        </>
+      return mode === "annotate" ? (
+        <LighterSampleRenderer sample={sample} />
+      ) : (
+        <ModalLookerNoTimeline sample={sample} />
       );
     }