particle-network-bg 1.0.1 → 1.0.2

package/README.md

@@ -89,6 +89,8 @@ function App() {
 ```
 
 > **Note:** Config is applied on mount. The canvas resizes to the window. When gradients are enabled, a background `<div>` is automatically created behind the canvas for smooth CSS-based gradient rendering.
+>
+> Pulse animations are automatically phase-randomized so particles don't pulse in sync.
 
 ## Configuration
 
@@ -160,6 +162,7 @@ new ParticleNetwork(canvas, {
     secondaryHighlightPosition: "bottom-right",
     minRadius: 20,            // min size for liquid glass particles (overrides root minRadius)
     maxRadius: 40,            // max size for liquid glass particles (overrides root maxRadius)
+    blobSpeed: 1,             // blob deformation speed multiplier (0 = frozen, 2 = double speed)
   },
 });
 ```
@@ -344,7 +347,7 @@ function App() {
       </ChildParticle>
 
       {/* Liquid glass blob particle */}
-      <GlassChildParticle id="clock" x={600} y={400} radius={60}>
+      <GlassChildParticle id="clock" x={600} y={400} radius={60} glassColor="#ff6600" glassOpacity={0.8}>
         <span>🕐</span>
       </GlassChildParticle>
 
@@ -371,6 +374,9 @@ function App() {
 | `overflow`       | string    | `"hidden"` | CSS overflow for the child content container                |
 | `anchorForce`    | number    | `0.05`   | Spring force pulling back to anchor (0–1). Lower = more floaty |
 | `mouseInfluence` | number    | `0.1`    | Mouse influence multiplier (0–1). 0 = ignores mouse           |
+| `glassOpacity`   | number    | —        | Opacity (0–1) for liquid glass. Overrides global `liquidGlass.opacity` |
+| `glassColor`     | string    | —        | Color (hex) for liquid glass. Overrides global `liquidGlass.color` |
+| `liquidGlassConfig` | `Partial<LiquidGlassConfig>` | — | Full liquid glass config override, merged over global `liquidGlass` |
 | `children`       | ReactNode | —        | Content to render inside the particle                         |
 | `style`          | CSSProperties | —   | Style applied to the inner wrapper div                        |
 | `className`      | string    | —        | Class applied to the inner wrapper div                        |
@@ -391,7 +397,9 @@ network.addChildParticle({
   radius: 50,
   anchorForce: 0.05,
   mouseInfluence: 0.1,
-  liquidGlass: false,
+  liquidGlass: true,
+  glassOpacity: 0.7,                 // override global liquidGlass.opacity
+  glassColor: "#ff6600",             // override global liquidGlass.color
 });
 
 // Update its anchor (e.g. on scroll/resize)
@@ -436,6 +444,9 @@ interface ChildParticleConfig {
   anchorForce?: number;
   mouseInfluence?: number;
   liquidGlass?: boolean;
+  glassOpacity?: number;              // overrides global liquidGlass.opacity
+  glassColor?: string;                // overrides global liquidGlass.color
+  liquidGlassConfig?: Partial<LiquidGlassConfig>; // merged over global liquidGlass
 }
 
 interface ChildParticlePosition {

package/dist/{chunk-BMXQY2SK.mjs → chunk-JZTYQ6XI.mjs}

@@ -43,6 +43,7 @@ var DEFAULT_LIQUID_GLASS = {
   shadowStrength: 0.4,
   secondaryReflection: 0.25,
   secondaryHighlightPosition: "bottom-right",
+  blobSpeed: 1,
   minRadius: 20,
   maxRadius: 40
 };
@@ -158,7 +159,7 @@ var ParticleNetwork = class {
       const h = isRect ? particle.height : (particle.currentRadius ?? particle.radius) * 2;
       el.style.width = w + "px";
       el.style.height = h + "px";
-      el.style.transform = `translate(${px - w / 2}px, ${py - h / 2}px)`;
+      el.style.transform = `translate3d(${Math.round(px - w / 2)}px, ${Math.round(py - h / 2)}px, 0)`;
       if (isRect) {
         const br = particle.borderRadius ?? Math.min(w, h) / 2;
         el.style.borderRadius = br + "px";
@@ -314,7 +315,14 @@ var ParticleNetwork = class {
       if (!Array.isArray(config.particleTypes)) {
         throw new Error("particleTypes must be an array");
       }
-      if (!config.assets || typeof config.assets !== "object") {
+      let hasAssetEntries = false;
+      for (const entry of config.particleTypes) {
+        if (entry?.type === "asset") {
+          hasAssetEntries = true;
+          break;
+        }
+      }
+      if (hasAssetEntries && (!config.assets || typeof config.assets !== "object")) {
         throw new Error("assets map is required when using particleTypes with asset entries");
       }
       for (let i = 0; i < config.particleTypes.length; i++) {
@@ -334,8 +342,9 @@ var ParticleNetwork = class {
           if (typeof pt.asset !== "string" || !pt.asset) {
             throw new Error(`particleTypes[${i}].asset must be a non-empty string`);
           }
-          if (!config.assets[pt.asset]) {
-            throw new Error(`particleTypes[${i}]: asset "${pt.asset}" not found in assets`);
+          const assetKey = pt.asset;
+          if (!config.assets?.[assetKey]) {
+            throw new Error(`particleTypes[${i}]: asset "${assetKey}" not found in assets`);
           }
         }
       }
@@ -433,6 +442,7 @@ var ParticleNetwork = class {
       delete p.assetId;
       delete p.liquidGlass;
       delete p.typeConfig;
+      delete p.pulsePhase;
     });
     if (particleTypes?.length) {
       const counts = [];
@@ -501,6 +511,14 @@ var ParticleNetwork = class {
     if (!particleTypes?.length && (this.config.liquidGlassPercentage != null || this.config.liquidGlassCount != null)) {
       this.assignLiquidGlass();
     }
+    this.particles.forEach((p) => {
+      if (p.isChild) return;
+      const tc = p.typeConfig;
+      const doPulse = tc?.pulse ?? this.config.pulseEnabled;
+      if (doPulse) {
+        p.pulsePhase = Math.random() * Math.PI * 2;
+      }
+    });
     this.assignMouseBehavior();
   }
   assignLiquidGlass() {
@@ -606,7 +624,8 @@ var ParticleNetwork = class {
         if (doPulse) {
           const speed = tc?.pulseSpeed ?? this.config.pulseSpeed;
           this.pulseAngle += speed;
-          const pulseScale = Math.sin(this.pulseAngle) * 0.5 + 1;
+          const phase = particle.pulsePhase ?? 0;
+          const pulseScale = Math.sin(this.pulseAngle + phase) * 0.5 + 1;
           particle.currentRadius = particle.radius * pulseScale;
         } else {
           particle.currentRadius = particle.radius;
@@ -807,7 +826,20 @@ var ParticleNetwork = class {
   }
   draw3DFluidSphere(particle) {
     const tc = particle.typeConfig;
-    const perTypeLg = tc && "liquidGlass" in tc && typeof tc.liquidGlass === "object" ? tc.liquidGlass : void 0;
+    let perTypeLg = tc && "liquidGlass" in tc && typeof tc.liquidGlass === "object" ? tc.liquidGlass : void 0;
+    if (particle.isChild && particle.childId) {
+      const childConfig = this.childParticleConfigs.get(particle.childId);
+      if (childConfig) {
+        const overrides = {
+          ...childConfig.liquidGlassConfig ?? {},
+          ...childConfig.glassOpacity != null && { opacity: childConfig.glassOpacity },
+          ...childConfig.glassColor != null && { color: childConfig.glassColor }
+        };
+        if (Object.keys(overrides).length > 0) {
+          perTypeLg = { ...perTypeLg ?? {}, ...overrides };
+        }
+      }
+    }
     const lg = perTypeLg ? { ...this.getLiquidGlassConfig(), ...perTypeLg } : this.getLiquidGlassConfig();
     const r = particle.currentRadius ?? particle.radius;
     if (r <= 0) return;
@@ -816,46 +848,60 @@ var ParticleNetwork = class {
     const cx = particle.x;
     const cy = particle.y;
     const isRect = particle.width != null && particle.height != null;
-    let opacity = (lg.opacity ?? DEFAULT_LIQUID_GLASS.opacity) * this.config.particleOpacity;
-    if (this.config.depthEffectEnabled) {
-      opacity *= 0.6 + 0.4 * particle.z;
+    const hasExplicitChildOpacity = particle.isChild && particle.childId && (() => {
+      const cfg = this.childParticleConfigs.get(particle.childId);
+      return cfg?.glassOpacity != null || cfg?.liquidGlassConfig?.opacity != null;
+    })();
+    let opacity = lg.opacity ?? DEFAULT_LIQUID_GLASS.opacity;
+    if (!hasExplicitChildOpacity) {
+      opacity *= this.config.particleOpacity;
+      if (this.config.depthEffectEnabled) {
+        opacity *= 0.6 + 0.4 * particle.z;
+      }
     }
     if (opacity <= 0) return;
-    blob.rotation += blob.rotSpeed;
+    const blobSpeed = lg.blobSpeed ?? 1;
+    blob.rotation += blob.rotSpeed * blobSpeed;
     for (let m = 0; m < blob.phases.length; m++) {
-      blob.phases[m] += blob.phaseSpeeds[m];
+      blob.phases[m] += blob.phaseSpeeds[m] * blobSpeed;
     }
-    blob.hlAngle += blob.hlAngleSpeed;
+    blob.hlAngle += blob.hlAngleSpeed * blobSpeed;
     this.updateBlobMouse(particle);
     const color = lg.color ?? DEFAULT_LIQUID_GLASS.color;
     const baseR = parseInt(color.slice(1, 3), 16);
     const baseG = parseInt(color.slice(3, 5), 16);
     const baseB = parseInt(color.slice(5, 7), 16);
     const shadowStr = lg.shadowStrength ?? DEFAULT_LIQUID_GLASS.shadowStrength;
+    const refl = (lg.reflectionStrength ?? DEFAULT_LIQUID_GLASS.reflectionStrength) / DEFAULT_LIQUID_GLASS.reflectionStrength;
     const gradR = isRect ? Math.max(particle.width, particle.height) / 2 : r;
     const hlDist = gradR * 0.35;
     const hlX = cx + Math.cos(blob.hlAngle) * hlDist;
     const hlY = cy + Math.sin(blob.hlAngle) * hlDist;
-    const lr = Math.min(255, baseR + Math.round((255 - baseR) * 0.55));
-    const lgr = Math.min(255, baseG + Math.round((255 - baseG) * 0.55));
-    const lb = Math.min(255, baseB + Math.round((255 - baseB) * 0.55));
+    const lr = Math.min(255, baseR + Math.round((255 - baseR) * 0.55 * refl));
+    const lgr = Math.min(255, baseG + Math.round((255 - baseG) * 0.55 * refl));
+    const lb = Math.min(255, baseB + Math.round((255 - baseB) * 0.55 * refl));
     const dr = Math.max(0, Math.round(baseR * (1 - shadowStr * 0.35)));
     const dg = Math.max(0, Math.round(baseG * (1 - shadowStr * 0.35)));
     const db = Math.max(0, Math.round(baseB * (1 - shadowStr * 0.35)));
     this.ctx.save();
-    const grad = this.ctx.createRadialGradient(
-      hlX,
-      hlY,
-      gradR * 0.05,
-      cx,
-      cy,
-      gradR * 1.05
-    );
-    grad.addColorStop(0, `rgba(${lr},${lgr},${lb}, ${opacity * 0.95})`);
-    grad.addColorStop(0.4, `rgba(${baseR},${baseG},${baseB}, ${opacity * 0.8})`);
-    grad.addColorStop(0.8, `rgba(${dr},${dg},${db}, ${opacity * 0.6})`);
-    grad.addColorStop(1, `rgba(${dr},${dg},${db}, ${opacity * 0.25})`);
-    this.ctx.fillStyle = grad;
+    this.ctx.globalAlpha = 1;
+    if (hasExplicitChildOpacity && opacity >= 0.99) {
+      this.ctx.fillStyle = `rgba(${baseR},${baseG},${baseB}, ${opacity})`;
+    } else {
+      const grad = this.ctx.createRadialGradient(
+        hlX,
+        hlY,
+        gradR * 0.05,
+        cx,
+        cy,
+        gradR * 1.05
+      );
+      grad.addColorStop(0, `rgba(${lr},${lgr},${lb}, ${opacity * 0.95})`);
+      grad.addColorStop(0.4, `rgba(${baseR},${baseG},${baseB}, ${opacity * 0.8})`);
+      grad.addColorStop(0.8, `rgba(${dr},${dg},${db}, ${opacity * 0.6})`);
+      grad.addColorStop(1, `rgba(${dr},${dg},${db}, ${opacity * 0.25})`);
+      this.ctx.fillStyle = grad;
+    }
     if (isRect) {
       const halfW = particle.width / 2;
       const halfH = particle.height / 2;

package/dist/index.d.mts

@@ -38,6 +38,8 @@ interface LiquidGlassConfig {
     minRadius?: number;
     /** Maximum radius (px) for liquid glass particles (overrides root maxRadius). */
     maxRadius?: number;
+    /** Blob deformation speed multiplier (default 1). 0 = frozen, 2 = double speed. */
+    blobSpeed?: number;
 }
 interface CircleTypeEntry {
     type: "circle";
@@ -94,6 +96,12 @@ interface ChildParticleConfig {
     mouseInfluence?: number;
     /** Render as liquid glass particle. Default false. */
     liquidGlass?: boolean;
+    /** Opacity (0–1) for liquid glass child particles. Overrides global liquidGlass.opacity. */
+    glassOpacity?: number;
+    /** Color (hex) for liquid glass child particles. Overrides global liquidGlass.color. */
+    glassColor?: string;
+    /** Full liquid glass config override for child particles. Merged over global liquidGlass. */
+    liquidGlassConfig?: Partial<LiquidGlassConfig>;
 }
 /** Emitted position data for a child particle each frame. */
 interface ChildParticlePosition {
@@ -208,6 +216,8 @@ interface Particle {
     overflow?: string;
     /** Per-type config entry (shallow overrides root config). */
     typeConfig?: ParticleTypeEntry;
+    /** Random phase offset (0–2π) for pulse animation. Makes particles pulse out of sync. */
+    pulsePhase?: number;
     /** Smoothed x for overlay positioning. */
     smoothX?: number;
     /** Smoothed y for overlay positioning. */

package/dist/index.d.ts

@@ -38,6 +38,8 @@ interface LiquidGlassConfig {
     minRadius?: number;
     /** Maximum radius (px) for liquid glass particles (overrides root maxRadius). */
     maxRadius?: number;
+    /** Blob deformation speed multiplier (default 1). 0 = frozen, 2 = double speed. */
+    blobSpeed?: number;
 }
 interface CircleTypeEntry {
     type: "circle";
@@ -94,6 +96,12 @@ interface ChildParticleConfig {
     mouseInfluence?: number;
     /** Render as liquid glass particle. Default false. */
     liquidGlass?: boolean;
+    /** Opacity (0–1) for liquid glass child particles. Overrides global liquidGlass.opacity. */
+    glassOpacity?: number;
+    /** Color (hex) for liquid glass child particles. Overrides global liquidGlass.color. */
+    glassColor?: string;
+    /** Full liquid glass config override for child particles. Merged over global liquidGlass. */
+    liquidGlassConfig?: Partial<LiquidGlassConfig>;
 }
 /** Emitted position data for a child particle each frame. */
 interface ChildParticlePosition {
@@ -208,6 +216,8 @@ interface Particle {
     overflow?: string;
     /** Per-type config entry (shallow overrides root config). */
     typeConfig?: ParticleTypeEntry;
+    /** Random phase offset (0–2π) for pulse animation. Makes particles pulse out of sync. */
+    pulsePhase?: number;
     /** Smoothed x for overlay positioning. */
     smoothX?: number;
     /** Smoothed y for overlay positioning. */

package/dist/index.js

@@ -67,6 +67,7 @@ var DEFAULT_LIQUID_GLASS = {
   shadowStrength: 0.4,
   secondaryReflection: 0.25,
   secondaryHighlightPosition: "bottom-right",
+  blobSpeed: 1,
   minRadius: 20,
   maxRadius: 40
 };
@@ -182,7 +183,7 @@ var ParticleNetwork = class {
       const h = isRect ? particle.height : (particle.currentRadius ?? particle.radius) * 2;
       el.style.width = w + "px";
       el.style.height = h + "px";
-      el.style.transform = `translate(${px - w / 2}px, ${py - h / 2}px)`;
+      el.style.transform = `translate3d(${Math.round(px - w / 2)}px, ${Math.round(py - h / 2)}px, 0)`;
       if (isRect) {
         const br = particle.borderRadius ?? Math.min(w, h) / 2;
         el.style.borderRadius = br + "px";
@@ -338,7 +339,14 @@ var ParticleNetwork = class {
       if (!Array.isArray(config.particleTypes)) {
         throw new Error("particleTypes must be an array");
       }
-      if (!config.assets || typeof config.assets !== "object") {
+      let hasAssetEntries = false;
+      for (const entry of config.particleTypes) {
+        if (entry?.type === "asset") {
+          hasAssetEntries = true;
+          break;
+        }
+      }
+      if (hasAssetEntries && (!config.assets || typeof config.assets !== "object")) {
         throw new Error("assets map is required when using particleTypes with asset entries");
       }
       for (let i = 0; i < config.particleTypes.length; i++) {
@@ -358,8 +366,9 @@ var ParticleNetwork = class {
           if (typeof pt.asset !== "string" || !pt.asset) {
             throw new Error(`particleTypes[${i}].asset must be a non-empty string`);
           }
-          if (!config.assets[pt.asset]) {
-            throw new Error(`particleTypes[${i}]: asset "${pt.asset}" not found in assets`);
+          const assetKey = pt.asset;
+          if (!config.assets?.[assetKey]) {
+            throw new Error(`particleTypes[${i}]: asset "${assetKey}" not found in assets`);
           }
         }
       }
@@ -457,6 +466,7 @@ var ParticleNetwork = class {
       delete p.assetId;
       delete p.liquidGlass;
       delete p.typeConfig;
+      delete p.pulsePhase;
     });
     if (particleTypes?.length) {
       const counts = [];
@@ -525,6 +535,14 @@ var ParticleNetwork = class {
     if (!particleTypes?.length && (this.config.liquidGlassPercentage != null || this.config.liquidGlassCount != null)) {
       this.assignLiquidGlass();
     }
+    this.particles.forEach((p) => {
+      if (p.isChild) return;
+      const tc = p.typeConfig;
+      const doPulse = tc?.pulse ?? this.config.pulseEnabled;
+      if (doPulse) {
+        p.pulsePhase = Math.random() * Math.PI * 2;
+      }
+    });
     this.assignMouseBehavior();
   }
   assignLiquidGlass() {
@@ -630,7 +648,8 @@ var ParticleNetwork = class {
         if (doPulse) {
           const speed = tc?.pulseSpeed ?? this.config.pulseSpeed;
           this.pulseAngle += speed;
-          const pulseScale = Math.sin(this.pulseAngle) * 0.5 + 1;
+          const phase = particle.pulsePhase ?? 0;
+          const pulseScale = Math.sin(this.pulseAngle + phase) * 0.5 + 1;
           particle.currentRadius = particle.radius * pulseScale;
         } else {
           particle.currentRadius = particle.radius;
@@ -831,7 +850,20 @@ var ParticleNetwork = class {
   }
   draw3DFluidSphere(particle) {
     const tc = particle.typeConfig;
-    const perTypeLg = tc && "liquidGlass" in tc && typeof tc.liquidGlass === "object" ? tc.liquidGlass : void 0;
+    let perTypeLg = tc && "liquidGlass" in tc && typeof tc.liquidGlass === "object" ? tc.liquidGlass : void 0;
+    if (particle.isChild && particle.childId) {
+      const childConfig = this.childParticleConfigs.get(particle.childId);
+      if (childConfig) {
+        const overrides = {
+          ...childConfig.liquidGlassConfig ?? {},
+          ...childConfig.glassOpacity != null && { opacity: childConfig.glassOpacity },
+          ...childConfig.glassColor != null && { color: childConfig.glassColor }
+        };
+        if (Object.keys(overrides).length > 0) {
+          perTypeLg = { ...perTypeLg ?? {}, ...overrides };
+        }
+      }
+    }
     const lg = perTypeLg ? { ...this.getLiquidGlassConfig(), ...perTypeLg } : this.getLiquidGlassConfig();
     const r = particle.currentRadius ?? particle.radius;
     if (r <= 0) return;
@@ -840,46 +872,60 @@ var ParticleNetwork = class {
     const cx = particle.x;
     const cy = particle.y;
     const isRect = particle.width != null && particle.height != null;
-    let opacity = (lg.opacity ?? DEFAULT_LIQUID_GLASS.opacity) * this.config.particleOpacity;
-    if (this.config.depthEffectEnabled) {
-      opacity *= 0.6 + 0.4 * particle.z;
+    const hasExplicitChildOpacity = particle.isChild && particle.childId && (() => {
+      const cfg = this.childParticleConfigs.get(particle.childId);
+      return cfg?.glassOpacity != null || cfg?.liquidGlassConfig?.opacity != null;
+    })();
+    let opacity = lg.opacity ?? DEFAULT_LIQUID_GLASS.opacity;
+    if (!hasExplicitChildOpacity) {
+      opacity *= this.config.particleOpacity;
+      if (this.config.depthEffectEnabled) {
+        opacity *= 0.6 + 0.4 * particle.z;
+      }
     }
     if (opacity <= 0) return;
-    blob.rotation += blob.rotSpeed;
+    const blobSpeed = lg.blobSpeed ?? 1;
+    blob.rotation += blob.rotSpeed * blobSpeed;
     for (let m = 0; m < blob.phases.length; m++) {
-      blob.phases[m] += blob.phaseSpeeds[m];
+      blob.phases[m] += blob.phaseSpeeds[m] * blobSpeed;
     }
-    blob.hlAngle += blob.hlAngleSpeed;
+    blob.hlAngle += blob.hlAngleSpeed * blobSpeed;
     this.updateBlobMouse(particle);
     const color = lg.color ?? DEFAULT_LIQUID_GLASS.color;
     const baseR = parseInt(color.slice(1, 3), 16);
     const baseG = parseInt(color.slice(3, 5), 16);
     const baseB = parseInt(color.slice(5, 7), 16);
     const shadowStr = lg.shadowStrength ?? DEFAULT_LIQUID_GLASS.shadowStrength;
+    const refl = (lg.reflectionStrength ?? DEFAULT_LIQUID_GLASS.reflectionStrength) / DEFAULT_LIQUID_GLASS.reflectionStrength;
     const gradR = isRect ? Math.max(particle.width, particle.height) / 2 : r;
     const hlDist = gradR * 0.35;
     const hlX = cx + Math.cos(blob.hlAngle) * hlDist;
     const hlY = cy + Math.sin(blob.hlAngle) * hlDist;
-    const lr = Math.min(255, baseR + Math.round((255 - baseR) * 0.55));
-    const lgr = Math.min(255, baseG + Math.round((255 - baseG) * 0.55));
-    const lb = Math.min(255, baseB + Math.round((255 - baseB) * 0.55));
+    const lr = Math.min(255, baseR + Math.round((255 - baseR) * 0.55 * refl));
+    const lgr = Math.min(255, baseG + Math.round((255 - baseG) * 0.55 * refl));
+    const lb = Math.min(255, baseB + Math.round((255 - baseB) * 0.55 * refl));
     const dr = Math.max(0, Math.round(baseR * (1 - shadowStr * 0.35)));
     const dg = Math.max(0, Math.round(baseG * (1 - shadowStr * 0.35)));
     const db = Math.max(0, Math.round(baseB * (1 - shadowStr * 0.35)));
     this.ctx.save();
-    const grad = this.ctx.createRadialGradient(
-      hlX,
-      hlY,
-      gradR * 0.05,
-      cx,
-      cy,
-      gradR * 1.05
-    );
-    grad.addColorStop(0, `rgba(${lr},${lgr},${lb}, ${opacity * 0.95})`);
-    grad.addColorStop(0.4, `rgba(${baseR},${baseG},${baseB}, ${opacity * 0.8})`);
-    grad.addColorStop(0.8, `rgba(${dr},${dg},${db}, ${opacity * 0.6})`);
-    grad.addColorStop(1, `rgba(${dr},${dg},${db}, ${opacity * 0.25})`);
-    this.ctx.fillStyle = grad;
+    this.ctx.globalAlpha = 1;
+    if (hasExplicitChildOpacity && opacity >= 0.99) {
+      this.ctx.fillStyle = `rgba(${baseR},${baseG},${baseB}, ${opacity})`;
+    } else {
+      const grad = this.ctx.createRadialGradient(
+        hlX,
+        hlY,
+        gradR * 0.05,
+        cx,
+        cy,
+        gradR * 1.05
+      );
+      grad.addColorStop(0, `rgba(${lr},${lgr},${lb}, ${opacity * 0.95})`);
+      grad.addColorStop(0.4, `rgba(${baseR},${baseG},${baseB}, ${opacity * 0.8})`);
+      grad.addColorStop(0.8, `rgba(${dr},${dg},${db}, ${opacity * 0.6})`);
+      grad.addColorStop(1, `rgba(${dr},${dg},${db}, ${opacity * 0.25})`);
+      this.ctx.fillStyle = grad;
+    }
     if (isRect) {
       const halfW = particle.width / 2;
       const halfH = particle.height / 2;

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import {
   ParticleNetwork
-} from "./chunk-BMXQY2SK.mjs";
+} from "./chunk-JZTYQ6XI.mjs";
 export {
   ParticleNetwork
 };

package/dist/react.d.mts

@@ -1,7 +1,9 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
 import { ReactNode, CSSProperties, RefObject } from 'react';
-import { ParticleNetworkConfig } from './index.mjs';
+import { LiquidGlassConfig, ParticleNetworkConfig, ParticleNetwork } from './index.mjs';
 
+declare const ParticleNetworkContext: react.Context<ParticleNetwork | null>;
 declare function useParticleNetwork(config?: Partial<ParticleNetworkConfig>): RefObject<HTMLCanvasElement | null>;
 interface ParticleNetworkBgProps {
     config?: Partial<ParticleNetworkConfig>;
@@ -27,6 +29,12 @@ interface ChildParticleProps {
     anchorForce?: number;
     /** Mouse influence multiplier (0-1). Default 0.1. */
     mouseInfluence?: number;
+    /** Opacity (0-1) for liquid glass. Only applies when liquidGlass is true. */
+    glassOpacity?: number;
+    /** Color (hex) for liquid glass. Only applies when liquidGlass is true. */
+    glassColor?: string;
+    /** Full liquid glass config override. Merged over global liquidGlass. */
+    liquidGlassConfig?: Partial<LiquidGlassConfig>;
     children?: ReactNode;
     style?: CSSProperties;
     className?: string;
@@ -49,10 +57,16 @@ interface GlassChildParticleProps {
     anchorForce?: number;
     /** Mouse influence multiplier (0-1). Default 0.1. */
     mouseInfluence?: number;
+    /** Opacity (0-1) for the glass background. Default uses global liquidGlass.opacity. */
+    glassOpacity?: number;
+    /** Color (hex) for the glass background. Default uses global liquidGlass.color. */
+    glassColor?: string;
+    /** Full liquid glass config override. Merged over global liquidGlass. */
+    liquidGlassConfig?: Partial<LiquidGlassConfig>;
     children?: ReactNode;
     style?: CSSProperties;
     className?: string;
 }
 declare function GlassChildParticle(props: GlassChildParticleProps): react_jsx_runtime.JSX.Element;
 
-export { ChildParticle, type ChildParticleProps, GlassChildParticle, type GlassChildParticleProps, ParticleNetworkBg, type ParticleNetworkBgProps, useParticleNetwork };
+export { ChildParticle, type ChildParticleProps, GlassChildParticle, type GlassChildParticleProps, ParticleNetworkBg, type ParticleNetworkBgProps, ParticleNetworkContext, useParticleNetwork };

package/dist/react.d.ts

@@ -1,7 +1,9 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
 import { ReactNode, CSSProperties, RefObject } from 'react';
-import { ParticleNetworkConfig } from './index.js';
+import { LiquidGlassConfig, ParticleNetworkConfig, ParticleNetwork } from './index.js';
 
+declare const ParticleNetworkContext: react.Context<ParticleNetwork | null>;
 declare function useParticleNetwork(config?: Partial<ParticleNetworkConfig>): RefObject<HTMLCanvasElement | null>;
 interface ParticleNetworkBgProps {
     config?: Partial<ParticleNetworkConfig>;
@@ -27,6 +29,12 @@ interface ChildParticleProps {
     anchorForce?: number;
     /** Mouse influence multiplier (0-1). Default 0.1. */
     mouseInfluence?: number;
+    /** Opacity (0-1) for liquid glass. Only applies when liquidGlass is true. */
+    glassOpacity?: number;
+    /** Color (hex) for liquid glass. Only applies when liquidGlass is true. */
+    glassColor?: string;
+    /** Full liquid glass config override. Merged over global liquidGlass. */
+    liquidGlassConfig?: Partial<LiquidGlassConfig>;
     children?: ReactNode;
     style?: CSSProperties;
     className?: string;
@@ -49,10 +57,16 @@ interface GlassChildParticleProps {
     anchorForce?: number;
     /** Mouse influence multiplier (0-1). Default 0.1. */
     mouseInfluence?: number;
+    /** Opacity (0-1) for the glass background. Default uses global liquidGlass.opacity. */
+    glassOpacity?: number;
+    /** Color (hex) for the glass background. Default uses global liquidGlass.color. */
+    glassColor?: string;
+    /** Full liquid glass config override. Merged over global liquidGlass. */
+    liquidGlassConfig?: Partial<LiquidGlassConfig>;
     children?: ReactNode;
     style?: CSSProperties;
     className?: string;
 }
 declare function GlassChildParticle(props: GlassChildParticleProps): react_jsx_runtime.JSX.Element;
 
-export { ChildParticle, type ChildParticleProps, GlassChildParticle, type GlassChildParticleProps, ParticleNetworkBg, type ParticleNetworkBgProps, useParticleNetwork };
+export { ChildParticle, type ChildParticleProps, GlassChildParticle, type GlassChildParticleProps, ParticleNetworkBg, type ParticleNetworkBgProps, ParticleNetworkContext, useParticleNetwork };

package/dist/react.js

@@ -23,6 +23,7 @@ __export(react_exports, {
   ChildParticle: () => ChildParticle,
   GlassChildParticle: () => GlassChildParticle,
   ParticleNetworkBg: () => ParticleNetworkBg,
+  ParticleNetworkContext: () => ParticleNetworkContext,
   useParticleNetwork: () => useParticleNetwork
 });
 module.exports = __toCommonJS(react_exports);
@@ -74,6 +75,7 @@ var DEFAULT_LIQUID_GLASS = {
   shadowStrength: 0.4,
   secondaryReflection: 0.25,
   secondaryHighlightPosition: "bottom-right",
+  blobSpeed: 1,
   minRadius: 20,
   maxRadius: 40
 };
@@ -189,7 +191,7 @@ var ParticleNetwork = class {
       const h = isRect ? particle.height : (particle.currentRadius ?? particle.radius) * 2;
       el.style.width = w + "px";
       el.style.height = h + "px";
-      el.style.transform = `translate(${px - w / 2}px, ${py - h / 2}px)`;
+      el.style.transform = `translate3d(${Math.round(px - w / 2)}px, ${Math.round(py - h / 2)}px, 0)`;
       if (isRect) {
         const br = particle.borderRadius ?? Math.min(w, h) / 2;
         el.style.borderRadius = br + "px";
@@ -345,7 +347,14 @@ var ParticleNetwork = class {
       if (!Array.isArray(config.particleTypes)) {
         throw new Error("particleTypes must be an array");
       }
-      if (!config.assets || typeof config.assets !== "object") {
+      let hasAssetEntries = false;
+      for (const entry of config.particleTypes) {
+        if (entry?.type === "asset") {
+          hasAssetEntries = true;
+          break;
+        }
+      }
+      if (hasAssetEntries && (!config.assets || typeof config.assets !== "object")) {
         throw new Error("assets map is required when using particleTypes with asset entries");
       }
       for (let i = 0; i < config.particleTypes.length; i++) {
@@ -365,8 +374,9 @@ var ParticleNetwork = class {
           if (typeof pt.asset !== "string" || !pt.asset) {
             throw new Error(`particleTypes[${i}].asset must be a non-empty string`);
           }
-          if (!config.assets[pt.asset]) {
-            throw new Error(`particleTypes[${i}]: asset "${pt.asset}" not found in assets`);
+          const assetKey = pt.asset;
+          if (!config.assets?.[assetKey]) {
+            throw new Error(`particleTypes[${i}]: asset "${assetKey}" not found in assets`);
           }
         }
       }
@@ -464,6 +474,7 @@ var ParticleNetwork = class {
       delete p.assetId;
       delete p.liquidGlass;
       delete p.typeConfig;
+      delete p.pulsePhase;
     });
     if (particleTypes?.length) {
       const counts = [];
@@ -532,6 +543,14 @@ var ParticleNetwork = class {
     if (!particleTypes?.length && (this.config.liquidGlassPercentage != null || this.config.liquidGlassCount != null)) {
       this.assignLiquidGlass();
     }
+    this.particles.forEach((p) => {
+      if (p.isChild) return;
+      const tc = p.typeConfig;
+      const doPulse = tc?.pulse ?? this.config.pulseEnabled;
+      if (doPulse) {
+        p.pulsePhase = Math.random() * Math.PI * 2;
+      }
+    });
     this.assignMouseBehavior();
   }
   assignLiquidGlass() {
@@ -637,7 +656,8 @@ var ParticleNetwork = class {
         if (doPulse) {
           const speed = tc?.pulseSpeed ?? this.config.pulseSpeed;
           this.pulseAngle += speed;
-          const pulseScale = Math.sin(this.pulseAngle) * 0.5 + 1;
+          const phase = particle.pulsePhase ?? 0;
+          const pulseScale = Math.sin(this.pulseAngle + phase) * 0.5 + 1;
           particle.currentRadius = particle.radius * pulseScale;
         } else {
           particle.currentRadius = particle.radius;
@@ -838,7 +858,20 @@ var ParticleNetwork = class {
   }
   draw3DFluidSphere(particle) {
     const tc = particle.typeConfig;
-    const perTypeLg = tc && "liquidGlass" in tc && typeof tc.liquidGlass === "object" ? tc.liquidGlass : void 0;
+    let perTypeLg = tc && "liquidGlass" in tc && typeof tc.liquidGlass === "object" ? tc.liquidGlass : void 0;
+    if (particle.isChild && particle.childId) {
+      const childConfig = this.childParticleConfigs.get(particle.childId);
+      if (childConfig) {
+        const overrides = {
+          ...childConfig.liquidGlassConfig ?? {},
+          ...childConfig.glassOpacity != null && { opacity: childConfig.glassOpacity },
+          ...childConfig.glassColor != null && { color: childConfig.glassColor }
+        };
+        if (Object.keys(overrides).length > 0) {
+          perTypeLg = { ...perTypeLg ?? {}, ...overrides };
+        }
+      }
+    }
     const lg = perTypeLg ? { ...this.getLiquidGlassConfig(), ...perTypeLg } : this.getLiquidGlassConfig();
     const r = particle.currentRadius ?? particle.radius;
     if (r <= 0) return;
@@ -847,46 +880,60 @@ var ParticleNetwork = class {
     const cx = particle.x;
     const cy = particle.y;
     const isRect = particle.width != null && particle.height != null;
-    let opacity = (lg.opacity ?? DEFAULT_LIQUID_GLASS.opacity) * this.config.particleOpacity;
-    if (this.config.depthEffectEnabled) {
-      opacity *= 0.6 + 0.4 * particle.z;
+    const hasExplicitChildOpacity = particle.isChild && particle.childId && (() => {
+      const cfg = this.childParticleConfigs.get(particle.childId);
+      return cfg?.glassOpacity != null || cfg?.liquidGlassConfig?.opacity != null;
+    })();
+    let opacity = lg.opacity ?? DEFAULT_LIQUID_GLASS.opacity;
+    if (!hasExplicitChildOpacity) {
+      opacity *= this.config.particleOpacity;
+      if (this.config.depthEffectEnabled) {
+        opacity *= 0.6 + 0.4 * particle.z;
+      }
     }
     if (opacity <= 0) return;
-    blob.rotation += blob.rotSpeed;
+    const blobSpeed = lg.blobSpeed ?? 1;
+    blob.rotation += blob.rotSpeed * blobSpeed;
     for (let m = 0; m < blob.phases.length; m++) {
-      blob.phases[m] += blob.phaseSpeeds[m];
+      blob.phases[m] += blob.phaseSpeeds[m] * blobSpeed;
     }
-    blob.hlAngle += blob.hlAngleSpeed;
+    blob.hlAngle += blob.hlAngleSpeed * blobSpeed;
     this.updateBlobMouse(particle);
     const color = lg.color ?? DEFAULT_LIQUID_GLASS.color;
     const baseR = parseInt(color.slice(1, 3), 16);
     const baseG = parseInt(color.slice(3, 5), 16);
     const baseB = parseInt(color.slice(5, 7), 16);
     const shadowStr = lg.shadowStrength ?? DEFAULT_LIQUID_GLASS.shadowStrength;
+    const refl = (lg.reflectionStrength ?? DEFAULT_LIQUID_GLASS.reflectionStrength) / DEFAULT_LIQUID_GLASS.reflectionStrength;
     const gradR = isRect ? Math.max(particle.width, particle.height) / 2 : r;
     const hlDist = gradR * 0.35;
     const hlX = cx + Math.cos(blob.hlAngle) * hlDist;
     const hlY = cy + Math.sin(blob.hlAngle) * hlDist;
-    const lr = Math.min(255, baseR + Math.round((255 - baseR) * 0.55));
-    const lgr = Math.min(255, baseG + Math.round((255 - baseG) * 0.55));
-    const lb = Math.min(255, baseB + Math.round((255 - baseB) * 0.55));
+    const lr = Math.min(255, baseR + Math.round((255 - baseR) * 0.55 * refl));
+    const lgr = Math.min(255, baseG + Math.round((255 - baseG) * 0.55 * refl));
+    const lb = Math.min(255, baseB + Math.round((255 - baseB) * 0.55 * refl));
     const dr = Math.max(0, Math.round(baseR * (1 - shadowStr * 0.35)));
     const dg = Math.max(0, Math.round(baseG * (1 - shadowStr * 0.35)));
     const db = Math.max(0, Math.round(baseB * (1 - shadowStr * 0.35)));
     this.ctx.save();
-    const grad = this.ctx.createRadialGradient(
-      hlX,
-      hlY,
-      gradR * 0.05,
-      cx,
-      cy,
-      gradR * 1.05
-    );
-    grad.addColorStop(0, `rgba(${lr},${lgr},${lb}, ${opacity * 0.95})`);
-    grad.addColorStop(0.4, `rgba(${baseR},${baseG},${baseB}, ${opacity * 0.8})`);
-    grad.addColorStop(0.8, `rgba(${dr},${dg},${db}, ${opacity * 0.6})`);
-    grad.addColorStop(1, `rgba(${dr},${dg},${db}, ${opacity * 0.25})`);
-    this.ctx.fillStyle = grad;
+    this.ctx.globalAlpha = 1;
+    if (hasExplicitChildOpacity && opacity >= 0.99) {
+      this.ctx.fillStyle = `rgba(${baseR},${baseG},${baseB}, ${opacity})`;
+    } else {
+      const grad = this.ctx.createRadialGradient(
+        hlX,
+        hlY,
+        gradR * 0.05,
+        cx,
+        cy,
+        gradR * 1.05
+      );
+      grad.addColorStop(0, `rgba(${lr},${lgr},${lb}, ${opacity * 0.95})`);
+      grad.addColorStop(0.4, `rgba(${baseR},${baseG},${baseB}, ${opacity * 0.8})`);
+      grad.addColorStop(0.8, `rgba(${dr},${dg},${db}, ${opacity * 0.6})`);
+      grad.addColorStop(1, `rgba(${dr},${dg},${db}, ${opacity * 0.25})`);
+      this.ctx.fillStyle = grad;
+    }
     if (isRect) {
       const halfW = particle.width / 2;
       const halfH = particle.height / 2;
@@ -1308,6 +1355,9 @@ function BaseChildParticle({
   anchorForce,
   mouseInfluence,
   liquidGlass,
+  glassOpacity,
+  glassColor,
+  liquidGlassConfig,
   children,
   style,
   className
@@ -1327,7 +1377,10 @@ function BaseChildParticle({
       overflow,
       anchorForce,
       mouseInfluence,
-      liquidGlass
+      liquidGlass,
+      glassOpacity,
+      glassColor,
+      liquidGlassConfig
     });
     setOverlayEl(instance.getChildOverlayElement(id));
     return () => {
@@ -1347,9 +1400,12 @@ function BaseChildParticle({
       overflow,
       anchorForce,
       mouseInfluence,
-      liquidGlass
+      liquidGlass,
+      glassOpacity,
+      glassColor,
+      liquidGlassConfig
     });
-  }, [instance, id, x, y, radius, width, height, borderRadius, overflow, anchorForce, mouseInfluence, liquidGlass]);
+  }, [instance, id, x, y, radius, width, height, borderRadius, overflow, anchorForce, mouseInfluence, liquidGlass, glassOpacity, glassColor, liquidGlassConfig]);
   if (!overlayEl) return null;
   const isRect = width != null && height != null;
   const portalBorderRadius = isRect ? (borderRadius ?? Math.min(width, height) / 2) + "px" : "50%";
@@ -1379,5 +1435,6 @@ function BaseChildParticle({
   ChildParticle,
   GlassChildParticle,
   ParticleNetworkBg,
+  ParticleNetworkContext,
   useParticleNetwork
 });

package/dist/react.mjs

@@ -1,6 +1,6 @@
 import {
   ParticleNetwork
-} from "./chunk-BMXQY2SK.mjs";
+} from "./chunk-JZTYQ6XI.mjs";
 
 // src/react.tsx
 import {
@@ -78,6 +78,9 @@ function BaseChildParticle({
   anchorForce,
   mouseInfluence,
   liquidGlass,
+  glassOpacity,
+  glassColor,
+  liquidGlassConfig,
   children,
   style,
   className
@@ -97,7 +100,10 @@ function BaseChildParticle({
       overflow,
       anchorForce,
       mouseInfluence,
-      liquidGlass
+      liquidGlass,
+      glassOpacity,
+      glassColor,
+      liquidGlassConfig
     });
     setOverlayEl(instance.getChildOverlayElement(id));
     return () => {
@@ -117,9 +123,12 @@ function BaseChildParticle({
       overflow,
       anchorForce,
       mouseInfluence,
-      liquidGlass
+      liquidGlass,
+      glassOpacity,
+      glassColor,
+      liquidGlassConfig
     });
-  }, [instance, id, x, y, radius, width, height, borderRadius, overflow, anchorForce, mouseInfluence, liquidGlass]);
+  }, [instance, id, x, y, radius, width, height, borderRadius, overflow, anchorForce, mouseInfluence, liquidGlass, glassOpacity, glassColor, liquidGlassConfig]);
   if (!overlayEl) return null;
   const isRect = width != null && height != null;
   const portalBorderRadius = isRect ? (borderRadius ?? Math.min(width, height) / 2) + "px" : "50%";
@@ -148,5 +157,6 @@ export {
   ChildParticle,
   GlassChildParticle,
   ParticleNetworkBg,
+  ParticleNetworkContext,
   useParticleNetwork
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "particle-network-bg",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Interactive particle network animation for backgrounds",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",