mountain/
├── README.md                    # 架构说明（本文件）
├── index.ts                     # 统一导出
│
├── canvas-mountain.tsx          # React 组件（主线程）
├── mountain.worker.ts           # Worker 调度器
│
├── mountain.ts                  # Mountain 数据模型类 ⭐️
├── mountain-renderer.ts         # MountainRenderer 渲染器类 ⭐️
│
├── config.ts                    # 配置常量
├── types.ts                     # 类型定义
└── renderer.ts                  # Canvas 渲染函数

class Mountain {
  // 构造函数
  constructor(config: MountainConfig)

  // 生成数据（异步）
  async generate(): Promise<void>

  // 获取数据（只读）
  getPoints(): readonly Point[]
  getLines(): readonly PrecomputedLine[][]
  getDrawArea(): { drawWidth, drawHeight, offsetX, offsetY }
  getRotationConstants(): RotationConstants | null
  getPreRenderState(): PreRenderState | null

  // 清理资源
  dispose(): void
}

class MountainRenderer {
  // 静态方法：判断是否需要重新生成
  static needsRegeneration(
    oldConfig: MountainRendererConfig,
    newConfig: MountainRendererConfig
  ): boolean

  // 构造函数
  constructor(
    ctx: OffscreenCanvasRenderingContext2D,
    canvasWidth: number,
    canvasHeight: number,
    config: MountainRendererConfig
  )

  // 初始化（创建 Mountain 并生成数据）
  async initialize(): Promise<void>

  // 开始动画
  startAnimation(): void

  // 停止动画
  stopAnimation(): void

  // 更新滚动进度
  updateScrollProgress(progress: number): void

  // 清理资源
  dispose(): void

  // 获取 Mountain 实例（调试用）
  getMountain(): Mountain | null
}

// 初始动画模式：逐点增量渲染
renderIncremental() {
  drawMountainIncremental(ctx, lines, renderedPointsCount, ...)
}

// 高性能模式：使用 ImageBitmap 缓存
renderWithBitmapCache() {
  const bitmap = preRenderState.bitmaps.get(nearestStep);
  if (bitmap) {
    ctx.drawImage(bitmap, 0, 0);  // O(1) 操作
  }
}

private animationLoop = (): void => {
  // 1. 增加已渲染点数
  this.animationState.renderedPointsCount += this.animationState.animationSpeed;

  // 2. 判断是否完成
  if (this.animationState.renderedPointsCount >= totalPoints) {
    this.animationState.renderedPointsCount = totalPoints;
    this.animationState.isAnimating = false;

    // 3. 渲染最后一帧
    this.renderFrame();
    this.logAnimationStats(currentTime, totalPoints);
    self.postMessage({ type: "animationComplete" });
    return;
  }

  // 4. 继续渲染
  this.renderFrame();
  this.animationState.animationRafId = requestAnimationFrame(this.animationLoop);
};

private renderFrame(): void {
  const isFullyRendered = renderedPointsCount >= totalPoints;
  
  // 模式 1: 高性能缓存模式（最快）
  if (isFullyRendered && preRenderState?.bitmaps.size > 0) {
    this.renderWithBitmapCache();
  }
  // 模式 2: 增量渲染模式（初始动画）
  else {
    this.renderIncremental();
  }
}

private renderWithBitmapCache(): void {
  const stepSize = 1 / ROTATION_CONFIG.CACHE_STEPS;
  const nearestStep = Math.round(currentScrollProgress / stepSize) * stepSize;
  const bitmap = preRenderState.bitmaps.get(nearestStep);
  
  if (bitmap) {
    // O(1) 操作：直接绘制 GPU 纹理
    this.ctx.drawImage(bitmap, 0, 0);
  } else {
    // 降级到实时渲染，并优先预渲染这个角度
    this.renderFull();
    prioritizeAngle(nearestStep, preRenderState);
  }
  
  // 继续预渲染剩余角度
  if (!preRenderState.isPreRendering && preRenderState.queue.length > 0) {
    scheduleNextPreRender(preRenderState, this.createDrawMountainCallback());
  }
}

// canvas-mountain.tsx
const dpr = window.devicePixelRatio || 1;

// 设置实际像素尺寸（高分辨率）
canvas.width = width * dpr;
canvas.height = height * dpr;

// 设置 CSS 显示尺寸（保持界面大小）
canvas.style.width = `${width}px`;
canvas.style.height = `${height}px`;

// 传递给 Worker
worker.postMessage({ type: "init", canvas: offscreen, dpr });

// mountain.worker.ts
const canvas = data.canvas;
const ctx = canvas.getContext("2d");
const dpr = data.dpr;

// 应用 DPR 缩放变换
ctx.scale(dpr, dpr);

// 之后所有绘图都使用逻辑坐标
ctx.strokeStyle = "white";
ctx.moveTo(100, 100);  // 逻辑坐标，自动映射到 200, 200（DPR=2）

// mountain.ts - initializePreRenderState
const dpr = this.config.dpr ?? 1;

// 创建高分辨率临时 canvas
const tempCanvas = new OffscreenCanvas(width * dpr, height * dpr);
const tempCtx = tempCanvas.getContext("2d");

// 应用 DPR 缩放
tempCtx.scale(dpr, dpr);

// 渲染时使用逻辑坐标
drawMountainFull(tempCtx, lines, progress, ...);

// 转换为高分辨率 ImageBitmap
const bitmap = await createImageBitmap(tempCanvas);

// mountain-renderer.ts - renderWithBitmapCache
const bitmap = preRenderState.bitmaps.get(nearestStep);
if (bitmap) {
  // ⚠️ 必须指定目标尺寸为逻辑尺寸
  // bitmap 是高分辨率的，需要缩放到逻辑坐标空间
  this.ctx.drawImage(bitmap, 0, 0, this.canvasWidth, this.canvasHeight);
}

// canvas-mountain.tsx - 参数更新时
useEffect(() => {
  const dpr = window.devicePixelRatio || 1;
  
  // 发送新的 DPR 给 Worker
  worker.postMessage({
    type: "updateParams",
    width,
    height,
    dpr,  // 可能变化的 DPR
    ...
  });
}, [width, height, ...]);

// mountain.worker.ts - 处理 DPR 变化
if (newDpr !== dpr) {
  dpr = newDpr;
  
  // 调整 canvas 尺寸
  canvas.width = width * dpr;
  canvas.height = height * dpr;
  
  // 重新应用缩放（调整尺寸会重置 transform）
  ctx.scale(dpr, dpr);
}

// ❌ 错误 1：不设置 CSS 尺寸
canvas.width = width * dpr;
canvas.height = height * dpr;
// 结果：界面显示变大

// ✅ 正确
canvas.style.width = `${width}px`;
canvas.style.height = `${height}px`;

// ❌ 错误 2：不应用 scale 变换
canvas.width = width * dpr;
ctx.moveTo(100, 100);  // 实际会画在 (100, 100) 物理像素，看起来很小
// 结果：绘制内容缩小

// ✅ 正确
ctx.scale(dpr, dpr);
ctx.moveTo(100, 100);  // 自动映射到 (200, 200) 物理像素（DPR=2）

// ❌ 错误 3：drawImage 不指定尺寸
const bitmap = createImageBitmap(tempCanvas);  // 高分辨率
ctx.drawImage(bitmap, 0, 0);  // 按实际像素尺寸绘制
// 结果：图像放大

// ✅ 正确
ctx.drawImage(bitmap, 0, 0, width, height);  // 指定逻辑尺寸

// ❌ 错误 4：transferControlToOffscreen 后修改尺寸
canvas.transferControlToOffscreen();
canvas.width = newWidth;  // 抛出错误
// 结果：Cannot resize canvas after call to transferControlToOffscreen

// ✅ 正确：在 Worker 内部修改
const canvas = data.canvas;  // OffscreenCanvas
canvas.width = newWidth * dpr;
ctx.scale(dpr, dpr);

// 每帧只绘制新增部分
for (let i = startPoint; i < pointsToRender; i++) {
  // 绘制第 i 个点的所有线段
}
// 而不是每次都从 0 开始绘制

dispose(): void {
  // 1. 停止动画
  this.stopAnimation();
  
  // 2. 清理 ImageBitmap（GPU 资源）
  if (this.mountain) {
    this.mountain.dispose();  // 内部调用 bitmap.close()
    this.mountain = null;
  }
  
  // 3. 清理状态
  this.animationState = null;
}

import { CanvasMountain } from "./mountain";

<CanvasMountain
  seed="mountain-1"
  xOffset={0}
  yOffset={0}
  speed={1}
  scrollProgress={scrollProgressMotionValue}
  debug={false}
/>

import { Mountain, MountainRenderer } from "./mountain";

// 1. 单独使用 Mountain 数据模型
const mountain = new Mountain({
  seed: "custom-mountain",
  width: 1920,
  height: 1080,
  xOffset: 0,
  yOffset: 0,
  debug: true,
});

await mountain.generate();
const points = mountain.getPoints();
const lines = mountain.getLines();

// 使用数据做自定义处理...

// 2. 使用 MountainRenderer
const renderer = new MountainRenderer(ctx, width, height, {
  seed: "custom-mountain",
  width: 1920,
  height: 1080,
  xOffset: 0,
  yOffset: 0,
  speed: 2,
  debug: true,
});

await renderer.initialize();
renderer.startAnimation();

// 更新滚动
renderer.updateScrollProgress(0.5);

// 获取 Mountain 实例
const mountain2 = renderer.getMountain();

// 清理
renderer.dispose();

<CanvasMountain debug={true} ... />