@aiquants/spreadsheet 0.17.3 → 0.18.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -84,6 +84,29 @@
84
84
  * アウトセット帯 ([clamp, clamp + 3) / (−3, 0]) に載った非所有クローンは消灯する — 漸進アンツ
85
85
  * アウトセットが幽霊破線を継ぎ目の向こうへ引き戻せないようにするため。帯の外はクリップが元より
86
86
  * 不可視化しており、書込パターンは v0.8 と byte 恒等のまま。
87
+ *
88
+ * v0.18 frame (`frameRange`): every quadrant holds one static frame node right after its divider
89
+ * segments, so the runtime stack becomes bands < fills < dividers < frame < activeFrame < … and
90
+ * both insertion anchors keep landing below it through `chromeFloorOf`. Each quadrant frames only
91
+ * the tracks it paints (`layerTracksOf` / `frameSpanOf`) and marks the sides the range continues
92
+ * past as open (`data-aqsp-frame-open`), so the clipped clones join into one seamless frame; the
93
+ * node is placed by insets (`frameAxisCssOf`) whose open sides follow the quadrant's own size. While
94
+ * a frame is set, every quadrant also leads with a band clip capped at the layer's cells
95
+ * (`layerCellsOf` through `min(100%, …)`) that holds the band groups — their far segments end at
96
+ * the clip, their geometry unchanged — the dividers stop at the same cells
97
+ * (`max(0px, calc(100% - …))`) and the marquee's far headroom ends there, so no cell chrome runs
98
+ * past the frame, and a resize that changes no rendered track (which repaints nothing) keeps all of
99
+ * it right. Without a frame the overlay reproduces the v0.17 DOM and writes exactly.
100
+ *
101
+ * v0.18 外枠 (`frameRange`): 各象限は分割線セグメントの直後に静的な外枠のノードを 1 つ持ち、実行時スタックは
102
+ * 帯 < fill < 分割線 < 外枠 < activeFrame < … になる。動的挿入アンカー 2 つは `chromeFloorOf` 経由で外枠の下へ
103
+ * 着地し続ける。各象限は自分が描くトラックだけを囲み (`layerTracksOf` / `frameSpanOf`)、範囲が先へ続く辺を
104
+ * 開く (`data-aqsp-frame-open`) ので、クリップされた複製は継ぎ目の無い 1 つの枠になる。ノードは
105
+ * 詰め (`frameAxisCssOf`) で置き、開いた辺は象限自身の大きさに従う。枠のある間、各象限はさらに層のセル
106
+ * (`layerCellsOf` を `min(100%, …)` で) に抑えた帯の切り抜きを先頭に持ち、帯の組をその中に入れる (遠い側の片は
107
+ * 切り抜きで端が切れ、帯の幾何は変わらない)。分割線は同じセルで止まり (`max(0px, calc(100% - …))`)、マーキーの
108
+ * 遠い側の余白もそこで終わるので、セルのクロームは枠の外へ出ず、描くトラックの変わらない大きさの変化 (何も描き直さ
109
+ * ない) でもどれも正しいままでいる。枠が無ければ v0.17 の DOM と書き込みを厳密に再現する。
87
110
  */
88
111
 
89
112
  import { useWheelBridge, type VirtualGridHandle } from "@aiquants/virtualscroll"
@@ -126,6 +149,216 @@ const CLIP_MARQUEE_OUTSET = 3
126
149
  */
127
150
  export const clipMarqueeOutset = (headroom: number): string => `${-Math.min(CLIP_MARQUEE_OUTSET, Math.max(0, Math.floor(headroom)))}px`
128
151
 
152
+ /**
153
+ * The part of a frame range inside a grid of the given counts, or null when no cell of it is (v0.18). The range's bounds
154
+ * are validated non-negative integers with each start at most its end, so only the ends can lie outside. Exported for
155
+ * the direct value pins (barrel-private).
156
+ * 外枠の範囲のうち、行と列の数のグリッドの中にある部分 (v0.18。1 つのセルも無ければ null)。範囲の境は検め済み (非負の整数で
157
+ * 始まりは終わり以下) のため、外へ出うるのは終わりだけ。値ピン用にモジュール export (バレル非公開)。
158
+ */
159
+ export const frameRangeWithin = (range: CellRange, rowCount: number, colCount: number): CellRange | null => {
160
+ const endRow = Math.min(range.endRow, rowCount - 1)
161
+ const endCol = Math.min(range.endCol, colCount - 1)
162
+ return range.startRow > endRow || range.startCol > endCol ? null : { startRow: range.startRow, startCol: range.startCol, endRow, endCol }
163
+ }
164
+
165
+ /**
166
+ * The length of the cells one layer can paint along one axis from its origin (v0.18), from the tracks alone: all the
167
+ * tracks for an unsplit axis (m), the scroll tracks between the frozen bands for s, and null for a frozen band (f, t),
168
+ * whose tracks always fill it. A layer longer than this (a box wider or taller than the table) has no cells past it.
169
+ * The value does not depend on the viewport, so CSS can cap the layer with it (`min(100%, …)`) and a resize that
170
+ * changes no rendered track — which repaints nothing — keeps it right. Exported for the direct value pins
171
+ * (barrel-private).
172
+ * 1 つの層が 1 つの軸で原点から描けるセルの長さ (v0.18)。トラックだけから決まる: 分けない軸 (m) は全部のトラック、s は凍結の帯の
173
+ * 間のスクロールのトラック、凍結の帯 (f・t) はトラックがいつも層を満たすため null。層がこれより長ければ (表より広いか高い箱)、
174
+ * その先にセルは無い。ビューポートに依らないため、CSS で層を抑えられ (`min(100%, …)`)、描くトラックの変わらない大きさの変化 (何も
175
+ * 描き直さない) でも正しいままでいる。値ピン用にモジュール export (バレル非公開)。
176
+ *
177
+ * @param kind - The layer's band kind on this axis. この軸の層の帯の種別。
178
+ * @param total - The axis's tree size (px). 軸の木の大きさ (px)。
179
+ * @param frozen - The leading frozen band's tree size (px). 先頭の凍結の帯の木の大きさ (px)。
180
+ * @param trailing - The trailing frozen band's tree size (px). 末尾の凍結の帯の木の大きさ (px)。
181
+ * @returns The length (px), or null for a frozen band. 長さ (px)。凍結の帯は null。
182
+ */
183
+ export const layerCellsOf = (kind: AxisKind, total: number, frozen: number, trailing: number): number | null => {
184
+ if (kind === "m") {
185
+ return total
186
+ }
187
+ if (kind === "s") {
188
+ return Math.max(0, total - frozen - trailing)
189
+ }
190
+ return null
191
+ }
192
+
193
+ /**
194
+ * The length one layer paints cells over along one axis (v0.18): its cells (`layerCellsOf`) cut to the layer, or the
195
+ * whole layer for a frozen band. Exported for the direct value pins (barrel-private).
196
+ * 1 つの層が 1 つの軸でセルを描く長さ (v0.18): セル (`layerCellsOf`) を層で切ったもの。凍結の帯は層そのもの。値ピン用にモジュール
197
+ * export (バレル非公開)。
198
+ *
199
+ * @param layer - The layer's clamp extent (px). 層のクランプ範囲 (px)。
200
+ * @param cells - The layer's cells (`layerCellsOf`). 層のセル (`layerCellsOf`)。
201
+ * @returns The painted length (px). セルを描く長さ (px)。
202
+ */
203
+ export const paintedExtentOf = (layer: number, cells: number | null): number => (cells === null ? layer : Math.min(layer, cells))
204
+
205
+ /**
206
+ * The CSS size that caps a box at a layer's cells (v0.18): `100%` of the quadrant for a frozen band, else
207
+ * `min(100%, <cells>px)`. Exported for the direct value pins (barrel-private).
208
+ * 箱を層のセルで抑える CSS の大きさ (v0.18): 凍結の帯は象限の `100%`、ほかは `min(100%, <セル>px)`。値ピン用にモジュール export
209
+ * (バレル非公開)。
210
+ *
211
+ * @param cells - The layer's cells (`layerCellsOf`). 層のセル (`layerCellsOf`)。
212
+ * @returns The CSS size. CSS の大きさ。
213
+ */
214
+ export const cellsSizeCssOf = (cells: number | null): string => (cells === null ? "100%" : `min(100%, ${cells}px)`)
215
+
216
+ /**
217
+ * The CSS end inset that stops a divider at a layer's cells (v0.18): `0px` for a frozen band, else
218
+ * `max(0px, calc(100% - <cells>px))` — the part of the quadrant past the cells. Exported for the direct value pins
219
+ * (barrel-private).
220
+ * 分割線を層のセルで止める CSS の端の詰め (v0.18): 凍結の帯は `0px`、ほかは `max(0px, calc(100% - <セル>px))` — 象限のうちセルより
221
+ * 先の部分。値ピン用にモジュール export (バレル非公開)。
222
+ *
223
+ * @param cells - The layer's cells (`layerCellsOf`). 層のセル (`layerCellsOf`)。
224
+ * @returns The CSS inset. CSS の詰め。
225
+ */
226
+ export const cellsEndCssOf = (cells: number | null): string => (cells === null ? "0px" : `max(0px, calc(100% - ${cells}px))`)
227
+
228
+ /**
229
+ * The tracks one layer paints along one axis (v0.18) as `[first, last]`: the leading frozen tracks for f, the trailing
230
+ * ones for t, those between for s and all of them for m — `last < first` when the layer paints none. The counts are the
231
+ * engine's clamped ones (`getFrozenSize`). Exported for the direct value pins (barrel-private).
232
+ * 1 つの層が 1 つの軸で描くトラック (v0.18) を `[first, last]` で返す。f は先頭の凍結のトラック、t は末尾の凍結、s はその間、m は
233
+ * 全部 — 描かなければ `last < first`。数はエンジンがクランプした値 (`getFrozenSize`)。値ピン用にモジュール export (バレル非公開)。
234
+ *
235
+ * @param kind - The layer's band kind on this axis. この軸の層の帯の種別。
236
+ * @param count - The axis's track count. 軸のトラックの数。
237
+ * @param frozenCount - The leading frozen tracks. 先頭の凍結のトラックの数。
238
+ * @param trailingCount - The trailing frozen tracks. 末尾の凍結のトラックの数。
239
+ * @returns The first and last painted track. 描く最初と最後のトラック。
240
+ */
241
+ export const layerTracksOf = (kind: AxisKind, count: number, frozenCount: number, trailingCount: number): readonly [number, number] => {
242
+ switch (kind) {
243
+ case "f":
244
+ return [0, frozenCount - 1]
245
+ case "s":
246
+ return [frozenCount, count - trailingCount - 1]
247
+ case "t":
248
+ return [count - trailingCount, count - 1]
249
+ case "m":
250
+ return [0, count - 1]
251
+ }
252
+ }
253
+
254
+ /** The track interval of a layer in an unframed grid, where nothing reads it (paints none). / 枠の無いグリッドの層のトラックの区間 (読まれないので、描かない区間)。 */
255
+ const NO_TRACKS: readonly [number, number] = Object.freeze([0, -1] as const)
256
+
257
+ /** One axis of a frame inside one layer: its near and far edges in layer px and whether each is open (not drawn there). / 1 つの層の中の外枠の 1 つの軸: 層の px の近い辺と遠い辺、それぞれが開いている (そこに描かない) か。 */
258
+ export type FrameSpan = { near: number; far: number; nearOpen: boolean; farOpen: boolean }
259
+
260
+ /**
261
+ * Resolves one axis of a frame inside one layer into `span` (v0.18) and answers whether the layer frames anything on
262
+ * it: false when the layer paints none of the range on this axis or the range lies wholly beyond the layer's ± 1 screen
263
+ * margin (`span` is then left as it was). The layer paints the tracks `first..last`; a side whose range edge lies
264
+ * before `first` or after `last` continues into another pane (or past the axis's scrolled-away part), so it is pushed
265
+ * to the margin's edge and marked open — every pane frames only the cells it paints and the panes join into one frame
266
+ * without a seam. An edge clamped into the margin is open too (it is not there). The span is written in place, so the
267
+ * repaint path resolves a frame without allocating. Exported for the direct value pins (barrel-private).
268
+ * 1 つの層の中の外枠の 1 つの軸を `span` へ解き (v0.18)、層がこの軸で何かを囲むかを返す。層がこの軸で範囲のどこも描かないか、
269
+ * 範囲が層の ±1 画面の余白より外にあれば false (`span` はそのまま)。層はトラック `first..last` を描く。範囲の端が `first` より前か
270
+ * `last` より後にある側は別のペイン (かスクロールで外れた部分) へ続くため、余白の端に置いて開く — ペインはどれも自分が描くセルだけを
271
+ * 囲み、継ぎ目の無い 1 つの枠になる。余白へ詰めた辺も (そこに無いので) 開く。範囲はその場へ書くため、描き直しの道は確保なしに
272
+ * 外枠を解く。値ピン用にモジュール export (バレル非公開)。
273
+ *
274
+ * @param span - The span to write. 書く軸の範囲。
275
+ * @param start - The range's first track on this axis. 範囲のこの軸の最初のトラック。
276
+ * @param end - The range's last track on this axis. 範囲のこの軸の最後のトラック。
277
+ * @param first - The layer's first painted track. 層が描く最初のトラック。
278
+ * @param last - The layer's last painted track (below `first` when it paints none). 層が描く最後のトラック (描かなければ `first` より小さい)。
279
+ * @param nearEdge - The range's near edge through the layer's map (px). 層の写像を通した範囲の近い辺 (px)。
280
+ * @param farEdge - The range's far edge through the layer's map (px). 層の写像を通した範囲の遠い辺 (px)。
281
+ * @param clamp - The layer's clamp extent (px). 層のクランプ範囲 (px)。
282
+ * @returns Whether the layer frames anything on this axis. 層がこの軸で何かを囲むか。
283
+ */
284
+ export const frameSpanInto = (span: FrameSpan, start: number, end: number, first: number, last: number, nearEdge: number, farEdge: number, clamp: number): boolean => {
285
+ if (clamp <= 0 || last < first || end < first || start > last) {
286
+ return false
287
+ }
288
+ const low = -clamp * CLAMP_MARGIN_SCREENS
289
+ const high = clamp * (1 + CLAMP_MARGIN_SCREENS)
290
+ const nearInside = start >= first
291
+ const farInside = end <= last
292
+ const near = nearInside ? nearEdge : low
293
+ const far = farInside ? farEdge : high
294
+ if (far <= low || near >= high) {
295
+ return false
296
+ }
297
+ span.near = Math.max(near, low)
298
+ span.far = Math.min(far, high)
299
+ span.nearOpen = !nearInside || near < low
300
+ span.farOpen = !farInside || far > high
301
+ return true
302
+ }
303
+
304
+ /**
305
+ * A span no frame has resolved into yet (NaN edges never equal a resolved one, so the first placement always writes).
306
+ * まだどの外枠も解いていない軸の範囲を作る処理 (NaN の辺は解いた辺と等しくならず、最初の置き方は必ず書く)。
307
+ *
308
+ * @returns The span. 軸の範囲。
309
+ */
310
+ const unresolvedSpanOf = (): FrameSpan => ({ near: Number.NaN, far: Number.NaN, nearOpen: false, farOpen: false })
311
+
312
+ /**
313
+ * Whether two spans place a frame's axis alike (their edges and open sides).
314
+ * 2 つの軸の範囲が外枠の軸を同じに置くか (辺と開いた側)。
315
+ *
316
+ * @param a - One span. 一方の範囲。
317
+ * @param b - The other span. もう一方の範囲。
318
+ * @returns True when they are alike. 同じなら true。
319
+ */
320
+ const sameSpan = (a: FrameSpan, b: FrameSpan): boolean => a.near === b.near && a.far === b.far && a.nearOpen === b.nearOpen && a.farOpen === b.farOpen
321
+
322
+ /**
323
+ * Copies a span's edges and open sides.
324
+ * 軸の範囲の辺と開いた側を写す処理。
325
+ *
326
+ * @param to - The span to write. 書く範囲。
327
+ * @param from - The span to read. 読む範囲。
328
+ */
329
+ const copySpan = (to: FrameSpan, from: FrameSpan): void => {
330
+ to.near = from.near
331
+ to.far = from.far
332
+ to.nearOpen = from.nearOpen
333
+ to.farOpen = from.farOpen
334
+ }
335
+
336
+ /** The frame's sides in the CSS order, bit i of an open-side mask naming side i (v0.18). / CSS の順の外枠の辺 (v0.18)。開いた辺のマスクの bit i が辺 i。 */
337
+ const FRAME_SIDES = Object.freeze(["top", "right", "bottom", "left"] as const)
338
+
339
+ /**
340
+ * The open-side mask of a frame in one layer (v0.18): bit 1 top, 2 right, 4 bottom, 8 left. Exported for the direct
341
+ * value pins (barrel-private).
342
+ * 1 つの層の外枠の開いた辺のマスク (v0.18): bit 1 上・2 右・4 下・8 左。値ピン用にモジュール export (バレル非公開)。
343
+ *
344
+ * @param x - The horizontal span. 横の軸の範囲。
345
+ * @param y - The vertical span. 縦の軸の範囲。
346
+ * @returns The mask. マスク。
347
+ */
348
+ export const frameOpenMaskOf = (x: FrameSpan, y: FrameSpan): number => (y.nearOpen ? 1 : 0) | (x.farOpen ? 2 : 0) | (y.farOpen ? 4 : 0) | (x.nearOpen ? 8 : 0)
349
+
350
+ /**
351
+ * The `data-aqsp-frame-open` value of an open-side mask: the open sides in the CSS order, space-separated (the empty
352
+ * string for mask 0, which removes the attribute instead). Built only when the mask changes. Exported for the direct
353
+ * value pins (barrel-private).
354
+ * 開いた辺のマスクの `data-aqsp-frame-open` の値: 開いた辺を CSS の順に空白で区切る (マスク 0 は空文字で、属性を外す)。マスクが
355
+ * 変わったときだけ作る。値ピン用にモジュール export (バレル非公開)。
356
+ *
357
+ * @param mask - The open-side mask. 開いた辺のマスク。
358
+ * @returns The attribute value. 属性の値。
359
+ */
360
+ export const frameOpenSidesOf = (mask: number): string => FRAME_SIDES.filter((_side, bit) => (mask & (1 << bit)) !== 0).join(" ")
361
+
129
362
  /** Row / column / intersection highlight switches (v0.8 §2.4 — default all off = zero band nodes). / 行 / 列 / 交点強調のスイッチ (v0.8 §2.4 — 既定全 off = 帯ノード 0)。 */
130
363
  export type HighlightState = { row: boolean; column: boolean; intersection: boolean }
131
364
 
@@ -508,6 +741,13 @@ type SelectionOverlayProps = {
508
741
  * 帯ノード 0 (v0.7 の DOM 恒等)。
509
742
  */
510
743
  highlightRef?: RefObject<HighlightState>
744
+ /**
745
+ * v0.18 capability: the range to frame (the root's `frame` prop, validated there; the root repaints when it changes).
746
+ * Absent ⇒ no frame node, and the bands and dividers keep the clamp extents (v0.17 DOM and writes).
747
+ * v0.18 能力: 外枠を描く範囲 (root の `frame` prop。検めは root。変わったら root が repaint)。未指定 ⇒ 枠のノードは無く、帯と
748
+ * 分割線はクランプ範囲のまま (v0.17 の DOM と書き込み)。
749
+ */
750
+ frameRange?: CellRange
511
751
  /** v0.8 capability: identity-stable band palette written to `--aqsp-band-*` by a layout effect; the variables are removed again when the palette retires (undefined / identity change / unmount). Absent ⇒ no variable writes (CSS defaults apply — the v0.7 style attribute). / v0.8 能力: identity 安定の帯パレット (layout effect が `--aqsp-band-*` へ書き、パレットの退役 (undefined / identity 交代 / unmount) で変数を外す)。未指定 ⇒ 変数書込なし (CSS 既定 = v0.7 の style 属性)。 */
512
752
  highlightColors?: HighlightColors
513
753
  /** v0.8 capability: popover anchor cells to position (interactive + tip). Absent ⇒ anchors untouched. / v0.8 能力: 配置するポップオーバーアンカーのセル (interactive + tip)。未指定 ⇒ アンカーに触れない。 */
@@ -540,6 +780,43 @@ export type ResizeGuide = { axis: "row" | "col"; position: number; anchor: "lead
540
780
  */
541
781
  type FillSlot = { node: HTMLDivElement; last: { shown: boolean; width: number; height: number; transform: string } }
542
782
 
783
+ /**
784
+ * The frame node of one quadrant plus its placement state (v0.18 — same-value suppressed like a fill slot): the spans
785
+ * each repaint resolves into (`x`, `y`), the spans last placed (`drawnX`, `drawnY` — CSS is built only when they differ),
786
+ * the insets and sizes last written as CSS ("" = cleared) and the open-side mask of `data-aqsp-frame-open` (-1 = never
787
+ * written). A repaint that changes nothing allocates nothing.
788
+ * 象限 1 つの外枠のノードと置き方の状態 (v0.18 — fill のスロットと同じく同値抑止): 描き直しのたびに解く軸の範囲 (`x`・`y`)、最後に
789
+ * 置いた軸の範囲 (`drawnX`・`drawnY` — 違うときだけ CSS を作る)、最後に書いた CSS の詰めと大きさ ("" は外した値) と、
790
+ * `data-aqsp-frame-open` の開いた辺のマスク (-1 は未書込)。何も変えない描き直しは何も確保しない。
791
+ */
792
+ type FrameSlot = {
793
+ node: HTMLDivElement
794
+ x: FrameSpan
795
+ y: FrameSpan
796
+ drawnX: FrameSpan
797
+ drawnY: FrameSpan
798
+ last: { shown: boolean; left: string; top: string; right: string; bottom: string; width: string; height: string; open: number }
799
+ }
800
+
801
+ /**
802
+ * One axis of a frame node's CSS placement (v0.18): the near side at its span position — a closed one where the range
803
+ * starts, an open one at the margin's edge, a screen before the quadrant's start, where its missing line is out of view
804
+ * — and a closed far side through the size, an open one pinned to the quadrant's far edge (end inset 0, size auto). The
805
+ * size of a closed far side is therefore never negative (its edge lies past the margin's), so a range that scrolled
806
+ * out before the quadrant's start leaves no stale box, and its far line sits where the range ends even within a line's
807
+ * width of the start. An open far side follows the quadrant's own size, so a resize that repaints nothing still runs
808
+ * the frame's other lines to the quadrant's edge. Exported for the direct value pins (barrel-private).
809
+ * 外枠のノードの 1 つの軸の CSS の置き方 (v0.18): 近い辺は軸の範囲の位置 — 閉じた辺は範囲の始まり、開いた辺は余白の端 (象限の始まりの
810
+ * 1 画面手前。描かない線は見えない所) — に置く。閉じた遠い辺は大きさで、開いた遠い辺は象限の遠い端に付ける (端の詰め 0、大きさ
811
+ * auto)。そのため閉じた遠い辺の大きさは負にならず (その辺は余白の端より先にある)、象限の始まりより手前へスクロールで外れた範囲が
812
+ * 古い箱を残さず、始まりから線の太さの内でも遠い線は範囲の終わりに描かれる。開いた遠い辺は象限自身の大きさに従うため、何も描き
813
+ * 直さない大きさの変化でも、枠のほかの線は象限の端まで届く。値ピン用にモジュール export (バレル非公開)。
814
+ *
815
+ * @param span - The axis's span (`frameSpanInto`). 軸の範囲 (`frameSpanInto`)。
816
+ * @returns The start inset, the end inset and the size as CSS ("" = cleared). 始まりの詰め・終わりの詰め・大きさの CSS ("" は外す)。
817
+ */
818
+ export const frameAxisCssOf = (span: FrameSpan): { start: string; end: string; size: string } => (span.farOpen ? { start: `${span.near}px`, end: "0px", size: "" } : { start: `${span.near}px`, end: "", size: `${span.far - span.near}px` })
819
+
543
820
  /** Resident node set of one overlay layer (v0.5 layer split; every layer owns a dedicated container). / overlay 1 層ぶんの常設ノード束 (v0.5 の層分割。全層が専用コンテナを持つ)。 */
544
821
  type LayerNodes = {
545
822
  container: HTMLDivElement | null
@@ -560,22 +837,68 @@ type LayerNodes = {
560
837
  dividerSlots: (HTMLDivElement | null)[]
561
838
  /** Last-written shown state per divider slot (equality-suppressed `display` heal — v0.9 §2.4). / 分割線スロット毎の直近書込 shown 状態 (等値抑制 `display` heal — v0.9 §2.4)。 */
562
839
  dividerShown: boolean[]
563
- /** Identity-stable compact array of the quad's mounted segments (≤ 4, DOM order — the `chromeFloorOf` source, v0.9 §2.5). / 象限のマウント済みセグメントの identity 安定な圧縮配列 (≤ 4、DOM 順 — `chromeFloorOf` の源、v0.9 §2.5)。 */
564
- dividers: HTMLDivElement[]
840
+ /**
841
+ * Last-written end inset per divider slot as CSS — `bottom` of the vertical slots, `right` of the horizontal ones (v0.18:
842
+ * a framed grid stops its dividers at the layer's cells, `cellsEndCssOf`; `0px` = the JSX's initial end,
843
+ * equality-suppressed).
844
+ * 分割線スロット毎の直近書込の端の詰め (CSS) — 縦のスロットは `bottom`、横は `right` (v0.18: 枠のあるグリッドは分割線を層のセルで
845
+ * 止める。`cellsEndCssOf`。`0px` は JSX の初めの端で、等値抑止)。
846
+ */
847
+ dividerEnd: string[]
848
+ /** Mounted frame node of the quadrant (v0.18 — null without a frame). / 象限のマウント済みの外枠のノード (v0.18 — 枠が無ければ null)。 */
849
+ frame: FrameSlot | null
850
+ /**
851
+ * The quadrant's band clip (v0.18 — null without a frame): the first child of the quadrant, sized to the cells the
852
+ * layer paints, holding the band groups. A band's far segments end at the layer's clip, so a framed grid gives them
853
+ * this clip to stop them at the last painted cell (the band geometry itself is unchanged).
854
+ * 象限の帯の切り抜き (v0.18 — 枠が無ければ null): 象限の最初の子で、層が描くセルの大きさを持ち、帯の組を入れる。帯の遠い側の
855
+ * 片は層の切り抜きで端が切れるため、枠のあるグリッドはこの切り抜きを与えて最後に描くセルで止める (帯の幾何は変えない)。
856
+ */
857
+ bandClip: HTMLDivElement | null
858
+ /** Last-written band-clip size as CSS (`cellsSizeCssOf`; "" = never written). / 帯の切り抜きの直近の書き込みの大きさ (CSS。`cellsSizeCssOf`。"" は未書込)。 */
859
+ bandClipWidth: string
860
+ bandClipHeight: string
861
+ /**
862
+ * Identity-stable compact array of the quad's mounted static chrome below the active frame — the divider segments in
863
+ * slot order, then the frame (≤ 5, DOM order — the `chromeFloorOf` source, v0.9 §2.5 / v0.18).
864
+ * 象限のマウント済みの、アクティブ枠より下の静的クロームの identity 安定な圧縮配列 — スロット順の分割線、続いて外枠 (≤ 5、
865
+ * DOM 順 — `chromeFloorOf` の源、v0.9 §2.5 / v0.18)。
866
+ */
867
+ chrome: HTMLDivElement[]
565
868
  }
566
869
 
567
870
  /**
568
871
  * The canonical "first static chrome child" anchor of a quadrant (v0.9 §2.5 — ADR-24): the
569
- * quad's first mounted divider segment, else the active frame. A structural ordering definition
570
- * with a single source shared by BOTH dynamic insertion anchors (fill pool census #24 / band
571
- * groups census #25) — not a value fallback. A fill or band created AFTER dividers exist must
572
- * still land BELOW them, or the divider's seam absorption breaks.
573
- * 象限の「最初の静的クローム子」正準アンカー (v0.9 §2.5 — ADR-24): マウント済み分割線セグメントの
574
- * 先頭、無ければアクティブ枠。動的挿入アンカー 2 つ (fill プール census #24 / 帯組 census #25) が
575
- * 共有する構造的順序定義の単一源 — 値フォールバックではない。分割線マウント後に生成された fill /
576
- * 帯もその下へ着地しないと、分割線の継ぎ目吸収が破れる。
872
+ * quad's first mounted static chrome node (a divider segment, else the v0.18 frame), else the
873
+ * active frame. A structural ordering definition with a single source shared by BOTH dynamic
874
+ * insertion anchors (fill pool census #24 / band groups census #25) — not a value fallback. A
875
+ * fill or band created AFTER dividers or a frame exist must still land BELOW them, or the
876
+ * divider's seam absorption breaks and the bands tint over the frame.
877
+ * 象限の「最初の静的クローム子」正準アンカー (v0.9 §2.5 — ADR-24): マウント済みの静的クロームの
878
+ * 先頭 (分割線セグメント、無ければ v0.18 の外枠)、無ければアクティブ枠。動的挿入アンカー 2 つ
879
+ * (fill プール census #24 / 帯組 census #25) が共有する構造的順序定義の単一源 — 値フォールバック
880
+ * ではない。分割線か外枠のマウント後に生成された fill / 帯もその下へ着地しないと、分割線の継ぎ目
881
+ * 吸収が破れ、帯が外枠の上を染める。
882
+ */
883
+ const chromeFloorOf = (nodes: LayerNodes): HTMLDivElement | null => nodes.chrome[0] ?? nodes.active
884
+
885
+ /**
886
+ * Rebuilds a quadrant's static chrome array in DOM order — the mounted divider segments in slot order, then the v0.18
887
+ * frame — keeping the array's identity (the `chromeFloorOf` source). Runs only on a mount or unmount of one of them.
888
+ * 象限の静的クロームの配列を DOM の順 (スロット順のマウント済み分割線、続いて v0.18 の外枠) で組み直す。配列の identity は保つ
889
+ * (`chromeFloorOf` の読み先)。走るのはどれかのマウントとアンマウントのときだけ。
577
890
  */
578
- const chromeFloorOf = (nodes: LayerNodes): HTMLDivElement | null => nodes.dividers[0] ?? nodes.active
891
+ const rebuildChrome = (nodes: LayerNodes): void => {
892
+ nodes.chrome.length = 0
893
+ for (const node of nodes.dividerSlots) {
894
+ if (node !== null) {
895
+ nodes.chrome.push(node)
896
+ }
897
+ }
898
+ if (nodes.frame !== null) {
899
+ nodes.chrome.push(nodes.frame.node)
900
+ }
901
+ }
579
902
 
580
903
  /** Inline container geometry of one x-split ("" clears the property). / x 分割 1 本のコンテナインライン形状 ("" はプロパティ解除)。 */
581
904
  type XSplitStyle = { left: string; right: string; width: string }
@@ -596,11 +919,37 @@ type LayerCtx = {
596
919
  xStyle: XSplitStyle
597
920
  xSeamLead: boolean
598
921
  xSeamTrail: boolean
922
+ /** First and last column the layer paints (v0.18 — read by the frame; last < first when it paints none). / 層が描く最初と最後の列 (v0.18 — 外枠が読む。描かなければ last < first)。 */
923
+ xFirst: number
924
+ xLast: number
599
925
  mapY: (treeY: number) => number
600
926
  clampHeight: number
601
927
  yStyle: YSplitStyle
602
928
  ySeamLead: boolean
603
929
  ySeamTrail: boolean
930
+ /** First and last row the layer paints (v0.18). / 層が描く最初と最後の行 (v0.18)。 */
931
+ yFirst: number
932
+ yLast: number
933
+ /**
934
+ * The extents of the cells the layer paints (v0.18): the clamp extents, except that a framed grid limits them to the
935
+ * painted cells (`paintedExtentOf`). They give the marquee's far headroom, so the ants stay inside the frame.
936
+ * 層が描くセルの範囲 (v0.18): クランプ範囲。ただし枠のあるグリッドはセルを描く長さ (`paintedExtentOf`) までにする。マーキーの遠い
937
+ * 側の余白に使い、アンツを枠の内に保つ。
938
+ */
939
+ cells: BandExtents
940
+ /**
941
+ * The CSS of the layer's cells per axis (v0.18), resolved with the cached descriptors from the tracks alone
942
+ * (`layerCellsOf`): the band clip's size (`cellsSizeCssOf`) and the dividers' end inset (`cellsEndCssOf`) — the whole
943
+ * quadrant for a frozen band and in an unframed grid. CSS keeps both up with a resize that repaints nothing, and
944
+ * resolving them once per split geometry keeps a steady scroll frame from building them again.
945
+ * 層の軸ごとのセルの CSS (v0.18)。キャッシュした記述子と一緒に、トラックだけ (`layerCellsOf`) から解く: 帯の切り抜きの大きさ
946
+ * (`cellsSizeCssOf`) と分割線の端の詰め (`cellsEndCssOf`) — 凍結の帯と枠の無いグリッドは象限いっぱい。CSS が何も描き直さない
947
+ * 大きさの変化にも追いつき、分割の幾何ごとに 1 度だけ解くため、定常のスクロールのフレームは作り直さない。
948
+ */
949
+ xCellsSizeCss: string
950
+ yCellsSizeCss: string
951
+ xCellsEndCss: string
952
+ yCellsEndCss: string
604
953
  }
605
954
 
606
955
  /**
@@ -630,6 +979,17 @@ type SplitCache = {
630
979
  trailingVisibleHeight: number
631
980
  bodyWidth: number
632
981
  bodyHeight: number
982
+ /**
983
+ * v0.18 frame keys: whether a frame is drawn and, only while one is, the track counts and tree sizes the painted
984
+ * extents and the frame's track intervals read (-1 without a frame, so an unframed grid rebuilds exactly as before).
985
+ * v0.18 の外枠の鍵: 枠を描くかと、描く間だけ、セルを描く長さと枠のトラックの区間が読むトラックの数と木の大きさ (枠が無ければ
986
+ * -1 で、枠の無いグリッドは今までと同じ時にだけ組み直す)。
987
+ */
988
+ framed: boolean
989
+ rowCount: number
990
+ colCount: number
991
+ rowsTotal: number
992
+ colsTotal: number
633
993
  ctxs: LayerCtx[]
634
994
  }
635
995
 
@@ -652,7 +1012,12 @@ const emptyLayerNodes = (): LayerNodes => ({
652
1012
  bandClampHeight: -1,
653
1013
  dividerSlots: [null, null, null, null],
654
1014
  dividerShown: [false, false, false, false],
655
- dividers: [],
1015
+ dividerEnd: ["0px", "0px", "0px", "0px"],
1016
+ frame: null,
1017
+ bandClip: null,
1018
+ bandClipWidth: "",
1019
+ bandClipHeight: "",
1020
+ chrome: [],
656
1021
  })
657
1022
 
658
1023
  /** All quadrant keys ever rendered — the full {m,f,s,t}² pre-seed (v0.9 §2.5: identity-stable ref-bundle life structure). / 描画され得る全象限キー — {m,f,s,t}² のフル事前シード (v0.9 §2.5: identity 安定な ref 束の生活構造)。 */
@@ -692,12 +1057,17 @@ export const SelectionOverlay = ({
692
1057
  onSinkMouseDown,
693
1058
  editPaintRef,
694
1059
  highlightRef,
1060
+ frameRange,
695
1061
  highlightColors,
696
1062
  popoverAnchors,
697
1063
  interactiveAnchorRef,
698
1064
  tipAnchorRef,
699
1065
  }: SelectionOverlayProps): ReactNode => {
700
1066
  const overlayRef = useRef<HTMLDivElement | null>(null)
1067
+ /** Live frame range read by the write passes (render-time assignment, as the root's highlight ref). / 書込パスが読む外枠の範囲 (root の強調の ref と同じくレンダー時代入)。 */
1068
+ const frameRangeRef = useRef(frameRange)
1069
+ frameRangeRef.current = frameRange
1070
+ const framed = frameRange !== undefined
701
1071
  /** Live fill-preview rect (source ∪ band) for scroll-follow repositioning (§8.2). / 生存中 fill プレビュー矩形 (スクロール追随用)。 */
702
1072
  const liveFillPreviewRef = useRef<CellRange | null>(null)
703
1073
  /** Live resize guideline for scroll-follow repositioning (§7.2). / 生存中ガイドライン (スクロール追随用)。 */
@@ -790,6 +1160,47 @@ export const SelectionOverlay = ({
790
1160
  nodes.dividerShown[slot] = shown
791
1161
  node.style.display = shown ? "" : "none"
792
1162
  }, [])
1163
+ /**
1164
+ * Equality-suppressed size heal of the quadrant's band clip (v0.18): the cells the layer paints, so the band groups
1165
+ * inside it end at the last painted cell. A quadrant without a clip (no frame) writes nothing.
1166
+ * 象限の帯の切り抜きの大きさの等値抑制 heal (v0.18): 層が描くセルの大きさにし、中の帯の組を最後に描くセルで止める。切り抜きの
1167
+ * 無い象限 (枠が無い) は何も書かない。
1168
+ */
1169
+ const healBandClip = useCallback((nodes: LayerNodes, width: string, height: string) => {
1170
+ const clip = nodes.bandClip
1171
+ if (clip === null) {
1172
+ return
1173
+ }
1174
+ if (nodes.bandClipWidth !== width) {
1175
+ nodes.bandClipWidth = width
1176
+ clip.style.width = width
1177
+ }
1178
+ if (nodes.bandClipHeight !== height) {
1179
+ nodes.bandClipHeight = height
1180
+ clip.style.height = height
1181
+ }
1182
+ }, [])
1183
+ /**
1184
+ * Equality-suppressed end heal of one divider slot (v0.18): a framed grid stops its dividers at the last painted
1185
+ * cell, so the vertical slots (0, 1) take `bottom` and the horizontal ones (2, 3) take `right` — the part of the
1186
+ * quadrant past the layer's cells as CSS (`cellsEndCssOf`, resolved with the layer's descriptor), which follows a
1187
+ * resize that repaints nothing. An unframed grid's inset is `0px`, the JSX's end, and writes nothing.
1188
+ * 分割線スロット 1 つの端の等値抑制 heal (v0.18): 枠のあるグリッドは分割線を最後に描くセルで止めるため、縦のスロット (0・1) は
1189
+ * `bottom`、横 (2・3) は `right` に、象限のうち層のセルより先の部分を CSS で書く (`cellsEndCssOf`。層の記述子と一緒に解く)。何も
1190
+ * 描き直さない大きさの変化にも従う。枠の無いグリッドの詰めは JSX の端と同じ `0px` で、何も書かない。
1191
+ */
1192
+ const healDividerEnd = useCallback((nodes: LayerNodes, slot: number, inset: string) => {
1193
+ const node = nodes.dividerSlots[slot]
1194
+ if (node === null || nodes.dividerEnd[slot] === inset) {
1195
+ return
1196
+ }
1197
+ nodes.dividerEnd[slot] = inset
1198
+ if (slot < 2) {
1199
+ node.style.bottom = inset
1200
+ } else {
1201
+ node.style.right = inset
1202
+ }
1203
+ }, [])
793
1204
  /** Live scroll snapshot the cached split maps read (`layersFor` refreshes it on every call). / キャッシュ済み分割写像が読む生スクロール快照 (`layersFor` が毎呼び更新)。 */
794
1205
  const scrollSnapshotRef = useRef({ x: 0, y: 0 })
795
1206
  /** Split-descriptor cache — invalidated by freeze / viewport geometry change, never by scroll. / 分割記述子キャッシュ — 凍結 / viewport 幾何の変化で無効化 (スクロールでは無効化しない)。 */
@@ -815,9 +1226,21 @@ export const SelectionOverlay = ({
815
1226
  const scroll = scrollSnapshotRef.current
816
1227
  scroll.x = hx
817
1228
  scroll.y = vy
1229
+ // 外枠の鍵 (v0.18): 枠のある間だけ、トラックの数と木の大きさを鍵にする。枠の無いグリッドは -1 で、今までと同じ時にだけ組み直す
1230
+ const framed = frameRangeRef.current !== undefined
1231
+ const axes = axesRef.current
1232
+ const rowCount = framed ? axes.rowAxis.count : -1
1233
+ const colCount = framed ? axes.colAxis.count : -1
1234
+ const rowsTotal = framed ? axes.rowAxis.totalSize() : -1
1235
+ const colsTotal = framed ? axes.colAxis.totalSize() : -1
818
1236
  let cache = splitCacheRef.current
819
1237
  if (
820
1238
  cache === null ||
1239
+ cache.framed !== framed ||
1240
+ cache.rowCount !== rowCount ||
1241
+ cache.colCount !== colCount ||
1242
+ cache.rowsTotal !== rowsTotal ||
1243
+ cache.colsTotal !== colsTotal ||
821
1244
  cache.frozenCols !== frozen.cols ||
822
1245
  cache.frozenWidth !== frozen.width ||
823
1246
  cache.frozenRows !== frozen.rows ||
@@ -882,7 +1305,13 @@ export const SelectionOverlay = ({
882
1305
  ]
883
1306
  const ctxs: LayerCtx[] = []
884
1307
  for (const xs of xSplits) {
1308
+ // 枠のあるグリッドだけ、層のセル (帯の切り抜き・分割線の端・マーキーの余白) と枠が読むトラックの区間を持つ (枠が無ければ
1309
+ // セルは層いっぱいで、区間は読まれない)
1310
+ const xCells = framed ? layerCellsOf(xs.kind, colsTotal, frozen.width, frozen.trailingWidth) : null
1311
+ const [xFirst, xLast] = framed ? layerTracksOf(xs.kind, colCount, frozen.cols, frozen.trailingCols) : NO_TRACKS
885
1312
  for (const ys of ySplits) {
1313
+ const yCells = framed ? layerCellsOf(ys.kind, rowsTotal, frozen.height, frozen.trailingHeight) : null
1314
+ const [yFirst, yLast] = framed ? layerTracksOf(ys.kind, rowCount, frozen.rows, frozen.trailingRows) : NO_TRACKS
886
1315
  ctxs.push({
887
1316
  nodes: nodeSetFor(`${xs.kind}${ys.kind}`),
888
1317
  xKind: xs.kind,
@@ -892,11 +1321,20 @@ export const SelectionOverlay = ({
892
1321
  xStyle: xs.style,
893
1322
  xSeamLead: xs.seamLead,
894
1323
  xSeamTrail: xs.seamTrail,
1324
+ xFirst,
1325
+ xLast,
895
1326
  mapY: ys.map,
896
1327
  clampHeight: ys.clamp,
897
1328
  yStyle: ys.style,
898
1329
  ySeamLead: ys.seamLead,
899
1330
  ySeamTrail: ys.seamTrail,
1331
+ yFirst,
1332
+ yLast,
1333
+ cells: { clampWidth: paintedExtentOf(xs.clamp, xCells), clampHeight: paintedExtentOf(ys.clamp, yCells) },
1334
+ xCellsSizeCss: cellsSizeCssOf(xCells),
1335
+ yCellsSizeCss: cellsSizeCssOf(yCells),
1336
+ xCellsEndCss: cellsEndCssOf(xCells),
1337
+ yCellsEndCss: cellsEndCssOf(yCells),
900
1338
  })
901
1339
  }
902
1340
  }
@@ -913,6 +1351,11 @@ export const SelectionOverlay = ({
913
1351
  trailingVisibleHeight: frozen.trailingVisibleHeight,
914
1352
  bodyWidth,
915
1353
  bodyHeight,
1354
+ framed,
1355
+ rowCount,
1356
+ colCount,
1357
+ rowsTotal,
1358
+ colsTotal,
916
1359
  ctxs,
917
1360
  }
918
1361
  splitCacheRef.current = cache
@@ -934,10 +1377,17 @@ export const SelectionOverlay = ({
934
1377
  healDivider(ctx.nodes, 1, showXTrail)
935
1378
  healDivider(ctx.nodes, 2, showYLead)
936
1379
  healDivider(ctx.nodes, 3, showYTrail)
1380
+ // 枠のあるグリッドの分割線は層のセルで止める (縦は下、横は右を詰める。枠が無ければ 0px で書かない)
1381
+ healDividerEnd(ctx.nodes, 0, ctx.yCellsEndCss)
1382
+ healDividerEnd(ctx.nodes, 1, ctx.yCellsEndCss)
1383
+ healDividerEnd(ctx.nodes, 2, ctx.xCellsEndCss)
1384
+ healDividerEnd(ctx.nodes, 3, ctx.xCellsEndCss)
1385
+ // 帯の切り抜きは層のセルの大きさ (枠の無いグリッドには切り抜きが無い)
1386
+ healBandClip(ctx.nodes, ctx.xCellsSizeCss, ctx.yCellsSizeCss)
937
1387
  }
938
1388
  return cache.ctxs
939
1389
  },
940
- [handleRef, nodeSetFor, healContainer, healLayerBands, healDivider],
1390
+ [handleRef, nodeSetFor, healContainer, healLayerBands, healDivider, healDividerEnd, healBandClip],
941
1391
  )
942
1392
  /**
943
1393
  * Stable ref-callback set for one layer (❗ identity-stable via useMemo — a per-render
@@ -959,14 +1409,47 @@ export const SelectionOverlay = ({
959
1409
  */
960
1410
  const setDividerSlot = useCallback((n: LayerNodes, slot: number, el: HTMLDivElement | null) => {
961
1411
  n.dividerSlots[slot] = el
962
- // JSX 初期 display は "none" — 等値抑制キャッシュを初期値へ同期 (空砲抑制の防止)
1412
+ // JSX 初期 display は "none"、端は 0 — 等値抑制キャッシュを初期値へ同期 (空砲抑制の防止)
963
1413
  n.dividerShown[slot] = false
964
- // 圧縮配列は identity を保ったまま中身だけ再構成 (chromeFloorOf の読み先)
965
- n.dividers.length = 0
966
- for (const node of n.dividerSlots) {
967
- if (node !== null) {
968
- n.dividers.push(node)
969
- }
1414
+ n.dividerEnd[slot] = "0px"
1415
+ rebuildChrome(n)
1416
+ }, [])
1417
+ /**
1418
+ * Registers the quadrant's frame node (v0.18) with an empty write cache and rebuilds the static chrome array. Runs
1419
+ * only when the frame mounts or unmounts — never per frame.
1420
+ * 象限の外枠のノードを空の書き込みキャッシュで登録し、静的クロームの配列を組み直す (v0.18)。走るのは枠のマウントとアンマウント
1421
+ * のときだけで、毎フレームでは走らない。
1422
+ */
1423
+ const setFrameSlot = useCallback((n: LayerNodes, el: HTMLDivElement | null) => {
1424
+ n.frame = el === null ? null : { node: el, x: unresolvedSpanOf(), y: unresolvedSpanOf(), drawnX: unresolvedSpanOf(), drawnY: unresolvedSpanOf(), last: { shown: false, left: "", top: "", right: "", bottom: "", width: "", height: "", open: -1 } }
1425
+ rebuildChrome(n)
1426
+ }, [])
1427
+ /**
1428
+ * Registers the quadrant's band clip (v0.18) and retires the quadrant's band groups, which the next repaint creates
1429
+ * again inside the clip (on mount) or the quadrant (on unmount — React removed the clip with the groups in it). On
1430
+ * mount the clip moves to the quadrant's front: React inserts it before its next JSX sibling, above any fill already
1431
+ * inserted there, while the bands must stay below the fills.
1432
+ * 象限の帯の切り抜きを登録し (v0.18)、象限の帯の組を退役させる。次の repaint が組を切り抜きの中 (マウント) か象限 (アンマウント
1433
+ * — React が組ごと切り抜きを外した) に作り直す。マウントでは切り抜きを象限の先頭へ動かす: React は次の JSX の兄弟の前へ入れるため、
1434
+ * そこに既にある fill より上になるが、帯は fill より下でなければならない。
1435
+ */
1436
+ const setBandClip = useCallback((n: LayerNodes, el: HTMLDivElement | null) => {
1437
+ for (const group of n.bandPool) {
1438
+ removeBandNodes(group)
1439
+ }
1440
+ n.bandPool.length = 0
1441
+ if (n.dragBand !== null) {
1442
+ removeBandNodes(n.dragBand)
1443
+ n.dragBand = null
1444
+ }
1445
+ n.bandClampWidth = -1
1446
+ n.bandClampHeight = -1
1447
+ n.bandClip = el
1448
+ n.bandClipWidth = ""
1449
+ n.bandClipHeight = ""
1450
+ const quad = el === null ? null : el.parentElement
1451
+ if (el !== null && quad !== null && quad.firstChild !== el) {
1452
+ quad.insertBefore(el, quad.firstChild)
970
1453
  }
971
1454
  }, [])
972
1455
  const makeLayerRefs = useCallback(
@@ -991,6 +1474,9 @@ export const SelectionOverlay = ({
991
1474
  dividerXTrailing: (el: HTMLDivElement | null) => setDividerSlot(nodes(), 1, el),
992
1475
  dividerYLeading: (el: HTMLDivElement | null) => setDividerSlot(nodes(), 2, el),
993
1476
  dividerYTrailing: (el: HTMLDivElement | null) => setDividerSlot(nodes(), 3, el),
1477
+ // 外枠と帯の切り抜き (v0.18 — 存在は枠の有無の JSX 分岐、React が mount / unmount で装着・解除する)
1478
+ frame: (el: HTMLDivElement | null) => setFrameSlot(nodes(), el),
1479
+ bandClip: (el: HTMLDivElement | null) => setBandClip(nodes(), el),
994
1480
  active: (el: HTMLDivElement | null) => {
995
1481
  nodes().active = el
996
1482
  },
@@ -1008,7 +1494,7 @@ export const SelectionOverlay = ({
1008
1494
  },
1009
1495
  }
1010
1496
  },
1011
- [nodeSetFor, setDividerSlot],
1497
+ [nodeSetFor, setDividerSlot, setFrameSlot, setBandClip],
1012
1498
  )
1013
1499
  // 象限キーごとに identity 安定な ref 束を用意 (空 deps — 毎レンダー生成だと React が detach /
1014
1500
  // attach してプールが空になり塗りが二重化する)。JSX は実効 F / R に応じて必要な象限だけ描く
@@ -1119,12 +1605,118 @@ export const SelectionOverlay = ({
1119
1605
 
1120
1606
  /** Inserts a band group under the layer's fills (before the first fill, else before the chrome floor — v0.9 §2.5 census #25: the old `nodes.active` anchor could not land a band group below a mounted divider). / 帯組を層の fill の下へ挿入 (先頭 fill の手前、無ければ静的クローム床の手前 — v0.9 §2.5 census #25: 旧 `nodes.active` 直指しではマウント済み分割線の下へ帯組を入れられない)。 */
1121
1607
  const insertBandGroup = useCallback((container: HTMLDivElement, nodes: LayerNodes, group: BandNodes) => {
1608
+ // 枠のあるグリッド (v0.18) は帯を象限の先頭の帯の切り抜きへ入れ、最後に描くセルで切る (切り抜きは fill より下)
1609
+ if (nodes.bandClip !== null) {
1610
+ for (const node of bandNodeList(group)) {
1611
+ nodes.bandClip.appendChild(node)
1612
+ }
1613
+ return
1614
+ }
1122
1615
  const before = nodes.fillPool[0]?.node ?? chromeFloorOf(nodes)
1123
1616
  for (const node of bandNodeList(group)) {
1124
1617
  container.insertBefore(node, before)
1125
1618
  }
1126
1619
  }, [])
1127
1620
 
1621
+ /**
1622
+ * The frame range cut to the grid (`frameRangeWithin`), resolved again only when the range or the grid's counts
1623
+ * change, so a repaint pass reads it without allocating.
1624
+ * グリッドへ切った外枠の範囲 (`frameRangeWithin`)。範囲かグリッドの数が変わったときだけ解き直し、描き直しのパスは確保なしに読む。
1625
+ */
1626
+ const frameWithinRef = useRef<{ range: CellRange | undefined; rows: number; cols: number; within: CellRange | null }>({ range: undefined, rows: -1, cols: -1, within: null })
1627
+ /**
1628
+ * Places one quadrant's frame (v0.18): the part of the frame range the layer paints (`frameSpanInto` on both axes,
1629
+ * the range first cut to the grid by `frameRangeWithin`), with the sides the range continues past marked open
1630
+ * (`data-aqsp-frame-open`), hidden when the layer paints none of it, placed by insets (`frameAxisCssOf`) so its open
1631
+ * far sides follow the quadrant's size. The spans resolve into the slot's own spans and the CSS is built only when
1632
+ * they differ from the spans last placed, so a repaint that moves nothing allocates nothing; every write is
1633
+ * same-value suppressed besides (the fill slot's census #23 discipline): a steady scroll frame writes at most the
1634
+ * insets of the scrolled axis — the frame is one leaf node per quadrant, so the layout an inset costs is negligible
1635
+ * next to keeping the open sides right without a repaint.
1636
+ * 象限 1 つの外枠を置く (v0.18): 範囲 (先に `frameRangeWithin` でグリッドへ切る) のうち層が描く部分 (両軸の `frameSpanInto`) を
1637
+ * 囲み、範囲が先へ続く辺は開く (`data-aqsp-frame-open`)。層が範囲のどこも描かなければ隠す。詰め (`frameAxisCssOf`) で置き、開いた
1638
+ * 遠い辺は象限の大きさに従う。軸の範囲はスロット自身の範囲へ解き、最後に置いた範囲と違うときだけ CSS を作るため、何も動かさない
1639
+ * 描き直しは何も確保しない。そのうえ書き込みはどれも同値抑止 (fill のスロットの census #23 の規律) で、定常のスクロールのフレームが
1640
+ * 書くのはスクロールした軸の詰めまで — 外枠は象限に 1 つの葉のノードで、詰めが起こす配置の手間は、描き直さずに開いた辺を正しく
1641
+ * 保つことに比べて小さい。
1642
+ */
1643
+ const placeFrame = useCallback(
1644
+ (ctx: LayerCtx) => {
1645
+ const slot = ctx.nodes.frame
1646
+ if (slot === null) {
1647
+ return
1648
+ }
1649
+ const cut = frameWithinRef.current
1650
+ const range = frameRangeRef.current
1651
+ if (cut.range !== range || cut.rows !== rowAxis.count || cut.cols !== colAxis.count) {
1652
+ cut.range = range
1653
+ cut.rows = rowAxis.count
1654
+ cut.cols = colAxis.count
1655
+ cut.within = range === undefined ? null : frameRangeWithin(range, rowAxis.count, colAxis.count)
1656
+ }
1657
+ const within = cut.within
1658
+ const last = slot.last
1659
+ const style = slot.node.style
1660
+ const framed =
1661
+ within !== null &&
1662
+ frameSpanInto(slot.x, within.startCol, within.endCol, ctx.xFirst, ctx.xLast, ctx.mapX(colAxis.offsetOf(within.startCol)), ctx.mapX(colAxis.offsetOf(within.endCol) + colAxis.sizeOf(within.endCol)), ctx.clampWidth) &&
1663
+ frameSpanInto(slot.y, within.startRow, within.endRow, ctx.yFirst, ctx.yLast, ctx.mapY(rowAxis.offsetOf(within.startRow)), ctx.mapY(rowAxis.offsetOf(within.endRow) + rowAxis.sizeOf(within.endRow)), ctx.clampHeight)
1664
+ if (!framed) {
1665
+ if (last.shown) {
1666
+ last.shown = false
1667
+ style.display = "none"
1668
+ }
1669
+ return
1670
+ }
1671
+ if (!last.shown) {
1672
+ last.shown = true
1673
+ style.display = "block"
1674
+ }
1675
+ if (!sameSpan(slot.x, slot.drawnX)) {
1676
+ copySpan(slot.drawnX, slot.x)
1677
+ const horizontal = frameAxisCssOf(slot.x)
1678
+ if (horizontal.start !== last.left) {
1679
+ last.left = horizontal.start
1680
+ style.left = horizontal.start
1681
+ }
1682
+ if (horizontal.end !== last.right) {
1683
+ last.right = horizontal.end
1684
+ style.right = horizontal.end
1685
+ }
1686
+ if (horizontal.size !== last.width) {
1687
+ last.width = horizontal.size
1688
+ style.width = horizontal.size
1689
+ }
1690
+ }
1691
+ if (!sameSpan(slot.y, slot.drawnY)) {
1692
+ copySpan(slot.drawnY, slot.y)
1693
+ const vertical = frameAxisCssOf(slot.y)
1694
+ if (vertical.start !== last.top) {
1695
+ last.top = vertical.start
1696
+ style.top = vertical.start
1697
+ }
1698
+ if (vertical.end !== last.bottom) {
1699
+ last.bottom = vertical.end
1700
+ style.bottom = vertical.end
1701
+ }
1702
+ if (vertical.size !== last.height) {
1703
+ last.height = vertical.size
1704
+ style.height = vertical.size
1705
+ }
1706
+ }
1707
+ const open = frameOpenMaskOf(slot.x, slot.y)
1708
+ if (open !== last.open) {
1709
+ last.open = open
1710
+ if (open === 0) {
1711
+ slot.node.removeAttribute("data-aqsp-frame-open")
1712
+ } else {
1713
+ slot.node.setAttribute("data-aqsp-frame-open", frameOpenSidesOf(open))
1714
+ }
1715
+ }
1716
+ },
1717
+ [rowAxis, colAxis],
1718
+ )
1719
+
1128
1720
  /** Places one band group for a range in a layer (hidden when the quadrant has no extent). / 層内のレンジ 1 つに帯組を配置 (象限に範囲が無ければ消灯)。 */
1129
1721
  const placeBandGroup = useCallback(
1130
1722
  (group: BandNodes, range: CellRange, ctx: LayerCtx, highlight: HighlightState) => {
@@ -1422,7 +2014,7 @@ export const SelectionOverlay = ({
1422
2014
  node.setAttribute("data-aqsp-fill", "")
1423
2015
  // 生成時のみ display を初期化 — 以後は同値キャッシュが管理 (v0.9 §2.5 census #23)
1424
2016
  node.style.display = "none"
1425
- // 静的クローム床 (分割線先頭 or アクティブ枠 — chromeFloorOf) の手前へ挿入
2017
+ // 静的クローム床 (分割線か外枠の先頭、無ければアクティブ枠 — chromeFloorOf) の手前へ挿入
1426
2018
  // (v0.9 §2.5 census #24: 分割線マウント後に生成された fill が分割線の上へ来る
1427
2019
  // 継ぎ目吸収の破れを塞ぐ)。append だと DOM 順でシンクより上に描かれ、Phase 3 の
1428
2020
  // セル面積エディタが半透明 fill の下に沈む (従来規律は不変)
@@ -1469,6 +2061,9 @@ export const SelectionOverlay = ({
1469
2061
  // アクティブセル枠 (常設ノードは ref 直読み — dragRect と同じ規律)
1470
2062
  applyRect(ctx.nodes.active, rangeToLayerRect(makeRange(state.active, state.active), ctx))
1471
2063
 
2064
+ // 外枠 (v0.18): 層が描くトラックの部分を囲み、範囲が先へ続く辺は開く。枠の無いグリッドはノードが無く何も書かない
2065
+ placeFrame(ctx)
2066
+
1472
2067
  // 強調帯 (v0.8 §2.4): 末尾 BAND_RANGE_CAP レンジに 5 ノードずつ、fill の下。全 off は
1473
2068
  // プール縮退 (ノード除去) で帯 0 = v0.7 恒等
1474
2069
  syncLayerBands(ctx, container, bandRanges, highlight)
@@ -1522,8 +2117,10 @@ export const SelectionOverlay = ({
1522
2117
  // ctx.clampHeight へ。凍結行帯のマーキー帯が帯下限で正しく切られる。横は従来どおり)
1523
2118
  const outTop = clipMarqueeOutset(rect.top)
1524
2119
  const outLeft = clipMarqueeOutset(rect.left)
1525
- const outBottom = clipMarqueeOutset(ctx.clampHeight - (rect.top + rect.height))
1526
- const outRight = clipMarqueeOutset(ctx.clampWidth - (rect.left + rect.width))
2120
+ // 下と右の余白は層が描くセルの端まで (v0.18: 枠のあるグリッドでは表の端で、上と左と同じくアンツを枠の外へ出さない。
2121
+ // 枠の無いグリッドではクランプ範囲と同じ)
2122
+ const outBottom = clipMarqueeOutset(ctx.cells.clampHeight - (rect.top + rect.height))
2123
+ const outRight = clipMarqueeOutset(ctx.cells.clampWidth - (rect.left + rect.width))
1527
2124
  const signature = `${outTop} ${outRight} ${outBottom} ${outLeft}`
1528
2125
  if (signature !== marquee.dataset.aqspOutsetSig) {
1529
2126
  marquee.dataset.aqspOutsetSig = signature
@@ -1688,6 +2285,7 @@ export const SelectionOverlay = ({
1688
2285
  colAxis,
1689
2286
  activeHighlight,
1690
2287
  syncLayerBands,
2288
+ placeFrame,
1691
2289
  editPaintRef,
1692
2290
  placePopoverAnchors,
1693
2291
  ])
@@ -1876,6 +2474,8 @@ export const SelectionOverlay = ({
1876
2474
  const refs = quadRefs[key]
1877
2475
  return (
1878
2476
  <div key={key} className="aqsp-overlay-quad" data-aqsp-overlay-quad={key} {...legacyAttr(key)} style={style} ref={refs.container}>
2477
+ {/* 帯の切り抜き (v0.18): 枠のある象限の最初の子で、層が描くセルの大きさ。帯の組はこの中に入り、fill より下で、表の外へ出ない */}
2478
+ {framed ? <div className="aqsp-band-clip" data-aqsp-band-clip="" ref={refs.bandClip} /> : null}
1879
2479
  {/* 分割線セグメント (v0.9 §2.4 — ADR-24 挿入のみ): scroll 種象限の子に限定
1880
2480
  (構造強制 — 中央帯外に分割線画素が存在できず、overlap 縮退では象限クリップ
1881
2481
  ごと消える)。位置は activeFrame の直前 = 実行時挿入の fill / 帯の後 ⇒
@@ -1890,6 +2490,9 @@ export const SelectionOverlay = ({
1890
2490
  {xk === "s" && effectiveTrailingCols > 0 ? <div className="aqsp-freeze-divider aqsp-freeze-divider-v" data-aqsp-freeze-divider="x-trailing" style={{ right: 0, top: 0, bottom: 0, display: "none" }} ref={refs.dividerXTrailing} /> : null}
1891
2491
  {yk === "s" && effectiveFrozenRows > 0 ? <div className="aqsp-freeze-divider aqsp-freeze-divider-h" data-aqsp-freeze-divider="y-leading" style={{ top: 0, left: 0, right: 0, display: "none" }} ref={refs.dividerYLeading} /> : null}
1892
2492
  {yk === "s" && effectiveTrailingRows > 0 ? <div className="aqsp-freeze-divider aqsp-freeze-divider-h" data-aqsp-freeze-divider="y-trailing" style={{ bottom: 0, left: 0, right: 0, display: "none" }} ref={refs.dividerYTrailing} /> : null}
2493
+ {/* 外枠 (v0.18): 分割線の後・アクティブ枠の前 ⇒ 帯 < fill < 分割線 < 外枠 < activeFrame。分割線と帯の端を覆い、
2494
+ 焦点の印に覆われない。どの象限も同じ枠を自分の写像で描き、象限のクリップが分けて継ぎ目の無い 1 つの枠にする */}
2495
+ {framed ? <div className="aqsp-frame" data-aqsp-frame="" style={{ display: "none" }} ref={refs.frame} /> : null}
1893
2496
  <div className="aqsp-active-frame" data-aqsp-active="" style={{ display: "none" }} ref={refs.active} />
1894
2497
  <div className="aqsp-drag-rect" data-aqsp-drag-rect="" style={{ display: "none" }} ref={refs.dragRect} />
1895
2498
  <div className="aqsp-clip-marquee" data-aqsp-clip-marquee="" style={{ display: "none" }} ref={refs.marquee} />