@zerodep-dev/vue-tsx-pro-ui 0.0.0-stage → 0.1.0

package/dist/three/core/ThreeCanvas.js

@@ -0,0 +1,77 @@
+import { t } from "../../config/theme/tokens.js";
+import { mergeAttrs } from "../../utils/props.js";
+import { useThree } from "./renderer.js";
+import { createVNode, mergeProps, shallowRef, watch } from "vue";
+import { _component, readonlyProp, restProps } from "@zerodep-dev/vue-tsx-pro-tsx";
+import * as css from "@zerodep-dev/vue-tsx-pro-tsx/styles";
+//#region src/three/core/ThreeCanvas.tsx
+/** 未声明的属性落到外层 div 上 */
+/** ThreeCanvas 的样式：root、canvas、fallback、fallbackGradient（默认的降级渐变） */
+var threeCanvasStyles = css.create({
+	root: {
+		position: "relative",
+		display: "block",
+		width: "100%",
+		height: "100%",
+		overflow: "hidden"
+	},
+	canvas: {
+		position: "absolute",
+		inset: 0,
+		display: "block",
+		width: "100%",
+		height: "100%"
+	},
+	fallback: {
+		position: "absolute",
+		inset: 0
+	},
+	fallbackGradient: { backgroundImage: `radial-gradient(circle at 20% 25%, color-mix(in oklab, ${t.colors.accent} 28%, transparent), transparent 55%), radial-gradient(circle at 80% 70%, color-mix(in oklab, ${t.colors.chart3} 24%, transparent), transparent 55%), radial-gradient(circle at 60% 15%, color-mix(in oklab, ${t.colors.chart5} 18%, transparent), transparent 50%)` }
+});
+/** three.js 画布：生命周期、降级、无障碍，场景由 setup 搭建 */
+var ThreeCanvas = /*#__PURE__*/ _component((_props, _ctx) => {
+	const setup = readonlyProp(_props, "setup");
+	const quality = readonlyProp(_props, "quality", "auto");
+	const paused = readonlyProp(_props, "paused", false);
+	const resolution = readonlyProp(_props, "resolution", 1);
+	const fallback = readonlyProp(_props, "fallback");
+	const onStatusChange = readonlyProp(_props, "onStatusChange");
+	const propsCanvas = readonlyProp(_props, "propsCanvas");
+	const propsFallback = readonlyProp(_props, "propsFallback");
+	const rest = restProps(_props, _ctx, true);
+	let canvas = shallowRef(null);
+	const three = useThree({
+		canvas: () => canvas.value,
+		setup: (context) => setup.value(context),
+		quality: () => quality.value,
+		paused: () => paused.value,
+		resolution: () => resolution.value
+	});
+	watch(() => three.status, (status) => onStatusChange.value?.(status), { immediate: true });
+	return () => {
+		const labelled = rest["aria-label"] != null || rest["aria-labelledby"] != null;
+		return createVNode("div", mergeProps(mergeAttrs({
+			sx: threeCanvasStyles.root,
+			"aria-hidden": labelled ? void 0 : true
+		}, rest, { role: labelled ? "img" : void 0 }), { "data-state": three.status }), [three.status === "fallback" ? createVNode("div", mergeAttrs({ sx: [threeCanvasStyles.fallback, fallback.value == null && threeCanvasStyles.fallbackGradient] }, propsFallback.value, { "aria-hidden": true }), [fallback.value]) : createVNode("canvas", mergeProps({ "key": three.generation }, mergeAttrs({ sx: threeCanvasStyles.canvas }, propsCanvas.value, {
+			"aria-hidden": true,
+			ref: canvas
+		})), null)]);
+	};
+}, {
+	name: "ThreeCanvas",
+	props: [
+		"setup",
+		"quality",
+		"paused",
+		"resolution",
+		"fallback",
+		"onStatusChange",
+		"propsCanvas",
+		"propsFallback"
+	]
+});
+//#endregion
+export { ThreeCanvas, threeCanvasStyles };
+
+//# sourceMappingURL=ThreeCanvas.js.map

package/dist/three/core/ThreeCanvas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ThreeCanvas.js","names":["_vtp_readonlyProp","_vtp_restProps","_vue_shallowRef","_createVNode","_mergeProps"],"sources":["../../../src/three/core/ThreeCanvas.tsx"],"sourcesContent":["/**\n * three.js 画布（div > canvas）：渲染器的生命周期交给 useThree，这里只负责外层结构、降级与无障碍。\n *\n *   <ThreeCanvas\n *     sx={styles.hero}\n *     setup={(context) => {\n *       const mesh = new Mesh(new IcosahedronGeometry(1, 4), new MeshNormalMaterial());\n *       context.scene.add(mesh);\n *       return { frame: ({ time }) => (mesh.rotation.y = time) };\n *     }}\n *   />\n *\n * - 尺寸由外层 div 决定（默认占满父元素），canvas 铺满它，背景透明；\n * - 没有 WebGL、或 quality=\"off\" 时显示 fallback，默认是一层主题色的柔和渐变；\n * - 默认是装饰（aria-hidden）；传了 aria-label 时是一张图（role=\"img\"）；\n * - 渲染状态写在根元素的 data-state 上（idle / running / paused / still / fallback）。\n *\n * 部件：Root（div）、Canvas（canvas，重建时换新的一块）、Fallback（div，降级内容）。\n */\nimport { _component } from '@zerodep-dev/vue-tsx-pro-tsx';\nimport * as css from '@zerodep-dev/vue-tsx-pro-tsx/styles';\nimport { watch, type VNodeChild } from 'vue';\nimport { mergeAttrs, type PartProps } from '../../utils/props';\nimport type { ThreeQuality } from './quality';\nimport { useThree, type ThreeContext, type ThreeSceneHandle, type ThreeStatus } from './renderer';\nimport { t } from '../../config/theme/tokens';\n\n/** 未声明的属性落到外层 div 上 */\nexport interface ThreeCanvasProps extends PartProps<'div', 'role' | 'data-state'> {\n  /** 搭场景：每次创建渲染器时调用一次（被回收、上下文丢失后会重新调用），返回每帧、尺寸变化、释放的回调 */\n  setup: (context: ThreeContext) => ThreeSceneHandle | void;\n  /**\n   * 画质档位：像素比上限、粒子密度、抗锯齿；变了会重建。off 不创建 WebGL，显示 fallback\n   * @default 'auto'\n   */\n  quality?: ThreeQuality;\n  /** 暂停动画，停在当前画面 */\n  paused?: boolean;\n  /**\n   * 渲染分辨率相对像素比的倍数（0.1–1）：平滑的渐变、模糊的效果降低它能大幅省下 GPU 开销\n   * @default 1\n   */\n  resolution?: number;\n  /** 没有 WebGL（或 quality 为 off）时显示的内容，默认是主题色的柔和渐变 */\n  fallback?: VNodeChild;\n  /** 渲染状态变化时调用（同根元素的 data-state），挂载时先调用一次：比如降级时改放一张静态图，或一次性的效果直接收尾 */\n  onStatusChange?: (status: ThreeStatus) => void;\n  /** canvas 的部件属性 */\n  propsCanvas?: PartProps<'canvas', 'aria-hidden'>;\n  /** 降级内容外层的部件属性 */\n  propsFallback?: PartProps<'div', 'aria-hidden'>;\n}\n\n/** ThreeCanvas 的样式：root、canvas、fallback、fallbackGradient（默认的降级渐变） */\nexport const threeCanvasStyles = css.create({\n  root: {\n    position: 'relative',\n    display: 'block',\n    width: '100%',\n    height: '100%',\n    overflow: 'hidden',\n  },\n  canvas: {\n    position: 'absolute',\n    inset: 0,\n    display: 'block',\n    width: '100%',\n    height: '100%',\n  },\n  fallback: { position: 'absolute', inset: 0 },\n  fallbackGradient: {\n    backgroundImage: `radial-gradient(circle at 20% 25%, color-mix(in oklab, ${t.colors.accent} 28%, transparent), transparent 55%), radial-gradient(circle at 80% 70%, color-mix(in oklab, ${t.colors.chart3} 24%, transparent), transparent 55%), radial-gradient(circle at 60% 15%, color-mix(in oklab, ${t.colors.chart5} 18%, transparent), transparent 50%)`,\n  },\n});\n\n/** three.js 画布：生命周期、降级、无障碍，场景由 setup 搭建 */\nexport const ThreeCanvas = _component(\n  ({\n    setup,\n    quality = 'auto',\n    paused = false,\n    resolution = 1,\n    fallback,\n    onStatusChange,\n    propsCanvas,\n    propsFallback,\n    ...rest\n  }: ThreeCanvasProps) => {\n    let canvas = _state.raw<HTMLCanvasElement | null>(null);\n    const three = useThree({\n      canvas: () => canvas,\n      setup: (context) => setup(context),\n      quality: () => quality,\n      paused: () => paused,\n      resolution: () => resolution,\n    });\n    // 挂载时先报告一次：quality=\"off\" 一开始就是 fallback，之后不再变\n    watch(\n      () => three.status,\n      (status) => onStatusChange?.(status),\n      { immediate: true },\n    );\n\n    return () => {\n      const labelled = rest['aria-label'] != null || rest['aria-labelledby'] != null;\n      return (\n        <div\n          {...mergeAttrs<'div'>(\n            { sx: threeCanvasStyles.root, 'aria-hidden': labelled ? undefined : true },\n            rest,\n            { role: labelled ? 'img' : undefined },\n          )}\n          data-state={three.status}\n        >\n          {three.status === 'fallback' ? (\n            <div\n              {...mergeAttrs<'div'>(\n                {\n                  sx: [\n                    threeCanvasStyles.fallback,\n                    fallback == null && threeCanvasStyles.fallbackGradient,\n                  ],\n                },\n                propsFallback,\n                { 'aria-hidden': true },\n              )}\n            >\n              {fallback}\n            </div>\n          ) : (\n            <canvas\n              key={three.generation}\n              {...mergeAttrs<'canvas'>({ sx: threeCanvasStyles.canvas }, propsCanvas, {\n                'aria-hidden': true,\n                ref: _toRef(canvas),\n              })}\n            />\n          )}\n        </div>\n      );\n    };\n  },\n);\n"],"mappings":";;;;;;;;;AAsDA,IAAa,oBAAoB,IAAI,OAAO;CAC1C,MAAM;EACJ,UAAU;EACV,SAAS;EACT,OAAO;EACP,QAAQ;EACR,UAAU;CACZ;CACA,QAAQ;EACN,UAAU;EACV,OAAO;EACP,SAAS;EACT,OAAO;EACP,QAAQ;CACV;CACA,UAAU;EAAE,UAAU;EAAY,OAAO;CAAE;CAC3C,kBAAkB,EAChB,iBAAiB,0DAA0D,EAAE,OAAO,OAAM,+FAAgG,EAAE,OAAO,OAAM,+FAAgG,EAAE,OAAO,OAAM,sCAC1T;AACF,CAAC;;AAGD,IAAa,cAAc,0BACzB,QAAA,SAUwB;CAAA,MAAA,QAAAA,aAAA,QAAA,OAAA;CAAA,MAAA,UAAAA,aAAA,QAAA,WARZ,MAAM;CAAA,MAAA,SAAAA,aAAA,QAAA,UACP,KAAK;CAAA,MAAA,aAAAA,aAAA,QAAA,cACD,CAAC;CAAA,MAAA,WAAAA,aAAA,QAAA,UAAA;CAAA,MAAA,iBAAAA,aAAA,QAAA,gBAAA;CAAA,MAAA,cAAAA,aAAA,QAAA,aAAA;CAAA,MAAA,gBAAAA,aAAA,QAAA,eAAA;CAAA,MAKX,OAAIC,UAAA,QAAA,MAAA,IAAA;CAEP,IAAI,SAAMC,WAAwC,IAAI;CACtD,MAAM,QAAQ,SAAS;EACrB,cAAQ,OAAA;EACR,QAAQ,YAAY,MAAA,MAAM,OAAO;EACjC,eAAS,QAAA;EACT,cAAQ,OAAA;EACR,kBAAY,WAAA;CACd,CAAC;CAED,YACQ,MAAM,SACX,WAAW,eAAA,QAAiB,MAAM,GACnC,EAAE,WAAW,KAAK,CACpB;CAEA,aAAa;EACX,MAAM,WAAW,KAAK,iBAAiB,QAAQ,KAAK,sBAAsB;EAC1E,OAAAC,YAAA,OAAAC,WAEQ,WACF;GAAE,IAAI,kBAAkB;GAAM,eAAe,WAAW,KAAA,IAAY;EAAK,GACzE,MACA,EAAE,MAAM,WAAW,QAAQ,KAAA,EAAU,CACvC,GAAC,EAAA,cACW,MAAM,OAAM,CAAA,GAAA,CAEvB,MAAM,WAAW,aAAUD,YAAA,OAEpB,WACF,EACE,IAAI,CACF,kBAAkB,UAClB,SAAA,SAAY,QAAQ,kBAAkB,gBAAgB,EAE1D,GAAC,cAAA,OAED,EAAE,eAAe,KAAK,CACxB,GAAC,CAAA,SAAA,KAAA,CAAA,IAAAA,YAAA,UAAAC,WAAA,EAAA,OAMI,MAAM,WAAU,GACjB,WAAqB,EAAE,IAAI,kBAAkB,OAAO,GAAC,YAAA,OAAe;GACtE,eAAe;GACf,KAAG;EACL,CAAC,CAAC,GAAA,IAAA,CAEL,CAAA;CAGP;AACF,GAAC;CAAA,MAAA;CAAA,OAAA;EAAA;EAAA;EAAA;EAAA;EAAA;EAAA;EAAA;EAAA;CAAA;AAAA,CACH"}

package/dist/three/core/dispose.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 释放 three.js 对象占用的 GPU 资源：几何体、材质、材质与 uniform 里的纹理。
+ * three.js 不会随对象被垃圾回收而释放显存，移除模型、卸载场景时要显式调用。
+ */
+import type { Material, Object3D } from 'three';
+/** 释放材质，连同它的贴图与 ShaderMaterial uniform 里的纹理 */
+export declare function disposeMaterial(material: Material): void;
+/** 释放对象及其子孙的几何体、材质与纹理；场景的背景与环境贴图一并释放 */
+export declare function disposeObject(root: Object3D): void;

package/dist/three/core/dispose.js

@@ -0,0 +1,26 @@
+//#region src/three/core/dispose.ts
+function isTexture(value) {
+	return value?.isTexture === true;
+}
+/** 释放材质，连同它的贴图与 ShaderMaterial uniform 里的纹理 */
+function disposeMaterial(material) {
+	for (const value of Object.values(material)) if (isTexture(value)) value.dispose();
+	const uniforms = material.uniforms;
+	for (const uniform of Object.values(uniforms ?? {})) if (isTexture(uniform.value)) uniform.value.dispose();
+	material.dispose();
+}
+/** 释放对象及其子孙的几何体、材质与纹理；场景的背景与环境贴图一并释放 */
+function disposeObject(root) {
+	root.traverse((object) => {
+		const { geometry, material } = object;
+		geometry?.dispose();
+		for (const item of [material ?? []].flat()) disposeMaterial(item);
+	});
+	const { background, environment } = root;
+	if (isTexture(background)) background.dispose();
+	if (isTexture(environment)) environment.dispose();
+}
+//#endregion
+export { disposeMaterial, disposeObject };
+
+//# sourceMappingURL=dispose.js.map

package/dist/three/core/dispose.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispose.js","names":[],"sources":["../../../src/three/core/dispose.ts"],"sourcesContent":["/**\n * 释放 three.js 对象占用的 GPU 资源：几何体、材质、材质与 uniform 里的纹理。\n * three.js 不会随对象被垃圾回收而释放显存，移除模型、卸载场景时要显式调用。\n */\nimport type { Material, Object3D, Texture } from 'three';\n\nfunction isTexture(value: unknown): value is Texture {\n  return (value as Texture | null)?.isTexture === true;\n}\n\n/** 释放材质，连同它的贴图与 ShaderMaterial uniform 里的纹理 */\nexport function disposeMaterial(material: Material): void {\n  for (const value of Object.values(material)) {\n    if (isTexture(value)) value.dispose();\n  }\n  const uniforms = (material as { uniforms?: Record<string, { value: unknown }> }).uniforms;\n  for (const uniform of Object.values(uniforms ?? {})) {\n    if (isTexture(uniform.value)) uniform.value.dispose();\n  }\n  material.dispose();\n}\n\n/** 释放对象及其子孙的几何体、材质与纹理；场景的背景与环境贴图一并释放 */\nexport function disposeObject(root: Object3D): void {\n  root.traverse((object) => {\n    const { geometry, material } = object as Object3D & {\n      geometry?: { dispose(): void };\n      material?: Material | Material[];\n    };\n    geometry?.dispose();\n    for (const item of [material ?? []].flat()) disposeMaterial(item);\n  });\n  const { background, environment } = root as Object3D & {\n    background?: unknown;\n    environment?: unknown;\n  };\n  if (isTexture(background)) background.dispose();\n  if (isTexture(environment)) environment.dispose();\n}\n"],"mappings":";AAMA,SAAS,UAAU,OAAkC;CACnD,OAAQ,OAA0B,cAAc;AAClD;;AAGA,SAAgB,gBAAgB,UAA0B;CACxD,KAAK,MAAM,SAAS,OAAO,OAAO,QAAQ,GACxC,IAAI,UAAU,KAAK,GAAG,MAAM,QAAQ;CAEtC,MAAM,WAAY,SAA+D;CACjF,KAAK,MAAM,WAAW,OAAO,OAAO,YAAY,CAAC,CAAC,GAChD,IAAI,UAAU,QAAQ,KAAK,GAAG,QAAQ,MAAM,QAAQ;CAEtD,SAAS,QAAQ;AACnB;;AAGA,SAAgB,cAAc,MAAsB;CAClD,KAAK,UAAU,WAAW;EACxB,MAAM,EAAE,UAAU,aAAa;EAI/B,UAAU,QAAQ;EAClB,KAAK,MAAM,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,gBAAgB,IAAI;CAClE,CAAC;CACD,MAAM,EAAE,YAAY,gBAAgB;CAIpC,IAAI,UAAU,UAAU,GAAG,WAAW,QAAQ;CAC9C,IAAI,UAAU,WAAW,GAAG,YAAY,QAAQ;AAClD"}

package/dist/three/core/orbit.d.ts

@@ -0,0 +1,31 @@
+/** createOrbit 的选项 */
+export interface OrbitOptions {
+    /** 一开始的 yaw（弧度） */
+    yaw: number;
+    /** 一开始的 pitch（弧度） */
+    pitch: number;
+    /** pitch 的范围 ±pitchLimit（弧度），默认 1 */
+    pitchLimit?: number;
+}
+/** 拖动转动的状态与事件 */
+export interface Orbit {
+    /** 当前的 yaw（弧度） */
+    readonly yaw: number;
+    /** 当前的 pitch（弧度） */
+    readonly pitch: number;
+    /** 正在拖动（响应式）：切换 grab / grabbing 光标 */
+    readonly dragging: boolean;
+    /** 放到外层元素上的指针事件 */
+    readonly handlers: {
+        onPointerdown: (event: PointerEvent) => void;
+        onPointermove: (event: PointerEvent) => void;
+        onPointerup: () => void;
+        onPointercancel: () => void;
+    };
+    /** 直接转一下（键盘）：弧度 */
+    nudge(yaw: number, pitch: number): void;
+    /** 每帧调用：用掉拖动的量；没在拖时惯性回到 spin（弧度 / 秒）的自转。返回这一帧有没有变化 */
+    step(delta: number, spin: number): boolean;
+}
+/** 拖动转动 */
+export declare function createOrbit({ yaw, pitch, pitchLimit }: OrbitOptions): Orbit;

package/dist/three/core/orbit.js

@@ -0,0 +1,83 @@
+import { clamp } from "../../utils/data/number.js";
+import { shallowRef } from "vue";
+//#region src/three/core/orbit.ts
+/**
+* 拖动转动（Globe、ModelViewer 共用）：指针左右拖改 yaw、上下拖改 pitch（夹在 ±pitchLimit 内），
+* 松手后带着惯性慢慢回到自转；方向键也能转（nudge）。事件放在外层元素上，场景每帧调用 step 取用。
+*
+*   const orbit = createOrbit({ yaw: 0, pitch: 0.3 });
+*   <div {...orbit.handlers} />                  // 指针事件
+*   frame: ({ delta }) => { orbit.step(delta, speed); camera… orbit.yaw / orbit.pitch }
+*/
+/** 松手后惯性转动的最快速度（弧度 / 秒） */
+var MAX_SPIN = 3;
+/** 拖动一像素转多少弧度 */
+var PER_PIXEL = .006;
+/** 拖动转动 */
+function createOrbit({ yaw, pitch, pitchLimit = 1 }) {
+	const dragging = shallowRef(false);
+	const pointer = {
+		x: 0,
+		y: 0,
+		dx: 0,
+		dy: 0
+	};
+	let velocity = 0;
+	const clampPitch = (value) => clamp(value, -pitchLimit, pitchLimit);
+	const up = () => {
+		dragging.value = false;
+	};
+	return {
+		get yaw() {
+			return yaw;
+		},
+		get pitch() {
+			return pitch;
+		},
+		get dragging() {
+			return dragging.value;
+		},
+		handlers: {
+			onPointerdown(event) {
+				if (event.button !== 0) return;
+				event.currentTarget.setPointerCapture(event.pointerId);
+				pointer.x = event.clientX;
+				pointer.y = event.clientY;
+				dragging.value = true;
+			},
+			onPointermove(event) {
+				if (!dragging.value) return;
+				pointer.dx += event.clientX - pointer.x;
+				pointer.dy += event.clientY - pointer.y;
+				pointer.x = event.clientX;
+				pointer.y = event.clientY;
+			},
+			onPointerup: up,
+			onPointercancel: up
+		},
+		nudge(byYaw, byPitch) {
+			yaw += byYaw;
+			pitch = clampPitch(pitch + byPitch);
+		},
+		step(delta, spin) {
+			if (pointer.dx || pointer.dy) {
+				const turn = pointer.dx * PER_PIXEL;
+				yaw += turn;
+				pitch = clampPitch(pitch + pointer.dy * PER_PIXEL);
+				const speed = delta > 0 ? turn / delta : 0;
+				velocity = clamp(velocity * .5 + speed * .5, -3, MAX_SPIN);
+				pointer.dx = 0;
+				pointer.dy = 0;
+				return true;
+			}
+			if (dragging.value) return false;
+			velocity += (spin - velocity) * Math.min(1, delta * 1.5);
+			yaw += velocity * delta;
+			return velocity !== 0;
+		}
+	};
+}
+//#endregion
+export { createOrbit };
+
+//# sourceMappingURL=orbit.js.map

package/dist/three/core/orbit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orbit.js","names":[],"sources":["../../../src/three/core/orbit.ts"],"sourcesContent":["/**\n * 拖动转动（Globe、ModelViewer 共用）：指针左右拖改 yaw、上下拖改 pitch（夹在 ±pitchLimit 内），\n * 松手后带着惯性慢慢回到自转；方向键也能转（nudge）。事件放在外层元素上，场景每帧调用 step 取用。\n *\n *   const orbit = createOrbit({ yaw: 0, pitch: 0.3 });\n *   <div {...orbit.handlers} />                  // 指针事件\n *   frame: ({ delta }) => { orbit.step(delta, speed); camera… orbit.yaw / orbit.pitch }\n */\nimport { shallowRef } from 'vue';\nimport { clamp } from '../../utils/data/number';\n\n/** 松手后惯性转动的最快速度（弧度 / 秒） */\nconst MAX_SPIN = 3;\n/** 拖动一像素转多少弧度 */\nconst PER_PIXEL = 0.006;\n\n/** createOrbit 的选项 */\nexport interface OrbitOptions {\n  /** 一开始的 yaw（弧度） */\n  yaw: number;\n  /** 一开始的 pitch（弧度） */\n  pitch: number;\n  /** pitch 的范围 ±pitchLimit（弧度），默认 1 */\n  pitchLimit?: number;\n}\n\n/** 拖动转动的状态与事件 */\nexport interface Orbit {\n  /** 当前的 yaw（弧度） */\n  readonly yaw: number;\n  /** 当前的 pitch（弧度） */\n  readonly pitch: number;\n  /** 正在拖动（响应式）：切换 grab / grabbing 光标 */\n  readonly dragging: boolean;\n  /** 放到外层元素上的指针事件 */\n  readonly handlers: {\n    onPointerdown: (event: PointerEvent) => void;\n    onPointermove: (event: PointerEvent) => void;\n    onPointerup: () => void;\n    onPointercancel: () => void;\n  };\n  /** 直接转一下（键盘）：弧度 */\n  nudge(yaw: number, pitch: number): void;\n  /** 每帧调用：用掉拖动的量；没在拖时惯性回到 spin（弧度 / 秒）的自转。返回这一帧有没有变化 */\n  step(delta: number, spin: number): boolean;\n}\n\n/** 拖动转动 */\nexport function createOrbit({ yaw, pitch, pitchLimit = 1 }: OrbitOptions): Orbit {\n  const dragging = shallowRef(false);\n  const pointer = { x: 0, y: 0, dx: 0, dy: 0 };\n  let velocity = 0;\n  const clampPitch = (value: number) => clamp(value, -pitchLimit, pitchLimit);\n\n  const up = () => {\n    dragging.value = false;\n  };\n  return {\n    get yaw() {\n      return yaw;\n    },\n    get pitch() {\n      return pitch;\n    },\n    get dragging() {\n      return dragging.value;\n    },\n    handlers: {\n      onPointerdown(event) {\n        if (event.button !== 0) return;\n        (event.currentTarget as HTMLElement).setPointerCapture(event.pointerId);\n        pointer.x = event.clientX;\n        pointer.y = event.clientY;\n        dragging.value = true;\n      },\n      onPointermove(event) {\n        if (!dragging.value) return;\n        pointer.dx += event.clientX - pointer.x;\n        pointer.dy += event.clientY - pointer.y;\n        pointer.x = event.clientX;\n        pointer.y = event.clientY;\n      },\n      onPointerup: up,\n      onPointercancel: up,\n    },\n    nudge(byYaw, byPitch) {\n      yaw += byYaw;\n      pitch = clampPitch(pitch + byPitch);\n    },\n    step(delta, spin) {\n      if (pointer.dx || pointer.dy) {\n        const turn = pointer.dx * PER_PIXEL;\n        yaw += turn;\n        pitch = clampPitch(pitch + pointer.dy * PER_PIXEL);\n        // 松手时的速度：几帧平滑一下，再封顶（一帧里拖了一大段时不至于疯转）\n        const speed = delta > 0 ? turn / delta : 0;\n        velocity = clamp(velocity * 0.5 + speed * 0.5, -MAX_SPIN, MAX_SPIN);\n        pointer.dx = 0;\n        pointer.dy = 0;\n        return true;\n      }\n      if (dragging.value) return false;\n      // 松手后的惯性慢慢回到自转\n      velocity += (spin - velocity) * Math.min(1, delta * 1.5);\n      yaw += velocity * delta;\n      return velocity !== 0;\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;AAYA,IAAM,WAAW;;AAEjB,IAAM,YAAY;;AAkClB,SAAgB,YAAY,EAAE,KAAK,OAAO,aAAa,KAA0B;CAC/E,MAAM,WAAW,WAAW,KAAK;CACjC,MAAM,UAAU;EAAE,GAAG;EAAG,GAAG;EAAG,IAAI;EAAG,IAAI;CAAE;CAC3C,IAAI,WAAW;CACf,MAAM,cAAc,UAAkB,MAAM,OAAO,CAAC,YAAY,UAAU;CAE1E,MAAM,WAAW;EACf,SAAS,QAAQ;CACnB;CACA,OAAO;EACL,IAAI,MAAM;GACR,OAAO;EACT;EACA,IAAI,QAAQ;GACV,OAAO;EACT;EACA,IAAI,WAAW;GACb,OAAO,SAAS;EAClB;EACA,UAAU;GACR,cAAc,OAAO;IACnB,IAAI,MAAM,WAAW,GAAG;IACxB,MAAO,cAA8B,kBAAkB,MAAM,SAAS;IACtE,QAAQ,IAAI,MAAM;IAClB,QAAQ,IAAI,MAAM;IAClB,SAAS,QAAQ;GACnB;GACA,cAAc,OAAO;IACnB,IAAI,CAAC,SAAS,OAAO;IACrB,QAAQ,MAAM,MAAM,UAAU,QAAQ;IACtC,QAAQ,MAAM,MAAM,UAAU,QAAQ;IACtC,QAAQ,IAAI,MAAM;IAClB,QAAQ,IAAI,MAAM;GACpB;GACA,aAAa;GACb,iBAAiB;EACnB;EACA,MAAM,OAAO,SAAS;GACpB,OAAO;GACP,QAAQ,WAAW,QAAQ,OAAO;EACpC;EACA,KAAK,OAAO,MAAM;GAChB,IAAI,QAAQ,MAAM,QAAQ,IAAI;IAC5B,MAAM,OAAO,QAAQ,KAAK;IAC1B,OAAO;IACP,QAAQ,WAAW,QAAQ,QAAQ,KAAK,SAAS;IAEjD,MAAM,QAAQ,QAAQ,IAAI,OAAO,QAAQ;IACzC,WAAW,MAAM,WAAW,KAAM,QAAQ,IAAK,IAAW,QAAQ;IAClE,QAAQ,KAAK;IACb,QAAQ,KAAK;IACb,OAAO;GACT;GACA,IAAI,SAAS,OAAO,OAAO;GAE3B,aAAa,OAAO,YAAY,KAAK,IAAI,GAAG,QAAQ,GAAG;GACvD,OAAO,WAAW;GAClB,OAAO,aAAa;EACtB;CACF;AACF"}

package/dist/three/core/quality.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 3D 效果的画质档位与 WebGL 上下文的数量上限。
+ *
+ * 档位决定像素比上限、粒子等元素的密度、是否抗锯齿；auto 按设备判断（触屏、核数、内存、省流量）；off 不渲染，显示降级内容。
+ * 浏览器同时能保持的 WebGL 上下文有限（Chrome 约 16 个，超出时最早的上下文被强制丢失），
+ * 页面上的效果多时由这里分配：超过上限时，回收最久没出现在视口里的那个，它再滚回视口时重建。
+ */
+/** 画质档位 */
+export interface ThreeQualities {
+    /** 按设备选择：触屏或低端设备 low / medium，桌面 high */
+    auto: unknown;
+    /** 像素比 1、密度 0.4、不抗锯齿 */
+    low: unknown;
+    /** 像素比上限 1.5、密度 0.7 */
+    medium: unknown;
+    /** 像素比上限 2、全密度 */
+    high: unknown;
+    /** 不创建 WebGL，直接显示降级内容：用户在设置里关掉了特效、省电模式 */
+    off: unknown;
+}
+/** 画质档位名 */
+export type ThreeQuality = keyof ThreeQualities;
+/** 档位落到渲染上的参数 */
+export interface ResolvedThreeQuality {
+    /** 实际档位（auto 已按设备选定） */
+    level: Exclude<ThreeQuality, 'auto' | 'off'>;
+    /** 像素比上限：实际像素比取它与 devicePixelRatio 的较小值 */
+    pixelRatio: number;
+    /** 密度系数（0–1）：粒子数、网格细分等按它缩放 */
+    density: number;
+    /** 抗锯齿 */
+    antialias: boolean;
+}
+/** 档位名 → 渲染参数（off 不渲染，没有参数） */
+export declare function resolveThreeQuality(quality?: Exclude<ThreeQuality, 'off'>): ResolvedThreeQuality;
+/** 占用一个 WebGL 上下文的效果 */
+export interface ContextHolder {
+    /** 现在是否在视口里：只回收不在视口里的 */
+    readonly visible: boolean;
+    /** 上次在视口里的时间（performance.now()）：先回收最久没出现的 */
+    readonly lastSeen: number;
+    /** 被回收：释放渲染器与场景，回到等待状态 */
+    evict(): void;
+    /** 有空位了：等待中的效果再试一次 */
+    retry(): void;
+}
+/**
+ * 页面上同时保持的 WebGL 上下文上限，默认 8（给宿主自己的 canvas 留余量）。
+ * 只影响之后申请的效果；已经在渲染的不会因为调低而被回收
+ */
+export declare function setMaxThreeContexts(count: number): void;
+/** 当前占用的 WebGL 上下文数（测试、性能面板用） */
+export declare function activeThreeContexts(): number;
+/** 申请一个上下文：有空位直接占用；满了回收一个不在视口里的；都在视口里时排队，返回 false */
+export declare function acquireContext(holder: ContextHolder): boolean;
+/** 释放上下文（卸载、被回收、上下文丢失），排队的效果依次再试 */
+export declare function releaseContext(holder: ContextHolder): void;
+/** 排队的效果依次再试：有了空位，或有效果滚出视口（可以被回收）时调用 */
+export declare function retryWaiting(): void;

package/dist/three/core/quality.js

@@ -0,0 +1,80 @@
+//#region src/three/core/quality.ts
+var LEVELS = {
+	low: {
+		pixelRatio: 1,
+		density: .4,
+		antialias: false
+	},
+	medium: {
+		pixelRatio: 1.5,
+		density: .7,
+		antialias: true
+	},
+	high: {
+		pixelRatio: 2,
+		density: 1,
+		antialias: true
+	}
+};
+/** auto 的判断：省流量或很弱的设备 low，触屏或 4 核以下 medium，其余 high */
+function deviceLevel() {
+	if (typeof navigator === "undefined") return "medium";
+	const hints = navigator;
+	const cores = navigator.hardwareConcurrency || 4;
+	const memory = hints.deviceMemory ?? 8;
+	if (hints.connection?.saveData || cores <= 2 || memory <= 2) return "low";
+	if ((globalThis.matchMedia?.("(pointer: coarse)").matches ?? false) || cores <= 4 || memory <= 4) return "medium";
+	return "high";
+}
+/** 档位名 → 渲染参数（off 不渲染，没有参数） */
+function resolveThreeQuality(quality = "auto") {
+	const level = quality === "auto" ? deviceLevel() : quality;
+	return {
+		level,
+		...LEVELS[level]
+	};
+}
+var limit = 8;
+var holders = /* @__PURE__ */ new Set();
+var waiting = /* @__PURE__ */ new Set();
+/**
+* 页面上同时保持的 WebGL 上下文上限，默认 8（给宿主自己的 canvas 留余量）。
+* 只影响之后申请的效果；已经在渲染的不会因为调低而被回收
+*/
+function setMaxThreeContexts(count) {
+	limit = Math.max(1, Math.floor(count));
+}
+/** 当前占用的 WebGL 上下文数（测试、性能面板用） */
+function activeThreeContexts() {
+	return holders.size;
+}
+/** 申请一个上下文：有空位直接占用；满了回收一个不在视口里的；都在视口里时排队，返回 false */
+function acquireContext(holder) {
+	if (holders.has(holder)) return true;
+	if (holders.size >= limit) {
+		let oldest;
+		for (const other of holders) if (!other.visible && (!oldest || other.lastSeen < oldest.lastSeen)) oldest = other;
+		if (!oldest) {
+			waiting.add(holder);
+			return false;
+		}
+		holders.delete(oldest);
+		oldest.evict();
+	}
+	waiting.delete(holder);
+	holders.add(holder);
+	return true;
+}
+/** 释放上下文（卸载、被回收、上下文丢失），排队的效果依次再试 */
+function releaseContext(holder) {
+	waiting.delete(holder);
+	if (holders.delete(holder)) retryWaiting();
+}
+/** 排队的效果依次再试：有了空位，或有效果滚出视口（可以被回收）时调用 */
+function retryWaiting() {
+	for (const next of [...waiting]) next.retry();
+}
+//#endregion
+export { acquireContext, activeThreeContexts, releaseContext, resolveThreeQuality, retryWaiting, setMaxThreeContexts };
+
+//# sourceMappingURL=quality.js.map

package/dist/three/core/quality.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quality.js","names":[],"sources":["../../../src/three/core/quality.ts"],"sourcesContent":["/**\n * 3D 效果的画质档位与 WebGL 上下文的数量上限。\n *\n * 档位决定像素比上限、粒子等元素的密度、是否抗锯齿；auto 按设备判断（触屏、核数、内存、省流量）；off 不渲染，显示降级内容。\n * 浏览器同时能保持的 WebGL 上下文有限（Chrome 约 16 个，超出时最早的上下文被强制丢失），\n * 页面上的效果多时由这里分配：超过上限时，回收最久没出现在视口里的那个，它再滚回视口时重建。\n */\n\n/** 画质档位 */\nexport interface ThreeQualities {\n  /** 按设备选择：触屏或低端设备 low / medium，桌面 high */\n  auto: unknown;\n  /** 像素比 1、密度 0.4、不抗锯齿 */\n  low: unknown;\n  /** 像素比上限 1.5、密度 0.7 */\n  medium: unknown;\n  /** 像素比上限 2、全密度 */\n  high: unknown;\n  /** 不创建 WebGL，直接显示降级内容：用户在设置里关掉了特效、省电模式 */\n  off: unknown;\n}\n\n/** 画质档位名 */\nexport type ThreeQuality = keyof ThreeQualities;\n\n/** 档位落到渲染上的参数 */\nexport interface ResolvedThreeQuality {\n  /** 实际档位（auto 已按设备选定） */\n  level: Exclude<ThreeQuality, 'auto' | 'off'>;\n  /** 像素比上限：实际像素比取它与 devicePixelRatio 的较小值 */\n  pixelRatio: number;\n  /** 密度系数（0–1）：粒子数、网格细分等按它缩放 */\n  density: number;\n  /** 抗锯齿 */\n  antialias: boolean;\n}\n\nconst LEVELS: Record<ResolvedThreeQuality['level'], Omit<ResolvedThreeQuality, 'level'>> = {\n  low: { pixelRatio: 1, density: 0.4, antialias: false },\n  medium: { pixelRatio: 1.5, density: 0.7, antialias: true },\n  high: { pixelRatio: 2, density: 1, antialias: true },\n};\n\n/** 设备信息里非标准的字段（Chromium 才有） */\ninterface DeviceHints {\n  deviceMemory?: number;\n  connection?: { saveData?: boolean };\n}\n\n/** auto 的判断：省流量或很弱的设备 low，触屏或 4 核以下 medium，其余 high */\nfunction deviceLevel(): ResolvedThreeQuality['level'] {\n  if (typeof navigator === 'undefined') return 'medium';\n  const hints = navigator as Navigator & DeviceHints;\n  const cores = navigator.hardwareConcurrency || 4;\n  const memory = hints.deviceMemory ?? 8;\n  if (hints.connection?.saveData || cores <= 2 || memory <= 2) return 'low';\n  const coarse = globalThis.matchMedia?.('(pointer: coarse)').matches ?? false;\n  if (coarse || cores <= 4 || memory <= 4) return 'medium';\n  return 'high';\n}\n\n/** 档位名 → 渲染参数（off 不渲染，没有参数） */\nexport function resolveThreeQuality(\n  quality: Exclude<ThreeQuality, 'off'> = 'auto',\n): ResolvedThreeQuality {\n  const level = quality === 'auto' ? deviceLevel() : quality;\n  return { level, ...LEVELS[level] };\n}\n\n/** 占用一个 WebGL 上下文的效果 */\nexport interface ContextHolder {\n  /** 现在是否在视口里：只回收不在视口里的 */\n  readonly visible: boolean;\n  /** 上次在视口里的时间（performance.now()）：先回收最久没出现的 */\n  readonly lastSeen: number;\n  /** 被回收：释放渲染器与场景，回到等待状态 */\n  evict(): void;\n  /** 有空位了：等待中的效果再试一次 */\n  retry(): void;\n}\n\nlet limit = 8;\nconst holders = new Set<ContextHolder>();\nconst waiting = new Set<ContextHolder>();\n\n/**\n * 页面上同时保持的 WebGL 上下文上限，默认 8（给宿主自己的 canvas 留余量）。\n * 只影响之后申请的效果；已经在渲染的不会因为调低而被回收\n */\nexport function setMaxThreeContexts(count: number): void {\n  limit = Math.max(1, Math.floor(count));\n}\n\n/** 当前占用的 WebGL 上下文数（测试、性能面板用） */\nexport function activeThreeContexts(): number {\n  return holders.size;\n}\n\n/** 申请一个上下文：有空位直接占用；满了回收一个不在视口里的；都在视口里时排队，返回 false */\nexport function acquireContext(holder: ContextHolder): boolean {\n  if (holders.has(holder)) return true;\n  if (holders.size >= limit) {\n    let oldest: ContextHolder | undefined;\n    for (const other of holders) {\n      if (!other.visible && (!oldest || other.lastSeen < oldest.lastSeen)) oldest = other;\n    }\n    if (!oldest) {\n      waiting.add(holder);\n      return false;\n    }\n    holders.delete(oldest);\n    oldest.evict();\n  }\n  waiting.delete(holder);\n  holders.add(holder);\n  return true;\n}\n\n/** 释放上下文（卸载、被回收、上下文丢失），排队的效果依次再试 */\nexport function releaseContext(holder: ContextHolder): void {\n  waiting.delete(holder);\n  if (holders.delete(holder)) retryWaiting();\n}\n\n/** 排队的效果依次再试：有了空位，或有效果滚出视口（可以被回收）时调用 */\nexport function retryWaiting(): void {\n  for (const next of [...waiting]) next.retry();\n}\n"],"mappings":";AAqCA,IAAM,SAAqF;CACzF,KAAK;EAAE,YAAY;EAAG,SAAS;EAAK,WAAW;CAAM;CACrD,QAAQ;EAAE,YAAY;EAAK,SAAS;EAAK,WAAW;CAAK;CACzD,MAAM;EAAE,YAAY;EAAG,SAAS;EAAG,WAAW;CAAK;AACrD;;AASA,SAAS,cAA6C;CACpD,IAAI,OAAO,cAAc,aAAa,OAAO;CAC7C,MAAM,QAAQ;CACd,MAAM,QAAQ,UAAU,uBAAuB;CAC/C,MAAM,SAAS,MAAM,gBAAgB;CACrC,IAAI,MAAM,YAAY,YAAY,SAAS,KAAK,UAAU,GAAG,OAAO;CAEpE,KADe,WAAW,aAAa,mBAAmB,CAAC,CAAC,WAAW,UACzD,SAAS,KAAK,UAAU,GAAG,OAAO;CAChD,OAAO;AACT;;AAGA,SAAgB,oBACd,UAAwC,QAClB;CACtB,MAAM,QAAQ,YAAY,SAAS,YAAY,IAAI;CACnD,OAAO;EAAE;EAAO,GAAG,OAAO;CAAO;AACnC;AAcA,IAAI,QAAQ;AACZ,IAAM,0BAAU,IAAI,IAAmB;AACvC,IAAM,0BAAU,IAAI,IAAmB;;;;;AAMvC,SAAgB,oBAAoB,OAAqB;CACvD,QAAQ,KAAK,IAAI,GAAG,KAAK,MAAM,KAAK,CAAC;AACvC;;AAGA,SAAgB,sBAA8B;CAC5C,OAAO,QAAQ;AACjB;;AAGA,SAAgB,eAAe,QAAgC;CAC7D,IAAI,QAAQ,IAAI,MAAM,GAAG,OAAO;CAChC,IAAI,QAAQ,QAAQ,OAAO;EACzB,IAAI;EACJ,KAAK,MAAM,SAAS,SAClB,IAAI,CAAC,MAAM,YAAY,CAAC,UAAU,MAAM,WAAW,OAAO,WAAW,SAAS;EAEhF,IAAI,CAAC,QAAQ;GACX,QAAQ,IAAI,MAAM;GAClB,OAAO;EACT;EACA,QAAQ,OAAO,MAAM;EACrB,OAAO,MAAM;CACf;CACA,QAAQ,OAAO,MAAM;CACrB,QAAQ,IAAI,MAAM;CAClB,OAAO;AACT;;AAGA,SAAgB,eAAe,QAA6B;CAC1D,QAAQ,OAAO,MAAM;CACrB,IAAI,QAAQ,OAAO,MAAM,GAAG,aAAa;AAC3C;;AAGA,SAAgB,eAAqB;CACnC,KAAK,MAAM,QAAQ,CAAC,GAAG,OAAO,GAAG,KAAK,MAAM;AAC9C"}

package/dist/three/core/renderer.d.ts

@@ -0,0 +1,110 @@
+/**
+ * three.js 渲染器的生命周期（ThreeCanvas 用它；要自己安排外层结构时也可以直接用）：
+ *
+ *   const three = useThree({ canvas: () => canvas, setup: (context) => { …; return { frame } } });
+ *   <canvas key={three.generation} ref={…} />
+ *
+ * - 第一次进入视口时才创建渲染器，占用 WebGL 上下文的名额（quality.ts）；被回收、上下文丢失后换一块新 canvas
+ *   （generation 加一，渲染方用它作 key）再建，所以场景要在 setup 里搭，不要在外面持有渲染器；
+ * - 所有效果共用一个 requestAnimationFrame 循环；滚出视口、标签页隐藏、paused 时停下；
+ * - 减少动态效果（系统设置，或主题的时长为 0）时只画一帧静止画面，尺寸、主题色变化时（invalidate）重画；
+ * - 尺寸跟随 canvas 的布局尺寸（ResizeObserver），像素比取设备与画质档位上限的较小值；
+ * - 卸载、被回收时释放场景里的几何体、材质、纹理和渲染器，并立即交还上下文（forceContextLoss），
+ *   不等浏览器回收；上下文连续丢失三次后改显示降级内容。
+ */
+import { Scene, WebGLRenderer, type Camera, type Color } from 'three';
+import { type PointerState } from '../../utils/motion/pointer';
+import { type ResolvedThreeQuality, type ThreeQuality } from './quality';
+import { type ThemeColors, type ThemeColorSources } from './theme-colors';
+/** 画布的尺寸（CSS 像素）与实际使用的像素比 */
+export interface ThreeSize {
+    /** 宽度（CSS 像素） */
+    width: number;
+    /** 高度（CSS 像素） */
+    height: number;
+    /** 实际使用的像素比：设备像素比按画质档位封顶 */
+    pixelRatio: number;
+}
+/** 交给 setup 的场景上下文 */
+export interface ThreeContext {
+    /** 渲染器：透明背景，像素比与尺寸由这里管理 */
+    readonly renderer: WebGLRenderer;
+    /** 场景：卸载时连同里面的几何体、材质、纹理一起释放 */
+    readonly scene: Scene;
+    /** 相机：默认是透视相机（视角 45°，位于 z = 5），宽高比自动跟随；可以换成别的相机 */
+    camera: Camera;
+    /** 渲染器画到的 canvas 元素 */
+    readonly canvas: HTMLCanvasElement;
+    /** 当前尺寸，随布局变化 */
+    readonly size: Readonly<ThreeSize>;
+    /** 画质档位的参数：粒子数、细分等按 density 缩放 */
+    readonly quality: ResolvedThreeQuality;
+    /** 只画静止画面（减少动态效果）：指针跟随之类的交互也应停下 */
+    readonly still: boolean;
+    /** 指针相对画布的位置（-1 到 1）与 strength（指针在画布上为 1，离开后淡出），弹簧阻尼，见 pointer.ts */
+    readonly pointer: PointerState;
+    /** 请求重画一帧：循环停着（静止、暂停）时，数据变了用它刷新 */
+    invalidate: () => void;
+    /**
+     * 跟随画布所在位置主题的颜色（THREE.Color）：换主题时原地过渡到新色并重画。
+     * 材质的 color 直接赋这个对象（`material.color = palette.accent`），见 theme-colors.ts
+     */
+    themeColors: <Sources extends ThemeColorSources>(sources: Sources) => ThemeColors<Sources>;
+    /**
+     * 一列跟随主题的颜色（着色器的色板 uColors、粒子的色调）：给了 size 时取前 size 个，不足的用最后一个补齐
+     * （uniform 数组的长度是固定的）；sources 不能为空
+     */
+    themeColorList: (sources: readonly string[], size?: number) => Color[];
+}
+/** 每帧交给 frame 的时间 */
+export interface ThreeFrame {
+    /** 动画时间（秒）：只在循环运行时增长，暂停后接着走 */
+    time: number;
+    /** 距上一帧（秒），最多 0.1：切回标签页时不跳一大步 */
+    delta: number;
+}
+/** setup 返回的场景回调，都可省 */
+export interface ThreeSceneHandle {
+    /** 每帧渲染前调用：更新 uniform、位置 */
+    frame?(frame: ThreeFrame, context: ThreeContext): void;
+    /** 尺寸变化后调用（相机的宽高比已更新） */
+    resize?(size: Readonly<ThreeSize>, context: ThreeContext): void;
+    /** 释放前调用：清理 setup 里自己加的监听、加载器；场景里的对象由这里统一释放 */
+    dispose?(): void;
+}
+/** 渲染状态，写在根元素的 data-state 上 */
+export type ThreeStatus = 
+/** 还没创建（没进过视口、在排队、被回收） */
+'idle'
+/** 循环运行中 */
+ | 'running'
+/** 停着：滚出视口、标签页隐藏或 paused */
+ | 'paused'
+/** 只画了一帧静止画面（减少动态效果） */
+ | 'still'
+/** 没有 WebGL，或画质是 off：显示降级内容 */
+ | 'fallback';
+/** useThree 的选项 */
+export interface ThreeOptions {
+    /** 画在哪块 canvas 上（渲染方按 generation 换新的） */
+    canvas: () => HTMLCanvasElement | null | undefined;
+    /** 搭场景：每次创建渲染器时调用一次 */
+    setup: (context: ThreeContext) => ThreeSceneHandle | void;
+    /** 画质档位，默认 auto；变了会重建，off 时释放渲染器、显示降级内容 */
+    quality?: () => ThreeQuality | undefined;
+    /** 暂停循环（停在当前画面） */
+    paused?: () => boolean | undefined;
+    /** 渲染分辨率相对像素比的倍数（0–1），平滑的渐变类效果用 0.5 能省下大半的填充开销；默认 1 */
+    resolution?: () => number | undefined;
+}
+/** useThree 的返回值 */
+export interface ThreeController {
+    /** 渲染状态，响应式 */
+    readonly status: ThreeStatus;
+    /** canvas 的代数：重建时加一，渲染方用作 canvas 的 key */
+    readonly generation: number;
+    /** 请求重画一帧 */
+    invalidate: () => void;
+}
+/** three.js 渲染器的生命周期（在 setup 里调用），见文件开头 */
+export declare function useThree(options: ThreeOptions): ThreeController;