@defra/interactive-map 0.0.17-alpha → 0.0.19-alpha

package/src/InteractiveMap/domStateManager.test.js

@@ -69,6 +69,27 @@ describe('updateDOMState', () => {
     }
   })
 
+  it('isFullscreen override forces non-fullscreen even when URL param matches', () => {
+    mapInstance.config.behaviour = 'buttonFirst'
+    queryString.getQueryParam.mockReturnValue('map') // URL says fullscreen
+
+    updateDOMState(mapInstance, { isFullscreen: false }) // but override says no
+
+    expect(document.documentElement.classList.contains('im-is-fullscreen')).toBe(false)
+    expect(rootEl.style.height).toBe('auto')
+  })
+
+  it('buttonFirst with manageHistoryState false is always fullscreen regardless of URL', () => {
+    mapInstance.config.behaviour = 'buttonFirst'
+    mapInstance.config.manageHistoryState = false
+    queryString.getQueryParam.mockReturnValue(null) // no mv param in URL
+
+    updateDOMState(mapInstance)
+
+    expect(document.documentElement.classList.contains('im-is-fullscreen')).toBe(true)
+    expect(mapInstance.rootEl.style.height).toBe('100%')
+  })
+
   describe('hybrid behaviour', () => {
     beforeEach(() => {
       mapInstance.config.behaviour = 'hybrid'

package/src/InteractiveMap/historyManager.js

@@ -40,6 +40,32 @@ function closeMap (mapInstance) {
   }
 }
 
+/**
+ * Syncs a single map instance against the current URL view parameter.
+ *
+ * @param {MapInstance} mapInstance
+ * @param {string|null} viewId - The current `mv` query param value.
+ * @private
+ */
+function syncMapInstance (mapInstance, viewId) {
+  if (mapInstance.config.manageHistoryState === false) {
+    return
+  }
+
+  const shouldBeOpen = mapInstance.id === viewId
+  const isHybridVisible = mapInstance.config.behaviour === 'hybrid' && !isHybridFullscreen(mapInstance.config)
+  const isOpen = mapInstance.rootEl?.children.length
+
+  if (shouldBeOpen && (!isOpen || mapInstance._isHidden)) {
+    openMap(mapInstance)
+    return
+  }
+
+  if (!shouldBeOpen && isOpen && !isHybridVisible) {
+    closeMap(mapInstance)
+  }
+}
+
 /**
  * Handles the `popstate` event triggered by browser back/forward navigation.
  *
@@ -56,21 +82,7 @@ function closeMap (mapInstance) {
  */
 function handlePopstate () {
   const viewId = getQueryParam(defaults.mapViewParamKey)
-
-  for (const mapInstance of components.values()) {
-    const shouldBeOpen = mapInstance.id === viewId
-    const isHybridVisible = mapInstance.config.behaviour === 'hybrid' && !isHybridFullscreen(mapInstance.config)
-    const isOpen = mapInstance.rootEl?.children.length
-
-    if (shouldBeOpen && (!isOpen || mapInstance._isHidden)) {
-      openMap(mapInstance)
-      continue
-    }
-
-    if (!shouldBeOpen && isOpen && !isHybridVisible) {
-      closeMap(mapInstance)
-    }
-  }
+  components.forEach(mapInstance => syncMapInstance(mapInstance, viewId))
 }
 
 // -----------------------------------------------------------------------------
@@ -105,7 +117,7 @@ let initialized = false
  */
 function register (component) {
   if (!initialized) {
-    window.addEventListener('popstate', handlePopstate)
+    globalThis.addEventListener('popstate', handlePopstate)
     initialized = true
   }
 

package/src/InteractiveMap/historyManager.test.js

@@ -141,6 +141,23 @@ describe('historyManager', () => {
     expect(window.matchMedia).toHaveBeenCalledWith('(max-width: 768px)')
   })
 
+  it('skips component when manageHistoryState is false', () => {
+    const managedComponent = {
+      id: 'managed',
+      config: { behaviour: 'buttonFirst', hybridWidth: null, maxMobileWidth: 640, manageHistoryState: false },
+      rootEl: document.createElement('div'),
+      loadApp: jest.fn(),
+      removeApp: jest.fn(),
+      _isHidden: false
+    }
+    historyManager.register(managedComponent)
+    queryString.getQueryParam.mockReturnValue('managed')
+
+    window.dispatchEvent(popstateEvent)
+
+    expect(managedComponent.loadApp).not.toHaveBeenCalled()
+  })
+
   it('unregisters component', () => {
     historyManager.register(component1)
     component1.rootEl.appendChild(document.createElement('div'))

package/src/config/appConfig.js

@@ -24,7 +24,7 @@ export const defaultAppConfig = {
     label: 'Exit',
     iconId: 'close',
     onClick: (_e, { services }) => services.closeApp(),
-    excludeWhen: ({ appConfig, appState }) => !appConfig.hasExitButton || !(appState.isFullscreen && (new URL(window.location.href)).searchParams.has(appConfig.mapViewParamKey)),
+    excludeWhen: ({ appConfig, appState }) => !appConfig.hasExitButton || !appState.isFullscreen,
     mobile: exitButtonSlots,
     tablet: exitButtonSlots,
     desktop: exitButtonSlots
@@ -115,6 +115,7 @@ export const defaultButtonConfig = {
 // Used by addPanel
 export const defaultPanelConfig = {
   label: 'Panel',
+  focus: true,
   mobile: {
     slot: 'drawer',
     open: true,
@@ -159,9 +160,3 @@ export const scaleFactor = {
   medium: 1.5,
   large: 2
 }
-
-export const markerSvgPaths = [{
-  shape: 'pin',
-  backgroundPath: 'M31 16.001c0 7.489-8.308 15.289-11.098 17.698-.533.4-1.271.4-1.803 0C15.309 31.29 7 23.49 7 16.001c0-6.583 5.417-12 12-12s12 5.417 12 12z',
-  graphicPath: 'M19 11.001c-2.76 0-5 2.24-5 5s2.24 5 5 5 5-2.241 5-5-2.24-5-5-5z'
-}]

package/src/config/appConfig.test.js

@@ -1,5 +1,5 @@
 import { render } from '@testing-library/react'
-import { defaultAppConfig, defaultButtonConfig, scaleFactor, markerSvgPaths } from './appConfig'
+import { defaultAppConfig, defaultButtonConfig, scaleFactor } from './appConfig'
 
 describe('defaultAppConfig', () => {
   const appState = {
@@ -23,28 +23,18 @@ describe('defaultAppConfig', () => {
 
   // --- EXIT BUTTON (Line 27 Coverage) ---
   it('covers all branches of exitBtn excludeWhen', () => {
-    const config = { hasExitButton: true, mapViewParamKey: 'view' }
-
     expect(exitBtn.excludeWhen({
-      appConfig: { ...config, hasExitButton: false },
+      appConfig: { hasExitButton: false },
       appState: { isFullscreen: true }
     })).toBe(true)
 
-    window.history.pushState({}, '', '?view=map')
     expect(exitBtn.excludeWhen({
-      appConfig: config,
+      appConfig: { hasExitButton: true },
       appState: { isFullscreen: false }
     })).toBe(true)
 
-    window.history.pushState({}, '', '?wrong=param')
-    expect(exitBtn.excludeWhen({
-      appConfig: config,
-      appState: { isFullscreen: true }
-    })).toBe(true)
-
-    window.history.pushState({}, '', '?view=map')
     expect(exitBtn.excludeWhen({
-      appConfig: config,
+      appConfig: { hasExitButton: true },
       appState: { isFullscreen: true }
     })).toBe(false)
   })
@@ -135,6 +125,5 @@ describe('defaultAppConfig', () => {
   it('exports supplementary configs and constants', () => {
     expect(defaultButtonConfig.label).toBe('Button')
     expect(scaleFactor.large).toBe(2)
-    expect(markerSvgPaths[0].shape).toBe('pin')
   })
 })

package/src/config/defaults.js

@@ -16,7 +16,7 @@ const defaults = {
   containerHeight: '600px',
   deviceNotSupportedText: 'Your device is not supported. A map is available with a more up-to-date browser or device.',
   enableFullscreen: false,
-  enableZoomControls: false,
+  enableZoomControls: true,
   genericErrorText: 'There was a problem loading the map. Please try again later.',
   hasExitButton: false,
   hybridWidth: null, // Defaults to maxMobileWidth if not set
@@ -24,11 +24,10 @@ const defaults = {
   mapLabel: 'Interactive map',
   mapProvider: null,
   mapSize: 'small',
+  manageHistoryState: true,
   mapViewParamKey: 'mv',
   maxMobileWidth: 640,
   minDesktopWidth: 835,
-  markerColor: '#ff0000',
-  markerShape: 'pin',
   nudgePanDelta: 5,
   nudgeZoomDelta: 0.1,
   panDelta: 100,

package/src/config/events.js

@@ -62,32 +62,34 @@ export const EVENTS = {
   APP_READY: 'app:ready',
 
   /**
-   * Emitted when the map application becomes visible after being hidden.
+   * Emitted when the map application has opened and is visible.
    *
-   * This can occur in 'hybrid behaviour' responsive scenarios where the map is already initialized
-   * (e.g. initialized inline on desktop) but was hidden and then shown again
-   * (e.g. resizing to mobile and opening the map).
+   * Fired after initial load (`loadApp`) and when the app is shown again after being hidden (`showApp`).
+   * Subscribe to this event to react whenever the map becomes visible to the user.
    *
-   * @remarks
-   * - Only emitted when transitioning from hidden → visible.
-   * - Not fired on initial open.
-   * - The existing map state may be preserved depending on configuration.
+   * Payload: `{ statePreserved: boolean }` — `true` if the map state was preserved from a previous session.
+   *
+   * @example
+   * map.on(EVENTS.APP_OPENED, ({ statePreserved }) => {
+   *   console.log('Map opened, state preserved:', statePreserved)
+   * })
    */
-  APP_VISIBLE: 'app:visible',
+  APP_OPENED: 'app:opened',
 
   /**
-   * Emitted when the map application becomes hidden.
+   * Emitted when the map application has closed and is no longer visible.
+   *
+   * Fired when the app is hidden (`hideApp`) or removed (`removeApp`).
+   * Subscribe to this event to react whenever the map is closed.
    *
-   * This can occur in 'hybrid behaviour' responsive scenarios where the map was initialized inline
-   * (e.g. visible on desktop) but then becomes hidden
-   * (e.g. resizing to mobile or closing the map view).
+   * Payload: `{ statePreserved: boolean }` — `true` if the map state was preserved (i.e. can be restored).
    *
-   * @remarks
-   * - Only emitted when transitioning from visible → hidden.
-   * - Not fired on initial load if the map starts hidden.
-   * - The map state may be preserved depending on configuration.
+   * @example
+   * map.on(EVENTS.APP_CLOSED, ({ statePreserved }) => {
+   *   console.log('Map closed, state preserved:', statePreserved)
+   * })
    */
-  APP_HIDDEN: 'app:hidden',
+  APP_CLOSED: 'app:closed',
 
   /**
    * Emitted when a panel is opened.
@@ -202,9 +204,6 @@ export const EVENTS = {
    */
   MAP_CLICK: 'map:click',
 
-  /** Emitted when the user exits the map (e.g., via the close button). */
-  MAP_EXIT: 'map:exit',
-
   /** Emitted when the map is destroyed. Payload: { mapId: string } */
   MAP_DESTROY: 'map:destroy'
 }

package/src/config/mapTheme.js

@@ -0,0 +1,56 @@
+/**
+ * Canonical colour values for light and dark map colour schemes.
+ * These are the single source of truth for map overlay colours —
+ * used both by the symbol SVG renderer (JS canvas) and injected as
+ * CSS custom properties onto the app container for CSS-rendered elements.
+ *
+ * Per-style overrides take precedence: set `haloColor`, `selectedColor`, or
+ * `foregroundColor` directly on a `MapStyleConfig` to override these defaults.
+ */
+export const SCHEME_COLORS = {
+  light: {
+    haloColor: '#ffffff',
+    selectedColor: '#0b0c0c',
+    foregroundColor: '#0b0c0c'
+  },
+  dark: {
+    haloColor: '#0b0c0c',
+    selectedColor: '#ffffff',
+    foregroundColor: '#ffffff'
+  }
+}
+
+/**
+ * Resolves the three map overlay colours for the given map style,
+ * falling back to the appropriate scheme defaults when not explicitly set.
+ * Stored in `mapState.mapTheme` so plugins can read resolved values without
+ * importing from core.
+ *
+ * @param {import('../types.js').MapStyleConfig|null} mapStyle
+ * @returns {{ haloColor: string, selectedColor: string, foregroundColor: string }}
+ */
+export const resolveMapTheme = (mapStyle) => {
+  const scheme = SCHEME_COLORS[mapStyle?.mapColorScheme] ?? SCHEME_COLORS.light
+  return {
+    haloColor: mapStyle?.haloColor ?? scheme.haloColor,
+    selectedColor: mapStyle?.selectedColor ?? scheme.selectedColor,
+    foregroundColor: mapStyle?.foregroundColor ?? scheme.foregroundColor
+  }
+}
+
+/**
+ * Converts a mapStyle's overlay colours into CSS custom properties,
+ * falling back to the appropriate scheme defaults when not explicitly set.
+ * Suitable for spreading directly into a React `style` prop.
+ *
+ * @param {import('../types.js').MapStyleConfig|null} mapStyle
+ * @returns {Object} CSS custom property object
+ */
+export const getMapThemeVars = (mapStyle) => {
+  const { haloColor, selectedColor, foregroundColor } = resolveMapTheme(mapStyle)
+  return {
+    '--map-overlay-halo-color': haloColor,
+    '--map-overlay-selected-color': selectedColor,
+    '--map-overlay-foreground-color': foregroundColor
+  }
+}

package/src/config/patternConfig.js

@@ -0,0 +1,16 @@
+/**
+ * Built-in fill pattern SVG content.
+ * Each value is the inner SVG paths only (no wrapper element).
+ * Paths are authored in a 16×16 coordinate space and tile seamlessly.
+ * Use {{foregroundColor}} and {{backgroundColor}} tokens for colour injection.
+ */
+export const BUILT_IN_PATTERNS = {
+  'cross-hatch': '<path d="M0 4.486V3.485h3.5V.001h1v3.484h7.002V.001h1v3.484h3.5v1.001h-3.5v7h3.5v.999h-3.5v3.516h-1v-3.516H4.499v3.516h-1v-3.516H0v-.999h3.5v-7H0zm11.501 0H4.499v7h7.002v-7z" fill="{{foregroundColor}}"/>',
+  'diagonal-cross-hatch': '<path d="M0 8.707V7.293L7.293 0h1.414L16 7.293v1.414L8.707 16H7.293L0 8.707zM.707 8L8 15.293 15.293 8 8 .707.707 8z" fill="{{foregroundColor}}"/>',
+  'forward-diagonal-hatch': '<path d="M16 8.707V7.293L7.293 16h1.414L16 8.707zm-16 0L8.707 0H7.293L0 7.293v1.414z" fill="{{foregroundColor}}"/>',
+  'backward-diagonal-hatch': '<path d="M0 8.707V7.293L8.707 16H7.293L0 8.707zm16 0L7.293 0h1.414L16 7.293v1.414z" fill="{{foregroundColor}}"/>',
+  'horizontal-hatch': '<path d="M0 4.5V3.499h15.999V4.5H0zm0 7h15.999V12.5H0v-1.001z" fill="{{foregroundColor}}"/>',
+  'vertical-hatch': '<path d="M3.501 16.001V0h1v16.001h-1zm7.998 0V0h1v16.001h-1z" fill="{{foregroundColor}}"/>',
+  dot: '<path d="M3.999 2A2 2 0 0 1 6 3.999C6 5.103 5.103 6 3.999 6a2 2 0 0 1-1.999-2.001A2 2 0 0 1 3.999 2zm0 7.999C5.103 10 6 10.897 6 12.001A2 2 0 0 1 3.999 14a2 2 0 0 1-1.999-1.999A2 2 0 0 1 3.999 10zM11.999 2A2 2 0 0 1 14 3.999C14 5.103 13.103 6 11.999 6S10 5.103 10 3.999A2 2 0 0 1 11.999 2zm0 7.999c1.104 0 2.001.897 2.001 2.001A2 2 0 0 1 11.999 14 2 2 0 0 1 10 12.001c0-1.104.897-2.001 1.999-2.001z" fill="{{foregroundColor}}"/>',
+  diamond: '<path d="M4 .465L7.535 4 4 7.535.465 4 4 .465zm0 7.999l3.535 3.535L4 15.535.465 11.999 4 8.464zm8-8l3.535 3.535-3.536 3.536L8.464 4 12 .464zm0 8.001L15.536 12 12 15.536 8.465 12 12 8.465z" fill="{{foregroundColor}}"/>'
+}

package/src/config/symbolConfig.js

@@ -0,0 +1,80 @@
+/**
+ * Default token values applied to all symbols unless overridden at the constructor,
+ * symbol registration, or marker creation level.
+ * Colour values may be a plain string or a map-style-keyed object,
+ * e.g. { outdoor: '#ffffff', dark: '#0b0c0c' }
+ */
+export const symbolDefaults = {
+  symbol: 'pin',
+  backgroundColor: '#ca3535',
+  foregroundColor: '#ffffff',
+  haloWidth: '1',
+  selectedWidth: '6'
+}
+
+/**
+ * Built-in graphic path data strings for use with the `graphic` token.
+ *
+ * Each value is an SVG `d` attribute string in a 16×16 coordinate space,
+ * centred at (8, 8). The built-in symbols (`pin`, `circle`, `square`) apply a
+ * `translate` transform to position this 16×16 area correctly within their
+ * 38×38 viewBox — so graphic path data does not need to account for symbol
+ * positioning.
+ *
+ * @example
+ * markers.add('id', coords, { symbol: 'pin', graphic: graphics.dot })
+ *
+ * @example
+ * // Inline path data (16×16 space, centred at 8,8)
+ * markers.add('id', coords, { symbol: 'pin', graphic: 'M3 8 L8 3 L13 8 L8 13 Z' })
+ */
+export const graphics = {
+  /** Small filled circle — the default graphic for built-in symbols */
+  dot: 'M8 3c-2.76 0-5 2.24-5 5s2.24 5 5 5 5-2.241 5-5-2.24-5-5-5z',
+
+  /** Filled plus / cross shape */
+  cross: 'M6 3H10V6H13V10H10V13H6V10H3V6H6Z',
+
+  /** Filled diamond / rotated square */
+  diamond: 'M8 2L14 8L8 14L2 8Z',
+
+  /** Filled upward-pointing triangle */
+  triangle: 'M8 2L14 14H2Z',
+
+  /** Filled square */
+  square: 'M3 3H13V13H3Z'
+}
+
+// ─── Built-in symbol definitions ─────────────────────────────────────────────
+// Each symbol uses a 38×38 viewBox. SVG templates use {{token}} placeholders
+// resolved at render time by the symbolRegistry.
+
+export const pin = {
+  id: 'pin',
+  viewBox: '0 0 38 38',
+  anchor: [0.5, 0.9], // NOSONAR
+  graphic: graphics.dot,
+  svg: `<path d="M19 33.499c-5.318-5-12-9.509-12-16.998 0-6.583 5.417-12 12-12s12 5.417 12 12c0 7.489-6.682 11.998-12 16.998z" fill="none" stroke="{{selectedColor}}" stroke-width="{{selectedWidth}}"/>
+  <path d="M19 33.499c-5.318-5-12-9.509-12-16.998 0-6.583 5.417-12 12-12s12 5.417 12 12c0 7.489-6.682 11.998-12 16.998z" fill="{{backgroundColor}}" stroke="{{haloColor}}" stroke-width="{{haloWidth}}"/>
+  <g transform="translate(19, 16) scale(0.8) translate(-8, -8)"><path d="{{graphic}}" fill="{{foregroundColor}}"/></g>`
+}
+
+export const circle = {
+  id: 'circle',
+  viewBox: '0 0 38 38',
+  anchor: [0.5, 0.5],
+  graphic: graphics.dot,
+  svg: `<path d="M19 7C12.376 7 7 12.376 7 19s5.376 12 12 12a12.01 12.01 0 0 0 12-12A12.01 12.01 0 0 0 19 7z" fill="none" stroke="{{selectedColor}}" stroke-width="{{selectedWidth}}"/>
+  <path d="M19 7C12.376 7 7 12.376 7 19s5.376 12 12 12a12.01 12.01 0 0 0 12-12A12.01 12.01 0 0 0 19 7z" fill="{{backgroundColor}}" stroke="{{haloColor}}" stroke-width="{{haloWidth}}"/>
+  <g transform="translate(19, 19) scale(0.8) translate(-8, -8)"><path d="{{graphic}}" fill="{{foregroundColor}}"/></g>`
+}
+
+export const square = {
+  id: 'square',
+  viewBox: '0 0 38 38',
+  anchor: [0.5, 0.5],
+  graphic: graphics.dot,
+  svg: `<path d="M28 7a3 3 0 0 1 3 3v18a3 3 0 0 1-3 3H10a3 3 0 0 1-3-3V10a3 3 0 0 1 3-3h18z" fill="none" stroke="{{selectedColor}}" stroke-width="{{selectedWidth}}"/>
+  <path d="M28 7a3 3 0 0 1 3 3v18a3 3 0 0 1-3 3H10a3 3 0 0 1-3-3V10a3 3 0 0 1 3-3h18z" fill="{{backgroundColor}}" stroke="{{haloColor}}" stroke-width="{{haloWidth}}"/>
+  <g transform="translate(19, 19) scale(0.8) translate(-8, -8)"><path d="{{graphic}}" fill="{{foregroundColor}}"/></g>`
+}

package/src/scss/settings/_colors.scss

@@ -35,10 +35,6 @@
     --attributions-foreground-color: #0b0c0c;
     --attributions-background-color: #ffffff80;
 
-    // Map overlays, such as scale bar, target marker etc
-    --map-overlay-foreground-color: #0b0c0c;
-    --map-overlay-halo-color: #ffffff;
-
     // Fixed colours (Dont chnage with dark mode)
     --fixed-foreground-color: #0b0c0c;
 
@@ -78,8 +74,3 @@
     --content-link-color: #ffffff;
 }
 
-// Map color scheme specific overrides
-:root .im-o-app--dark-map {
-  --map-overlay-foreground-color: #ffffff;
-  --map-overlay-halo-color: #0b0c0c;
-}

package/src/services/closeApp.js

@@ -1,13 +1,4 @@
 // src/services/closeApp.js
-import { EVENTS as events } from '../config/events.js'
-
-export function closeApp (mapId, handleExitClick, eventBus) {
-  eventBus.emit(events.MAP_EXIT, { mapId })
-
-  if (history.state?.isBack) {
-    history.back()
-    return
-  }
-
+export function closeApp (_mapId, handleExitClick) {
   handleExitClick()
 }

package/src/services/closeApp.test.js

@@ -1,49 +1,9 @@
 import { closeApp } from './closeApp'
 
 describe('closeApp', () => {
-  let handleExitClickMock
-  let mockEventBus
-
-  beforeEach(() => {
-    handleExitClickMock = jest.fn()
-    mockEventBus = {
-      emit: jest.fn(),
-      on: jest.fn(),
-      off: jest.fn()
-    }
-    jest.spyOn(history, 'back').mockImplementation(() => {})
-  })
-
-  afterEach(() => {
-    jest.restoreAllMocks()
-    jest.clearAllMocks()
-  })
-
-  it('calls history.back() when history.state.isBack is true', () => {
-    Object.defineProperty(history, 'state', {
-      value: { isBack: true },
-      writable: true,
-      configurable: true
-    })
-
-    closeApp('map-123', handleExitClickMock, mockEventBus)
-
-    expect(mockEventBus.emit).toHaveBeenCalledWith('map:exit', { mapId: 'map-123' })
-    expect(history.back).toHaveBeenCalled()
-    expect(handleExitClickMock).not.toHaveBeenCalled()
-  })
-
-  it('calls handleExitClick when history.state.isBack is not true', () => {
-    Object.defineProperty(history, 'state', {
-      value: null,
-      writable: true,
-      configurable: true
-    })
-
-    closeApp('map-123', handleExitClickMock, mockEventBus)
-
-    expect(mockEventBus.emit).toHaveBeenCalledWith('map:exit', { mapId: 'map-123' })
-    expect(history.back).not.toHaveBeenCalled()
+  it('calls handleExitClick', () => {
+    const handleExitClickMock = jest.fn()
+    closeApp('map-123', handleExitClickMock)
     expect(handleExitClickMock).toHaveBeenCalled()
   })
 })

package/src/services/patternRegistry.js

@@ -0,0 +1,40 @@
+import { BUILT_IN_PATTERNS } from '../config/patternConfig.js'
+
+const patterns = new Map()
+
+export const patternRegistry = {
+  /**
+   * Register a named pattern.
+   *
+   * @param {string} id - Unique pattern name (e.g. 'my-hatch')
+   * @param {string} svgContent - Inner SVG path content in a 16×16 coordinate space.
+   *   Use {{foregroundColor}} and {{backgroundColor}} tokens for colour injection.
+   */
+  register (id, svgContent) {
+    patterns.set(id, { id, svgContent })
+  },
+
+  /**
+   * Retrieve a registered pattern by name.
+   *
+   * @param {string} id
+   * @returns {{ id: string, svgContent: string }|undefined}
+   */
+  get (id) {
+    return patterns.get(id)
+  },
+
+  /**
+   * Returns all registered patterns.
+   *
+   * @returns {{ id: string, svgContent: string }[]}
+   */
+  list () {
+    return [...patterns.values()]
+  }
+}
+
+// Seed built-in patterns
+Object.entries(BUILT_IN_PATTERNS).forEach(([id, svgContent]) => {
+  patternRegistry.register(id, svgContent)
+})

package/src/services/patternRegistry.test.js

@@ -0,0 +1,48 @@
+import { patternRegistry } from './patternRegistry.js'
+
+describe('patternRegistry', () => {
+  describe('built-in patterns', () => {
+    test.each([
+      'cross-hatch',
+      'diagonal-cross-hatch',
+      'forward-diagonal-hatch',
+      'backward-diagonal-hatch',
+      'horizontal-hatch',
+      'vertical-hatch',
+      'dot',
+      'diamond'
+    ])('seeds built-in pattern: %s', (id) => {
+      const pattern = patternRegistry.get(id)
+      expect(pattern).toBeDefined()
+      expect(pattern.id).toBe(id)
+      expect(typeof pattern.svgContent).toBe('string')
+      expect(pattern.svgContent.length).toBeGreaterThan(0)
+    })
+  })
+
+  describe('register / get', () => {
+    test('registers a custom pattern and retrieves it by id', () => {
+      patternRegistry.register('test-hatch', '<path d="M0 0L8 8" stroke="{{foreground}}"/>')
+      const result = patternRegistry.get('test-hatch')
+      expect(result).toEqual({ id: 'test-hatch', svgContent: '<path d="M0 0L8 8" stroke="{{foreground}}"/>' })
+    })
+
+    test('returns undefined for an unregistered id', () => {
+      expect(patternRegistry.get('nonexistent-pattern')).toBeUndefined()
+    })
+
+    test('overwrite an existing pattern by re-registering the same id', () => {
+      patternRegistry.register('overwrite-test', '<path d="M0 0"/>')
+      patternRegistry.register('overwrite-test', '<path d="M1 1"/>')
+      expect(patternRegistry.get('overwrite-test').svgContent).toBe('<path d="M1 1"/>')
+    })
+  })
+
+  describe('list', () => {
+    test('returns all registered patterns including built-ins', () => {
+      const all = patternRegistry.list()
+      expect(all.length).toBeGreaterThanOrEqual(8)
+      expect(all.every(p => p.id && p.svgContent)).toBe(true)
+    })
+  })
+})