@xingwangzhe/tags-cloud 0.5.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,78 @@
+# @xingwangzhe/tags-cloud
+
+[中文文档](README_CN.md) | [English](#)
+
+> Pure math 3D tag cloud engine
+
+## Features
+
+- **Zero DOM overhead** — pure math output, render via callback
+- **Fibonacci sphere distribution** — tags evenly placed on 3D sphere
+- **Arcball interaction** — drag to rotate with quaternion-based Shoemake arcball
+- **Auto-spin** — configurable per-axis spin (X/Y) with independent speed and direction
+- **TypeScript** — fully typed
+- **~2.3KB** gzipped
+
+## Install
+
+```bash
+bun add @xingwangzhe/tags-cloud
+```
+
+## Usage
+
+```ts
+import { TagCloud } from "@xingwangzhe/tags-cloud";
+
+// Zero config — auto-creates Canvas and renders text
+new TagCloud(document.getElementById("cloud"), {
+  tags: ["TypeScript", "Canvas", "3D"],
+  radius: 300,
+});
+```
+
+## API
+
+### `new TagCloud(container, options)`
+
+| Option            | Type             | Default         | Description                     |
+| ----------------- | ---------------- | --------------- | ------------------------------- |
+| `tags`            | `string[]`       | —               | Tag text list                   |
+| `radius`          | `number`         | `300`           | Sphere radius (px)              |
+| `spinY`           | `number`         | `0`             | Y-axis spin: +right -left 0=off |
+| `spinX`           | `number`         | `0`             | X-axis spin: +down -up 0=off    |
+| `reverse`         | `boolean`        | `false`         | Reverse both drag axes          |
+| `reverseX`        | `boolean`        | `false`         | Reverse X-axis drag only        |
+| `reverseY`        | `boolean`        | `false`         | Reverse Y-axis drag only        |
+| `inertiaDecay`    | `number`         | `0.96`          | Inertia decay per frame         |
+| `dragSensitivity` | `number`         | `3`             | Drag sensitivity multiplier     |
+| `fontFamily`      | `string`         | `system-ui`     | Font family                     |
+| `fontSize`        | `number`         | `14`            | Base font size (px)             |
+| `color`           | `string`         | `#fff`          | Text color                      |
+| `onRender`        | `(tags) => void` | built-in Canvas | Custom render callback          |
+
+### Instance Methods
+
+```ts
+cloud.setTags(["new", "tags"]); // Update tags
+cloud.pause(); // Pause
+cloud.resume(); // Resume
+cloud.destroy(); // Destroy (cleanup events + rAF)
+```
+
+## Development
+
+```bash
+bun install
+bun run build    # vite build
+bun run lint     # oxlint
+bun run fmt      # oxfmt
+```
+
+## Credits
+
+Core algorithm ported from [cong-min/TagCloud](https://github.com/cong-min/TagCloud)
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,239 @@
+//#region src/core/distribution.ts
+function e(e, t) {
+	let n = [];
+	for (let r = 0; r < e; r++) {
+		let i = Math.acos(-1 + (2 * r + 1) / e), a = Math.sqrt(e * Math.PI) * i;
+		n.push({
+			x: t * Math.cos(a) * Math.sin(i),
+			y: t * Math.sin(a) * Math.sin(i),
+			z: t * Math.cos(i)
+		});
+	}
+	return n;
+}
+//#endregion
+//#region src/TagCloud.ts
+var t = {
+	radius: 300,
+	spinY: 0,
+	spinX: 0,
+	reverse: !1,
+	reverseX: !1,
+	reverseY: !1,
+	inertiaDecay: .96,
+	dragSensitivity: 3,
+	fontFamily: "system-ui, sans-serif",
+	fontSize: 14,
+	color: "#ffffff"
+}, n = class {
+	#e;
+	#t = [];
+	#n;
+	#r;
+	#i = {
+		w: 1,
+		x: 0,
+		y: 0,
+		z: 0
+	};
+	#a = {
+		w: 1,
+		x: 0,
+		y: 0,
+		z: 0
+	};
+	#o = 0;
+	#s = 0;
+	#c = !1;
+	#l = !1;
+	#u = {
+		x: 0,
+		y: 0,
+		z: 0
+	};
+	#d = 0;
+	#f;
+	#p;
+	#m;
+	#h;
+	constructor(e, n) {
+		this.#f = e, this.#e = {
+			...t,
+			...n
+		}, this.#n = this.#e.radius, this.#r = 2 * this.#n, this.#e.onRender || (this.#e.onRender = this.#g), this.#v(this.#e.tags), this.#y(), this.#x();
+	}
+	#g = (e) => {
+		if (!this.#m) {
+			let e = document.createElement("canvas");
+			e.style.width = "100%", e.style.height = "100%", this.#f.appendChild(e), this.#m = e, this.#h = e.getContext("2d"), this.#_();
+		}
+		let { width: t, height: n } = this.#m.getBoundingClientRect(), r = this.#h;
+		r.clearRect(0, 0, t, n);
+		let { fontFamily: i, fontSize: a, color: o } = this.#e;
+		for (let t of e) r.save(), r.globalAlpha = t.alpha, r.font = `${a + t.scale * 5}px ${i}`, r.fillStyle = o, r.textAlign = "center", r.textBaseline = "middle", r.fillText(t.text, t.x, t.y), r.restore();
+	};
+	#_() {
+		let e = this.#m;
+		if (!e) return;
+		let t = window.devicePixelRatio || 1, { width: n, height: r } = e.getBoundingClientRect();
+		e.width = n * t, e.height = r * t, this.#h.setTransform(t, 0, 0, t, 0, 0);
+	}
+	setTags(e) {
+		this.#v(e);
+	}
+	pause() {
+		this.#c = !0;
+	}
+	resume() {
+		this.#c = !1;
+	}
+	destroy() {
+		cancelAnimationFrame(this.#d);
+		let e = this.#p;
+		this.#f.removeEventListener("pointerdown", e.down), window.removeEventListener("pointermove", e.move), window.removeEventListener("pointerup", e.up), this.#m && this.#m.remove();
+	}
+	#v(t) {
+		let n = 1.5 * this.#n, r = e(t.length, n / 2);
+		this.#t = r.map((e, n) => ({
+			...e,
+			text: t[n]
+		}));
+	}
+	#y() {
+		this.#f.style.cursor = "grab";
+		let e = () => this.#f.getBoundingClientRect();
+		this.#p = {
+			down: ((t) => {
+				this.#l = !0, this.#f.style.cursor = "grabbing", this.#a = { ...this.#i };
+				let n = e();
+				this.#u = this.#b(t.clientX - n.left, t.clientY - n.top, n.width, n.height), this.#o = 0, this.#s = 0;
+			}),
+			move: ((t) => {
+				if (!this.#l) return;
+				let n = e(), r = this.#b(t.clientX - n.left, t.clientY - n.top, n.width, n.height), i = this.#u, a = i.x * r.x + i.y * r.y + i.z * r.z, o = this.#e.reverse || this.#e.reverseX ? -1 : 1, s = this.#e.reverse || this.#e.reverseY ? -1 : 1, c = {
+					w: 1 + a,
+					x: (i.y * r.z - i.z * r.y) * o,
+					y: (i.x * r.z - i.z * r.x) * s,
+					z: (i.x * r.y - i.y * r.x) * o * s
+				}, l = Math.sqrt(c.w ** 2 + c.x ** 2 + c.y ** 2 + c.z ** 2);
+				c.w /= l, c.x /= l, c.y /= l, c.z /= l;
+				let u = this.#a;
+				this.#i = {
+					w: c.w * u.w - c.x * u.x - c.y * u.y - c.z * u.z,
+					x: c.w * u.x + c.x * u.w + c.y * u.z - c.z * u.y,
+					y: c.w * u.y - c.x * u.z + c.y * u.w + c.z * u.x,
+					z: c.w * u.z + c.x * u.y - c.y * u.x + c.z * u.w
+				};
+				let d = this.#e.dragSensitivity;
+				this.#o = c.y / l * d, this.#s = c.x / l * d;
+			}),
+			up: () => {
+				this.#l = !1, this.#f.style.cursor = "grab";
+			}
+		}, this.#f.addEventListener("pointerdown", this.#p.down), window.addEventListener("pointermove", this.#p.move), window.addEventListener("pointerup", this.#p.up);
+	}
+	#b(e, t, n, r) {
+		let i = e / n * 2 - 1, a = -(t / r * 2 - 1), o = i * i + a * a;
+		if (o > 1) {
+			let e = 1 / Math.sqrt(o);
+			return {
+				x: i * e,
+				y: a * e,
+				z: 0
+			};
+		}
+		return {
+			x: i,
+			y: a,
+			z: Math.sqrt(1 - o)
+		};
+	}
+	#x = () => {
+		this.#c || this.#w(), this.#d = requestAnimationFrame(this.#x);
+	};
+	#S(e) {
+		let t = e * Math.PI / 360, n = {
+			w: Math.cos(t),
+			x: 0,
+			y: Math.sin(t),
+			z: 0
+		}, r = this.#i;
+		this.#i = {
+			w: n.w * r.w - n.y * r.y,
+			x: n.w * r.x + n.y * r.z,
+			y: n.w * r.y + n.y * r.w,
+			z: n.w * r.z - n.y * r.x
+		};
+	}
+	#C(e) {
+		let t = e * Math.PI / 360, n = {
+			w: Math.cos(t),
+			x: Math.sin(t),
+			y: 0,
+			z: 0
+		}, r = this.#i;
+		this.#i = {
+			w: n.w * r.w - n.x * r.x,
+			x: n.w * r.x + n.x * r.w,
+			y: n.w * r.y - n.x * r.z,
+			z: n.w * r.z + n.x * r.y
+		};
+	}
+	#w() {
+		let e = this.#f.getBoundingClientRect(), t = e.width / 2, n = e.height / 2, r = this.#e.reverse || this.#e.reverseY ? -1 : 1, i = this.#e.reverse || this.#e.reverseX ? -1 : 1, a = this.#e.inertiaDecay;
+		this.#l || (this.#S((this.#e.spinY + this.#o) * r), this.#C((this.#e.spinX + this.#s) * i), this.#o *= a, this.#s *= a);
+		let { w: o, x: s, y: c, z: l } = this.#i, u = 1 - 2 * (c * c + l * l), d = 2 * (s * c - o * l), f = 2 * (s * l + o * c), p = 2 * (s * c + o * l), m = 1 - 2 * (s * s + l * l), h = 2 * (c * l - o * s), g = 2 * (s * l - o * c), _ = 2 * (c * l + o * s), v = this.#r * 2, y = [];
+		for (let e of this.#t) {
+			let r = u * e.x + d * e.y + f * e.z, i = p * e.x + m * e.y + h * e.z, a = g * e.x + _ * e.y + (1 - 2 * (s * s + c * c)) * e.z, o = v / (v + a), l = Math.min(1, Math.max(0, o * o - .25));
+			y.push({
+				text: e.text,
+				x: t + r * o,
+				y: n + i * o,
+				z: a,
+				scale: o,
+				alpha: l
+			});
+		}
+		this.#e.onRender(y.sort((e, t) => t.z - e.z));
+	}
+};
+//#endregion
+//#region src/core/rotation.ts
+function r(e, t, n) {
+	let r = Math.sin(t), i = Math.cos(t), a = Math.sin(n), o = Math.cos(n), s = e.y * i + e.z * -r, c = e.y * r + e.z * i;
+	return {
+		x: e.x * o + c * a,
+		y: s,
+		z: c * o - e.x * a
+	};
+}
+function i(e, t, n) {
+	let r = Math.sin(t), i = Math.cos(t), a = Math.sin(n), o = Math.cos(n);
+	return e.map((e) => {
+		let t = e.y * i + e.z * -r, n = e.y * r + e.z * i;
+		return {
+			x: e.x * o + n * a,
+			y: t,
+			z: n * o - e.x * a
+		};
+	});
+}
+//#endregion
+//#region src/core/projection.ts
+function a(e, t) {
+	let n = 2 * t;
+	return e.map((e) => {
+		let t = n / (n + e.z), r = Math.min(1, Math.max(0, t * t - .25));
+		return {
+			x: e.x,
+			y: e.y,
+			z: e.z,
+			scale: t,
+			alpha: r
+		};
+	});
+}
+//#endregion
+export { n as TagCloud, e as fibonacciSphere, a as project, r as rotatePoint, i as rotatePoints };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["#container","#opts","#radius","#depth","#canvasRender","#initTags","#bindEvents","#loop","#canvas","#ctx","#resizeCanvas","#paused","#raf","#handlers","#points","#dragging","#qDown","#qNow","#vDown","#screenToSphere","#velY","#velX","#tick","#rotateY","#rotateX"],"sources":["../src/core/distribution.ts","../src/TagCloud.ts","../src/core/rotation.ts","../src/core/projection.ts"],"sourcesContent":["/**\n * 斐波那契球面分布\n * Fibonacci sphere distribution\n *\n * 将 N 个点均匀分布在球面上，避免两极聚集\n * Evenly distributes N points on a sphere, avoiding polar clustering\n *\n * ported from TagCloud.js _computePosition\n */\n\nexport interface Vec3 {\n  x: number;\n  y: number;\n  z: number;\n}\n\n/**\n * 生成球面上均匀分布的 N 个点\n * Generate N evenly distributed points on a sphere of radius R\n */\nexport function fibonacciSphere(n: number, R: number): Vec3[] {\n  const points: Vec3[] = [];\n  for (let i = 0; i < n; i++) {\n    // φ = acos(1 - 2(i+0.5)/N) — 纬度均匀分布\n    // φ = acos(1 - 2(i+0.5)/N) — uniform latitude\n    const phi = Math.acos(-1 + (2 * i + 1) / n);\n    // θ = √(Nπ) × φ — 经度黄金比例螺旋\n    // θ = √(Nπ) × φ — golden ratio spiral for longitude\n    const theta = Math.sqrt(n * Math.PI) * phi;\n    points.push({\n      x: R * Math.cos(theta) * Math.sin(phi),\n      y: R * Math.sin(theta) * Math.sin(phi),\n      z: R * Math.cos(phi),\n    });\n  }\n  return points;\n}\n","/**\n * 3D 标签云 — 纯数学引擎\n * 3D Tag Cloud — Pure Math Engine\n *\n * 零 DOM 渲染，每帧通过 onRender 回调输出投影坐标\n * Zero DOM rendering, outputs projected coords via onRender callback each frame\n *\n * 基于 cong-min/TagCloud 算法\n * Based on cong-min/TagCloud algorithm\n */\nimport { fibonacciSphere } from \"./core/distribution\";\n\n// ── 类型\n// ── Types\n\n/** 投影后的标签数据 */\n/** Projected tag data */\nexport interface TagData {\n  text: string;\n  /** 容器内 X 坐标（像素） */\n  /** X coordinate in container (px) */\n  x: number;\n  /** 容器内 Y 坐标（像素） */\n  /** Y coordinate in container (px) */\n  y: number;\n  /** Z 深度（-radius ~ +radius） */\n  /** Z depth */\n  z: number;\n  /** 缩放比例 (0 ~ 1+) */\n  /** scale factor */\n  scale: number;\n  /** 透明度 (0 ~ 1) */\n  /** opacity */\n  alpha: number;\n}\n\nexport interface TagCloudOptions {\n  /** 标签文本数组 */\n  /** tag text array */\n  tags: string[];\n  /** 球面半径（px） */\n  /** sphere radius (px) (default 300) */\n  radius?: number;\n  /** 绕 Y 轴自旋速度（°/帧）: +右转 -左转 0=关 */\n  /** Y-axis auto-spin speed (°/frame): +right -left 0=off (default 0) */\n  spinY?: number;\n  /** 绕 X 轴自旋速度（°/帧）: +下转 -上转 0=关 */\n  /** X-axis auto-spin speed (°/frame): +down -up 0=off (default 0) */\n  spinX?: number;\n  /** 反转方向（X+Y 同时） */\n  /** reverse both axes (default false) */\n  reverse?: boolean;\n  /** 单独反转 X 轴（上下拖拽） */\n  /** reverse X-axis drag only (default false) */\n  reverseX?: boolean;\n  /** 反转 Y 轴拖拽方向 */\n  /** reverse Y-axis drag direction (default false) */\n  reverseY?: boolean;\n  /** 惯性衰减系数（每帧乘以此值） */\n  /** inertia decay per frame (default 0.96) */\n  inertiaDecay?: number;\n  /** 拖拽灵敏度（松手后惯性速度倍率） */\n  /** drag sensitivity for release velocity (default 3) */\n  dragSensitivity?: number;\n  /** 字体 */\n  /** font family (default \"system-ui, sans-serif\") */\n  fontFamily?: string;\n  /** 基础字号（px） */\n  /** base font size in px (default 14) */\n  fontSize?: number;\n  /** 文字颜色 */\n  /** text color (default \"#ffffff\") */\n  color?: string;\n  /** 自定义渲染回调（如不提供则用内置 Canvas） */\n  /** custom render callback (built-in Canvas if omitted) */\n  onRender?: (tags: TagData[]) => void;\n}\n\n// ── 内部类型\n// ── Internal Types\n\ninterface SpherePoint {\n  x: number;\n  y: number;\n  z: number;\n  text: string;\n}\n\ntype ResolvedOptions = TagCloudOptions & Required<Omit<TagCloudOptions, \"onRender\">>;\n\nconst DEFAULTS: Omit<ResolvedOptions, \"tags\" | \"onRender\"> = {\n  radius: 300,\n  spinY: 0,\n  spinX: 0,\n  reverse: false,\n  reverseX: false,\n  reverseY: false,\n  inertiaDecay: 0.96,\n  dragSensitivity: 3,\n  fontFamily: \"system-ui, sans-serif\",\n  fontSize: 14,\n  color: \"#ffffff\",\n};\n\n// ── 主类\n// ── Main Class\n\nexport class TagCloud {\n  #opts: ResolvedOptions;\n  #points: SpherePoint[] = [];\n  #radius: number;\n  #depth: number;\n\n  // 旋转状态 — 四元数\n  // rotation state as quaternion\n  #qNow = { w: 1, x: 0, y: 0, z: 0 };\n  #qDown = { w: 1, x: 0, y: 0, z: 0 };\n  #velY = 0;\n  #velX = 0;\n  #paused = false;\n\n  // 拖拽状态\n  // arcball drag state\n  #dragging = false;\n  #vDown = { x: 0, y: 0, z: 0 };\n\n  // 动画\n  // animation\n  #raf = 0;\n  #container: HTMLElement;\n  #handlers!: { down: EventListener; move: EventListener; up: EventListener };\n\n  // 内置 Canvas（仅当 onRender 未提供时创建）\n  // built-in Canvas (only when onRender is not provided)\n  #canvas?: HTMLCanvasElement;\n  #ctx?: CanvasRenderingContext2D;\n\n  constructor(container: HTMLElement, options: TagCloudOptions) {\n    this.#container = container;\n    this.#opts = { ...DEFAULTS, ...options } as ResolvedOptions;\n    this.#radius = this.#opts.radius;\n    this.#depth = 2 * this.#radius;\n\n    // 内置 Canvas 渲染器\n    // built-in Canvas renderer\n    if (!this.#opts.onRender) {\n      this.#opts.onRender = this.#canvasRender;\n    }\n\n    this.#initTags(this.#opts.tags);\n    this.#bindEvents();\n    this.#loop();\n  }\n\n  /** 内置 Canvas 渲染器 */\n  /** Built-in Canvas renderer */\n  #canvasRender = (tags: TagData[]): void => {\n    if (!this.#canvas) {\n      const c = document.createElement(\"canvas\");\n      c.style.width = \"100%\";\n      c.style.height = \"100%\";\n      this.#container.appendChild(c);\n      this.#canvas = c;\n      this.#ctx = c.getContext(\"2d\")!;\n      this.#resizeCanvas();\n    }\n    const { width, height } = this.#canvas.getBoundingClientRect();\n    const ctx = this.#ctx!;\n    ctx.clearRect(0, 0, width, height);\n    const { fontFamily, fontSize, color } = this.#opts;\n    for (const t of tags) {\n      ctx.save();\n      ctx.globalAlpha = t.alpha;\n      ctx.font = `${fontSize + t.scale * 5}px ${fontFamily}`;\n      ctx.fillStyle = color;\n      ctx.textAlign = \"center\";\n      ctx.textBaseline = \"middle\";\n      ctx.fillText(t.text, t.x, t.y);\n      ctx.restore();\n    }\n  };\n\n  #resizeCanvas(): void {\n    const c = this.#canvas;\n    if (!c) return;\n    const dpr = window.devicePixelRatio || 1;\n    const { width, height } = c.getBoundingClientRect();\n    c.width = width * dpr;\n    c.height = height * dpr;\n    this.#ctx!.setTransform(dpr, 0, 0, dpr, 0, 0);\n  }\n\n  // ── 公开 API\n  // ── Public API\n\n  setTags(tags: string[]): void {\n    this.#initTags(tags);\n  }\n  pause(): void {\n    this.#paused = true;\n  }\n  resume(): void {\n    this.#paused = false;\n  }\n\n  destroy(): void {\n    cancelAnimationFrame(this.#raf);\n    const h = this.#handlers;\n    this.#container.removeEventListener(\"pointerdown\", h.down);\n    window.removeEventListener(\"pointermove\", h.move);\n    window.removeEventListener(\"pointerup\", h.up);\n    if (this.#canvas) this.#canvas.remove();\n  }\n\n  // ── 内部方法\n  // ── Internal\n\n  #initTags(tags: string[]): void {\n    const size = 1.5 * this.#radius;\n    const positions = fibonacciSphere(tags.length, size / 2);\n    this.#points = positions.map((p, i) => ({ ...p, text: tags[i]! }));\n  }\n\n  #bindEvents(): void {\n    this.#container.style.cursor = \"grab\";\n\n    const rect = () => this.#container.getBoundingClientRect();\n\n    this.#handlers = {\n      down: ((e: PointerEvent) => {\n        this.#dragging = true;\n        this.#container.style.cursor = \"grabbing\";\n        this.#qDown = { ...this.#qNow };\n        const r = rect();\n        this.#vDown = this.#screenToSphere(\n          e.clientX - r.left,\n          e.clientY - r.top,\n          r.width,\n          r.height,\n        );\n        this.#velY = 0;\n        this.#velX = 0;\n      }) as EventListener,\n      move: ((e: PointerEvent) => {\n        if (!this.#dragging) return;\n        const r = rect();\n        const vCur = this.#screenToSphere(e.clientX - r.left, e.clientY - r.top, r.width, r.height);\n        const vA = this.#vDown;\n        const dot = vA.x * vCur.x + vA.y * vCur.y + vA.z * vCur.z;\n        // Shoemake arcball 四元数\n        // Shoemake arcball quaternion\n        const revX = this.#opts.reverse || this.#opts.reverseX ? -1 : 1;\n        const revY = this.#opts.reverse || this.#opts.reverseY ? -1 : 1;\n        const qDrag = {\n          w: 1 + dot,\n          x: (vA.y * vCur.z - vA.z * vCur.y) * revX,\n          y: (vA.x * vCur.z - vA.z * vCur.x) * revY,\n          z: (vA.x * vCur.y - vA.y * vCur.x) * revX * revY,\n        };\n        const len = Math.sqrt(qDrag.w ** 2 + qDrag.x ** 2 + qDrag.y ** 2 + qDrag.z ** 2);\n        qDrag.w /= len;\n        qDrag.x /= len;\n        qDrag.y /= len;\n        qDrag.z /= len;\n        // 组合\n        // compose\n        const qD = this.#qDown;\n        this.#qNow = {\n          w: qDrag.w * qD.w - qDrag.x * qD.x - qDrag.y * qD.y - qDrag.z * qD.z,\n          x: qDrag.w * qD.x + qDrag.x * qD.w + qDrag.y * qD.z - qDrag.z * qD.y,\n          y: qDrag.w * qD.y - qDrag.x * qD.z + qDrag.y * qD.w + qDrag.z * qD.x,\n          z: qDrag.w * qD.z + qDrag.x * qD.y - qDrag.y * qD.x + qDrag.z * qD.w,\n        };\n        // 拖拽速度\n        // drag velocity\n        const sens = this.#opts.dragSensitivity;\n        this.#velY = (qDrag.y / len) * sens;\n        this.#velX = (qDrag.x / len) * sens;\n      }) as EventListener,\n      up: () => {\n        this.#dragging = false;\n        this.#container.style.cursor = \"grab\";\n      },\n    };\n\n    this.#container.addEventListener(\"pointerdown\", this.#handlers.down);\n    window.addEventListener(\"pointermove\", this.#handlers.move);\n    window.addEventListener(\"pointerup\", this.#handlers.up);\n  }\n\n  /** 屏幕坐标 → 球面 3D 点 */\n  /** screen coords → sphere 3D point */\n  #screenToSphere(\n    sx: number,\n    sy: number,\n    w: number,\n    h: number,\n  ): { x: number; y: number; z: number } {\n    const x = (sx / w) * 2 - 1;\n    const y = -((sy / h) * 2 - 1);\n    const r2 = x * x + y * y;\n    if (r2 > 1) {\n      // 球外 → 投影到球边缘\n      // outside sphere → project to edge\n      const inv = 1 / Math.sqrt(r2);\n      return { x: x * inv, y: y * inv, z: 0 };\n    }\n    return { x, y, z: Math.sqrt(1 - r2) };\n  }\n\n  #loop = (): void => {\n    if (!this.#paused) this.#tick();\n    this.#raf = requestAnimationFrame(this.#loop);\n  };\n\n  /** 绕 Y 轴旋转 */\n  /** rotate around Y axis */\n  #rotateY(deg: number): void {\n    const half = (deg * Math.PI) / 360;\n    const qY = { w: Math.cos(half), x: 0, y: Math.sin(half), z: 0 };\n    const q = this.#qNow;\n    this.#qNow = {\n      w: qY.w * q.w - qY.y * q.y,\n      x: qY.w * q.x + qY.y * q.z,\n      y: qY.w * q.y + qY.y * q.w,\n      z: qY.w * q.z - qY.y * q.x,\n    };\n  }\n\n  /** 绕 X 轴旋转 */\n  /** rotate around X axis */\n  #rotateX(deg: number): void {\n    const half = (deg * Math.PI) / 360;\n    const qX = { w: Math.cos(half), x: Math.sin(half), y: 0, z: 0 };\n    const q = this.#qNow;\n    this.#qNow = {\n      w: qX.w * q.w - qX.x * q.x,\n      x: qX.w * q.x + qX.x * q.w,\n      y: qX.w * q.y - qX.x * q.z,\n      z: qX.w * q.z + qX.x * q.y,\n    };\n  }\n\n  #tick(): void {\n    const rect = this.#container.getBoundingClientRect();\n    const cx = rect.width / 2;\n    const cy = rect.height / 2;\n\n    // 自旋 + 惯性\n    // auto-spin + inertia\n    const revY = this.#opts.reverse || this.#opts.reverseY ? -1 : 1;\n    const revX = this.#opts.reverse || this.#opts.reverseX ? -1 : 1;\n    const decay = this.#opts.inertiaDecay;\n    if (!this.#dragging) {\n      this.#rotateY((this.#opts.spinY + this.#velY) * revY);\n      this.#rotateX((this.#opts.spinX + this.#velX) * revX);\n      this.#velY *= decay;\n      this.#velX *= decay;\n    }\n\n    // 四元数构造 3×3 旋转矩阵\n    // build 3×3 rotation matrix from quaternion\n    const { w, x, y, z } = this.#qNow;\n    const m00 = 1 - 2 * (y * y + z * z);\n    const m01 = 2 * (x * y - w * z);\n    const m02 = 2 * (x * z + w * y);\n    const m10 = 2 * (x * y + w * z);\n    const m11 = 1 - 2 * (x * x + z * z);\n    const m12 = 2 * (y * z - w * x);\n    const m20 = 2 * (x * z - w * y);\n    const m21 = 2 * (y * z + w * x);\n\n    const d2 = this.#depth * 2;\n    const projected: TagData[] = [];\n\n    for (const p of this.#points) {\n      // 矩阵 × 点\n      // matrix × point\n      const rx = m00 * p.x + m01 * p.y + m02 * p.z;\n      const ry = m10 * p.x + m11 * p.y + m12 * p.z;\n      const rz = m20 * p.x + m21 * p.y + (1 - 2 * (x * x + y * y)) * p.z;\n\n      const per = d2 / (d2 + rz);\n      const alpha = Math.min(1, Math.max(0, per * per - 0.25));\n\n      projected.push({\n        text: p.text,\n        x: cx + rx * per,\n        y: cy + ry * per,\n        z: rz,\n        scale: per,\n        alpha,\n      });\n    }\n\n    this.#opts.onRender(projected.sort((a, b) => b.z - a.z));\n  }\n}\n\nexport default TagCloud;\n","/**\n * 3D 旋转变换\n * 3D rotation transforms\n *\n * 绕 Y 轴和 X 轴旋转球面上的所有点\n * Rotates all points around Y and X axes\n *\n * ported from TagCloud.js _next() rotation logic\n */\n\nimport type { Vec3 } from \"./distribution\";\n\n/**\n * 旋转单个 3D 点\n * Rotate a single 3D point\n *\n * @param p - 待旋转的点\n * @param p - point to rotate\n * @param a - 绕 Y 轴的旋转角（弧度）\n * @param a - Y-axis rotation angle (radians)\n * @param b - 绕 X 轴的旋转角（弧度）\n * @param b - X-axis rotation angle (radians)\n */\nexport function rotatePoint(p: Vec3, a: number, b: number): Vec3 {\n  const sinA = Math.sin(a);\n  const cosA = Math.cos(a);\n  const sinB = Math.sin(b);\n  const cosB = Math.cos(b);\n\n  // Y 轴旋转\n  // Y-axis rotation\n  const y1 = p.y * cosA + p.z * -sinA;\n  const z1 = p.y * sinA + p.z * cosA;\n\n  // X 轴旋转\n  // X-axis rotation\n  const x2 = p.x * cosB + z1 * sinB;\n  const z2 = z1 * cosB - p.x * sinB;\n\n  return { x: x2, y: y1, z: z2 };\n}\n\n/**\n * 批量旋转所有点\n * Rotate all points in batch\n */\nexport function rotatePoints(points: Vec3[], a: number, b: number): Vec3[] {\n  const sinA = Math.sin(a);\n  const cosA = Math.cos(a);\n  const sinB = Math.sin(b);\n  const cosB = Math.cos(b);\n\n  return points.map((p) => {\n    const y1 = p.y * cosA + p.z * -sinA;\n    const z1 = p.y * sinA + p.z * cosA;\n    const x2 = p.x * cosB + z1 * sinB;\n    return { x: x2, y: y1, z: z1 * cosB - p.x * sinB };\n  });\n}\n","/**\n * 透视投影\n * Perspective projection\n *\n * 根据 Z 深度计算每个标签的缩放比例和透明度\n * Calculates scale and alpha for each tag based on Z depth\n *\n * per = (2 × depth) / (2 × depth + z)\n * scale = per\n * alpha = per² − 0.25 → clamped [0, 1]\n *\n * ported from TagCloud.js _next() projection logic\n */\n\nexport interface ProjectedTag {\n  /** 原始 X 坐标 */\n  /** original X coordinate */\n  x: number;\n  /** 原始 Y 坐标 */\n  /** original Y coordinate */\n  y: number;\n  /** 原始 Z 深度 */\n  /** original Z depth */\n  z: number;\n  /** 缩放比例 (1 = 最近, 0 = 最远) */\n  /** scale factor (1 = nearest, 0 = farthest) */\n  scale: number;\n  /** 透明度 (1 = 最前, 0 = 最后) */\n  /** opacity (1 = front, 0 = back) */\n  alpha: number;\n}\n\n/**\n * 对旋转后的点做透视投影\n * Apply perspective projection to rotated points\n *\n * @param points — 旋转后的 3D 点\n * @param points — rotated 3D points\n * @param depth — 透视深度 = 2 × 球半径\n * @param depth — perspective depth = 2 × sphere radius\n */\nexport function project(\n  points: { x: number; y: number; z: number }[],\n  depth: number,\n): ProjectedTag[] {\n  const d2 = 2 * depth;\n  return points.map((p) => {\n    // 透视缩放\n    // perspective scale\n    const per = d2 / (d2 + p.z);\n    // 透明度从 per² − 0.25 计算\n    // alpha derived from per² − 0.25\n    const alpha = Math.min(1, Math.max(0, per * per - 0.25));\n    return { x: p.x, y: p.y, z: p.z, scale: per, alpha };\n  });\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@xingwangzhe/tags-cloud",
+  "version": "0.5.0",
+  "description": "Canvas-driven 3D tag cloud engine",
+  "keywords": ["3d", "canvas", "sphere", "tag-cloud", "tags"],
+  "license": "MIT",
+  "files": ["dist", "src/core", "src/index.ts", "src/TagCloud.ts"],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "lint": "oxlint",
+    "prepublishOnly": "bun run build"
+  },
+  "devDependencies": {
+    "oxfmt": "^0.54.0",
+    "oxlint": "^1.69.0",
+    "vite": "^8.0.16"
+  }
+}

package/src/TagCloud.ts

@@ -0,0 +1,400 @@
+/**
+ * 3D 标签云 — 纯数学引擎
+ * 3D Tag Cloud — Pure Math Engine
+ *
+ * 零 DOM 渲染，每帧通过 onRender 回调输出投影坐标
+ * Zero DOM rendering, outputs projected coords via onRender callback each frame
+ *
+ * 基于 cong-min/TagCloud 算法
+ * Based on cong-min/TagCloud algorithm
+ */
+import { fibonacciSphere } from "./core/distribution";
+
+// ── 类型
+// ── Types
+
+/** 投影后的标签数据 */
+/** Projected tag data */
+export interface TagData {
+  text: string;
+  /** 容器内 X 坐标（像素） */
+  /** X coordinate in container (px) */
+  x: number;
+  /** 容器内 Y 坐标（像素） */
+  /** Y coordinate in container (px) */
+  y: number;
+  /** Z 深度（-radius ~ +radius） */
+  /** Z depth */
+  z: number;
+  /** 缩放比例 (0 ~ 1+) */
+  /** scale factor */
+  scale: number;
+  /** 透明度 (0 ~ 1) */
+  /** opacity */
+  alpha: number;
+}
+
+export interface TagCloudOptions {
+  /** 标签文本数组 */
+  /** tag text array */
+  tags: string[];
+  /** 球面半径（px） */
+  /** sphere radius (px) (default 300) */
+  radius?: number;
+  /** 绕 Y 轴自旋速度（°/帧）: +右转 -左转 0=关 */
+  /** Y-axis auto-spin speed (°/frame): +right -left 0=off (default 0) */
+  spinY?: number;
+  /** 绕 X 轴自旋速度（°/帧）: +下转 -上转 0=关 */
+  /** X-axis auto-spin speed (°/frame): +down -up 0=off (default 0) */
+  spinX?: number;
+  /** 反转方向（X+Y 同时） */
+  /** reverse both axes (default false) */
+  reverse?: boolean;
+  /** 单独反转 X 轴（上下拖拽） */
+  /** reverse X-axis drag only (default false) */
+  reverseX?: boolean;
+  /** 反转 Y 轴拖拽方向 */
+  /** reverse Y-axis drag direction (default false) */
+  reverseY?: boolean;
+  /** 惯性衰减系数（每帧乘以此值） */
+  /** inertia decay per frame (default 0.96) */
+  inertiaDecay?: number;
+  /** 拖拽灵敏度（松手后惯性速度倍率） */
+  /** drag sensitivity for release velocity (default 3) */
+  dragSensitivity?: number;
+  /** 字体 */
+  /** font family (default "system-ui, sans-serif") */
+  fontFamily?: string;
+  /** 基础字号（px） */
+  /** base font size in px (default 14) */
+  fontSize?: number;
+  /** 文字颜色 */
+  /** text color (default "#ffffff") */
+  color?: string;
+  /** 自定义渲染回调（如不提供则用内置 Canvas） */
+  /** custom render callback (built-in Canvas if omitted) */
+  onRender?: (tags: TagData[]) => void;
+}
+
+// ── 内部类型
+// ── Internal Types
+
+interface SpherePoint {
+  x: number;
+  y: number;
+  z: number;
+  text: string;
+}
+
+type ResolvedOptions = TagCloudOptions & Required<Omit<TagCloudOptions, "onRender">>;
+
+const DEFAULTS: Omit<ResolvedOptions, "tags" | "onRender"> = {
+  radius: 300,
+  spinY: 0,
+  spinX: 0,
+  reverse: false,
+  reverseX: false,
+  reverseY: false,
+  inertiaDecay: 0.96,
+  dragSensitivity: 3,
+  fontFamily: "system-ui, sans-serif",
+  fontSize: 14,
+  color: "#ffffff",
+};
+
+// ── 主类
+// ── Main Class
+
+export class TagCloud {
+  #opts: ResolvedOptions;
+  #points: SpherePoint[] = [];
+  #radius: number;
+  #depth: number;
+
+  // 旋转状态 — 四元数
+  // rotation state as quaternion
+  #qNow = { w: 1, x: 0, y: 0, z: 0 };
+  #qDown = { w: 1, x: 0, y: 0, z: 0 };
+  #velY = 0;
+  #velX = 0;
+  #paused = false;
+
+  // 拖拽状态
+  // arcball drag state
+  #dragging = false;
+  #vDown = { x: 0, y: 0, z: 0 };
+
+  // 动画
+  // animation
+  #raf = 0;
+  #container: HTMLElement;
+  #handlers!: { down: EventListener; move: EventListener; up: EventListener };
+
+  // 内置 Canvas（仅当 onRender 未提供时创建）
+  // built-in Canvas (only when onRender is not provided)
+  #canvas?: HTMLCanvasElement;
+  #ctx?: CanvasRenderingContext2D;
+
+  constructor(container: HTMLElement, options: TagCloudOptions) {
+    this.#container = container;
+    this.#opts = { ...DEFAULTS, ...options } as ResolvedOptions;
+    this.#radius = this.#opts.radius;
+    this.#depth = 2 * this.#radius;
+
+    // 内置 Canvas 渲染器
+    // built-in Canvas renderer
+    if (!this.#opts.onRender) {
+      this.#opts.onRender = this.#canvasRender;
+    }
+
+    this.#initTags(this.#opts.tags);
+    this.#bindEvents();
+    this.#loop();
+  }
+
+  /** 内置 Canvas 渲染器 */
+  /** Built-in Canvas renderer */
+  #canvasRender = (tags: TagData[]): void => {
+    if (!this.#canvas) {
+      const c = document.createElement("canvas");
+      c.style.width = "100%";
+      c.style.height = "100%";
+      this.#container.appendChild(c);
+      this.#canvas = c;
+      this.#ctx = c.getContext("2d")!;
+      this.#resizeCanvas();
+    }
+    const { width, height } = this.#canvas.getBoundingClientRect();
+    const ctx = this.#ctx!;
+    ctx.clearRect(0, 0, width, height);
+    const { fontFamily, fontSize, color } = this.#opts;
+    for (const t of tags) {
+      ctx.save();
+      ctx.globalAlpha = t.alpha;
+      ctx.font = `${fontSize + t.scale * 5}px ${fontFamily}`;
+      ctx.fillStyle = color;
+      ctx.textAlign = "center";
+      ctx.textBaseline = "middle";
+      ctx.fillText(t.text, t.x, t.y);
+      ctx.restore();
+    }
+  };
+
+  #resizeCanvas(): void {
+    const c = this.#canvas;
+    if (!c) return;
+    const dpr = window.devicePixelRatio || 1;
+    const { width, height } = c.getBoundingClientRect();
+    c.width = width * dpr;
+    c.height = height * dpr;
+    this.#ctx!.setTransform(dpr, 0, 0, dpr, 0, 0);
+  }
+
+  // ── 公开 API
+  // ── Public API
+
+  setTags(tags: string[]): void {
+    this.#initTags(tags);
+  }
+  pause(): void {
+    this.#paused = true;
+  }
+  resume(): void {
+    this.#paused = false;
+  }
+
+  destroy(): void {
+    cancelAnimationFrame(this.#raf);
+    const h = this.#handlers;
+    this.#container.removeEventListener("pointerdown", h.down);
+    window.removeEventListener("pointermove", h.move);
+    window.removeEventListener("pointerup", h.up);
+    if (this.#canvas) this.#canvas.remove();
+  }
+
+  // ── 内部方法
+  // ── Internal
+
+  #initTags(tags: string[]): void {
+    const size = 1.5 * this.#radius;
+    const positions = fibonacciSphere(tags.length, size / 2);
+    this.#points = positions.map((p, i) => ({ ...p, text: tags[i]! }));
+  }
+
+  #bindEvents(): void {
+    this.#container.style.cursor = "grab";
+
+    const rect = () => this.#container.getBoundingClientRect();
+
+    this.#handlers = {
+      down: ((e: PointerEvent) => {
+        this.#dragging = true;
+        this.#container.style.cursor = "grabbing";
+        this.#qDown = { ...this.#qNow };
+        const r = rect();
+        this.#vDown = this.#screenToSphere(
+          e.clientX - r.left,
+          e.clientY - r.top,
+          r.width,
+          r.height,
+        );
+        this.#velY = 0;
+        this.#velX = 0;
+      }) as EventListener,
+      move: ((e: PointerEvent) => {
+        if (!this.#dragging) return;
+        const r = rect();
+        const vCur = this.#screenToSphere(e.clientX - r.left, e.clientY - r.top, r.width, r.height);
+        const vA = this.#vDown;
+        const dot = vA.x * vCur.x + vA.y * vCur.y + vA.z * vCur.z;
+        // Shoemake arcball 四元数
+        // Shoemake arcball quaternion
+        const revX = this.#opts.reverse || this.#opts.reverseX ? -1 : 1;
+        const revY = this.#opts.reverse || this.#opts.reverseY ? -1 : 1;
+        const qDrag = {
+          w: 1 + dot,
+          x: (vA.y * vCur.z - vA.z * vCur.y) * revX,
+          y: (vA.x * vCur.z - vA.z * vCur.x) * revY,
+          z: (vA.x * vCur.y - vA.y * vCur.x) * revX * revY,
+        };
+        const len = Math.sqrt(qDrag.w ** 2 + qDrag.x ** 2 + qDrag.y ** 2 + qDrag.z ** 2);
+        qDrag.w /= len;
+        qDrag.x /= len;
+        qDrag.y /= len;
+        qDrag.z /= len;
+        // 组合
+        // compose
+        const qD = this.#qDown;
+        this.#qNow = {
+          w: qDrag.w * qD.w - qDrag.x * qD.x - qDrag.y * qD.y - qDrag.z * qD.z,
+          x: qDrag.w * qD.x + qDrag.x * qD.w + qDrag.y * qD.z - qDrag.z * qD.y,
+          y: qDrag.w * qD.y - qDrag.x * qD.z + qDrag.y * qD.w + qDrag.z * qD.x,
+          z: qDrag.w * qD.z + qDrag.x * qD.y - qDrag.y * qD.x + qDrag.z * qD.w,
+        };
+        // 拖拽速度
+        // drag velocity
+        const sens = this.#opts.dragSensitivity;
+        this.#velY = (qDrag.y / len) * sens;
+        this.#velX = (qDrag.x / len) * sens;
+      }) as EventListener,
+      up: () => {
+        this.#dragging = false;
+        this.#container.style.cursor = "grab";
+      },
+    };
+
+    this.#container.addEventListener("pointerdown", this.#handlers.down);
+    window.addEventListener("pointermove", this.#handlers.move);
+    window.addEventListener("pointerup", this.#handlers.up);
+  }
+
+  /** 屏幕坐标 → 球面 3D 点 */
+  /** screen coords → sphere 3D point */
+  #screenToSphere(
+    sx: number,
+    sy: number,
+    w: number,
+    h: number,
+  ): { x: number; y: number; z: number } {
+    const x = (sx / w) * 2 - 1;
+    const y = -((sy / h) * 2 - 1);
+    const r2 = x * x + y * y;
+    if (r2 > 1) {
+      // 球外 → 投影到球边缘
+      // outside sphere → project to edge
+      const inv = 1 / Math.sqrt(r2);
+      return { x: x * inv, y: y * inv, z: 0 };
+    }
+    return { x, y, z: Math.sqrt(1 - r2) };
+  }
+
+  #loop = (): void => {
+    if (!this.#paused) this.#tick();
+    this.#raf = requestAnimationFrame(this.#loop);
+  };
+
+  /** 绕 Y 轴旋转 */
+  /** rotate around Y axis */
+  #rotateY(deg: number): void {
+    const half = (deg * Math.PI) / 360;
+    const qY = { w: Math.cos(half), x: 0, y: Math.sin(half), z: 0 };
+    const q = this.#qNow;
+    this.#qNow = {
+      w: qY.w * q.w - qY.y * q.y,
+      x: qY.w * q.x + qY.y * q.z,
+      y: qY.w * q.y + qY.y * q.w,
+      z: qY.w * q.z - qY.y * q.x,
+    };
+  }
+
+  /** 绕 X 轴旋转 */
+  /** rotate around X axis */
+  #rotateX(deg: number): void {
+    const half = (deg * Math.PI) / 360;
+    const qX = { w: Math.cos(half), x: Math.sin(half), y: 0, z: 0 };
+    const q = this.#qNow;
+    this.#qNow = {
+      w: qX.w * q.w - qX.x * q.x,
+      x: qX.w * q.x + qX.x * q.w,
+      y: qX.w * q.y - qX.x * q.z,
+      z: qX.w * q.z + qX.x * q.y,
+    };
+  }
+
+  #tick(): void {
+    const rect = this.#container.getBoundingClientRect();
+    const cx = rect.width / 2;
+    const cy = rect.height / 2;
+
+    // 自旋 + 惯性
+    // auto-spin + inertia
+    const revY = this.#opts.reverse || this.#opts.reverseY ? -1 : 1;
+    const revX = this.#opts.reverse || this.#opts.reverseX ? -1 : 1;
+    const decay = this.#opts.inertiaDecay;
+    if (!this.#dragging) {
+      this.#rotateY((this.#opts.spinY + this.#velY) * revY);
+      this.#rotateX((this.#opts.spinX + this.#velX) * revX);
+      this.#velY *= decay;
+      this.#velX *= decay;
+    }
+
+    // 四元数构造 3×3 旋转矩阵
+    // build 3×3 rotation matrix from quaternion
+    const { w, x, y, z } = this.#qNow;
+    const m00 = 1 - 2 * (y * y + z * z);
+    const m01 = 2 * (x * y - w * z);
+    const m02 = 2 * (x * z + w * y);
+    const m10 = 2 * (x * y + w * z);
+    const m11 = 1 - 2 * (x * x + z * z);
+    const m12 = 2 * (y * z - w * x);
+    const m20 = 2 * (x * z - w * y);
+    const m21 = 2 * (y * z + w * x);
+
+    const d2 = this.#depth * 2;
+    const projected: TagData[] = [];
+
+    for (const p of this.#points) {
+      // 矩阵 × 点
+      // matrix × point
+      const rx = m00 * p.x + m01 * p.y + m02 * p.z;
+      const ry = m10 * p.x + m11 * p.y + m12 * p.z;
+      const rz = m20 * p.x + m21 * p.y + (1 - 2 * (x * x + y * y)) * p.z;
+
+      const per = d2 / (d2 + rz);
+      const alpha = Math.min(1, Math.max(0, per * per - 0.25));
+
+      projected.push({
+        text: p.text,
+        x: cx + rx * per,
+        y: cy + ry * per,
+        z: rz,
+        scale: per,
+        alpha,
+      });
+    }
+
+    this.#opts.onRender(projected.sort((a, b) => b.z - a.z));
+  }
+}
+
+export default TagCloud;

package/src/core/distribution.ts

@@ -0,0 +1,37 @@
+/**
+ * 斐波那契球面分布
+ * Fibonacci sphere distribution
+ *
+ * 将 N 个点均匀分布在球面上，避免两极聚集
+ * Evenly distributes N points on a sphere, avoiding polar clustering
+ *
+ * ported from TagCloud.js _computePosition
+ */
+
+export interface Vec3 {
+  x: number;
+  y: number;
+  z: number;
+}
+
+/**
+ * 生成球面上均匀分布的 N 个点
+ * Generate N evenly distributed points on a sphere of radius R
+ */
+export function fibonacciSphere(n: number, R: number): Vec3[] {
+  const points: Vec3[] = [];
+  for (let i = 0; i < n; i++) {
+    // φ = acos(1 - 2(i+0.5)/N) — 纬度均匀分布
+    // φ = acos(1 - 2(i+0.5)/N) — uniform latitude
+    const phi = Math.acos(-1 + (2 * i + 1) / n);
+    // θ = √(Nπ) × φ — 经度黄金比例螺旋
+    // θ = √(Nπ) × φ — golden ratio spiral for longitude
+    const theta = Math.sqrt(n * Math.PI) * phi;
+    points.push({
+      x: R * Math.cos(theta) * Math.sin(phi),
+      y: R * Math.sin(theta) * Math.sin(phi),
+      z: R * Math.cos(phi),
+    });
+  }
+  return points;
+}

package/src/core/projection.ts

@@ -0,0 +1,56 @@
+/**
+ * 透视投影
+ * Perspective projection
+ *
+ * 根据 Z 深度计算每个标签的缩放比例和透明度
+ * Calculates scale and alpha for each tag based on Z depth
+ *
+ * per = (2 × depth) / (2 × depth + z)
+ * scale = per
+ * alpha = per² − 0.25 → clamped [0, 1]
+ *
+ * ported from TagCloud.js _next() projection logic
+ */
+
+export interface ProjectedTag {
+  /** 原始 X 坐标 */
+  /** original X coordinate */
+  x: number;
+  /** 原始 Y 坐标 */
+  /** original Y coordinate */
+  y: number;
+  /** 原始 Z 深度 */
+  /** original Z depth */
+  z: number;
+  /** 缩放比例 (1 = 最近, 0 = 最远) */
+  /** scale factor (1 = nearest, 0 = farthest) */
+  scale: number;
+  /** 透明度 (1 = 最前, 0 = 最后) */
+  /** opacity (1 = front, 0 = back) */
+  alpha: number;
+}
+
+/**
+ * 对旋转后的点做透视投影
+ * Apply perspective projection to rotated points
+ *
+ * @param points — 旋转后的 3D 点
+ * @param points — rotated 3D points
+ * @param depth — 透视深度 = 2 × 球半径
+ * @param depth — perspective depth = 2 × sphere radius
+ */
+export function project(
+  points: { x: number; y: number; z: number }[],
+  depth: number,
+): ProjectedTag[] {
+  const d2 = 2 * depth;
+  return points.map((p) => {
+    // 透视缩放
+    // perspective scale
+    const per = d2 / (d2 + p.z);
+    // 透明度从 per² − 0.25 计算
+    // alpha derived from per² − 0.25
+    const alpha = Math.min(1, Math.max(0, per * per - 0.25));
+    return { x: p.x, y: p.y, z: p.z, scale: per, alpha };
+  });
+}

package/src/core/rotation.ts

@@ -0,0 +1,59 @@
+/**
+ * 3D 旋转变换
+ * 3D rotation transforms
+ *
+ * 绕 Y 轴和 X 轴旋转球面上的所有点
+ * Rotates all points around Y and X axes
+ *
+ * ported from TagCloud.js _next() rotation logic
+ */
+
+import type { Vec3 } from "./distribution";
+
+/**
+ * 旋转单个 3D 点
+ * Rotate a single 3D point
+ *
+ * @param p - 待旋转的点
+ * @param p - point to rotate
+ * @param a - 绕 Y 轴的旋转角（弧度）
+ * @param a - Y-axis rotation angle (radians)
+ * @param b - 绕 X 轴的旋转角（弧度）
+ * @param b - X-axis rotation angle (radians)
+ */
+export function rotatePoint(p: Vec3, a: number, b: number): Vec3 {
+  const sinA = Math.sin(a);
+  const cosA = Math.cos(a);
+  const sinB = Math.sin(b);
+  const cosB = Math.cos(b);
+
+  // Y 轴旋转
+  // Y-axis rotation
+  const y1 = p.y * cosA + p.z * -sinA;
+  const z1 = p.y * sinA + p.z * cosA;
+
+  // X 轴旋转
+  // X-axis rotation
+  const x2 = p.x * cosB + z1 * sinB;
+  const z2 = z1 * cosB - p.x * sinB;
+
+  return { x: x2, y: y1, z: z2 };
+}
+
+/**
+ * 批量旋转所有点
+ * Rotate all points in batch
+ */
+export function rotatePoints(points: Vec3[], a: number, b: number): Vec3[] {
+  const sinA = Math.sin(a);
+  const cosA = Math.cos(a);
+  const sinB = Math.sin(b);
+  const cosB = Math.cos(b);
+
+  return points.map((p) => {
+    const y1 = p.y * cosA + p.z * -sinA;
+    const z1 = p.y * sinA + p.z * cosA;
+    const x2 = p.x * cosB + z1 * sinB;
+    return { x: x2, y: y1, z: z1 * cosB - p.x * sinB };
+  });
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * @xingwangzhe/tags-cloud
+ *
+ * 纯数学 3D 标签云引擎
+ * Pure math 3D tag cloud engine
+ *
+ * 用法
+ * Usage:
+ *
+ * ```ts
+ * import { TagCloud } from "@xingwangzhe/tags-cloud";
+ *
+ * const cloud = new TagCloud(container, {
+ *   tags: ["TS", "Canvas", "3D"],
+ *   radius: 300,
+ * });
+ * ```
+ *
+ * 底层数学模块
+ * Low-level math modules:
+ *
+ * ```ts
+ * import { fibonacciSphere, rotatePoints, project } from "@xingwangzhe/tags-cloud";
+ * ```
+ */
+
+export { TagCloud } from "./TagCloud";
+export type { TagCloudOptions, TagData } from "./TagCloud";
+export { fibonacciSphere } from "./core/distribution";
+export type { Vec3 } from "./core/distribution";
+export { rotatePoint, rotatePoints } from "./core/rotation";
+export { project } from "./core/projection";
+export type { ProjectedTag } from "./core/projection";