@jbrowse/core 5.0.0-beta.1 → 5.0.0-beta.3

package/esm/ReExports/workerNamespaceNames.js

@@ -0,0 +1,281 @@
+import { DATA_GRID_NAMES } from './MuiDataGridReExports.js';
+import { MUI_COMPONENT_NAMES } from './muiComponentNames.js';
+// Own-key names of each namespace-shaped UI module the RPC worker stubs.
+// workerModules.test.ts pins them to modules.ts; agent-docs/reference/EAGER_BUNDLE.md
+export const REACT_DOM_NAMES = [
+    '__DOM_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE',
+    'createPortal',
+    'default',
+    'flushSync',
+    'preconnect',
+    'prefetchDNS',
+    'preinit',
+    'preinitModule',
+    'preload',
+    'preloadModule',
+    'requestFormReset',
+    'unstable_batchedUpdates',
+    'useFormState',
+    'useFormStatus',
+    'version',
+];
+export const REACT_DOM_CLIENT_NAMES = [
+    'createRoot',
+    'default',
+    'hydrateRoot',
+    'version',
+];
+export const MOBX_REACT_NAMES = [
+    'Observer',
+    '_observerFinalizationRegistry',
+    'clearTimers',
+    'enableStaticRendering',
+    'isUsingStaticRendering',
+    'observer',
+    'useLocalObservable',
+];
+export const MUI_UTILS_NAMES = [
+    'capitalize',
+    'createChainedFunction',
+    'createSvgIcon',
+    'debounce',
+    'deprecatedPropType',
+    'getActiveElement',
+    'isMuiElement',
+    'mergeSlotProps',
+    'ownerDocument',
+    'ownerWindow',
+    'requirePropFactory',
+    'setRef',
+    'unstable_ClassNameGenerator',
+    'unstable_memoTheme',
+    'unstable_useEnhancedEffect',
+    'unstable_useId',
+    'unsupportedProp',
+    'useControlled',
+    'useEventCallback',
+    'useForkRef',
+];
+export const MUI_STYLES_NAMES = [
+    'CssVarsProvider',
+    'Experimental_CssVarsProvider',
+    'StyledEngineProvider',
+    'THEME_ID',
+    'ThemeProvider',
+    'adaptV4Theme',
+    'alpha',
+    'createColorScheme',
+    'createStyles',
+    'createTheme',
+    'css',
+    'darken',
+    'decomposeColor',
+    'duration',
+    'easing',
+    'emphasize',
+    'enhanceHighContrast',
+    'experimental_sx',
+    'extendTheme',
+    'getContrastRatio',
+    'getInitColorSchemeScript',
+    'getLuminance',
+    'getOverlayAlpha',
+    'hexToRgb',
+    'hslToRgb',
+    'keyframes',
+    'makeStyles',
+    'private_createTypography',
+    'private_excludeVariablesFromRoot',
+    'recomposeColor',
+    'responsiveFontSizes',
+    'rgbToHex',
+    'shouldSkipGeneratingVar',
+    'styled',
+    'unstable_createBreakpoints',
+    'unstable_createMuiStrictModeTheme',
+    'unstable_getUnit',
+    'unstable_toUnitless',
+    'useColorScheme',
+    'useTheme',
+    'useThemeProps',
+    'withStyles',
+    'withTheme',
+];
+export const TSS_REACT_NAMES = ['cx', 'keyframes', 'makeStyles'];
+export const MATERIAL_UI_LAB_NAMES = [
+    'Alert',
+    'Autocomplete',
+    'ToggleButton',
+    'ToggleButtonGroup',
+];
+export const MUI_MATERIAL_NAMES = [
+    ...MUI_COMPONENT_NAMES,
+    'alpha',
+    'createTheme',
+    'useTheme',
+];
+export const MATERIAL_UI_CORE_NAMES = [
+    ...MUI_COMPONENT_NAMES,
+    'alpha',
+    'makeStyles',
+    'useTheme',
+];
+export const CORE_UI_NAMES = [
+    'ActionLink',
+    'AssemblySelector',
+    'BaseExportSvgDialog',
+    'BaseTooltip',
+    'CONTEXT_MENU_Z_INDEX',
+    'CascadingMenu',
+    'CascadingMenuButton',
+    'ConfirmDialog',
+    'ContextMenu',
+    'CopyToClipboardButton',
+    'Crosshairs',
+    'Dialog',
+    'EditableTypography',
+    'ErrorBanner',
+    'ErrorBar',
+    'ErrorMessage',
+    'ErrorOverlay',
+    'ExportSvgDialog',
+    'ExternalLink',
+    'FatalErrorDialog',
+    'FileDropZone',
+    'FileSelector',
+    'GRADIENT_LEGEND_HEIGHT',
+    'GRADIENT_LEGEND_SVG_AREA_WIDTH',
+    'GRADIENT_LEGEND_WIDTH',
+    'GpuFallbackButton',
+    'INLINE_MENU_ROW_WIDTH',
+    'InfoDialog',
+    'JexlFilterDialog',
+    'LAUNCH_LABEL',
+    'LEGEND_ROW_HEIGHT',
+    'LEGEND_SWATCH',
+    'LabeledCheckbox',
+    'LegendSwatchGlyph',
+    'LoadingEllipses',
+    'LoadingOverlay',
+    'LoadingProgress',
+    'LogoFull',
+    'Logomark',
+    'MAX_LEGEND_ITEMS',
+    'Menu',
+    'MonospaceTextField',
+    'NumberTextField',
+    'PinAdornment',
+    'PluggableComponent',
+    'PluggableComponents',
+    'PluggableElements',
+    'PrerenderedCanvas',
+    'ProgressChip',
+    'RefNameAutocomplete',
+    'RefNameAutocompleteEndAdornment',
+    'ReplaceCurrentViewButton',
+    'ResetToDefaultButton',
+    'ResizeHandle',
+    'SanitizedHTML',
+    'ScrollChrome',
+    'ScrollEdgeShadow',
+    'SettingsChangesTable',
+    'ShareLinkField',
+    'SingleSlider',
+    'SliderTooltip',
+    'StatusProgressBar',
+    'SubmitDialog',
+    'SubmitForm',
+    'SvgColorLegend',
+    'SvgGradientLegend',
+    'TOOLTIP_Z_INDEX',
+    'TagTextField',
+    'VIEW_HEADER_HEIGHT',
+    'VerticalScrollbar',
+    'ViewLoadingScreen',
+    'addExtensionElement',
+    'adornmentReservePx',
+    'checkboxItem',
+    'colorFwdStrand',
+    'colorInterchrom',
+    'colorLongInsert',
+    'colorLongreadInv',
+    'colorNeutralRead',
+    'colorPairLL',
+    'colorPairLR',
+    'colorPairLRDark',
+    'colorPairRL',
+    'colorPairRR',
+    'colorRevStrand',
+    'colorShortInsert',
+    'colorSplitReadInversion',
+    'colorSupplementary',
+    'colorUnmappedMate',
+    'colorUnmappedMateDark',
+    'createJBrowseBaseTheme',
+    'createJBrowseTheme',
+    'createJBrowseThemeFromArgs',
+    'defaultThemes',
+    'displayTypesWithPromotableSlots',
+    'getInputWidth',
+    'hoverBoxStyle',
+    'launchTargetsMenuItem',
+    'legendEntries',
+    'legendIsReadable',
+    'legendSwatches',
+    'makePromotableSizeMenu',
+    'makeSizeMenu',
+    'makeSizeSubMenu',
+    'matchesTrackSelector',
+    'measureLegendText',
+    'methylated5hmC',
+    'methylated5mC',
+    'misKindedPins',
+    'nonEmptyLegendSections',
+    'promotableSlotsWithoutPin',
+    'pushIntoSubMenu',
+    'pushLaunchViewMenuItem',
+    'radioItems',
+    'replaceViewAction',
+    'resolveSubMenu',
+    'sliderScale',
+    'staysOpenOnClick',
+    'tagColorPalette',
+    'unmethylated5mC',
+    'useAssemblySelection',
+    'useCopyToClipboard',
+    'useExportSvgPreference',
+    'useMouseState',
+    'useMouseTracking',
+    'useRecentLocations',
+    'wrapComponent',
+];
+const BASE_FEATURE_DETAIL_NAMES = [
+    'Attributes',
+    'BaseAttributes',
+    'BaseCard',
+    'BaseCoreDetails',
+    'FeatureDetails',
+    'FeatureWash',
+];
+export const WORKER_NAMESPACE_NAMES = {
+    'react-dom': REACT_DOM_NAMES,
+    'react-dom/client': REACT_DOM_CLIENT_NAMES,
+    'mobx-react': MOBX_REACT_NAMES,
+    '@mui/material/utils': MUI_UTILS_NAMES,
+    '@material-ui/core/utils': MUI_UTILS_NAMES,
+    'tss-react': TSS_REACT_NAMES,
+    'tss-react/mui': TSS_REACT_NAMES,
+    '@mui/material': MUI_MATERIAL_NAMES,
+    '@material-ui/core': MATERIAL_UI_CORE_NAMES,
+    '@mui/material/styles': MUI_STYLES_NAMES,
+    '@material-ui/core/styles': MUI_STYLES_NAMES,
+    '@material-ui/lab': MATERIAL_UI_LAB_NAMES,
+    '@mui/x-data-grid': DATA_GRID_NAMES,
+    '@jbrowse/core/ui': CORE_UI_NAMES,
+    // @mui/icons-material is NOT re-exported, so a plugin that wants an icon
+    // bundles icons-material, which reads `createSvgIcon` off this module. The
+    // main thread serves it (modules.ts) and the worker has to as well, or the
+    // plugin throws at module scope building its icons.
+    '@mui/material/SvgIcon': ['createSvgIcon'],
+    '@jbrowse/core/BaseFeatureWidget/BaseFeatureDetail': BASE_FEATURE_DETAIL_NAMES,
+};

package/esm/configuration/configurationSchema.d.ts

@@ -85,46 +85,13 @@ export declare function ConfigurationSchema<const DEFINITION extends Configurati
  * it as the plain object it is.
  *
  * Shares `TrackConfigurationReference`'s per-PluginManager cache, so hydrating
- * the same entry twice returns the same node and a track that gets opened later
- * reuses it.
+ * the same entry twice returns the same node — and in admin/embedded sessions a
+ * track opened later resolves to that same node. A non-admin's open track does
+ * not: it resolves to the session's private working copy (ADR-032) and this is
+ * the pristine mirror beside it. The two agree in content, which is what the
+ * caller needs; `CopyConfigEntryPoints.test.ts` pins both halves.
  */
 export declare function hydrateTrackConfig(pluginManager: PluginManager, config: Record<string, unknown>): AnyConfigurationModel | undefined;
-/**
- * Reference to a track configuration. Snapshot output is the trackId string.
- *
- * One load-bearing complication: **`types.union(trackRef, schemaType)` accepts a
- * string id OR a full config.** A view that synthesizes a track nobody else can
- * draw — a read-vs-ref synteny band, an SV inspector row, a circular view's
- * added track — writes the config here rather than registering it in
- * `session.tracks`, and it then lives and dies with the track that holds it.
- * `ReadVsRef.test.tsx` and `SVInspector.test.tsx` are the canaries.
- *
- * NOTE: don't add `as SCHEMATYPE` to the return value. It narrows SnapshotIn
- * to just the object branch, forcing callers to wrap string ids in
- * `@ts-expect-error`. The inferred union SnapshotIn is `string | SnapshotIn<schema>`.
- */
-export declare function TrackConfigurationReference(schemaType: IAnyType): import("@jbrowse/mobx-state-tree").ITypeUnion<any, any, any>;
-/**
- * Reference to a display configuration. Looked up inside the containing track
- * config's `displays` array. Snapshot output is the displayId string.
- *
- * Resolution order:
- *   1. by displayId
- *   2. by `parent.type` — handles old sessions where the saved displayId
- *      no longer matches but a display of the same type exists on the track
- *
- * Step 2 is the safety net because `baseTrackConfig.preProcessSnapshot`
- * already injects a stub display for every registered displayType on the
- * track, so a same-type lookup always succeeds at runtime for properly
- * loaded tracks. An older third step auto-created a *detached* config when
- * neither matched — that produced an orphaned MST node whose edits silently
- * didn't persist. Removed in favor of a clear throw, since
- * preProcessSnapshot's injection makes the path effectively dead.
- *
- * Union-with-schemaType branch is for the same reason as `TrackConfigurationReference`:
- * `CircularView.addTrackConf` passes inline display configs as MST instances.
- */
-export declare function DisplayConfigurationReference(schemaType: IAnyType): import("@jbrowse/mobx-state-tree").ITypeUnion<any, any, any>;
 type ConfigReferenceInstance<SCHEMA extends AnyConfigurationSchemaType> = (SCHEMA extends ConfigurationSchemaType<infer D, any> ? IsAny<D> extends true ? any : SCHEMA['Type'] : SCHEMA['Type']) & {
     [K in GetInheritedIdentifier<SCHEMA>]: string;
 };

package/esm/configuration/configurationSchema.js

@@ -198,6 +198,17 @@ function makeConfigurationSchemaModel(modelName, schemaDefinition, options) {
                         .sort()
                         .join(', ')}`);
             }
+            // MST skips its own type check in a production build, and a value the
+            // slot's union cannot take is then dropped with no throw: the write
+            // reported success and the slot kept its old value. `is` still runs
+            // there, so the guard holds in both builds.
+            if (!modelDefinition[slotName].is(value)) {
+                const declared = schemaDefinition[slotName];
+                const slotType = isSlotDefinitionEntry(declared)
+                    ? declared.type
+                    : 'value';
+                throw new Error(`${modelName}.${slotName} is a ${slotType} slot and cannot take ${JSON.stringify(value)}`);
+            }
             self[slotName] = value;
         },
     }));
@@ -239,34 +250,14 @@ export function ConfigurationSchema(modelName, inputSchemaDefinition, inputOptio
     const { schemaDefinition, options } = preprocessConfigurationSchemaArguments(modelName, inputSchemaDefinition, inputOptions);
     return makeConfigurationSchemaModel(modelName, schemaDefinition, options);
 }
-// The hydration cache lives on the PluginManager instance (see
-// trackConfigHydrationCache's doc comment there and ADR-031), not as a
-// module-level singleton: it must never hand a track resolved on one
-// PluginManager instance a node built with another instance's env, and
-// scoping it to the instance rules that out structurally rather than by
-// convention. Nested a second level by schemaType, since one PluginManager
-// registers a distinct schemaType per track type.
-function frozenTrackHydrationCache(pluginManager, schemaType) {
-    const byType = pluginManager.trackConfigHydrationCache;
-    let cache = byType.get(schemaType);
-    if (!cache) {
-        cache = new WeakMap();
-        byType.set(schemaType, cache);
-    }
-    return cache;
-}
 // The frozen -> live half of TrackConfigurationReference's `get`, shared with
-// hydrateTrackConfig below so there is one hydration and one cache rather than
-// two that can drift on which env or which key they use.
+// hydrateTrackConfig below so there is one hydration rather than two that can
+// drift on which env they build with. The memo it goes through belongs to the
+// PluginManager instance (ADR-031): a node built with one instance's env must
+// never be handed to another, and `pluginManager.hydratedTrackConfig` scopes
+// that structurally rather than by convention.
 function hydrateInto(pluginManager, schemaType, frozen) {
-    const cache = frozenTrackHydrationCache(pluginManager, schemaType);
-    const cached = cache.get(frozen);
-    if (cached) {
-        return cached;
-    }
-    const model = schemaType.create(frozen, { pluginManager });
-    cache.set(frozen, model);
-    return model;
+    return pluginManager.hydratedTrackConfig(schemaType, frozen, () => schemaType.create(frozen, { pluginManager }));
 }
 /**
  * #api core/configuration
@@ -290,8 +281,11 @@ function hydrateInto(pluginManager, schemaType, frozen) {
  * it as the plain object it is.
  *
  * Shares `TrackConfigurationReference`'s per-PluginManager cache, so hydrating
- * the same entry twice returns the same node and a track that gets opened later
- * reuses it.
+ * the same entry twice returns the same node — and in admin/embedded sessions a
+ * track opened later resolves to that same node. A non-admin's open track does
+ * not: it resolves to the session's private working copy (ADR-032) and this is
+ * the pristine mirror beside it. The two agree in content, which is what the
+ * caller needs; `CopyConfigEntryPoints.test.ts` pins both halves.
  */
 export function hydrateTrackConfig(pluginManager, config) {
     const type = config.type;
@@ -315,7 +309,18 @@ export function hydrateTrackConfig(pluginManager, config) {
 // config snapshot (held as a standalone schema instance). Both reference kinds
 // resolve to `schemaType` instances, so MST can't auto-dispatch on the instance
 // side — the explicit snapshot dispatcher (string → ref, object → schema)
-// disambiguates. Shared by TrackConfigurationReference/DisplayConfigurationReference.
+// disambiguates. Shared by TrackConfigurationReference/DisplayConfigurationReference,
+// and by neither accident nor oversight NOT by the plain branch — see the note
+// on it in `ConfigurationReference`.
+//
+// One consequence, because both refs' `set` callbacks read as if it were not
+// true: assigning a config **node** here does not store a reference to it. The
+// dispatcher sees a non-string and picks `schemaType`, so MST tries to adopt the
+// node as an inline child — which throws if it already has a parent. `set` is
+// therefore unreachable on both refs (checked by making it throw: 231 suites
+// stayed green), and exists only because MST rejects a custom reference
+// declaring `get` without it. The plain branch, with no dispatcher, does the
+// opposite and stores the reference.
 function idOrSnapshotUnion(ref, schemaType) {
     return types.union({
         dispatcher: snapshot => (typeof snapshot === 'string' ? ref : schemaType),
@@ -335,7 +340,7 @@ function idOrSnapshotUnion(ref, schemaType) {
  * to just the object branch, forcing callers to wrap string ids in
  * `@ts-expect-error`. The inferred union SnapshotIn is `string | SnapshotIn<schema>`.
  */
-export function TrackConfigurationReference(schemaType) {
+function TrackConfigurationReference(schemaType) {
     const trackRef = types.reference(schemaType, {
         get(id, parent) {
             const session = getSession(parent);
@@ -381,15 +386,26 @@ export function TrackConfigurationReference(schemaType) {
  * Step 2 is the safety net because `baseTrackConfig.preProcessSnapshot`
  * already injects a stub display for every registered displayType on the
  * track, so a same-type lookup always succeeds at runtime for properly
- * loaded tracks. An older third step auto-created a *detached* config when
- * neither matched — that produced an orphaned MST node whose edits silently
- * didn't persist. Removed in favor of a clear throw, since
- * preProcessSnapshot's injection makes the path effectively dead.
+ * loaded tracks. It is what carries a **renamed display type** across for a
+ * catalog track: the injected stub is named for the new type, the display
+ * model's own `preProcessSnapshot` rewrites the state model's, and the saved
+ * `configuration` id still spells the old name, so only the type match
+ * reconnects them. Not every pre-rename session reaches it — a track config
+ * that itself declares the old display entry keeps that entry's `displayId`
+ * through the alias rewrite (`{ ...d, type: canonical }`) and wins the
+ * first-wins dedupe, so its session resolves by id. An older third step
+ * auto-created a *detached* config when neither matched — that produced an
+ * orphaned MST node whose edits silently didn't persist. Removed in favor of a
+ * clear throw.
  *
- * Union-with-schemaType branch is for the same reason as `TrackConfigurationReference`:
- * `CircularView.addTrackConf` passes inline display configs as MST instances.
+ * The union's schemaType branch is symmetry with `TrackConfigurationReference`
+ * rather than a path anything in tree takes: the two production writers,
+ * `showTrackGeneric` and `BaseTrackModel.replaceDisplay`, both write a
+ * displayId string, because a display config belongs in its track config's
+ * `displays` array. It stays because it costs nothing and because dropping it
+ * narrows `SnapshotIn` for every caller.
  */
-export function DisplayConfigurationReference(schemaType) {
+function DisplayConfigurationReference(schemaType) {
     const displayRef = types.reference(schemaType, {
         get(id, parent) {
             // track.configuration is a hydrated MST node (hydrated lazily via
@@ -443,9 +459,17 @@ export function ConfigurationReference(schemaType) {
         ? TrackConfigurationReference(schemaType)
         : id === 'displayId'
             ? DisplayConfigurationReference(schemaType)
-            : // Plain (non-track/display) ref. The union accepts either an id
-                // string (resolved via `types.reference`) or an inline schema
-                // snapshot (held as a standalone schema instance).
+            : // Plain (non-track/display) ref — internet accounts, connections —
+                // resolved by MST's own identifier lookup rather than through the
+                // session. **Deliberately not `idOrSnapshotUnion`**, even though it is
+                // the same two members: this branch is also handed a *live, in-tree*
+                // config node (`initializeInternetAccount` pushes
+                // `jbrowse.internetAccounts[i]` straight through), and an undispatched
+                // union sends that to the reference member because
+                // `BaseReferenceType.isAssignableFrom` defers to its target type. A
+                // `typeof snapshot === 'string'` dispatcher sends it to the schema
+                // member instead, and MST refuses to adopt a node that already has a
+                // parent. `InternetAccounts.test.ts` is the canary.
                 types.union(types.reference(schemaType), schemaType);
     return ref;
 }

package/esm/configuration/index.d.ts

@@ -15,5 +15,5 @@ export { toCallbackValue, toFixedValue } from './configurationSlot.ts';
 export { getSlotDefinition, isConfigurationSlot, makeSlotFacade, preProcessSlotValues, slotChoices, } from './slotFacade.ts';
 export type { SlotFacade } from './slotFacade.ts';
 export type { ResolvableDisplay } from './promotableResolve.ts';
-export { clearPromotedDefaults, getDisplayTypeDefaultChanges, isSlotCustomized, makePin, getConfigSnapshotWithPromotables, getTrackConfigWithPromotables, } from './promotableDefaults.ts';
-export type { Pin, ResolvedConfigSnapshot, TrackConfigWithPromotables, } from './promotableDefaults.ts';
+export { clearPromotedDefaults, getDisplayTypeDefaultChanges, isSlotCustomized, makePin, makeTogglePin, getConfigSnapshotWithPromotables, getTrackConfigWithPromotables, } from './promotableDefaults.ts';
+export type { Pin, ResolvedConfigSnapshot, TogglePin, TrackConfigWithPromotables, ValuePin, } from './promotableDefaults.ts';

package/esm/configuration/index.js

@@ -16,4 +16,4 @@ export { tabixIndexFields } from './tabixIndexFields.js';
 export { evaluateJexl, isCallbackValue } from './slotValueUtils.js';
 export { toCallbackValue, toFixedValue } from './configurationSlot.js';
 export { getSlotDefinition, isConfigurationSlot, makeSlotFacade, preProcessSlotValues, slotChoices, } from './slotFacade.js';
-export { clearPromotedDefaults, getDisplayTypeDefaultChanges, isSlotCustomized, makePin, getConfigSnapshotWithPromotables, getTrackConfigWithPromotables, } from './promotableDefaults.js';
+export { clearPromotedDefaults, getDisplayTypeDefaultChanges, isSlotCustomized, makePin, makeTogglePin, getConfigSnapshotWithPromotables, getTrackConfigWithPromotables, } from './promotableDefaults.js';

package/esm/configuration/promotableDefaults.d.ts

@@ -1,8 +1,8 @@
 import type { TrackConfigChange } from '../util/trackConfigDelta.ts';
-import type { Pin } from './promotablePin.ts';
+import type { TogglePin, ValuePin } from './promotablePin.ts';
 import type { PromotedDefaultStore, ResolvableDisplay } from './promotableResolve.ts';
 import type { AnyConfigurationModel, ConfigurationSchemaForModel, ConfigurationSlotName, ConfigurationSlotValueResolved } from './types.ts';
-export type { Pin } from './promotablePin.ts';
+export type { Pin, TogglePin, ValuePin } from './promotablePin.ts';
 /**
  * #api core/configuration
  * Whether this track has customized the slot (holds a non-default value of its
@@ -11,10 +11,10 @@ export type { Pin } from './promotablePin.ts';
  * base instead reads as at-default for a track merely *following* a non-base
  * promoted default, so the reset control lights up on a no-op.
  *
- * `SLOT` is constrained the way `getConf`'s is. A pin or a reset over a slot
- * name the schema does not declare is inert and silent — `resolveSlot` answers
- * about nothing, so the control draws outline forever — and a widened `self`
- * switches the check off (`HostChecksSlotNames`).
+ * `SLOT` is constrained the way `getConf`'s is, and a widened `self` switches
+ * the check off (`HostChecksSlotNames`). A slot name the schema does not
+ * declare throws at the first read (`getSlotDefinition`), and a declared but
+ * non-promotable one throws in `resolveSlotIn`.
  */
 export declare function isSlotCustomized<CONFMODEL extends AnyConfigurationModel, SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>>>(self: ResolvableDisplay<CONFMODEL>, slot: SLOT): boolean;
 declare const promotablesResolved: unique symbol;
@@ -149,20 +149,22 @@ export declare function isPromotableDefault(self: ResolvableDisplay, slot: strin
 export declare function applySlotToOpenTracks(displays: ResolvableDisplay[], slot: string, value: unknown): void;
 /**
  * #api core/configuration
- * The pin for one promotable slot: "apply this value to every open track of this
- * display type", and — via the snackbar it raises — "keep it as the default for
- * the ones opened later".
+ * The pin on a radio or slider row: "apply this value to every open track of
+ * this display type", and — via the snackbar it raises — "keep it as the
+ * default for the ones opened later".
  *
  * `value` chooses between the subsystem's two meanings, which are otherwise
  * identical:
  *
- * - **Give it** for a per-value pin — "make *arcs* the default" — independent of
- *   what the track currently shows. Use on an always-visible pin so it can never
- *   promote a meaningless value, and so two rows sharing one slot (arcs `'arc'`
- *   vs read cloud `'cloud'`; sashimi `'down'` vs `'auto'`) stay independent.
+ * - **Give it** for a per-value pin — "make *compact* the default" —
+ *   independent of what the track currently shows. Use on an always-visible pin
+ *   so it can never promote a meaningless value, and so two rows sharing one
+ *   slot (sashimi `'down'` vs `'auto'`) stay independent.
  * - **Omit it** for "whatever I'm showing", resolved through the cascade. Use for
- *   a symmetric or continuous setting where no fixed on-value makes sense
- *   (wiggle point size, arc line width, `mismatchAlpha`).
+ *   a continuous setting where no fixed on-value makes sense (wiggle point size,
+ *   arc line width).
+ *
+ * A checkbox row takes neither: {@link makeTogglePin}.
  *
  * One function with an optional argument, rather than the two exported builders
  * it replaces — a per-value one and a `…CurrentValue…` one, the second of which
@@ -172,7 +174,40 @@ export declare function applySlotToOpenTracks(displays: ResolvableDisplay[], slo
  */
 export declare function makePin<CONFMODEL extends AnyConfigurationModel, SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>>>(self: ResolvableDisplay<CONFMODEL>, slot: SLOT, ...value: [] | [
     ConfigurationSlotValueResolved<ConfigurationSchemaForModel<CONFMODEL>, SLOT>
-]): Pin;
+]): ValuePin;
+/**
+ * The two states a checkbox row moves a slot between. Omitted for a
+ * `maybeBoolean` slot, where they are `true` and `false`; required for a
+ * two-member enum (`linkedReads`: "View as pairs" toggles `'normal'`/`'off'`).
+ * A slot with three or more members is a radio group, not a checkbox per
+ * member — `readConnections` was two checkboxes over one slot, and the
+ * unticked one's pin wrote the whole slot under a label naming only itself.
+ */
+export interface ToggleStates<T> {
+    on: T;
+    off: T;
+}
+/**
+ * #api core/configuration
+ * The pin on a checkbox row: the row's own checkbox, acting on every open track
+ * of the display type. `active` mirrors the row, so the pin draws filled
+ * exactly when the box is ticked; a click flips the row's state on every open
+ * track and offers the new state as the display type's default. It never
+ * clears a default the way {@link makePin}'s filled pin does — flipping back
+ * and taking the offer promotes the other value, and promoting the base value
+ * clears the default (`applyAndOfferDefault`).
+ *
+ * Replaces a symmetric `makePin(self, slot)` on these rows, which carried the
+ * row's current state: beside an unchecked box that applied *off* everywhere
+ * and visibly did nothing. It also replaces the per-value `makePin` a checkbox
+ * row over a shared enum slot used to carry, which gave two checkbox rows in
+ * one submenu two different pins: one filled when its value was promoted and
+ * clearing on a second click, the other filled when the box was ticked and
+ * flipping. With `states`, a checkbox row is always the toggle kind.
+ */
+export declare function makeTogglePin<CONFMODEL extends AnyConfigurationModel, SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>>>(self: ResolvableDisplay<CONFMODEL>, slot: SLOT, ...states: ConfigurationSlotValueResolved<ConfigurationSchemaForModel<CONFMODEL>, SLOT> extends boolean ? [] | [ToggleStates<boolean>] : [
+    ToggleStates<ConfigurationSlotValueResolved<ConfigurationSchemaForModel<CONFMODEL>, SLOT>>
+]): TogglePin;
 /**
  * #api core/configuration
  * Effective differences a track following the default inherits from session-wide
@@ -189,9 +224,9 @@ export declare function getDisplayTypeDefaultChanges(self: ResolvableDisplay): T
  *
  * **`slots` is required, and an all-slots default is not the convenience it
  * looks like.** It reaches further than any list a dialog can have shown: a
- * promoted default the track *customized* over, or one promoted to a value
- * equal to `promotedBase`, is `inherited: false` and so appears in no row, yet
- * still governs sibling tracks — so clearing it from a dialog that never showed
+ * promoted default the track *customized* over is `inherited: false` and so
+ * appears in no row, yet still governs sibling tracks — so clearing it from a
+ * dialog that never showed
  * it moves tracks other than the one whose badge was clicked. Clearing every
  * promoted default at once is a preferences-scope action, and Preferences →
  * "Reset to defaults" is where it lives (`clearPreferenceOverrides`).