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

package/dist/three/core/renderer.js

@@ -0,0 +1,303 @@
+import { clamp } from "../../utils/data/number.js";
+import { durations } from "../../config/theme/tokens.js";
+import { useConfig } from "../../config/context.js";
+import { readToken } from "../../config/theme/theme.js";
+import { parseDuration } from "../../utils/motion/animation.js";
+import { useResizeObserver } from "../../utils/dom/resize.js";
+import { useIntersectionObserver } from "../../utils/dom/intersection.js";
+import { useReducedMotion } from "../../utils/dom/media-query.js";
+import { usePointer } from "../../utils/motion/pointer.js";
+import { usePageVisible } from "../../utils/dom/page-visibility.js";
+import { disposeObject } from "./dispose.js";
+import { acquireContext, releaseContext, resolveThreeQuality, retryWaiting } from "./quality.js";
+import { createThemeColorSet } from "./theme-colors.js";
+import { onScopeDispose, shallowRef, watch } from "vue";
+import { PerspectiveCamera, Scene, WebGLRenderer } from "three";
+//#region src/three/core/renderer.ts
+/**
+* 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），
+*   不等浏览器回收；上下文连续丢失三次后改显示降级内容。
+*/
+var tickers = /* @__PURE__ */ new Set();
+var tickerFrame = 0;
+function runTickers(now) {
+	tickerFrame = 0;
+	for (const tick of [...tickers]) tick(now);
+	if (tickers.size) tickerFrame = requestAnimationFrame(runTickers);
+}
+function subscribe(tick) {
+	tickers.add(tick);
+	tickerFrame ||= requestAnimationFrame(runTickers);
+}
+/** 上下文连续丢失这么多次后不再重建，改显示降级内容 */
+var MAX_CONTEXT_LOSSES = 3;
+/** 主题的时长为 0（主题编辑器关掉了动效，或系统要求减少动态效果）：读不到主题时当作有动效 */
+function themeMotionOff(element) {
+	try {
+		return parseDuration(readToken(element, durations.md)) === 0;
+	} catch {
+		return false;
+	}
+}
+/** three.js 渲染器的生命周期（在 setup 里调用），见文件开头 */
+function useThree(options) {
+	const config = useConfig();
+	const reducedMotion = useReducedMotion();
+	const off = () => options.quality?.() === "off";
+	const status = shallowRef(off() ? "fallback" : "idle");
+	const pointer = usePointer(options.canvas);
+	const generation = shallowRef(0);
+	const themeStill = shallowRef(false);
+	const pageVisible = usePageVisible();
+	const visible = shallowRef(false);
+	let instance;
+	let lastSeen = 0;
+	let losses = 0;
+	let unmounted = false;
+	let unsupported = false;
+	const still = () => reducedMotion.value || themeStill.value;
+	const holder = {
+		get visible() {
+			return visible.value;
+		},
+		get lastSeen() {
+			return lastSeen;
+		},
+		evict() {
+			teardown();
+			status.value = "idle";
+			generation.value++;
+		},
+		retry: () => start()
+	};
+	function draw(target, delta) {
+		target.handle.frame?.({
+			time: target.time,
+			delta
+		}, target.context);
+		target.renderer.render(target.context.scene, target.context.camera);
+	}
+	function tick(now) {
+		const target = instance;
+		if (!target) return;
+		const delta = target.last ? Math.min((now - target.last) / 1e3, .1) : 0;
+		target.last = now;
+		target.time += delta;
+		draw(target, delta);
+	}
+	function invalidate() {
+		const target = instance;
+		if (!target || target.ticking || target.pending) return;
+		target.pending = requestAnimationFrame(() => {
+			target.pending = 0;
+			if (instance === target) draw(target, 0);
+		});
+	}
+	function resize(target) {
+		const { canvas, context, renderer, handle } = target;
+		const size = context.size;
+		size.width = canvas.clientWidth;
+		size.height = canvas.clientHeight;
+		size.pixelRatio = Math.min(globalThis.devicePixelRatio || 1, context.quality.pixelRatio) * clamp(options.resolution?.() ?? 1, .1, 1);
+		renderer.setPixelRatio(size.pixelRatio);
+		renderer.setSize(size.width, size.height, false);
+		const camera = context.camera;
+		if (camera.isPerspectiveCamera && size.height > 0) {
+			camera.aspect = size.width / size.height;
+			camera.updateProjectionMatrix();
+		}
+		handle.resize?.(size, context);
+		invalidate();
+	}
+	function create(canvas, level) {
+		const quality = resolveThreeQuality(level);
+		const renderer = new WebGLRenderer({
+			canvas,
+			alpha: true,
+			antialias: quality.antialias
+		});
+		renderer.setClearColor(0, 0);
+		const camera = new PerspectiveCamera(45, 1, .1, 100);
+		camera.position.z = 5;
+		const colorSets = [];
+		const context = {
+			renderer,
+			scene: new Scene(),
+			camera,
+			canvas,
+			size: {
+				width: 0,
+				height: 0,
+				pixelRatio: 1
+			},
+			quality,
+			pointer,
+			get still() {
+				return still();
+			},
+			invalidate,
+			themeColors(sources) {
+				const set = createThemeColorSet(invalidate);
+				set.refresh(canvas, sources, false);
+				colorSets.push({
+					set,
+					sources
+				});
+				return set.colors;
+			},
+			themeColorList(sources, size) {
+				const used = size == null ? sources : sources.slice(0, size);
+				const themed = context.themeColors(Object.fromEntries(used.map((color, i) => [i, color])));
+				const list = used.map((_, index) => themed[index]);
+				while (size != null && list.length < size) list.push(list.at(-1));
+				return list;
+			}
+		};
+		const target = {
+			renderer,
+			context,
+			handle: {},
+			canvas,
+			onLost: () => lose(target),
+			time: 0,
+			last: 0,
+			pending: 0,
+			ticking: false,
+			colorSets
+		};
+		canvas.addEventListener("webglcontextlost", target.onLost);
+		return target;
+	}
+	function start() {
+		const canvas = options.canvas();
+		if (unmounted || instance || !canvas || !visible.value || status.value === "fallback") return;
+		const level = options.quality?.();
+		if (level === "off") return;
+		if (!acquireContext(holder)) return;
+		try {
+			instance = create(canvas, level);
+		} catch {
+			releaseContext(holder);
+			unsupported = true;
+			status.value = "fallback";
+			return;
+		}
+		try {
+			instance.handle = options.setup(instance.context) ?? {};
+		} catch (error) {
+			teardown();
+			unsupported = true;
+			status.value = "fallback";
+			throw error;
+		}
+		resize(instance);
+		update();
+	}
+	function teardown() {
+		const target = instance;
+		if (!target) return;
+		instance = void 0;
+		tickers.delete(tick);
+		cancelAnimationFrame(target.pending);
+		target.canvas.removeEventListener("webglcontextlost", target.onLost);
+		for (const { set } of target.colorSets) set.stop();
+		target.handle.dispose?.();
+		disposeObject(target.context.scene);
+		target.renderer.dispose();
+		if (!target.renderer.getContext().isContextLost()) target.renderer.forceContextLoss();
+		releaseContext(holder);
+	}
+	function lose(target) {
+		if (instance !== target) return;
+		teardown();
+		losses++;
+		unsupported = losses >= MAX_CONTEXT_LOSSES;
+		status.value = unsupported ? "fallback" : "idle";
+		if (status.value === "idle") generation.value++;
+	}
+	/** 按可见性、暂停、静止决定循环开还是停 */
+	function update() {
+		const target = instance;
+		if (!target) return;
+		const mode = still() ? "still" : options.paused?.() || !visible.value || !pageVisible.value ? "paused" : "running";
+		target.ticking = mode === "running";
+		if (target.ticking) {
+			target.last = 0;
+			subscribe(tick);
+		} else {
+			tickers.delete(tick);
+			if (mode === "still") invalidate();
+		}
+		status.value = mode;
+	}
+	if (typeof IntersectionObserver === "undefined") visible.value = true;
+	useIntersectionObserver(options.canvas, ([entry]) => {
+		visible.value = entry.isIntersecting;
+		lastSeen = performance.now();
+	});
+	useResizeObserver(options.canvas, () => instance && resize(instance));
+	watch(options.canvas, (canvas) => canvas && start(), {
+		immediate: true,
+		flush: "post"
+	});
+	watch(visible, (shown) => {
+		if (instance) update();
+		else start();
+		if (!shown && instance) retryWaiting();
+	});
+	watch([
+		() => options.paused?.(),
+		reducedMotion,
+		themeStill,
+		pageVisible
+	], update);
+	watch([() => config.theme, options.canvas], ([, canvas]) => {
+		if (!canvas) return;
+		themeStill.value = themeMotionOff(canvas);
+		for (const { set, sources } of instance?.colorSets ?? []) set.refresh(canvas, sources, true);
+		invalidate();
+	}, {
+		immediate: true,
+		flush: "post"
+	});
+	watch(() => options.resolution?.(), () => instance && resize(instance));
+	watch(() => options.quality?.(), () => {
+		if (unsupported) return;
+		if (off()) {
+			teardown();
+			status.value = "fallback";
+		} else if (instance || status.value === "fallback") {
+			teardown();
+			status.value = "idle";
+			generation.value++;
+		}
+	});
+	onScopeDispose(() => {
+		unmounted = true;
+		teardown();
+		releaseContext(holder);
+	});
+	return {
+		get status() {
+			return status.value;
+		},
+		get generation() {
+			return generation.value;
+		},
+		invalidate
+	};
+}
+//#endregion
+export { useThree };
+
+//# sourceMappingURL=renderer.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.js","names":[],"sources":["../../../src/three/core/renderer.ts"],"sourcesContent":["/**\n * three.js 渲染器的生命周期（ThreeCanvas 用它；要自己安排外层结构时也可以直接用）：\n *\n *   const three = useThree({ canvas: () => canvas, setup: (context) => { …; return { frame } } });\n *   <canvas key={three.generation} ref={…} />\n *\n * - 第一次进入视口时才创建渲染器，占用 WebGL 上下文的名额（quality.ts）；被回收、上下文丢失后换一块新 canvas\n *   （generation 加一，渲染方用它作 key）再建，所以场景要在 setup 里搭，不要在外面持有渲染器；\n * - 所有效果共用一个 requestAnimationFrame 循环；滚出视口、标签页隐藏、paused 时停下；\n * - 减少动态效果（系统设置，或主题的时长为 0）时只画一帧静止画面，尺寸、主题色变化时（invalidate）重画；\n * - 尺寸跟随 canvas 的布局尺寸（ResizeObserver），像素比取设备与画质档位上限的较小值；\n * - 卸载、被回收时释放场景里的几何体、材质、纹理和渲染器，并立即交还上下文（forceContextLoss），\n *   不等浏览器回收；上下文连续丢失三次后改显示降级内容。\n */\nimport { PerspectiveCamera, Scene, WebGLRenderer, type Camera, type Color } from 'three';\nimport { onScopeDispose, shallowRef, watch } from 'vue';\nimport { useConfig } from '../../config/context';\nimport { readToken } from '../../config/theme/theme';\nimport { durations } from '../../config/theme/tokens';\nimport { useReducedMotion } from '../../utils/dom/media-query';\nimport { useIntersectionObserver } from '../../utils/dom/intersection';\nimport { usePageVisible } from '../../utils/dom/page-visibility';\nimport { useResizeObserver } from '../../utils/dom/resize';\nimport { disposeObject } from './dispose';\nimport { clamp } from '../../utils/data/number';\nimport { parseDuration } from '../../utils/motion/animation';\nimport { usePointer, type PointerState } from '../../utils/motion/pointer';\nimport {\n  acquireContext,\n  releaseContext,\n  resolveThreeQuality,\n  retryWaiting,\n  type ContextHolder,\n  type ResolvedThreeQuality,\n  type ThreeQuality,\n} from './quality';\nimport {\n  createThemeColorSet,\n  type ThemeColors,\n  type ThemeColorSet,\n  type ThemeColorSources,\n} from './theme-colors';\n\n/** 画布的尺寸（CSS 像素）与实际使用的像素比 */\nexport interface ThreeSize {\n  /** 宽度（CSS 像素） */\n  width: number;\n  /** 高度（CSS 像素） */\n  height: number;\n  /** 实际使用的像素比：设备像素比按画质档位封顶 */\n  pixelRatio: number;\n}\n\n/** 交给 setup 的场景上下文 */\nexport interface ThreeContext {\n  /** 渲染器：透明背景，像素比与尺寸由这里管理 */\n  readonly renderer: WebGLRenderer;\n  /** 场景：卸载时连同里面的几何体、材质、纹理一起释放 */\n  readonly scene: Scene;\n  /** 相机：默认是透视相机（视角 45°，位于 z = 5），宽高比自动跟随；可以换成别的相机 */\n  camera: Camera;\n  /** 渲染器画到的 canvas 元素 */\n  readonly canvas: HTMLCanvasElement;\n  /** 当前尺寸，随布局变化 */\n  readonly size: Readonly<ThreeSize>;\n  /** 画质档位的参数：粒子数、细分等按 density 缩放 */\n  readonly quality: ResolvedThreeQuality;\n  /** 只画静止画面（减少动态效果）：指针跟随之类的交互也应停下 */\n  readonly still: boolean;\n  /** 指针相对画布的位置（-1 到 1）与 strength（指针在画布上为 1，离开后淡出），弹簧阻尼，见 pointer.ts */\n  readonly pointer: PointerState;\n  /** 请求重画一帧：循环停着（静止、暂停）时，数据变了用它刷新 */\n  invalidate: () => void;\n  /**\n   * 跟随画布所在位置主题的颜色（THREE.Color）：换主题时原地过渡到新色并重画。\n   * 材质的 color 直接赋这个对象（`material.color = palette.accent`），见 theme-colors.ts\n   */\n  themeColors: <Sources extends ThemeColorSources>(sources: Sources) => ThemeColors<Sources>;\n  /**\n   * 一列跟随主题的颜色（着色器的色板 uColors、粒子的色调）：给了 size 时取前 size 个，不足的用最后一个补齐\n   * （uniform 数组的长度是固定的）；sources 不能为空\n   */\n  themeColorList: (sources: readonly string[], size?: number) => Color[];\n}\n\n/** 每帧交给 frame 的时间 */\nexport interface ThreeFrame {\n  /** 动画时间（秒）：只在循环运行时增长，暂停后接着走 */\n  time: number;\n  /** 距上一帧（秒），最多 0.1：切回标签页时不跳一大步 */\n  delta: number;\n}\n\n/** setup 返回的场景回调，都可省 */\nexport interface ThreeSceneHandle {\n  /** 每帧渲染前调用：更新 uniform、位置 */\n  frame?(frame: ThreeFrame, context: ThreeContext): void;\n  /** 尺寸变化后调用（相机的宽高比已更新） */\n  resize?(size: Readonly<ThreeSize>, context: ThreeContext): void;\n  /** 释放前调用：清理 setup 里自己加的监听、加载器；场景里的对象由这里统一释放 */\n  dispose?(): void;\n}\n\n/** 渲染状态，写在根元素的 data-state 上 */\nexport type ThreeStatus =\n  /** 还没创建（没进过视口、在排队、被回收） */\n  | 'idle'\n  /** 循环运行中 */\n  | 'running'\n  /** 停着：滚出视口、标签页隐藏或 paused */\n  | 'paused'\n  /** 只画了一帧静止画面（减少动态效果） */\n  | 'still'\n  /** 没有 WebGL，或画质是 off：显示降级内容 */\n  | 'fallback';\n\n/** useThree 的选项 */\nexport interface ThreeOptions {\n  /** 画在哪块 canvas 上（渲染方按 generation 换新的） */\n  canvas: () => HTMLCanvasElement | null | undefined;\n  /** 搭场景：每次创建渲染器时调用一次 */\n  setup: (context: ThreeContext) => ThreeSceneHandle | void;\n  /** 画质档位，默认 auto；变了会重建，off 时释放渲染器、显示降级内容 */\n  quality?: () => ThreeQuality | undefined;\n  /** 暂停循环（停在当前画面） */\n  paused?: () => boolean | undefined;\n  /** 渲染分辨率相对像素比的倍数（0–1），平滑的渐变类效果用 0.5 能省下大半的填充开销；默认 1 */\n  resolution?: () => number | undefined;\n}\n\n/** useThree 的返回值 */\nexport interface ThreeController {\n  /** 渲染状态，响应式 */\n  readonly status: ThreeStatus;\n  /** canvas 的代数：重建时加一，渲染方用作 canvas 的 key */\n  readonly generation: number;\n  /** 请求重画一帧 */\n  invalidate: () => void;\n}\n\n// 所有效果共用一个动画帧循环\nconst tickers = new Set<(now: number) => void>();\nlet tickerFrame = 0;\n\nfunction runTickers(now: number) {\n  tickerFrame = 0;\n  for (const tick of [...tickers]) tick(now);\n  if (tickers.size) tickerFrame = requestAnimationFrame(runTickers);\n}\n\nfunction subscribe(tick: (now: number) => void) {\n  tickers.add(tick);\n  tickerFrame ||= requestAnimationFrame(runTickers);\n}\n\n/** 上下文连续丢失这么多次后不再重建，改显示降级内容 */\nconst MAX_CONTEXT_LOSSES = 3;\n\n/** 主题的时长为 0（主题编辑器关掉了动效，或系统要求减少动态效果）：读不到主题时当作有动效 */\nfunction themeMotionOff(element: Element) {\n  try {\n    return parseDuration(readToken(element, durations.md)) === 0;\n  } catch {\n    return false;\n  }\n}\n\ninterface Instance {\n  renderer: WebGLRenderer;\n  context: ThreeContext;\n  handle: ThreeSceneHandle;\n  canvas: HTMLCanvasElement;\n  onLost: () => void;\n  time: number;\n  last: number;\n  pending: number;\n  ticking: boolean;\n  colorSets: { set: ThemeColorSet<ThemeColorSources>; sources: ThemeColorSources }[];\n}\n\n/** three.js 渲染器的生命周期（在 setup 里调用），见文件开头 */\nexport function useThree(options: ThreeOptions): ThreeController {\n  const config = useConfig();\n  const reducedMotion = useReducedMotion();\n  const off = () => options.quality?.() === 'off';\n  const status = shallowRef<ThreeStatus>(off() ? 'fallback' : 'idle');\n  const pointer = usePointer(options.canvas);\n  const generation = shallowRef(0);\n  const themeStill = shallowRef(false);\n  const pageVisible = usePageVisible();\n  const visible = shallowRef(false);\n\n  let instance: Instance | undefined;\n  let lastSeen = 0;\n  let losses = 0;\n  let unmounted = false;\n  // 创建失败或上下文反复丢失：换画质也不再重试（区别于 off 的降级）\n  let unsupported = false;\n\n  const still = () => reducedMotion.value || themeStill.value;\n\n  const holder: ContextHolder = {\n    get visible() {\n      return visible.value;\n    },\n    get lastSeen() {\n      return lastSeen;\n    },\n    evict() {\n      teardown();\n      status.value = 'idle';\n      generation.value++;\n    },\n    retry: () => start(),\n  };\n\n  function draw(target: Instance, delta: number) {\n    target.handle.frame?.({ time: target.time, delta }, target.context);\n    target.renderer.render(target.context.scene, target.context.camera);\n  }\n\n  function tick(now: number) {\n    const target = instance;\n    if (!target) return;\n    const delta = target.last ? Math.min((now - target.last) / 1000, 0.1) : 0;\n    target.last = now;\n    target.time += delta;\n    draw(target, delta);\n  }\n\n  function invalidate() {\n    const target = instance;\n    if (!target || target.ticking || target.pending) return;\n    target.pending = requestAnimationFrame(() => {\n      target.pending = 0;\n      if (instance === target) draw(target, 0);\n    });\n  }\n\n  function resize(target: Instance) {\n    const { canvas, context, renderer, handle } = target;\n    const size = context.size as ThreeSize;\n    size.width = canvas.clientWidth;\n    size.height = canvas.clientHeight;\n    size.pixelRatio =\n      Math.min(globalThis.devicePixelRatio || 1, context.quality.pixelRatio) *\n      clamp(options.resolution?.() ?? 1, 0.1, 1);\n    renderer.setPixelRatio(size.pixelRatio);\n    renderer.setSize(size.width, size.height, false);\n    const camera = context.camera as Camera & Partial<PerspectiveCamera>;\n    if (camera.isPerspectiveCamera && size.height > 0) {\n      camera.aspect = size.width / size.height;\n      camera.updateProjectionMatrix!();\n    }\n    handle.resize?.(size, context);\n    invalidate();\n  }\n\n  function create(\n    canvas: HTMLCanvasElement,\n    level: Exclude<ThreeQuality, 'off'> | undefined,\n  ): Instance {\n    const quality = resolveThreeQuality(level);\n    const renderer = new WebGLRenderer({ canvas, alpha: true, antialias: quality.antialias });\n    renderer.setClearColor(0x000000, 0);\n    const camera = new PerspectiveCamera(45, 1, 0.1, 100);\n    camera.position.z = 5;\n    const colorSets: Instance['colorSets'] = [];\n    const context: ThreeContext = {\n      renderer,\n      scene: new Scene(),\n      camera,\n      canvas,\n      size: { width: 0, height: 0, pixelRatio: 1 },\n      quality,\n      pointer,\n      get still() {\n        return still();\n      },\n      invalidate,\n      themeColors(sources) {\n        const set = createThemeColorSet<typeof sources>(invalidate);\n        set.refresh(canvas, sources, false);\n        colorSets.push({ set, sources });\n        return set.colors;\n      },\n      themeColorList(sources, size) {\n        const used = size == null ? sources : sources.slice(0, size);\n        const themed = context.themeColors(Object.fromEntries(used.map((color, i) => [i, color])));\n        const list = used.map((_, index) => themed[index]!);\n        while (size != null && list.length < size) list.push(list.at(-1)!);\n        return list;\n      },\n    };\n    const target: Instance = {\n      renderer,\n      context,\n      handle: {},\n      canvas,\n      onLost: () => lose(target),\n      time: 0,\n      last: 0,\n      pending: 0,\n      ticking: false,\n      colorSets,\n    };\n    canvas.addEventListener('webglcontextlost', target.onLost);\n    return target;\n  }\n\n  function start() {\n    const canvas = options.canvas();\n    if (unmounted || instance || !canvas || !visible.value || status.value === 'fallback') return;\n    const level = options.quality?.();\n    if (level === 'off') return;\n    if (!acquireContext(holder)) return;\n    try {\n      instance = create(canvas, level);\n    } catch {\n      // 没有 WebGL（浏览器禁用、驱动黑名单、测试环境）\n      releaseContext(holder);\n      unsupported = true;\n      status.value = 'fallback';\n      return;\n    }\n    try {\n      instance.handle = options.setup(instance.context) ?? {};\n    } catch (error) {\n      teardown();\n      unsupported = true;\n      status.value = 'fallback';\n      throw error;\n    }\n    resize(instance);\n    update();\n  }\n\n  function teardown() {\n    const target = instance;\n    if (!target) return;\n    instance = undefined;\n    tickers.delete(tick);\n    cancelAnimationFrame(target.pending);\n    target.canvas.removeEventListener('webglcontextlost', target.onLost);\n    for (const { set } of target.colorSets) set.stop();\n    target.handle.dispose?.();\n    disposeObject(target.context.scene);\n    target.renderer.dispose();\n    if (!target.renderer.getContext().isContextLost()) target.renderer.forceContextLoss();\n    releaseContext(holder);\n  }\n\n  function lose(target: Instance) {\n    if (instance !== target) return;\n    teardown();\n    losses++;\n    unsupported = losses >= MAX_CONTEXT_LOSSES;\n    status.value = unsupported ? 'fallback' : 'idle';\n    // 丢失过上下文的 canvas 拿不回新的上下文：换一块\n    if (status.value === 'idle') generation.value++;\n  }\n\n  /** 按可见性、暂停、静止决定循环开还是停 */\n  function update() {\n    const target = instance;\n    if (!target) return;\n    const mode: ThreeStatus = still()\n      ? 'still'\n      : options.paused?.() || !visible.value || !pageVisible.value\n        ? 'paused'\n        : 'running';\n    target.ticking = mode === 'running';\n    if (target.ticking) {\n      target.last = 0;\n      subscribe(tick);\n    } else {\n      tickers.delete(tick);\n      if (mode === 'still') invalidate();\n    }\n    status.value = mode;\n  }\n\n  // 没有 IntersectionObserver 的环境（服务端、旧测试环境）当作一直在视口里\n  if (typeof IntersectionObserver === 'undefined') visible.value = true;\n  useIntersectionObserver(options.canvas, ([entry]) => {\n    visible.value = entry!.isIntersecting;\n    lastSeen = performance.now();\n  });\n  useResizeObserver(options.canvas, () => instance && resize(instance));\n  watch(options.canvas, (canvas) => canvas && start(), { immediate: true, flush: 'post' });\n\n  watch(visible, (shown) => {\n    if (instance) update();\n    else start();\n    // 滚出视口的效果可以被回收：排队的效果再试\n    if (!shown && instance) retryWaiting();\n  });\n  watch([() => options.paused?.(), reducedMotion, themeStill, pageVisible], update);\n\n  // 主题变了（含主题编辑器关掉动效）：重新判断要不要静止，并重画\n  watch(\n    [() => config.theme, options.canvas],\n    ([, canvas]) => {\n      if (!canvas) return;\n      themeStill.value = themeMotionOff(canvas);\n      for (const { set, sources } of instance?.colorSets ?? []) set.refresh(canvas, sources, true);\n      invalidate();\n    },\n    { immediate: true, flush: 'post' },\n  );\n\n  watch(\n    () => options.resolution?.(),\n    () => instance && resize(instance),\n  );\n\n  watch(\n    () => options.quality?.(),\n    () => {\n      if (unsupported) return;\n      if (off()) {\n        teardown();\n        status.value = 'fallback';\n      } else if (instance || status.value === 'fallback') {\n        // 换档重建；从 off 回来时渲染方重新挂上 canvas，再按可见性创建\n        teardown();\n        status.value = 'idle';\n        generation.value++;\n      }\n    },\n  );\n\n  onScopeDispose(() => {\n    unmounted = true;\n    teardown();\n    releaseContext(holder);\n  });\n\n  return {\n    get status() {\n      return status.value;\n    },\n    get generation() {\n      return generation.value;\n    },\n    invalidate,\n  };\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,19 @@
+/**
+ * 着色器的公共片段（GLSL 字符串），拼进自己的片段着色器：
+ *
+ *   const fragmentShader = `
+ *     ${shaderChunks.simplexNoise}
+ *     ${shaderChunks.themePalette}
+ *     void main() { gl_FragColor = vec4(themePalette(snoise(vec3(vUv * 3.0, uTime)) * 0.5 + 0.5), 1.0); }
+ *   `;
+ *
+ * themePalette 用的 uColors、uColorCount 由 ShaderBackground 自动传入（主题色板）。
+ */
+/** 色板最多几个颜色（uColors 数组的长度） */
+export declare const THEME_PALETTE_SIZE = 6;
+/** 公共着色器片段：simplexNoise、fbm、themePalette */
+export declare const shaderChunks: {
+    readonly simplexNoise: "\nvec3 mod289(vec3 x) { return x - floor(x * (1.0 / 289.0)) * 289.0; }\nvec4 mod289(vec4 x) { return x - floor(x * (1.0 / 289.0)) * 289.0; }\nvec4 permute(vec4 x) { return mod289(((x * 34.0) + 10.0) * x); }\nvec4 taylorInvSqrt(vec4 r) { return 1.79284291400159 - 0.85373472095314 * r; }\n\nfloat snoise(vec3 v) {\n  const vec2 C = vec2(1.0 / 6.0, 1.0 / 3.0);\n  const vec4 D = vec4(0.0, 0.5, 1.0, 2.0);\n  vec3 i = floor(v + dot(v, C.yyy));\n  vec3 x0 = v - i + dot(i, C.xxx);\n  vec3 g = step(x0.yzx, x0.xyz);\n  vec3 l = 1.0 - g;\n  vec3 i1 = min(g.xyz, l.zxy);\n  vec3 i2 = max(g.xyz, l.zxy);\n  vec3 x1 = x0 - i1 + C.xxx;\n  vec3 x2 = x0 - i2 + C.yyy;\n  vec3 x3 = x0 - D.yyy;\n  i = mod289(i);\n  vec4 p = permute(permute(permute(\n    i.z + vec4(0.0, i1.z, i2.z, 1.0))\n    + i.y + vec4(0.0, i1.y, i2.y, 1.0))\n    + i.x + vec4(0.0, i1.x, i2.x, 1.0));\n  float n_ = 0.142857142857;\n  vec3 ns = n_ * D.wyz - D.xzx;\n  vec4 j = p - 49.0 * floor(p * ns.z * ns.z);\n  vec4 x_ = floor(j * ns.z);\n  vec4 y_ = floor(j - 7.0 * x_);\n  vec4 x = x_ * ns.x + ns.yyyy;\n  vec4 y = y_ * ns.x + ns.yyyy;\n  vec4 h = 1.0 - abs(x) - abs(y);\n  vec4 b0 = vec4(x.xy, y.xy);\n  vec4 b1 = vec4(x.zw, y.zw);\n  vec4 s0 = floor(b0) * 2.0 + 1.0;\n  vec4 s1 = floor(b1) * 2.0 + 1.0;\n  vec4 sh = -step(h, vec4(0.0));\n  vec4 a0 = b0.xzyw + s0.xzyw * sh.xxyy;\n  vec4 a1 = b1.xzyw + s1.xzyw * sh.zzww;\n  vec3 p0 = vec3(a0.xy, h.x);\n  vec3 p1 = vec3(a0.zw, h.y);\n  vec3 p2 = vec3(a1.xy, h.z);\n  vec3 p3 = vec3(a1.zw, h.w);\n  vec4 norm = taylorInvSqrt(vec4(dot(p0, p0), dot(p1, p1), dot(p2, p2), dot(p3, p3)));\n  p0 *= norm.x;\n  p1 *= norm.y;\n  p2 *= norm.z;\n  p3 *= norm.w;\n  vec4 m = max(0.5 - vec4(dot(x0, x0), dot(x1, x1), dot(x2, x2), dot(x3, x3)), 0.0);\n  m = m * m;\n  return 105.0 * dot(m * m, vec4(dot(p0, x0), dot(p1, x1), dot(p2, x2), dot(p3, x3)));\n}\n";
+    readonly fbm: "\nfloat fbm(vec3 p) {\n  float sum = 0.0;\n  float amplitude = 0.5;\n  for (int octave = 0; octave < 4; octave++) {\n    sum += amplitude * snoise(p);\n    p = p * 2.02 + vec3(17.0);\n    amplitude *= 0.5;\n  }\n  return sum;\n}\n";
+    readonly themePalette: "\n#define THEME_PALETTE_SIZE 6\nuniform vec3 uColors[THEME_PALETTE_SIZE];\nuniform int uColorCount;\n\nvec3 themePalette(float t) {\n  float scaled = clamp(t, 0.0, 1.0) * float(max(uColorCount - 1, 1));\n  vec3 color = uColors[0];\n  for (int i = 1; i < THEME_PALETTE_SIZE; i++) {\n    if (i >= uColorCount) break;\n    color = mix(color, uColors[i], clamp(scaled - float(i - 1), 0.0, 1.0));\n  }\n  return color;\n}\n";
+};

package/dist/three/core/shaders.js

@@ -0,0 +1,100 @@
+//#region src/three/core/shaders.ts
+/**
+* 着色器的公共片段（GLSL 字符串），拼进自己的片段着色器：
+*
+*   const fragmentShader = `
+*     ${shaderChunks.simplexNoise}
+*     ${shaderChunks.themePalette}
+*     void main() { gl_FragColor = vec4(themePalette(snoise(vec3(vUv * 3.0, uTime)) * 0.5 + 0.5), 1.0); }
+*   `;
+*
+* themePalette 用的 uColors、uColorCount 由 ShaderBackground 自动传入（主题色板）。
+*/
+/** 色板最多几个颜色（uColors 数组的长度） */
+var THEME_PALETTE_SIZE = 6;
+/** 公共着色器片段：simplexNoise、fbm、themePalette */
+var shaderChunks = {
+	simplexNoise: `
+vec3 mod289(vec3 x) { return x - floor(x * (1.0 / 289.0)) * 289.0; }
+vec4 mod289(vec4 x) { return x - floor(x * (1.0 / 289.0)) * 289.0; }
+vec4 permute(vec4 x) { return mod289(((x * 34.0) + 10.0) * x); }
+vec4 taylorInvSqrt(vec4 r) { return 1.79284291400159 - 0.85373472095314 * r; }
+
+float snoise(vec3 v) {
+  const vec2 C = vec2(1.0 / 6.0, 1.0 / 3.0);
+  const vec4 D = vec4(0.0, 0.5, 1.0, 2.0);
+  vec3 i = floor(v + dot(v, C.yyy));
+  vec3 x0 = v - i + dot(i, C.xxx);
+  vec3 g = step(x0.yzx, x0.xyz);
+  vec3 l = 1.0 - g;
+  vec3 i1 = min(g.xyz, l.zxy);
+  vec3 i2 = max(g.xyz, l.zxy);
+  vec3 x1 = x0 - i1 + C.xxx;
+  vec3 x2 = x0 - i2 + C.yyy;
+  vec3 x3 = x0 - D.yyy;
+  i = mod289(i);
+  vec4 p = permute(permute(permute(
+    i.z + vec4(0.0, i1.z, i2.z, 1.0))
+    + i.y + vec4(0.0, i1.y, i2.y, 1.0))
+    + i.x + vec4(0.0, i1.x, i2.x, 1.0));
+  float n_ = 0.142857142857;
+  vec3 ns = n_ * D.wyz - D.xzx;
+  vec4 j = p - 49.0 * floor(p * ns.z * ns.z);
+  vec4 x_ = floor(j * ns.z);
+  vec4 y_ = floor(j - 7.0 * x_);
+  vec4 x = x_ * ns.x + ns.yyyy;
+  vec4 y = y_ * ns.x + ns.yyyy;
+  vec4 h = 1.0 - abs(x) - abs(y);
+  vec4 b0 = vec4(x.xy, y.xy);
+  vec4 b1 = vec4(x.zw, y.zw);
+  vec4 s0 = floor(b0) * 2.0 + 1.0;
+  vec4 s1 = floor(b1) * 2.0 + 1.0;
+  vec4 sh = -step(h, vec4(0.0));
+  vec4 a0 = b0.xzyw + s0.xzyw * sh.xxyy;
+  vec4 a1 = b1.xzyw + s1.xzyw * sh.zzww;
+  vec3 p0 = vec3(a0.xy, h.x);
+  vec3 p1 = vec3(a0.zw, h.y);
+  vec3 p2 = vec3(a1.xy, h.z);
+  vec3 p3 = vec3(a1.zw, h.w);
+  vec4 norm = taylorInvSqrt(vec4(dot(p0, p0), dot(p1, p1), dot(p2, p2), dot(p3, p3)));
+  p0 *= norm.x;
+  p1 *= norm.y;
+  p2 *= norm.z;
+  p3 *= norm.w;
+  vec4 m = max(0.5 - vec4(dot(x0, x0), dot(x1, x1), dot(x2, x2), dot(x3, x3)), 0.0);
+  m = m * m;
+  return 105.0 * dot(m * m, vec4(dot(p0, x0), dot(p1, x1), dot(p2, x2), dot(p3, x3)));
+}
+`,
+	fbm: `
+float fbm(vec3 p) {
+  float sum = 0.0;
+  float amplitude = 0.5;
+  for (int octave = 0; octave < 4; octave++) {
+    sum += amplitude * snoise(p);
+    p = p * 2.02 + vec3(17.0);
+    amplitude *= 0.5;
+  }
+  return sum;
+}
+`,
+	themePalette: `
+#define THEME_PALETTE_SIZE 6
+uniform vec3 uColors[THEME_PALETTE_SIZE];
+uniform int uColorCount;
+
+vec3 themePalette(float t) {
+  float scaled = clamp(t, 0.0, 1.0) * float(max(uColorCount - 1, 1));
+  vec3 color = uColors[0];
+  for (int i = 1; i < THEME_PALETTE_SIZE; i++) {
+    if (i >= uColorCount) break;
+    color = mix(color, uColors[i], clamp(scaled - float(i - 1), 0.0, 1.0));
+  }
+  return color;
+}
+`
+};
+//#endregion
+export { THEME_PALETTE_SIZE, shaderChunks };
+
+//# sourceMappingURL=shaders.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shaders.js","names":[],"sources":["../../../src/three/core/shaders.ts"],"sourcesContent":["/**\n * 着色器的公共片段（GLSL 字符串），拼进自己的片段着色器：\n *\n *   const fragmentShader = `\n *     ${shaderChunks.simplexNoise}\n *     ${shaderChunks.themePalette}\n *     void main() { gl_FragColor = vec4(themePalette(snoise(vec3(vUv * 3.0, uTime)) * 0.5 + 0.5), 1.0); }\n *   `;\n *\n * themePalette 用的 uColors、uColorCount 由 ShaderBackground 自动传入（主题色板）。\n */\n\n/** 色板最多几个颜色（uColors 数组的长度） */\nexport const THEME_PALETTE_SIZE = 6;\n\n/**\n * 三维 simplex 噪声 `float snoise(vec3 v)`，返回 -1 到 1。\n * 来自 Ashima Arts 的 webgl-noise（Ian McEwan、Stefan Gustavson，MIT 许可）\n */\nconst simplexNoise = /* glsl */ `\nvec3 mod289(vec3 x) { return x - floor(x * (1.0 / 289.0)) * 289.0; }\nvec4 mod289(vec4 x) { return x - floor(x * (1.0 / 289.0)) * 289.0; }\nvec4 permute(vec4 x) { return mod289(((x * 34.0) + 10.0) * x); }\nvec4 taylorInvSqrt(vec4 r) { return 1.79284291400159 - 0.85373472095314 * r; }\n\nfloat snoise(vec3 v) {\n  const vec2 C = vec2(1.0 / 6.0, 1.0 / 3.0);\n  const vec4 D = vec4(0.0, 0.5, 1.0, 2.0);\n  vec3 i = floor(v + dot(v, C.yyy));\n  vec3 x0 = v - i + dot(i, C.xxx);\n  vec3 g = step(x0.yzx, x0.xyz);\n  vec3 l = 1.0 - g;\n  vec3 i1 = min(g.xyz, l.zxy);\n  vec3 i2 = max(g.xyz, l.zxy);\n  vec3 x1 = x0 - i1 + C.xxx;\n  vec3 x2 = x0 - i2 + C.yyy;\n  vec3 x3 = x0 - D.yyy;\n  i = mod289(i);\n  vec4 p = permute(permute(permute(\n    i.z + vec4(0.0, i1.z, i2.z, 1.0))\n    + i.y + vec4(0.0, i1.y, i2.y, 1.0))\n    + i.x + vec4(0.0, i1.x, i2.x, 1.0));\n  float n_ = 0.142857142857;\n  vec3 ns = n_ * D.wyz - D.xzx;\n  vec4 j = p - 49.0 * floor(p * ns.z * ns.z);\n  vec4 x_ = floor(j * ns.z);\n  vec4 y_ = floor(j - 7.0 * x_);\n  vec4 x = x_ * ns.x + ns.yyyy;\n  vec4 y = y_ * ns.x + ns.yyyy;\n  vec4 h = 1.0 - abs(x) - abs(y);\n  vec4 b0 = vec4(x.xy, y.xy);\n  vec4 b1 = vec4(x.zw, y.zw);\n  vec4 s0 = floor(b0) * 2.0 + 1.0;\n  vec4 s1 = floor(b1) * 2.0 + 1.0;\n  vec4 sh = -step(h, vec4(0.0));\n  vec4 a0 = b0.xzyw + s0.xzyw * sh.xxyy;\n  vec4 a1 = b1.xzyw + s1.xzyw * sh.zzww;\n  vec3 p0 = vec3(a0.xy, h.x);\n  vec3 p1 = vec3(a0.zw, h.y);\n  vec3 p2 = vec3(a1.xy, h.z);\n  vec3 p3 = vec3(a1.zw, h.w);\n  vec4 norm = taylorInvSqrt(vec4(dot(p0, p0), dot(p1, p1), dot(p2, p2), dot(p3, p3)));\n  p0 *= norm.x;\n  p1 *= norm.y;\n  p2 *= norm.z;\n  p3 *= norm.w;\n  vec4 m = max(0.5 - vec4(dot(x0, x0), dot(x1, x1), dot(x2, x2), dot(x3, x3)), 0.0);\n  m = m * m;\n  return 105.0 * dot(m * m, vec4(dot(p0, x0), dot(p1, x1), dot(p2, x2), dot(p3, x3)));\n}\n`;\n\n/** 分形噪声 `float fbm(vec3 p)`：几层 simplex 噪声叠加，返回约 -1 到 1；依赖 simplexNoise */\nconst fbm = /* glsl */ `\nfloat fbm(vec3 p) {\n  float sum = 0.0;\n  float amplitude = 0.5;\n  for (int octave = 0; octave < 4; octave++) {\n    sum += amplitude * snoise(p);\n    p = p * 2.02 + vec3(17.0);\n    amplitude *= 0.5;\n  }\n  return sum;\n}\n`;\n\n/** 主题色板 `vec3 themePalette(float t)`：t 从 0 到 1 依次经过 uColors 的各个颜色；uColors 的长度是 THEME_PALETTE_SIZE */\nconst themePalette = /* glsl */ `\n#define THEME_PALETTE_SIZE ${THEME_PALETTE_SIZE}\nuniform vec3 uColors[THEME_PALETTE_SIZE];\nuniform int uColorCount;\n\nvec3 themePalette(float t) {\n  float scaled = clamp(t, 0.0, 1.0) * float(max(uColorCount - 1, 1));\n  vec3 color = uColors[0];\n  for (int i = 1; i < THEME_PALETTE_SIZE; i++) {\n    if (i >= uColorCount) break;\n    color = mix(color, uColors[i], clamp(scaled - float(i - 1), 0.0, 1.0));\n  }\n  return color;\n}\n`;\n\n/** 公共着色器片段：simplexNoise、fbm、themePalette */\nexport const shaderChunks = { simplexNoise, fbm, themePalette } as const;\n"],"mappings":";;;;;;;;;;;;;AAaA,IAAa,qBAAqB;;AA2FlC,IAAa,eAAe;CAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAAc;;;;;;;;;;;;CAAK;;;;;;;;;;;;;;;AAAa"}

package/dist/three/core/theme-colors.d.ts

@@ -0,0 +1,30 @@
+import { Color } from 'three';
+/** 一组要读的颜色：名字 → token 或 CSS 颜色 */
+export type ThemeColorSources = Readonly<Record<string, string>>;
+/** 一组主题色：名字 → THREE.Color（换色时原地修改） */
+export type ThemeColors<Sources extends ThemeColorSources> = {
+    readonly [Name in keyof Sources]: Color;
+};
+/**
+ * 在 scope 元素上读出 CSS 颜色，写进 target（sRGB 转成 three.js 的线性工作空间）。
+ * 解析不了时（读不到主题、格式不认识）保持原值，返回 false
+ */
+export declare function readThemeColor(scope: Element, value: string, target: Color): boolean;
+/** 一组跟随主题的颜色：refresh 读取并过渡，stop 取消还在跑的过渡 */
+export interface ThemeColorSet<Sources extends ThemeColorSources> {
+    /** 名字 → THREE.Color：材质直接引用这些对象，换主题时原地改值 */
+    readonly colors: ThemeColors<Sources>;
+    /** 在 scope 上重新读取；transition 为 false（第一次读）时直接换 */
+    refresh(scope: Element, sources: Sources, transition: boolean): void;
+    /** 取消还在跑的过渡 */
+    stop(): void;
+}
+/** 建一组主题色（useThemeColors 与场景上下文的 themeColors 共用） */
+export declare function createThemeColorSet<Sources extends ThemeColorSources>(onChange?: () => void): ThemeColorSet<Sources>;
+/** useThemeColors 的选项 */
+export interface ThemeColorOptions {
+    /** 颜色变了（第一次读到、过渡的每一帧）时调用：循环停着的场景在这里请求重画 */
+    onChange?: () => void;
+}
+/** 组件里的主题色（在 setup 里调用）：scope 元素挂载后读取，换主题或来源变了时过渡到新色，见文件开头 */
+export declare function useThemeColors<Sources extends ThemeColorSources>(scope: () => Element | null | undefined, sources: Sources | (() => Sources), { onChange }?: ThemeColorOptions): ThemeColors<Sources>;

package/dist/three/core/theme-colors.js

@@ -0,0 +1,113 @@
+import { clamp } from "../../utils/data/number.js";
+import { useConfig } from "../../config/context.js";
+import { themeTransitionOrInstant } from "../../utils/motion/animation.js";
+import { onScopeDispose, watch } from "vue";
+import { animate } from "animejs";
+import { converter, modeLab, modeLch, modeLrgb, modeOklab, modeOklch, modeP3, modeRgb, parse, useMode } from "culori/fn";
+import { Color, SRGBColorSpace } from "three";
+//#region src/three/core/theme-colors.ts
+/**
+* 主题色 → THREE.Color：3D 场景拿不到 CSS 变量，这里在元素上读出颜色的当前取值，转成 three.js 的颜色。
+*
+*   // 场景里（ThreeCanvas 的 setup）：跟随画布所在位置的主题，换色时自动重画
+*   setup: ({ scene, themeColors }) => {
+*     const palette = themeColors({ accent: colors.accent, glow: colors.chart3 });
+*     material.color = palette.accent;          // 直接赋同一个对象；构造参数里传会被复制一份
+*     uniforms.uGlow = { value: palette.glow };
+*   }
+*
+*   // 组件里（颜色来源随 props 变化时）
+*   const palette = useThemeColors(() => host, () => ({ main: color }), { onChange: invalidate });
+*
+* 切换主题、主题编辑器改品牌色时重新读取，按主题的 lg 时长与 standard 缓动从旧色过渡到新色（减少动态效果时直接换）；
+* Color 对象始终是同一批，材质与 uniform 不用重建。
+*
+* 颜色可以是 token（`colors.accent`）或任意 CSS 颜色（`'#e5484d'`、`'color-mix(…)'`）：
+* 交给一个隐藏的探针元素，由浏览器解析出最终的颜色，light-dark()、color-mix()、主题覆盖都能用。透明度不保留。
+*/
+useMode(modeRgb);
+useMode(modeLrgb);
+useMode(modeP3);
+useMode(modeLab);
+useMode(modeLch);
+useMode(modeOklab);
+useMode(modeOklch);
+var toRgb = converter("rgb");
+/**
+* 在 scope 元素上读出 CSS 颜色，写进 target（sRGB 转成 three.js 的线性工作空间）。
+* 解析不了时（读不到主题、格式不认识）保持原值，返回 false
+*/
+function readThemeColor(scope, value, target) {
+	const probe = document.createElement("span");
+	probe.style.display = "none";
+	probe.style.color = value;
+	scope.append(probe);
+	const computed = getComputedStyle(probe).color;
+	probe.remove();
+	const parsed = computed ? parse(computed) : void 0;
+	const rgb = parsed && toRgb(parsed);
+	if (!rgb) return false;
+	const unit = (channel) => clamp(channel || 0, 0, 1);
+	target.setRGB(unit(rgb.r), unit(rgb.g), unit(rgb.b), SRGBColorSpace);
+	return true;
+}
+/** 建一组主题色（useThemeColors 与场景上下文的 themeColors 共用） */
+function createThemeColorSet(onChange) {
+	const colors = {};
+	let running;
+	return {
+		colors,
+		refresh(scope, sources, transition) {
+			running?.cancel();
+			const from = {};
+			const to = {};
+			for (const [name, value] of Object.entries(sources)) {
+				const color = colors[name] ??= new Color();
+				from[name] = color.clone();
+				to[name] = color.clone();
+				readThemeColor(scope, value, to[name]);
+			}
+			const apply = (progress) => {
+				for (const name of Object.keys(to)) colors[name].lerpColors(from[name], to[name], progress);
+				onChange?.();
+			};
+			const timing = transition ? themeTransitionOrInstant(scope, { duration: "lg" }) : {};
+			if (!timing.duration) return apply(1);
+			const state = { progress: 0 };
+			running = animate(state, {
+				progress: 1,
+				...timing,
+				onUpdate: () => apply(state.progress)
+			});
+		},
+		stop() {
+			running?.cancel();
+		}
+	};
+}
+/** 组件里的主题色（在 setup 里调用）：scope 元素挂载后读取，换主题或来源变了时过渡到新色，见文件开头 */
+function useThemeColors(scope, sources, { onChange } = {}) {
+	const config = useConfig();
+	const set = createThemeColorSet(onChange);
+	const read = () => typeof sources === "function" ? sources() : sources;
+	for (const name of Object.keys(read())) set.colors[name] = new Color();
+	let loaded = false;
+	watch([
+		() => config.theme,
+		scope,
+		() => JSON.stringify(read())
+	], ([, element]) => {
+		if (!element) return;
+		set.refresh(element, read(), loaded);
+		loaded = true;
+	}, {
+		immediate: true,
+		flush: "post"
+	});
+	onScopeDispose(() => set.stop());
+	return set.colors;
+}
+//#endregion
+export { createThemeColorSet, readThemeColor, useThemeColors };
+
+//# sourceMappingURL=theme-colors.js.map

package/dist/three/core/theme-colors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-colors.js","names":[],"sources":["../../../src/three/core/theme-colors.ts"],"sourcesContent":["/**\n * 主题色 → THREE.Color：3D 场景拿不到 CSS 变量，这里在元素上读出颜色的当前取值，转成 three.js 的颜色。\n *\n *   // 场景里（ThreeCanvas 的 setup）：跟随画布所在位置的主题，换色时自动重画\n *   setup: ({ scene, themeColors }) => {\n *     const palette = themeColors({ accent: colors.accent, glow: colors.chart3 });\n *     material.color = palette.accent;          // 直接赋同一个对象；构造参数里传会被复制一份\n *     uniforms.uGlow = { value: palette.glow };\n *   }\n *\n *   // 组件里（颜色来源随 props 变化时）\n *   const palette = useThemeColors(() => host, () => ({ main: color }), { onChange: invalidate });\n *\n * 切换主题、主题编辑器改品牌色时重新读取，按主题的 lg 时长与 standard 缓动从旧色过渡到新色（减少动态效果时直接换）；\n * Color 对象始终是同一批，材质与 uniform 不用重建。\n *\n * 颜色可以是 token（`colors.accent`）或任意 CSS 颜色（`'#e5484d'`、`'color-mix(…)'`）：\n * 交给一个隐藏的探针元素，由浏览器解析出最终的颜色，light-dark()、color-mix()、主题覆盖都能用。透明度不保留。\n */\nimport { animate, type JSAnimation } from 'animejs';\nimport {\n  converter,\n  modeLab,\n  modeLch,\n  modeLrgb,\n  modeOklab,\n  modeOklch,\n  modeP3,\n  modeRgb,\n  parse,\n  useMode,\n} from 'culori/fn';\nimport { Color, SRGBColorSpace } from 'three';\nimport { onScopeDispose, watch } from 'vue';\nimport { useConfig } from '../../config/context';\nimport { clamp } from '../../utils/data/number';\nimport { themeTransitionOrInstant } from '../../utils/motion/animation';\n\n// 浏览器给出的计算值可能是 rgb()、color(srgb …)、color(display-p3 …)、oklch()、lab() 等\nuseMode(modeRgb);\nuseMode(modeLrgb);\nuseMode(modeP3);\nuseMode(modeLab);\nuseMode(modeLch);\nuseMode(modeOklab);\nuseMode(modeOklch);\nconst toRgb = converter('rgb');\n\n/** 一组要读的颜色：名字 → token 或 CSS 颜色 */\nexport type ThemeColorSources = Readonly<Record<string, string>>;\n\n/** 一组主题色：名字 → THREE.Color（换色时原地修改） */\nexport type ThemeColors<Sources extends ThemeColorSources> = {\n  readonly [Name in keyof Sources]: Color;\n};\n\n/**\n * 在 scope 元素上读出 CSS 颜色，写进 target（sRGB 转成 three.js 的线性工作空间）。\n * 解析不了时（读不到主题、格式不认识）保持原值，返回 false\n */\nexport function readThemeColor(scope: Element, value: string, target: Color): boolean {\n  const probe = document.createElement('span');\n  probe.style.display = 'none';\n  probe.style.color = value;\n  scope.append(probe);\n  const computed = getComputedStyle(probe).color;\n  probe.remove();\n  const parsed = computed ? parse(computed) : undefined;\n  const rgb = parsed && toRgb(parsed);\n  if (!rgb) return false;\n  const unit = (channel: number) => clamp(channel || 0, 0, 1);\n  target.setRGB(unit(rgb.r), unit(rgb.g), unit(rgb.b), SRGBColorSpace);\n  return true;\n}\n\n/** 一组跟随主题的颜色：refresh 读取并过渡，stop 取消还在跑的过渡 */\nexport interface ThemeColorSet<Sources extends ThemeColorSources> {\n  /** 名字 → THREE.Color：材质直接引用这些对象，换主题时原地改值 */\n  readonly colors: ThemeColors<Sources>;\n  /** 在 scope 上重新读取；transition 为 false（第一次读）时直接换 */\n  refresh(scope: Element, sources: Sources, transition: boolean): void;\n  /** 取消还在跑的过渡 */\n  stop(): void;\n}\n\n/** 建一组主题色（useThemeColors 与场景上下文的 themeColors 共用） */\nexport function createThemeColorSet<Sources extends ThemeColorSources>(\n  onChange?: () => void,\n): ThemeColorSet<Sources> {\n  const colors: Record<string, Color> = {};\n  let running: JSAnimation | undefined;\n  return {\n    colors: colors as ThemeColors<Sources>,\n    refresh(scope, sources, transition) {\n      void running?.cancel();\n      const from: Record<string, Color> = {};\n      const to: Record<string, Color> = {};\n      for (const [name, value] of Object.entries(sources)) {\n        const color = (colors[name] ??= new Color());\n        from[name] = color.clone();\n        to[name] = color.clone();\n        readThemeColor(scope, value, to[name]!);\n      }\n      const apply = (progress: number) => {\n        for (const name of Object.keys(to))\n          colors[name]!.lerpColors(from[name]!, to[name]!, progress);\n        onChange?.();\n      };\n      const timing = transition ? themeTransitionOrInstant(scope, { duration: 'lg' }) : {};\n      if (!timing.duration) return apply(1);\n      const state = { progress: 0 };\n      running = animate(state, { progress: 1, ...timing, onUpdate: () => apply(state.progress) });\n    },\n    stop() {\n      void running?.cancel();\n    },\n  };\n}\n\n/** useThemeColors 的选项 */\nexport interface ThemeColorOptions {\n  /** 颜色变了（第一次读到、过渡的每一帧）时调用：循环停着的场景在这里请求重画 */\n  onChange?: () => void;\n}\n\n/** 组件里的主题色（在 setup 里调用）：scope 元素挂载后读取，换主题或来源变了时过渡到新色，见文件开头 */\nexport function useThemeColors<Sources extends ThemeColorSources>(\n  scope: () => Element | null | undefined,\n  sources: Sources | (() => Sources),\n  { onChange }: ThemeColorOptions = {},\n): ThemeColors<Sources> {\n  const config = useConfig();\n  const set = createThemeColorSet<Sources>(onChange);\n  const read = () => (typeof sources === 'function' ? sources() : sources);\n  // 挂载前就能拿到全部名字：材质可以在第一次读取前引用这些对象\n  for (const name of Object.keys(read())) (set.colors as Record<string, Color>)[name] = new Color();\n  let loaded = false;\n  watch(\n    [() => config.theme, scope, () => JSON.stringify(read())],\n    ([, element]) => {\n      if (!element) return;\n      set.refresh(element, read(), loaded);\n      loaded = true;\n    },\n    { immediate: true, flush: 'post' },\n  );\n  onScopeDispose(() => set.stop());\n  return set.colors;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,QAAQ,OAAO;AACf,QAAQ,QAAQ;AAChB,QAAQ,MAAM;AACd,QAAQ,OAAO;AACf,QAAQ,OAAO;AACf,QAAQ,SAAS;AACjB,QAAQ,SAAS;AACjB,IAAM,QAAQ,UAAU,KAAK;;;;;AAc7B,SAAgB,eAAe,OAAgB,OAAe,QAAwB;CACpF,MAAM,QAAQ,SAAS,cAAc,MAAM;CAC3C,MAAM,MAAM,UAAU;CACtB,MAAM,MAAM,QAAQ;CACpB,MAAM,OAAO,KAAK;CAClB,MAAM,WAAW,iBAAiB,KAAK,CAAC,CAAC;CACzC,MAAM,OAAO;CACb,MAAM,SAAS,WAAW,MAAM,QAAQ,IAAI,KAAA;CAC5C,MAAM,MAAM,UAAU,MAAM,MAAM;CAClC,IAAI,CAAC,KAAK,OAAO;CACjB,MAAM,QAAQ,YAAoB,MAAM,WAAW,GAAG,GAAG,CAAC;CAC1D,OAAO,OAAO,KAAK,IAAI,CAAC,GAAG,KAAK,IAAI,CAAC,GAAG,KAAK,IAAI,CAAC,GAAG,cAAc;CACnE,OAAO;AACT;;AAaA,SAAgB,oBACd,UACwB;CACxB,MAAM,SAAgC,CAAC;CACvC,IAAI;CACJ,OAAO;EACG;EACR,QAAQ,OAAO,SAAS,YAAY;GAClC,SAAc,OAAO;GACrB,MAAM,OAA8B,CAAC;GACrC,MAAM,KAA4B,CAAC;GACnC,KAAK,MAAM,CAAC,MAAM,UAAU,OAAO,QAAQ,OAAO,GAAG;IACnD,MAAM,QAAS,OAAO,UAAU,IAAI,MAAM;IAC1C,KAAK,QAAQ,MAAM,MAAM;IACzB,GAAG,QAAQ,MAAM,MAAM;IACvB,eAAe,OAAO,OAAO,GAAG,KAAM;GACxC;GACA,MAAM,SAAS,aAAqB;IAClC,KAAK,MAAM,QAAQ,OAAO,KAAK,EAAE,GAC/B,OAAO,KAAK,CAAE,WAAW,KAAK,OAAQ,GAAG,OAAQ,QAAQ;IAC3D,WAAW;GACb;GACA,MAAM,SAAS,aAAa,yBAAyB,OAAO,EAAE,UAAU,KAAK,CAAC,IAAI,CAAC;GACnF,IAAI,CAAC,OAAO,UAAU,OAAO,MAAM,CAAC;GACpC,MAAM,QAAQ,EAAE,UAAU,EAAE;GAC5B,UAAU,QAAQ,OAAO;IAAE,UAAU;IAAG,GAAG;IAAQ,gBAAgB,MAAM,MAAM,QAAQ;GAAE,CAAC;EAC5F;EACA,OAAO;GACL,SAAc,OAAO;EACvB;CACF;AACF;;AASA,SAAgB,eACd,OACA,SACA,EAAE,aAAgC,CAAC,GACb;CACtB,MAAM,SAAS,UAAU;CACzB,MAAM,MAAM,oBAA6B,QAAQ;CACjD,MAAM,aAAc,OAAO,YAAY,aAAa,QAAQ,IAAI;CAEhE,KAAK,MAAM,QAAQ,OAAO,KAAK,KAAK,CAAC,GAAG,IAAK,OAAiC,QAAQ,IAAI,MAAM;CAChG,IAAI,SAAS;CACb,MACE;QAAO,OAAO;EAAO;QAAa,KAAK,UAAU,KAAK,CAAC;CAAC,IACvD,GAAG,aAAa;EACf,IAAI,CAAC,SAAS;EACd,IAAI,QAAQ,SAAS,KAAK,GAAG,MAAM;EACnC,SAAS;CACX,GACA;EAAE,WAAW;EAAM,OAAO;CAAO,CACnC;CACA,qBAAqB,IAAI,KAAK,CAAC;CAC/B,OAAO,IAAI;AACb"}