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

package/src/pref-viewer-menu-3d.js

@@ -5,6 +5,8 @@ import I18n from "./localization/i18n.js";
 /**
  * PrefViewerMenu3D - Localized floating control panel for Babylon.js render settings.
  *
+ * Shares its viewer control presentation; supports explicit touch open/close and hover on fine pointers.
+ * Owns temporary touch-press feedback until release/cancellation, focus loss or disconnection.
  * Renders a gear-icon toggle button that appears on viewer hover and opens a panel with:
  *  - Boolean switches for every boolean render setting (AA, SSAO, IBL, shadows, highlight, etc.).
  *  - A hue slider for the highlight color.
@@ -62,6 +64,54 @@ export default class PrefViewerMenu3D extends HTMLElement {
         onToggleEnter: null,
     };
 
+    #touchPressedControl = null;
+    #touchPointerId = null;
+
+    /**
+     * Marks one enabled touch control while the finger is down, independent of native :active timing.
+     * A second touch cancels the current feedback without changing values or preventing native scrolling/input.
+     * @param {PointerEvent} event - Pointer down bubbling from this menu.
+     * @returns {void}
+     */
+    #onTouchPress = event => {
+        if (event.pointerType !== "touch") {
+            return;
+        }
+        if (this.#touchPressedControl) {
+            this.#clearTouchPress();
+            return;
+        }
+        const control = event.target.closest?.('button, input[type="range"], .menu-switch');
+        if (!control || !this.contains(control) || control.matches(':disabled, [data-disabled]')
+            || control.querySelector('input:disabled')) {
+            return;
+        }
+        this.#touchPressedControl = control;
+        this.#touchPointerId = event.pointerId;
+        control.setAttribute("data-touch-pressed", "");
+    };
+
+    /**
+     * Releases feedback for the active finger on pointer up or cancellation, including outside the menu.
+     * @param {PointerEvent} event - Document-level pointer completion.
+     * @returns {void}
+     */
+    #onTouchRelease = event => {
+        if (event.pointerId === this.#touchPointerId) {
+            this.#clearTouchPress();
+        }
+    };
+
+    /**
+     * Removes only this menu's owned touch-press state; also handles window blur and disconnection.
+     * @returns {void} Idempotent; does not change focus, settings, click handling or native range dragging.
+     */
+    #clearTouchPress = () => {
+        this.#touchPressedControl?.removeAttribute("data-touch-pressed");
+        this.#touchPressedControl = null;
+        this.#touchPointerId = null;
+    };
+
     #DEFAULT_RENDER_SETTINGS = { ...BabylonJSController.config.render.defaultSettings };
     // Only include boolean settings as switches; scalar settings are handled by sliders.
     #MENU_SWITCHES = Object.keys(this.#DEFAULT_RENDER_SETTINGS).filter(key =>
@@ -144,7 +194,7 @@ export default class PrefViewerMenu3D extends HTMLElement {
     }
 
     /**
-     * Builds the internal DOM structure for the toggle button, panel, switches, color slider, and lighting controls.
+     * Builds localized toggle/close controls and an initially inert panel with switches and sliders.
      * @private
      * @returns {void}
      */
@@ -152,11 +202,12 @@ export default class PrefViewerMenu3D extends HTMLElement {
         const wrapper = document.createElement("div");
         wrapper.className = "menu-wrapper";
         wrapper.innerHTML = `
-            <button class="menu-toggle" type="button" aria-label="${this.#texts.title}">
+            <button class="menu-toggle" type="button" aria-expanded="false" aria-label="${this.#texts.title}">
                 <svg viewBox="0 0 24 24"><path d="M12,8A4,4 0 0,1 16,12A4,4 0 0,1 12,16A4,4 0 0,1 8,12A4,4 0 0,1 12,8M12,10A2,2 0 0,0 10,12A2,2 0 0,0 12,14A2,2 0 0,0 14,12A2,2 0 0,0 12,10M10,22C9.75,22 9.54,21.82 9.5,21.58L9.13,18.93C8.5,18.68 7.96,18.34 7.44,17.94L4.95,18.95C4.73,19.03 4.46,18.95 4.34,18.73L2.34,15.27C2.21,15.05 2.27,14.78 2.46,14.63L4.57,12.97L4.5,12L4.57,11L2.46,9.37C2.27,9.22 2.21,8.95 2.34,8.73L4.34,5.27C4.46,5.05 4.73,4.96 4.95,5.05L7.44,6.05C7.96,5.66 8.5,5.32 9.13,5.07L9.5,2.42C9.54,2.18 9.75,2 10,2H14C14.25,2 14.46,2.18 14.5,2.42L14.87,5.07C15.5,5.32 16.04,5.66 16.56,6.05L19.05,5.05C19.27,4.96 19.54,5.05 19.66,5.27L21.66,8.73C21.79,8.95 21.73,9.22 21.54,9.37L19.43,11L19.5,12L19.43,13L21.54,14.63C21.73,14.78 21.79,15.05 21.66,15.27L19.66,18.73C19.54,18.95 19.27,19.04 19.05,18.95L16.56,17.95C16.04,18.34 15.5,18.68 14.87,18.93L14.5,21.58C14.46,21.82 14.25,22 14,22H10M11.25,4L10.88,6.61C9.68,6.86 8.62,7.5 7.85,8.39L5.44,7.35L4.69,8.65L6.8,10.2C6.4,11.37 6.4,12.64 6.8,13.8L4.68,15.36L5.43,16.66L7.86,15.62C8.63,16.5 9.68,17.14 10.87,17.38L11.24,20H12.76L13.13,17.39C14.32,17.14 15.37,16.5 16.14,15.62L18.57,16.66L19.32,15.36L17.2,13.81C17.6,12.64 17.6,11.37 17.2,10.2L19.31,8.65L18.56,7.35L16.15,8.39C15.38,7.5 14.32,6.86 13.12,6.62L12.75,4H11.25Z" /></svg>
             </button>
-            <div class="menu-panel" role="dialog" aria-label="${this.#texts.title}">
+            <div class="menu-panel" inert aria-hidden="true" role="dialog" aria-label="${this.#texts.title}">
                 <div class="menu-header">
+                    <button class="menu-close" type="button" aria-label="${this.#texts.actions.close}">×</button>
                     <p class="menu-title">${this.#texts.title}</p>
                     <p class="menu-subtitle">${this.#texts.subtitle}</p>
                 </div>
@@ -231,7 +282,7 @@ export default class PrefViewerMenu3D extends HTMLElement {
     /**
      * Normalizes locale data into a predictable shape consumed by the UI helpers.
      * @private
-     * @returns {{title: string, subtitle: string, actions: {play: string, pause: string}, features: object}} Structured copy bundle for titles, actions, and feature labels.
+     * @returns {{title: string, subtitle: string, actions: {play: string, pause: string, close: string}, features: object}} Structured copy bundle for titles, actions, and feature labels.
      */
     #getMenuTexts() {
         const data = this.#getMenuNamespace();
@@ -241,13 +292,14 @@ export default class PrefViewerMenu3D extends HTMLElement {
             actions: {
                 play: data.actions?.play || "",
                 pause: data.actions?.pause || "",
+                close: data.actions?.close || "Close",
             },
             features: data.features || {},
         };
     }
 
     /**
-     * Replaces all textual UI nodes with the latest localized strings.
+     * Replaces all textual UI nodes, including the close action, with the latest localized strings.
      * @private
      * @returns {void}
      */
@@ -257,6 +309,7 @@ export default class PrefViewerMenu3D extends HTMLElement {
         }
         this.#elements.toggleButton.setAttribute("aria-label", this.#texts.title);
         this.#elements.panel?.setAttribute("aria-label", this.#texts.title);
+        this.#elements.closeButton?.setAttribute("aria-label", this.#texts.actions.close);
         if (this.#elements.title) {
             this.#elements.title.textContent = this.#texts.title;
         }
@@ -308,13 +361,14 @@ export default class PrefViewerMenu3D extends HTMLElement {
     }
 
     /**
-     * Caches references to frequently used DOM nodes for event binding and UI synchronization.
+     * Caches toggle/close actions and settings nodes for event binding and UI synchronization.
      * @private
      * @returns {void}
      */
     #cacheElements() {
         this.#elements.toggleButton = this.querySelector(".menu-toggle");
         this.#elements.panel = this.querySelector(".menu-panel");
+        this.#elements.closeButton = this.querySelector(".menu-close");
         this.#elements.title = this.querySelector(".menu-title");
         this.#elements.subtitle = this.querySelector(".menu-subtitle");
 
@@ -348,7 +402,8 @@ export default class PrefViewerMenu3D extends HTMLElement {
     }
 
     /**
-     * Attaches all interactive event listeners for hover, focus, switch, color, and lighting controls.
+     * Attaches hover/focus, touch-press feedback, explicit toggle/close and settings listeners.
+     * Retains document completion/window blur subscriptions for feedback cleanup during teardown.
      * @private
      * @returns {void}
      */
@@ -356,9 +411,37 @@ export default class PrefViewerMenu3D extends HTMLElement {
         if (!this.#elements.toggleButton || !this.#elements.panel) {
             return;
         }
-        this.#handles.onToggleEnter = () => this.#openMenu();
-        this.#handles.onPanelEnter = () => this.#openMenu();
+        /** Opens on hover/focus only for compact fine-pointer presentation. @returns {void} */
+        this.#handles.onToggleEnter = () => {
+            if (!this.#usesTouchControls()) {
+                this.#openMenu();
+            }
+        };
+        /** Toggles on trusted click/tap without requiring synthetic mouse hover. @returns {void} */
+        this.#handles.onToggleClick = () => {
+            if (this.#usesTouchControls()) {
+                this.hasAttribute("data-open") ? this.#closeMenu() : this.#openMenu();
+            }
+        };
+        /** Closes explicitly and returns keyboard focus to the trigger. @returns {void} */
+        this.#handles.onCloseClick = () => { this.#elements.toggleButton.focus(); this.#closeMenu(); };
+        /** Closes the settings panel when Escape is pressed. @param {KeyboardEvent} event - Panel key event. @returns {void} */
+        this.#handles.onPanelKeyDown = event => {
+            if (event.key === "Escape") {
+                this.#handles.onCloseClick();
+            }
+        };
+        /** Opens settings on actual fine-pointer hover. @returns {void} */
+        this.#handles.onPanelEnter = () => {
+            if (!this.#usesTouchControls()) {
+                this.#openMenu();
+            }
+        };
+        /** Keeps touch panels open on pointer leave. @param {MouseEvent} event - Leave event. @returns {void} */
         this.#handles.onHostLeave = (event) => {
+            if (this.#usesTouchControls()) {
+                return;
+            }
             if (event.relatedTarget && this.contains(event.relatedTarget)) {
                 return;
             }
@@ -369,6 +452,13 @@ export default class PrefViewerMenu3D extends HTMLElement {
         this.#handles.onLightingSliderInput = (event) => this.#handleLightingSliderInput(event);
         this.#handles.onLightingPlayClick = () => this.#toggleLightingPlayback();
 
+        this.addEventListener("pointerdown", this.#onTouchPress);
+        this.ownerDocument.addEventListener("pointerup", this.#onTouchRelease);
+        this.ownerDocument.addEventListener("pointercancel", this.#onTouchRelease);
+        this.ownerDocument.defaultView?.addEventListener("blur", this.#clearTouchPress);
+        this.#elements.toggleButton.addEventListener("click", this.#handles.onToggleClick);
+        this.#elements.closeButton.addEventListener("click", this.#handles.onCloseClick);
+        this.#elements.panel.addEventListener("keydown", this.#handles.onPanelKeyDown);
         this.#elements.toggleButton.addEventListener("mouseenter", this.#handles.onToggleEnter);
         this.#elements.toggleButton.addEventListener("focus", this.#handles.onToggleEnter);
         this.#elements.panel.addEventListener("mouseenter", this.#handles.onPanelEnter);
@@ -380,7 +470,8 @@ export default class PrefViewerMenu3D extends HTMLElement {
     }
 
     /**
-     * Removes previously attached event listeners, guarding against partially initialized states.
+     * Removes hover, touch feedback, explicit toggle/close, keyboard and settings listeners, guarding partial initialization.
+     * Clears owned press state and document/window subscriptions before disconnection.
      * @private
      * @returns {void}
      */
@@ -388,6 +479,14 @@ export default class PrefViewerMenu3D extends HTMLElement {
         if (!this.#elements.toggleButton) {
             return;
         }
+        this.removeEventListener("pointerdown", this.#onTouchPress);
+        this.ownerDocument.removeEventListener("pointerup", this.#onTouchRelease);
+        this.ownerDocument.removeEventListener("pointercancel", this.#onTouchRelease);
+        this.ownerDocument.defaultView?.removeEventListener("blur", this.#clearTouchPress);
+        this.#clearTouchPress();
+        this.#elements.toggleButton.removeEventListener("click", this.#handles.onToggleClick);
+        this.#elements.closeButton?.removeEventListener("click", this.#handles.onCloseClick);
+        this.#elements.panel?.removeEventListener("keydown", this.#handles.onPanelKeyDown);
         this.#elements.toggleButton.removeEventListener("mouseenter", this.#handles.onToggleEnter);
         this.#elements.toggleButton.removeEventListener("focus", this.#handles.onToggleEnter);
         this.#elements.panel?.removeEventListener("mouseenter", this.#handles.onPanelEnter);
@@ -399,24 +498,40 @@ export default class PrefViewerMenu3D extends HTMLElement {
     }
 
     /**
-     * Opens the menu panel when the viewer is hovered and the menu is enabled.
+     * Reads inherited presentation state without installing a second capability observer.
+     * @private
+     * @returns {boolean} True for comfortable controls or an actual primary coarse pointer.
+     */
+    #usesTouchControls() {
+        const surface = this.closest("[data-controls-density]");
+        return surface?.dataset.controlsDensity === "comfortable" || surface?.dataset.controlsTouch === "true";
+    }
+
+    /**
+     * Opens enabled settings for touch presentation or an actually hovered viewer; exposes panel focus targets.
      * @private
      * @returns {void}
      */
     #openMenu() {
-        if (!this.#isEnabled || !this.hasAttribute("data-viewer-hover")) {
+        if (!this.#isEnabled || (!this.#usesTouchControls() && !this.hasAttribute("data-viewer-hover"))) {
             return;
         }
         this.setAttribute("data-open", "true");
+        this.#elements.toggleButton?.setAttribute("aria-expanded", "true");
+        this.#elements.panel?.removeAttribute("inert");
+        this.#elements.panel?.setAttribute("aria-hidden", "false");
     }
 
     /**
-     * Closes the menu panel and removes its open state attribute.
+     * Closes settings, synchronizes expanded state and removes hidden panel controls from keyboard navigation.
      * @private
      * @returns {void}
      */
     #closeMenu() {
         this.removeAttribute("data-open");
+        this.#elements.toggleButton?.setAttribute("aria-expanded", "false");
+        this.#elements.panel?.setAttribute("inert", "");
+        this.#elements.panel?.setAttribute("aria-hidden", "true");
     }
 
     /**
@@ -748,7 +863,7 @@ export default class PrefViewerMenu3D extends HTMLElement {
     /**
      * Sets the locale used for menu labels and helper text.
      * @public
-     * @param {string} cultureId - Locale identifier, e.g., "en-EN".
+     * @param {string} [cultureId=I18n.DEFAULT_LOCALE] - Locale identifier, e.g., "en-EN".
      * @returns {void}
      */
     setCulture(cultureId = I18n.DEFAULT_LOCALE) {
@@ -778,7 +893,7 @@ export default class PrefViewerMenu3D extends HTMLElement {
     /**
      * Applies a new render settings snapshot to the UI and clears the applying state.
      * @public
-     * @param {object} settings - Render settings snapshot from PrefViewer or BabylonJSController.
+     * @param {object} [settings={}] - Render settings snapshot from PrefViewer or BabylonJSController.
      * @returns {void}
      */
     setSettings(settings = {}) {
@@ -796,7 +911,7 @@ export default class PrefViewerMenu3D extends HTMLElement {
     }
 
     /**
-     * Receives viewer hover state so the menu only opens when the user interacts with the 3D viewport.
+     * Receives hover state; pointer leave closes fine-pointer settings while touch panels require explicit close.
      * @public
      * @param {boolean} isHovering - True when the viewer is hovered.
      * @returns {void}
@@ -809,7 +924,9 @@ export default class PrefViewerMenu3D extends HTMLElement {
             this.setAttribute("data-viewer-hover", "true");
         } else {
             this.removeAttribute("data-viewer-hover");
-            this.#closeMenu();
+            if (!this.#usesTouchControls()) {
+                this.#closeMenu();
+            }
         }
     }
 

package/src/pref-viewer-style-controller.js

@@ -0,0 +1,320 @@
+import * as ViewerStyles from "./styles.js";
+
+/**
+ * Owns one root viewer's validated appearance, explicit patches and optional saved preferences.
+ * Projects values onto a shadow-internal boundary; never mutates shared defaults or the public host style.
+ * No observers or graphics resources are owned. Reattach after reconnect to replace the owned boundary stylesheet.
+ */
+export default class PrefViewerStyleController {
+    static #DEFAULT_PRIMARY = ViewerStyles.PrefViewerViewCubePalette.colors.hover;
+    static #FIELDS = Object.freeze({
+        colorPrimary: ["color", "--pref-viewer-color-primary"],
+        "viewCube.colors.face": ["color", "--pref-viewer-view-cube-fill-color"],
+        "viewCube.colors.edge": ["color", "--pref-viewer-view-cube-edge-color"],
+        "viewCube.colors.corner": ["color", "--pref-viewer-view-cube-corner-color"],
+        "viewCube.colors.border": ["color", "--pref-viewer-view-cube-border-color"],
+        "viewCube.colors.text": ["color", "--pref-viewer-view-cube-text-color"],
+        "viewCube.colors.hover": ["color", "--pref-viewer-view-cube-hover-color"],
+        "viewCube.colors.active": ["color", "--pref-viewer-view-cube-active-color"],
+        "viewCube.hoverOpacity": ["opacity", "--pref-viewer-view-cube-hover-opacity"],
+        "viewCube.activeOpacity": ["opacity", "--pref-viewer-view-cube-active-opacity"],
+        "viewCube.typography.fontFamily": ["family", "--pref-viewer-view-cube-text-font-family"],
+        "viewCube.typography.fontSize": ["size", "--pref-viewer-view-cube-text-font-size"],
+        "viewCube.typography.fontWeight": ["weight", "--pref-viewer-view-cube-text-font-weight"],
+        "viewCube.typography.letterSpacing": ["spacing", "--pref-viewer-view-cube-text-letter-spacing"],
+        "viewCube.typography.textTransform": ["transform", "--pref-viewer-view-cube-text-transform"],
+    });
+    #document;
+    #surface = null;
+    #boundary = null;
+    #primaryColor = PrefViewerStyleController.#DEFAULT_PRIMARY;
+    #saved = new Map();
+    #explicit = new Map();
+    #persistence = { enabled: true, key: ViewerStyles.PREF_VIEWER_STYLES_STORAGE_KEY };
+
+    /** @param {Document} document - Owning document, used for CSS validation and best-effort origin storage. */
+    constructor(document) {
+        this.#document = document;
+    }
+
+    /** @returns {object} Detached merged overrides, including the effective primary default; omitted leaves use component defaults. */
+    get styles() {
+        return { colorPrimary: PrefViewerStyleController.#DEFAULT_PRIMARY, ...PrefViewerStyleController.#expand(this.#values()) };
+    }
+
+    /** @returns {string} Opaque sRGB hex primary for Babylon materials; resolved when projecting the current API styles. */
+    get primaryColor() {
+        return this.#primaryColor;
+    }
+
+    /** @returns {{enabled: boolean, key: string}} Detached persistence configuration; keys address this origin's localStorage. */
+    get persistence() {
+        return { ...this.#persistence };
+    }
+
+    /**
+     * Configures storage without writing it. An attached viewer reloads the selected key, preserving explicit patches/reset markers.
+     * @param {{enabled?: boolean, key?: string}} value - Partial options; invalid leaves are ignored. Disable before insertion to avoid reads.
+     * @returns {void} Storage failures leave explicit styles and defaults usable.
+     */
+    setPersistence(value) {
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+            return;
+        }
+        if (typeof value.enabled === "boolean") {
+            this.#persistence.enabled = value.enabled;
+        }
+        if (typeof value.key === "string" && value.key.trim()) {
+            this.#persistence.key = value.key.trim();
+        }
+        if (this.#surface) {
+            this.#restore();
+            this.#project();
+        }
+    }
+
+    /**
+     * Installs the CSS inheritance boundary and restores the selected saved layer without writing preferences.
+     * Internal density/layout rules are appended later and override reset tokens at the same specificity.
+     * @param {HTMLElement} surface - The root viewer's wrapper inside its ShadowRoot, never the public host.
+     * @returns {void} Reattachment releases the previous owned stylesheet and preserves explicit patches.
+     */
+    attach(surface) {
+        this.#boundary?.remove();
+        this.#surface = surface;
+        this.#boundary = this.#document.createElement("style");
+        const templates = Object.values(ViewerStyles).filter(value => typeof value === "string");
+        templates.push(ViewerStyles.PrefViewerViewCubePalette.styles, ViewerStyles.PrefViewerViewCubeTypography.styles);
+        const tokens = new Set(templates.join("\n").match(/--[a-zA-Z][\w-]*/g));
+        tokens.add("--pref-viewer-view-cube-inset-right");
+        this.#boundary.textContent = `.pref-viewer-wrapper {\n    all: initial;\n    direction: ltr;\n    unicode-bidi: isolate;\n${[...tokens].map(token => `    ${token}: initial;`).join("\n")}\n}`;
+        surface.prepend(this.#boundary);
+        this.#restore();
+        this.#project();
+    }
+
+    /**
+     * Applies a partial patch. Null leaves/groups reset matching saved and explicit customizations; unknown/invalid values are ignored.
+     * @param {object} patch - Supported style tree, already parsed by the public facade.
+     * @returns {boolean} Whether at least one valid leaf or reset was accepted; accepted patches persist best-effort.
+     */
+    update(patch) {
+        const changes = this.#normalize(patch);
+        if (!changes.size) {
+            return false;
+        }
+        for (const [path, value] of changes) {
+            this.#explicit.set(path, value);
+        }
+        this.#project();
+        this.#persist();
+        return true;
+    }
+
+    /**
+     * Removes only the configured storage entry; current appearance remains intact and a later patch may save it again.
+     * @returns {boolean} True on successful removal; false when persistence is disabled or storage is unavailable.
+     */
+    clearPersisted() {
+        if (!this.#persistence.enabled) {
+            return false;
+        }
+        try {
+            const storage = this.#document.defaultView?.localStorage;
+            if (!storage) {
+                return false;
+            }
+            storage.removeItem(this.#persistence.key);
+            return true;
+        } catch (_error) {
+            return false;
+        }
+    }
+
+    /** @returns {Map<string, string|number>} Effective overrides after applying explicit values and reset markers to stored values. */
+    #values() {
+        const values = new Map(this.#saved);
+        for (const [path, value] of this.#explicit) {
+            if (value === null) {
+                values.delete(path);
+            } else {
+                values.set(path, value);
+            }
+        }
+        return values;
+    }
+
+    /**
+     * Whitelists known leaves; a null group expands to individual reset markers so later partial changes cannot revive saved siblings.
+     * @param {object} input - Candidate style tree; arrays and non-objects are ignored.
+     * @returns {Map<string, string|number|null>} Accepted flattened leaves; no caller object references are retained.
+     */
+    #normalize(input) {
+        const result = new Map();
+        if (!input || typeof input !== "object" || Array.isArray(input)) {
+            return result;
+        }
+        for (const [path, [kind]] of Object.entries(PrefViewerStyleController.#FIELDS)) {
+            let value = input;
+            for (const segment of path.split(".")) {
+                if (value === null) {
+                    break;
+                }
+                if (!value || typeof value !== "object" || Array.isArray(value) || !Object.hasOwn(value, segment)) {
+                    value = undefined;
+                    break;
+                }
+                value = value[segment];
+            }
+            if (value === null || this.#valid(kind, value)) {
+                result.set(path, typeof value === "string" ? value.trim() : value);
+            }
+        }
+        return result;
+    }
+
+    /**
+     * Validates a leaf with native CSS parsing for colors/families and explicit numeric/enum constraints elsewhere.
+     * @param {string} kind - Internal schema validation kind.
+     * @param {*} value - Candidate leaf; CSS references and inheritance keywords are rejected.
+     * @returns {boolean} Whether the value is independent of external CSS and valid for the supported field.
+     */
+    #valid(kind, value) {
+        if (["opacity", "size", "weight", "spacing"].includes(kind)) {
+            if (typeof value !== "number" || !Number.isFinite(value)) {
+                return false;
+            }
+            if (kind === "opacity") {
+                return value >= 0 && value <= 1;
+            }
+            if (kind === "weight") {
+                return Number.isInteger(value) && value >= 1 && value <= 1000;
+            }
+            return kind === "size" ? value > 0 : value >= 0;
+        }
+        if (typeof value !== "string" || !value.trim() || /[;{}]|\b(?:var|env)\s*\(|\b(?:inherit|initial|unset|revert|revert-layer|currentcolor)\b/i.test(value)) {
+            return false;
+        }
+        if (kind === "transform") {
+            return ["none", "uppercase", "lowercase"].includes(value.trim());
+        }
+        const style = this.#document.createElement("span").style;
+        const property = kind === "color" ? "color" : "font-family";
+        style.setProperty(property, value.trim());
+        return Boolean(style.getPropertyValue(property));
+    }
+
+    /**
+     * Expands a whitelist-generated flat map to a detached JSON-safe object.
+     * @param {Map<string, string|number>} values - Known schema paths, excluding reset markers.
+     * @returns {object} Nested override tree suitable for getters and storage.
+     */
+    static #expand(values) {
+        const result = {};
+        for (const [path, value] of values) {
+            const segments = path.split(".");
+            let target = result;
+            for (const segment of segments.slice(0, -1)) {
+                target = target[segment] ??= {};
+            }
+            target[segments.at(-1)] = value;
+        }
+        return result;
+    }
+
+    /** @returns {void} Replaces the saved layer from the configured key; corrupt/unsupported data and inaccessible storage are ignored. */
+    #restore() {
+        this.#saved.clear();
+        if (!this.#persistence.enabled) {
+            return;
+        }
+        try {
+            const serialized = this.#document.defaultView?.localStorage?.getItem(this.#persistence.key);
+            const data = serialized ? JSON.parse(serialized) : null;
+            if (!data || typeof data !== "object" || Array.isArray(data)) {
+                return;
+            }
+            const patch = data.version === 1 ? data.styles : !Object.hasOwn(data, "version") ? { colorPrimary: data.colorPrimary } : null;
+            this.#saved = new Map([...this.#normalize(patch)].filter(([, value]) => value !== null));
+        } catch (_error) {
+            // Storage is optional; explicit styles remain available.
+        }
+    }
+
+    /** @returns {void} Writes only effective overrides with schema version 1; blocked/full storage never interrupts viewer work. */
+    #persist() {
+        if (!this.#persistence.enabled) {
+            return;
+        }
+        try {
+            const styles = PrefViewerStyleController.#expand(this.#values());
+            this.#document.defaultView?.localStorage?.setItem(this.#persistence.key, JSON.stringify({ version: 1, styles }));
+        } catch (_error) {
+            // Rendering and queue processing continue when storage cannot be written.
+        }
+    }
+
+    /** @returns {void} Projects API values and fixed inherited typography onto the internal wrapper without changing the public host. */
+    #project() {
+        if (!this.#surface) {
+            return;
+        }
+        const values = this.#values();
+        const style = this.#surface.style;
+        style.fontFamily = ViewerStyles.PrefViewerStyleVariables.fontFamily;
+        style.fontSize = ViewerStyles.PrefViewerStyleVariables.fontSize;
+        style.fontWeight = "400";
+        style.fontStyle = "normal";
+        style.lineHeight = "1.2";
+        style.color = "#000000";
+        style.letterSpacing = "normal";
+        style.wordSpacing = "normal";
+        style.textTransform = "none";
+        style.textShadow = "none";
+        style.textAlign = "start";
+        for (const [path, [kind, token]] of Object.entries(PrefViewerStyleController.#FIELDS)) {
+            if (values.has(path)) {
+                const value = values.get(path);
+                style.setProperty(token, ["size", "spacing"].includes(kind) ? `${value}px` : String(value));
+            } else {
+                style.removeProperty(token);
+            }
+        }
+        this.#primaryColor = this.#resolvePrimary(this.styles.colorPrimary);
+        style.setProperty("--pref-viewer-color-primary", this.#primaryColor);
+    }
+
+    /**
+     * Resolves a validated CSS color to opaque sRGB for Babylon's hex-only material consumers.
+     * Uses computed RGB for common syntaxes and a one-pixel sRGB canvas for modern color functions.
+     * @param {string} color - Valid independent CSS color, including named colors and short hex.
+     * @returns {string} Six-digit hex, falling back to the default when browser normalization is unavailable.
+     */
+    #resolvePrimary(color) {
+        const probe = this.#document.createElement("span");
+        probe.style.color = color;
+        probe.style.display = "none";
+        this.#surface.append(probe);
+        try {
+            const computed = this.#document.defaultView.getComputedStyle(probe).color;
+            const rgb = /^rgba?\(\s*([\d.]+)[,\s]+([\d.]+)[,\s]+([\d.]+)/i.exec(computed);
+            let channels;
+            if (rgb) {
+                channels = rgb.slice(1, 4).map(Number);
+            } else {
+                const canvas = this.#document.createElement("canvas");
+                canvas.width = canvas.height = 1;
+                const context = canvas.getContext("2d", { willReadFrequently: true });
+                if (!context) {
+                    return PrefViewerStyleController.#DEFAULT_PRIMARY;
+                }
+                context.fillStyle = color;
+                context.fillRect(0, 0, 1, 1);
+                channels = Array.from(context.getImageData(0, 0, 1, 1).data).slice(0, 3);
+            }
+            return `#${channels.map(channel => Math.max(0, Math.min(255, Math.round(channel))).toString(16).padStart(2, "0")).join("")}`;
+        } finally {
+            probe.remove();
+        }
+    }
+}