@5even7/dlc-ui 0.2.0 → 0.2.2

package/dist/vue3.mjs

@@ -184,60 +184,266 @@ function getPreset(kind, ref) {
   return found;
 }
 
-const DEFAULTS = {
-  capsule: {
-    width: '100%',
-    height: 160,
+const DEFAULTS = {
+  capsule: {
+    width: '100%',
+    height: 160,
     quality: 'auto',
     renderer: 'auto',
     respectReducedMotion: true,
     mouseColor: true,
-    showCopy: true
-  },
-  progress: {
-    width: 454,
-    height: 104,
-    min: 0,
+    textRatio: 39
+  },
+  progress: {
+    width: 454,
+    height: 104,
+    min: 0,
     max: 100,
-    draggable: true,
-    keyboard: true,
-    edgeStyle: 'flow',
-    quality: 'auto',
-    renderer: 'auto',
-    showCopy: true,
-    respectReducedMotion: true
-  }
+    draggable: true,
+    keyboard: true,
+    disabled: false,
+    valueSuffix: '%',
+    edgeStyle: 'flow',
+    quality: 'auto',
+    renderer: 'auto',
+    textRatio: 54,
+    showValue: true,
+    respectReducedMotion: true
+  }
 };
 
-/**
- * All user-facing copy lives here so wording/brand changes never require a
- * global search. Templates use {brand} {code} {name} placeholders.
- */
-const COPY = {
-  brandName: '画境观屿',
-  dragLabel: 'DRAG',
-  valueSuffix: '%',
+/**
+ * Internal accessibility labels and small UI text. Since the copy API was
+ * removed (slots own the text area), these are no longer user-overridable.
+ * Templates use {brand} {code} {name} placeholders.
+ */
+const COPY = {
+  brandName: '画境观屿',
+  valueSuffix: '%',
   progressAria: '{brand} {code} 加载进度',
   capsuleAria: '打开 {name} 沉浸预览'
 };
 
-function hexToRgb01$1(hex) {
-  const normalized = hex.replace('#', '');
-  const value = Number.parseInt(normalized, 16);
-  return [
-    ((value >> 16) & 255) / 255,
-    ((value >> 8) & 255) / 255,
-    (value & 255) / 255
-  ];
-}
-
-function hexToRgba(hex, alpha = 1) {
-  const normalized = hex.replace('#', '');
-  const value = Number.parseInt(normalized, 16);
-  const red = (value >> 16) & 255;
-  const green = (value >> 8) & 255;
-  const blue = value & 255;
-  return `rgba(${red}, ${green}, ${blue}, ${alpha})`;
+/**
+ * Color helpers. `normalizeColor` converts any supported CSS color
+ * (hex / named / rgb() / rgba()) into a 6-digit hex string, so renderers can
+ * keep working with #rrggbb only. rgba() alpha is intentionally dropped:
+ * the WebGL shader has no per-color alpha channel, and the component is
+ * opaque by design — use component-level `opacity` for transparency.
+ */
+
+const NAMED_COLORS = {
+  aliceblue: '#f0f8ff',
+  antiquewhite: '#faebd7',
+  aqua: '#00ffff',
+  aquamarine: '#7fffd4',
+  azure: '#f0ffff',
+  beige: '#f5f5dc',
+  bisque: '#ffe4c4',
+  black: '#000000',
+  blanchedalmond: '#ffebcd',
+  blue: '#0000ff',
+  blueviolet: '#8a2be2',
+  brown: '#a52a2a',
+  burlywood: '#deb887',
+  cadetblue: '#5f9ea0',
+  chartreuse: '#7fff00',
+  chocolate: '#d2691e',
+  coral: '#ff7f50',
+  cornflowerblue: '#6495ed',
+  cornsilk: '#fff8dc',
+  crimson: '#dc143c',
+  cyan: '#00ffff',
+  darkblue: '#00008b',
+  darkcyan: '#008b8b',
+  darkgoldenrod: '#b8860b',
+  darkgray: '#a9a9a9',
+  darkgreen: '#006400',
+  darkgrey: '#a9a9a9',
+  darkkhaki: '#bdb76b',
+  darkmagenta: '#8b008b',
+  darkolivegreen: '#556b2f',
+  darkorange: '#ff8c00',
+  darkorchid: '#9932cc',
+  darkred: '#8b0000',
+  darksalmon: '#e9967a',
+  darkseagreen: '#8fbc8f',
+  darkslateblue: '#483d8b',
+  darkslategray: '#2f4f4f',
+  darkslategrey: '#2f4f4f',
+  darkturquoise: '#00ced1',
+  darkviolet: '#9400d3',
+  deeppink: '#ff1493',
+  deepskyblue: '#00bfff',
+  dimgray: '#696969',
+  dimgrey: '#696969',
+  dodgerblue: '#1e90ff',
+  firebrick: '#b22222',
+  floralwhite: '#fffaf0',
+  forestgreen: '#228b22',
+  fuchsia: '#ff00ff',
+  gainsboro: '#dcdcdc',
+  ghostwhite: '#f8f8ff',
+  gold: '#ffd700',
+  goldenrod: '#daa520',
+  gray: '#808080',
+  green: '#008000',
+  greenyellow: '#adff2f',
+  grey: '#808080',
+  honeydew: '#f0fff0',
+  hotpink: '#ff69b4',
+  indianred: '#cd5c5c',
+  indigo: '#4b0082',
+  ivory: '#fffff0',
+  khaki: '#f0e68c',
+  lavender: '#e6e6fa',
+  lavenderblush: '#fff0f5',
+  lawngreen: '#7cfc00',
+  lemonchiffon: '#fffacd',
+  lightblue: '#add8e6',
+  lightcoral: '#f08080',
+  lightcyan: '#e0ffff',
+  lightgoldenrodyellow: '#fafad2',
+  lightgray: '#d3d3d3',
+  lightgreen: '#90ee90',
+  lightgrey: '#d3d3d3',
+  lightpink: '#ffb6c1',
+  lightsalmon: '#ffa07a',
+  lightseagreen: '#20b2aa',
+  lightskyblue: '#87cefa',
+  lightslategray: '#778899',
+  lightslategrey: '#778899',
+  lightsteelblue: '#b0c4de',
+  lightyellow: '#ffffe0',
+  lime: '#00ff00',
+  limegreen: '#32cd32',
+  linen: '#faf0e6',
+  magenta: '#ff00ff',
+  maroon: '#800000',
+  mediumaquamarine: '#66cdaa',
+  mediumblue: '#0000cd',
+  mediumorchid: '#ba55d3',
+  mediumpurple: '#9370db',
+  mediumseagreen: '#3cb371',
+  mediumslateblue: '#7b68ee',
+  mediumspringgreen: '#00fa9a',
+  mediumturquoise: '#48d1cc',
+  mediumvioletred: '#c71585',
+  midnightblue: '#191970',
+  mintcream: '#f5fffa',
+  mistyrose: '#ffe4e1',
+  moccasin: '#ffe4b5',
+  navajowhite: '#ffdead',
+  navy: '#000080',
+  oldlace: '#fdf5e6',
+  olive: '#808000',
+  olivedrab: '#6b8e23',
+  orange: '#ffa500',
+  orangered: '#ff4500',
+  orchid: '#da70d6',
+  palegoldenrod: '#eee8aa',
+  palegreen: '#98fb98',
+  paleturquoise: '#afeeee',
+  palevioletred: '#db7093',
+  papayawhip: '#ffefd5',
+  peachpuff: '#ffdab9',
+  peru: '#cd853f',
+  pink: '#ffc0cb',
+  plum: '#dda0dd',
+  powderblue: '#b0e0e6',
+  purple: '#800080',
+  rebeccapurple: '#663399',
+  red: '#ff0000',
+  rosybrown: '#bc8f8f',
+  royalblue: '#4169e1',
+  saddlebrown: '#8b4513',
+  salmon: '#fa8072',
+  sandybrown: '#f4a460',
+  seagreen: '#2e8b57',
+  seashell: '#fff5ee',
+  sienna: '#a0522d',
+  silver: '#c0c0c0',
+  skyblue: '#87ceeb',
+  slateblue: '#6a5acd',
+  slategray: '#708090',
+  slategrey: '#708090',
+  snow: '#fffafa',
+  springgreen: '#00ff7f',
+  steelblue: '#4682b4',
+  tan: '#d2b48c',
+  teal: '#008080',
+  thistle: '#d8bfd8',
+  tomato: '#ff6347',
+  turquoise: '#40e0d0',
+  violet: '#ee82ee',
+  wheat: '#f5deb3',
+  white: '#ffffff',
+  whitesmoke: '#f5f5f5',
+  yellow: '#ffff00',
+  yellowgreen: '#9acd32'
+};
+
+function clampChannel(value) {
+  return Math.min(255, Math.max(0, Math.round(value)));
+}
+
+function normalizeRgbArgs(args) {
+  const parts = args.split(/[,\s/]+/).filter(Boolean);
+  if (parts.length < 3) return null;
+  const to255 = (value) => {
+    if (typeof value !== 'string' || !value) return null;
+    if (value.endsWith('%')) return clampChannel((parseFloat(value) / 100) * 255);
+    const number = Number(value);
+    return Number.isFinite(number) ? clampChannel(number) : null;
+  };
+  const red = to255(parts[0]);
+  const green = to255(parts[1]);
+  const blue = to255(parts[2]);
+  if (red === null || green === null || blue === null) return null;
+  return `#${[red, green, blue].map((n) => n.toString(16).padStart(2, '0')).join('')}`;
+}
+
+/**
+ * Convert any supported CSS color into `#rrggbb`. Returns null when the
+ * value cannot be parsed. Supports: #rgb / #rrggbb (case-insensitive),
+ * CSS named colors, rgb() / rgba() with comma or modern space syntax,
+ * including percentages. Alpha in rgba() is ignored.
+ */
+function normalizeColor(value) {
+  if (typeof value !== 'string') return null;
+  const input = value.trim();
+  if (!input) return null;
+  const lower = input.toLowerCase();
+  if (NAMED_COLORS[lower]) return NAMED_COLORS[lower];
+  if (/^#([0-9a-f]{3}|[0-9a-f]{6})$/i.test(input)) {
+    const hex = input.slice(1).toLowerCase();
+    if (hex.length === 3) return `#${hex.split('').map((c) => c + c).join('')}`;
+    return `#${hex}`;
+  }
+  const match = input.match(/^rgba?\((.*)\)$/i);
+  if (match) return normalizeRgbArgs(match[1]);
+  return null;
+}
+
+function hexToRgb01$1(color) {
+  const hex = normalizeColor(color);
+  if (!hex) return [0, 0, 0];
+  const value = Number.parseInt(hex.slice(1), 16);
+  return [
+    ((value >> 16) & 255) / 255,
+    ((value >> 8) & 255) / 255,
+    (value & 255) / 255
+  ];
+}
+
+function hexToRgba(color, alpha = 1) {
+  const hex = normalizeColor(color);
+  if (!hex) return 'rgba(0, 0, 0, 0)';
+  const value = Number.parseInt(hex.slice(1), 16);
+  const red = (value >> 16) & 255;
+  const green = (value >> 8) & 255;
+  const blue = value & 255;
+  return `rgba(${red}, ${green}, ${blue}, ${alpha})`;
 }
 
 const VERTEX_SHADER$1 = `#version 300 es
@@ -465,12 +671,31 @@ class CosmicRenderer {
     this.timeOffset = preset.seed * 0.73;
   }
 
-  setDprCap(cap) {
-    this.options.dprCap = cap;
-    this.resize();
-  }
-
-  randomize() {
+  setDprCap(cap) {
+    this.options.dprCap = cap;
+    this.resize();
+  }
+
+  setMouseColor(enabled) {
+    this.options.mouseColor = enabled !== false;
+    if (this.options.mouseColor) {
+      if (this.onPointerMove) return this;
+      this.#bindEvents();
+      return this;
+    }
+    if (this.onPointerMove) {
+      const target = this.eventTarget;
+      target.removeEventListener('pointermove', this.onPointerMove);
+      target.removeEventListener('pointerdown', this.onPointerMove);
+      target.removeEventListener('pointerleave', this.onPointerLeave);
+      this.onPointerMove = null;
+      this.onPointerLeave = null;
+    }
+    this.motionTarget = 0;
+    return this;
+  }
+
+  randomize() {
     this.preset.seed = Math.random() * 100;
     this.timeOffset = Math.random() * 40;
   }
@@ -550,10 +775,12 @@ class FallbackRenderer {
     }
   }
 
-  drawNebula(time) {
-    const ctx = this.context;
-    const { width, height } = this.canvas;
-    const gradient = ctx.createLinearGradient(0, 0, width, height);
+  drawNebula(time) {
+    const ctx = this.context;
+    const { width, height } = this.canvas;
+    const t = time * (this.preset.speed || 1);
+    const phase = (this.preset.seed || 0) * 0.7;
+    const gradient = ctx.createLinearGradient(0, 0, width, height);
     gradient.addColorStop(0, this.preset.colors[0]);
     gradient.addColorStop(0.38, this.preset.colors[1]);
     gradient.addColorStop(0.72, this.preset.colors[2]);
@@ -561,10 +788,10 @@ class FallbackRenderer {
     ctx.fillStyle = gradient;
     ctx.fillRect(0, 0, width, height);
 
-    ctx.globalCompositeOperation = 'screen';
-    for (let index = 0; index < 6; index += 1) {
-      const x = (0.5 + 0.45 * Math.sin(time * 0.32 + index * 1.7)) * width;
-      const y = (0.5 + 0.4 * Math.cos(time * 0.25 + index)) * height;
+    ctx.globalCompositeOperation = 'screen';
+    for (let index = 0; index < 6; index += 1) {
+      const x = (0.5 + 0.45 * Math.sin(t * 0.32 + index * 1.7 + phase)) * width;
+      const y = (0.5 + 0.4 * Math.cos(t * 0.25 + index + phase)) * height;
       const radius = Math.max(width, height) * (0.08 + (index % 3) * 0.04);
       const glow = ctx.createRadialGradient(x, y, 0, x, y, radius);
       glow.addColorStop(0, rgb(this.preset.colors[(index + 1) % 4], 0.24));
@@ -585,8 +812,11 @@ class FallbackRenderer {
     this.preset = preset;
   }
 
-  randomize() {}
-  dispose() {}
+  randomize() {
+    if (this.preset) this.preset.seed = Math.random() * 100;
+  }
+  setMouseColor() {}
+  dispose() {}
 }
 
 /**
@@ -686,78 +916,105 @@ function createVisibilityGuard(element) {
   };
 }
 
-function prefersReducedMotion$1() {
+/**
+ * Run a callback asynchronously, right after the current task and before the
+ * next paint. Used for mount-time events (ready / error) so listeners that
+ * are attached after create() still receive them. Falls back for legacy
+ * browsers that lack queueMicrotask / Promise.
+ */
+function nextTick(fn) {
+  if (typeof queueMicrotask === 'function') {
+    queueMicrotask(fn);
+  } else if (typeof Promise !== 'undefined' && typeof Promise.resolve === 'function') {
+    Promise.resolve().then(fn);
+  } else {
+    setTimeout(fn, 0);
+  }
+}
+
+function prefersReducedMotion$2() {
   return typeof matchMedia !== 'undefined' && matchMedia('(prefers-reduced-motion: reduce)').matches;
 }
 
 /**
- * Mount a cosmic (nebula) capsule into `container`.
- *
- * Options: preset (id/code/name or object), width, height (number=px or
- * string with px/%/vw/vh/em/rem), colors, seed, speed, quality,
- * respectReducedMotion, copy, cssVars.
- */
-function createCapsule(container, options = {}) {
+ * 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.
+ */
+function createCapsule(container, options = {}) {
   if (!container || typeof container.appendChild !== 'function') {
     throw new Error('createCapsule: container element is required');
   }
 
   const preset = { ...getPreset('capsule', options.preset ?? '初光') };
-  const merged = normalizeOptions(DEFAULTS.capsule, preset, options);
-  const copy = { ...COPY, ...(merged.copy || {}) };
-
-  const root = document.createElement('div');
-  root.className = 'hj-capsule-root hj-capsule-cosmic';
-  root.dataset.group = preset.group;
-  root.dataset.mode = 'nebula';
-  root.dataset.theme = preset.theme || 'light';
-  root.setAttribute('aria-label', copy.capsuleAria.replace('{name}', preset.name));
-
-  const copyEnabled = copy.enabled !== false && merged.showCopy !== false;
-
-  const copyText = (key, fallback) => {
-    const value = copy[key];
-    return value === undefined ? fallback : value;
-  };
-
-  function buildCopyHtml() {
-    const codeText = copyText('code', preset.code);
-    const nameText = copyText('name', preset.name);
-    const subtitleText = copyText('subtitle', preset.subtitle);
-    const stateText = copyText('state', 'LIVE COSMIC STUDY');
-    let html = '';
-    if (codeText) html += `<span class="hj-capsule-code">${codeText}</span>`;
-    if (nameText) html += `<span class="hj-capsule-name">${nameText}</span>`;
-    if (subtitleText) html += `<span class="hj-capsule-brand">${subtitleText}</span>`;
-    if (stateText) html += `<span class="hj-capsule-state">${stateText}</span>`;
-    return html;
-  }
-
-  const copyLayer = document.createElement('div');
-  copyLayer.className = 'hj-capsule-copy';
-  const renderCopy = () => {
-    if (copyEnabled) copyLayer.innerHTML = buildCopyHtml();
-  };
-  renderCopy();
-
-  const isHexColor = (value) => typeof value === 'string' && /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.test(value);
-  if (copy.background) {
-    root.style.setProperty('--hj-copy-bg', isHexColor(copy.background)
-      ? `linear-gradient(90deg, ${copy.background} 0%, ${copy.background} 74%, ${hexToRgba(copy.background, 0.97)} 84%, ${hexToRgba(copy.background, 0)} 100%)`
-      : copy.background);
-  }
-  if (copy.color) root.style.setProperty('--hj-copy-color', copy.color);
-
-  const canvas = document.createElement('canvas');
-  canvas.className = 'hj-capsule-canvas';
-  canvas.setAttribute('aria-hidden', 'true');
-
-  if (copyEnabled) root.appendChild(copyLayer);
-  root.appendChild(canvas);
-  container.appendChild(root);
-
-  const emitter = createEmitter();
-  let paused = merged.respectReducedMotion && prefersReducedMotion$1();
+  const merged = normalizeOptions(DEFAULTS.capsule, preset, options);
+  const normalizedColors = merged.colors.map(normalizeColor);
+  if (normalizedColors.every(Boolean)) preset.colors = normalizedColors;
+  preset.seed = merged.seed;
+  preset.speed = merged.speed;
+  let customLabel = typeof options.label === 'string' && options.label ? options.label : null;
+
+  const root = document.createElement('div');
+  root.className = 'hj-capsule-root hj-capsule-cosmic';
+  root.dataset.group = preset.group;
+  root.dataset.mode = 'nebula';
+  root.dataset.theme = preset.theme || 'light';
+  root.setAttribute('role', 'img');
+  const updateAria = () => {
+    root.setAttribute('aria-label', customLabel || COPY.capsuleAria.replace('{name}', preset.name));
+  };
+  updateAria();
+
+  // Slot containers are always present but transparent by default: without
+  // content they are invisible, so "no slot" behaves like the old
+  // showCopy=false. They only provide geometry — no typography, padding or
+  // background is imposed on user content (see docs: 插槽 CSS 约定).
+  const fillContent = (layer, content) => {
+    layer.innerHTML = '';
+    if (content == null) return;
+    if (typeof content === 'string') {
+      layer.innerHTML = content;
+      return;
+    }
+    const nodes = Array.isArray(content) ? content : [content];
+    for (const node of nodes) {
+      if (node && typeof node.nodeType === 'number') layer.appendChild(node);
+    }
+  };
+
+  const textLayer = document.createElement('div');
+  textLayer.className = 'hj-capsule-text hj-capsule-copy';
+
+  const visualLayer = document.createElement('div');
+  visualLayer.className = 'hj-capsule-visual';
+
+  fillContent(textLayer, options.text);
+  fillContent(visualLayer, options.colorContent);
+
+  const canvas = document.createElement('canvas');
+  canvas.className = 'hj-capsule-canvas';
+  canvas.setAttribute('aria-hidden', 'true');
+
+  root.appendChild(textLayer);
+  root.appendChild(visualLayer);
+  root.appendChild(canvas);
+  container.appendChild(root);
+
+  const emitter = createEmitter();
+  let paused = merged.respectReducedMotion && prefersReducedMotion$2();
+  let disposed = false;
+  const dirty = {
+    preset: false,
+    seed: false,
+    speed: false,
+    colors: false,
+    textRatio: false,
+    cssVars: false
+  };
 
   let renderer;
   const useWebgl = merged.renderer !== 'canvas2d';
@@ -766,19 +1023,25 @@ function createCapsule(container, options = {}) {
       renderer = new CosmicRenderer(canvas, merged, { dprCap: dprCapFor(merged.quality) });
     } catch (error) {
       renderer = new FallbackRenderer(canvas, merged);
-      emitter.emit('error', { message: String(error && error.message ? error.message : error) });
+      nextTick(() => {
+        if (disposed) return;
+        emitter.emit('error', { message: String(error && error.message ? error.message : error) });
+      });
     }
   } else {
     renderer = new FallbackRenderer(canvas, merged);
   }
 
-  const applySize = () => {
-    root.style.width = parseSize(merged.width);
-    root.style.height = parseSize(merged.height);
-    const vars = merged.cssVars || {};
-    for (const name of Object.keys(vars)) root.style.setProperty(name, vars[name]);
-    renderer.resize();
-  };
+  const applySize = () => {
+    root.style.width = parseSize(merged.width);
+    root.style.height = parseSize(merged.height);
+    const vars = merged.cssVars || {};
+    for (const name of Object.keys(vars)) root.style.setProperty(name, vars[name]);
+    if (merged.textRatio !== undefined) {
+      root.style.setProperty('--hj-text-width', `${merged.textRatio}%`);
+    }
+    renderer.resize();
+  };
   applySize();
 
   const resizeObserver = typeof ResizeObserver !== 'undefined'
@@ -807,38 +1070,47 @@ function createCapsule(container, options = {}) {
     () => paused
   );
 
-  emitter.emit('ready', { preset: { ...preset } });
+  nextTick(() => {
+    if (disposed) return;
+    emitter.emit('ready', { preset: { ...preset } });
+  });
 
-  const syncCopy = () => {
-    root.dataset.mode = 'nebula';
-    root.dataset.theme = preset.theme || 'light';
-    renderCopy();
-  };
-
-  return {
+  const syncTheme = () => {
+    root.dataset.mode = 'nebula';
+    root.dataset.theme = preset.theme || 'light';
+    updateAria();
+  };
+
+  return {
     element: root,
     canvas,
     preset,
     on: emitter.on,
     off: emitter.off,
-    setPreset(ref) {
-      const next = getPreset('capsule', ref);
-      Object.assign(preset, next);
-      renderer.setPreset(next);
-      syncCopy();
-      renderer.resize();
-      emitter.emit('presetchange', { preset: { ...next } });
-      return this;
+    setPreset(ref) {
+      const next = getPreset('capsule', ref);
+      dirty.preset = true;
+      Object.assign(preset, next);
+      const nextColors = preset.colors.map(normalizeColor);
+      if (nextColors.every(Boolean)) preset.colors = nextColors;
+      renderer.setPreset({ ...preset });
+      syncTheme();
+      renderer.resize();
+      emitter.emit('presetchange', { preset: { ...next } });
+      return this;
     },
     setColors(colors) {
-      if (!Array.isArray(colors) || colors.length !== 4) return this;
-      preset.colors = colors;
-      renderer.setPreset({ ...preset, colors });
+      const next = Array.isArray(colors) ? colors.map(normalizeColor) : [];
+      if (next.length !== 4 || next.some((color) => !color)) return this;
+      dirty.colors = true;
+      preset.colors = next;
+      renderer.setPreset({ ...preset, colors: next });
       return this;
     },
     setSeed(seed) {
       const value = Number(seed);
       if (!Number.isFinite(value)) return this;
+      dirty.seed = true;
       preset.seed = value;
       renderer.setPreset({ ...preset });
       return this;
@@ -846,20 +1118,49 @@ function createCapsule(container, options = {}) {
     setSpeed(speed) {
       const value = Number(speed);
       if (!Number.isFinite(value)) return this;
+      dirty.speed = true;
       preset.speed = value;
       renderer.setPreset({ ...preset });
       return this;
     },
-    setSize(width, height) {
+    setText(content) {
+      fillContent(textLayer, content);
+      return this;
+    },
+    setColorContent(content) {
+      fillContent(visualLayer, content);
+      return this;
+    },
+    setTextRatio(ratio) {
+      const value = Number(ratio);
+      if (!Number.isFinite(value) || value < 0 || value > 100) return this;
+      dirty.textRatio = true;
+      merged.textRatio = value;
+      root.style.setProperty('--hj-text-width', `${value}%`);
+      return this;
+    },
+    setCssVars(vars) {
+      if (!vars || typeof vars !== 'object') return this;
+      dirty.cssVars = true;
+      merged.cssVars = { ...(merged.cssVars || {}), ...vars };
+      for (const name of Object.keys(vars)) root.style.setProperty(name, vars[name]);
+      return this;
+    },
+    setLabel(label) {
+      customLabel = typeof label === 'string' && label ? label : null;
+      updateAria();
+      return this;
+    },
+    setSize(width, height) {
       if (width !== undefined) merged.width = width;
       if (height !== undefined) merged.height = height;
       applySize();
       return this;
     },
-    randomize() {
-      renderer.randomize();
-      return this;
-    },
+    randomize() {
+      this.setSeed(Math.random() * 100);
+      return this;
+    },
     pause() {
       paused = true;
       return this;
@@ -873,15 +1174,19 @@ function createCapsule(container, options = {}) {
       if (typeof renderer.setDprCap === 'function') renderer.setDprCap(dprCapFor(quality));
       return this;
     },
-    dispose() {
-      unsubscribe();
+    dispose() {
+      disposed = true;
+      unsubscribe();
       visibility.dispose();
       if (resizeObserver) resizeObserver.disconnect();
       else window.removeEventListener('resize', renderer.resize);
-      renderer.dispose();
-      root.remove();
-    }
-  };
+      renderer.dispose();
+      root.remove();
+    },
+    textRatio: merged.textRatio,
+    cssVars: merged.cssVars,
+    dirty
+  };
 }
 
 const PROGRESS_MOTION_WIDTH = 240;
@@ -1506,7 +1811,7 @@ function interpolate(template, values) {
   return template.replace(/\{(\w+)\}/g, (_, key) => (values[key] !== undefined ? values[key] : ''));
 }
 
-function prefersReducedMotion() {
+function prefersReducedMotion$1() {
   return typeof matchMedia !== 'undefined' && matchMedia('(prefers-reduced-motion: reduce)').matches;
 }
 
@@ -1569,14 +1874,16 @@ const FLOW_PROFILES = {
 };
 
 class ProgressCapsuleController {
-  constructor({ root, canvas, valueElement, preset, emitter, options, copy }) {
+  constructor({ root, canvas, valueElement, preset, emitter, options, copy, dirty }) {
     this.root = root;
     this.canvas = canvas;
     this.valueElement = valueElement;
     this.preset = preset;
     this.emitter = emitter;
-    this.options = options;
-    this.copy = copy;
+    this.options = options;
+    this.copy = copy;
+    this.dirty = dirty;
+    this.valueSuffix = options.valueSuffix ?? copy.valueSuffix;
     this.profile = preset.edgeStyle === 'tide'
       ? FLOW_PROFILES.tide
       : (FLOW_PROFILES[preset.id] || FLOW_PROFILES['visual-training']);
@@ -1617,11 +1924,22 @@ class ProgressCapsuleController {
     this.value = clamp(nextValue, this.min, this.max);
     const 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', `${rounded}${this.copy.valueSuffix}`);
-    this.valueElement.textContent = `${rounded}${this.copy.valueSuffix}`;
-    if (!this.suppressEvents) this.emitter.emit('change', { value: this.value, source });
-  }
+    this.root.setAttribute('aria-valuenow', String(rounded));
+    this.root.setAttribute('aria-valuetext', `${rounded}${this.valueSuffix}`);
+    if (this.valueElement) this.valueElement.textContent = `${rounded}${this.valueSuffix}`;
+    if (!this.suppressEvents) {
+      if (this.dirty) this.dirty.value = true;
+      this.emitter.emit('change', { value: this.value, source });
+    }
+  }
+
+  setValueSuffix(suffix) {
+    this.valueSuffix = String(suffix == null ? '' : suffix);
+    const rounded = Math.round(this.value);
+    if (this.valueElement) this.valueElement.textContent = `${rounded}${this.valueSuffix}`;
+    this.root.setAttribute('aria-valuetext', `${rounded}${this.valueSuffix}`);
+    return this;
+  }
 
   resizeCanvas() {
     const bounds = this.root.getBoundingClientRect();
@@ -1794,13 +2112,14 @@ class ProgressCapsuleController {
     if (clamped !== this.value) this.setProgress(clamped, 'prop');
   }
 
-  drawReferenceFlow() {
+  drawReferenceFlow() {
     const ctx = this.ctx;
     const width = this.width;
     const height = this.height;
     if (!ctx || width <= 0 || height <= 0) return;
 
-    const shoreline = width * (this.value / 100);
+    const range = Math.max(this.max - this.min, 1);
+    const shoreline = width * Math.min(Math.max((this.value - this.min) / range, 0), 1);
     const time = this.flowTime;
     const [dark, accentA, accentB, glow] = this.preset.colors;
 
@@ -1918,32 +2237,49 @@ class ProgressCapsuleController {
     }
   }
 
-  updateFromPointer(event) {
-    const bounds = this.root.getBoundingClientRect();
-    const ratio = bounds.width > 0 ? (event.clientX - bounds.left) / bounds.width : 0;
-    this.setProgress(ratio * 100, 'drag');
-  }
-
-  beginDrag(event) {
-    if (event.button !== undefined && event.button !== 0) return;
-    event.preventDefault();
-    this.dragging = true;
-    this.root.classList.add('is-dragging');
-    try { this.root.setPointerCapture?.(event.pointerId); } catch {}
-    this.emitter.emit('dragstart', { value: this.value });
-    this.updateFromPointer(event);
-  }
-
-  moveDrag(event) {
-    if (!this.dragging) return;
-    event.preventDefault();
-    this.updateFromPointer(event);
-  }
-
-  endDrag(event) {
-    if (!this.dragging) return;
-    this.dragging = false;
-    this.root.classList.remove('is-dragging');
+  updateFromPointer(event) {
+    const bounds = this.root.getBoundingClientRect();
+    const ratio = bounds.width > 0 ? (event.clientX - bounds.left) / bounds.width : 0;
+    this.setProgress(this.min + ratio * (this.max - this.min), 'drag');
+  }
+
+  beginDrag(event) {
+    if (event.button !== undefined && event.button !== 0) return;
+    event.preventDefault();
+    this.dragging = true;
+    this.pendingPointer = null;
+    this._dragRaf = 0;
+    this.root.classList.add('is-dragging');
+    try { this.root.setPointerCapture?.(event.pointerId); } catch {}
+    this.emitter.emit('dragstart', { value: this.value });
+    this.updateFromPointer(event);
+  }
+
+  moveDrag(event) {
+    if (!this.dragging) return;
+    event.preventDefault();
+    // rAF 合并：一帧最多一次 setProgress/change，视觉仍每帧更新。
+    this.pendingPointer = event;
+    if (this._dragRaf) return;
+    this._dragRaf = requestAnimationFrame(() => {
+      this._dragRaf = 0;
+      const pending = this.pendingPointer;
+      this.pendingPointer = null;
+      if (pending) this.updateFromPointer(pending);
+    });
+  }
+
+  endDrag(event) {
+    if (!this.dragging) return;
+    this.dragging = false;
+    if (this._dragRaf) {
+      cancelAnimationFrame(this._dragRaf);
+      this._dragRaf = 0;
+    }
+    const pending = this.pendingPointer;
+    this.pendingPointer = null;
+    if (pending) this.updateFromPointer(pending);
+    this.root.classList.remove('is-dragging');
     try {
       if (event?.pointerId !== undefined && this.root.hasPointerCapture?.(event.pointerId)) {
         this.root.releasePointerCapture(event.pointerId);
@@ -1965,15 +2301,16 @@ class ProgressCapsuleController {
     }
 
     if (this.options.keyboard !== false) {
-      this.handlers.keydown = (event) => {
-        const actions = {
-          ArrowLeft: -2,
-          ArrowDown: -2,
-          ArrowRight: 2,
-          ArrowUp: 2,
-          PageDown: -10,
-          PageUp: 10
-        };
+      this.handlers.keydown = (event) => {
+        const step = (this.max - this.min) * 0.02;
+        const actions = {
+          ArrowLeft: -step,
+          ArrowDown: -step,
+          ArrowRight: step,
+          ArrowUp: step,
+          PageDown: -step * 5,
+          PageUp: step * 5
+        };
         if (event.key === 'Home') {
           event.preventDefault();
           this.setProgress(this.min, 'keyboard');
@@ -2011,8 +2348,9 @@ class ProgressCapsuleController {
     this.preset = { ...this.preset, colors };
   }
 
-  dispose() {
-    if (this.resizeObserver) this.resizeObserver.disconnect();
+  dispose() {
+    if (this._dragRaf) cancelAnimationFrame(this._dragRaf);
+    if (this.resizeObserver) this.resizeObserver.disconnect();
     else window.removeEventListener('resize', this.resizeCanvas);
     for (const name of Object.keys(this.handlers)) {
       const handler = this.handlers[name];
@@ -2023,103 +2361,127 @@ class ProgressCapsuleController {
 }
 
 /**
- * Mount a fluid progress capsule into `container`.
- *
- * Options: preset (id/code/name or object), width, height, value, min, max,
- * draggable, keyboard, colors, edgeStyle, quality,
- * respectReducedMotion, copy, cssVars.
- */
-function createProgressCapsule(container, options = {}) {
+ * Mount a fluid progress capsule into `container`.
+ *
+ * Options: preset (id/code/name or object), width, height, value, min, max,
+ * draggable, keyboard, 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.
+ */
+function createProgressCapsule(container, options = {}) {
   if (!container || typeof container.appendChild !== 'function') {
     throw new Error('createProgressCapsule: container element is required');
   }
 
   const preset = { ...getPreset('progress', options.preset ?? '星火') };
-  const merged = normalizeOptions(DEFAULTS.progress, preset, options);
-  const copy = { ...COPY, ...(merged.copy || {}) };
-
-  const root = document.createElement('div');
-  root.className = 'hj-capsule-root hj-progress-root';
-  root.setAttribute('role', 'slider');
-  root.setAttribute('tabindex', '0');
-  root.setAttribute('data-draggable', String(merged.draggable !== false));
+  const merged = normalizeOptions(DEFAULTS.progress, preset, options);
+  const normalizedColors = merged.colors.map(normalizeColor);
+  if (normalizedColors.every(Boolean)) preset.colors = normalizedColors;
+  preset.edgeStyle = merged.edgeStyle;
+  const copy = COPY;
+  let customLabel = typeof options.label === 'string' && options.label ? options.label : null;
+  // Vue 的裸布尔属性（<ProgressCapsule disabled />）会传成空字符串，
+  // 这里统一按 true 处理。
+  const disabled = merged.disabled === true || merged.disabled === '' || merged.disabled === 'true';
+  const effectiveDraggable = disabled ? false : merged.draggable !== false;
+  const effectiveKeyboard = disabled ? false : merged.keyboard !== false;
+  const dirty = {
+    preset: false,
+    colors: false,
+    textRatio: false,
+    cssVars: false,
+    edgeStyle: false,
+    value: false
+  };
+
+  const root = document.createElement('div');
+  root.className = 'hj-capsule-root hj-progress-root';
+  root.setAttribute('role', 'slider');
+  root.setAttribute('tabindex', '0');
+  root.setAttribute('data-draggable', String(effectiveDraggable));
+  if (disabled) {
+    root.setAttribute('aria-disabled', 'true');
+    root.classList.add('is-disabled');
+  }
   root.setAttribute('aria-valuemin', String(merged.min ?? 0));
   root.setAttribute('aria-valuemax', String(merged.max ?? 100));
   root.setAttribute('aria-valuenow', String(preset.initialProgress));
-  root.setAttribute(
-    'aria-label',
-    interpolate(copy.progressAria, { brand: copy.brandName, code: preset.code, name: preset.name })
-  );
-  if (merged.keyboard === false) root.setAttribute('tabindex', '-1');
+  const updateAria = () => {
+    root.setAttribute(
+      'aria-label',
+      customLabel || interpolate(copy.progressAria, { brand: copy.brandName, code: preset.code, name: preset.name })
+    );
+  };
+  updateAria();
+  if (!effectiveKeyboard) root.setAttribute('tabindex', '-1');
 
   const canvas = document.createElement('canvas');
   canvas.className = 'hj-progress-canvas';
   canvas.setAttribute('aria-hidden', 'true');
 
-  const copyEnabled = copy.enabled !== false && merged.showCopy !== false;
-
-  const copyText = (key, fallback) => {
-    const value = copy[key];
-    return value === undefined ? fallback : value;
-  };
-
-  function buildCopyHtml() {
-    let html = '';
-    const brandText = copy.brandName || '';
-    const subtitleText = copyText('subtitle', preset.subtitle);
-    if (brandText) html += `<span class="hj-progress-name">${brandText}</span>`;
-    if (subtitleText) html += `<span class="hj-progress-subtitle">${subtitleText}</span>`;
-    return html;
-  }
-
-  const copyLayer = document.createElement('div');
-  copyLayer.className = 'hj-progress-copy';
-  const renderCopy = () => {
-    if (copyEnabled) copyLayer.innerHTML = buildCopyHtml();
-  };
-  renderCopy();
-
-  if (copy.background) {
-    root.style.setProperty('--hj-progress-copy-bg', copy.background);
-    root.style.setProperty('--hj-progress-copy-pad', '6px 12px');
-  }
-  if (copy.color) root.style.setProperty('--hj-progress-copy-color', copy.color);
-
-  const valueElement = document.createElement('div');
-  valueElement.className = 'hj-progress-value';
-  valueElement.setAttribute('aria-hidden', 'true');
-
-  const dragLabel = document.createElement('span');
-  dragLabel.className = 'hj-progress-drag-label';
-  dragLabel.setAttribute('aria-hidden', 'true');
-  dragLabel.textContent = copy.dragLabel;
-
-  root.appendChild(canvas);
-  if (copyEnabled) root.appendChild(copyLayer);
-  root.appendChild(valueElement);
-  root.appendChild(dragLabel);
-  container.appendChild(root);
-
-  const emitter = createEmitter();
-  let paused = merged.respectReducedMotion && prefersReducedMotion();
-
-  const applySize = () => {
-    root.style.width = parseSize(merged.width);
-    root.style.height = parseSize(merged.height);
-    const vars = merged.cssVars || {};
-    for (const name of Object.keys(vars)) root.style.setProperty(name, vars[name]);
-  };
+  // Slot containers are always present but transparent by default; they only
+  // provide geometry, never typography/padding/background (docs: 插槽 CSS 约定).
+  const fillContent = (layer, content) => {
+    layer.innerHTML = '';
+    if (content == null) return;
+    if (typeof content === 'string') {
+      layer.innerHTML = content;
+      return;
+    }
+    const nodes = Array.isArray(content) ? content : [content];
+    for (const node of nodes) {
+      if (node && typeof node.nodeType === 'number') layer.appendChild(node);
+    }
+  };
+
+  const textLayer = document.createElement('div');
+  textLayer.className = 'hj-progress-text hj-progress-copy';
+
+  const visualLayer = document.createElement('div');
+  visualLayer.className = 'hj-progress-visual';
+
+  fillContent(textLayer, options.text);
+  fillContent(visualLayer, options.colorContent);
+
+  const valueElement = merged.showValue === false ? null : document.createElement('div');
+  if (valueElement) {
+    valueElement.className = 'hj-progress-value';
+    valueElement.setAttribute('aria-hidden', 'true');
+  }
+
+  root.appendChild(canvas);
+  root.appendChild(textLayer);
+  root.appendChild(visualLayer);
+  if (valueElement) root.appendChild(valueElement);
+  container.appendChild(root);
+
+  const emitter = createEmitter();
+  let paused = merged.respectReducedMotion && prefersReducedMotion$1();
+  let disposed = false;
+
+  const applySize = () => {
+    root.style.width = parseSize(merged.width);
+    root.style.height = parseSize(merged.height);
+    const vars = merged.cssVars || {};
+    for (const name of Object.keys(vars)) root.style.setProperty(name, vars[name]);
+    if (merged.textRatio !== undefined) {
+      root.style.setProperty('--hj-text-width', `${merged.textRatio}%`);
+    }
+  };
   applySize();
 
-  const controller = new ProgressCapsuleController({
-    root,
-    canvas,
-    valueElement,
-    preset,
-    emitter,
-    options: merged,
-    copy
-  });
+  const controller = new ProgressCapsuleController({
+    root,
+    canvas,
+    valueElement,
+    preset,
+    emitter,
+    options: { ...merged, draggable: effectiveDraggable, keyboard: effectiveKeyboard },
+    copy,
+    dirty
+  });
 
   let overlay = null;
   if (merged.renderer !== 'canvas2d') {
@@ -2130,7 +2492,13 @@ function createProgressCapsule(container, options = {}) {
       getProgress: () => controller.value
     });
   }
-  if (overlay) controller.webglActive = true;
+  if (overlay) controller.webglActive = true;
+  else if (merged.renderer !== 'canvas2d') {
+    nextTick(() => {
+      if (disposed) return;
+      emitter.emit('error', { message: 'WebGL2 unavailable, using Canvas2D fallback' });
+    });
+  }
 
   const visibility = createVisibilityGuard(root);
   let flowTime = 0;
@@ -2146,15 +2514,14 @@ function createProgressCapsule(container, options = {}) {
     () => paused
   );
 
-  emitter.emit('ready', { preset: { ...preset } });
+  nextTick(() => {
+    if (disposed) return;
+    emitter.emit('ready', { preset: { ...preset } });
+  });
 
-  const syncDom = () => {
-    root.setAttribute(
-      'aria-label',
-      interpolate(copy.progressAria, { brand: copy.brandName, code: preset.code, name: preset.name })
-    );
-    renderCopy();
-  };
+  const syncDom = () => {
+    updateAria();
+  };
 
   return {
     element: root,
@@ -2175,26 +2542,30 @@ function createProgressCapsule(container, options = {}) {
     },
     setPreset(ref) {
       const next = getPreset('progress', ref);
+      dirty.preset = true;
       Object.assign(preset, next);
-      controller.preset = next;
-      controller.profile = next.edgeStyle === 'tide'
-        ? FLOW_PROFILES.tide
-        : (FLOW_PROFILES[next.id] || FLOW_PROFILES['visual-training']);
-      controller.flowTime = stringSeed(next.id) * 31;
-      controller.seed = stringSeed(`${next.id}-reference`) * Math.PI * 2;
-      syncDom();
-      if (overlay) {
-        overlay.dispose();
-        overlay = attachProgressFlowOverlay({ root, canvas, preset: next, getProgress: () => controller.value });
-      }
-      controller.webglActive = Boolean(overlay);
-      controller.resizeCanvas();
-      emitter.emit('presetchange', { preset: { ...next } });
+      const 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.flowTime = stringSeed(next.id) * 31;
+      controller.seed = stringSeed(`${next.id}-reference`) * Math.PI * 2;
+      syncDom();
+      if (overlay) {
+        overlay.dispose();
+        overlay = attachProgressFlowOverlay({ root, canvas, preset, getProgress: () => controller.value });
+      }
+      controller.webglActive = Boolean(overlay);
+      controller.resizeCanvas();
+      emitter.emit('presetchange', { preset: { ...preset } });
       return this;
     },
     setEdgeStyle(edgeStyle) {
       const value = String(edgeStyle || '').toLowerCase();
       if (value !== 'flow' && value !== 'tide') return this;
+      dirty.edgeStyle = true;
       preset.edgeStyle = value;
       controller.profile = value === 'tide'
         ? FLOW_PROFILES.tide
@@ -2207,12 +2578,46 @@ function createProgressCapsule(container, options = {}) {
       controller.resizeCanvas();
       return this;
     },
+    setText(content) {
+      fillContent(textLayer, content);
+      return this;
+    },
+    setColorContent(content) {
+      fillContent(visualLayer, content);
+      return this;
+    },
+    setTextRatio(ratio) {
+      const value = Number(ratio);
+      if (!Number.isFinite(value) || value < 0 || value > 100) return this;
+      dirty.textRatio = true;
+      merged.textRatio = value;
+      root.style.setProperty('--hj-text-width', `${value}%`);
+      return this;
+    },
+    setCssVars(vars) {
+      if (!vars || typeof vars !== 'object') return this;
+      dirty.cssVars = true;
+      merged.cssVars = { ...(merged.cssVars || {}), ...vars };
+      for (const name of Object.keys(vars)) root.style.setProperty(name, vars[name]);
+      return this;
+    },
+    setLabel(label) {
+      customLabel = typeof label === 'string' && label ? label : null;
+      updateAria();
+      return this;
+    },
+    setValueSuffix(suffix) {
+      controller.setValueSuffix(suffix);
+      return this;
+    },
     setColors(colors) {
-      if (!Array.isArray(colors) || colors.length !== 4) return this;
-      controller.setColors(colors);
-      if (overlay) overlay.setColors(colors);
-      controller.resizeCanvas();
-      return this;
+      const next = Array.isArray(colors) ? colors.map(normalizeColor) : [];
+      if (next.length !== 4 || next.some((color) => !color)) return this;
+      dirty.colors = true;
+      controller.setColors(next);
+      if (overlay) overlay.setColors(next);
+      controller.resizeCanvas();
+      return this;
     },
     setSize(width, height) {
       if (width !== undefined) merged.width = width;
@@ -2239,14 +2644,240 @@ function createProgressCapsule(container, options = {}) {
       controller.resizeCanvas();
       return this;
     },
-    dispose() {
-      unsubscribe();
+    dispose() {
+      disposed = true;
+      unsubscribe();
       visibility.dispose();
       if (overlay) overlay.dispose();
-      controller.dispose();
-      root.remove();
-    }
+      controller.dispose();
+      root.remove();
+    },
+    textRatio: merged.textRatio,
+    cssVars: merged.cssVars,
+    dirty
+  };
+}
+
+function prefersReducedMotion() {
+  return typeof matchMedia !== 'undefined' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+
+/**
+ * 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 (id/code/name or object), colors, seed, speed, quality,
+ * renderer, mouseColor, respectReducedMotion, opacity (0-1), fallbackColor
+ * (true=preset base color, a hex string, or false to disable).
+ */
+function createColorBackground(host, options = {}) {
+  if (!host || typeof host.appendChild !== 'function') {
+    throw new Error('createColorBackground: host element is required');
+  }
+
+  const preset = { ...getPreset('capsule', options.preset ?? '初光') };
+  const merged = normalizeOptions(
+    {
+      quality: DEFAULTS.capsule.quality,
+      renderer: DEFAULTS.capsule.renderer,
+      respectReducedMotion: DEFAULTS.capsule.respectReducedMotion,
+      mouseColor: true,
+      opacity: 1,
+      fallbackColor: true
+    },
+    preset,
+    options
+  );
+  const normalizedColors = merged.colors.map(normalizeColor);
+  if (normalizedColors.every(Boolean)) preset.colors = normalizedColors;
+  preset.seed = merged.seed;
+  preset.speed = merged.speed;
+
+  const computed = getComputedStyle(host);
+  if (computed.position === 'static' || computed.position === '') {
+    host.style.position = 'relative';
+  }
+  host.style.isolation = 'isolate';
+
+  const layer = document.createElement('div');
+  layer.className = 'dlc-color-layer';
+
+  const syncLayerVars = () => {
+    layer.style.setProperty('--dlc-color-opacity', String(merged.opacity));
+    const fallback =
+      merged.fallbackColor === false || merged.fallbackColor == null
+        ? 'transparent'
+        : typeof merged.fallbackColor === 'string'
+          ? merged.fallbackColor
+          : preset.colors[0];
+    layer.style.setProperty('--dlc-color-bg', fallback);
   };
+  syncLayerVars();
+
+  const canvas = document.createElement('canvas');
+  canvas.className = 'dlc-color-canvas';
+  canvas.setAttribute('aria-hidden', 'true');
+  layer.appendChild(canvas);
+  host.appendChild(layer);
+
+  const emitter = createEmitter();
+  let paused = merged.respectReducedMotion && prefersReducedMotion();
+  let disposed = false;
+  const dirty = {
+    preset: false,
+    seed: false,
+    speed: false,
+    colors: false,
+    opacity: false,
+    fallbackColor: false,
+    mouseColor: false
+  };
+
+  let renderer;
+  const useWebgl = merged.renderer !== 'canvas2d';
+  if (useWebgl) {
+    try {
+      renderer = new CosmicRenderer(canvas, merged, {
+        dprCap: dprCapFor(merged.quality),
+        mouseColor: merged.mouseColor !== false,
+        eventTarget: host
+      });
+    } catch (error) {
+      renderer = new FallbackRenderer(canvas, merged);
+      nextTick(() => {
+        if (disposed) return;
+        emitter.emit('error', {
+          message: String(error && error.message ? error.message : error)
+        });
+      });
+    }
+  } else {
+    renderer = new FallbackRenderer(canvas, merged);
+  }
+
+  const resizeObserver =
+    typeof ResizeObserver !== 'undefined'
+      ? new ResizeObserver(() => renderer.resize())
+      : null;
+  if (resizeObserver) resizeObserver.observe(host);
+  else window.addEventListener('resize', renderer.resize);
+
+  const visibility = createVisibilityGuard(layer);
+
+  let animationTime = 0;
+  const unsubscribe = subscribeScheduler(
+    (delta) => {
+      animationTime += delta;
+      if (visibility.isVisible()) renderer.draw(animationTime);
+    },
+    () => paused
+  );
+
+  nextTick(() => {
+    if (disposed) return;
+    emitter.emit('ready', { preset: { ...preset } });
+  });
+
+  return {
+    element: host,
+    layer,
+    canvas,
+    preset,
+    on: emitter.on,
+    off: emitter.off,
+    setPreset(ref) {
+      const next = getPreset('capsule', ref);
+      dirty.preset = true;
+      Object.assign(preset, next);
+      const nextColors = preset.colors.map(normalizeColor);
+      if (nextColors.every(Boolean)) preset.colors = nextColors;
+      renderer.setPreset({ ...preset });
+      renderer.resize();
+      syncLayerVars();
+      emitter.emit('presetchange', { preset: { ...preset } });
+      return this;
+    },
+    setColors(colors) {
+      const next = Array.isArray(colors) ? colors.map(normalizeColor) : [];
+      if (next.length !== 4 || next.some((color) => !color)) return this;
+      dirty.colors = true;
+      preset.colors = next;
+      renderer.setPreset({ ...preset, colors: next });
+      syncLayerVars();
+      return this;
+    },
+    setSeed(seed) {
+      const value = Number(seed);
+      if (!Number.isFinite(value)) return this;
+      dirty.seed = true;
+      preset.seed = value;
+      renderer.setPreset({ ...preset });
+      return this;
+    },
+    setSpeed(speed) {
+      const value = Number(speed);
+      if (!Number.isFinite(value)) return this;
+      dirty.speed = true;
+      preset.speed = value;
+      renderer.setPreset({ ...preset });
+      return this;
+    },
+    setFallbackColor(value) {
+      dirty.fallbackColor = true;
+      merged.fallbackColor = value;
+      syncLayerVars();
+      return this;
+    },
+    setMouseColor(value) {
+      dirty.mouseColor = true;
+      merged.mouseColor = value !== false;
+      if (typeof renderer.setMouseColor === 'function') renderer.setMouseColor(merged.mouseColor);
+      return this;
+    },
+    setQuality(quality) {
+      merged.quality = quality;
+      if (typeof renderer.setDprCap === 'function') renderer.setDprCap(dprCapFor(quality));
+      return this;
+    },
+    setOpacity(value) {
+      const opacity = Number(value);
+      if (!Number.isFinite(opacity)) return this;
+      dirty.opacity = true;
+      merged.opacity = Math.min(1, Math.max(0, opacity));
+      layer.style.setProperty('--dlc-color-opacity', String(merged.opacity));
+      return this;
+    },
+    randomize() {
+      this.setSeed(Math.random() * 100);
+      return this;
+    },
+    pause() {
+      paused = true;
+      return this;
+    },
+    resume() {
+      paused = false;
+      return this;
+    },
+    dispose() {
+      disposed = true;
+      unsubscribe();
+      visibility.dispose();
+      if (resizeObserver) resizeObserver.disconnect();
+      else window.removeEventListener('resize', renderer.resize);
+      renderer.dispose();
+      layer.remove();
+    },
+    opacity: merged.opacity,
+    fallbackColor: merged.fallbackColor,
+    mouseColor: merged.mouseColor,
+    dirty
+  };
 }
 
 /**
@@ -2255,11 +2886,12 @@ function createProgressCapsule(container, options = {}) {
  * `h` (see vue2.js / vue3.js). Lifecycle options cover both.
  */
 
-const CAPSULE_EVENTS = [
-  'ready', 'error', 'click', 'pointerdown', 'pointerup', 'dblclick',
-  'pointerenter', 'pointerleave', 'presetchange'
-];
-const PROGRESS_EVENTS = ['ready', 'error', 'change', 'dragstart', 'dragend', 'presetchange'];
+const CAPSULE_EVENTS = [
+  'ready', 'error', 'click', 'pointerdown', 'pointerup', 'dblclick',
+  'pointerenter', 'pointerleave', 'presetchange'
+];
+const PROGRESS_EVENTS = ['ready', 'error', 'change', 'dragstart', 'dragend', 'presetchange'];
+const COLOR_EVENTS = ['ready', 'error', 'presetchange'];
 
 function hookEvents(controller, events, emit) {
   for (const event of events) {
@@ -2267,42 +2899,92 @@ function hookEvents(controller, events, emit) {
   }
 }
 
-function makeWrapper({ name, props, events, create, render, methods, watch }) {
-  const internalMethods = {
-    mountController() {
-      this.controller = create(this.$el, this.$props);
-      hookEvents(this.controller, events, (event, payload) => this.$emit(event, payload));
-    },
-    recreate() {
-      if (this.controller) this.controller.dispose();
-      if (this.$el) this.$el.innerHTML = '';
-      this.mountController();
-    },
-    scheduleRecreate() {
-      if (this._recreateQueued) return;
-      this._recreateQueued = true;
+function makeWrapper({ name, props, events, create, render, methods, watch }) {
+  const internalMethods = {
+    mountController(extraState = {}) {
+      this.controller = create(this.$el, { ...this.$props, ...extraState });
+      hookEvents(this.controller, events, (event, payload) => this.$emit(event, payload));
+      this.moveSlots();
+      this.applyAttrs();
+    },
+    recreate() {
+      const extraState = this.runtimeState();
+      if (this.controller) this.controller.dispose();
+      this.mountController(extraState);
+    },
+    scheduleRecreate() {
+      if (this._recreateQueued) return;
+      this._recreateQueued = true;
       this.$nextTick(() => {
         this._recreateQueued = false;
-        this.recreate();
-      });
-    }
-  };
-
-  return {
-    name,
-    props,
-    emits: events,
-    render,
+        this.recreate();
+      });
+    },
+    moveSlots() {
+      if (!this.controller || !this.controller.element || !this.$el) return;
+      const root = this.controller.element;
+      const textLayer = root.querySelector('.hj-capsule-text, .hj-progress-text');
+      const visualLayer = root.querySelector('.hj-capsule-visual, .hj-progress-visual');
+      const move = (wrapper, layer) => {
+        if (!wrapper || !layer) return;
+        for (const node of Array.from(wrapper.childNodes)) layer.appendChild(node);
+      };
+      const refs = this.$refs || {};
+      move(refs.slotText, textLayer);
+      move(refs.slotColor, visualLayer);
+    },
+    applyAttrs() {
+      if (!this.controller || !this.controller.element || !this.$attrs) return;
+      const root = this.controller.element;
+      for (const key of Object.keys(this.$attrs)) {
+        if (key === 'class' || key === 'style') continue;
+        const value = this.$attrs[key];
+        if (value == null || value === false) root.removeAttribute(key);
+        else root.setAttribute(key, String(value));
+      }
+    },
+    runtimeState() {
+      const controller = this.controller;
+      if (!controller || !controller.dirty) return {};
+      const dirty = controller.dirty;
+      const state = {};
+      if (dirty.preset && controller.preset) state.preset = controller.preset.name;
+      if (dirty.seed && controller.preset && controller.preset.seed !== undefined) state.seed = controller.preset.seed;
+      if (dirty.speed && controller.preset && controller.preset.speed !== undefined) state.speed = controller.preset.speed;
+      if (dirty.colors && controller.preset && Array.isArray(controller.preset.colors)) {
+        state.colors = [...controller.preset.colors];
+      }
+      if (dirty.textRatio && controller.textRatio !== undefined) state.textRatio = controller.textRatio;
+      if (dirty.cssVars && controller.cssVars) state.cssVars = { ...controller.cssVars };
+      if (dirty.value && typeof controller.getValue === 'function') state.value = controller.getValue();
+      if (dirty.edgeStyle && controller.preset) state.edgeStyle = controller.preset.edgeStyle;
+      if (dirty.opacity) state.opacity = controller.opacity;
+      if (dirty.fallbackColor) state.fallbackColor = controller.fallbackColor;
+      if (dirty.mouseColor) state.mouseColor = controller.mouseColor;
+      return state;
+    }
+  };
+
+  return {
+    name,
+    props,
+    emits: events,
+    render,
+    inheritAttrs: false,
     mounted() {
       this.mountController();
     },
     beforeUnmount() {
       if (this.controller) this.controller.dispose();
     },
-    beforeDestroy() {
-      if (this.controller) this.controller.dispose();
-    },
-    watch: {
+    beforeDestroy() {
+      if (this.controller) this.controller.dispose();
+    },
+    updated() {
+      this.moveSlots();
+      this.applyAttrs();
+    },
+    watch: {
       preset(value) { if (value && this.controller) this.controller.setPreset(value); },
       colors(value) { if (value && this.controller) this.controller.setColors(value); },
       width(value) { if (value !== undefined && this.controller) this.controller.setSize(value); },
@@ -2316,11 +2998,11 @@ function makeWrapper({ name, props, events, create, render, methods, watch }) {
 
 function makeCapsuleWrapper(createCapsule, render) {
   return makeWrapper({
-    name: 'CosmicCapsule',
+    name: 'CosmicCapsule',
     props: [
       'preset', 'width', 'height', 'colors', 'seed', 'speed',
-      'mouseColor', 'renderer', 'quality', 'respectReducedMotion', 'copy', 'cssVars'
-    ],
+      'textRatio', 'label', 'mouseColor', 'renderer', 'quality', 'respectReducedMotion', 'cssVars'
+    ],
     events: CAPSULE_EVENTS,
     create: createCapsule,
     render,
@@ -2337,6 +3019,15 @@ function makeCapsuleWrapper(createCapsule, render) {
           this.controller.setSpeed(speed);
         }
       },
+      textRatio(value) {
+        if (value !== undefined && this.controller) this.controller.setTextRatio(Number(value));
+      },
+      cssVars(value) {
+        if (value && this.controller) this.controller.setCssVars(value);
+      },
+      label(value) {
+        if (this.controller) this.controller.setLabel(value);
+      },
       mouseColor() {
         this.scheduleRecreate();
       },
@@ -2348,23 +3039,28 @@ function makeCapsuleWrapper(createCapsule, render) {
       randomize() { return this.controller && this.controller.randomize(); },
       pause() { return this.controller && this.controller.pause(); },
       resume() { return this.controller && this.controller.resume(); },
-      setPreset(preset) { return this.controller && this.controller.setPreset(preset); },
-      setSize(width, height) { return this.controller && this.controller.setSize(width, height); },
-      setColors(colors) { return this.controller && this.controller.setColors(colors); },
-      setQuality(quality) { return this.controller && this.controller.setQuality(quality); },
-      getController() { return this.controller; }
+      setPreset(preset) { return this.controller && this.controller.setPreset(preset); },
+      setSize(width, height) { return this.controller && this.controller.setSize(width, height); },
+      setColors(colors) { return this.controller && this.controller.setColors(colors); },
+      setText(content) { return this.controller && this.controller.setText(content); },
+      setColorContent(content) { return this.controller && this.controller.setColorContent(content); },
+      setTextRatio(ratio) { return this.controller && this.controller.setTextRatio(ratio); },
+      setCssVars(vars) { return this.controller && this.controller.setCssVars(vars); },
+      setLabel(label) { return this.controller && this.controller.setLabel(label); },
+      setQuality(quality) { return this.controller && this.controller.setQuality(quality); },
+      getController() { return this.controller; }
     }
   });
 }
 
-function makeProgressWrapper(createProgressCapsule, render) {
+function makeProgressWrapper(createProgressCapsule, render) {
   return makeWrapper({
-    name: 'ProgressCapsule',
-    props: [
-      'preset', 'width', 'height', 'value', 'min', 'max',
-      'draggable', 'keyboard', 'edgeStyle', 'colors', 'quality', 'renderer',
-      'respectReducedMotion', 'copy', 'cssVars'
-    ],
+    name: 'ProgressCapsule',
+    props: [
+      'preset', 'width', 'height', 'value', 'min', 'max',
+      'draggable', 'keyboard', 'disabled', 'edgeStyle', 'colors', 'textRatio', 'label', 'showValue', 'valueSuffix',
+      'quality', 'renderer', 'respectReducedMotion', 'cssVars'
+    ],
     events: PROGRESS_EVENTS,
     create: createProgressCapsule,
     render,
@@ -2381,9 +3077,27 @@ function makeProgressWrapper(createProgressCapsule, render) {
       edgeStyle(value) {
         if (value && this.controller) this.controller.setEdgeStyle(value);
       },
-      draggable() {
-        this.scheduleRecreate();
-      },
+      textRatio(value) {
+        if (value !== undefined && this.controller) this.controller.setTextRatio(Number(value));
+      },
+      cssVars(value) {
+        if (value && this.controller) this.controller.setCssVars(value);
+      },
+      label(value) {
+        if (this.controller) this.controller.setLabel(value);
+      },
+      valueSuffix(value) {
+        if (value !== undefined && this.controller) this.controller.setValueSuffix(value);
+      },
+      showValue() {
+        this.scheduleRecreate();
+      },
+      disabled() {
+        this.scheduleRecreate();
+      },
+      draggable() {
+        this.scheduleRecreate();
+      },
       keyboard() {
         this.scheduleRecreate();
       },
@@ -2398,24 +3112,96 @@ function makeProgressWrapper(createProgressCapsule, render) {
       randomize() { return this.controller && this.controller.randomize(); },
       pause() { return this.controller && this.controller.pause(); },
       resume() { return this.controller && this.controller.resume(); },
-      setPreset(preset) { return this.controller && this.controller.setPreset(preset); },
-      setSize(width, height) { return this.controller && this.controller.setSize(width, height); },
-      setColors(colors) { return this.controller && this.controller.setColors(colors); },
-      setQuality(quality) { return this.controller && this.controller.setQuality(quality); },
+      setPreset(preset) { return this.controller && this.controller.setPreset(preset); },
+      setSize(width, height) { return this.controller && this.controller.setSize(width, height); },
+      setColors(colors) { return this.controller && this.controller.setColors(colors); },
+      setText(content) { return this.controller && this.controller.setText(content); },
+      setColorContent(content) { return this.controller && this.controller.setColorContent(content); },
+      setTextRatio(ratio) { return this.controller && this.controller.setTextRatio(ratio); },
+      setCssVars(vars) { return this.controller && this.controller.setCssVars(vars); },
+      setLabel(label) { return this.controller && this.controller.setLabel(label); },
+      setValueSuffix(suffix) { return this.controller && this.controller.setValueSuffix(suffix); },
+      setQuality(quality) { return this.controller && this.controller.setQuality(quality); },
       getController() { return this.controller; }
     }
-  });
+  });
 }
 
-// Vue3 does NOT pass `h` to the render option; it must be imported.
-const render = () => h('div', { class: 'hj-vue-host' });
-
-const CosmicCapsule = makeCapsuleWrapper(createCapsule, render);
-const ProgressCapsule = makeProgressWrapper(createProgressCapsule, render);
-
-var vue3 = {
-  CosmicCapsule,
-  ProgressCapsule
+function makeColorWrapper(createColorBackground, render) {
+  return makeWrapper({
+    name: 'ColorBackground',
+    props: [
+      'preset', 'colors', 'seed', 'speed', 'quality', 'renderer',
+      'mouseColor', 'respectReducedMotion', 'opacity', 'fallbackColor'
+    ],
+    events: COLOR_EVENTS,
+    create: createColorBackground,
+    render,
+    watch: {
+      seed(value) {
+        const seed = Number(value);
+        if (this.controller && Number.isFinite(seed)) this.controller.setSeed(seed);
+      },
+      speed(value) {
+        const speed = Number(value);
+        if (this.controller && Number.isFinite(speed)) this.controller.setSpeed(speed);
+      },
+      opacity(value) {
+        if (value !== undefined && this.controller) this.controller.setOpacity(Number(value));
+      },
+      fallbackColor(value) {
+        if (this.controller) this.controller.setFallbackColor(value);
+      },
+      mouseColor(value) {
+        if (this.controller) this.controller.setMouseColor(value);
+      },
+      renderer() {
+        this.scheduleRecreate();
+      },
+      respectReducedMotion() {
+        this.scheduleRecreate();
+      }
+    },
+    methods: {
+      setPreset(preset) { return this.controller && this.controller.setPreset(preset); },
+      setColors(colors) { return this.controller && this.controller.setColors(colors); },
+      setSeed(seed) { return this.controller && this.controller.setSeed(seed); },
+      setSpeed(speed) { return this.controller && this.controller.setSpeed(speed); },
+      setQuality(quality) { return this.controller && this.controller.setQuality(quality); },
+      setOpacity(value) { return this.controller && this.controller.setOpacity(value); },
+      setFallbackColor(value) { return this.controller && this.controller.setFallbackColor(value); },
+      setMouseColor(value) { return this.controller && this.controller.setMouseColor(value); },
+      randomize() { return this.controller && this.controller.randomize(); },
+      pause() { return this.controller && this.controller.pause(); },
+      resume() { return this.controller && this.controller.resume(); },
+      getController() { return this.controller; }
+    }
+  });
+}
+
+// Vue3 does NOT pass `h` to the render option; it must be imported. Slot
+// content renders into two marker wrappers, then moveSlots moves it into the
+// component's slot containers.
+const render = function render() {
+  return h('div', { class: 'hj-vue-host' }, [
+    h('div', { class: 'hj-vue-slot-text', ref: 'slotText' }, this.$slots.default ? this.$slots.default() : []),
+    h('div', { class: 'hj-vue-slot-color', ref: 'slotColor' }, this.$slots.color ? this.$slots.color() : [])
+  ]);
+};
+
+// Color 的宿主内容就是组件内容：直接放在 host 里，浮在背景层上方。
+const renderColor = function renderColor() {
+  return h('div', { class: 'hj-vue-host' }, this.$slots.default ? this.$slots.default() : []);
+};
+
+const CosmicCapsule = makeCapsuleWrapper(createCapsule, render);
+const ProgressCapsule = makeProgressWrapper(createProgressCapsule, render);
+const ColorBackground = makeColorWrapper(createColorBackground, renderColor);
+
+var vue3 = {
+  CosmicCapsule,
+  ProgressCapsule,
+  ColorBackground
 };
 
-export { CosmicCapsule, ProgressCapsule, vue3 as default };
+export { ColorBackground, CosmicCapsule, ProgressCapsule, vue3 as default };