@jbrowse/product-core 4.2.1 → 5.0.0-beta.1

package/esm/RootModel/PreferencesConfig.js

@@ -0,0 +1,61 @@
+import { ConfigurationSchema } from '@jbrowse/core/configuration';
+import { types } from '@jbrowse/mobx-state-tree';
+/**
+ * #config PreferencesConfigSchema
+ * #category root
+ * admin/embedder defaults for user-facing preferences, found on the root config
+ * as `configuration.preferences`. Individual users override these at runtime
+ * (persisted to localStorage) via the session `getPreference` reader; a runtime
+ * override map layered over config defaults, at app scope.
+ */
+export function PreferencesConfigSchemaFactory() {
+    return ConfigurationSchema('Preferences', {
+        /**
+         * #slot configuration.preferences.animationMode
+         * controls feature-layout animations: 'enabled' always animates (the
+         * default), 'system' respects the OS prefers-reduced-motion setting,
+         * 'disabled' never animates
+         */
+        animationMode: {
+            model: types.enumeration('AnimationMode', [
+                'system',
+                'enabled',
+                'disabled',
+            ]),
+            type: 'stringEnum',
+            defaultValue: 'enabled',
+        },
+        /**
+         * #slot configuration.preferences.scrollZoom
+         * when true, scrolling the mouse wheel over a track zooms in and out
+         * without holding Ctrl. Applies globally to all wheel-zoom views.
+         */
+        scrollZoom: {
+            type: 'boolean',
+            defaultValue: false,
+        },
+        /**
+         * #slot configuration.preferences.numberGrouping
+         * when true (the default), numbers are displayed with thousand separators
+         * — `chr1:1,234,567`. Turn it off to render them bare, which is what you
+         * want if you copy coordinates out of JBrowse into tools that won't accept
+         * the commas. Applies to every displayed number, and takes effect on
+         * reload.
+         */
+        numberGrouping: {
+            type: 'boolean',
+            defaultValue: true,
+        },
+        /**
+         * #slot configuration.preferences.useWorkspaces
+         * when true, views open in the tabbed/tiled workspace layout rather than
+         * stacked vertically. Only the default: a session that names
+         * `useWorkspaces` itself (a shared snapshot, or a session spec carrying a
+         * `layout`) still wins, and a user's own toggle overrides it.
+         */
+        useWorkspaces: {
+            type: 'boolean',
+            defaultValue: false,
+        },
+    });
+}

package/esm/RootModel/createConfigModel.d.ts

@@ -0,0 +1,232 @@
+import RpcManager from '@jbrowse/core/rpc/RpcManager';
+import type PluginManager from '@jbrowse/core/PluginManager';
+import type { ConfigurationSnapshot } from '@jbrowse/core/configuration';
+import type { IAnyType } from '@jbrowse/mobx-state-tree';
+declare function rootConfigurationSchema(): import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
+    readonly rpc: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
+        readonly defaultDriver: {
+            readonly type: "string";
+            readonly description: "the RPC driver to run data fetching on: MainThreadRpcDriver or WebWorkerRpcDriver. Leave empty to use the default for this application";
+            readonly defaultValue: "";
+            readonly advanced: true;
+        };
+        readonly workerCount: {
+            readonly type: "number";
+            readonly description: "The number of workers to use. If 0 (the default) JBrowse will decide how many workers to use.";
+            readonly defaultValue: 0;
+            readonly advanced: true;
+        };
+    }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
+    readonly hierarchical: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
+        readonly sort: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
+            readonly trackNames: {
+                readonly type: "boolean";
+                readonly defaultValue: false;
+            };
+            readonly categories: {
+                readonly type: "boolean";
+                readonly defaultValue: false;
+            };
+        }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
+        readonly defaultFolderCategories: {
+            readonly type: "stringArray";
+            readonly description: "list of category names to display as folders by default";
+            readonly defaultValue: readonly [];
+        };
+        readonly defaultCollapsed: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
+            readonly categoryNames: {
+                readonly type: "stringArray";
+                readonly defaultValue: readonly [];
+            };
+            readonly topLevelCategories: {
+                readonly type: "boolean";
+                readonly defaultValue: false;
+            };
+            readonly subCategories: {
+                readonly type: "boolean";
+                readonly defaultValue: false;
+            };
+        }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
+    }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
+    readonly preferences: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
+        readonly animationMode: {
+            readonly model: import("@jbrowse/mobx-state-tree").ISimpleType<"disabled" | "enabled" | "system">;
+            readonly type: "stringEnum";
+            readonly defaultValue: "enabled";
+        };
+        readonly scrollZoom: {
+            readonly type: "boolean";
+            readonly defaultValue: false;
+        };
+        readonly numberGrouping: {
+            readonly type: "boolean";
+            readonly defaultValue: true;
+        };
+        readonly useWorkspaces: {
+            readonly type: "boolean";
+            readonly defaultValue: false;
+        };
+    }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
+    readonly formatDetails: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
+        readonly feature: {
+            readonly type: "frozen";
+            readonly description: "adds extra fields to the feature details";
+            readonly defaultValue: {};
+            readonly contextVariable: ["feature"];
+        };
+        readonly subfeatures: {
+            readonly type: "frozen";
+            readonly description: "adds extra fields to the subfeatures of a feature";
+            readonly defaultValue: {};
+            readonly contextVariable: ["feature"];
+        };
+        readonly depth: {
+            readonly type: "maybeNumber";
+            readonly description: "levels of subfeature the formatDetails.subfeatures callback runs on, default 2";
+        };
+        readonly maxDepth: {
+            readonly type: "maybeNumber";
+            readonly description: "hide subfeatures nested deeper than this, default no limit";
+        };
+    }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
+    readonly formatAbout: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
+        readonly config: {
+            readonly type: "frozen";
+            readonly description: "formats configuration object in about dialog";
+            readonly defaultValue: {};
+            readonly contextVariable: ["config"];
+        };
+        readonly hideUris: {
+            readonly type: "boolean";
+            readonly defaultValue: false;
+        };
+    }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
+    readonly theme: {
+        readonly type: "frozen";
+        readonly defaultValue: {};
+    };
+}, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
+/**
+ * What an embedder may put in `createViewState`'s `configuration` option: every
+ * root slot and sub-schema by name, values unchecked. Derived from the schema
+ * above rather than restated, so a slot added there is spellable here the same
+ * day.
+ */
+export type RootConfigurationSnapshot = ConfigurationSnapshot<ReturnType<typeof rootConfigurationSchema>>;
+export declare function createConfigModel(pluginManager: PluginManager, assemblyConfigSchemasType: IAnyType): import("@jbrowse/mobx-state-tree").IModelType<{
+    configuration: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
+        readonly rpc: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
+            readonly defaultDriver: {
+                readonly type: "string";
+                readonly description: "the RPC driver to run data fetching on: MainThreadRpcDriver or WebWorkerRpcDriver. Leave empty to use the default for this application";
+                readonly defaultValue: "";
+                readonly advanced: true;
+            };
+            readonly workerCount: {
+                readonly type: "number";
+                readonly description: "The number of workers to use. If 0 (the default) JBrowse will decide how many workers to use.";
+                readonly defaultValue: 0;
+                readonly advanced: true;
+            };
+        }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
+        readonly hierarchical: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
+            readonly sort: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
+                readonly trackNames: {
+                    readonly type: "boolean";
+                    readonly defaultValue: false;
+                };
+                readonly categories: {
+                    readonly type: "boolean";
+                    readonly defaultValue: false;
+                };
+            }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
+            readonly defaultFolderCategories: {
+                readonly type: "stringArray";
+                readonly description: "list of category names to display as folders by default";
+                readonly defaultValue: readonly [];
+            };
+            readonly defaultCollapsed: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
+                readonly categoryNames: {
+                    readonly type: "stringArray";
+                    readonly defaultValue: readonly [];
+                };
+                readonly topLevelCategories: {
+                    readonly type: "boolean";
+                    readonly defaultValue: false;
+                };
+                readonly subCategories: {
+                    readonly type: "boolean";
+                    readonly defaultValue: false;
+                };
+            }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
+        }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
+        readonly preferences: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
+            readonly animationMode: {
+                readonly model: import("@jbrowse/mobx-state-tree").ISimpleType<"disabled" | "enabled" | "system">;
+                readonly type: "stringEnum";
+                readonly defaultValue: "enabled";
+            };
+            readonly scrollZoom: {
+                readonly type: "boolean";
+                readonly defaultValue: false;
+            };
+            readonly numberGrouping: {
+                readonly type: "boolean";
+                readonly defaultValue: true;
+            };
+            readonly useWorkspaces: {
+                readonly type: "boolean";
+                readonly defaultValue: false;
+            };
+        }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
+        readonly formatDetails: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
+            readonly feature: {
+                readonly type: "frozen";
+                readonly description: "adds extra fields to the feature details";
+                readonly defaultValue: {};
+                readonly contextVariable: ["feature"];
+            };
+            readonly subfeatures: {
+                readonly type: "frozen";
+                readonly description: "adds extra fields to the subfeatures of a feature";
+                readonly defaultValue: {};
+                readonly contextVariable: ["feature"];
+            };
+            readonly depth: {
+                readonly type: "maybeNumber";
+                readonly description: "levels of subfeature the formatDetails.subfeatures callback runs on, default 2";
+            };
+            readonly maxDepth: {
+                readonly type: "maybeNumber";
+                readonly description: "hide subfeatures nested deeper than this, default no limit";
+            };
+        }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
+        readonly formatAbout: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
+            readonly config: {
+                readonly type: "frozen";
+                readonly description: "formats configuration object in about dialog";
+                readonly defaultValue: {};
+                readonly contextVariable: ["config"];
+            };
+            readonly hideUris: {
+                readonly type: "boolean";
+                readonly defaultValue: false;
+            };
+        }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
+        readonly theme: {
+            readonly type: "frozen";
+            readonly defaultValue: {};
+        };
+    }, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
+    assembly: IAnyType;
+    tracks: import("@jbrowse/mobx-state-tree").IArrayType<IAnyType>;
+    internetAccounts: import("@jbrowse/mobx-state-tree").IArrayType<IAnyType>;
+    connections: import("@jbrowse/mobx-state-tree").IArrayType<IAnyType>;
+    aggregateTextSearchAdapters: import("@jbrowse/mobx-state-tree").IArrayType<IAnyType>;
+    plugins: import("@jbrowse/mobx-state-tree").IType<any, any, any>;
+}, {
+    readonly assemblies: any[];
+    readonly assemblyName: string;
+    readonly rpcManager: RpcManager;
+}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>;
+export {};

package/esm/RootModel/createConfigModel.js

@@ -0,0 +1,56 @@
+import { ConfigurationSchema, FormatAboutConfigSchemaFactory, FormatDetailsConfigSchemaFactory, readConfObject, } from '@jbrowse/core/configuration';
+import RpcManager from '@jbrowse/core/rpc/RpcManager';
+import { expandLooseTrackConfig } from '@jbrowse/core/util/tracks';
+import { getParent, types } from '@jbrowse/mobx-state-tree';
+import { HierarchicalConfigSchemaFactory } from './HierarchicalConfig.js';
+import { PreferencesConfigSchemaFactory } from './PreferencesConfig.js';
+// A function rather than a module constant so it is still built once per
+// createConfigModel call, as it was inline — what the function buys is a name
+// for its type, since `SnapshotIn` of the model erases every slot name (a
+// schema's MST props are assembled as a `Record<string, any>`).
+function rootConfigurationSchema() {
+    return ConfigurationSchema('Root', {
+        rpc: RpcManager.configSchema,
+        hierarchical: HierarchicalConfigSchemaFactory(),
+        preferences: PreferencesConfigSchemaFactory(),
+        formatDetails: FormatDetailsConfigSchemaFactory(),
+        formatAbout: FormatAboutConfigSchemaFactory(),
+        theme: { type: 'frozen', defaultValue: {} },
+    });
+}
+export function createConfigModel(pluginManager, assemblyConfigSchemasType) {
+    return (types
+        .model('Configuration', {
+        configuration: rootConfigurationSchema(),
+        assembly: assemblyConfigSchemasType,
+        tracks: types.array(pluginManager.pluggableConfigSchemaType('track')),
+        internetAccounts: types.array(pluginManager.pluggableConfigSchemaType('internet account')),
+        connections: types.array(pluginManager.pluggableConfigSchemaType('connection')),
+        aggregateTextSearchAdapters: types.array(pluginManager.pluggableConfigSchemaType('text search adapter')),
+        plugins: types.frozen(),
+    })
+        // The one assembly is what every loose `{ trackId, uri }` track is on, so
+        // a snapshot need not repeat its name per track.
+        .preProcessSnapshot((snap) => {
+        const tracks = snap?.tracks;
+        const assemblyName = snap?.assembly
+            ?.name;
+        return Array.isArray(tracks)
+            ? {
+                ...snap,
+                tracks: tracks.map(t => expandLooseTrackConfig(t, pluginManager, assemblyName)),
+            }
+            : snap;
+    })
+        .views(self => ({
+        get assemblies() {
+            return [self.assembly];
+        },
+        get assemblyName() {
+            return readConfObject(self.assembly, 'name');
+        },
+        get rpcManager() {
+            return getParent(self).rpcManager;
+        },
+    })));
+}

package/esm/RootModel/index.d.ts

@@ -1,5 +1,10 @@
-export * from './BaseRootModel.ts';
-export * from './InternetAccounts.ts';
-export * from './FormatAbout.ts';
-export * from './FormatDetails.ts';
-export * from './HierarchicalConfig.ts';
+export { BaseRootModelFactory, isRootModel } from './BaseRootModel.ts';
+export type { BaseRootModel, BaseRootModelType } from './BaseRootModel.ts';
+export { InternetAccountsRootModelMixin } from './InternetAccounts.ts';
+export type { RootModelWithInternetAccounts, RootModelWithInternetAccountsType, } from './InternetAccounts.ts';
+export { FormatAboutConfigSchemaFactory, FormatDetailsConfigSchemaFactory, } from '@jbrowse/core/configuration';
+export { HierarchicalConfigSchemaFactory } from './HierarchicalConfig.ts';
+export { PreferencesConfigSchemaFactory } from './PreferencesConfig.ts';
+export { createConfigModel } from './createConfigModel.ts';
+export type { RootConfigurationSnapshot } from './createConfigModel.ts';
+export { exportSessionMenuItem, importSessionMenuItem, newSessionMenuItem, openConnectionMenuItem, openTrackMenuItem, pluginStoreMenuItem, preferencesMenuItem, redoMenuItem, undoMenuItem, workspacesMenuItem, } from './menuItems.ts';

package/esm/RootModel/index.js

@@ -1,5 +1,10 @@
-export * from "./BaseRootModel.js";
-export * from "./InternetAccounts.js";
-export * from "./FormatAbout.js";
-export * from "./FormatDetails.js";
-export * from "./HierarchicalConfig.js";
+export { BaseRootModelFactory, isRootModel } from './BaseRootModel.js';
+export { InternetAccountsRootModelMixin } from './InternetAccounts.js';
+// re-exported rather than declared here: the same two schemas hang off every
+// track config, so they live in core next to `createBaseTrackConfig` and this
+// keeps the long-published `@jbrowse/product-core` spelling working
+export { FormatAboutConfigSchemaFactory, FormatDetailsConfigSchemaFactory, } from '@jbrowse/core/configuration';
+export { HierarchicalConfigSchemaFactory } from './HierarchicalConfig.js';
+export { PreferencesConfigSchemaFactory } from './PreferencesConfig.js';
+export { createConfigModel } from './createConfigModel.js';
+export { exportSessionMenuItem, importSessionMenuItem, newSessionMenuItem, openConnectionMenuItem, openTrackMenuItem, pluginStoreMenuItem, preferencesMenuItem, redoMenuItem, undoMenuItem, workspacesMenuItem, } from './menuItems.js';

package/esm/RootModel/menuItems.d.ts

@@ -0,0 +1,24 @@
+import type { SessionWithMultipleViews } from '../Session/index.ts';
+import type PluginManager from '@jbrowse/core/PluginManager';
+import type { MenuItem } from '@jbrowse/core/ui';
+import type { DialogComponentType } from '@jbrowse/core/util';
+interface RootWithDefaultSession {
+    setDefaultSession: () => void;
+}
+export declare function newSessionMenuItem(root: RootWithDefaultSession): MenuItem;
+export declare function importSessionMenuItem(): MenuItem;
+export declare function exportSessionMenuItem(): MenuItem;
+export declare function openTrackMenuItem(): MenuItem;
+export declare function openConnectionMenuItem(): MenuItem;
+export declare function pluginStoreMenuItem(): MenuItem;
+export declare function preferencesMenuItem(pluginManager: PluginManager, PreferencesDialog: DialogComponentType): MenuItem;
+interface HistoryManager {
+    canUndo: boolean;
+    canRedo: boolean;
+    undo(): void;
+    redo(): void;
+}
+export declare function undoMenuItem(history: HistoryManager): MenuItem;
+export declare function redoMenuItem(history: HistoryManager): MenuItem;
+export declare function workspacesMenuItem(session: SessionWithMultipleViews | undefined): MenuItem;
+export {};

package/esm/RootModel/menuItems.js

@@ -0,0 +1,143 @@
+import { Cable } from '@jbrowse/core/ui/Icons';
+import AddIcon from '@mui/icons-material/Add';
+import ExtensionIcon from '@mui/icons-material/Extension';
+import GetAppIcon from '@mui/icons-material/GetApp';
+import PublishIcon from '@mui/icons-material/Publish';
+import RedoIcon from '@mui/icons-material/Redo';
+import SettingsIcon from '@mui/icons-material/Settings';
+import SpaceDashboardIcon from '@mui/icons-material/SpaceDashboard';
+import StorageIcon from '@mui/icons-material/Storage';
+import UndoIcon from '@mui/icons-material/Undo';
+import { getShareableSessionSnapshot } from '../Session/index.js';
+// the renderer binds the active session into each onClick (see AppToolbar's
+// wrapMenuItems), so these handlers receive it as their argument
+const MULTI_VIEW_WARNING = 'This will add a track to the first view. Note: if you want to open a track in a specific view open the track selector for that view and use the add track (plus icon) in the bottom right';
+const WORKSPACES_HELP_TEXT = 'Workspaces allow you to organize views into tabs and tiles. There are a variety of unique features, for instance, you can drag views between tabs or split them side-by-side. Try clicking and dragging the tab header to create a new split';
+export function newSessionMenuItem(root) {
+    return {
+        label: 'New session',
+        icon: AddIcon,
+        onClick: () => {
+            root.setDefaultSession();
+        },
+    };
+}
+export function importSessionMenuItem() {
+    return {
+        label: 'Import session...',
+        icon: PublishIcon,
+        onClick: (session) => {
+            session.showWidget(session.addWidget('ImportSessionWidget', 'importSessionWidget'));
+        },
+    };
+}
+export function exportSessionMenuItem() {
+    return {
+        label: 'Export session',
+        icon: GetAppIcon,
+        onClick: async (session) => {
+            const { saveAs } = await import('@jbrowse/core/util/FileSaver');
+            saveAs(new Blob([
+                JSON.stringify({
+                    // an exported file is read by someone who doesn't have this
+                    // browser's promoted display-type defaults, so flatten the
+                    // cascade into it (same rule as ShareDialog)
+                    session: getShareableSessionSnapshot(session),
+                }, null, 2),
+            ], { type: 'text/plain;charset=utf-8' }), 'session.json');
+        },
+    };
+}
+export function openTrackMenuItem() {
+    return {
+        label: 'Open track...',
+        icon: StorageIcon,
+        onClick: (session) => {
+            const firstView = session.views[0];
+            if (!firstView) {
+                session.notify('Please open a view to add a track first');
+            }
+            else {
+                const widget = session.addWidget('AddTrackWidget', 'addTrackWidget', {
+                    view: firstView.id,
+                });
+                session.showWidget(widget);
+                if (session.views.length > 1) {
+                    session.notify(MULTI_VIEW_WARNING);
+                }
+            }
+        },
+    };
+}
+export function openConnectionMenuItem() {
+    return {
+        label: 'Open connection...',
+        icon: Cable,
+        onClick: (session) => {
+            const widget = session.addWidget('AddConnectionWidget', 'addConnectionWidget');
+            session.showWidget(widget);
+        },
+    };
+}
+export function pluginStoreMenuItem() {
+    return {
+        label: 'Plugin store',
+        icon: ExtensionIcon,
+        onClick: (session) => {
+            session.showWidget(session.addWidget('PluginStoreWidget', 'pluginStoreWidget'));
+        },
+    };
+}
+// the dialog component differs per product, so it is passed in rather than
+// imported; typing it as DialogComponentType lets queueDialog accept it with no
+// cast (the inline call sites needed `as BaseSession` to reach queueDialog)
+export function preferencesMenuItem(pluginManager, PreferencesDialog) {
+    return {
+        label: 'Preferences',
+        icon: SettingsIcon,
+        onClick: (session) => {
+            session.queueDialog(handleClose => [
+                PreferencesDialog,
+                { session, pluginManager, handleClose },
+            ]);
+        },
+    };
+}
+export function undoMenuItem(history) {
+    return {
+        label: 'Undo',
+        icon: UndoIcon,
+        onClick: () => {
+            if (history.canUndo) {
+                history.undo();
+            }
+        },
+    };
+}
+export function redoMenuItem(history) {
+    return {
+        label: 'Redo',
+        icon: RedoIcon,
+        onClick: () => {
+            if (history.canRedo) {
+                history.redo();
+            }
+        },
+    };
+}
+export function workspacesMenuItem(session) {
+    return {
+        label: 'Use workspaces',
+        icon: SpaceDashboardIcon,
+        type: 'checkbox',
+        checked: session?.effectiveUseWorkspaces ?? false,
+        helpText: WORKSPACES_HELP_TEXT,
+        // opts out of the checkbox "stay open" default: this re-lays out the whole
+        // app (classic stack <-> tiled workspace), so it's a one-shot mode switch
+        // rather than a setting to flip repeatedly with the menu up
+        keepMenuOpen: false,
+        onClick: () => {
+            session?.setUseWorkspacesPreference(!session.effectiveUseWorkspaces);
+        },
+    };
+}