@tatamicks/core 0.3.2 → 1.0.1

package/dist/src/canvas.d.ts

@@ -0,0 +1,2523 @@
+/**
+ * @tatamicks/core/canvas - キャンバスサブパスエントリポイント
+ *
+ * ブロックレイヤー・インタラクションレイヤー・ウィジェットなど内部 canvas コンポーネントへのアクセスを提供する Advanced API。
+ *
+ * @remarks Advanced — これらは内部実装の詳細を公開する低レベル API です。
+ *
+ * Breaking changes が生じる可能性があります。
+ *
+ * @packageDocumentation
+ */
+
+import { ComponentType } from 'react';
+import { default as default_2 } from 'react';
+import { Dispatch } from 'react';
+import { FC } from 'react';
+import { ForwardRefExoticComponent } from 'react';
+import { JSX } from 'react/jsx-runtime';
+import { MemoExoticComponent } from 'react';
+import { NamedExoticComponent } from 'react';
+import { RefAttributes } from 'react';
+import { SetStateAction } from 'react';
+
+/**
+ * 登録済みアクションの実行および有効判定インターフェース。
+ *
+ * @remarks
+ * button ブロックのクリック時に呼び出される。
+ */
+declare interface ActionContext {
+    /** 指定 ID のアクションを実行する。 */
+    execute(actionId: BuiltinActionId | (string & {}), payload?: unknown): void;
+    /** 指定 ID のアクションが実行可能か返す。 */
+    isEnabled(actionId: BuiltinActionId | (string & {})): boolean;
+}
+
+/* Excluded from this release type: ActionHandler */
+
+/**
+ * アクション ID をキーとしたハンドラマップ。
+ *
+ * `useBookActionContext` に渡すことで {@link ActionContext} として組み立てられる。
+ */
+export declare type ActionHandlers = {
+    [K in BuiltinActionId]?: ActionHandler;
+} & {
+    [actionId: string]: ActionHandler | undefined;
+};
+
+/**
+ * 物理的な実寸を表す単位の配列（`fr` / `%` を除く）。
+ */
+export declare const ACTUAL_UNITS: readonly ["mm", "cm", "inch", "pt", "px"];
+
+/**
+ * 物理的な実寸を表す単位（`fr` / `%` を除く）。
+ */
+export declare type ActualUnit = (typeof ACTUAL_UNITS)[number];
+
+/**
+ * 配置プロパティの `PropDef`。
+ *
+ * @remarks
+ * **Canvas** — ブロックプラグイン実装時に `plugin.props` へ追加する。
+ */
+export declare const alignmentProp: {
+    kind: string;
+    defaultProps: {
+        horizontal: HorizontalAlign;
+        vertical: VerticalAlign;
+    };
+};
+
+/**
+ * ブロック内の水平・垂直配置を保持する Props。
+ */
+export declare interface AlignmentProps {
+    /** 水平配置 */
+    horizontal?: HorizontalAlign;
+    /** 垂直配置 */
+    vertical?: VerticalAlign;
+}
+
+/**
+ * 全単位の配列。
+ */
+export declare const ALL_UNITS: readonly ["mm", "cm", "fr", "inch", "pt", "px", "%"];
+
+/* Excluded from this release type: AnyBlockPlugin */
+
+/**
+ * 全ブロックに共通して存在する基底プロパティ。
+ *
+ * コンテナが alignment / padding を CSS に変換し、Renderer は意識しない。
+ */
+export declare interface BaseBlockProps extends AlignmentProps, PaddingProps {
+    /** 値の読み書き先 `BindingContext` のドットパス。バインディングを使わないブロックは省略可 */
+    binding?: string;
+}
+
+declare type BaseRenderer = ForwardRefExoticComponent<RendererProps<Record<string, Value>, Value> & RefAttributes<BlockRef>>;
+
+/**
+ * binding パスによる設定値の読み書きインターフェース。
+ *
+ * @remarks
+ * `HiddenBinding` の評価および button ブロックのアクション判定に使用される。
+ */
+declare interface BindingContext {
+    /**
+     * 指定パスの値を取得する。
+     *
+     * - パスが存在し値が `null` の場合: `null` を返す。
+     * - パスの値が未設定（未登録）の場合: `undefined` を返す。
+     *
+     * `extra` として渡す実装では、担当外のパスに対して `undefined` を返すことで
+     * 組み込みの BindingContext へのフォールバックを指示できる。
+     * 有効値として `null` を返す場合はフォールバックしない。
+     */
+    get(path: string): Value | undefined;
+    /** 指定パスに値を書き込む。 */
+    set(path: string, value: Value): void;
+}
+
+/**
+ * book 内のブロックを表すインターフェース。
+ *
+ * @remarks
+ * - `kind` はプラグインの登録 ID（`createPluginRegistry` に渡した `kind`）と対応する。
+ *
+ * - `props` の値解決順序: `block.props` → `page.blockDefaults?.[kind]` → `PropDef.defaultProps`
+ *
+ * - `id` はブック全体でユニークである必要がある。
+ *
+ * - `P` のジェネリクスは `Page.blocks: Block[]` に格納すると `Record<string, Value>` に消去される。
+ *
+ *   そのため `block.kind === "text"` のように `kind` で条件分岐しても TypeScript は `props` の型を絞り込まない。
+ *
+ *   props に型安全にアクセスするには `pluginRegistry[block.kind]?.validateProps(block.props)` を使用すること。
+ *
+ *   実行時の型保証は `BlockPlugin.validateProps` が担保している。
+ *
+ * - `P` に関数・クラスインスタンス・DOM 要素など非シリアライズ可能な値を含めると、JSON 保存時に値が消失する。
+ *
+ *   型パラメータ `P` は {@link SerializableRecord}（= `Record<string, Value | undefined>`）互換であること。
+ *
+ *   検証には `satisfies SerializableRecord` を使用すること。
+ */
+declare interface Block<P extends SerializableRecord = Record<string, Value>> {
+    /** ブロック ID */
+    id: string;
+    /** ブロック種別（プラグインの kind） */
+    kind: string;
+    /** ブロックの位置とサイズ */
+    layout: BlockRect;
+    /** ブロック固有のプロパティ（プラグインごとに内容が異なる） */
+    props: P;
+    /** ブロックのスタイル */
+    style?: BlockStyle;
+    /** ブロックの動作設定 */
+    behavior?: BlockBehavior;
+    /** ブロックの表示/非表示を制御する条件式 */
+    hiddenBinding?: HiddenBinding;
+    /**
+     * form モードで送信するデフォルト値。
+     *
+     * 設定されている場合、edit モードで自動で初期値として使用される。
+     */
+    initValue?: Value;
+}
+
+/**
+ * ブロックの動作設定。
+ *
+ * @remarks
+ * キーが存在する（`true`）場合に有効、`undefined` の場合は無効として扱う。
+ */
+declare interface BlockBehavior {
+    /**
+     * 読み取り専用フラグ。
+     *
+     * `NoteMode.VIEW` の強制読み取りとは独立して動作し、EDIT モードでも入力をブロックする。
+     */
+    readOnly?: true;
+    /**
+     * コンテンツ実測幅にブロックを伸縮させる。
+     *
+     * `paper.autoWidth` と組み合わせるとキャンバス幅も追従する。
+     */
+    widthFit?: true;
+    /**
+     * コンテンツ実測高さにブロックを伸縮させる。
+     *
+     * `paper.autoHeight` と組み合わせるとキャンバス高さも追従する。
+     */
+    heightFit?: true;
+}
+
+/**
+ * ユーザー設定の枠線を SVG で描画するコンポーネント。
+ *
+ * 枠線スタイルが未設定、または全辺が空の場合は `null` を返します。
+ *
+ * @remarks
+ * **Canvas** — {@link BlockLayer} のブロック枠線描画サブコンポーネント。
+ */
+export declare const BlockBorder: FC<BlockBorderProps>;
+
+/**
+ * `BlockBorder` コンポーネントへの props。
+ */
+export declare interface BlockBorderProps {
+    /** ブロックのサイズ（px）。 */
+    blockSizePx: BlockSizePx;
+    /** ユーザー設定の枠線スタイル。省略時は描画しない。 */
+    borderStyle?: BorderStyle;
+    /** z-index のベース値。 */
+    blockZIndex: number;
+    /** z-index のサブオフセット（既定値: `BLOCK_SUB_INDEX.BORDER`）。 */
+    subZIndex?: number;
+    /** `false` にすると枠線全体を非表示にする（既定値: `true`）。 */
+    visible?: boolean;
+    /** DPI 値。線幅の単位変換に使用する（既定値: `DEFAULT_DPI`）。 */
+    dpi?: number;
+}
+
+/**
+ * ブロックの背景を描画するコンポーネント。
+ *
+ * @remarks
+ * **Canvas** — {@link BlockLayer} のブロック背景描画サブコンポーネント。
+ */
+export declare const BlockCanvas: FC<BlockCanvasProps>;
+
+/**
+ * `BlockCanvas` コンポーネントへの props。
+ */
+export declare interface BlockCanvasProps {
+    /** ブロックのサイズ（px）。 */
+    blockSizePx: BlockSizePx;
+    /** z-index のベース値。 */
+    blockZIndex: number;
+    /** z-index のサブオフセット（既定値: `BLOCK_SUB_INDEX.BG`）。 */
+    subZIndex?: number;
+    /** 背景色（既定値: `"transparent"`）。 */
+    backgroundColor?: string;
+}
+
+/**
+ * ブロックの全構成要素を統合するコンテナコンポーネント。
+ *
+ * `ref` で {@link BlockRef} を取得できます。
+ *
+ * @remarks
+ * **Canvas** — {@link BlockLayer} の1ブロック統合コンテナ。
+ */
+export declare const BlockContainer: NamedExoticComponent<BlockContainerProps & RefAttributes<BlockRef>>;
+
+/**
+ * 1ブロック全体（背景・レンダラー・枠線・ガイド・バリデーション）をまとめるコンテナコンポーネント。
+ */
+export declare interface BlockContainerProps {
+    /** 対象ブロックデータ。 */
+    block: Block;
+    /** 解決済みプラグイン。 */
+    resolvedPlugin: ResolvedPlugin;
+    /** ブロックの位置とサイズ（px）。 */
+    blockRectPx: BlockRectPx;
+    /** z-index のベース値。 */
+    blockZIndex: number;
+    /** 表示モード（ビュー / フォーム / 編集）。 */
+    mode: NoteMode;
+    /** ブロックの現在値。 */
+    value: Value;
+    /** ブロックのデフォルト値設定。 */
+    blockDefaults?: BlockDefaults;
+    /** 値変更時のコールバック。 */
+    onValueChange?: (val: Value) => void;
+    /** フォーカス離脱時の値確定通知コールバック。 */
+    onBlur?: (value: Value) => void;
+    /** ガイド枠線を表示するか（既定値: `true`）。 */
+    showGuides?: boolean;
+    /** ユーザー設定枠線を表示するか（既定値: `true`）。 */
+    showBorder?: boolean;
+    /** デフォルトのガイド枠線スタイル。 */
+    defaultGuideBorder?: BorderStyle;
+    /** DPI 値（既定値: `DEFAULT_DPI`）。 */
+    dpi?: number;
+    /** ポインターイベントの通過設定（既定値: `"none"`）。 */
+    pointerEvents?: "auto" | "none";
+    /** バリデーションオーバーレイを表示するか（既定値: `false`）。 */
+    showValidation?: boolean;
+    /** バリデーションエラー一覧。 */
+    validationErrors?: ValidationError[];
+    /** ブロックの高さが動的に測定された際のコールバック。 */
+    onMeasureHeight?: (blockId: string, heightPx: number) => void;
+    /** ブロックの幅が動的に測定された際のコールバック。 */
+    onMeasureWidth?: (blockId: string, widthPx: number) => void;
+    /** フォーカス中のブロック ID。 */
+    focusedBlockId?: string;
+    /** 値バインディング用コンテキスト。 */
+    bindingContext?: BindingContext;
+    /** アクション実行用コンテキスト。 */
+    actionContext?: ActionContext;
+}
+
+/**
+ * ブロック種別ごとの共通デフォルトプロパティ。
+ *
+ * @remarks
+ * - キー: プラグインの kind（例: `"text"`, `"checkbox"`）
+ * - 値: プロパティの部分辞書。`block.props` にキーが存在しない場合に参照され、
+ *   それも存在しない場合は `PropDef.defaultProps` にフォールバックする
+ *
+ * @example
+ * ```ts
+ * const defaults: BlockDefaults = {
+ *   text: { fontFamily: "serif", verticalAlign: "center" },
+ *   checkbox: { horizontalAlign: "center" },
+ * };
+ * ```
+ */
+declare type BlockDefaults = Record<string, Record<string, Value>>;
+
+/**
+ * ブロック挿入 DnD で `dataTransfer` に格納するデータ。
+ */
+export declare interface BlockDragData {
+    /** 挿入するブロックの種別 ID。 */
+    kind: string;
+    /** デフォルトサイズ（グリッドセル数）。 */
+    defaultSize?: {
+        w: number;
+        h: number;
+    };
+}
+
+/**
+ * 編集ガイド用の薄い枠線を SVG で描画するコンポーネント。
+ *
+ * ユーザー設定枠線がない場合にレイアウト確認用として表示します。
+ *
+ * @remarks
+ * **Canvas** — {@link BlockLayer} のガイド枠線描画サブコンポーネント。
+ */
+export declare const BlockGuideBorder: FC<BlockGuideBorderProps>;
+
+/**
+ * `BlockGuideBorder` コンポーネントへの props。
+ */
+export declare interface BlockGuideBorderProps {
+    /** ブロックのサイズ（px）。 */
+    blockSizePx: BlockSizePx;
+    /** z-index のベース値。 */
+    blockZIndex: number;
+    /** z-index のサブオフセット（既定値: `BLOCK_SUB_INDEX.GUIDE`）。 */
+    subZIndex?: number;
+    /** 表示するガイド枠線スタイル（既定値: `DEFAULT_GUIDE_BORDER`）。 */
+    borderStyle?: BorderStyle;
+    /** `false` にするとガイド枠線全体を非表示にする（既定値: `true`）。 */
+    visible?: boolean;
+}
+
+/**
+ * ブロック一覧を描画するレイヤーコンポーネント。
+ *
+ * @remarks
+ * **Canvas** — {@link Note} 実装を担う低レベルブロックレンダリングレイヤー。
+ *
+ * 通常は {@link Note} を使用する。
+ */
+export declare const BlockLayer: MemoExoticComponent<({ blocks, pluginRegistry, mode, values, blockDefaults, selectedBlockIds, getBlockRectPx, onValueChange, onBlur, showGuides, showBorder, defaultGuideBorder, dpi, showValidation, validationErrors, onMeasureHeight, onMeasureWidth, focusedBlockId, bindingContext, actionContext, }: BlockLayerProps) => JSX.Element>;
+
+/**
+ * `BlockLayer` コンポーネントへの props。
+ */
+export declare interface BlockLayerProps {
+    /** 描画対象のブロック一覧。 */
+    blocks: Block[];
+    /** プラグインレジストリ。 */
+    pluginRegistry: PluginRegistry;
+    /** 表示モード。 */
+    mode: NoteMode;
+    /** ブロック ID → 現在値のマップ。 */
+    values: Record<string, Value>;
+    /** ブロックのデフォルト値設定。 */
+    blockDefaults?: BlockDefaults;
+    /** 選択中のブロック ID 一覧（既定値: `[]`）。 */
+    selectedBlockIds?: string[];
+    /** ブロックからキャンバス上の矩形座標（px）を返す関数。 */
+    getBlockRectPx: (block: Block) => BlockRectPx;
+    /** ブロックの値が変更されたときのコールバック。 */
+    onValueChange?: (blockId: string, value: Value) => void;
+    /** フォーカス離脱時の値確定通知コールバック。 */
+    onBlur?: (blockId: string, value: Value) => void;
+    /** ガイド枠線を表示するか（既定値: `true`）。 */
+    showGuides?: boolean;
+    /** ユーザー設定枠線を表示するか（既定値: `true`）。 */
+    showBorder?: boolean;
+    /** デフォルトのガイド枠線スタイル。 */
+    defaultGuideBorder?: BorderStyle;
+    /** DPI 値（既定値: `DEFAULT_DPI`）。 */
+    dpi?: number;
+    /** バリデーションオーバーレイを表示するか（既定値: `false`）。 */
+    showValidation?: boolean;
+    /** ブロック ID → バリデーションエラー一覧のマップ。 */
+    validationErrors?: Record<string, ValidationError[]>;
+    /** ブロックの高さが測定された際のコールバック。 */
+    onMeasureHeight?: (blockId: string, heightPx: number) => void;
+    /** ブロックの幅が測定された際のコールバック。 */
+    onMeasureWidth?: (blockId: string, widthPx: number) => void;
+    /** フォーカス中のブロック ID。 */
+    focusedBlockId?: string;
+    /** 値バインディング用コンテキスト。 */
+    bindingContext?: BindingContext;
+    /** アクション実行用コンテキスト。 */
+    actionContext?: ActionContext;
+}
+
+/**
+ * ブロックプラグインの定義。
+ *
+ * @remarks
+ * 型パラメータ `P` は JSON シリアライズ可能なプロパティのみを持つこと。
+ *
+ * 関数・クラスインスタンス・DOM 要素などの非 serializable な値を含めると、`book` を JSON 保存・復元した際に値が消失する。
+ *
+ * `P extends BaseBlockProps` は TypeScript 上の型エラーとならないため、非シリアライズ型を渡してもコンパイル時には検知されない。
+ *
+ * `P` の serializable 性を型レベルで検証するには `satisfies SerializableRecord` を使う。
+ *
+ * @example
+ * ```ts
+ * import type { SerializableRecord } from "@tatamicks/core";
+ *
+ * interface MyProps extends BaseBlockProps {
+ *   label: string;
+ *   count: number;
+ * }
+ * // ✅ シリアライズ可能か検証
+ * type _check = MyProps satisfies SerializableRecord;
+ * ```
+ */
+export declare interface BlockPlugin<P extends BaseBlockProps = BaseBlockProps, V = Value> {
+    /** プラグインの一意識別子。`block.kind` と対応する */
+    kind: string;
+    /** UI表示・アイコン・デフォルトサイズ等のメタ情報 */
+    meta: BlockPluginMeta;
+    /**
+     * ブロックを描画する `forwardRef` コンポーネント。
+     *
+     * `BlockRef.focus()` を `useImperativeHandle` で公開する必要がある。
+     *
+     * @example
+     * ```tsx
+     * const MyRenderer = forwardRef<BlockRef, RendererProps<MyProps, string>>(
+     *   ({ props, value, onChange, readOnly }, ref) => {
+     *     const inputRef = useRef<HTMLInputElement>(null);
+     *     useImperativeHandle(ref, () => ({ focus: () => inputRef.current?.focus() }));
+     *     return (
+     *       <input
+     *         ref={inputRef}
+     *         value={value ?? ""}
+     *         readOnly={readOnly}
+     *         onChange={(e) => onChange(e.target.value)}
+     *       />
+     *     );
+     *   },
+     * );
+     * ```
+     */
+    Renderer: ForwardRefExoticComponent<RendererProps<P, V> & RefAttributes<BlockRef>>;
+    /**
+     * プロパティパネルに表示するプロパティ定義一覧。
+     *
+     * `defaultProps` は配列順に合成され、同じキーは後ろの定義が優先される。
+     */
+    properties: PropDef[];
+    /**
+     * ストレージから読み込んだ生の `block.props` をサニタイズして型安全な Props に変換する。
+     *
+     * 省略時は raw オブジェクトをそのまま使用する。
+     */
+    validateProps?: (props: unknown) => P;
+    /**
+     * 外部 state から読み込んだ生の値をサニタイズする。
+     *
+     * `undefined` を返した場合は `block.initValue`、それもなければ raw 値にフォールバックする。
+     *
+     * フォールバックを指示する場合にのみ `undefined` を使い、`null` は正当な値として返せる。
+     *
+     * 省略時は raw 値をそのまま使用する。
+     *
+     * 戻り値 `V` は {@link Value} 互換型（JSON serializable）にすること。
+     *
+     * 日付は `Date` インスタンスではなく ISO 8601 文字列（例: `"2025-01-01"`）で表現する。
+     */
+    validateValue?: (value: unknown, props: P) => V | undefined;
+    /** 旧バージョンの props を現バージョンにマイグレーションする。`validateProps` の前に呼ばれる */
+    migrateProps?: (props: unknown) => Record<string, unknown>;
+}
+
+/**
+ * pluginのメタ情報（UI表示・アイコン・デフォルトサイズ）。
+ */
+export declare interface BlockPluginMeta {
+    /** UIに表示されるブロック名 */
+    displayName: string;
+    /** ブロックの説明文 */
+    description?: string;
+    /** ブロックのグリッド上のデフォルトサイズ */
+    defaultSize?: BlockSize;
+    /** ブロック選択パネルなどで使用するアイコンコンポーネント */
+    icon?: ComponentType<{
+        className?: string;
+    }>;
+}
+
+/**
+ * ブロックのグリッド上座標。
+ */
+declare interface BlockPos {
+    /** グリッド列の開始位置 (0-based) */
+    x: number;
+    /** グリッド行の開始位置 (0-based) */
+    y: number;
+}
+
+/**
+ * キャンバス上のブロック位置（px 単位）。
+ */
+declare interface BlockPosPx {
+    /** 左端の x 座標（px）。 */
+    left: number;
+    /** 上端の y 座標（px）。 */
+    top: number;
+}
+
+/**
+ * ブロックのグリッド上の位置とサイズを合わせた矩形領域。
+ */
+declare interface BlockRect extends BlockPos, BlockSize {
+}
+
+/**
+ * キャンバス上のブロック矩形（位置 + サイズ）（px 単位）。
+ */
+declare interface BlockRectPx extends BlockPosPx, BlockSizePx {
+}
+
+/**
+ * Rendererが forwardRef で外部に公開するインターフェース。
+ */
+export declare interface BlockRef {
+    focus: () => void;
+}
+
+/**
+ * プラグインの `Renderer` を実行し、コンテナ内にマウントするコンポーネント。
+ *
+ * `ref` で {@link BlockRef} を取得できます。
+ *
+ * @remarks
+ * **Canvas** — {@link BlockLayer} 内でプラグインレンダラーを実行するサブコンポーネント。
+ */
+export declare const BlockRenderer: NamedExoticComponent<BlockRendererProps & RefAttributes<BlockRef>>;
+
+/**
+ * `BlockRenderer` コンポーネントへの props。
+ */
+export declare interface BlockRendererProps {
+    /** ブロックの ID。 */
+    id: string;
+    /** 解決済みプラグイン。 */
+    resolvedPlugin: ResolvedPlugin;
+    /** プロパティマップ（プラグインデフォルトとユーザー値をマージ済み）。 */
+    props: Record<string, Value>;
+    /** ブロックの現在値。 */
+    value: Value;
+    /** 値変更時のコールバック。読み取り専用の場合は不要。 */
+    onChange?: (value: Value) => void;
+    /** `true` の場合、レンダラーは読み取り専用で入力を受け付けない。 */
+    readOnly: boolean;
+    /** 表示モード。 */
+    mode: NoteMode;
+    /** ブロックのサイズ（px）。 */
+    blockSizePx: BlockSizePx;
+    /** z-index のベース値。 */
+    blockZIndex: number;
+    /** z-index のサブオフセット（既定値: `BLOCK_SUB_INDEX.CONTENT`）。 */
+    subZIndex?: number;
+    /** 高さが動的に測定された際のコールバック。 */
+    onMeasureHeight?: (heightPx: number) => void;
+    /** 幅が動的に測定された際のコールバック。 */
+    onMeasureWidth?: (widthPx: number) => void;
+    /** フォーカス離脱時の値確定通知コールバック。 */
+    onBlur?: (value: Value) => void;
+    /** 値バインディング用コンテキスト。 */
+    bindingContext?: BindingContext;
+    /** アクション実行用コンテキスト。 */
+    actionContext?: ActionContext;
+}
+
+/**
+ * ブロックのグリッド上サイズ。
+ */
+declare interface BlockSize {
+    /** 列方向の幅（列数） */
+    w: number;
+    /** 行方向の高さ（行数） */
+    h: number;
+}
+
+/**
+ * キャンバス上のブロックサイズ（px 単位）。
+ */
+declare interface BlockSizePx {
+    /** 幅（px）。 */
+    width: number;
+    /** 高さ（px）。 */
+    height: number;
+}
+
+/**
+ * ブロックのスタイル定義。
+ */
+declare interface BlockStyle {
+    /** 背景色 (CSS color 値) */
+    backgroundColor?: string;
+    /** 枠線スタイル */
+    border?: BorderStyle;
+}
+
+/**
+ * 複数ページのフォームを表すスキーマ（Book）。
+ *
+ * @remarks
+ * - `pages` は最低1ページ必須（タプル型で空配列を禁止）
+ * - `Page.id` はオプション。index による識別がベースだが、並び替え・外部同期には `id` を利用する
+ * - `block.id` はブック全体でユニークであること
+ * - `paper` はブック全体で共通（全ページ同一の用紙設定を維持する）
+ */
+declare interface Book {
+    /** ブック全体の用紙設定。全ページ共通（PDF の慣習に従いページごとの変更は不可） */
+    paper: Paper;
+    /** ページ一覧（0-based インデックス順） */
+    pages: [Page, ...Page[]];
+    /** ブックレベルのメタデータ。例: `{ title: "月次業務報告書", version: "2" }` */
+    metaData?: Record<string, Value>;
+}
+
+/**
+ * {@link useBookBindingContext} のオプション。
+ */
+export declare interface BookBindingContextOptions {
+    /**
+     * `grid.*` パスの解決対象ページインデックス。デフォルト: 0。
+     */
+    pageIdx?: number;
+    /**
+     * ユーザー定義の追加 BindingContext。
+     * 組み込みパスより優先して参照される。
+     * `get` が `undefined` を返した場合 / `set` が処理しなかった場合は組み込みにフォールバックする。
+     * 注意: `set` のフォールバック判定は `extra.get(path)` が `undefined` かどうかを基準にする。
+     */
+    extra?: BindingContext;
+}
+
+/**
+ * 枠線の幅に使用できる単位の配列。
+ */
+export declare const BORDER_UNITS: readonly ["px", "pt", "mm"];
+
+/**
+ * 四辺それぞれの枠線スタイル定義。省略した辺は枠線なし。
+ *
+ * `all` を指定した場合、各辺に個別指定がなければ `all` の値が全辺に適用される。
+ */
+declare interface BorderStyle {
+    top?: LineStyle;
+    right?: LineStyle;
+    bottom?: LineStyle;
+    left?: LineStyle;
+    /** 全辺共通スタイル。各辺に個別指定がない場合のフォールバック */
+    all?: LineStyle;
+}
+
+/**
+ * 枠線の幅に使用できる単位。
+ */
+declare type BorderUnit = (typeof BORDER_UNITS)[number];
+
+/**
+ * 組み込みアクション ID のユニオン型。
+ *
+ * `ActionContext.execute` / `ActionContext.isEnabled` の引数に指定したとき IDE の補完候補として表示される。
+ * カスタムアクション ID は任意の `string` として渡せる。
+ */
+declare type BuiltinActionId = "undo" | "redo" | "paste" | "delete" | "copy" | "duplicate" | "addPage" | "deletePage" | "selectBlocks" | "goToPage" | "updateBlocks";
+
+/* Excluded from this release type: ButtonAction */
+
+/**
+ * `buttonAction` prop 定義。
+ *
+ * @remarks
+ * **Canvas** — カスタムプラグイン専用。
+ */
+export declare const buttonActionProp: {
+    kind: string;
+    defaultProps: {
+        action: string;
+    };
+};
+
+/**
+ * ボタンクリック時のアクション設定 props。
+ */
+export declare interface ButtonActionProps {
+    /** クリック時のアクション。文字列の場合はパス評価、オブジェクトの場合は指定パスへ値をセットする。 */
+    action?: string | {
+        path: string;
+        value: Value;
+    };
+}
+
+/**
+ * ボタンブロックの props 型。
+ */
+export declare type ButtonBlockProps = BaseBlockProps & ButtonContentProps & ButtonActionProps;
+
+/**
+ * ボタンブロックの値型。ボタンは値を持たないため常に `null`。
+ *
+ * @remarks
+ * **Canvas** — カスタムプラグイン向けの型。
+ */
+export declare type ButtonBlockValue = null;
+
+/**
+ * `buttonContent` prop 定義。
+ *
+ * @remarks
+ * **Canvas** — カスタムプラグイン専用。
+ */
+export declare const buttonContentProp: {
+    kind: string;
+    defaultProps: {
+        label: string;
+        icon: string;
+        iconPath: string;
+        title: string;
+    };
+};
+
+/**
+ * ボタンの表示内容（ラベル・アイコン）props。
+ */
+export declare interface ButtonContentProps {
+    /** ボタンに表示するテキスト。 */
+    label?: string;
+    /** アイコン文字列（Unicode 絵文字等を `<span>` テキストとして表示）。 */
+    icon?: string;
+    /** SVG パスデータ。`icon` より優先される。 */
+    iconPath?: string;
+    /** ツールチップに表示するテキスト。 */
+    title?: string;
+}
+
+/**
+ * ボタンブロックのプラグイン定義。
+ *
+ * `kind: "button"` で登録され、クリックで `action` prop に定義したバインディング操作を実行する。
+ *
+ * @remarks
+ * **Canvas** — カスタムプラグインの実装例。
+ *
+ * 標準フォーム構築では `createPluginRegistry` に渡すだけで使用できる。
+ */
+export declare const ButtonPlugin: BlockPlugin<ButtonBlockProps, ButtonBlockValue>;
+
+/**
+ * ボタンブロックのレンダラーコンポーネント。
+ *
+ * `action` props に応じてクリック時にバインディング操作またはアクション実行を行う。
+ *
+ * @remarks
+ * **Canvas** — ButtonPlugin と組み合わせて使用する実装コンポーネント。
+ */
+export declare const ButtonRenderer: ForwardRefExoticComponent<RendererProps<ButtonBlockProps, null> & RefAttributes<BlockRef>>;
+
+/**
+ * チェックボックスブロックの props 型。
+ */
+export declare type CheckboxBlockProps = BaseBlockProps & RequiredProps & CheckboxStyleProps;
+
+/**
+ * チェックボックスブロックの値型。
+ */
+export declare type CheckboxBlockValue = boolean;
+
+/**
+ * チェックボックスブロックのレンダラーコンポーネント。
+ *
+ * `value`（`boolean`）のトグル操作をし、SVG ビジュアルでチェック状態を表示する。
+ */
+export declare const CheckboxRenderer: ForwardRefExoticComponent<RendererProps<CheckboxBlockProps, boolean> & RefAttributes<BlockRef>>;
+
+/**
+ * チェックボックスの外観カスタマイズ設定。
+ */
+export declare interface CheckboxStyleConfig {
+    /** チェックボックス全体のサイズ。 */
+    checkboxSize?: Dimension;
+    /** 枠の太さ。 */
+    borderWidth?: Dimension;
+    /** 枠の色。 */
+    borderColor?: string;
+    /** チェックマークの線の太さ。 */
+    checkWidth?: Dimension;
+    /** チェックマークの色。 */
+    checkColor?: string;
+    /** 未チェック時の背景色。 */
+    backgroundColor?: string;
+    /** チェック時の背景色。 */
+    checkedBackgroundColor?: string;
+}
+
+/**
+ * `checkboxStyle` prop 定義。チェックボックスの外観デフォルト値を含む。
+ */
+export declare const checkboxStyleProp: {
+    kind: string;
+    defaultProps: {
+        styleConfig: {
+            checkboxSize: {
+                value: number;
+                unit: string;
+            };
+            borderWidth: {
+                value: number;
+                unit: string;
+            };
+            borderColor: string;
+            checkWidth: {
+                value: number;
+                unit: string;
+            };
+            checkColor: string;
+            backgroundColor: string;
+            checkedBackgroundColor: string;
+        };
+    };
+};
+
+/**
+ * チェックボックスの外観カスタマイズ props。
+ */
+export declare interface CheckboxStyleProps {
+    /** 外観カスタマイズ設定。 */
+    styleConfig?: CheckboxStyleConfig;
+}
+
+/**
+ * デフォルトの DPI 値。
+ *
+ * CSS の基準解像度である 96dpi を採用している。
+ */
+export declare const DEFAULT_DPI = 96;
+
+/**
+ * ユーザー設定枠線が未設定のブロックに適用するデフォルトのガイド枠線スタイル。
+ *
+ * @remarks
+ * **Canvas** — {@link BlockGuideBorder} のデフォルト枠線スタイル。
+ */
+export declare const DEFAULT_GUIDE_BORDER: BorderStyle;
+
+/**
+ * 数値と単位の組み合わせ。
+ */
+declare interface Dimension<U extends Unit = Unit> {
+    /** 数値 */
+    value: number;
+    /** 単位 */
+    unit: U;
+}
+
+/**
+ * Dimension<PaperUnit> バインディング用の 2 列入力 atom widget。
+ *
+ * @remarks
+ * **Canvas** — カスタムシェル構築専用。
+ *
+ * 列 0 (1fr): 数値入力テキストブロック → `{binding}.value`
+ *
+ * 列 1 (15mm): 単位 select ブロック   → `{binding}.unit`
+ *
+ * binding には Dimension のルートパス（例: "paper.size.width"）を渡す。
+ *
+ * autoWidth: true により widget 自体もコンテナ幅いっぱいに広がる。
+ *
+ * @example
+ * ```ts
+ * // NoteBlock として使う場合
+ * {
+ *   id: "width-input",
+ *   kind: "note",
+ *   layout: { x: 0, y: 0, w: 5, h: 2 },
+ *   props: dimensionInputWidget("paper.size.width"),
+ * }
+ * ```
+ */
+export declare function dimensionInputWidget(binding: string): NoteBlockProps;
+
+/**
+ * {@link Dimension} オブジェクトを寸法文字列（例: `"210mm"`）に変換する。
+ */
+export declare function dimensionToString<U extends Unit>(dim: Dimension<U>): string;
+
+/**
+ * ドラッグ中の詳細状態
+ *
+ * @remarks
+ * **Canvas** — {@link InteractionLayer} のドラッグ中状態型。
+ */
+export declare interface DraggingState {
+    type: DragType;
+    blockIds: string[];
+    startGrid: {
+        col: number;
+        row: number;
+    };
+    currentGrid: {
+        col: number;
+        row: number;
+    };
+    /** マウスの現在座標 (px, キャンバス相対)。キャンバス外ゴースト表示用 */
+    currentMousePx?: {
+        x: number;
+        y: number;
+    };
+    /** リサイズ用ハンドル方向 */
+    handle?: ResizeHandle;
+    /** 挿入用: プラグイン種別 */
+    pluginKind?: string;
+    /** 挿入用: デフォルトサイズ */
+    defaultSize?: {
+        w: number;
+        h: number;
+    };
+    /** キャンバス外フラグ */
+    isOutside?: boolean;
+}
+
+/**
+ * ドラッグ種別
+ *
+ * @remarks
+ * **Canvas** — {@link InteractionLayer} のドラッグ種別。
+ */
+export declare enum DragType {
+    MOVE = "move",
+    RESIZE = "resize",
+    INSERT = "insert"
+}
+
+/**
+ * チェックボックス用バリデーション。
+ *
+ * エラーがなければ空配列を返す。
+ */
+export declare function evaluateCheckboxValidation(schema: RequiredSchema, value: boolean | undefined): ValidationError[];
+
+/**
+ * `ValidationSchema` の設定値と実際の値を照合し、違反しているエラーを返す。
+ *
+ * エラーがなければ空配列を返す。
+ */
+export declare function evaluateValidation(schema: ValidationSchema, value: string | undefined): ValidationError[];
+
+/**
+ * ボタンの `action` 設定に応じてクリック時の処理を実行する。
+ *
+ * - 文字列 action: `actionContext.execute` を呼び出す
+ * - オブジェクト action: `bindingContext.set` で指定パスに値をセットする
+ * - どちらでもない場合: `onChange(null)` を呼び出す
+ *
+ * @remarks
+ * **Canvas** — カスタムプラグイン実装者向け
+ */
+export declare function executeButtonAction(action: ButtonAction, { actionContext, bindingContext, onChange }: ExecuteContext): void;
+
+/* Excluded from this release type: ExecuteContext */
+
+/**
+ * フォントサイズに使用できる単位の配列。
+ */
+export declare const FONT_UNITS: readonly ["pt", "px", "mm"];
+
+/**
+ * フォントスタイルプロパティの `PropDef`。
+ *
+ * @remarks
+ * **Canvas** — ブロックプラグイン実装時に `plugin.props` へ追加する。
+ */
+export declare const fontStyleProp: {
+    kind: string;
+    defaultProps: {
+        fontFamily: string;
+        fontSize: {
+            value: number;
+            unit: string;
+        };
+        color: string;
+        fontWeight: false;
+        italic: false;
+        underline: false;
+        lineThrough: false;
+    };
+};
+
+/**
+ * ブロック内のフォントスタイルを保持する Props。
+ */
+export declare interface FontStyleProps {
+    /** フォントファミリー */
+    fontFamily?: string;
+    /** フォントサイズ */
+    fontSize?: Dimension<FontUnit>;
+    /** 文字色（CSS カラー値） */
+    color?: string;
+    /** `true` のとき太字 */
+    fontWeight?: boolean;
+    /** `true` のときイタリック */
+    italic?: boolean;
+    /** `true` のとき下線 */
+    underline?: boolean;
+    /** `true` のとき取り消し線 */
+    lineThrough?: boolean;
+}
+
+/**
+ * フォントサイズに使用できる単位。
+ */
+export declare type FontUnit = (typeof FONT_UNITS)[number];
+
+/**
+ * ボタンの `action` がアクティブ状態か（トグル選択中か）を返す。
+ *
+ * オブジェクト形式の action でバインディング値と一致する場合に `true` を返す。
+ *
+ * @remarks
+ * **Canvas** — カスタムプラグイン実装者向け
+ */
+export declare function getButtonActionActive(action: ButtonAction, bindingContext: BindingContext | undefined): boolean;
+
+/**
+ * `InteractionState` から現在モードを導出する
+ *
+ * @remarks
+ * **Canvas** — {@link InteractionState} から動作モードを導出するユーティリティ。
+ */
+export declare function getInteractionMode(state: InteractionState): InteractionMode;
+
+/**
+ * プリセット用紙サイズの対応寸法を mm 単位で返す。
+ *
+ * `orientation` が `true` のとき横向き（幅と高さを入れ替え）。
+ */
+export declare function getPaperSize(preset: Exclude<PaperSizePreset, PaperSizePreset.CUSTOM>, orientation: boolean): {
+    width: number;
+    height: number;
+};
+
+/**
+ * ページのグリッド定義。
+ *
+ * @remarks
+ * `cols` / `rows` を省略した列/行は全て 1fr 等分割として扱われる。
+ */
+declare interface Grid {
+    /** 列数 */
+    colCount: number;
+    /** 行数 */
+    rowCount: number;
+    /** 列のサイズ定義マップ（インデックス → Dimension）。省略時は全列 1fr。 */
+    cols?: Record<number, Dimension<GridUnit>>;
+    /** 行のサイズ定義マップ（インデックス → Dimension）。省略時は全行 1fr。 */
+    rows?: Record<number, Dimension<GridUnit>>;
+}
+
+/**
+ * グリッドの列・行サイズに使用できる単位の配列。
+ */
+export declare const GRID_UNITS: readonly ["mm", "cm", "fr", "inch", "pt", "px"];
+
+/**
+ * グリッド列数 atom widget。
+ *
+ * @remarks
+ * **Canvas** — カスタムシェル構築専用。
+ *
+ * 3 列 × 1 行: [列数ラベル][数値入力][stepper]
+ *
+ * binding: `grid.colCount`
+ */
+export declare const gridColCountWidget: WidgetDef;
+
+/**
+ * グリッド行数 atom widget。
+ *
+ * @remarks
+ * **Canvas** — カスタムシェル構築専用。
+ *
+ * 3 列 × 1 行: [行数ラベル][数値入力][stepper]
+ *
+ * binding: `grid.rowCount`
+ */
+export declare const gridRowCountWidget: WidgetDef;
+
+/**
+ * グリッドの列・行サイズに使用できる単位（`fr` を含む）。
+ */
+declare type GridUnit = (typeof GRID_UNITS)[number];
+
+/**
+ * `block.props` がバリデーションルールを持つかどうかを判定する型ガード。
+ */
+export declare function hasValidationRule(props: unknown): props is ValidationSchema;
+
+/**
+ * ブロックの表示/非表示を binding 値で制御する条件式。
+ *
+ * - `string` — 指定パスの値が truthy のとき非表示
+ *
+ * - `{ path, eq }` — 指定パスの値が `eq` と等しいとき非表示
+ *
+ * - `{ path, neq }` — 指定パスの値が `neq` と等しくないとき非表示
+ *
+ * `eq` / `neq` は `===` による参照比較を行うため、オブジェクト・配列を指定しても期待通りに動作しない。
+ *
+ * そのため `Value` からオブジェクト・配列変形を除いた `Exclude<Value, Value[] | readonly Value[] | { [key: string]: Value }>` に制限している。
+ */
+export declare type HiddenBinding = string | {
+    path: string;
+    /**
+     * `===` で比較するためプリミティブ値のみ有効。
+     *
+     * `Value` からオブジェクト・配列を除いた型。
+     */
+    eq: Exclude<Value, Value[] | readonly Value[] | {
+        [key: string]: Value;
+    }>;
+    /** `eq` と同時指定不可 */
+    neq?: never;
+} | {
+    path: string;
+    /**
+     * `===` で比較するためプリミティブ値のみ有効。
+     *
+     * `Value` からオブジェクト・配列を除いた型。
+     */
+    neq: Exclude<Value, Value[] | readonly Value[] | {
+        [key: string]: Value;
+    }>;
+    /** `neq` と同時指定不可 */
+    eq?: never;
+};
+
+/**
+ * ブロック内の水平配置。
+ */
+export declare enum HorizontalAlign {
+    left = "left",
+    center = "center",
+    right = "right"
+}
+
+/**
+ * テキスト入力の HTML `input[type]` 属性値。バリデーション・キーボードの振る舞いに影響する。
+ */
+export declare enum InputType {
+    text = "text",
+    number = "number",
+    email = "email",
+    tel = "tel",
+    url = "url",
+    date = "date",
+    password = "password"
+}
+
+/**
+ * ブロックの移動・リサイズ・挿入・編集のインタラクションを集約した全体制御レイヤーコンポーネント。
+ *
+ * @remarks
+ * **Canvas** — {@link Note} 実装を担う低レベルインタラクションレイヤー。
+ *
+ * 通常は {@link Note} を使用する。
+ */
+export declare const InteractionLayer: MemoExoticComponent<({ page, pluginRegistry, gridLength, blockDefaults, getBlockRectPx, getColIndex, getRowIndex, state, onStateChange, selectedBlockIds, onSelectionChange, onPageChange, actionContext, bindingContext, scale, className, selectionStyle, }: InteractionLayerProps) => JSX.Element>;
+
+/**
+ * `InteractionLayer` コンポーネントへの props。
+ */
+export declare interface InteractionLayerProps {
+    /** 描画対象のページデータ。 */
+    page: Page;
+    /** プラグインレジストリ。 */
+    pluginRegistry: PluginRegistry;
+    /** グリッドの列数・行数。 */
+    gridLength: {
+        cols: number;
+        rows: number;
+    };
+    /** ブロックのデフォルト値設定。 */
+    blockDefaults?: BlockDefaults;
+    /** ブロックからキャンバス上の矩形座標（px）を返す関数。 */
+    getBlockRectPx: (block: Block) => BlockRectPx;
+    /** x 座標（px）からグリッド列インデックスを返す関数。 */
+    getColIndex: (px: number) => number;
+    /** y 座標（px）からグリッド行インデックスを返す関数。 */
+    getRowIndex: (px: number) => number;
+    /** インタラクション状態（controlled）。 */
+    state: InteractionState;
+    /** 状態変更時のコールバック。 */
+    onStateChange: (state: InteractionState) => void;
+    /** 選択中のブロック ID 一覧（controlled）。 */
+    selectedBlockIds: string[];
+    /** 選択変更時のコールバック。 */
+    onSelectionChange: OnSelectionChange;
+    /** ページ変更（ブロック追加・削除・移動など）時のコールバック。 */
+    onPageChange: (page: Page, options?: {
+        mergeKey?: string;
+        noTimeWindow?: boolean;
+    }) => void;
+    /** アクション実行用コンテキスト（undo/redo など）。 */
+    actionContext: ActionContext;
+    /** 値バインディング用コンテキスト。 */
+    bindingContext?: BindingContext;
+    /** キャンバスのスケール倍率（既定値: `1.0`）。 */
+    scale?: number;
+    /** ルート要素の CSS クラス名。 */
+    className?: string;
+    /** 選択枠線のスタイル。 */
+    selectionStyle?: BorderStyle;
+}
+
+/**
+ * インタラクションモード（dragging/editingBlockId から導出）
+ *
+ * @remarks
+ * **Canvas** — {@link InteractionLayer} の動作モード列挙型。
+ */
+export declare enum InteractionMode {
+    IDLE = "idle",
+    PRESSING = "pressing",
+    DRAGGING = "dragging",
+    INSERT = "insert",
+    EDITING = "editing"
+}
+
+/**
+ * インタラクション状態（外部で管理する controlled state）
+ *
+ * - 選択状態 (`selectedBlockIds`) は外部で管理されるため含まない
+ * - モード (`InteractionMode`) は `editingBlockId` と `dragging` から導出する
+ *
+ * @remarks
+ * **Canvas** — {@link InteractionLayer} に渡す制御状態型。
+ */
+export declare interface InteractionState {
+    /** 編集中ブロックID。null = 非編集 */
+    editingBlockId: string | null;
+    /** ドラッグ中状態 */
+    dragging?: DraggingState;
+}
+
+/**
+ * ボタンの `action` が現在有効か（クリック可能状態か）を返す。
+ *
+ * @remarks
+ * **Canvas** — カスタムプラグイン実装者向け
+ */
+export declare function isButtonActionEnabled(action: ButtonAction, actionContext: ActionContext | undefined): boolean;
+
+/**
+ * 値が {@link Value} 型かどうかを判定する型ガード。
+ *
+ * `null`・プリミティブ（文字列・数値・ブールアン）・プレインオブジェクト・配列を再帰的に認め、
+ * それ以外は `false` を返す。
+ */
+export declare function isValue(v: unknown): v is Value;
+
+/**
+ * 線のスタイル定義（色・幅・種別）。
+ */
+declare interface LineStyle {
+    /** CSS カラー値 */
+    color: string;
+    /** 線の幅 */
+    width: Dimension<BorderUnit>;
+    /** 線の種別 */
+    type: LineType;
+}
+
+/**
+ * 枠線・区切り線に適用するスタイル種別。
+ */
+declare enum LineType {
+    /** 実線 */
+    SOLID = "solid",
+    /** 破線 */
+    DASHED = "dashed",
+    /** 点線 */
+    DOTTED = "dotted"
+}
+
+/**
+ * マージン設定 compound widget（3 行・行 widget 構成）。
+ *
+ * @remarks
+ * **Canvas** — カスタムシェル構築専用。
+ *
+ * - 行 0（常に表示）: 一括 checkbox
+ *   + 上マージン入力（個別時） ← hiddenBinding: "margin.bulk"
+ *   + 全辺共通マージン入力（一括時） ← hiddenBinding: { path: "margin.bulk", neq: true }
+ * - 行 1（個別時）: 左・右マージン  ← hiddenBinding: "margin.bulk"
+ * - 行 2（個別時・末尾）: 下マージン ← hiddenBinding: "margin.bulk"
+ *
+ * binding:
+ * - `margin.bulk` / `margin.all` / `margin.top` / `margin.left` / `margin.right` / `margin.bottom`
+ */
+export declare const marginSettingsWidget: WidgetDef;
+
+/**
+ * ノートブロックのプラグイン定義。
+ *
+ * `kind: "note"` で登録され、Book を内包して別のグリッドをブロック内にレンダリングする。
+ *
+ * @remarks
+ * **Canvas** — 入れ子グリッドユースケース向けのプラグイン。
+ *
+ * 標準フォーム構築では `createPluginRegistry` に渡すだけで使用できる。
+ */
+export declare const NoteBlockPlugin: BlockPlugin<NoteBlockProps, NoteBlockValue>;
+
+/**
+ * ノートブロックの props 型。Book を内包して入れ子グリッドを実現する。
+ *
+ * @remarks
+ * **Canvas** — 入れ子グリッド構築向けの型。
+ *
+ * 一般的なフォーム構築では直接参照することは少ない。
+ */
+export declare interface NoteBlockProps extends BaseBlockProps {
+    /** ネストして表示する内包 Book。 */
+    book: Book;
+    /** 内包 Book で表示するページインデックス。省略時は 0。 */
+    pageIdx?: number;
+}
+
+/**
+ * ノートブロックのレンダラーコンポーネント。
+ *
+ * Book を内包し、ブロックのサイズに合わせてスケールしてグリッドをレンダリングする。
+ *
+ * @remarks
+ * **Canvas** — `NoteBlockPlugin` と組み合わせて使用する実装コンポーネント。
+ */
+export declare const NoteBlockRenderer: ForwardRefExoticComponent<RendererProps<NoteBlockProps, null> & RefAttributes<BlockRef>>;
+
+/**
+ * ノートブロックの値型。ノートブロックは値を持たないため常に `null`。
+ *
+ * @remarks
+ * **Canvas** — 入れ子グリッド構築向けの型。
+ */
+export declare type NoteBlockValue = null;
+
+/**
+ * Note の表示・編集モード。
+ */
+declare enum NoteMode {
+    /**
+     * ブロックの配置・サイズ変更、グリッド設定、`initValue`（初期値）の設定が可能。
+     *
+     * 入力コントロールは動作するが、値はセッション内のみ保持される（永続化されない）。
+     */
+    FORM = "Form",
+    /**
+     * ブロックの値を入力・編集できる。
+     *
+     * レイアウトや `initValue` は変更不可。
+     */
+    EDIT = "Edit",
+    /**
+     * すべて読み取り専用。入力コントロールは無効。
+     *
+     * `showValidation` によるバリデーション結果の表示が有効。
+     */
+    VIEW = "View"
+}
+
+/**
+ * TextBlock を数値入力専用設定にしたブロック定義ヘルパー。
+ *
+ * @remarks
+ * **Canvas** — カスタムシェル構築向レイアウトヘルパー。
+ *
+ * binding には数値を保持するパス（例: "paper.size.width.value"）を渡す。
+ *
+ * 返り値のレイアウトはデフォルト `{ x:0, y:0, w:1, h:1 }` のため、
+ * 複合 widget 内で spread して上書きすること。
+ *
+ * @example
+ * ```ts
+ * {
+ *   ...numberInputBlock("width-value", "paper.size.width.value"),
+ *   layout: { x: 0, y: 0, w: 2, h: 1 },
+ * }
+ * ```
+ */
+export declare function numberInputBlock(id: string, binding: string): Block;
+
+/**
+ * Book 全体の変更通知（ブロック・グリッド・用紙変更を一本で扱う）。
+ *
+ * @remarks
+ * `options.mergeKey` を指定すると、同一キーの連続変更が履歴上でマージされる。
+ * `options.noTimeWindow` を `true` にすると 500ms の時間窓制限なしにマージされる（セッション型用）。
+ * ドラッグ中の連続更新やパネルのキー入力など、Undo を細分化したくない場面で使用する。
+ */
+export declare type OnBookChange = (book: Book, options?: {
+    mergeKey?: string;
+    noTimeWindow?: boolean;
+}) => void;
+
+/**
+ * ブロック選択状態の変更通知（FORM モードでの選択操作）。
+ */
+export declare type OnSelectionChange = (selectedIds: string[]) => void;
+
+/**
+ * values の変更通知（EDIT モードでの入力値変更）。
+ *
+ * 差分リスト形式で渡される。1 ブロック編集 → 1 要素の配列。
+ * `value` が `undefined` の場合はそのブロックの値を削除する。
+ *
+ * @example
+ * ```tsx
+ * onValuesChange={(changes) => {
+ *     setValues(prev => {
+ *         const next = { ...prev };
+ *         for (const { id, value } of changes) {
+ *             if (value === undefined) delete next[id];
+ *             else next[id] = value;
+ *         }
+ *         return next;
+ *     });
+ * }}
+ * ```
+ */
+export declare type OnValuesChange = (changes: ValueChange[]) => void;
+
+/**
+ * パディングに使用できる単位の配列。
+ */
+export declare const PADDING_UNITS: readonly ["mm", "pt", "px", "%"];
+
+/**
+ * 余白プロパティの `PropDef`。
+ *
+ * @remarks
+ * **Canvas** — ブロックプラグイン実装時に `plugin.props` へ追加する。
+ */
+export declare const paddingProp: {
+    kind: string;
+    defaultProps: {
+        top: {
+            value: number;
+            unit: string;
+        };
+        right: {
+            value: number;
+            unit: string;
+        };
+        bottom: {
+            value: number;
+            unit: string;
+        };
+        left: {
+            value: number;
+            unit: string;
+        };
+    };
+};
+
+/**
+ * ブロック内の上下左右の余白を保持する Props。
+ */
+export declare interface PaddingProps {
+    top?: Dimension<PaddingUnit>;
+    right?: Dimension<PaddingUnit>;
+    bottom?: Dimension<PaddingUnit>;
+    left?: Dimension<PaddingUnit>;
+    /** 全辺一括モード。`true` のとき `all` が全辺に適用される */
+    bulk?: boolean;
+    /** 全辺共通パディング（`bulk: true` のとき有効） */
+    all?: Dimension<PaddingUnit>;
+}
+
+/**
+ * パディングに使用できる単位（`%` を含む）。
+ */
+export declare type PaddingUnit = (typeof PADDING_UNITS)[number];
+
+/**
+ * 1ページ分のフォームスキーマ。
+ */
+declare interface Page {
+    /** ページの一意 ID。保存済み Book に ID がない場合は {@link ensurePageIds} で付与できる */
+    id?: string;
+    /** グリッド設定（スパース形式）。全列・全行が 1fr の場合は colCount / rowCount のみ */
+    grid: Grid;
+    /** 配置されているブロック一覧 */
+    blocks: Block[];
+    /** ブロック種別ごとの共通デフォルト設定。値解決順序は `Block` の @remarks を参照 */
+    blockDefaults?: BlockDefaults;
+    /** ページ固有のメタデータ（バージョン・タイトルなど） */
+    metaData?: Record<string, Value>;
+}
+
+/**
+ * ページに適用する用紙設定（サイズ・マージン・向き）。
+ */
+declare interface Paper {
+    /** 用紙サイズ */
+    size: PaperSize;
+    /** 用紙マージン */
+    margin: PaperMargin;
+    /** 用紙の向き。true = 横向き (landscape)、省略/false = 縦向き (portrait) */
+    orientation?: boolean;
+    /**
+     * 幅自動リサイズ。
+     *
+     * `true` のとき、`widthFit` ブロックの実測幅に合わせてキャンバス幅を広げる。
+     */
+    autoWidth?: boolean;
+    /**
+     * 高さ自動リサイズ。
+     *
+     * `true` のとき、`heightFit` ブロックの実測高さに合わせてキャンバス高さを広げる。
+     */
+    autoHeight?: boolean;
+}
+
+/**
+ * `paperSizeWidget` 内のブロック定義（再利用可能）。
+ *
+ * @remarks
+ * **Canvas** — カスタムシェル構築専用。
+ *
+ * 4列×2行グリッド想定:
+ * - 行 0: プリセット select（colspan: 4）
+ * - 行 1: 幅value / 幅unit / 高さvalue / 高さunit（Custom 選択時のみ）
+ */
+export declare const PAPER_SIZE_BLOCKS: Block[];
+
+/**
+ * 用紙サイズに使用できる単位の配列。
+ */
+export declare const PAPER_UNITS: readonly ["mm", "cm", "inch"];
+
+/**
+ * 用紙四辺のマージン設定。
+ */
+declare interface PaperMargin {
+    top: Dimension<PaperUnit>;
+    right: Dimension<PaperUnit>;
+    bottom: Dimension<PaperUnit>;
+    left: Dimension<PaperUnit>;
+    /**
+     * 一括編集フラグ。`true` のとき、`all` フィールドが四辺の共通値として使われる。
+     *
+     * Book に保存されるため、通常の binding パス `margin.bulk` で読み書きできる。
+     */
+    bulk?: boolean;
+    /**
+     * 一括モード時の四辺共通マージン値。`bulk` が `true` のときのみ描画・印刷に使用される。
+     *
+     * binding パス `margin.all.value` / `margin.all.unit` で読み書きできる。
+     */
+    all?: Dimension<PaperUnit>;
+}
+
+/**
+ * 横向き checkbox atom widget。
+ *
+ * @remarks
+ * **Canvas** — カスタムシェル構築専用。
+ *
+ * binding: `paper.orientation`（true = landscape, false = portrait）
+ */
+export declare const paperOrientationWidget: WidgetDef;
+
+/**
+ * 用紙プリセット選択 atom widget。
+ *
+ * @remarks
+ * **Canvas** — カスタムシェル構築専用。
+ *
+ * binding: `paper.size.preset`
+ */
+export declare const paperPresetSelectWidget: WidgetDef;
+
+/**
+ * 用紙サイズ設定。
+ *
+ * @remarks
+ * `preset` が `CUSTOM` 以外の場合も `width` / `height` には実寸が格納される。
+ */
+declare interface PaperSize {
+    /** 選択中のプリセット */
+    preset: PaperSizePreset;
+    /** 幅（物理単位）。`CUSTOM` 時はユーザー指定値。 */
+    width: Dimension<PaperUnit>;
+    /** 高さ（物理単位）。`CUSTOM` 時はユーザー指定値。 */
+    height: Dimension<PaperUnit>;
+}
+
+/**
+ * 用紙サイズのプリセット種別。`CUSTOM` 選択時は `PaperSize.width` / `height` が有効になる。
+ */
+declare enum PaperSizePreset {
+    A4 = "A4",
+    B5 = "B5",
+    A3 = "A3",
+    LETTER = "Letter",
+    LEGAL = "Legal",
+    CUSTOM = "Custom"
+}
+
+/**
+ * 用紙サイズ設定 compound widget。
+ *
+ * @remarks
+ * **Canvas** — カスタムシェル構築専用。
+ *
+ * グリッド: 4列×2行
+ * - 列 1 (15mm): 幅単位 select
+ * - 列 3 (15mm): 高さ単位 select
+ * - その他: 1fr
+ *
+ * 行 0: プリセット select（常に表示）
+ *
+ * 行 1: 幅・高さ dimension 入力（Custom 選択時のみ表示）
+ */
+export declare const paperSizeWidget: WidgetDef;
+
+/**
+ * 用紙サイズに使用できる単位。
+ */
+declare type PaperUnit = (typeof PAPER_UNITS)[number];
+
+/**
+ * プレースホルダープロパティの `PropDef`。
+ *
+ * @remarks
+ * **Canvas** — ブロックプラグイン実装時に `plugin.props` へ追加する。
+ */
+export declare const placeholderProp: {
+    kind: string;
+    defaultProps: {
+        placeholder: string;
+    };
+};
+
+/**
+ * ブロックのプレースホルダーテキストを保持する Props。
+ */
+export declare interface PlaceholderProps {
+    /** 未入力時に表示するプレースホルダー文字列 */
+    placeholder?: string;
+}
+
+/**
+ * `createPluginRegistry` が返す、`block.kind` をキーにしたプラグインレジストリ。
+ *
+ * 未登録の `kind` は `undefined` になるため、アクセス前に存在確認が必要。
+ */
+declare type PluginRegistry = Record<string, ResolvedPlugin | undefined>;
+
+/**
+ * 印刷時の余白設定。各辺に CSS の長さ値（例: `"10mm"`）を指定する。
+ * 省略した辺はブラウザのデフォルト余白が適用される。
+ */
+declare interface PrintMargin {
+    top?: string;
+    right?: string;
+    bottom?: string;
+    left?: string;
+}
+
+/**
+ * 印刷ダイアログへ渡す設定。
+ *
+ * @remarks
+ * - 省略したフィールドはブラウザのデフォルト値に従う。
+ * - `paperSize` に `"Custom"` は指定不可（型レベルで `Exclude` により除外済み）。
+ */
+declare interface PrintSettings {
+    /** 印刷する用紙サイズ。省略時は `book.paper.size` を使用。 */
+    paperSize?: Exclude<PaperSizePreset, "Custom">;
+    /** 用紙の向き。true = 横向き (landscape)。省略時は `book.paper.orientation` を使用。 */
+    orientation?: boolean;
+    /** 印刷余白。省略時はブラウザのデフォルト余白。 */
+    margin?: PrintMargin;
+}
+
+/**
+ * coreのプロパティカタログに登録する1機能の定義。
+ *
+ * @remarks
+ * `defaultProps` は `createPluginRegistry` でプラグイン単位に合成され、実際のブロック描画時は `PropDef.defaultProps` → `page.blockDefaults[kind]` → `block.props` の順でマージされる。
+ *
+ * 後段の値ほど優先される。
+ */
+export declare interface PropDef {
+    /** プロパティの種別 ID。`BlockPlugin.properties` 内で一意になるよう設定する */
+    kind: string;
+    /** このプロパティを持つブロック種別のデフォルト props */
+    defaultProps: Record<string, Value>;
+    /**
+     * カスタム編集UIコンポーネント（省略時はPropertyFieldのビルトインUIにフォールバック）。
+     *
+     * 外部プラグインは独自のエディタUIをここに渡すことができる。	 *	 * `PropertyComponentProps<Value>` を実装することで `readOnly` が正しく受け取れる。
+     */
+    component?: ComponentType<PropertyComponentProps<Value>>;
+}
+
+/**
+ * UI コンポーネント（Checkbox, NumberInput 等）の共通 Props 基底型。
+ */
+export declare interface PropertyComponentProps<T> {
+    /** このコンポーネントが編集対象とする現在の値 */
+    value: T;
+    /** 値が変更されたときに呼ばれるコールバック */
+    onChange: (value: T) => void;
+    /**
+     * `true` のとき、ユーザーによる値変更を禁止する。
+     *
+     * カスタムコンポーネントを実装する際は必ずこのフラグを参照してインタラクションを無効化すること。
+     */
+    readOnly?: boolean;
+}
+
+/**
+ * Renderer コンポーネントが受け取る props。
+ */
+export declare interface RendererProps<P = Record<string, Value>, V = Value> {
+    /** ブロック ID */
+    id: string;
+    /** ブロックのプロパティ（プラグイン固有型） */
+    props: P;
+    /** ブロックの値 */
+    value: V;
+    /** 値の変更通知コールバック */
+    onChange: (value: V) => void;
+    /** フォーカス離脱時の値確定通知コールバック（オプション） */
+    onBlur?: (value: V) => void;
+    /**
+     * 読み取り専用フラグ。
+     *
+     * `BlockContainer` が以下のロジックで計算して渡す。
+     *
+     * - EDIT モード: `block.behavior?.readOnly ?? false`
+     *
+     * - FORM / VIEW モード: 常に `true`
+     */
+    readOnly: boolean;
+    /** Note のモード（`EDIT` / `VIEW` / `FORM`） */
+    mode: NoteMode;
+    /** ブロックの描画領域（px）。未設定時は auto として扱う */
+    dimensions?: {
+        widthPx: number;
+        heightPx: number;
+    };
+    /**
+     * ブロック幅の実測値（px）を通知するコールバック。
+     *
+     * `block.behavior.widthFit === true` のブロックに限り `BlockContainer` から渡される。
+     */
+    onMeasureWidth?: (widthPx: number) => void;
+    /**
+     * ブロック高さの実測値（px）を通知するコールバック。
+     *
+     * `block.behavior.heightFit === true` のブロックに限り `BlockContainer` から渡される。
+     */
+    onMeasureHeight?: (heightPx: number) => void;
+    /** `BindingContext`（値の読み書きパス解決）。必要なブロックのみ参照する */
+    bindingContext?: BindingContext;
+    /** `ActionContext`（undo/redo 等のアクション実行）。必要なブロックのみ参照する */
+    actionContext?: ActionContext;
+    /** アクセシビリティラベル。`BlockRenderer` が `resolvedPlugin.meta.displayName` を自動セットする */
+    ariaLabel?: string;
+}
+
+/**
+ * 必須入力プロパティの `PropDef`。
+ *
+ * @remarks
+ * **Canvas** — ブロックプラグイン実装時に `plugin.props` へ追加する。
+ */
+export declare const requiredProp: {
+    kind: string;
+    defaultProps: {
+        required: false;
+    };
+};
+
+/**
+ * ブロックの必須入力設定を保持する Props。
+ */
+export declare interface RequiredProps {
+    /** `true` のとき、値が空の場合にバリデーションエラーとなる */
+    required?: boolean;
+}
+
+/**
+ * 必須バリデーションのみのスキーマ（Select・Checkbox で使用）。
+ */
+export declare interface RequiredSchema {
+    /** `true` のとき、未入力または空値でエラーとなる。省略時はバリデーションしない */
+    required?: boolean;
+}
+
+/**
+ * リサイズハンドル方向（8方向）
+ *
+ * @remarks
+ * **Canvas** — {@link InteractionLayer} のリサイズハンドル方向。
+ */
+export declare enum ResizeHandle {
+    N = "n",
+    NE = "ne",
+    E = "e",
+    SE = "se",
+    S = "s",
+    SW = "sw",
+    W = "w",
+    NW = "nw"
+}
+
+/**
+ * レジストリに登録された解決済みプラグイン。
+ *
+ * @remarks
+ * BlockPlugin<P,V> のジェネリクスを型消去し、Shell/Canvas 層が any なしで扱えるフラットな構造にまとめたもの。
+ *
+ * Renderer の P/V variance 問題は BaseRenderer 型への単一キャストで解決。
+ */
+export declare interface ResolvedPlugin {
+    /** `block.kind` と対応するプラグインの一意識別子 */
+    kind: string;
+    /** UI 表示・アイコン・デフォルトサイズ等のメタ情報 */
+    meta: BlockPluginMeta;
+    /** プロパティパネルに表示するプロパティ定義一覧 */
+    properties: PropDef[];
+    /** プラグインの全 `PropDef.defaultProps` を合成した、このブロック種別のデフォルト props */
+    defaultProps: Record<string, Value>;
+    /**
+     * ブロックを描画する Renderer コンポーネント。
+     *
+     * BlockPlugin<P,V>.Renderer を格納する際、P/V の variance 問題を回避するためベース型にキャストしている。
+     *
+     * 実行時には block.props（解決済み）と value が渡されるため安全。
+     */
+    Renderer: BaseRenderer;
+    /** 旧バージョンの props を現バージョンに変換する。`validateProps` の前に呼ばれる */
+    migrateProps?: (props: unknown) => Record<string, unknown>;
+    /**
+     * ストレージから読み込んだ生の `block.props` をサニタイズして型安全な Props に変換する。
+     *
+     * 省略時は raw オブジェクトをそのまま使用する。
+     */
+    validateProps?: (props: unknown) => Record<string, Value>;
+    /**
+     * 外部 state から読み込んだ生の値をサニタイズする。
+     *
+     * `undefined` を返した場合は `block.initValue`、それもなければ raw 値にフォールバックする。
+     *
+     * フォールバックを指示する場合にのみ `undefined` を使い、`null` は正当な値として返せる。
+     *
+     * 省略時は raw 値をそのまま使用する。
+     */
+    validateValue?: (value: unknown, props: Record<string, Value>) => Value | undefined;
+}
+
+/**
+ * `book.paper` に `printSettings` のサイズ・向きをマージした実効用紙設定を返す。
+ *
+ * `printSettings` を省略した場合は `book.paper` をそのまま返す。
+ */
+export declare function resolveEffectivePaper(book: Book, printSettings?: PrintSettings): Paper;
+
+/**
+ * セレクトボックスブロックの props 型。
+ */
+export declare type SelectBlockProps = BaseBlockProps & FontStyleProps & PlaceholderProps & RequiredProps & SelectConfigProps;
+
+/**
+ * セレクトボックスブロックの値型。`null` は未選択状態を表す。
+ */
+export declare type SelectBlockValue = string | null;
+
+/**
+ * `selectConfig` prop 定義。セレクトボックスの選択肢デフォルト値を含む。
+ */
+export declare const selectConfigProp: {
+    kind: string;
+    defaultProps: {
+        selectConfig: {
+            options: {
+                label: string;
+                value: string;
+            }[];
+        };
+    };
+};
+
+/**
+ * セレクトボックスの選択肢設定 props。
+ */
+export declare interface SelectConfigProps {
+    /** 選択肢と機能設定。 */
+    selectConfig: SelectOptionsConfig;
+}
+
+/**
+ * セレクトボックスの個々の選択肢。
+ */
+export declare interface SelectOption {
+    /** ユーザーに表示するラベル。 */
+    label: string;
+    /** 選択時にブロック値として記録される内部値。 */
+    value: string;
+    /** ラベルに適用する文字色（任意）。 */
+    color?: string;
+}
+
+/**
+ * セレクトボックスの選択肢一覧と機能設定。
+ */
+export declare interface SelectOptionsConfig {
+    /** 選択肢の配列。 */
+    options: SelectOption[];
+    /** `true` のとき空白選択（未選択）を許可する。 */
+    allowEmpty?: boolean;
+}
+
+/**
+ * セレクトボックスブロックのレンダラーコンポーネント。
+ *
+ * 選択肢一覧からユーザーが 1 つを選択し、`string | null` 値を管理する。
+ *
+ * `mode === NoteMode.VIEW` のときは選択ラベルをテキストとして表示する。
+ */
+export declare const SelectRenderer: ForwardRefExoticComponent<RendererProps<SelectBlockProps, SelectBlockValue> & RefAttributes<BlockRef>>;
+
+/**
+ * JSON シリアライズ可能なプロパティのみを持つオブジェクト型の境界。
+ *
+ * `BlockPlugin<P>` / `Block<P>` の型引数制約として使用し、`P` に関数・クラスインスタンス・DOM 要素など非 serializable な型が混入した場合に型エラーとして検出する。
+ *
+ * オプショナルフィールド（`?`）は `undefined` を許容するため `Value | undefined` としている。
+ */
+declare type SerializableRecord = Record<string, Value | undefined>;
+
+/**
+ * ブロックの幅・高さに使用できる単位の配列。
+ */
+export declare const SIZE_UNITS: readonly ["mm", "cm", "inch", "pt", "px", "%"];
+
+/**
+ * ブロックの幅・高さに使用できる単位（`%` を含む）。
+ */
+export declare type SizeUnit = (typeof SIZE_UNITS)[number];
+
+/**
+ * ブロック挿入 DnD を開始する。
+ *
+ * `dragstart` イベントハンドラ内で呼ぶ。
+ *
+ * ドロップ先は自動的に `NoteForm` がハンドルする。
+ *
+ * @example
+ * ```tsx
+ * <div
+ *   draggable
+ *   onDragStart={(e) => startBlockDrag(e, plugin.kind, plugin.meta.defaultSize)}
+ * >
+ *   {plugin.meta.displayName}
+ * </div>
+ * ```
+ */
+export declare function startBlockDrag(e: default_2.DragEvent | DragEvent, kind: string, defaultSize?: {
+    w: number;
+    h: number;
+}): void;
+
+/**
+ * `stepperBehavior` prop 定義。
+ *
+ * @remarks
+ * **Canvas** — カスタムプラグイン実装時に利用する。
+ */
+export declare const stepperBehaviorProp: {
+    kind: string;
+    defaultProps: {
+        step: number;
+    };
+};
+
+/**
+ * ステッパーの数値範囲・ステップ幅の振る舞い props。
+ *
+ * @remarks
+ * **Canvas** — カスタムプラグイン実装時に利用する。
+ */
+export declare interface StepperBehaviorProps {
+    /** 1ステップ当たりの増減幅。デフォルト: 1。 */
+    step?: number;
+    /** 入力可能な最小値。 */
+    min?: number;
+    /** 入力可能な最大値。 */
+    max?: number;
+}
+
+/**
+ * ステッパーブロックの props 型。
+ *
+ * @remarks
+ * **Canvas** — カスタムプラグイン向けの型。
+ *
+ * 一般的なフォーム構築では直接参照することはない。
+ */
+export declare type StepperBlockProps = BaseBlockProps & StepperBehaviorProps & StepperStyleProps;
+
+/**
+ * ステッパーブロックの値型。`null` は未入力状態を表す。
+ *
+ * @remarks
+ * **Canvas** — カスタムプラグイン向けの型。
+ */
+export declare type StepperBlockValue = number | null;
+
+/**
+ * ステッパーブロックのプラグイン定義。
+ *
+ * `kind: "stepper"` で登録され、数値を±ボタンで増減する UI ブロック。
+ *
+ * @remarks
+ * **Canvas** — カスタムプラグインの実装例。
+ *
+ * ステッパー機能が必要なフォームに `createPluginRegistry` に渡す。
+ *
+ * 標準フォーム構築では `createPluginRegistry` に渡すだけで使用できる。
+ */
+export declare const StepperPlugin: BlockPlugin<StepperBlockProps, StepperBlockValue>;
+
+/**
+ * ステッパーブロックのレンダラーコンポーネント。
+ *
+ * 上下のボタンで数値を `step` 幅分増減し、`min`/`max` でクランプする。
+ *
+ * @remarks
+ * **Canvas** — `StepperPlugin` と組み合わせて使用する実装コンポーネント。
+ */
+export declare const StepperRenderer: ForwardRefExoticComponent<RendererProps<StepperBlockProps, StepperBlockValue> & RefAttributes<BlockRef>>;
+
+/**
+ * ステッパーの矢印外観カスタマイズ設定。
+ *
+ * @remarks
+ * **Canvas** — カスタムプラグイン実装時に利用すること。
+ */
+export declare interface StepperStyleConfig {
+    /** 矢印の色（CSS 値 / `currentColor` も可）。 */
+    arrowColor?: string;
+    /** 矢印の幅（px）。 */
+    arrowWidth?: number;
+    /** 矢印の高さ（px）。 */
+    arrowHeight?: number;
+    /** 矢印と値表示領域の間距（px）。 */
+    arrowGap?: number;
+}
+
+/**
+ * `stepperStyle` prop 定義。
+ *
+ * @remarks
+ * **Canvas** — カスタムプラグイン実装時に利用する。
+ */
+export declare const stepperStyleProp: {
+    kind: string;
+    defaultProps: {
+        styleConfig: {
+            arrowWidth: number;
+            arrowHeight: number;
+            arrowColor: string;
+            arrowGap: number;
+        };
+    };
+};
+
+/**
+ * ステッパーブロックの外観カスタマイズ props。
+ *
+ * @remarks
+ * **Canvas** — カスタムプラグイン実装時に利用する。
+ */
+export declare interface StepperStyleProps {
+    /** 矢印外観カスタマイズ設定。 */
+    styleConfig?: StepperStyleConfig;
+}
+
+/**
+ * 寸法文字列（例: `"210mm"`）を {@link Dimension} オブジェクトに変換する。
+ *
+ * @throws {@link Error} 文字列が `<数値><単位>` の形式でない場合、または単位が `allowedUnits` 外の場合
+     */
+ export declare function stringToDimension<U extends Unit>(str: string, allowedUnits: readonly U[]): Dimension<U>;
+
+ /**
+  * `textBehavior` prop 定義。テキストブロックのレイアウト挙動のデフォルト値を含む。
+  */
+ export declare const textBehaviorProp: {
+     kind: string;
+     defaultProps: {
+         lineHeight: number;
+         multiline: true;
+         wordWrap: WordWrap;
+         whiteSpace: WhiteSpace;
+     };
+ };
+
+ /**
+  * テキスト入力の改行・折り返し・行間隔などのレイアウト挙動 props。
+  */
+ export declare interface TextBehaviorProps {
+     /** 行間隔（CSS `line-height` 相当）。デフォルト: 1.2。 */
+     lineHeight?: number;
+     /** `true` のとき複数行入力を許可する。デフォルト: true。 */
+     multiline?: boolean;
+     /** 折り返しの振る舞い（CSS `overflow-wrap` 相当）。 */
+     wordWrap?: WordWrap;
+     /** スペース・改行のレンダリング模式（CSS `white-space` 相当）。 */
+     whiteSpace?: WhiteSpace;
+ }
+
+ /**
+  * テキストブロックの props 型。
+  *
+  * フォント・文字幅返・入力バリデーション・プレースホルダーなどの属性群の共和型。
+  */
+ export declare type TextBlockProps = BaseBlockProps & FontStyleProps & PlaceholderProps & RequiredProps & TextBehaviorProps & TextValidationProps;
+
+ /**
+  * テキストブロックの値型。`null` は未入力状態を表す。
+  */
+ export declare type TextBlockValue = string | null;
+
+ /**
+  * テキストブロックのレンダラーコンポーネント。
+  *
+  * `multiline` prop に応じて `<input>` と `<textarea>` を切り替える。
+  *
+  * `onMeasureHeight` / `onMeasureWidth` を通じてコンテンツ高さ・幅を外部に通知する。
+  */
+ export declare const TextRenderer: ForwardRefExoticComponent<RendererProps<TextBlockProps, TextBlockValue> & RefAttributes<BlockRef>>;
+
+ /**
+  * `textValidation` prop 定義。テキスト入力のバリデーションルールのデフォルト値を含む。
+  */
+ export declare const textValidationProp: {
+     kind: string;
+     defaultProps: {
+         inputType: InputType;
+     };
+ };
+
+ /**
+  * テキスト入力の入力タイプ・数値範囲・文字数・パターンなどのバリデーション props。
+  */
+ export declare interface TextValidationProps {
+     /** 入力タイプ（`<input type>` 属性）。デフォルト: `text`。 */
+     inputType?: InputType;
+     /** 数値入力の最小値。 */
+     min?: number;
+     /** 数値入力の最大値。 */
+     max?: number;
+     /** 数値入力のステップ幅。 */
+     step?: number;
+     /** 最小文字数。 */
+     minLength?: number;
+     /** 最大文字数。 */
+     maxLength?: number;
+     /** 入力値を検証する正規表現パターン。 */
+     pattern?: string;
+ }
+
+ /**
+  * 各種単位の値を mm に変換するユーティリティオブジェクト。
+  *
+  * `fr` と `%` のような相対単位は物理長に変換できないため、`fromDim` でこれらを指定すると `Error` をスローする。
+  */
+ export declare const toMm: {
+     fromCm: (cm: number) => number;
+     fromInch: (inch: number) => number;
+     fromPt: (pt: number) => number;
+     fromPx: (px: number) => number;
+     fromDim<U extends Unit>(dim: Dimension<U>): number;
+ };
+
+ /**
+  * 各種単位の値を px に変換するユーティリティオブジェクト。
+  *
+  * `%` を変換する際は `fromDim` の `baseSizePx` が必要。`fr` の変換はサポートしていないため `Error` をスローする。
+  */
+ export declare const toPx: {
+     fromMm: (mm: number, dpi?: number) => number;
+     fromCm: (cm: number, dpi?: number) => number;
+     fromInch: (inch: number, dpi?: number) => number;
+     fromPt: (pt: number, dpi?: number) => number;
+     fromPx: (px: number, dpi?: number) => number;
+     fromDim<U extends Unit>(dim: Dimension<U>, dpi?: number, baseSizePx?: number): number;
+ };
+
+ /**
+  * このパッケージで使用できる全単位。
+  */
+ declare type Unit = (typeof ALL_UNITS)[number];
+
+ /**
+  * このパッケージで扱う全単位の列挙。
+  */
+ export declare const Units: {
+     readonly MM: "mm";
+     readonly CM: "cm";
+     readonly FR: "fr";
+     readonly INCH: "inch";
+     readonly PT: "pt";
+     readonly PX: "px";
+     readonly PERCENT: "%";
+ };
+
+ /**
+  * SelectBlock を PaperUnit (mm / cm / inch) 選択専用設定にしたブロック定義ヘルパー。
+  *
+  * @remarks
+  * **Canvas** — カスタムシェル構築向レイアウトヘルパー。
+  *
+  * binding には単位を保持するパス（例: "paper.size.width.unit"）を渡す。
+  *
+  * 返り値のレイアウトはデフォルト `{ x:0, y:0, w:1, h:1 }` のため、
+  * 複合 widget 内で spread して上書きすること。
+  *
+  * @example
+  * ```ts
+  * {
+  *   ...unitSelectBlock("width-unit", "paper.size.width.unit"),
+  *   layout: { x: 2, y: 0, w: 1, h: 1 },
+  * }
+  * ```
+  */
+ export declare function unitSelectBlock(id: string, binding: string): Block;
+
+ /**
+  * `ActionHandlers` から {@link ActionContext} を組み立てるフック。
+  *
+  * @remarks
+  * **Canvas** — 通常は {@link useNoteContext} 経由で利用してください。
+  *
+  * 直接使用する場合はアクションの有効/無効判定を自前で実装する必要があります。
+  */
+ export declare function useBookActionContext(handlers: ActionHandlers): ActionContext;
+
+ /**
+  * book 全体の読み書きを担う BindingContext を生成するフック。
+  *
+  * @remarks
+  * **Canvas** — 通常は {@link useNoteContext} 経由で自動生成される。
+  *
+  * 直接呼ぶのは独自の BindingContext レイヤーを構築する場合のみとすること。
+  *
+  * 以下のパス名前空間を組み込みで処理する：
+  * - `paper.*` — `book.paper.*` に対応
+  * - `margin.*` — `book.paper.margin.*` に対応（`margin.bulk` / `margin.all.*` も通常パスとして解決）
+  * - `grid.*`  — `book.pages[pageIdx].grid.*` に対応（`options.pageIdx` で制御）
+  * - 上記以外 — `book` のルートから直接解決（後方互換）
+  *
+  * @example
+  * ```tsx
+  * const bindingContext = useBookBindingContext(book, onBookChange, { pageIdx });
+  *
+  * // 全ての widget に同じ bindingContext を渡すだけ
+  * <FloatingWidget bindingContext={bindingContext} ... />
+  * ```
+  */
+ export declare function useBookBindingContext(book: Book, onBookChange: OnBookChange, options?: BookBindingContextOptions): BindingContext;
+
+ /**
+  * `useReducer` ベースの Undo/Redo 履歴管理フック。
+  *
+  * 同じ `mergeKey` かつ {@link MERGE_WINDOW_MS} ms 以内の変更は履歴エントリをマージする。
+  *
+  * @remarks
+  * **Canvas** — 通常は {@link useNoteContext} から自動利用される。
+  *
+  * 直接呼ぶのは独自の履歴層を構築する場合のみとすること。
+  */
+ export declare function useBookHistory({ initialBook, maxHistory, }: UseBookHistoryOptions): UseBookHistoryResult;
+
+ /**
+  * {@link useBookHistory} のオプション。
+  */
+ export declare interface UseBookHistoryOptions {
+     /** 履歴の初期 Book。 */
+     initialBook: Book;
+     /**
+      * 保持する最大履歴件数。`null` または省略時は `100` が使われる。
+      *
+      * 超過した古いエントリは末尾追加時に先頭から切り捨てられる。
+      */
+     maxHistory?: number | null;
+ }
+
+ /**
+  * {@link useBookHistory} の戻り値。
+  */
+ export declare interface UseBookHistoryResult {
+     /** 現在の Book（履歴上のカレントポインタ側）。 */
+     book: Book;
+     /** Book の変更を履歴に追加するコールバック。`mergeKey` が同じ変更はマージされる（`noTimeWindow: true` で時間窓なし）。 */
+     handleBookChange: (book: Book, options?: {
+         mergeKey?: string;
+         noTimeWindow?: boolean;
+     }) => void;
+     /** Undo 可能かどうか。 */
+     canUndo: boolean;
+     /** Redo 可能かどうか。 */
+     canRedo: boolean;
+     /** Undo 実行関数。 */
+     undo: () => void;
+     /** Redo 実行関数。 */
+     redo: () => void;
+     /** `useBookActionContext` にそのまま渡せる undo/redo の ActionHandlers。 */
+     historyActionHandlers: ActionHandlers;
+ }
+
+ /**
+  * `InteractionLayer` に渡す `state` と `onStateChange` を提供する。
+  *
+  * @example
+  * ```tsx
+  * const [state, onStateChange] = useInteractionState();
+  * return <InteractionLayer state={state} onStateChange={onStateChange} ... />;
+  * ```
+  *
+  * @remarks
+  * **Canvas** — {@link InteractionLayer} の `state` / `onStateChange` を提供するシンプルなフック。
+  */
+ export declare function useInteractionState(initialState?: Partial<InteractionState>): [InteractionState, Dispatch<SetStateAction<InteractionState>>];
+
+ /**
+  * 未検証の値を {@link Page} として検証する。
+  *
+  * @throws {@link Error} ページの構造（`grid` / `blocks` / `metaData`）が不正な場合
+      */
+  export declare function validatePage(value: unknown): Page;
+
+  /**
+   * 未検証の値を `Record<string, Value>` として検証する。
+   *
+   * @throws {@link Error} 値がプレインオブジェクトでない場合、またはいずれかのプロパティが無効な {@link Value} の場合
+       */
+   export declare function validateValues(data: unknown): Record<string, Value>;
+
+   /**
+    * バリデーション結果の1件分。プラグインのバリデーター関数が返す配列の要素型。
+    *
+    * @remarks
+    * `useNoteLayout` が `Record<blockId, ValidationError[]>` として管理する。
+    */
+   declare interface ValidationError {
+       /** ユーザーに表示するエラーメッセージ */
+       message: string;
+       /** エラー種別を識別するコード（例: `"required"`, `"min_length"`） */
+       code: string;
+       /** エラーに関連するフィールド名。ブロック内の特定フィールドを示す場合に使用。 */
+       field?: string;
+       /** 重大度レベル */
+       severity: ValidationSeverity;
+       /** プラグインが付加する任意のメタデータ */
+       metadata?: Record<string, Value>;
+   }
+
+   /**
+    * バリデーションエラーを示すオーバーレイコンポーネント。
+    *
+    * エラーがある場合は黒黄の縞模様を表示し、ホバー時にエラーメッセージをツールチップが示します。
+    *
+    * @remarks
+    * **Canvas** — {@link BlockLayer} のバリデーションオーバーレイサブコンポーネント。
+    *
+    * 通常は {@link BlockLayer} の `showValidation` prop で制御する。
+    */
+   export declare const ValidationOverlay: FC<ValidationOverlayProps>;
+
+   /**
+    * `ValidationOverlay` コンポーネントへの props。
+    */
+   export declare interface ValidationOverlayProps {
+       /** ブロックのサイズ（px）。 */
+       blockSizePx: BlockSizePx;
+       /** z-index のベース値。 */
+       blockZIndex: number;
+       /** 表示するバリデーションエラー一覧。空配列の場合は描画しない。 */
+       errors: ValidationError[];
+   }
+
+   /**
+    * バリデーションプロパティのスキーマ（Text で使用）。
+    */
+   export declare interface ValidationSchema extends RequiredSchema {
+       /** 入力文字数の最小値。省略時はチェックしない */
+       minLength?: number;
+       /** 入力文字数の最大値。省略時はチェックしない */
+       maxLength?: number;
+       /** 入力値にマッチさせる正規表現パターン。省略時はチェックしない */
+       pattern?: string;
+   }
+
+   /**
+    * バリデーション結果の重大度レベル。
+    */
+   declare enum ValidationSeverity {
+       /** 修正が必要なエラー */
+       ERROR = "error",
+       /** 推奨される修正があるが続行可能な警告 */
+       WARNING = "warning",
+       /** 参考情報 */
+       INFO = "info"
+   }
+
+   /**
+    * このパッケージで扱う値の型。JSON シリアライズ可能な値のみを表す再帰型。
+    *
+    * ブロックの入力値・バインディング値・スキーマのデフォルト値などに共通して使用される。
+    */
+   declare type Value = string | number | boolean | null | Value[] | readonly Value[] | {
+       [key: string]: Value;
+   };
+
+   /**
+    * 1 件の値変更を表す。
+    *
+    * @remarks
+    * `value` が `undefined` の場合はそのブロックの値を削除する。
+    */
+   export declare type ValueChange = {
+       id: string;
+       value: Value | undefined;
+   };
+
+   /**
+    * ブロック内の垂直配置。
+    */
+   export declare enum VerticalAlign {
+       top = "top",
+       center = "center",
+       bottom = "bottom"
+   }
+
+   /**
+    * テキストの改行・スペースのレンダリング模式（CSS `white-space` 相当）。
+    */
+   export declare enum WhiteSpace {
+       normal = "normal",
+       nowrap = "nowrap",
+       pre = "pre",
+       preWrap = "pre-wrap",
+       preLine = "pre-line"
+   }
+
+   /**
+    * ウィジェット定義。NoteBlockProps と必要プラグインを一体化した型。
+    *
+    * @remarks
+    * {@link FloatingWidget} に渡すことで、`pluginRegistry` を別途用意する必要がなくなる。
+    *
+    * `plugins` には、このウィジェットを描画するために必要なプラグインをすべて列挙する。
+    *
+    * `FloatingWidget` はこれを元に内部で `PluginRegistry` を構築する。
+    */
+   declare interface WidgetDef {
+       /** Widget として表示する NoteBlock の初期データ */
+       props: NoteBlockProps;
+       /** このウィジェットを描画するために必要なプラグイン */
+       plugins: readonly AnyBlockPlugin[];
+   }
+
+   /**
+    * テキストの折り返し・改行插入の振る舞い。
+    */
+   export declare enum WordWrap {
+       normal = "normal",
+       breakWord = "break-word",
+       breakAll = "break-all"
+   }
+
+   export { }