@wcstack/state 1.5.2 → 1.6.1

package/README.ja.md

@@ -76,6 +76,7 @@ CDNのスクリプトはカスタム要素の定義を登録するだけで、
 - **SVG サポート** — `<svg>` 要素内でのフルバインディング対応
 - **ライフサイクルフック** — `$connectedCallback` / `$disconnectedCallback` / `$updatedCallback`、Web Component 用 `$stateReadyCallback`
 - **TypeScript サポート** — `defineState()` によるドットパス自動補完付き型付き状態定義（[詳細](docs/define-state.ja.md)）
+- **サーバーサイドレンダリング** — `enable-ssr` 属性 + `@wcstack/server` でフル SSR と自動ハイドレーション
 - **依存ゼロ** — ランタイム依存なし
 
 ## インストール
@@ -1037,7 +1038,7 @@ customElements.define("my-component", MyComponent);
       timer: null,
       count: 0,
 
-      // <wcs-state> が DOM に接続された時に呼ばれる（async 対応）
+      // <wcs-state> が DOM に接続された時に呼ばれる
       async $connectedCallback() {
         const res = await fetch("/api/initial-count");
         this.count = await res.json();
@@ -1055,16 +1056,16 @@ customElements.define("my-component", MyComponent);
 
 | フック | タイミング | 非同期 |
 |---|---|---|
-| `$connectedCallback` | 初回接続時は状態初期化後、再接続時は毎回呼び出し | 可（`async` 対応） |
+| `$connectedCallback` | 初回接続時は状態初期化後、再接続時は毎回呼び出し | 可（await される） |
 | `$disconnectedCallback` | 要素が DOM から削除された時 | 不可（同期のみ） |
-| `$updatedCallback(paths, indexesListByPath)` | 状態変更が適用された後に呼び出し | 戻り値は未使用（待機されない） |
+| `$updatedCallback(paths, indexesListByPath)` | 状態変更が適用された後に呼び出し | 可（await されない） |
 
-リアクティブ Proxy はすべてのプロパティへの代入を変更として検知します。そのため、標準の `async/await` による処理とプロパティへの直接代入だけで非同期ロジックが完結します。ローディングフラグの切り替え、取得したデータの格納、エラーメッセージの更新といった処理もすべて単なるプロパティ代入で行えるため、非同期状態を管理するための複雑な抽象化機能は必要ありません。
+`$disconnectedCallback` を除くすべてのフックで `async` を使用できます。リアクティブ Proxy はすべてのプロパティへの代入を変更として検知します。そのため、標準の `async/await` による処理とプロパティへの直接代入だけで非同期ロジックが完結します。ローディングフラグの切り替え、取得したデータの格納、エラーメッセージの更新といった処理もすべて単なるプロパティ代入で行えるため、非同期状態を管理するための複雑な抽象化機能は必要ありません。
 
 - フック内の `this` は読み書き可能な状態プロキシです。
 - `$connectedCallback` は要素が接続される**たびに**呼ばれます（一度削除された後の再接続も含みます）。再確立が必要なセットアップ処理に適しています。
 - `$disconnectedCallback` は同期的に呼び出されます。タイマーのクリア、イベントリスナーの削除、リソースの解放といったクリーンアップ処理に使用してください。
-- `$updatedCallback(paths, indexesListByPath)` は更新された状態パスの一覧を受け取ります。ワイルドカードをもつパスが更新された場合は、`indexesListByPath` から対象のインデックス情報も取得可能です。
+- `$updatedCallback(paths, indexesListByPath)` は更新された状態パスの一覧を受け取ります。ワイルドカードをもつパスが更新された場合は、`indexesListByPath` から対象のインデックス情報も取得可能です。`async` を使用できますが、戻り値は await されません。
 - Web Component を使用している場合は、コンポーネント側に `async $stateReadyCallback(stateProp)` を定義おくことで、`bind-component` でバインドした状態が利用可能になった瞬間にフックとして呼び出されます。
 
 ## 設定
@@ -1190,6 +1191,60 @@ buildBindings(root)
 - **StateAddress** — PathInfo + ListIndex の組み合わせ
 - **AbsoluteStateAddress** — 状態名 + StateAddress（クロス状態参照用）
 
+## サーバーサイドレンダリング
+
+`@wcstack/state` は [`@wcstack/server`](../server/) パッケージと連携して SSR をサポートしています。クライアント用に書いたテンプレートがそのままサーバーでレンダリングされます — 変更不要。
+
+### クイックセットアップ
+
+1. `<wcs-state>` に `enable-ssr` を追加:
+
+```html
+<wcs-state enable-ssr>
+  <script type="module">
+    export default {
+      items: [],
+      async $connectedCallback() {
+        const res = await fetch("/api/items");
+        this.items = await res.json();
+      }
+    };
+  </script>
+</wcs-state>
+<template data-wcs="for: items">
+  <div data-wcs="textContent: items.*.name"></div>
+</template>
+```
+
+2. サーバーでレンダリング:
+
+```javascript
+import { renderToString } from "@wcstack/server";
+
+const html = await renderToString(template, {
+  baseUrl: "http://localhost:3000"
+});
+```
+
+これだけです。クライアント側の `@wcstack/state` は `<wcs-ssr>` 要素を自動検出し、JSON スナップショットから状態を復元し��再レンダリングなしでリアクティビティを再開します。
+
+### 仕組み
+
+| フェーズ | 動作 |
+|---------|------|
+| **サーバー** | `renderToString()` が happy-dom でテンプレートを実行、`$connectedCallback`（`fetch()` 含む）を実行し、全バインディングを適用、ハイドレーションデータを含む `<wcs-ssr>` 要素付きのレンダリング済み HTML を出力 |
+| **クライアント** | `<wcs-state enable-ssr>` が `<wcs-ssr>` の JSON から状態をロード、`$connectedCallback` をスキップ、`hydrateBindings()` が既存の DOM にリアクティビティを接続 |
+| **フォールバック** | ���ーバー/クライアントのバージョン不一致時、SSR DOM をクリーンアップして `buildBindings()` でフルクライアントサイドレンダリングを実行 |
+
+### `enable-ssr` の動作
+
+| コンテキスト | 動作 |
+|------------|------|
+| **サーバー**（`renderToString`） | 状態 JSON、テンプレートフラグメント、プロパティデータを含む `<wcs-ssr>` を生成 |
+| **クラ��アント**（ハイドレーション） | `<wcs-ssr>` を読み取り、状態を復元、`$connectedCallback` をスキップ、既存 DOM のバイン���ィングをハイドレート |
+
+API の詳細は [`@wcstack/server` README](../server/README.ja.md) を参照してください。
+
 ## ライセンス
 
 MIT

package/README.md

@@ -76,6 +76,7 @@ That's it. No build, no bootstrap code, no framework.
 - **SVG support** — full binding support inside `<svg>` elements
 - **Lifecycle hooks** — `$connectedCallback` / `$disconnectedCallback` / `$updatedCallback`, plus `$stateReadyCallback` for Web Components
 - **TypeScript support** — `defineState()` for typed state definitions with dot-path autocompletion ([details](docs/define-state.md))
+- **Server-Side Rendering** — `enable-ssr` attribute + `@wcstack/server` for full SSR with automatic hydration
 - **Zero dependencies** — no runtime dependencies
 
 ## Installation
@@ -1037,7 +1038,7 @@ State objects can define `$connectedCallback`, `$disconnectedCallback`, and `$up
       timer: null,
       count: 0,
 
-      // Called when <wcs-state> is connected to the DOM (supports async)
+      // Called when <wcs-state> is connected to the DOM
       async $connectedCallback() {
         const res = await fetch("/api/initial-count");
         this.count = await res.json();
@@ -1055,16 +1056,16 @@ State objects can define `$connectedCallback`, `$disconnectedCallback`, and `$up
 
 | Hook | Timing | Async |
 |---|---|---|
-| `$connectedCallback` | After state initialization on first connect; on every reconnect thereafter | Yes (`async` supported) |
+| `$connectedCallback` | After state initialization on first connect; on every reconnect thereafter | Yes (awaited) |
 | `$disconnectedCallback` | When the element is removed from the DOM | No (sync only) |
-| `$updatedCallback(paths, indexesListByPath)` | After state updates are applied | Return value is ignored (not awaited) |
+| `$updatedCallback(paths, indexesListByPath)` | After state updates are applied | Yes (not awaited) |
 
-Since the reactive proxy detects every property assignment as a change, standard `async/await` with direct property updates is sufficient for asynchronous operations — loading flags, fetched data, and error messages are all just property assignments, without requiring additional abstractions for async state management.
+All hooks except `$disconnectedCallback` support `async` — you can use `async/await` in any of them. Since the reactive proxy detects every property assignment as a change, standard `async/await` with direct property updates is sufficient for asynchronous operations — loading flags, fetched data, and error messages are all just property assignments, without requiring additional abstractions for async state management.
 
 - `this` inside hooks is the state proxy with full read/write access
 - `$connectedCallback` is called **every time** the element is connected (including re-insertion after removal), making it suitable for setup that should be re-established
 - `$disconnectedCallback` is called synchronously — use it for cleanup such as clearing timers, removing event listeners, or releasing resources
-- `$updatedCallback(paths, indexesListByPath)` receives the updated path list. For wildcard updates, `indexesListByPath` contains the updated index sets
+- `$updatedCallback(paths, indexesListByPath)` receives the updated path list. For wildcard updates, `indexesListByPath` contains the updated index sets. Can be `async`, but the return value is not awaited
 - In Web Components, define `async $stateReadyCallback(stateProp)` to receive a hook when the bound state becomes available via `bind-component`
 
 ## Configuration
@@ -1190,6 +1191,60 @@ Paths like `users.*.name` are decomposed into:
 - **StateAddress** — combination of PathInfo + ListIndex
 - **AbsoluteStateAddress** — state name + StateAddress (for cross-state references)
 
+## Server-Side Rendering
+
+`@wcstack/state` supports SSR via the companion [`@wcstack/server`](../server/) package. The same templates you write for the client render on the server — no changes needed.
+
+### Quick Setup
+
+1. Add `enable-ssr` to your `<wcs-state>` element:
+
+```html
+<wcs-state enable-ssr>
+  <script type="module">
+    export default {
+      items: [],
+      async $connectedCallback() {
+        const res = await fetch("/api/items");
+        this.items = await res.json();
+      }
+    };
+  </script>
+</wcs-state>
+<template data-wcs="for: items">
+  <div data-wcs="textContent: items.*.name"></div>
+</template>
+```
+
+2. Render on the server:
+
+```javascript
+import { renderToString } from "@wcstack/server";
+
+const html = await renderToString(template, {
+  baseUrl: "http://localhost:3000"
+});
+```
+
+That's it. The client-side `@wcstack/state` automatically detects the `<wcs-ssr>` element, restores state from the JSON snapshot, and resumes reactivity without re-rendering.
+
+### How It Works
+
+| Phase | What happens |
+|-------|-------------|
+| **Server** | `renderToString()` runs your template in happy-dom, executes `$connectedCallback` (including `fetch()`), applies all bindings, and outputs rendered HTML with a `<wcs-ssr>` element containing hydration data |
+| **Client** | `<wcs-state enable-ssr>` loads state from `<wcs-ssr>` JSON, skips `$connectedCallback`, and `hydrateBindings()` wires up reactivity on the existing DOM |
+| **Fallback** | If server/client versions mismatch, the SSR DOM is cleaned up and `buildBindings()` runs a full client-side render |
+
+### What `enable-ssr` Does
+
+| Context | Behavior |
+|---------|----------|
+| **Server** (`renderToString`) | Generates `<wcs-ssr>` with state JSON, template fragments, and property data |
+| **Client** (hydration) | Reads `<wcs-ssr>`, restores state, skips `$connectedCallback`, hydrates bindings on existing DOM |
+
+See [`@wcstack/server` README](../server/README.md) for full API documentation.
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -1,5 +1,25 @@
+interface IState {
+    [key: string]: any;
+}
+interface ITagNames {
+    readonly state: string;
+    readonly ssr: string;
+}
 interface IWritableTagNames {
     state?: string;
+    ssr?: string;
+}
+interface IConfig {
+    readonly bindAttributeName: string;
+    readonly commentTextPrefix: string;
+    readonly commentForPrefix: string;
+    readonly commentIfPrefix: string;
+    readonly commentElseIfPrefix: string;
+    readonly commentElsePrefix: string;
+    readonly tagNames: ITagNames;
+    readonly locale: string;
+    readonly debug: boolean;
+    readonly enableMustache: boolean;
 }
 interface IWritableConfig {
     bindAttributeName?: string;
@@ -16,6 +36,82 @@ interface IWritableConfig {
 
 declare function bootstrapState(config?: IWritableConfig): void;
 
+declare function getConfig(): IConfig;
+
+/**
+ * 指定された rootNode のバインディング初期化が完了するまで待機する Promise を返す。
+ */
+declare function getBindingsReady(rootNode: Node): Promise<void>;
+
+interface ISsrElement {
+    readonly name: string;
+    readonly version: string;
+    readonly stateData: IState;
+    readonly templates: Map<string, HTMLTemplateElement>;
+    readonly hydrateProps: Record<string, Record<string, unknown>>;
+    getTemplate(uuid: string): HTMLTemplateElement | null;
+    verifyVersion(): boolean;
+}
+declare class Ssr extends HTMLElement implements ISsrElement {
+    private _stateData;
+    private _templates;
+    private _hydrateProps;
+    get name(): string;
+    get version(): string;
+    get stateData(): IState;
+    get templates(): Map<string, HTMLTemplateElement>;
+    get hydrateProps(): Record<string, Record<string, unknown>>;
+    getTemplate(uuid: string): HTMLTemplateElement | null;
+    /**
+     * サーバーの SSR バージョンとクライアントの state バージョンを検証する。
+     * メジャー・マイナーバージョンが一致すればtrue。
+     * version 属性がない場合は検証スキップ（true）。
+     */
+    verifyVersion(): boolean;
+    setStateData(data: IState): void;
+    setHydrateProps(props: Record<string, Record<string, unknown>>): void;
+    private _loadStateData;
+    private _loadTemplates;
+    private _loadHydrateProps;
+    static findByName(root: Node, name: string): ISsrElement | null;
+    /**
+     * stateData と構造テンプレート・プロパティから <wcs-ssr> の中身を構築する。
+     * server パッケージの renderToString から呼ばれる。
+     */
+    /**
+     * wcs-state 要素から $ プレフィックスや関数を除いたデータを抽出する。
+     */
+    static extractStateData(stateEl: Element): Record<string, any>;
+    static buildContent(ssrEl: Element, stateData: Record<string, any>): void;
+    /**
+     * SSR ブロック境界コメント (@@wcs-*-start/end) を除去する
+     */
+    static removeBlockBoundaryComments(root: Node): void;
+    /**
+     * SSR の構造プレースホルダーコメント (@@wcs-for:uuid 等) を除去する
+     */
+    static removeStructuralComments(root: Node): void;
+    /**
+     * SSR テキストバインディングコメントを復元する。
+     * <!--@@wcs-text-start:path-->text<!--@@wcs-text-end:path-->
+     * → <!--@@: path--> (バインディングシステムが認識する形式)
+     */
+    static restoreTextBindings(root: Node): void;
+    /**
+     * SSR DOM をクリーンアップし、buildBindings が動作できる状態に戻す。
+     * バージョン不一致時のフォールバック用。
+     *
+     * 1. SSR ブロック境界コメント間のレンダリング済みノードを除去
+     * 2. SSR テキストバインディングを @@: 形式に復元
+     * 3. プレースホルダーコメントを <wcs-ssr> 内のテンプレートで差し替え
+     * 4. data-wcs-ssr-id 属性を除去
+     * 5. <wcs-ssr> を除去
+     */
+    static cleanupDom(root: Document): void;
+}
+
+declare function buildBindings(root: Document | ShadowRoot): Promise<void>;
+
 /**
  * defineState.ts
  *
@@ -232,5 +328,7 @@ type WcsThis<T> = T & WcsStateApi & WcsPathAccessor<T>;
  */
 declare function defineState<T extends Record<string, any>>(definition: T & ThisType<WcsThis<T>>): T;
 
-export { bootstrapState, defineState };
-export type { IWritableConfig, IWritableTagNames, WcsPathValue, WcsPaths, WcsStateApi, WcsThis };
+declare const VERSION: string;
+
+export { Ssr, VERSION, bootstrapState, buildBindings, defineState, getBindingsReady, getConfig };
+export type { ISsrElement, IWritableConfig, IWritableTagNames, WcsPathValue, WcsPaths, WcsStateApi, WcsThis };