@foxglove/extension 2.45.0 → 2.47.0

package/package.json

@@ -1,13 +1,18 @@
 {
   "name": "@foxglove/extension",
-  "version": "2.45.0",
+  "version": "2.47.0",
   "license": "MIT",
   "author": {
     "name": "Foxglove Technologies",
     "email": "support@foxglove.dev"
   },
   "homepage": "https://foxglove.dev/",
+  "type": "module",
   "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./experimental": "./src/experimental.ts"
+  },
   "files": [
     "src"
   ],
@@ -15,7 +20,7 @@
     "prepack": "tsc -b tsconfig.json"
   },
   "devDependencies": {
-    "@foxglove/tsconfig": "3.1.0",
+    "@foxglove/tsconfig": "3.2.0",
     "typescript": "5.9.3"
   }
 }

package/src/experimental.ts

@@ -1,14 +1,9 @@
 /* eslint-disable @typescript-eslint/no-namespace */
-import type { Immutable } from "./immutable";
+import type { Immutable } from "./immutable.ts";
 import type {
   ExtensionContext as BaseExtensionContext,
-  MessageEvent,
   PanelExtensionContext as BasePanelExtensionContext,
-  SettingsTreeAction,
-  SettingsTreeFields,
-  SettingsTreeNode,
-  Topic,
-} from "./stable";
+} from "./stable.ts";
 
 /**
  * The experimental namespace contains experimental APIs that are not yet stable and WILL change or
@@ -119,7 +114,7 @@ export namespace Experimental {
    */
   export type VideoFrameDecoder = Pick<
     VideoDecoder,
-    "close" | "configure" | "decode" | "reset" | "state"
+    "close" | "configure" | "decode" | "reset" | "state" | "decodeQueueSize" | "ondequeue"
   >;
 
   /**
@@ -140,13 +135,6 @@ export namespace Experimental {
      */
     registerDataLoader(args: RegisterDataLoaderArgs): void;
 
-    /**
-     * Register a panel overlay extension to create 2D HTML overlays for 3D and Image panels
-     *
-     * See: {@link PanelOverlayExtensionArgs}
-     */
-    registerPanelOverlay(args: PanelOverlayExtensionArgs): void;
-
     /**
      * `registerPanel` adds a new panel to the Foxglove interface. To register a panel you provide a
      * `name` and an `initPanel` function.
@@ -210,11 +198,15 @@ export namespace Experimental {
     /**
      * This function will be called when your extension is loaded. In this function, you can register
      * your custom panels or other types of extension features.
+     *
+     * The function may return a Promise if async initialization is needed before registering
+     * extension features. The extension will not be considered fully activated until the Promise
+     * resolves.
      */
     activate: ExtensionActivate;
   }
 
-  export type ExtensionActivate = (extensionContext: ExtensionContext) => void;
+  export type ExtensionActivate = (extensionContext: ExtensionContext) => void | Promise<void>;
 
   /**
    * A button in the panel toolbar.
@@ -277,98 +269,6 @@ export namespace Experimental {
    */
   export type PanelToolbarItem = PanelToolbarButton | PanelToolbarLink | PanelToolbarDivider;
 
-  export type PanelOverlayExtensionBaseConfig = { visible: boolean };
-
-  export type PanelOverlaySubscription<T = unknown> = {
-    /**
-     * This method will only be run against Topics with schemas that match the topic or schema of the overarching subscription.
-     * So if you always want to receive messages from a topic with a given name or schema you can simply return true.
-     * These subscriptions will only be active when the custom layer extension's visibility is true.
-     */
-    shouldSubscribe?: (topic: string, schema: string) => boolean;
-    /** Callback that will be fired for each matching incoming message */
-    handler: (messageEvent: MessageEvent<T>) => void;
-    /** Queue of messages to be handled since last frame. Will be reassigned to new empty array each frame. */
-    queue?: MessageEvent<T>[] | undefined;
-    /** Optional callback to be called on `queue` to filter. Returns new queue. */
-    filterQueue?: (queue: ReadonlyArray<MessageEvent<T>>) => ReadonlyArray<MessageEvent<T>>;
-  };
-
-  export type AnyPanelOverlaySubscription = Immutable<
-    | {
-        type: "schema";
-        schemaNames: Set<string>;
-        // any is used here to allow storing heterogeneous arrays of subscriptions
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        subscription: PanelOverlaySubscription<any>;
-      }
-    | {
-        type: "topic";
-        topicName: string;
-        // any is used here to allow storing heterogeneous arrays of subscriptions
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        subscription: PanelOverlaySubscription<any>;
-      }
-  >;
-
-  export type ActionHandler = (action: SettingsTreeAction) => void;
-
-  export type SettingsTreeNodeWithActionHandler = SettingsTreeNode & { handler?: ActionHandler };
-
-  export type SettingsPath = ReadonlyArray<string>;
-
-  export type SettingsTreeEntry = { path: SettingsPath; node: SettingsTreeNodeWithActionHandler };
-
-  export interface PanelOverlayExtensionContext<
-    Config extends PanelOverlayExtensionBaseConfig = PanelOverlayExtensionBaseConfig,
-  > {
-    /** Get the current config object for the panel overlay. */
-    getConfig: () => PanelOverlayExtensionBaseConfig & Partial<Config>;
-    /** Update the config object for the panel overlay.
-     * The draft object is meant to be mutated and set to the desired state.
-     */
-    updateConfig: (updateHandler: (draft: Partial<Config>) => void) => void;
-    /** Get all available topics that can be subscribed to. */
-    getTopics: () => readonly Topic[];
-    /** Queue an animation frame. This will call the extension's `startFrame` when the next animation frame is ready.*/
-    queueAnimationFrame: () => void;
-    /** The container element where the panel overlay will be rendered.
-     * The extension is meant to either use this as a react root element, or append elements and update them manually.
-     */
-    overlayContainerElement: HTMLElement;
-  }
-  export interface PanelOverlayExtension {
-    /** The unique identifier for the panel overlay. */
-    readonly id: string;
-    /** The label to display in the settings panel for the panel overlay. */
-    readonly label?: string;
-    getSubscriptions: () => AnyPanelOverlaySubscription[];
-    /** Callback that will be fired when the available topics change.
-     * To get the new state of topics call `getTopics`.
-     */
-    onTopicsChanged: () => void;
-    /** Called when there is a user-driven settings change from the settings panel.  */
-    handleSettingsAction: (action: SettingsTreeAction) => void;
-    /** Used to specify the desired fields in the panel overlay's section of the settings tree */
-    settingsNodeFields: () => SettingsTreeFields;
-    /** Will be called when there is a seek on the playback bar or sometimes when subscriptions change. */
-    onSeek: () => void;
-    /** Will be called every time the panel canvas is re-rendered by an animation frame. */
-    startFrame: () => void;
-    /** Will be called when the 3D Renderer is disposed because of a parameter change or the panel is unmounted. */
-    dispose: () => void;
-  }
-
-  export type PanelOverlayExtensionArgs<
-    Config extends PanelOverlayExtensionBaseConfig = PanelOverlayExtensionBaseConfig,
-  > = {
-    /** The unique identifier for the panel overlay - should match the id of the PanelOverlay */
-    id: string;
-    /** Specifies the default config for the panel overlay. */
-    defaultConfig: Config;
-    init: (context: PanelOverlayExtensionContext) => PanelOverlayExtension;
-  };
-
   export interface PanelExtensionContext extends BasePanelExtensionContext {
     /**
      * Set the items in the panel toolbar.

package/src/index.ts

@@ -1,3 +1,3 @@
-export * from "./stable";
-export type { Immutable } from "./immutable";
-export type { Experimental } from "./experimental";
+export * from "./stable.ts";
+export type { Immutable } from "./immutable.ts";
+export type { Experimental } from "./experimental.ts";

package/src/stable.ts

@@ -1,4 +1,4 @@
-import type { Immutable } from "./immutable";
+import type { Immutable } from "./immutable.ts";
 
 /** Valid types for parameter data (such as rosparams) */
 export type ParameterValue =
@@ -1214,7 +1214,7 @@ export interface ExtensionContext {
  * @inline
  * @hidden
  */
-export type ExtensionActivate = (extensionContext: ExtensionContext) => void;
+export type ExtensionActivate = (extensionContext: ExtensionContext) => void | Promise<void>;
 
 /**
  * ExtensionModule describes the interface your extension module must export. This typically corresponds to your `index.ts` file.
@@ -1234,12 +1234,29 @@ export type ExtensionActivate = (extensionContext: ExtensionContext) => void;
  * export default { activate };
  * ```
  *
+ * The `activate` function can also return a Promise to perform async initialization before
+ * registering panels or converters:
+ *
+ * ```typescript
+ * export async function activate(context: ExtensionContext) {
+ *   // Initialize WASM or other async resources
+ *   await initializeWasm();
+ *
+ *   // Now register panels/converters that depend on the initialized resources
+ *   context.registerPanel({ ... });
+ * }
+ * ```
+ *
  * @category Entry point
  */
 export interface ExtensionModule {
   /**
    * This function will be called when your extension is loaded. In this function, you can register
    * your custom panels or other types of extension features.
+   *
+   * The function may return a Promise if async initialization is needed before registering
+   * extension features. The extension will not be considered fully activated until the Promise
+   * resolves.
    */
   activate: ExtensionActivate;
 }
@@ -1344,7 +1361,12 @@ export type SettingsTreeFieldValue =
       validTypes?: string[];
       /** Only include paths from these topics in autocomplete suggestions */
       validTopics?: string[];
-      /** True if the input should allow math modifiers like "@abs" */
+      /** True if the input should allow message path functions like "@abs" */
+      supportsMessagePathFunctions?: boolean;
+      /**
+       * @deprecated Use `supportsMessagePathFunctions` instead.
+       * True if the input should allow message path functions like "@abs".
+       */
       supportsMathModifiers?: boolean;
     }
   | {