@mar7th/firework 1.0.0

package/docs/performance-optimization-plan.md

@@ -0,0 +1,396 @@
+# SparkFireworks 性能优化方案
+
+## 背景
+
+当前项目在粒子数量较多、开启拖尾、辉光、复杂形状或自动连续发射时容易掉帧。主要原因不是单个算法复杂，而是多个高频开销叠加：
+
+- 粒子生成时线性扫描粒子池。
+- 每帧更新和绘制都会遍历整个粒子池。
+- 轨迹每帧创建对象并使用 `shift()` 移除旧点，容易触发 GC。
+- 每个粒子绘制都执行 `save/restore`、颜色混合、CSS 字符串拼接、阴影、路径绘制。
+- `shadowBlur`、`globalCompositeOperation = "lighter"`、星形/心形路径在 Canvas 2D 中成本较高。
+- 低 FPS 自适应只降低未来爆炸粒子数，不能快速缓解已经存在的绘制压力。
+
+目标是在保持现有效果和 API 基本兼容的前提下，让高粒子数场景更稳定，并为后续 WebGL/Worker 改造留出结构空间。
+
+## 优化目标
+
+- 默认配置保持 60 FPS 附近。
+- 1000-1400 活跃粒子时减少明显卡顿和 GC 抖动。
+- 低端设备或高 DPI 屏幕下能自动降级效果。
+- 不破坏 `FireworksSimulator`、`SparkFireworks.create()`、高级脚本粒子格式等公开 API。
+- 优化应可分阶段落地，每阶段都能独立验证。
+
+## 当前热点定位
+
+### 粒子池
+
+文件：`src/core/ParticleSystem.js`
+
+现状：
+
+- `spawn()` 使用 `this.pool.find((item) => !item.active)`，每创建一个粒子都可能扫描整个池。
+- `update()` 和 `draw()` 遍历完整 `pool`，即使大部分粒子不活跃也会被检查。
+- `addExplosion()` 批量生成粒子时，上述扫描会被放大。
+
+风险：
+
+- 一次 1000 粒子的爆炸接近 O(n * poolSize)。
+- 多次爆炸叠加时，主线程会在粒子生成阶段产生明显尖峰。
+
+### 粒子更新
+
+文件：`src/core/Particle.js`
+
+现状：
+
+- 每粒子每帧调用 `Math.pow(runtimeConfig.damping, step)`。
+- 开启拖尾时每帧 `this.trail.push({ x, y, life })`，长度超过 8 后 `shift()`。
+- 粒子 `reset()` 中直接替换 `this.trail = []`，复用粒子对象时仍会持续制造新数组和轨迹点对象。
+
+风险：
+
+- 大量短生命周期对象造成 GC 抖动。
+- `shift()` 会移动数组元素，粒子多时成本明显。
+
+### 粒子绘制
+
+文件：`src/core/Particle.js`
+
+现状：
+
+- 每粒子每帧执行 `mixColor()`、`rgbToCss()`，产生新颜色对象或字符串。
+- 每粒子绘制都 `ctx.save()` / `ctx.restore()`。
+- 每粒子都设置 `shadowColor` 和 `shadowBlur`。
+- 圆形使用 `arc()`，星形和心形每次都重新构建路径。
+- 拖尾每段线单独 `beginPath()`、`stroke()`，并为每段生成颜色字符串。
+
+风险：
+
+- Canvas 2D 绘制调用过多，主线程容易被 draw call 和状态切换占满。
+- `shadowBlur` 在高粒子数下非常昂贵。
+- 复杂形状和旋转进一步放大路径计算成本。
+
+### 渲染器和像素比
+
+文件：`src/core/Renderer.js`
+
+现状：
+
+- `pixelRatio` 固定取 `Math.min(devicePixelRatio, 2)`。
+- 高 DPI 屏幕上绘制像素数可能是 CSS 面积的 4 倍。
+- 低 FPS 时不会动态降低像素比。
+
+风险：
+
+- 同样粒子数在高 DPI 屏上会更卡。
+- 自适应策略无法处理填充率瓶颈。
+
+### 低 FPS 自适应
+
+文件：`src/core/FireworksSimulator.js`
+
+现状：
+
+- 低 FPS 持续后只将 `config.particleCount` 乘以 0.72。
+- 已经活跃的粒子不会被裁剪或缩短寿命。
+- 不会降低辉光、拖尾、闪烁、复杂形状或像素比。
+
+风险：
+
+- 自适应生效慢。
+- 卡顿来自绘制时，仅降低未来粒子数不够。
+- 低帧时不能直接大步推进物理状态，否则粒子位置会突然跨越；应将大时间片拆成多个小步更新。
+- 连续点击时升空壳队列过长会让爆炸延后；高负载下需要允许直接在目标点爆炸。
+
+## 分阶段实施计划
+
+### 阶段 1：低风险结构优化
+
+目标：减少无效遍历和生成尖峰，不改变视觉效果。
+
+任务：
+
+1. 将 `ParticleSystem` 从完整池遍历改为 `activeParticles` + `freeParticles`。
+2. `spawn()` 从 `freeParticles.pop()` 取粒子，失败时直接丢弃。
+3. `update()` 只遍历活跃数组；粒子死亡后用 swap-remove 移除。
+4. `draw()` 只绘制活跃数组。
+5. `clear()` 将活跃粒子归还空闲栈。
+
+建议结构：
+
+```js
+class ParticleSystem {
+  constructor(factory, maxParticles) {
+    this.pool = Array.from({ length: maxParticles }, () => new Particle());
+    this.freeParticles = [...this.pool];
+    this.activeParticles = [];
+    this.activeCount = 0;
+  }
+}
+```
+
+验收：
+
+- 同样配置下视觉表现基本一致。
+- 连续点击发射时生成阶段不再明显卡一下。
+- `activeCount` 与实际活跃数组长度一致。
+- `npm run build` 通过。
+
+### 阶段 2：轨迹内存优化
+
+目标：消除拖尾造成的大量对象分配和数组移动。
+
+任务：
+
+1. 在 `Particle` 构造或初始化时创建固定长度轨迹数组。
+2. 使用环形索引写入轨迹点，不再 `push()` 对象和 `shift()`。
+3. `reset()` 只重置轨迹长度和写入索引。
+4. `drawTrail()` 按时间顺序读取环形缓冲。
+
+建议数据结构：
+
+```js
+this.trailX = new Float32Array(8);
+this.trailY = new Float32Array(8);
+this.trailLength = 0;
+this.trailCursor = 0;
+```
+
+验收：
+
+- 开启拖尾时视觉表现接近原效果。
+- Performance 面板中 GC 频率下降。
+- 高粒子数拖尾场景帧时间更平稳。
+
+### 阶段 3：绘制路径和颜色缓存
+
+目标：减少每粒子每帧的 Canvas 状态切换、路径构建和字符串创建。
+
+任务：
+
+1. 在 `Particle.reset()` 时将 `startColor`、`endColor` 解析为 RGB 数字字段。
+2. 将颜色变化量按有限档位量化，例如 32 或 64 档。
+3. 缓存 `rgba(r,g,b,a)` 字符串，避免每粒子每帧重复拼接。
+4. 圆形、方形、星形、心形改为离屏 sprite 缓存。
+5. 主画布绘制时优先使用 `drawImage()`，仅在缺少缓存时回退路径绘制。
+
+建议新增模块：
+
+- `src/core/ParticleSpriteCache.js`
+- `src/core/ColorRampCache.js`
+
+缓存 key 示例：
+
+```text
+textureType:sizeBucket:colorBucket:alphaBucket:glowBucket
+```
+
+注意：
+
+- 先对 `circle` 和 `square` 做 sprite 缓存，收益最大且风险最低。
+- `star` 和 `heart` 可以第二步接入。
+- 如果旋转只影响复杂形状，可在高粒子数时关闭或降低旋转更新频率。
+
+验收：
+
+- 默认圆形粒子下 draw call 仍多，但路径构建和阴影开销下降。
+- 星形/心形效果保持可接受。
+- sprite 缓存大小可控，不随时间无限增长。
+
+### 阶段 4：高负载自适应降级
+
+目标：在卡顿发生前主动降低昂贵效果。
+
+任务：
+
+1. 根据 `activeCount` 和 FPS 计算性能等级。
+2. 性能等级影响运行时绘制参数，不直接覆盖用户配置。
+3. 高负载时分级降低：
+   - `shadowBlur`
+   - `glowIntensity`
+   - `flicker`
+   - 粒子拖尾段数
+   - 复杂形状旋转
+   - `pixelRatio`
+4. 低 FPS 持续时缩短部分活跃粒子的剩余寿命，快速降低压力。
+
+建议等级：
+
+```text
+level 0: 正常
+level 1: activeCount > 600，降低 shadowBlur 和拖尾段数
+level 2: activeCount > 900 或 FPS < 45，关闭单粒子 shadowBlur，保留 lighter
+level 3: FPS < 35，pixelRatio 降到 1，关闭 flicker，缩短剩余寿命
+```
+
+建议新增运行时状态：
+
+```js
+this.performanceLevel = 0;
+this.renderQuality = {
+  pixelRatio: 1,
+  glowScale: 1,
+  trailSampleStep: 1,
+  useParticleShadow: true,
+  useFlicker: true
+};
+```
+
+验收：
+
+- 高负载时画面会略降级，但不会持续严重卡顿。
+- 用户配置值不被静默改写，控制面板显示仍保持用户选择。
+- 低 FPS 事件仍能正常触发。
+
+### 阶段 5：像素比和画布填充率优化
+
+目标：降低高 DPI 屏幕和大画布上的像素填充压力。
+
+任务：
+
+1. `Renderer.resize()` 支持传入目标像素比。
+2. 根据性能等级动态调整 `pixelRatio`。注意：运行中直接 resize canvas 会清空 backing store，容易造成爆炸瞬间闪屏；该项需要延迟到无活跃粒子时执行，或使用双缓冲方案。
+3. 避免每次 `setConfig()` 都强制完整背景重绘，只有背景相关配置变化时才重绘。
+4. 对静态背景使用离屏缓存，拖尾模式下只覆盖半透明黑色。
+
+验收：
+
+- Retina 屏上低负载仍清晰，高负载时能自动降像素比。
+- 调整非背景参数不会触发不必要的完整背景重绘。
+
+### 阶段 6：长期方向
+
+如果后续需要更高粒子上限，可以考虑更大的结构改造：
+
+1. WebGL 或 WebGPU 粒子渲染
+   - 使用点精灵或实例化绘制。
+   - 粒子位置、速度、寿命进入 typed array。
+   - 适合 5000+ 粒子规模。
+
+2. Worker 更新粒子状态
+   - 主线程只负责渲染和输入。
+   - 粒子位置通过 transferable typed array 或双缓冲同步。
+   - 需要权衡同步成本，建议在 Canvas 2D 优化完成后再评估。
+
+3. 完整数据导向重写
+   - 使用 SoA：`x[]`、`y[]`、`vx[]`、`vy[]`、`life[]`。
+   - 减少对象访问和方法调用。
+   - 代码可读性下降，适合作为高性能模式而不是默认实现。
+
+## 推荐实施顺序
+
+优先级从高到低：
+
+1. `ParticleSystem` 活跃数组和空闲栈。
+2. 轨迹环形缓冲。
+3. 圆形和方形 sprite 缓存。
+4. 高负载运行时降级。
+5. 动态像素比，需避免运行中 resize 闪屏。
+6. 星形和心形 sprite 缓存。
+7. WebGL/Worker 可行性验证。
+
+不建议第一阶段就做 WebGL 或 Worker。当前瓶颈仍有大量 Canvas 2D 和对象分配层面的低风险优化空间，先处理这些能更快获得收益，也能保留现有 API 和代码结构。
+
+## 性能验证方案
+
+### 手动测试场景
+
+1. 默认配置，连续点击 10 次。
+2. `particleCount = 1000`，关闭二次爆炸。
+3. `particleCount = 1000`，开启拖尾、辉光、闪烁。
+4. `textureType = "star"` 和 `"heart"` 分别测试。
+5. 开启 `autoLaunch`，`autoLaunchIntervalSeconds = 0.25`（兼容旧配置 `autoInterval = 250`），运行 30 秒。
+6. 高 DPI 屏幕或浏览器缩放 150% 下测试。
+
+### 观察指标
+
+- FPS 是否稳定在 45-60。
+- Performance 录制中是否存在明显 GC 尖峰。
+- 粒子生成瞬间是否有长任务。
+- Canvas 绘制时间是否随优化下降。
+- 低 FPS 降级是否及时恢复流畅。
+
+### 建议添加调试指标
+
+可以在性能面板或开发模式日志中加入：
+
+```text
+FPS
+activeParticles
+freeParticles
+performanceLevel
+pixelRatio
+drawMode: path | sprite
+spriteCacheSize
+```
+
+## 兼容性约束
+
+- 不改变公开构造方式：`SparkFireworks.create(canvas, configOrOptions)`。
+- 不改变高级脚本返回粒子的字段语义。
+- `particleCount` 仍表示单次爆炸期望粒子数，但实际生成数应受池容量限制。
+- 性能降级只影响运行时绘制质量，不应永久覆盖用户配置。
+- 现有预设应继续可用。
+
+## 风险和回滚点
+
+### 活跃数组改造
+
+风险：
+
+- 粒子死亡时移除逻辑错误可能导致漏绘、重复绘制或 `activeCount` 不准。
+
+回滚：
+
+- 保留原 `pool` 字段，必要时恢复完整池遍历。
+
+### 轨迹环形缓冲
+
+风险：
+
+- 读取顺序错误会导致拖尾断裂或反向。
+
+回滚：
+
+- 保留原 `trail` 绘制路径，先用配置开关切换。
+
+### Sprite 缓存
+
+风险：
+
+- 缓存 key 过细导致内存增长。
+- 缓存 key 过粗导致颜色或尺寸跳变明显。
+
+回滚：
+
+- `Particle.draw()` 保留路径绘制回退。
+
+### 动态像素比
+
+风险：
+
+- 频繁 resize 会导致画面闪烁或背景重绘成本上升。
+
+回滚：
+
+- 像素比调整加冷却时间，或只在低 FPS 持续超过阈值后调整。
+
+## 第一批落地清单
+
+第一批建议只做不会改变视觉输出的改造：
+
+- [x] `ParticleSystem` 改成活跃数组 + 空闲栈。
+- [x] `spawn()` 不再使用 `find()`。
+- [x] `update()` 和 `draw()` 只遍历活跃粒子。
+- [x] `clear()` 正确回收粒子。
+- [x] 添加基础统计字段，便于观察活跃粒子和空闲粒子数量。
+- [x] 运行 `npm run build`。
+- [ ] 在默认配置和 1000 粒子配置下手动验证。
+
+第二批再处理视觉层面的高收益优化：
+
+- [x] 轨迹环形缓冲。
+- [ ] 圆形 sprite 缓存。
+- [x] 高负载关闭或降低单粒子 shadowBlur。
+- [x] 低 FPS 时只改运行时质量，不直接覆盖用户配置。

package/examples/production.html

@@ -0,0 +1,203 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>SparkFireworks Production Example</title>
+    <style>
+      html,
+      body {
+        width: 100%;
+        height: 100%;
+        margin: 0;
+        background: #050711;
+      }
+
+      canvas {
+        display: block;
+        width: 100vw;
+        height: 100vh;
+      }
+
+      .toolbar {
+        position: fixed;
+        top: 16px;
+        left: 16px;
+        display: flex;
+        flex-wrap: wrap;
+        gap: 8px;
+        max-width: min(760px, calc(100vw - 32px));
+      }
+
+      button {
+        min-height: 34px;
+        border: 1px solid rgba(255, 255, 255, 0.22);
+        border-radius: 6px;
+        padding: 0 12px;
+        background: rgba(10, 16, 24, 0.82);
+        color: #fff;
+        cursor: pointer;
+      }
+
+      button:hover {
+        border-color: rgba(72, 214, 194, 0.8);
+        background: rgba(72, 214, 194, 0.18);
+      }
+    </style>
+  </head>
+  <body>
+    <canvas id="fireworks"></canvas>
+
+    <div class="toolbar">
+      <button id="launchWithTrail">随机发射（带轨迹）</button>
+      <button id="launchWithoutTrail">随机发射（不带轨迹）</button>
+      <button id="launchAdvanced">高级模式发射</button>
+      <button id="start">开始自动播放</button>
+      <button id="stop">停止自动播放</button>
+      <button id="preset">爱心预设</button>
+      <button id="reset">初始化设置</button>
+      <button id="clear">清除粒子</button>
+    </div>
+
+    <!-- 生产环境中先执行 npm run build:lib，再引入 dist-lib 里的 UMD 文件。 -->
+    <script src="../dist-lib/spark-fireworks.umd.cjs"></script>
+    <script>
+      const canvas = document.getElementById("fireworks");
+
+      const fullConfig = {
+        // 粒子基础
+        particleCount: 260,
+        particleMinSize: 2.5,
+        particleMaxSize: 7,
+        sizeEndMultiplier: 0.35,
+
+        // 运动学
+        gravity: 0.18,
+        damping: 0.982,
+        initialSpeedMin: 2.8,
+        initialSpeedMax: 8.2,
+        particleLife: 94,
+        rotationSpeed: 0.025,
+        colorShiftRate: 0.035,
+
+        // 视觉
+        colorStart: "#ffd166",
+        colorEnd: "#ef476f",
+        useRandomColors: false,
+        textureType: "circle",
+        glowIntensity: 0.75,
+
+        // 特效
+        explosionShape: "sphere",
+        enableSecondaryBurst: false,
+        secondaryBurstRatio: 0.2,
+        enableTrails: true,
+        showLaunchTrail: true,
+        windEnabled: false,
+        windX: 0,
+        windY: 0,
+        flicker: true,
+        fadeTrail: 0.18,
+
+        // 自动播放
+        autoLaunch: false,
+        autoLaunchIntervalSeconds: 0.9,
+        autoInterval: 900,
+
+        // 背景
+        backgroundType: "starfield",
+        backgroundColor: "#060912",
+        backgroundColor2: "#10243a",
+        backgroundImageMode: "cover"
+      };
+
+      const fireworks = SparkFireworks.create(canvas, {
+        config: fullConfig,
+        advancedMode: false,
+        createParticles(canvasData) {
+          const particles = [];
+          const count = 320;
+          const centerX = canvasData.x;
+          const centerY = canvasData.y;
+
+          for (let i = 0; i < count; i += 1) {
+            const angle = (i / count) * Math.PI * 2;
+            const wave = 0.65 + Math.abs(Math.sin(angle * 4)) * 0.75;
+            const speed = wave * (3.5 + Math.random() * 6);
+
+            particles.push({
+              x: centerX,
+              y: centerY,
+              vx: Math.cos(angle) * speed,
+              vy: Math.sin(angle) * speed,
+              size: 2 + Math.random() * 5,
+              life: 70 + Math.random() * 55,
+              startColor: i % 2 === 0 ? "#48d6c2" : "#ffcf5a",
+              endColor: i % 3 === 0 ? "#ffffff" : "#ef476f",
+              textureType: i % 5 === 0 ? "star" : "circle",
+              rotationVelocity: -0.04 + Math.random() * 0.08,
+              secondaryEligible: false
+            });
+          }
+
+          console.log(particles);
+
+          return particles;
+        }
+      });
+
+      function getRandomLaunchPoint() {
+        const rect = canvas.getBoundingClientRect();
+        return {
+          x: rect.width * (0.16 + Math.random() * 0.68),
+          y: rect.height * (0.16 + Math.random() * 0.46)
+        };
+      }
+
+      function launchRandomWithTrail() {
+        const point = getRandomLaunchPoint();
+        fireworks.setConfig({
+          ...fullConfig,
+          showLaunchTrail: true,
+          enableTrails: true
+        });
+        fireworks.launch(point.x, point.y, { withShell: true });
+      }
+
+      function launchRandomWithoutTrail() {
+        const point = getRandomLaunchPoint();
+        fireworks.setConfig({
+          ...fullConfig,
+          showLaunchTrail: false,
+          enableTrails: false
+        });
+        fireworks.launch(point.x, point.y, { withShell: false });
+      }
+
+      function launchAdvancedMode() {
+        const point = getRandomLaunchPoint();
+        fireworks.setAdvancedMode(true);
+        fireworks.setConfig({
+          ...fullConfig,
+          showLaunchTrail: false,
+          enableTrails: true,
+          textureType: "star",
+          colorStart: "#48d6c2",
+          colorEnd: "#ef476f",
+          fadeTrail: 0.11
+        });
+        fireworks.launch(point.x, point.y, { withShell: false });
+        fireworks.setAdvancedMode(false);
+      }
+
+      document.getElementById("launchWithTrail").onclick = launchRandomWithTrail;
+      document.getElementById("launchWithoutTrail").onclick = launchRandomWithoutTrail;
+      document.getElementById("launchAdvanced").onclick = launchAdvancedMode;
+      document.getElementById("start").onclick = () => fireworks.startAutoPlay();
+      document.getElementById("stop").onclick = () => fireworks.stopAutoPlay();
+      document.getElementById("preset").onclick = () => fireworks.selectPreset("heart");
+      document.getElementById("reset").onclick = () => fireworks.resetConfig(fullConfig);
+      document.getElementById("clear").onclick = () => fireworks.clearParticles();
+    </script>
+  </body>
+</html>

package/guide.html

@@ -0,0 +1,89 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="icon" type="image/jpeg" href="/favicon.jpg" />
+    <title>SparkFireworks 使用指导</title>
+    <script>
+      var _hmt = _hmt || [];
+      (function() {
+        var hm = document.createElement("script");
+        hm.src = "https://hm.baidu.com/hm.js?c39438c75acf24e0e70a36e03a29e613";
+        var s = document.getElementsByTagName("script")[0];
+        s.parentNode.insertBefore(hm, s);
+      })();
+    </script>
+    <script type="module" src="/src/pages.js"></script>
+  </head>
+  <body>
+    <main class="site-shell">
+      <nav class="site-nav" aria-label="站点导航">
+        <a class="brand" href="/">SparkFireworks</a>
+        <div class="nav-links">
+          <a href="/demo.html">功能演示</a>
+          <a href="/guide.html">使用指导</a>
+          <a href="/advanced-guide.html">高级指导</a>
+          <a href="/api-download.html">API 下载</a>
+        </div>
+      </nav>
+
+      <header class="page-title">
+        <h1>使用指导</h1>
+        <p>这页面向普通使用者，介绍功能演示页里每一类控件的作用，以及如何稳定地调出想要的烟花效果。</p>
+      </header>
+
+      <section class="doc-section">
+        <h2>快速开始</h2>
+        <ol>
+          <li>打开 <a href="/demo.html">功能演示页</a>。</li>
+          <li>点击画布任意位置发射烟花。</li>
+          <li>在右侧面板调整颜色、形状、粒子数量、拖尾、背景等参数。</li>
+          <li>使用顶部预设下拉框快速切换内置效果。</li>
+        </ol>
+      </section>
+
+      <section class="doc-section">
+        <h2>顶部工具栏</h2>
+        <ul>
+          <li><strong>预设选择：</strong>选择内置预设或保存到本地的配置。</li>
+          <li><strong>初始化设置：</strong>恢复默认配置。</li>
+          <li><strong>保存：</strong>把当前配置保存到浏览器本地。</li>
+          <li><strong>导出/导入：</strong>把配置保存成 JSON 文件，或从 JSON 文件恢复。</li>
+          <li><strong>分享：</strong>把当前配置写入链接，便于复制给其他人。</li>
+          <li><strong>自动：</strong>按自动间隔持续发射随机烟花。</li>
+          <li><strong>暂停：</strong>暂停或恢复动画。</li>
+          <li><strong>清除：</strong>清空当前画布上的粒子。</li>
+        </ul>
+      </section>
+
+      <section class="doc-section">
+        <h2>参数面板</h2>
+        <h3>样式</h3>
+        <p>控制粒子的起始颜色、结束颜色、随机颜色、粒子形状和辉光强度。辉光越高越亮，但绘制成本也更高。</p>
+        <h3>特效</h3>
+        <p>控制爆炸形状、二次爆炸、拖尾、升空轨迹、风场、闪烁和画面残影。拖尾和二次爆炸都会增加性能压力，应按设备能力酌情开启。</p>
+        <h3>粒子</h3>
+        <p>控制单次爆炸粒子数、初速度、阻尼、重力、生命周期、大小和自动播放间隔。粒子数量越高，画面越密集，性能压力也越大。</p>
+        <h3>背景</h3>
+        <p>支持纯色、线性渐变、径向渐变、星空和图片背景。上传图片后会自动切换到图片背景。</p>
+      </section>
+
+      <section class="doc-section">
+        <h2>调参建议</h2>
+        <ul>
+          <li>想要干净利落的爆炸：降低 `fadeTrail`，关闭粒子拖尾，使用圆形粒子。</li>
+          <li>想要浪漫柔和的效果：提高辉光，开启拖尾，降低重力和速度。</li>
+          <li>想要大规模烟花：提高粒子数，但谨慎开启二次爆炸和复杂形状。</li>
+          <li>帧率下降时：先降低粒子数量、关闭二次爆炸，再降低辉光和拖尾。</li>
+        </ul>
+      </section>
+
+      <section class="doc-section">
+        <h2>预设和配置</h2>
+        <p>内置预设适合快速体验不同风格。本地保存的预设只保存在当前浏览器；需要迁移到其他设备时，请使用导出和导入功能。</p>
+        <p class="note">高级脚本不会自动保存到普通预设里。需要复用脚本时，建议保存为独立 JS 文件或复制到高级指导页中的示例格式。</p>
+      </section>
+    </main>
+  </body>
+</html>