@aiquants/spreadsheet 0.9.0 → 0.10.0

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

package/src/popover/usePopovers.ts

@@ -21,6 +21,13 @@
  * cell binds —) and the
  * IME guard the layer applies to every popover keydown (`isCompositionKeydown`). No DOM is
  * rendered here — PopoverLayer.tsx renders from `context` / `tipContext` (lazy mount).
+ * v0.10 read-only (design ADR-30, refusals via the required `rejectReadOnly` funnel): S3 = ONE
+ * interactive-context builder site for the declaration-gated `cellReadOnly` key (note / comment /
+ * link builds and the G14a re-present all share it); G14a re-checks live at `commitOrReject`'s
+ * head (refusal re-presents with `cellReadOnly` recomputed, `rejected` kept false, draft
+ * preserved); G14b is the list commit's defense-in-depth; G14c refuses a list open PRE-open —
+ * after the RangeError wiring check, BEFORE the commit gate (doomed-open: no force-commit).
+ * Capability undeclared = contexts and conduct byte-identical to v0.9.
  *
  * ポップオーバー状態機械 (v0.8 §1.8 / §4.1.15 — ADR-15 対話層)。6 種 (note エディタ / ホバー
  * note tip / コメントスレッド / ハイパーリンクエディタ / 検証リスト / 検証メッセージ) を overlay が
@@ -39,7 +46,12 @@
  * 変化 (root の active 効果が呼ぶ) のたびに再評価し、離れれば外し、ホバー中セルへ乗れば結ぶ —)、
  * 層が全 popover keydown に掛ける
  * IME ガード (`isCompositionKeydown`)。DOM は描かない — PopoverLayer.tsx が `context` /
- * `tipContext` から遅延マウントする。
+ * `tipContext` から遅延マウントする。v0.10 読み取り専用 (設計 ADR-30、拒否は必須 `rejectReadOnly`
+ * 漏斗): S3 = 宣言ゲートキー `cellReadOnly` の単一対話 context ビルダ (note / comment / link の
+ * 構築と G14a 再提示が共有)、G14a = commitOrReject 頭の live 再検査 (拒否は cellReadOnly 再計算 +
+ * rejected false のまま + 下書き保持で再提示)、G14b = list commit の縦深防御、G14c = list の
+ * pre-open 拒否 (RangeError 結線検査の後・commit ゲートの前 — doomed-open で force-commit なし)。
+ * 能力未宣言は context も品行も v0.9 とバイト恒等。
  */
 
 import type { VirtualGridHandle } from "@aiquants/virtualscroll"
@@ -48,7 +60,7 @@ import { isCompositionKeydown } from "../keyboard/compositionGuard.ts"
 import type { AxisModel } from "../model/axisModel.ts"
 import { type CellComment, type CellCommentInput, normalizeAdapterHyperlink, normalizeHyperlink } from "../model/cellAnnotations.ts"
 import { type CellCoord, clampCoord, coordEquals } from "../model/cellCoord.ts"
-import type { CellEdit, EditRejection, SpreadsheetDataAdapter } from "../model/dataAdapter.ts"
+import { type CellEdit, type EditRejection, isReadOnlyCell, type ReadOnlyRejection, readOnlyDeclared, type SpreadsheetDataAdapter } from "../model/dataAdapter.ts"
 import { colToViewportX, rowToViewportY, viewportXToCol, viewportYToRow } from "../model/frozenPartition.ts"
 import { resolveLabel, type SpreadsheetLabels } from "../model/labels.ts"
 import { NOTE_TIP_LEAVE_GRACE_MS, type PopoverRect, shouldShowNoteTip } from "./placement.ts"
@@ -62,17 +74,28 @@ export const POPOVER_KINDS: readonly PopoverKind[] = ["note", "note-tip", "comme
 /** The `popovers` prop: `false` disables a kind (its commands pass through, `openPopover` throws). / `popovers` prop: `false` はその kind を無効化 (コマンドは素通し、`openPopover` は RangeError)。 */
 export type PopoverOverrides = { readonly [K in PopoverKind]?: boolean }
 
-/** Note editor context (v0.8 §1.8). `current` undefined = no note yet; `commit(null)` clears. / note エディタ文脈。current undefined = ノートなし、commit(null) は消去。 */
-export type NotePopoverContext = { kind: "note"; cell: CellCoord; anchorRect: PopoverRect; current: string | undefined; commit: (next: string | null) => void; close: () => void; rejected: boolean }
+/** Note editor context (v0.8 §1.8). `current` undefined = no note yet; `commit(null)` clears. `cellReadOnly` (v0.10, declaration-gated): key ABSENT = the `isCellReadOnly` capability is undeclared (byte-identical context), else the live predicate answer — `true` disables the default component's commit affordance (G14a walls the commit regardless). / note エディタ文脈。current undefined = ノートなし、commit(null) は消去。cellReadOnly (v0.10、宣言ゲート): キー不在 = isCellReadOnly 能力未宣言 (context はバイト恒等)、あれば live 述語の答え — true は既定コンポーネントの確定操作を disabled にする (壁は G14a)。 */
+export type NotePopoverContext = { kind: "note"; cell: CellCoord; anchorRect: PopoverRect; current: string | undefined; commit: (next: string | null) => void; close: () => void; rejected: boolean; cellReadOnly?: boolean }
 
 /** Hover note tip context (read-only). / ホバー note tip 文脈 (読み取り専用)。 */
 export type NoteTipContext = { kind: "note-tip"; cell: CellCoord; anchorRect: PopoverRect; current: string; close: () => void }
 
-/** Comment thread context: the reply UI commits `[...current (with ids), { text }]`; `null` clears the thread. / コメントスレッド文脈: 返信 UI は `[...current (id つき), { text }]` を commit、null はスレッド消去。 */
-export type CommentPopoverContext = { kind: "comment"; cell: CellCoord; anchorRect: PopoverRect; current: readonly CellComment[]; commit: (next: readonly CellCommentInput[] | null) => void; close: () => void; rejected: boolean }
+/** Comment thread context: the reply UI commits `[...current (with ids), { text }]`; `null` clears the thread. `cellReadOnly` (v0.10): same declaration-gated key as the note context. / コメントスレッド文脈: 返信 UI は `[...current (id つき), { text }]` を commit、null はスレッド消去。cellReadOnly (v0.10) は note 文脈と同じ宣言ゲートキー。 */
+export type CommentPopoverContext = { kind: "comment"; cell: CellCoord; anchorRect: PopoverRect; current: readonly CellComment[]; commit: (next: readonly CellCommentInput[] | null) => void; close: () => void; rejected: boolean; cellReadOnly?: boolean }
 
-/** Hyperlink editor context: `url` on commit is a normalised href or null (clear); `canOpen` = onHyperlinkOpen declared. / ハイパーリンクエディタ文脈: commit の url は正規化済み href か null (消去)、canOpen = onHyperlinkOpen 宣言。 */
-export type LinkPopoverContext = { kind: "link"; cell: CellCoord; anchorRect: PopoverRect; current: { text: string; url: string | undefined }; commit: (next: { text: string; url: string | null }) => void; close: () => void; canOpen: boolean; open: () => void; rejected: boolean }
+/** Hyperlink editor context: `url` on commit is a normalised href or null (clear); `canOpen` = onHyperlinkOpen declared. `cellReadOnly` (v0.10): same declaration-gated key as the note context (the Open button stays live — navigation is a read). / ハイパーリンクエディタ文脈: commit の url は正規化済み href か null (消去)、canOpen = onHyperlinkOpen 宣言。cellReadOnly (v0.10) は note 文脈と同じ宣言ゲートキー (Open は読みなので生きたまま)。 */
+export type LinkPopoverContext = {
+    kind: "link"
+    cell: CellCoord
+    anchorRect: PopoverRect
+    current: { text: string; url: string | undefined }
+    commit: (next: { text: string; url: string | null }) => void
+    close: () => void
+    canOpen: boolean
+    open: () => void
+    rejected: boolean
+    cellReadOnly?: boolean
+}
 
 /** Validation list picker context: `current` = the list rule's values, `typed` = the prefix that opened it. / 検証リスト文脈: current = list 規則の値、typed = 開いたときの入力プレフィックス。 */
 export type ListPopoverContext = { kind: "list"; cell: CellCoord; anchorRect: PopoverRect; current: readonly string[]; typed: string; commit: (value: string) => void; close: () => void }
@@ -144,6 +167,15 @@ export type UsePopoversParams = {
     /** Composite drag probe incl. the reference drag — the tip is never shown mid-drag. / 参照ドラッグ含む合成ドラッグ判定 — ドラッグ中は tip を出さない。 */
     isDraggingAny: () => boolean
     commitEdits: (edits: readonly CellEdit[], rejection: EditRejection) => number | null
+    /**
+     * v0.10 read-only refusal funnel (required seam — the root always wires it; identity-stable,
+     * read through paramsRef): G14a (interactive commit), G14b (list commit) and G14c (the list
+     * pre-open refusal) fire it once per refused gesture. Capability absent ⇒ never called.
+     * v0.10 読み取り専用拒否漏斗 (必須 seam — root が常に渡す。identity 安定、paramsRef 読み):
+     * G14a (対話 commit)・G14b (list commit)・G14c (list の pre-open 拒否) が拒否ジェスチャ毎
+     * 1 回発火する。能力未宣言なら一度も呼ばれない。
+     */
+    rejectReadOnly: (rejection: ReadOnlyRejection) => void
     labels: SpreadsheetLabels
     onHyperlinkOpen?: (url: string, cell: CellCoord) => void
     /** Root-owned anchor state the overlay positions. / root 所有のアンカー状態 (overlay が配置)。 */
@@ -451,10 +483,34 @@ export const usePopovers = (params: UsePopoversParams): PopoverController => {
         [writeAnchors],
     )
 
-    /** Runs an annotate commit; a rejection re-presents the context with `rejected: true`. / annotate の commit を実行し、拒否なら rejected: true で再提示する。 */
+    /**
+     * S3 (v0.10): the SINGLE interactive-context builder site for the declaration-gated
+     * `cellReadOnly` key — the three build paths (note / comment / link) and the G14a re-present
+     * all spread this result, so the census stays at one `readOnlyDeclared` + one `isReadOnlyCell`
+     * call. Key absent = capability undeclared (context byte-identical), else the live answer.
+     * S3 (v0.10): 宣言ゲートキー `cellReadOnly` の**単一**対話 context ビルダサイト — 3 つの構築
+     * 経路 (note / comment / link) と G14a の再提示が全てこの戻り値を spread するため、census は
+     * readOnlyDeclared 1 + isReadOnlyCell 1 のまま。キー不在 = 能力未宣言 (context バイト恒等)、
+     * あれば live の答え。
+     */
+    const readOnlyKeyOf = useCallback((cell: CellCoord): { cellReadOnly?: boolean } => {
+        const p = paramsRef.current
+        // 宣言時だけキーを出す (undefined キーも出さない — v0.9 形ホストの context はバイト恒等)
+        return readOnlyDeclared(p.adapter) ? { cellReadOnly: isReadOnlyCell(p.adapter, cell.row, cell.col) } : {}
+    }, [])
+
+    /** Runs an annotate commit; a G14a read-only refusal re-presents with `cellReadOnly` recomputed (`rejected` stays false), an adapter rejection re-presents with `rejected: true`. / annotate の commit を実行。G14a の読み取り専用拒否は cellReadOnly を再計算して再提示 (rejected は false のまま)、アダプタ拒否は rejected: true で再提示。 */
     const commitOrReject = useCallback(
         (ctx: NotePopoverContext | CommentPopoverContext | LinkPopoverContext, edits: readonly CellEdit[]) => {
             const p = paramsRef.current
+            // G14a (v0.10 §6.10): commit 頭の live 再検査 — adapter 不到達。再提示は cellReadOnly 再計算
+            // (今は true — 既定コンポーネントが確定操作を disabled に)、rejected は false のまま
+            // (true は「adapter が投げた、再試行の余地あり」の意味 — ここでは嘘になる)、入力値は保持
+            if (isReadOnlyCell(p.adapter, ctx.cell.row, ctx.cell.col)) {
+                p.rejectReadOnly({ kind: "operation", op: "annotate", cellCount: 1 })
+                present({ ...ctx, ...readOnlyKeyOf(ctx.cell) })
+                return
+            }
             if (p.commitEdits(edits, { source: "annotate" }) === null) {
                 // 拒否: 開いたまま rejected 状態へ (既定コンポーネントが Ctrl+Enter 再試行 / Escape 破棄を担う)
                 present({ ...ctx, rejected: true })
@@ -462,7 +518,7 @@ export const usePopovers = (params: UsePopoversParams): PopoverController => {
             }
             close()
         },
-        [present, close],
+        [present, close, readOnlyKeyOf],
     )
 
     const open = useCallback(
@@ -472,6 +528,14 @@ export const usePopovers = (params: UsePopoversParams): PopoverController => {
                 throw new RangeError(`[spreadsheet] openPopover("${kind}") is unavailable: the kind is disabled by the popovers prop or its adapter capability is undeclared`)
             }
             const cell = p.getActive()
+            // G14c (v0.10 §6.10 — doomed-open 原則): list の pre-open 拒否。座席は RangeError 結線検査の
+            // 後 (結線バグはデータ状態に優先 — fail-fast 序列保存)・open 経路 commit ゲートの**前**
+            // (拒否される open が無関係セッションを force-commit しない)。picker の対話 = 書込そのもの
+            // なので popover は開かない。RangeError にはしない (読み取り専用はデータ状態で結線バグではない)
+            if (kind === "list" && isReadOnlyCell(p.adapter, cell.row, cell.col)) {
+                p.rejectReadOnly({ kind: "edit", cell, editSession: "none" })
+                return
+            }
             if (kind === "note-tip") {
                 // 手動表示: active セルにノートがあるときだけ (ホバー述語とは独立)
                 showTip(cell)
@@ -515,6 +579,14 @@ export const usePopovers = (params: UsePopoversParams): PopoverController => {
                     current: rule.values,
                     typed,
                     commit: (value: string) => {
+                        // G14b (v0.10 §6.10): list commit の縦深防御 — 開いている間の読み取り専用化を
+                        // commitEdits 前に live 再検査 (G14c が正門、ここは第二壁)。拒否は無書込で閉じる
+                        // (picker に他の対話は無い — Escape 相当の閉鎖)
+                        if (isReadOnlyCell(paramsRef.current.adapter, cell.row, cell.col)) {
+                            paramsRef.current.rejectReadOnly({ kind: "edit", cell, editSession: "none" })
+                            close()
+                            return
+                        }
                         // リスト確定はセル編集 (source "edit"、セッションなし = discarded)
                         paramsRef.current.commitEdits([{ row: cell.row, col: cell.col, text: value }], { source: "edit", editSession: "discarded" })
                         close()
@@ -537,6 +609,8 @@ export const usePopovers = (params: UsePopoversParams): PopoverController => {
                     },
                     close,
                     rejected: false,
+                    // S3: 宣言ゲートキー (単一ビルダ経由 — 未宣言はキー不在で context バイト恒等)
+                    ...readOnlyKeyOf(cell),
                 }
                 present(ctx)
                 return
@@ -554,6 +628,8 @@ export const usePopovers = (params: UsePopoversParams): PopoverController => {
                     },
                     close,
                     rejected: false,
+                    // S3: 宣言ゲートキー (単一ビルダ経由)
+                    ...readOnlyKeyOf(cell),
                 }
                 present(ctx)
                 return
@@ -585,10 +661,12 @@ export const usePopovers = (params: UsePopoversParams): PopoverController => {
                     }
                 },
                 rejected: false,
+                // S3: 宣言ゲートキー (単一ビルダ経由)
+                ...readOnlyKeyOf(cell),
             }
             present(ctx)
         },
-        [anchorRectOf, close, commitOrReject, hideTipNow, present, showTip],
+        [anchorRectOf, close, commitOrReject, hideTipNow, present, showTip, readOnlyKeyOf],
     )
 
     const { enabled, bodyRef } = params