@foxglove/extension 2.24.0 → 2.25.0

package/src/index.ts

@@ -1,1423 +1,3 @@
-import type { Immutable } from "./immutable";
-
+export * from "./stable";
 export type { Immutable } from "./immutable";
-
-/** Valid types for parameter data (such as rosparams) */
-export type ParameterValue =
-  | undefined
-  | boolean
-  | number
-  | string
-  | Date
-  | Uint8Array
-  | ParameterValue[]
-  | { [key: string]: ParameterValue };
-
-/** Valid types for [variables](https://docs.foxglove.dev/docs/visualization/variables) */
-export type VariableValue =
-  | undefined
-  | boolean
-  | number
-  | string
-  | VariableValue[]
-  | { [key: string]: VariableValue };
-
-export type VariableStruct = { [key: string]: VariableValue };
-
-/** Valid types for application settings */
-export type AppSettingValue = string | number | boolean | undefined;
-
-/**
- * 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 named channel of messages.
- */
-export type Topic = {
-  /**
-   * topic name i.e. "/some/topic"
-   */
-  name: string;
-  /**
-   * @deprecated Renamed to `schemaName`. `datatype` will be removed in a future release.
-   */
-  datatype: string;
-  /**
-   * The schema name is an identifier for the types of messages on this topic. Typically this is the
-   * fully-qualified name of the message schema. The fully-qualified name depends on the data source
-   * and data loaded by the data source.
-   *
-   * i.e. `package.Message` in protobuf-like serialization or `pkg/Msg` in ROS systems.
-   */
-  schemaName: string;
-
-  /**
-   * 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 {@link Subscription.convertTo} option.
-   */
-  convertibleTo?: readonly string[];
-};
-
-/**
- * A single subscription passed to {@link PanelExtensionContext.subscribe}.
- *
- * @category Custom panels
- */
-export type Subscription = {
-  topic: string;
-
-  /**
-   * If a topic has additional schema names, specifying a schema name will convert messages on that
-   * topic to the convertTo schema using a registered message converter. MessageEvents for the
-   * subscription will contain the converted message and an originalMessageEvent field with the
-   * original message event.
-   */
-  convertTo?: string;
-
-  /**
-   * Setting preload to _true_ hints to the data source that it should attempt to load all available
-   * 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 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" */
-  topic: string;
-  /**
-   * The schema name is an identifier for the schema of the message within the message event.
-   */
-  schemaName: string;
-  /**
-   * The time in nanoseconds this message was received. This may be set by the
-   * local system clock or the data source, depending on the data source used
-   * and whether time is simulated via a /clock topic or similar mechanism.
-   * 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.
-   */
-  receiveTime: Time;
-  /**
-   * The time in nanoseconds this message was originally published. This is
-   * only available for some data sources. 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.
-   */
-  publishTime?: Time;
-  /** The deserialized message as a JavaScript object. */
-  message: T;
-  /**
-   * The approximate size of this message event in its deserialized form. This can be
-   * useful for statistics tracking and cache eviction.
-   */
-  sizeInBytes: number;
-
-  /**
-   * When subscribing to a topic using the `convertTo` option, the message event `message`
-   * 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 {
-  /**
-   * 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
-     * new panel will be adjacent to the calling panel.
-     */
-    position: "sibling";
-
-    /**
-     * The type of panel to open. For extension panels, this `"extensionName.panelName"` where
-     * extensionName is the `name` field from the extension's package.json, and panelName is the
-     * name provided to `registerPanel()`.
-     */
-    type: string;
-
-    /**
-     * Whether to update an existing sibling panel of the same type, if it already exists. If false
-     * or omitted, a new panel will always be added.
-     *
-     * @deprecated This parameter is only supported for built-in panels at this time.
-     */
-    updateIfExists?: boolean;
-
-    /**
-     * A function that returns the state for the new panel. If updating an existing panel, the
-     * existing state will be passed in.
-     * @see `updateIfExists`
-     */
-    getState(existingState?: unknown): unknown;
-  }): 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.
-   */
-  currentFrame?: MessageEvent[];
-
-  /**
-   * True if the data source performed a seek. This indicates that some data may have been skipped
-   * (never appeared in the `currentFrame`), so panels should clear out any stale state to avoid
-   * displaying incorrect data.
-   */
-  didSeek?: boolean;
-
-  /**
-   * All available messages. Best-effort list of all available messages.
-   *
-   * @deprecated Please use {@link PanelExtensionContext.subscribeMessageRange} instead.
-   */
-  allFrames?: MessageEvent[];
-
-  /**
-   * Map of current parameter values. Parameters are key/value pairs associated with the data
-   * source, and may not be available for all data sources. For example, ROS 1 live connections
-   * support parameters through the Parameter Server <http://wiki.ros.org/Parameter%20Server>.
-   */
-  parameters?: Map<string, ParameterValue>;
-
-  /**
-   * Transient panel state shared between panels of the same type. This can be any data a
-   * panel author wishes to share between panels.
-   */
-  sharedPanelState?: Record<string, unknown>;
-
-  /**
-   * Map of current Studio variables. Variables are key/value pairs that are globally accessible
-   * to panels and scripts in the current layout. See
-   * <https://docs.foxglove.dev/docs/visualization/variables> for more information.
-   */
-  variables?: Map<string, VariableValue>;
-
-  /**
-   * List of available topics. This list includes subscribed and unsubscribed topics.
-   */
-  topics?: Topic[];
-
-  /**
-   * A timestamp value indicating the current playback time.
-   */
-  currentTime?: Time;
-
-  /**
-   * The start timestamp of the playback range for the current data source. For offline files it
-   * is expected to be present. For live connections, the start time may or may not be present
-   * depending on the data source.
-   */
-  startTime?: Time;
-
-  /**
-   * The end timestamp of the playback range for the current data source. For offline files it
-   * is expected to be present. For live connections, the end time may or may not be present
-   * depending on the data source.
-   */
-  endTime?: Time;
-
-  /**
-   * A seconds value indicating a preview time. The preview time is set when a user hovers
-   * over the seek bar or when a panel sets the preview time explicitly. The preview time
-   * is a seconds value within the playback range.
-   *
-   * i.e. A plot panel may set the preview time when a user is hovering over the plot to signal
-   * to other panels where the user is currently hovering and allow them to render accordingly.
-   */
-  previewTime?: number | undefined;
-
-  /** The color scheme currently in use throughout the app. */
-  colorScheme?: "dark" | "light";
-
-  /** Application settings. This will only contain keys/values that were subscribed to using {@link @PanelExtensionContext.subscribeAppSettings} */
-  appSettings?: Map<string, AppSettingValue>;
-};
-
-/**
- * This type represents the arguments you pass to {@link PanelExtensionContext.subscribeMessageRange}.
- *
- * @category Custom panels
- */
-export type SubscribeMessageRangeArgs = {
-  /**
-   * Topic to be subscribed to.
-   */
-  topic: string;
-  /**
-   * Convert messages to this schema before delivering to the subscriber.
-   *
-   * MessageEvents for the subscription will contain the converted message and an
-   * `originalMessageEvent` field with the original message event. If no `convertTo` schema is
-   * specified, then no message converters will be used. If no message converter exists for
-   * converting the original schema to the `convertTo` schema, then no messages are delivered for
-   * this subscription.
-   */
-  convertTo?: string;
-  /**
-   * `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
-   * of the iterable is a batch of message events for the subscription's topic. These batches and
-   * messages are in _log time_ order. When there are no more messages to read the iterator will
-   * finish.
-   *
-   * ```typescript
-   * async function onNewRangeIterator(batchIterator) {
-   *   for await (const batch of batchIterator) {
-   *     //...
-   *   }
-   * }
-   * ```
-   *
-   * `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 `onNewRangeIterator` is called, you should discard previously received data.
-   *
-   * 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.
-   */
-  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.
-   */
-  readonly panelElement: HTMLDivElement;
-
-  /**
-   * Initial panel state
-   */
-  readonly initialState: unknown;
-
-  /** Actions the panel may perform related to the user's current layout. See {@link LayoutActions} for details. */
-  readonly layout: LayoutActions;
-
-  /**
-   * Identifies the semantics of the data being played back, such as which topics or parameters
-   * are semantically meaningful or normalization conventions to use. This typically maps to a
-   * shorthand identifier for a robotics framework such as "ros1", "ros2", or "ulog". See the MCAP
-   * profiles concept at <https://github.com/foxglove/mcap/blob/main/docs/specification/appendix.md#well-known-profiles>.
-   */
-  readonly dataSourceProfile?: string;
-
-  /**
-   * 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: "allFrames"): void;
-
-  /**
-   * 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
-   *
-   * 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;
-
-  /**
-   * 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;
-
-  /**
-   * 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;
-
-  /**
-   * 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;
-
-  /**
-   * Set the active preview time. Setting the preview time to undefined clears the preview time.
-   */
-  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.
-   *
-   * This property may be `undefined` if the current data source does not support seeking.
-   */
-  seekPlayback?(time: number | Time): void;
-
-  /**
-   * Use `context.subscribe` to indicate the topics your panel wants to receive messages for. The
-   * messages are provided during render in {@link RenderState.currentFrame}.
-   *
-   * @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.
-   *
-   * ```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.
-   */
-  unsubscribeAll(): void;
-
-  /**
-   * 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;
-
-  /**
-   * 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;
-
-  /**
-   * 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
-   */
-  publish?(topic: string, message: unknown): void;
-
-  /**
-   * 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
-   * @returns A promise that resolves when the result is available or rejected with an error
-   */
-  callService?(service: string, request: unknown): Promise<unknown>;
-
-  /**
-   * 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).
-   *
-   * **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;
-
-  /**
-   * 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;
-
-  /**
-   * 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;
-  /**
-   * Subscribe to receive the entire time range of messages for a given topic for the current data source.
-   *
-   * See {@link SubscribeMessageRangeArgs} for more information on behavior.
-   *
-   * 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 {@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.
-   */
-  name: string;
-
-  /**
-   * This function is invoked when your panel is initialized
-   *
-   * @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;
-};
-
-/** @category Topic aliases */
-export type BaseTopic = { name: string; schemaName?: string };
-/** @category Topic aliases */
-export type TopicAlias = { name: string; sourceTopicName: string };
-
-/**
- * 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<{
-    topics: BaseTopic[];
-    globalVariables: Readonly<Record<string, VariableValue>>;
-  }>,
-) => 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 {
-  /**
-   * @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;
-
-  /**
-   * `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).
-   *
-   * 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.
-   *
-   * 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;
-
-  /**
-   * `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 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"
-  | "AutoAwesome"
-  | "Background"
-  | "Camera"
-  | "Cells"
-  | "Check"
-  | "Circle"
-  | "Clear"
-  | "Clock"
-  | "Collapse"
-  | "Cube"
-  | "Delete"
-  | "Expand"
-  | "Flag"
-  | "Folder"
-  | "FolderOpen"
-  | "Grid"
-  | "Hive"
-  | "ImageProjection"
-  | "Map"
-  | "Move"
-  | "MoveDown"
-  | "MoveUp"
-  | "NorthWest"
-  | "Note"
-  | "NoteFilled"
-  | "Points"
-  | "PrecisionManufacturing"
-  | "Radar"
-  | "Settings"
-  | "Shapes"
-  | "Share"
-  | "Star"
-  | "SouthEast"
-  | "Timeline"
-  | "Topic"
-  | "Walk"
-  | "World";
-
-/**
- * A settings tree field specifies the input type and the value of a field
- * in the settings editor.
- *
- * @category Custom panels
- */
-export type SettingsTreeFieldValue =
-  | {
-      input: "autocomplete";
-      value?: string;
-      items: string[];
-
-      /**
-       * Optional placeholder text displayed in the field input when value is undefined
-       */
-      placeholder?: string;
-    }
-  | { input: "boolean"; value?: boolean }
-  | {
-      input: "rgb";
-      value?: string;
-
-      /**
-       * Optional placeholder text displayed in the field input when value is undefined
-       */
-      placeholder?: string;
-
-      /**
-       * Optional field that's true if the clear button should be hidden.
-       */
-      hideClearButton?: boolean;
-    }
-  | {
-      input: "rgba";
-      value?: string;
-
-      /**
-       * Optional placeholder text displayed in the field input when value is undefined
-       */
-      placeholder?: string;
-
-      /**
-       * Optional field that's true if the clear button should be hidden.
-       */
-      hideClearButton?: boolean;
-    }
-  | { input: "gradient"; value?: [string, string] }
-  | {
-      input: "messagepath";
-      value?: string;
-      validTypes?: string[];
-      /** True if the input should allow math modifiers like @abs. */
-      supportsMathModifiers?: boolean;
-    }
-  | {
-      input: "number";
-      value?: number;
-      step?: number;
-      max?: number;
-      min?: number;
-      precision?: number;
-
-      /**
-       * Optional placeholder text displayed in the field input when value is undefined
-       */
-      placeholder?: string;
-    }
-  | {
-      input: "select";
-      value?: number | number[];
-      options: Array<{ label: string; value: undefined | number; disabled?: boolean }>;
-    }
-  | {
-      input: "select";
-      value?: string | string[];
-      options: Array<{ label: string; value: undefined | string; disabled?: boolean }>;
-    }
-  | {
-      input: "string";
-      value?: string;
-
-      /**
-       * Optional placeholder text displayed in the field input when value is undefined
-       */
-      placeholder?: string;
-    }
-  | {
-      input: "toggle";
-      value?: string;
-      options: string[] | Array<{ label: string; value: undefined | string }>;
-    }
-  | {
-      input: "toggle";
-      value?: number;
-      options: number[] | Array<{ label: string; value: undefined | number }>;
-    }
-  | {
-      input: "vec3";
-      value?: [undefined | number, undefined | number, undefined | number];
-      placeholder?: [undefined | string, undefined | string, undefined | string];
-      step?: number;
-      precision?: number;
-      labels?: [string, string, string];
-      max?: number;
-      min?: number;
-    }
-  | {
-      input: "vec2";
-      value?: [undefined | number, undefined | number];
-      placeholder?: [undefined | string, undefined | string];
-      step?: number;
-      precision?: number;
-      labels?: [string, string];
-      max?: number;
-      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.
-   */
-  disabled?: boolean;
-
-  /**
-   * Optional help text to explain the purpose of the field.
-   */
-  help?: string;
-
-  /**
-   * The label displayed alongside the field.
-   */
-  label: string;
-
-  /**
-   * True if the field is readonly.
-   */
-  readonly?: boolean;
-
-  /**
-   * Optional message indicating any error state for the field.
-   */
-  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";
-
-  /**
-   * A unique idenfier for the action.
-   */
-  id: string;
-
-  /**
-   * A descriptive label for the action.
-   */
-  label: string;
-
-  /**
-   * Optional icon to display with the action.
-   */
-  icon?: SettingsIcon;
-
-  /**
-   * Specifies whether the item is rendered as an inline action or as an item in the
-   * context menu. Defaults to "menu" if not specified. Inline items will be rendered
-   * as an icon only if their icon is specified.
-   */
-  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.
-   */
-  actions?: SettingsTreeNodeAction[];
-
-  /**
-   * Other settings tree nodes nested under this node.
-   */
-  children?: SettingsTreeChildren;
-
-  /**
-   * Set to collapsed if the node should be initially collapsed.
-   */
-  defaultExpansionState?: "collapsed" | "expanded";
-
-  /**
-   * Optional message indicating any error state for the node.
-   */
-  error?: string;
-
-  /**
-   * Field inputs attached directly to this node.
-   */
-  fields?: SettingsTreeFields;
-
-  /**
-   * Optional icon to display next to the node label.
-   */
-  icon?: SettingsIcon;
-
-  /**
-   * An optional label shown at the top of this node.
-   */
-  label?: string;
-
-  /**
-   * True if the node label can be edited by the user.
-   */
-  renamable?: boolean;
-
-  /**
-   * Optional sort order to override natural object ordering. All nodes
-   * with a sort order will be rendered before nodes all with no sort order.
-   *
-   * Nodes without an explicit order will be ordered according to ECMA
-   * object ordering rules.
-   *
-   * https://262.ecma-international.org/6.0/#sec-ordinary-object-internal-methods-and-internal-slots-ownpropertykeys
-   */
-  order?: number | string;
-
-  /**
-   * An optional visibility status. If this is not undefined, the node
-   * editor will display a visiblity toggle button and send update actions
-   * to the action handler.
-   **/
-  visible?: boolean;
-
-  /**
-   * Filter Children by visibility status
-   */
-  enableVisibilityFilter?: boolean;
-};
-
-/**
- * Distributes Pick<T, K> across all members of a union, used for extracting structured
- * subtypes.
- */
-type DistributivePick<T, K extends keyof T> = T extends unknown ? Pick<T, K> : never;
-
-/**
- * Represents actions that can be dispatched to source of the SettingsTree to implement
- * edits and updates.
- *
- * @category Custom panels
- */
-export type SettingsTreeAction =
-  | {
-      action: "update";
-      payload: { path: readonly string[] } & DistributivePick<
-        SettingsTreeFieldValue,
-        "input" | "value"
-      >;
-    }
-  | {
-      action: "perform-node-action";
-      payload: { id: string; path: readonly string[] };
-    };
-
-/**
- * @inline
- * @hidden
- */
-export type SettingsTreeNodes = Record<string, undefined | SettingsTreeNode>;
-
-/**
- * A settings tree is a tree of panel settings that can be displayed and edited in
- * the panel settings sidebar.
- *
- * Nodes and fields in the tree can be referred to by a string path, which collects
- * the keys of each node on the path from the root to the child node or field.
- *
- * For example, for the following tree:
- *
- * ```json
- *  root: {
- *    children: {
- *      a: {
- *        children: {
- *          b: {
- *            fields: {
- *              toggleMe: {
- *                label: "Toggle me",
- *                input: "boolean",
- *                value: false,
- *              },
- *            },
- *          },
- *        },
- *      },
- *    },
- *  },
- * ```
- *
- * 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 = {
-  /**
-   * Handler to process all actions on the settings tree initiated by the UI.
-   */
-  actionHandler: (action: SettingsTreeAction) => void;
-
-  /**
-   * True if the settings editor should show the filter control.
-   */
-  enableFilter?: boolean;
-
-  /**
-   * Setting this will have a one-time effect of scrolling the editor to the
-   * node at the path and highlighting it. This is a transient effect so it is
-   * not necessary to subsequently unset this.
-   */
-  focusedPath?: readonly string[];
-
-  /**
-   * The settings tree root nodes. Updates to these will automatically be
-   * reflected in the editor UI.
-   */
-  nodes: SettingsTreeNodes;
-};
+export type { Experimental } from "./experimental";