@taboo-avalanche/andesite-compiler 1.0.0

package/src/rasterize/puppeteer.ts

@@ -0,0 +1,2257 @@
+import puppeteer, { type Browser, type Page, type ElementHandle } from 'puppeteer'
+import * as fs from 'fs'
+import * as path from 'path'
+import {
+  DEFAULT_PROGRESS_STEPS,
+  HUD_ANCHORS,
+  type ButtonStateDecl,
+  type ButtonLabelDecl,
+  type LabelDecl,
+  type TextInputCompletionDecl,
+  type TextInputDecl,
+  type SlotDecl,
+  type ProgressDecl,
+  type SpriteDecl,
+  type ScrollViewDecl,
+  type HudAnchor,
+  type HudMountDecl,
+  type ViewStackDecl,
+} from '@taboo-avalanche/andesite'
+
+// 普通面板/按钮导出 4x 源图，再通过 .gf 逻辑尺寸按原始尺寸显示，避免高 GUI scale 放大后发糊。
+// 倍率越高越清晰但 mcpack/显存按平方增长；链路倍率无关（origin 取 PNG 像素，logical 取 CSS 尺寸）。
+// 进度条不走截图，仍在 renderProgressPng 中按 CSS 像素直接绘制。
+const RASTER_SCALE = 4
+
+interface PanelRaster {
+  id: string
+  mountId?: string
+  texturePath: string
+  /** 面板边框盒（本体）在页面内的坐标与尺寸；导入器据此把控件定位到与 dev 一致的位置。 */
+  x: number
+  y: number
+  width: number
+  height: number
+  /** 贴图相对边框盒的四向外扩量（box-shadow 投影）；仅外扩>0 时存在，导入器据此外扩渲染。 */
+  overflow?: VisualOverflow
+  defaultVisible?: boolean
+  png: Uint8Array
+}
+
+interface ButtonRaster {
+  id: string
+  mountId?: string
+  defaultTexturePath: string
+  pressedTexturePath: string
+  x: number
+  y: number
+  width: number
+  height: number
+  pressDuration: number
+  clickable: boolean
+  layer?: number
+  defaultVisible?: boolean
+  states: ButtonStateDecl[]
+  labels: ButtonLabelDecl[]
+  defaultPng: Uint8Array
+  pressedPng: Uint8Array
+}
+
+interface DomBox {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+interface RepeaterCellBox extends DomBox {
+  index: number
+}
+
+export interface AndesiteRasterResult {
+  kind: 'menu' | 'hud'
+  // 页面整体包围盒（内容根 px），供运行时居中摆放
+  width: number
+  height: number
+  mounts: HudMountDecl[]
+  viewStacks: ViewStackDecl[]
+  panels: PanelRaster[]
+  buttons: ButtonRaster[]
+  labels: LabelDecl[]
+  inputs: TextInputDecl[]
+  slots: SlotDecl[]
+  progresses: ProgressDecl[]
+  sprites: SpriteDecl[]
+  scrollViews: ScrollViewDecl[]
+}
+
+const PUPPETEER_LAUNCH_ARGS = [
+  `--force-device-scale-factor=${RASTER_SCALE}`,
+  '--no-sandbox',
+  '--disable-setuid-sandbox',
+  '--disable-dev-shm-usage',
+]
+
+export interface RasterizeOptions {
+  /** 为 true 时输出浏览器控制台与请求失败日志 */
+  verbose?: boolean
+}
+
+/**
+ * 启动可复用的 Puppeteer 实例，供 build-all 多页栅格化共用，避免每页重复 launch。
+ */
+export async function launchRasterBrowser(): Promise<Browser> {
+  return puppeteer.launch({ headless: true, args: PUPPETEER_LAUNCH_ARGS })
+}
+
+/**
+ * 在已有 Browser 上栅格化单个页面（独立 Tab，用毕关闭 Page）。
+ */
+export async function rasterizeAllInBrowser(
+  browser: Browser,
+  pageUrl: string,
+  outputDir: string,
+  options?: RasterizeOptions,
+): Promise<AndesiteRasterResult> {
+  const page = await browser.newPage()
+  const verbose = options?.verbose === true
+  try {
+    if (verbose) {
+      page.on('console', msg => console.log('[browser console]', msg.type(), msg.text()))
+      page.on('pageerror', err => console.log('[browser error]', err.message))
+      page.on('requestfailed', req => console.log('[request failed]', req.url(), req.failure()?.errorText))
+    }
+    await page.setViewport({ width: 176, height: 222, deviceScaleFactor: RASTER_SCALE })
+    await page.goto(pageUrl, { waitUntil: 'domcontentloaded' })
+    await page.evaluate('globalThis.__name = (fn) => fn')
+    await page.waitForFunction(
+      () => document.querySelector('[data-andesite-canvas]') !== null,
+      { timeout: 15000 },
+    )
+    const canvasSize = await page.$eval('[data-andesite-canvas]', node => {
+      const rect = (node as HTMLElement).getBoundingClientRect()
+      return {
+        width: rect.width,
+        height: rect.height,
+      }
+    })
+    await page.setViewport({
+      width: Math.max(176, Math.ceil(canvasSize.width)),
+      height: Math.max(222, Math.ceil(canvasSize.height)),
+      deviceScaleFactor: RASTER_SCALE,
+    })
+    const kind: AndesiteRasterResult['kind'] = await page.$eval('[data-andesite-canvas]', node => {
+      return (node as HTMLElement).getAttribute('data-andesite-page-kind') === 'hud' ? 'hud' : 'menu'
+    })
+    // 页面整体包围盒：菜单以内容根居中；HUD 控件另按最近 mount 作为局部坐标基准。
+    const pageBox = await page.$eval('[data-andesite-content-root]', node => {
+      const rect = (node as HTMLElement).getBoundingClientRect()
+      return { width: Math.round(rect.width), height: Math.round(rect.height) }
+    })
+    // 布局体检前置到栅格化之前，一次浏览器往返查两类会让控件"看着好、导出丢/错位"的隐性错误：
+    // 1) 塌陷：控件边框盒宽或高 ≤1px，几乎总是 absolute 脱离文档流反向撑父容器、或父容器高度为 0
+    //    所致。编译器对 0 尺寸控件本应按 isCollectable 跳过，但静默丢弃会让 sprites 数组凭空变空、
+    //    作者难以定位，故在此显式报错。
+    // 2) 出屏：菜单页把控件移出内容包围盒（误用 inset:0 全屏遮罩 / transform 居中 frame），AndesiteCanvas
+    //    按内容包围盒导出、引擎 anchor=center 自动居中，任何自行定位都会把内容移出导出区；不在此拦截，
+    //    这类页面会在截图阶段以难懂的 clip 宽高错误崩溃。检测用元素边框盒（getBoundingClientRect，不含
+    //    box-shadow 外溢），故合法投影不误判。出屏判定仅菜单页（HUD 控件按各自 mount 局部坐标，其锚点
+    //    本就允许相对屏幕边角偏移）；塌陷判定两类页面都做。
+    const layout = await page.evaluate(() => {
+      const root = document.querySelector<HTMLElement>('[data-andesite-content-root]')
+      const collapsed: string[] = []
+      const outOfBounds: string[] = []
+      const rootRect = root ? root.getBoundingClientRect() : null
+      // 允许 1px 舍入误差；只拦真正越界，不把细线/1px 装饰误判为塌陷
+      const tol = 1
+      for (const el of Array.from(document.querySelectorAll<HTMLElement>('[data-andesite-id]'))) {
+        // 视图栈稍后逐视图量尺寸并体检，不能拿默认隐藏视图的零矩形判塌陷。
+        if (el.closest('[data-andesite-viewstack]')) continue
+        // 声明 defaultVisible=false 的控件以 display:none 默认隐藏（翻页/页签的隐藏组），getBoundingClientRect 全为 0，
+        // 这是预期而非布局塌陷——跳过塌陷与出屏检测，照常栅格化（截图时临时恢复可见）。
+        if (el.getAttribute('data-andesite-default-visible') === 'false') {
+          continue
+        }
+        const r = el.getBoundingClientRect()
+        const id = el.getAttribute('data-andesite-id') ?? '?'
+        if (r.width <= tol || r.height <= tol) {
+          collapsed.push(`${id} (宽=${Math.round(r.width)}, 高=${Math.round(r.height)})`)
+          continue
+        }
+        if (rootRect) {
+          const x = r.left - rootRect.left
+          const y = r.top - rootRect.top
+          if (x < -tol || y < -tol || x + r.width > rootRect.width + tol || y + r.height > rootRect.height + tol) {
+            outOfBounds.push(`${id} (x=${Math.round(x)}, y=${Math.round(y)}, ${Math.round(r.width)}×${Math.round(r.height)}, 页面 ${Math.round(rootRect.width)}×${Math.round(rootRect.height)})`)
+          }
+        }
+      }
+      return { collapsed, outOfBounds }
+    })
+    // 布局体检仅输出警告，不中断编译。只要浏览器能渲染，就原样烘焙；
+    // 塌陷或出屏由作者自行在预览中确认，编译器不替作者做审美判断。
+    if (layout.collapsed.length && verbose) {
+      console.warn(`[andesite-compiler] 布局塌陷警告: ${layout.collapsed.slice(0, 8).join('；')}${layout.collapsed.length > 8 ? ` 等 ${layout.collapsed.length} 个` : ''}`)
+    }
+    if (kind !== 'hud' && layout.outOfBounds.length && verbose) {
+      console.warn(`[andesite-compiler] 控件出屏警告: ${layout.outOfBounds.slice(0, 8).join('；')}${layout.outOfBounds.length > 8 ? ` 等 ${layout.outOfBounds.length} 个` : ''}`)
+    }
+    const mounts = kind === 'hud' ? await collectHudMounts(page) : []
+    const viewStacks: ViewStackDecl[] = []
+    for (const stack of await page.$$('[data-andesite-viewstack]')) {
+      const info = await stack.evaluate(node => ({ id: node.getAttribute('data-andesite-id')!, defaultView: node.getAttribute('data-andesite-default-view')! }))
+      const views: ViewStackDecl['views'] = []
+      for (const el of await stack.$$(':scope > [data-andesite-view]')) {
+        const box = await measureAndesiteBox(el)
+        const info = await el.evaluate(node => ({
+          id: node.getAttribute('data-andesite-id')!,
+          name: node.getAttribute('data-andesite-view-name')!,
+          parentView: node.parentElement?.closest('[data-andesite-view]')?.getAttribute('data-andesite-id') ?? undefined,
+          controls: Array.from(node.querySelectorAll('[data-andesite-id]'))
+            .filter(child => child.closest('[data-andesite-view]') === node && !child.hasAttribute('data-andesite-viewstack'))
+            .map(child => child.getAttribute('data-andesite-id')!),
+        }))
+        if (box.width <= 0 || box.height <= 0) throw new Error(`Collapsed AView: ${info.id}`)
+        const layer = optionalNumber(await stack.evaluate(node => node.getAttribute('data-andesite-layer')))
+        views.push({ ...info, ...box, layer, mountId: await collectHudMountId(el), controls: [info.id + '/__background', ...info.controls] })
+      }
+      viewStacks.push({ ...info, views })
+    }
+    const labels = await collectLabels(page)
+    const inputs = await rasterizeTextInputs(page, outputDir)
+    const backgroundPanels = kind === 'hud'
+      ? await rasterizeHudStaticBackgrounds(page, outputDir)
+      : await rasterizeStaticBackground(page, outputDir)
+    const panels = await rasterizePanels(page, outputDir)
+    const buttons = await rasterizeButtons(page, outputDir)
+    const progresses = await rasterizeProgresses(page, outputDir)
+    const sprites = await rasterizeSprites(page, outputDir)
+    const scrollViews = await rasterizeScrollViews(page, outputDir)
+    // HUD 是 Bedrock-only，不能把 ASlot 导出成 Java chest slot。
+    const slots = kind === 'hud' ? [] : await collectSlots(page)
+    // 所有视图都必须参与体检，非默认视图不得静默丢控件或以零尺寸导出。
+    const exported = [...panels, ...buttons, ...labels, ...inputs, ...progresses, ...sprites, ...scrollViews, ...slots]
+    const exportedIds = new Set(exported.map(control => control.id))
+    for (const stack of viewStacks) for (const view of stack.views) {
+      view.controls = view.controls.filter(id => exportedIds.has(id))
+      for (const control of exported.filter(control => view.controls.includes(control.id))) {
+        if (control.width <= 0 || control.height <= 0) throw new Error(`Collapsed AView control: ${control.id}`)
+        if (kind !== 'hud' && (control.x < -1 || control.y < -1 || control.x + control.width > pageBox.width + 1 || control.y + control.height > pageBox.height + 1)) {
+          throw new Error(`AView control outside page: ${control.id}`)
+        }
+      }
+    }
+    return { kind, width: pageBox.width, height: pageBox.height, mounts, viewStacks, panels: [...backgroundPanels, ...panels], buttons, labels, inputs, slots, progresses, sprites, scrollViews }
+  } finally {
+    await page.close()
+  }
+}
+
+/**
+ * 单页便捷入口：内部 launch + 栅格化 + close。
+ */
+export async function rasterizeAll(pageUrl: string, outputDir: string, options?: RasterizeOptions): Promise<AndesiteRasterResult> {
+  const browser = await launchRasterBrowser()
+  try {
+    return await rasterizeAllInBrowser(browser, pageUrl, outputDir, options)
+  } finally {
+    await browser.close()
+  }
+}
+
+async function collectHudMounts(page: Page): Promise<HudMountDecl[]> {
+  const elements = await page.$$('[data-andesite-hud-mount]')
+  const results: HudMountDecl[] = []
+  for (const el of elements) {
+    const mount = await el.evaluate(node => {
+      const target = node as HTMLElement
+      return {
+        id: target.getAttribute('data-andesite-id') ?? '',
+        x: target.getAttribute('data-andesite-x') ?? '0',
+        y: target.getAttribute('data-andesite-y') ?? '0',
+        anchor: target.getAttribute('data-andesite-anchor') ?? 'top-left',
+        offsetX: target.getAttribute('data-andesite-offset-x'),
+        offsetY: target.getAttribute('data-andesite-offset-y'),
+        scale: target.getAttribute('data-andesite-scale'),
+        layer: target.getAttribute('data-andesite-layer'),
+        visibleByDefault: target.getAttribute('data-andesite-visible-by-default'),
+      }
+    })
+    const offsetX = optionalNumber(mount.offsetX)
+    const offsetY = optionalNumber(mount.offsetY)
+    const scale = optionalNumber(mount.scale)
+    const layer = optionalNumber(mount.layer)
+    const visibleByDefault = mount.visibleByDefault == null || mount.visibleByDefault === ''
+      ? undefined
+      : mount.visibleByDefault === 'true' || mount.visibleByDefault === '1'
+    results.push({
+      id: mount.id,
+      x: clampPercent(Number(mount.x)),
+      y: clampPercent(Number(mount.y)),
+      anchor: normalizeHudAnchor(mount.anchor),
+      ...(offsetX == null ? {} : { offsetX }),
+      ...(offsetY == null ? {} : { offsetY }),
+      ...(scale == null ? {} : { scale }),
+      ...(layer == null ? {} : { layer }),
+      ...(visibleByDefault == null ? {} : { visibleByDefault }),
+    })
+  }
+  return results
+}
+
+function normalizeHudAnchor(value: string): HudAnchor {
+  return (HUD_ANCHORS as readonly string[]).includes(value) ? (value as HudAnchor) : 'top-left'
+}
+
+function optionalNumber(value: string | null): number | undefined {
+  if (value == null || value === '') {
+    return undefined
+  }
+  const number = Number(value)
+  return Number.isFinite(number) ? number : undefined
+}
+
+async function collectButtonClickable(target: Awaited<ReturnType<Page['$']>>): Promise<boolean> {
+  if (!target) {
+    return true
+  }
+  return await target.evaluate((node: Element) => node.getAttribute('data-andesite-clickable') !== 'false')
+}
+
+function clampPercent(value: number): number {
+  if (!Number.isFinite(value)) {
+    return 0
+  }
+  return Math.max(0, Math.min(100, value))
+}
+
+async function rasterizeStaticBackground(page: Page, outputDir: string): Promise<PanelRaster[]> {
+  const root = await page.$('[data-andesite-content-root]')
+  if (!root) {
+    return []
+  }
+  const box = await measureAndesiteBox(root)
+  if (box.width <= 0 || box.height <= 0) {
+    return []
+  }
+  const texturePath = 'textures/__page_background.png'
+  const screenshot = await withHiddenAndesiteControls(page, async () => {
+    return await root.screenshot({ type: 'png', omitBackground: true })
+  })
+  const outputPath = path.join(outputDir, texturePath)
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true })
+  fs.writeFileSync(outputPath, screenshot)
+  return [{ id: '__page_background', texturePath, x: box.x, y: box.y, width: box.width, height: box.height, png: screenshot }]
+}
+
+async function rasterizeHudStaticBackgrounds(page: Page, outputDir: string): Promise<PanelRaster[]> {
+  const elements = await page.$$('[data-andesite-hud-mount]')
+  const results: PanelRaster[] = []
+  for (const el of elements) {
+    const mountId = await el.evaluate((node: Element) => node.getAttribute('data-andesite-id') ?? '')
+    if (mountId === '') {
+      continue
+    }
+
+    const rect = await el.evaluate((node: Element) => {
+      const bounds = (node as HTMLElement).getBoundingClientRect()
+      return {
+        width: Math.round(bounds.width),
+        height: Math.round(bounds.height),
+      }
+    })
+    if (rect.width <= 0 || rect.height <= 0) {
+      continue
+    }
+
+    const safeMountId = mountId.replace(/[:\/.-]/g, '_') || 'default'
+    const id = `__hud_mount_${safeMountId}_background`
+    const texturePath = `textures/${id}.png`
+    // 原位截图，不用克隆 overlay：克隆成 fixed 会破坏 mount 内 flex stretch 布局，
+    // 说明条这类撑满全宽的普通 div 在克隆里收缩成内容宽，导致背景图右半缺失。
+    // withIsolatedCapture 原位保留布局，仅隐藏独立 A* 控件、清理祖先背景。
+    const screenshot = await withIsolatedCapture(page, el, async () => {
+      return await el.screenshot({ type: 'png', omitBackground: true })
+    })
+    const outputPath = path.join(outputDir, texturePath)
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true })
+    fs.writeFileSync(outputPath, screenshot)
+    results.push({ id, mountId, texturePath, x: 0, y: 0, width: rect.width, height: rect.height, png: screenshot })
+  }
+  return results
+}
+
+
+async function isInsideScrollView(target: Awaited<ReturnType<Page['$']>>): Promise<boolean> {
+  if (!target) {
+    return false
+  }
+  return await target.evaluate((node: Element) => node.closest('[data-andesite-type="scroll-view"]') != null)
+}
+
+async function isInsideRepeater(target: Awaited<ReturnType<Page['$']>>): Promise<boolean> {
+  if (!target) {
+    return false
+  }
+  return await target.evaluate((node: Element) => node.closest('[data-andesite-type="repeater"]') != null)
+}
+
+async function measureBoxRelativeToScrollChild(
+  target: Awaited<ReturnType<Page['$']>>,
+  scrollEl: Awaited<ReturnType<Page['$']>>,
+): Promise<DomBox> {
+  return await measureBoxRelativeToAncestor(target, scrollEl)
+}
+
+async function measureBoxRelativeToAncestor(
+  target: Awaited<ReturnType<Page['$']>>,
+  ancestor: Awaited<ReturnType<Page['$']>>,
+): Promise<DomBox> {
+  if (!target || !ancestor) {
+    return { x: 0, y: 0, width: 0, height: 0 }
+  }
+  return await target.evaluate((node: Element, ancestorNode: Element) => {
+    const ancestorRect = (ancestorNode as HTMLElement).getBoundingClientRect()
+    const rect = (node as HTMLElement).getBoundingClientRect()
+    return {
+      x: Math.round(rect.left - ancestorRect.left),
+      y: Math.round(rect.top - ancestorRect.top),
+      width: Math.round(rect.width),
+      height: Math.round(rect.height),
+    }
+  }, ancestor)
+}
+
+async function rasterizeScrollViews(page: Page, outputDir: string): Promise<ScrollViewDecl[]> {
+  const elements = await page.$$('[data-andesite-type="scroll-view"]')
+  const results: ScrollViewDecl[] = []
+  for (const scrollEl of elements) {
+    if (!await isCollectableAndesiteElement(scrollEl)) {
+      continue
+    }
+    const id = await scrollEl.evaluate((node: Element) => node.getAttribute('data-andesite-id') ?? '')
+    const mountId = await collectHudMountId(scrollEl)
+    const box = await measureAndesiteBox(scrollEl)
+    const defaultVisible = await scrollEl.evaluate(
+      (node: Element) => node.getAttribute('data-andesite-default-visible') !== 'false',
+    )
+    const scrollPanels: ScrollViewDecl['panels'] = []
+    const panelEls = await scrollEl.$$('[data-andesite-type="panel"]')
+    for (const panelEl of panelEls) {
+      if (!await isCollectableAndesiteElement(panelEl)) {
+        continue
+      }
+      if (await isInsideRepeater(panelEl)) {
+        continue
+      }
+      const panelId = await panelEl.evaluate((node: Element) => node.getAttribute('data-andesite-id') ?? '')
+      const panelBox = await measureBoxRelativeToScrollChild(panelEl, scrollEl)
+      const texturePath = `textures/${panelId}.png`
+      const screenshot = await withUnclippedScrollCapture(page, panelEl, async () => {
+        return await withIsolatedCapture(page, panelEl, async () => panelEl.screenshot({ type: 'png', omitBackground: true }))
+      })
+      const outputPath = path.join(outputDir, texturePath)
+      fs.mkdirSync(path.dirname(outputPath), { recursive: true })
+      fs.writeFileSync(outputPath, screenshot)
+      scrollPanels.push({
+        id: panelId,
+        texture: texturePath,
+        x: panelBox.x,
+        y: panelBox.y,
+        width: panelBox.width,
+        height: panelBox.height,
+      })
+    }
+    const scrollButtons: ScrollViewDecl['buttons'] = []
+    const buttonEls = await scrollEl.$$('[data-andesite-type="button"]')
+    for (const btnEl of buttonEls) {
+      if (!await isCollectableAndesiteElement(btnEl)) {
+        continue
+      }
+      if (await isInsideRepeater(btnEl)) {
+        continue
+      }
+      const btnId = await btnEl.evaluate((node: Element) => node.getAttribute('data-andesite-id') ?? '')
+      const btnBox = await measureBoxRelativeToScrollChild(btnEl, scrollEl)
+      const texturePath = `textures/${btnId}.png`
+      const defaultPng = await withUnclippedScrollCapture(page, btnEl, async () => {
+        return await withIsolatedCapture(page, btnEl, async () => {
+          await setButtonCaptureState(btnEl, 'default', true)
+          return await captureButtonPng(page, btnEl)
+        })
+      })
+      const pressedPng = await withUnclippedScrollCapture(page, btnEl, async () => {
+        return await withIsolatedCapture(page, btnEl, async () => {
+          await setButtonCaptureState(btnEl, 'pressed', true)
+          return await captureButtonPng(page, btnEl)
+        })
+      })
+      const atlas = await combinePngsVertically(page, [defaultPng, pressedPng])
+      const outputPath = path.join(outputDir, texturePath)
+      fs.mkdirSync(path.dirname(outputPath), { recursive: true })
+      fs.writeFileSync(outputPath, atlas)
+      await resetButtonPreviewState(btnEl)
+      scrollButtons.push({
+        id: btnId,
+        defaultTexture: texturePath,
+        pressedTexture: texturePath,
+        x: btnBox.x,
+        y: btnBox.y,
+        width: btnBox.width,
+        height: btnBox.height,
+      })
+    }
+    const scrollLabels: ScrollViewDecl['labels'] = []
+    const labelEls = await scrollEl.$$('[data-andesite-type="label"]')
+    for (const labelEl of labelEls) {
+      if (!await isCollectableAndesiteElement(labelEl)) {
+        continue
+      }
+      if (await isInsideRepeater(labelEl)) {
+        continue
+      }
+      const labelBox = await measureBoxRelativeToScrollChild(labelEl, scrollEl)
+      const labelId = await labelEl.evaluate((node: Element) => node.getAttribute('data-andesite-id') ?? '')
+      const text = await labelEl.evaluate((node: Element) => node.getAttribute('data-andesite-text') ?? '')
+      const size = await labelEl.evaluate((node: Element) => node.getAttribute('data-andesite-size') ?? 'NORMAL')
+      const align = await labelEl.evaluate((node: Element) => node.getAttribute('data-andesite-align') ?? 'LEFT')
+      const color = await labelEl.evaluate((node: Element) => node.getAttribute('data-andesite-color') ?? 'ffffff')
+      scrollLabels.push({
+        id: labelId,
+        text,
+        x: labelBox.x,
+        y: labelBox.y,
+        width: labelBox.width,
+        height: labelBox.height,
+        size: size as ScrollViewDecl['labels'][0]['size'],
+        align: align as ScrollViewDecl['labels'][0]['align'],
+        color,
+      })
+    }
+    const scrollSlots: ScrollViewDecl['slots'] = []
+    const slotEls = await scrollEl.$$('[data-andesite-type="slot"]')
+    for (const slotEl of slotEls) {
+      if (!await isCollectableAndesiteElement(slotEl)) {
+        continue
+      }
+      if (await isInsideRepeater(slotEl)) {
+        continue
+      }
+      const slotId = await slotEl.evaluate((node: Element) => node.getAttribute('data-andesite-id') ?? '')
+      const slotMountId = await collectHudMountId(slotEl)
+      const slotIndex = await slotEl.evaluate((node: Element) => node.getAttribute('data-andesite-slot-index') ?? '')
+      const slotBox = await measureBoxRelativeToScrollChild(slotEl, scrollEl)
+      scrollSlots.push({
+        id: slotId,
+        mountId: slotMountId,
+        slot: slotIndex === '' ? scrollSlots.length : Number(slotIndex),
+        x: slotBox.x,
+        y: slotBox.y,
+        width: slotBox.width,
+        height: slotBox.height,
+      })
+    }
+    const scrollRepeaters = await rasterizeScrollRepeaters(page, scrollEl, outputDir)
+    const contentFromDom = await scrollEl.evaluate((node: Element) => {
+      const content = node.querySelector<HTMLElement>('[data-andesite-scroll-content]')
+      return content ? Math.round(content.scrollHeight) : 0
+    })
+    const contentHeight = Math.max(
+      contentFromDom,
+      box.height,
+      scrollPanels.reduce((max, panel) => Math.max(max, panel.y + panel.height), 0),
+      scrollButtons.reduce((max, btn) => Math.max(max, btn.y + btn.height), 0),
+      scrollLabels.reduce((max, label) => Math.max(max, label.y + label.height), 0),
+      scrollSlots.reduce((max, slot) => Math.max(max, slot.y + slot.height), 0),
+      scrollRepeaters.reduce((max, repeater) => Math.max(max, repeater.y + repeater.contentHeight), 0),
+    )
+    results.push({
+      id,
+      mountId,
+      x: box.x,
+      y: box.y,
+      width: box.width,
+      height: box.height,
+      contentHeight,
+      defaultVisible,
+      panels: scrollPanels,
+      buttons: scrollButtons,
+      labels: scrollLabels,
+      slots: scrollSlots,
+      repeaters: scrollRepeaters,
+    })
+  }
+  return results
+}
+
+async function rasterizeScrollRepeaters(
+  page: Page,
+  scrollEl: Awaited<ReturnType<Page['$']>>,
+  outputDir: string,
+): Promise<ScrollViewDecl['repeaters']> {
+  if (!scrollEl) {
+    return []
+  }
+  const repeaterEls = await scrollEl.$$('[data-andesite-type="repeater"]')
+  const results: ScrollViewDecl['repeaters'] = []
+  for (const repeaterEl of repeaterEls) {
+    if (!await isCollectableAndesiteElement(repeaterEl)) {
+      continue
+    }
+    const id = await repeaterEl.evaluate((node: Element) => node.getAttribute('data-andesite-id') ?? '')
+    const source = await repeaterEl.evaluate((node: Element) => node.getAttribute('data-andesite-source') ?? id)
+    const repeaterBox = await measureBoxRelativeToScrollChild(repeaterEl, scrollEl)
+    const cellBoxes = await collectRepeaterCellBoxes(repeaterEl)
+    const declaredColumns = optionalNumber(await repeaterEl.evaluate((node: Element) => node.getAttribute('data-andesite-columns')))
+    const declaredItemWidth = optionalNumber(await repeaterEl.evaluate((node: Element) => node.getAttribute('data-andesite-item-width')))
+    const declaredItemHeight = optionalNumber(await repeaterEl.evaluate((node: Element) => node.getAttribute('data-andesite-item-height')))
+    const declaredMaxItems = optionalNumber(await repeaterEl.evaluate((node: Element) => node.getAttribute('data-andesite-max-items')))
+    const declaredRowGap = optionalNumber(await repeaterEl.evaluate((node: Element) => node.getAttribute('data-andesite-row-gap')))
+    const declaredColumnGap = optionalNumber(await repeaterEl.evaluate((node: Element) => node.getAttribute('data-andesite-column-gap')))
+    const columns = Math.max(1, Math.floor(declaredColumns ?? inferRepeaterColumns(cellBoxes)))
+    const itemWidth = Math.max(1, Math.round(declaredItemWidth ?? cellBoxes[0]?.width ?? repeaterBox.width))
+    const itemHeight = Math.max(1, Math.round(declaredItemHeight ?? cellBoxes[0]?.height ?? repeaterBox.height))
+    const maxItems = declaredMaxItems ?? 0
+    const rowGap = Math.max(0, Math.round(declaredRowGap ?? inferRepeaterRowGap(cellBoxes, columns)))
+    const columnGap = Math.max(0, Math.round(declaredColumnGap ?? inferRepeaterColumnGap(cellBoxes, columns)))
+    const safeColumns = Math.max(1, Math.floor(columns))
+    const maxRows = maxItems > 0 ? Math.ceil(maxItems / safeColumns) : 1
+    const contentHeight = Math.max(itemHeight, maxRows * itemHeight + Math.max(0, maxRows - 1) * rowGap)
+    const templatePanels: ScrollViewDecl['panels'] = []
+    const panelEls = await repeaterEl.$$('[data-andesite-type="panel"]')
+    for (const panelEl of panelEls) {
+      if (!await isCollectableAndesiteElement(panelEl) || !await isInsideRepeaterFirstRow(panelEl, columns)) {
+        continue
+      }
+      const panelId = await panelEl.evaluate((node: Element) => node.getAttribute('data-andesite-id') ?? '')
+      const panelBox = await measureBoxRelativeToAncestor(panelEl, repeaterEl)
+      const texturePath = `textures/${panelId}.png`
+      const screenshot = await withUnclippedScrollCapture(page, panelEl, async () => {
+        return await withIsolatedCapture(page, panelEl, async () => panelEl.screenshot({ type: 'png', omitBackground: true }))
+      })
+      const outputPath = path.join(outputDir, texturePath)
+      fs.mkdirSync(path.dirname(outputPath), { recursive: true })
+      fs.writeFileSync(outputPath, screenshot)
+      templatePanels.push({
+        id: panelId,
+        texture: texturePath,
+        x: panelBox.x,
+        y: panelBox.y,
+        width: panelBox.width,
+        height: panelBox.height,
+      })
+    }
+    const templateButtons: ScrollViewDecl['buttons'] = []
+    const buttonEls = await repeaterEl.$$('[data-andesite-type="button"]')
+    for (const btnEl of buttonEls) {
+      if (!await isCollectableAndesiteElement(btnEl) || !await isInsideRepeaterFirstRow(btnEl, columns)) {
+        continue
+      }
+      const btnId = await btnEl.evaluate((node: Element) => node.getAttribute('data-andesite-id') ?? '')
+      const btnBox = await measureBoxRelativeToAncestor(btnEl, repeaterEl)
+      const texturePath = `textures/${btnId}.png`
+      const defaultPng = await withUnclippedScrollCapture(page, btnEl, async () => {
+        return await withIsolatedCapture(page, btnEl, async () => {
+          await setButtonCaptureState(btnEl, 'default', true)
+          return await captureButtonPng(page, btnEl)
+        })
+      })
+      const pressedPng = await withUnclippedScrollCapture(page, btnEl, async () => {
+        return await withIsolatedCapture(page, btnEl, async () => {
+          await setButtonCaptureState(btnEl, 'pressed', true)
+          return await captureButtonPng(page, btnEl)
+        })
+      })
+      const atlas = await combinePngsVertically(page, [defaultPng, pressedPng])
+      const outputPath = path.join(outputDir, texturePath)
+      fs.mkdirSync(path.dirname(outputPath), { recursive: true })
+      fs.writeFileSync(outputPath, atlas)
+      await resetButtonPreviewState(btnEl)
+      templateButtons.push({
+        id: btnId,
+        defaultTexture: texturePath,
+        pressedTexture: texturePath,
+        x: btnBox.x,
+        y: btnBox.y,
+        width: btnBox.width,
+        height: btnBox.height,
+      })
+    }
+    const templateLabels: ScrollViewDecl['labels'] = []
+    const labelEls = await repeaterEl.$$('[data-andesite-type="label"]')
+    for (const labelEl of labelEls) {
+      if (!await isCollectableAndesiteElement(labelEl) || !await isInsideRepeaterFirstRow(labelEl, columns)) {
+        continue
+      }
+      const labelBox = await measureBoxRelativeToAncestor(labelEl, repeaterEl)
+      const labelId = await labelEl.evaluate((node: Element) => node.getAttribute('data-andesite-id') ?? '')
+      const text = await labelEl.evaluate((node: Element) => node.getAttribute('data-andesite-text') ?? '')
+      const size = await labelEl.evaluate((node: Element) => node.getAttribute('data-andesite-size') ?? 'NORMAL')
+      const align = await labelEl.evaluate((node: Element) => node.getAttribute('data-andesite-align') ?? 'LEFT')
+      const color = await labelEl.evaluate((node: Element) => node.getAttribute('data-andesite-color') ?? 'ffffff')
+      templateLabels.push({
+        id: labelId,
+        text,
+        x: labelBox.x,
+        y: labelBox.y,
+        width: labelBox.width,
+        height: labelBox.height,
+        size: size as ScrollViewDecl['labels'][0]['size'],
+        align: align as ScrollViewDecl['labels'][0]['align'],
+        color,
+      })
+    }
+    const templateSlots: ScrollViewDecl['slots'] = []
+    const slotEls = await repeaterEl.$$('[data-andesite-type="slot"]')
+    for (const slotEl of slotEls) {
+      if (!await isCollectableAndesiteElement(slotEl)) {
+        continue
+      }
+      const slotId = await slotEl.evaluate((node: Element) => node.getAttribute('data-andesite-id') ?? '')
+      const slotMountId = await collectHudMountId(slotEl)
+      const slotMeta = await slotEl.evaluate((node: Element) => {
+        const declared = node.getAttribute('data-andesite-slot-index') ?? ''
+        const cell = node.closest('[data-andesite-repeater-cell]')
+        return {
+          slot: declared !== '' ? declared : cell?.getAttribute('data-andesite-repeater-slot') ?? '',
+          itemIndex: cell?.getAttribute('data-andesite-repeater-cell') ?? '',
+          virtual: node.getAttribute('data-andesite-virtual') === 'true',
+        }
+      })
+      const slotBox = await measureBoxRelativeToAncestor(slotEl, repeaterEl)
+      templateSlots.push({
+        id: slotId,
+        mountId: slotMountId,
+        slot: slotMeta.slot === '' ? templateSlots.length : Number(slotMeta.slot),
+        ...(slotMeta.itemIndex === '' ? {} : { itemIndex: Number(slotMeta.itemIndex) }),
+        ...(slotMeta.virtual ? { virtual: true } : {}),
+        x: slotBox.x,
+        y: slotBox.y,
+        width: slotBox.width,
+        height: slotBox.height,
+      })
+    }
+    results.push({
+      id,
+      source,
+      x: repeaterBox.x,
+      y: repeaterBox.y,
+      width: Math.max(repeaterBox.width, columns * itemWidth + Math.max(0, columns - 1) * columnGap),
+      height: itemHeight,
+      columns,
+      itemWidth,
+      itemHeight,
+      ...(maxItems > 0 ? { maxItems: Math.floor(maxItems) } : {}),
+      contentHeight,
+      rowGap,
+      columnGap,
+      panels: templatePanels,
+      buttons: templateButtons,
+      labels: templateLabels,
+      slots: templateSlots,
+    })
+  }
+  return results
+}
+
+async function collectRepeaterCellBoxes(repeaterEl: Awaited<ReturnType<Page['$']>>): Promise<RepeaterCellBox[]> {
+  if (!repeaterEl) {
+    return []
+  }
+  const cells = await repeaterEl.$$('[data-andesite-repeater-cell]')
+  const boxes: RepeaterCellBox[] = []
+  for (const cell of cells) {
+    const index = await cell.evaluate((node: Element) => Number((node as HTMLElement).dataset.andesiteRepeaterCell ?? '-1'))
+    if (!Number.isFinite(index) || index < 0) {
+      continue
+    }
+    const box = await measureBoxRelativeToAncestor(cell, repeaterEl)
+    boxes.push({ index, ...box })
+  }
+  boxes.sort((a, b) => a.index - b.index)
+  return boxes
+}
+
+function inferRepeaterColumns(cells: RepeaterCellBox[]): number {
+  if (cells.length <= 1) {
+    return 1
+  }
+  const first = cells[0]
+  const firstRowY = first.y
+  return Math.max(1, cells.filter(cell => Math.abs(cell.y - firstRowY) <= 1).length)
+}
+
+function inferRepeaterColumnGap(cells: RepeaterCellBox[], columns: number): number {
+  if (columns <= 1 || cells.length <= 1) {
+    return 0
+  }
+  const firstRow = cells.slice(0, columns).sort((a, b) => a.x - b.x)
+  if (firstRow.length <= 1) {
+    return 0
+  }
+  return firstRow[1].x - firstRow[0].x - firstRow[0].width
+}
+
+function inferRepeaterRowGap(cells: RepeaterCellBox[], columns: number): number {
+  if (cells.length <= columns) {
+    return 0
+  }
+  const first = cells[0]
+  const secondRow = cells.find(cell => cell.index >= columns)
+  if (!secondRow) {
+    return 0
+  }
+  return secondRow.y - first.y - first.height
+}
+
+async function isInsideRepeaterFirstRow(target: Awaited<ReturnType<Page['$']>>, columns: number): Promise<boolean> {
+  if (!target) {
+    return false
+  }
+  return await target.evaluate((node: Element, columnCount: number) => {
+    const cell = node.closest('[data-andesite-repeater-cell]') as HTMLElement | null
+    if (!cell) {
+      return false
+    }
+    const index = Number(cell.getAttribute('data-andesite-repeater-cell') ?? '-1')
+    return Number.isFinite(index) && index >= 0 && index < Math.max(1, Math.floor(columnCount))
+  }, columns)
+}
+
+async function rasterizePanels(page: Page, outputDir: string): Promise<PanelRaster[]> {
+  const elements = await page.$$('[data-andesite-type="panel"], [data-andesite-view]')
+  const results: PanelRaster[] = []
+  for (const el of elements) {
+    if (await isInsideScrollView(el)) {
+      continue
+    }
+    const id = await el.evaluate((node: Element) => (node.getAttribute('data-andesite-id') ?? '') + (node.hasAttribute('data-andesite-view') ? '/__background' : ''))
+    const mountId = await collectHudMountId(el)
+    const defaultVisible = await readDefaultVisible(el)
+    const box = await measureAndesiteBox(el)
+    // box-shadow 外溢（如面板底部投影）不在边框盒内，page.screenshot 按边框盒 clip 会把它裁掉。
+    // 量出四向外溢，贴图按含阴影的视觉包围盒外扩截取，保留完整投影；导出 overflow 供导入器
+    // 把控件按边框盒定位、贴图按外扩尺寸渲染——本体对齐边框盒、投影自然溢出控件框外。
+    // blur 不是像素外溢上界；面板随后会逐像素裁剪，先留足模糊尾部，避免把真实阴影截掉。
+    const estimatedOverflow = await measureShadowOverflow(el, 2)
+    const texturePath = `textures/${encodeURIComponent(id)}.png`
+    const captured = await withIsolatedCapture(page, el, async () => {
+      // clip 原点必须在预处理（目标已显示）后实时量：defaultVisible=false 的目标被单独显示时，
+      // 其在网格/flex 中的实际落位可能不同于"全部兄弟都显示"时的排版位置（隐藏兄弟不再占轨道），
+      // 用预处理前量的坐标会错位截空。这里量的是目标当前真实渲染位置。
+      // 负 clip 会让 Chromium 的实际取样原点与声明尺寸脱节；仅平移还不足以保留右/下阴影，
+      // 需用透明占位撑开文档绘制范围。保持视口不变，避免 vw、媒体查询及百分比布局重新排版。
+      const captureSpace = await el.evaluateHandle((node: Element, pad: VisualOverflow) => {
+        const html = document.documentElement
+        const rect = (node as HTMLElement).getBoundingClientRect()
+        const state = { style: html.getAttribute('style'), x: window.scrollX, y: window.scrollY, width: rect.width, height: rect.height, spacer: document.createElement('div') }
+        const dx = Math.max(0, Math.ceil(pad.left - rect.left - state.x))
+        const dy = Math.max(0, Math.ceil(pad.top - rect.top - state.y))
+        const right = Math.ceil(Math.max(html.scrollWidth, rect.right + state.x + pad.right))
+        const bottom = Math.ceil(Math.max(html.scrollHeight, rect.bottom + state.y + pad.bottom))
+        const transform = getComputedStyle(html).transform
+        state.spacer.style.cssText = `all: initial; position: absolute; left: ${right}px; top: ${bottom}px; width: 1px; height: 1px; visibility: hidden; pointer-events: none;`
+        html.appendChild(state.spacer)
+        if (dx > 0 || dy > 0) {
+          html.style.setProperty('transition', 'none', 'important')
+          html.style.setProperty('transform', `translate(${dx}px, ${dy}px)${transform === 'none' ? '' : ` ${transform}`}`, 'important')
+        }
+        return state
+      }, estimatedOverflow)
+      try {
+        const abs = await el.evaluate((node: Element) => {
+          const rect = (node as HTMLElement).getBoundingClientRect()
+          return { left: rect.left + window.scrollX, top: rect.top + window.scrollY, width: rect.width, height: rect.height }
+        })
+        const originalSize = await captureSpace.evaluate(state => ({ width: state.width, height: state.height }))
+        if (Math.abs(abs.width - originalSize.width) > 0.01 || Math.abs(abs.height - originalSize.height) > 0.01) {
+          throw new Error(`Panel layout changed while preparing shadow capture: ${id}`)
+        }
+        // 主动把 clip 对齐到整数 CSS 像素（左上 floor、右下 ceil），供 trimShadowOverflow 校验与反推。
+        const left = Math.floor(abs.left - estimatedOverflow.left)
+        const top = Math.floor(abs.top - estimatedOverflow.top)
+        const right = Math.ceil(abs.left + abs.width + estimatedOverflow.right)
+        const bottom = Math.ceil(abs.top + abs.height + estimatedOverflow.bottom)
+        const clip: DomBox = { x: left, y: top, width: right - left, height: bottom - top }
+        if (clip.x < 0 || clip.y < 0) {
+          throw new Error(`Panel shadow capture is outside the padded page: ${id}`)
+        }
+        const borderBoxInClip: DomBox = { x: abs.left - left, y: abs.top - top, width: abs.width, height: abs.height }
+        const png = await page.screenshot({
+          type: 'png',
+          omitBackground: true,
+          captureBeyondViewport: true,
+          clip,
+        })
+        return { png, clip, borderBoxInClip }
+      } finally {
+        try {
+          await captureSpace.evaluate(state => {
+            state.spacer.remove()
+            const html = document.documentElement
+            if (state.style === null) {
+              html.removeAttribute('style')
+            } else {
+              html.setAttribute('style', state.style)
+            }
+            window.scrollTo(state.x, state.y)
+          })
+        } finally {
+          await captureSpace.dispose()
+        }
+      }
+    })
+    // 截图后扫真实 alpha 包围盒，裁掉边框盒外的纯透明（如 overflow-hidden 裁掉的投影），反推真实 overflow。
+    const trimmed = await trimShadowOverflow(page, captured.png, captured.clip, captured.borderBoxInClip, RASTER_SCALE)
+    const outputPath = path.join(outputDir, texturePath)
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true })
+    fs.writeFileSync(outputPath, trimmed.png)
+    const overflow = trimmed.overflow
+    const hasOverflow = overflow.left > 0 || overflow.top > 0 || overflow.right > 0 || overflow.bottom > 0
+    results.push({ id, mountId, texturePath, x: box.x, y: box.y, width: captured.borderBoxInClip.width, height: captured.borderBoxInClip.height, ...(hasOverflow ? { overflow } : {}), ...(defaultVisible == null ? {} : { defaultVisible }), png: trimmed.png })
+  }
+  return results
+}
+
+async function rasterizeButtons(page: Page, outputDir: string): Promise<ButtonRaster[]> {
+  const elements = await page.$$('[data-andesite-type="button"]')
+  const results: ButtonRaster[] = []
+  for (const el of elements) {
+    if (await isInsideScrollView(el)) {
+      continue
+    }
+    const id = await el.evaluate((node: Element) => node.getAttribute('data-andesite-id') ?? '')
+    const mountId = await collectHudMountId(el)
+     const defaultVisible = await readDefaultVisible(el)
+    const box = await measureAndesiteBox(el)
+    const pressDuration = Number(await el.evaluate((node: Element) => node.getAttribute('data-andesite-press-duration') ?? '2'))
+    const clickable = await collectButtonClickable(el)
+    const layer = optionalNumber(await el.evaluate((node: Element) => node.getAttribute('data-andesite-layer')))
+    const statesJson = await el.evaluate((node: Element) => node.getAttribute('data-andesite-states') ?? '[]')
+    const labelsJson = await el.evaluate((node: Element) => node.getAttribute('data-andesite-labels') ?? '[]')
+    const states = JSON.parse(statesJson) as ButtonStateDecl[]
+    const labels = JSON.parse(labelsJson) as ButtonLabelDecl[]
+    const texturePath = `textures/${id}.png`
+    // 外层容器 box-shadow 外溢需在导出坐标与尺寸中体现，与截图外扩保持一致，
+    // 否则放大后的贴图按边框盒坐标摆放会偏移、投影对不齐按钮体。
+    const overflow = await measureShadowOverflow(el)
+    const frames: Uint8Array[] = []
+    // 截取默认态
+    await setButtonCaptureState(el, 'default', true)
+    if (el) {
+      const screenshot = await withIsolatedCapture(page, el, async () => {
+        await setButtonCaptureState(el, 'default', true)
+        return await captureButtonPng(page, el)
+      })
+      frames.push(screenshot)
+    }
+    // 截取按下态
+    await setButtonCaptureState(el, 'pressed', true)
+    if (el) {
+      const screenshot = await withIsolatedCapture(page, el, async () => {
+        await setButtonCaptureState(el, 'pressed', true)
+        return await captureButtonPng(page, el)
+      })
+      frames.push(screenshot)
+    }
+    if (frames.length === 2) {
+      const atlas = await combinePngsVertically(page, frames)
+      const outputPath = path.join(outputDir, texturePath)
+      fs.mkdirSync(path.dirname(outputPath), { recursive: true })
+      fs.writeFileSync(outputPath, atlas)
+      results.push({
+        id,
+        mountId,
+        defaultTexturePath: texturePath,
+        pressedTexturePath: texturePath,
+        x: box.x - overflow.left,
+        y: box.y - overflow.top,
+        width: box.width + overflow.left + overflow.right,
+        height: box.height + overflow.top + overflow.bottom,
+        pressDuration,
+        clickable,
+        ...(layer == null ? {} : { layer }),
+         ...(defaultVisible == null ? {} : { defaultVisible }),
+        states,
+        labels,
+        defaultPng: frames[0],
+        pressedPng: frames[1],
+      })
+    }
+    await resetButtonPreviewState(el)
+  }
+  return results
+}
+
+async function rasterizeTextInputs(page: Page, outputDir: string): Promise<TextInputDecl[]> {
+  const elements = await page.$$('[data-andesite-type="text-input"]')
+  const results: TextInputDecl[] = []
+  for (const el of elements) {
+    if (!await isCollectableAndesiteElement(el)) {
+      continue
+    }
+    const id = await el.evaluate((node: Element) => node.getAttribute('data-andesite-id') ?? '')
+    const mountId = await collectHudMountId(el)
+    const box = await measureAndesiteBox(el)
+    const value = await el.evaluate((node: Element) => node.getAttribute('data-andesite-value') ?? '')
+    const placeholder = await el.evaluate((node: Element) => node.getAttribute('data-andesite-placeholder') ?? '')
+    const maxLength = Number(await el.evaluate((node: Element) => node.getAttribute('data-andesite-max-length') ?? '32'))
+    const size = await el.evaluate((node: Element) => node.getAttribute('data-andesite-size') ?? 'NORMAL')
+    const align = await el.evaluate((node: Element) => node.getAttribute('data-andesite-align') ?? 'LEFT')
+    const color = await el.evaluate((node: Element) => node.getAttribute('data-andesite-color') ?? 'ffffff')
+    const placeholderColor = await el.evaluate((node: Element) => node.getAttribute('data-andesite-placeholder-color') ?? '8a8a8a')
+    const completionJson = await el.evaluate((node: Element) => node.getAttribute('data-andesite-completion') ?? '{}')
+    const texturePath = `textures/${id}.png`
+    const screenshot = await withIsolatedCapture(page, el, async () => {
+      return await el.screenshot({ type: 'png', omitBackground: true })
+    })
+    const outputPath = path.join(outputDir, texturePath)
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true })
+    fs.writeFileSync(outputPath, screenshot)
+    results.push({
+      id,
+      mountId,
+      texture: texturePath,
+      value,
+      placeholder,
+      x: box.x,
+      y: box.y,
+      width: box.width,
+      height: box.height,
+      maxLength: Number.isFinite(maxLength) ? maxLength : 32,
+      size: size as TextInputDecl['size'],
+      align: align as TextInputDecl['align'],
+      color,
+      placeholderColor,
+      completion: normalizeTextInputCompletion(completionJson),
+    })
+  }
+  return results
+}
+
+function normalizeTextInputCompletion(json: string): TextInputCompletionDecl {
+  const fallback: TextInputCompletionDecl = {
+    server: false,
+    minChars: 0,
+    maxItems: 0,
+    debounceTicks: 0,
+  }
+  const parsed = safeJson(json)
+  if (parsed.server !== true) {
+    return fallback
+  }
+  return {
+    server: true,
+    minChars: nonNegativeNumber(parsed.minChars, 1),
+    maxItems: nonNegativeNumber(parsed.maxItems, 5),
+    debounceTicks: nonNegativeNumber(parsed.debounceTicks, 2),
+  }
+}
+
+function safeJson(json: string): Partial<TextInputCompletionDecl> {
+  try {
+    return JSON.parse(json) as Partial<TextInputCompletionDecl>
+  } catch {
+    return {}
+  }
+}
+
+function nonNegativeNumber(value: unknown, fallback: number): number {
+  const number = Number(value ?? fallback)
+  return Number.isFinite(number) ? Math.max(0, number) : fallback
+}
+
+async function captureButtonPng(page: Page, el: Awaited<ReturnType<Page['$']>>): Promise<Uint8Array> {
+  if (!el) {
+    return new Uint8Array()
+  }
+  const cloneHandle = await el.evaluateHandle((node: Element) => {
+    const root = document.querySelector<HTMLElement>('[data-andesite-content-root]')
+    const html = document.documentElement
+    const body = document.body
+    // 声明 defaultVisible=false 的按钮以 display:none 默认隐藏，需先恢复 display 才能量出真实尺寸，
+    // 克隆到 overlay 前再还原，避免污染实时页面。
+    const selfHidden = (node as HTMLElement).getAttribute('data-andesite-default-visible') === 'false' && (node as HTMLElement).style.display === 'none'
+    if (selfHidden) {
+      (node as HTMLElement).style.display = ''
+    }
+    if (root) {
+      root.dataset.andesiteButtonCaptureVisibility = root.style.visibility
+      root.style.visibility = 'hidden'
+      // 显式 visibility:visible 的状态层可穿透祖先 visibility；opacity 隔离整棵原树，克隆不受影响。
+      root.dataset.andesiteButtonCaptureOpacity = root.style.opacity
+      root.style.opacity = '0'
+    }
+    html.dataset.andesiteButtonCaptureBackground = html.style.background
+    html.dataset.andesiteButtonCaptureBackgroundColor = html.style.backgroundColor
+    body.dataset.andesiteButtonCaptureBackground = body.style.background
+    body.dataset.andesiteButtonCaptureBackgroundColor = body.style.backgroundColor
+    html.style.background = 'transparent'
+    html.style.backgroundColor = 'transparent'
+    body.style.background = 'transparent'
+    body.style.backgroundColor = 'transparent'
+
+    const wrapper = document.createElement('div')
+    wrapper.dataset.andesiteButtonCaptureOverlay = 'true'
+    wrapper.style.position = 'fixed'
+    wrapper.style.left = '0'
+    wrapper.style.top = '0'
+    wrapper.style.margin = '0'
+    wrapper.style.padding = '0'
+    wrapper.style.background = 'transparent'
+    wrapper.style.pointerEvents = 'none'
+    wrapper.style.zIndex = '2147483647'
+
+    const rect = (node as HTMLElement).getBoundingClientRect()
+    const clone = node.cloneNode(true) as HTMLElement
+    // 按钮常用 w-full / absolute 子层，独立截图时必须脱离原布局后固化测量尺寸。
+    clone.style.position = 'relative'
+    clone.style.left = '0'
+    clone.style.top = '0'
+    clone.style.right = 'auto'
+    clone.style.bottom = 'auto'
+    clone.style.width = `${Math.max(1, Math.round(rect.width))}px`
+    clone.style.height = `${Math.max(1, Math.round(rect.height))}px`
+    clone.style.margin = '0'
+    // 外层容器 box-shadow（底座/扩散投影）溢出边框盒，克隆截图需按外扩 clip 保留，
+    // 与面板路径一致；否则按钮底部投影在编译产物里被裁掉（dev 实时渲染不受影响）。
+    const cloneBoxShadow = getComputedStyle(node as HTMLElement).boxShadow
+    clone.style.boxShadow = cloneBoxShadow
+    clone.querySelectorAll<HTMLElement>('[data-andesite-type]').forEach(controlNode => {
+      controlNode.style.opacity = '0'
+    })
+    clone.querySelectorAll<HTMLElement>('[data-andesite-type="label"], [data-andesite-preview]').forEach(previewNode => {
+      previewNode.style.visibility = 'hidden'
+      previewNode.style.opacity = '0'
+    })
+    wrapper.appendChild(clone)
+    body.appendChild(wrapper)
+    if (selfHidden) {
+      (node as HTMLElement).style.display = 'none'
+    }
+    return clone
+  })
+  const cloneElement = cloneHandle.asElement() as ElementHandle<HTMLElement> | null
+  try {
+    if (!cloneElement) {
+      return new Uint8Array()
+    }
+    // 外层容器 box-shadow（底座/扩散投影）溢出边框盒，克隆元素自身 screenshot 会裁掉。
+    // 量出四向外溢后给克隆留出 margin，再用 page.screenshot 按外扩 clip 截取，保留投影。
+    const overflow = await measureShadowOverflow(cloneElement)
+    if (overflow.left > 0 || overflow.top > 0 || overflow.right > 0 || overflow.bottom > 0) {
+      await cloneElement.evaluate((node: Element, pad: { left: number; top: number }) => {
+        const el = node as HTMLElement
+        el.style.marginLeft = `${pad.left}px`
+        el.style.marginTop = `${pad.top}px`
+      }, { left: overflow.left, top: overflow.top })
+      const box = await cloneElement.boundingBox()
+      if (!box) {
+        return new Uint8Array()
+      }
+      return await page.screenshot({
+        type: 'png',
+        omitBackground: true,
+        clip: {
+          x: Math.max(0, box.x - overflow.left),
+          y: Math.max(0, box.y - overflow.top),
+          width: box.width + overflow.left + overflow.right,
+          height: box.height + overflow.top + overflow.bottom,
+        },
+      })
+    }
+    return await cloneElement.screenshot({ type: 'png', omitBackground: true })
+  } finally {
+    await page.evaluate(() => {
+      document.querySelectorAll<HTMLElement>('[data-andesite-button-capture-overlay]').forEach(node => {
+        node.remove()
+      })
+      const root = document.querySelector<HTMLElement>('[data-andesite-content-root]')
+      if (root) {
+        root.style.visibility = root.dataset.andesiteButtonCaptureVisibility ?? ''
+        delete root.dataset.andesiteButtonCaptureVisibility
+        root.style.opacity = root.dataset.andesiteButtonCaptureOpacity ?? ''
+        delete root.dataset.andesiteButtonCaptureOpacity
+      }
+      const html = document.documentElement
+      const body = document.body
+      html.style.background = html.dataset.andesiteButtonCaptureBackground ?? ''
+      html.style.backgroundColor = html.dataset.andesiteButtonCaptureBackgroundColor ?? ''
+      body.style.background = body.dataset.andesiteButtonCaptureBackground ?? ''
+      body.style.backgroundColor = body.dataset.andesiteButtonCaptureBackgroundColor ?? ''
+      delete html.dataset.andesiteButtonCaptureBackground
+      delete html.dataset.andesiteButtonCaptureBackgroundColor
+      delete body.dataset.andesiteButtonCaptureBackground
+      delete body.dataset.andesiteButtonCaptureBackgroundColor
+    })
+    await cloneHandle.dispose()
+  }
+}
+
+// 仅改变编译专用页面：沿目标祖先逐层选中视图，兄弟仍 display:none，保持真实布局而非把全部视图摊开。
+async function selectCaptureView(target: Awaited<ReturnType<Page['$']>>): Promise<void> {
+  if (!target) return
+  await target.evaluate(node => {
+    const selected = new Map<Element, Element>()
+    let view = node.closest('[data-andesite-view]')
+    while (view) {
+      selected.set(view.parentElement!, view)
+      view = view.parentElement?.closest('[data-andesite-view]') ?? null
+    }
+    for (const stack of document.querySelectorAll('[data-andesite-viewstack]')) {
+      for (const child of stack.querySelectorAll<HTMLElement>(':scope > [data-andesite-view]')) {
+        const active = selected.has(stack) ? selected.get(stack) === child : child.dataset.andesiteViewName === stack.getAttribute('data-andesite-default-view')
+        child.style.display = active ? child.dataset.andesiteViewDisplay ?? '' : 'none'
+      }
+    }
+  })
+}
+
+async function measureAndesiteBox(target: Awaited<ReturnType<Page['$']>>): Promise<DomBox> {
+  if (!target) {
+    return { x: 0, y: 0, width: 0, height: 0 }
+  }
+  await selectCaptureView(target)
+  return await target.evaluate((node: Element) => {
+    const canvas = document.querySelector<HTMLElement>('[data-andesite-canvas]')
+    const isHud = canvas?.getAttribute('data-andesite-page-kind') === 'hud'
+    const root = isHud
+      ? (node.closest('[data-andesite-hud-mount]') as HTMLElement | null) ?? document.querySelector<HTMLElement>('[data-andesite-content-root]')
+      : document.querySelector<HTMLElement>('[data-andesite-content-root]')
+    if (!root) {
+      return { x: 0, y: 0, width: 0, height: 0 }
+    }
+    // 声明 defaultVisible=false 的控件以 display:none 默认隐藏，getBoundingClientRect 全为 0。
+    // 只恢复自身 display 不够——兄弟隐藏控件仍 display:none 会改变网格/flex 轨道分配，
+    // 父级 display:none 则自身仍无布局。须把页面上所有此类隐藏控件一并临时恢复，按真实排版测量后统一还原。
+    const hiddenSiblings = Array.from(
+      (root as HTMLElement).querySelectorAll<HTMLElement>('[data-andesite-default-visible="false"]'),
+    ).filter(n => n.style.display === 'none')
+    hiddenSiblings.forEach(n => { n.style.display = '' })
+    const rootRect = root.getBoundingClientRect()
+    const rect = (node as HTMLElement).getBoundingClientRect()
+    hiddenSiblings.forEach(n => { n.style.display = 'none' })
+    return {
+      x: Math.round(rect.left - rootRect.left),
+      y: Math.round(rect.top - rootRect.top),
+      width: Math.round(rect.width),
+      height: Math.round(rect.height),
+    }
+  })
+}
+
+// progress 被圆角容器包裹时取容器包围盒（与 renderProgressPng 的胶囊外形同一参照），否则取自身。
+async function measureProgressCapsuleBox(target: Awaited<ReturnType<Page['$']>>): Promise<DomBox> {
+  if (!target) {
+    return { x: 0, y: 0, width: 0, height: 0 }
+  }
+  return await target.evaluate((node: Element) => {
+    const canvas = document.querySelector<HTMLElement>('[data-andesite-canvas]')
+    const isHud = canvas?.getAttribute('data-andesite-page-kind') === 'hud'
+    const root = isHud
+      ? (node.closest('[data-andesite-hud-mount]') as HTMLElement | null) ?? document.querySelector<HTMLElement>('[data-andesite-content-root]')
+      : document.querySelector<HTMLElement>('[data-andesite-content-root]')
+    if (!root) {
+      return { x: 0, y: 0, width: 0, height: 0 }
+    }
+    let capsule: HTMLElement = node as HTMLElement
+    let current: HTMLElement | null = (node as HTMLElement).parentElement
+    while (current && current !== document.body) {
+      const style = getComputedStyle(current)
+      const radius = Number.parseFloat(style.borderTopLeftRadius || '0')
+      const clipped = style.overflow === 'hidden' || style.overflowX === 'hidden' || style.overflowY === 'hidden'
+      if (clipped && Number.isFinite(radius) && radius > 0) {
+        capsule = current
+        break
+      }
+      current = current.parentElement
+    }
+    const rootRect = root.getBoundingClientRect()
+    const rect = capsule.getBoundingClientRect()
+    return {
+      x: Math.round(rect.left - rootRect.left),
+      y: Math.round(rect.top - rootRect.top),
+      width: Math.round(rect.width),
+      height: Math.round(rect.height),
+    }
+  })
+}
+
+// 元素边框盒不含 box-shadow 外溢；截图与导出尺寸需按视觉包围盒外扩，否则面板底部投影被裁掉。
+interface VisualOverflow { left: number; top: number; right: number; bottom: number }
+
+async function measureShadowOverflow(target: Awaited<ReturnType<Page['$']>>, blurScale = 1): Promise<VisualOverflow> {
+  if (!target) {
+    return { left: 0, top: 0, right: 0, bottom: 0 }
+  }
+  return await target.evaluate((node: Element, blurScale: number) => {
+    // 自身 overflow:hidden 只裁剪内容，不裁自身 box-shadow；祖先裁剪交由真实截图和 alpha 测量处理。
+    const shadow = getComputedStyle(node as HTMLElement).boxShadow
+    const overflow = { left: 0, top: 0, right: 0, bottom: 0 }
+    if (!shadow || shadow === 'none') {
+      return overflow
+    }
+    // 按逗号拆分层阴影，但 rgba() 内含逗号，需跳过括号内的逗号。
+    const layers: string[] = []
+    let depth = 0
+    let current = ''
+    for (const ch of shadow) {
+      if (ch === '(') depth++
+      if (ch === ')') depth--
+      if (ch === ',' && depth === 0) { layers.push(current); current = ''; continue }
+      current += ch
+    }
+    layers.push(current)
+    for (const layer of layers) {
+      if (/\binset\b/.test(layer)) continue  // 内阴影不外溢
+      const nums = layer.match(/-?\d+(?:\.\d+)?px/g)?.map(v => parseFloat(v)) ?? []
+      const [offsetX = 0, offsetY = 0, blur = 0, spread = 0] = nums
+      const reach = blur * blurScale + Math.max(0, spread)
+      overflow.left = Math.max(overflow.left, -offsetX + reach - Math.min(0, spread))
+      overflow.top = Math.max(overflow.top, -offsetY + reach - Math.min(0, spread))
+      overflow.right = Math.max(overflow.right, offsetX + reach - Math.min(0, spread))
+      overflow.bottom = Math.max(overflow.bottom, offsetY + reach - Math.min(0, spread))
+    }
+    return {
+      left: Math.max(0, Math.ceil(overflow.left)),
+      top: Math.max(0, Math.ceil(overflow.top)),
+      right: Math.max(0, Math.ceil(overflow.right)),
+      bottom: Math.max(0, Math.ceil(overflow.bottom)),
+    }
+  }, blurScale)
+}
+
+// measureShadowOverflow 按 box-shadow 声明算理论外溢，但不知道元素自身 overflow:hidden 会把投影裁进
+// 边框盒（如 wish_panel 自身 rounded + overflow-hidden，投影根本渲染不出去）。结果理论外溢虚高，
+// clip 外扩出一块实际没有任何像素的纯透明区，导入器又按虚高 overflow 外扩控件框 → 本体在框内占比变小、
+// 游戏里显得图小。这里截图后扫真实 alpha 包围盒，把边框盒之外的纯透明裁掉，并用真实包围盒反推 overflow。
+// 更正上述裁剪原因：元素自身 overflow:hidden 不会裁掉自身投影；祖先可以裁剪投影，负 clip 则会造成取样坐标脱节。
+// 裁剪框 = alpha 包围盒 ∪ 边框盒（边框盒必须完整保留，圆角/透明控件也不例外），只删纯透明(alpha=0)。
+async function trimShadowOverflow(
+  page: Page,
+  png: Uint8Array,
+  clip: DomBox,
+  borderBoxInClip: DomBox,
+  scale: number,
+): Promise<{ png: Uint8Array; overflow: VisualOverflow }> {
+  const geometry = [
+    clip.x, clip.y, clip.width, clip.height,
+    borderBoxInClip.x, borderBoxInClip.y, borderBoxInClip.width, borderBoxInClip.height,
+    scale,
+  ]
+  if (!geometry.every(Number.isFinite) || scale <= 0 || clip.x < 0 || clip.y < 0 || clip.width <= 0 || clip.height <= 0 || borderBoxInClip.width <= 0 || borderBoxInClip.height <= 0) {
+    throw new Error('Invalid shadow capture geometry')
+  }
+  // Puppeteer 会对 clip 做 CSS 像素舍入，调用方须先固定最终整数截图矩形。
+  if (![clip.x, clip.y, clip.width, clip.height].every(Number.isInteger)) {
+    throw new Error('Shadow capture clip must use integer CSS coordinates')
+  }
+
+  const result = await page.evaluate(async (input) => {
+    const image = new Image()
+    const loaded = new Promise<void>((resolve, reject) => {
+      image.onload = () => resolve()
+      image.onerror = () => reject(new Error('Failed to decode shadow capture'))
+    })
+    image.src = `data:image/png;base64,${input.base64}`
+    await loaded
+
+    const width = image.naturalWidth
+    const height = image.naturalHeight
+    // 不从错误的 PNG 尺寸反推 scale，否则把截图异常掩盖成合法缩放。
+    if (width !== Math.round(input.clip.width * input.scale) || height !== Math.round(input.clip.height * input.scale)) {
+      throw new Error(`Shadow capture PNG ${width}x${height} does not match clip ${input.clip.width}x${input.clip.height} @${input.scale}`)
+    }
+
+    const box = input.borderBoxInClip
+    const bx0 = box.x * input.scale
+    const by0 = box.y * input.scale
+    const bx1 = (box.x + box.width) * input.scale
+    const by1 = (box.y + box.height) * input.scale
+    if (bx0 < 0 || by0 < 0 || bx1 > width || by1 > height) {
+      throw new Error('Border box is outside shadow capture')
+    }
+
+    const canvas = document.createElement('canvas')
+    canvas.width = width
+    canvas.height = height
+    const ctx = canvas.getContext('2d', { willReadFrequently: true })
+    if (!ctx) {
+      throw new Error('Failed to create shadow scan context')
+    }
+    ctx.drawImage(image, 0, 0)
+    const pixels = ctx.getImageData(0, 0, width, height).data
+
+    // 从完整边框盒向外扩展（右/下用 exclusive 边界），透明控件也保留其布局尺寸。
+    let left = Math.floor(bx0)
+    let top = Math.floor(by0)
+    let right = Math.ceil(bx1)
+    let bottom = Math.ceil(by1)
+    for (let y = 0, alphaIndex = 3; y < height; y++) {
+      for (let x = 0; x < width; x++, alphaIndex += 4) {
+        // 只删纯透明，保留所有低 alpha 阴影像素。
+        if (pixels[alphaIndex] === 0) {
+          continue
+        }
+        if (x < left) left = x
+        if (y < top) top = y
+        if (x + 1 > right) right = x + 1
+        if (y + 1 > bottom) bottom = y + 1
+      }
+    }
+
+    // overflow = 边框盒各边到裁剪框各边的距离（CSS px），天然非负，与裁剪后贴图尺寸自洽。
+    const overflow = {
+      left: (bx0 - left) / input.scale,
+      top: (by0 - top) / input.scale,
+      right: (right - bx1) / input.scale,
+      bottom: (bottom - by1) / input.scale,
+    }
+
+    if (left === 0 && top === 0 && right === width && bottom === height) {
+      return { base64: null, overflow }
+    }
+
+    const cropped = document.createElement('canvas')
+    cropped.width = right - left
+    cropped.height = bottom - top
+    const croppedCtx = cropped.getContext('2d')
+    if (!croppedCtx) {
+      throw new Error('Failed to create shadow crop context')
+    }
+    croppedCtx.imageSmoothingEnabled = false
+    croppedCtx.drawImage(image, left, top, cropped.width, cropped.height, 0, 0, cropped.width, cropped.height)
+    const dataUrl = cropped.toDataURL('image/png')
+    return { base64: dataUrl.substring(dataUrl.indexOf(',') + 1), overflow }
+  }, {
+    base64: Buffer.from(png).toString('base64'),
+    clip,
+    borderBoxInClip,
+    scale,
+  })
+
+  return {
+    png: result.base64 === null ? png : Buffer.from(result.base64, 'base64'),
+    overflow: result.overflow,
+  }
+}
+
+async function collectHudMountId(target: Awaited<ReturnType<Page['$']>>): Promise<string | undefined> {
+  if (!target) {
+    return undefined
+  }
+  return await target.evaluate((node: Element) => {
+    const canvas = document.querySelector<HTMLElement>('[data-andesite-canvas]')
+    if (canvas?.getAttribute('data-andesite-page-kind') !== 'hud') {
+      return undefined
+    }
+
+    const mount = node.closest('[data-andesite-hud-mount]') as HTMLElement | null
+    const mountId = mount?.getAttribute('data-andesite-id') ?? ''
+    return mountId === '' ? undefined : mountId
+  })
+}
+
+async function isCollectableAndesiteElement(target: Awaited<ReturnType<Page['$']>>): Promise<boolean> {
+  if (!target) {
+    return false
+  }
+  const box = await measureAndesiteBox(target)
+  if (box.width <= 0 || box.height <= 0) return false
+  return await target.evaluate((node: Element) => {
+    // 视图层级由 viewStacks 单独导出，采集时祖先视图已经切到当前目标。
+    if (node.closest('[data-andesite-viewstack]') && !node.closest('[data-andesite-view]')) {
+      return false
+    }
+
+    // AButton 会为默认/按下态复制 children；隐藏克隆层里的 A* 控件只用于按钮贴图导出，不应重复注册为运行时控件。
+    let current: HTMLElement | null = node as HTMLElement
+    while (current) {
+      const style = getComputedStyle(current)
+      if (current.getAttribute('data-andesite-preview') === 'button-size' || current.hasAttribute('data-andesite-button-export')) {
+        return false
+      }
+      if (style.display === 'none' || style.visibility === 'hidden' || style.visibility === 'collapse') {
+        // 声明了 data-andesite-default-visible="false" 的控件，其 hidden 是"默认隐藏待运行时切换"，
+        // 不是要剔除——照常导出（并在结果里记 defaultVisible=false，由运行时控制初始显隐）。
+        // 未声明该标记的 hidden 控件维持旧行为：视为真隐藏，跳过。
+        if (current.getAttribute('data-andesite-default-visible') !== 'false') {
+          return false
+        }
+      }
+      if (current.hasAttribute('data-andesite-content-root')) {
+        break
+      }
+      current = current.parentElement
+    }
+    return true
+  })
+}
+
+// 读取控件声明的默认可见性。仅当显式标记 data-andesite-default-visible="false" 时返回 false（默认隐藏，
+// 待运行时切换）；未标记或标记为 true 都视为默认可见，返回 undefined 以保持 andesite.json 简洁、向后兼容。
+async function readDefaultVisible(target: Awaited<ReturnType<Page['$']>>): Promise<boolean | undefined> {
+  if (!target) {
+    return undefined
+  }
+  const value = await target.evaluate((node: Element) => node.getAttribute('data-andesite-default-visible'))
+  return value === 'false' ? false : undefined
+}
+
+async function withIsolatedCapture<T>(page: Page, target: Awaited<ReturnType<Page['$']>>, capture: () => Promise<T>, hideTargetLabels = true): Promise<T> {
+  if (!target) {
+    return await capture()
+  }
+  await page.evaluate((targetNode: Element, hideLabels: boolean) => {
+    const root = document.querySelector<HTMLElement>('[data-andesite-content-root]')
+    const nodes = Array.from((root ?? document).querySelectorAll<HTMLElement>('*'))
+    nodes.forEach(node => {
+      node.dataset.andesiteCaptureVisibility = node.style.visibility
+      node.dataset.andesiteCaptureOpacity = node.style.opacity
+      node.dataset.andesiteCaptureDisplay = node.style.display
+      node.style.visibility = 'hidden'
+    })
+
+    // Puppeteer 截图的是屏幕合成结果，必须只显示当前目标，避免普通 sibling overlay 被烘进 PNG。
+    // 目标若声明 defaultVisible=false，其初始 display 是 none（默认隐藏），须临时恢复为可见才能截到内容，
+    // 截完由下方恢复逻辑还原。祖先链恢复其原始值即可（目标自身随后单独强制）。
+    let current: HTMLElement | null = targetNode as HTMLElement
+    while (current) {
+      current.style.visibility = current.dataset.andesiteCaptureVisibility ?? ''
+      current = current.parentElement
+    }
+    if (targetNode.getAttribute('data-andesite-default-visible') === 'false') {
+      (targetNode as HTMLElement).style.visibility = 'visible'
+      // display:none 时 visibility 不生效。目标自身恢复 display 之外，其 defaultVisible=false 的祖先
+      // （如整组隐藏的卡片，按钮嵌在其内）也必须一并恢复，否则目标仍无布局、截不到内容。
+      ;(targetNode as HTMLElement).style.display = ''
+      let ancestor = (targetNode as HTMLElement).parentElement
+      while (ancestor && ancestor !== document.documentElement) {
+        if (ancestor.getAttribute('data-andesite-default-visible') === 'false') {
+          ancestor.style.display = ''
+        }
+        ancestor = ancestor.parentElement
+      }
+    }
+    targetNode.querySelectorAll<HTMLElement>('*').forEach(node => {
+      if (node === targetNode || !node.matches('[data-andesite-type]')) {
+        node.style.visibility = node.dataset.andesiteCaptureVisibility ?? ''
+      }
+    })
+    // 按钮贴图只烘普通 DOM 装饰；嵌套的 A* 控件独立导出，必须整棵透明，避免 ASprite 子状态 visibility 穿透。
+    targetNode.querySelectorAll<HTMLElement>('[data-andesite-type]').forEach(node => {
+      node.style.opacity = '0'
+    })
+    // 控件贴图只截自身像素；祖先容器（HUD mount、content-root、预览舞台 #1a1a1a、body 等）的背景
+    // 不能烘进 PNG，否则面板圆角/半透明边缘会被填上舞台底色（黑）。黑色舞台在 content-root 之上，
+    // 必须一路清到 body，不能在 content-root 停下。此前仅 sprite 清理且止于 content-root，现统一。
+    {
+      let current = targetNode.parentElement
+      while (current && current !== document.documentElement) {
+        current.dataset.andesiteCaptureBackground = current.style.background
+        current.dataset.andesiteCaptureBackgroundColor = current.style.backgroundColor
+        current.dataset.andesiteCaptureBorderColor = current.style.borderColor
+        current.dataset.andesiteCaptureBoxShadow = current.style.boxShadow
+        current.dataset.andesiteCaptureOutline = current.style.outline
+        current.style.background = 'transparent'
+        current.style.backgroundColor = 'transparent'
+        current.style.borderColor = 'transparent'
+        current.style.boxShadow = 'none'
+        current.style.outline = 'none'
+        current = current.parentElement
+      }
+    }
+    if (hideLabels) {
+      targetNode.querySelectorAll<HTMLElement>('[data-andesite-type="label"], [data-andesite-preview]').forEach(node => {
+        node.style.visibility = 'hidden'
+        node.style.opacity = '0'
+      })
+    }
+  }, target, hideTargetLabels)
+  try {
+    return await capture()
+  } finally {
+    await page.evaluate(() => {
+      document.querySelectorAll<HTMLElement>('[data-andesite-capture-visibility]').forEach(node => {
+        node.style.visibility = node.dataset.andesiteCaptureVisibility ?? ''
+        node.style.opacity = node.dataset.andesiteCaptureOpacity ?? ''
+        if (node.dataset.andesiteCaptureDisplay != null) {
+          node.style.display = node.dataset.andesiteCaptureDisplay
+          delete node.dataset.andesiteCaptureDisplay
+        }
+        if (node.dataset.andesiteCaptureBackground != null) {
+          node.style.background = node.dataset.andesiteCaptureBackground
+          node.style.backgroundColor = node.dataset.andesiteCaptureBackgroundColor ?? ''
+          node.style.borderColor = node.dataset.andesiteCaptureBorderColor ?? ''
+          node.style.boxShadow = node.dataset.andesiteCaptureBoxShadow ?? ''
+          node.style.outline = node.dataset.andesiteCaptureOutline ?? ''
+          delete node.dataset.andesiteCaptureBackground
+          delete node.dataset.andesiteCaptureBackgroundColor
+          delete node.dataset.andesiteCaptureBorderColor
+          delete node.dataset.andesiteCaptureBoxShadow
+          delete node.dataset.andesiteCaptureOutline
+        }
+        delete node.dataset.andesiteCaptureVisibility
+        delete node.dataset.andesiteCaptureOpacity
+      })
+    })
+  }
+}
+
+async function withUnclippedScrollCapture<T>(page: Page, target: Awaited<ReturnType<Page['$']>>, capture: () => Promise<T>): Promise<T> {
+  if (!target) {
+    return await capture()
+  }
+  await page.evaluate((targetNode: Element) => {
+    const scrollNode = targetNode.closest<HTMLElement>('[data-andesite-type="scroll-view"]')
+    if (!scrollNode) {
+      return
+    }
+    const contentNode = scrollNode.querySelector<HTMLElement>('[data-andesite-scroll-content]')
+    const nodes = [scrollNode, contentNode]
+    nodes.forEach(node => {
+      if (!node) {
+        return
+      }
+      node.dataset.andesiteScrollCaptureOverflow = node.style.overflow
+      node.dataset.andesiteScrollCaptureOverflowX = node.style.overflowX
+      node.dataset.andesiteScrollCaptureOverflowY = node.style.overflowY
+      node.style.overflow = 'visible'
+      node.style.overflowX = 'visible'
+      node.style.overflowY = 'visible'
+    })
+  }, target)
+  try {
+    return await capture()
+  } finally {
+    await page.evaluate(() => {
+      document.querySelectorAll<HTMLElement>('[data-andesite-scroll-capture-overflow]').forEach(node => {
+        node.style.overflow = node.dataset.andesiteScrollCaptureOverflow ?? ''
+        node.style.overflowX = node.dataset.andesiteScrollCaptureOverflowX ?? ''
+        node.style.overflowY = node.dataset.andesiteScrollCaptureOverflowY ?? ''
+        delete node.dataset.andesiteScrollCaptureOverflow
+        delete node.dataset.andesiteScrollCaptureOverflowX
+        delete node.dataset.andesiteScrollCaptureOverflowY
+      })
+    })
+  }
+}
+
+async function withHiddenAndesiteControls<T>(page: Page, capture: () => Promise<T>, target?: Awaited<ReturnType<Page['$']>>): Promise<T> {
+  await page.evaluate((targetNode: Element | null) => {
+    const root = (targetNode as HTMLElement | null) ?? document.querySelector<HTMLElement>('[data-andesite-content-root]')
+    if (!root) {
+      return
+    }
+
+    const rootRect = root.getBoundingClientRect()
+    const carrier = targetNode == null ? (root.firstElementChild as HTMLElement | null) ?? root : root
+    const carrierRect = carrier.getBoundingClientRect()
+    const overlay = carrier.cloneNode(true) as HTMLElement
+    overlay.dataset.andesiteStaticCaptureOverlay = 'true'
+    overlay.style.position = 'fixed'
+    overlay.style.left = `${carrierRect.left}px`
+    overlay.style.top = `${carrierRect.top}px`
+    overlay.style.width = `${carrierRect.width}px`
+    overlay.style.height = `${carrierRect.height}px`
+    overlay.style.margin = '0'
+    overlay.style.zIndex = '2147483647'
+    overlay.style.pointerEvents = 'none'
+    overlay.style.visibility = 'visible'
+    const hiddenControls = [
+      ...(overlay.matches('[data-andesite-type], [data-andesite-preview]') ? [overlay] : []),
+      ...Array.from(overlay.querySelectorAll<HTMLElement>('[data-andesite-type], [data-andesite-preview]')),
+    ]
+    hiddenControls.forEach(node => {
+      // 静态背景要保留布局占位；opacity 会隐藏整棵子树，避免子节点 visibility 覆盖导致按钮被烘进背景。
+      node.style.opacity = '0'
+    })
+    root.dataset.andesiteCaptureVisibility = root.style.visibility
+    root.dataset.andesiteStaticCapture = 'true'
+    root.style.visibility = 'hidden'
+
+    // 静态背景需要保留普通 DOM 装饰，但不能把按钮、Label、Panel 等独立控件重复烘进背景图。
+    if (carrierRect.left !== rootRect.left || carrierRect.top !== rootRect.top) {
+      const wrapper = document.createElement('div')
+      wrapper.dataset.andesiteStaticCaptureOverlay = 'true'
+      wrapper.style.position = 'fixed'
+      wrapper.style.left = `${rootRect.left}px`
+      wrapper.style.top = `${rootRect.top}px`
+      wrapper.style.width = `${rootRect.width}px`
+      wrapper.style.height = `${rootRect.height}px`
+      wrapper.style.margin = '0'
+      wrapper.style.zIndex = '2147483647'
+      wrapper.style.pointerEvents = 'none'
+      wrapper.appendChild(overlay)
+      document.body.appendChild(wrapper)
+    } else {
+      document.body.appendChild(overlay)
+    }
+  }, target ?? null)
+  // 只合成静态副本；omitBackground 不会移除预览舞台和 body 的 CSS 底色。
+  // 预览舞台 .andesite-preview-stage 带 #1a1a1a 底色与背景图，opacity:0 不阻止其背景被合成，
+  // 必须显式把背景清成 transparent，否则 HUD mount 背景图会带上一层深灰底。
+  const captureStyle = await page.addStyleTag({ content: `
+    html, body, .andesite-preview-stage, .andesite-preview-canvas-wrapper { background: transparent !important; background-image: none !important; }
+    body > :not([data-andesite-static-capture-overlay]) { opacity: 0 !important; }
+  ` })
+  try {
+    return await capture()
+  } finally {
+    await captureStyle.evaluate(node => node.remove())
+    await page.evaluate(() => {
+      document.querySelectorAll<HTMLElement>('[data-andesite-capture-visibility]').forEach(node => {
+        node.style.visibility = node.dataset.andesiteCaptureVisibility ?? ''
+        delete node.dataset.andesiteCaptureVisibility
+      })
+      document.querySelectorAll<HTMLElement>('[data-andesite-static-capture]').forEach(node => {
+        delete node.dataset.andesiteStaticCapture
+      })
+      document.querySelectorAll<HTMLElement>('[data-andesite-static-capture-overlay]').forEach(node => {
+        node.remove()
+      })
+    })
+  }
+}
+
+async function setButtonCaptureState(el: Awaited<ReturnType<Page['$']>>, state: 'default' | 'pressed', showPreview: boolean): Promise<void> {
+  if (!el) {
+    return
+  }
+  await el.evaluate((node: Element, targetState: 'default' | 'pressed', shouldShowPreview: boolean) => {
+    const defaultNode = node.querySelector<HTMLElement>('[data-andesite-state="default"]')
+    const pressedNode = node.querySelector<HTMLElement>('[data-andesite-state="pressed"]')
+    const contentNode = node.querySelector<HTMLElement>('[data-andesite-preview="button-content"]')
+    const previewNode = node.querySelector<HTMLElement>('[data-andesite-preview="button-labels"]')
+    if (defaultNode) {
+      defaultNode.style.visibility = 'visible'
+      defaultNode.style.opacity = targetState === 'default' ? '1' : '0'
+    }
+    if (pressedNode) {
+      pressedNode.style.visibility = 'visible'
+      pressedNode.style.opacity = targetState === 'pressed' ? '1' : '0'
+    }
+    if (contentNode) {
+      contentNode.style.visibility = 'hidden'
+      contentNode.style.opacity = '0'
+    }
+    if (previewNode) {
+      previewNode.style.visibility = shouldShowPreview ? 'visible' : 'hidden'
+    }
+  }, state, showPreview)
+}
+
+async function resetButtonPreviewState(el: Awaited<ReturnType<Page['$']>>): Promise<void> {
+  if (!el) {
+    return
+  }
+  await el.evaluate((node: Element) => {
+    const defaultNode = node.querySelector<HTMLElement>('[data-andesite-state="default"]')
+    const pressedNode = node.querySelector<HTMLElement>('[data-andesite-state="pressed"]')
+    const contentNode = node.querySelector<HTMLElement>('[data-andesite-preview="button-content"]')
+    if (defaultNode) {
+      defaultNode.style.visibility = 'visible'
+      defaultNode.style.opacity = '0'
+    }
+    if (pressedNode) {
+      pressedNode.style.visibility = 'visible'
+      pressedNode.style.opacity = '0'
+    }
+    if (contentNode) {
+      contentNode.style.visibility = 'visible'
+      contentNode.style.opacity = '1'
+    }
+  })
+}
+
+async function rasterizeProgresses(page: Page, outputDir: string): Promise<ProgressDecl[]> {
+  const elements = await page.$$('[data-andesite-type="progress"]')
+  const results: ProgressDecl[] = []
+  for (const el of elements) {
+    if (!await isCollectableAndesiteElement(el)) {
+      continue
+    }
+    const id = await el.evaluate((node: Element) => node.getAttribute('data-andesite-id') ?? '')
+    const mountId = await collectHudMountId(el)
+    // 圆角容器包裹 progress 时，导出包围盒取容器（与 renderProgressPng 的胶囊外形一致），
+    // 否则取 progress 自身；保证贴图尺寸、坐标与胶囊外形对齐。
+    const box = await measureProgressCapsuleBox(el)
+    const value = Number(await el.evaluate((node: Element) => node.getAttribute('data-andesite-value') ?? '0'))
+    const max = Number(await el.evaluate((node: Element) => node.getAttribute('data-andesite-max') ?? '100'))
+    const steps = Math.max(1, Number(await el.evaluate((node: Element) => node.getAttribute('data-andesite-steps') ?? `${DEFAULT_PROGRESS_STEPS}`)))
+    const currentPercent = max <= 0 ? 0 : Math.max(0, Math.min(100, value / max * 100))
+    const defaultIndex = Math.round(currentPercent / 100 * steps)
+    const states: ProgressDecl['states'] = []
+    const frames: Uint8Array[] = []
+    const texturePath = `textures/${id}.png`
+    for (let i = 0; i <= steps; i++) {
+      const percent = Math.round(i * 1000 / steps) / 10
+      const percentId = progressPercentId(percent)
+      const screenshot = await renderProgressPng(el, percent)
+      frames.push(screenshot)
+      states.push({
+        id: `p_${percentId}`,
+        texture: texturePath,
+        value: percent,
+        defaultState: i === defaultIndex,
+      })
+    }
+    const atlas = await combinePngsVertically(page, frames)
+    const outputPath = path.join(outputDir, texturePath)
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true })
+    fs.writeFileSync(outputPath, atlas)
+    results.push({ id, mountId, x: box.x, y: box.y, width: box.width, height: box.height, states })
+  }
+  return results
+}
+
+async function rasterizeSprites(page: Page, outputDir: string): Promise<SpriteDecl[]> {
+  const elements = await page.$$('[data-andesite-type="sprite"]')
+  const results: SpriteDecl[] = []
+  for (const el of elements) {
+    if (!await isCollectableAndesiteElement(el)) {
+      continue
+    }
+    const id = await el.evaluate((node: Element) => node.getAttribute('data-andesite-id') ?? '')
+    const mountId = await collectHudMountId(el)
+    const box = await measureAndesiteBox(el)
+    const statesJson = await el.evaluate((node: Element) => node.getAttribute('data-andesite-states') ?? '[]')
+    const stateDecls = JSON.parse(statesJson) as Array<{ id: string; defaultState?: boolean }>
+    const texturePath = `textures/${id}.png`
+    const frames: Uint8Array[] = []
+    const states: SpriteDecl['states'] = []
+    for (let i = 0; i < stateDecls.length; i++) {
+      const state = stateDecls[i]
+      const screenshot = await captureSpriteStatePng(page, el, state.id)
+      frames.push(screenshot)
+      states.push({
+        id: state.id,
+        texture: texturePath,
+        defaultState: state.defaultState === true || (i === 0 && !stateDecls.some(item => item.defaultState === true)),
+      })
+    }
+    if (frames.length === 0) {
+      continue
+    }
+
+    const atlas = await combinePngsVertically(page, frames)
+    const outputPath = path.join(outputDir, texturePath)
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true })
+    fs.writeFileSync(outputPath, atlas)
+    results.push({ id, mountId, x: box.x, y: box.y, width: box.width, height: box.height, states })
+  }
+  return results
+}
+
+async function captureSpriteStatePng(page: Page, el: Awaited<ReturnType<Page['$']>>, stateId: string): Promise<Uint8Array> {
+  if (!el) {
+    return new Uint8Array()
+  }
+  const cloneHandle = await el.evaluateHandle((node: Element, targetStateId: string) => {
+    const root = document.querySelector<HTMLElement>('[data-andesite-content-root]')
+    const html = document.documentElement
+    const body = document.body
+    if (root) {
+      root.dataset.andesiteSpriteCaptureVisibility = root.style.visibility
+      root.style.visibility = 'hidden'
+      // 与按钮克隆一致，阻止原页面显式可见的状态层污染透明帧。
+      root.dataset.andesiteSpriteCaptureOpacity = root.style.opacity
+      root.style.opacity = '0'
+    }
+    html.dataset.andesiteSpriteCaptureBackground = html.style.background
+    html.dataset.andesiteSpriteCaptureBackgroundColor = html.style.backgroundColor
+    body.dataset.andesiteSpriteCaptureBackground = body.style.background
+    body.dataset.andesiteSpriteCaptureBackgroundColor = body.style.backgroundColor
+    html.style.background = 'transparent'
+    html.style.backgroundColor = 'transparent'
+    body.style.background = 'transparent'
+    body.style.backgroundColor = 'transparent'
+
+    const wrapper = document.createElement('div')
+    wrapper.dataset.andesiteSpriteCaptureOverlay = 'true'
+    wrapper.style.position = 'fixed'
+    wrapper.style.left = '0'
+    wrapper.style.top = '0'
+    wrapper.style.margin = '0'
+    wrapper.style.padding = '0'
+    wrapper.style.background = 'transparent'
+    wrapper.style.pointerEvents = 'none'
+    wrapper.style.zIndex = '2147483647'
+
+    const rect = (node as HTMLElement).getBoundingClientRect()
+    const clone = node.cloneNode(true) as HTMLElement
+    // 状态层常用 absolute inset-0 继承父级尺寸；克隆到独立 wrapper 后必须固化尺寸，否则截图宽高会归零。
+    clone.style.position = 'relative'
+    clone.style.left = '0'
+    clone.style.top = '0'
+    clone.style.right = 'auto'
+    clone.style.bottom = 'auto'
+    clone.style.width = `${Math.max(1, Math.round(rect.width))}px`
+    clone.style.height = `${Math.max(1, Math.round(rect.height))}px`
+    clone.style.margin = '0'
+    clone.querySelectorAll<HTMLElement>('[data-andesite-state]').forEach(stateNode => {
+      stateNode.style.visibility = stateNode.getAttribute('data-andesite-state') === targetStateId ? 'visible' : 'hidden'
+    })
+    wrapper.appendChild(clone)
+    body.appendChild(wrapper)
+    return clone
+  }, stateId)
+  const cloneElement = cloneHandle.asElement()
+  try {
+    if (!cloneElement) {
+      return new Uint8Array()
+    }
+    return await cloneElement.screenshot({ type: 'png', omitBackground: true })
+  } finally {
+    await page.evaluate(() => {
+      document.querySelectorAll<HTMLElement>('[data-andesite-sprite-capture-overlay]').forEach(node => {
+        node.remove()
+      })
+      const root = document.querySelector<HTMLElement>('[data-andesite-content-root]')
+      if (root) {
+        root.style.visibility = root.dataset.andesiteSpriteCaptureVisibility ?? ''
+        delete root.dataset.andesiteSpriteCaptureVisibility
+        root.style.opacity = root.dataset.andesiteSpriteCaptureOpacity ?? ''
+        delete root.dataset.andesiteSpriteCaptureOpacity
+      }
+      const html = document.documentElement
+      const body = document.body
+      html.style.background = html.dataset.andesiteSpriteCaptureBackground ?? ''
+      html.style.backgroundColor = html.dataset.andesiteSpriteCaptureBackgroundColor ?? ''
+      body.style.background = body.dataset.andesiteSpriteCaptureBackground ?? ''
+      body.style.backgroundColor = body.dataset.andesiteSpriteCaptureBackgroundColor ?? ''
+      delete html.dataset.andesiteSpriteCaptureBackground
+      delete html.dataset.andesiteSpriteCaptureBackgroundColor
+      delete body.dataset.andesiteSpriteCaptureBackground
+      delete body.dataset.andesiteSpriteCaptureBackgroundColor
+    })
+    await cloneHandle.dispose()
+  }
+}
+
+async function combinePngsVertically(page: Page, frames: Uint8Array[]): Promise<Uint8Array> {
+  if (frames.length === 0) {
+    return new Uint8Array()
+  }
+  const dataUrls = frames.map(frame => `data:image/png;base64,${Buffer.from(frame).toString('base64')}`)
+  const dataUrl = await page.evaluate(async (sources: string[]) => {
+    const images = await Promise.all(sources.map(source => new Promise<HTMLImageElement>((resolve, reject) => {
+      const image = new Image()
+      image.onload = () => resolve(image)
+      image.onerror = () => reject(new Error(`Failed to load atlas frame: ${source.substring(0, 32)}`))
+      image.src = source
+    })))
+    const width = Math.max(...images.map(image => image.width))
+    const height = images.reduce((sum, image) => sum + image.height, 0)
+    const canvas = document.createElement('canvas')
+    canvas.width = width
+    canvas.height = height
+    const ctx = canvas.getContext('2d')!
+    ctx.imageSmoothingEnabled = false
+
+    // Andesite 源 atlas 纵向排列，避免 progress 档位较多时生成过宽图片。
+    let y = 0
+    images.forEach(image => {
+      ctx.drawImage(image, 0, y)
+      y += image.height
+    })
+    return canvas.toDataURL('image/png')
+  }, dataUrls)
+  return Buffer.from(dataUrl.substring(dataUrl.indexOf(',') + 1), 'base64')
+}
+
+function progressPercentId(percent: number): string {
+  const normalized = Math.round(percent * 10) / 10
+  return Number.isInteger(normalized) ? `${normalized}` : normalized.toFixed(1).replace('.', '_')
+}
+
+async function renderProgressPng(el: Awaited<ReturnType<Page['$']>>, percent: number): Promise<Uint8Array> {
+  if (!el) {
+    return new Uint8Array()
+  }
+  const dataUrl = await el.evaluate((node: Element, value: number) => {
+    const target = node as HTMLElement
+    // 圆角/边框常做在包裹 progress 的容器上（容器 overflow:hidden 把直角 fill 裁成胶囊）。
+    // 单独栅格化 progress 会丢失容器裁剪、暴露直角；向上找最近的圆角裁剪容器，用它作胶囊外形，
+    // 让导出贴图自带与 web 一致的圆角与边框。
+    let capsule: HTMLElement = target
+    let current: HTMLElement | null = target.parentElement
+    while (current && current !== document.body) {
+      const style = getComputedStyle(current)
+      const radius = Number.parseFloat(style.borderTopLeftRadius || '0')
+      const clipped = style.overflow === 'hidden' || style.overflowX === 'hidden' || style.overflowY === 'hidden'
+      if (clipped && Number.isFinite(radius) && radius > 0) {
+        capsule = current
+        break
+      }
+      current = current.parentElement
+    }
+    const rect = capsule.getBoundingClientRect()
+    const width = Math.max(1, Math.round(rect.width))
+    const height = Math.max(1, Math.round(rect.height))
+    const capsuleStyle = getComputedStyle(capsule)
+    const track = target.children.item(0) as HTMLElement | null
+    const fill = target.children.item(1) as HTMLElement | null
+    const trackStyle = track ? getComputedStyle(track) : getComputedStyle(target)
+    const fillStyle = fill ? getComputedStyle(fill) : trackStyle
+    const fillWidth = Math.max(0, Math.min(width, Math.round(width * value / 100)))
+    // 胶囊外形容器的圆角同时约束底槽与填充；填充自身圆角取容器值，保证任意进度下两端圆弧一致。
+    const capsuleRadius = borderRadius(capsuleStyle, width, height)
+    const capsuleBorder = Number.parseFloat(capsuleStyle.borderTopWidth || '0')
+    const capsuleBorderColor = capsuleStyle.borderTopColor
+    const canvas = document.createElement('canvas')
+    canvas.width = width
+    canvas.height = height
+    const ctx = canvas.getContext('2d')!
+    ctx.imageSmoothingEnabled = false
+    // AProgress 不能依赖截图路径，否则动态进度每一帧会互相污染；Canvas 绘制时必须还原 CSS 圆角。
+    // 底槽：优先取容器底色（无则退回 track 色），再画容器边框，与 web 叠放顺序一致。
+    ctx.fillStyle = solidColor(capsuleStyle.backgroundColor, solidColor(trackStyle.backgroundColor, '#00000000'))
+    fillRoundedRect(ctx, 0, 0, width, height, capsuleRadius)
+    if (capsuleBorder > 0 && capsuleBorderColor && capsuleBorderColor !== 'rgba(0, 0, 0, 0)') {
+      ctx.lineWidth = capsuleBorder
+      ctx.strokeStyle = capsuleBorderColor
+      strokeRoundedRect(ctx, capsuleBorder / 2, capsuleBorder / 2, width - capsuleBorder, height - capsuleBorder, Math.max(0, capsuleRadius - capsuleBorder / 2))
+    }
+    if (fillWidth > 0) {
+      ctx.fillStyle = fillPaint(ctx, fillStyle.backgroundImage, fillStyle.backgroundColor, fillWidth, height)
+      fillRoundedRect(ctx, 0, 0, fillWidth, height, capsuleRadius)
+    }
+    return canvas.toDataURL('image/png')
+
+    function solidColor(value: string, fallback: string): string {
+      return value && value !== 'rgba(0, 0, 0, 0)' ? value : fallback
+    }
+
+    function fillPaint(context: CanvasRenderingContext2D, backgroundImage: string, backgroundColor: string, fillWidth: number, fillHeight: number): string | CanvasGradient {
+      // 解析 linear-gradient 的方向与颜色停靠点；computed style 会把方向归一成角度或省略（默认 180deg 自上而下）。
+      const gradientMatch = backgroundImage.match(/linear-gradient\((.*)\)$/)
+      if (gradientMatch) {
+        const body = gradientMatch[1]
+        const stops = parseGradientStops(body)
+        if (stops.length >= 2) {
+          const [x0, y0, x1, y1] = gradientAxis(body, fillWidth, fillHeight)
+          const gradient = context.createLinearGradient(x0, y0, x1, y1)
+          for (const stop of stops) {
+            gradient.addColorStop(stop.offset, stop.color)
+          }
+          return gradient
+        }
+      }
+      return solidColor(backgroundColor, '#ffffff')
+    }
+
+    // 解析 linear-gradient 的角度/方向为 canvas 起止坐标。角度以顺时针、0deg 指向正上方为准（CSS 规范）。
+    function gradientAxis(body: string, width: number, height: number): [number, number, number, number] {
+      const first = body.slice(0, body.indexOf(',')).trim().toLowerCase()
+      let deg = 180
+      if (/^-?\d+(?:\.\d+)?deg$/.test(first)) {
+        deg = Number.parseFloat(first)
+      } else if (first.startsWith('to ')) {
+        if (first.includes('top')) deg = 0
+        else if (first.includes('bottom')) deg = 180
+        else if (first.includes('left')) deg = 270
+        else if (first.includes('right')) deg = 90
+      }
+      const rad = (deg - 90) * Math.PI / 180
+      const dx = Math.cos(rad)
+      const dy = Math.sin(rad)
+      // 渐变轴长度取矩形对角在方向上的投影，保证 CSS 角到角语义。
+      const half = Math.abs(width * dx) / 2 + Math.abs(height * dy) / 2
+      const cx = width / 2
+      const cy = height / 2
+      return [cx - dx * half, cy - dy * half, cx + dx * half, cy + dy * half]
+    }
+
+    // 解析颜色停靠点为 {color, offset}；无显式百分比时按索引均摊。rgba() 内含逗号需整体匹配。
+    function parseGradientStops(body: string): Array<{ color: string; offset: number }> {
+      const colorRe = /(rgba?\([^)]*\))(?:\s+(\d+(?:\.\d+)?)%)?/g
+      const stops: Array<{ color: string; offset: number }> = []
+      let match: RegExpExecArray | null
+      while ((match = colorRe.exec(body)) !== null) {
+        const percent = match[2] !== undefined ? Number.parseFloat(match[2]) / 100 : -1
+        stops.push({ color: match[1], offset: percent })
+      }
+      const n = stops.length
+      // 省略角度的方向前缀不是颜色，colorRe 不会误匹配；补齐未声明的停靠点。
+      for (let i = 0; i < n; i++) {
+        if (stops[i].offset < 0) {
+          stops[i].offset = n <= 1 ? 0 : i / (n - 1)
+        }
+      }
+      return stops
+    }
+
+    function borderRadius(style: CSSStyleDeclaration, rectWidth: number, rectHeight: number): number {
+      const value = Number.parseFloat(style.borderTopLeftRadius || style.borderRadius || '0')
+      if (!Number.isFinite(value) || value <= 0) {
+        return 0
+      }
+      return Math.min(value, rectWidth / 2, rectHeight / 2)
+    }
+
+    function fillRoundedRect(context: CanvasRenderingContext2D, x: number, y: number, rectWidth: number, rectHeight: number, radius: number): void {
+      roundedRectPath(context, x, y, rectWidth, rectHeight, radius)
+      context.fill()
+    }
+
+    function strokeRoundedRect(context: CanvasRenderingContext2D, x: number, y: number, rectWidth: number, rectHeight: number, radius: number): void {
+      roundedRectPath(context, x, y, rectWidth, rectHeight, radius)
+      context.stroke()
+    }
+
+    function roundedRectPath(context: CanvasRenderingContext2D, x: number, y: number, rectWidth: number, rectHeight: number, radius: number): void {
+      if (radius <= 0) {
+        context.beginPath()
+        context.rect(x, y, rectWidth, rectHeight)
+        return
+      }
+      context.beginPath()
+      context.moveTo(x + radius, y)
+      context.lineTo(x + rectWidth - radius, y)
+      context.quadraticCurveTo(x + rectWidth, y, x + rectWidth, y + radius)
+      context.lineTo(x + rectWidth, y + rectHeight - radius)
+      context.quadraticCurveTo(x + rectWidth, y + rectHeight, x + rectWidth - radius, y + rectHeight)
+      context.lineTo(x + radius, y + rectHeight)
+      context.quadraticCurveTo(x, y + rectHeight, x, y + rectHeight - radius)
+      context.lineTo(x, y + radius)
+      context.quadraticCurveTo(x, y, x + radius, y)
+      context.closePath()
+    }
+  }, percent)
+  return Buffer.from(dataUrl.substring(dataUrl.indexOf(',') + 1), 'base64')
+}
+
+async function collectLabels(page: Page): Promise<LabelDecl[]> {
+  const elements = await page.$$('[data-andesite-type="label"]')
+  const results: LabelDecl[] = []
+  for (const el of elements) {
+    if (!await isCollectableAndesiteElement(el)) {
+      continue
+    }
+    if (await isInsideScrollView(el)) {
+      continue
+    }
+    const id = await el.evaluate((node: Element) => node.getAttribute('data-andesite-id') ?? '')
+    const mountId = await collectHudMountId(el)
+    const defaultVisible = await readDefaultVisible(el)
+    const rotatedBy = await findRotatingLabelAncestor(el)
+    if (rotatedBy != null) {
+      throw new Error(`[Andesite] ALabel 不支持旋转 transform：${id} 受到 ${rotatedBy} 影响。请移除 rotate-*，或把该文本改为静态 DOM 烘进背景。`)
+    }
+    const box = await measureAndesiteBox(el)
+    const text = await el.evaluate((node: Element) => node.getAttribute('data-andesite-text') ?? '')
+    const size = await el.evaluate((node: Element) => node.getAttribute('data-andesite-size') ?? 'NORMAL')
+    const align = await el.evaluate((node: Element) => node.getAttribute('data-andesite-align') ?? 'LEFT')
+    const color = await el.evaluate((node: Element) => node.getAttribute('data-andesite-color') ?? 'ffffff')
+    const shadowColor = await el.evaluate((node: Element) => node.getAttribute('data-andesite-shadow-color') ?? '')
+    const shadowOffset = Number(await el.evaluate((node: Element) => node.getAttribute('data-andesite-shadow-offset') ?? '1'))
+    const shadowVerticalOffset = Number(await el.evaluate((node: Element) => node.getAttribute('data-andesite-shadow-vertical-offset') ?? '1'))
+    results.push({
+      id, mountId, text, x: box.x, y: box.y, width: box.width, height: box.height,
+      size: size as LabelDecl['size'],
+      align: align as LabelDecl['align'],
+      color,
+      shadowColor: shadowColor || undefined,
+      shadowOffset,
+      shadowVerticalOffset,
+      ...(defaultVisible == null ? {} : { defaultVisible }),
+    })
+  }
+  return results
+}
+
+async function findRotatingLabelAncestor(el: Awaited<ReturnType<Page['$']>>): Promise<string | null> {
+  if (!el) {
+    return null
+  }
+  return await el.evaluate((node: Element) => {
+    const root = document.querySelector<HTMLElement>('[data-andesite-content-root]')
+    let current: HTMLElement | null = node as HTMLElement
+    while (current) {
+      const style = getComputedStyle(current)
+      // Bedrock 动态 label 只能还原轴对齐盒模型；旋转会让文本与已烘焙背景错位。
+      if (hasNonAxisAlignedTransform(style)) {
+        return describeNode(current)
+      }
+      if (current === root) {
+        break
+      }
+      current = current.parentElement
+    }
+    return null
+
+    function hasNonAxisAlignedTransform(style: CSSStyleDeclaration): boolean {
+      if (hasRotateProperty(style.getPropertyValue('rotate'))) {
+        return true
+      }
+      const transform = style.transform
+      if (transform == null || transform === '' || transform === 'none') {
+        return false
+      }
+      const matrix = transform.match(/^matrix\(([^)]+)\)$/)
+      if (matrix != null) {
+        const values = matrix[1].split(',').map(value => Number.parseFloat(value.trim()))
+        return values.length >= 4 && (Math.abs(values[1]) > 0.0001 || Math.abs(values[2]) > 0.0001)
+      }
+      const matrix3d = transform.match(/^matrix3d\(([^)]+)\)$/)
+      if (matrix3d != null) {
+        const values = matrix3d[1].split(',').map(value => Number.parseFloat(value.trim()))
+        return values.length >= 16 && (Math.abs(values[1]) > 0.0001 || Math.abs(values[4]) > 0.0001)
+      }
+      return /rotate|skew/i.test(transform)
+    }
+
+    function hasRotateProperty(value: string): boolean {
+      if (value == null || value === '' || value === 'none') {
+        return false
+      }
+      return value.split(/\s+/).some(part => {
+        const n = Number.parseFloat(part)
+        return Number.isFinite(n) && Math.abs(n) > 0.0001
+      })
+    }
+
+    function describeNode(target: HTMLElement): string {
+      const tag = target.tagName.toLowerCase()
+      const id = target.id ? `#${target.id}` : ''
+      const className = typeof target.className === 'string' && target.className !== ''
+        ? `.${target.className.trim().split(/\s+/).join('.')}`
+        : ''
+      return `${tag}${id}${className}`
+    }
+  })
+}
+
+/**
+ * 收集页面中所有原生 ASlot 的坐标和尺寸，不截图。
+ */
+async function collectSlots(page: Page): Promise<SlotDecl[]> {
+  const elements = await page.$$('[data-andesite-type="slot"]')
+  const results: SlotDecl[] = []
+  let visibleIndex = 0
+  for (let i = 0; i < elements.length; i++) {
+    const el = elements[i]
+    if (!await isCollectableAndesiteElement(el)) {
+      continue
+    }
+    if (await isInsideScrollView(el)) {
+      continue
+    }
+    if (await isInsideRepeater(el)) {
+      continue
+    }
+    const id = await el.evaluate((node: Element) => node.getAttribute('data-andesite-id') ?? '')
+    const mountId = await collectHudMountId(el)
+    const slotIndex = await el.evaluate((node: Element) => node.getAttribute('data-andesite-slot-index') ?? '')
+    const slot = slotIndex === '' ? visibleIndex : Number(slotIndex)
+    const box = await measureAndesiteBox(el)
+    const x = box.x
+    const y = box.y
+    const width = box.width
+    const height = box.height
+    results.push({ id, mountId, slot, x, y, width, height })
+    visibleIndex++
+  }
+  return results
+}