@aiquants/spreadsheet 0.9.0 → 0.11.0

package/dist/index.d.cts

@@ -2,6 +2,8 @@ import { ForwardRefExoticComponent } from 'react';
 import { ProfilerOnRenderCallback } from 'react';
 import { ReactNode } from 'react';
 import { RefAttributes } from 'react';
+import { ScrollBarTapCircleOptions } from '@aiquants/virtualscroll';
+import { TapScrollCircleRenderProps } from '@aiquants/virtualscroll';
 
 /** Border colour when `CellBorder.color` is absent (a stated default, not a fallback). / 罫線色の宣言済み既定 (fallback ではなく仕様上の既定)。 */
 export declare const BORDER_DEFAULT_COLOR = "#000000";
@@ -402,7 +404,7 @@ export declare const columnNameToIndex: (name: string) => number;
  */
 export declare const CommentPopover: ({ ctx, labels }: CommentPopoverProps) => ReactNode;
 
-/** Comment thread context: the reply UI commits `[...current (with ids), { text }]`; `null` clears the thread. / コメントスレッド文脈: 返信 UI は `[...current (id つき), { text }]` を commit、null はスレッド消去。 */
+/** 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 declare type CommentPopoverContext = {
     kind: "comment";
     cell: CellCoord;
@@ -411,6 +413,7 @@ export declare type CommentPopoverContext = {
     commit: (next: readonly CellCommentInput[] | null) => void;
     close: () => void;
     rejected: boolean;
+    cellReadOnly?: boolean;
 };
 
 export declare type CommentPopoverProps = {
@@ -480,10 +483,12 @@ export declare const DEFAULT_HIGHLIGHT_COLORS: HighlightColors;
 
 /**
  * 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 declare const DEFAULT_LABELS: SpreadsheetLabels;
 
@@ -680,7 +685,7 @@ export declare type HtmlTableResult = {
  */
 export declare const LinkPopover: ({ ctx, labels }: LinkPopoverProps) => ReactNode;
 
-/** Hyperlink editor context: `url` on commit is a normalised href or null (clear); `canOpen` = onHyperlinkOpen declared. / ハイパーリンクエディタ文脈: commit の url は正規化済み href か null (消去)、canOpen = onHyperlinkOpen 宣言。 */
+/** 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 declare type LinkPopoverContext = {
     kind: "link";
     cell: CellCoord;
@@ -697,6 +702,7 @@ export declare type LinkPopoverContext = {
     canOpen: boolean;
     open: () => void;
     rejected: boolean;
+    cellReadOnly?: boolean;
 };
 
 export declare type LinkPopoverProps = {
@@ -796,7 +802,7 @@ export declare type NotEmptyCondition = {
  */
 export declare const NotePopover: ({ ctx, labels }: NotePopoverProps) => ReactNode;
 
-/** Note editor context (v0.8 §1.8). `current` undefined = no note yet; `commit(null)` clears. / note エディタ文脈。current undefined = ノートなし、commit(null) は消去。 */
+/** 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 declare type NotePopoverContext = {
     kind: "note";
     cell: CellCoord;
@@ -805,6 +811,7 @@ export declare type NotePopoverContext = {
     commit: (next: string | null) => void;
     close: () => void;
     rejected: boolean;
+    cellReadOnly?: boolean;
 };
 
 export declare type NotePopoverProps = {
@@ -1006,6 +1013,36 @@ export declare const rangeSize: (range: CellRange) => {
     cols: number;
 };
 
+/**
+ * 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 数ではない)。
+ */
+export declare 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;
+};
+
 /** Public custom cell renderer context (ADR-8). / 公開セルレンダラーの ctx (ADR-8)。 */
 export declare type RenderCellContext = {
     row: number;
@@ -1028,6 +1065,8 @@ export declare type ScalePoint = {
     value?: number;
 };
 
+export { ScrollBarTapCircleOptions }
+
 /**
  * Options for the programmatic {@link SpreadsheetHandle.scrollToCell} jump — the render-surface
  * pass-through of the engine's cell-targeted scroll (alignX uses start/end/center, alignY uses
@@ -1349,6 +1388,21 @@ export declare 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
@@ -1488,6 +1542,8 @@ export declare 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. / 返信入力欄のラベル。 */
@@ -1610,6 +1666,55 @@ export declare type SpreadsheetProps = {
      * frozenTrailingColumns の行双子。エンジン契約・取消シームは同文)。典型は固定合計行。
      */
     frozenTrailingRows?: number;
+    /**
+     * Tap-scroll circle tuning (v0.10 — the VirtualGrid `scrollBarOptions.tapScrollCircleOptions`
+     * engine-validated pass-through; LIVE prop): position and enable/disable of the touch
+     * tap-scroll circle. The engine's `resolveTapScrollCircleOptions` is the validation SSOT —
+     * undefined is the engine's declared absence signal (engine defaults), never a value
+     * fallback in this package.
+     * タップサークル調整 (v0.10 — VirtualGrid `scrollBarOptions.tapScrollCircleOptions` の
+     * エンジン検証素通し。ライブ prop): タッチのタップスクロールサークルの位置・有効 / 無効の
+     * 調整口。検証の SSOT はエンジンの `resolveTapScrollCircleOptions` — undefined はエンジン
+     * 宣言の不在信号 (エンジン既定) で、本パッケージでの値フォールバックなし。
+     */
+    tapScrollCircleOptions?: ScrollBarTapCircleOptions;
+    /**
+     * Row-axis overscan pass-through (the VirtualGrid `overscanRows` knob; LIVE prop): rows
+     * rendered beyond each vertical viewport edge. This slack is the only thing absorbing the
+     * engine's one-frame rendering-window lag during fast scrolling (the blank-band remedy —
+     * the slack in px is overscan × row height per edge). Undefined ⇒ the engine default (3).
+     * The engine clamps invalid values silently, so THIS surface owns the fail-fast: a
+     * non-integer or negative value throws a RangeError at render. Cost multiplies with the
+     * column axis (bounded by the engine cell cap).
+     * 行軸 overscan の素通し (VirtualGrid `overscanRows`。ライブ prop): 縦 viewport 端の外側へ
+     * 描画する行数。高速スクロール時の描画窓 1 フレーム遅れを吸収する唯一の余裕 (白帯対策 —
+     * 余裕 px は片端あたり overscan × 行高)。undefined はエンジン既定 (3)。エンジンは不正値を
+     * 無言クランプするため fail-fast は本層所有 — 非整数・負値は render 時 RangeError。費用は
+     * 列軸との積で増幅 (エンジンのセル上限で有界)。
+     */
+    overscanRows?: number;
+    /**
+     * Column-axis overscan pass-through (the VirtualGrid `overscanCols` knob; LIVE prop) — the
+     * column twin of `overscanRows`, same validation contract (non-negative integer or
+     * RangeError; undefined ⇒ engine default 3).
+     * 列軸 overscan の素通し (VirtualGrid `overscanCols`。ライブ prop) — `overscanRows` の
+     * 列双子。検証契約は同文 (非負整数、それ以外 RangeError。undefined ⇒ エンジン既定 3)。
+     */
+    overscanCols?: number;
+    /**
+     * Background layer rendered behind the scroll-band rows, inside the engine content element
+     * (the VirtualGrid `background` pass-through; LIVE prop). VIEWPORT-PINNED: the engine
+     * translates only its row wrapper, so this layer does NOT follow the scroll offset —
+     * periodic row ruling placed here slides against the real rows while scrolling. Suited to
+     * a static texture that reads as "content still arriving" in the overscan-exhausted band,
+     * not to row-aligned gridlines.
+     * スクロール帯行の背後・エンジンコンテンツ要素内に描画する背景レイヤー (VirtualGrid
+     * `background` の素通し。ライブ prop)。viewport 固定: エンジンが translate するのは行
+     * ラッパーだけで、この層はスクロール量に追従しない — 周期的な行罫線を置くとスクロール中に
+     * 実際の行へ対して滑る。overscan が尽きた帯で「まだ到着中」と読める静的テクスチャ向きで、
+     * 行整合の罫線には不向き。
+     */
+    background?: ReactNode;
     /**
      * Identity-stable contract (same as adapter): an inline arrow here defeats the CellView memo
      * and turns every host re-render into a full visible re-slice (~800 cells at 16k columns).
@@ -1672,6 +1777,39 @@ export declare type SpreadsheetProps = {
      * Escape は WCAG 2.1.2 のフォーカス脱出)。
      */
     onEditRejected?: (error: unknown, rejection: EditRejection) => void;
+    /**
+     * Read-only refusal notice (v0.10): fired once per refused gesture — the adapter was never
+     * called, so this is neither an EditRejection nor an operation limit. Never fired when the
+     * adapter does not declare `isCellReadOnly`; omit for silence.
+     * 読み取り専用拒否通知 (v0.10)。拒否されたジェスチャ毎に 1 回発火 — adapter は呼ばれて
+     * いないため EditRejection でも操作上限でもない。`isCellReadOnly` 未宣言では発火せず、
+     * 省略時は通知なし。
+     */
+    onReadOnlyRejected?: (rejection: ReadOnlyRejection) => void;
+    /**
+     * AT announcement text for a read-only refusal (v0.10), routed through the live region;
+     * omit for silence (no built-in strings). Inherits the announcement debounce + rAF collapse,
+     * which is what keeps autorepeat / IME refusal storms from spamming the live region.
+     * 読み取り専用拒否の AT 読み上げ文言 (v0.10) — live region 経由。省略で無音 (組み込み文言
+     * なし)。読み上げのデバウンス + rAF 合流を継承し、autorepeat / IME の拒否連打でも live
+     * region は溢れない。
+     */
+    formatReadOnlyAnnouncement?: (rejection: ReadOnlyRejection) => string;
+    /**
+     * Paste outcome summary (v0.10 plan §3.1): the menu channel mirrors `paste(options)`'s
+     * resolve value 1:1 (read refusals and the write-time re-gate included); the event channel
+     * fires once per gesture that reaches the paste pipeline — the drag-freeze consumption and a
+     * null `clipboardData` stay deliberately silent, and an empty grid attaches no listener at
+     * all. Cause-specific callbacks (`onClipboardUnavailable` / `onOperationRejected` /
+     * `onReadOnlyRejected`) fire FIRST — `"rejected"` can be the trailing summary of one of
+     * them. Omit = never fired.
+     * 貼り付け結果の要約 (v0.10 計画 §3.1)。menu チャネルは `paste(options)` の resolve 値の
+     * 1:1 鏡 (読み拒否・書込時再ゲート含む)、event チャネルは貼り付けパイプラインに到達した
+     * ゲスチャ毎 1 回 — ドラッグ凍結消費と `clipboardData` null は意図的無言、空グリッドは
+     * リスナ自体が無い。原因特定系 callback が先に発火し、`"rejected"` はその後追いの要約に
+     * なり得る。省略時は発火なし。
+     */
+    onPasteResolved?: (outcome: PasteOutcome, channel: ClipChannel) => void;
     /** Change notice for out-of-package writes (undo / collaboration); each increment repaints visible cells (§6.9-2). / パッケージ外経路のデータ変更通知。 */
     dataVersion?: number;
     /** Operation cell-count ceiling, default 100,000 (ADR-12). / 操作セル数上限。 */
@@ -1698,10 +1836,17 @@ export declare type SpreadsheetProps = {
      * AT announcement text for the active cell; omit for silence (no built-in strings). `text`
      * is the RAW canonical getCellText; `displayText` is what a sighted user sees (the
      * getCellFormat-formatted string — equals `text` when the cell has no format), so AT can
-     * hear "87.0%" for a cell whose raw value is "0.87".
+     * hear "87.0%" for a cell whose raw value is "0.87". `readOnly` (v0.10) is
+     * declaration-gated three-valued: the key is ABSENT when the adapter does not declare
+     * `isCellReadOnly` (payload byte-identical to v0.9), `false` = declared editable, `true` =
+     * declared read-only — the navigation-time read-only channel (DOM focus stays on the sink,
+     * so `aria-readonly` is inert during Arrow navigation).
      * AT 向け読み上げ文言 (省略で無音)。`text` は素の正準 getCellText、`displayText` は目視と同じ
      * 表示文字列 (getCellFormat 整形後 — 書式なしセルでは text と同値)。素値 "0.87" の表示
-     * "87.0%" をそのまま読み上げられる。
+     * "87.0%" をそのまま読み上げられる。`readOnly` (v0.10) は宣言ゲートの 3 値: `isCellReadOnly`
+     * 未宣言はキー自体なし (payload は v0.9 とバイト同一)、`false` = 宣言済み編集可、`true` =
+     * 宣言済み読み取り専用 — 矢印航行時の読み取り専用チャネル (フォーカスはシンク常駐のため
+     * `aria-readonly` は航行中の AT に届かない)。
      */
     formatCellAnnouncement?: (ctx: {
         row: number;
@@ -1709,6 +1854,7 @@ export declare type SpreadsheetProps = {
         text: string;
         displayText: string;
         columnName: string;
+        readOnly?: boolean;
     }) => string;
     /** AT announcement for the selection extent ("A1 to C3, 3 rows 3 cols"); omit for silence. / AT 向け選択範囲読み上げ。 */
     formatSelectionAnnouncement?: (ctx: {
@@ -1865,8 +2011,21 @@ export declare type SpreadsheetProps = {
 declare type SpreadsheetTestProps = {
     /** Test-only CellView re-render counter; never passed in production. / テスト専用カウンタ。 */
     __onCellRender?: ProfilerOnRenderCallback;
+    /**
+     * Test-only virtual-keyboard raise spy (v0.10 plan §6.4 / RC-G2t): called synchronously by
+     * the single `raiseVirtualKeyboard` funnel, so spy count ≡ raise executions — a React-batched
+     * raise-then-lower mutates no DOM (`inputmode` observer-blind) yet still counts. Never
+     * passed in production (zero calls when unset — the `__onCellRender` conduct).
+     * テスト専用の仮想キーボード招待スパイ (v0.10 計画 §6.4 / RC-G2t)。単一漏斗
+     * `raiseVirtualKeyboard` が同期で呼ぶため、計数 ≡ raise 実行 — React バッチの
+     * raise-then-lower は DOM 無変異 (`inputmode` の観測は盲目) でも計数には映る。production
+     * では渡さない (未指定 = 呼出しゼロ — `__onCellRender` と同じ品行)。
+     */
+    __onVirtualKeyboardRaise?: () => void;
 };
 
+export { TapScrollCircleRenderProps }
+
 /** Case-sensitive needle test on the raw text. / 素の text に対する大文字小文字区別の needle 判定。 */
 export declare type TextCondition = {
     type: "text";

package/dist/index.d.ts

@@ -2,6 +2,8 @@ import { ForwardRefExoticComponent } from 'react';
 import { ProfilerOnRenderCallback } from 'react';
 import { ReactNode } from 'react';
 import { RefAttributes } from 'react';
+import { ScrollBarTapCircleOptions } from '@aiquants/virtualscroll';
+import { TapScrollCircleRenderProps } from '@aiquants/virtualscroll';
 
 /** Border colour when `CellBorder.color` is absent (a stated default, not a fallback). / 罫線色の宣言済み既定 (fallback ではなく仕様上の既定)。 */
 export declare const BORDER_DEFAULT_COLOR = "#000000";
@@ -402,7 +404,7 @@ export declare const columnNameToIndex: (name: string) => number;
  */
 export declare const CommentPopover: ({ ctx, labels }: CommentPopoverProps) => ReactNode;
 
-/** Comment thread context: the reply UI commits `[...current (with ids), { text }]`; `null` clears the thread. / コメントスレッド文脈: 返信 UI は `[...current (id つき), { text }]` を commit、null はスレッド消去。 */
+/** 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 declare type CommentPopoverContext = {
     kind: "comment";
     cell: CellCoord;
@@ -411,6 +413,7 @@ export declare type CommentPopoverContext = {
     commit: (next: readonly CellCommentInput[] | null) => void;
     close: () => void;
     rejected: boolean;
+    cellReadOnly?: boolean;
 };
 
 export declare type CommentPopoverProps = {
@@ -480,10 +483,12 @@ export declare const DEFAULT_HIGHLIGHT_COLORS: HighlightColors;
 
 /**
  * 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 declare const DEFAULT_LABELS: SpreadsheetLabels;
 
@@ -680,7 +685,7 @@ export declare type HtmlTableResult = {
  */
 export declare const LinkPopover: ({ ctx, labels }: LinkPopoverProps) => ReactNode;
 
-/** Hyperlink editor context: `url` on commit is a normalised href or null (clear); `canOpen` = onHyperlinkOpen declared. / ハイパーリンクエディタ文脈: commit の url は正規化済み href か null (消去)、canOpen = onHyperlinkOpen 宣言。 */
+/** 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 declare type LinkPopoverContext = {
     kind: "link";
     cell: CellCoord;
@@ -697,6 +702,7 @@ export declare type LinkPopoverContext = {
     canOpen: boolean;
     open: () => void;
     rejected: boolean;
+    cellReadOnly?: boolean;
 };
 
 export declare type LinkPopoverProps = {
@@ -796,7 +802,7 @@ export declare type NotEmptyCondition = {
  */
 export declare const NotePopover: ({ ctx, labels }: NotePopoverProps) => ReactNode;
 
-/** Note editor context (v0.8 §1.8). `current` undefined = no note yet; `commit(null)` clears. / note エディタ文脈。current undefined = ノートなし、commit(null) は消去。 */
+/** 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 declare type NotePopoverContext = {
     kind: "note";
     cell: CellCoord;
@@ -805,6 +811,7 @@ export declare type NotePopoverContext = {
     commit: (next: string | null) => void;
     close: () => void;
     rejected: boolean;
+    cellReadOnly?: boolean;
 };
 
 export declare type NotePopoverProps = {
@@ -1006,6 +1013,36 @@ export declare const rangeSize: (range: CellRange) => {
     cols: number;
 };
 
+/**
+ * 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 数ではない)。
+ */
+export declare 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;
+};
+
 /** Public custom cell renderer context (ADR-8). / 公開セルレンダラーの ctx (ADR-8)。 */
 export declare type RenderCellContext = {
     row: number;
@@ -1028,6 +1065,8 @@ export declare type ScalePoint = {
     value?: number;
 };
 
+export { ScrollBarTapCircleOptions }
+
 /**
  * Options for the programmatic {@link SpreadsheetHandle.scrollToCell} jump — the render-surface
  * pass-through of the engine's cell-targeted scroll (alignX uses start/end/center, alignY uses
@@ -1349,6 +1388,21 @@ export declare 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
@@ -1488,6 +1542,8 @@ export declare 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. / 返信入力欄のラベル。 */
@@ -1610,6 +1666,55 @@ export declare type SpreadsheetProps = {
      * frozenTrailingColumns の行双子。エンジン契約・取消シームは同文)。典型は固定合計行。
      */
     frozenTrailingRows?: number;
+    /**
+     * Tap-scroll circle tuning (v0.10 — the VirtualGrid `scrollBarOptions.tapScrollCircleOptions`
+     * engine-validated pass-through; LIVE prop): position and enable/disable of the touch
+     * tap-scroll circle. The engine's `resolveTapScrollCircleOptions` is the validation SSOT —
+     * undefined is the engine's declared absence signal (engine defaults), never a value
+     * fallback in this package.
+     * タップサークル調整 (v0.10 — VirtualGrid `scrollBarOptions.tapScrollCircleOptions` の
+     * エンジン検証素通し。ライブ prop): タッチのタップスクロールサークルの位置・有効 / 無効の
+     * 調整口。検証の SSOT はエンジンの `resolveTapScrollCircleOptions` — undefined はエンジン
+     * 宣言の不在信号 (エンジン既定) で、本パッケージでの値フォールバックなし。
+     */
+    tapScrollCircleOptions?: ScrollBarTapCircleOptions;
+    /**
+     * Row-axis overscan pass-through (the VirtualGrid `overscanRows` knob; LIVE prop): rows
+     * rendered beyond each vertical viewport edge. This slack is the only thing absorbing the
+     * engine's one-frame rendering-window lag during fast scrolling (the blank-band remedy —
+     * the slack in px is overscan × row height per edge). Undefined ⇒ the engine default (3).
+     * The engine clamps invalid values silently, so THIS surface owns the fail-fast: a
+     * non-integer or negative value throws a RangeError at render. Cost multiplies with the
+     * column axis (bounded by the engine cell cap).
+     * 行軸 overscan の素通し (VirtualGrid `overscanRows`。ライブ prop): 縦 viewport 端の外側へ
+     * 描画する行数。高速スクロール時の描画窓 1 フレーム遅れを吸収する唯一の余裕 (白帯対策 —
+     * 余裕 px は片端あたり overscan × 行高)。undefined はエンジン既定 (3)。エンジンは不正値を
+     * 無言クランプするため fail-fast は本層所有 — 非整数・負値は render 時 RangeError。費用は
+     * 列軸との積で増幅 (エンジンのセル上限で有界)。
+     */
+    overscanRows?: number;
+    /**
+     * Column-axis overscan pass-through (the VirtualGrid `overscanCols` knob; LIVE prop) — the
+     * column twin of `overscanRows`, same validation contract (non-negative integer or
+     * RangeError; undefined ⇒ engine default 3).
+     * 列軸 overscan の素通し (VirtualGrid `overscanCols`。ライブ prop) — `overscanRows` の
+     * 列双子。検証契約は同文 (非負整数、それ以外 RangeError。undefined ⇒ エンジン既定 3)。
+     */
+    overscanCols?: number;
+    /**
+     * Background layer rendered behind the scroll-band rows, inside the engine content element
+     * (the VirtualGrid `background` pass-through; LIVE prop). VIEWPORT-PINNED: the engine
+     * translates only its row wrapper, so this layer does NOT follow the scroll offset —
+     * periodic row ruling placed here slides against the real rows while scrolling. Suited to
+     * a static texture that reads as "content still arriving" in the overscan-exhausted band,
+     * not to row-aligned gridlines.
+     * スクロール帯行の背後・エンジンコンテンツ要素内に描画する背景レイヤー (VirtualGrid
+     * `background` の素通し。ライブ prop)。viewport 固定: エンジンが translate するのは行
+     * ラッパーだけで、この層はスクロール量に追従しない — 周期的な行罫線を置くとスクロール中に
+     * 実際の行へ対して滑る。overscan が尽きた帯で「まだ到着中」と読める静的テクスチャ向きで、
+     * 行整合の罫線には不向き。
+     */
+    background?: ReactNode;
     /**
      * Identity-stable contract (same as adapter): an inline arrow here defeats the CellView memo
      * and turns every host re-render into a full visible re-slice (~800 cells at 16k columns).
@@ -1672,6 +1777,39 @@ export declare type SpreadsheetProps = {
      * Escape は WCAG 2.1.2 のフォーカス脱出)。
      */
     onEditRejected?: (error: unknown, rejection: EditRejection) => void;
+    /**
+     * Read-only refusal notice (v0.10): fired once per refused gesture — the adapter was never
+     * called, so this is neither an EditRejection nor an operation limit. Never fired when the
+     * adapter does not declare `isCellReadOnly`; omit for silence.
+     * 読み取り専用拒否通知 (v0.10)。拒否されたジェスチャ毎に 1 回発火 — adapter は呼ばれて
+     * いないため EditRejection でも操作上限でもない。`isCellReadOnly` 未宣言では発火せず、
+     * 省略時は通知なし。
+     */
+    onReadOnlyRejected?: (rejection: ReadOnlyRejection) => void;
+    /**
+     * AT announcement text for a read-only refusal (v0.10), routed through the live region;
+     * omit for silence (no built-in strings). Inherits the announcement debounce + rAF collapse,
+     * which is what keeps autorepeat / IME refusal storms from spamming the live region.
+     * 読み取り専用拒否の AT 読み上げ文言 (v0.10) — live region 経由。省略で無音 (組み込み文言
+     * なし)。読み上げのデバウンス + rAF 合流を継承し、autorepeat / IME の拒否連打でも live
+     * region は溢れない。
+     */
+    formatReadOnlyAnnouncement?: (rejection: ReadOnlyRejection) => string;
+    /**
+     * Paste outcome summary (v0.10 plan §3.1): the menu channel mirrors `paste(options)`'s
+     * resolve value 1:1 (read refusals and the write-time re-gate included); the event channel
+     * fires once per gesture that reaches the paste pipeline — the drag-freeze consumption and a
+     * null `clipboardData` stay deliberately silent, and an empty grid attaches no listener at
+     * all. Cause-specific callbacks (`onClipboardUnavailable` / `onOperationRejected` /
+     * `onReadOnlyRejected`) fire FIRST — `"rejected"` can be the trailing summary of one of
+     * them. Omit = never fired.
+     * 貼り付け結果の要約 (v0.10 計画 §3.1)。menu チャネルは `paste(options)` の resolve 値の
+     * 1:1 鏡 (読み拒否・書込時再ゲート含む)、event チャネルは貼り付けパイプラインに到達した
+     * ゲスチャ毎 1 回 — ドラッグ凍結消費と `clipboardData` null は意図的無言、空グリッドは
+     * リスナ自体が無い。原因特定系 callback が先に発火し、`"rejected"` はその後追いの要約に
+     * なり得る。省略時は発火なし。
+     */
+    onPasteResolved?: (outcome: PasteOutcome, channel: ClipChannel) => void;
     /** Change notice for out-of-package writes (undo / collaboration); each increment repaints visible cells (§6.9-2). / パッケージ外経路のデータ変更通知。 */
     dataVersion?: number;
     /** Operation cell-count ceiling, default 100,000 (ADR-12). / 操作セル数上限。 */
@@ -1698,10 +1836,17 @@ export declare type SpreadsheetProps = {
      * AT announcement text for the active cell; omit for silence (no built-in strings). `text`
      * is the RAW canonical getCellText; `displayText` is what a sighted user sees (the
      * getCellFormat-formatted string — equals `text` when the cell has no format), so AT can
-     * hear "87.0%" for a cell whose raw value is "0.87".
+     * hear "87.0%" for a cell whose raw value is "0.87". `readOnly` (v0.10) is
+     * declaration-gated three-valued: the key is ABSENT when the adapter does not declare
+     * `isCellReadOnly` (payload byte-identical to v0.9), `false` = declared editable, `true` =
+     * declared read-only — the navigation-time read-only channel (DOM focus stays on the sink,
+     * so `aria-readonly` is inert during Arrow navigation).
      * AT 向け読み上げ文言 (省略で無音)。`text` は素の正準 getCellText、`displayText` は目視と同じ
      * 表示文字列 (getCellFormat 整形後 — 書式なしセルでは text と同値)。素値 "0.87" の表示
-     * "87.0%" をそのまま読み上げられる。
+     * "87.0%" をそのまま読み上げられる。`readOnly` (v0.10) は宣言ゲートの 3 値: `isCellReadOnly`
+     * 未宣言はキー自体なし (payload は v0.9 とバイト同一)、`false` = 宣言済み編集可、`true` =
+     * 宣言済み読み取り専用 — 矢印航行時の読み取り専用チャネル (フォーカスはシンク常駐のため
+     * `aria-readonly` は航行中の AT に届かない)。
      */
     formatCellAnnouncement?: (ctx: {
         row: number;
@@ -1709,6 +1854,7 @@ export declare type SpreadsheetProps = {
         text: string;
         displayText: string;
         columnName: string;
+        readOnly?: boolean;
     }) => string;
     /** AT announcement for the selection extent ("A1 to C3, 3 rows 3 cols"); omit for silence. / AT 向け選択範囲読み上げ。 */
     formatSelectionAnnouncement?: (ctx: {
@@ -1865,8 +2011,21 @@ export declare type SpreadsheetProps = {
 declare type SpreadsheetTestProps = {
     /** Test-only CellView re-render counter; never passed in production. / テスト専用カウンタ。 */
     __onCellRender?: ProfilerOnRenderCallback;
+    /**
+     * Test-only virtual-keyboard raise spy (v0.10 plan §6.4 / RC-G2t): called synchronously by
+     * the single `raiseVirtualKeyboard` funnel, so spy count ≡ raise executions — a React-batched
+     * raise-then-lower mutates no DOM (`inputmode` observer-blind) yet still counts. Never
+     * passed in production (zero calls when unset — the `__onCellRender` conduct).
+     * テスト専用の仮想キーボード招待スパイ (v0.10 計画 §6.4 / RC-G2t)。単一漏斗
+     * `raiseVirtualKeyboard` が同期で呼ぶため、計数 ≡ raise 実行 — React バッチの
+     * raise-then-lower は DOM 無変異 (`inputmode` の観測は盲目) でも計数には映る。production
+     * では渡さない (未指定 = 呼出しゼロ — `__onCellRender` と同じ品行)。
+     */
+    __onVirtualKeyboardRaise?: () => void;
 };
 
+export { TapScrollCircleRenderProps }
+
 /** Case-sensitive needle test on the raw text. / 素の text に対する大文字小文字区別の needle 判定。 */
 export declare type TextCondition = {
     type: "text";