rocket-back-to-top 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,154 @@
+# rocket-back-to-top
+
+零依赖 Web Component：用一艘 Canvas 绘制的火箭「返回页面顶部」。
+
+- 越接近页面底部，燃料越满，火焰与粒子越强
+- 点击后原地喷射，页面平滑滚动跟随回顶
+- 回顶过程中用户滚动可立即打断并交还控制权
+- 可在原生 HTML / Vue / React / Angular 中直接使用
+
+自定义元素标签：`<rocket-to-top>`
+
+## 安装
+
+```bash
+npm install rocket-back-to-top
+# 或
+yarn add rocket-back-to-top
+# 或
+pnpm add rocket-back-to-top
+```
+
+## 使用
+
+```js
+import 'rocket-back-to-top';
+```
+
+```html
+<rocket-to-top threshold="300" position="right" size="64"></rocket-to-top>
+```
+
+CDN：
+
+```html
+<script type="module">
+  import 'https://cdn.jsdelivr.net/npm/rocket-back-to-top/src/index.js';
+</script>
+<rocket-to-top></rocket-to-top>
+```
+
+## 属性
+
+| 属性 | 类型 | 默认 | 说明 |
+|------|------|------|------|
+| `threshold` | number | `300` | 滚过多少 px 后显示 |
+| `position` | `"right"` \| `"left"` | `"right"` | 贴在视口左/右下角 |
+| `size` | number | `64` | 逻辑宽度（px），高度约为 `size * 1.85` |
+
+## 事件与方法
+
+| 事件 | 说明 |
+|------|------|
+| `rocket-launch` | 开始喷射并回顶 |
+| `rocket-arrive` | 已到达顶部 |
+| `rocket-pause` | 回顶过程中被用户滚动打断 |
+
+```js
+const el = document.querySelector('rocket-to-top');
+
+el.addEventListener('rocket-launch', (e) => {
+  console.log('fuel', e.detail.fuel);
+});
+el.addEventListener('rocket-arrive', () => {
+  console.log('arrived');
+});
+el.addEventListener('rocket-pause', (e) => {
+  console.log('paused', e.detail.reason, e.detail.scrollY);
+});
+
+el.launch(); // 开始回顶
+el.pause();  // 手动打断回顶
+```
+
+## 跨框架
+
+### Vue 3
+
+```vue
+<script setup>
+import 'rocket-back-to-top';
+</script>
+
+<template>
+  <rocket-to-top
+    threshold="300"
+    position="right"
+    size="64"
+    @rocket-launch="onLaunch"
+    @rocket-arrive="onArrive"
+    @rocket-pause="onPause"
+  />
+</template>
+```
+
+Vite 可配置：
+
+```js
+vue: {
+  template: {
+    compilerOptions: {
+      isCustomElement: (tag) => tag === 'rocket-to-top',
+    },
+  },
+}
+```
+
+### React
+
+```jsx
+import { useEffect, useRef } from 'react';
+import 'rocket-back-to-top';
+
+export function BackToTop() {
+  const ref = useRef(null);
+
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    const onLaunch = () => console.log('launch');
+    const onArrive = () => console.log('arrive');
+    const onPause = () => console.log('pause');
+    el.addEventListener('rocket-launch', onLaunch);
+    el.addEventListener('rocket-arrive', onArrive);
+    el.addEventListener('rocket-pause', onPause);
+    return () => {
+      el.removeEventListener('rocket-launch', onLaunch);
+      el.removeEventListener('rocket-arrive', onArrive);
+      el.removeEventListener('rocket-pause', onPause);
+    };
+  }, []);
+
+  return <rocket-to-top ref={ref} threshold="300" position="right" size="64" />;
+}
+```
+
+### Angular
+
+```ts
+import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
+import 'rocket-back-to-top';
+
+@NgModule({
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+})
+export class AppModule {}
+```
+
+```html
+<rocket-to-top threshold="300" position="right" size="64"></rocket-to-top>
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "rocket-back-to-top",
+  "version": "1.0.0",
+  "description": "Zero-dependency Web Component: a rocket back-to-top button with fuel, flame and particle effects",
+  "type": "module",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "types",
+    "LICENSE",
+    "README.md"
+  ],
+  "sideEffects": [
+    "./src/index.js",
+    "./src/rocket-to-top.js"
+  ],
+  "scripts": {
+    "demo": "npx --yes serve . -p 4173",
+    "pack:check": "npm pack --dry-run"
+  },
+  "keywords": [
+    "web-component",
+    "custom-element",
+    "back-to-top",
+    "scroll-to-top",
+    "rocket",
+    "canvas",
+    "vanilla-js",
+    "vue",
+    "react",
+    "angular"
+  ],
+  "author": "detectiveBoy",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitee.com/detective-boy/rocket-back-to-top.git"
+  },
+  "bugs": {
+    "url": "https://gitee.com/detective-boy/rocket-back-to-top/issues"
+  },
+  "homepage": "https://gitee.com/detective-boy/rocket-back-to-top#readme",
+  "engines": {
+    "node": ">=16"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.js

@@ -0,0 +1,5 @@
+/**
+ * rocket-back-to-top
+ * Zero-dependency Web Component: <rocket-to-top>
+ */
+export { RocketToTop, RocketToTop as default } from './rocket-to-top.js';

package/src/rocket-renderer.js

@@ -0,0 +1,415 @@
+/**
+ * Full-canvas rocket, fuel gauge, flame, and particle renderer.
+ */
+
+const PARTICLE_COLORS = [
+  '#fff7c2',
+  '#ffe066',
+  '#ff9f1a',
+  '#ff6b00',
+  '#ff3d00',
+  '#ff1744',
+];
+
+function rand(min, max) {
+  return min + Math.random() * (max - min);
+}
+
+function pick(arr) {
+  return arr[(Math.random() * arr.length) | 0];
+}
+
+export class RocketRenderer {
+  /**
+   * @param {HTMLCanvasElement} canvas
+   */
+  constructor(canvas) {
+    this.canvas = canvas;
+    this.ctx = canvas.getContext('2d');
+    this.particles = [];
+    this.time = 0;
+    this.fuel = 0;
+    this.thrust = 0;
+    this.visible = false;
+    this._logicalSize = 64;
+    this._dpr = 1;
+  }
+
+  setSize(logicalSize) {
+    this._logicalSize = logicalSize;
+    this.resize();
+  }
+
+  resize() {
+    const dpr = Math.min(window.devicePixelRatio || 1, 2);
+    this._dpr = dpr;
+    // Extra vertical room for flame + particles below rocket
+    const w = this._logicalSize;
+    const h = this._logicalSize * 1.85;
+    this.canvas.width = Math.round(w * dpr);
+    this.canvas.height = Math.round(h * dpr);
+    this.canvas.style.width = `${w}px`;
+    this.canvas.style.height = `${h}px`;
+    this.ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+  }
+
+  /**
+   * @param {{ fuel: number, thrust: number, visible: boolean, dt: number }} state
+   */
+  render(state) {
+    this.fuel = state.fuel;
+    this.thrust = state.thrust;
+    this.visible = state.visible;
+    this.time += state.dt;
+
+    const ctx = this.ctx;
+    const w = this._logicalSize;
+    const h = this._logicalSize * 1.85;
+    ctx.clearRect(0, 0, w, h);
+
+    if (!this.visible && this.thrust <= 0.01) {
+      this.particles.length = 0;
+      return;
+    }
+
+    const rocketCenterX = w / 2;
+    // Layout: nose → body → nozzle; flame/particles emit from nozzle
+    const topY = w * 0.06;
+    const noseH = w * 0.22;
+    const bodyH = w * 0.52;
+    const nozzleH = w * 0.06;
+    const nozzleY = topY + noseH + bodyH + nozzleH;
+    const intensity = Math.max(this.fuel * 0.55, this.thrust);
+
+    this._spawnParticles(rocketCenterX, nozzleY, intensity, state.dt);
+    this._updateParticles(state.dt);
+    this._drawParticles(ctx);
+    this._drawFlame(ctx, rocketCenterX, nozzleY, intensity);
+    this._drawRocket(ctx, rocketCenterX, topY, w);
+  }
+
+  _spawnParticles(x, nozzleY, intensity, dt) {
+    if (intensity < 0.04) return;
+
+    const rate = 18 + intensity * 90;
+    const count = Math.floor(rate * dt + Math.random());
+
+    for (let i = 0; i < count; i++) {
+      const speed = rand(40, 80) + intensity * rand(80, 160);
+      const angle = Math.PI / 2 + rand(-0.45, 0.45);
+      this.particles.push({
+        x: x + rand(-4, 4),
+        y: nozzleY + rand(0, 4),
+        vx: Math.cos(angle) * speed * rand(0.3, 0.7) + rand(-20, 20),
+        vy: Math.sin(angle) * speed,
+        life: rand(0.25, 0.55 + intensity * 0.35),
+        maxLife: 0,
+        size: rand(1.2, 2.8) + intensity * rand(0.5, 2.2),
+        color: pick(PARTICLE_COLORS),
+        spin: rand(-6, 6),
+      });
+      this.particles[this.particles.length - 1].maxLife =
+        this.particles[this.particles.length - 1].life;
+    }
+
+    // Cap particle count for performance
+    if (this.particles.length > 220) {
+      this.particles.splice(0, this.particles.length - 220);
+    }
+  }
+
+  _updateParticles(dt) {
+    for (let i = this.particles.length - 1; i >= 0; i--) {
+      const p = this.particles[i];
+      p.life -= dt;
+      if (p.life <= 0) {
+        this.particles.splice(i, 1);
+        continue;
+      }
+      p.x += p.vx * dt;
+      p.y += p.vy * dt;
+      p.vx *= 0.98;
+      p.vy += 30 * dt;
+      p.vx += Math.sin(this.time * 12 + p.spin) * 8 * dt;
+    }
+  }
+
+  _drawParticles(ctx) {
+    for (const p of this.particles) {
+      const alpha = clamp01(p.life / p.maxLife);
+      ctx.globalAlpha = alpha * 0.9;
+      ctx.fillStyle = p.color;
+      ctx.beginPath();
+      ctx.arc(p.x, p.y, p.size * (0.5 + alpha * 0.5), 0, Math.PI * 2);
+      ctx.fill();
+    }
+    ctx.globalAlpha = 1;
+  }
+
+  _drawFlame(ctx, x, nozzleY, intensity) {
+    if (intensity < 0.03) return;
+
+    const flicker = 0.85 + Math.sin(this.time * 28) * 0.08 + Math.sin(this.time * 47) * 0.07;
+    const power = intensity * flicker;
+    const flameH = (14 + power * 42) * (0.9 + this.thrust * 0.35);
+    const flameW = 6 + power * 14;
+
+    ctx.save();
+    ctx.translate(x, nozzleY);
+    ctx.globalCompositeOperation = 'lighter';
+
+    // Outer glow
+    const glow = ctx.createRadialGradient(0, flameH * 0.35, 1, 0, flameH * 0.2, flameW * 1.8);
+    glow.addColorStop(0, `rgba(255, 120, 20, ${0.35 * power})`);
+    glow.addColorStop(1, 'rgba(255, 40, 0, 0)');
+    ctx.fillStyle = glow;
+    ctx.beginPath();
+    ctx.ellipse(0, flameH * 0.35, flameW * 1.6, flameH * 0.7, 0, 0, Math.PI * 2);
+    ctx.fill();
+
+    // Outer cone
+    this._flameCone(ctx, flameW * 1.15, flameH, [
+      [0, `rgba(255, 60, 0, ${0.55 * power})`],
+      [0.45, `rgba(255, 100, 10, ${0.4 * power})`],
+      [1, 'rgba(255, 40, 0, 0)'],
+    ]);
+
+    // Mid cone
+    this._flameCone(ctx, flameW * 0.72, flameH * 0.82, [
+      [0, `rgba(255, 180, 40, ${0.75 * power})`],
+      [0.5, `rgba(255, 120, 20, ${0.45 * power})`],
+      [1, 'rgba(255, 80, 0, 0)'],
+    ]);
+
+    // Core
+    this._flameCone(ctx, flameW * 0.38, flameH * 0.55, [
+      [0, `rgba(255, 255, 240, ${0.95 * power})`],
+      [0.35, `rgba(255, 240, 160, ${0.8 * power})`],
+      [1, 'rgba(255, 200, 60, 0)'],
+    ]);
+
+    ctx.restore();
+  }
+
+  _flameCone(ctx, halfW, height, stops) {
+    const sway = Math.sin(this.time * 22) * halfW * 0.12;
+    const path = new Path2D();
+    path.moveTo(-halfW * 0.55, 0);
+    path.quadraticCurveTo(-halfW + sway * 0.3, height * 0.4, sway * 0.5, height);
+    path.quadraticCurveTo(halfW + sway * 0.3, height * 0.4, halfW * 0.55, 0);
+    path.closePath();
+
+    const grad = ctx.createLinearGradient(0, 0, 0, height);
+    for (const [t, color] of stops) grad.addColorStop(t, color);
+    ctx.fillStyle = grad;
+    ctx.fill(path);
+  }
+
+  _drawRocket(ctx, cx, topY, size) {
+    const bodyW = size * 0.28;
+    const bodyH = size * 0.52;
+    const noseH = size * 0.22;
+    const finH = size * 0.18;
+    const bodyTop = topY + noseH;
+    const bodyBottom = bodyTop + bodyH;
+
+    ctx.save();
+
+    // Soft shadow under rocket
+    ctx.fillStyle = 'rgba(0,0,0,0.18)';
+    ctx.beginPath();
+    ctx.ellipse(cx, bodyBottom + 6, bodyW * 0.7, 4, 0, 0, Math.PI * 2);
+    ctx.fill();
+
+    // Fins
+    this._drawFin(ctx, cx - bodyW * 0.55, bodyBottom - finH * 0.2, -1, finH, bodyW);
+    this._drawFin(ctx, cx + bodyW * 0.55, bodyBottom - finH * 0.2, 1, finH, bodyW);
+
+    // Body cylinder with metallic gradient
+    const bodyGrad = ctx.createLinearGradient(cx - bodyW / 2, 0, cx + bodyW / 2, 0);
+    bodyGrad.addColorStop(0, '#7a8699');
+    bodyGrad.addColorStop(0.18, '#e8edf5');
+    bodyGrad.addColorStop(0.4, '#f7f9fc');
+    bodyGrad.addColorStop(0.62, '#c5cedb');
+    bodyGrad.addColorStop(0.85, '#8b96a8');
+    bodyGrad.addColorStop(1, '#5c6678');
+
+    roundRect(ctx, cx - bodyW / 2, bodyTop, bodyW, bodyH, 3);
+    ctx.fillStyle = bodyGrad;
+    ctx.fill();
+
+    // Body outline
+    ctx.strokeStyle = 'rgba(40,50,70,0.35)';
+    ctx.lineWidth = 1;
+    ctx.stroke();
+
+    // Horizontal panel lines
+    ctx.strokeStyle = 'rgba(60,70,90,0.25)';
+    ctx.lineWidth = 0.8;
+    for (let i = 1; i <= 3; i++) {
+      const y = bodyTop + (bodyH * i) / 4;
+      ctx.beginPath();
+      ctx.moveTo(cx - bodyW / 2 + 2, y);
+      ctx.lineTo(cx + bodyW / 2 - 2, y);
+      ctx.stroke();
+    }
+
+    // Red accent stripe
+    const stripeY = bodyTop + bodyH * 0.38;
+    const stripeGrad = ctx.createLinearGradient(cx - bodyW / 2, 0, cx + bodyW / 2, 0);
+    stripeGrad.addColorStop(0, '#a31212');
+    stripeGrad.addColorStop(0.5, '#e53935');
+    stripeGrad.addColorStop(1, '#8e0e0e');
+    ctx.fillStyle = stripeGrad;
+    ctx.fillRect(cx - bodyW / 2, stripeY, bodyW, bodyH * 0.1);
+
+    // Fuel gauge on left side of body
+    this._drawFuelGauge(ctx, cx - bodyW / 2 - size * 0.06, bodyTop + bodyH * 0.15, size * 0.05, bodyH * 0.55);
+
+    // Window
+    const winR = bodyW * 0.22;
+    const winY = bodyTop + bodyH * 0.22;
+    const winGrad = ctx.createRadialGradient(cx - winR * 0.3, winY - winR * 0.3, 1, cx, winY, winR);
+    winGrad.addColorStop(0, '#b3e5fc');
+    winGrad.addColorStop(0.55, '#0288d1');
+    winGrad.addColorStop(1, '#01579b');
+    ctx.beginPath();
+    ctx.arc(cx, winY, winR, 0, Math.PI * 2);
+    ctx.fillStyle = winGrad;
+    ctx.fill();
+    ctx.strokeStyle = '#37474f';
+    ctx.lineWidth = 1.4;
+    ctx.stroke();
+    // Window highlight
+    ctx.beginPath();
+    ctx.arc(cx - winR * 0.35, winY - winR * 0.35, winR * 0.28, 0, Math.PI * 2);
+    ctx.fillStyle = 'rgba(255,255,255,0.55)';
+    ctx.fill();
+
+    // Nose cone
+    const noseGrad = ctx.createLinearGradient(cx - bodyW / 2, topY, cx + bodyW / 2, bodyTop);
+    noseGrad.addColorStop(0, '#c62828');
+    noseGrad.addColorStop(0.45, '#ef5350');
+    noseGrad.addColorStop(1, '#8e0000');
+    ctx.beginPath();
+    ctx.moveTo(cx, topY);
+    ctx.quadraticCurveTo(cx + bodyW * 0.55, bodyTop - noseH * 0.15, cx + bodyW / 2, bodyTop);
+    ctx.lineTo(cx - bodyW / 2, bodyTop);
+    ctx.quadraticCurveTo(cx - bodyW * 0.55, bodyTop - noseH * 0.15, cx, topY);
+    ctx.closePath();
+    ctx.fillStyle = noseGrad;
+    ctx.fill();
+    ctx.strokeStyle = 'rgba(80,0,0,0.35)';
+    ctx.lineWidth = 1;
+    ctx.stroke();
+
+    // Nose tip highlight
+    ctx.beginPath();
+    ctx.moveTo(cx - 1, topY + 4);
+    ctx.lineTo(cx - bodyW * 0.12, bodyTop - 4);
+    ctx.strokeStyle = 'rgba(255,255,255,0.35)';
+    ctx.lineWidth = 1.5;
+    ctx.stroke();
+
+    // Nozzle
+    const nzW = bodyW * 0.55;
+    const nzH = size * 0.06;
+    const nzGrad = ctx.createLinearGradient(cx - nzW / 2, 0, cx + nzW / 2, 0);
+    nzGrad.addColorStop(0, '#455a64');
+    nzGrad.addColorStop(0.5, '#90a4ae');
+    nzGrad.addColorStop(1, '#37474f');
+    ctx.beginPath();
+    ctx.moveTo(cx - nzW * 0.35, bodyBottom);
+    ctx.lineTo(cx + nzW * 0.35, bodyBottom);
+    ctx.lineTo(cx + nzW / 2, bodyBottom + nzH);
+    ctx.lineTo(cx - nzW / 2, bodyBottom + nzH);
+    ctx.closePath();
+    ctx.fillStyle = nzGrad;
+    ctx.fill();
+
+    ctx.restore();
+  }
+
+  _drawFin(ctx, x, y, dir, finH, bodyW) {
+    const finW = bodyW * 0.55;
+    const grad = ctx.createLinearGradient(x, y, x + dir * finW, y + finH);
+    grad.addColorStop(0, '#d32f2f');
+    grad.addColorStop(1, '#6d0f0f');
+    ctx.beginPath();
+    ctx.moveTo(x, y);
+    ctx.lineTo(x + dir * finW, y + finH * 0.85);
+    ctx.lineTo(x + dir * finW * 0.15, y + finH);
+    ctx.lineTo(x, y + finH * 0.55);
+    ctx.closePath();
+    ctx.fillStyle = grad;
+    ctx.fill();
+    ctx.strokeStyle = 'rgba(60,0,0,0.4)';
+    ctx.lineWidth = 0.8;
+    ctx.stroke();
+  }
+
+  _drawFuelGauge(ctx, x, y, w, h) {
+    // Frame
+    ctx.fillStyle = 'rgba(30,35,45,0.85)';
+    roundRect(ctx, x - 1, y - 1, w + 2, h + 2, 2);
+    ctx.fill();
+
+    ctx.fillStyle = '#1a1f2a';
+    roundRect(ctx, x, y, w, h, 1.5);
+    ctx.fill();
+
+    const fillH = h * clamp01(this.fuel);
+    if (fillH > 0.5) {
+      const fy = y + h - fillH;
+      const fuelGrad = ctx.createLinearGradient(x, fy, x, y + h);
+      const hot = this.fuel > 0.7;
+      fuelGrad.addColorStop(0, hot ? '#fff59d' : '#ffb74d');
+      fuelGrad.addColorStop(0.4, hot ? '#ffca28' : '#ff9800');
+      fuelGrad.addColorStop(1, hot ? '#ff6f00' : '#e65100');
+      ctx.fillStyle = fuelGrad;
+      roundRect(ctx, x, fy, w, fillH, 1.5);
+      ctx.fill();
+
+      // Shine
+      ctx.fillStyle = 'rgba(255,255,255,0.25)';
+      ctx.fillRect(x + 1, fy + 1, w * 0.35, Math.max(0, fillH - 2));
+    }
+
+    // Tick marks
+    ctx.strokeStyle = 'rgba(255,255,255,0.25)';
+    ctx.lineWidth = 0.6;
+    for (let i = 1; i < 4; i++) {
+      const ty = y + (h * i) / 4;
+      ctx.beginPath();
+      ctx.moveTo(x, ty);
+      ctx.lineTo(x + w * 0.4, ty);
+      ctx.stroke();
+    }
+
+    // Glow when full
+    if (this.fuel > 0.92) {
+      ctx.shadowColor = '#ffab00';
+      ctx.shadowBlur = 6;
+      ctx.strokeStyle = 'rgba(255,200,50,0.6)';
+      ctx.lineWidth = 1;
+      roundRect(ctx, x - 1, y - 1, w + 2, h + 2, 2);
+      ctx.stroke();
+      ctx.shadowBlur = 0;
+    }
+  }
+}
+
+function clamp01(v) {
+  return Math.min(1, Math.max(0, v));
+}
+
+function roundRect(ctx, x, y, w, h, r) {
+  const rr = Math.min(r, w / 2, h / 2);
+  ctx.beginPath();
+  ctx.moveTo(x + rr, y);
+  ctx.arcTo(x + w, y, x + w, y + h, rr);
+  ctx.arcTo(x + w, y + h, x, y + h, rr);
+  ctx.arcTo(x, y + h, x, y, rr);
+  ctx.arcTo(x, y, x + w, y, rr);
+  ctx.closePath();
+}

package/src/rocket-to-top.js

@@ -0,0 +1,341 @@
+import { RocketRenderer } from './rocket-renderer.js';
+import {
+  getScrollProgress,
+  animateScrollToTop,
+  clamp,
+} from './scroll-controller.js';
+
+const STYLES = `
+  :host {
+    position: fixed;
+    z-index: 9999;
+    bottom: 28px;
+    display: block;
+    width: var(--rtt-size, 64px);
+    height: calc(var(--rtt-size, 64px) * 1.85);
+    pointer-events: none;
+    opacity: 0;
+    transform: translateY(12px) scale(0.92);
+    transition: opacity 0.28s ease, transform 0.28s ease;
+  }
+  :host([position="left"]) {
+    left: 24px;
+    right: auto;
+  }
+  :host(:not([position="left"])) {
+    right: 24px;
+    left: auto;
+  }
+  :host([data-visible]) {
+    opacity: 1;
+    transform: translateY(0) scale(1);
+    pointer-events: auto;
+  }
+  :host([data-launching]) {
+    pointer-events: none;
+  }
+  button {
+    all: unset;
+    box-sizing: border-box;
+    display: block;
+    width: 100%;
+    height: 100%;
+    cursor: pointer;
+    border-radius: 12px;
+  }
+  button:focus-visible {
+    outline: 2px solid #ff9800;
+    outline-offset: 4px;
+  }
+  canvas {
+    display: block;
+    width: 100%;
+    height: 100%;
+    pointer-events: none;
+  }
+`;
+
+/**
+ * <rocket-to-top threshold="300" position="right" size="64"></rocket-to-top>
+ *
+ * Events:
+ * - rocket-launch
+ * - rocket-arrive
+ * - rocket-pause  (用户滚动打断回顶动画)
+ */
+export class RocketToTop extends HTMLElement {
+  static get observedAttributes() {
+    return ['threshold', 'position', 'size'];
+  }
+
+  constructor() {
+    super();
+    this._root = this.attachShadow({ mode: 'open' });
+    this._fuel = 0;
+    this._thrust = 0;
+    this._visible = false;
+    this._launching = false;
+    this._rafId = 0;
+    this._lastTs = 0;
+    this._cancelScroll = null;
+    this._onScroll = this._onScroll.bind(this);
+    this._onResize = this._onResize.bind(this);
+    this._loop = this._loop.bind(this);
+    this._onClick = this._onClick.bind(this);
+    this._onKeyDown = this._onKeyDown.bind(this);
+  }
+
+  connectedCallback() {
+    this._renderDom();
+    this._applySize();
+    this._renderer = new RocketRenderer(this._canvas);
+    this._renderer.setSize(this.size);
+    this._onScroll();
+    window.addEventListener('scroll', this._onScroll, { passive: true });
+    window.addEventListener('resize', this._onResize, { passive: true });
+    this._btn.addEventListener('click', this._onClick);
+    this._btn.addEventListener('keydown', this._onKeyDown);
+    this._startLoop();
+  }
+
+  disconnectedCallback() {
+    window.removeEventListener('scroll', this._onScroll);
+    window.removeEventListener('resize', this._onResize);
+    this._btn?.removeEventListener('click', this._onClick);
+    this._btn?.removeEventListener('keydown', this._onKeyDown);
+    this._stopLoop();
+    this._cancelScroll?.();
+    this._cancelScroll = null;
+    this._launching = false;
+    this.removeAttribute('data-launching');
+  }
+
+  attributeChangedCallback(name) {
+    if (!this._canvas) return;
+    if (name === 'size') {
+      this._applySize();
+      this._renderer?.setSize(this.size);
+    }
+    if (name === 'threshold' || name === 'position') {
+      this._onScroll();
+    }
+  }
+
+  get threshold() {
+    const v = Number(this.getAttribute('threshold'));
+    return Number.isFinite(v) && v >= 0 ? v : 300;
+  }
+
+  set threshold(v) {
+    this.setAttribute('threshold', String(v));
+  }
+
+  get position() {
+    return this.getAttribute('position') === 'left' ? 'left' : 'right';
+  }
+
+  set position(v) {
+    this.setAttribute('position', v === 'left' ? 'left' : 'right');
+  }
+
+  get size() {
+    const v = Number(this.getAttribute('size'));
+    return Number.isFinite(v) && v > 16 ? v : 64;
+  }
+
+  set size(v) {
+    this.setAttribute('size', String(v));
+  }
+
+  _renderDom() {
+    if (this._canvas) return;
+    const style = document.createElement('style');
+    style.textContent = STYLES;
+    this._btn = document.createElement('button');
+    this._btn.type = 'button';
+    this._btn.setAttribute('aria-label', '返回顶部');
+    this._btn.setAttribute('title', '火箭返回顶部');
+    this._canvas = document.createElement('canvas');
+    this._btn.appendChild(this._canvas);
+    this._root.append(style, this._btn);
+  }
+
+  _applySize() {
+    this.style.setProperty('--rtt-size', `${this.size}px`);
+  }
+
+  _onScroll() {
+    if (this._launching) return;
+    const { scrollY, progress } = getScrollProgress();
+    this._fuel = progress;
+    const shouldShow = scrollY > this.threshold;
+    this._setVisible(shouldShow);
+  }
+
+  _onResize() {
+    this._renderer?.resize();
+    this._onScroll();
+  }
+
+  _setVisible(show) {
+    this._visible = show;
+    if (show) {
+      this.setAttribute('data-visible', '');
+    } else {
+      this.removeAttribute('data-visible');
+    }
+    if (show || this._thrust > 0.01) {
+      this._startLoop();
+    }
+  }
+
+  _onClick(e) {
+    e.preventDefault();
+    this.launch();
+  }
+
+  _onKeyDown(e) {
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      this.launch();
+    }
+  }
+
+  /**
+   * 打断回顶：停止滚动动画，火焰熄灭，把滚动控制权还给用户。
+   * @param {string} [reason]
+   */
+  pause(reason = 'manual') {
+    if (!this._launching) return;
+    this._cancelScroll?.();
+    this._cancelScroll = null;
+    this._finishLaunchInterrupted(reason);
+  }
+
+  _finishLaunchInterrupted(reason) {
+    this._launching = false;
+    this.removeAttribute('data-launching');
+    this._thrust = 0;
+    const { scrollY, progress } = getScrollProgress();
+    this._fuel = progress;
+    this._setVisible(scrollY > this.threshold);
+    this._startLoop();
+    this.dispatchEvent(
+      new CustomEvent('rocket-pause', {
+        bubbles: true,
+        composed: true,
+        detail: { reason, scrollY, fuel: progress },
+      })
+    );
+  }
+
+  /** Public API: start launch / scroll to top */
+  launch() {
+    if (this._launching) return;
+    const { scrollY } = getScrollProgress();
+    if (scrollY <= 0) return;
+
+    this._launching = true;
+    this.setAttribute('data-launching', '');
+    this._setVisible(true);
+    this._thrust = 1;
+    this._startLoop();
+
+    this.dispatchEvent(
+      new CustomEvent('rocket-launch', {
+        bubbles: true,
+        composed: true,
+        detail: { fuel: this._fuel, scrollY },
+      })
+    );
+
+    const durationMs = clamp(900 + scrollY * 0.35, 1000, 2200);
+
+    this._cancelScroll = animateScrollToTop({
+      durationMs,
+      onUpdate: (t, y) => {
+        if (!this._launching) return;
+        // Strong thrust at start, taper as we approach top; keep flame lively
+        this._thrust = clamp(1 - t * 0.55, 0.35, 1);
+        const { progress } = getScrollProgress();
+        this._fuel = progress;
+        if (y <= this.threshold) {
+          this._setVisible(true);
+        }
+      },
+      onInterrupt: (reason) => {
+        this._cancelScroll = null;
+        this._finishLaunchInterrupted(reason);
+      },
+      onComplete: () => {
+        this._cancelScroll = null;
+        this._thrust = 0;
+        this._fuel = 0;
+        this._launching = false;
+        this.removeAttribute('data-launching');
+        this._setVisible(false);
+        this.dispatchEvent(
+          new CustomEvent('rocket-arrive', {
+            bubbles: true,
+            composed: true,
+          })
+        );
+      },
+    });
+  }
+
+  _startLoop() {
+    if (this._rafId) return;
+    this._lastTs = performance.now();
+    this._rafId = requestAnimationFrame(this._loop);
+  }
+
+  _stopLoop() {
+    if (this._rafId) {
+      cancelAnimationFrame(this._rafId);
+      this._rafId = 0;
+    }
+  }
+
+  _loop(ts) {
+    const dt = clamp((ts - this._lastTs) / 1000, 0, 0.05);
+    this._lastTs = ts;
+
+    // Idle flame subtle pulse from fuel
+    let thrust = this._thrust;
+    if (!this._launching && this._visible) {
+      thrust = Math.max(thrust, this._fuel * 0.25);
+    }
+
+    this._renderer.render({
+      fuel: this._fuel,
+      thrust,
+      visible: this._visible || this._launching,
+      dt,
+    });
+
+    const needContinue =
+      this._visible ||
+      this._launching ||
+      this._thrust > 0.01 ||
+      (this._renderer.particles?.length ?? 0) > 0;
+
+    if (needContinue) {
+      this._rafId = requestAnimationFrame(this._loop);
+    } else {
+      this._rafId = 0;
+      this._renderer.render({
+        fuel: 0,
+        thrust: 0,
+        visible: false,
+        dt: 0,
+      });
+    }
+  }
+}
+
+if (!customElements.get('rocket-to-top')) {
+  customElements.define('rocket-to-top', RocketToTop);
+}
+
+export default RocketToTop;

package/src/scroll-controller.js

@@ -0,0 +1,148 @@
+/**
+ * Scroll progress tracking and smooth scroll-to-top animation.
+ */
+
+export function clamp(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}
+
+export function getScrollProgress() {
+  const doc = document.documentElement;
+  const scrollY = window.scrollY || doc.scrollTop || 0;
+  const maxScroll = Math.max(1, doc.scrollHeight - window.innerHeight);
+  return {
+    scrollY,
+    maxScroll,
+    progress: clamp(scrollY / maxScroll, 0, 1),
+  };
+}
+
+/**
+ * Ease-out cubic for natural deceleration.
+ */
+export function easeOutCubic(t) {
+  return 1 - Math.pow(1 - t, 3);
+}
+
+const NAV_KEYS = new Set([
+  'ArrowUp',
+  'ArrowDown',
+  'PageUp',
+  'PageDown',
+  'Home',
+  'End',
+  ' ',
+  'Spacebar',
+]);
+
+/**
+ * Animate window scroll from current position to top.
+ * User wheel / touch / nav keys / scrollbar drag will interrupt and call onInterrupt.
+ *
+ * @param {object} options
+ * @param {number} options.durationMs
+ * @param {(t: number, scrollY: number) => void} options.onUpdate - t in [0,1]
+ * @param {() => void} options.onComplete
+ * @param {(reason: string) => void} options.onInterrupt
+ * @returns {() => void} cancel function
+ */
+export function animateScrollToTop({
+  durationMs = 1400,
+  onUpdate,
+  onComplete,
+  onInterrupt,
+} = {}) {
+  const startY = window.scrollY || document.documentElement.scrollTop || 0;
+  if (startY <= 0) {
+    onUpdate?.(1, 0);
+    onComplete?.();
+    return () => {};
+  }
+
+  const startTime = performance.now();
+  let rafId = 0;
+  let cancelled = false;
+  let finished = false;
+  let expectedY = startY;
+  let programmatic = false;
+  let clearProgrammaticId = 0;
+
+  const cleanup = () => {
+    window.removeEventListener('scroll', onScrollCheck, true);
+    window.removeEventListener('wheel', onUserInput, true);
+    window.removeEventListener('touchmove', onUserInput, true);
+    window.removeEventListener('keydown', onKeyInterrupt, true);
+    if (clearProgrammaticId) cancelAnimationFrame(clearProgrammaticId);
+  };
+
+  const stop = (reason, interrupted) => {
+    if (cancelled || finished) return;
+    cancelled = true;
+    if (rafId) cancelAnimationFrame(rafId);
+    rafId = 0;
+    cleanup();
+    if (interrupted) {
+      onInterrupt?.(reason);
+    }
+  };
+
+  const onUserInput = () => {
+    stop('pointer', true);
+  };
+
+  const onKeyInterrupt = (e) => {
+    if (NAV_KEYS.has(e.key)) stop('keydown', true);
+  };
+
+  const onScrollCheck = () => {
+    if (cancelled || finished || programmatic) return;
+    const actual = window.scrollY || document.documentElement.scrollTop || 0;
+    // Scrollbar drag or other external scroll fighting the animation
+    if (Math.abs(actual - expectedY) > 6) {
+      stop('scroll', true);
+    }
+  };
+
+  const tick = (now) => {
+    if (cancelled) return;
+
+    const elapsed = now - startTime;
+    const t = clamp(elapsed / durationMs, 0, 1);
+    const eased = easeOutCubic(t);
+    const nextY = startY * (1 - eased);
+
+    programmatic = true;
+    expectedY = nextY;
+    window.scrollTo(0, nextY);
+    if (clearProgrammaticId) cancelAnimationFrame(clearProgrammaticId);
+    clearProgrammaticId = requestAnimationFrame(() => {
+      programmatic = false;
+      clearProgrammaticId = 0;
+    });
+
+    onUpdate?.(t, nextY);
+
+    if (t < 1) {
+      rafId = requestAnimationFrame(tick);
+    } else {
+      finished = true;
+      programmatic = true;
+      expectedY = 0;
+      window.scrollTo(0, 0);
+      cleanup();
+      onUpdate?.(1, 0);
+      onComplete?.();
+    }
+  };
+
+  window.addEventListener('scroll', onScrollCheck, { passive: true, capture: true });
+  window.addEventListener('wheel', onUserInput, { passive: true, capture: true });
+  window.addEventListener('touchmove', onUserInput, { passive: true, capture: true });
+  window.addEventListener('keydown', onKeyInterrupt, { capture: true });
+
+  rafId = requestAnimationFrame(tick);
+
+  return () => {
+    stop('cancel', false);
+  };
+}

package/types/index.d.ts

@@ -0,0 +1,56 @@
+export interface RocketLaunchDetail {
+  fuel: number;
+  scrollY: number;
+}
+
+export interface RocketPauseDetail {
+  reason: string;
+  scrollY: number;
+  fuel: number;
+}
+
+export declare class RocketToTop extends HTMLElement {
+  static readonly observedAttributes: string[];
+
+  threshold: number;
+  position: 'left' | 'right';
+  size: number;
+
+  /** Start launch / smooth scroll to top */
+  launch(): void;
+
+  /** Interrupt launch and restore user scroll control */
+  pause(reason?: string): void;
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'rocket-to-top': RocketToTop;
+  }
+
+  interface HTMLElementEventMap {
+    'rocket-launch': CustomEvent<RocketLaunchDetail>;
+    'rocket-arrive': CustomEvent<void>;
+    'rocket-pause': CustomEvent<RocketPauseDetail>;
+  }
+}
+
+/** React / JSX consumers (optional, no react dependency required) */
+declare namespace JSX {
+  interface IntrinsicElements {
+    'rocket-to-top': {
+      threshold?: string | number;
+      position?: 'left' | 'right';
+      size?: string | number;
+      children?: unknown;
+      class?: string;
+      className?: string;
+      style?: unknown;
+      ref?: unknown;
+      key?: unknown;
+      [attr: string]: unknown;
+    };
+  }
+}
+
+export { RocketToTop as default };