@wcstack/state 3.3.0 → 3.5.0

package/dist/index.d.ts

@@ -90,6 +90,8 @@ interface IStateProxy extends IState {
 }
 type Mutability = "readonly" | "writable";
 
+type ParseBindTextResult = IParsedBinding;
+
 /**
  * Filter/types.ts
  *
@@ -106,6 +108,23 @@ type Mutability = "readonly" | "writable";
  */
 type FilterFn<T = unknown> = (value: unknown) => T;
 
+/**
+ * パース結果の変換フック（Phase 2 のマウント — impl-plan §3-0 の 1）。
+ * マウントされたスコープの収集は、これで各パース結果を親ツリーの絶対パスへ書き換える。
+ * `uuid` を持つエントリ（構造フラグメントの参照）には掛けない — フラグメント側の
+ * パース結果は登録時（collectStructuralFragments）に変換済みで、二重に掛けると
+ * 接頭辞が二重になる。
+ */
+type ParseResultTransform = (parsed: ParseBindTextResult, forPath?: string) => ParseBindTextResult;
+interface IDeferredSpreadEntry {
+    readonly node: Node;
+    readonly tagName: string;
+    readonly parseResults: ParseBindTextResult[];
+    readonly transform?: ParseResultTransform;
+    /** 予約中の定義待ちの取り消し（`scheduleDeferredSpreads` が持つ。行の活性化し直しで待ちを重ねない） */
+    cancel?: () => void;
+}
+
 interface IContent {
     readonly firstNode: Node | null;
     readonly lastNode: Node | null;
@@ -125,6 +144,11 @@ interface IContent {
      * 従来経路（deactivate + unmount）で解体する。
      */
     tryDestroy(): boolean;
+    /**
+     * まだ展開していない、未定義カスタム要素への spread（#330）。持つ行だけに付く（形を増やさない）。
+     * 活性化のたびに定義待ちへ予約し、展開したものは外れる
+     */
+    spreads?: IDeferredSpreadEntry[];
 }
 
 /**
@@ -775,6 +799,7 @@ interface IBindingErrorInfo {
 }
 interface IWritableConfig {
     bindAttributeName?: string;
+    /** @deprecated Removed in 4.0, whose `bootstrapState` throws on it (3.5 warns `wcs/v4-migration`). */
     commentTextPrefix?: string;
     commentForPrefix?: string;
     commentIfPrefix?: string;
@@ -782,11 +807,16 @@ interface IWritableConfig {
     commentElsePrefix?: string;
     tagNames?: IWritableTagNames;
     locale?: string;
+    /** @deprecated Removed in 4.0, whose `bootstrapState` throws on it (3.5 warns `wcs/v4-migration`). */
     debug?: boolean;
+    /** Moves to the state's `$behavior` in 4.0 (3.5 warns `wcs/v4-migration`); in 3.x, set it here. */
     enableMustache?: boolean;
+    /** Moves to the state's `$behavior` in 4.0 (3.5 warns `wcs/v4-migration`); in 3.x, set it here. */
     enableDirectionalInitialSync?: boolean;
+    /** @deprecated Removed in 4.0, whose `bootstrapState` throws on it (3.5 warns `wcs/v4-migration`). */
     enablePropagationContext?: boolean;
     enableContractAnalyzer?: boolean;
+    /** Moves to the state's `$behavior` in 4.0 (3.5 warns `wcs/v4-migration`); in 3.x, set it here. */
     sameValueGuard?: boolean;
 }
 
@@ -1414,6 +1444,11 @@ type DevtoolsEvent = {
     readonly maxDepth: number;
     /** 打ち切ったバッチに載っていたアドレスのパス（報告用） */
     readonly paths: readonly string[];
+} | {
+    readonly type: "state:render-chain-limit";
+    readonly maxDepth: number;
+    /** 打ち切ったバッチに載っていたアドレスのパス（＝ 直前の描画の中で書かれたパス） */
+    readonly paths: readonly string[];
 } | {
     readonly type: "state:watch-fired";
     /** `$watch` の宣言キー（ワイルドカードを含む生のパス） */
@@ -1641,7 +1676,23 @@ declare class State extends HTMLElementBase implements IStateElement {
     private set _state(value);
     attributeChangedCallback(_name: string, oldValue: string | null, newValue: string | null): void;
     private _loadFromSsrElement;
-    /** state / src / json / inner <script> / API set のソース解決（_initialize とボリュームで共用）。 */
+    /**
+     * state / src / json / inner <script> / API set のソース解決（_initialize とボリュームで共用）。
+     *
+     * A load failure is not wrapped, here or in the loaders: what was thrown propagates as is —
+     * the SyntaxError of `JSON.parse` (`state=` / `json=`), the `import()` rejection or the
+     * module's own throw (`src="*.js"`), the inline-script loader's Error (the import failure is
+     * its `cause`), the unsupported-extension error, or a non-Error value. On a root,
+     * `_failInitializeLoudly` logs it under the element's "failed to initialize" line and rejects
+     * connectedCallbackPromise with that same value (the README contract); on a volume,
+     * volumeLifecycle logs it under its "failed to load" line. The old wrappers
+     * (`Failed to initialize state: ${e}` here, `Failed to load script file` /
+     * `Failed to parse JSON from script element` in the loaders) were new Errors that kept the
+     * original only as text, losing its type, stack and cause.
+     *
+     * Two sources do not fail at all in 3.x (README): `src="*.json"` that cannot be fetched or
+     * parsed, and `state=` naming no JSON script. Both log and start with an empty state.
+     */
     private _loadStateFromSource;
     /**
      * 初回マウントのロードと登録。戻り値は「この接続で初期化を**完了**したか」で、