@aiquants/spreadsheet 0.8.0 → 0.10.0

package/src/overlay/useFillHandle.ts

@@ -15,6 +15,21 @@
  * 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
+ * builds the forward ctx pair, classifies the corner strictly (`endCol >= count − T` is
+ * trailing — the boundary track is SCROLL) and gains the ceiling clamp twins
+ * `min(inside, extent − vis − 1)` so a non-trailing corner's inside pixel never re-anchors into
+ * the trailing band (the FZ19 floor's far mirror). T = 0 keeps every path byte-identical.
+ *
  * fill ハンドル機械 (§8 PT-2 — copy fill のみ)。常設ハンドルノードへ wire-once の pointerdown
  * を 1 本。press は義務 repaint より先に自機フラグをセット (§8.1 の可視凍結が評価前に成立して
  * いないと display:none が capture を殺す)。ドラッグはボックス方式 (v0.3 の斜め
@@ -29,15 +44,28 @@
  * `readFillSource` / `fillSourceEdit`): `getCellFormula` 宣言時は対象毎に相対シフトした数式ソース、
  * 宣言済み側面 (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 対を構築し、隅を
+ * 厳密分類 (`endCol >= count − T` が末尾 — 境界トラックは SCROLL) して天井クランプ双子
+ * `min(inside, extent − vis − 1)` を得る (非末尾隅の内側 px が末尾帯へ再アンカーされない —
+ * FZ19 床の遠ミラー)。T = 0 は全経路 byte 恒等。
  */
 
 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 { colToViewportX, rowToViewportY, viewportXToCol, viewportYToRow } from "../model/frozenPartition.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"
 import type { SelectionEngine } from "../selection/useSelectionEngine.ts"
@@ -56,6 +84,17 @@ import type { SelectionEngine } from "../selection/useSelectionEngine.ts"
  */
 const FILL_ARM_THRESHOLD = 4
 
+/** `getFrozenSize()` snapshot shape (engine 3.5.0 — 10 fields incl. the trailing family). / `getFrozenSize()` 快照の形 (エンジン 3.5.0 — 末尾族込みの 10 フィールド)。 */
+type FrozenSnapshot = ReturnType<VirtualGridHandle["getFrozenSize"]>
+
+/**
+ * Pre-attach frozen-size snapshot (all zeros — the capability branch for a not-yet-attached
+ * handle, byte-matching the engine's pre-measure state, not a value fallback).
+ * 装着前の凍結寸法快照 (全 0 — 未装着ハンドルの能力分岐。エンジンの未測定状態と byte 一致で、
+ * 値フォールバックではない)。
+ */
+const EMPTY_FROZEN_SIZE: FrozenSnapshot = Object.freeze({ cols: 0, width: 0, rows: 0, height: 0, trailingCols: 0, trailingRows: 0, trailingWidth: 0, trailingHeight: 0, trailingVisibleWidth: 0, trailingVisibleHeight: 0 })
+
 type UseFillHandleParams = {
     /** Zoom scale reader (v0.3): client px = logical px × zoom — divide client deltas once at this boundary. / ズーム倍率 reader (v0.3)。client px = 論理 px × zoom — client 差分はこの境界で 1 回だけ除算する。 */
     zoomRef: RefObject<number>
@@ -75,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 エッジ。 */
@@ -150,10 +197,21 @@ export const useFillHandle = (params: UseFillHandleParams): SelectionEngine => {
             return null
         }
         // ズーム境界 (v0.3): client 差分を z で 1 回だけ除算して論理 px へ。
-        // 列は凍結パーティション逆写像 (v0.5 計画 §2)
+        // 両軸とも凍結パーティション 3 分岐逆写像 (v0.5 / v0.6 計画 §2、v0.9 §2.1)
         const z = paramsRef.current.zoomRef.current
         const frozen = handle.getFrozenSize()
-        return clampCoord({ row: viewportYToRow(rowAxis, (clientY - rect.top) / z, vy, frozen.height), col: viewportXToCol(colAxis, (clientX - rect.left) / z, hx, frozen.width) }, rowAxis.count, colAxis.count)
+        // 判断時 extent (v0.9 §2.1 — census #5 の新規 getViewportSize() 読み)。逆写像 ctx は
+        // この場でインライン構築し (跨サイト共有ビルダ禁止 — §5.3)、trailingSize は TREE
+        // フィールド trailingWidth / trailingHeight を正準に引く (vis 代替は分類等価ゆえ命名ピン)
+        const viewport = handle.getViewportSize()
+        return clampCoord(
+            {
+                row: viewportYToRow(rowAxis, (clientY - rect.top) / z, { scroll: vy, frozenSize: frozen.height, trailingSize: frozen.trailingHeight, extent: viewport.height }),
+                col: viewportXToCol(colAxis, (clientX - rect.left) / z, { scroll: hx, frozenSize: frozen.width, trailingSize: frozen.trailingWidth, extent: viewport.width }),
+            },
+            rowAxis.count,
+            colAxis.count,
+        )
     }, [])
 
     /**
@@ -228,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)
@@ -357,13 +427,19 @@ export const useFillHandle = (params: UseFillHandleParams): SelectionEngine => {
                 const hx = pressPosition.x
                 // ズーム境界 (v0.3): 論理オフセットは ×z で視覚 px へ写してから client と比較する
                 const zPress = p.zoomRef.current
-                // 隅の x は凍結パーティション順写像 (v0.5 計画 §2 — repaintOverlay のハンドル描画と
-                // 同式)。無条件 −hx だと凍結 endCol の押下で dx が hx·z ぶん膨らみ、以後の全ヒット
-                // テストが左へ hx ずれる (誤列への fill 確定 + 暴走左オートスクロール)
-                const pressFrozen = p.handleRef.current?.getFrozenSize() ?? { cols: 0, width: 0, rows: 0, height: 0 }
-                const cornerViewportX = colToViewportX(p.colAxis, source.endCol, hx, pressFrozen.cols) + p.colAxis.sizeOf(source.endCol)
+                // 隅の x は凍結パーティション順写像 (v0.5 計画 §2、v0.9 §2.1 で 3 分岐 —
+                // repaintOverlay のハンドル描画と同式)。無条件 −hx だと凍結 endCol の押下で dx が
+                // hx·z ぶん膨らみ、以後の全ヒットテストが左へ hx ずれる (誤列への fill 確定 +
+                // 暴走左オートスクロール)
+                const pressFrozen = p.handleRef.current?.getFrozenSize() ?? EMPTY_FROZEN_SIZE
+                // 判断時 forward ctx (v0.9 §2.1 — census #6): 押下 1 スナップショットの
+                // getViewportSize() を extent に両軸をその場インライン構築 (§5.3)
+                const pressViewport = p.handleRef.current?.getViewportSize() ?? { width: 0, height: 0 }
+                const pressCtxX: AxisForwardCtx = { scroll: hx, frozenCount: pressFrozen.cols, trailingCount: pressFrozen.trailingCols, extent: pressViewport.width }
+                const pressCtxY: AxisForwardCtx = { scroll: pressVy, frozenCount: pressFrozen.rows, trailingCount: pressFrozen.trailingRows, extent: pressViewport.height }
+                const cornerViewportX = colToViewportX(p.colAxis, source.endCol, pressCtxX) + p.colAxis.sizeOf(source.endCol)
                 // 隅 y も凍結パーティション順写像 (v0.6 — repaintOverlay のハンドル描画と同式)
-                const cornerViewportY = rowToViewportY(p.rowAxis, source.endRow, pressVy, pressFrozen.rows) + p.rowAxis.sizeOf(source.endRow)
+                const cornerViewportY = rowToViewportY(p.rowAxis, source.endRow, pressCtxY) + p.rowAxis.sizeOf(source.endRow)
                 // 内側 1px は論理 px の概念 (「隅の内側最終 px」) — 視覚 1px のままだと z < 1 で
                 // 1/z 論理 px に膨らみ、極小トラック (< 1/z px) では隣トラックへ再アンカーされて
                 // 押下点回帰キャンセルが 1 トラック fill に化ける。×zPress で論理 1px に固定。
@@ -371,11 +447,22 @@ export const useFillHandle = (params: UseFillHandleParams): SelectionEngine => {
                 // 内側 px が凍結帯へ潜って全ヒットテストが F−1 列へ解決する — 帯下限 W_F で
                 // クランプ (R2 是正。凍結 endCol と W_F = 0 はクランプ不要 — 後者は v0.4 恒等)
                 const insideRawX = cornerViewportX - 1
-                const insideViewportX = source.endCol >= pressFrozen.cols && pressFrozen.width > 0 ? Math.max(insideRawX, pressFrozen.width) : insideRawX
+                const flooredInsideX = source.endCol >= pressFrozen.cols && pressFrozen.width > 0 ? Math.max(insideRawX, pressFrozen.width) : insideRawX
+                // 厳密分類 (v0.9 §4.5 — FZ21 ミラー): endCol >= count − T が末尾 (境界列
+                // count − T − 1 は SCROLL)。T = 0 は count − 0 = count で恒偽
+                const endColIsTrailing = source.endCol >= p.colAxis.count - pressFrozen.trailingCols
+                // 天井双子 (v0.9 §4.5 — FZ19 の帯床クランプのミラー): 非末尾 endCol の内側 px が
+                // 末尾帯 [extent − vis, extent) へ潜ると全ヒットテストが末尾列へ解決し、押下点回帰
+                // キャンセルが末尾への fill 書込に化ける — 帯直前の最終 px extent − vis − 1 で
+                // クランプ (末尾 endCol 自身は帯内が正位置なのでクランプしない。T_px = 0 は恒等)
+                const insideViewportX = !endColIsTrailing && pressFrozen.trailingWidth > 0 ? Math.min(flooredInsideX, pressViewport.width - pressFrozen.trailingVisibleWidth - 1) : flooredInsideX
                 // 内側 py も帯下限 H_F でクランプ (v0.6 — 横の insideViewportX と対称。小数 vy の隅
                 // すきまでスクロール帯 endRow が凍結帯へ潜る dy ギャップを閉塞)
                 const insideRawY = cornerViewportY - 1
-                const insideViewportY = source.endRow >= pressFrozen.rows && pressFrozen.height > 0 ? Math.max(insideRawY, pressFrozen.height) : insideRawY
+                const flooredInsideY = source.endRow >= pressFrozen.rows && pressFrozen.height > 0 ? Math.max(insideRawY, pressFrozen.height) : insideRawY
+                // 縦の天井双子 (v0.9 §4.5 — 横と対称の末尾帯クランプ)
+                const endRowIsTrailing = source.endRow >= p.rowAxis.count - pressFrozen.trailingRows
+                const insideViewportY = !endRowIsTrailing && pressFrozen.trailingHeight > 0 ? Math.min(flooredInsideY, pressViewport.height - pressFrozen.trailingVisibleHeight - 1) : flooredInsideY
                 grabOffsetRef.current = { dx: event.clientX - (rect.left + insideViewportX * zPress), dy: event.clientY - (rect.top + insideViewportY * zPress) }
             } else {
                 grabOffsetRef.current = { dx: 0, dy: 0 }

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)}>