@neo-ui-kit/react 1.0.3 → 1.2.0

package/README.md

@@ -25,7 +25,7 @@ import "@neo-ui-kit/react/styles.css";
 To test repository changes before publishing, run `npm run package` from the repository root and install the resulting archive in a separate application:
 
 ```bash
-npm install /path/to/adui/release/neo-ui-kit-react-1.0.3.tgz
+npm install /path/to/adui/release/neo-ui-kit-react-1.2.0.tgz
 ```
 
 Maintainers publish new versions from `Pro100Dimka/adui` using the `release.yml` GitHub Actions workflow, a matching `v<version>` tag, and the `npm-publication` environment. npm trusts its OIDC identity; no `NPM_TOKEN` is required. The workflow checks the project and packed consumer before publishing the tested archive. Published `1.0.0` cannot be overwritten: code and README changes in npm require a new package version. See the [repository release instructions](https://github.com/Pro100Dimka/adui#npm-пакет).
@@ -182,6 +182,20 @@ import { ThemeProvider, useMotion } from "@neo-ui-kit/react/core";
 
 Canvas-rendered volume knob. Drag near the edge to rotate, drag from the center to move linearly, click the outer scale to jump. Wheel and arrow keys change the value, Shift gives a fine step, PageUp/PageDown change by 10, Home/End set 0/100, Escape cancels a drag, double-click resets. `onValueChange` fires while adjusting, `onValueCommit` after the gesture. `readOnly` turns it into a gauge.
 
+## 1.2.0 release notes
+
+- `QuantumBackground` takes `threeUrl`, the base address of a three.js 0.182 copy (the folder with `build/` and `examples/jsm/`), so the scene can work offline and without a third-party CDN. A relative address keeps the scene's import map — and its CSP hash — the same wherever the app runs. The default stays `quantumBackgroundThreeUrl` (unpkg).
+- The scene no longer loads web fonts from Google Fonts: it makes no requests beyond three.js.
+
+## 1.1.0 release notes
+
+- **`QuantumBackground` is configured through props.** Every scene setting (`field`, `sensitivity`, `density`, `bloom`, …) is an optional prop with defaults in `quantumBackgroundDefaults`; `quantumBackgroundControls` describes them for building a settings panel. **The component no longer draws its own control panel** — build one next to it (the documentation page shows how) and drive audio through the ref (`QuantumBackgroundHandle`) with `onTransportChange` / `onWaveformChange`.
+- New `QuantumBackground` props: `spectrum` / `spectrumRange` (sound from the host app), `particleCount`, `fieldSize`, `fullscreen` / `onFullscreenChange`, and `children` laid over the scene.
+- Reaction lines, particle trails and lens/anamorphic light take the theme's colours at the presets' brightness, so the bloom still flashes in any theme.
+- The field fills the scene edge to edge in full screen; the running reaction lights toggle and every documented setting reaches the renderer.
+- New `resolveTokens` resolves many theme tokens with one style recalculation; `resolveToken` and the `ThemeEditor` use it.
+- Dialog, Card and Spotlight pointer lights no longer restyle everything inside them on each pointer move.
+
 ## 1.0.3 release notes
 
 - Point the npm Homepage link directly to the documentation overview.
@@ -223,15 +237,41 @@ Repository evidence, browser runners, before/after measurements and coverage lim
 
 ## QuantumBackground
 
-`QuantumBackground` is the complete Quantum Fields visualizer inside an iframe. A compact, transparent field sits above the kit's `FilePicker`, externally controlled `AudioPlayer`, tooltip-labelled microphone/screenshot/fullscreen actions, field selector, and sensitivity control. The selected song name appears on the file button; playback and seeking use the visualizer's single audio source. Other controls live in a closed-by-default “Тонкая настройка” section below the field. It follows the nearest `ThemeProvider` palette. This experience includes MIT-licensed upstream code and CDN-loaded Three.js modules; the upstream notice is shipped as `UPSTREAM-LICENSE.txt`. It is not mounted in overview-card previews.
+`QuantumBackground` is the complete Quantum Fields visualizer inside an iframe. It renders only the scene: every visual and audio-reaction setting is an optional prop, so one component serves a hero background, a music page or a configurable studio. It follows the nearest `ThemeProvider` palette: particles, connection lines, the running reaction lights, particle trails and the lens-flare/anamorphic tints all take the theme's colours, whichever `field` is chosen. This experience includes MIT-licensed upstream code and CDN-loaded Three.js modules; the upstream notice is shipped as `UPSTREAM-LICENSE.txt`. It is not mounted in overview-card previews.
 
 ```tsx
 import { QuantumBackground, ThemeProvider } from "@neo-ui-kit/react";
 import "@neo-ui-kit/react/styles.css";
 
 <ThemeProvider theme="violet">
-  <QuantumBackground />
+  <QuantumBackground field="Neutrino" bloom={0.8} connectionsEnabled={false} interactive={false} style={{ height: "100vh" }}>
+    <h1>Over the field</h1>
+  </QuantumBackground>
 </ThemeProvider>
 ```
 
-`QuantumBackgroundProps` accepts div attributes and an optional `particleBudget` cap. Leave the cap unset for the original adaptive particle count. `QuantumFieldExperience` and `QuantumFieldExperienceProps` remain compatible aliases. The separate lightweight `QuantumField` primitive documented above keeps its original props and rendering; it is not an alias of the full background.
+Settings (`QuantumBackgroundSettings`): `field` (one of `quantumBackgroundFields`), `sensitivity`, `density`, `timeScale`, `paused`, `interactive`, nebula, connection, crawler, particle-trail, lens-flare, depth-of-field, camera-shake, bloom, trails, chromatic, anamorphic, god-ray, grain, vortex, pulse, bass-gate, onset, audio-camera, terrain-height and adaptive-quality values. Unset props use `quantumBackgroundDefaults`; only props that change are sent to the scene. `quantumBackgroundControls` lists each setting's group, label, range, step and the switch it depends on, for building your own settings panel next to the component. `particleCount` sets how many particles are drawn across both layers (0 to `quantumBackgroundMaxParticles`, 85 000); leave it unset to follow `density`. Adaptive quality may draw fewer, so turn `adaptiveQualityEnabled` off when the exact count matters. `particleBudget` is an upper cap on top of either. `fieldSize` is the share of the scene the field spans (0.78 by default, 1 reaches the edges). `fullscreen` makes the scene cover the whole viewport above the page, and the field then runs edge to edge (`quantumBackgroundFullscreenFieldSize`, 1.1) unless `fieldSize` is set (in the browser's top layer, so no ancestor's `overflow`, `transform` or `z-index` clips it, and the iframe keeps running); Escape calls `onFullscreenChange(false)`, so keep it controlled. `children` are laid over the scene, e.g. a close button while full screen. This differs from `ref.toggleFullscreen()`, which uses the browser's Fullscreen API and needs a click.
+
+`threeUrl` points the scene at your own copy of three.js 0.182 instead of unpkg (for example `threeUrl="./vendor/three/"` with `build/three.module.js` and `examples/jsm/` served there); with it the scene makes no network requests at all. Only the scene's import map changes, so a strict CSP pins the same script hashes everywhere.
+
+`spectrum` feeds sound the scene cannot hear itself — a native audio engine, a WebRTC call, a server stream: band levels 0–1 from low to high frequencies, log-spaced across `spectrumRange` (default `[40, 12000]` Hz), any band count. Pass a new array whenever the levels change (10–60 times a second); bands, beats, reaction lines and flashes follow it exactly as they follow a playing song. A file or microphone started from the ref takes over while it plays; `spectrum={undefined}` returns the scene to silence.
+
+```tsx
+const [bands, setBands] = useState<number[]>();
+useEffect(() => engine.onSpectrum(setBands), []); // e.g. 18 bands from 40 Hz to 12 kHz
+<QuantumBackground spectrum={bands} spectrumRange={[40, 12000]} />
+```
+
+Audio is a one-off action rather than a setting, so it is on the ref (`QuantumBackgroundHandle`): `loadFile(file)`, `togglePlayback()`, `seek(seconds)`, `toggleMicrophone()`, `screenshot()` and `toggleFullscreen()`. `onTransportChange` reports `{ mode, playing, current, duration, track }`, and `onWaveformChange` reports the peaks of a loaded file, so a kit `FilePicker`, `AudioPlayer` and `IconButton`s can drive it:
+
+```tsx
+const scene = useRef<QuantumBackgroundHandle>(null);
+const [transport, setTransport] = useState<QuantumBackgroundTransport>();
+
+<QuantumBackground ref={scene} field={field} sensitivity={sensitivity} onTransportChange={setTransport} />
+<FilePicker variant="button" accept="audio/*" onFiles={([file]) => file && scene.current?.loadFile(file)} />
+<AudioPlayer playing={transport?.playing} position={transport?.current} duration={transport?.duration}
+  onPlayingChange={() => scene.current?.togglePlayback()} onTimeChange={(s) => scene.current?.seek(s)} />
+```
+
+The documentation page builds exactly such a panel (song, player, microphone, snapshot, fullscreen, field and sensitivity, plus a closed “Тонкая настройка” section) outside the component. `QuantumFieldExperience`, `QuantumFieldExperienceProps` and `quantumFieldExperienceControls` remain compatible aliases; note that `QuantumFieldExperience` no longer renders its own control panel. The separate lightweight `QuantumField` primitive documented above keeps its original props and rendering; it is not an alias of the full background.

package/dist/components/artwork/QuantumField/QuantumFieldExperience.d.ts

@@ -1,26 +1,216 @@
-import { type HTMLAttributes } from "react";
-type Control = {
-    key: string;
+import { type HTMLAttributes, type ReactNode } from "react";
+/** Where the scene loads three.js from unless `threeUrl` says otherwise: the version it is built and tested with. */
+export declare const quantumBackgroundThreeUrl = "https://unpkg.com/three@0.182.0/";
+export declare const quantumBackgroundFields: readonly ["Photon (EM)", "Gluon (Strong)", "Higgs (Mass)", "Gravity", "Dark Energy", "Neutrino", "Waveform Terrain"];
+export type QuantumBackgroundField = typeof quantumBackgroundFields[number];
+/** Every visual and audio-reaction setting of the scene. All of them are optional props of `QuantumBackground`. */
+export interface QuantumBackgroundSettings {
+    field: QuantumBackgroundField;
+    sensitivity: number;
+    density: number;
+    /** Share of the scene the field spans: 1 reaches the edges, above 1 runs past them. */
+    fieldSize: number;
+    timeScale: number;
+    nebulaEnabled: boolean;
+    nebulaIntensity: number;
+    connectionsEnabled: boolean;
+    connectionThreshold: number;
+    connectionOpacity: number;
+    crawlersEnabled: boolean;
+    particleTrailsEnabled: boolean;
+    particleTrailOpacity: number;
+    lensFlareEnabled: boolean;
+    lensFlareIntensity: number;
+    dofEnabled: boolean;
+    dofFocus: number;
+    dofFocalLength: number;
+    dofBokehStrength: number;
+    cameraShake: number;
+    bloom: number;
+    trails: number;
+    chromaticAberration: number;
+    anamorphicStretch: number;
+    godRaysEnabled: boolean;
+    godRaysIntensity: number;
+    filmGrain: number;
+    vortexStrength: number;
+    pulseIntensity: number;
+    bassGateEnabled: boolean;
+    bassGateThreshold: number;
+    bassGateAttack: number;
+    bassGateRelease: number;
+    onsetSensitivity: number;
+    audioCameraEnabled: boolean;
+    audioCameraIntensity: number;
+    waveformTerrainHeight: number;
+    adaptiveQualityEnabled: boolean;
+    targetFPS: number;
+    interactive: boolean;
+    paused: boolean;
+}
+export type QuantumBackgroundSettingKey = keyof QuantumBackgroundSettings;
+export type QuantumBackgroundControl = {
+    key: QuantumBackgroundSettingKey;
     label: string;
     value: number | boolean | string;
     min?: number;
     max?: number;
     step?: number;
     options?: readonly string[];
+    /** A boolean setting that has to be on for this one to have an effect. */
+    enabledBy?: QuantumBackgroundSettingKey;
 };
-export declare const quantumFieldExperienceControls: readonly {
+/** Ranges, defaults and labels of every setting, grouped, for building a settings panel next to the scene. */
+export declare const quantumBackgroundControls: readonly {
     id: string;
     label: string;
-    controls: readonly Control[];
+    controls: readonly QuantumBackgroundControl[];
 }[];
-export type QuantumBackgroundProps = Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+/** Values the scene uses for settings that are not passed as props. */
+export declare const quantumBackgroundDefaults: Readonly<QuantumBackgroundSettings>;
+/** `fieldSize` used while `fullscreen` is on and no `fieldSize` is given: the field runs past the screen edges. */
+export declare const quantumBackgroundFullscreenFieldSize = 1.1;
+/** Most particles the scene can draw across both layers (35 000 field + 50 000 secondary). */
+export declare const quantumBackgroundMaxParticles = 85000;
+/** Audio state of the scene, reported through `onTransportChange`. */
+export type QuantumBackgroundTransport = {
+    /** `"file"` while a loaded song is the source, `"mic"` while the microphone is, otherwise `null`. */
+    mode: "file" | "mic" | null;
+    playing: boolean;
+    /** Seconds; 0 unless a file is loaded. */
+    current: number;
+    duration: number;
+    track: string;
+};
+/** Audio and capture actions, reached through `ref`. Settings are props; these are one-off commands. */
+export interface QuantumBackgroundHandle {
+    /** Decodes the file and starts playing it as the scene's audio source. */
+    loadFile(file: File): void;
+    /** Plays or pauses the loaded file. */
+    togglePlayback(): void;
+    seek(seconds: number): void;
+    /** Starts the microphone, or stops it when it is the current source. */
+    toggleMicrophone(): void;
+    /** Downloads a PNG of the current frame. */
+    screenshot(): void;
+    /** Opens the scene full screen, or leaves full screen. */
+    toggleFullscreen(): void;
+}
+export type QuantumBackgroundProps = Partial<QuantumBackgroundSettings> & Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    /**
+     * Number of particles across both layers, 0–`quantumBackgroundMaxParticles`. Unset follows `density`.
+     * Adaptive quality may draw fewer; turn `adaptiveQualityEnabled` off to keep the exact count.
+     */
+    particleCount?: number;
     /** Maximum number of visible particles across both field layers. Adaptive quality may draw fewer. */
     particleBudget?: number;
+    /**
+     * Base address of a three.js 0.182 copy — the folder holding `build/three.module.js` and
+     * `examples/jsm/` — so the scene works offline and without a third-party CDN. A relative address
+     * resolves against the page and keeps the scene's import map (and its CSP hash) the same wherever
+     * the app is installed. Default: `quantumBackgroundThreeUrl` (unpkg).
+     */
+    threeUrl?: string;
+    /**
+     * Sound the scene cannot hear itself — a native audio engine, a WebRTC call, a server stream: band
+     * levels 0–1 from low to high frequencies, log-spaced across `spectrumRange`. Any band count works;
+     * pass a new array whenever the levels change (10–60 times a second). While set, it drives the field
+     * like a playing song; a file or microphone started from the ref takes over while it plays.
+     * `undefined` returns the scene to silence.
+     */
+    spectrum?: readonly number[];
+    /** Frequencies in Hz of the first and last `spectrum` band. Default `[40, 12000]`. */
+    spectrumRange?: readonly [number, number];
+    /** Covers the whole viewport above the page; the field then fills it edge to edge unless `fieldSize` is set. */
+    fullscreen?: boolean;
+    /** Asks to leave `fullscreen` when the viewer presses Escape. */
+    onFullscreenChange?: (fullscreen: boolean) => void;
+    /** Content laid over the scene, e.g. a hero heading. */
+    children?: ReactNode;
+    /** Called when the audio source, playback state or position changes (about 4 times a second while playing). */
+    onTransportChange?: (transport: QuantumBackgroundTransport) => void;
+    /** Peaks (0–1) of a newly loaded file, for drawing its waveform. */
+    onWaveformChange?: (points: number[]) => void;
 };
-/** Full MIT-licensed renderer; the host kit owns the controls and theme. */
-export declare function QuantumBackground({ className, particleBudget, ...props }: QuantumBackgroundProps): import("react").JSX.Element;
+/** Full MIT-licensed audio-reactive scene. Every setting is a prop; audio actions are on the ref. */
+export declare const QuantumBackground: import("react").ForwardRefExoticComponent<Partial<QuantumBackgroundSettings> & Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    /**
+     * Number of particles across both layers, 0–`quantumBackgroundMaxParticles`. Unset follows `density`.
+     * Adaptive quality may draw fewer; turn `adaptiveQualityEnabled` off to keep the exact count.
+     */
+    particleCount?: number;
+    /** Maximum number of visible particles across both field layers. Adaptive quality may draw fewer. */
+    particleBudget?: number;
+    /**
+     * Base address of a three.js 0.182 copy — the folder holding `build/three.module.js` and
+     * `examples/jsm/` — so the scene works offline and without a third-party CDN. A relative address
+     * resolves against the page and keeps the scene's import map (and its CSP hash) the same wherever
+     * the app is installed. Default: `quantumBackgroundThreeUrl` (unpkg).
+     */
+    threeUrl?: string;
+    /**
+     * Sound the scene cannot hear itself — a native audio engine, a WebRTC call, a server stream: band
+     * levels 0–1 from low to high frequencies, log-spaced across `spectrumRange`. Any band count works;
+     * pass a new array whenever the levels change (10–60 times a second). While set, it drives the field
+     * like a playing song; a file or microphone started from the ref takes over while it plays.
+     * `undefined` returns the scene to silence.
+     */
+    spectrum?: readonly number[];
+    /** Frequencies in Hz of the first and last `spectrum` band. Default `[40, 12000]`. */
+    spectrumRange?: readonly [number, number];
+    /** Covers the whole viewport above the page; the field then fills it edge to edge unless `fieldSize` is set. */
+    fullscreen?: boolean;
+    /** Asks to leave `fullscreen` when the viewer presses Escape. */
+    onFullscreenChange?: (fullscreen: boolean) => void;
+    /** Content laid over the scene, e.g. a hero heading. */
+    children?: ReactNode;
+    /** Called when the audio source, playback state or position changes (about 4 times a second while playing). */
+    onTransportChange?: (transport: QuantumBackgroundTransport) => void;
+    /** Peaks (0–1) of a newly loaded file, for drawing its waveform. */
+    onWaveformChange?: (points: number[]) => void;
+} & import("react").RefAttributes<QuantumBackgroundHandle>>;
 /** @deprecated Use QuantumBackground. The original import remains compatible. */
-export declare const QuantumFieldExperience: typeof QuantumBackground;
+export declare const QuantumFieldExperience: import("react").ForwardRefExoticComponent<Partial<QuantumBackgroundSettings> & Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    /**
+     * Number of particles across both layers, 0–`quantumBackgroundMaxParticles`. Unset follows `density`.
+     * Adaptive quality may draw fewer; turn `adaptiveQualityEnabled` off to keep the exact count.
+     */
+    particleCount?: number;
+    /** Maximum number of visible particles across both field layers. Adaptive quality may draw fewer. */
+    particleBudget?: number;
+    /**
+     * Base address of a three.js 0.182 copy — the folder holding `build/three.module.js` and
+     * `examples/jsm/` — so the scene works offline and without a third-party CDN. A relative address
+     * resolves against the page and keeps the scene's import map (and its CSP hash) the same wherever
+     * the app is installed. Default: `quantumBackgroundThreeUrl` (unpkg).
+     */
+    threeUrl?: string;
+    /**
+     * Sound the scene cannot hear itself — a native audio engine, a WebRTC call, a server stream: band
+     * levels 0–1 from low to high frequencies, log-spaced across `spectrumRange`. Any band count works;
+     * pass a new array whenever the levels change (10–60 times a second). While set, it drives the field
+     * like a playing song; a file or microphone started from the ref takes over while it plays.
+     * `undefined` returns the scene to silence.
+     */
+    spectrum?: readonly number[];
+    /** Frequencies in Hz of the first and last `spectrum` band. Default `[40, 12000]`. */
+    spectrumRange?: readonly [number, number];
+    /** Covers the whole viewport above the page; the field then fills it edge to edge unless `fieldSize` is set. */
+    fullscreen?: boolean;
+    /** Asks to leave `fullscreen` when the viewer presses Escape. */
+    onFullscreenChange?: (fullscreen: boolean) => void;
+    /** Content laid over the scene, e.g. a hero heading. */
+    children?: ReactNode;
+    /** Called when the audio source, playback state or position changes (about 4 times a second while playing). */
+    onTransportChange?: (transport: QuantumBackgroundTransport) => void;
+    /** Peaks (0–1) of a newly loaded file, for drawing its waveform. */
+    onWaveformChange?: (points: number[]) => void;
+} & import("react").RefAttributes<QuantumBackgroundHandle>>;
 /** @deprecated Use QuantumBackgroundProps. */
 export type QuantumFieldExperienceProps = QuantumBackgroundProps;
-export {};
+/** @deprecated Use quantumBackgroundControls. */
+export declare const quantumFieldExperienceControls: readonly {
+    id: string;
+    label: string;
+    controls: readonly QuantumBackgroundControl[];
+}[];

package/dist/components/artwork/QuantumField/styles.css

@@ -23,51 +23,34 @@
   z-index: 1;
 }
 
-.ad-quantum-field-experience {
-  width: 100%;
-  overflow: hidden;
-  border-radius: var(--ad-radius-lg, 1rem);
-  background: transparent;
-}
-.ad-qf-controls {
-  display: grid;
-  gap: 0.75rem;
-  padding: 0.75rem 0;
-}
-.ad-qf-toolbar { display: flex; flex-wrap: wrap; align-items: center; gap: 0.625rem; }
-.ad-qf-toolbar > .ad-file-picker { flex: none; }
-.ad-qf-toolbar > .ad-file-picker > small { display: none; }
-.ad-qf-toolbar > .ad-file-picker > .ad-button { max-width: 11rem; }
-.ad-qf-toolbar > .ad-file-picker .ad-button-label { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
-.ad-qf-toolbar > .ad-audio-player { flex: 1 1 13rem; min-width: min(100%, 13rem); padding: 0.35rem 0.5rem; }
-.ad-qf-toolbar .ad-player-play > .ad-icon-button { --ad-size-h: 2.25rem; width: 2.25rem; height: 2.25rem; }
-.ad-qf-actions { display: flex; align-items: center; gap: 0.25rem; }
-.ad-qf-actions > .ad-tooltip-trigger { display: inline-flex; }
-.ad-qf-controls nav { max-width: 100%; overflow-x: auto; }
-.ad-qf-controls .ad-collapse-content { display: grid; gap: 0.75rem; }
-.ad-qf-control-panel { display: grid; gap: 0.75rem; }
-.ad-qf-setting-grid {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(min(100%, 13rem), 1fr));
-  gap: 0.75rem 1rem;
-  align-items: center;
-}
-.ad-qf-essentials { flex: 1 1 18rem; grid-template-columns: repeat(2, minmax(0, 1fr)); }
-.ad-qf-setting { display: flex; align-items: end; gap: 0.5rem; min-width: 0; }
-.ad-qf-setting > .ad-slider-field { flex: 1; min-width: 0; }
-.ad-qf-setting > output { min-width: 3ch; padding-bottom: 0.55rem; color: var(--ad-muted); font-variant-numeric: tabular-nums; text-align: end; }
-.ad-qf-fps, .ad-qf-status { color: var(--ad-muted); font-size: 0.75rem; }
-.ad-qf-status { min-height: 1em; }
-.ad-qf-viewport {
+.ad-quantum-background {
   position: relative;
   width: 100%;
   height: clamp(18rem, 42vh, 27rem);
+  overflow: hidden;
+  isolation: isolate;
+  border-radius: var(--ad-radius-lg, 1rem);
   background: transparent;
 }
-.ad-qf-viewport > .ad-quantum-field {
-  height: 100%;
+.ad-quantum-background[data-fullscreen] {
+  position: fixed;
+  inset: 0;
+  z-index: var(--ad-z-overlay, 900);
+  width: 100vw;
+  height: 100dvh;
+  max-width: none;
+  max-height: none;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  border-radius: 0;
+  color: inherit;
+  background: var(--ad-surface-dialog, #050208);
 }
-.ad-qf-viewport > iframe {
+.ad-quantum-background[data-fullscreen]::backdrop { background: transparent; }
+.ad-quantum-background > iframe {
+  position: absolute;
+  inset: 0;
   display: block;
   width: 100%;
   height: 100%;
@@ -75,3 +58,10 @@
   background: transparent;
   color-scheme: dark;
 }
+.ad-qb-content {
+  position: absolute;
+  inset: 0;
+  z-index: 1;
+  pointer-events: none;
+}
+.ad-qb-content > * { pointer-events: auto; }

package/dist/components/effects/Spotlight/styles.css

@@ -8,6 +8,9 @@
 }
 .ad-spotlight::before,
 .ad-spotlight::after {
+  /* The pointer position is not inherited by default: the lights read it from their own surface. */
+  --ad-spot-x: inherit;
+  --ad-spot-y: inherit;
   content: "";
   position: absolute;
   inset: 0;

package/dist/components/feedback/Dialog/styles.css

@@ -18,8 +18,8 @@ html:has(.ad-dialog[open]) {
   color: var(--ad-text);
 }
 /* Pointer light: a soft glow under the cursor, painted over the window's own surface. */
-.ad-dialog[data-ad-material] {
-  --ad-material-bg:
+.ad.ad-dialog[data-ad-material] {
+  background:
     radial-gradient(26rem circle at var(--ad-spot-x, -40rem) var(--ad-spot-y, -40rem), rgb(from var(--ad-primary) r g b / 0.11), transparent 60%),
     var(--ad-surface-dialog);
 }

package/dist/components/foundation/ThemeEditor/themeConfig.d.ts

@@ -43,5 +43,14 @@ export declare function themeProps(config: ThemeConfig): {
 export declare function exportTheme(config: ThemeConfig): string;
 /** Reads a theme back from JSON; throws an Error with a readable message when it is not one. */
 export declare function parseTheme(text: string, locale?: Locale): ThemeConfig;
-/** Current value of a token inside `scope`: colours as #rrggbb, everything else as written. */
+/**
+ * Current values of several tokens inside `scope`: colours as #rrggbb, everything else as written.
+ * All colour probes are inserted together, so the page's styles are recalculated once instead of
+ * once per token — on a large page that is the difference between one frame and a visible freeze.
+ */
+export declare function resolveTokens(scope: Element, tokens: readonly (string | {
+    name: string;
+    kind?: ThemeTokenKind;
+})[]): Record<string, string>;
+/** Current value of a token inside `scope`: colours as #rrggbb, everything else as written. Use `resolveTokens` for several. */
 export declare function resolveToken(scope: Element, name: string, kind?: ThemeTokenKind): string;

package/dist/components/layout/Card/styles.css

@@ -19,6 +19,9 @@
 }
 /* Pointer spotlight: a soft ruby light under the cursor, faded in on hover. */
 .ad-card::after {
+  /* The pointer position is not inherited by default: the light reads it from its own card. */
+  --ad-spot-x: inherit;
+  --ad-spot-y: inherit;
   content: "";
   position: absolute;
   inset: 0;

package/dist/index.d.ts

@@ -22,7 +22,7 @@ export { MelodixText } from "./components/effects/MelodixText/MelodixText";
 export type { MelodixTextProps } from "./components/effects/MelodixText/MelodixText";
 export { ThemeEditor } from "./components/foundation/ThemeEditor/ThemeEditor";
 export type { ThemeEditorProps } from "./components/foundation/ThemeEditor/ThemeEditor";
-export { defaultThemeConfig, deriveSecondary, exportTheme, parseTheme, resolveToken, themeProps, themeTokenGroups } from "./components/foundation/ThemeEditor/themeConfig";
+export { defaultThemeConfig, deriveSecondary, exportTheme, parseTheme, resolveToken, resolveTokens, themeProps, themeTokenGroups } from "./components/foundation/ThemeEditor/themeConfig";
 export type { ThemeConfig, ThemeTokenGroup, ThemeTokenKind } from "./components/foundation/ThemeEditor/themeConfig";
 export { Chip } from "./components/controls/Chip/Chip";
 export type { ChipProps } from "./components/controls/Chip/Chip";
@@ -122,8 +122,8 @@ export { NeonWaves } from "./components/artwork/NeonWaves/NeonWaves";
 export type { NeonWavesProps } from "./components/artwork/NeonWaves/NeonWaves";
 export { QuantumField, quantumFieldModes, quantumFieldResolution, quantumFieldAudio } from "./components/artwork/QuantumField/QuantumField";
 export type { QuantumFieldProps, QuantumFieldMode, QuantumFieldQuality, QuantumAudioFrame } from "./components/artwork/QuantumField/QuantumField";
-export { QuantumBackground, QuantumFieldExperience } from "./components/artwork/QuantumField/QuantumFieldExperience";
-export type { QuantumBackgroundProps, QuantumFieldExperienceProps } from "./components/artwork/QuantumField/QuantumFieldExperience";
+export { QuantumBackground, QuantumFieldExperience, quantumBackgroundControls, quantumBackgroundDefaults, quantumBackgroundFields, quantumBackgroundFullscreenFieldSize, quantumBackgroundMaxParticles, quantumBackgroundThreeUrl, quantumFieldExperienceControls } from "./components/artwork/QuantumField/QuantumFieldExperience";
+export type { QuantumBackgroundProps, QuantumBackgroundSettings, QuantumBackgroundSettingKey, QuantumBackgroundField, QuantumBackgroundControl, QuantumBackgroundHandle, QuantumBackgroundTransport, QuantumFieldExperienceProps } from "./components/artwork/QuantumField/QuantumFieldExperience";
 export { createQuantumFieldAudio } from "./components/artwork/QuantumField/audio";
 export { Spectrum } from "./components/artwork/Spectrum/Spectrum";
 export type { SpectrumProps } from "./components/artwork/Spectrum/Spectrum";