@wcstack/network 1.22.5 → 1.23.0

package/README.ja.md

@@ -52,11 +52,6 @@ npm install @wcstack/network
       get imgSrc() {
         return this.lowQuality ? "/thumb.jpg" : "/full.jpg";
       },
-      // 初回スナップショットはバインド確立前に発火するため、一度だけ pull する（「注意・制限」参照）。
-      async $connectedCallback() {
-        await customElements.whenDefined("wcs-network");
-        this.effectiveType = document.querySelector("wcs-network").effectiveType;
-      },
     };
   </script>
 </wcs-state>
@@ -66,7 +61,7 @@ npm install @wcstack/network
 <img data-wcs="attr.src: imgSrc">
 ```
 
-このページの全例に共通するタイミング規則が1つあります: `<wcs-network>` はスナップショットを `wcs-network:change` イベントで公開しますが、*初回*のスナップショットは接続時に同期発火するため、`@wcstack/state` がバインドリスナーを張るより先に流れてしまい、バインドしたパスは*次*の回線変化からしか更新されません。上の `$connectedCallback` ブロックはその初回スナップショットを一度だけ pull しています。これが無いと、読込時点で既に低速回線だった場合にページが適応しません（「注意・制限」参照）。
+このページの全例に共通するタイミング規則が1つあります: `<wcs-network>` はスナップショットを `wcs-network:change` イベントで公開しますが、*初回*のスナップショットは接続時に同期発火するため、`@wcstack/state` がバインドリスナーを張るより先に流れてしまいます。それでも初期値が届くのは、`<wcs-network>` の観測可能プロパティがすべて output-only（`properties` にのみ宣言され `inputs` に無い）だからです — 既定の binding authority が `element` になり、バインド確立時に**イベントを待たずプロパティを直接読みます**（directional initial sync、v1.21.0 以降は既定 ON）。手動 pull は不要です（「注意・制限」参照）。
 
 ### 2. データセーバーを尊重する
 
@@ -74,12 +69,9 @@ npm install @wcstack/network
 <wcs-state>
   <script type="module">
     export default {
+      // 読込時点で既にデータセーバーONでも、初期スナップショットが
+      // バインド確立時に pull されるので追加の配線は要りません。
       saveData: null,
-      // 例1と同じ初期 pull — 読込時点で既にデータセーバーONの場合があるため。
-      async $connectedCallback() {
-        await customElements.whenDefined("wcs-network");
-        this.saveData = document.querySelector("wcs-network").saveData;
-      },
     };
   </script>
 </wcs-state>
@@ -98,12 +90,6 @@ npm install @wcstack/network
     export default {
       netSupported: false,
       effectiveType: null,
-      async $connectedCallback() {
-        await customElements.whenDefined("wcs-network");
-        const net = document.querySelector("wcs-network");
-        this.netSupported = net.supported;
-        this.effectiveType = net.effectiveType;
-      },
     };
   </script>
 </wcs-state>
@@ -112,7 +98,7 @@ npm install @wcstack/network
 <div data-wcs="hidden: netSupported|not">回線: <span data-wcs="textContent: effectiveType"></span></div>
 ```
 
-バインドする state パスは必ず事前に宣言してください — 未宣言パスへのバインドは初期化時に例外になります。例2の `saveData` と異なり `supported` は厳密な boolean（`null` になり得ない）なので、ここでは `|not` が安全です。この例では初期 pull が*必須*です: `supported` は接続時に一度だけ確定し、安定した回線では以後 `change` が二度と発火しないため、pull が無いと対応ブラウザでも UI が永久に隠れたままになります。非対応ブラウザでは pull が `false` を読むだけなので、UI はそのまま隠れ続けます。
+バインドする state パスは必ず事前に宣言してください — 未宣言パスへのバインドは初期化時に例外になります。例2の `saveData` と異なり `supported` は厳密な boolean（`null` になり得ない）なので、ここでは `|not` が安全です。この例は初期スナップショットの pull に**最も強く依存**します: `supported` は接続時に一度だけ確定し、安定した回線では以後 `change` が二度と発火しないため、バインド確立時の pull が唯一の到達経路です（実ブラウザ回帰 = `e2e/tests/monitor-initial-snapshot.spec.ts`）。非対応ブラウザでは pull が `false` を読むだけなので、UI はそのまま隠れ続けます。
 
 ## 観測可能プロパティ（出力）
 
@@ -139,7 +125,7 @@ npm install @wcstack/network
 ## 注意・制限
 
 - **Firefox と Safari は `navigator.connection` を実装していません。** これらのブラウザでは `supported` は `false` のまま、他の4プロパティは `null` のままです — これを例外ケースでなく常態として設計してください。
-- **初回スナップショットはバインドに届きません。** 最初の `wcs-network:change` は `connectedCallback` 中に同期発火しますが、`@wcstack/state` のバインドリスナー確立はそれより後です（バインド構築は後続の microtask に遅延 — `docs/timing-and-firing-contract.md` §4.1 参照）。イベントは後から購読した相手に再送されないため、バインドしたパスは*次*の回線変化からしか更新されません。初期値が重要な場合（`supported` と `saveData` ではほぼ常に重要）は、クイックスタートの各例のように `$connectedCallback` で一度だけ pull してください。これは全 monitor ノード共通の wc-bindable イベント契約の性質であり、本パッケージ固有の癖ではありません。
+- **初回スナップショットの*イベント*はバインドに届きませんが、値は届きます。** 最初の `wcs-network:change` は `connectedCallback` 中に同期発火しますが、`@wcstack/state` のバインドリスナー確立はそれより後です（バインド構築は後続の microtask に遅延 — `docs/timing-and-firing-contract.md` §4.1 参照）。イベントは後から購読した相手に再送されません。それでも初期値が失われないのは、本ノードの観測可能プロパティがすべて output-only（`properties` のみ・`inputs` に無い）で、既定の binding authority が `element` になるためです: バインドは確立時にプロパティを直接読みます（directional initial sync、v1.21.0 以降は既定 ON）。手動 pull は不要で、これは全 monitor ノード共通の挙動です。`enableDirectionalInitialSync: false` に倒した構成でのみ、`$connectedCallback` + `whenDefined` での手動 pull が再び必要になります。
 - **`_gen` 世代ガードが無い。** 他の大半の wcstack IO ノードと異なり、`navigator.connection` の `change` イベント購読・購読解除は完全に同期的です。dispose() とレースしうる非同期probeの解決が存在しません。詳細は `docs/network-tag-design.md` §5。
 - **再接続で再購読。** 要素を取り外して再挿入すると、切断時に `change` リスナーを解除し、再接続時に（その時点の `navigator.connection` に対して）再確立します。
 - **SSR（`@wcstack/server`）。** `static hasConnectedCallbackPromise = true` を宣言し `connectedCallbackPromise` を公開しますが、`observe()` が同期的なため、この promise は常に即座に settle します。
@@ -217,6 +203,8 @@ console.log(net.effectiveType);
 net.dispose();           // live な `change` リスナーを外す
 ```
 
+Core の構造サーフェスは wcstack I/O ノード横断の規範です([async-io-node-guidelines §3.9](../../docs/async-io-node-guidelines.md))。要素なしで signals に束縛するには [@wcstack/signals — Core を直接束縛する](../signals/README.ja.md#core-を直接束縛する要素なし) を参照。
+
 ## ライセンス
 
 MIT

package/README.md

@@ -52,11 +52,6 @@ npm install @wcstack/network
       get imgSrc() {
         return this.lowQuality ? "/thumb.jpg" : "/full.jpg";
       },
-      // The initial snapshot fires before bindings attach — pull it once (see Notes).
-      async $connectedCallback() {
-        await customElements.whenDefined("wcs-network");
-        this.effectiveType = document.querySelector("wcs-network").effectiveType;
-      },
     };
   </script>
 </wcs-state>
@@ -66,7 +61,7 @@ npm install @wcstack/network
 <img data-wcs="attr.src: imgSrc">
 ```
 
-One timing rule applies to every example on this page: `<wcs-network>` publishes its snapshot through `wcs-network:change` events, and the *first* snapshot fires synchronously at connect — before `@wcstack/state` has attached its binding listeners — so bound paths only start updating from the *next* connection change. The `$connectedCallback` block pulls that initial snapshot once; without it, this page would not adapt when the connection is already slow at load time (see Notes & limitations).
+One timing rule applies to every example on this page: `<wcs-network>` publishes its snapshot through `wcs-network:change` events, and the *first* snapshot fires synchronously at connect — before `@wcstack/state` has attached its binding listeners. The initial value still arrives, because every observable property on `<wcs-network>` is output-only (declared in `properties`, absent from `inputs`): that makes the default binding authority `element`, so the binding **reads the property directly when it attaches** instead of waiting for an event it already missed (directional initial sync, on by default since v1.21.0). No manual pull is needed (see Notes & limitations).
 
 ### 2. Respect Data Saver
 
@@ -74,12 +69,9 @@ One timing rule applies to every example on this page: `<wcs-network>` publishes
 <wcs-state>
   <script type="module">
     export default {
+      // Data Saver may already be on at load time; the initial snapshot is
+      // pulled when the binding attaches, so no extra wiring is needed.
       saveData: null,
-      // Initial pull, as in example 1 — Data Saver may already be on at load time.
-      async $connectedCallback() {
-        await customElements.whenDefined("wcs-network");
-        this.saveData = document.querySelector("wcs-network").saveData;
-      },
     };
   </script>
 </wcs-state>
@@ -98,12 +90,6 @@ One timing rule applies to every example on this page: `<wcs-network>` publishes
     export default {
       netSupported: false,
       effectiveType: null,
-      async $connectedCallback() {
-        await customElements.whenDefined("wcs-network");
-        const net = document.querySelector("wcs-network");
-        this.netSupported = net.supported;
-        this.effectiveType = net.effectiveType;
-      },
     };
   </script>
 </wcs-state>
@@ -112,7 +98,7 @@ One timing rule applies to every example on this page: `<wcs-network>` publishes
 <div data-wcs="hidden: netSupported|not">Connection: <span data-wcs="textContent: effectiveType"></span></div>
 ```
 
-Every bound state path must be declared up front — binding an undeclared path throws at initialization. Unlike `saveData` above, `supported` is a strict boolean (never `null`), so `|not` is safe here. The initial pull is *essential* in this example: `supported` is set exactly once at connect, and a stable connection never fires another `change` — without the pull the UI would stay hidden forever even in supporting browsers. In an unsupported browser the pull reads `false`, so the UI simply stays hidden.
+Every bound state path must be declared up front — binding an undeclared path throws at initialization. Unlike `saveData` above, `supported` is a strict boolean (never `null`), so `|not` is safe here. This example leans hardest on the initial snapshot pull: `supported` is set exactly once at connect and a stable connection never fires another `change`, so the read at binding-attach time is its only delivery path (real-browser regression: `e2e/tests/monitor-initial-snapshot.spec.ts`). In an unsupported browser that read returns `false`, so the UI simply stays hidden.
 
 ## Observable Properties (outputs)
 
@@ -139,7 +125,7 @@ All five derive from the single `wcs-network:change` event (a full snapshot disp
 ## Notes & limitations
 
 - **Firefox and Safari do not implement `navigator.connection`.** `supported` stays `false` and the other four properties stay `null` in those browsers — design around this as the common case, not an edge case.
-- **The initial snapshot does not reach bindings.** The first `wcs-network:change` fires synchronously during `connectedCallback` — before `@wcstack/state` attaches its binding listeners (binding setup is deferred to a later microtask; see `docs/timing-and-firing-contract.md` §4.1) — and events are not replayed to late subscribers, so bound paths update only from the *next* connection change. If the initial value matters (it almost always does for `supported` and `saveData`), pull it once in `$connectedCallback` as the Quick Start examples do. This is a property of the wc-bindable event contract shared by all monitor nodes, not a quirk of this package.
+- **The initial snapshot *event* misses bindings, but the value still arrives.** The first `wcs-network:change` fires synchronously during `connectedCallback` — before `@wcstack/state` attaches its binding listeners (binding setup is deferred to a later microtask; see `docs/timing-and-firing-contract.md` §4.1) — and events are not replayed to late subscribers. The value is not lost, because every observable property here is output-only (`properties` only, never `inputs`), which makes the default binding authority `element`: the binding reads the property directly when it attaches (directional initial sync, on by default since v1.21.0). No manual pull is needed, and this holds for every monitor node. Only if you explicitly set `enableDirectionalInitialSync: false` do you need the older `$connectedCallback` + `whenDefined` pull again.
 - **No `_gen` generation guard.** Unlike most wcstack IO nodes, subscribing to `navigator.connection`'s `change` event is fully synchronous — there is no asynchronous probe whose stale resolution could race a `dispose()`. See `docs/network-tag-design.md` §5.
 - **Reconnect re-subscribes.** Removing and re-inserting the element tears down the `change` listener on disconnect and re-establishes it (against whatever `navigator.connection` currently is) on reconnect.
 - **SSR (`@wcstack/server`).** Declares `static hasConnectedCallbackPromise = true` and exposes `connectedCallbackPromise`, though since `observe()` is synchronous this promise always settles immediately.
@@ -219,6 +205,8 @@ console.log(net.effectiveType);
 net.dispose();           // detach the live `change` listener
 ```
 
+The structural Core surface is normative across wcstack IO nodes ([async-io-node-guidelines §3.9](../../docs/async-io-node-guidelines.md)); to bind it into signals with no element at all, see [@wcstack/signals — Binding a Core directly](../signals/README.md#binding-a-core-directly-no-element).
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wcstack/network",
-  "version": "1.22.5",
+  "version": "1.23.0",
   "description": "Declarative Network Information component for Web Components. Framework-agnostic navigator.connection monitor via wc-bindable-protocol.",
   "type": "module",
   "main": "./dist/index.esm.js",