# @wcstack/storage

> 🤖 **AI coding agents**: This README is a package-level reference, not the primary entry point for building a wcstack application. If you have not already done so, first read the repository [README](https://github.com/wcstack/wcstack#readme) and [AGENTS.md](https://github.com/wcstack/wcstack/blob/main/AGENTS.md), then use the [wcstack-app skill](https://github.com/wcstack/wcstack-skill).

`@wcstack/storage` は wcstack エコシステムのためのヘッドレス ストレージ コンポーネントです。

視覚的な UI ウィジェットではありません。
ブラウザのストレージ（localStorage / sessionStorage）とリアクティブな状態をつなぐ **I/O ノード** です。

`@wcstack/state` と組み合わせると、`<wcs-storage>` はパス契約を通じて直接バインドできます:

- **入力 / コマンドサーフェス**: `key`, `type`, `trigger`
- **出力ステートサーフェス**: `value`, `loading`, `error`

つまり、ブラウザストレージの永続化を HTML 内で宣言的に表現できます。UI レイヤーに `localStorage.getItem()`、`JSON.parse()`、シリアライズのグルーコードを書く必要はありません。

`@wcstack/storage` は [CSBC](https://github.com/csbc-dev/arch/blob/main/README.md)（Core / Shell / Binding Contract）アーキテクチャに従います:

- **Core** (`StorageCore`) がストレージの読み書き、クロスタブ同期を処理
- **Shell** (`<wcs-storage>`) がその状態を DOM に接続
- フレームワークやバインディングシステムは [wc-bindable-protocol](https://github.com/wc-bindable-protocol/wc-bindable-protocol) 経由で利用

## なぜこれが存在するのか

フロントエンドアプリケーションでは、ユーザー設定やセッションデータの永続化に localStorage / sessionStorage を頻繁に使います。
しかし、読み込み、JSON パース、保存、エラー処理のグルーコードは毎回同じようなパターンです。

`@wcstack/storage` はそのグルーコードを再利用可能なコンポーネントに移し、ストレージの値をバインド可能な状態として公開します。

`@wcstack/state` と組み合わせたフローは:

1. `<wcs-storage>` が接続時にストレージから自動読み込み
2. `value` が `data-wcs` で UI にバインド
3. 状態が変わると自動的にストレージに書き戻し
4. 他のタブでの変更も自動検知

永続化が命令的なグルーコードではなく、**状態遷移**になります。

## インストール

```bash
npm install @wcstack/storage
```

## クイックスタート

### 1. プリミティブ値の自動保存

プリミティブ値（文字列、数値、boolean）は `value` バインディングだけで双方向永続化できます。

```html
<script type="module" src="https://esm.run/@wcstack/storage/auto"></script>
<script type="module" src="https://esm.run/@wcstack/state/auto"></script>

<wcs-state>
  <script type="module">
    export default {
      // 空のキーは null をロードする — 都合のよい初期値ではなく
      // 要素の実初期値をシードする（下記「5. load-before-bind」参照）
      username: null,
    };
  </script>
</wcs-state>

<wcs-storage key="username" data-wcs="value#init=element: username"></wcs-storage>

<input data-wcs="value: username" placeholder="ユーザー名">
<p>保存済み: <span data-wcs="textContent: username"></span></p>
```

これがデフォルトモードです:

- `key` を設定すると接続時に自動読み込み
- `value` にバインドすると双方向永続化
- 任意で `loading`、`error` もバインド
- `value` バインディングに `#init=element` を付けて保存値を初期同期の勝者にする — 理由は「5. load-before-bind」を参照

### 2. フォームを 1 つのオブジェクトとして永続化する

いちばんありそうな形 —— 複数の入力欄を 1 つのキーにまとめて保存し、リロードで復元する。state に**アクセサペア**（オブジェクトを組み立てる getter と、受け取ってばらす setter）を置き、そこへ `value#init=element` をバインドします:

```html
<wcs-state>
  <script type="module">
    export default {
      form: { name: "", email: "" },

      // 保存経路。各フィールドを *パスで* 読むので、どれが変わっても getter が
      // 再評価され、新しいオブジェクトが <wcs-storage> の value へ流れて保存される
      // （write-through）。
      get formSnapshot() {
        return { name: this["form.name"], email: this["form.email"] };
      },
      // 復元経路。ロード時に永続化済みオブジェクトがここに届く（空キーなら null）。
      set formSnapshot(v) {
        if (v) this.form = { ...this.form, ...v };
      },
    };
  </script>
</wcs-state>

<wcs-storage key="signup-form" type="local"
  data-wcs="value#init=element: formSnapshot"></wcs-storage>

<input data-wcs="value: form.name" placeholder="名前">
<input data-wcs="value: form.email" type="email" placeholder="メール">
```

**フロー:**

1. 接続時に `<wcs-storage>` がキーをロード。`#init=element` によりロード済みオブジェクトが `formSnapshot` に書かれ → setter が `form` を埋め → 入力欄に復元値が出る
2. 入力すると `form.name` が書かれ → `formSnapshot` が dirty に → バインディングが新しいオブジェクトを `value` に適用 → 保存
3. 保存が発火する `value` イベントは、state が `value` に書いている最中に、同じオブジェクトで dispatch される。これは state 自身の書き込みが返ってきたもので、state へは書かれない（[規則](../state/README.ja.md#要素から-state-に何が書かれるかpropertiesgetter)）。setter が走るのはロード時と、別のタブがキーを保存したとき（そのオブジェクトは新しいもの）。タブをまたぐとキーは 1 つの単位で、後から保存した方が勝つ

間違えやすい点が 4 つ:

- 1 つのウィンドウのための下書き（書きかけのフォーム）には `type="session"` が向きます。再読み込みを越えて残り、2 つ目のタブは自分の下書きを持ちます。`localStorage`（既定）では、2 つ目のタブで打った文字が保存されるたびに、1 つ目のタブの下書きを置き換えます。記録に属する下書き（チケットへの返信）には、代わりに記録ごとのキー（記録の id から作る getter に `key: draftKey`）が向き、ふつうは `localStorage` に置きます: 固定のキーは下書きを記録から記録へ運び、セッションストレージはタブとともに失われ、複製したタブに写されます（[開いたままのページ](../../docs/long-lived-pages.ja.md)）。

- フィールドは `this["form.name"]` で読み、`this.form.name` で読ま**ない**こと。後者は `form` にしか依存を張らず（`.name` は返ってきたオブジェクトへの素のプロパティアクセス）、フィールドを編集しても getter は再評価されません —— [依存追跡の境界](../state/README.ja.md#依存追跡の境界) を参照
- 保存した値は配備を越えて残ります。キーには前の版のアプリが保存したものが入っていて、前の版を開いたままのタブは新しい版の保存を受け取ります（`storage` イベント）。逆も同じで、形が変わっていても何も言いません。保存するオブジェクトに版を持たせて setter で移すか、形を変えるときにキーを変えてください。
- 空キーでは初回ロードで seed オブジェクトが 1 回書かれます。`null` が setter を通り、アクセサペアへの書き込みは常に getter を再評価するからです。永続化済みデータが上書きされることはありません —— 保存済みオブジェクトは復元され、同じ内容で再保存されます

`value` を `form` へ直接束ねないのは、束縛がそのパス自身への代入でしか当て直されないからです。`form.name`（リストなら `cart.0.quantity`）への書き込みでは `value: form` は当て直されず、変更は保存されません —— エラーは出ず、再読み込みで古い値に戻ります。上の getter はフィールドをすべてパスで読むので、編集のたびに再評価されます。リストも同じ形で、保存するものを返す行 getter と、それを集める `$getAll` を使います（`get "cart.*.saved"() { … }`、`get savedCart() { return this.$getAll("cart.*.saved", []); }`）。`wcs-validate` は直接の形を `wcs/input-nested-write` で、`null` 以外でシードしたスロットへの `#init=element` を `wcs/storage-init-seed` で、`#init=element` なしで束ねたアクセサペア（getter の最初の値が保存値の上に保存される）を `wcs/storage-seed-clobber` で報告します。

このパターンは `packages/storage/__tests__/integration.accessorPairForm.test.ts` が実 `@wcstack/state` に対して固定しています。

#### 任意のタイミングで保存する（`manual` + `trigger`）

変更のたびではなく自分で選んだ瞬間に保存したい場合は、`manual` を付けて `trigger:` を真偽値で駆動します。依存走査は**親→子方向**のみなので、`settings.theme` が変わっても `settings` へのバインディングは発火しません。`$dependOn` で監視するフィールドを列挙し、`trigger` でオブジェクト全体をコミットします:

```html
<wcs-state>
  <script type="module">
    export default defineState({
      settings: { theme: "light", lang: "ja" },

      get settingsChanged() {
        this.$dependOn("settings.theme");
        this.$dependOn("settings.lang");
        return true;
      },
    });
  </script>
</wcs-state>

<wcs-storage key="app-settings" manual
  data-wcs="value: settings; trigger: settingsChanged">
</wcs-storage>

<select data-wcs="value: settings.theme">
  <option value="light">ライト</option>
  <option value="dark">ダーク</option>
</select>

<select data-wcs="value: settings.lang">
  <option value="ja">日本語</option>
  <option value="en">English</option>
</select>
```

**フロー:**

1. ユーザーがテーマを変更 → `settings.theme` が更新
2. 動的依存により `settingsChanged` が再評価 → `true` を返す
3. `trigger: settingsChanged` バインディングが発火 → `save()` 実行
4. `settings` オブジェクト全体が localStorage に保存

### 3. sessionStorage の使用

`type="session"` で sessionStorage を使用します:

```html
<wcs-state>
  <script type="module">
    export default { sessionData: null };
  </script>
</wcs-state>

<wcs-storage key="session-data" type="session"
  data-wcs="value#init=element: sessionData">
</wcs-storage>

<p data-wcs="textContent: sessionData"></p>
```

### 4. クロスタブ同期

localStorage の変更は、別のタブからの更新も自動的に検知されます:

```html
<wcs-state>
  <script type="module">
    export default {
      // 下記「5. load-before-bind」参照
      sharedCounter: null,
    };
  </script>
</wcs-state>

<wcs-storage key="shared-counter"
  data-wcs="value#init=element: sharedCounter">
</wcs-storage>

<!-- 他のタブで localStorage を変更すると、この値も自動更新される -->
<p data-wcs="textContent: sharedCounter"></p>
```

> **注意**: `storage` イベントは同一オリジンの他のタブでの変更時にのみ発火します。sessionStorage はタブ間で共有されないため、クロスタブ同期は localStorage でのみ動作します。

### 5. load-before-bind: `#init=element`

`<wcs-storage>` は自身の `connectedCallback` で永続値をロードして通知します。スクリプトのロード状況によっては、これは `<wcs-state>` のバインディング確立**前**に起こりえます — 帰結は 2 つ:

1. **上書き消去（clobber）**: `value` はこの要素で唯一の*双方向*メンバなので、既定のバインディング authority は `state` です。初期の state→element 適用が state スロットのシード値を `value` に書き込み、write-through 保存が**リロードのたびに永続データを上書き**します。
2. **ロードの取り逃し**: ロード完了を知らせる value イベントが誰も聴いていない間に発火し、state スロットがシード値のまま残ることがあります。

両方を塞ぐのは修飾子 1 つです。`#init=element` は初期同期の authority を**要素側**にします:

```html
<wcs-state>
  <script type="module">
    export default {
      // 空のキーは null をロードするので、それが正直なシード値。
      // 都合のよい [] ではなく正規化 getter 経由で読む。
      todos: null,
      get list() {
        return Array.isArray(this.todos) ? this.todos : [];
      },
    };
  </script>
</wcs-state>

<wcs-storage key="todos" type="local" data-wcs="value#init=element: todos"></wcs-storage>
```

- `#init=element` は**初期の state→element 書き込みを行わず**（clobber しない）、**要素の現在の `value` を state スロットへ pull します**（取り逃さない）。
- authority が支配するのは*初期同期のみ*です。以後の `todos` 代入は通常どおり state→element に流れるので、自動保存は生きたままです。
- シードは要素の実初期値（空キーなら `null`）に合わせ、読み出しは派生 getter で null ガードしてください。`[]` や `""` のような都合のよいシードは、どのみち初期 pull で置き換えられます。
- `enableDirectionalInitialSync`（v1.21.0 以降は既定 ON。4.0 では `bootstrapState()` のオプションではなく、ルートの state の `$behavior` のキー）が前提です。無効化した場合（`$behavior: { enableDirectionalInitialSync: false }`）`#init=` は throw するので、その構成では `undefined` シード + `$connectedCallback` での一度きり pull に倒してください。
- 動作する実例: `examples/state-cross-tab-todo`、`examples/state-color-palette`。

## ステートサーフェス vs コマンドサーフェス

`<wcs-storage>` は 2 種類のプロパティを公開します。

### 出力ステート（バインド可能な状態）

現在のストレージの値を表し、CSBC のメインサーフェスです:

| プロパティ | 型 | 説明 |
|------------|------|------|
| `value` | `any` | ストレージに保存された値 |
| `loading` | `boolean` | 読み書き中は `true` |
| `error` | `WcsStorageError \| Error \| null` | ストレージ操作のエラー |

### 入力 / コマンドサーフェス

HTML、JS、または `@wcstack/state` バインディングからストレージ操作を制御します:

| プロパティ | 型 | 説明 |
|------------|------|------|
| `key` | `string` | ストレージキー |
| `storageKey` | `string` | React と Vue のための、`key` の別名（4.6 から。[フレームワーク連携](#フレームワーク連携) を参照） |
| `type` | `"local" \| "session"` | ストレージタイプ |
| `value` | `any` | 設定すると自動保存（`manual` でない場合） |
| `trigger` | `boolean` | 単方向の保存トリガー |
| `manual` | `boolean` | 自動読み込み・自動保存を無効化 |

**`null` と `undefined`。** 属性に対応する入力（`key`・`type`・`manual`）は、`null` を「クリア」として扱います。属性を外し、入力は既定値（key なし・`local`・manual でない）に戻ります。`undefined` は「値が無い」で、属性を最初の書き込みの前の状態 — マークアップに書かれた値、無ければ属性なし — に戻します。どちらも文字列 `"null"` / `"undefined"` として書くことはありません（`@wcstack/state` は `undefined` を書きませんが、React 19 は値のあった prop を外したときに書き、直接の代入でも届きます）。`value = null` はストレージからキーを削除します（`manual` モードでは次の保存用に `null` をステージします）。`value = undefined` は何もしません — 保存済みのエントリは残り、何もステージしません。`trigger` はどちらも無視します。

## `:state()` による CSS スタイリング

`<wcs-storage>` は 2 つの boolean 出力ステートを
[`ElementInternals` の `CustomStateSet`](https://developer.mozilla.org/ja/docs/Web/API/CustomStateSet)
に反映します。そのため `data-wcs` バインディングやクラスの手動トグルなしに、CSS の
`:state()` 疑似クラスで直接スタイリングできます。

| ステート | on になる条件 |
|----------|----------------|
| `loading` | `wcs-storage:loading-changed` が `true` で発火（`false` でクリア） |
| `error` | `wcs-storage:error` が非 `null` の detail で発火（`null` でクリア） |

```css
wcs-storage:state(loading) ~ .spinner { display: block; }
wcs-storage:state(loading) ~ .spinner { display: none; } /* デフォルト */

form:has(wcs-storage:state(error)) .banner { display: block; }
```

属性やクラスと異なり `:state()` は要素の外部から書き込めないため、この出力ステートが
入力と混同される心配がありません。

**対応ブラウザ**（新構文 `:state(x)`）: Chrome/Edge 125+、Safari 17.4+、Firefox 126+。
非対応の環境ではステートが一切 set されないだけです — `:state()` セレクタがマッチしなく
なりますが、`<wcs-storage>` 自体は通常どおり動作し続けます（graceful degradation・never-throw）。

**SSR:** `:state()` は HTML にシリアライズできないため、サーバーレンダリングされた
マークアップの初期ペイントにはこれらのステートは乗りません（`@wcstack/server` は無改変）。
ハイドレーション前の見た目を制御したい場合は、代わりに `wcs-storage:not(:defined)` と組み合わせてください。

### デバッグ

カスタムステートは DevTools の Elements パネルには表示されず、`attachInternals()`
は同一要素に 2 回呼べないため、コンソールから直接覗く手段がありません。そのための
デバッグ専用の補助を 2 つ用意しています:

- `el.debugStates` — 現在 on になっているステート名の**スナップショット**配列
  （例: `["loading"]`）。`wc-bindable` の一部ではなく（バインド対象ではない）、
  形状も契約として保証されません — デバッグ用途にのみ使ってください。
- `debug-states` 属性（opt-in・既定 OFF）は、ステート変化を要素の
  `data-wcs-state-loading` / `data-wcs-state-error` 属性にミラーします。
  Elements パネルを開いておけば、トグルのたびにハイライトされます:

  ```html
  <wcs-storage key="prefs" debug-states></wcs-storage>
  ```

**CSS は `data-wcs-state-*` ではなく `:state()` に書いてください。** ミラーされた
属性は、DevTools を開いた状態でステート変化を可視化するためだけのものであり、
スタイリング用の正式なフックではありません。

## アーキテクチャ

`@wcstack/storage` は CSBC アーキテクチャに従います。

### Core: `StorageCore`

`StorageCore` は純粋な `EventTarget` クラスです。
以下を内包します:

- ストレージの読み込み・保存・削除
- JSON の自動シリアライズ / デシリアライズ
- クロスタブ同期（`storage` イベント監視）
- `wc-bindable-protocol` 宣言

`EventTarget` と `localStorage` / `sessionStorage` をサポートする任意のランタイムでヘッドレスに動作します。

### Shell: `<wcs-storage>`

`<wcs-storage>` は `StorageCore` の薄い `HTMLElement` ラッパーです。
以下を追加します:

- 属性 / プロパティマッピング
- DOM ライフサイクル統合（接続時に自動読み込み、切断時にクリーンアップ）
- `value` セッター経由の自動保存
- `trigger` などの宣言的実行ヘルパー

この分離により、ストレージロジックのポータビリティを保ちながら、`@wcstack/state` のような DOM ベースのバインディングシステムとの自然な連携を可能にしています。

### Target injection

Core は **target injection** により Shell 上で直接イベントを発火するため、イベントの再ディスパッチは不要です。

## ヘッドレス利用（Core 単体）

`StorageCore` は DOM なしで単体利用できます。`static wcBindable` を宣言しているため、`@wc-bindable/core` の `bind()` で状態をサブスクライブできます — フレームワークアダプタと同じ仕組みです:

```typescript
import { StorageCore } from "@wcstack/storage";
import { bind } from "@wc-bindable/core";

const core = new StorageCore();

const unbind = bind(core, (name, value) => {
  console.log(`${name}:`, value);
});

core.key = "my-data";
core.load();

unbind();
```

### JSON 自動シリアライズ

`StorageCore` はデータ型に応じて自動的にシリアライズ / デシリアライズを行います:

| 保存時の型 | ストレージ上の形式 | 読み込み時の型 |
|-----------|-------------------|--------------|
| オブジェクト / 配列 | `JSON.stringify()` 結果 | `JSON.parse()` 結果 |
| 文字列 | そのまま | JSON パース成功時はパース結果、失敗時はそのまま文字列 |
| 数値 / boolean | `JSON.stringify()` 結果 | `JSON.parse()` 結果 |
| `null` / `undefined` | キーを削除 | `null` |
| `Blob` / `File`、`Map` / `Set`、バイナリ（値のどこにあっても） | `{}`（JSON はどれも保てない） | 空のオブジェクト |

これは Core の `save(value)` の挙動です。保存した下書きに入れた録画クリップや選んだファイルは、再読み込みの後 `{}` で返ってきます。そうした値は保存する値の外に置いてください（IndexedDB かサーバに置く）。4.5 から、そうした値を持つ保存は、何がどこにあるかを添えて要素ごとに 1 回警告します（`[wcs/storage-unserializable]`）。要素の `value` セッターは `null` でキーを削除しますが、`undefined` は無視します（[入力 / コマンドサーフェス](#入力--コマンドサーフェス)参照）。

Core の構造サーフェスは wcstack I/O ノード横断の規範です([async-io-node-guidelines §3.9](../../docs/async-io-node-guidelines.ja.md))。要素なしで signals に束縛するには [@wcstack/signals — Core を直接束縛する](../signals/README.ja.md#core-を直接束縛する要素なし) を参照。

## 要素一覧

### `<wcs-storage>`

| 属性 | 型 | デフォルト | 説明 |
|------|------|------------|------|
| `key` | `string` | — | ストレージキー |
| `storage-key` | `string` | — | React と Vue が触らない名前のストレージキー（4.6 から）。両方書いたときは `key` が勝つ |
| `type` | `"local" \| "session"` | `local` | ストレージタイプ |
| `manual` | `boolean` | `false` | 自動読み込み・自動保存を無効化 |

| プロパティ | 型 | 説明 |
|------------|------|------|
| `value` | `any` | ストレージの値（設定すると自動保存） |
| `loading` | `boolean` | 読み書き中は `true` |
| `error` | `WcsStorageError \| Error \| null` | エラー情報 |
| `trigger` | `boolean` | `true` を設定すると save を実行 |
| `manual` | `boolean` | 自動モードの無効化 |

| メソッド | 説明 |
|----------|------|
| `load()` | ストレージから値を読み込み |
| `save()` | 現在の値をストレージに保存 |
| `remove()` | ストレージからキーを削除 |

## wc-bindable-protocol

`StorageCore` と `<wcs-storage>` はどちらも wc-bindable-protocol に準拠しており、プロトコル対応の任意のフレームワークやコンポーネントと相互運用できます。

宣言は wc-bindable インターフェースモデルの全体に従い、3 つの独立したサーフェスを持ちます:

- **`properties`** — `bind()` が購読する観測可能な出力（`value`, `loading`, `error`, および Shell の `trigger`）
- **`inputs`** — 設定可能なサーフェス（`key`, `type` など）。ツール・コード生成・リモートプロキシが読む宣言的メタデータ
- **`commands`** — 呼び出し可能なメソッド（`load`, `save`, `remove`）。`@wcstack/state` のようなバインディングシステムが名前で呼び出せる

プロトコル上、コアの `bind()` が解釈するのは `properties` のみです。`inputs` / `commands`（および `attribute` / `async` ヒント）は記述的なメタデータであり、暗黙の双方向データフローを生成しません。

### Core (`StorageCore`)

`StorageCore` は任意のランタイムが購読できるバインド可能な状態に加え、ポータブルな入力 / コマンドサーフェスを宣言します:

```typescript
static wcBindable = {
  protocol: "wc-bindable",
  version: 1,
  properties: [
    { name: "value",   event: "wcs-storage:value-changed",
      getter: (e) => e.detail },
    { name: "loading", event: "wcs-storage:loading-changed" },
    { name: "error",   event: "wcs-storage:error" },
  ],
  inputs: [
    { name: "key" },
    { name: "type" },
  ],
  commands: [
    { name: "load" },
    { name: "save" },
    { name: "remove" },
  ],
};
```

ヘッドレス利用では `core.load()` / `core.save(value)` を直接呼び出します — `trigger` は不要です。

### Shell (`<wcs-storage>`)

Shell は Core の宣言を `trigger` 出力と DOM 駆動の入力サーフェスで拡張します。`commands`（`load` / `save` / `remove`）は Core からそのまま継承されます:

```typescript
static wcBindable = {
  ...StorageCore.wcBindable,
  properties: [
    ...StorageCore.wcBindable.properties,
    { name: "trigger", event: "wcs-storage:trigger-changed" },
  ],
  inputs: [
    { name: "key" },
    { name: "storageKey" },
    { name: "type" },
    { name: "value" },
    { name: "manual" },
    { name: "trigger" },
  ],
};
```

Shell の inputs は意図的に `attribute` ヒントを持ちません: `key` / `storageKey` / `type` / `manual` のセッターは既に各属性へ反映するため、`inputs[].attribute` を反映するバインディングシステムだと属性を二重に設定してしまうからです。

## TypeScript 型

```typescript
import type {
  WcsStorageError, WcsStorageCoreValues, WcsStorageValues, StorageType
} from "@wcstack/storage";
```

```typescript
type StorageType = "local" | "session";

// ストレージ操作エラー
interface WcsStorageError {
  operation: "load" | "save" | "remove" | "type";
  message: string;
}

// Core（ヘッドレス）— 3 つの状態プロパティ
interface WcsStorageCoreValues<T = unknown> {
  value: T;
  loading: boolean;
  error: WcsStorageError | Error | null;
}

// Shell（<wcs-storage>）— Core を拡張し trigger を追加
interface WcsStorageValues<T = unknown> extends WcsStorageCoreValues<T> {
  trigger: boolean;
}
```

## なぜ `@wcstack/state` とうまく連携するのか

`@wcstack/state` は UI と状態の唯一の契約としてパス文字列を使います。
`<wcs-storage>` はこのモデルに自然に適合します:

- `<wcs-storage>` が接続時にストレージから自動読み込み
- `value` が状態パスにバインドされ、UI に反映
- ユーザーが UI を操作すると状態が変わり、自動的にストレージに書き戻し
- リロードしても状態が復元される
- バインドに `#init=element` を付け、スロットは `null` で開始する（クイックスタート 5）ため、リロードが保存値を上書きしない

永続化が通常の状態更新と同じように見えるようになります。

## フレームワーク連携

`<wcs-storage>` は CSBC + `wc-bindable-protocol` なので、`@wc-bindable/*` の薄いアダプタを通じて任意のフレームワークで動作します。

**フレームワークのテンプレートでは、`key` でなく `storage-key` を書いてください**（4.6 から）。React と Vue は `key` を自分のものとして取り、要素に渡しません。JSX や Vue のテンプレートの `<wcs-storage key="…">` には key が無く、何も読み込まず、何も保存しません。要素は最初の保存のときに `[wcs/command-not-ready]` で警告するようになりました。`storage-key`（プロパティは `storageKey`）は同じ入力で、以下の例はどのフレームワークでもこれを使います。4.5 以前では、ref を通してプロパティを設定してください: `el.key = "app-settings"`。

### React

```tsx
import { useWcBindable } from "@wc-bindable/react";
import type { WcsStorageValues } from "@wcstack/storage";

interface Settings { theme: string; lang: string; }

function SettingsPanel() {
  const [ref, { value: settings, loading, error }] =
    useWcBindable<HTMLElement, WcsStorageValues<Settings>>();

  return (
    <>
      <wcs-storage ref={ref} storage-key="app-settings" />
      {loading && <p>読み込み中...</p>}
      {settings && <p>テーマ: {settings.theme}</p>}
    </>
  );
}
```

**React から保存する。** 描画の中で作ったオブジェクトを `value` の prop で渡さないでください（`value={{ q, page }}`）。描画のたびに新しいオブジェクトを書き、書くたびに保存して `value` を知らせ、アダプターの更新がまた描画します。React は "Maximum update depth exceeded" で止まります。最初の描画は、空の既定値を保存済みの値の上に書いてしまいもします。保存済みの値を一度読み、その後はフィールドが変わったときだけ書いてください:

```tsx
type StorageElement = HTMLElement & { value: Filters | null };

function FilterStore({ filters, onRestore }: { filters: Filters; onRestore: (f: Filters) => void }) {
  const el = useRef<StorageElement | null>(null);
  const [restored, setRestored] = useState(false);
  // 要素は接続したときに読み込み、ref はその後に走る: 保存済みの値を一度読む
  const ref = useCallback((node: StorageElement | null) => {
    el.current = node;
    if (node === null) return;
    if (node.value) onRestore(node.value);
    setRestored(true);
  }, []); // eslint-disable-line react-hooks/exhaustive-deps
  // 読んだ後に、フィールドが変わったときだけ保存する: 依存はオブジェクトでなくフィールド
  useEffect(() => {
    if (restored && el.current) el.current.value = { q: filters.q, page: filters.page };
  }, [restored, filters.q, filters.page]);
  return <wcs-storage ref={ref} storage-key="inv-filters" />;
}
```

`@wcstack/state` では `value#init=element` が同じことをします（[§5](#5-load-before-bind-initelement)）。

**他のタブに追随する。** 他のタブの保存は `wcs-storage:value-changed` で届きます。要素でそれを聴き、自分の保存が出すイベント（代入の最中に出ます）は飛ばしてください。代わりにアダプターの `value` を当てると、自分の保存が 1 描画遅れて戻り、その間に打った分を巻き戻します: "bolt" を速く打つと、"bol" と "bolt" を交互に保存して当てることが止まりませんでした。

```tsx
const saving = useRef(false);
useEffect(() => {
  const node = el.current;
  if (!node) return;
  const onChange = (e: Event) => {
    const v = (e as CustomEvent<Filters | null>).detail;
    if (!saving.current && v) onRestore(v);
  };
  node.addEventListener("wcs-storage:value-changed", onChange);
  return () => node.removeEventListener("wcs-storage:value-changed", onChange);
}, []); // eslint-disable-line react-hooks/exhaustive-deps
// 保存する effect の中で:
//   saving.current = true; try { el.current.value = { q: filters.q, page: filters.page }; } finally { saving.current = false; }
```

[`examples/fw-inventory`](../../examples/fw-inventory/) はフィルタをこの形で保ちます。

### Vue

```vue
<script setup lang="ts">
import { useWcBindable } from "@wc-bindable/vue";
import type { WcsStorageValues } from "@wcstack/storage";

interface Settings { theme: string; lang: string; }

const { ref: settings, values } = useWcBindable<HTMLElement, WcsStorageValues<Settings>>();
</script>

<template>
  <wcs-storage ref="settings" storage-key="app-settings" />
  <p v-if="values.loading">読み込み中...</p>
  <p v-else-if="values.value">テーマ: {{ values.value.theme }}</p>
</template>
```

テンプレート ref は静的に名前で書きます（`ref="settings"`）。`<script setup>` の `:ref="…"` には ref が剥がされた値（`null`）が渡り、アダプターは束縛しません。

### Svelte

```svelte
<script>
import { wcBindable } from "@wc-bindable/svelte";

let settings = $state(null);
let loading = $state(false);
</script>

<wcs-storage storage-key="app-settings"
  use:wcBindable={{ onUpdate: (name, v) => {
    if (name === "value") settings = v;
    if (name === "loading") loading = v;
  }}} />

{#if loading}
  <p>読み込み中...</p>
{:else if settings}
  <p>テーマ: {settings.theme}</p>
{/if}
```

### Solid

```tsx
import { createWcBindable } from "@wc-bindable/solid";
import type { WcsStorageValues } from "@wcstack/storage";

interface Settings { theme: string; lang: string; }

function SettingsPanel() {
  const [values, directive] = createWcBindable<WcsStorageValues<Settings>>();

  return (
    <>
      <wcs-storage ref={directive} storage-key="app-settings" />
      <Show when={!values.loading} fallback={<p>読み込み中...</p>}>
        <p>テーマ: {values.value?.theme}</p>
      </Show>
    </>
  );
}
```

### Vanilla — `bind()` を直接利用

```javascript
import { bind } from "@wc-bindable/core";

const storageEl = document.querySelector("wcs-storage");

bind(storageEl, (name, value) => {
  console.log(`${name} changed:`, value);
});
```

## オプションの DOM トリガー

`autoTrigger` が有効（デフォルト）の場合、`data-storagetarget` 属性を持つ要素のクリックで対応する `<wcs-storage>` の `save()` が実行されます:

```html
<button data-storagetarget="settings-store">設定を保存</button>
<wcs-storage id="settings-store" key="settings" manual
  data-wcs="value: settings"></wcs-storage>
```

## 設定

```javascript
import { bootstrapStorage } from "@wcstack/storage";

bootstrapStorage({
  autoTrigger: true,
  triggerAttribute: "data-storagetarget",
  tagNames: {
    storage: "wcs-storage",
  },
});
```

`bootstrapStorage()` は、持っていないオプション、既定値と型の違う値（`null` や、オブジェクトの所の配列を含む）、定義していない `tagNames` のキー、文字列でないタグ名で例外を投げます。当てる前にすべてのオプションを確かめるので、投げたときは何も当てません。値が `undefined` のオプションは飛ばします。

## 設計メモ

- **4.8 から、入れ直しの読み込みはマイクロタスクで行う。** 最初の接続はその場で読み込む — 同じタスクで付いた束縛が `value` を引き、読み込み済みであることを当てにする。入れ直しは 1 マイクロタスク後に、そのときの `key` で読み込む（[タイミング契約](../../docs/timing-and-firing-contract.ja.md) §23）。`@wcstack/router` はパラメータだけの遷移でルートの要素を入れ直し、`@wcstack/state` が次のルートの入力を書くのはその後で、その場で読み込むと前のルートのキーを読み、その値を一瞬知らせていた。
- `value`、`loading`、`error` は **出力ステート**
- `key`、`type`、`trigger` は **入力 / コマンドサーフェス**
- `trigger` は意図的に単方向: `true` を書き込むと保存、リセットで完了を通知。`save()` は never-throw（`key` 未設定などの失敗は throw せず `error` プロパティに流す）で、`trigger` は成否にかかわらず `false` へ復帰し完了イベントも発火するため、`true` で固着しない。
- `value` セッターは `manual` でない場合に自動保存を行う
- **`value` セッター vs `save()` / `trigger`**: `value` への代入（非 manual）は *代入された引数* を保存する（ライトスルー）。一方 `save()` と `trigger` は *現在の `value`*（直前の `load()` や他タブからの `storage` イベントで更新されうる）を保存する。このため `trigger`/`save()` は他タブ由来の値を書き戻す可能性がある。
- **`manual` モードでの `value`**: `manual` では `value` セッターは値を**ステージング**する（ストレージへは書き込まない）。`el.value = x` で読み取り値は更新される（`el.value === x`）が、ストレージには触れず、実際の書き込みは `save()` / `trigger` でのみ行われる。これにより `value: …` + `trigger: …` のバインディング対が機能する — バインドされた値がステージングされ、トリガー時にコミットされる。
- **非 manual の `value` 経路にはエコーガードを置かない**: 同値の `value-changed` 再発火をスキップするのは*ステージング*経路（`manual` モードで使う Core の `value` セッター）のみ。主経路である非 manual の `value` セッター → `save()` は意図的にライトスルーであり、代入値が現在値と等しくても毎回保存し `value-changed` を再発火する。これは仕様である — 上記のライトスルー契約を保つ必要があり、同一タブでは `storage` イベントが再発火しないためフィードバックループは生じない。`data-wcs="value: x"` の双方向バインディングでもエコーされる `value-changed` は無害で、`@wcstack/state` 側がラウンドトリップを重複排除する。
- **`save` コマンドのアリティ**: ヘッドレスな Core は `save(value)`、Shell は `save()`（現在値を保存）。どちらも同じ `commands` 名 `save` に現れるが、プロトコルの `commands` メタデータは記述的でアリティを持たないため、これは契約上の差異でありプロトコル違反ではない。
- **不正な `type`**: `"session"` 以外の `type` 属性はすべて `"local"` として扱う。不正値（例: `type="sesion"`）は例外を投げずに `local` へフォールバックし、要素は値ごとに 1 回 `[wcs/storage-type-invalid]` で警告する（データはセッションが終わってもディスクに残る）。
- **実行時の `type` 変更**: 接続後に `type` 属性を変更すると以降の操作で使うストレージ領域は切り替わるが、新しい領域から**自動で再ロードはしない**（非 manual で自動再ロードするのは `key` 変更時のみ）。新領域の値が必要なら明示的に `load()` を呼ぶこと。
- **`error` の形状**: ストレージ失敗時、`error` には失敗した呼び出し（`load` / `save` / `remove`、あるいはヘッドレスで不正な `type` を代入した場合の `type`）を示す `WcsStorageError`（`{ operation, message }`）が設定される。操作は **never-throw**: key 未設定での操作呼び出しは throw せず `error` に `{ operation, message: "key is required." }` として流れ（`wcs-storage:error` も発火）、要素が `[wcs/command-not-ready]` で警告する。警告は key がまた来るまで 1 回（4.8 から。それまでは要素ごとに 1 回）。したがって実際には `error` は常に `WcsStorageError` か `null` のいずれかになる。より広い `WcsStorageError | Error | null` 型は前方互換性と兄弟パッケージとの一貫性のために維持している。
- JSON 自動シリアライズにより、オブジェクト / 配列 / プリミティブを透過的に扱える
- `null` の保存はストレージからのキー削除として扱われる（Core の `save(undefined)` も同じ）。要素の `value` への `undefined` の代入は何もせず、保存済みのエントリを残す
- `storage` イベントによるクロスタブ同期は localStorage でのみ動作。Shell は接続時（および再 attach 時）に監視を現在の `key` / `type` へ結びつけるため、自動ロードが走らない `manual` モードでもクロスタブ同期が機能する。接続後に `key` 属性を変更した場合も常に Core の key を再同期するため、`manual` モードや key を空にした場合でもクロスタブ同期は新しい key を追従する。クロスタブ更新が成功すると残存していた `error` もクリアされる（`load()` / `save()` / `remove()` が成功時に冒頭で error を null にするのと同様）。これにより、過去の失敗で残った error と新鮮な value が共存しない。
- `manual` は保存タイミングを明示的に制御したい場合に有用

## ライセンス

MIT
