From b4eb6e0b0aee715cc07d30b43a93199f9c6b4d83 Mon Sep 17 00:00:00 2001
From: Tao <taoyuaus@gmail.com>
Date: Mon, 27 Jul 2026 22:30:22 -0700
Subject: [PATCH] fix(xlsx): clip anchored charts/images/drawings to the grid's
 freeze panes

The chart, image, and drawing layers spanned the whole sheet surface
with no clipping, so anchored objects scrolled past the grid origin
painted over the column/row headers, the formula bar, and the host UI
around the viewer. Each layer also carried its own copy of the
frozen-extent, anchor-rect, and scroll-compensation math.

Consolidate the geometry in grid-metrics.ts: createGridPaneLayout()
derives the freeze-pane sub-boxes (main / frozen-rows / frozen-cols /
frozen-corner) inside a grid-body layer inset past the headers, and
places each object in the pane owning its anchor origin, compensating
scroll only on the scrolling axes. The three layers become thin views
that group items by pane; each pane clips its own objects the way Excel
clips drawings per pane, with frozen panes stacked above the main pane
to match the canvas paint order.

Also align the public GRID_ROW_HEADER_WIDTH constant (40 -> 48) with
the gutter XlsxGrid actually paints, so setChartRect/getChartRect
coordinates agree with on-screen geometry; internal.ts is now the
single source for both header metrics.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../src/components/XlsxChartOverlay.vue       | 124 ++++++++--------
 .../src/components/XlsxDrawingLayer.vue       | 117 +++++++++-------
 packages/vue-xlsx/src/components/XlsxGrid.vue |   5 +-
 .../src/components/XlsxImageLayer.vue         | 118 ++++++++--------
 .../vue-xlsx/src/components/grid-metrics.ts   | 132 ++++++++++++++++++
 packages/vue-xlsx/src/composables/internal.ts |   4 +-
 tests/component/xlsx-anchored-panes.test.mjs  |  86 ++++++++++++
 7 files changed, 408 insertions(+), 178 deletions(-)
 create mode 100644 packages/vue-xlsx/src/components/grid-metrics.ts
 create mode 100644 tests/component/xlsx-anchored-panes.test.mjs

diff --git a/packages/vue-xlsx/src/components/XlsxChartOverlay.vue b/packages/vue-xlsx/src/components/XlsxChartOverlay.vue
index 4847219..74a35fc 100644
--- a/packages/vue-xlsx/src/components/XlsxChartOverlay.vue
+++ b/packages/vue-xlsx/src/components/XlsxChartOverlay.vue
@@ -4,35 +4,44 @@
     data-testid="xlsx-chart-overlay"
     :data-state="controller.isChartsLoading ? 'loading' : 'ready'"
     :data-chart-count="chartItems.length"
+    :style="layerStyle"
   >
     <div
-      v-for="item in chartItems"
-      :key="item.chart.id"
-      class="xlsx-chart-overlay__item"
-      data-testid="xlsx-chart-item"
-      :class="{
-        'xlsx-chart-overlay__item--selected': item.chart.id === selectedChartId,
-      }"
-      :style="item.style"
-      @pointerdown.stop="onChartPointerDown(item.chart, $event)"
+      v-for="pane in panes"
+      :key="pane.key"
+      class="xlsx-chart-overlay__pane"
+      :data-grid-pane="pane.key"
+      :style="pane.style"
     >
-      <MemoChartSvg
-        v-if="item.chart.chartType !== 'Unsupported'"
-        :chart="item.chart"
-        :rect="item.rect"
-        :palette="chartPalette"
-        :selected-chart-element="
-          selectedChartId === item.chart.id ? controller.selectedChartElement : null
-        "
-        :on-chart-element-pointer-down="
-          selectedChartId === item.chart.id ? onChartElementPointerDown : undefined
-        "
-        :on-chart-element-double-click="
-          selectedChartId === item.chart.id ? onChartElementDoubleClick : undefined
-        "
-      />
-      <div v-else class="xlsx-chart-overlay__unsupported">
-        📊 不支持的图表类型
+      <div
+        v-for="item in pane.items"
+        :key="item.chart.id"
+        class="xlsx-chart-overlay__item"
+        data-testid="xlsx-chart-item"
+        :class="{
+          'xlsx-chart-overlay__item--selected': item.chart.id === selectedChartId,
+        }"
+        :style="item.style"
+        @pointerdown.stop="onChartPointerDown(item.chart, $event)"
+      >
+        <MemoChartSvg
+          v-if="item.chart.chartType !== 'Unsupported'"
+          :chart="item.chart"
+          :rect="item.rect"
+          :palette="chartPalette"
+          :selected-chart-element="
+            selectedChartId === item.chart.id ? controller.selectedChartElement : null
+          "
+          :on-chart-element-pointer-down="
+            selectedChartId === item.chart.id ? onChartElementPointerDown : undefined
+          "
+          :on-chart-element-double-click="
+            selectedChartId === item.chart.id ? onChartElementDoubleClick : undefined
+          "
+        />
+        <div v-else class="xlsx-chart-overlay__unsupported">
+          📊 不支持的图表类型
+        </div>
       </div>
     </div>
   </div>
@@ -40,9 +49,9 @@
 
 <script setup lang="ts">
 import { computed, type CSSProperties } from "vue";
-import type { XlsxViewerController, XlsxChart, XlsxChartElementSelection, XlsxImageRect, XlsxImageAnchor, XlsxSheetData } from "@arcships/xlsx-core";
-import { anchorToAbsoluteRect, emuToPixels } from "@arcships/xlsx-core";
+import type { XlsxViewerController, XlsxChart, XlsxChartElementSelection, XlsxImageRect } from "@arcships/xlsx-core";
 import { MemoChartSvg } from "../optional/lazy-renderers";
+import { createGridPaneLayout, gridBodyLayerStyle, resolveAnchorRect, type GridPaneKey } from "./grid-metrics";
 import type { ChartRendererPalette } from "../render/chart-types";
 
 const props = defineProps<{
@@ -52,6 +61,7 @@ const props = defineProps<{
   scrollTop?: number;
 }>();
 
+const layerStyle = gridBodyLayerStyle;
 const selectedChartId = computed(() => props.controller.selectedChartId);
 
 const chartPalette = computed<ChartRendererPalette>(() => ({
@@ -64,51 +74,31 @@ const chartPalette = computed<ChartRendererPalette>(() => ({
 interface ChartItem {
   chart: XlsxChart;
   rect: XlsxImageRect;
+  pane: GridPaneKey;
   style: CSSProperties;
 }
 
-function frozenExtent(sheet: XlsxSheetData | null, axis: "column" | "row", zoomScale: number): number {
-  if (!sheet?.freezePanes) return 0;
-  const limit = axis === "column" ? sheet.freezePanes.col : sheet.freezePanes.row;
-  const indices = axis === "column" ? sheet.visibleCols : sheet.visibleRows;
-  const sizes = axis === "column" ? sheet.colWidths : sheet.rowHeights;
-  const fallback = axis === "column" ? sheet.defaultColWidthPx : sheet.defaultRowHeightPx;
-  const zoom = Math.max(0.1, zoomScale / 100);
-  return indices.reduce((total, actualIndex, displayIndex) =>
-    actualIndex < limit ? total + (sizes[displayIndex] || fallback) * zoom : total,
-  0);
-}
-
-function resolveAnchorRect(anchor: XlsxImageAnchor, sheet: XlsxSheetData | null, zoomScale: number): XlsxImageRect {
-  const rect = anchorToAbsoluteRect(anchor, sheet);
-  const zoom = Math.max(0.1, zoomScale / 100);
-  return {
-    left: emuToPixels(rect.x) * zoom,
-    top: emuToPixels(rect.y) * zoom,
-    width: Math.max(1, emuToPixels(rect.cx) * zoom),
-    height: Math.max(1, emuToPixels(rect.cy) * zoom),
-  };
-}
+const paneLayout = computed(() => createGridPaneLayout(
+  props.controller.activeSheet,
+  props.controller.zoomScale,
+  props.scrollLeft ?? 0,
+  props.scrollTop ?? 0,
+));
 
 const chartItems = computed<ChartItem[]>(() => {
-  const charts = props.controller.charts as XlsxChart[];
-  return charts
+  const layout = paneLayout.value;
+  return (props.controller.charts as XlsxChart[])
     .filter((chart) => chart.anchor)
     .map((chart) => {
       const rect = resolveAnchorRect(chart.anchor, props.controller.activeSheet, props.controller.zoomScale);
       const isSelected = chart.id === selectedChartId.value;
-      const frozenWidth = frozenExtent(props.controller.activeSheet, "column", props.controller.zoomScale);
-      const frozenHeight = frozenExtent(props.controller.activeSheet, "row", props.controller.zoomScale);
-      const scrollX = rect.left < frozenWidth ? 0 : props.scrollLeft ?? 0;
-      const scrollY = rect.top < frozenHeight ? 0 : props.scrollTop ?? 0;
+      const placement = layout.place(rect);
       return {
         chart,
         rect,
+        pane: placement.pane,
         style: {
-          left: `${rect.left + 48 - scrollX}px`,
-          top: `${rect.top + 24 - scrollY}px`,
-          width: `${rect.width}px`,
-          height: `${rect.height}px`,
+          ...placement.style,
           position: "absolute",
           pointerEvents: "auto",
           cursor: "pointer",
@@ -120,6 +110,11 @@ const chartItems = computed<ChartItem[]>(() => {
     });
 });
 
+const panes = computed(() => paneLayout.value.panes.map((pane) => ({
+  ...pane,
+  items: chartItems.value.filter((item) => item.pane === pane.key),
+})));
+
 function onChartPointerDown(chart: XlsxChart, _event: PointerEvent) {
   props.controller.selectChart(chart.id);
 }
@@ -134,9 +129,14 @@ function onChartElementDoubleClick(selection: XlsxChartElementSelection, _event:
 </script>
 
 <style scoped>
+/* Geometry (inset past the headers) comes from `gridBodyLayerStyle`; each
+   freeze pane clips its own charts so a scrolled-away chart never paints over
+   frozen panes, the headers, or the host UI around the surface. */
 .xlsx-chart-overlay {
-  height: 100%; left: 0; pointer-events: none;
-  position: absolute; top: 0; width: 100%;
+  pointer-events: none; position: absolute;
+}
+.xlsx-chart-overlay__pane {
+  overflow: hidden; pointer-events: none; position: absolute;
 }
 .xlsx-chart-overlay__item { background: transparent; overflow: hidden; }
 .xlsx-chart-overlay__item--selected { box-shadow: 0 0 0 1px #2563eb; }
diff --git a/packages/vue-xlsx/src/components/XlsxDrawingLayer.vue b/packages/vue-xlsx/src/components/XlsxDrawingLayer.vue
index 7fbd993..26c3513 100644
--- a/packages/vue-xlsx/src/components/XlsxDrawingLayer.vue
+++ b/packages/vue-xlsx/src/components/XlsxDrawingLayer.vue
@@ -4,71 +4,70 @@
     data-testid="xlsx-drawing-layer"
     :data-shape-count="shapeItems.length"
     :data-form-control-count="controlItems.length"
+    :style="layerStyle"
   >
     <div
-      v-for="item in shapeItems"
-      :key="item.shape.id"
-      class="xlsx-drawing-layer__shape"
-      data-testid="xlsx-shape"
-      :data-shape-geometry="item.shape.geometry"
-      :style="item.style"
+      v-for="pane in panes"
+      :key="pane.key"
+      class="xlsx-drawing-layer__pane"
+      :data-grid-pane="pane.key"
+      :style="pane.style"
     >
-      <svg viewBox="0 0 100 100" preserveAspectRatio="none" aria-hidden="true">
-        <ellipse v-if="/ellipse|oval/i.test(item.shape.geometry)" cx="50" cy="50" rx="48" ry="48" />
-        <path v-else-if="item.shape.svgPath" :d="item.shape.svgPath" :viewBox="item.shape.svgViewBox ? `0 0 ${item.shape.svgViewBox.width} ${item.shape.svgViewBox.height}` : undefined" />
-        <rect v-else x="1" y="1" width="98" height="98" rx="4" />
-      </svg>
-      <div class="xlsx-drawing-layer__text">{{ shapeText(item.shape) }}</div>
-    </div>
-    <div
-      v-for="item in controlItems"
-      :key="item.control.id"
-      class="xlsx-drawing-layer__control"
-      data-testid="xlsx-form-control"
-      :data-control-kind="item.control.kind"
-      :style="item.style"
-    >
-      <span v-if="item.control.kind === 'checkbox'" class="xlsx-drawing-layer__box">{{ item.control.checked ? '✓' : '' }}</span>
-      <span v-else-if="item.control.kind === 'radio'" class="xlsx-drawing-layer__radio">{{ item.control.checked ? '●' : '' }}</span>
-      <button v-else-if="item.control.kind === 'button'" type="button" disabled>{{ item.control.label || item.control.name || '按钮' }}</button>
-      <span v-else>{{ item.control.label || item.control.name || controlLabel(item.control.kind) }}</span>
-      <span v-if="item.control.kind === 'checkbox' || item.control.kind === 'radio'">{{ item.control.label || item.control.name }}</span>
+      <div
+        v-for="item in pane.shapes"
+        :key="item.shape.id"
+        class="xlsx-drawing-layer__shape"
+        data-testid="xlsx-shape"
+        :data-shape-geometry="item.shape.geometry"
+        :style="item.style"
+      >
+        <svg viewBox="0 0 100 100" preserveAspectRatio="none" aria-hidden="true">
+          <ellipse v-if="/ellipse|oval/i.test(item.shape.geometry)" cx="50" cy="50" rx="48" ry="48" />
+          <path v-else-if="item.shape.svgPath" :d="item.shape.svgPath" :viewBox="item.shape.svgViewBox ? `0 0 ${item.shape.svgViewBox.width} ${item.shape.svgViewBox.height}` : undefined" />
+          <rect v-else x="1" y="1" width="98" height="98" rx="4" />
+        </svg>
+        <div class="xlsx-drawing-layer__text">{{ shapeText(item.shape) }}</div>
+      </div>
+      <div
+        v-for="item in pane.controls"
+        :key="item.control.id"
+        class="xlsx-drawing-layer__control"
+        data-testid="xlsx-form-control"
+        :data-control-kind="item.control.kind"
+        :style="item.style"
+      >
+        <span v-if="item.control.kind === 'checkbox'" class="xlsx-drawing-layer__box">{{ item.control.checked ? '✓' : '' }}</span>
+        <span v-else-if="item.control.kind === 'radio'" class="xlsx-drawing-layer__radio">{{ item.control.checked ? '●' : '' }}</span>
+        <button v-else-if="item.control.kind === 'button'" type="button" disabled>{{ item.control.label || item.control.name || '按钮' }}</button>
+        <span v-else>{{ item.control.label || item.control.name || controlLabel(item.control.kind) }}</span>
+        <span v-if="item.control.kind === 'checkbox' || item.control.kind === 'radio'">{{ item.control.label || item.control.name }}</span>
+      </div>
     </div>
   </div>
 </template>
 
 <script setup lang="ts">
 import { computed, type CSSProperties } from "vue"
-import type { XlsxFormControl, XlsxImageAnchor, XlsxShape, XlsxSheetData, XlsxViewerController } from "@arcships/xlsx-core"
-import { anchorToAbsoluteRect, emuToPixels } from "@arcships/xlsx-core"
+import type { XlsxFormControl, XlsxImageAnchor, XlsxShape, XlsxViewerController } from "@arcships/xlsx-core"
+import { createGridPaneLayout, gridBodyLayerStyle, resolveAnchorRect, type GridPaneKey } from "./grid-metrics"
 
 const props = defineProps<{ controller: XlsxViewerController; scrollLeft?: number; scrollTop?: number }>()
 
-function frozenExtent(sheet: XlsxSheetData | null, axis: "column" | "row", zoomScale: number): number {
-  if (!sheet?.freezePanes) return 0
-  const limit = axis === "column" ? sheet.freezePanes.col : sheet.freezePanes.row
-  const indices = axis === "column" ? sheet.visibleCols : sheet.visibleRows
-  const sizes = axis === "column" ? sheet.colWidths : sheet.rowHeights
-  const fallback = axis === "column" ? sheet.defaultColWidthPx : sheet.defaultRowHeightPx
-  const zoom = Math.max(.1, zoomScale / 100)
-  return indices.reduce((sum, actual, display) => actual < limit ? sum + (sizes[display] || fallback) * zoom : sum, 0)
-}
+const layerStyle = gridBodyLayerStyle
+
+const paneLayout = computed(() => createGridPaneLayout(
+  props.controller.activeSheet,
+  props.controller.zoomScale,
+  props.scrollLeft ?? 0,
+  props.scrollTop ?? 0,
+))
 
-function itemStyle(anchor: XlsxImageAnchor, zIndex: number, extra?: CSSProperties): CSSProperties {
-  const sheet = props.controller.activeSheet
-  const zoom = Math.max(.1, props.controller.zoomScale / 100)
-  const rect = anchorToAbsoluteRect(anchor, sheet)
-  const left = emuToPixels(rect.x) * zoom
-  const top = emuToPixels(rect.y) * zoom
-  const frozenWidth = frozenExtent(sheet, "column", props.controller.zoomScale)
-  const frozenHeight = frozenExtent(sheet, "row", props.controller.zoomScale)
+function itemPlacement(anchor: XlsxImageAnchor, zIndex: number, extra?: CSSProperties): { pane: GridPaneKey; style: CSSProperties } {
+  const rect = resolveAnchorRect(anchor, props.controller.activeSheet, props.controller.zoomScale)
+  const placement = paneLayout.value.place(rect)
   return {
-    left: `${left + 48 - (left < frozenWidth ? 0 : props.scrollLeft ?? 0)}px`,
-    top: `${top + 24 - (top < frozenHeight ? 0 : props.scrollTop ?? 0)}px`,
-    width: `${Math.max(1, emuToPixels(rect.cx) * zoom)}px`,
-    height: `${Math.max(1, emuToPixels(rect.cy) * zoom)}px`,
-    zIndex: Math.max(1, zIndex),
-    ...extra,
+    pane: placement.pane,
+    style: { ...placement.style, zIndex: Math.max(1, zIndex), ...extra },
   }
 }
 
@@ -76,7 +75,7 @@ const shapeItems = computed(() => (props.controller.shapes as XlsxShape[])
   .filter((shape) => !shape.hidden)
   .map((shape) => ({
     shape,
-    style: itemStyle(shape.anchor, shape.zIndex, {
+    ...itemPlacement(shape.anchor, shape.zIndex, {
       "--shape-fill": shape.fill?.none ? "transparent" : shape.fill?.color || "#dbeafe",
       "--shape-stroke": shape.stroke?.none ? "transparent" : shape.stroke?.color || "#2563eb",
       "--shape-stroke-width": `${shape.stroke?.widthPx || 1}px`,
@@ -86,14 +85,24 @@ const shapeItems = computed(() => (props.controller.shapes as XlsxShape[])
 
 const controlItems = computed(() => (props.controller.formControls as XlsxFormControl[])
   .filter((control) => !control.hidden)
-  .map((control) => ({ control, style: itemStyle(control.anchor, control.zIndex) })))
+  .map((control) => ({ control, ...itemPlacement(control.anchor, control.zIndex) })))
+
+const panes = computed(() => paneLayout.value.panes.map((pane) => ({
+  ...pane,
+  shapes: shapeItems.value.filter((item) => item.pane === pane.key),
+  controls: controlItems.value.filter((item) => item.pane === pane.key),
+})))
 
 function shapeText(shape: XlsxShape): string { return shape.paragraphs.map((p) => p.runs.map((r) => r.text).join("")).join("\n") }
 function controlLabel(kind: XlsxFormControl["kind"]): string { return ({ dropdown: "下拉框", editbox: "输入框", listbox: "列表框", spinner: "微调框", scrollbar: "滚动条", label: "标签", "group-box": "分组框", unknown: "控件" } as Record<string, string>)[kind] || kind }
 </script>
 
 <style scoped>
-.xlsx-drawing-layer { height: 100%; left: 0; pointer-events: none; position: absolute; top: 0; width: 100%; }
+/* Geometry (inset past the headers) comes from `gridBodyLayerStyle`; each
+   freeze pane clips its own drawings so a scrolled-away shape never paints
+   over frozen panes, the headers, or the host UI around the surface. */
+.xlsx-drawing-layer { pointer-events: none; position: absolute; }
+.xlsx-drawing-layer__pane { overflow: hidden; pointer-events: none; position: absolute; }
 .xlsx-drawing-layer__shape, .xlsx-drawing-layer__control { box-sizing: border-box; overflow: hidden; pointer-events: none; position: absolute; }
 .xlsx-drawing-layer__shape svg { fill: var(--shape-fill); height: 100%; left: 0; position: absolute; stroke: var(--shape-stroke); stroke-width: var(--shape-stroke-width); top: 0; width: 100%; }
 .xlsx-drawing-layer__text { align-items: center; display: flex; height: 100%; justify-content: center; padding: 6px; position: relative; text-align: center; white-space: pre-wrap; z-index: 1; }
diff --git a/packages/vue-xlsx/src/components/XlsxGrid.vue b/packages/vue-xlsx/src/components/XlsxGrid.vue
index 204c28a..426a3c0 100644
--- a/packages/vue-xlsx/src/components/XlsxGrid.vue
+++ b/packages/vue-xlsx/src/components/XlsxGrid.vue
@@ -93,6 +93,7 @@ import {
   type XlsxResolvedCellStyle,
   type XlsxSheetData,
 } from "@arcships/xlsx-core";
+import { GRID_HEADER_HEIGHT_PX, GRID_ROW_HEADER_WIDTH_PX } from "./grid-metrics";
 
 const props = defineProps<{
   controller: XlsxViewerController;
@@ -111,8 +112,8 @@ const emit = defineEmits<{
 // ── Constants ──────────────────────────────────────────────────────────
 const DEFAULT_ROW_HEIGHT = 24;
 const DEFAULT_COL_WIDTH = 80;
-const HEADER_HEIGHT = 24;
-const ROW_HEADER_WIDTH = 48;
+const HEADER_HEIGHT = GRID_HEADER_HEIGHT_PX;
+const ROW_HEADER_WIDTH = GRID_ROW_HEADER_WIDTH_PX;
 const OVERSCAN = 240;
 const WORKER_ROW_BATCH_SIZE = 64;
 const MIN_DISPLAY_ROWS = 200;
diff --git a/packages/vue-xlsx/src/components/XlsxImageLayer.vue b/packages/vue-xlsx/src/components/XlsxImageLayer.vue
index 83fb5a1..f811e8b 100644
--- a/packages/vue-xlsx/src/components/XlsxImageLayer.vue
+++ b/packages/vue-xlsx/src/components/XlsxImageLayer.vue
@@ -1,40 +1,48 @@
 <template>
-  <div class="xlsx-image-layer" data-testid="xlsx-image-layer">
+  <div class="xlsx-image-layer" data-testid="xlsx-image-layer" :style="layerStyle">
     <div
-      v-for="item in imageItems"
-      :key="item.image.id"
-      class="xlsx-image-layer__item"
-      data-testid="xlsx-image-item"
-      :class="{
-        'xlsx-image-layer__item--selected': item.image.id === selectedImageId,
-      }"
-      :style="item.style"
-      @pointerdown.stop="onImagePointerDown(item.image, $event)"
+      v-for="pane in panes"
+      :key="pane.key"
+      class="xlsx-image-layer__pane"
+      :data-grid-pane="pane.key"
+      :style="pane.style"
     >
-      <img
-        v-if="item.image.src && !failedImageIds.has(item.image.id) && permittedImageIds.has(item.image.id)"
-        :src="item.image.src"
-        :alt="item.image.name ?? 'image'"
-        class="xlsx-image-layer__img"
-        draggable="false"
-        decoding="async"
-        data-image-state="loading"
-        @load="onImageLoad(item.image, $event)"
-        @error="onImageError(item.image, $event)"
-      />
       <div
-        v-else
-        class="xlsx-image-layer__placeholder"
-        :data-image-state="failedImageIds.has(item.image.id) ? 'error' : 'queued'"
-      >🖼️</div>
+        v-for="item in pane.items"
+        :key="item.image.id"
+        class="xlsx-image-layer__item"
+        data-testid="xlsx-image-item"
+        :class="{
+          'xlsx-image-layer__item--selected': item.image.id === selectedImageId,
+        }"
+        :style="item.style"
+        @pointerdown.stop="onImagePointerDown(item.image, $event)"
+      >
+        <img
+          v-if="item.image.src && !failedImageIds.has(item.image.id) && permittedImageIds.has(item.image.id)"
+          :src="item.image.src"
+          :alt="item.image.name ?? 'image'"
+          class="xlsx-image-layer__img"
+          draggable="false"
+          decoding="async"
+          data-image-state="loading"
+          @load="onImageLoad(item.image, $event)"
+          @error="onImageError(item.image, $event)"
+        />
+        <div
+          v-else
+          class="xlsx-image-layer__placeholder"
+          :data-image-state="failedImageIds.has(item.image.id) ? 'error' : 'queued'"
+        >🖼️</div>
+      </div>
     </div>
   </div>
 </template>
 
 <script setup lang="ts">
 import { computed, onUnmounted, ref, watch, type CSSProperties } from "vue";
-import type { XlsxViewerController, XlsxImage, XlsxImageAnchor, XlsxSheetData } from "@arcships/xlsx-core";
-import { anchorToAbsoluteRect, emuToPixels } from "@arcships/xlsx-core";
+import type { XlsxViewerController, XlsxImage } from "@arcships/xlsx-core";
+import { createGridPaneLayout, gridBodyLayerStyle, resolveAnchorRect, type GridPaneKey } from "./grid-metrics";
 
 const props = defineProps<{
   controller: XlsxViewerController;
@@ -43,6 +51,7 @@ const props = defineProps<{
   scrollTop?: number;
 }>();
 
+const layerStyle = gridBodyLayerStyle;
 const selectedImageId = computed(() => props.controller.selectedImageId);
 const failedImageIds = ref(new Set<string>());
 const permittedImageIds = ref(new Set<string>());
@@ -52,51 +61,32 @@ const knownSources = new Map<string, string>();
 
 interface ImageItem {
   image: XlsxImage;
+  pane: GridPaneKey;
   style: CSSProperties;
 }
 
-function frozenExtent(sheet: XlsxSheetData | null, axis: "column" | "row", zoomScale: number): number {
-  if (!sheet?.freezePanes) return 0;
-  const limit = axis === "column" ? sheet.freezePanes.col : sheet.freezePanes.row;
-  const indices = axis === "column" ? sheet.visibleCols : sheet.visibleRows;
-  const sizes = axis === "column" ? sheet.colWidths : sheet.rowHeights;
-  const fallback = axis === "column" ? sheet.defaultColWidthPx : sheet.defaultRowHeightPx;
-  const zoom = Math.max(0.1, zoomScale / 100);
-  return indices.reduce((total, actualIndex, displayIndex) =>
-    actualIndex < limit ? total + (sizes[displayIndex] || fallback) * zoom : total,
-  0);
-}
-
-function resolveAnchorRect(anchor: XlsxImageAnchor, sheet: XlsxSheetData | null, zoomScale: number) {
-  const rect = anchorToAbsoluteRect(anchor, sheet);
-  const zoom = Math.max(0.1, zoomScale / 100);
-  return {
-    left: emuToPixels(rect.x) * zoom,
-    top: emuToPixels(rect.y) * zoom,
-    width: Math.max(1, emuToPixels(rect.cx) * zoom),
-    height: Math.max(1, emuToPixels(rect.cy) * zoom),
-  };
-}
+const paneLayout = computed(() => createGridPaneLayout(
+  props.controller.activeSheet,
+  props.controller.zoomScale,
+  props.scrollLeft ?? 0,
+  props.scrollTop ?? 0,
+));
 
 const imageItems = computed<ImageItem[]>(() => {
   if (!props.showImages) return [];
+  const layout = paneLayout.value;
   const images = props.controller.images as XlsxImage[];
   return images
     .filter((img) => img.anchor)
     .map((image) => {
       const rect = resolveAnchorRect(image.anchor, props.controller.activeSheet, props.controller.zoomScale);
       const isSelected = image.id === selectedImageId.value;
-      const frozenWidth = frozenExtent(props.controller.activeSheet, "column", props.controller.zoomScale);
-      const frozenHeight = frozenExtent(props.controller.activeSheet, "row", props.controller.zoomScale);
-      const scrollX = rect.left < frozenWidth ? 0 : props.scrollLeft ?? 0;
-      const scrollY = rect.top < frozenHeight ? 0 : props.scrollTop ?? 0;
+      const placement = layout.place(rect);
       return {
         image,
+        pane: placement.pane,
         style: {
-          left: `${rect.left + 48 - scrollX}px`,
-          top: `${rect.top + 24 - scrollY}px`,
-          width: `${rect.width}px`,
-          height: `${rect.height}px`,
+          ...placement.style,
           position: "absolute",
           pointerEvents: "auto",
           cursor: "pointer",
@@ -108,6 +98,11 @@ const imageItems = computed<ImageItem[]>(() => {
     });
 });
 
+const panes = computed(() => paneLayout.value.panes.map((pane) => ({
+  ...pane,
+  items: imageItems.value.filter((item) => item.pane === pane.key),
+})));
+
 function scheduleImageDecodes(): void {
   const visibleIds = new Set(imageItems.value.map((item) => item.image.id));
   for (const id of [...activeImageIds, ...completedImageIds]) {
@@ -189,9 +184,14 @@ function onImagePointerDown(image: XlsxImage, _event: PointerEvent) {
 </script>
 
 <style scoped>
+/* Geometry (inset past the headers) comes from `gridBodyLayerStyle`; each
+   freeze pane clips its own images so a scrolled-away image never paints over
+   frozen panes, the headers, or the host UI around the surface. */
 .xlsx-image-layer {
-  height: 100%; left: 0; pointer-events: none;
-  position: absolute; top: 0; width: 100%;
+  pointer-events: none; position: absolute;
+}
+.xlsx-image-layer__pane {
+  overflow: hidden; pointer-events: none; position: absolute;
 }
 .xlsx-image-layer__item { background: transparent; overflow: hidden; }
 .xlsx-image-layer__item--selected { box-shadow: 0 0 0 2px #2563eb; }
diff --git a/packages/vue-xlsx/src/components/grid-metrics.ts b/packages/vue-xlsx/src/components/grid-metrics.ts
new file mode 100644
index 0000000..8ecd9d8
--- /dev/null
+++ b/packages/vue-xlsx/src/components/grid-metrics.ts
@@ -0,0 +1,132 @@
+import type { CSSProperties } from "vue";
+import type { XlsxImageAnchor, XlsxImageRect, XlsxSheetData } from "@arcships/xlsx-core";
+import { anchorToAbsoluteRect, emuToPixels } from "@arcships/xlsx-core";
+import { GRID_HEADER_HEIGHT, GRID_ROW_HEADER_WIDTH } from "../composables/internal";
+
+/** Height of the grid's column-header strip, in CSS pixels. */
+export const GRID_HEADER_HEIGHT_PX = GRID_HEADER_HEIGHT;
+/** Width of the grid's row-header gutter, in CSS pixels. */
+export const GRID_ROW_HEADER_WIDTH_PX = GRID_ROW_HEADER_WIDTH;
+
+/**
+ * Absolute box covering the grid body only (headers excluded), used by the
+ * chart / image / drawing overlays. `overflow: hidden` on the layer keeps
+ * anchored objects from painting over the headers or escaping the surface
+ * into the surrounding UI while the grid is scrolled.
+ */
+export const gridBodyLayerStyle: CSSProperties = {
+  height: `calc(100% - ${GRID_HEADER_HEIGHT_PX}px)`,
+  left: `${GRID_ROW_HEADER_WIDTH_PX}px`,
+  top: `${GRID_HEADER_HEIGHT_PX}px`,
+  width: `calc(100% - ${GRID_ROW_HEADER_WIDTH_PX}px)`,
+};
+
+/** Zoom factor derived from the controller's percentage scale. */
+export function gridZoomFactor(zoomScale: number): number {
+  const scale = zoomScale / 100;
+  return Number.isFinite(scale) ? Math.max(0.1, scale) : 1;
+}
+
+/** Pixel extent of the frozen columns or rows at the current zoom. */
+export function frozenExtent(
+  sheet: XlsxSheetData | null,
+  axis: "column" | "row",
+  zoomScale: number,
+): number {
+  if (!sheet?.freezePanes) return 0;
+  const limit = axis === "column" ? sheet.freezePanes.col : sheet.freezePanes.row;
+  const indices = axis === "column" ? sheet.visibleCols : sheet.visibleRows;
+  const sizes = axis === "column" ? sheet.colWidths : sheet.rowHeights;
+  const fallback = axis === "column" ? sheet.defaultColWidthPx : sheet.defaultRowHeightPx;
+  const zoom = gridZoomFactor(zoomScale);
+  return indices.reduce((total, actualIndex, displayIndex) =>
+    actualIndex < limit ? total + (sizes[displayIndex] || fallback) * zoom : total,
+  0);
+}
+
+/** Content-space rect (grid-body coordinates, zoom applied) of an anchored object. */
+export function resolveAnchorRect(
+  anchor: XlsxImageAnchor,
+  sheet: XlsxSheetData | null,
+  zoomScale: number,
+): XlsxImageRect {
+  const rect = anchorToAbsoluteRect(anchor, sheet);
+  const zoom = gridZoomFactor(zoomScale);
+  return {
+    left: emuToPixels(rect.x) * zoom,
+    top: emuToPixels(rect.y) * zoom,
+    width: Math.max(1, emuToPixels(rect.cx) * zoom),
+    height: Math.max(1, emuToPixels(rect.cy) * zoom),
+  };
+}
+
+export type GridPaneKey = "main" | "frozen-rows" | "frozen-cols" | "frozen-corner";
+
+export interface GridPane {
+  key: GridPaneKey;
+  style: CSSProperties;
+}
+
+export interface GridPanePlacement {
+  pane: GridPaneKey;
+  style: CSSProperties;
+}
+
+export interface GridPaneLayout {
+  panes: GridPane[];
+  place: (rect: XlsxImageRect) => GridPanePlacement;
+}
+
+/**
+ * Freeze-pane layout for anchored-object layers. `panes` are absolute,
+ * `overflow: hidden` sub-boxes of the grid-body layer — Excel clips drawings
+ * per pane — with frozen panes stacked above the main pane, mirroring how the
+ * canvas paints frozen cells over the scrolling region. `place` assigns an
+ * object to the pane owning its anchor origin and positions it relative to
+ * that pane's box; only the scrolling axes subtract scroll.
+ */
+export function createGridPaneLayout(
+  sheet: XlsxSheetData | null,
+  zoomScale: number,
+  scrollLeft: number,
+  scrollTop: number,
+): GridPaneLayout {
+  const frozenWidth = frozenExtent(sheet, "column", zoomScale);
+  const frozenHeight = frozenExtent(sheet, "row", zoomScale);
+  const scrollingWidth = frozenWidth ? `calc(100% - ${frozenWidth}px)` : "100%";
+  const scrollingHeight = frozenHeight ? `calc(100% - ${frozenHeight}px)` : "100%";
+
+  const panes: GridPane[] = [
+    { key: "main", style: { height: scrollingHeight, left: `${frozenWidth}px`, top: `${frozenHeight}px`, width: scrollingWidth, zIndex: 1 } },
+  ];
+  if (frozenHeight > 0) {
+    panes.push({ key: "frozen-rows", style: { height: `${frozenHeight}px`, left: `${frozenWidth}px`, top: "0px", width: scrollingWidth, zIndex: 2 } });
+  }
+  if (frozenWidth > 0) {
+    panes.push({ key: "frozen-cols", style: { height: scrollingHeight, left: "0px", top: `${frozenHeight}px`, width: `${frozenWidth}px`, zIndex: 2 } });
+  }
+  if (frozenWidth > 0 && frozenHeight > 0) {
+    panes.push({ key: "frozen-corner", style: { height: `${frozenHeight}px`, left: "0px", top: "0px", width: `${frozenWidth}px`, zIndex: 3 } });
+  }
+
+  const place = (rect: XlsxImageRect): GridPanePlacement => {
+    const colFrozen = rect.left < frozenWidth;
+    const rowFrozen = rect.top < frozenHeight;
+    const pane: GridPaneKey =
+      colFrozen && rowFrozen ? "frozen-corner"
+      : rowFrozen ? "frozen-rows"
+      : colFrozen ? "frozen-cols"
+      : "main";
+    return {
+      pane,
+      style: {
+        height: `${rect.height}px`,
+        left: `${rect.left - (colFrozen ? 0 : frozenWidth + scrollLeft)}px`,
+        top: `${rect.top - (rowFrozen ? 0 : frozenHeight + scrollTop)}px`,
+        width: `${rect.width}px`,
+      },
+    };
+  };
+
+  return { panes, place };
+}
diff --git a/packages/vue-xlsx/src/composables/internal.ts b/packages/vue-xlsx/src/composables/internal.ts
index 0cc8182..0974f65 100644
--- a/packages/vue-xlsx/src/composables/internal.ts
+++ b/packages/vue-xlsx/src/composables/internal.ts
@@ -33,8 +33,10 @@ export const XLSX_MIME_TYPE = "application/vnd.openxmlformats-officedocument.spr
 export const CSV_MIME_TYPE = "text/csv;charset=utf-8";
 export const MIN_COL_WIDTH_PX = 30;
 export const MIN_ROW_HEIGHT_PX = 16;
+// Must match the header strips painted by XlsxGrid; components/grid-metrics.ts
+// re-exports these for the view layer, so this is the single source of truth.
 export const GRID_HEADER_HEIGHT = 24;
-export const GRID_ROW_HEADER_WIDTH = 40;
+export const GRID_ROW_HEADER_WIDTH = 48;
 export const HISTORY_LIMIT = 100;
 export const DEFAULT_HISTORY_MAX_BYTES = 32 * 1024 * 1024;
 export const INTERNAL_CLIPBOARD_MIME = "application/x-react-xlsx-range+json";
diff --git a/tests/component/xlsx-anchored-panes.test.mjs b/tests/component/xlsx-anchored-panes.test.mjs
new file mode 100644
index 0000000..7cfa05a
--- /dev/null
+++ b/tests/component/xlsx-anchored-panes.test.mjs
@@ -0,0 +1,86 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { importFromDemo, mount, walk } from "./vue-test-renderer.mjs";
+
+const { XlsxImageLayer } = await importFromDemo("@arcships/vue-xlsx");
+
+const PX_TO_EMU = 9525;
+
+function absoluteImage(id, xPx, yPx) {
+  return {
+    id,
+    name: id,
+    mimeType: "image/png",
+    sheetIndex: 0,
+    workbookSheetIndex: 0,
+    src: `data:image/png;base64,${id}`,
+    zIndex: 0,
+    anchor: {
+      kind: "absolute",
+      positionEmu: { x: xPx * PX_TO_EMU, y: yPx * PX_TO_EMU },
+      sizeEmu: { cx: 120 * PX_TO_EMU, cy: 80 * PX_TO_EMU },
+    },
+  };
+}
+
+test("XLSX image layer clips anchored objects per freeze pane and only scrolls the scrolling pane", async () => {
+  const controller = {
+    selectedImageId: null,
+    zoomScale: 100,
+    activeSheet: {
+      name: "Sheet1",
+      freezePanes: { row: 2, col: 0 },
+      visibleRows: Array.from({ length: 20 }, (_, index) => index),
+      visibleCols: Array.from({ length: 10 }, (_, index) => index),
+      rowHeights: [],
+      colWidths: [],
+      defaultRowHeightPx: 24,
+      defaultColWidthPx: 80,
+      colWidthOverridesPx: {},
+      rowHeightOverridesPx: {},
+    },
+    // 一张锚在冻结行区（y=0），一张锚在滚动区（y=240px）。
+    images: [absoluteImage("frozen", 0, 0), absoluteImage("scrolling", 100, 240)],
+    selectImage() {},
+  };
+  const mounted = await mount(XlsxImageLayer, {
+    controller,
+    showImages: true,
+    scrollLeft: 30,
+    scrollTop: 100,
+  });
+  try {
+    const nodes = walk(mounted.root);
+    const panes = nodes.filter((node) => node.props?.["data-grid-pane"]);
+    assert.deepEqual(
+      panes.map((pane) => pane.props["data-grid-pane"]).sort(),
+      ["frozen-rows", "main"],
+      "freezePanes {row:2, col:0} should produce a main pane plus a frozen-rows strip",
+    );
+
+    const paneByKey = new Map(panes.map((pane) => [pane.props["data-grid-pane"], pane]));
+    const frozenPane = paneByKey.get("frozen-rows");
+    const mainPane = paneByKey.get("main");
+    // 冻结行高 2 × 24px；两个窗格在网格正文层内各占其位。
+    assert.equal(frozenPane.props.style.height, "48px");
+    assert.equal(frozenPane.props.style.top, "0px");
+    assert.equal(mainPane.props.style.top, "48px");
+
+    const itemsIn = (pane) =>
+      walk(pane).filter((node) => node.props?.["data-testid"] === "xlsx-image-item");
+    const [frozenItem] = itemsIn(frozenPane);
+    const [scrollingItem] = itemsIn(mainPane);
+    assert.ok(frozenItem, "the y=0 image belongs to the frozen-rows pane");
+    assert.ok(scrollingItem, "the y=240 image belongs to the main pane");
+
+    // 冻结条随水平滚动、不随垂直滚动：left = 0 − 30，top 固定 0。
+    assert.equal(frozenItem.props.style.left, "-30px");
+    assert.equal(frozenItem.props.style.top, "0px");
+    // 滚动区两轴都补偿，且相对 main 窗格原点（去掉 48px 冻结高）。
+    assert.equal(scrollingItem.props.style.left, "70px");
+    assert.equal(scrollingItem.props.style.top, "92px");
+  } finally {
+    mounted.app.unmount();
+  }
+});