@labpics/colors 0.9.1 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/pkg/labcolors.js CHANGED
@@ -18,44 +18,30 @@ export class LabColors {
18
18
  wasm.__wbg_labcolors_free(ptr, 0);
19
19
  }
20
20
  /**
21
- * PROTOTYPE — NOT part of the public API (unlisted, `_`-prefixed; may change
22
- * or be removed without notice). Recheck one foreground set against MANY
23
- * background samples in a single call. The reactive controller's worst-case
24
- * loop rechecks the same foregrounds against every sample of a varying
25
- * backdrop; the dominant per-foreground CAM16 forward is background-
26
- * independent, so this shares it across all samples instead of recomputing it
27
- * per `recheckContrast` call.
28
- *
29
- * Returns a flat, background-major `Float64Array`: sample `s`, foreground `i`
30
- * is at `(s * fgHexes.length + i) * 2` (`lc`) and `+1` (`wcagRatio`). The
31
- * values are byte-identical to calling `recheckContrast(bgHexes[s], fgHexes,
32
- * theme)` for each `s`. Wiring the runtime to it is an OWNER decision (it
33
- * changes the controller↔engine call shape); it is measured, not adopted.
34
- * @param {string[]} bg_hexes
35
- * @param {string[]} fg_hexes
36
- * @param {string} theme
37
- * @returns {Float64Array}
21
+ * Exact stable-Glow runtime recheck. Returns whether the point screen
22
+ * layer is a byte-for-byte no-op for every alpha under encoded sRGB8.
23
+ * `adaptTheme` uses this cheap core-owned predicate to detect the only
24
+ * stable determinate/indeterminate class transition without running CAM16
25
+ * or re-solving on every animated-background frame.
26
+ * @param {string} tint_hex
27
+ * @param {string} bg_hex
28
+ * @returns {boolean}
38
29
  */
39
- _recheckContrastMulti(bg_hexes, fg_hexes, theme) {
30
+ isStableGlowPointNoop(tint_hex, bg_hex) {
40
31
  try {
41
32
  const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
42
- const ptr0 = passArrayJsValueToWasm0(bg_hexes, wasm.__wbindgen_export);
33
+ const ptr0 = passStringToWasm0(tint_hex, wasm.__wbindgen_export, wasm.__wbindgen_export2);
43
34
  const len0 = WASM_VECTOR_LEN;
44
- const ptr1 = passArrayJsValueToWasm0(fg_hexes, wasm.__wbindgen_export);
35
+ const ptr1 = passStringToWasm0(bg_hex, wasm.__wbindgen_export, wasm.__wbindgen_export2);
45
36
  const len1 = WASM_VECTOR_LEN;
46
- const ptr2 = passStringToWasm0(theme, wasm.__wbindgen_export, wasm.__wbindgen_export2);
47
- const len2 = WASM_VECTOR_LEN;
48
- wasm.labcolors__recheckContrastMulti(retptr, this.__wbg_ptr, ptr0, len0, ptr1, len1, ptr2, len2);
37
+ wasm.labcolors_isStableGlowPointNoop(retptr, this.__wbg_ptr, ptr0, len0, ptr1, len1);
49
38
  var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
50
39
  var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
51
40
  var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
52
- var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
53
- if (r3) {
54
- throw takeObject(r2);
41
+ if (r2) {
42
+ throw takeObject(r1);
55
43
  }
56
- var v4 = getArrayF64FromWasm0(r0, r1).slice();
57
- wasm.__wbindgen_export4(r0, r1 * 8, 8);
58
- return v4;
44
+ return r0 !== 0;
59
45
  } finally {
60
46
  wasm.__wbindgen_add_to_stack_pointer(16);
61
47
  }
@@ -99,7 +85,12 @@ export class LabColors {
99
85
  }
100
86
  }
101
87
  /**
102
- * Calculate the muddiness score (0 to 1) of an sRGB hex colour.
88
+ * Return the frozen legacy `muddiness` coordinate for an sRGB hex colour.
89
+ *
90
+ * This is an experimental compatibility proxy: it reproduces the historic
91
+ * numeric API, but is not an observer-validated human clean/dirty verdict
92
+ * or a production decision. The legacy identifier is retained only for
93
+ * compatibility.
103
94
  * @param {string} hex
104
95
  * @returns {number}
105
96
  */
@@ -173,6 +164,47 @@ export class LabColors {
173
164
  wasm.__wbindgen_add_to_stack_pointer(16);
174
165
  }
175
166
  }
167
+ /**
168
+ * Recheck one foreground set against MANY background samples in a single
169
+ * call. The reactive controller's worst-case loop rechecks the same
170
+ * foregrounds against every sample of a varying backdrop (gradient / image /
171
+ * bg-blur / glass); the dominant per-foreground CAM16 forward is background-
172
+ * independent, so this shares it across all samples instead of recomputing it
173
+ * per `recheckContrast` call — a measured ~2.6x on the multi-sample recheck.
174
+ *
175
+ * Returns a flat, background-major `Float64Array`: sample `s`, foreground `i`
176
+ * is at `(s * fgHexes.length + i) * 2` (`lc`) and `+1` (`wcagRatio`). The
177
+ * values are byte-identical to calling `recheckContrast(bgHexes[s], fgHexes,
178
+ * theme)` for each `s`.
179
+ * @param {string[]} bg_hexes
180
+ * @param {string[]} fg_hexes
181
+ * @param {string} theme
182
+ * @returns {Float64Array}
183
+ */
184
+ recheckContrastMulti(bg_hexes, fg_hexes, theme) {
185
+ try {
186
+ const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
187
+ const ptr0 = passArrayJsValueToWasm0(bg_hexes, wasm.__wbindgen_export);
188
+ const len0 = WASM_VECTOR_LEN;
189
+ const ptr1 = passArrayJsValueToWasm0(fg_hexes, wasm.__wbindgen_export);
190
+ const len1 = WASM_VECTOR_LEN;
191
+ const ptr2 = passStringToWasm0(theme, wasm.__wbindgen_export, wasm.__wbindgen_export2);
192
+ const len2 = WASM_VECTOR_LEN;
193
+ wasm.labcolors_recheckContrastMulti(retptr, this.__wbg_ptr, ptr0, len0, ptr1, len1, ptr2, len2);
194
+ var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
195
+ var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
196
+ var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
197
+ var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
198
+ if (r3) {
199
+ throw takeObject(r2);
200
+ }
201
+ var v4 = getArrayF64FromWasm0(r0, r1).slice();
202
+ wasm.__wbindgen_export4(r0, r1 * 8, 8);
203
+ return v4;
204
+ } finally {
205
+ wasm.__wbindgen_add_to_stack_pointer(16);
206
+ }
207
+ }
176
208
  /**
177
209
  * Resolve every role for `bgHex` under `theme` (`"light" | "dark" |
178
210
  * "light-ic" | "dark-ic"`).
@@ -180,9 +212,9 @@ export class LabColors {
180
212
  * Returns a `ResolvedTheme` object. Per-role unreachability is part of a
181
213
  * successful result (each role carries its own `kind`); only whole-call
182
214
  * failures reject (no config loaded yet as `config_required`, invalid hex,
183
- * unknown theme, and the by-construction-unreachable oklch serialisation
184
- * failure as `internal_error`) — as a structured `"<code>: <message>"`
185
- * error, never an unwound panic.
215
+ * unknown theme, a core invariant failure, and the by-construction-
216
+ * unreachable oklch serialisation failure as `internal_error`) — as a
217
+ * structured `"<code>: <message>"` error, never an unwound panic.
186
218
  * @param {string} bg_hex
187
219
  * @param {string} theme
188
220
  * @returns {ResolvedTheme}
Binary file
@@ -2,11 +2,12 @@
2
2
  /* eslint-disable */
3
3
  export const memory: WebAssembly.Memory;
4
4
  export const __wbg_labcolors_free: (a: number, b: number) => void;
5
- export const labcolors__recheckContrastMulti: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;
5
+ export const labcolors_isStableGlowPointNoop: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
6
6
  export const labcolors_loadConfig: (a: number, b: number, c: number, d: number) => void;
7
7
  export const labcolors_muddiness: (a: number, b: number, c: number, d: number) => void;
8
8
  export const labcolors_new: () => number;
9
9
  export const labcolors_recheckContrast: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;
10
+ export const labcolors_recheckContrastMulti: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;
10
11
  export const labcolors_resolveTheme: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
11
12
  export const __wbindgen_export: (a: number, b: number) => number;
12
13
  export const __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
package/watch-theme.d.ts CHANGED
@@ -1,57 +1,57 @@
1
- // Public types for the reactive theme runtime.
2
-
3
- import type { LabColors, ResolvedTheme, ThemeName } from "./pkg/labcolors.js";
4
-
5
- export interface WatchThemeOptions {
6
- /** An initialised `LabColors` engine (after `await init()`). */
7
- colors: Pick<LabColors, "resolveTheme">;
8
- /** Theme name. */
9
- theme: ThemeName;
10
- /**
11
- * Explicit effective background, overriding the ancestor-composite. Use a hex
12
- * string or a `() => hex` you sample yourself for image/gradient/blur surfaces
13
- * that have no single readable `background-color`.
14
- */
15
- background?: string | (() => string);
16
- /** Element to write the `--lab-*` variables onto. Defaults to the watched element. */
17
- target?: HTMLElement;
18
- /** Base colour when the ancestor chain is fully translucent. Default `"#FFFFFF"`. */
19
- fallback?: string;
20
- /** Auto-refresh on DOM attribute mutations. Default `true`. */
21
- observe?: boolean;
22
- /** Mutation-observer root. Defaults to the document element. */
23
- root?: Node;
24
- /** Window-like host (for `MutationObserver`). Defaults to `globalThis`. */
25
- win?: Window;
26
- /** Injection seam for the computed style of an element (testing). */
27
- getStyle?: (element: unknown) => { getPropertyValue(property: string): string };
28
- /** Injection seam for an element's parent (testing). */
29
- parentOf?: (element: unknown) => unknown;
30
- }
31
-
32
- export interface WatchController {
33
- /**
34
- * Re-resolve and re-apply if the effective background (or theme) changed;
35
- * `force` re-applies unconditionally. Returns the now-applied result, or the
36
- * cached one when nothing changed.
37
- */
38
- refresh(force?: boolean): ResolvedTheme | null;
39
- /** Switch theme and re-apply. */
40
- setTheme(theme: ThemeName): void;
41
- /** The effective background hex last resolved. */
42
- background(): string;
43
- /** Disconnect observers and stop watching. */
44
- stop(): void;
45
- }
46
-
47
- /**
48
- * Keep an element's `--lab-*` variables in sync with its (effective) background.
49
- *
50
- * Discrete background/theme changes are caught by a `MutationObserver`;
51
- * continuous (animated) backgrounds are driven by calling `refresh()` from a
52
- * `requestAnimationFrame` loop (cheap — re-resolves only on real change).
53
- */
54
- export declare function watchTheme(
55
- element: HTMLElement,
56
- options: WatchThemeOptions,
57
- ): WatchController;
1
+ // Public types for the reactive theme runtime.
2
+
3
+ import type { LabColors, ResolvedTheme, ThemeName } from "./pkg/labcolors.js";
4
+
5
+ export interface WatchThemeOptions {
6
+ /** An initialised `LabColors` engine (after `await init()`). */
7
+ colors: Pick<LabColors, "resolveTheme">;
8
+ /** Theme name. */
9
+ theme: ThemeName;
10
+ /**
11
+ * Explicit effective background, overriding the ancestor-composite. Use a hex
12
+ * string or a `() => hex` you sample yourself for image/gradient/blur surfaces
13
+ * that have no single readable `background-color`.
14
+ */
15
+ background?: string | (() => string);
16
+ /** Element to write the `--lab-*` variables onto. Defaults to the watched element. */
17
+ target?: HTMLElement;
18
+ /** Base colour when the ancestor chain is fully translucent. Default `"#FFFFFF"`. */
19
+ fallback?: string;
20
+ /** Auto-refresh on DOM attribute mutations. Default `true`. */
21
+ observe?: boolean;
22
+ /** Mutation-observer root. Defaults to the document element. */
23
+ root?: Node;
24
+ /** Window-like host (for `MutationObserver`). Defaults to `globalThis`. */
25
+ win?: Window;
26
+ /** Injection seam for the computed style of an element (testing). */
27
+ getStyle?: (element: unknown) => { getPropertyValue(property: string): string };
28
+ /** Injection seam for an element's parent (testing). */
29
+ parentOf?: (element: unknown) => unknown;
30
+ }
31
+
32
+ export interface WatchController {
33
+ /**
34
+ * Re-resolve and re-apply if the effective background (or theme) changed;
35
+ * `force` re-applies unconditionally. Returns the now-applied result, or the
36
+ * cached one when nothing changed.
37
+ */
38
+ refresh(force?: boolean): ResolvedTheme | null;
39
+ /** Switch theme and re-apply. */
40
+ setTheme(theme: ThemeName): void;
41
+ /** The effective background hex last resolved. */
42
+ background(): string;
43
+ /** Disconnect observers and stop watching. */
44
+ stop(): void;
45
+ }
46
+
47
+ /**
48
+ * Keep an element's `--lab-*` variables in sync with its (effective) background.
49
+ *
50
+ * Discrete background/theme changes are caught by a `MutationObserver`;
51
+ * continuous (animated) backgrounds are driven by calling `refresh()` from a
52
+ * `requestAnimationFrame` loop (cheap — re-resolves only on real change).
53
+ */
54
+ export declare function watchTheme(
55
+ element: HTMLElement,
56
+ options: WatchThemeOptions,
57
+ ): WatchController;
package/watch-theme.js CHANGED
@@ -1,144 +1,144 @@
1
- // Reactive theme runtime — zero dependencies.
2
- //
3
- // `applyTheme` writes a resolved theme's `--lab-*` variables onto an element
4
- // once. `watchTheme` closes the loop the css-injection-runtime chapter left
5
- // open: it keeps an element's variables *in sync* with its background. Point it
6
- // at a surface and theming follows the background — the seamless drop-in for a
7
- // design system that re-resolves against a changing background.
8
- //
9
- // It serves both regimes:
10
- // * DISCRETE changes (theme switch, a class/style toggle, DOM reflow) are
11
- // caught automatically by a `MutationObserver` — call once, forget.
12
- // * CONTINUOUS changes (a CSS-animated or per-frame-scripted background that
13
- // never mutates inline style) are driven by the caller calling `refresh()`
14
- // inside its own `requestAnimationFrame` loop. `refresh()` is cheap: it
15
- // re-resolves only when the effective background actually changed, so a
16
- // steady background costs one string compare per frame, not a WASM solve.
17
- //
18
- // The effective background is computed by alpha-compositing ancestors
19
- // (`effective-bg.js`); for surfaces over images/gradients/blur — which have no
20
- // single readable colour — pass an explicit `background` (a hex string or a
21
- // `() => hex` you sample yourself).
22
-
23
- import { applyTheme } from "./apply-theme.js";
24
- import { effectiveBackground } from "./effective-bg.js";
25
-
26
- /**
27
- * @typedef {object} WatchController
28
- * @property {(force?: boolean) => (object | null)} refresh Re-resolve+apply if the
29
- * background (or theme) changed; `force` re-applies unconditionally. Returns the
30
- * `resolveTheme` result that is now applied, or `null` if nothing was applied.
31
- * @property {(theme: string) => void} setTheme Switch theme and re-apply.
32
- * @property {() => string} background The effective background hex last resolved.
33
- * @property {() => void} stop Disconnect observers and stop watching.
34
- */
35
-
36
- /**
37
- * Keep `element`'s `--lab-*` variables in sync with its (effective) background.
38
- *
39
- * @param {*} element The surface to read the background from and (by default)
40
- * write the variables onto.
41
- * @param {object} options
42
- * @param {{ resolveTheme: (bgHex: string, theme: string) => object }} options.colors
43
- * An initialised `LabColors` engine (already `await init()`-ed).
44
- * @param {string} options.theme Theme name (`"light" | "dark" | …`).
45
- * @param {string | (() => string)} [options.background] Explicit effective
46
- * background, overriding the ancestor-composite (use for image/gradient/blur
47
- * surfaces you sample yourself).
48
- * @param {*} [options.target=element] Element to write the variables onto.
49
- * @param {string} [options.fallback="#FFFFFF"] Base for a fully-translucent chain.
50
- * @param {boolean} [options.observe=true] Auto-refresh on DOM attribute mutations.
51
- * @param {*} [options.root] Mutation-observer root (default: the document element).
52
- * @param {*} [options.win=globalThis] Window-like host (for MutationObserver).
53
- * @param {(el:*)=>*} [options.getStyle] Injection seam for `effectiveBackground`.
54
- * @param {(el:*)=>*} [options.parentOf] Injection seam for `effectiveBackground`.
55
- * @returns {WatchController}
56
- */
57
- export function watchTheme(element, options) {
58
- if (!options || typeof options.colors?.resolveTheme !== "function") {
59
- throw new TypeError("watchTheme: options.colors must be an initialised LabColors engine");
60
- }
61
- if (typeof options.theme !== "string") {
62
- throw new TypeError("watchTheme: options.theme must be a theme name string");
63
- }
64
-
65
- const target = options.target ?? element;
66
- const fallback = options.fallback ?? "#FFFFFF";
67
- const win = options.win ?? (typeof globalThis !== "undefined" ? globalThis : undefined);
68
- let theme = options.theme;
69
- let lastBg = null;
70
- let lastTheme = null;
71
- let lastResult = null;
72
-
73
- const readBackground = () => {
74
- const b = options.background;
75
- if (typeof b === "function") return b();
76
- if (typeof b === "string") return b;
77
- return effectiveBackground(element, {
78
- fallback,
79
- getStyle: options.getStyle,
80
- parentOf: options.parentOf,
81
- });
82
- };
83
-
84
- const refresh = (force = false) => {
85
- const bg = readBackground();
86
- if (!force && bg === lastBg && theme === lastTheme) return lastResult;
87
- const result = options.colors.resolveTheme(bg, theme);
88
- applyTheme(target, result);
89
- lastBg = bg;
90
- lastTheme = theme;
91
- lastResult = result;
92
- return result;
93
- };
94
-
95
- // Coalesce a burst of mutations into a single refresh on the next microtask.
96
- let scheduled = false;
97
- let stopped = false;
98
- const schedule = () => {
99
- if (scheduled || stopped) return;
100
- scheduled = true;
101
- Promise.resolve().then(() => {
102
- scheduled = false;
103
- // A `stop()` between scheduling and this microtask must cancel the refresh
104
- // — the watcher is done, no late writes.
105
- if (!stopped) refresh();
106
- });
107
- };
108
-
109
- let observer = null;
110
- if (options.observe !== false && win && typeof win.MutationObserver === "function") {
111
- const root =
112
- options.root ??
113
- (typeof win.document !== "undefined" ? win.document.documentElement : null);
114
- if (root) {
115
- observer = new win.MutationObserver(schedule);
116
- // A background can change on the element OR any ancestor, via inline style
117
- // or a class swap — so watch attribute changes across the subtree.
118
- observer.observe(root, {
119
- subtree: true,
120
- attributes: true,
121
- attributeFilter: ["style", "class"],
122
- });
123
- }
124
- }
125
-
126
- // Apply immediately so the surface is correct on creation.
127
- refresh(true);
128
-
129
- return {
130
- refresh,
131
- setTheme(next) {
132
- theme = next;
133
- refresh();
134
- },
135
- background() {
136
- return lastBg;
137
- },
138
- stop() {
139
- stopped = true;
140
- if (observer) observer.disconnect();
141
- observer = null;
142
- },
143
- };
144
- }
1
+ // Reactive theme runtime — zero dependencies.
2
+ //
3
+ // `applyTheme` writes a resolved theme's `--lab-*` variables onto an element
4
+ // once. `watchTheme` closes the loop the css-injection-runtime chapter left
5
+ // open: it keeps an element's variables *in sync* with its background. Point it
6
+ // at a surface and theming follows the background — the seamless drop-in for a
7
+ // design system that re-resolves against a changing background.
8
+ //
9
+ // It serves both regimes:
10
+ // * DISCRETE changes (theme switch, a class/style toggle, DOM reflow) are
11
+ // caught automatically by a `MutationObserver` — call once, forget.
12
+ // * CONTINUOUS changes (a CSS-animated or per-frame-scripted background that
13
+ // never mutates inline style) are driven by the caller calling `refresh()`
14
+ // inside its own `requestAnimationFrame` loop. `refresh()` is cheap: it
15
+ // re-resolves only when the effective background actually changed, so a
16
+ // steady background costs one string compare per frame, not a WASM solve.
17
+ //
18
+ // The effective background is computed by alpha-compositing ancestors
19
+ // (`effective-bg.js`); for surfaces over images/gradients/blur — which have no
20
+ // single readable colour — pass an explicit `background` (a hex string or a
21
+ // `() => hex` you sample yourself).
22
+
23
+ import { applyTheme } from "./apply-theme.js";
24
+ import { effectiveBackground } from "./effective-bg.js";
25
+
26
+ /**
27
+ * @typedef {object} WatchController
28
+ * @property {(force?: boolean) => (object | null)} refresh Re-resolve+apply if the
29
+ * background (or theme) changed; `force` re-applies unconditionally. Returns the
30
+ * `resolveTheme` result that is now applied, or `null` if nothing was applied.
31
+ * @property {(theme: string) => void} setTheme Switch theme and re-apply.
32
+ * @property {() => string} background The effective background hex last resolved.
33
+ * @property {() => void} stop Disconnect observers and stop watching.
34
+ */
35
+
36
+ /**
37
+ * Keep `element`'s `--lab-*` variables in sync with its (effective) background.
38
+ *
39
+ * @param {*} element The surface to read the background from and (by default)
40
+ * write the variables onto.
41
+ * @param {object} options
42
+ * @param {{ resolveTheme: (bgHex: string, theme: string) => object }} options.colors
43
+ * An initialised `LabColors` engine (already `await init()`-ed).
44
+ * @param {string} options.theme Theme name (`"light" | "dark" | …`).
45
+ * @param {string | (() => string)} [options.background] Explicit effective
46
+ * background, overriding the ancestor-composite (use for image/gradient/blur
47
+ * surfaces you sample yourself).
48
+ * @param {*} [options.target=element] Element to write the variables onto.
49
+ * @param {string} [options.fallback="#FFFFFF"] Base for a fully-translucent chain.
50
+ * @param {boolean} [options.observe=true] Auto-refresh on DOM attribute mutations.
51
+ * @param {*} [options.root] Mutation-observer root (default: the document element).
52
+ * @param {*} [options.win=globalThis] Window-like host (for MutationObserver).
53
+ * @param {(el:*)=>*} [options.getStyle] Injection seam for `effectiveBackground`.
54
+ * @param {(el:*)=>*} [options.parentOf] Injection seam for `effectiveBackground`.
55
+ * @returns {WatchController}
56
+ */
57
+ export function watchTheme(element, options) {
58
+ if (!options || typeof options.colors?.resolveTheme !== "function") {
59
+ throw new TypeError("watchTheme: options.colors must be an initialised LabColors engine");
60
+ }
61
+ if (typeof options.theme !== "string") {
62
+ throw new TypeError("watchTheme: options.theme must be a theme name string");
63
+ }
64
+
65
+ const target = options.target ?? element;
66
+ const fallback = options.fallback ?? "#FFFFFF";
67
+ const win = options.win ?? (typeof globalThis !== "undefined" ? globalThis : undefined);
68
+ let theme = options.theme;
69
+ let lastBg = null;
70
+ let lastTheme = null;
71
+ let lastResult = null;
72
+
73
+ const readBackground = () => {
74
+ const b = options.background;
75
+ if (typeof b === "function") return b();
76
+ if (typeof b === "string") return b;
77
+ return effectiveBackground(element, {
78
+ fallback,
79
+ getStyle: options.getStyle,
80
+ parentOf: options.parentOf,
81
+ });
82
+ };
83
+
84
+ const refresh = (force = false) => {
85
+ const bg = readBackground();
86
+ if (!force && bg === lastBg && theme === lastTheme) return lastResult;
87
+ const result = options.colors.resolveTheme(bg, theme);
88
+ applyTheme(target, result);
89
+ lastBg = bg;
90
+ lastTheme = theme;
91
+ lastResult = result;
92
+ return result;
93
+ };
94
+
95
+ // Coalesce a burst of mutations into a single refresh on the next microtask.
96
+ let scheduled = false;
97
+ let stopped = false;
98
+ const schedule = () => {
99
+ if (scheduled || stopped) return;
100
+ scheduled = true;
101
+ Promise.resolve().then(() => {
102
+ scheduled = false;
103
+ // A `stop()` between scheduling and this microtask must cancel the refresh
104
+ // — the watcher is done, no late writes.
105
+ if (!stopped) refresh();
106
+ });
107
+ };
108
+
109
+ let observer = null;
110
+ if (options.observe !== false && win && typeof win.MutationObserver === "function") {
111
+ const root =
112
+ options.root ??
113
+ (typeof win.document !== "undefined" ? win.document.documentElement : null);
114
+ if (root) {
115
+ observer = new win.MutationObserver(schedule);
116
+ // A background can change on the element OR any ancestor, via inline style
117
+ // or a class swap — so watch attribute changes across the subtree.
118
+ observer.observe(root, {
119
+ subtree: true,
120
+ attributes: true,
121
+ attributeFilter: ["style", "class"],
122
+ });
123
+ }
124
+ }
125
+
126
+ // Apply immediately so the surface is correct on creation.
127
+ refresh(true);
128
+
129
+ return {
130
+ refresh,
131
+ setTheme(next) {
132
+ theme = next;
133
+ refresh();
134
+ },
135
+ background() {
136
+ return lastBg;
137
+ },
138
+ stop() {
139
+ stopped = true;
140
+ if (observer) observer.disconnect();
141
+ observer = null;
142
+ },
143
+ };
144
+ }