@5even7/dlc-ui 0.2.11 → 0.2.12

package/dist/index.umd.js

@@ -189,9 +189,9 @@
     }
   }
 
-  /**
-   * Tiny event emitter. Accepts any event name so the API stays open for
-   * future events (hover, click, custom) without breaking changes.
+  /**
+   * Tiny event emitter. Accepts any event name so the API stays open for
+   * future events (hover, click, custom) without breaking changes.
    */
   function createEmitter() {
     // Plain object storage (no Map/Set) so the legacy build has no API
@@ -241,9 +241,9 @@
 
   var UNIT_PATTERN = /^[\d.]+(?:px|%|vw|vh|vmin|vmax|em|rem)$/;
 
-  /**
-   * Normalize a size option to a CSS length string.
-   * Accepts numbers (treated as px) or strings with px/%, vw/vh/vmin/vmax, em/rem.
+  /**
+   * Normalize a size option to a CSS length string.
+   * Accepts numbers (treated as px) or strings with px/%, vw/vh/vmin/vmax, em/rem.
    */
   function parseSize(value) {
     if (typeof value === 'number') {
@@ -282,11 +282,17 @@
     var tier = QUALITY_TIERS[quality] || QUALITY_TIERS.medium;
     return tier.dpr;
   }
+  function effectiveDprCap(quality) {
+    var renderScale = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 1;
+    var scale = Number(renderScale);
+    var normalizedScale = Number.isFinite(scale) ? Math.min(1, Math.max(0.25, scale)) : 1;
+    return Math.max(0.5, dprCapFor(quality) * normalizedScale);
+  }
 
-  /**
-   * Merge defaults < preset < user. Unknown user keys are preserved so the
-   * component API can grow (new props, cssVars, callbacks) without a breaking
-   * change.
+  /**
+   * Merge defaults < preset < user. Unknown user keys are preserved so the
+   * component API can grow (new props, cssVars, callbacks) without a breaking
+   * change.
    */
   function normalizeOptions(defaults, preset, user) {
     // undefined means "not provided" (e.g. Vue $props with unset props):
@@ -304,9 +310,9 @@
     return _objectSpread2(_objectSpread2(_objectSpread2({}, defaults), presetOptions), userOptions);
   }
 
-  /**
-   * 公共色板：NC-01~NC-06 的四色组（底色 / 主色 / 辅色 / 高光色）。
-   * Capsule 预置与 dlc-color 等组件共用，新增色板只改这里。
+  /**
+   * 公共色板：NC-01~NC-06 的四色组（底色 / 主色 / 辅色 / 高光色）。
+   * Capsule 预置与 dlc-color 等组件共用，新增色板只改这里。
    */
   var PALETTES$1 = {
     original: ['#FFF3EA', '#F5B27A', '#F67BC6', '#A978E8'],
@@ -317,9 +323,9 @@
     plus: ['#FFF0E6', '#F6C26B', '#F98A64', '#E86D74']
   };
 
-  /**
-   * Capsule 预置：仅星云材质 NC-01~NC-06（NC-07~09 aurora 已移除）。
-   * 颜色引用公共色板，seed/speed 决定形态与流速。
+  /**
+   * Capsule 预置：仅星云材质 NC-01~NC-06（NC-07~09 aurora 已移除）。
+   * 颜色引用公共色板，seed/speed 决定形态与流速。
    */
   var CAPSULE_PRESETS = [{
     id: 'original',
@@ -438,6 +444,11 @@
       height: 160,
       quality: 'auto',
       renderer: 'auto',
+      renderScale: 1,
+      powerPreference: 'high-performance',
+      fps: 60,
+      paused: false,
+      static: false,
       respectReducedMotion: true,
       mouseColor: true,
       textRatio: 39
@@ -447,13 +458,22 @@
       height: 104,
       min: 0,
       max: 100,
+      step: 'any',
       draggable: true,
+      keyboard: true,
       disabled: false,
       readonly: false,
+      direction: 'ltr',
+      precision: 0,
       valueSuffix: '%',
       edgeStyle: 'flow',
       quality: 'auto',
       renderer: 'auto',
+      renderScale: 1,
+      powerPreference: 'high-performance',
+      fps: 60,
+      paused: false,
+      static: false,
       textRatio: 54,
       showValue: true,
       respectReducedMotion: true
@@ -743,7 +763,7 @@
         alpha: false,
         antialias: false,
         depth: false,
-        powerPreference: 'high-performance',
+        powerPreference: this.options.powerPreference || 'high-performance',
         preserveDrawingBuffer: false
       });
       if (!this.gl) throw new Error('WebGL2 is not available');
@@ -754,16 +774,19 @@
       this.motion = 0;
       this.motionTarget = 0;
       this.timeOffset = preset.seed * 0.73;
+      this.colors = preset.colors.map(hexToRgb01$1);
       this.visible = true;
       this.disposed = false;
       _assertClassBrand(_CosmicRenderer_brand, this, _setupGeometry).call(this);
       _assertClassBrand(_CosmicRenderer_brand, this, _bindEvents).call(this);
+      _assertClassBrand(_CosmicRenderer_brand, this, _bindContextEvents).call(this);
       this.resize();
     }
     return _createClass(CosmicRenderer, [{
       key: "setPreset",
       value: function setPreset(preset) {
         this.preset = _objectSpread2({}, preset);
+        this.colors = preset.colors.map(hexToRgb01$1);
         this.timeOffset = preset.seed * 0.73;
       }
     }, {
@@ -808,15 +831,14 @@
         if (this.canvas.width !== width || this.canvas.height !== height) {
           this.canvas.width = width;
           this.canvas.height = height;
-          this.gl.viewport(0, 0, width, height);
         }
+        this.gl.viewport(0, 0, width, height);
       }
     }, {
       key: "draw",
       value: function draw(elapsedSeconds) {
         var paused = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : false;
         if (this.disposed || !this.visible) return;
-        this.resize();
         var gl = this.gl;
         this.pointer[0] += (this.pointerTarget[0] - this.pointer[0]) * 0.08;
         this.pointer[1] += (this.pointerTarget[1] - this.pointer[1]) * 0.08;
@@ -825,16 +847,15 @@
         gl.bindBuffer(gl.ARRAY_BUFFER, this.buffer);
         gl.enableVertexAttribArray(this.locations.position);
         gl.vertexAttribPointer(this.locations.position, 2, gl.FLOAT, false, 0, 0);
-        var colors = this.preset.colors.map(hexToRgb01$1);
         gl.uniform2f(this.locations.resolution, this.canvas.width, this.canvas.height);
         gl.uniform1f(this.locations.time, this.timeOffset + (paused ? 0 : elapsedSeconds * this.preset.speed));
         gl.uniform1f(this.locations.seed, this.preset.seed);
         gl.uniform1f(this.locations.motion, this.motion);
         gl.uniform2f(this.locations.pointer, this.pointer[0], this.pointer[1]);
-        gl.uniform3fv(this.locations.colorA, colors[0]);
-        gl.uniform3fv(this.locations.colorB, colors[1]);
-        gl.uniform3fv(this.locations.colorC, colors[2]);
-        gl.uniform3fv(this.locations.colorD, colors[3]);
+        gl.uniform3fv(this.locations.colorA, this.colors[0]);
+        gl.uniform3fv(this.locations.colorB, this.colors[1]);
+        gl.uniform3fv(this.locations.colorC, this.colors[2]);
+        gl.uniform3fv(this.locations.colorD, this.colors[3]);
         gl.drawArrays(gl.TRIANGLES, 0, 3);
       }
     }, {
@@ -845,6 +866,8 @@
         target.removeEventListener('pointermove', this.onPointerMove);
         target.removeEventListener('pointerdown', this.onPointerMove);
         target.removeEventListener('pointerleave', this.onPointerLeave);
+        this.canvas.removeEventListener('webglcontextlost', this.onContextLost, false);
+        this.canvas.removeEventListener('webglcontextrestored', this.onContextRestored, false);
         this.gl.deleteBuffer(this.buffer);
         this.gl.deleteProgram(this.program);
         var lose = this.gl.getExtension('WEBGL_lose_context');
@@ -901,6 +924,26 @@
       passive: true
     });
   }
+  function _bindContextEvents() {
+    var _this3 = this;
+    this.onContextLost = function (event) {
+      event.preventDefault();
+      if (_this3.disposed) return;
+      _this3.visible = false;
+      if (typeof _this3.options.onContextLost === 'function') _this3.options.onContextLost(event);
+    };
+    this.onContextRestored = function () {
+      if (_this3.disposed) return;
+      _this3.program = createProgram$1(_this3.gl);
+      _this3.locations = _assertClassBrand(_CosmicRenderer_brand, _this3, _getLocations).call(_this3);
+      _assertClassBrand(_CosmicRenderer_brand, _this3, _setupGeometry).call(_this3);
+      _this3.visible = true;
+      _this3.resize();
+      if (typeof _this3.options.onContextRestored === 'function') _this3.options.onContextRestored();
+    };
+    this.canvas.addEventListener('webglcontextlost', this.onContextLost, false);
+    this.canvas.addEventListener('webglcontextrestored', this.onContextRestored, false);
+  }
 
   function rgb(color) {
     var alpha = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 1;
@@ -915,18 +958,20 @@
   }
   var FallbackRenderer = /*#__PURE__*/function () {
     function FallbackRenderer(canvas, preset) {
+      var options = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
       _classCallCheck(this, FallbackRenderer);
       this.canvas = canvas;
       this.preset = preset;
       this.context = canvas.getContext('2d');
       this.visible = true;
       this.timePhase = 0;
+      this.dprCap = options.dprCap || 1.5;
     }
     return _createClass(FallbackRenderer, [{
       key: "resize",
       value: function resize() {
         var rect = this.canvas.getBoundingClientRect();
-        var dpr = Math.min(window.devicePixelRatio || 1, 1.5);
+        var dpr = Math.min(window.devicePixelRatio || 1, this.dprCap);
         var width = Math.max(2, Math.round(rect.width * dpr));
         var height = Math.max(2, Math.round(rect.height * dpr));
         if (this.canvas.width !== width || this.canvas.height !== height) {
@@ -967,7 +1012,6 @@
       key: "draw",
       value: function draw(time) {
         if (!this.visible) return;
-        this.resize();
         this.drawNebula(time);
       }
     }, {
@@ -975,6 +1019,12 @@
       value: function setPreset(preset) {
         this.preset = preset;
       }
+    }, {
+      key: "setDprCap",
+      value: function setDprCap(cap) {
+        this.dprCap = cap;
+        this.resize();
+      }
     }, {
       key: "randomize",
       value: function randomize() {
@@ -992,10 +1042,10 @@
     }]);
   }();
 
-  /**
-   * Document-level shared rAF scheduler. Every component instance subscribes
-   * its own frame callback; the whole page runs ONE animation loop (like the
-   * original demo), which avoids jank from many competing rAF loops.
+  /**
+   * Document-level shared rAF scheduler. Every component instance subscribes
+   * its own frame callback; the whole page runs ONE animation loop (like the
+   * original demo), which avoids jank from many competing rAF loops.
    */
   var subscribers = [];
   var running = false;
@@ -1004,11 +1054,7 @@
   var last = 0;
   function tick(now) {
     if (!running) return;
-    var delta = last ? Math.min((now - last) / 1000, 0.05) : 0;
-    last = now;
-    // Schedule the next frame BEFORE running callbacks so one throwing
-    // subscriber can never kill the whole animation loop.
-    rafId = requestAnimationFrame(tick);
+    var activeItems = [];
     if (!globallyPaused) {
       var _iterator = _createForOfIteratorHelper(subscribers.slice()),
         _step;
@@ -1016,10 +1062,8 @@
         for (_iterator.s(); !(_step = _iterator.n()).done;) {
           var item = _step.value;
           try {
-            if (!item.isPaused()) item.onFrame(delta, now);
-          } catch (error) {
-            console.warn('[dlc-ui] frame error:', error);
-          }
+            if (!item.isPaused()) activeItems.push(item);
+          } catch (_unused) {}
         }
       } catch (err) {
         _iterator.e(err);
@@ -1027,6 +1071,25 @@
         _iterator.f();
       }
     }
+    if (activeItems.length === 0) {
+      running = false;
+      rafId = 0;
+      last = 0;
+      return;
+    }
+    var delta = last ? Math.min((now - last) / 1000, 0.05) : 0;
+    last = now;
+    // Schedule the next frame BEFORE running callbacks so one throwing
+    // subscriber can never kill the whole animation loop.
+    rafId = requestAnimationFrame(tick);
+    for (var _i = 0, _activeItems = activeItems; _i < _activeItems.length; _i++) {
+      var _item = _activeItems[_i];
+      try {
+        _item.onFrame(delta, now);
+      } catch (error) {
+        console.warn('[dlc-ui] frame error:', error);
+      }
+    }
     if (subscribers.length === 0) {
       cancelAnimationFrame(rafId);
       running = false;
@@ -1044,6 +1107,10 @@
   }
   function resumeAll() {
     globallyPaused = false;
+    start();
+  }
+  function wakeScheduler() {
+    start();
   }
   function subscribeScheduler(onFrame, isPaused) {
     var item = {
@@ -1063,11 +1130,12 @@
     };
   }
 
-  /**
-   * Gates drawing on "element intersects viewport AND the page tab is visible".
-   * Falls back to always-visible when IntersectionObserver is unavailable.
+  /**
+   * Gates drawing on "element intersects viewport AND the page tab is visible".
+   * Falls back to always-visible when IntersectionObserver is unavailable.
    */
   function createVisibilityGuard(element) {
+    var onChange = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : null;
     var intersecting = true;
     var pageVisible = typeof document === 'undefined' || !document.hidden;
     var disposed = false;
@@ -1077,6 +1145,7 @@
         intersecting = entries.some(function (entry) {
           return entry.isIntersecting;
         });
+        if (typeof onChange === 'function') onChange();
       }, {
         rootMargin: '180px'
       });
@@ -1084,6 +1153,7 @@
     }
     var onVisibilityChange = function onVisibilityChange() {
       pageVisible = typeof document !== 'undefined' && !document.hidden;
+      if (typeof onChange === 'function') onChange();
     };
     if (typeof document !== 'undefined') {
       document.addEventListener('visibilitychange', onVisibilityChange);
@@ -1119,18 +1189,69 @@
     }
   }
 
-  function prefersReducedMotion$2() {
-    return typeof matchMedia !== 'undefined' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+  function normalizeFps(value) {
+    var fallback = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 60;
+    var fps = Number(value);
+    if (!Number.isFinite(fps)) return fallback;
+    return Math.min(60, Math.max(1, fps));
+  }
+  function createFrameGate() {
+    var initialFps = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : 60;
+    var fps = normalizeFps(initialFps);
+    var elapsed = 0;
+    return {
+      shouldDraw: function shouldDraw(delta) {
+        elapsed += delta;
+        var interval = 1 / fps;
+        if (elapsed + 0.0001 < interval) return false;
+        elapsed %= interval;
+        return true;
+      },
+      setFps: function setFps(value) {
+        fps = normalizeFps(value, fps);
+        elapsed = 0;
+        return fps;
+      },
+      getFps: function getFps() {
+        return fps;
+      }
+    };
+  }
+  function createReducedMotionPreference(enabled, onChange) {
+    var query = enabled && typeof matchMedia !== 'undefined' ? matchMedia('(prefers-reduced-motion: reduce)') : null;
+    var notify = function notify() {
+      if (typeof onChange === 'function') onChange(Boolean(query && query.matches));
+    };
+    if (query) {
+      if (typeof query.addEventListener === 'function') query.addEventListener('change', notify);else if (typeof query.addListener === 'function') query.addListener(notify);
+    }
+    return {
+      matches: function matches() {
+        return Boolean(query && query.matches);
+      },
+      dispose: function dispose() {
+        if (!query) return;
+        if (typeof query.removeEventListener === 'function') query.removeEventListener('change', notify);else if (typeof query.removeListener === 'function') query.removeListener(notify);
+      }
+    };
   }
 
-  /**
+  function toFiniteNumber(value) {
+    if (value == null || typeof value === 'boolean') return null;
+    if (typeof value === 'string' && value.trim() === '') return null;
+    var number = Number(value);
+    return Number.isFinite(number) ? number : null;
+  }
+
+  /**
    * Mount a cosmic (nebula) capsule into `container`.
    *
    * Options: preset (literary name), width, height (number=px or string with
    * px/%/vw/vh/em/rem), colors, seed, speed, textRatio (0-100, text region
    * width in percent), text (HTML string or DOM nodes for the text slot),
    * colorContent (HTML string or DOM nodes for the color slot), quality,
-   * renderer, respectReducedMotion, mouseColor, cssVars.
+   * renderer, quality, renderScale, powerPreference, fps, paused/static,
+   * respectReducedMotion, mouseColor, cssVars.
    */
   function createCapsule(container) {
     var _options$preset;
@@ -1140,10 +1261,19 @@
     }
     var preset = _objectSpread2({}, getPreset('capsule', (_options$preset = options.preset) !== null && _options$preset !== void 0 ? _options$preset : '初光'));
     var merged = normalizeOptions(DEFAULTS.capsule, preset, options);
-    var normalizedColors = merged.colors.map(normalizeColor);
-    if (normalizedColors.every(Boolean)) preset.colors = normalizedColors;
-    preset.seed = merged.seed;
-    preset.speed = merged.speed;
+    var normalizedColors = Array.isArray(merged.colors) ? merged.colors.map(normalizeColor) : [];
+    if (normalizedColors.length === 4 && normalizedColors.every(Boolean)) preset.colors = normalizedColors;
+    var initialSeed = toFiniteNumber(merged.seed);
+    var initialSpeed = toFiniteNumber(merged.speed);
+    if (initialSeed !== null) preset.seed = initialSeed;
+    if (initialSpeed !== null) preset.speed = initialSpeed;
+    merged.colors = _toConsumableArray(preset.colors);
+    merged.seed = preset.seed;
+    merged.speed = preset.speed;
+    var optionColors = Array.isArray(options.colors) ? options.colors.map(normalizeColor) : [];
+    var colorOverride = optionColors.length === 4 && optionColors.every(Boolean) ? _toConsumableArray(optionColors) : null;
+    var seedOverride = options.seed !== undefined ? toFiniteNumber(options.seed) : null;
+    var speedOverride = options.speed !== undefined ? toFiniteNumber(options.speed) : null;
     var customLabel = typeof options.label === 'string' && options.label ? options.label : null;
     var root = document.createElement('div');
     root.className = 'hj-capsule-root hj-capsule-cosmic';
@@ -1195,25 +1325,49 @@
     root.appendChild(canvas);
     container.appendChild(root);
     var emitter = createEmitter();
-    var paused = merged.respectReducedMotion && prefersReducedMotion$2();
+    var manuallyPaused = merged.paused === true;
+    var reducedPaused = false;
+    var staticMode = merged.static === true;
+    var contextLost = false;
     var disposed = false;
+    var renderOnce = function renderOnce() {};
     var dirty = {
       preset: false,
       seed: false,
       speed: false,
       colors: false,
       textRatio: false,
-      cssVars: false
+      cssVars: false,
+      mouseColor: false,
+      quality: false,
+      renderScale: false,
+      paused: false,
+      static: false,
+      fps: false
     };
     var renderer;
     var useWebgl = merged.renderer !== 'canvas2d';
     if (useWebgl) {
       try {
         renderer = new CosmicRenderer(canvas, merged, {
-          dprCap: dprCapFor(merged.quality)
+          dprCap: effectiveDprCap(merged.quality, merged.renderScale),
+          mouseColor: merged.mouseColor !== false,
+          powerPreference: merged.powerPreference,
+          onContextLost: function onContextLost() {
+            contextLost = true;
+            emitter.emit('contextlost', {});
+          },
+          onContextRestored: function onContextRestored() {
+            contextLost = false;
+            emitter.emit('contextrestored', {});
+            renderOnce();
+            wakeScheduler();
+          }
         });
       } catch (error) {
-        renderer = new FallbackRenderer(canvas, merged);
+        renderer = new FallbackRenderer(canvas, merged, {
+          dprCap: effectiveDprCap(merged.quality, merged.renderScale)
+        });
         nextTick(function () {
           if (disposed) return;
           emitter.emit('error', {
@@ -1222,8 +1376,15 @@
         });
       }
     } else {
-      renderer = new FallbackRenderer(canvas, merged);
+      renderer = new FallbackRenderer(canvas, merged, {
+        dprCap: effectiveDprCap(merged.quality, merged.renderScale)
+      });
     }
+    var animationTime = 0;
+    var frameGate = createFrameGate(merged.fps);
+    renderOnce = function renderOnce() {
+      return renderer.draw(animationTime);
+    };
     var applySize = function applySize() {
       root.style.width = parseSize(merged.width);
       root.style.height = parseSize(merged.height);
@@ -1241,11 +1402,21 @@
       renderer.resize();
     };
     applySize();
-    var resizeObserver = typeof ResizeObserver !== 'undefined' ? new ResizeObserver(function () {
-      return renderer.resize();
-    }) : null;
-    if (resizeObserver) resizeObserver.observe(root);else window.addEventListener('resize', renderer.resize);
-    var visibility = createVisibilityGuard(root);
+    var resize = function resize() {
+      renderer.resize();
+      if (manuallyPaused || reducedPaused || staticMode) renderOnce();
+    };
+    var resizeObserver = typeof ResizeObserver !== 'undefined' ? new ResizeObserver(resize) : null;
+    if (resizeObserver) resizeObserver.observe(root);else window.addEventListener('resize', resize);
+    var visibility = createVisibilityGuard(root, wakeScheduler);
+    var motionPreference = createReducedMotionPreference(merged.respectReducedMotion, function (matches) {
+      reducedPaused = matches;
+      if (matches) renderOnce();else wakeScheduler();
+    });
+    reducedPaused = motionPreference.matches();
+    var isMotionPaused = function isMotionPaused() {
+      return manuallyPaused || reducedPaused || staticMode || contextLost;
+    };
     root.addEventListener('pointerenter', function () {
       return emitter.emit('pointerenter', {
         preset: _objectSpread2({}, preset)
@@ -1280,12 +1451,12 @@
         preset: _objectSpread2({}, preset)
       });
     });
-    var animationTime = 0;
+    renderOnce();
     var unsubscribe = subscribeScheduler(function (delta) {
       animationTime += delta;
-      if (visibility.isVisible()) renderer.draw(animationTime);
+      if (frameGate.shouldDraw(delta)) renderer.draw(animationTime);
     }, function () {
-      return paused;
+      return isMotionPaused() || !visibility.isVisible();
     });
     nextTick(function () {
       if (disposed) return;
@@ -1308,11 +1479,15 @@
         var next = getPreset('capsule', ref);
         dirty.preset = true;
         Object.assign(preset, next);
+        if (colorOverride) preset.colors = _toConsumableArray(colorOverride);
+        if (seedOverride !== null) preset.seed = seedOverride;
+        if (speedOverride !== null) preset.speed = speedOverride;
         var nextColors = preset.colors.map(normalizeColor);
         if (nextColors.every(Boolean)) preset.colors = nextColors;
         renderer.setPreset(_objectSpread2({}, preset));
         syncTheme();
         renderer.resize();
+        if (isMotionPaused()) renderOnce();
         emitter.emit('presetchange', {
           preset: _objectSpread2({}, next)
         });
@@ -1324,26 +1499,32 @@
           return !color;
         })) return this;
         dirty.colors = true;
+        colorOverride = _toConsumableArray(next);
         preset.colors = next;
         renderer.setPreset(_objectSpread2(_objectSpread2({}, preset), {}, {
           colors: next
         }));
+        if (isMotionPaused()) renderOnce();
         return this;
       },
       setSeed: function setSeed(seed) {
-        var value = Number(seed);
-        if (!Number.isFinite(value)) return this;
+        var value = toFiniteNumber(seed);
+        if (value === null) return this;
         dirty.seed = true;
+        seedOverride = value;
         preset.seed = value;
         renderer.setPreset(_objectSpread2({}, preset));
+        if (isMotionPaused()) renderOnce();
         return this;
       },
       setSpeed: function setSpeed(speed) {
-        var value = Number(speed);
-        if (!Number.isFinite(value)) return this;
+        var value = toFiniteNumber(speed);
+        if (value === null) return this;
         dirty.speed = true;
+        speedOverride = value;
         preset.speed = value;
         renderer.setPreset(_objectSpread2({}, preset));
+        if (isMotionPaused()) renderOnce();
         return this;
       },
       setText: function setText(content) {
@@ -1379,6 +1560,7 @@
         return this;
       },
       setMouseColor: function setMouseColor(value) {
+        dirty.mouseColor = true;
         merged.mouseColor = value !== false;
         if (typeof renderer.setMouseColor === 'function') renderer.setMouseColor(merged.mouseColor);
         return this;
@@ -1393,6 +1575,7 @@
           merged.height = height;
         }
         applySize();
+        if (isMotionPaused()) renderOnce();
         return this;
       },
       randomize: function randomize() {
@@ -1400,23 +1583,59 @@
         return this;
       },
       pause: function pause() {
-        paused = true;
+        dirty.paused = true;
+        manuallyPaused = true;
+        renderOnce();
         return this;
       },
       resume: function resume() {
-        paused = false;
+        dirty.paused = true;
+        manuallyPaused = false;
+        wakeScheduler();
+        return this;
+      },
+      setPaused: function setPaused(value) {
+        return value ? this.pause() : this.resume();
+      },
+      setStatic: function setStatic(value) {
+        dirty.static = true;
+        staticMode = value === true;
+        merged.static = staticMode;
+        if (staticMode) renderOnce();else wakeScheduler();
+        return this;
+      },
+      setFps: function setFps(fps) {
+        dirty.fps = true;
+        merged.fps = frameGate.setFps(fps);
+        wakeScheduler();
         return this;
       },
       setQuality: function setQuality(quality) {
+        dirty.quality = true;
         merged.quality = quality;
-        if (typeof renderer.setDprCap === 'function') renderer.setDprCap(dprCapFor(quality));
+        if (typeof renderer.setDprCap === 'function') {
+          renderer.setDprCap(effectiveDprCap(quality, merged.renderScale));
+        }
+        if (isMotionPaused()) renderOnce();
+        return this;
+      },
+      setRenderScale: function setRenderScale(renderScale) {
+        var value = Number(renderScale);
+        if (!Number.isFinite(value)) return this;
+        dirty.renderScale = true;
+        merged.renderScale = Math.min(1, Math.max(0.25, value));
+        if (typeof renderer.setDprCap === 'function') {
+          renderer.setDprCap(effectiveDprCap(merged.quality, merged.renderScale));
+        }
+        if (isMotionPaused()) renderOnce();
         return this;
       },
       dispose: function dispose() {
         disposed = true;
         unsubscribe();
         visibility.dispose();
-        if (resizeObserver) resizeObserver.disconnect();else window.removeEventListener('resize', renderer.resize);
+        motionPreference.dispose();
+        if (resizeObserver) resizeObserver.disconnect();else window.removeEventListener('resize', resize);
         renderer.dispose();
         root.remove();
       },
@@ -1426,6 +1645,24 @@
       get cssVars() {
         return merged.cssVars;
       },
+      get mouseColor() {
+        return merged.mouseColor;
+      },
+      get quality() {
+        return merged.quality;
+      },
+      get renderScale() {
+        return merged.renderScale;
+      },
+      get paused() {
+        return manuallyPaused;
+      },
+      get static() {
+        return staticMode;
+      },
+      get fps() {
+        return frameGate.getFps();
+      },
       dirty: dirty
     };
   }
@@ -1566,64 +1803,95 @@
   var ProgressFlowRenderer = /*#__PURE__*/function () {
     function ProgressFlowRenderer(canvas, preset) {
       var _PROFILE_INDEX$preset;
+      var options = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
       _classCallCheck(this, ProgressFlowRenderer);
       var gl = canvas.getContext('webgl2', {
         alpha: false,
         antialias: true,
         premultipliedAlpha: false,
-        powerPreference: 'high-performance'
+        powerPreference: options.powerPreference || 'high-performance'
       });
       if (!gl) throw new Error('WebGL2 unavailable');
       this.canvas = canvas;
+      this.options = options;
       this.gl = gl;
-      this.program = createProgram(gl);
       this.profile = preset.edgeStyle === 'tide' ? 3 : (_PROFILE_INDEX$preset = PROFILE_INDEX[preset.id]) !== null && _PROFILE_INDEX$preset !== void 0 ? _PROFILE_INDEX$preset : 2;
       this.seed = stringSeed$1("".concat(preset.id, "-shader")) * 13.7 + 1.0;
       this.colors = preset.colors.map(hexToRgb01);
       this.motionData = getProgressMotionData(preset.id, preset.edgeStyle);
       var motionFactor = preset.edgeStyle === 'tide' ? MOTION_SCALE_FACTORS.tide : MOTION_SCALE_FACTORS[preset.id] || 1.04;
       this.motionScale = PROGRESS_MOTION_MAX_PX * motionFactor / 1257;
-      this.position = gl.getAttribLocation(this.program, 'a_position');
-      this.uniforms = {
-        resolution: gl.getUniformLocation(this.program, 'u_resolution'),
-        time: gl.getUniformLocation(this.program, 'u_time'),
-        progress: gl.getUniformLocation(this.program, 'u_progress'),
-        seed: gl.getUniformLocation(this.program, 'u_seed'),
-        profile: gl.getUniformLocation(this.program, 'u_profile'),
-        motion: gl.getUniformLocation(this.program, 'u_motion'),
-        effect: gl.getUniformLocation(this.program, 'u_effect'),
-        hasEffect: gl.getUniformLocation(this.program, 'u_hasEffect'),
-        effectFrames: gl.getUniformLocation(this.program, 'u_effectFrames'),
-        motionDuration: gl.getUniformLocation(this.program, 'u_motionDuration'),
-        motionScale: gl.getUniformLocation(this.program, 'u_motionScale'),
-        dark: gl.getUniformLocation(this.program, 'u_dark'),
-        accentA: gl.getUniformLocation(this.program, 'u_accentA'),
-        accentB: gl.getUniformLocation(this.program, 'u_accentB'),
-        glow: gl.getUniformLocation(this.program, 'u_glow')
-      };
-      this.buffer = gl.createBuffer();
-      gl.bindBuffer(gl.ARRAY_BUFFER, this.buffer);
-      gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1, -1, 1, -1, -1, 1, -1, 1, 1, -1, 1, 1]), gl.STATIC_DRAW);
-      this.motionTexture = gl.createTexture();
-      gl.activeTexture(gl.TEXTURE0);
-      gl.bindTexture(gl.TEXTURE_2D, this.motionTexture);
-      gl.pixelStorei(gl.UNPACK_ALIGNMENT, 1);
-      gl.texImage2D(gl.TEXTURE_2D, 0, gl.R8, PROGRESS_MOTION_WIDTH, PROGRESS_MOTION_HEIGHT, 0, gl.RED, gl.UNSIGNED_BYTE, this.motionData);
-      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
-      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
-      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.REPEAT);
-      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
-      this.effectTexture = gl.createTexture();
-      gl.activeTexture(gl.TEXTURE1);
-      gl.bindTexture(gl.TEXTURE_2D, this.effectTexture);
-      gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGB, 1, 1, 0, gl.RGB, gl.UNSIGNED_BYTE, new Uint8Array([32, 33, 38]));
-      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
-      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
-      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
-      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
-      this.effectUploaded = false;
+      this.disposed = false;
+      this.contextLost = false;
+      this.setupResources();
+      this.bindContextEvents();
     }
     return _createClass(ProgressFlowRenderer, [{
+      key: "setupResources",
+      value: function setupResources() {
+        var gl = this.gl;
+        this.program = createProgram(gl);
+        this.position = gl.getAttribLocation(this.program, 'a_position');
+        this.uniforms = {
+          resolution: gl.getUniformLocation(this.program, 'u_resolution'),
+          time: gl.getUniformLocation(this.program, 'u_time'),
+          progress: gl.getUniformLocation(this.program, 'u_progress'),
+          seed: gl.getUniformLocation(this.program, 'u_seed'),
+          profile: gl.getUniformLocation(this.program, 'u_profile'),
+          motion: gl.getUniformLocation(this.program, 'u_motion'),
+          effect: gl.getUniformLocation(this.program, 'u_effect'),
+          hasEffect: gl.getUniformLocation(this.program, 'u_hasEffect'),
+          effectFrames: gl.getUniformLocation(this.program, 'u_effectFrames'),
+          motionDuration: gl.getUniformLocation(this.program, 'u_motionDuration'),
+          motionScale: gl.getUniformLocation(this.program, 'u_motionScale'),
+          dark: gl.getUniformLocation(this.program, 'u_dark'),
+          accentA: gl.getUniformLocation(this.program, 'u_accentA'),
+          accentB: gl.getUniformLocation(this.program, 'u_accentB'),
+          glow: gl.getUniformLocation(this.program, 'u_glow')
+        };
+        this.buffer = gl.createBuffer();
+        gl.bindBuffer(gl.ARRAY_BUFFER, this.buffer);
+        gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1, -1, 1, -1, -1, 1, -1, 1, 1, -1, 1, 1]), gl.STATIC_DRAW);
+        this.motionTexture = gl.createTexture();
+        gl.activeTexture(gl.TEXTURE0);
+        gl.bindTexture(gl.TEXTURE_2D, this.motionTexture);
+        gl.pixelStorei(gl.UNPACK_ALIGNMENT, 1);
+        gl.texImage2D(gl.TEXTURE_2D, 0, gl.R8, PROGRESS_MOTION_WIDTH, PROGRESS_MOTION_HEIGHT, 0, gl.RED, gl.UNSIGNED_BYTE, this.motionData);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.REPEAT);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+        this.effectTexture = gl.createTexture();
+        gl.activeTexture(gl.TEXTURE1);
+        gl.bindTexture(gl.TEXTURE_2D, this.effectTexture);
+        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGB, 1, 1, 0, gl.RGB, gl.UNSIGNED_BYTE, new Uint8Array([32, 33, 38]));
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+        this.effectUploaded = false;
+      }
+    }, {
+      key: "bindContextEvents",
+      value: function bindContextEvents() {
+        var _this = this;
+        this.onContextLost = function (event) {
+          event.preventDefault();
+          if (_this.disposed) return;
+          _this.contextLost = true;
+          if (typeof _this.options.onContextLost === 'function') _this.options.onContextLost(event);
+        };
+        this.onContextRestored = function () {
+          if (_this.disposed) return;
+          _this.setupResources();
+          _this.contextLost = false;
+          _this.gl.viewport(0, 0, _this.canvas.width, _this.canvas.height);
+          if (typeof _this.options.onContextRestored === 'function') _this.options.onContextRestored();
+        };
+        this.canvas.addEventListener('webglcontextlost', this.onContextLost, false);
+        this.canvas.addEventListener('webglcontextrestored', this.onContextRestored, false);
+      }
+    }, {
       key: "resize",
       value: function resize(width, height, dpr) {
         var pixelWidth = Math.max(1, Math.round(width * dpr));
@@ -1638,6 +1906,7 @@
       key: "draw",
       value: function draw(time, progress) {
         var effectImage = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : null;
+        if (this.disposed || this.contextLost) return;
         var gl = this.gl;
         gl.useProgram(this.program);
         gl.bindBuffer(gl.ARRAY_BUFFER, this.buffer);
@@ -1654,7 +1923,8 @@
         gl.uniform1f(this.uniforms.motionDuration, PROGRESS_MOTION_DURATION);
         gl.uniform1f(this.uniforms.motionScale, this.motionScale);
         var hasEffect = this.effectUploaded ? 1 : 0;
-        if (!this.effectUploaded && effectImage && effectImage.complete && effectImage.naturalWidth > 0) {
+        var effectWidth = effectImage && (effectImage.naturalWidth || effectImage.width || 0);
+        if (!this.effectUploaded && effectImage && effectWidth > 0) {
           gl.activeTexture(gl.TEXTURE1);
           gl.bindTexture(gl.TEXTURE_2D, this.effectTexture);
           gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
@@ -1686,7 +1956,10 @@
     }, {
       key: "dispose",
       value: function dispose() {
+        this.disposed = true;
         var gl = this.gl;
+        this.canvas.removeEventListener('webglcontextlost', this.onContextLost, false);
+        this.canvas.removeEventListener('webglcontextrestored', this.onContextRestored, false);
         gl.deleteBuffer(this.buffer);
         gl.deleteTexture(this.motionTexture);
         gl.deleteTexture(this.effectTexture);
@@ -1697,8 +1970,9 @@
     }]);
   }();
   function createProgressFlowRenderer(canvas, preset) {
+    var options = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
     try {
-      return new ProgressFlowRenderer(canvas, preset);
+      return new ProgressFlowRenderer(canvas, preset, options);
     } catch (error) {
       console.warn('[画境观屿] 进度流体 WebGL2 不可用，使用 Canvas 2D 降级。', error);
       return null;
@@ -1758,50 +2032,49 @@
       context.fillRect(20, 0, 44, FRAME_HEIGHT);
       context.restore();
     }
-    var image = new Image();
-    image.decoding = 'async';
-    var state = {
-      image: image,
-      ready: false
+
+    // A canvas is a valid TexImageSource. Keeping it directly avoids a PNG
+    // encode -> base64 allocation -> Image decode round trip at startup.
+    return {
+      image: canvas,
+      ready: true
     };
-    image.addEventListener('load', function () {
-      state.ready = true;
-    }, {
-      once: true
-    });
-    image.addEventListener('error', function () {
-      state.ready = false;
-    }, {
-      once: true
-    });
-    image.src = canvas.toDataURL('image/png');
-    return state;
   }
   function getProgressReferenceAtlas(id) {
     if (!CACHE[id]) CACHE[id] = createAtlas(id);
     return CACHE[id];
   }
 
-  /**
-   * Attach a WebGL2 fluid overlay to a progress capsule root.
-   *
-   * @param {object} params
-   * @param {HTMLElement} params.root    progress capsule root element
-   * @param {HTMLCanvasElement} params.canvas  2D fallback canvas (kept beneath)
-   * @param {object} params.preset      progress preset
-   * @param {() => number} params.getProgress  reads the current progress value
-   * @returns {{ update(flowTime: number): void, dispose(): void } | null}
+  /**
+   * Attach a WebGL2 fluid overlay to a progress capsule root.
+   *
+   * @param {object} params
+   * @param {HTMLElement} params.root    progress capsule root element
+   * @param {HTMLCanvasElement} params.canvas  2D fallback canvas (kept beneath)
+   * @param {object} params.preset      progress preset
+   * @param {() => number} params.getProgress  reads the current progress value
+   * @returns {{ update(flowTime: number): void, setDprCap(cap: number): void, dispose(): void } | null}
    */
   function attachProgressFlowOverlay(_ref) {
     var root = _ref.root,
       canvas = _ref.canvas,
       preset = _ref.preset,
-      getProgress = _ref.getProgress;
+      getProgress = _ref.getProgress,
+      _ref$dprCap = _ref.dprCap,
+      dprCap = _ref$dprCap === void 0 ? 2 : _ref$dprCap,
+      _ref$powerPreference = _ref.powerPreference,
+      powerPreference = _ref$powerPreference === void 0 ? 'high-performance' : _ref$powerPreference,
+      onContextLost = _ref.onContextLost,
+      onContextRestored = _ref.onContextRestored;
     var overlay = document.createElement('canvas');
     overlay.className = 'hj-progress-canvas hj-progress-overlay';
     overlay.setAttribute('aria-hidden', 'true');
     canvas.insertAdjacentElement('afterend', overlay);
-    var renderer = createProgressFlowRenderer(overlay, preset);
+    var renderer = createProgressFlowRenderer(overlay, preset, {
+      powerPreference: powerPreference,
+      onContextLost: onContextLost,
+      onContextRestored: onContextRestored
+    });
     if (!renderer) {
       overlay.remove();
       return null;
@@ -1812,7 +2085,7 @@
       var bounds = root.getBoundingClientRect();
       var width = Math.max(1, bounds.width);
       var height = Math.max(1, bounds.height);
-      var dpr = Math.min(window.devicePixelRatio || 1, 2);
+      var dpr = Math.min(window.devicePixelRatio || 1, dprCap);
       overlay.style.width = "".concat(width, "px");
       overlay.style.height = "".concat(height, "px");
       renderer.resize(width, height, dpr);
@@ -1836,6 +2109,10 @@
       setColors: function setColors(colors) {
         renderer.setColors(colors);
       },
+      setDprCap: function setDprCap(cap) {
+        dprCap = cap;
+        resize();
+      },
       dispose: function dispose() {
         if (resizeObserver) resizeObserver.disconnect();
         if (onWindowResize) window.removeEventListener('resize', onWindowResize);
@@ -1846,6 +2123,47 @@
     };
   }
 
+  function normalizeRange(min, max) {
+    var fallbackMin = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : 0;
+    var fallbackMax = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : 100;
+    var nextMin = toFiniteNumber(min);
+    var nextMax = toFiniteNumber(max);
+    if (nextMin === null) nextMin = fallbackMin;
+    if (nextMax === null) nextMax = fallbackMax;
+    if (nextMin > nextMax) {
+      var swap = nextMin;
+      nextMin = nextMax;
+      nextMax = swap;
+    }
+    return [nextMin, nextMax];
+  }
+  function clampProgressValue(value, min, max) {
+    var number = toFiniteNumber(value);
+    if (number === null) return null;
+    return Math.min(Math.max(number, min), max);
+  }
+  function normalizeProgressStep(step) {
+    var fallback = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 'any';
+    if (step === 'any' || step == null) return 'any';
+    var increment = toFiniteNumber(step);
+    return increment !== null && increment > 0 ? increment : fallback;
+  }
+  function snapProgressValue(value, min, max) {
+    var step = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : 'any';
+    var clamped = clampProgressValue(value, min, max);
+    if (clamped === null) return null;
+    if (step === 'any' || step == null) return clamped;
+    var increment = normalizeProgressStep(step);
+    if (increment === 'any') return clamped;
+    var snapped = min + Math.round((clamped - min) / increment) * increment;
+    return Math.min(Math.max(Number(snapped.toFixed(12)), min), max);
+  }
+  function progressRatio(value, min, max) {
+    var range = max - min;
+    if (!Number.isFinite(range) || range <= 0) return 0;
+    return Math.min(Math.max((value - min) / range, 0), 1);
+  }
+
   var clamp = function clamp(value, min, max) {
     return Math.min(Math.max(value, min), max);
   };
@@ -1872,9 +2190,6 @@
       return values[key] !== undefined ? values[key] : '';
     });
   }
-  function prefersReducedMotion$1() {
-    return typeof matchMedia !== 'undefined' && matchMedia('(prefers-reduced-motion: reduce)').matches;
-  }
   var FLOW_PROFILES = {
     'model-training': {
       cycles: [0.98, 3.05, 5.45],
@@ -1935,8 +2250,6 @@
   var ProgressCapsuleController = /*#__PURE__*/function () {
     function ProgressCapsuleController(_ref) {
       var _options$valueSuffix,
-        _options$min,
-        _options$max,
         _options$value,
         _this = this;
       var root = _ref.root,
@@ -1958,11 +2271,18 @@
       this.dirty = dirty;
       this.valueSuffix = (_options$valueSuffix = options.valueSuffix) !== null && _options$valueSuffix !== void 0 ? _options$valueSuffix : copy.valueSuffix;
       this.profile = preset.edgeStyle === 'tide' ? FLOW_PROFILES.tide : FLOW_PROFILES[preset.id] || FLOW_PROFILES['visual-training'];
-      this.min = (_options$min = options.min) !== null && _options$min !== void 0 ? _options$min : 0;
-      this.max = (_options$max = options.max) !== null && _options$max !== void 0 ? _options$max : 100;
-      this.dprCap = dprCapFor(options.quality);
+      var _normalizeRange = normalizeRange(options.min, options.max);
+      var _normalizeRange2 = _slicedToArray(_normalizeRange, 2);
+      this.min = _normalizeRange2[0];
+      this.max = _normalizeRange2[1];
+      this.step = normalizeProgressStep(options.step);
+      this.precision = Number.isInteger(Number(options.precision)) ? clamp(Number(options.precision), 0, 20) : 0;
+      this.formatValue = typeof options.formatValue === 'function' ? options.formatValue : null;
+      this.direction = options.direction === 'rtl' ? 'rtl' : 'ltr';
+      this.dprCap = effectiveDprCap(options.quality, options.renderScale);
       this.ctx = canvas.getContext('2d');
-      this.value = clamp((_options$value = options.value) !== null && _options$value !== void 0 ? _options$value : preset.initialProgress, this.min, this.max);
+      this.value = snapProgressValue((_options$value = options.value) !== null && _options$value !== void 0 ? _options$value : preset.initialProgress, this.min, this.max, this.step);
+      if (this.value === null) this.value = clamp(preset.initialProgress, this.min, this.max);
       this.dragging = false;
       this.webglActive = false;
       this.flowTime = stringSeed(preset.id) * 31;
@@ -1972,10 +2292,12 @@
       this.width = 0;
       this.height = 0;
       this.handlers = {};
-      this.resizeObserver = typeof ResizeObserver !== 'undefined' ? new ResizeObserver(function () {
-        return _this.resizeCanvas();
-      }) : null;
-      if (this.resizeObserver) this.resizeObserver.observe(this.root);else window.addEventListener('resize', this.resizeCanvas);
+      this.onResize = function () {
+        _this.resizeCanvas();
+        if (typeof _this.options.onResize === 'function') _this.options.onResize();
+      };
+      this.resizeObserver = typeof ResizeObserver !== 'undefined' ? new ResizeObserver(this.onResize) : null;
+      if (this.resizeObserver) this.resizeObserver.observe(this.root);else window.addEventListener('resize', this.onResize);
       this.suppressEvents = true;
       this.setProgress(this.value, 'init');
       this.suppressEvents = false;
@@ -1988,16 +2310,37 @@
         this.randomState = Math.imul(this.randomState, 1664525) + 1013904223 >>> 0;
         return this.randomState / 4294967296;
       }
+    }, {
+      key: "displayText",
+      value: function displayText() {
+        if (this.formatValue) {
+          return String(this.formatValue(this.value, {
+            min: this.min,
+            max: this.max,
+            suffix: this.valueSuffix
+          }));
+        }
+        var number = this.precision > 0 ? this.value.toFixed(this.precision) : String(Math.round(this.value));
+        return "".concat(number).concat(this.valueSuffix);
+      }
+    }, {
+      key: "syncValueDom",
+      value: function syncValueDom() {
+        var text = this.displayText();
+        this.root.style.setProperty('--progress', this.value.toFixed(2));
+        this.root.style.setProperty('--progress-ratio', progressRatio(this.value, this.min, this.max).toFixed(4));
+        this.root.setAttribute('aria-valuenow', String(this.value));
+        this.root.setAttribute('aria-valuetext', text);
+        if (this.valueElement) this.valueElement.textContent = text;
+      }
     }, {
       key: "setProgress",
       value: function setProgress(nextValue) {
         var source = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 'auto';
-        this.value = clamp(nextValue, this.min, this.max);
-        var rounded = Math.round(this.value);
-        this.root.style.setProperty('--progress', this.value.toFixed(2));
-        this.root.setAttribute('aria-valuenow', String(rounded));
-        this.root.setAttribute('aria-valuetext', "".concat(rounded).concat(this.valueSuffix));
-        if (this.valueElement) this.valueElement.textContent = "".concat(rounded).concat(this.valueSuffix);
+        var next = snapProgressValue(nextValue, this.min, this.max, this.step);
+        if (next === null) return false;
+        this.value = next;
+        this.syncValueDom();
         if (!this.suppressEvents) {
           if (this.dirty) this.dirty.value = true;
           this.emitter.emit('change', {
@@ -2005,19 +2348,58 @@
             source: source
           });
         }
+        return true;
       }
     }, {
       key: "setValueSuffix",
       value: function setValueSuffix(suffix) {
+        if (this.dirty) this.dirty.valueSuffix = true;
         this.valueSuffix = String(suffix == null ? '' : suffix);
-        var rounded = Math.round(this.value);
-        if (this.valueElement) this.valueElement.textContent = "".concat(rounded).concat(this.valueSuffix);
-        this.root.setAttribute('aria-valuetext', "".concat(rounded).concat(this.valueSuffix));
+        this.syncValueDom();
+        return this;
+      }
+    }, {
+      key: "setStep",
+      value: function setStep(step) {
+        var nextStep = normalizeProgressStep(step, this.step);
+        if (nextStep === this.step) return this;
+        if (this.dirty) this.dirty.step = true;
+        this.step = nextStep;
+        var next = snapProgressValue(this.value, this.min, this.max, this.step);
+        if (next !== null && next !== this.value) this.setProgress(next, 'prop');
+        return this;
+      }
+    }, {
+      key: "setPrecision",
+      value: function setPrecision(precision) {
+        var value = Number(precision);
+        if (!Number.isInteger(value) || value < 0 || value > 20) return this;
+        if (this.dirty) this.dirty.precision = true;
+        this.precision = value;
+        this.syncValueDom();
+        return this;
+      }
+    }, {
+      key: "setFormatValue",
+      value: function setFormatValue(formatter) {
+        if (formatter != null && typeof formatter !== 'function') return this;
+        if (this.dirty) this.dirty.formatValue = true;
+        this.formatValue = formatter || null;
+        this.syncValueDom();
+        return this;
+      }
+    }, {
+      key: "setDirection",
+      value: function setDirection(direction) {
+        if (this.dirty) this.dirty.direction = true;
+        this.direction = direction === 'rtl' ? 'rtl' : 'ltr';
+        this.root.dataset.direction = this.direction;
         return this;
       }
     }, {
       key: "setShowValue",
       value: function setShowValue(show) {
+        if (this.dirty) this.dirty.showValue = true;
         if (this.valueElement) this.valueElement.hidden = show === false;
         return this;
       }
@@ -2182,15 +2564,14 @@
     }, {
       key: "setRange",
       value: function setRange(min, max) {
-        if (min > max) {
-          var swap = min;
-          min = max;
-          max = swap;
-        }
-        this.min = min;
-        this.max = max;
-        var clamped = clamp(this.value, this.min, this.max);
-        if (clamped !== this.value) this.setProgress(clamped, 'prop');
+        var nextRange = normalizeRange(min, max, this.min, this.max);
+        this.min = nextRange[0];
+        this.max = nextRange[1];
+        this.root.setAttribute('aria-valuemin', String(this.min));
+        this.root.setAttribute('aria-valuemax', String(this.max));
+        var next = snapProgressValue(this.value, this.min, this.max, this.step);
+        if (next !== this.value) this.setProgress(next, 'prop');else this.syncValueDom();
+        return this;
       }
     }, {
       key: "drawReferenceFlow",
@@ -2315,8 +2696,39 @@
       value: function updateFromPointer(event) {
         var bounds = this.root.getBoundingClientRect();
         var ratio = bounds.width > 0 ? (event.clientX - bounds.left) / bounds.width : 0;
+        if (this.direction === 'rtl') ratio = 1 - ratio;
         this.setProgress(this.min + ratio * (this.max - this.min), 'drag');
       }
+    }, {
+      key: "onKeyDown",
+      value: function onKeyDown(event) {
+        var range = this.max - this.min;
+        var configuredStep = Number(this.step);
+        var step = Number.isFinite(configuredStep) && configuredStep > 0 ? configuredStep : Math.max(range / 100, 1e-7);
+        var direction = this.direction === 'rtl' ? -1 : 1;
+        var aliases = {
+          Left: 'ArrowLeft',
+          Right: 'ArrowRight',
+          Up: 'ArrowUp',
+          Down: 'ArrowDown'
+        };
+        var keyCodes = {
+          35: 'End',
+          36: 'Home',
+          33: 'PageUp',
+          34: 'PageDown',
+          37: 'ArrowLeft',
+          38: 'ArrowUp',
+          39: 'ArrowRight',
+          40: 'ArrowDown'
+        };
+        var key = aliases[event.key] || event.key || keyCodes[event.keyCode];
+        var next = null;
+        if (key === 'ArrowRight') next = this.value + step * direction;else if (key === 'ArrowLeft') next = this.value - step * direction;else if (key === 'ArrowUp') next = this.value + step;else if (key === 'ArrowDown') next = this.value - step;else if (key === 'PageUp') next = this.value + step * 10;else if (key === 'PageDown') next = this.value - step * 10;else if (key === 'Home') next = this.min;else if (key === 'End') next = this.max;
+        if (next === null) return;
+        event.preventDefault();
+        this.setProgress(next, 'keyboard');
+      }
     }, {
       key: "beginDrag",
       value: function beginDrag(event) {
@@ -2404,6 +2816,12 @@
           this.root.addEventListener('pointerup', this.handlers.pointerup);
           this.root.addEventListener('pointercancel', this.handlers.pointercancel);
         }
+        if (this.options.keyboard !== false) {
+          this.handlers.keydown = function (event) {
+            return _this3.onKeyDown(event);
+          };
+          this.root.addEventListener('keydown', this.handlers.keydown);
+        }
       }
     }, {
       key: "update",
@@ -2422,20 +2840,19 @@
       key: "randomize",
       value: function randomize() {
         this.flowTime = this.random() * 40;
+        return this.flowTime;
       }
     }, {
       key: "setColors",
       value: function setColors(colors) {
         if (!Array.isArray(colors) || colors.length !== 4) return;
-        this.preset = _objectSpread2(_objectSpread2({}, this.preset), {}, {
-          colors: colors
-        });
+        this.preset.colors = _toConsumableArray(colors);
       }
     }, {
       key: "dispose",
       value: function dispose() {
         if (this._dragRaf) cancelAnimationFrame(this._dragRaf);
-        if (this.resizeObserver) this.resizeObserver.disconnect();else window.removeEventListener('resize', this.resizeCanvas);
+        if (this.resizeObserver) this.resizeObserver.disconnect();else window.removeEventListener('resize', this.onResize);
         for (var _i = 0, _Object$keys = Object.keys(this.handlers); _i < _Object$keys.length; _i++) {
           var name = _Object$keys[_i];
           var handler = this.handlers[name];
@@ -2446,15 +2863,16 @@
     }]);
   }();
 
-  /**
+  /**
    * Mount a fluid progress capsule into `container`.
    *
-   * Options: preset (literary name), width, height, value, min, max,
-   * draggable, colors, edgeStyle, textRatio (0-100, text region
+   * Options: preset (literary name), width, height, value/modelValue, min, max,
+   * step, draggable, keyboard, direction, precision/formatValue, colors,
+   * edgeStyle, textRatio (0-100, text region
    * width in percent), text (HTML string or DOM nodes for the text slot),
    * colorContent (HTML string or DOM nodes for the color slot),
-   * showValue (show/hide the right-side percentage), quality,
-   * respectReducedMotion, cssVars.
+   * showValue (show/hide the right-side percentage), quality, renderScale,
+   * powerPreference, fps, paused/static, respectReducedMotion, cssVars.
    */
   function createProgressCapsule(container) {
     var _options$preset, _merged$min, _merged$max;
@@ -2464,14 +2882,20 @@
     }
     var preset = _objectSpread2({}, getPreset('progress', (_options$preset = options.preset) !== null && _options$preset !== void 0 ? _options$preset : '星火'));
     var merged = normalizeOptions(DEFAULTS.progress, preset, options);
-    if (merged.min > merged.max) {
-      var swap = merged.min;
-      merged.min = merged.max;
-      merged.max = swap;
-    }
-    var normalizedColors = merged.colors.map(normalizeColor);
-    if (normalizedColors.every(Boolean)) preset.colors = normalizedColors;
-    preset.edgeStyle = merged.edgeStyle;
+    var _normalizeRange3 = normalizeRange(merged.min, merged.max);
+    var _normalizeRange4 = _slicedToArray(_normalizeRange3, 2);
+    merged.min = _normalizeRange4[0];
+    merged.max = _normalizeRange4[1];
+    if (merged.modelValue !== undefined) merged.value = merged.modelValue;
+    var normalizedColors = Array.isArray(merged.colors) ? merged.colors.map(normalizeColor) : [];
+    if (normalizedColors.length === 4 && normalizedColors.every(Boolean)) preset.colors = normalizedColors;
+    var initialEdgeStyle = merged.edgeStyle === 'tide' || merged.edgeStyle === 'flow' ? merged.edgeStyle : preset.edgeStyle;
+    preset.edgeStyle = initialEdgeStyle;
+    merged.edgeStyle = initialEdgeStyle;
+    merged.colors = _toConsumableArray(preset.colors);
+    var optionColors = Array.isArray(options.colors) ? options.colors.map(normalizeColor) : [];
+    var colorOverride = optionColors.length === 4 && optionColors.every(Boolean) ? _toConsumableArray(optionColors) : null;
+    var edgeStyleOverride = options.edgeStyle === 'flow' || options.edgeStyle === 'tide' ? merged.edgeStyle : null;
     var copy = COPY;
     var customLabel = typeof options.label === 'string' && options.label ? options.label : null;
     // Vue 的裸布尔属性（<ProgressCapsule disabled />）会传成空字符串，
@@ -2480,18 +2904,31 @@
     var readonly = merged.readonly === true || merged.readonly === '' || merged.readonly === 'true';
     var locked = disabled || readonly;
     var effectiveDraggable = locked ? false : merged.draggable !== false;
+    var effectiveKeyboard = locked ? false : merged.keyboard !== false;
     var dirty = {
       preset: false,
       colors: false,
       textRatio: false,
       cssVars: false,
       edgeStyle: false,
-      value: false
+      value: false,
+      step: false,
+      precision: false,
+      formatValue: false,
+      direction: false,
+      showValue: false,
+      valueSuffix: false,
+      quality: false,
+      renderScale: false,
+      paused: false,
+      static: false,
+      fps: false
     };
     var root = document.createElement('div');
     root.className = 'hj-capsule-root hj-progress-root';
     root.setAttribute('role', 'slider');
     root.setAttribute('data-draggable', String(effectiveDraggable));
+    root.dataset.direction = merged.direction === 'rtl' ? 'rtl' : 'ltr';
     if (disabled) {
       root.setAttribute('aria-disabled', 'true');
       root.classList.add('is-disabled');
@@ -2500,7 +2937,8 @@
       root.setAttribute('aria-readonly', 'true');
       root.classList.add('is-readonly');
     }
-    if (locked) root.setAttribute('tabindex', '-1');
+    root.setAttribute('tabindex', locked ? '-1' : effectiveKeyboard ? '0' : '-1');
+    root.setAttribute('aria-orientation', 'horizontal');
     root.setAttribute('aria-valuemin', String((_merged$min = merged.min) !== null && _merged$min !== void 0 ? _merged$min : 0));
     root.setAttribute('aria-valuemax', String((_merged$max = merged.max) !== null && _merged$max !== void 0 ? _merged$max : 100));
     root.setAttribute('aria-valuenow', String(preset.initialProgress));
@@ -2555,8 +2993,22 @@
     root.appendChild(valueElement);
     container.appendChild(root);
     var emitter = createEmitter();
-    var paused = merged.respectReducedMotion && prefersReducedMotion$1();
+    var manuallyPaused = merged.paused === true;
+    var reducedPaused = false;
+    var staticMode = merged.static === true;
+    var contextLost = false;
     var disposed = false;
+    var renderOnce = function renderOnce() {};
+    var onContextLost = function onContextLost() {
+      contextLost = true;
+      emitter.emit('contextlost', {});
+    };
+    var onContextRestored = function onContextRestored() {
+      contextLost = false;
+      emitter.emit('contextrestored', {});
+      renderOnce();
+      wakeScheduler();
+    };
     var applySize = function applySize() {
       root.style.width = parseSize(merged.width);
       root.style.height = parseSize(merged.height);
@@ -2577,7 +3029,11 @@
       preset: preset,
       emitter: emitter,
       options: _objectSpread2(_objectSpread2({}, merged), {}, {
-        draggable: effectiveDraggable
+        draggable: effectiveDraggable,
+        keyboard: effectiveKeyboard,
+        onResize: function onResize() {
+          if (manuallyPaused || reducedPaused || staticMode) renderOnce();
+        }
       }),
       copy: copy,
       dirty: dirty
@@ -2589,8 +3045,12 @@
         canvas: canvas,
         preset: preset,
         getProgress: function getProgress() {
-          return controller.value;
-        }
+          return progressRatio(controller.value, controller.min, controller.max) * 100;
+        },
+        dprCap: effectiveDprCap(merged.quality, merged.renderScale),
+        powerPreference: merged.powerPreference,
+        onContextLost: onContextLost,
+        onContextRestored: onContextRestored
       });
     }
     if (overlay) controller.webglActive = true;else if (merged.renderer !== 'canvas2d') {
@@ -2601,17 +3061,34 @@
         });
       });
     }
-    var visibility = createVisibilityGuard(root);
+    var visibility = createVisibilityGuard(root, wakeScheduler);
+    var motionPreference = createReducedMotionPreference(merged.respectReducedMotion, function (matches) {
+      reducedPaused = matches;
+      if (matches) renderOnce();else wakeScheduler();
+    });
+    reducedPaused = motionPreference.matches();
+    var isMotionPaused = function isMotionPaused() {
+      return manuallyPaused || reducedPaused || staticMode || contextLost;
+    };
     var flowTime = 0;
+    var frameGate = createFrameGate(merged.fps);
+    renderOnce = function renderOnce() {
+      controller.draw();
+      if (overlay) overlay.update(flowTime);
+    };
+    renderOnce();
+    var offPausedChange = emitter.on('change', function () {
+      if (isMotionPaused()) renderOnce();
+    });
     var unsubscribe = subscribeScheduler(function (delta, now) {
       flowTime += delta;
       controller.update(delta, false);
-      if (visibility.isVisible()) {
+      if (frameGate.shouldDraw(delta)) {
         controller.draw();
         if (overlay) overlay.update(flowTime);
       }
     }, function () {
-      return paused;
+      return isMotionPaused() || !visibility.isVisible();
     });
     nextTick(function () {
       if (disposed) return;
@@ -2638,32 +3115,41 @@
       },
       setRange: function setRange(min, max) {
         controller.setRange(min, max);
+        if (isMotionPaused()) renderOnce();
         return this;
       },
       setPreset: function setPreset(ref) {
         var next = getPreset('progress', ref);
         dirty.preset = true;
         Object.assign(preset, next);
+        if (colorOverride) preset.colors = _toConsumableArray(colorOverride);
+        if (edgeStyleOverride) preset.edgeStyle = edgeStyleOverride;
         var nextColors = preset.colors.map(normalizeColor);
         if (nextColors.every(Boolean)) preset.colors = nextColors;
         controller.preset = preset;
-        controller.profile = next.edgeStyle === 'tide' ? FLOW_PROFILES.tide : FLOW_PROFILES[next.id] || FLOW_PROFILES['visual-training'];
+        controller.profile = preset.edgeStyle === 'tide' ? FLOW_PROFILES.tide : FLOW_PROFILES[preset.id] || FLOW_PROFILES['visual-training'];
         controller.flowTime = stringSeed(next.id) * 31;
         controller.seed = stringSeed("".concat(next.id, "-reference")) * Math.PI * 2;
         syncDom();
         if (overlay) {
           overlay.dispose();
+          contextLost = false;
           overlay = attachProgressFlowOverlay({
             root: root,
             canvas: canvas,
             preset: preset,
             getProgress: function getProgress() {
-              return controller.value;
-            }
+              return progressRatio(controller.value, controller.min, controller.max) * 100;
+            },
+            dprCap: effectiveDprCap(merged.quality, merged.renderScale),
+            powerPreference: merged.powerPreference,
+            onContextLost: onContextLost,
+            onContextRestored: onContextRestored
           });
         }
         controller.webglActive = Boolean(overlay);
         controller.resizeCanvas();
+        if (isMotionPaused()) renderOnce();
         emitter.emit('presetchange', {
           preset: _objectSpread2({}, preset)
         });
@@ -2673,21 +3159,28 @@
         var value = String(edgeStyle || '').toLowerCase();
         if (value !== 'flow' && value !== 'tide') return this;
         dirty.edgeStyle = true;
+        edgeStyleOverride = value;
         preset.edgeStyle = value;
         controller.profile = value === 'tide' ? FLOW_PROFILES.tide : FLOW_PROFILES[preset.id] || FLOW_PROFILES['visual-training'];
         if (overlay) {
           overlay.dispose();
+          contextLost = false;
           overlay = attachProgressFlowOverlay({
             root: root,
             canvas: canvas,
             preset: preset,
             getProgress: function getProgress() {
-              return controller.value;
-            }
+              return progressRatio(controller.value, controller.min, controller.max) * 100;
+            },
+            dprCap: effectiveDprCap(merged.quality, merged.renderScale),
+            powerPreference: merged.powerPreference,
+            onContextLost: onContextLost,
+            onContextRestored: onContextRestored
           });
         }
         controller.webglActive = Boolean(overlay);
         controller.resizeCanvas();
+        if (isMotionPaused()) renderOnce();
         return this;
       },
       setText: function setText(content) {
@@ -2725,6 +3218,22 @@
         controller.setValueSuffix(suffix);
         return this;
       },
+      setStep: function setStep(step) {
+        controller.setStep(step);
+        return this;
+      },
+      setPrecision: function setPrecision(precision) {
+        controller.setPrecision(precision);
+        return this;
+      },
+      setFormatValue: function setFormatValue(formatter) {
+        controller.setFormatValue(formatter);
+        return this;
+      },
+      setDirection: function setDirection(direction) {
+        controller.setDirection(direction);
+        return this;
+      },
       setShowValue: function setShowValue(show) {
         controller.setShowValue(show);
         return this;
@@ -2735,9 +3244,12 @@
           return !color;
         })) return this;
         dirty.colors = true;
+        colorOverride = _toConsumableArray(next);
+        preset.colors = _toConsumableArray(next);
         controller.setColors(next);
         if (overlay) overlay.setColors(next);
         controller.resizeCanvas();
+        if (isMotionPaused()) renderOnce();
         return this;
       },
       setSize: function setSize(width, height) {
@@ -2751,30 +3263,68 @@
         }
         applySize();
         controller.resizeCanvas();
+        if (isMotionPaused()) renderOnce();
         return this;
       },
       randomize: function randomize() {
-        controller.randomize();
+        flowTime = controller.randomize();
+        if (isMotionPaused()) renderOnce();
         return this;
       },
       pause: function pause() {
-        paused = true;
+        dirty.paused = true;
+        manuallyPaused = true;
+        renderOnce();
         return this;
       },
       resume: function resume() {
-        paused = false;
+        dirty.paused = true;
+        manuallyPaused = false;
+        wakeScheduler();
+        return this;
+      },
+      setPaused: function setPaused(value) {
+        return value ? this.pause() : this.resume();
+      },
+      setStatic: function setStatic(value) {
+        dirty.static = true;
+        staticMode = value === true;
+        merged.static = staticMode;
+        if (staticMode) renderOnce();else wakeScheduler();
+        return this;
+      },
+      setFps: function setFps(fps) {
+        dirty.fps = true;
+        merged.fps = frameGate.setFps(fps);
+        wakeScheduler();
         return this;
       },
       setQuality: function setQuality(quality) {
+        dirty.quality = true;
         merged.quality = quality;
-        controller.dprCap = dprCapFor(quality);
+        controller.dprCap = effectiveDprCap(quality, merged.renderScale);
+        controller.resizeCanvas();
+        if (overlay) overlay.setDprCap(controller.dprCap);
+        if (isMotionPaused()) renderOnce();
+        return this;
+      },
+      setRenderScale: function setRenderScale(renderScale) {
+        var value = Number(renderScale);
+        if (!Number.isFinite(value)) return this;
+        dirty.renderScale = true;
+        merged.renderScale = Math.min(1, Math.max(0.25, value));
+        controller.dprCap = effectiveDprCap(merged.quality, merged.renderScale);
         controller.resizeCanvas();
+        if (overlay) overlay.setDprCap(controller.dprCap);
+        if (isMotionPaused()) renderOnce();
         return this;
       },
       dispose: function dispose() {
         disposed = true;
         unsubscribe();
+        offPausedChange();
         visibility.dispose();
+        motionPreference.dispose();
         if (overlay) overlay.dispose();
         controller.dispose();
         root.remove();
@@ -2785,26 +3335,89 @@
       get cssVars() {
         return merged.cssVars;
       },
+      get min() {
+        return controller.min;
+      },
+      get max() {
+        return controller.max;
+      },
+      get step() {
+        return controller.step;
+      },
+      get precision() {
+        return controller.precision;
+      },
+      get formatValue() {
+        return controller.formatValue;
+      },
+      get direction() {
+        return controller.direction;
+      },
+      get showValue() {
+        return !valueElement.hidden;
+      },
+      get valueSuffix() {
+        return controller.valueSuffix;
+      },
+      get quality() {
+        return merged.quality;
+      },
+      get renderScale() {
+        return merged.renderScale;
+      },
+      get paused() {
+        return manuallyPaused;
+      },
+      get static() {
+        return staticMode;
+      },
+      get fps() {
+        return frameGate.getFps();
+      },
       dirty: dirty
     };
   }
 
-  function prefersReducedMotion() {
-    return typeof matchMedia !== 'undefined' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+  var HOST_STYLES = new WeakMap();
+  function acquireHostStyles(host) {
+    var active = HOST_STYLES.get(host);
+    if (active) {
+      active.count += 1;
+      return;
+    }
+    var state = {
+      count: 1,
+      position: host.style.position,
+      isolation: host.style.isolation
+    };
+    var computed = getComputedStyle(host);
+    if (computed.position === 'static' || computed.position === '') host.style.position = 'relative';
+    host.style.isolation = 'isolate';
+    HOST_STYLES.set(host, state);
+  }
+  function releaseHostStyles(host) {
+    var state = HOST_STYLES.get(host);
+    if (!state) return;
+    state.count -= 1;
+    if (state.count > 0) return;
+    host.style.position = state.position;
+    host.style.isolation = state.isolation;
+    HOST_STYLES.delete(host);
   }
 
-  /**
-   * Mount the cosmic (nebula) material as a background layer inside `host`.
-   *
-   * The layer is absolutely positioned and defaults to `z-index: -1`, so it
-   * paints behind the host's in-flow content: text/buttons/images inside the
-   * host sit on top with zero extra CSS. Host gets `position: relative;
-   * isolation: isolate` automatically so the layer can never escape its box
-   * (or break stacking outside it).
-   *
+  /**
+   * Mount the cosmic (nebula) material as a background layer inside `host`.
+   *
+   * The layer is absolutely positioned and defaults to `z-index: -1`, so it
+   * paints behind the host's in-flow content: text/buttons/images inside the
+   * host sit on top with zero extra CSS. Host gets `position: relative;
+   * isolation: isolate` automatically so the layer can never escape its box
+   * (or break stacking outside it).
+   *
    * Options: preset (literary name), colors, seed, speed, quality,
-   * renderer, mouseColor, respectReducedMotion, opacity (0-1), fallbackColor
-   * (true=preset base color, a hex string, or false to disable).
+   * renderer, renderScale, powerPreference, fps, paused/static, mouseColor,
+   * respectReducedMotion, opacity (0-1), fallbackColor (true=preset base
+   * color, a hex string, or false to disable).
    */
   function createColorBackground(host) {
     var _options$preset;
@@ -2818,18 +3431,29 @@
       renderer: DEFAULTS.capsule.renderer,
       respectReducedMotion: DEFAULTS.capsule.respectReducedMotion,
       mouseColor: true,
+      renderScale: 1,
+      powerPreference: 'high-performance',
+      fps: DEFAULTS.capsule.fps,
+      paused: false,
+      static: false,
       opacity: 1,
       fallbackColor: true
     }, preset, options);
-    var normalizedColors = merged.colors.map(normalizeColor);
-    if (normalizedColors.every(Boolean)) preset.colors = normalizedColors;
-    preset.seed = merged.seed;
-    preset.speed = merged.speed;
-    var computed = getComputedStyle(host);
-    if (computed.position === 'static' || computed.position === '') {
-      host.style.position = 'relative';
-    }
-    host.style.isolation = 'isolate';
+    merged.opacity = Number.isFinite(Number(merged.opacity)) ? Math.min(1, Math.max(0, Number(merged.opacity))) : 1;
+    var normalizedColors = Array.isArray(merged.colors) ? merged.colors.map(normalizeColor) : [];
+    if (normalizedColors.length === 4 && normalizedColors.every(Boolean)) preset.colors = normalizedColors;
+    var initialSeed = toFiniteNumber(merged.seed);
+    var initialSpeed = toFiniteNumber(merged.speed);
+    if (initialSeed !== null) preset.seed = initialSeed;
+    if (initialSpeed !== null) preset.speed = initialSpeed;
+    merged.colors = _toConsumableArray(preset.colors);
+    merged.seed = preset.seed;
+    merged.speed = preset.speed;
+    var optionColors = Array.isArray(options.colors) ? options.colors.map(normalizeColor) : [];
+    var colorOverride = optionColors.length === 4 && optionColors.every(Boolean) ? _toConsumableArray(optionColors) : null;
+    var seedOverride = options.seed !== undefined ? toFiniteNumber(options.seed) : null;
+    var speedOverride = options.speed !== undefined ? toFiniteNumber(options.speed) : null;
+    acquireHostStyles(host);
     var layer = document.createElement('div');
     layer.className = 'dlc-color-layer';
     var syncLayerVars = function syncLayerVars() {
@@ -2844,8 +3468,12 @@
     layer.appendChild(canvas);
     host.appendChild(layer);
     var emitter = createEmitter();
-    var paused = merged.respectReducedMotion && prefersReducedMotion();
+    var manuallyPaused = merged.paused === true;
+    var reducedPaused = false;
+    var staticMode = merged.static === true;
+    var contextLost = false;
     var disposed = false;
+    var renderOnce = function renderOnce() {};
     var dirty = {
       preset: false,
       seed: false,
@@ -2853,19 +3481,37 @@
       colors: false,
       opacity: false,
       fallbackColor: false,
-      mouseColor: false
+      mouseColor: false,
+      quality: false,
+      renderScale: false,
+      paused: false,
+      static: false,
+      fps: false
     };
     var renderer;
     var useWebgl = merged.renderer !== 'canvas2d';
     if (useWebgl) {
       try {
         renderer = new CosmicRenderer(canvas, merged, {
-          dprCap: dprCapFor(merged.quality),
+          dprCap: effectiveDprCap(merged.quality, merged.renderScale),
           mouseColor: merged.mouseColor !== false,
-          eventTarget: host
+          eventTarget: host,
+          powerPreference: merged.powerPreference,
+          onContextLost: function onContextLost() {
+            contextLost = true;
+            emitter.emit('contextlost', {});
+          },
+          onContextRestored: function onContextRestored() {
+            contextLost = false;
+            emitter.emit('contextrestored', {});
+            renderOnce();
+            wakeScheduler();
+          }
         });
       } catch (error) {
-        renderer = new FallbackRenderer(canvas, merged);
+        renderer = new FallbackRenderer(canvas, merged, {
+          dprCap: effectiveDprCap(merged.quality, merged.renderScale)
+        });
         nextTick(function () {
           if (disposed) return;
           emitter.emit('error', {
@@ -2874,19 +3520,37 @@
         });
       }
     } else {
-      renderer = new FallbackRenderer(canvas, merged);
+      renderer = new FallbackRenderer(canvas, merged, {
+        dprCap: effectiveDprCap(merged.quality, merged.renderScale)
+      });
     }
-    var resizeObserver = typeof ResizeObserver !== 'undefined' ? new ResizeObserver(function () {
-      return renderer.resize();
-    }) : null;
-    if (resizeObserver) resizeObserver.observe(host);else window.addEventListener('resize', renderer.resize);
-    var visibility = createVisibilityGuard(layer);
+    renderer.resize();
     var animationTime = 0;
+    var frameGate = createFrameGate(merged.fps);
+    renderOnce = function renderOnce() {
+      return renderer.draw(animationTime);
+    };
+    var resize = function resize() {
+      renderer.resize();
+      if (manuallyPaused || reducedPaused || staticMode) renderOnce();
+    };
+    var resizeObserver = typeof ResizeObserver !== 'undefined' ? new ResizeObserver(resize) : null;
+    if (resizeObserver) resizeObserver.observe(host);else window.addEventListener('resize', resize);
+    var visibility = createVisibilityGuard(layer, wakeScheduler);
+    var motionPreference = createReducedMotionPreference(merged.respectReducedMotion, function (matches) {
+      reducedPaused = matches;
+      if (matches) renderOnce();else wakeScheduler();
+    });
+    reducedPaused = motionPreference.matches();
+    var isMotionPaused = function isMotionPaused() {
+      return manuallyPaused || reducedPaused || staticMode || contextLost;
+    };
+    renderOnce();
     var unsubscribe = subscribeScheduler(function (delta) {
       animationTime += delta;
-      if (visibility.isVisible()) renderer.draw(animationTime);
+      if (frameGate.shouldDraw(delta)) renderer.draw(animationTime);
     }, function () {
-      return paused;
+      return isMotionPaused() || !visibility.isVisible();
     });
     nextTick(function () {
       if (disposed) return;
@@ -2905,11 +3569,15 @@
         var next = getPreset('capsule', ref);
         dirty.preset = true;
         Object.assign(preset, next);
+        if (colorOverride) preset.colors = _toConsumableArray(colorOverride);
+        if (seedOverride !== null) preset.seed = seedOverride;
+        if (speedOverride !== null) preset.speed = speedOverride;
         var nextColors = preset.colors.map(normalizeColor);
         if (nextColors.every(Boolean)) preset.colors = nextColors;
         renderer.setPreset(_objectSpread2({}, preset));
         renderer.resize();
         syncLayerVars();
+        if (isMotionPaused()) renderOnce();
         emitter.emit('presetchange', {
           preset: _objectSpread2({}, preset)
         });
@@ -2921,27 +3589,33 @@
           return !color;
         })) return this;
         dirty.colors = true;
+        colorOverride = _toConsumableArray(next);
         preset.colors = next;
         renderer.setPreset(_objectSpread2(_objectSpread2({}, preset), {}, {
           colors: next
         }));
         syncLayerVars();
+        if (isMotionPaused()) renderOnce();
         return this;
       },
       setSeed: function setSeed(seed) {
-        var value = Number(seed);
-        if (!Number.isFinite(value)) return this;
+        var value = toFiniteNumber(seed);
+        if (value === null) return this;
         dirty.seed = true;
+        seedOverride = value;
         preset.seed = value;
         renderer.setPreset(_objectSpread2({}, preset));
+        if (isMotionPaused()) renderOnce();
         return this;
       },
       setSpeed: function setSpeed(speed) {
-        var value = Number(speed);
-        if (!Number.isFinite(value)) return this;
+        var value = toFiniteNumber(speed);
+        if (value === null) return this;
         dirty.speed = true;
+        speedOverride = value;
         preset.speed = value;
         renderer.setPreset(_objectSpread2({}, preset));
+        if (isMotionPaused()) renderOnce();
         return this;
       },
       setFallbackColor: function setFallbackColor(value) {
@@ -2957,8 +3631,23 @@
         return this;
       },
       setQuality: function setQuality(quality) {
+        dirty.quality = true;
         merged.quality = quality;
-        if (typeof renderer.setDprCap === 'function') renderer.setDprCap(dprCapFor(quality));
+        if (typeof renderer.setDprCap === 'function') {
+          renderer.setDprCap(effectiveDprCap(quality, merged.renderScale));
+        }
+        if (isMotionPaused()) renderOnce();
+        return this;
+      },
+      setRenderScale: function setRenderScale(renderScale) {
+        var value = Number(renderScale);
+        if (!Number.isFinite(value)) return this;
+        dirty.renderScale = true;
+        merged.renderScale = Math.min(1, Math.max(0.25, value));
+        if (typeof renderer.setDprCap === 'function') {
+          renderer.setDprCap(effectiveDprCap(merged.quality, merged.renderScale));
+        }
+        if (isMotionPaused()) renderOnce();
         return this;
       },
       setOpacity: function setOpacity(value) {
@@ -2974,20 +3663,42 @@
         return this;
       },
       pause: function pause() {
-        paused = true;
+        dirty.paused = true;
+        manuallyPaused = true;
+        renderOnce();
         return this;
       },
       resume: function resume() {
-        paused = false;
+        dirty.paused = true;
+        manuallyPaused = false;
+        wakeScheduler();
+        return this;
+      },
+      setPaused: function setPaused(value) {
+        return value ? this.pause() : this.resume();
+      },
+      setStatic: function setStatic(value) {
+        dirty.static = true;
+        staticMode = value === true;
+        merged.static = staticMode;
+        if (staticMode) renderOnce();else wakeScheduler();
+        return this;
+      },
+      setFps: function setFps(fps) {
+        dirty.fps = true;
+        merged.fps = frameGate.setFps(fps);
+        wakeScheduler();
         return this;
       },
       dispose: function dispose() {
         disposed = true;
         unsubscribe();
         visibility.dispose();
-        if (resizeObserver) resizeObserver.disconnect();else window.removeEventListener('resize', renderer.resize);
+        motionPreference.dispose();
+        if (resizeObserver) resizeObserver.disconnect();else window.removeEventListener('resize', resize);
         renderer.dispose();
         layer.remove();
+        releaseHostStyles(host);
       },
       get opacity() {
         return merged.opacity;
@@ -2998,6 +3709,21 @@
       get mouseColor() {
         return merged.mouseColor;
       },
+      get quality() {
+        return merged.quality;
+      },
+      get renderScale() {
+        return merged.renderScale;
+      },
+      get paused() {
+        return manuallyPaused;
+      },
+      get static() {
+        return staticMode;
+      },
+      get fps() {
+        return frameGate.getFps();
+      },
       dirty: dirty
     };
   }
@@ -3016,6 +3742,7 @@
   exports.createColorBackground = createColorBackground;
   exports.createProgressCapsule = createProgressCapsule;
   exports.dprCapFor = dprCapFor;
+  exports.effectiveDprCap = effectiveDprCap;
   exports.getPreset = getPreset;
   exports.hexToRgb01 = hexToRgb01$1;
   exports.hexToRgba = hexToRgba;