@defra/interactive-map 0.0.22-alpha → 0.0.24-alpha

package/src/services/symbolRegistry.test.js

@@ -1,12 +1,16 @@
 import { symbolRegistry } from './symbolRegistry.js'
-import { symbolDefaults } from '../config/symbolConfig.js'
-import { SCHEME_COLORS } from '../config/mapTheme.js'
+import { symbolDefaults, pin } from '../config/symbolConfig.js'
+import { THEME_COLORS } from '../config/mapTheme.js'
 import { getValueForStyle } from '../utils/getValueForStyle.js'
 
 const STYLE_ID = 'test'
 const mapStyle = { id: STYLE_ID }
+const COLOR_OVERRIDE = '#ff0000'
+const FILL_OVERRIDE = `fill="${COLOR_OVERRIDE}"`
 
 beforeEach(() => {
+  symbolRegistry.clear()
+  symbolRegistry.initialise()
   symbolRegistry.setDefaults({})
 })
 
@@ -58,20 +62,20 @@ describe('symbolRegistry — setDefaults / getDefaults', () => {
   })
 
   it('constructor defaults override hardcoded defaults', () => {
-    symbolRegistry.setDefaults({ backgroundColor: '#ff0000', symbol: 'circle' })
+    symbolRegistry.setDefaults({ backgroundColor: COLOR_OVERRIDE, symbol: 'circle' })
     const defaults = symbolRegistry.getDefaults()
-    expect(defaults.backgroundColor).toBe('#ff0000')
+    expect(defaults.backgroundColor).toBe(COLOR_OVERRIDE)
     expect(defaults.symbol).toBe('circle')
   })
 
   it('constructor defaults do not affect unset properties', () => {
-    symbolRegistry.setDefaults({ backgroundColor: '#ff0000' })
+    symbolRegistry.setDefaults({ backgroundColor: COLOR_OVERRIDE })
     const defaults = symbolRegistry.getDefaults()
     expect(defaults.foregroundColor).toBe(symbolDefaults.foregroundColor)
   })
 
   it('setDefaults with null or undefined resets to hardcoded defaults', () => {
-    symbolRegistry.setDefaults({ backgroundColor: '#ff0000' })
+    symbolRegistry.setDefaults({ backgroundColor: COLOR_OVERRIDE })
     symbolRegistry.setDefaults(null)
     expect(symbolRegistry.getDefaults().backgroundColor).toBe(symbolDefaults.backgroundColor)
   })
@@ -81,24 +85,23 @@ describe('symbolRegistry — resolve', () => {
   const BACKGROUND_SVG = '<path fill="{{backgroundColor}}"/>'
   const symbolDef = {
     id: 'test',
-    svg: '<path fill="{{backgroundColor}}" stroke="{{haloColor}}" stroke-width="{{haloWidth}}"/><path fill="{{foregroundColor}}" stroke="{{selectedColor}}"/>'
+    svg: '<path fill="{{backgroundColor}}" stroke="{{haloColor}}"/><path fill="{{foregroundColor}}" stroke="{{selectedColor}}"/><path stroke="{{activeColor}}"/>'
   }
 
   it('injects default token values when no overrides given', () => {
     const resolved = symbolRegistry.resolve(symbolDef, {}, mapStyle)
     expect(resolved).toContain(`fill="${getValueForStyle(symbolDefaults.backgroundColor, STYLE_ID)}"`)
     expect(resolved).toContain(`fill="${getValueForStyle(symbolDefaults.foregroundColor, STYLE_ID)}"`)
-    expect(resolved).toContain(`stroke-width="${symbolDefaults.haloWidth}"`)
   })
 
-  it('always produces empty selectedColor token — ring is hidden', () => {
+  it('always produces empty selectedColor and activeColor tokens — rings are hidden', () => {
     const resolved = symbolRegistry.resolve(symbolDef, {}, mapStyle)
-    expect(resolved).toContain('stroke=""')
+    expect(resolved).toContain('stroke="none"')
   })
 
   it('uses light scheme haloColor when mapStyle has no haloColor', () => {
     const resolved = symbolRegistry.resolve(symbolDef, {}, mapStyle)
-    expect(resolved).toContain(`stroke="${SCHEME_COLORS.light.haloColor}"`)
+    expect(resolved).toContain(`stroke="${THEME_COLORS.light.haloColor}"`)
   })
 
   it('uses mapStyle.haloColor when provided', () => {
@@ -107,8 +110,8 @@ describe('symbolRegistry — resolve', () => {
   })
 
   it('overrides default backgroundColor with a plain string', () => {
-    const resolved = symbolRegistry.resolve(symbolDef, { backgroundColor: '#ff0000' }, mapStyle)
-    expect(resolved).toContain('fill="#ff0000"')
+    const resolved = symbolRegistry.resolve(symbolDef, { backgroundColor: COLOR_OVERRIDE }, mapStyle)
+    expect(resolved).toContain(FILL_OVERRIDE)
   })
 
   it('overrides default with a style-keyed color', () => {
@@ -163,48 +166,70 @@ describe('symbolRegistry — resolve', () => {
   })
 })
 
-describe('symbolRegistry — resolveSelected', () => {
+describe('symbolRegistry — resolveActive (keyboard cursor state)', () => {
   const symbolDef = {
-    id: 'test-sel',
-    svg: '<path stroke="{{selectedColor}}" stroke-width="{{selectedWidth}}"/><path fill="{{backgroundColor}}"/>'
+    id: 'test-active',
+    svg: '<path fill="{{selectedColor}}" stroke="{{activeColor}}" stroke-width="6"/><path fill="{{backgroundColor}}"/>'
   }
 
-  it('uses light scheme selectedColor when mapStyle has no selectedColor', () => {
-    const resolved = symbolRegistry.resolveSelected(symbolDef, {}, mapStyle)
-    expect(resolved).toContain(`stroke="${SCHEME_COLORS.light.selectedColor}"`)
+  it('renders selectedColor from scheme when mapStyle has no selectedColor', () => {
+    const resolved = symbolRegistry.resolveActive(symbolDef, {}, mapStyle)
+    expect(resolved).toContain(`fill="${THEME_COLORS.light.selectedColor}"`)
+  })
+
+  it('renders activeColor from scheme when mapStyle has no activeColor', () => {
+    const resolved = symbolRegistry.resolveActive(symbolDef, {}, mapStyle)
+    expect(resolved).toContain(`stroke="${THEME_COLORS.light.activeColor}"`)
   })
 
   it('uses mapStyle.selectedColor when provided', () => {
-    const resolved = symbolRegistry.resolveSelected(symbolDef, {}, { id: STYLE_ID, selectedColor: '#ff0000' })
-    expect(resolved).toContain('stroke="#ff0000"')
+    const resolved = symbolRegistry.resolveActive(symbolDef, {}, { id: STYLE_ID, selectedColor: COLOR_OVERRIDE })
+    expect(resolved).toContain(FILL_OVERRIDE)
   })
 
-  it('uses selectedWidth from symbolDefaults', () => {
-    const resolved = symbolRegistry.resolveSelected(symbolDef, {}, mapStyle)
-    expect(resolved).toContain(`stroke-width="${symbolDefaults.selectedWidth}"`)
+  it('uses mapStyle.activeColor when provided', () => {
+    const resolved = symbolRegistry.resolveActive(symbolDef, {}, { id: STYLE_ID, activeColor: '#00ff00' })
+    expect(resolved).toContain('stroke="#00ff00"')
   })
 
   it('handles null styleColors — uses cascade defaults', () => {
-    const resolved = symbolRegistry.resolveSelected(symbolDef, null, mapStyle)
-    expect(resolved).toContain(`stroke="${SCHEME_COLORS.light.selectedColor}"`)
+    const resolved = symbolRegistry.resolveActive(symbolDef, null, mapStyle)
+    expect(resolved).toContain(`fill="${THEME_COLORS.light.selectedColor}"`)
   })
 
   it('returns empty string for null symbolDef', () => {
-    expect(symbolRegistry.resolveSelected(null, {}, mapStyle)).toBe('')
+    expect(symbolRegistry.resolveActive(null, {}, mapStyle)).toBe('')
   })
 
   it('symbol-level selectedColor is ignored — mapStyle wins', () => {
     const defWithSelected = { ...symbolDef, selectedColor: '#00ff00' }
-    const resolved = symbolRegistry.resolveSelected(defWithSelected, {}, { id: STYLE_ID, selectedColor: '#ff0000' })
-    expect(resolved).toContain('stroke="#ff0000"')
+    const resolved = symbolRegistry.resolveActive(defWithSelected, {}, { id: STYLE_ID, selectedColor: COLOR_OVERRIDE })
+    expect(resolved).toContain(FILL_OVERRIDE)
   })
 
   it('still resolves other tokens correctly', () => {
-    const resolved = symbolRegistry.resolveSelected(symbolDef, { backgroundColor: '#d4351c' }, mapStyle)
+    const resolved = symbolRegistry.resolveActive(symbolDef, { backgroundColor: '#d4351c' }, mapStyle)
     expect(resolved).toContain('fill="#d4351c"')
   })
 })
 
+describe('symbolRegistry — resolveSelected (committed selection state)', () => {
+  const symbolDef = {
+    id: 'test-selected',
+    svg: '<path fill="{{selectedColor}}"/>'
+  }
+
+  it('returns empty string for null symbolDef', () => {
+    expect(symbolRegistry.resolveSelected(null, {}, mapStyle)).toBe('')
+  })
+
+  it('handles null styleColors — uses cascade defaults', () => {
+    const resolved = symbolRegistry.resolveSelected(symbolDef, null, mapStyle)
+    expect(typeof resolved).toBe('string')
+    expect(resolved.length).toBeGreaterThan(0)
+  })
+})
+
 describe('symbolRegistry — graphic token', () => {
   const graphicDef = {
     id: 'test-graphic',
@@ -257,6 +282,91 @@ describe('symbolRegistry — graphic token', () => {
     const pin = symbolRegistry.get('pin')
     const resolved = symbolRegistry.resolve(pin, {}, mapStyle)
     expect(resolved).toContain(`d="${pin.graphic}"`)
-    expect(resolved).toContain('translate(19, 16) scale(0.8) translate(-8, -8)')
+    expect(resolved).toContain('translate(22, 19) scale(0.8) translate(-8, -8)')
+  })
+})
+
+// ─── getSymbolDef ─────────────────────────────────────────────────────────────
+
+describe('getSymbolDef', () => {
+  it('returns undefined when dataset has no symbol', () => {
+    expect(symbolRegistry.getSymbolDef({})).toBeUndefined()
+  })
+
+  it('looks up string symbol id in the registry', () => {
+    expect(symbolRegistry.getSymbolDef({ symbol: 'pin' })).toBe(pin)
+  })
+
+  it('returns undefined for an unregistered string symbol', () => {
+    expect(symbolRegistry.getSymbolDef({ symbol: 'missing' })).toBeUndefined()
+  })
+
+  it('returns inline def from symbolSvgContent with svg key', () => {
+    const dataset = { symbolSvgContent: '<circle/>', symbolViewBox: '0 0 10 10' }
+    const result = symbolRegistry.getSymbolDef(dataset)
+    expect(result.svg).toBe('<circle/>')
+  })
+
+  it('symbolSvgContent takes precedence over symbol id', () => {
+    const result = symbolRegistry.getSymbolDef({ symbol: 'pin', symbolSvgContent: '<circle/>' })
+    expect(result.svg).toBe('<circle/>')
+  })
+})
+
+// ─── getSymbolImageId ─────────────────────────────────────────────────────────
+
+describe('getSymbolImageId', () => {
+  it('returns null when dataset has no symbol', () => {
+    expect(symbolRegistry.getSymbolImageId({}, mapStyle)).toBeNull()
+  })
+
+  it('returns null for an unregistered symbol id', () => {
+    expect(symbolRegistry.getSymbolImageId({ symbol: 'does-not-exist' }, mapStyle)).toBeNull()
+  })
+
+  it('returns a string prefixed symbol- for normal state', () => {
+    const id = symbolRegistry.getSymbolImageId({ symbol: 'pin' }, mapStyle)
+    expect(typeof id).toBe('string')
+    expect(id).toMatch(/^symbol-[a-z0-9]+-\d+(\.\d+)?x$/)
+  })
+
+  it('returns a string prefixed symbol-act- for active state', () => {
+    const id = symbolRegistry.getSymbolImageId({ symbol: 'pin' }, mapStyle, true)
+    expect(typeof id).toBe('string')
+    expect(id).toMatch(/^symbol-act-[a-z0-9]+-\d+(\.\d+)?x$/)
+  })
+
+  it('normal and active ids differ for the same dataset', () => {
+    const normalId = symbolRegistry.getSymbolImageId({ symbol: 'pin' }, mapStyle, false)
+    const activeId = symbolRegistry.getSymbolImageId({ symbol: 'pin' }, mapStyle, true)
+    expect(normalId).not.toBe(activeId)
+  })
+
+  it('same dataset and style always produces the same id', () => {
+    const id1 = symbolRegistry.getSymbolImageId({ symbol: 'pin' }, mapStyle)
+    const id2 = symbolRegistry.getSymbolImageId({ symbol: 'pin' }, mapStyle)
+    expect(id1).toBe(id2)
+  })
+
+  it('different symbols produce different ids', () => {
+    const pinId = symbolRegistry.getSymbolImageId({ symbol: 'pin' }, mapStyle)
+    const circleId = symbolRegistry.getSymbolImageId({ symbol: 'circle' }, mapStyle)
+    expect(pinId).not.toBe(circleId)
+  })
+
+  it('different backgrounds produce different ids', () => {
+    const redId = symbolRegistry.getSymbolImageId({ symbol: 'pin', symbolBackgroundColor: '#ff0000' }, mapStyle)
+    const blueId = symbolRegistry.getSymbolImageId({ symbol: 'pin', symbolBackgroundColor: '#0000ff' }, mapStyle)
+    expect(redId).not.toBe(blueId)
+  })
+
+  it('resolves inline symbolSvgContent', () => {
+    const dataset = {
+      symbolSvgContent: '<circle cx="19" cy="19" r="12" fill="{{backgroundColor}}"/>',
+      symbolViewBox: '0 0 38 38',
+      symbolAnchor: [0.5, 0.5]
+    }
+    const id = symbolRegistry.getSymbolImageId(dataset, mapStyle)
+    expect(id).toMatch(/^symbol-[a-z0-9]+-\d+(\.\d+)?x$/)
   })
 })

package/src/types.js

@@ -91,6 +91,41 @@
  * Core services (announce, reverseGeocode, closeApp, etc.).
  */
 
+/**
+ * Defines an item in a button's popup menu.
+ *
+ * @typedef {Object} MenuItemDefinition
+ *
+ * @property {string} id
+ * Unique item identifier. Used to control state via toggleButtonState().
+ *
+ * @property {string} label
+ * Display text for the item.
+ *
+ * @property {string} [iconId]
+ * Icon identifier from the icon registry.
+ *
+ * @property {string} [iconSvgContent]
+ * Raw SVG content for the item icon. The outer SVG tag should be excluded.
+ *
+ * @property {boolean} [isPressed]
+ * Initial checked state. When set, the item renders as menuitemcheckbox.
+ *
+ * @property {boolean} [keepFocus=false]
+ * When true, focus returns to the menu's trigger button after selection instead of
+ * moving to the panel (if panelId is set) or the map viewport.
+ *
+ * @property {(e: MouseEvent) => void} [onClick]
+ * Click handler. Receives the native event. Not called when panelId is set.
+ *
+ * @property {string} [panelId]
+ * Associated panel identifier. When set, selecting the item opens the panel and moves
+ * focus to it. onClick is not called.
+ *
+ * @property {(context: PluginContext) => boolean} [pressedWhen]
+ * Reactive callback to determine if the item should appear checked. Plugin buttons only.
+ */
+
 /**
  * Defines a button that can be rendered in the UI at various breakpoints.
  *
@@ -133,12 +168,21 @@
  * @property {string | (() => string)} label
  * Accesible label. Text or a function returning the text. Used for the label or tooltip if 'showLabel' is false.
  *
+ * @property {MenuItemDefinition[]} [menuItems]
+ * Items for the button's popup menu. When provided, the button acts as a menu trigger.
+ *
  * @property {ButtonBreakpointConfig} mobile
  * Mobile breakpoint configuration.
  *
  * @property {(event: MouseEvent, context: PluginContext) => void} [onClick]
  * Click handler for the button.
  *
+ * @property {boolean} [keepFocus=false]
+ * When true, focus remains on this button after activation instead of moving to the panel or viewport.
+ * Use for repeated incremental actions (e.g. zoom) where the user may activate the button
+ * multiple times. Toggle buttons (isPressed/pressedWhen) always keep focus regardless of this flag.
+ * When combined with panelId, the panel opens but focus stays on the button.
+ *
  * @property {string} [panelId]
  * Associated panel identifier to toggle open when clicked.
  *
@@ -221,6 +265,10 @@
  * @property {(point: { x: number, y: number }) => any[]} getFeaturesAtPoint
  * Query rendered features at a screen pixel position (x from left edge, y from top edge of viewport).
  *
+ * @property {(layerIds: string[]) => any[]} getVisibleFeatures
+ * Return all GeoJSON features currently visible in the viewport on the given layers,
+ * respecting layer visibility and any active filters. Returns [] if unsupported.
+ *
  * @property {() => string} getAreaDimensions
  * Get the dimensions of the visible map area as a formatted string (e.g., '400m by 750m').
  *
@@ -236,7 +284,7 @@
  * @property {(point: { x: number, y: number }) => [number, number]} screenToMap
  * Convert screen pixel position (x from left edge, y from top edge of viewport) to map coordinates ([lng, lat] or [easting, northing] depending on the crs of the map provider).
  *
- * @property {(selectedFeatures: any[], stylesMap: any) => any} [updateHighlightedFeatures]
+ * @property {(selectedFeatures: any[], activeFeatures: any[], stylesMap: any) => any} [updateHighlightedFeatures]
  * @experimental Update highlighted features on the map.
  *
  * @property {(direction: string) => any} [highlightNextLabel]
@@ -329,7 +377,7 @@
  * Alt text for logo.
  *
  * @property {'light' | 'dark'} [mapColorScheme]
- * Map colour scheme. Sets the default values of `haloColor`, `selectedColor`, and `foregroundColor`
+ * Map colour scheme. Sets the default values of `haloColor`, `selectedColor`, `activeColor`, and `foregroundColor`
  * when not explicitly provided, and signals to map overlay components which tonal range to use.
  * `'light'` (default): dark overlays on a light basemap. `'dark'`: light overlays on a dark or aerial basemap.
  *
@@ -342,10 +390,14 @@
  * Injected as the `--map-overlay-halo-color` CSS custom property.
  *
  * @property {string} [selectedColor]
- * Theme colour for selected state — used by map overlay components to indicate a selected feature.
+ * Theme colour for committed selection — used by map overlay components to indicate a selected feature.
  * Falls back to `#0b0c0c` (light) or `#ffffff` (dark).
  * Injected as the `--map-overlay-selected-color` CSS custom property.
  *
+ * @property {string} [activeColor]
+ * Theme colour for the active (keyboard cursor) state — the focus ring shown when navigating features
+ * with the keyboard. Falls back to `#ffdd00` for both light and dark schemes.
+ *
  * @property {string} [foregroundColor]
  * Foreground colour for elements rendered on top of the map (e.g. text or iconography in overlay components).
  * Falls back to `#0b0c0c` (light) or `#ffffff` (dark).
@@ -367,7 +419,7 @@
  * @property {string} [symbolSvgContent]
  * Default inner SVG path content. When set, overrides `symbol`.
  *
- * @property {string} [viewBox='0 0 38 38']
+ * @property {string} [viewBox='0 0 44 44']
  * Default SVG viewBox.
  *
  * @property {[number, number]} [anchor=[0.5, 0.5]]
@@ -379,15 +431,10 @@
  * @property {string | Record<string, string>} [foregroundColor='#ffffff']
  * Default foreground fill colour.
  *
- * @property {string} [haloWidth='1']
- * Default halo stroke width in SVG units.
- *
  * @property {string} [graphic]
  * Default SVG `d` attribute value for the foreground graphic path. Each built-in symbol sets
  * its own default (a small dot). Override to swap the graphic across all markers globally.
  *
- * @property {string} [selectedWidth='6']
- * Selection ring stroke width in SVG units. App-wide only — ignored at symbol registration and marker creation level.
  */
 
 /**
@@ -420,8 +467,8 @@
  * When set, `symbol` is ignored.
  *
  * @property {string} [viewBox]
- * SVG viewBox attribute for the symbol, e.g. `'0 0 38 38'`.
- * Defaults to the registered symbol's viewBox, or `'0 0 38 38'`.
+ * SVG viewBox attribute for the symbol, e.g. `'0 0 44 44'`.
+ * Defaults to the registered symbol's viewBox, or `'0 0 44 44'`.
  *
  * @property {[number, number]} [anchor]
  * Anchor point as a normalised [x, y] pair where [0, 0] is top-left and [1, 1] is bottom-right.
@@ -434,9 +481,6 @@
  * @property {string | Record<string, string>} [foregroundColor]
  * Foreground fill colour of the symbol (e.g. the inner dot on a pin).
  *
- * @property {string} [haloWidth]
- * Stroke width of the halo in SVG units. Defaults to `'1'`.
- *
  * @property {string} [graphic]
  * SVG `d` attribute value for the foreground graphic path. Replaces the foreground shape of the
  * symbol while keeping its background, halo and selection ring intact. Each built-in symbol
@@ -447,6 +491,14 @@
  * import { graphics } from './config/symbolConfig.js'
  * markers.add('id', coords, { symbol: 'pin', graphic: graphics.cross })
  *
+ * @property {string} [label]
+ * Plain-text label for this marker. Used as the accessible name on the marker SVG, and rendered
+ * as a visible label bubble when `showLabel` is `true` or when `symbol` is `null` (standalone label).
+ *
+ * @property {boolean} [showLabel=false]
+ * Whether to render a visible label bubble above the marker symbol. Defaults to `false`.
+ * Set `symbol` to `null` instead to create a standalone label with no symbol.
+ *
  */
 
 /**
@@ -457,6 +509,11 @@
  * @property {PanelBreakpointConfig} desktop
  * Desktop breakpoint configuration.
  *
+ * @property {boolean} [focus=true]
+ * Whether to move focus to the panel when it opens. Set to false to prevent the panel from
+ * receiving focus — useful for panels present on page load or panels that should not interrupt
+ * the user's current flow. Modal panels always receive focus regardless of this setting.
+ *
  * @property {string} [html]
  * HTML content.
  *

package/src/utils/constrainKeyboardFocus.js

@@ -4,11 +4,11 @@ export function constrainKeyboardFocus (containerEl, e) {
   }
 
   const selectors = [
-    'a[href]:not([disabled])',
-    'button:not([disabled])',
-    'textarea:not([disabled])',
-    'input:not([disabled])',
-    'select:not([disabled])',
+    'a[href]:not([disabled]):not([tabindex="-1"])',
+    'button:not([disabled]):not([tabindex="-1"])',
+    'textarea:not([disabled]):not([tabindex="-1"])',
+    'input:not([disabled]):not([tabindex="-1"])',
+    'select:not([disabled]):not([tabindex="-1"])',
     '*[tabindex="0"]:not([disabled])'
   ]
   let focusableEls = Array.from(containerEl.querySelectorAll(selectors.join(',')))

package/src/utils/detectInterfaceType.js

@@ -1,5 +1,6 @@
 let lastInterfaceType = window.matchMedia('(pointer: coarse)').matches ? 'touch' : 'unknown'
 const interfaceTypeListeners = new Set()
+const interfaceTypeImmediateListeners = new Set()
 
 // -----------------------------------------------------------------------------
 // Internal (not exported)
@@ -20,9 +21,8 @@ function normalizePointerType (pointerType) {
 function notifyListeners (newType) {
   if (lastInterfaceType !== newType) {
     lastInterfaceType = newType
-    interfaceTypeListeners.forEach((listener) => {
-      listener(newType)
-    })
+    interfaceTypeImmediateListeners.forEach(listener => listener(newType))
+    interfaceTypeListeners.forEach(listener => listener(newType))
   }
 }
 
@@ -44,7 +44,18 @@ function createInterfaceDetector () {
 
   const handlePointer = event => {
     const type = normalizePointerType(event.pointerType)
-    setTimeout(() => notifyListeners(type), REACT_CLICK_DELAY)
+    if (type === lastInterfaceType) {
+      return
+    }
+    // Update synchronously so getInterfaceType() returns the new value immediately —
+    // this prevents focusin handlers from seeing the stale 'keyboard' type during a
+    // pointer-triggered focus move. Listeners (React state) are still notified async
+    // to avoid layout thrashing during the click event.
+    lastInterfaceType = type
+    interfaceTypeImmediateListeners.forEach(listener => listener(type))
+    setTimeout(() => {
+      interfaceTypeListeners.forEach(listener => listener(type))
+    }, REACT_CLICK_DELAY)
   }
 
   const handleKeyDown = e => {
@@ -81,8 +92,19 @@ function subscribeToInterfaceChanges (onInterfaceTypeChange) {
   }
 }
 
+// Fires synchronously within the same event cycle — use for direct DOM updates
+// that need to be in sync with the pointer event (no 150ms React delay).
+function subscribeToInterfaceChangesImmediate (onInterfaceTypeChange) {
+  interfaceTypeImmediateListeners.add(onInterfaceTypeChange)
+
+  return () => {
+    interfaceTypeImmediateListeners.delete(onInterfaceTypeChange)
+  }
+}
+
 export {
   createInterfaceDetector,
   getInterfaceType,
-  subscribeToInterfaceChanges
+  subscribeToInterfaceChanges,
+  subscribeToInterfaceChangesImmediate
 }

package/src/utils/detectInterfaceType.test.js

@@ -54,7 +54,7 @@ const triggerDomEvent = (event, payload) => {
 
 // --- TEST SUITE ---
 describe('Interface Detector Utility Module', () => {
-  let createInterfaceDetector, getInterfaceType, subscribeToInterfaceChanges
+  let createInterfaceDetector, getInterfaceType, subscribeToInterfaceChanges, subscribeToInterfaceChangesImmediate
   let cleanup
 
   beforeEach(async () => {
@@ -72,6 +72,7 @@ describe('Interface Detector Utility Module', () => {
     createInterfaceDetector = importedModule.createInterfaceDetector
     getInterfaceType = importedModule.getInterfaceType
     subscribeToInterfaceChanges = importedModule.subscribeToInterfaceChanges
+    subscribeToInterfaceChangesImmediate = importedModule.subscribeToInterfaceChangesImmediate
 
     Object.keys(eventListeners).forEach(key => delete eventListeners[key])
     Object.keys(mediaListeners).forEach(key => delete mediaListeners[key])
@@ -99,18 +100,21 @@ describe('Interface Detector Utility Module', () => {
 
     // --- Path 1a: pointerdown 'touch' ---
     triggerDomEvent('pointerdown', { pointerType: 'touch' })
+    expect(getInterfaceType()).toBe('touch') // synchronous update
+    expect(handler).not.toHaveBeenCalled() // listener still pending
     jest.advanceTimersByTime(150)
-    expect(getInterfaceType()).toBe('touch')
     expect(handler).toHaveBeenCalledWith('touch')
     handler.mockClear()
 
     // --- Path 1b: pointerdown 'pen' ---
     triggerDomEvent('pointerdown', { pointerType: 'pen' })
     jest.advanceTimersByTime(150)
-    expect(handler).not.toHaveBeenCalled()
+    expect(handler).not.toHaveBeenCalled() // 'pen' normalises to 'touch' — no change
 
     // --- Path 1c: pointerdown 'mouse' ---
     triggerDomEvent('pointerdown', { pointerType: 'mouse' })
+    expect(getInterfaceType()).toBe('mouse') // synchronous update
+    expect(handler).not.toHaveBeenCalled() // listener still pending
     jest.advanceTimersByTime(150)
     expect(getInterfaceType()).toBe('mouse')
     expect(handler).toHaveBeenCalledWith('mouse')
@@ -129,6 +133,10 @@ describe('Interface Detector Utility Module', () => {
     expect(handler).toHaveBeenCalledWith('keyboard')
     handler.mockClear()
 
+    // Tab again when already keyboard — notifyListeners no-op branch
+    triggerDomEvent('keydown', { key: 'Tab' })
+    expect(handler).not.toHaveBeenCalled()
+
     // keydown with non-Tab
     triggerDomEvent('keydown', { key: 'a' })
     expect(handler).not.toHaveBeenCalled()
@@ -152,6 +160,24 @@ describe('Interface Detector Utility Module', () => {
     expect(handler).not.toHaveBeenCalled()
   })
 
+  it('subscribeToInterfaceChangesImmediate fires synchronously and unsubscribes', () => {
+    const handler = jest.fn()
+    const unsubscribe = subscribeToInterfaceChangesImmediate(handler)
+    cleanup = createInterfaceDetector()
+
+    triggerDomEvent('pointerdown', { pointerType: 'touch' })
+    expect(handler).toHaveBeenCalledWith('touch') // fires before timer advance
+
+    // Tab keydown goes through notifyListeners — exercises immediate forEach callback
+    triggerDomEvent('keydown', { key: 'Tab' })
+    expect(handler).toHaveBeenCalledWith('keyboard')
+    expect(handler).toHaveBeenCalledTimes(2)
+
+    unsubscribe()
+    triggerDomEvent('pointerdown', { pointerType: 'mouse' })
+    expect(handler).toHaveBeenCalledTimes(2) // no longer called after unsubscribe
+  })
+
   it('should return "touch" when matchMedia initially matches coarse pointer', async () => {
     jest.resetModules()