@preference-sl/pref-viewer 2.18.0-beta.1 → 3.0.0-beta.0

package/src/pref-viewer.js

@@ -1,5 +1,7 @@
 import PrefViewerTask from "./pref-viewer-task.js";
-import { PREF_VIEWER_STYLES_STORAGE_KEY, PrefViewerStyles, PrefViewerStyleVariables } from "./styles.js";
+import { PrefViewerStyles } from "./styles.js";
+import PrefViewerStyleController from "./pref-viewer-style-controller.js";
+import PrefViewerControlsPresentation from "./pref-viewer-controls-presentation.js";
 import I18n from "./localization/i18n.js";
 
 /**
@@ -7,9 +9,10 @@ import I18n from "./localization/i18n.js";
  *
  * Overview:
  *  - Hosts synchronized 2D (SVG) and 3D (Babylon.js) canvases plus a render-settings menu inside a single shadow DOM wrapper.
+ *  - Loads optional font CSS without blocking local shadow styles or the canvas's initial layout measurement.
  *  - Queues mutations (config/model/scene/materials/drawing/options/culture) to guarantee deterministic execution and avoid race conditions.
  *  - Normalizes remote URLs, Base64 payloads, and IndexedDB lookups before forwarding jobs to the BabylonJSController stack.
- *  - Persists the active locale and supported style variables to localStorage, mirrors locale to PrefViewerMenu3D, and keeps the shared i18n module in sync with the chosen culture.
+ *  - Persists locale and optional instance-owned appearance overrides; mirrors locale to the menu and shared i18n module.
  *  - Surfaces a dialog API that powers built-in download flows (GLB, glTF+ZIP, USDZ) for model-only, scene-only, or combined asset exports.
  *  - Emits granular lifecycle custom events so host applications can react to loading progress, drawing zoom changes, selection changes, and menu interactions.
  *  - Exposes imperative methods for toggling visibility, updating options, switching modes, controlling animations, managing selection state, and requesting downloads without attribute juggling.
@@ -30,8 +33,9 @@ import I18n from "./localization/i18n.js";
  *  - mode: Switches between `2d` and `3d`, automatically hiding/showing the relevant subcomponents and menu states.
  *  - show-model / show-scene: Boolean flags to toggle visibility without reloading the underlying resources.
  *  - show-render-menu: Boolean flag to show or hide the render-settings menu (default: true).
+ *  - view-cube-renderer: Selects independent Babylon Canvas (default) or SVG via reflected viewCubeRenderer.
  *  - show-view-cube: Enables the 3D orientation overlay unless "false"; visible cubes position the render menu below their measured height.
- *  - styles: JSON style overrides. Currently supports `colorPrimary`, persisted in localStorage and exposed as `--pref-viewer-color-primary`.
+ *  - styles: Validated primary/ViewCube appearance overrides; optional versioned persistence and private CSS projection.
  *
  * Public Methods (selection):
  *  - loadConfig / loadModel / loadScene / loadMaterials / loadDrawing: Queue asset ingestion jobs.
@@ -67,6 +71,7 @@ import I18n from "./localization/i18n.js";
  *  - Legacy `scene-*` and `drawing-*` aliases are still emitted alongside their modern equivalents for backward compatibility.
  *
  * Notes:
+ *  - Owns one responsive control presentation shared by nested overlays; disconnect releases its observers.
  *  - Stores the cube layout handler and subscribes only for active 3D cube layout; open dialogs render above viewer overlays.
  *  - Internally wires PrefViewerMenu3D hover/apply events to PrefViewer3D render settings, ensuring persisted toggles stay in sync with BabylonJSController.
  *  - Cleans up dialogs, listeners, and subcomponents on disconnect to prevent leaks when frameworks mount/unmount the custom element.
@@ -74,6 +79,9 @@ import I18n from "./localization/i18n.js";
  *  - Designed for embeddable configurators, product showcases, and sales tooling that require responsive 2D/3D switching plus offline-friendly exports.
  */
 export default class PrefViewer extends HTMLElement {
+    #controlsPresentation = null;
+    #presentationFontLink = null;
+    #presentationRootStyle = null;
     // Internal state flags
     #isInitialized = false;
     #isLoaded = false;
@@ -101,10 +109,7 @@ export default class PrefViewer extends HTMLElement {
     #cultureSuppressAttribute = false;
 
     // Runtime style management
-    #STYLES_STORAGE_KEY = PREF_VIEWER_STYLES_STORAGE_KEY;
-    #styles = {
-        colorPrimary: PrefViewerStyleVariables.colorPrimary,
-    };
+    #styleController;
 
     // References to internal components
     #wrapper = null;
@@ -126,9 +131,23 @@ export default class PrefViewer extends HTMLElement {
         onViewCubeLayout: null,
     };
 
+    /** @returns {"svg"|"canvas"} Per-instance normalized renderer; missing/invalid attributes use Canvas. */
+    get viewCubeRenderer() {
+        return this.getAttribute("view-cube-renderer") === "svg" ? "svg" : "canvas";
+    }
+
+    /**
+     * Reflects the renderer preference immediately without reloading assets or changing visibility.
+     * @param {"svg"|"canvas"} value - SVG selects the vector widget; all other values select the dedicated Canvas 3D scene.
+     * @returns {void}
+     */
+    set viewCubeRenderer(value) {
+        this.setAttribute("view-cube-renderer", value === "svg" ? "svg" : "canvas");
+    }
+
     /**
      * Creates a new PrefViewer instance and attaches a shadow DOM.
-     * Initializes internal state and component references.
+     * Initializes instance-owned styling without reading storage until insertion; other component references are created on connection.
      * @public
      */
     constructor() {
@@ -141,22 +160,24 @@ export default class PrefViewer extends HTMLElement {
             this.#culture = I18n.setLocale(this.#cultureInitial);
         }
 
-        this.#applyStyles(this.#stylesReadPersisted(), { persist: false, applyCssVariables: false });
+        this.#styleController = new PrefViewerStyleController(this.ownerDocument);
     }
 
     /**
-     * Returns the list of attributes to observe for changes.
+     * Returns observed data, visibility, renderer selection, styles and controls-density attributes.
      * @public
      * @returns {string[]} Array of attribute names to observe.
      */
     static get observedAttributes() {
-        return ["config", "culture", "drawing", "materials", "mode", "model", "scene", "options", "show-model", "show-scene", "show-render-menu", "show-view-cube", "styles"];
+        return ["config", "culture", "drawing", "materials", "mode", "model", "scene", "options", "show-model", "show-scene", "show-render-menu", "show-view-cube", "view-cube-renderer", "styles", "controls-density"];
     }
 
     /**
      * Observes changes to specific attributes and triggers corresponding actions.
      * Loads configuration, drawing, model, scene, materials, or options when their attributes change.
      * Toggles model or scene visibility when "show-model" or "show-scene" attributes change, recreates the 3D menu when "show-render-menu" changes, and queues style overrides when "styles" changes.
+     * "view-cube-renderer" switches the active cube without loading assets.
+     * "controls-density" refreshes shared control presentation without queuing asset work.
      * "show-view-cube" synchronizes lazy cube activation and conditional layout subscription before forwarding the attribute.
      * @public
      * @param {string} name - The name of the changed attribute.
@@ -166,6 +187,12 @@ export default class PrefViewer extends HTMLElement {
      */
     attributeChangedCallback(name, _old, value) {
         switch (name) {
+            case "view-cube-renderer":
+                this.#component3D?.setAttribute("view-cube-renderer", this.viewCubeRenderer);
+                break;
+            case "controls-density":
+                this.#controlsPresentation?.refresh();
+                break;
             case "show-view-cube":
                 this.#setViewCubeLayoutSubscription(this.#mode === "3d" && value !== "false");
                 this.#component3D?.setAttribute("show-view-cube", value === "false" ? "false" : "true");
@@ -236,17 +263,19 @@ export default class PrefViewer extends HTMLElement {
     /**
      * Called when the element is inserted into the DOM.
      * Initializes the 3D and 2D viewer components and starts processing tasks.
-     * Restores the primary animation-highlight color after creating the 3D component and menu.
+     * Restores saved styles inside a CSS inheritance boundary before creating controls and synchronizes the effective primary highlight.
      * @public
      * @returns {void|boolean} Returns false if initialization fails; otherwise void.
      */
     connectedCallback() {
         this.#createShadowDOM();
-        this.#stylesApplyCssVariables();
+        this.#styleController.attach(this.#wrapper);
+        this.#controlsPresentation = new PrefViewerControlsPresentation(this.#wrapper,
+            () => this.getAttribute("controls-density"), () => this.#component3D?.refreshViewCube?.());
         this.#createComponent3D();
         this.#createComponent2D();
         this.#createMenu3D();
-        this.#applyRenderSettings({ highlightColor: this.#styles.colorPrimary, persist: false });
+        this.#applyRenderSettings({ highlightColor: this.#styleController.primaryColor, persist: false });
 
         this.setMode(this.getAttribute("mode") ?? this.#mode);
 
@@ -264,11 +293,13 @@ export default class PrefViewer extends HTMLElement {
 
     /**
      * Removes stored child/menu/dialog listeners and subcomponents when detached.
-     * Unsubscribes the cube layout handler before the 3D component and its overlay are torn down.
+     * Disposes responsive control observers and unsubscribes the cube layout handler before the 3D component and its overlay are torn down.
      * @public
      * @returns {void}
      */
     disconnectedCallback() {
+        this.#controlsPresentation?.dispose();
+        this.#controlsPresentation = null;
         if (this.#wrapper) {
             this.#wrapper.removeEventListener("mouseenter", this.#handlers.onViewerHoverStart);
             this.#wrapper.removeEventListener("mouseleave", this.#handlers.onViewerHoverEnd);
@@ -296,21 +327,31 @@ export default class PrefViewer extends HTMLElement {
     }
 
     /**
-     * Creates the root shadow DOM structure and host styles.
+     * Replaces owned wrapper/font/style nodes on reconnect while preserving consumer-added shadow content.
+     * Optional font CSS starts with print media and switches on load, allowing local styles and canvas layout
+     * to become usable even while the external font stylesheet is pending or unavailable.
      * @private
      * @returns {void}
      */
     #createShadowDOM() {
+        this.#wrapper?.remove();
+        this.#presentationFontLink?.remove();
+        this.#presentationRootStyle?.remove();
         this.#wrapper = document.createElement("div");
         this.#wrapper.classList.add("pref-viewer-wrapper");
         this.shadowRoot.append(this.#wrapper);
 
-        const link = document.createElement("link");
+        const link = this.#presentationFontLink = document.createElement("link");
         link.setAttribute("rel", "stylesheet");
         link.setAttribute("href", "https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,100..900;1,100..900&display=swap");
+        // Font CSS must not block local shadow styles while Babylon measures its canvas.
+        // Otherwise its intrinsic buffer can be mistaken for the CSS viewport and scaled again.
+        link.media = "print";
+        link.addEventListener("load", () => { link.media = "all"; }, { once: true });
         this.shadowRoot.append(link);
 
         const style = document.createElement("style");
+        this.#presentationRootStyle = style;
         style.textContent = PrefViewerStyles;
         this.shadowRoot.append(style);
     }
@@ -351,7 +392,7 @@ export default class PrefViewer extends HTMLElement {
     }
     /**
      * Creates and appends the 3D viewer component to the shadow DOM, initially hidden.
-     * Forwards show-view-cube, stores its layout handler in #handlers and subscribes before activation
+     * Forwards renderer selection and show-view-cube, stores its layout handler in #handlers and subscribes before activation
      * so the first measured layout positions the render menu correctly.
      * @private
      * @returns {void}
@@ -360,6 +401,7 @@ export default class PrefViewer extends HTMLElement {
         this.#handlers.on3DElementClick = this.#on3DElementClick.bind(this);
         this.#component3D = document.createElement("pref-viewer-3d");
         this.#component3D.setAttribute("visible", "false");
+        this.#component3D.setAttribute("view-cube-renderer", this.viewCubeRenderer);
         this.#component3D.setAttribute("show-view-cube", this.getAttribute("show-view-cube") === "false" ? "false" : "true");
         this.#handlers.onViewCubeLayout = (event) => {
             if (event.detail.offset > 0) {
@@ -490,80 +532,17 @@ export default class PrefViewer extends HTMLElement {
     }
 
     /**
-     * Reads persisted style overrides from localStorage.
-     * @private
-     * @returns {object} Persisted style overrides, or an empty object when unavailable.
-     */
-    #stylesReadPersisted() {
-        if (typeof window === "undefined") {
-            return {};
-        }
-        try {
-            const serialized = window.localStorage?.getItem(this.#STYLES_STORAGE_KEY);
-            return serialized ? JSON.parse(serialized) : {};
-        } catch (_error) {
-            return {};
-        }
-    }
-
-    /**
-     * Persists current style overrides in localStorage.
-     * @private
-     * @returns {void}
-     */
-    #stylesPersist() {
-        if (typeof window === "undefined") {
-            return;
-        }
-        try {
-            window.localStorage?.setItem(this.#STYLES_STORAGE_KEY, JSON.stringify(this.#styles));
-        } catch (_error) {}
-    }
-
-    /**
-     * Keeps the host CSS custom properties in sync with the style variables.
-     * @private
-     * @returns {void}
+     * Validates and merges a partial appearance patch through the instance-owned controller.
+     * Projects styles inside the shadow boundary and persists only overrides when enabled.
+     * @param {object} styles - Supported primary/ViewCube leaves; null leaves or groups restore defaults.
+     * @returns {boolean} Whether at least one supported value or reset was accepted.
      */
-    #stylesApplyCssVariables() {
-        this.style.setProperty("--pref-viewer-color-primary", this.#styles.colorPrimary);
-    }
-
-    /**
-     * Applies supported style overrides to PrefViewerStyleVariables and the host CSS variables.
-     * @private
-     * @param {object} styles - Style overrides.
-     * @param {object} [options] - Apply options.
-     * @param {boolean} [options.persist=true] - Whether to persist the resolved styles.
-     * @param {boolean} [options.applyCssVariables=true] - Whether to update host CSS custom properties immediately.
-     * @returns {boolean} True when at least one supported style was applied.
-     */
-    #applyStyles(styles, options = {}) {
-        const { persist = true, applyCssVariables = true } = options;
-        if (!styles || typeof styles !== "object") {
-            return false;
-        }
-
-        const nextStyles = {};
-        if (typeof styles.colorPrimary === "string" && styles.colorPrimary.trim().length > 0) {
-            nextStyles.colorPrimary = styles.colorPrimary.trim();
-        }
-
-        if (!Object.keys(nextStyles).length) {
+    #applyStyles(styles) {
+        if (!this.#styleController.update(styles)) {
             return false;
         }
-
-        this.#styles = {
-            ...this.#styles,
-            ...nextStyles,
-        };
-        PrefViewerStyleVariables.colorPrimary = this.#styles.colorPrimary;
-        if (applyCssVariables) {
-            this.#stylesApplyCssVariables();
-        }
-        if (persist) {
-            this.#stylesPersist();
-        }
+        this.#controlsPresentation?.refresh();
+        this.#component3D?.refreshViewCube?.();
         return true;
     }
 
@@ -688,7 +667,7 @@ export default class PrefViewer extends HTMLElement {
     }
 
     /**
-     * Adds a new task to the internal queue for processing.
+     * Adds a task in order; every partial style patch is retained, while pending options/drawing tasks are replaced.
      * If the viewer is initialized and not currently loading, immediately processes the next task.
      * @private
      * @param {*} value - The payload or data for the task.
@@ -697,7 +676,7 @@ export default class PrefViewer extends HTMLElement {
      */
     #addTaskToQueue(value, type) {
         const task = new PrefViewerTask(value, type);
-        if (task.type === PrefViewerTask.Types.Options || task.type === PrefViewerTask.Types.Drawing || task.type === PrefViewerTask.Types.Styles) {
+        if (task.type === PrefViewerTask.Types.Options || task.type === PrefViewerTask.Types.Drawing) {
             this.#taskQueue = this.#taskQueue.filter((queuedTask) => queuedTask.type !== task.type);
         }
         this.#taskQueue.push(task);
@@ -932,10 +911,14 @@ export default class PrefViewer extends HTMLElement {
      * @private
      * @param {object} config - The configuration object to process.
      * @param {boolean} [config.showRenderMenu] - Reflects render-menu visibility before loading assets; non-booleans are ignored.
+     * @param {"svg"|"canvas"} [config.viewCubeRenderer] - Optional per-instance renderer, applied in queue order; omission preserves it.
      * @param {boolean} [config.showViewCube] - Reflects cube activation before loading assets; non-booleans are ignored.
      * @returns {Promise<void>} Resolves after the load attempt and advances the task queue.
      */
     async #processConfig(config) {
+        if (Object.hasOwn(config, "viewCubeRenderer")) {
+            this.viewCubeRenderer = config.viewCubeRenderer;
+        }
         for (const [property, attribute] of [["showRenderMenu", "show-render-menu"], ["showViewCube", "show-view-cube"]]) {
             if (typeof config[property] === "boolean") {
                 const value = String(config[property]);
@@ -1066,7 +1049,7 @@ export default class PrefViewer extends HTMLElement {
     }
 
     /**
-     * Applies queued styles and synchronizes animation-opening highlight color without reloading assets.
+     * Applies queued appearance patches; only an accepted primary-color override synchronizes animation highlights.
      * Waits for render settings/menu synchronization before advancing the task queue.
      * @private
      * @param {object} styles - Style overrides to apply.
@@ -1075,7 +1058,11 @@ export default class PrefViewer extends HTMLElement {
     async #processStyles(styles) {
         try {
             if (this.#applyStyles(styles)) {
-                await this.#applyRenderSettings({ highlightColor: this.#styles.colorPrimary });
+                const primary = styles.colorPrimary;
+                const acceptedPrimary = primary === null || (typeof primary === "string" && primary.trim() === this.styles.colorPrimary);
+                if (acceptedPrimary) {
+                    await this.#applyRenderSettings({ highlightColor: this.#styleController.primaryColor });
+                }
             }
         } finally {
             this.#processNextTask();
@@ -1355,12 +1342,13 @@ export default class PrefViewer extends HTMLElement {
 
     /**
      * Loads a configuration object or JSON string and adds it to the task queue.
-     * Queues supplied styles/culture before the configuration and a supplied drawing afterward.
+     * Validates/snapshots supplied style patches through setStyles(), queues styles/culture before config and drawing afterward.
      * Boolean showRenderMenu/showViewCube flags apply when that config task is processed, before its 3D load.
      * Omitted/non-boolean flags preserve current attributes; equal values do not recreate the menu.
      * @public
      * @param {object|string} config - Configuration object or JSON string; overlay flags apply in queue order.
      * @param {boolean} [config.showRenderMenu] - Sets show-render-menu when explicitly boolean.
+     * @param {"svg"|"canvas"} [config.viewCubeRenderer] - Optional per-instance renderer, applied in queue order; omission preserves it.
      * @param {boolean} [config.showViewCube] - Sets show-view-cube when explicitly boolean.
      * @returns {false|void} Returns false for an absent/falsy payload; otherwise queues the configuration.
      * @throws {SyntaxError} If a supplied JSON string cannot be parsed.
@@ -1371,7 +1359,7 @@ export default class PrefViewer extends HTMLElement {
             return false;
         }
         if (config.styles) {
-            this.#addTaskToQueue(config.styles, "styles");
+            this.setStyles(config.styles);
         }
         if (config.culture) {
             this.#addTaskToQueue(config.culture, "culture");
@@ -1503,19 +1491,49 @@ export default class PrefViewer extends HTMLElement {
     }
 
     /**
-     * Sets supported PrefViewer style variables from an object or JSON string and adds them to the task queue.
-     * Currently supports `colorPrimary`, which updates `PrefViewerStyleVariables.colorPrimary`, applies the host CSS custom property,
-     * synchronizes animation-opening highlight color (including active highlights), and persists the value in localStorage.
+     * Sets instance-owned primary/ViewCube appearance from a JSON-safe object or JSON string through the task queue.
+     * Synchronizes primary highlight settings and optionally persists supported overrides; external CSS is not consulted.
      * @public
-     * @param {object|string} styles - Style overrides object or JSON string.
-     * @returns {boolean|void} Returns false if styles are invalid; otherwise void.
+     * Queues a detached partial primary/ViewCube style patch. Unknown/invalid leaves are ignored when processed.
+     * @param {object|string} styles - Style tree or JSON; null leaves/groups reset customizations.
+     * @returns {boolean|void} False for a non-object payload; accepted objects are queued and return void, not a Promise.
+     * @throws {SyntaxError} If a JSON string is malformed.
      */
     setStyles(styles) {
         styles = typeof styles === "string" ? JSON.parse(styles) : styles;
-        if (!styles || typeof styles !== "object") {
+        if (!styles || typeof styles !== "object" || Array.isArray(styles)) {
             return false;
         }
-        this.#addTaskToQueue(styles, "styles");
+        this.#addTaskToQueue(structuredClone(styles), "styles");
+    }
+
+    /**
+     * Removes only this viewer's configured saved styles, preserving its current appearance.
+     * A later accepted patch can save the current overrides again. Disabled/unavailable storage is a no-op.
+     * @returns {boolean} Whether the configured entry was successfully removed.
+     */
+    clearPersistedStyles() {
+        return this.#styleController.clearPersisted();
+    }
+
+    /** @returns {{enabled: boolean, key: string}} Detached optional persistence configuration. */
+    get stylesPersistence() {
+        return this.#styleController.persistence;
+    }
+
+    /**
+     * Selects optional origin-local storage. Existing explicit patches take priority over restored values.
+     * Configure before insertion to disable reads; switching keys never writes automatically.
+     * @param {{enabled?: boolean, key?: string}} value - Partial configuration; enabled defaults true, key defaults pref-viewer/styles.
+     * @returns {void} Refreshes mounted controls and primary highlights without reloading assets.
+     */
+    set stylesPersistence(value) {
+        this.#styleController.setPersistence(value);
+        this.#controlsPresentation?.refresh();
+        this.#component3D?.refreshViewCube?.();
+        if (this.#isInitialized) {
+            this.#applyRenderSettings({ highlightColor: this.#styleController.primaryColor, persist: false });
+        }
     }
 
     /**
@@ -1534,9 +1552,10 @@ export default class PrefViewer extends HTMLElement {
 
     /**
      * Defines the elements that the host application considers selectable.
-     * The normalized state is rendered by the 2D component as non-destructive yellow SVG clones.
+     * The normalized state is forwarded to both renderers: SVG selection clones in 2D and material overlays in 3D.
+     * Emits pref-viewer-selection-state-changed after applying the normalized state.
      * @public
-     * @param {Array<string|{id?: string, Id?: string}>} elements - Element ids or objects containing id/Id.
+     * @param {Array<string|{id?: string, Id?: string}>} [elements=[]] - Element ids or objects containing id/Id.
      * @returns {object} Current selection state.
      */
     setSelectableElements(elements = []) {
@@ -1549,7 +1568,7 @@ export default class PrefViewer extends HTMLElement {
     /**
      * Defines the currently selected elements using the semantic PrefViewer contract.
      * @public
-     * @param {Array<string|{id?: string, Id?: string, highlights?: string[], Highlights?: string[]}>} elements - Element ids or objects containing id/Id and optional highlights/Highlights.
+     * @param {Array<string|{id?: string, Id?: string, highlights?: string[], Highlights?: string[]}>} [elements=[]] - Element ids or objects containing id/Id and optional highlights/Highlights.
      * @returns {object} Current selection state.
      */
     setSelectedElements(elements = []) {
@@ -1564,7 +1583,7 @@ export default class PrefViewer extends HTMLElement {
     /**
      * Applies a complete host selection state in one call.
      * @public
-     * @param {{selectableIds?: Array<string|object>, selectables?: Array<string|object>, selectedItems?: Array<string|object>, selectedIds?: Array<string|object>, selected?: Array<string|object>}} state - Selection state with selectableIds/selectables and selectedItems/selectedIds/selected.
+     * @param {{selectableIds?: Array<string|object>, selectables?: Array<string|object>, selectedItems?: Array<string|object>, selectedIds?: Array<string|object>, selected?: Array<string|object>}} [state={}] - Selection state with selectableIds/selectables and selectedItems/selectedIds/selected.
      * @returns {object} Current selection state.
      */
     applySelectionState(state = {}) {
@@ -1923,6 +1942,7 @@ export default class PrefViewer extends HTMLElement {
      * @public
      * @param {object|string} value - Configuration payload or serialized JSON.
      * @param {boolean} [value.showRenderMenu] - Optional render-menu visibility for an object payload.
+     * @param {"svg"|"canvas"} [value.viewCubeRenderer] - Optional renderer applied with the queued configuration.
      * @param {boolean} [value.showViewCube] - Optional cube visibility for an object payload.
      * @throws {SyntaxError} If a supplied JSON string cannot be parsed.
      */
@@ -1984,10 +2004,14 @@ export default class PrefViewer extends HTMLElement {
         this.setOptions(value);
     }
 
+    /** @returns {object} Detached merged style overrides including the effective primary color; missing leaves use internal defaults. */
+    get styles() {
+        return this.#styleController.styles;
+    }
+
     /**
-     * Sends style updates to `setStyles()` enabling reactive bindings.
-     * @public
-     * @param {object|string} value - Style overrides object or JSON string.
+     * Queues the same validated partial appearance patch as setStyles().
+     * @param {object|string} value - Override tree or JSON; null leaves/groups restore defaults.
      */
     set styles(value) {
         this.setStyles(value);