react-native-terra-ui 0.7.2 → 0.8.1

package/src/theme/resolve-config.ts

@@ -0,0 +1,406 @@
+/**
+ * Pure theme resolution — normalization, layer processing, derived values and
+ * theme creation. Shared by startup configuration, runtime accent changes and
+ * previews so every consumer sees the same colors for the same input.
+ *
+ * Precedence, identical for both schemes:
+ *
+ *   default tokens → shared → schemes[scheme]
+ *       → generated selected accent → selected accent explicit overrides
+ *
+ * This module must stay free of registry, provider, Unistyles and renderer
+ * imports so `createTerraThemes` works without any native configuration.
+ */
+import {
+  type AccentGenerationContext,
+  type AccentSurfaceRole,
+  type ContrastDiagnostic,
+  checkAccentContrast,
+  GENERATED_ACCENT_ROLES,
+  type GeneratedAccentRole,
+  generateAccentColors,
+  isSupportedAccentSeed,
+} from "#utils/accent-generator";
+import { deepMerge, isPlainObject } from "#utils/deep-merge";
+import { warnContrastDiagnostics } from "./diagnostics";
+import { TerraConfigError } from "./errors";
+import { normalizeTokenOverride } from "./legacy-tokens";
+import {
+  buildRadiusScale,
+  buildSpacingScale,
+  createDefaultThemeSource,
+  finalizeThemeSource,
+  type ThemeSource,
+} from "./theme";
+import type {
+  Accent,
+  AccentSchemeInput,
+  CreateTerraThemesOptions,
+  ElevationKey,
+  Scheme,
+  TerraTheme,
+  TerraThemeInput,
+  TerraThemeOverride,
+  ThemeColor,
+} from "./types";
+
+const SCHEMES: readonly Scheme[] = ["light", "dark"];
+
+const SURFACE_ROLES: readonly AccentSurfaceRole[] = [
+  "surface.canvas",
+  "surface.default",
+  "surface.raised",
+  "surface.sunken",
+];
+
+// ─── Layer state ─────────────────────────────────────────────────────────────
+
+/**
+ * A theme mid-resolution: its source form plus provenance for every elevation
+ * level whose `shadowColor` a layer pinned explicitly. Default shadow colors are
+ * derived, never pinned, so a later `color.shadow` override still moves them.
+ */
+export interface ThemeLayerState {
+  readonly source: ThemeSource;
+  readonly pinnedShadowColors: Readonly<Partial<Record<ElevationKey, string>>>;
+}
+
+/**
+ * Deep-copies an override, dropping `undefined` and `null` leaves (neither is
+ * an override; `null` is not a deletion mechanism). The copy means later
+ * mutation of caller data can never reach a normalized config or a theme.
+ */
+function sanitizeOverride<T>(value: T): T {
+  if (Array.isArray(value)) {
+    return value.map((item) => sanitizeOverride(item)) as unknown as T;
+  }
+  if (isPlainObject(value)) {
+    const out: Record<string, unknown> = {};
+    for (const [key, item] of Object.entries(value)) {
+      if (item === undefined || item === null) continue;
+      out[key] = sanitizeOverride(item);
+    }
+    return out as T;
+  }
+  return value;
+}
+
+/**
+ * Applies one override layer onto `state` and returns the next state. Every
+ * layer — shared, scheme, generated accent, accent overrides, or a full accent
+ * patch — goes through here, so they all follow the same rules:
+ * - deprecated names are normalized within the layer (canonical wins);
+ * - `undefined`/`null` leaves are no override; arrays replace; objects merge;
+ * - `spacing.base` / `radius.base` regenerate their scale, then that layer's
+ *   explicit steps win over the regenerated values;
+ * - `elevation.<level>.shadowColor` pins that level (a later pin replaces an
+ *   earlier one); other elevation fields merge normally.
+ * Inputs are never mutated.
+ */
+export function applyThemeLayer(state: ThemeLayerState, override?: TerraThemeOverride): ThemeLayerState {
+  if (!override) return state;
+  const normalized = normalizeTokenOverride(sanitizeOverride(override));
+  if (!normalized) return state;
+
+  const { radius, spacing, elevation, ...rest } = normalized;
+  let source = deepMerge(state.source, rest as Partial<ThemeSource>);
+  const pinnedShadowColors = { ...state.pinnedShadowColors };
+
+  if (radius) {
+    const { base, ...steps } = radius;
+    if (base !== undefined) {
+      source = { ...source, radius: buildRadiusScale(base) };
+    }
+    source = deepMerge(source, { radius: steps });
+  }
+
+  if (spacing) {
+    const { base, ...steps } = spacing;
+    if (base !== undefined) {
+      source = { ...source, spacing: buildSpacingScale(base) };
+    }
+    source = deepMerge(source, { spacing: steps });
+  }
+
+  if (elevation) {
+    const levels: Partial<ThemeSource["elevation"]> = {};
+    for (const [key, level] of Object.entries(elevation)) {
+      if (!level) continue;
+      const { shadowColor, ...fields } = level;
+      if (shadowColor !== undefined) {
+        pinnedShadowColors[key as ElevationKey] = shadowColor;
+      }
+      levels[key as ElevationKey] = fields as ThemeSource["elevation"][ElevationKey];
+    }
+    source = deepMerge(source, { elevation: levels });
+  }
+
+  return { source, pinnedShadowColors };
+}
+
+// ─── Normalized configuration ────────────────────────────────────────────────
+
+export type NormalizedAccentScheme =
+  | { readonly kind: "none" }
+  | { readonly kind: "seed"; readonly seed: string; readonly overrides?: Partial<ThemeColor> }
+  | { readonly kind: "patch"; readonly patch: TerraThemeOverride };
+
+interface NormalizedAccentEntry {
+  readonly light: NormalizedAccentScheme;
+  readonly dark: NormalizedAccentScheme;
+}
+
+/**
+ * A validated, immutable theme configuration. `base` is the fully layered
+ * `defaults → shared → scheme` state per scheme; every accent selection is
+ * re-resolved from it rather than from a previously resolved accent.
+ */
+export interface NormalizedThemeConfig {
+  readonly accentNames: readonly string[];
+  readonly defaultAccent: string | null;
+  /** @internal Immutable `defaults → shared → scheme` state per scheme. */
+  readonly base: Readonly<Record<Scheme, ThemeLayerState>>;
+  /** @internal Per-accent, per-scheme normalized inputs. */
+  readonly accents: Readonly<Record<string, NormalizedAccentEntry>>;
+}
+
+export function normalizeAccentScheme(
+  input: AccentSchemeInput | undefined,
+  path: string
+): NormalizedAccentScheme {
+  if (input === undefined || input === null) return { kind: "none" };
+
+  if (typeof input === "string") {
+    if (!isSupportedAccentSeed(input)) {
+      throw new TerraConfigError(
+        `${path}.seed`,
+        `Unsupported accent seed ${JSON.stringify(input)}; expected an opaque six-digit hex color (#rrggbb).`
+      );
+    }
+    return { kind: "seed", seed: input.trim() };
+  }
+
+  if (!isPlainObject(input)) {
+    throw new TerraConfigError(
+      path,
+      "Expected a color string, `{ seed, overrides }`, or a theme override object."
+    );
+  }
+
+  if (!("seed" in input)) {
+    return { kind: "patch", patch: sanitizeOverride(input as TerraThemeOverride) };
+  }
+
+  const extra = Object.keys(input).filter((key) => key !== "seed" && key !== "overrides");
+  if (extra.length > 0) {
+    throw new TerraConfigError(
+      path,
+      `A seeded accent accepts only \`seed\` and \`overrides\`; found ${extra
+        .map((key) => `\`${key}\``)
+        .join(
+          ", "
+        )}. Use \`{ seed, overrides: { ... } }\` for color exceptions, or drop \`seed\` for a full theme override.`
+    );
+  }
+
+  const { seed, overrides } = input as { seed: unknown; overrides?: unknown };
+  if (!isSupportedAccentSeed(seed)) {
+    throw new TerraConfigError(
+      `${path}.seed`,
+      `Unsupported accent seed ${JSON.stringify(seed)}; expected an opaque six-digit hex color (#rrggbb).`
+    );
+  }
+  if (overrides !== undefined && !isPlainObject(overrides)) {
+    throw new TerraConfigError(`${path}.overrides`, "Expected a flat semantic color patch object.");
+  }
+
+  return {
+    kind: "seed",
+    seed: seed.trim(),
+    ...(overrides ? { overrides: sanitizeOverride(overrides as Partial<ThemeColor>) } : {}),
+  };
+}
+
+function normalizeAccentEntry(name: string, accent: Accent): NormalizedAccentEntry {
+  const path = `accents.${name}`;
+  if (!isPlainObject(accent)) {
+    throw new TerraConfigError(path, "Expected an object with `light` and/or `dark` scheme inputs.");
+  }
+  return {
+    light: normalizeAccentScheme(accent.light, `${path}.light`),
+    dark: normalizeAccentScheme(accent.dark, `${path}.dark`),
+  };
+}
+
+function assertOverrideObject(value: unknown, path: string): void {
+  if (value !== undefined && !isPlainObject(value)) {
+    throw new TerraConfigError(path, "Expected a theme override object.");
+  }
+}
+
+/**
+ * Validates a theme input and pre-computes the immutable per-scheme base
+ * (`defaults → shared → scheme`). Throws {@link TerraConfigError} for invalid
+ * input — before any state exists to mutate. Never mutates `input` or the
+ * exported defaults.
+ */
+export function normalizeThemeInput(input: TerraThemeInput = {}): NormalizedThemeConfig {
+  if (!isPlainObject(input)) {
+    throw new TerraConfigError("", "Expected a configuration object.");
+  }
+
+  assertOverrideObject(input.shared, "shared");
+  assertOverrideObject(input.schemes, "schemes");
+  assertOverrideObject(input.schemes?.light, "schemes.light");
+  assertOverrideObject(input.schemes?.dark, "schemes.dark");
+  if (input.accents !== undefined && !isPlainObject(input.accents)) {
+    throw new TerraConfigError("accents", "Expected a record of named accents.");
+  }
+
+  const accents: Record<string, NormalizedAccentEntry> = {};
+  for (const [name, accent] of Object.entries(input.accents ?? {})) {
+    accents[name] = normalizeAccentEntry(name, accent);
+  }
+  const accentNames = Object.keys(accents);
+
+  let defaultAccent: string | null = null;
+  if (input.defaultAccent !== undefined && input.defaultAccent !== null) {
+    if (typeof input.defaultAccent !== "string" || !Object.hasOwn(accents, input.defaultAccent)) {
+      throw new TerraConfigError(
+        "defaultAccent",
+        `Unknown accent ${JSON.stringify(input.defaultAccent)}; declared accents: ${
+          accentNames.length > 0 ? accentNames.map((n) => `"${n}"`).join(", ") : "(none)"
+        }.`
+      );
+    }
+    defaultAccent = input.defaultAccent;
+  }
+
+  const base = {} as Record<Scheme, ThemeLayerState>;
+  for (const scheme of SCHEMES) {
+    let state: ThemeLayerState = { source: createDefaultThemeSource(scheme), pinnedShadowColors: {} };
+    state = applyThemeLayer(state, input.shared);
+    state = applyThemeLayer(state, input.schemes?.[scheme]);
+    base[scheme] = state;
+  }
+
+  return { accentNames, defaultAccent, base, accents };
+}
+
+// ─── Resolution ──────────────────────────────────────────────────────────────
+
+export interface ResolvedThemes {
+  themes: Record<Scheme, TerraTheme>;
+  /** Final-colour contrast pairs that fail or cannot be evaluated, across both schemes. */
+  diagnostics: ContrastDiagnostic[];
+}
+
+function getAccentEntry(
+  config: NormalizedThemeConfig,
+  accent: string | null
+): NormalizedAccentEntry | undefined {
+  if (accent === null) return undefined;
+
+  const entry = config.accents[accent];
+  if (entry) return entry;
+
+  throw new TerraConfigError(
+    "accent",
+    `Unknown accent ${JSON.stringify(accent)}; declared accents: ${
+      config.accentNames.length > 0 ? config.accentNames.map((name) => `"${name}"`).join(", ") : "(none)"
+    }.`
+  );
+}
+
+function accentContext(scheme: Scheme, source: ThemeSource): AccentGenerationContext {
+  const surfaces = {} as Record<AccentSurfaceRole, string>;
+  for (const role of SURFACE_ROLES) {
+    surfaces[role] = source.color[role];
+  }
+  return { scheme, surfaces, pressedOpacity: source.opacity.pressed };
+}
+
+function pickGeneratedRoles(color: ThemeSource["color"]): Record<GeneratedAccentRole, string> {
+  const out = {} as Record<GeneratedAccentRole, string>;
+  for (const role of GENERATED_ACCENT_ROLES) {
+    out[role] = color[role];
+  }
+  return out;
+}
+
+function resolveScheme(
+  scheme: Scheme,
+  base: ThemeLayerState,
+  accent: NormalizedAccentScheme
+): { theme: TerraTheme; diagnostics: ContrastDiagnostic[] } {
+  let state = base;
+  let diagnostics: ContrastDiagnostic[] = [];
+
+  if (accent.kind === "patch") {
+    state = applyThemeLayer(state, accent.patch);
+  } else if (accent.kind === "seed") {
+    const context = accentContext(scheme, state.source);
+    const generated = generateAccentColors(accent.seed, context);
+    state = applyThemeLayer(state, { color: generated.colors } as TerraThemeOverride);
+    if (accent.overrides) {
+      state = applyThemeLayer(state, { color: accent.overrides });
+    }
+    // The post-override check is authoritative: it evaluates the colours that
+    // actually ship, so an override that fixes a pair leaves no stale report.
+    diagnostics = checkAccentContrast(
+      pickGeneratedRoles(state.source.color),
+      accentContext(scheme, state.source)
+    );
+  }
+
+  return { theme: finalizeThemeSource(state.source, state.pinnedShadowColors), diagnostics };
+}
+
+/**
+ * Resolves both schemes for `accent` from the config's immutable base. `null`
+ * selects the base themes; an unknown name throws {@link TerraConfigError}.
+ * Returned themes are freshly built and independently owned.
+ */
+export function resolveThemes(config: NormalizedThemeConfig, accent: string | null): ResolvedThemes {
+  const entry = getAccentEntry(config, accent);
+
+  const themes = {} as Record<Scheme, TerraTheme>;
+  const diagnostics: ContrastDiagnostic[][] = [];
+  for (const scheme of SCHEMES) {
+    const resolved = resolveScheme(scheme, config.base[scheme], entry?.[scheme] ?? { kind: "none" });
+    themes[scheme] = resolved.theme;
+    diagnostics.push(resolved.diagnostics);
+  }
+
+  return { themes, diagnostics: diagnostics.flat() };
+}
+
+/** Resolves one scheme without generating and finalizing the other. */
+export function resolveThemeScheme(
+  config: NormalizedThemeConfig,
+  scheme: Scheme,
+  accent: string | null
+): { theme: TerraTheme; diagnostics: ContrastDiagnostic[] } {
+  const entry = getAccentEntry(config, accent);
+  return resolveScheme(scheme, config.base[scheme], entry?.[scheme] ?? { kind: "none" });
+}
+
+/**
+ * Pure theme creation — no Unistyles configuration or registry involved.
+ * `options.accent` omitted → the input's `defaultAccent`; `null` → the base
+ * themes. Invalid input and unknown accents throw {@link TerraConfigError}.
+ * In development, contrast diagnostics are reported once each via
+ * `console.warn`; requested colors are never altered.
+ */
+export function createTerraThemes(
+  input?: TerraThemeInput,
+  options?: CreateTerraThemesOptions
+): Record<Scheme, TerraTheme> {
+  const config = normalizeThemeInput(input);
+  const accent = options?.accent === undefined ? config.defaultAccent : options.accent;
+  const { themes, diagnostics } = resolveThemes(config, accent);
+
+  warnContrastDiagnostics(diagnostics);
+
+  return themes;
+}

package/src/theme/runtime.ts

@@ -1,26 +1,64 @@
-import { UnistylesRuntime } from "react-native-unistyles";
+/**
+ * Runtime selection commands — accent and theme mode — plus the subscribed
+ * selection snapshot consumed by `useTheme()`.
+ *
+ * Every accent change re-resolves both schemes from the installed, immutable
+ * configuration (never from the previously resolved accent), hands them to
+ * Unistyles, and only then publishes the new selection. A rejected or failed
+ * change leaves both the native themes and the published selection untouched.
+ */
+import { warnContrastDiagnostics } from "./diagnostics";
+import { resolveThemes } from "./resolve-config";
+import { getInstalledConfig, getThemeSelection, publishThemeSelection } from "./selection-store";
+import type { Scheme, ThemeMode } from "./types";
+import { applyMode, updateThemes } from "./unistyles-adapter";
 
-import { getRegistry, resolveTheme } from "./registry";
-import type { Scheme } from "./types";
+export type { ThemeSelection } from "./selection-store";
+export { getThemeSelection, subscribeThemeSelection } from "./selection-store";
 
-/** Apply a named accent at runtime by updating both registered themes. */
-export function applyAccent(name: string): void {
-  const registry = getRegistry();
-  if (!registry.accents[name]) {
+/**
+ * Apply a registered accent (`null` restores the base themes) by updating both
+ * registered themes. An unknown name warns in development and changes nothing.
+ *
+ * If the native update fails part-way (see `updateThemes` in the adapter), the
+ * error propagates and the previous selection stays published; calling
+ * `applyAccent(getCurrentAccent() ?? null)` rewrites both themes.
+ */
+export function applyAccent(name: string | null): void {
+  const config = getInstalledConfig();
+  if (name !== null && !config.accentNames.includes(name)) {
     if (__DEV__) {
       console.warn(`[react-native-terra-ui] Unknown accent "${name}".`);
     }
     return;
   }
-  registry.currentAccent = name;
-  UnistylesRuntime.updateTheme("light", () => resolveTheme("light", name));
-  UnistylesRuntime.updateTheme("dark", () => resolveTheme("dark", name));
+
+  const { themes, diagnostics } = resolveThemes(config, name);
+  updateThemes(themes);
+  publishThemeSelection({ accent: name ?? undefined });
+  warnContrastDiagnostics(diagnostics);
+}
+
+/** The applied accent name, or `undefined` for the base themes. */
+export const getCurrentAccent = (): string | undefined => getThemeSelection().accent;
+
+/**
+ * Choose how the active scheme is selected: `system` follows the OS appearance;
+ * `light` / `dark` pin a scheme until the next call.
+ */
+export function setThemeMode(mode: ThemeMode): void {
+  applyMode(mode);
+  publishThemeSelection({ mode });
 }
 
-export const getCurrentAccent = (): string | undefined => getRegistry().currentAccent;
+/** The current theme mode. A system appearance change does not change it. */
+export const getThemeMode = (): ThemeMode => getThemeSelection().mode;
 
-/** Switch the active color scheme, disabling adaptive (system) theming. */
+/**
+ * Pin the active color scheme, disabling adaptive (system) theming.
+ * Compatibility wrapper for `setThemeMode(scheme)`; use `setThemeMode("system")`
+ * to return to the OS preference.
+ */
 export function applyScheme(scheme: Scheme): void {
-  UnistylesRuntime.setAdaptiveThemes(false);
-  UnistylesRuntime.setTheme(scheme);
+  setThemeMode(scheme);
 }

package/src/theme/screen-margin.ts

@@ -1,26 +1,7 @@
-import type { UnistylesBreakpoints } from "react-native-unistyles";
+import type { ResolvedScreenPadding } from "./screen-padding";
+import { resolveScreenPadding } from "./screen-padding";
 
-import { resolveBreakpointValue } from "./breakpoints";
-import type { TerraTheme } from "./types";
-
-export interface ResolvedScreenMargin {
-  x: number;
-  y: number;
-}
-
-/**
- * Resolves both axes of `theme.layout.screen.margin` for the current runtime
- * breakpoint in one call — nearly every consumer needs both axes, so this
- * saves calling `resolveBreakpointValue` twice. Call inside a
- * `StyleSheet.create` factory (passing `rt.breakpoint`) so the result stays
- * reactive to breakpoint changes; outside one, use {@link useScreenMargin}.
- */
-export function resolveScreenMargin(
-  theme: TerraTheme,
-  breakpoint: keyof UnistylesBreakpoints | undefined
-): ResolvedScreenMargin {
-  return {
-    x: resolveBreakpointValue(theme.layout.screen.margin.x, breakpoint),
-    y: resolveBreakpointValue(theme.layout.screen.margin.y, breakpoint),
-  };
-}
+/** @deprecated Use ResolvedScreenPadding. */
+export type ResolvedScreenMargin = ResolvedScreenPadding;
+/** @deprecated Use resolveScreenPadding. */
+export const resolveScreenMargin = resolveScreenPadding;

package/src/theme/screen-padding.ts

@@ -0,0 +1,26 @@
+import type { UnistylesBreakpoints } from "react-native-unistyles";
+
+import { resolveBreakpointValue } from "./breakpoints";
+import type { TerraTheme } from "./types";
+
+export interface ResolvedScreenPadding {
+  x: number;
+  y: number;
+}
+
+/**
+ * Resolves both axes of `theme.layout.screen.padding` for the current runtime
+ * breakpoint in one call — nearly every consumer needs both axes, so this
+ * saves calling `resolveBreakpointValue` twice. Call inside a
+ * `StyleSheet.create` factory (passing `rt.breakpoint`) so the result stays
+ * reactive to breakpoint changes; outside one, use {@link useScreenPadding}.
+ */
+export function resolveScreenPadding(
+  theme: TerraTheme,
+  breakpoint: keyof UnistylesBreakpoints | undefined
+): ResolvedScreenPadding {
+  return {
+    x: resolveBreakpointValue(theme.layout.screen.padding.x, breakpoint),
+    y: resolveBreakpointValue(theme.layout.screen.padding.y, breakpoint),
+  };
+}

package/src/theme/selection-store.ts

@@ -0,0 +1,76 @@
+/**
+ * Internal runtime state shared by `registry.ts` (installation) and
+ * `runtime.ts` (selection commands). Lives in its own module so neither of
+ * those has to import the other.
+ *
+ * Holds two things, both private to `theme/`:
+ * - the installed {@link NormalizedThemeConfig} — immutable; every accent
+ *   selection is re-resolved from it, never layered on a previous result;
+ * - the selection snapshot (`accent`, `mode`) behind a `useSyncExternalStore`
+ *   compatible subscribe/get pair. The snapshot object keeps its identity until
+ *   a value actually changes, so subscribers only re-render on real changes.
+ *
+ * Nothing here touches Unistyles. Callers publish *after* native work succeeds.
+ */
+import { type NormalizedThemeConfig, normalizeThemeInput } from "./resolve-config";
+import type { ThemeMode } from "./types";
+
+// ─── Installed configuration ─────────────────────────────────────────────────
+
+/**
+ * Before any configure call the built-in defaults are "installed", matching
+ * the previous behaviour where `resolveTheme` worked pre-configuration.
+ */
+let installedConfig: NormalizedThemeConfig = normalizeThemeInput({});
+
+/** @internal Read-only handle on the installed config. */
+export const getInstalledConfig = (): NormalizedThemeConfig => installedConfig;
+
+/** @internal Replaces the installed config; only `registry.ts` should call this. */
+export function setInstalledConfig(config: NormalizedThemeConfig): void {
+  installedConfig = config;
+}
+
+// ─── Selection snapshot ──────────────────────────────────────────────────────
+
+/** The current runtime selection: which accent is applied and how the scheme is chosen. */
+export interface ThemeSelection {
+  /** Applied accent name, or `undefined` for the base themes. */
+  readonly accent: string | undefined;
+  /** `system` follows the OS appearance; `light` / `dark` pin a scheme. */
+  readonly mode: ThemeMode;
+}
+
+let selection: ThemeSelection = Object.freeze({ accent: undefined, mode: "system" as ThemeMode });
+
+const listeners = new Set<() => void>();
+
+/**
+ * Current selection snapshot. Stable identity: the same object is returned
+ * until {@link publishThemeSelection} commits a real change, which makes it a
+ * valid `getSnapshot` for `useSyncExternalStore`.
+ */
+export const getThemeSelection = (): ThemeSelection => selection;
+
+/** Subscribe to selection changes. Returns the unsubscribe function. */
+export function subscribeThemeSelection(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/**
+ * @internal Commits a (partial) selection change and notifies subscribers.
+ * A no-op — same snapshot identity, no notification — when nothing changed.
+ */
+export function publishThemeSelection(next: Partial<ThemeSelection>): void {
+  const accent = "accent" in next ? next.accent : selection.accent;
+  const mode = next.mode ?? selection.mode;
+  if (accent === selection.accent && mode === selection.mode) return;
+
+  selection = Object.freeze({ accent, mode });
+  for (const listener of listeners) {
+    listener();
+  }
+}