@pantoken/scope 0.3.11

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Danny Wahl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { _ as THEME_ATTR, a as createScope, b as schemeClass, c as resolveScheme, d as BOUNDARY_CLASS, f as COLOR_ATTR, g as SCOPE_ATTRS, h as SCHEME_ATTR, i as connectScope, l as resolveScope, m as INSTANCE_ATTR, n as ensureProperties, o as getScope, p as DEFAULT_INSTANCE, r as hasProperties, s as resolveInstance, t as observeScope, u as BOUNDARY_ATTR, v as colorClass, x as themeClass, y as isScheme } from "./src-Daa7KXHA.mjs";
+export { BOUNDARY_ATTR, BOUNDARY_CLASS, COLOR_ATTR, DEFAULT_INSTANCE, INSTANCE_ATTR, SCHEME_ATTR, SCOPE_ATTRS, THEME_ATTR, colorClass, connectScope, createScope, ensureProperties, getScope, hasProperties, isScheme, observeScope, resolveInstance, resolveScheme, resolveScope, schemeClass, themeClass };

package/dist/scope.d.mts

@@ -0,0 +1,179 @@
+import { BOUNDARY_ATTR, BOUNDARY_CLASS, COLOR_ATTR, INSTANCE_ATTR, SCHEME_ATTR, SCOPE_ATTRS, Scheme, Scheme as Scheme$1, THEME_ATTR, colorClass, isScheme, schemeClass, themeClass } from "@pantoken/utils/scope";
+//#region src/contract.d.ts
+/** The resolvable state of a scope. Every field is optional — an unset field inherits. */
+interface ScopeConfig {
+  /** Theme key, e.g. `"rebrand"`. Matched by `[data-pantoken-theme="…"]`. */
+  theme?: string;
+  /** Pinned color scheme. Omit to follow the OS preference. */
+  scheme?: Scheme$1;
+  /** Custom brand color key. */
+  color?: string;
+  /** Identifier of the pantoken instance that owns this scope. */
+  instanceId?: string;
+}
+/** A {@link ScopeConfig} resolved against the DOM, plus where each part came from. */
+interface ResolvedScope extends ScopeConfig {
+  /** The nearest element that declared any scope attribute, or `null` when none did. */
+  element: Element | null;
+  /** True when resolution stopped at a `data-pantoken-boundary` element. */
+  bounded: boolean;
+}
+/** The default instance id, used when a scope does not name one. */
+export declare const DEFAULT_INSTANCE = "pantoken";
+//#endregion
+//#region src/resolve.d.ts
+/**
+ * Resolve the scope in effect for `start` by walking up its ancestors.
+ *
+ * @param start - The element to resolve for. Its own attributes participate.
+ * @returns The {@link ResolvedScope}; fields no ancestor declared are left `undefined`.
+ *
+ * @example
+ * ```ts
+ * import { resolveScope } from "@pantoken/scope";
+ *
+ * // <div data-pantoken-theme="canvas"><span id="x"></span></div>
+ * resolveScope(document.querySelector("#x")!).theme; // "canvas"
+ * ```
+ */
+export declare function resolveScope(start: Element | null): ResolvedScope;
+/**
+ * The instance that owns `start`, falling back to {@link DEFAULT_INSTANCE}.
+ *
+ * Use this to decide whether an event or message is yours before acting on it.
+ */
+export declare function resolveInstance(start: Element | null): string;
+/**
+ * The effective color scheme for `start`: an explicit pin if any ancestor set one, otherwise the
+ * `color-scheme` the element actually computes to, otherwise the OS preference.
+ *
+ * Never reads `document.documentElement` — that global read is exactly what desynchronises two
+ * instances on one page.
+ */
+export declare function resolveScheme(start: Element | null): Scheme;
+//#endregion
+//#region src/scope.d.ts
+/** The message envelope exchanged between a scope and its attached frames. */
+interface ScopeMessage extends ScopeConfig {
+  type: "pantoken-scope" | "pantoken-scope-request";
+  instanceId: string;
+}
+/** Options for {@link createScope}. */
+interface CreateScopeOptions extends ScopeConfig {
+  /**
+   * Identifier distinguishing this pantoken instance from others on the page. Scopes, storage keys,
+   * and frame messages are all keyed by it.
+   */
+  instanceId?: string;
+  /**
+   * Stop ancestor resolution at this element, so nothing outside can theme what is inside. Use for
+   * a preview pane that must not inherit the surrounding app's theme.
+   */
+  boundary?: boolean;
+  /** Persist and restore state. Pass `false` to keep the scope in-memory only (default `true`). */
+  persist?: boolean;
+  /** Storage backend (default `localStorage`, silently skipped when unavailable). */
+  storage?: Pick<Storage, "getItem" | "setItem"> | null;
+}
+/** A live scope bound to one element. */
+interface PantokenScope {
+  /** The element carrying the scope attributes. */
+  readonly element: HTMLElement;
+  /** The instance this scope belongs to. */
+  readonly instanceId: string;
+  /** The scope's own configuration — what it declares, not what it inherits. */
+  get(): ScopeConfig;
+  /** Merge a partial configuration in. Pass `null` for a field to clear it and inherit again. */
+  set(patch: Partial<Record<keyof ScopeConfig, string | null | undefined>>): void;
+  /** Resolve the effective scope for a descendant (defaults to this scope's own element). */
+  resolve(el?: Element): ResolvedScope;
+  /** Send this scope's state to `frame` and keep it in sync. Returns a detach function. */
+  attachFrame(frame: HTMLIFrameElement): () => void;
+  /** Observe changes. Returns an unsubscribe function. */
+  subscribe(listener: (config: ScopeConfig) => void): () => void;
+  /** Remove the attributes, detach frames, and unregister. */
+  destroy(): void;
+}
+/** The scope registered for `instanceId` in `doc`, if any. */
+export declare function getScope(instanceId?: string, doc?: Document): PantokenScope | undefined;
+/**
+ * Create a scope rooted at `element`.
+ *
+ * @example Two independent themes on one page
+ * ```ts
+ * import { createScope } from "@pantoken/scope";
+ *
+ * createScope(document.querySelector("#app")!, { theme: "rebrand", scheme: "dark" });
+ * createScope(document.querySelector("#preview")!, {
+ *   instanceId: "preview",
+ *   theme: "canvas",
+ *   scheme: "light",
+ *   boundary: true,
+ * });
+ * ```
+ */
+export declare function createScope(element: HTMLElement, options?: CreateScopeOptions): PantokenScope;
+/** Options for {@link connectScope}. */
+interface ConnectScopeOptions {
+  /** The instance to accept messages for (default {@link DEFAULT_INSTANCE}). */
+  instanceId?: string;
+  /** The element to apply received state to (default `document.documentElement`). */
+  element?: HTMLElement;
+  /** The window to talk to (default `window.parent`). */
+  host?: Window | null;
+  /** The origin the host must have. Pass `"*"` only for an opaque-origin `srcdoc` document. */
+  hostOrigin?: string;
+  /** Called after each applied update. */
+  onChange?: (config: ScopeConfig) => void;
+}
+/**
+ * Run inside a frame: ask the host page's scope for its state and follow it.
+ *
+ * The frame gets its own scope element, so it can be told to render a different theme or scheme than
+ * the host — it is not inheriting ambiently.
+ *
+ * @returns A disconnect function.
+ */
+export declare function connectScope(options?: ConnectScopeOptions): () => void;
+//#endregion
+//#region src/inject.d.ts
+/**
+ * Inject `css` into `doc` once. A second call with the same `id` does nothing, whichever instance
+ * makes it.
+ *
+ * @param css - The registrations sheet, e.g. `@pantoken/css/properties.css`.
+ * @param options - `id` distinguishes unrelated sheets; `doc` defaults to the current document.
+ * @returns `true` when this call performed the injection.
+ *
+ * @example
+ * ```ts
+ * import { ensureProperties } from "@pantoken/scope";
+ * import properties from "@pantoken/css/properties.css?inline";
+ *
+ * ensureProperties(properties);
+ * ```
+ */
+export declare function ensureProperties(css: string, options?: {
+  id?: string;
+  doc?: Document;
+}): boolean;
+/** True when a registrations sheet with `id` is already present in `doc`. */
+export declare function hasProperties(id?: string, doc?: Document): boolean;
+//#endregion
+//#region src/observe.d.ts
+/**
+ * Call `listener` whenever the scope resolved for `target` changes, including when an ancestor's
+ * attributes change.
+ *
+ * @returns A stop function.
+ *
+ * @example
+ * ```ts
+ * import { observeScope } from "@pantoken/scope";
+ *
+ * const stop = observeScope(el, (scope) => render(scope.theme, scope.scheme));
+ * ```
+ */
+export declare function observeScope(target: Element, listener: (scope: ResolvedScope) => void): () => void;
+//#endregion
+export { BOUNDARY_ATTR, BOUNDARY_CLASS, COLOR_ATTR, type ConnectScopeOptions, type CreateScopeOptions, INSTANCE_ATTR, type PantokenScope, type ResolvedScope, SCHEME_ATTR, SCOPE_ATTRS, type Scheme, type ScopeConfig, type ScopeMessage, THEME_ATTR, colorClass, isScheme, schemeClass, themeClass };

package/dist/scope.mjs

@@ -0,0 +1,2 @@
+import { _ as THEME_ATTR, a as createScope, b as schemeClass, c as resolveScheme, d as BOUNDARY_CLASS, f as COLOR_ATTR, g as SCOPE_ATTRS, h as SCHEME_ATTR, i as connectScope, l as resolveScope, m as INSTANCE_ATTR, n as ensureProperties, o as getScope, p as DEFAULT_INSTANCE, r as hasProperties, s as resolveInstance, t as observeScope, u as BOUNDARY_ATTR, v as colorClass, x as themeClass, y as isScheme } from "./src-Daa7KXHA.mjs";
+export { BOUNDARY_ATTR, BOUNDARY_CLASS, COLOR_ATTR, DEFAULT_INSTANCE, INSTANCE_ATTR, SCHEME_ATTR, SCOPE_ATTRS, THEME_ATTR, colorClass, connectScope, createScope, ensureProperties, getScope, hasProperties, isScheme, observeScope, resolveInstance, resolveScheme, resolveScope, schemeClass, themeClass };

package/dist/src-Daa7KXHA.mjs

@@ -0,0 +1,416 @@
+import { BOUNDARY_ATTR, BOUNDARY_CLASS, COLOR_ATTR, INSTANCE_ATTR, SCHEME_ATTR, SCOPE_ATTRS, THEME_ATTR, colorClass, isScheme, schemeClass, themeClass } from "@pantoken/utils/scope";
+//#region src/contract.ts
+/** The default instance id, used when a scope does not name one. */
+const DEFAULT_INSTANCE = "pantoken";
+//#endregion
+//#region src/resolve.ts
+/**
+* Ancestor resolution — the "auto-detect inheritance" half of multi-instance support.
+*
+* Each scope attribute resolves independently: a subtree can override the color scheme while still
+* inheriting the theme from an ancestor, which is what the CSS does too (separate cascade layers,
+* separate attributes). Resolution stops at the first `data-pantoken-boundary` element, and never
+* crosses a shadow root — a shadow root is an implicit boundary.
+*
+* @module
+*/
+function attr(el, name) {
+	const value = el.getAttribute(name);
+	return value === null || value === "" ? void 0 : value;
+}
+/**
+* The value a `.--pantoken-<kind>-<value>` class encodes, if the element carries one.
+*
+* The emitter pairs every scope attribute with a class twin for hosts that strip `data-*`, so
+* resolution has to read both or the runtime and the stylesheet disagree about what's in effect.
+*/
+function fromClass(el, kind) {
+	const prefix = `--pantoken-${kind}-`;
+	for (const cls of el.classList) if (cls.startsWith(prefix) && cls.length > prefix.length) return cls.slice(prefix.length);
+}
+const readTheme = (el) => attr(el, THEME_ATTR) ?? fromClass(el, "theme");
+const readColor = (el) => attr(el, COLOR_ATTR) ?? fromClass(el, "color");
+function readScheme(el) {
+	const value = attr(el, SCHEME_ATTR) ?? fromClass(el, "scheme");
+	return isScheme(value) ? value : void 0;
+}
+const isBoundary = (el) => el.hasAttribute(BOUNDARY_ATTR) || el.classList.contains(BOUNDARY_CLASS);
+/**
+* Resolve the scope in effect for `start` by walking up its ancestors.
+*
+* @param start - The element to resolve for. Its own attributes participate.
+* @returns The {@link ResolvedScope}; fields no ancestor declared are left `undefined`.
+*
+* @example
+* ```ts
+* import { resolveScope } from "@pantoken/scope";
+*
+* // <div data-pantoken-theme="canvas"><span id="x"></span></div>
+* resolveScope(document.querySelector("#x")!).theme; // "canvas"
+* ```
+*/
+function resolveScope(start) {
+	let theme;
+	let scheme;
+	let color;
+	let instanceId;
+	let element = null;
+	let bounded = false;
+	for (let el = start; el; el = el.parentElement) {
+		let declared = false;
+		const nextTheme = readTheme(el);
+		if (theme === void 0 && nextTheme !== void 0) {
+			theme = nextTheme;
+			declared = true;
+		}
+		const nextScheme = readScheme(el);
+		if (scheme === void 0 && nextScheme !== void 0) {
+			scheme = nextScheme;
+			declared = true;
+		}
+		const nextColor = readColor(el);
+		if (color === void 0 && nextColor !== void 0) {
+			color = nextColor;
+			declared = true;
+		}
+		const nextInstance = attr(el, INSTANCE_ATTR);
+		if (instanceId === void 0 && nextInstance !== void 0) {
+			instanceId = nextInstance;
+			declared = true;
+		}
+		if (declared && element === null) element = el;
+		if (isBoundary(el)) {
+			bounded = true;
+			break;
+		}
+	}
+	return {
+		theme,
+		scheme,
+		color,
+		instanceId,
+		element,
+		bounded
+	};
+}
+/**
+* The instance that owns `start`, falling back to {@link DEFAULT_INSTANCE}.
+*
+* Use this to decide whether an event or message is yours before acting on it.
+*/
+function resolveInstance(start) {
+	return resolveScope(start).instanceId ?? "pantoken";
+}
+/**
+* The effective color scheme for `start`: an explicit pin if any ancestor set one, otherwise the
+* `color-scheme` the element actually computes to, otherwise the OS preference.
+*
+* Never reads `document.documentElement` — that global read is exactly what desynchronises two
+* instances on one page.
+*/
+function resolveScheme(start) {
+	const pinned = resolveScope(start).scheme;
+	if (pinned) return pinned;
+	const view = start?.ownerDocument?.defaultView;
+	if (start && view) {
+		const computed = view.getComputedStyle(start).colorScheme;
+		if (computed === "dark") return "dark";
+		if (computed === "light") return "light";
+	}
+	return view?.matchMedia?.("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+}
+//#endregion
+//#region src/scope.ts
+/**
+* Scope instances — the "manual config to avoid collision" half of multi-instance support.
+*
+* A scope owns one element and writes the `data-pantoken-*` attributes onto it. Everything below
+* that element resolves to it; siblings are independent. State is persisted under a key namespaced
+* by instance id, and child frames are messaged individually after opting in via
+* {@link PantokenScope.attachFrame} — never by sweeping the whole document for iframes.
+*
+* @module
+*/
+const registries = /* @__PURE__ */ new WeakMap();
+function registryFor(doc) {
+	let registry = registries.get(doc);
+	if (!registry) {
+		registry = /* @__PURE__ */ new Map();
+		registries.set(doc, registry);
+	}
+	return registry;
+}
+/** The scope registered for `instanceId` in `doc`, if any. */
+function getScope(instanceId = DEFAULT_INSTANCE, doc = document) {
+	return registryFor(doc).get(instanceId);
+}
+const storageKey = (instanceId, field) => `pantoken:${instanceId}:${field}`;
+function defaultStorage() {
+	try {
+		return typeof localStorage === "undefined" ? null : localStorage;
+	} catch {
+		return null;
+	}
+}
+/**
+* The origin to post to for `frame`. A `srcdoc` frame has an opaque origin that can only be
+* addressed as `"*"`; anything with a real `src` gets its concrete origin so the message cannot
+* leak to a navigated-away document.
+*/
+function frameOrigin(frame) {
+	if (!frame.hasAttribute("src")) return "*";
+	try {
+		return new URL(frame.src, frame.ownerDocument.location.href).origin;
+	} catch {
+		return frame.ownerDocument.location.origin;
+	}
+}
+const FIELDS = {
+	theme: THEME_ATTR,
+	scheme: SCHEME_ATTR,
+	color: COLOR_ATTR
+};
+/**
+* Create a scope rooted at `element`.
+*
+* @example Two independent themes on one page
+* ```ts
+* import { createScope } from "@pantoken/scope";
+*
+* createScope(document.querySelector("#app")!, { theme: "rebrand", scheme: "dark" });
+* createScope(document.querySelector("#preview")!, {
+*   instanceId: "preview",
+*   theme: "canvas",
+*   scheme: "light",
+*   boundary: true,
+* });
+* ```
+*/
+function createScope(element, options = {}) {
+	const { instanceId = DEFAULT_INSTANCE, boundary = false, persist = true, storage = defaultStorage(), ...initial } = options;
+	const doc = element.ownerDocument;
+	const registry = registryFor(doc);
+	registry.get(instanceId)?.destroy();
+	const read = (field) => {
+		if (!persist || !storage) return void 0;
+		try {
+			return storage.getItem(storageKey(instanceId, field)) ?? void 0;
+		} catch {
+			return;
+		}
+	};
+	const config = {
+		theme: initial.theme ?? read("theme"),
+		scheme: initial.scheme ?? (isScheme(read("scheme")) ? read("scheme") : void 0),
+		color: initial.color ?? read("color"),
+		instanceId
+	};
+	const listeners = /* @__PURE__ */ new Set();
+	const frames = /* @__PURE__ */ new Set();
+	let destroyed = false;
+	const write = () => {
+		element.setAttribute(INSTANCE_ATTR, instanceId);
+		if (boundary) element.setAttribute(BOUNDARY_ATTR, "");
+		for (const [field, attribute] of Object.entries(FIELDS)) {
+			const value = config[field];
+			if (value === void 0) element.removeAttribute(attribute);
+			else element.setAttribute(attribute, value);
+		}
+		element.style.colorScheme = config.scheme ?? "";
+	};
+	const persistConfig = () => {
+		if (!persist || !storage) return;
+		for (const field of Object.keys(FIELDS)) try {
+			storage.setItem(storageKey(instanceId, field), config[field] ?? "");
+		} catch {}
+	};
+	const post = (frame) => {
+		const message = {
+			type: "pantoken-scope",
+			instanceId,
+			...config
+		};
+		frame.contentWindow?.postMessage(message, frameOrigin(frame));
+	};
+	const broadcast = () => {
+		for (const frame of frames) post(frame);
+		for (const listener of listeners) listener({ ...config });
+	};
+	const onFrameRequest = (event) => {
+		const data = event.data;
+		if (data?.type !== "pantoken-scope-request") return;
+		if (data.instanceId !== instanceId) return;
+		for (const frame of frames) if (frame.contentWindow === event.source) post(frame);
+	};
+	doc.defaultView?.addEventListener("message", onFrameRequest);
+	write();
+	persistConfig();
+	const scope = {
+		element,
+		instanceId,
+		get: () => ({ ...config }),
+		set(patch) {
+			if (destroyed) return;
+			for (const field of Object.keys(FIELDS)) {
+				if (!(field in patch)) continue;
+				const value = patch[field];
+				if (value === null || value === void 0) delete config[field];
+				else if (field === "scheme") config.scheme = isScheme(value) ? value : void 0;
+				else config[field] = value;
+			}
+			write();
+			persistConfig();
+			broadcast();
+		},
+		resolve: (el = element) => resolveScope(el),
+		attachFrame(frame) {
+			frames.add(frame);
+			post(frame);
+			return () => {
+				frames.delete(frame);
+			};
+		},
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		destroy() {
+			if (destroyed) return;
+			destroyed = true;
+			doc.defaultView?.removeEventListener("message", onFrameRequest);
+			frames.clear();
+			listeners.clear();
+			for (const attribute of [
+				...Object.values(FIELDS),
+				INSTANCE_ATTR,
+				BOUNDARY_ATTR
+			]) element.removeAttribute(attribute);
+			element.style.colorScheme = "";
+			if (registry.get(instanceId) === scope) registry.delete(instanceId);
+		}
+	};
+	registry.set(instanceId, scope);
+	return scope;
+}
+/**
+* Run inside a frame: ask the host page's scope for its state and follow it.
+*
+* The frame gets its own scope element, so it can be told to render a different theme or scheme than
+* the host — it is not inheriting ambiently.
+*
+* @returns A disconnect function.
+*/
+function connectScope(options = {}) {
+	const { instanceId = DEFAULT_INSTANCE, element = document.documentElement, host = window.parent, hostOrigin, onChange } = options;
+	const local = createScope(element, {
+		instanceId,
+		persist: false
+	});
+	const onMessage = (event) => {
+		if (host && event.source !== host) return;
+		if (hostOrigin && hostOrigin !== "*" && event.origin !== hostOrigin) return;
+		const data = event.data;
+		if (data?.type !== "pantoken-scope" || data.instanceId !== instanceId) return;
+		local.set({
+			theme: data.theme,
+			scheme: data.scheme,
+			color: data.color
+		});
+		onChange?.(local.get());
+	};
+	window.addEventListener("message", onMessage);
+	const request = {
+		type: "pantoken-scope-request",
+		instanceId
+	};
+	host?.postMessage(request, hostOrigin ?? "*");
+	return () => {
+		window.removeEventListener("message", onMessage);
+		local.destroy();
+	};
+}
+//#endregion
+//#region src/inject.ts
+/**
+* One-time injection of the document-global half of the token sheet.
+*
+* `@property` registrations are document-scoped, so a second instance injecting its own copy would
+* silently redefine every token's initial-value for the whole page. {@link ensureProperties} makes
+* that a no-op instead.
+*
+* @module
+*/
+const MARKER = "data-pantoken-properties";
+/**
+* Inject `css` into `doc` once. A second call with the same `id` does nothing, whichever instance
+* makes it.
+*
+* @param css - The registrations sheet, e.g. `@pantoken/css/properties.css`.
+* @param options - `id` distinguishes unrelated sheets; `doc` defaults to the current document.
+* @returns `true` when this call performed the injection.
+*
+* @example
+* ```ts
+* import { ensureProperties } from "@pantoken/scope";
+* import properties from "@pantoken/css/properties.css?inline";
+*
+* ensureProperties(properties);
+* ```
+*/
+function ensureProperties(css, options = {}) {
+	const { id = "default", doc = document } = options;
+	if (doc.head.querySelector(`style[${MARKER}="${CSS.escape(id)}"]`)) return false;
+	const style = doc.createElement("style");
+	style.setAttribute(MARKER, id);
+	style.textContent = css;
+	doc.head.prepend(style);
+	return true;
+}
+/** True when a registrations sheet with `id` is already present in `doc`. */
+function hasProperties(id = "default", doc = document) {
+	return doc.head.querySelector(`style[${MARKER}="${CSS.escape(id)}"]`) !== null;
+}
+//#endregion
+//#region src/observe.ts
+/**
+* Reacting to scope changes made outside this instance — an ancestor retheming, or another
+* instance's scope element changing above ours.
+*
+* @module
+*/
+/**
+* Call `listener` whenever the scope resolved for `target` changes, including when an ancestor's
+* attributes change.
+*
+* @returns A stop function.
+*
+* @example
+* ```ts
+* import { observeScope } from "@pantoken/scope";
+*
+* const stop = observeScope(el, (scope) => render(scope.theme, scope.scheme));
+* ```
+*/
+function observeScope(target, listener) {
+	const view = target.ownerDocument.defaultView;
+	if (!view?.MutationObserver) return () => {};
+	let previous = resolveScope(target);
+	const observer = new view.MutationObserver(() => {
+		const next = resolveScope(target);
+		if (next.theme === previous.theme && next.scheme === previous.scheme && next.color === previous.color && next.instanceId === previous.instanceId) return;
+		previous = next;
+		listener(next);
+	});
+	observer.observe(target.ownerDocument.documentElement, {
+		attributes: true,
+		attributeFilter: [...SCOPE_ATTRS, "class"],
+		subtree: true
+	});
+	return () => {
+		observer.disconnect();
+	};
+}
+//#endregion
+export { THEME_ATTR as _, createScope as a, schemeClass as b, resolveScheme as c, BOUNDARY_CLASS as d, COLOR_ATTR as f, SCOPE_ATTRS as g, SCHEME_ATTR as h, connectScope as i, resolveScope as l, INSTANCE_ATTR as m, ensureProperties as n, getScope as o, DEFAULT_INSTANCE as p, hasProperties as r, resolveInstance as s, observeScope as t, BOUNDARY_ATTR as u, colorClass as v, themeClass as x, isScheme as y };

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@pantoken/scope",
+  "version": "0.3.11",
+  "description": "Run several pantoken themes and color schemes in one document: per-subtree scopes, ancestor resolution, and hard boundaries.",
+  "homepage": "https://pantoken.app",
+  "bugs": "https://github.com/thedannywahl/pantoken/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thedannywahl/pantoken.git",
+    "directory": "formats/scope"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/scope.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@pantoken/utils": "1.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.1",
+    "happy-dom": "^20.14.5",
+    "typescript": "^7.0.2",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.3.3",
+    "vite-plus": "0.3.3"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "pantoken": {
+    "key": "scope",
+    "kind": "namespace"
+  },
+  "scripts": {
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check"
+  }
+}