@foxglove/extension 2.22.0 → 2.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foxglove/extension",
-  "version": "2.22.0",
+  "version": "2.24.0",
   "license": "MIT",
   "author": {
     "name": "Foxglove Technologies",

package/src/index.ts

@@ -2,7 +2,7 @@ import type { Immutable } from "./immutable";
 
 export type { Immutable } from "./immutable";
 
-// Valid types for parameter data (such as rosparams)
+/** Valid types for parameter data (such as rosparams) */
 export type ParameterValue =
   | undefined
   | boolean
@@ -13,7 +13,7 @@ export type ParameterValue =
   | ParameterValue[]
   | { [key: string]: ParameterValue };
 
-// Valid types for global variables
+/** Valid types for [variables](https://docs.foxglove.dev/docs/visualization/variables) */
 export type VariableValue =
   | undefined
   | boolean
@@ -24,16 +24,23 @@ export type VariableValue =
 
 export type VariableStruct = { [key: string]: VariableValue };
 
-// Valid types for application settings
+/** Valid types for application settings */
 export type AppSettingValue = string | number | boolean | undefined;
 
-export interface Time {
+/**
+ * A timestamp with nanosecond precision.
+ *
+ * The timestamp is often nanoseconds since the UNIX epoch, but may be
+ * relative to another event such as system boot time or simulation start
+ * time depending on the context.
+ */
+export type Time = {
   sec: number;
   nsec: number;
-}
+};
 
 /**
- * A topic is a namespace for specific types of messages
+ * A Topic is a named channel of messages.
  */
 export type Topic = {
   /**
@@ -56,11 +63,16 @@ export type Topic = {
   /**
    * Lists any additional schema names available for subscribers on the topic. When subscribing to
    * a topic, the panel can request messages be automatically converted from schemaName into one
-   * of the convertibleTo schemas using the convertTo option.
+   * of the convertibleTo schemas using the {@link Subscription.convertTo} option.
    */
   convertibleTo?: readonly string[];
 };
 
+/**
+ * A single subscription passed to {@link PanelExtensionContext.subscribe}.
+ *
+ * @category Custom panels
+ */
 export type Subscription = {
   topic: string;
 
@@ -77,12 +89,16 @@ export type Subscription = {
    * messages for the topic. The default behavior is to only load messages for the current frame.
    *
    * **Only** topics with `preload: true` are available in the `allFrames` render state.
+   *
+   * @deprecated Please use {@link PanelExtensionContext.subscribeMessageRange} instead.
    */
   preload?: boolean;
 };
 
 /**
- * A message event frames message data with the topic and receive time
+ * A MessageEvent represents a single message along with metadata about the message.
+ *
+ * Remember to import MessageEvent from `@foxglove/extension`. This is not the same as the DOM [MessageEvent](https://developer.mozilla.org/en-US/docs/Web/API/MessageEvent) class.
  */
 export type MessageEvent<T = unknown> = {
   /** The topic name this message was received on, i.e. "/some/topic" */
@@ -117,14 +133,39 @@ export type MessageEvent<T = unknown> = {
 
   /**
    * When subscribing to a topic using the `convertTo` option, the message event `message`
-   * contains the converted message and the originalMessageEvent field contains the original
+   * contains the converted message and the `originalMessageEvent` field contains the original
    * un-converted message event.
    */
   originalMessageEvent?: MessageEvent;
 };
 
+/**
+ * Actions the panel may perform related to the user's current layout via {@link PanelExtensionContext.layout | context.layout}.
+ *
+ * @category Custom panels
+ */
 export interface LayoutActions {
-  /** Open a new panel or update an existing panel in the layout.  */
+  /**
+   * Use `context.layout.addPanel` to add a panel adjacent to the current panel in the layout.
+   *
+   * The value of `position` must be set to `"sibling"`.
+   *
+   * The value of `type` can refer to a panel from a custom extension as `extensionname.panelname`,
+   * where `extensionname` is the extension name from `package.json` and `panelname` is the name
+   * provided when the extension registers a panel.
+   *
+   * `getState` is set to a function that returns the state (also known as panel settings) for the
+   * new panel, or return `undefined` to use the new panel's default settings.
+   *
+   * ```ts
+   * // Add new panel
+   * context.layout.addPanel({
+   *   position: "sibling",
+   *   type: "MyExtension.MyPanel",
+   *   getState: () => ({}),
+   * });
+   * ```
+   */
   addPanel(params: {
     /**
      * Where to position the panel. Currently, only "sibling" is supported which indicates the
@@ -156,6 +197,19 @@ export interface LayoutActions {
   }): void;
 }
 
+/**
+ * RenderState is the information passed to your panel's
+ * {@link PanelExtensionContext.onRender | onRender} function.
+ *
+ * To receive updates for a particular part of RenderState, you must first call
+ * {@link PanelExtensionContext.watch | watch} with the field name. For example, call
+ * `watch("currentTime")` to receive updates for `currentTime`.
+ *
+ * If a field is missing from RenderState, either the value has not changed since the last call to
+ * `onRender`, or you did not `watch` the field.
+ *
+ * @category Custom panels
+ */
 export type RenderState = {
   /**
    * The latest messages for the current render frame. These are new messages since the last render frame.
@@ -171,6 +225,8 @@ export type RenderState = {
 
   /**
    * All available messages. Best-effort list of all available messages.
+   *
+   * @deprecated Please use {@link PanelExtensionContext.subscribeMessageRange} instead.
    */
   allFrames?: MessageEvent[];
 
@@ -231,11 +287,16 @@ export type RenderState = {
   /** The color scheme currently in use throughout the app. */
   colorScheme?: "dark" | "light";
 
-  /** Application settings. This will only contain subscribed application setting key/values */
+  /** Application settings. This will only contain keys/values that were subscribed to using {@link @PanelExtensionContext.subscribeAppSettings} */
   appSettings?: Map<string, AppSettingValue>;
 };
 
-type SubscribeMessageRangeArgs = {
+/**
+ * This type represents the arguments you pass to {@link PanelExtensionContext.subscribeMessageRange}.
+ *
+ * @category Custom panels
+ */
+export type SubscribeMessageRangeArgs = {
   /**
    * Topic to be subscribed to.
    */
@@ -251,7 +312,7 @@ type SubscribeMessageRangeArgs = {
    */
   convertTo?: string;
   /**
-   * `onReset` is a function that receives an async iterable when there is message data available on
+   * `onNewRangeIterator` is a function that receives an async iterable when there is message data available on
    * the subscription.
    *
    * To read messages, your function should iterate through the provided async iterable. Each item
@@ -260,25 +321,47 @@ type SubscribeMessageRangeArgs = {
    * finish.
    *
    * ```typescript
-   * async function onReset(batchIterator) {
+   * async function onNewRangeIterator(batchIterator) {
    *   for await (const batch of batchIterator) {
    *     //...
    *   }
    * }
    * ```
    *
-   * `onReset` is called again when the upstream topic data changes. I.E subscribing to a
+   * `onNewRangeIterator` is called again when the upstream topic data changes. I.E subscribing to a
    * user-script output topic and the user script changes, or subscribing to an aliased topic and
    * the alias changes. When topic data changes, the previous iterator will end, and its data is no
-   * longer valid. When `onReset` is called, you should discard previously received data.
+   * longer valid. When `onNewRangeIterator` is called, you should discard previously received data.
    *
-   * If your `onReset` function throws an error, the iterator will end and you will not receive any
-   * more messages until `onReset` is called again. Your error will appear in the problems sidebar
+   * If your `onNewRangeIterator` function throws an error, the iterator will end and you will not receive any
+   * more messages until `onNewRangeIterator` is called again. Your error will appear in the problems sidebar
    * for user visibility.
    */
-  onReset: (batchIterator: AsyncIterable<Immutable<MessageEvent[]>>) => Promise<void>;
+  onNewRangeIterator: (batchIterator: AsyncIterable<Immutable<MessageEvent[]>>) => Promise<void>;
+
+  /**
+   * @deprecated This method has been renamed. Use `onNewRangeIterator`.
+   */
+  onReset?: (batchIterator: AsyncIterable<Immutable<MessageEvent[]>>) => Promise<void>;
 };
 
+/**
+ * The `PanelExtensionContext` exposes properties and methods for writing a custom panel. The
+ * context has methods to subscribe for messages, receive updates, configure your panel's settings,
+ * and render your panel to the UI.
+ *
+ * The {@link ExtensionPanelRegistration.initPanel | initPanel} function used in
+ * {@link ExtensionContext.registerPanel | registerPanel} accepts a {@link PanelExtensionContext}
+ * argument. This argument contains properties and methods for accessing panel data and rendering UI
+ * updates. The `initPanel` function also returns an optional cleanup function to run when the
+ * extension `panelElement` unmounts.
+ *
+ * See the [Creating a custom
+ * panel](https://docs.foxglove.dev/docs/visualization/extensions/guides/create-custom-panel) guide
+ * for more details.
+ *
+ * @category Custom panels
+ */
 export type PanelExtensionContext = {
   /**
    * The root element for the panel. Add your panel elements as children under this element.
@@ -290,7 +373,7 @@ export type PanelExtensionContext = {
    */
   readonly initialState: unknown;
 
-  /** Actions the panel may perform related to the user's current layout. */
+  /** Actions the panel may perform related to the user's current layout. See {@link LayoutActions} for details. */
   readonly layout: LayoutActions;
 
   /**
@@ -304,103 +387,285 @@ export type PanelExtensionContext = {
   /**
    * Subscribe to updates on this field within the render state. Render will only be invoked when
    * this field changes.
+   *
+   * Use `context.watch` to indicate which fields in {@link RenderState} (e.g. `currentFrame`,
+   * `currentTime`, `previewTime`, `parameters`, `topics`) should trigger panel re-renders when
+   * their contained values change.
+   *
+   * ```ts
+   * context.watch("topics");
+   * context.watch("currentFrame");
+   * context.watch("parameters");
+   * context.watch("currentTime");
+   * ```
+   */
+  watch(field: keyof RenderState): void;
+
+  /**
+   * Subscribe to updates on this field within the render state. Render will only be invoked when
+   * this field changes.
+   *
+   * @deprecated Calling `watch` with `allFrames` is deprecated. Use {@link PanelExtensionContext.subscribeMessageRange} instead.
    */
-  watch: (field: keyof RenderState) => void;
+  watch(field: "allFrames"): void;
 
   /**
-   * Save arbitrary object as persisted panel state. This state is persisted for the panel
-   * within a layout.
+   * Use `context.saveState` to save an arbitrary object as persisted panel state (also known as
+   * panel settings) in the current layout. You can view the current panel state using
+   * [Import/export settings](https://docs.foxglove.dev/docs/visualization/panels/introduction#importexport-settings).
+   *
+   * ```ts
+   * context.initialState = undefined; // your panel's initial state
    *
-   * The state value should be JSON serializable.
+   * context.saveState({ myNum: 2, myBool: false, myStr: "abc" });
+   * ```
+   *
+   * @param state The state to save. This value should be JSON serializable.
    */
-  saveState: (state: Partial<unknown>) => void;
+  saveState(state: Partial<unknown>): void;
 
   /**
-   * Set the value of parameter name to value.
+   * Use `context.setParameter` to set a parameter `name` to any valid `value` (i.e. primitives, dates, `Uint8Array`s, and arrays or objects containing these values).
+   *
+   * ```ts
+   * context.setParameter("/param1", "value1");
+   * ```
    *
    * @param name The name of the parameter to set.
    * @param value The new value of the parameter.
    */
-  setParameter: (name: string, value: ParameterValue) => void;
+  setParameter(name: string, value: ParameterValue): void;
 
   /**
    * Set the transient state shared by panels of the same type as the caller of this function.
    * This will not be persisted in the layout.
    */
-  setSharedPanelState: (state: undefined | Record<string, unknown>) => void;
+  setSharedPanelState(state: undefined | Record<string, unknown>): void;
 
   /**
-   * Set the value of variable name to value.
+   * Use `context.setVariable` to set a
+   * [variable](https://docs.foxglove.dev/docs/visualization/variables) `name` to any valid variable
+   * `value`.
+   *
+   * ```ts
+   * context.setVariable("myVar", 55);
+   *
+   * context.onRender = (renderState: RenderState, done) => {
+   *   // Read variable values from the renderState
+   *   const variableValues = renderState.variables;
+   *   const myVarValue = variableValues.myVar;
+   *
+   *   // Call done when you've rendered all the UI for this renderState. If your UI framework delays rendering, call done when rendering has actaully happened.
+   *   done();
+   * };
+   * ```
    *
    * @param name The name of the variable to set.
    * @param value The new value of the variable.
    */
-  setVariable: (name: string, value: VariableValue) => void;
+  setVariable(name: string, value: VariableValue): void;
 
   /**
    * Set the active preview time. Setting the preview time to undefined clears the preview time.
    */
-  setPreviewTime: (time: number | undefined) => void;
+  setPreviewTime(time: number | undefined): void;
 
   /**
    * Seek playback to the given time. Behaves as if the user had clicked the playback bar
    * to seek.
    *
    * Clients can pass a number or alternatively a Time object for greater precision.
-   */
-  seekPlayback?: (time: number | Time) => void;
-
-  /**
-   * Subscribe to an array of topic names.
-   *
-   * Subscribe will update the current subscriptions to the list of topic names. Passing an empty
-   * array will unsubscribe from all topics.
-   *
-   * Calling subscribe with an empty array of topics is analagous to unsubscribeAll.
    *
-   * @deprecated Use `subscribe` with an array of Subscription objects instead.
+   * This property may be `undefined` if the current data source does not support seeking.
    */
-  subscribe(topics: string[]): void;
+  seekPlayback?(time: number | Time): void;
 
   /**
-   * Subscribe to an array of topics with additional options for each subscription.
+   * Use `context.subscribe` to indicate the topics your panel wants to receive messages for. The
+   * messages are provided during render in {@link RenderState.currentFrame}.
    *
-   * Subscribe will update the current subscriptions to the new list of Subscriptions and
+   * @remarks
+   *
+   * This method will update the current subscriptions to the new list of Subscriptions and
    * unsubscribe from any previously subscribed topics no longer in the Subscription list. Passing
    * an empty array will unsubscribe from all topics.
    *
-   * Calling subscribe with an empty array is analagous to unsubscribeAll.
+   * ```ts
+   * context.subscribe([{ topic: "/some/topic" }, { topic: "/another/topic" }]);
+   * ```
+   *
+   * `context.subscribe([])` will unsubscribe from all topics, and is equivalent to
+   * `unsubscribeAll`.
+   *
+   * #### Range loading
+   *
+   * Most panels display data from the current frame; examples of built-in panels that display the
+   * current frame are 3D, Image, and Raw Message, however some panels can display data for multiple
+   * messages or even the entire dataset duration (Plot, Map, State Transitions).
+   *
+   * Subscriptions will provide only the messages for the current frame. If your panel would like to
+   * process all the available messages on a topic, use
+   * {@link @PanelExtensionContext.subscribeMessageRange | subscribeMessageRange} instead.
+   *
+   * > NOTE: Message range loading is done on a best-effort basis. If your range-loaded messages
+   * > exceed available memory limits for the browser or desktop app, then the data may not
+   * > represent the full dataset range. Range loading results in more data transfer and memory use
+   * > and is recommended only for panels which require access to the entire dataset.
+   *
+   * #### Message converters
+   *
+   * Message converters can convert messages from one schema to another – for example, a user might
+   * convert custom GPS message into
+   * [`foxglove.LocationFix`](https://docs.foxglove.dev/docs/visualization/message-schemas/location-fix)
+   * messages for visualization in the [Map
+   * panel](https://docs.foxglove.dev/docs/visualization/panels/map). Users may have one or more
+   * message converters registered.
+   *
+   * If your panel expects messages with specific schema names, you can leverage registered message
+   * converters to convert from one schema to another.
+   *
+   * Specify the `convertTo` option to enable message conversion on a topic. When conversion is
+   * enabled for a subscription, the {@link MessageEvent}s will contain `message` entries with the
+   * converted message rather than the original message on the topic. The original message is
+   * available in the `originalMessageEvent` field in the message event.
+   *
+   * ```ts
+   * context.subscribe([{ topic: "/some/topic", convertTo: "foxglove.LocationFix" }]);
+   * ```
+   *
+   * The {@link Topic.convertibleTo | convertibleTo} field within {@link RenderState.topics} will
+   * contain the names of schemas you can convert this topic into.
    */
   subscribe(subscriptions: Subscription[]): void;
 
+  /**
+   * @deprecated Use `subscribe` with an array of Subscription objects instead.
+   */
+  subscribe(topics: string[]): void;
+
   /**
    * Unsubscribe from all topics.
    *
-   * Note: This is analagous to calling subscribe([]) with an empty array of topics.
+   * Note: This is analagous to calling `subscribe([])` with an empty array of topics.
    */
   unsubscribeAll(): void;
 
   /**
-   * Subscribe to any changes in application settings for an array of setting names.
+   * Subscribe to any changes in application settings for an array of setting keys.
+   *
+   * The keys and their corresponding values are not currently documented and are subject to change.
    */
   subscribeAppSettings(settings: string[]): void;
 
   /**
-   * Indicate intent to publish messages on a specific topic.
+   * Use `context.advertise` to indicate an intent to publish a specific datatype on a topic. A
+   * panel must call `context.advertise` before being able to publish on the topic
+   * (`context.publish`). Options are specific to the data source - some make use of options; others
+   * do not.
+   *
+   * This property may be `undefined` if the current data source does not support publishing.
+   *
+   * ```ts
+   * context.advertise("/my_image_topic", "sensor_msgs/Image");
+   * ```
+   *
+   * `options` are specific to each data source - see documentation below for supported data
+   * sources.
    *
    * @param topic The topic on which the extension will publish messages.
    * @param schemaName The name of the schema that the published messages will conform to.
    * @param options Options passed to the current data source for additional configuration.
+   *
+   * @remarks
+   *
+   * #### [Native (ROS 1)](https://docs.foxglove.dev/docs/connecting-to-data/frameworks/ros1#native)
+   *
+   * | field     | type             | description                                                                                                                                                          |
+   * | --------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+   * | datatypes | `Map<string, T>` | JavaScript map of datatype names and [`MessageDefinition`](https://github.com/foxglove/message-definition/blob/main/src/types.ts#L185) definitions for a given topic |
+   *
+   * Common datatype definitions are available in the `@foxglove/rosmsg-msgs-common` package.
+   *
+   * ```ts
+   * import { ros1 } from "@foxglove/rosmsg-msgs-common";
+   *
+   * context.advertise?.(currentTopic, "sensor_msgs/Joy", {
+   *   datatypes: new Map([
+   *     ["std_msgs/Header", ros1["std_msgs/Header"]],
+   *     ["std_msgs/Float32", ros1["std_msgs/Float32"]],
+   *     ["std_msgs/Int32", ros1["std_msgs/Int32"]],
+   *     ["sensor_msgs/Joy", ros1["sensor_msgs/Joy"]],
+   *   ]),
+   * });
+   * ```
+   *
+   * #### [Foxglove WebSocket](https://docs.foxglove.dev/docs/connecting-to-data/frameworks/custom#foxglove-websocket)
+   *
+   * `options` depend on the server implementation.
+   *
+   * ##### [Foxglove Bridge](https://docs.foxglove.dev/docs/connecting-to-data/ros-foxglove-bridge)
+   *
+   * When using the Foxglove Bridge with ROS data, use `context.dataSourceProfile` to determine the
+   * ROS version.
+   *
+   * For ROS 1 data, pass datatypes the same way you would for a [native ROS 1](#native-ros-1)
+   * connection.
+   *
+   * For ROS 2 data, pass datatypes using the following fields:
+   *
+   * | field     | type             | description                                                                                                                                                          |
+   * | --------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+   * | datatypes | `Map<string, T>` | JavaScript map of datatype names and [`MessageDefinition`](https://github.com/foxglove/message-definition/blob/main/src/types.ts#L185) definitions for a given topic |
+   *
+   * Common datatype definitions are available in the `@foxglove/rosmsg-msgs-common` package.
+   *
+   * ```ts
+   * import { ros2humble as ros2 } from "@foxglove/rosmsg-msgs-common";
+   * // For Galactic and lower, use:
+   * // import { ros2galactic as ros2 } from "@foxglove/rosmsg-msgs-common";
+   * ```
+   *
+   * ```ts
+   * context.advertise?.(currentTopic, "sensor_msgs/Joy", {
+   *   datatypes: new Map([
+   *     ["std_msgs/Header", ros2["std_msgs/Header"]],
+   *     ["std_msgs/Float32", ros2["std_msgs/Float32"]],
+   *     ["std_msgs/Int32", ros2["std_msgs/Int32"]],
+   *     ["sensor_msgs/Joy", ros2["sensor_msgs/Joy"]],
+   *   ]),
+   * });
+   * ```
+   *
+   * #### Rosbridge ([ROS 1](https://docs.foxglove.dev/docs/connecting-to-data/frameworks/ros1#rosbridge), [ROS 2](https://docs.foxglove.dev/docs/connecting-to-data/frameworks/ros2#rosbridge))
+   *
+   * No `options` required. Simply publish a JSON message with fields conforming to the advertised
+   * datatype, and the bridge node will serialize it according to the datatype.
    */
   advertise?(topic: string, schemaName: string, options?: Record<string, unknown>): void;
 
   /**
    * Indicate that you no longer want to advertise on this topic.
+   *
+   * ```ts
+   * context.unadvertise("/my_image_topic");
+   * ```
+   *
+   * This property may be `undefined` if the current data source does not support publishing.
    */
   unadvertise?(topic: string): void;
 
   /**
-   * Publish a message on a given topic. You must first advertise on the topic before publishing.
+   * Use `context.publish` to publish a message on a previously advertised topic. (You must first
+   * call {@link PanelExtensionContext.advertise | advertise} to advertise the topic before
+   * publishing.) If the topic is not advertised or otherwise malformed, the function will throw an
+   * error.
+   *
+   * ```ts
+   * context.advertise("/my_color_topic", "std_msgs/ColorRGBA");
+   * context.publish("/my_color_topic", { r: 0, g: 1, b: 0, a: 1 });
+   * ```
+   *
+   * This property may be `undefined` if the current data source does not support publishing.
    *
    * @param topic The name of the topic to publish the message on
    * @param message The message to publish
@@ -408,7 +673,13 @@ export type PanelExtensionContext = {
   publish?(topic: string, message: unknown): void;
 
   /**
-   * Call a service.
+   * Use `context.callService` to make a service call to the specified `service` with a request payload.
+   *
+   * ```ts
+   * context.callService("my_service", { foo: "bar" });
+   * ```
+   *
+   * This property may be `undefined` if the current data source does not support services.
    *
    * @param service The name of the service to call
    * @param request The request payload for the service call
@@ -417,68 +688,215 @@ export type PanelExtensionContext = {
   callService?(service: string, request: unknown): Promise<unknown>;
 
   /**
-   * Process render events for the panel. Each render event receives a render state and a done callback.
-   * Render events occur frequently (60hz, 30hz, etc).
+   * Set this property to a function during your panel's
+   * {@link ExtensionPanelRegistration.initPanel | initialization}.
+   *
+   * Foxglove will run `context.onRender` whenever your panel needs to re-render during playback.
+   * The function accepts `renderState` and a `done` callback as its arguments. Render events occur
+   * frequently (60hz, 30hz, etc).
    *
-   * The done callback should be called once the panel has rendered the render state.
+   * **Note**: Your `onRender` function **must** call `done` after rendering to indicate that the
+   * panel is ready to render the next set of data. The exact placement of this `done` invocation
+   * will vary between frameworks and different extensions' logic.
+   *
+   * ```ts
+   * context.onRender = (renderState, done) => {
+   *   // Render your UI updates with fields from RenderState
+   *
+   *   // Call done when you've rendered all the UI for this renderState.
+   *   // If your UI framework delays rendering, call done when rendering has actually happened.
+   *   done();
+   * };
+   * ```
    */
   onRender?: (renderState: Immutable<RenderState>, done: () => void) => void;
 
   /**
-   * Updates the panel's settings editor. Call this every time you want to update
-   * the representation of the panel settings in the editor.
+   * Call the `updatePanelSettingsEditor` method on your panel's {@link PanelExtensionContext}
+   * instance to define or update its settings.
+   *
+   * ```ts
+   * const panelSettings: SettingsTree = {
+   *   nodes: { ... },
+   *   actionHandler: (action: SettingsTreeAction) => { ... }
+   * };
+   *
+   * context.updatePanelSettingsEditor(panelSettings);
+   * ```
+   *
+   * The `settings` argument must be a valid {@link SettingsTree} and include 2 mandatory properties
+   * – `nodes` and `actionHandler`:
+   *
+   * - `nodes` - Hierarchical structure where each node can contain input fields, display fields, or
+   *   even other nodes
+   * - `actionHandler` - Function that is invoked when the user interacts with the settings UI;
+   *   contains logic to process the interactions and update the panel or settings tree
+   *
+   * It can also include the following optional properties:
+   *
+   * - `enableFilter` – Whether the settings should show the filter control
+   * - `focusedPath` – Node to scroll to (transient one-time effect)
+   *
+   * The example tree below has a `title` text input field inside a `General` section along with an
+   * `actionHandler` to respond to updates for the `title` field.
+   *
+   * ```ts
+   * const panelSettings: SettingsTree = {
+   *   nodes: {
+   *     general: {
+   *       label: "General",
+   *       fields: {
+   *         title: "{
+   *           label: "Title",
+   *           input: "string",
+   *           // `panelTitle` refers to a value in your extension panel's config
+   *           value: panelTitle,
+   *         },
+   *       },
+   *     },
+   *   },
+   *   actionHandler: (action: SettingsTreeAction) => {
+   *     switch (action.action) {
+   *       case "perform-node-action":
+   *         // Handle user-defined actions for nodes in the settings tree
+   *         break;
+   *       case "update":
+   *         if (action.payload.path[0] === "general" && action.payload.path[1] === "title") {
+   *           // Read action.payload.value for the new panel title value
+   *           panelTitle = action.payload.value;
+   *
+   *           // Update your panel's state accordingly
+   *         }
+   *         break;
+   *     }
+   *   },
+   * }
+   *
+   * context.updatePanelSettingsEditor(panelSettings);
+   * ```
+   *
+   * #### `SettingsTreeAction`
+   *
+   * A {@link SettingsTreeAction} describes how the settings UI should update when a user interacts
+   * with its fields.
+   *
+   * Each `SettingsTreeAction` has a `payload` with a `path` to the settings field to update (e.g.
+   * `["general", "title"]`).
+   *
+   * The `update` action corresponds to a user setting a new value for a field (e.g. "My new
+   * title").
+   *
+   * #### Special node properties
+   *
+   * There are two special {@link SettingsTreeNode} properties, `label` and `visibility`. The value
+   * you specify for `label` will control the label displayed in the settings editor. If you set the
+   * `renamable` node property to `true`, the user can edit the node `label` – you will receive a
+   * `SettingsTreeAction` of `update` with a path ending in `label`.
+   *
+   * In addition, if you specify a boolean value for `visibility` of the node then the settings
+   * editor will provide a button to toggle the visibility of the node and you will receive an
+   * `update` action with `visibility` as the final element in the path.
+   *
+   * For an example of how to use these special properties, check out the [panel settings example
+   * extension](https://github.com/foxglove/create-foxglove-extension/tree/main/examples/panel-settings).
+   *
+   * #### Input types
+   *
+   * In addition to the `string` input type in the example above, the panel API provides a wide
+   * array of types for your extension panel input fields.
+   *
+   * Each input type has different properties that you can configure:
+   *
+   * - `autocomplete`
+   * - `boolean`
+   * - `rgb`
+   * - `rgba`
+   * - `gradient`
+   * - `messagepath`
+   * - `select`
+   * - `string`
+   * - `toggle`
+   * - `vec3`
+   * - `vec2`
    */
   updatePanelSettingsEditor(settings: Immutable<SettingsTree>): void;
 
   /**
-   * Updates the panel's default title. Users can always override the default title by editing it
-   * manually. A value of `undefined` will display the panel's name in the title bar.
+   * Use `context.setDefaultPanelTitle` to override a panel's default title. Users can always
+   * override the default title by editing it manually. If no override or default title is set, the
+   * panel will simply display its type (e.g. "Image").
+   *
+   * ```ts
+   * // Override the default panel title
+   * context.setDefaultPanelTitle(`Plot of ${config.topicName}`);
+   * ```
    */
   setDefaultPanelTitle(defaultTitle: string | undefined): void;
   /**
-   * NOTE: UNSTABLE API SUBJECT TO CHANGE
-   *
    * Subscribe to receive the entire time range of messages for a given topic for the current data source.
    *
-   * See `SubscribeMessageRangeArgs` for more information on behavior.
+   * See {@link SubscribeMessageRangeArgs} for more information on behavior.
    *
-   * Note: This will not read messages for live sources, like foxglove bridge, rosbridge, or ROS1
-   * native. For those messages you will still need to use `context.subscribe()` and
-   * watch("currentFrame").
+   * Note: This will not read messages for live sources, like foxglove_bridge, rosbridge, or ROS 1
+   * native connections. For those messages you will still need to use `context.subscribe()` and
+   * `watch("currentFrame")`.
    *
    * @returns A function that will unsubscribe from the topic, cancel the active async iterator,
-   * and prevent `onReset` from being called again.
+   * and prevent {@link SubscribeMessageRangeArgs.onNewRangeIterator | onNewRangeIterator} from being called again.
+   */
+  subscribeMessageRange?: (args: SubscribeMessageRangeArgs) => () => void;
+
+  /**
+   * @deprecated Renamed to `subscribeMessageRange`. Please use that method instead.
    */
   UNSTABLE_subscribeMessageRange?: (args: SubscribeMessageRangeArgs) => () => void;
 };
 
+/**
+ * This type represents the arguments you pass to {@link ExtensionContext.registerPanel}.
+ *
+ * @category Custom panels
+ */
 export type ExtensionPanelRegistration = {
-  // Unique name of the panel within your extension
-  //
-  // NOTE: Panel names within your extension must be unique. The panel name identifies this panel
-  // within a layout. Changing the panel name will cause layouts using the old name unable to load
-  // your panel.
+  /**
+   * Unique name of the panel within your extension
+   *
+   * NOTE: Panel names within your extension must be unique. The panel name identifies this panel
+   * within a layout. Changing the panel name will cause layouts using the old name unable to load
+   * your panel.
+   */
   name: string;
 
   /**
    * This function is invoked when your panel is initialized
-   * @return: (optional) A function which is called when the panel is removed or replaced. Typically intended for cleanup logic to gracefully teardown your panel.
+   *
+   * @returns (optional) A function which will be called when the panel is removed or replaced.
+   * Perform any cleanup logic here to gracefully tear down your panel.
    */
   initPanel: (context: PanelExtensionContext) => void | (() => void);
 };
 
+/**
+ * This type represents the arguments you pass to {@link ExtensionContext.registerMessageConverter}.
+ *
+ * @category Message converters
+ */
 export type RegisterMessageConverterArgs<Src> = {
   fromSchemaName: string;
   toSchemaName: string;
   converter: (msg: Src, event: Immutable<MessageEvent<Src>>) => unknown;
 };
 
-type BaseTopic = { name: string; schemaName?: string };
-type TopicAlias = { name: string; sourceTopicName: string };
+/** @category Topic aliases */
+export type BaseTopic = { name: string; schemaName?: string };
+/** @category Topic aliases */
+export type TopicAlias = { name: string; sourceTopicName: string };
 
 /**
- * An AliasFunction takes a list of data source topics and variables and outputs
- * a list of aliased topics.
+ * A TopicAliasFunction takes a list of data source topics and variables and outputs
+ * a list of aliased topics. Register this function using {@link ExtensionContext.registerTopicAliases}.
+ *
+ * @category Topic aliases
  */
 export type TopicAliasFunction = (
   args: Immutable<{
@@ -487,41 +905,116 @@ export type TopicAliasFunction = (
   }>,
 ) => TopicAlias[];
 
+/**
+ * The {@link ExtensionModule.activate | activate} function's first argument is an
+ * `ExtensionContext` — this context allows you to extend Foxglove for your custom workflows.
+ *
+ * ```typescript
+ * export function activate(extensionContext: ExtensionContext) {
+ *   // ... call methods on the extensionContext to extend Foxglove
+ * }
+ * ```
+ *
+ * @category Entry point
+ */
 export interface ExtensionContext {
-  /** The current _mode_ of the application. */
+  /**
+   * @deprecated This field is no longer used.
+   * @hidden
+   */
   readonly mode: "production" | "development" | "test";
 
+  /**
+   * `registerPanel` adds a new panel to the Foxglove interface. To register a panel you provide a
+   * `name` and an `initPanel` function.
+   *
+   * The `initPanel` function accepts a {@link PanelExtensionContext} argument, which contains
+   * properties and methods for accessing panel data and rendering UI updates. It also returns an
+   * optional cleanup function to run when the extension `panelElement` unmounts.
+   *
+   * See the [Creating a custom
+   * panel](https://docs.foxglove.dev/docs/visualization/extensions/guides/create-custom-panel)
+   * guide for more details.
+   */
   registerPanel(params: ExtensionPanelRegistration): void;
 
   /**
-   * Register a function to convert messages from one schema to another.
+   * `registerMessageConverter` registers a function to convert messages from one schema to another.
+   *
+   * Message converters allow you to leverage Foxglove's built-in visualization panels by
+   * transforming messages to adhere to Foxglove-supported schemas — for example, you can convert
+   * your custom GPS messages to
+   * [`foxglove.LocationFix`](https://docs.foxglove.dev/docs/visualization/message-schemas/location-fix)
+   * messages for visualization in the [Map
+   * panel](https://docs.foxglove.dev/docs/visualization/panels/map).
    *
-   * A converter function is invoked when a panel subscribes to a topic with the `convertTo` option.
-   * The return value of the converter function is the converted message and is provided to the
-   * panel.
+   * Whenever a panel subscribes to a topic with the
+   * [`convertTo`](https://docs.foxglove.dev/docs/visualization/extensions/api/panel#message-converters)
+   * option, the converter function runs on the original message and outputs the converted message,
+   * which it then provides it to the panel. If the function returns `undefined`, the output is
+   * ignored, and no message is provided to the panel. This is useful if you want to selectively
+   * output converted messages depending on the input messages' contents.
    *
-   * If the converter function invocation returns _undefined_, the output of the converter for that
-   * message is ignored and no message is provided to the panel. This is useful in instances where
-   * you might want to selectively output a converted schema depending on the input message.
+   * See the [Creating a message
+   * converter](https://docs.foxglove.dev/docs/visualization/extensions/guides/create-message-converter)
+   * guide for more details.
+
    */
   registerMessageConverter<Src>(args: RegisterMessageConverterArgs<Src>): void;
 
   /**
-   * Registers a new alias function with the extension context. The function will be
-   * called every time there is a new set of topics and variables and returns an array of
-   * topic aliases.
+   * `registerTopicAliases` registers a function to compute topic aliases. The provided alias
+   * function should accept an argument with two fields – `topics` with the data source's original
+   * topics and `globalVariables` with the current layout's variables – and return a list of aliased
+   * topics.
+   *
+   * Your alias function runs whenever there are changes to the data source topics or variables. Any
+   * aliases it returns are added to the data source topics (replacing any previously returned
+   * aliases) and available for subscribing or use within message paths as if they were real topics.
    */
   registerTopicAliases(aliasFunction: TopicAliasFunction): void;
 }
 
+/**
+ * @inline
+ * @hidden
+ */
 export type ExtensionActivate = (extensionContext: ExtensionContext) => void;
 
-// ExtensionModule describes the interface your extension entry level module must export
-// as its default export
+/**
+ * ExtensionModule describes the interface your extension module must export. This typically corresponds to your `index.ts` file.
+ *
+ * You may use either a `default` export or named export syntax:
+ *
+ * ```typescript
+ * export function activate(context: ExtensionContext) {
+ *   // ... call methods on the extensionContext to extend Foxglove
+ * }
+ * ```
+ *
+ * ```typescript
+ * function activate(context: ExtensionContext) {
+ *   // ... call methods on the extensionContext to extend Foxglove
+ * }
+ * export default { activate };
+ * ```
+ *
+ * @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.
+   */
   activate: ExtensionActivate;
 }
 
+/**
+ * Icons that can be displayed in the settings tree. Most icon names come from the Material Design
+ * icon set, but the exact icons displayed may change in the future.
+ *
+ * @category Custom panels
+ */
 export type SettingsIcon =
   | "Add"
   | "Addchart"
@@ -566,6 +1059,8 @@ export type SettingsIcon =
 /**
  * A settings tree field specifies the input type and the value of a field
  * in the settings editor.
+ *
+ * @category Custom panels
  */
 export type SettingsTreeFieldValue =
   | {
@@ -678,6 +1173,12 @@ export type SettingsTreeFieldValue =
       min?: number;
     };
 
+/**
+ * A settings tree field specifies the input type and the value of a field
+ * in the settings editor.
+ *
+ * @category Custom panels
+ */
 export type SettingsTreeField = SettingsTreeFieldValue & {
   /**
    * True if the field is disabled.
@@ -705,10 +1206,21 @@ export type SettingsTreeField = SettingsTreeFieldValue & {
   error?: string;
 };
 
+/**
+ * @category Custom panels
+ */
 export type SettingsTreeFields = Record<string, undefined | SettingsTreeField>;
 
+/**
+ * @category Custom panels
+ */
 export type SettingsTreeChildren = Record<string, undefined | SettingsTreeNode>;
 
+/**
+ * An action included in the action menu for a settings node.
+ *
+ * @category Custom panels
+ */
 export type SettingsTreeNodeActionItem = {
   type: "action";
 
@@ -735,13 +1247,23 @@ export type SettingsTreeNodeActionItem = {
   display?: "menu" | "inline";
 };
 
+/**
+ * @category Custom panels
+ */
 export type SettingsTreeNodeActionDivider = { type: "divider" };
 
 /**
  * An action included in the action menu for a settings node.
+ *
+ * @category Custom panels
  */
 export type SettingsTreeNodeAction = SettingsTreeNodeActionItem | SettingsTreeNodeActionDivider;
 
+/**
+ * A node represents a single item or group of items in the settings tree.
+ *
+ * @category Custom panels
+ */
 export type SettingsTreeNode = {
   /**
    * An array of actions that can be performed on this node.
@@ -816,6 +1338,8 @@ type DistributivePick<T, K extends keyof T> = T extends unknown ? Pick<T, K> : n
 /**
  * Represents actions that can be dispatched to source of the SettingsTree to implement
  * edits and updates.
+ *
+ * @category Custom panels
  */
 export type SettingsTreeAction =
   | {
@@ -830,6 +1354,10 @@ export type SettingsTreeAction =
       payload: { id: string; path: readonly string[] };
     };
 
+/**
+ * @inline
+ * @hidden
+ */
 export type SettingsTreeNodes = Record<string, undefined | SettingsTreeNode>;
 
 /**
@@ -841,6 +1369,7 @@ export type SettingsTreeNodes = Record<string, undefined | SettingsTreeNode>;
  *
  * For example, for the following tree:
  *
+ * ```json
  *  root: {
  *    children: {
  *      a: {
@@ -858,12 +1387,15 @@ export type SettingsTreeNodes = Record<string, undefined | SettingsTreeNode>;
  *      },
  *    },
  *  },
+ * ```
  *
- * the path to the node at b would be ["a", "b"] and the path to the toggleMe
- * field would be ["a", "b", "toggleMe"]. These paths are used in the
+ * the path to the node at b would be `["a", "b"]` and the path to the toggleMe
+ * field would be `["a", "b", "toggleMe"]`. These paths are used in the
  * actionHandler, which responds to updates to values in the tree, and also in
  * the focusedPath, which is used to focus the editor UI at a particular node
  * in the tree.
+ *
+ * @category Custom panels
  */
 export type SettingsTree = {
   /**