@wcstack/storage 1.22.5 → 1.22.6

package/README.ja.md

@@ -55,15 +55,14 @@ npm install @wcstack/storage
 <wcs-state>
   <script type="module">
     export default {
-      // 意図的に undefined — "" や null で初期化すると双方向バインディング
-      // 経由で書き戻され、リロードのたびに保存値を上書きしてしまう
-      // （下記「5. load-before-bind」参照）
-      username: undefined,
+      // 空のキーは null をロードする — 都合のよい初期値ではなく
+      // 要素の実初期値をシードする（下記「5. load-before-bind」参照）
+      username: null,
     };
   </script>
 </wcs-state>
 
-<wcs-storage key="username" data-wcs="value: username"></wcs-storage>
+<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>
@@ -74,7 +73,7 @@ npm install @wcstack/storage
 - `key` を設定すると接続時に自動読み込み
 - `value` にバインドすると双方向永続化
 - 任意で `loading`、`error` もバインド
-- バインドする state スロットは `undefined` で開始する — 完全な idiom は「5. load-before-bind」を参照
+- `value` バインディングに `#init=element` を付けて保存値を初期同期の勝者にする — 理由は「5. load-before-bind」を参照
 
 ### 2. オブジェクトの永続化と `$trackDependency`
 
@@ -146,14 +145,14 @@ localStorage の変更は、別のタブからの更新も自動的に検知さ
 <wcs-state>
   <script type="module">
     export default {
-      // 意図的に undefined — 下記「5. load-before-bind」参照
-      sharedCounter: undefined,
+      // 下記「5. load-before-bind」参照
+      sharedCounter: null,
     };
   </script>
 </wcs-state>
 
 <wcs-storage key="shared-counter"
-  data-wcs="value: sharedCounter">
+  data-wcs="value#init=element: sharedCounter">
 </wcs-storage>
 
 <!-- 他のタブで localStorage を変更すると、この値も自動更新される -->
@@ -162,47 +161,36 @@ localStorage の変更は、別のタブからの更新も自動的に検知さ
 
 > **注意**: `storage` イベントは同一オリジンの他のタブでの変更時にのみ発火します。sessionStorage はタブ間で共有されないため、クロスタブ同期は localStorage でのみ動作します。
 
-### 5. load-before-bind: 永続スロットの idiom
+### 5. load-before-bind: `#init=element`
 
 `<wcs-storage>` は自身の `connectedCallback` で永続値をロードして通知します。スクリプトのロード状況によっては、これは `<wcs-state>` のバインディング確立**前**に起こりえます — 帰結は 2 つ:
 
-1. **上書き消去（clobber）**: バインドした state スロットが `""` / `0` / `null` / `[]` で始まると、初期の state→element 適用がその値を `value` に書き込み、write-through 保存が**リロードのたびに永続データを上書き**します。
-2. **ロードの取り逃し**: ロード完了を知らせる value イベントが誰も聴いていない間に発火し、state スロットが初期値のまま残ることがあります。
+1. **上書き消去（clobber）**: `value` はこの要素で唯一の*双方向*メンバなので、既定のバインディング authority は `state` です。初期の state→element 適用が state スロットのシード値を `value` に書き込み、write-through 保存が**リロードのたびに永続データを上書き**します。
+2. **ロードの取り逃し**: ロード完了を知らせる value イベントが誰も聴いていない間に発火し、state スロットがシード値のまま残ることがあります。
 
-両方を塞ぐ idiom:
+両方を塞ぐのは修飾子 1 つです。`#init=element` は初期同期の authority を**要素側**にします:
 
 ```html
 <wcs-state>
   <script type="module">
     export default {
-      // 1. undefined =「無意見」: 初期適用がスキップされ、
-      //    永続値が上書きされることはない
-      todos: undefined,
-      // 読み出しは正規化 getter 経由
+      // 空のキーは null をロードするので、それが正直なシード値。
+      // 都合のよい [] ではなく正規化 getter 経由で読む。
+      todos: null,
       get list() {
         return Array.isArray(this.todos) ? this.todos : [];
       },
-      // 2. <wcs-storage> がロード済みの値を一度だけ pull する
-      $connectedCallback() {
-        (async () => {
-          await customElements.whenDefined("wcs-storage");
-          const el = document.querySelector("wcs-storage");
-          if (!el) return;
-          await el.connectedCallbackPromise;
-          if (!Array.isArray(this.todos) && Array.isArray(el.value)) {
-            this.todos = el.value;
-          }
-        })();
-      },
     };
   </script>
 </wcs-state>
 
-<wcs-storage key="todos" type="local" data-wcs="value: todos"></wcs-storage>
+<wcs-storage key="todos" type="local" data-wcs="value#init=element: todos"></wcs-storage>
 ```
 
-- 原則: **`value` に双方向バインドする state スロットは `undefined` で開始する** — `""` / `0` / `null` / `[]` にしない。
-- `$connectedCallback` の pull が必要なのは、永続値を初回描画で表示したい場合だけです。ユーザー操作後にしか書かないスロットなら `undefined` だけで十分です。
+- `#init=element` は**初期の state→element 書き込みを行わず**（clobber しない）、**要素の現在の `value` を state スロットへ pull します**（取り逃さない）。
+- authority が支配するのは*初期同期のみ*です。以後の `todos` 代入は通常どおり state→element に流れるので、自動保存は生きたままです。
+- シードは要素の実初期値（空キーなら `null`）に合わせ、読み出しは派生 getter で null ガードしてください。`[]` や `""` のような都合のよいシードは、どのみち初期 pull で置き換えられます。
+- `enableDirectionalInitialSync`（v1.21.0 以降は既定 ON）が前提です。明示的に無効化した場合 `#init=` は throw するので、その構成では `undefined` シード + `$connectedCallback` での一度きり pull に倒してください。
 - 動作する実例: `examples/state-cross-tab-todo`、`examples/state-color-palette`。
 
 ## ステートサーフェス vs コマンドサーフェス

package/README.md

@@ -54,15 +54,14 @@ Primitive values (strings, numbers, booleans) work with just a `value` binding f
 <wcs-state>
   <script type="module">
     export default {
-      // undefined on purpose — a "" / null initial would be written back
-      // through the two-way binding and overwrite the saved value on
-      // reload (see "5. Load-before-bind" below)
-      username: undefined,
+      // null is what an empty key loads as — seed the element's real initial
+      // value, not a convenient one (see "5. Load-before-bind" below)
+      username: null,
     };
   </script>
 </wcs-state>
 
-<wcs-storage key="username" data-wcs="value: username"></wcs-storage>
+<wcs-storage key="username" data-wcs="value#init=element: username"></wcs-storage>
 
 <input data-wcs="value: username" placeholder="Username">
 <p>Saved: <span data-wcs="textContent: username"></span></p>
@@ -73,7 +72,7 @@ This is the default mode:
 - Set a `key` to auto-load on connection
 - Bind to `value` for two-way persistence
 - Optionally bind `loading` and `error` as well
-- Start the bound state slot as `undefined` — see [5. Load-before-bind](#5-load-before-bind-the-persistent-slot-idiom) for the full idiom
+- Add `#init=element` to the `value` binding so the stored value wins the initial sync — see [5. Load-before-bind](#5-load-before-bind-initelement) for why
 
 ### 2. Persisting objects with `$trackDependency`
 
@@ -145,14 +144,14 @@ localStorage changes are automatically detected from other tabs:
 <wcs-state>
   <script type="module">
     export default {
-      // undefined on purpose — see "5. Load-before-bind" below
-      sharedCounter: undefined,
+      // see "5. Load-before-bind" below
+      sharedCounter: null,
     };
   </script>
 </wcs-state>
 
 <wcs-storage key="shared-counter"
-  data-wcs="value: sharedCounter">
+  data-wcs="value#init=element: sharedCounter">
 </wcs-storage>
 
 <!-- Changes from other tabs update this value automatically -->
@@ -161,47 +160,36 @@ localStorage changes are automatically detected from other tabs:
 
 > **Note**: The `storage` event only fires for changes made in other tabs of the same origin. Since sessionStorage is not shared across tabs, cross-tab sync only works with localStorage.
 
-### 5. Load-before-bind: the persistent-slot idiom
+### 5. Load-before-bind: `#init=element`
 
 `<wcs-storage>` loads and announces the persisted value in its own `connectedCallback`. Depending on script loading, that can happen **before** `<wcs-state>` finishes attaching its bindings — with two consequences:
 
-1. **Clobber**: if the bound state slot starts as `""` / `0` / `null` / `[]`, the initial state→element apply writes that value into `value`, and the write-through save **overwrites the persisted data on every reload**.
-2. **Missed load**: the value event announcing the loaded data fired before anyone was listening, so the state slot can stay at its initial value.
+1. **Clobber**: `value` is the one *bidirectional* member on this element, so its default binding authority is `state`. The initial state→element apply writes the state slot's seed into `value`, and the write-through save **overwrites the persisted data on every reload**.
+2. **Missed load**: the value event announcing the loaded data fired before anyone was listening, so the state slot can stay at its seed.
 
-The idiom that closes both:
+One modifier closes both. `#init=element` makes the **element** the authority for the initial sync:
 
 ```html
 <wcs-state>
   <script type="module">
     export default {
-      // 1. undefined = "no opinion": the initial apply is skipped,
-      //    so the persisted value is never clobbered
-      todos: undefined,
-      // reads go through a normalizing getter
+      // An empty key loads as null, so that is the honest seed. Reads go
+      // through a normalizing getter instead of a convenient [] seed.
+      todos: null,
       get list() {
         return Array.isArray(this.todos) ? this.todos : [];
       },
-      // 2. pull the value <wcs-storage> already loaded, once
-      $connectedCallback() {
-        (async () => {
-          await customElements.whenDefined("wcs-storage");
-          const el = document.querySelector("wcs-storage");
-          if (!el) return;
-          await el.connectedCallbackPromise;
-          if (!Array.isArray(this.todos) && Array.isArray(el.value)) {
-            this.todos = el.value;
-          }
-        })();
-      },
     };
   </script>
 </wcs-state>
 
-<wcs-storage key="todos" type="local" data-wcs="value: todos"></wcs-storage>
+<wcs-storage key="todos" type="local" data-wcs="value#init=element: todos"></wcs-storage>
 ```
 
-- Rule of thumb: **a state slot bound two-way to `value` must start as `undefined`** — never `""` / `0` / `null` / `[]`.
-- The `$connectedCallback` pull is only needed when the persisted value must render on first paint. If the slot is only ever written after user interaction, `undefined` alone is enough.
+- `#init=element` **skips the initial state→element write** (no clobber) and **pulls the element's current `value` into the state slot** (no missed load).
+- Authority governs the *initial sync only*: every later `todos` assignment still flows state→element, so auto-save keeps working.
+- Seed the slot with the element's real initial value (`null` for an empty key) and null-guard reads through a derived getter. A convenient `[]` / `""` seed does not survive the initial pull anyway.
+- Needs `enableDirectionalInitialSync`, on by default since v1.21.0. If you explicitly disable it, `#init=` throws; seed `undefined` and pull once in `$connectedCallback` instead.
 - Working examples: `examples/state-cross-tab-todo`, `examples/state-color-palette`.
 
 ## State Surface vs Command Surface

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wcstack/storage",
-  "version": "1.22.5",
+  "version": "1.22.6",
   "description": "Declarative persistent storage component for Web Components. Framework-agnostic localStorage/sessionStorage via wc-bindable-protocol.",
   "type": "module",
   "main": "./dist/index.esm.js",