@jbrowse/core 5.0.0-beta.2 → 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.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;
         },
     }));

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`).

package/esm/configuration/promotableDefaults.js

@@ -24,10 +24,10 @@ import { isConfigurationModel } from './schemaTypes.js';
  * 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 function isSlotCustomized(self, slot) {
     return resolveSlot(self, slot).customized;
@@ -178,17 +178,11 @@ export function applySlotToOpenTracks(displays, slot, value) {
     }
 }
 /**
- * The pin's click. Two branches, chosen by whether this value is *already* the
- * display type's promoted default:
- *
- * - **It isn't** — write `value` into every open track of the type, and offer
- *   the promotion as a snackbar action. Applying to the tracks in front of the
- *   user is the click they mean far more often, so it is the one that needs no
- *   second click; a default outlives the tracks it was set for and governs every
- *   track of the type opened later, so it is the escalation (ADR-048).
- * - **It is** — clear it, touching no track. The open tracks hold their values
- *   because the user applied them, so reverting them here would make a toggle
- *   into a bulk discard.
+ * The pin's click: write `value` into every open track of the type, and offer
+ * the promotion as a snackbar action. Applying to the tracks in front of the
+ * user is the click they mean far more often, so it is the one that needs no
+ * second click; a default outlives the tracks it was set for and governs every
+ * track of the type opened later, so it is the escalation (ADR-048).
  *
  * The apply is one operation over *every* open track, not a labeled pair over
  * the tracks that differ and the tracks that follow. Overwriting a customized
@@ -203,43 +197,60 @@ export function applySlotToOpenTracks(displays, slot, value) {
  * the offer got a silent no-op. What is still guarded is the session, which owns
  * the map the write lands in. ADR-048 has the decisions this does not change:
  * no track set and no apply/promote decision may be closed over.
+ *
+ * **Promoting the slot's base value clears the default instead of storing it.**
+ * The cascade resolves the two identically, but a stored base was a third
+ * state the rest of the subsystem could see: the Preferences inventory listed a
+ * row reading "from X to X", and the base option's radio pin drew filled. Now
+ * "Set as the default" on the base row is the per-value way to undo a promoted
+ * default, and a filled pin only ever means a non-base value is promoted. The
+ * base is read here rather than at click time because it is a schema literal
+ * and cannot change.
  */
-function applyPinClick(self, slot, value, isDefault) {
+function applyAndOfferDefault(self, slot, value) {
     const session = getSession(self);
     const displayType = self.type;
-    if (isDefault) {
-        session.setDisplayTypeDefault(displayType, slot, undefined);
-        session.notify('Cleared the default', 'info');
-    }
-    else {
-        const open = openTracksOfType(self);
-        applySlotToOpenTracks(open, slot, value);
-        session.notify(`Applied to ${open.length} open ${pluralize(open.length, 'track')}`, 'info', {
-            name: 'Set as the default',
-            onClick: () => {
-                if (isAlive(session)) {
-                    session.setDisplayTypeDefault(displayType, slot, value);
-                }
-            },
-        });
-    }
+    const { base } = resolveSlot(self, slot);
+    const promoted = deepEqual(value, base) ? undefined : value;
+    const open = openTracksOfType(self);
+    applySlotToOpenTracks(open, slot, value);
+    session.notify(`Applied to ${open.length} open ${pluralize(open.length, 'track')}`, 'info', {
+        name: 'Set as the default',
+        onClick: () => {
+            if (isAlive(session)) {
+                session.setDisplayTypeDefault(displayType, slot, promoted);
+            }
+        },
+    });
+}
+/**
+ * A value pin's click when its value is already the promoted default: clear
+ * it, touching no track. The open tracks hold their values because the user
+ * applied them, so reverting them here would make a toggle into a bulk discard.
+ */
+function clearDefault(self, slot) {
+    const session = getSession(self);
+    session.setDisplayTypeDefault(self.type, slot, undefined);
+    session.notify('Cleared the default', 'info');
 }
 /**
  * #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
@@ -277,11 +288,63 @@ export function makePin(self, slot, ...value) {
     // same `deepEqual`, no second walk.
     const active = deepEqual(res.promoted, onValue);
     return {
+        kind: 'value',
+        slot,
+        onValue,
+        active,
+        toggle: () => {
+            if (active) {
+                clearDefault(self, slot);
+            }
+            else {
+                applyAndOfferDefault(self, slot, onValue);
+            }
+        },
+    };
+}
+/**
+ * #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 function makeTogglePin(self, slot, 
+// rest-tuple, like `makePin`'s value: a boolean slot may omit the states, and
+// any other slot has to name them, so the type says which without a runtime
+// check that could only fire on a schema widened to `any`
+...states) {
+    const current = resolveSlot(self, slot).value;
+    const [given] = states;
+    if (!given && typeof current !== 'boolean') {
+        throw new Error(`cannot build a toggle pin over config slot "${slot}" without naming its on/off states: it resolves to ${JSON.stringify(current)}, not a boolean`);
+    }
+    const { on, off } = given ?? { on: true, off: false };
+    for (const state of [on, off]) {
+        if (!isPromotableValue(self.configuration, slot, state)) {
+            throw new Error(`cannot toggle config slot "${slot}" to ${JSON.stringify(state)}: the cascade refuses it, so the pin could never apply it`);
+        }
+    }
+    const active = deepEqual(current, on);
+    const onValue = active ? off : on;
+    return {
+        kind: 'toggle',
         slot,
         onValue,
         active,
         toggle: () => {
-            applyPinClick(self, slot, onValue, active);
+            applyAndOfferDefault(self, slot, onValue);
         },
     };
 }
@@ -317,9 +380,9 @@ export function getDisplayTypeDefaultChanges(self) {
  *
  * **`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`).