@aiquants/spreadsheet 0.9.0 → 0.11.0

package/src/grid/GridBody.tsx

@@ -23,6 +23,11 @@
  * engine-validated pass-throughs onto VirtualGrid's `frozenTrailingCols` / `frozenTrailingRows`
  * — validation SSOT is the engine's fail-fast contract, no second layer here (§1.1).
  *
+ * v0.10 read-only cells (plan §6.5, S1): `getCellProps` conditionally stamps painted read-only
+ * cells with `aria-readonly="true"` + `data-aqsp-readonly=""` through the `isReadOnlyCell`
+ * helper (ADR-31 — no package CSS; capability absent ⇒ O(1) false ⇒ keys absent ⇒ the DOM
+ * stays byte-identical).
+ *
  * グリッド本体。VirtualGrid 結線 (両軸) とセルレンダラーを所有する。v0.4 から横軸は VirtualGrid
  * の所有 (量子化列アンカー + 残差 transform + 横バー) — v0.3 の列スタック (useColumnWindow /
  * --aqsp-hx CSS 変数 / 軸原点絶対 left / 自前 HScrollBar) は設計計画 §7-1 に従い削除。
@@ -41,16 +46,20 @@
  * v0.9 末尾凍結 (計画 §4.15): `frozenTrailingColumns` / `frozenTrailingRows` は VirtualGrid の
  * `frozenTrailingCols` / `frozenTrailingRows` へのエンジン検証素通し — 検証 SSOT はエンジンの
  * fail-fast 契約で、ここに第二検証層は置かない (§1.1)。
+ *
+ * v0.10 読み取り専用セル (計画 §6.5、S1): `getCellProps` が塗られた読み取り専用セルへ
+ * `aria-readonly="true"` + `data-aqsp-readonly=""` を `isReadOnlyCell` ヘルパ経由で条件スタンプ
+ * する (ADR-31 — パッケージ CSS なし。能力未宣言 = O(1) false = キー不在 = DOM バイト同一)。
  */
 
-import { VirtualGrid, type VirtualGridHandle, type VirtualGridRange } from "@aiquants/virtualscroll"
+import { type ScrollBarTapCircleOptions, VirtualGrid, type VirtualGridHandle, type VirtualGridRange } from "@aiquants/virtualscroll"
 import { type HTMLAttributes, memo, type ProfilerOnRenderCallback, type ReactNode, type RefObject, useCallback, useMemo, useRef, useSyncExternalStore } from "react"
 import { type AxisModel, nextVisibleIndex } from "../model/axisModel.ts"
 import { normalizeAdapterHyperlink } from "../model/cellAnnotations.ts"
 import { alignToJustify, type CellAlign, type CellValueFormat, formatCellValue } from "../model/cellFormat.ts"
 import { type CellPaint, resolveCellPaint } from "../model/cellPaint.ts"
 import { type CfIndex, type CfMemo, createCfMemo, resolvePaintedFormat } from "../model/conditionalFormat.ts"
-import { lazyCellText, resolveCellAlign, type SpreadsheetDataAdapter } from "../model/dataAdapter.ts"
+import { isReadOnlyCell, lazyCellText, resolveCellAlign, type SpreadsheetDataAdapter } from "../model/dataAdapter.ts"
 import { isVisiblyInvalid } from "../model/dataValidation.ts"
 import { SCROLLBAR_WIDTH, type ViewStore } from "../model/viewStore.ts"
 import { CellView, type RenderCellContext } from "./CellView.tsx"
@@ -299,6 +308,32 @@ type GridBodyProps = {
      * 焦点回収 — §4.2.11)。未指定 ⇒ v0.7 のゲート。
      */
     isPointing?: () => boolean
+    /**
+     * Tap-scroll circle tuning (v0.10 — the engine `scrollBarOptions.tapScrollCircleOptions`
+     * engine-validated pass-through; the engine's `resolveTapScrollCircleOptions` is the
+     * validation SSOT). Undefined rides the memo as an explicit key = the engine's declared
+     * absence signal (engine defaults), never a value fallback here.
+     * タップサークル調整 (v0.10 — エンジン `scrollBarOptions.tapScrollCircleOptions` の
+     * エンジン検証素通し。検証の SSOT はエンジンの `resolveTapScrollCircleOptions`)。undefined は
+     * キー同乗のままエンジン宣言の不在信号 (エンジン既定) — この層での値フォールバックなし。
+     */
+    tapScrollCircleOptions?: ScrollBarTapCircleOptions
+    /**
+     * Row-axis overscan (the engine `overscanRows` pass-through; the Spreadsheet surface owns
+     * the fail-fast validation — the engine clamps silently). Undefined ⇒ engine default (3).
+     * 行軸 overscan (エンジン `overscanRows` の素通し。fail-fast 検証は Spreadsheet 面所有 —
+     * エンジンは無言クランプ)。undefined ⇒ エンジン既定 (3)。
+     */
+    overscanRows?: number
+    /** Column-axis overscan — the column twin of `overscanRows`, same contract. / 列軸 overscan — `overscanRows` の列双子 (同契約)。 */
+    overscanCols?: number
+    /**
+     * Background layer behind the scroll-band rows (the engine `background` pass-through;
+     * viewport-pinned — the engine translates only its row wrapper).
+     * スクロール帯行背後の背景レイヤー (エンジン `background` の素通し。viewport 固定 —
+     * エンジンが translate するのは行ラッパーのみ)。
+     */
+    background?: ReactNode
 }
 
 /**
@@ -328,6 +363,10 @@ const GridBodyInner = ({
     cfIndexRef,
     cfMemoRef,
     isPointing,
+    tapScrollCircleOptions,
+    overscanRows,
+    overscanCols,
+    background,
 }: GridBodyProps): ReactNode => {
     const internalBodyRef = useRef<HTMLDivElement | null>(null)
     // 外部 ref (エンジン結線用) と内部 ref の合成
@@ -357,7 +396,8 @@ const GridBodyInner = ({
     // (§7-8 — サンプリング省略の Fenwick baseValue)。pointerDragInputs はペン / タッチのみ
     // (マウスドラッグは選択エンジンの所有)
     const behaviorOptions = useMemo(() => ({ enableKeyboardNavigation: false, pointerDragInputs: ["pen", "touch"] as const, resetOnGetItemHeightChange: true, resetOnGetColWidthChange: true, defaultColWidth: defaultColumnWidth }), [defaultColumnWidth])
-    const scrollBarOptions = useMemo(() => ({ width: SCROLLBAR_WIDTH }), [])
+    // タップサークル素通し (v0.10 §2.1): 未指定は undefined キー同乗 = エンジン宣言の不在信号
+    const scrollBarOptions = useMemo(() => ({ width: SCROLLBAR_WIDTH, tapScrollCircleOptions }), [tapScrollCircleOptions])
     // 表示値書式の掛け金 (getCellProps が書き、同じセルの children が直後に消費 — 番兵は届かない座標)
     const displayLatchRef = useRef<DisplayLatch>({ row: -1, col: -1, value: undefined })
     /**
@@ -381,6 +421,11 @@ const GridBodyInner = ({
                 "data-row": row,
                 "data-col": col,
                 className: "aqsp-cell",
+                // S1 (v0.10 §6.5 / 設計 ADR-31): 読み取り専用スタンプ — 閲覧モード / a11y ツリー用の
+                // aria-readonly と data-* フック (パッケージ CSS なし)。ヘルパ経由が規範 (member 名の
+                // 単一居住 — layer-2 census)。未宣言 = O(1) false = キー不在 = v0.9 と DOM バイト同一、
+                // 宣言ホストは塗りセル毎 1 述語読み (ADR-31 の登記コスト)
+                ...(isReadOnlyCell(adapter, row, col) ? { "aria-readonly": "true", "data-aqsp-readonly": "" } : {}),
             }
             const rich = resolveRichCellProps(adapter, rowAxis, colAxis, cf, row, col)
             // 掛け金は毎セル更新 (v0.1 恒等の null でも座標を進める — children が消費するのは書式能力下だけ)
@@ -491,6 +536,9 @@ const GridBodyInner = ({
                 contentProps={contentProps}
                 behaviorOptions={behaviorOptions}
                 scrollBarOptions={scrollBarOptions}
+                overscanRows={overscanRows}
+                overscanCols={overscanCols}
+                background={background}
                 callbackThrottleMs={0}
                 onScroll={onScroll}
                 onRangeChange={onRangeChange}

package/src/index.ts

@@ -36,6 +36,10 @@
  * (分冊 00 §5.2)。
  */
 
+// 統合タップサークル (エンジン v3.6.0 — ADR-33 縮小形): tapScrollCircleOptions prop (v0.10 H2) と
+// renderVisual をエンジン直接依存なしで型付ける型のみ再 export。値面 (tapScrollCircleSampleVisual) は
+// 意図的に非再 export — エンジン所有のまま
+export type { ScrollBarTapCircleOptions, TapScrollCircleRenderProps } from "@aiquants/virtualscroll"
 export { type ClipCell, type ClipChannel, type ClipComment, type ClipFlavours, type ClipPayload, type ClipSource, detectClipSource, parseClipPayload, serializeClipPayload } from "./clipboard/clipPayload.ts"
 export { type HtmlTableKind, type HtmlTableResult, parseHtmlTable, serializeHtmlTable } from "./clipboard/htmlInterop.ts"
 // parseHtmlTable の第 3 引数型 — 復号器のホスト宣言 (codec 本体は非公開のまま、引数型だけ名指しできるようにする)
@@ -87,7 +91,7 @@ export type {
     ScalePoint,
     TextCondition,
 } from "./model/conditionalFormat.ts"
-export type { CellEdit, CellPatch, EditContext, EditRejection, EditSource, PasteEditContext, PlainEditContext, SpreadsheetDataAdapter } from "./model/dataAdapter.ts"
+export type { CellEdit, CellPatch, EditContext, EditRejection, EditSource, PasteEditContext, PlainEditContext, ReadOnlyRejection, SpreadsheetDataAdapter } from "./model/dataAdapter.ts"
 // データ検証の語彙 — 規則 union / 判定に加え、共通オプション・7 つの腕・op 語彙・validateCellText の評価器型も名指しできる
 export {
     type CheckboxValidationRule,

package/src/keyboard/useGridKeyboard.ts

@@ -29,7 +29,9 @@
  * Latin letter, else the physical `Key*` code), so they fire on non-Latin layouts (RU / EL …)
  * exactly like Excel / Sheets and like every command row; on Latin layouts the match is
  * identical to the produced-character test. Every addition is a capability param — absent =
- * the v0.7 keymap.
+ * the v0.7 keymap. v0.10 read-only cells (design §4.1, via the required `rejectReadOnly`
+ * funnel): G3 refuses the whole Delete / Backspace when the selection contains a read-only
+ * cell — after the limit gate, before enumeration; an undeclared capability is byte-identical.
  *
  * シンク keydown 上のキーマップ実装 (§6.6.1 の契約表 — idle 列。編集列は Phase 3 の編集
  * セッションへ委譲)。v0.2 で findDataEdge ナビゲーション + ディスパッチ前 fail-fast 検証 (§2)・
@@ -54,7 +56,9 @@
  * Ctrl+Z / Ctrl+Shift+Z / Ctrl+Y / Ctrl+Shift+V) は表と同じ VK 規則 (`matchChord` — 生成文字がラテン
  * 文字ならその文字、非ラテンは物理 `Key*` code) で照合し、非ラテン配列 (RU / EL …) でも Excel /
  * Sheets やコマンド行と同じく成立する (ラテン配列では生成文字照合と同一)。追加は全て能力 param —
- * 不在 = v0.7 キーマップ。
+ * 不在 = v0.7 キーマップ。v0.10 読み取り専用セル (設計 §4.1、必須 `rejectReadOnly` 漏斗経由):
+ * G3 は選択に読み取り専用セルを含む Delete / Backspace を全体拒否する — 限度ゲート後・列挙前。
+ * 能力未宣言はバイト恒等。
  */
 
 import type { VirtualGridHandle } from "@aiquants/virtualscroll"
@@ -63,7 +67,7 @@ import type { PasteOptions } from "../clipboard/pasteSpecial.ts"
 import type { PointingSeams } from "../editor/useCellEditor.ts"
 import { type AxisModel, nextVisibleIndex } from "../model/axisModel.ts"
 import { type CellCoord, type CellRange, countRangeCells, enumerateRangeCells, makeRange, type SpreadsheetDirection, type SpreadsheetOperation } from "../model/cellCoord.ts"
-import { aspectCapabilities, type CellEdit, type EditRejection, type SpreadsheetDataAdapter } from "../model/dataAdapter.ts"
+import { aspectCapabilities, type CellEdit, type EditRejection, type ReadOnlyRejection, rangesContainReadOnly, type SpreadsheetDataAdapter } from "../model/dataAdapter.ts"
 import { colToViewportX, rowToViewportY } from "../model/frozenPartition.ts"
 import { reduceActiveCycle, type SelectionState } from "../selection/selectionState.ts"
 import { COMPOSITION_CLEAR_MS, isCompositionKeydown } from "./compositionGuard.ts"
@@ -155,6 +159,17 @@ type UseGridKeyboardParams = {
     pendingPasteOptionsRef?: RefObject<PasteOptions | null>
     /** v0.8 capability (§2.7): the keyboard-pointing reference-rect writer — paints the pointed cell / range on the overlay's resident drag-rect node with the fixed "point" mode (the same node the reference drag paints; null hides it). Undefined = no rect (the pointing rows rewrite the reference only). / v0.8 能力 (§2.7): キーボードポインティングの参照矩形 writer — 指し先セル / レンジを overlay の常設ドラッグ矩形ノードへ固定 "point" モードで描く (参照ドラッグと同一ノード。null は消灯)。undefined = 矩形なし (ポインティング行は参照書換のみ)。 */
     onPointFrame?: (range: CellRange | null) => void
+    /**
+     * v0.10 read-only refusal funnel (required seam — the root always wires it; identity-stable,
+     * read through paramsRef): G3 (the Delete / Backspace whole-refusal when the selection
+     * contains a read-only cell, `{op:"delete"}`) fires it once per refused keystroke with the
+     * limit channel's own overlap-naive count. Capability absent ⇒ never called (byte identity).
+     * v0.10 読み取り専用拒否漏斗 (必須 seam — root が常に渡す。identity 安定、paramsRef 読み):
+     * G3 (選択に読み取り専用セルを含む Delete / Backspace の全体拒否 — `{op:"delete"}`) が拒否
+     * キーストローク毎 1 回、限度チャネルと同じ overlap-naive の数で発火する。能力未宣言なら
+     * 一度も呼ばれない (バイト恒等)。
+     */
+    rejectReadOnly: (rejection: ReadOnlyRejection) => void
 }
 
 /**
@@ -691,6 +706,12 @@ export const useGridKeyboard = (params: UseGridKeyboardParams): void => {
                     p.onOperationRejected?.("delete", count, "limit")
                     return
                 }
+                // G3 (v0.10 設計 §4.1): 限度ゲート通過後・enumerateRangeCells 前の読み取り専用 walk —
+                // 混在選択は全体拒否 (消費形は限度拒否と同一、cellCount は既計算の overlap-naive 値を再利用)
+                if (p.adapter !== undefined && rangesContainReadOnly(p.adapter, state.ranges)) {
+                    p.rejectReadOnly({ kind: "operation", op: "delete", cellCount: count })
+                    return
+                }
                 const edits: CellEdit[] = []
                 // Delete はパッチ (v0.8 §4.2.7): text を消し、getCellHyperlink 宣言時だけ hyperlink も消す
                 // (Excel: 内容の削除はリンクも外す)。未宣言側面のキーは出さない — 能力分岐 (adapter 未配線 = text のみ)

package/src/model/dataAdapter.ts

@@ -10,8 +10,12 @@
  * PAINTED format = base ⊕ conditional formats), lazyCellText (the once-only text thunk = the
  * eighth read of a cell), resolveEditText (the editor seed — formula source or canonical text,
  * fail-fast on a formula that does not start with "=") and aspectCapabilities (the write gate's
- * single reader of the declared aspects). Every capability is a DECLARATION: absence is a code
- * branch that reproduces the v0.7 behaviour exactly, never a value fallback.
+ * single reader of the declared aspects). v0.10 adds the 11th optional member `isCellReadOnly`
+ * (a NON-aspect capability), the refusal context `ReadOnlyRejection` and the read-only helper
+ * quartet (readOnlyDeclared / isReadOnlyCell / rangesContainReadOnly / rectContainsReadOnly) —
+ * the ONLY production module where the member name appears (layer-2 census, ADR-27). Every
+ * capability is a DECLARATION: absence is a code branch that reproduces the previous behaviour
+ * exactly, never a value fallback.
  * グリッドと consumer の唯一のデータ境界 (v0.8 — ADR-13 リッチセル / ADR-16 書込語彙): 8 つの
  * 任意リッチセル能力読みを持つアダプタ型、グリッドが書くセル単位パッチ (CellPatch / CellEdit —
  * 未指定キーは「触らない」、`null` は「消す」)、全 applyEdits が受け取る判別可能な書込文脈
@@ -158,6 +162,41 @@ void plainContextNeverPaste
 // 混入いずれも即赤)
 export type EditRejection = { source: "edit"; editSession: "kept" | "discarded" } | { source: "paste" | "fill" | "delete" | "format" | "calc" | "annotate" }
 
+/**
+ * Context of a READ-ONLY refusal (v0.10, delivered by onReadOnlyRejected): fired once per
+ * refused gesture — the adapter was never called, so this is neither an {@link EditRejection}
+ * (applyEdits never threw) nor an operation limit. `kind: "edit"` is a refused single-cell
+ * text-write entry or commit and carries the cell; `kind: "operation"` is a refused whole
+ * operation with its producer's own overlap-naive `cellCount` arithmetic (the same numbers the
+ * limit channel reports — never a dedup count).
+ * 読み取り専用拒否の文脈 (v0.10 — onReadOnlyRejected が届ける): 拒否されたジェスチャ毎に 1 回
+ * 発火。adapter は呼ばれていないため {@link EditRejection} (applyEdits の throw) でも操作上限
+ * でもない。`kind: "edit"` はセル単位テキスト書込の入口 / 確定の拒否でセル座標を運び、
+ * `kind: "operation"` は操作全体の拒否で、`cellCount` はプロデューサ自身の overlap-naive 算術
+ * (上限チャネルと同じ数 — dedup 数ではない)。
+ */
+// 明示リテラル union で宣言する (api-extractor は Exclude<SpreadsheetOperation, ...> 等の lib 汎用型を
+// d.ts ロールアップできない — EditRejection と同じ制約)。op の 7 リテラル (copy / cut / resize を除いた
+// 集合 + "cut") と editSession の 3 リテラルは dataAdapter.spec.ts の型パリティガードが双方向に機械封印する
+export type ReadOnlyRejection =
+    | {
+          readonly kind: "edit"
+          readonly cell: CellCoord
+          /**
+           * Fate of the edit session THIS refusal adjudicated: "none" = no session commit was
+           * adjudicated (no session existed at the refusing gate, or the gate does not commit
+           * sessions — an untouched session may still exist, e.g. the G15 list chord during a
+           * flipped session); "kept" / "discarded" = G16's caller-declared fate.
+           * この拒否が裁いた編集セッションの帰結。none = セッション確定を裁いていない。
+           */
+          readonly editSession: "none" | "kept" | "discarded"
+      }
+    | {
+          readonly kind: "operation"
+          readonly op: "cut" | "delete" | "paste" | "fill" | "format" | "calc" | "annotate"
+          readonly cellCount: number
+      }
+
 /**
  * The single data boundary between the grid and the consumer. Reads via getCellText (renderCell
  * — a SpreadsheetProps prop, not an adapter member — customizes only the presentation of that
@@ -344,6 +383,21 @@ export type SpreadsheetDataAdapter = {
      * PasteEditContext.conditionalFormats で届く)。未宣言 = base 書式をそのまま塗る。
      */
     getConditionalFormats?: () => readonly ConditionalFormatRule[]
+    /**
+     * Read-only declaration for one cell (v0.10 read-only cells). `true` = the cell can never be
+     * written by this grid: edit-mode entry is refused, an already-open session's commit re-checks
+     * this predicate live, and every write operation whose target set contains the cell is rejected
+     * WHOLE before the adapter is called. Consulted live per gesture (never memoised); publish
+     * changes via `dataVersion`. The grid only ever calls this with in-grid coordinates. Host cost
+     * budget: O(1) and allocation-free — the same budget as `getCellText` (it also runs once per
+     * painted read-only-capable cell). Absence = every cell editable = the previous version's
+     * behaviour byte-identically.
+     * 読み取り専用宣言 (v0.10)。true のセルは編集モードに入れず、開いているセッションの確定も
+     * ライブ再検査され、対象に含む書込操作は adapter 到達前に全体拒否。ジェスチャ毎に生読み、
+     * 変更は dataVersion で公開。座標は常にグリッド内。ホスト側コストは O(1)・割当なし
+     * (getCellText と同格、描画パスでも呼ばれるため)。未宣言 = 全セル編集可 = 従来挙動とバイト同一。
+     */
+    isCellReadOnly?: (row: number, col: number) => boolean
     /**
      * OPTIONAL capability (v0.8): the numeric minimum / maximum over a range, for colorScale
      * rules whose end points omit `value`; null = the range holds no numeric value. Memoised by
@@ -476,3 +530,68 @@ export const aspectCapabilities = (adapter: SpreadsheetDataAdapter): AspectCapab
     cf: adapter.getConditionalFormats !== undefined,
     formula: adapter.getCellFormula !== undefined,
 })
+
+/**
+ * Whether the read-only capability is declared (v0.10 ADR-27). Used only where
+ * declaration-presence itself is the semantic — the announcement payload key and the popover
+ * context key: a declared host gets an explicit `false` for editable cells, an undeclared host
+ * gets no key at all (byte-identical payloads).
+ * 読み取り専用能力が宣言されているか (v0.10 ADR-27)。宣言の有無そのものが意味になる場所
+ * (announcement payload キー / ポップオーバー context キー) 専用 — 宣言ホストは編集可セルに
+ * 明示 `false`、未宣言ホストはキー自体なし (payload はバイト同一)。
+ */
+export const readOnlyDeclared = (adapter: SpreadsheetDataAdapter): boolean => adapter.isCellReadOnly !== undefined
+
+/**
+ * Live read-only answer for one cell: `false` in O(1) without calling anything when the
+ * capability is absent (the byte-identity lever — every gate and stamp goes through this
+ * helper, never the member; v0.10 ADR-27 / ADR-31). A throw from the host predicate is a host
+ * bug and propagates (no try/catch — Strict No-Fallback).
+ * セル 1 つの読み取り専用ライブ判定: 能力未宣言なら何も呼ばず O(1) で `false` (バイト恒等の
+ * 支点 — 全ゲート / スタンプはメンバー直接読みでなく必ず本ヘルパを通る。v0.10 ADR-27 /
+ * ADR-31)。ホスト述語の throw はホストのバグとして素通し (try/catch しない — Strict No-Fallback)。
+ */
+export const isReadOnlyCell = (adapter: SpreadsheetDataAdapter, row: number, col: number): boolean => adapter.isCellReadOnly?.(row, col) === true
+
+/**
+ * Whether a grid-clamped rect contains at least one read-only cell: rectangular walk with
+ * short-circuit on first hit; `false` in O(1) when the capability is absent. For the
+ * paste / cut / cut-move rect walls (v0.10 ADR-27).
+ * グリッド内 clamp 済み矩形に読み取り専用セルが 1 つでも含まれるか: 最初のヒットで短絡する
+ * 矩形 walk。能力未宣言は O(1) で `false`。paste / cut / cut-move の矩形壁用 (v0.10 ADR-27)。
+ */
+export const rectContainsReadOnly = (adapter: SpreadsheetDataAdapter, rect: CellRange): boolean => {
+    // 能力分岐: 未宣言は述語 0 呼びの O(1) false (v0.9 挙動とバイト同一)
+    const predicate = adapter.isCellReadOnly
+    if (predicate === undefined) {
+        return false
+    }
+    // 矩形 walk — 最初のヒットで短絡 (割当なし。上限ゲートが先に走るため walk は有界)
+    for (let row = rect.startRow; row <= rect.endRow; row += 1) {
+        for (let col = rect.startCol; col <= rect.endCol; col += 1) {
+            if (predicate(row, col)) {
+                return true
+            }
+        }
+    }
+    return false
+}
+
+/**
+ * Whether a range set contains at least one read-only cell: plain nested-loop enumeration with
+ * short-circuit on first hit and NO dedup (re-testing an overlapped cell of a pure predicate is
+ * harmless; a dedup Set would add O(cells) allocation inside a gate that must be
+ * allocation-free); `false` in O(1) when the capability is absent (v0.10 ADR-27).
+ * レンジ集合に読み取り専用セルが 1 つでも含まれるか: 素朴 2 重ループ列挙 + 最初のヒットで短絡、
+ * dedup なし (純述語の重複再検査は無害。dedup Set は割当ゼロであるべきゲートに O(セル数) の
+ * 割当を持ち込む)。能力未宣言は O(1) で `false` (v0.10 ADR-27)。
+ */
+export const rangesContainReadOnly = (adapter: SpreadsheetDataAdapter, ranges: readonly CellRange[]): boolean => {
+    // 矩形 walk は rectContainsReadOnly と単一実装を共有 (SSOT — 能力分岐も同関数の冒頭 1 箇所)
+    for (const range of ranges) {
+        if (rectContainsReadOnly(adapter, range)) {
+            return true
+        }
+    }
+    return false
+}

package/src/model/labels.ts

@@ -45,6 +45,8 @@ export type SpreadsheetLabels = {
     noteEscapeHint: string
     /** Note popover hint in the rejected state (Ctrl+Enter retries, Escape closes without saving). / 拒否状態のノートヒント。 */
     noteRejectedHint: string
+    /** Note popover hint in the v0.10 read-only viewer mode (Escape closes without saving — the commit affordance is disabled, so the hint must not promise a save). / 読み取り専用ビューアモード (v0.10) のノートヒント (Escape は保存せず閉じる — 確定操作は disabled のため保存を約束しない)。 */
+    noteViewerHint: string
     /** Comment popover heading. / コメントポップオーバーの見出し。 */
     commentTitle: string
     /** Comment reply field label. / 返信入力欄のラベル。 */
@@ -103,6 +105,7 @@ export const LABEL_KEYS = [
     "noteSave",
     "noteEscapeHint",
     "noteRejectedHint",
+    "noteViewerHint",
     "commentTitle",
     "commentReply",
     "commentPost",
@@ -129,10 +132,12 @@ void labelKeysCoverEveryKey
 
 /**
  * English defaults for every key. `sinkAriaLabel` / `rootAriaLabel` are byte-identical to the
- * v0.7 prop defaults (the fold is DOM-identical); `noteEscapeHint` = "Escape saves and closes";
+ * v0.7 prop defaults (the fold is DOM-identical); `noteEscapeHint` = "Escape saves and closes"
+ * and its v0.10 viewer counterpart `noteViewerHint` = "Escape closes without saving";
  * `commentCount` and `listMore` pluralise ("1 comment" / "n comments", "1 more value" / "n more values"). Frozen.
  * 全キーの英語既定。`sinkAriaLabel` / `rootAriaLabel` は v0.7 の prop 既定と byte 同一 (畳込みは
- * DOM 恒等)、`noteEscapeHint` = "Escape saves and closes"、`commentCount` / `listMore` は単複を区別。凍結済み。
+ * DOM 恒等)、`noteEscapeHint` = "Escape saves and closes" とその v0.10 ビューア対応
+ * `noteViewerHint` = "Escape closes without saving"、`commentCount` / `listMore` は単複を区別。凍結済み。
  */
 export const DEFAULT_LABELS: SpreadsheetLabels = Object.freeze({
     sinkAriaLabel: "Spreadsheet grid. Press Escape to move focus out of the grid.",
@@ -141,6 +146,7 @@ export const DEFAULT_LABELS: SpreadsheetLabels = Object.freeze({
     noteSave: "Save",
     noteEscapeHint: "Escape saves and closes",
     noteRejectedHint: "The note was rejected. Press Ctrl+Enter to retry or Escape to close without saving",
+    noteViewerHint: "Escape closes without saving",
     commentTitle: "Comments",
     commentReply: "Reply",
     commentPost: "Post",

package/src/overlay/useFillHandle.ts

@@ -15,6 +15,13 @@
  * plus every declared aspect (format / validation / hyperlink / note), comments never; a v0.7
  * adapter yields exactly `{ row, col, text }`.
  *
+ * v0.10 read-only wall (G7 — design ADR-28 rule 5): `confirmFill` walks the ≤2-rect disjoint
+ * decomposition of box ∖ source (`fillExtensionRects` — diagonal L legs included) after the limit
+ * gate and before `expandFill`; a hit refuses the WHOLE fill through the required
+ * `rejectReadOnly` funnel with `cellCount` = box area − source area (exact — deliberately not the
+ * limit gate's estimate) and the limit-refusal cleanup (no selection growth, no bumpEdit). Fill
+ * FROM a read-only source stays legal; capability undeclared = byte-identical behaviour.
+ *
  * v0.9 trailing freeze (plan §2.1 / §4.5 — census #5 / #6): the hover hit test builds BOTH
  * inverse ctx literals inline from one handle snapshot (a NEW judgment-time `getViewportSize()`
  * read supplies `extent`; `trailingSize` cites the TREE fields); the press-time grab arithmetic
@@ -38,6 +45,12 @@
  * 宣言済み側面 (format / validation / hyperlink / note) の全部、comments は決して運ばず、v0.7
  * アダプタは `{ row, col, text }` ちょうど。
  *
+ * v0.10 読み取り専用壁 (G7 — 設計 ADR-28 rule 5): `confirmFill` は限度ゲート後・`expandFill` 前に
+ * box ∖ source の ≤2 非交矩形分解 (`fillExtensionRects` — 斜めの L 字 2 レッグ込み) を walk し、
+ * hit は必須 `rejectReadOnly` 漏斗経由で fill 全体を拒否する (cellCount = box 面積 − source 面積 —
+ * 限度ゲートの見積りとは意図的に別の数)。後始末は限度拒否と同一 (選択不伸長・bumpEdit なし)。
+ * 読み取り専用ソースからの fill は合法のまま。能力未宣言は挙動バイト恒等。
+ *
  * v0.9 末尾凍結 (計画 §2.1 / §4.5 — census #5 / #6): hover ヒットテストは 1 ハンドル快照から
  * 両軸の逆写像 ctx をインライン構築 (新規の判断時 `getViewportSize()` 読みが `extent` を供給、
  * `trailingSize` は TREE フィールドを引用)。押下時の grab 算術は順写像 ctx 対を構築し、隅を
@@ -48,10 +61,10 @@
 
 import type { VirtualGridHandle } from "@aiquants/virtualscroll"
 import { type RefObject, useCallback, useEffect, useMemo, useRef } from "react"
-import { estimateFillCellCount, expandFill, fillSourceEdit, readFillSource } from "../clipboard/tiling.ts"
+import { estimateFillCellCount, expandFill, fillExtensionRects, fillSourceEdit, readFillSource } from "../clipboard/tiling.ts"
 import type { AxisModel } from "../model/axisModel.ts"
 import { type CellCoord, type CellRange, clampCoord, makeRange, type SpreadsheetOperation } from "../model/cellCoord.ts"
-import type { CellEdit, EditRejection, SpreadsheetDataAdapter } from "../model/dataAdapter.ts"
+import { type CellEdit, type EditRejection, type ReadOnlyRejection, rangesContainReadOnly, type SpreadsheetDataAdapter } from "../model/dataAdapter.ts"
 import { type AxisForwardCtx, colToViewportX, rowToViewportY, viewportXToCol, viewportYToRow } from "../model/frozenPartition.ts"
 import type { SelectionState } from "../selection/selectionState.ts"
 import type { AutoScroller } from "../selection/useAutoScroller.ts"
@@ -101,6 +114,14 @@ type UseFillHandleParams = {
     commitEdits: (edits: readonly CellEdit[], rejection: EditRejection) => number | null
     maxOperationCells: number
     onOperationRejected?: (op: SpreadsheetOperation, cellCount: number, reason: "limit" | "bounds") => void
+    /**
+     * v0.10 read-only refusal funnel (required seam — the root always wires it; identity-stable,
+     * read through paramsRef): G7 fires it once per refused confirm. Capability absent ⇒ never
+     * called (byte identity).
+     * v0.10 読み取り専用拒否漏斗 (必須 seam — root が常に渡す。identity 安定、paramsRef 読み):
+     * G7 が拒否された確定毎に 1 回発火する。能力未宣言なら一度も呼ばれない (バイト恒等)。
+     */
+    rejectReadOnly: (rejection: ReadOnlyRejection) => void
     /** Preview writer relay (overlay-owned positioner + liveFillPreviewRef). / プレビュー writer リレー。 */
     writeFillPreview: (range: CellRange | null) => void
     /** §8.2 repaint edges (press after flag + cleanup end). / §8.2 の repaint エッジ。 */
@@ -265,6 +286,18 @@ export const useFillHandle = (params: UseFillHandleParams): SelectionEngine => {
             p.onOperationRejected?.("fill", count, "limit")
             return
         }
+        // G7 (v0.10 §6.8 / 設計 ADR-28 rule 5): 読み取り専用壁 — walk は拡張域 (box ∖ source) の
+        // ≤2 非交矩形分解 fillExtensionRects (斜めドラッグの L 字 2 レッグ対応)。ソース行 / 列は
+        // 書込対象ではないため walk 外 = 読み取り専用ソースからの fill は合法 (Excel 同等)。座席は
+        // 限度ゲート後・expandFill (実体化) 前。cellCount = box 面積 − source 面積 (正確 — 限度
+        // チャネルの見積り estimateFillCellCount とは別の数、登記済み非対称)。後始末は限度拒否と
+        // 同一 (cleanupDrag 済み — 選択不伸長・bumpEdit なし)
+        if (rangesContainReadOnly(p.adapter, fillExtensionRects(source, box))) {
+            const boxArea = (box.endRow - box.startRow + 1) * (box.endCol - box.startCol + 1)
+            const sourceArea = (source.endRow - source.startRow + 1) * (source.endCol - source.startCol + 1)
+            p.rejectReadOnly({ kind: "operation", op: "fill", cellCount: boxArea - sourceArea })
+            return
+        }
         // 展開は fillDown / fillRight と同じソース毎規則 (分冊 08 §4 の fill 行): 種 (数式ソースか正準
         // 文字列) + 宣言済み側面を 1 回読み、対象毎に数式を相対シフト — v0.7 アダプタは { row, col, text } ちょうど
         const edits = expandFill((row, col) => readFillSource(p.adapter, row, col), source, box, fillSourceEdit)

package/src/popover/CommentPopover.tsx

@@ -6,12 +6,17 @@
  * Ctrl+Enter posts (retries after a rejection), Escape closes. Leaving by focus closes without
  * posting. DOM hooks: `data-aqsp-popover="comment"`, `data-aqsp-popover-title`,
  * `data-aqsp-comment-thread`, `data-aqsp-comment-id`, `data-aqsp-comment-input`,
- * `data-aqsp-popover-post`, `data-aqsp-popover-close`, `data-aqsp-popover-rejected`.
+ * `data-aqsp-popover-post`, `data-aqsp-popover-close`, `data-aqsp-popover-rejected`. v0.10 viewer
+ * mode (`ctx.cellReadOnly === true`): the Post button is `disabled` + `aria-disabled` and
+ * Ctrl+Enter does nothing — the thread stays readable (the wall is G14a; key absent =
+ * v0.9-identical conduct).
  *
  * 既定のコメントスレッド (v0.8 §4.1.16): 既存スレッド (著者 / 時刻 / 本文 — 各件は consumer の id を
  * 保つ) + 返信 textarea + 投稿ボタン。投稿はスレッド全体 `[...current (id つき), { text }]` を
  * commit する — id / 著者 / 時計はパッケージが採番しない (設計 v5「Comments」)。空の返信は投稿
  * しない。キー: Ctrl+Enter 投稿 (拒否後は再試行)、Escape で閉じる。フォーカス離脱は投稿せず閉じる。
+ * v0.10 ビューアモード (`ctx.cellReadOnly === true`): 投稿ボタンは `disabled` + `aria-disabled`、
+ * Ctrl+Enter は何もしない — スレッドは読めるまま (壁は G14a。キー不在 = v0.9 恒等)。
  */
 
 import { type FocusEvent, type KeyboardEvent, type ReactNode, useId, useRef, useState } from "react"
@@ -26,6 +31,9 @@ export type CommentPopoverProps = { ctx: CommentPopoverContext; labels: Spreadsh
  */
 export const CommentPopover = ({ ctx, labels }: CommentPopoverProps): ReactNode => {
     const [reply, setReply] = useState("")
+    // v0.10 (設計 ADR-30): 宣言ゲートキーが true のときだけ確定操作を disabled に (キー不在 = v0.9 恒等)。
+    // 壁は G14a — ここは表示であって防壁ではない
+    const readOnly = ctx.cellReadOnly === true
     const titleId = useId()
     const settlingRef = useRef(false)
 
@@ -38,6 +46,10 @@ export const CommentPopover = ({ ctx, labels }: CommentPopoverProps): ReactNode
         }
     }
     const post = (): void => {
+        // 読み取り専用ビューア: 投稿は不可 (disabled ボタンと同じ品行 — Ctrl+Enter も何もしない)
+        if (readOnly) {
+            return
+        }
         // 空 (空白のみ) の返信は投稿しない
         if (reply.trim() === "") {
             return
@@ -97,7 +109,7 @@ export const CommentPopover = ({ ctx, labels }: CommentPopoverProps): ReactNode
                 onKeyDown={onKeyDown}
             />
             <div className="aqsp-popover-actions">
-                <button type="button" className="aqsp-popover-button" data-aqsp-popover-post="" onClick={post}>
+                <button type="button" className="aqsp-popover-button" data-aqsp-popover-post="" disabled={readOnly} aria-disabled={readOnly ? "true" : undefined} onClick={post}>
                     {resolveLabel(labels, "commentPost")}
                 </button>
                 <button type="button" className="aqsp-popover-button" data-aqsp-popover-close="" aria-label={resolveLabel(labels, "popoverClose")} onClick={() => settle(ctx.close)}>

package/src/popover/LinkPopover.tsx

@@ -10,14 +10,19 @@
  * without saving. DOM hooks: `data-aqsp-popover="link"`, `data-aqsp-popover-title`,
  * `data-aqsp-link-text`, `data-aqsp-link-url`, `data-aqsp-popover-save`, `data-aqsp-link-open`
  * (the Open button — distinct from the layer's anchor open-state `data-aqsp-popover-open`),
- * `data-aqsp-popover-close`, `data-aqsp-popover-rejected`.
+ * `data-aqsp-popover-close`, `data-aqsp-popover-rejected`. v0.10 viewer mode
+ * (`ctx.cellReadOnly === true`): Save is `disabled` + `aria-disabled` and Enter does nothing,
+ * while the URL stays readable and Open stays live (navigation is a read — the wall is G14a; key
+ * absent = v0.9-identical conduct).
  *
  * 既定のハイパーリンクエディタ (v0.8 §4.1.16): text + URL 欄、保存、Open (ホストが onHyperlinkOpen を
  * 宣言し (`ctx.canOpen`) セルにリンクがあるときだけ)、閉じる。URL は打鍵毎に normalizeHyperlink で
  * 検証し、正規化不能な非空値は不正表示 (`data-aqsp-link-invalid` / `aria-invalid`) で保存を拒む —
  * commit は常に正規化済み href か null (空欄 = リンク消去) だけを運ぶ。空の text 下書き + 有効 URL の
  * 保存は href を表示テキストとして commit する (Sheets / Excel 同等 — 空セルのリンクを見えないままに
- * しない)。キー: Enter 保存、Escape で閉じる。フォーカス離脱は保存せず閉じる。
+ * しない)。キー: Enter 保存、Escape で閉じる。フォーカス離脱は保存せず閉じる。v0.10 ビューアモード
+ * (`ctx.cellReadOnly === true`): 保存は `disabled` + `aria-disabled` で Enter も何もしないが、URL は
+ * 読めたまま Open も生きている (ナビゲーションは読み — 壁は G14a。キー不在 = v0.9 恒等)。
  */
 
 import { type FocusEvent, type KeyboardEvent, type ReactNode, useId, useRef, useState } from "react"
@@ -34,6 +39,9 @@ export type LinkPopoverProps = { ctx: LinkPopoverContext; labels: SpreadsheetLab
 export const LinkPopover = ({ ctx, labels }: LinkPopoverProps): ReactNode => {
     const [text, setText] = useState(ctx.current.text)
     const [url, setUrl] = useState(ctx.current.url === undefined ? "" : ctx.current.url)
+    // v0.10 (設計 ADR-30): 宣言ゲートキーが true のときだけ確定操作を disabled に (キー不在 = v0.9 恒等)。
+    // Open は読み (ナビゲーション) なので生きたまま。壁は G14a — ここは表示であって防壁ではない
+    const readOnly = ctx.cellReadOnly === true
     const titleId = useId()
     const settlingRef = useRef(false)
     // 空欄はリンク消去、それ以外は正規化 (null = 不正)
@@ -49,6 +57,10 @@ export const LinkPopover = ({ ctx, labels }: LinkPopoverProps): ReactNode => {
         }
     }
     const save = (): void => {
+        // 読み取り専用ビューア: 保存は不可 (disabled ボタンと同じ品行 — Enter も何もしない)
+        if (readOnly) {
+            return
+        }
         // 不正 URL は保存しない (表示で知らせる — 代替値は作らない)
         if (invalid) {
             return
@@ -91,7 +103,7 @@ export const LinkPopover = ({ ctx, labels }: LinkPopoverProps): ReactNode => {
                 <input className="aqsp-popover-input" data-aqsp-link-url="" data-aqsp-popover-autofocus="" type="url" value={url} aria-invalid={invalid || ctx.rejected ? true : undefined} onChange={(event) => setUrl(event.currentTarget.value)} onKeyDown={onKeyDown} />
             </label>
             <div className="aqsp-popover-actions">
-                <button type="button" className="aqsp-popover-button" data-aqsp-popover-save="" disabled={invalid} onClick={save}>
+                <button type="button" className="aqsp-popover-button" data-aqsp-popover-save="" disabled={invalid || readOnly} aria-disabled={readOnly ? "true" : undefined} onClick={save}>
                     {resolveLabel(labels, "linkSave")}
                 </button>
                 {ctx.canOpen && ctx.current.url !== undefined ? (

package/src/popover/NotePopover.tsx

@@ -5,17 +5,26 @@
  * focus saves-if-changed — an anchor scrolled under a frozen band is clipped, not un-rendered
  * (SelectionOverlay `placeAnchor`), so the textarea keeps focus and that is NOT a leave: the
  * editor hides and comes back with its draft. The textarea's `aria-describedby` points at the hint paragraph, which
- * swaps between `labels.noteEscapeHint` and `labels.noteRejectedHint` with the rejected state.
+ * swaps among `labels.noteEscapeHint` (normal), `labels.noteRejectedHint` (rejected) and
+ * `labels.noteViewerHint` (viewer mode — precedence over the rejected wording, since neither save
+ * nor retry is possible there and the hint must not promise either).
  * DOM hooks: `data-aqsp-popover="note"`, `data-aqsp-popover-title`, `data-aqsp-note-input`,
  * `data-aqsp-popover-save`, `data-aqsp-popover-close`, `data-aqsp-popover-hint`,
- * `data-aqsp-popover-rejected`.
+ * `data-aqsp-popover-rejected`. v0.10 viewer mode (`ctx.cellReadOnly === true`): the Save button
+ * is `disabled` + `aria-disabled` (native only — no new attribute, no package CSS, design ADR-31),
+ * Ctrl+Enter does nothing, Escape / focus-leave close WITHOUT saving (the wall is G14a; key
+ * absent = v0.9-identical conduct), and the hint swaps to `noteViewerHint`.
  *
  * 既定の note エディタ (v0.8 §4.1.16): textarea の下書き + 保存 / 閉じるボタン。キー: Escape は
  * 通常状態で「変更があれば保存して閉じる」、拒否状態では保存せず閉じる。Ctrl+Enter は保存 (拒否後は
  * 再試行)。フォーカスがポップオーバーを離れたら変更があれば保存 — 凍結帯の下へ潜ったアンカーは
  * clip されるだけで描画から外れない (SelectionOverlay の placeAnchor) ので textarea はフォーカスを保ち、
  * 離脱には当たらない: エディタは隠れて下書きごと戻る。textarea の aria-describedby は
- * ヒント段落を指し、拒否状態で `labels.noteEscapeHint` ↔ `labels.noteRejectedHint` が差し替わる。
+ * ヒント段落を指し、`labels.noteEscapeHint` (通常) ↔ `labels.noteRejectedHint` (拒否状態) ↔
+ * `labels.noteViewerHint` (ビューアモード — 保存も再試行も不能のため拒否文言より優先) が差し替わる。
+ * v0.10 ビューアモード (`ctx.cellReadOnly === true`): 保存ボタンは `disabled` + `aria-disabled`
+ * (ネイティブのみ — 新属性 / パッケージ CSS なし、設計 ADR-31)、Ctrl+Enter は何もせず、Escape /
+ * フォーカス離脱は保存せず閉じ、ヒントは `noteViewerHint` に差し替わる (壁は G14a。キー不在 = v0.9 恒等)。
  */
 
 import { type FocusEvent, type KeyboardEvent, type ReactNode, useId, useRef, useState } from "react"
@@ -31,6 +40,9 @@ export type NotePopoverProps = { ctx: NotePopoverContext; labels: SpreadsheetLab
 export const NotePopover = ({ ctx, labels }: NotePopoverProps): ReactNode => {
     const initial = ctx.current === undefined ? "" : ctx.current
     const [draft, setDraft] = useState(initial)
+    // v0.10 (設計 ADR-30): 宣言ゲートキーが true のときだけ確定操作を disabled に (キー不在 = v0.9 恒等)。
+    // 壁は G14a — ここは表示であって防壁ではない
+    const readOnly = ctx.cellReadOnly === true
     const titleId = useId()
     const hintId = useId()
     /** True while THIS component drives a commit / close (its synchronous focusout must not re-fire the save). / 自分が commit / close を駆動している間 true (同期 focusout の二重保存を防ぐ)。 */
@@ -46,11 +58,16 @@ export const NotePopover = ({ ctx, labels }: NotePopoverProps): ReactNode => {
         }
     }
     const save = (): void => {
+        // 読み取り専用ビューア: 確定操作は不可 (disabled ボタンと同じ品行 — Ctrl+Enter も何もしない)
+        if (readOnly) {
+            return
+        }
         // 空の下書きはノート消去
         settle(() => ctx.commit(draft === "" ? null : draft))
     }
     const saveIfChanged = (): void => {
-        if (draft !== initial) {
+        // 読み取り専用ビューア: Escape / フォーカス離脱は保存せず閉じる (下書きは commit できない)
+        if (draft !== initial && !readOnly) {
             save()
         } else {
             settle(ctx.close)
@@ -91,10 +108,11 @@ export const NotePopover = ({ ctx, labels }: NotePopoverProps): ReactNode => {
             </div>
             <textarea className="aqsp-popover-textarea" data-aqsp-note-input="" data-aqsp-popover-autofocus="" value={draft} aria-describedby={hintId} aria-invalid={ctx.rejected ? true : undefined} onChange={(event) => setDraft(event.currentTarget.value)} onKeyDown={onKeyDown} />
             <p className="aqsp-popover-hint" id={hintId} data-aqsp-popover-hint="">
-                {resolveLabel(labels, ctx.rejected ? "noteRejectedHint" : "noteEscapeHint")}
+                {/* ビューアは保存 (noteEscapeHint) も再試行 (noteRejectedHint) も約束できない — Escape は保存せず閉じるため noteViewerHint を最優先 */}
+                {resolveLabel(labels, readOnly ? "noteViewerHint" : ctx.rejected ? "noteRejectedHint" : "noteEscapeHint")}
             </p>
             <div className="aqsp-popover-actions">
-                <button type="button" className="aqsp-popover-button" data-aqsp-popover-save="" onClick={save}>
+                <button type="button" className="aqsp-popover-button" data-aqsp-popover-save="" disabled={readOnly} aria-disabled={readOnly ? "true" : undefined} onClick={save}>
                     {resolveLabel(labels, "noteSave")}
                 </button>
                 <button type="button" className="aqsp-popover-button" data-aqsp-popover-close="" aria-label={resolveLabel(labels, "popoverClose")} onClick={() => settle(ctx.close)}>