@5even7/dlc-ui 0.2.11 → 0.2.12

package/dist/index.cjs

@@ -185,9 +185,9 @@ function _unsupportedIterableToArray(r, a) {
   }
 }
 
-/**
- * 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
@@ -237,9 +237,9 @@ function createEmitter() {
 
 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') {
@@ -278,11 +278,17 @@ function dprCapFor(quality) {
   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):
@@ -300,9 +306,9 @@ function normalizeOptions(defaults, preset, user) {
   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'],
@@ -313,9 +319,9 @@ var PALETTES$1 = {
   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',
@@ -434,6 +440,11 @@ var DEFAULTS = {
     height: 160,
     quality: 'auto',
     renderer: 'auto',
+    renderScale: 1,
+    powerPreference: 'high-performance',
+    fps: 60,
+    paused: false,
+    static: false,
     respectReducedMotion: true,
     mouseColor: true,
     textRatio: 39
@@ -443,13 +454,22 @@ var DEFAULTS = {
     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
@@ -739,7 +759,7 @@ var CosmicRenderer = /*#__PURE__*/function () {
       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');
@@ -750,16 +770,19 @@ var CosmicRenderer = /*#__PURE__*/function () {
     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;
     }
   }, {
@@ -804,15 +827,14 @@ var CosmicRenderer = /*#__PURE__*/function () {
       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;
@@ -821,16 +843,15 @@ var CosmicRenderer = /*#__PURE__*/function () {
       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);
     }
   }, {
@@ -841,6 +862,8 @@ var CosmicRenderer = /*#__PURE__*/function () {
       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');
@@ -897,6 +920,26 @@ function _bindEvents() {
     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;
@@ -911,18 +954,20 @@ function rgb(color) {
 }
 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) {
@@ -963,7 +1008,6 @@ var FallbackRenderer = /*#__PURE__*/function () {
     key: "draw",
     value: function draw(time) {
       if (!this.visible) return;
-      this.resize();
       this.drawNebula(time);
     }
   }, {
@@ -971,6 +1015,12 @@ var FallbackRenderer = /*#__PURE__*/function () {
     value: function setPreset(preset) {
       this.preset = preset;
     }
+  }, {
+    key: "setDprCap",
+    value: function setDprCap(cap) {
+      this.dprCap = cap;
+      this.resize();
+    }
   }, {
     key: "randomize",
     value: function randomize() {
@@ -988,10 +1038,10 @@ var FallbackRenderer = /*#__PURE__*/function () {
   }]);
 }();
 
-/**
- * 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;
@@ -1000,11 +1050,7 @@ var rafId = 0;
 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;
@@ -1012,10 +1058,8 @@ function tick(now) {
       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);
@@ -1023,6 +1067,25 @@ function tick(now) {
       _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;
@@ -1040,6 +1103,10 @@ function pauseAll() {
 }
 function resumeAll() {
   globallyPaused = false;
+  start();
+}
+function wakeScheduler() {
+  start();
 }
 function subscribeScheduler(onFrame, isPaused) {
   var item = {
@@ -1059,11 +1126,12 @@ function subscribeScheduler(onFrame, isPaused) {
   };
 }
 
-/**
- * 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;
@@ -1073,6 +1141,7 @@ function createVisibilityGuard(element) {
       intersecting = entries.some(function (entry) {
         return entry.isIntersecting;
       });
+      if (typeof onChange === 'function') onChange();
     }, {
       rootMargin: '180px'
     });
@@ -1080,6 +1149,7 @@ function createVisibilityGuard(element) {
   }
   var onVisibilityChange = function onVisibilityChange() {
     pageVisible = typeof document !== 'undefined' && !document.hidden;
+    if (typeof onChange === 'function') onChange();
   };
   if (typeof document !== 'undefined') {
     document.addEventListener('visibilitychange', onVisibilityChange);
@@ -1115,18 +1185,69 @@ function nextTick(fn) {
   }
 }
 
-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;
@@ -1136,10 +1257,19 @@ function createCapsule(container) {
   }
   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';
@@ -1191,25 +1321,49 @@ function createCapsule(container) {
   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', {
@@ -1218,8 +1372,15 @@ function createCapsule(container) {
       });
     }
   } 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);
@@ -1237,11 +1398,21 @@ function createCapsule(container) {
     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)
@@ -1276,12 +1447,12 @@ function createCapsule(container) {
       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;
@@ -1304,11 +1475,15 @@ function createCapsule(container) {
       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)
       });
@@ -1320,26 +1495,32 @@ function createCapsule(container) {
         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) {
@@ -1375,6 +1556,7 @@ function createCapsule(container) {
       return this;
     },
     setMouseColor: function setMouseColor(value) {
+      dirty.mouseColor = true;
       merged.mouseColor = value !== false;
       if (typeof renderer.setMouseColor === 'function') renderer.setMouseColor(merged.mouseColor);
       return this;
@@ -1389,6 +1571,7 @@ function createCapsule(container) {
         merged.height = height;
       }
       applySize();
+      if (isMotionPaused()) renderOnce();
       return this;
     },
     randomize: function randomize() {
@@ -1396,23 +1579,59 @@ function createCapsule(container) {
       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();
     },
@@ -1422,6 +1641,24 @@ function createCapsule(container) {
     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
   };
 }
@@ -1562,64 +1799,95 @@ function createProgram(gl) {
 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));
@@ -1634,6 +1902,7 @@ var ProgressFlowRenderer = /*#__PURE__*/function () {
     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);
@@ -1650,7 +1919,8 @@ var ProgressFlowRenderer = /*#__PURE__*/function () {
       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);
@@ -1682,7 +1952,10 @@ var ProgressFlowRenderer = /*#__PURE__*/function () {
   }, {
     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);
@@ -1693,8 +1966,9 @@ var ProgressFlowRenderer = /*#__PURE__*/function () {
   }]);
 }();
 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;
@@ -1754,50 +2028,49 @@ function createAtlas(id) {
     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;
@@ -1808,7 +2081,7 @@ function attachProgressFlowOverlay(_ref) {
     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);
@@ -1832,6 +2105,10 @@ function attachProgressFlowOverlay(_ref) {
     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);
@@ -1842,6 +2119,47 @@ function attachProgressFlowOverlay(_ref) {
   };
 }
 
+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);
 };
@@ -1868,9 +2186,6 @@ function interpolate(template, values) {
     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],
@@ -1931,8 +2246,6 @@ var FLOW_PROFILES = {
 var ProgressCapsuleController = /*#__PURE__*/function () {
   function ProgressCapsuleController(_ref) {
     var _options$valueSuffix,
-      _options$min,
-      _options$max,
       _options$value,
       _this = this;
     var root = _ref.root,
@@ -1954,11 +2267,18 @@ var ProgressCapsuleController = /*#__PURE__*/function () {
     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;
@@ -1968,10 +2288,12 @@ var ProgressCapsuleController = /*#__PURE__*/function () {
     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;
@@ -1984,16 +2306,37 @@ var ProgressCapsuleController = /*#__PURE__*/function () {
       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', {
@@ -2001,19 +2344,58 @@ var ProgressCapsuleController = /*#__PURE__*/function () {
           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;
     }
@@ -2178,15 +2560,14 @@ var ProgressCapsuleController = /*#__PURE__*/function () {
   }, {
     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",
@@ -2311,8 +2692,39 @@ var ProgressCapsuleController = /*#__PURE__*/function () {
     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) {
@@ -2400,6 +2812,12 @@ var ProgressCapsuleController = /*#__PURE__*/function () {
         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",
@@ -2418,20 +2836,19 @@ var ProgressCapsuleController = /*#__PURE__*/function () {
     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];
@@ -2442,15 +2859,16 @@ var ProgressCapsuleController = /*#__PURE__*/function () {
   }]);
 }();
 
-/**
+/**
  * 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;
@@ -2460,14 +2878,20 @@ function createProgressCapsule(container) {
   }
   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 />）会传成空字符串，
@@ -2476,18 +2900,31 @@ function createProgressCapsule(container) {
   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');
@@ -2496,7 +2933,8 @@ function createProgressCapsule(container) {
     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));
@@ -2551,8 +2989,22 @@ function createProgressCapsule(container) {
   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);
@@ -2573,7 +3025,11 @@ function createProgressCapsule(container) {
     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
@@ -2585,8 +3041,12 @@ function createProgressCapsule(container) {
       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') {
@@ -2597,17 +3057,34 @@ function createProgressCapsule(container) {
       });
     });
   }
-  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;
@@ -2634,32 +3111,41 @@ function createProgressCapsule(container) {
     },
     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)
       });
@@ -2669,21 +3155,28 @@ function createProgressCapsule(container) {
       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) {
@@ -2721,6 +3214,22 @@ function createProgressCapsule(container) {
       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;
@@ -2731,9 +3240,12 @@ function createProgressCapsule(container) {
         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) {
@@ -2747,30 +3259,68 @@ function createProgressCapsule(container) {
       }
       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();
@@ -2781,26 +3331,89 @@ function createProgressCapsule(container) {
     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;
@@ -2814,18 +3427,29 @@ function createColorBackground(host) {
     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() {
@@ -2840,8 +3464,12 @@ function createColorBackground(host) {
   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,
@@ -2849,19 +3477,37 @@ function createColorBackground(host) {
     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', {
@@ -2870,19 +3516,37 @@ function createColorBackground(host) {
       });
     }
   } 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;
@@ -2901,11 +3565,15 @@ function createColorBackground(host) {
       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)
       });
@@ -2917,27 +3585,33 @@ function createColorBackground(host) {
         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) {
@@ -2953,8 +3627,23 @@ function createColorBackground(host) {
       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) {
@@ -2970,20 +3659,42 @@ function createColorBackground(host) {
       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;
@@ -2994,6 +3705,21 @@ function createColorBackground(host) {
     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
   };
 }
@@ -3012,6 +3738,7 @@ exports.createCapsule = createCapsule;
 exports.createColorBackground = createColorBackground;
 exports.createProgressCapsule = createProgressCapsule;
 exports.dprCapFor = dprCapFor;
+exports.effectiveDprCap = effectiveDprCap;
 exports.getPreset = getPreset;
 exports.hexToRgb01 = hexToRgb01$1;
 exports.hexToRgba = hexToRgba;