@deviltea/widget-core 0.0.6 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -10,13 +10,30 @@ interface JsonObject {
10
10
  readonly [key: string]: JsonValue;
11
11
  }
12
12
  type JsonValue = JsonPrimitive | JsonArray | JsonObject;
13
+ /**
14
+ * The maximum JSON nesting depth of authored source and SourcePatch operands: the number of containers
15
+ * (objects and arrays) a value may be nested inside, counting the value's own container. A value nested
16
+ * deeper is outside the JSON domain (`json-incompatible-value`, reason `max-depth-exceeded`) and is never
17
+ * descended into, so arbitrarily deep input yields a diagnostic or an operation failure instead of exhausting
18
+ * the call stack. A widget node nests three containers per tree level (node, `slots`, slot Array), so the
19
+ * limit allows widget trees about 85 levels deep. The value leaves a wide margin below the call-stack limit of
20
+ * Node 22/24 and of smaller-stack embedded engines, and is part of the public contract.
21
+ */
22
+ declare const MAX_JSON_DEPTH = 256;
23
+ declare function isJsonValue(value: unknown): value is JsonValue;
13
24
  /**
14
25
  * Type-level diagnostic for a RawConfig that is not statically within JsonValue. Optional properties
15
26
  * are allowed to be omitted, but an explicitly required `undefined` remains outside the domain.
16
27
  */
17
- type IsAny$1<T> = 0 extends 1 & T ? true : false;
28
+ type IsAny$2<T> = 0 extends 1 & T ? true : false;
18
29
  type OptionalKeys<T extends object> = { [Key in keyof T]-?: Record<never, never> extends Pick<T, Key> ? Key : never; }[keyof T];
19
- type JsonDomainViolation<Value> = IsAny$1<Value> extends true ? 'authored JSON values cannot contain any' : [Value] extends [never] ? never : [Value] extends [JsonValue] ? never : Value extends string | number | boolean | null ? never : Value extends ((...args: any[]) => any) ? 'authored values must be JSON-compatible' : Value extends readonly (infer Element)[] ? JsonDomainViolation<Element> : Value extends object ? Exclude<keyof Value, string> extends never ? { [Key in keyof Value]-?: Key extends OptionalKeys<Value> ? JsonDomainViolation<Exclude<Value[Key], undefined>> : JsonDomainViolation<Value[Key]>; }[keyof Value] : 'authored JSON objects may only have string keys' : 'authored values must be JSON-compatible';
30
+ /**
31
+ * Well-known-symbol members that only class instances carry (`Date`, `Map`, `Set`, iterables, ...).
32
+ * Checked before the string-key rule, so such a value reports the non-plain-object reason instead of
33
+ * "may only have string keys".
34
+ */
35
+ type ClassInstanceSymbolKey = typeof Symbol.iterator | typeof Symbol.asyncIterator | typeof Symbol.toPrimitive | typeof Symbol.toStringTag;
36
+ type JsonDomainViolation<Value> = IsAny$2<Value> extends true ? 'authored JSON values cannot contain any' : [Value] extends [never] ? never : [Value] extends [JsonValue] ? never : Value extends string | number | boolean | null ? never : Value extends ((...args: any[]) => any) ? 'authored values must be JSON-compatible' : Value extends readonly (infer Element)[] ? JsonDomainViolation<Element> : Value extends object ? [Extract<keyof Value, ClassInstanceSymbolKey>] extends [never] ? Exclude<keyof Value, string> extends never ? { [Key in keyof Value]-?: Key extends OptionalKeys<Value> ? JsonDomainViolation<Exclude<Value[Key], undefined>> : JsonDomainViolation<Value[Key]>; }[keyof Value] : 'authored JSON objects may only have string keys' : 'authored JSON objects must be plain objects, not class instances such as Date, Map or Set' : 'authored values must be JSON-compatible';
20
37
  //#endregion
21
38
  //#region src/types.d.ts
22
39
  /**
@@ -53,7 +70,7 @@ interface WidgetInterfaces {
53
70
  * A readonly array that is non-empty when present. Used by every optional `related` collection.
54
71
  */
55
72
  type NonEmptyReadonlyArray<T> = readonly [T, ...T[]];
56
- type IsAny<T> = 0 extends 1 & T ? true : false;
73
+ type IsAny$1<T> = 0 extends 1 & T ? true : false;
57
74
  /**
58
75
  * Reads one declared capability. Returns `never` when the capability is absent.
59
76
  *
@@ -104,7 +121,7 @@ type WidgetMethodOf<Interfaces extends WidgetInterfaces, Name extends WidgetMemb
104
121
  type WidgetMethodArgsOf<Interfaces extends WidgetInterfaces, Name extends WidgetMemberKey> = Parameters<WidgetMethodOf<Interfaces, Name>>;
105
122
  type WidgetMethodReturnOf<Interfaces extends WidgetInterfaces, Name extends WidgetMemberKey> = ReturnType<WidgetMethodOf<Interfaces, Name>>;
106
123
  type WidgetEventArgsOf<Interfaces extends WidgetInterfaces, Name extends WidgetMemberKey> = Extract<WidgetMemberValueOf<WidgetEventsOf<Interfaces>, Name>, readonly any[]>;
107
- type ContainsPromiseLike<Value> = IsAny<Value> extends true ? false : [Extract<Value, PromiseLike<unknown>>] extends [never] ? false : true;
124
+ type ContainsPromiseLike<Value> = IsAny$1<Value> extends true ? false : [Extract<Value, PromiseLike<unknown>>] extends [never] ? false : true;
108
125
  type MemberKeyDomainViolation<Section extends string, Members> = [Members] extends [never] ? never : [keyof Members] extends [never] ? never : [keyof Members] extends [WidgetMemberKey] ? WidgetMemberKey extends keyof Members ? `'${Section}' must not be declared with a broad string index signature` : never : `'${Section}' member keys must be finite string literals`;
109
126
  type SyncValueDomainViolation<Section extends string, Members> = [Members] extends [never] ? never : true extends { [Key in keyof Members]-?: ContainsPromiseLike<Members[Key]>; }[keyof Members] ? `'${Section}' values must not be PromiseLike; the core semantic boundary is synchronous` : never;
110
127
  type SyncMethodReturnViolation<Interfaces extends WidgetInterfaces> = WidgetMethodsOf<Interfaces> extends (infer Methods) ? [Methods] extends [never] ? never : true extends { [Key in keyof Methods]-?: ContainsPromiseLike<ReturnType<Extract<Methods[Key], (...args: any[]) => any>>>; }[keyof Methods] ? `'methods' return types must not be PromiseLike; the core semantic boundary is synchronous` : never : never;
@@ -151,11 +168,18 @@ declare const widgetValueContractType: unique symbol;
151
168
  *
152
169
  * The generic parameter exists only for Plugin-author type safety. Runtime/integration identity is the
153
170
  * stable string `id`; descriptor object identity has no semantic meaning.
171
+ *
172
+ * A contract for `Value` describes every value of that type, so it can be attached to a Property whose
173
+ * value type is the same or narrower (every value the Property produces satisfies the contract):
174
+ * `WidgetValueContract<string>` fits a `'small' | 'large'` Property, but not a `string | null` one.
154
175
  */
155
176
  interface WidgetValueContract<Value> {
156
177
  readonly id: string;
157
- /** Type-only invariant brand; the factory-created runtime descriptor contains only `id`. */
158
- readonly [widgetValueContractType]: (value: Value) => Value;
178
+ /**
179
+ * Type-only contravariant brand (`WidgetValueContract<Wide>` is assignable to
180
+ * `WidgetValueContract<Narrow>`); the factory-created runtime descriptor contains only `id`.
181
+ */
182
+ readonly [widgetValueContractType]: (value: Value) => void;
159
183
  }
160
184
  /**
161
185
  * Declares a stable semantic value-contract id while retaining the associated TypeScript value type for
@@ -190,6 +214,8 @@ interface ErasedWidgetPropertyDefinition {
190
214
  interface ErasedWidgetMethodDefinition {
191
215
  readonly registerDeps?: (ctx: any) => RegisteredDeps;
192
216
  readonly validateArgs: (args: readonly unknown[], ctx: any) => boolean;
217
+ /** The declared Events, a frozen copy; checked against the events section by `done()`. */
218
+ readonly emits?: readonly WidgetMemberKey[];
193
219
  readonly execute: (ctx: any) => unknown;
194
220
  }
195
221
  interface ErasedWidgetEventDefinition {
@@ -234,14 +260,19 @@ interface WidgetPluginCapabilities {
234
260
  readonly methods: boolean;
235
261
  readonly events: boolean;
236
262
  }
237
- /**
238
- * A completed plugin. Plugin-specific integration options are captured by the plugin factory's
239
- * closure; there is no `pluginConfig` / `globalConfig`.
240
- */
263
+ /** Passive RawConfig authoring metadata of a plugin with a config capability. */
241
264
  interface WidgetPluginConfigMetadata {
242
265
  readonly description: string;
243
266
  readonly schema: WidgetConfigJsonSchema | null;
244
267
  }
268
+ /**
269
+ * A completed plugin. Plugin-specific integration options are captured by the plugin factory's
270
+ * closure; there is no `pluginConfig` / `globalConfig`.
271
+ *
272
+ * A completed plugin is immutable: `done()` freezes it, every section builder is sealed once its build
273
+ * callback returns, and every config, slot and member definition was captured by value when declared,
274
+ * so neither a retained builder section nor later mutation of the author's definition objects changes it.
275
+ */
245
276
  interface WidgetPlugin<Type extends string = string, Interfaces extends WidgetInterfaces = WidgetInterfaces> {
246
277
  readonly type: Type;
247
278
  readonly description: string;
@@ -291,19 +322,60 @@ type WidgetRegisterDepsContext<Interfaces extends WidgetInterfaces, Consumer ext
291
322
  } & WidgetResolvedConfigContext<Interfaces>;
292
323
  type WidgetPropertyComputeContext<Interfaces extends WidgetInterfaces, Deps extends RegisteredDeps> = {
293
324
  readonly widget: SelfBlueprintWidgetNode<Interfaces>;
294
- readonly blueprint: ValidBlueprintView;
325
+ readonly blueprint: BlueprintRuntimeView;
295
326
  readonly deps: ToExecutedDeps<Deps, 'property'>;
296
327
  } & DiagnosticCollector<RelativeValueDiagnosticInput> & WidgetResolvedConfigContext<Interfaces>;
297
328
  type WidgetEventEmitter<Interfaces extends WidgetInterfaces> = { readonly [Name in WidgetEventKeyOf<Interfaces>]: (...args: WidgetEventArgsOf<Interfaces, Name>) => void; };
298
- type WidgetEventEmitterContext<Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'events'> extends true ? {
299
- readonly emit: WidgetEventEmitter<Interfaces>;
329
+ /** The `emit` one Method receives carries exactly the Events it declares in `emits`. */
330
+ type WidgetMethodEventEmitter<Interfaces extends WidgetInterfaces, Emits extends WidgetEventKeyOf<Interfaces>> = { readonly [Name in Emits]: (...args: WidgetEventArgsOf<Interfaces, Name>) => void; };
331
+ type WidgetEventEmitterContext<Interfaces extends WidgetInterfaces, Emits extends WidgetEventKeyOf<Interfaces> = never> = HasWidgetCapability<Interfaces, 'events'> extends true ? {
332
+ readonly emit: WidgetMethodEventEmitter<Interfaces, Emits>;
300
333
  } : unknown;
301
- type WidgetMethodExecuteContext<Interfaces extends WidgetInterfaces, Name extends WidgetMemberKey, Deps extends RegisteredDeps> = {
334
+ type WidgetMethodExecuteContext<Interfaces extends WidgetInterfaces, Name extends WidgetMemberKey, Deps extends RegisteredDeps, Emits extends WidgetEventKeyOf<Interfaces> = never> = {
302
335
  readonly args: WidgetMethodArgsOf<Interfaces, Name>;
303
336
  readonly widget: SelfBlueprintWidgetNode<Interfaces>;
304
- readonly blueprint: ValidBlueprintView;
337
+ readonly blueprint: BlueprintRuntimeView;
305
338
  readonly deps: ToExecutedDeps<Deps, 'method'>;
306
- } & DiagnosticCollector<RelativeValueDiagnosticInput> & WidgetResolvedConfigContext<Interfaces> & WidgetEventEmitterContext<Interfaces>;
339
+ } & DiagnosticCollector<RelativeValueDiagnosticInput> & WidgetResolvedConfigContext<Interfaces> & WidgetEventEmitterContext<Interfaces, Emits>;
340
+ type IsAny<T> = 0 extends 1 & T ? true : false;
341
+ type IsExactlyVoid<T> = (<X>() => X extends T ? 1 : 2) extends (<X>() => X extends void ? 1 : 2) ? true : false;
342
+ /**
343
+ * Whether `Value` can be a thenable: anything with a callable `then`, which is what the runtime guard
344
+ * rejects (not only a native `PromiseLike`). An object whose `then` is not a function is not one. For a
345
+ * value of a type parameter the check stays deferred, which TypeScript accepts.
346
+ */
347
+ type MayBeThenable<Value> = [Extract<Value, {
348
+ readonly then: (...args: never) => unknown;
349
+ }>] extends [never] ? false : true;
350
+ /**
351
+ * What a thenable result is checked against. The `then` text is the compile-error message; no callable
352
+ * `then` satisfies it.
353
+ */
354
+ interface WidgetSynchronousResultViolation {
355
+ readonly then: 'widget-core: semantic callbacks are synchronous; returning a PromiseLike/thenable is a contract violation';
356
+ }
357
+ /**
358
+ * The return type a semantic callback is checked against, given `Result`, the callback's own return type:
359
+ * `Result` itself unless it can be a thenable. A `void` (or `unknown`) return type cannot do this on its own:
360
+ * TypeScript lets a `void`-returning function type accept any function, an `async` one included, and every
361
+ * value is assignable to `unknown`. Gating on the callback's own return type rejects a thenable while every
362
+ * synchronous value — an `unknown`-typed expression, a value of a type parameter, an object whose `then` is
363
+ * not a function — still type-checks.
364
+ *
365
+ * `Result` is inferred where the callback is written into the builder (a Method's `execute`, a slot's or the
366
+ * plugin's `validateStructure`) or into `createWidgetSystem`'s options. A standalone definition type has no
367
+ * callback to infer from, so `Result` defaults to `unknown` and it accepts any return: a thenable reaching
368
+ * Core through a callback typed only by such an annotation is caught by the runtime guard instead, which
369
+ * throws a `TypeError`.
370
+ */
371
+ type WidgetSynchronousResult<Result> = Result & (MayBeThenable<Result> extends true ? WidgetSynchronousResultViolation : unknown);
372
+ /**
373
+ * `execute`'s return type for the declared Method return `Declared`. A declared type a thenable is
374
+ * assignable to — exactly `void`, `unknown`, `{}`, `object` — gates on the `execute`'s own return type
375
+ * `Result` (see {@link WidgetSynchronousResult}); any other declared type already rejects a PromiseLike (see
376
+ * `WidgetInterfacesViolationOf`). `any` stays unchecked.
377
+ */
378
+ type WidgetMethodExecuteResult<Declared, Result> = IsAny<Declared> extends true ? Declared : IsExactlyVoid<Declared> extends true ? WidgetSynchronousResult<Result> : PromiseLike<unknown> extends Declared ? Declared & WidgetSynchronousResult<Result> : Declared;
307
379
  interface WidgetConfigDefinition<Interfaces extends WidgetInterfaces> {
308
380
  readonly description: string;
309
381
  /** Passive Draft 2020-12 authoring metadata. Core does not validate or execute this schema. */
@@ -311,17 +383,24 @@ interface WidgetConfigDefinition<Interfaces extends WidgetInterfaces> {
311
383
  readonly validate: (input: unknown, ctx: WidgetConfigValidateContext) => input is WidgetRawConfigOf<Interfaces>;
312
384
  readonly resolve: (rawConfig: WidgetRawConfigOf<Interfaces> | null) => WidgetResolvedConfigOf<Interfaces>;
313
385
  }
314
- interface WidgetSlotDefinition<Interfaces extends WidgetInterfaces, SlotName extends WidgetMemberKey> {
386
+ /** `Result` is the slot validator's own return type (see {@link WidgetSynchronousResult}). */
387
+ interface WidgetSlotDefinition<Interfaces extends WidgetInterfaces, SlotName extends WidgetMemberKey, Result = unknown> {
315
388
  readonly description: string;
316
- readonly validateStructure?: (ctx: WidgetSlotValidateStructureContext<Interfaces, SlotName>) => void;
389
+ readonly validateStructure?: (ctx: WidgetSlotValidateStructureContext<Interfaces, SlotName>) => WidgetSynchronousResult<Result>;
317
390
  }
318
391
  type WidgetSlotDefinitions<Interfaces extends WidgetInterfaces> = { readonly [Name in WidgetSlotNameOf<Interfaces>]: WidgetSlotDefinition<Interfaces, Name>; };
392
+ /** The return type of the `validateStructure` a slots object declares for `Name`, or `unknown`. */
393
+ type WidgetSlotStructureResultOf<Definitions, Name extends PropertyKey> = Definitions extends { readonly [Key in Name]: {
394
+ readonly validateStructure?: (...args: never) => infer Result;
395
+ }; } ? Result : unknown;
319
396
  /**
320
397
  * Rejects a slots object that carries a slot the interfaces never declared, including when the
321
- * object is supplied through a variable instead of a fresh object literal.
398
+ * object is supplied through a variable instead of a fresh object literal, and a slot validator that
399
+ * returns a thenable.
322
400
  */
323
- type ExactWidgetSlotDefinitions<Interfaces extends WidgetInterfaces, Definitions> = WidgetSlotDefinitions<Interfaces> & { readonly [Name in keyof Definitions as Name extends WidgetSlotNameOf<Interfaces> ? never : Name]: never; };
324
- type WidgetPluginValidateStructure<Interfaces extends WidgetInterfaces> = (ctx: WidgetPluginValidateStructureContext<Interfaces>) => void;
401
+ type ExactWidgetSlotDefinitions<Interfaces extends WidgetInterfaces, Definitions> = { readonly [Name in WidgetSlotNameOf<Interfaces>]: WidgetSlotDefinition<Interfaces, Name, WidgetSlotStructureResultOf<Definitions, Name>>; } & { readonly [Name in keyof Definitions as Name extends WidgetSlotNameOf<Interfaces> ? never : Name]: never; };
402
+ /** `Result` is the validator's own return type (see {@link WidgetSynchronousResult}). */
403
+ type WidgetPluginValidateStructure<Interfaces extends WidgetInterfaces, Result = unknown> = (ctx: WidgetPluginValidateStructureContext<Interfaces>) => WidgetSynchronousResult<Result>;
325
404
  interface WidgetStateMemberDefinition<Interfaces extends WidgetInterfaces, Key extends WidgetMemberKey> {
326
405
  /** Passive authoring policy. Omitted means this State member is not author-writable. */
327
406
  readonly authorWritable?: boolean;
@@ -334,11 +413,25 @@ interface WidgetPropertyDefinition<Interfaces extends WidgetInterfaces, Name ext
334
413
  readonly registerDeps?: (ctx: WidgetRegisterDepsContext<Interfaces, 'property'>) => Deps;
335
414
  readonly compute: (ctx: WidgetPropertyComputeContext<Interfaces, Deps>) => WidgetPropertyValueOf<Interfaces, Name>;
336
415
  }
337
- interface WidgetMethodDefinition<Interfaces extends WidgetInterfaces, Name extends WidgetMemberKey, Deps extends RegisteredDeps> {
416
+ interface WidgetMethodDefinitionFields<Interfaces extends WidgetInterfaces, Name extends WidgetMemberKey, Deps extends RegisteredDeps, Result, Emits extends WidgetEventKeyOf<Interfaces>> {
338
417
  readonly registerDeps?: (ctx: WidgetRegisterDepsContext<Interfaces, 'method'>) => Deps;
339
418
  readonly validateArgs: (args: readonly unknown[], ctx: WidgetMethodValidateArgsContext<Interfaces>) => args is WidgetMethodArgsOf<Interfaces, Name>;
340
- readonly execute: (ctx: WidgetMethodExecuteContext<Interfaces, Name, Deps>) => WidgetMethodReturnOf<Interfaces, Name>;
419
+ /**
420
+ * The Events this Method may emit. Omitted or empty means none. A Method that emits an Event, itself or
421
+ * through the Methods it invokes, is not read-only, so no Property may depend on it.
422
+ */
423
+ readonly emits?: readonly Emits[];
424
+ readonly execute: (ctx: WidgetMethodExecuteContext<Interfaces, Name, Deps, Emits>) => WidgetMethodExecuteResult<WidgetMethodReturnOf<Interfaces, Name>, Result>;
341
425
  }
426
+ /**
427
+ * `Result` is `execute`'s own return type (see {@link WidgetMethodExecuteResult}). `Emits` is the union of
428
+ * the Events the Method declares: whenever it is not `never`, `execute` receives an `emit` with those
429
+ * Events, so `emits` is required (a definition that types `emit` without declaring it would throw at its
430
+ * first emit).
431
+ */
432
+ type WidgetMethodDefinition<Interfaces extends WidgetInterfaces, Name extends WidgetMemberKey, Deps extends RegisteredDeps, Result = unknown, Emits extends WidgetEventKeyOf<Interfaces> = never> = WidgetMethodDefinitionFields<Interfaces, Name, Deps, Result, Emits> & ([Emits] extends [never] ? unknown : {
433
+ readonly emits: readonly Emits[];
434
+ });
342
435
  interface WidgetEventDefinition {
343
436
  readonly description: string;
344
437
  }
@@ -352,7 +445,7 @@ interface WidgetSectionMarker<Kind extends string, Remaining extends WidgetMembe
352
445
  }
353
446
  type WidgetStateSection<Interfaces extends WidgetInterfaces, Remaining extends WidgetStateKeyOf<Interfaces>> = WidgetSectionMarker<'state', Remaining> & { [Key in Remaining]: (definition: WidgetStateMemberDefinition<Interfaces, Key>) => WidgetStateSection<Interfaces, Exclude<Remaining, Key>>; };
354
447
  type WidgetPropertiesSection<Interfaces extends WidgetInterfaces, Remaining extends WidgetPropertyKeyOf<Interfaces>> = WidgetSectionMarker<'properties', Remaining> & { [Name in Remaining]: <const Deps extends RegisteredDeps = EmptyRegisteredDeps>(definition: WidgetPropertyDefinition<Interfaces, Name, Deps>) => WidgetPropertiesSection<Interfaces, Exclude<Remaining, Name>>; };
355
- type WidgetMethodsSection<Interfaces extends WidgetInterfaces, Remaining extends WidgetMethodKeyOf<Interfaces>> = WidgetSectionMarker<'methods', Remaining> & { [Name in Remaining]: <const Deps extends RegisteredDeps = EmptyRegisteredDeps>(definition: WidgetMethodDefinition<Interfaces, Name, Deps>) => WidgetMethodsSection<Interfaces, Exclude<Remaining, Name>>; };
448
+ type WidgetMethodsSection<Interfaces extends WidgetInterfaces, Remaining extends WidgetMethodKeyOf<Interfaces>> = WidgetSectionMarker<'methods', Remaining> & { [Name in Remaining]: <const Deps extends RegisteredDeps = EmptyRegisteredDeps, Result = unknown, const Emits extends WidgetEventKeyOf<Interfaces> = never>(definition: WidgetMethodDefinition<Interfaces, Name, Deps, Result, Emits>) => WidgetMethodsSection<Interfaces, Exclude<Remaining, Name>>; };
356
449
  type WidgetEventsSection<Interfaces extends WidgetInterfaces, Remaining extends WidgetEventKeyOf<Interfaces>> = WidgetSectionMarker<'events', Remaining> & { [Name in Remaining]: (definition: WidgetEventDefinition) => WidgetEventsSection<Interfaces, Exclude<Remaining, Name>>; };
357
450
  /**
358
451
  * Returned instead of the next builder phase when the supplied `WidgetInterfaces` is outside the
@@ -365,16 +458,21 @@ interface WidgetPluginDonePhase<Type extends string, Interfaces extends WidgetIn
365
458
  done: () => WidgetPlugin<Type, Interfaces>;
366
459
  }
367
460
  /**
368
- * Outer capability phases in their fixed call order. Part of the type-level order diagnostics only;
369
- * the runtime builder is order-agnostic.
461
+ * Outer builder phases in their fixed call order: every capability phase plus the optional,
462
+ * capability-independent `structure` phase. Part of the type-level order diagnostics only; the runtime
463
+ * builder is order-agnostic.
370
464
  */
371
- type WidgetPluginPhaseOrder = readonly ['config', 'slots', 'state', 'properties', 'methods', 'events'];
465
+ type WidgetPluginPhaseOrder = readonly ['config', 'slots', 'structure', 'state', 'properties', 'methods', 'events'];
372
466
  type WidgetPluginPhaseName = WidgetPluginPhaseOrder[number];
373
- /** The phases whose capability was declared in `Interfaces`. */
374
- type WidgetPluginDeclaredPhaseName<Interfaces extends WidgetInterfaces> = { [Phase in WidgetPluginPhaseName]: HasWidgetCapability<Interfaces, Phase> extends true ? Phase : never; }[WidgetPluginPhaseName];
467
+ type WidgetPluginCapabilityPhaseName = Exclude<WidgetPluginPhaseName, 'structure'>;
468
+ /**
469
+ * The phases available for `Interfaces`: every phase whose capability was declared, plus `structure`,
470
+ * which every plugin may call (at most once) regardless of its capabilities.
471
+ */
472
+ type WidgetPluginAvailablePhaseName<Interfaces extends WidgetInterfaces> = 'structure' | { [Phase in WidgetPluginCapabilityPhaseName]: HasWidgetCapability<Interfaces, Phase> extends true ? Phase : never; }[WidgetPluginCapabilityPhaseName];
375
473
  type WidgetPluginPhaseIsBefore<A extends WidgetPluginPhaseName, B extends WidgetPluginPhaseName, Order extends readonly WidgetPluginPhaseName[] = WidgetPluginPhaseOrder> = Order extends readonly [infer Head, ...infer Tail extends readonly WidgetPluginPhaseName[]] ? Head extends A ? true : Head extends B ? false : WidgetPluginPhaseIsBefore<A, B, Tail> : false;
376
474
  /**
377
- * Type-only order marker: the message of the compile error raised when a declared phase is called at
475
+ * Type-only order marker: the message of the compile error raised when an available phase is called at
378
476
  * the wrong position. The marker name and reason text are diagnostics, not protocol.
379
477
  */
380
478
  interface WidgetPluginPhaseOrderViolation<Reason extends string> {
@@ -386,39 +484,58 @@ interface WidgetPluginPhaseOrderViolation<Reason extends string> {
386
484
  * reason) in the message, while the function constituent keeps callbacks contextually typed, so no
387
485
  * implicit-`any` follow-on errors appear. Section builders may return anything.
388
486
  */
389
- type WidgetPluginMisplacedArguments<Interfaces extends WidgetInterfaces, Phase extends WidgetPluginPhaseName, Violation> = Phase extends 'config' ? [definition: Violation & WidgetConfigDefinition<Interfaces>] : Phase extends 'slots' ? [definitions: Violation & WidgetSlotDefinitions<Interfaces>, validateStructure?: WidgetPluginValidateStructure<Interfaces>] : Phase extends 'state' ? [build: Violation & ((section: WidgetStateSection<Interfaces, WidgetStateKeyOf<Interfaces>>) => unknown)] : Phase extends 'properties' ? [build: Violation & ((section: WidgetPropertiesSection<Interfaces, WidgetPropertyKeyOf<Interfaces>>) => unknown)] : Phase extends 'methods' ? [build: Violation & ((section: WidgetMethodsSection<Interfaces, WidgetMethodKeyOf<Interfaces>>) => unknown)] : [build: Violation & ((section: WidgetEventsSection<Interfaces, WidgetEventKeyOf<Interfaces>>) => unknown)];
390
- type WidgetPluginPhaseOrderReason<Phase extends WidgetPluginPhaseName, Stage extends WidgetPluginPhaseName | 'done'> = Stage extends WidgetPluginPhaseName ? WidgetPluginPhaseIsBefore<Phase, Stage> extends true ? `'.${Phase}()' was already called or must be called earlier; the next phase is '.${Stage}()'. Order: description -> interfaces -> config? -> slots? -> state? -> properties? -> methods? -> events? -> done()` : `'.${Phase}()' is called too early; call '.${Stage}()' first. Order: description -> interfaces -> config? -> slots? -> state? -> properties? -> methods? -> events? -> done()` : `'.${Phase}()' cannot be called here; the declared phases are already complete, so only '.done()' remains. Order: description -> interfaces -> config? -> slots? -> state? -> properties? -> methods? -> events? -> done()`;
487
+ type WidgetPluginMisplacedArguments<Interfaces extends WidgetInterfaces, Phase extends WidgetPluginPhaseName, Violation> = Phase extends 'config' ? [definition: Violation & WidgetConfigDefinition<Interfaces>] : Phase extends 'slots' ? [definitions: Violation & WidgetSlotDefinitions<Interfaces>] : Phase extends 'structure' ? [validateStructure: Violation & WidgetPluginValidateStructure<Interfaces>] : Phase extends 'state' ? [build: Violation & ((section: WidgetStateSection<Interfaces, WidgetStateKeyOf<Interfaces>>) => unknown)] : Phase extends 'properties' ? [build: Violation & ((section: WidgetPropertiesSection<Interfaces, WidgetPropertyKeyOf<Interfaces>>) => unknown)] : Phase extends 'methods' ? [build: Violation & ((section: WidgetMethodsSection<Interfaces, WidgetMethodKeyOf<Interfaces>>) => unknown)] : [build: Violation & ((section: WidgetEventsSection<Interfaces, WidgetEventKeyOf<Interfaces>>) => unknown)];
488
+ type WidgetPluginPhaseOrderReason<Phase extends WidgetPluginPhaseName, Stage extends WidgetPluginPhaseName | 'done'> = Stage extends WidgetPluginPhaseName ? WidgetPluginPhaseIsBefore<Phase, Stage> extends true ? `'.${Phase}()' was already called or must be called earlier; the next phase is '.${Stage}()'. Order: description -> interfaces -> config? -> slots? -> structure? -> state? -> properties? -> methods? -> events? -> done()` : `'.${Phase}()' is called too early; call '.${Stage}()' first. Order: description -> interfaces -> config? -> slots? -> structure? -> state? -> properties? -> methods? -> events? -> done()` : `'.${Phase}()' cannot be called here; the declared phases are already complete, so only '.done()' remains. Order: description -> interfaces -> config? -> slots? -> structure? -> state? -> properties? -> methods? -> events? -> done()`;
391
489
  /**
392
- * Adds type-only order markers for every declared phase that is not callable at `Stage`. A marker
393
- * takes the real phase's arguments with the first one intersected with
490
+ * Adds type-only order markers for every available phase that is not in `Callable` (by default just
491
+ * `Stage`, the next phase; the `structure` stage also keeps the optional `structure` phase callable).
492
+ * A marker takes the real phase's arguments with the first one intersected with
394
493
  * `WidgetPluginPhaseOrderViolation`, so no real value satisfies it and the call fails with an
395
- * order-specific diagnostic (the function constituent keeps a callback passed to it contextually typed,
396
- * so no implicit-`any` follow-on errors appear). It returns the same phase, so a misplaced call never
397
- * advances the chain.
494
+ * order-specific diagnostic relative to `Stage` (the function constituent keeps a callback passed to it
495
+ * contextually typed, so no implicit-`any` follow-on errors appear). It returns the same phase, so a
496
+ * misplaced call never advances the chain.
398
497
  */
399
- type WidgetPluginOrderedPhase<Phase, Interfaces extends WidgetInterfaces, Stage extends WidgetPluginPhaseName | 'done'> = [Exclude<WidgetPluginDeclaredPhaseName<Interfaces>, Stage>] extends [never] ? Phase : Phase & { [Misplaced in Exclude<WidgetPluginDeclaredPhaseName<Interfaces>, Stage>]: (...args: WidgetPluginMisplacedArguments<Interfaces, Misplaced, WidgetPluginPhaseOrderViolation<WidgetPluginPhaseOrderReason<Misplaced, Stage>>>) => WidgetPluginOrderedPhase<Phase, Interfaces, Stage>; };
400
- type WidgetPluginEventsPhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'events'> extends true ? WidgetPluginOrderedPhase<{
498
+ type WidgetPluginOrderedPhase<Phase, Interfaces extends WidgetInterfaces, Stage extends WidgetPluginPhaseName | 'done', Callable extends WidgetPluginPhaseName | 'done' = Stage> = [Exclude<WidgetPluginAvailablePhaseName<Interfaces>, Callable>] extends [never] ? Phase : Phase & { [Misplaced in Exclude<WidgetPluginAvailablePhaseName<Interfaces>, Callable>]: (...args: WidgetPluginMisplacedArguments<Interfaces, Misplaced, WidgetPluginPhaseOrderViolation<WidgetPluginPhaseOrderReason<Misplaced, Stage>>>) => WidgetPluginOrderedPhase<Phase, Interfaces, Stage, Callable>; };
499
+ interface WidgetPluginEventsPhaseMembers<Type extends string, Interfaces extends WidgetInterfaces> {
401
500
  events: (build: (section: WidgetEventsSection<Interfaces, WidgetEventKeyOf<Interfaces>>) => WidgetEventsSection<Interfaces, never>) => WidgetPluginOrderedPhase<WidgetPluginDonePhase<Type, Interfaces>, Interfaces, 'done'>;
402
- }, Interfaces, 'events'> : WidgetPluginOrderedPhase<WidgetPluginDonePhase<Type, Interfaces>, Interfaces, 'done'>;
403
- type WidgetPluginMethodsPhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'methods'> extends true ? WidgetPluginOrderedPhase<{
501
+ }
502
+ interface WidgetPluginMethodsPhaseMembers<Type extends string, Interfaces extends WidgetInterfaces> {
404
503
  methods: (build: (section: WidgetMethodsSection<Interfaces, WidgetMethodKeyOf<Interfaces>>) => WidgetMethodsSection<Interfaces, never>) => WidgetPluginEventsPhase<Type, Interfaces>;
405
- }, Interfaces, 'methods'> : WidgetPluginEventsPhase<Type, Interfaces>;
406
- type WidgetPluginPropertiesPhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'properties'> extends true ? WidgetPluginOrderedPhase<{
504
+ }
505
+ interface WidgetPluginPropertiesPhaseMembers<Type extends string, Interfaces extends WidgetInterfaces> {
407
506
  properties: (build: (section: WidgetPropertiesSection<Interfaces, WidgetPropertyKeyOf<Interfaces>>) => WidgetPropertiesSection<Interfaces, never>) => WidgetPluginMethodsPhase<Type, Interfaces>;
408
- }, Interfaces, 'properties'> : WidgetPluginMethodsPhase<Type, Interfaces>;
409
- type WidgetPluginStatePhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'state'> extends true ? WidgetPluginOrderedPhase<{
507
+ }
508
+ interface WidgetPluginStatePhaseMembers<Type extends string, Interfaces extends WidgetInterfaces> {
410
509
  state: (build: (section: WidgetStateSection<Interfaces, WidgetStateKeyOf<Interfaces>>) => WidgetStateSection<Interfaces, never>) => WidgetPluginPropertiesPhase<Type, Interfaces>;
411
- }, Interfaces, 'state'> : WidgetPluginPropertiesPhase<Type, Interfaces>;
510
+ }
511
+ type WidgetPluginEventsPhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'events'> extends true ? WidgetPluginOrderedPhase<WidgetPluginEventsPhaseMembers<Type, Interfaces>, Interfaces, 'events'> : WidgetPluginOrderedPhase<WidgetPluginDonePhase<Type, Interfaces>, Interfaces, 'done'>;
512
+ type WidgetPluginMethodsPhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'methods'> extends true ? WidgetPluginOrderedPhase<WidgetPluginMethodsPhaseMembers<Type, Interfaces>, Interfaces, 'methods'> : WidgetPluginEventsPhase<Type, Interfaces>;
513
+ type WidgetPluginPropertiesPhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'properties'> extends true ? WidgetPluginOrderedPhase<WidgetPluginPropertiesPhaseMembers<Type, Interfaces>, Interfaces, 'properties'> : WidgetPluginMethodsPhase<Type, Interfaces>;
514
+ type WidgetPluginStatePhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'state'> extends true ? WidgetPluginOrderedPhase<WidgetPluginStatePhaseMembers<Type, Interfaces>, Interfaces, 'state'> : WidgetPluginPropertiesPhase<Type, Interfaces>;
515
+ /**
516
+ * The `structure` stage: the optional `.structure()` call and the first declared phase after it (or
517
+ * `.done()`) are both callable. Order markers report relative to that next phase, since `structure` may
518
+ * be skipped.
519
+ */
520
+ type WidgetPluginStructureStage<Type extends string, Interfaces extends WidgetInterfaces, Next extends WidgetPluginPhaseName | 'done', NextMembers> = WidgetPluginOrderedPhase<{
521
+ structure: <Result = unknown>(validateStructure: WidgetPluginValidateStructure<Interfaces, Result>) => WidgetPluginStatePhase<Type, Interfaces>;
522
+ } & NextMembers, Interfaces, Next, 'structure' | Next>;
523
+ /**
524
+ * The optional plugin-level structure validator phase. It is not a capability: every plugin may call
525
+ * `.structure(validateStructure)` at most once, after `slots?` and before `state?`, and it changes
526
+ * neither `plugin.capabilities`, the catalog, nor inspection.
527
+ */
528
+ type WidgetPluginStructurePhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'state'> extends true ? WidgetPluginStructureStage<Type, Interfaces, 'state', WidgetPluginStatePhaseMembers<Type, Interfaces>> : HasWidgetCapability<Interfaces, 'properties'> extends true ? WidgetPluginStructureStage<Type, Interfaces, 'properties', WidgetPluginPropertiesPhaseMembers<Type, Interfaces>> : HasWidgetCapability<Interfaces, 'methods'> extends true ? WidgetPluginStructureStage<Type, Interfaces, 'methods', WidgetPluginMethodsPhaseMembers<Type, Interfaces>> : HasWidgetCapability<Interfaces, 'events'> extends true ? WidgetPluginStructureStage<Type, Interfaces, 'events', WidgetPluginEventsPhaseMembers<Type, Interfaces>> : WidgetPluginStructureStage<Type, Interfaces, 'done', WidgetPluginDonePhase<Type, Interfaces>>;
412
529
  /**
413
530
  * `slots: never` is the canonical explicit-empty slots declaration (diagnostic #10 amendment
414
531
  * "declaration-presence semantics and public `WidgetPlugin.capabilities`"): the phase still exists —
415
532
  * gated on `HasWidgetCapability`, never on whether `WidgetCapabilityOf<Interfaces, 'slots'>` happens to
416
533
  * be `never` — and completes as `.slots({})`, since `ExactWidgetSlotDefinitions` for zero slot names is
417
- * exactly `{}`.
534
+ * exactly `{}`. A plugin-level structure validator is declared with the following `.structure()` phase.
418
535
  */
419
536
  type WidgetPluginSlotsPhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'slots'> extends true ? WidgetPluginOrderedPhase<{
420
- slots: <const Definitions extends ExactWidgetSlotDefinitions<Interfaces, Definitions>>(definitions: Definitions, validateStructure?: WidgetPluginValidateStructure<Interfaces>) => WidgetPluginStatePhase<Type, Interfaces>;
421
- }, Interfaces, 'slots'> : WidgetPluginStatePhase<Type, Interfaces>;
537
+ slots: <const Definitions extends ExactWidgetSlotDefinitions<Interfaces, Definitions>>(definitions: Definitions) => WidgetPluginStructurePhase<Type, Interfaces>;
538
+ }, Interfaces, 'slots'> : WidgetPluginStructurePhase<Type, Interfaces>;
422
539
  type WidgetPluginConfigPhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'config'> extends true ? WidgetPluginOrderedPhase<{
423
540
  config: (definition: WidgetConfigDefinition<Interfaces>) => WidgetPluginSlotsPhase<Type, Interfaces>;
424
541
  }, Interfaces, 'config'> : WidgetPluginSlotsPhase<Type, Interfaces>;
@@ -431,8 +548,9 @@ interface WidgetPluginDescriptionPhase<Type extends string> {
431
548
  /**
432
549
  * Starts the plugin builder for one plugin `type`.
433
550
  *
434
- * Phase order is `description -> interfaces -> config? -> slots? -> state? -> properties? -> methods? -> events? -> done()`;
435
- * a phase exists only when its capability is declared. Calling a declared phase out of order (or
551
+ * Phase order is `description -> interfaces -> config? -> slots? -> structure? -> state? -> properties? -> methods? -> events? -> done()`;
552
+ * a capability phase exists only when its capability is declared, while the optional `structure` phase
553
+ * (the plugin-level structure validator) is available to every plugin. Calling a phase out of order (or
436
554
  * repeating it) fails type-checking with an order-specific diagnostic; the runtime builder itself is
437
555
  * order-agnostic.
438
556
  */
@@ -455,10 +573,11 @@ interface WidgetCatalog {
455
573
  type WidgetSystemValidateStructureContext<Plugins extends AnyWidgetPluginTuple> = {
456
574
  readonly blueprint: BlueprintCompileView<Plugins>;
457
575
  } & DiagnosticCollector<RelativeSystemStructureDiagnosticInput<Plugins>>;
458
- type WidgetSystemValidateStructure<Plugins extends AnyWidgetPluginTuple> = (ctx: WidgetSystemValidateStructureContext<Plugins>) => void;
459
- interface CreateWidgetSystemOptions<Plugins extends AnyWidgetPluginTuple> {
576
+ /** `Result` is the validator's own return type (see `WidgetSynchronousResult`). */
577
+ type WidgetSystemValidateStructure<Plugins extends AnyWidgetPluginTuple, Result = unknown> = (ctx: WidgetSystemValidateStructureContext<Plugins>) => WidgetSynchronousResult<Result>;
578
+ interface CreateWidgetSystemOptions<Plugins extends AnyWidgetPluginTuple, Result = unknown> {
460
579
  readonly plugins: Plugins;
461
- readonly validateStructure?: WidgetSystemValidateStructure<Plugins>;
580
+ readonly validateStructure?: WidgetSystemValidateStructure<Plugins, Result>;
462
581
  }
463
582
  /**
464
583
  * Selects one registered plugin by its `type` discriminator.
@@ -466,6 +585,20 @@ interface CreateWidgetSystemOptions<Plugins extends AnyWidgetPluginTuple> {
466
585
  type WidgetPluginOf<Plugins extends AnyWidgetPluginTuple, Type extends string> = Extract<Plugins[number], {
467
586
  readonly type: Type;
468
587
  }>;
588
+ /** The registered plugin types that are string literals; a plugin typed with a broad `string` adds none. */
589
+ type WidgetPluginLiteralTypeOf<Plugins extends AnyWidgetPluginTuple> = WidgetPluginTypeOf<Plugins[number]> extends (infer Type) ? Type extends string ? (string extends Type ? never : Type) : never : never;
590
+ /**
591
+ * `getPlugin` overloads. `Plugins` appears only in type-parameter constraints and in `WidgetPluginOf`, so
592
+ * a precisely typed System stays assignable to a loosely typed one (`WidgetSystem`).
593
+ */
594
+ interface WidgetSystemGetPlugin<Plugins extends AnyWidgetPluginTuple> {
595
+ /** A registered literal type (or a union of them): that exact plugin. */
596
+ <Type extends WidgetPluginLiteralTypeOf<Plugins>>(type: Type): WidgetPluginOf<Plugins, Type>;
597
+ /** Any type on a loosely typed System (one with a broad `string` plugin type), which may be unregistered. */
598
+ <Type extends WidgetPluginTypeOf<Plugins[number]>>(type: Type): AnyWidgetPlugin | null;
599
+ /** A broad `string`, which may name no registered plugin. An unregistered literal on a precisely typed System stays a type error. */
600
+ <Type extends string>(type: string extends Type ? Type : never): AnyWidgetPlugin | null;
601
+ }
469
602
  interface WidgetSystem<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple> {
470
603
  /**
471
604
  * The registered plugin tuple. It defines this instance's TypeScript universe; there is no
@@ -474,7 +607,8 @@ interface WidgetSystem<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTup
474
607
  readonly plugins: Plugins;
475
608
  readonly validateStructure: WidgetSystemValidateStructure<Plugins> | null;
476
609
  readonly catalog: WidgetCatalog;
477
- getPlugin: <Type extends WidgetPluginTypeOf<Plugins[number]>>(type: Type) => WidgetPluginOf<Plugins, Type>;
610
+ /** The registered plugin of `type`, or `null` when no plugin of that type is registered. */
611
+ getPlugin: WidgetSystemGetPlugin<Plugins>;
478
612
  /**
479
613
  * The compilation boundary. The input is `unknown` because JSON-parsed/untrusted document data is
480
614
  * the real boundary; malformed input still produces an inspectable Blueprint.
@@ -488,19 +622,26 @@ interface WidgetSystem<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTup
488
622
  */
489
623
  createBlueprint: (definition: unknown) => WidgetSystemBlueprint<Plugins>;
490
624
  /**
491
- * Parses `text` with `JSON.parse` and compiles the result. Observably equivalent to
492
- * `createBlueprint(JSON.parse(text))`, but cheaper: a value produced by `JSON.parse` (without a
493
- * reviver) is in the authored JSON domain by construction, so Core skips the whole-source JSON-domain
494
- * inspection and `sourceJsonCompatible` is `true`. Invalid JSON text throws the `SyntaxError` from
495
- * `JSON.parse`, unchanged. The parsed source is referenced by nothing but the Blueprint.
625
+ * Parses `text` with `JSON.parse` and compiles the result. Equivalent to
626
+ * `createBlueprint(JSON.parse(text))`, including its diagnostics: a value Core parsed itself can only
627
+ * leave the authored JSON domain through a non-finite number (`1e400` parses to `Infinity`, diagnosed as
628
+ * `json-incompatible-value` / `non-finite-number`) or through nesting deeper than `MAX_JSON_DEPTH`, so Core
629
+ * replaces the descriptor-level JSON-domain inspection with a cheaper scan for exactly those two cases and
630
+ * runs the full inspection when the scan finds either. `sourceJsonCompatible` is `true` only when that
631
+ * proof succeeds. Invalid JSON text throws the `SyntaxError` from `JSON.parse`, unchanged. The parsed
632
+ * source is referenced by nothing but the Blueprint.
496
633
  */
497
634
  createBlueprintFromJson: (text: string) => WidgetSystemBlueprint<Plugins>;
498
635
  }
499
- type WidgetSystemConfigurationErrorCode = 'foreign-plugin' | 'duplicate-plugin-type';
636
+ type WidgetSystemConfigurationErrorCode = 'invalid-options' | 'foreign-plugin' | 'duplicate-plugin-type';
500
637
  /**
501
- * Thrown by `createWidgetSystem` for an invalid plugin registration. Discriminate by class and `code`;
502
- * `message` is not protocol.
638
+ * Thrown by `createWidgetSystem` for invalid options or an invalid plugin registration. Discriminate by
639
+ * class and `code`; `message` is not protocol. The options shape is checked first, then the plugin
640
+ * entries in tuple order.
503
641
  *
642
+ * - `invalid-options`: `options` is not an object, `options.plugins` is not an array, or
643
+ * `options.validateStructure` is present (neither `undefined` nor `null`) but not a function.
644
+ * `pluginIndex`, `pluginType` and `firstPluginIndex` are `null`.
504
645
  * - `foreign-plugin`: the entry at `pluginIndex` was not completed by this loaded module instance
505
646
  * (another module instance or a structural look-alike). `pluginType` is its `type` when a string,
506
647
  * else `null`. `firstPluginIndex` is `null`.
@@ -509,19 +650,26 @@ type WidgetSystemConfigurationErrorCode = 'foreign-plugin' | 'duplicate-plugin-t
509
650
  */
510
651
  declare class WidgetSystemConfigurationError extends Error {
511
652
  readonly code: WidgetSystemConfigurationErrorCode;
512
- readonly pluginIndex: number;
653
+ readonly pluginIndex: number | null;
513
654
  readonly pluginType: string | null;
514
655
  readonly firstPluginIndex: number | null;
515
656
  readonly name = "WidgetSystemConfigurationError";
516
- constructor(code: WidgetSystemConfigurationErrorCode, pluginIndex: number, pluginType: string | null, firstPluginIndex?: number | null, message?: string);
657
+ constructor(code: WidgetSystemConfigurationErrorCode, pluginIndex: number | null, pluginType: string | null, firstPluginIndex?: number | null, message?: string);
517
658
  }
518
659
  /**
519
- * Creates an instance-scoped, immutable widget system. Duplicate `plugin.type` is rejected.
660
+ * Creates an instance-scoped, immutable widget system. Malformed options, foreign plugins and duplicate
661
+ * `plugin.type` are rejected with a `WidgetSystemConfigurationError`.
520
662
  */
521
- declare function createWidgetSystem<const Plugins extends AnyWidgetPluginTuple>(options: CreateWidgetSystemOptions<Plugins>): WidgetSystem<Plugins>;
663
+ declare function createWidgetSystem<const Plugins extends AnyWidgetPluginTuple, Result = unknown>(options: CreateWidgetSystemOptions<Plugins, Result>): WidgetSystem<Plugins>;
522
664
  //#endregion
523
665
  //#region src/internal/contract.d.ts
524
666
  type WidgetSystemBlueprintStatus = 'valid' | 'invalid';
667
+ /**
668
+ * The structured (array form) `SourcePath` of one Blueprint node's authored object within `blueprint.source`,
669
+ * e.g. `[]` for the root and `['slots', 'children', 0]` for its first child. Used verbatim as a `SourcePatch`
670
+ * path against the same source it addresses exactly that node.
671
+ */
672
+ type BlueprintSourcePath = readonly (string | number)[];
525
673
  interface BlueprintWidgetNodeBase<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple, Source = unknown> {
526
674
  /**
527
675
  * The exact source fragment for this recovered node. Never mutated, cloned or frozen by the core.
@@ -535,6 +683,10 @@ interface BlueprintWidgetNodeBase<Plugins extends AnyWidgetPluginTuple = AnyWidg
535
683
  */
536
684
  interface UnresolvedBlueprintWidgetNode<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple, Source = unknown> extends BlueprintWidgetNodeBase<Plugins, Source> {
537
685
  readonly resolved: false;
686
+ /** Best-effort identity hint: the authored `id` when it is a string, else `null`. */
687
+ readonly id: string | null;
688
+ /** Best-effort identity hint: the authored `type` when it is a string (even an unknown one), else `null`. */
689
+ readonly type: string | null;
538
690
  }
539
691
  /**
540
692
  * Complete declared semantic slot map. Only declared slots appear, every declared slot exists, and an
@@ -659,7 +811,7 @@ interface BlueprintCompileView<Plugins extends AnyWidgetPluginTuple = AnyWidgetP
659
811
  /**
660
812
  * Read-only valid-Blueprint view handed to runtime semantic callbacks (`compute`, `execute`).
661
813
  */
662
- interface ValidBlueprintView<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple> {
814
+ interface BlueprintRuntimeView<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple> {
663
815
  readonly root: ResolvedBlueprintWidgetNode<Plugins, JsonValue>;
664
816
  getWidget: (id: WidgetId) => ResolvedBlueprintWidgetNode<Plugins, JsonValue> | null;
665
817
  getParent: (node: ResolvedBlueprintWidgetNode<Plugins>) => ResolvedBlueprintWidgetNode<Plugins, JsonValue> | null;
@@ -674,6 +826,11 @@ interface ValidBlueprintView<Plugins extends AnyWidgetPluginTuple = AnyWidgetPlu
674
826
  type WidgetSourceFor<Plugin extends AnyWidgetPlugin, Plugins extends AnyWidgetPluginTuple> = {
675
827
  readonly id: WidgetId;
676
828
  readonly type: WidgetPluginTypeOf<Plugin>;
829
+ /**
830
+ * The reserved extension key: any JSON value, preserved in `source` and never interpreted by
831
+ * Core. Every other unrecognized own key is diagnosed as `unexpected-widget-field`.
832
+ */
833
+ readonly meta?: JsonValue;
677
834
  } & (HasWidgetCapability<WidgetInterfacesOf<Plugin>, 'config'> extends true ? [null] extends [WidgetRawConfigOf<WidgetInterfacesOf<Plugin>>] ? {
678
835
  readonly config?: WidgetRawConfigOf<WidgetInterfacesOf<Plugin>>;
679
836
  } : {
@@ -697,13 +854,14 @@ interface WidgetSystemBlueprintBase<Plugins extends AnyWidgetPluginTuple, Source
697
854
  */
698
855
  recompile: (definition: unknown) => WidgetSystemBlueprint<Plugins>;
699
856
  }
700
- interface ValidWidgetSystemBlueprint<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple> extends WidgetSystemBlueprintBase<Plugins, JsonValue> {
857
+ interface ValidWidgetSystemBlueprint<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple> extends WidgetSystemBlueprintBase<Plugins, WidgetSource<Plugins>> {
701
858
  readonly status: 'valid';
702
859
  readonly sourceJsonCompatible: true;
703
860
  readonly root: ResolvedBlueprintWidgetNode<Plugins, JsonValue>;
704
861
  getWidget: (id: WidgetId) => ResolvedBlueprintWidgetNode<Plugins, JsonValue> | null;
705
862
  getParent: (node: BlueprintWidgetNode<Plugins>) => ResolvedBlueprintWidgetNode<Plugins, JsonValue> | null;
706
863
  getLocation: (node: BlueprintWidgetNode<Plugins>) => WidgetLocation<Plugins, JsonValue> | null;
864
+ getSourcePath: (node: BlueprintWidgetNode<Plugins>) => BlueprintSourcePath | null;
707
865
  getChildren: (node: BlueprintWidgetNode<Plugins>) => readonly ResolvedBlueprintWidgetNode<Plugins, JsonValue>[];
708
866
  getChildrenAt: (node: BlueprintWidgetNode<Plugins>, slot: WidgetMemberKey) => readonly ResolvedBlueprintWidgetNode<Plugins, JsonValue>[];
709
867
  readonly diagnostics: readonly never[];
@@ -716,6 +874,7 @@ interface InvalidWidgetSystemBlueprint<Plugins extends AnyWidgetPluginTuple = An
716
874
  getWidget: (id: WidgetId) => BlueprintWidgetNode<Plugins, Source> | null;
717
875
  getParent: (node: BlueprintWidgetNode<Plugins>) => BlueprintWidgetNode<Plugins, Source> | null;
718
876
  getLocation: (node: BlueprintWidgetNode<Plugins>) => WidgetLocation<Plugins, Source> | null;
877
+ getSourcePath: (node: BlueprintWidgetNode<Plugins>) => BlueprintSourcePath | null;
719
878
  getChildren: (node: BlueprintWidgetNode<Plugins>) => readonly BlueprintWidgetNode<Plugins, Source>[];
720
879
  getChildrenAt: (node: BlueprintWidgetNode<Plugins>, slot: WidgetMemberKey) => readonly BlueprintWidgetNode<Plugins, Source>[];
721
880
  readonly diagnostics: readonly BlueprintDiagnostic<Plugins>[];
@@ -741,14 +900,16 @@ interface RuntimeState<T> {
741
900
  getDiagnostics: () => readonly RuntimeStateDiagnostic[];
742
901
  subscribeDiagnostics: (listener: (diagnostics: readonly RuntimeStateDiagnostic[]) => void) => () => void;
743
902
  }
903
+ /** A completed result's ok value is exactly what `compute` returned (never an added `null`). */
744
904
  interface RuntimeProperty<T> {
745
- get: () => ExecutionResult<T | null, RuntimePropertyDiagnostic>;
746
- subscribe: (listener: (result: ExecutionResult<T | null, RuntimePropertyDiagnostic>) => void) => () => void;
905
+ get: () => ExecutionResult<T, RuntimePropertyDiagnostic>;
906
+ subscribe: (listener: (result: ExecutionResult<T, RuntimePropertyDiagnostic>) => void) => () => void;
747
907
  getDiagnostics: () => readonly RuntimePropertyDiagnostic[];
748
908
  subscribeDiagnostics: (listener: (diagnostics: readonly RuntimePropertyDiagnostic[]) => void) => () => void;
749
909
  }
910
+ /** A successful invocation's ok value is exactly what `execute` returned (never an added `null`). */
750
911
  interface RuntimeMethod<Fn extends (...args: any[]) => any> {
751
- (...args: Parameters<Fn>): ExecutionResult<ReturnType<Fn> | null, RuntimeMethodDiagnostic>;
912
+ (...args: Parameters<Fn>): ExecutionResult<ReturnType<Fn>, RuntimeMethodDiagnostic>;
752
913
  getDiagnostics: () => readonly RuntimeMethodDiagnostic[];
753
914
  subscribeDiagnostics: (listener: (diagnostics: readonly RuntimeMethodDiagnostic[]) => void) => () => void;
754
915
  }
@@ -757,6 +918,12 @@ interface RuntimeEvent<Args extends readonly unknown[]> {
757
918
  }
758
919
  type RuntimeStateSurface<Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'state'> extends true ? {
759
920
  readonly state: { readonly [Key in WidgetStateKeyOf<Interfaces>]: RuntimeState<WidgetStateValueOf<Interfaces, Key>>; };
921
+ /**
922
+ * `WidgetSystemRuntime.resetState()` scoped to this widget: restores its State members to their
923
+ * initialization outcome without running `validate`, in one batch; Property/Method diagnostic
924
+ * snapshots are not reset. Throws `WidgetSystemRuntimeDisposedError` after dispose.
925
+ */
926
+ resetState: () => void;
760
927
  } : unknown;
761
928
  type RuntimePropertySurface<Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'properties'> extends true ? {
762
929
  readonly properties: { readonly [Name in WidgetPropertyKeyOf<Interfaces>]: RuntimeProperty<WidgetPropertyValueOf<Interfaces, Name>>; };
@@ -778,7 +945,7 @@ type RuntimeMethodSurface<Interfaces extends WidgetInterfaces> = HasWidgetCapabi
778
945
  type RuntimeWidgetFor<Plugin extends AnyWidgetPlugin, Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple> = {
779
946
  readonly id: WidgetId;
780
947
  readonly type: WidgetPluginTypeOf<Plugin>;
781
- readonly blueprint: ResolvedBlueprintWidgetNodeFor<Plugin, Plugins>;
948
+ readonly blueprintNode: ResolvedBlueprintWidgetNodeFor<Plugin, Plugins>;
782
949
  /**
783
950
  * This widget's own aggregate diagnostic snapshot: state members -> property members -> method
784
951
  * members, declaration order within each capability, each primitive's own local diagnostic order.
@@ -793,7 +960,8 @@ type RuntimeWidget<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple>
793
960
  * Executable instance of a valid Blueprint.
794
961
  *
795
962
  * After `dispose()`, `isDisposed` and `blueprint` stay readable while every live query/operation and
796
- * every new subscription throws `WidgetSystemRuntimeDisposedError`.
963
+ * every new subscription throws `WidgetSystemRuntimeDisposedError`. Disposal notifies only the listeners
964
+ * registered with `subscribeDisposal()`; it emits no State, Property, Event or diagnostic notification.
797
965
  */
798
966
  interface WidgetSystemRuntime<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple> {
799
967
  readonly blueprint: ValidWidgetSystemBlueprint<Plugins>;
@@ -807,12 +975,35 @@ interface WidgetSystemRuntime<Plugins extends AnyWidgetPluginTuple = AnyWidgetPl
807
975
  * through ordinary invalidation.
808
976
  */
809
977
  resetState: () => void;
978
+ /**
979
+ * The current value of every State member, keyed by widget id and then member key, in exactly the
980
+ * shape `overrideStateDefaults` accepts: `blueprint.createRuntime({ overrideStateDefaults:
981
+ * runtime.snapshotState() })` reproduces every non-null value. Members whose value is `null` are
982
+ * omitted, and so are widgets left with no entry. Returns a fresh plain object owned by the caller;
983
+ * the values themselves are passed by reference, not cloned.
984
+ */
985
+ snapshotState: () => Record<WidgetId, Record<WidgetMemberKey, unknown>>;
810
986
  /**
811
987
  * Runtime-level diagnostics plus the current state/property/method diagnostic snapshots, in deterministic
812
988
  * order. Never history, and never activates property evaluation.
813
989
  */
814
- getDiagnostics: () => readonly WidgetSystemRuntimeDiagnostic[];
815
- subscribeDiagnostics: (listener: (diagnostics: readonly WidgetSystemRuntimeDiagnostic[]) => void) => () => void;
990
+ getDiagnostics: () => readonly RuntimeDiagnostic[];
991
+ subscribeDiagnostics: (listener: (diagnostics: readonly RuntimeDiagnostic[]) => void) => () => void;
992
+ /**
993
+ * Registers a listener that runs exactly once, synchronously, inside the first `dispose()` call, with no
994
+ * arguments — for a host to cancel the asynchronous work it owns. By then the Runtime is already fully
995
+ * disposed: `isDisposed` is `true`, every Runtime-owned subscription is torn down, a live operation throws
996
+ * `WidgetSystemRuntimeDisposedError`, `dispose()` is a no-op, and `blueprint` and a widget's `id`,
997
+ * `type` and `blueprintNode` stay readable. Listeners run in subscription order, like Event listeners from
998
+ * a list fixed when delivery starts: one removed meanwhile still runs, and none can be added meanwhile,
999
+ * because subscribing to a disposed Runtime throws `WidgetSystemRuntimeDisposedError`, as it does after
1000
+ * disposal in general (the listener is never invoked immediately). A throwing listener never reaches the
1001
+ * `dispose()` caller or stops the remaining listeners; it is reported asynchronously like any other
1002
+ * isolated listener exception. Registering the same function twice makes two independent registrations.
1003
+ * The returned unsubscribe function is idempotent and safe to call before or after disposal; once the
1004
+ * listener has run it does nothing, and the Runtime keeps no reference to the listener.
1005
+ */
1006
+ subscribeDisposal: (listener: () => void) => () => void;
816
1007
  dispose: () => void;
817
1008
  }
818
1009
  //#endregion
@@ -823,14 +1014,23 @@ interface DiagnosticBase<Code extends string = string, Location = unknown> {
823
1014
  readonly location: Location;
824
1015
  readonly message: string;
825
1016
  }
826
- /** General structural diagnostic shape for code which does not need a narrower union. */
827
- type Diagnostic<Code extends string = string, Location = unknown> = DiagnosticBase<Code, Location>;
828
1017
  declare const EMPTY_DIAGNOSTICS: readonly never[];
829
1018
  declare class WidgetSystemRuntimeDisposedError extends Error {
830
1019
  readonly name = "WidgetSystemRuntimeDisposedError";
831
1020
  readonly code: "runtime-disposed";
832
1021
  constructor(message?: string);
833
1022
  }
1023
+ /**
1024
+ * Thrown when one Runtime's event emits nest deeper than its re-entrancy limit: an event listener keeps
1025
+ * re-invoking a Method that emits again. A non-semantic safety guard against runaway re-entrancy (a
1026
+ * `RangeError`, like any other runaway recursion), never a Diagnostic. Event-listener isolation does not
1027
+ * swallow it, so it unwinds every nested emit to the operation that started the loop.
1028
+ */
1029
+ declare class WidgetSystemRuntimeReentrancyError extends RangeError {
1030
+ readonly name = "WidgetSystemRuntimeReentrancyError";
1031
+ readonly code: "emit-depth-exceeded";
1032
+ constructor(message?: string);
1033
+ }
834
1034
  interface RelativeValueDiagnosticInput {
835
1035
  readonly message: string;
836
1036
  readonly path?: DiagnosticPath;
@@ -941,7 +1141,9 @@ type BlueprintDependencyOperation = BlueprintDependencyReference['operation'];
941
1141
  type BlueprintDiagnosticRelated<Plugins extends AnyWidgetPluginTuple> = NonEmptyReadonlyArray<BlueprintNodeDiagnosticLocation<Plugins>>;
942
1142
  type BlueprintDefinitionDiagnostic<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple> = DiagnosticBase<'invalid-widget-definition', BlueprintWidgetDiagnosticLocation<Plugins>> | (DiagnosticBase<'invalid-widget-id', BlueprintWidgetDiagnosticLocation<Plugins>> & {
943
1143
  readonly path: DiagnosticPath;
944
- readonly related?: BlueprintDiagnosticRelated<Plugins>;
1144
+ }) | (DiagnosticBase<'duplicate-widget-id', BlueprintWidgetDiagnosticLocation<Plugins>> & {
1145
+ readonly path: DiagnosticPath;
1146
+ readonly related: BlueprintDiagnosticRelated<Plugins>;
945
1147
  }) | (DiagnosticBase<'invalid-widget-type', BlueprintWidgetDiagnosticLocation<Plugins>> & {
946
1148
  readonly path: DiagnosticPath;
947
1149
  }) | (DiagnosticBase<'unknown-widget-type', BlueprintWidgetDiagnosticLocation<Plugins>> & {
@@ -956,6 +1158,8 @@ type BlueprintDefinitionDiagnostic<Plugins extends AnyWidgetPluginTuple = AnyWid
956
1158
  readonly path: DiagnosticPath;
957
1159
  }) | (DiagnosticBase<'invalid-widget-slot', BlueprintWidgetDiagnosticLocation<Plugins>> & {
958
1160
  readonly path: DiagnosticPath;
1161
+ }) | (DiagnosticBase<'unexpected-widget-field', BlueprintWidgetDiagnosticLocation<Plugins>> & {
1162
+ readonly path: DiagnosticPath;
959
1163
  });
960
1164
  type BlueprintConfigDiagnostic<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple> = DiagnosticBase<'invalid-widget-config', BlueprintWidgetDiagnosticLocation<Plugins>> & {
961
1165
  readonly path?: DiagnosticPath;
@@ -971,13 +1175,14 @@ type BlueprintDependencyDiagnostic<Plugins extends AnyWidgetPluginTuple = AnyWid
971
1175
  }) | (DiagnosticBase<'ambiguous-dependency-target', BlueprintDependencyDiagnosticLocation<Plugins>> & {
972
1176
  readonly dependency: BlueprintDependencyReference;
973
1177
  readonly related: NonEmptyReadonlyArray<BlueprintDependencyDiagnosticLocation<Plugins>>;
974
- }) | (DiagnosticBase<'property-dependency-has-write-effects', BlueprintDependencyDiagnosticLocation<Plugins>> & {
1178
+ }) | (DiagnosticBase<'property-dependency-has-side-effects', BlueprintDependencyDiagnosticLocation<Plugins>> & {
975
1179
  readonly dependency: BlueprintDependencyReference;
976
1180
  readonly related: NonEmptyReadonlyArray<BlueprintDependencyDiagnosticLocation<Plugins>>;
977
1181
  }) | (DiagnosticBase<'property-evaluation-cycle', BlueprintDependencyDiagnosticLocation<Plugins>> & {
978
- readonly related?: NonEmptyReadonlyArray<BlueprintDependencyDiagnosticLocation<Plugins>>;
1182
+ /** Every member of the cycle, the subject included, in member order; one array shared by all diagnostics of the cycle. */
1183
+ readonly related: NonEmptyReadonlyArray<BlueprintDependencyDiagnosticLocation<Plugins>>;
979
1184
  });
980
- type JsonCompatibilityReason = 'undefined' | 'non-finite-number' | 'bigint' | 'symbol' | 'function' | 'unsupported-object-prototype' | 'symbol-key' | 'accessor-property' | 'sparse-array' | 'array-extra-property' | 'cyclic-reference';
1185
+ type JsonCompatibilityReason = 'undefined' | 'non-finite-number' | 'bigint' | 'symbol' | 'function' | 'unsupported-object-prototype' | 'symbol-key' | 'accessor-property' | 'sparse-array' | 'array-extra-property' | 'cyclic-reference' | 'max-depth-exceeded';
981
1186
  type JsonCompatibilityDiagnostic = DiagnosticBase<'json-incompatible-value', BlueprintSourceDiagnosticLocation> & {
982
1187
  readonly path: DiagnosticPath;
983
1188
  readonly reason: JsonCompatibilityReason;
@@ -1004,7 +1209,7 @@ type RuntimePrimitiveDiagnosticLocation = {
1004
1209
  interface RuntimeLevelDiagnosticLocation {
1005
1210
  readonly type: 'runtime';
1006
1211
  }
1007
- type RuntimeDiagnosticLocation = RuntimePrimitiveDiagnosticLocation;
1212
+ type RuntimeDiagnosticLocation = RuntimePrimitiveDiagnosticLocation | RuntimeLevelDiagnosticLocation;
1008
1213
  type RuntimeStateDiagnostic = DiagnosticBase<'invalid-state-value', Extract<RuntimePrimitiveDiagnosticLocation, {
1009
1214
  type: 'state';
1010
1215
  }>> & {
@@ -1036,7 +1241,7 @@ type RuntimeMethodResultDiagnostic = DiagnosticBase<'invalid-method-result', Ext
1036
1241
  type RuntimeDependencyTargetFailedDiagnostic = DiagnosticBase<'dependency-target-failed', RuntimePrimitiveDiagnosticLocation> & {
1037
1242
  readonly dependency: BlueprintDependencyReference;
1038
1243
  readonly related: NonEmptyReadonlyArray<RuntimePrimitiveDiagnosticLocation>;
1039
- readonly cause: RuntimeDiagnostic;
1244
+ readonly cause: RuntimeWidgetDiagnostic;
1040
1245
  };
1041
1246
  type RuntimeDependencyValueRejectedDiagnostic = DiagnosticBase<'dependency-value-rejected', RuntimePrimitiveDiagnosticLocation> & {
1042
1247
  readonly dependency: BlueprintDependencyReference;
@@ -1055,7 +1260,6 @@ type RuntimeMethodDependencyDiagnostic = (RuntimeDependencyTargetFailedDiagnosti
1055
1260
  };
1056
1261
  type RuntimePropertyDiagnostic = RuntimePropertyResultDiagnostic | RuntimePropertyDependencyDiagnostic;
1057
1262
  type RuntimeMethodDiagnostic = RuntimeMethodArgsDiagnostic | RuntimeMethodResultDiagnostic | RuntimeMethodDependencyDiagnostic;
1058
- type RuntimeDiagnostic = RuntimeStateDiagnostic | RuntimePropertyDiagnostic | RuntimeMethodDiagnostic;
1059
1263
  type RuntimeLevelDiagnostic = (DiagnosticBase<'invalid-state-overrides', RuntimeLevelDiagnosticLocation> & {
1060
1264
  readonly path?: DiagnosticPath;
1061
1265
  readonly reason?: string;
@@ -1073,7 +1277,7 @@ type RuntimeLevelDiagnostic = (DiagnosticBase<'invalid-state-overrides', Runtime
1073
1277
  readonly reason?: string;
1074
1278
  });
1075
1279
  type RuntimeWidgetDiagnostic = RuntimeStateDiagnostic | RuntimePropertyDiagnostic | RuntimeMethodDiagnostic;
1076
- type WidgetSystemRuntimeDiagnostic = RuntimeLevelDiagnostic | RuntimeWidgetDiagnostic;
1280
+ type RuntimeDiagnostic = RuntimeLevelDiagnostic | RuntimeWidgetDiagnostic;
1077
1281
  //#endregion
1078
1282
  //#region src/dep.d.ts
1079
1283
  /**
@@ -1227,11 +1431,16 @@ type SelfStateDependencyOperations<Interfaces extends WidgetInterfaces, Consumer
1227
1431
  } & (Consumer extends 'method' ? {
1228
1432
  set: <Key extends WidgetStateKeyOf<Interfaces>>(key: Key) => StateSetDepExpression<WidgetStateValueOf<Interfaces, Key>, false>;
1229
1433
  } : unknown);
1434
+ /**
1435
+ * A self Property read yields exactly what its `compute` returned: a self target is never absent, so no
1436
+ * `null` is added (unlike a State read, whose member may hold `null`).
1437
+ */
1230
1438
  interface SelfPropertyDependencyOperations<Interfaces extends WidgetInterfaces> {
1231
- get: <Name extends WidgetPropertyKeyOf<Interfaces>>(name: Name) => PropertyGetDepExpression<WidgetPropertyValueOf<Interfaces, Name> | null, false>;
1439
+ get: <Name extends WidgetPropertyKeyOf<Interfaces>>(name: Name) => PropertyGetDepExpression<WidgetPropertyValueOf<Interfaces, Name>, false>;
1232
1440
  }
1441
+ /** A self Method invocation yields exactly what its `execute` returned; see {@link SelfPropertyDependencyOperations}. */
1233
1442
  interface SelfMethodDependencyOperations<Interfaces extends WidgetInterfaces> {
1234
- invoke: <Name extends WidgetMethodKeyOf<Interfaces>>(name: Name) => MethodInvokeDepExpression<WidgetMethodArgsOf<Interfaces, Name>, WidgetMethodReturnOf<Interfaces, Name> | null, false>;
1443
+ invoke: <Name extends WidgetMethodKeyOf<Interfaces>>(name: Name) => MethodInvokeDepExpression<WidgetMethodArgsOf<Interfaces, Name>, WidgetMethodReturnOf<Interfaces, Name>, false>;
1235
1444
  }
1236
1445
  /**
1237
1446
  * `self` target stage: guaranteed target, strongly typed, and capability-aware.
@@ -1260,4 +1469,4 @@ interface DependencyBuilder<Interfaces extends WidgetInterfaces, Consumer extend
1260
1469
  widget: (widgetId: WidgetId) => OptionalizableDependencyTarget<Consumer>;
1261
1470
  }
1262
1471
  //#endregion
1263
- export { RuntimeDependencyValueRejectedDiagnostic as $, createWidgetValueContract as $n, WidgetCatalogEntry as $t, BlueprintNodeDiagnostic as A, WidgetPluginInterfacesPhase as An, JsonPrimitive as Ar, RuntimeEventSurface as At, Diagnostic as B, WidgetPropertyComputeContext as Bn, SelfBlueprintWidgetNodeView as Bt, BlueprintDependencyDiagnosticLocation as C, WidgetPlugin as Cn, WidgetResolvedConfigOf as Cr, CreateWidgetSystemRuntimeOptions as Ct, BlueprintDiagnostic as D, WidgetPluginDescriptionPhase as Dn, WidgetStateValueOf as Dr, ResolvedBlueprintWidgetNodeView as Dt, BlueprintDependencyTarget as E, WidgetPluginConfigPhase as En, WidgetStateOf as Er, ResolvedBlueprintWidgetNodeFor as Et, BlueprintSourceDiagnostic as F, WidgetPluginStatePhase as Fn, RuntimeState as Ft, JsonCompatibilityDiagnostic as G, WidgetSlotDefinitions as Gn, WidgetLocationView as Gt, DiagnosticCollector as H, WidgetRegisterDepsContext as Hn, ValidBlueprintView as Ht, BlueprintSourceDiagnosticLocation as I, WidgetPluginTypeOf as In, RuntimeStateSurface as It, RelativeSlotStructureDiagnosticInput as J, WidgetStateMemberDefinition as Jn, WidgetSystemBlueprint as Jt, JsonCompatibilityReason as K, WidgetSlotValidateStructureContext as Kn, WidgetSource as Kt, BlueprintStructureDiagnostic as L, WidgetPluginValidateStructure as Ln, RuntimeWidget as Lt, BlueprintPropertyDiagnosticLocation as M, WidgetPluginPhaseOrderViolation as Mn, RuntimeMethodSurface as Mt, BlueprintSlotChildDiagnosticLocation as N, WidgetPluginPropertiesPhase as Nn, RuntimeProperty as Nt, BlueprintDiagnosticLocation as O, WidgetPluginDonePhase as On, JsonArray as Or, ResolvedBlueprintWidgetNodeViewFor as Ot, BlueprintSlotDiagnosticLocation as P, WidgetPluginSlotsPhase as Pn, RuntimePropertySurface as Pt, RuntimeDependencyTargetFailedDiagnostic as Q, createWidgetPlugin as Qn, WidgetCatalog as Qt, BlueprintStructureDiagnosticLocation as R, WidgetPluginValidateStructureContext as Rn, RuntimeWidgetFor as Rt, BlueprintDependencyDiagnostic as S, WidgetMethodsSection as Sn, WidgetRawConfigOf as Sr, BlueprintWidgetNodeView as St, BlueprintDependencyReference as T, WidgetPluginConfigMetadata as Tn, WidgetStateKeyOf as Tr, ResolvedBlueprintWidgetNode as Tt, DiagnosticPath as U, WidgetResolvedConfigContext as Un, ValidWidgetSystemBlueprint as Ut, DiagnosticBase as V, WidgetPropertyDefinition as Vn, UnresolvedBlueprintWidgetNode as Vt, EMPTY_DIAGNOSTICS as W, WidgetSlotDefinition as Wn, WidgetLocation as Wt, RelativeSystemStructureDiagnosticInput as X, WidgetStateValidateContext as Xn, WidgetSystemRuntime as Xt, RelativeStructureDiagnosticLocation as Y, WidgetStateSection as Yn, WidgetSystemBlueprintStatus as Yt, RelativeValueDiagnosticInput as Z, WidgetValueContract as Zn, CreateWidgetSystemOptions as Zt, ToExecutedDeps as _, WidgetInterfacesOf as _n, WidgetMethodReturnOf as _r, BlueprintNodeConfigFields as _t, MaybeOptional as a, WidgetSystemValidateStructureContext as an, WidgetEventArgsOf as ar, RuntimeMethodDependencyDiagnostic as at, BlueprintConfigDiagnostic as b, WidgetMethodExecuteContext as bn, WidgetPropertyKeyOf as br, BlueprintWidgetNode as bt, PropertyGetDepExpression as c, AnyWidgetPluginTuple as cn, WidgetId as cr, RuntimePropertyDependencyDiagnostic as ct, SelfMethodDependencyOperations as d, WidgetConfigJsonSchema as dn, WidgetMemberKey as dr, RuntimeStateDiagnostic as dt, WidgetPluginOf as en, ExecutionFailure as er, RuntimeDiagnostic as et, SelfPropertyDependencyOperations as f, WidgetConfigValidateContext as fn, WidgetMemberKeysOf as fr, RuntimeWidgetDiagnostic as ft, ToExecutedDep as g, WidgetEventsSection as gn, WidgetMethodOf as gr, BlueprintCompileView as gt, StateSetDepExpression as h, WidgetEventEmitterContext as hn, WidgetMethodKeyOf as hr, WidgetSystemRuntimeDisposedError as ht, EmptyRegisteredDeps as i, WidgetSystemValidateStructure as in, WidgetCapabilityOf as ir, RuntimeMethodArgsDiagnostic as it, BlueprintNodeDiagnosticLocation as j, WidgetPluginMethodsPhase as jn, JsonValue as jr, RuntimeMethod as jt, BlueprintMethodDiagnosticLocation as k, WidgetPluginEventsPhase as kn, JsonObject as kr, RuntimeEvent as kt, RegisteredDeps as l, WIDGET_CONFIG_JSON_SCHEMA_DIALECT as ln, WidgetInterfaces as lr, RuntimePropertyDiagnostic as lt, StateGetDepExpression as m, WidgetEventEmitter as mn, WidgetMethodArgsOf as mr, WidgetSystemRuntimeDiagnostic as mt, DependencyBuilder as n, WidgetSystemConfigurationError as nn, HasWidgetCapability as nr, RuntimeLevelDiagnostic as nt, MethodInvokeDepExpression as o, createWidgetSystem as on, WidgetEventKeyOf as or, RuntimeMethodDiagnostic as ot, SelfStateDependencyOperations as p, WidgetEventDefinition as pn, WidgetMemberValueOf as pr, SourceAccessDiagnostic as pt, RelativePluginStructureDiagnosticInput as q, WidgetStateDefaultContext as qn, WidgetSourceFor as qt, DependencyConsumer as r, WidgetSystemConfigurationErrorCode as rn, NonEmptyReadonlyArray as rr, RuntimeLevelDiagnosticLocation as rt, OptionalizableDependencyTarget as s, AnyWidgetPlugin as sn, WidgetEventsOf as sr, RuntimeMethodResultDiagnostic as st, AnyDepExpression as t, WidgetSystem as tn, ExecutionResult as tr, RuntimeDiagnosticLocation as tt, SelfDependencyTarget as u, WidgetConfigDefinition as un, WidgetInterfacesViolationOf as ur, RuntimePropertyResultDiagnostic as ut, UnknownTargetDependencyOperations as v, WidgetInterfacesViolation as vn, WidgetMethodsOf as vr, BlueprintSemanticSlots as vt, BlueprintDependencyOperation as w, WidgetPluginCapabilities as wn, WidgetSlotNameOf as wr, InvalidWidgetSystemBlueprint as wt, BlueprintDefinitionDiagnostic as x, WidgetMethodValidateArgsContext as xn, WidgetPropertyValueOf as xr, BlueprintWidgetNodeBase as xt, UnknownTargetStateDependencyOperations as y, WidgetMethodDefinition as yn, WidgetPropertiesOf as yr, BlueprintSemanticSlotsView as yt, BlueprintWidgetDiagnosticLocation as z, WidgetPropertiesSection as zn, SelfBlueprintWidgetNode as zt };
1472
+ export { RuntimeDiagnostic as $, WidgetStateValidateContext as $n, WidgetCatalog as $t, BlueprintNodeDiagnostic as A, WidgetPluginDonePhase as An, WidgetStateValueOf as Ar, ResolvedBlueprintWidgetNodeViewFor as At, DiagnosticBase as B, WidgetPluginValidateStructure as Bn, RuntimeWidgetFor as Bt, BlueprintDependencyDiagnosticLocation as C, WidgetMethodValidateArgsContext as Cn, WidgetPropertyKeyOf as Cr, BlueprintWidgetNodeBase as Ct, BlueprintDiagnostic as D, WidgetPluginConfigMetadata as Dn, WidgetSlotNameOf as Dr, ResolvedBlueprintWidgetNode as Dt, BlueprintDependencyTarget as E, WidgetPluginCapabilities as En, WidgetResolvedConfigOf as Er, InvalidWidgetSystemBlueprint as Et, BlueprintSourceDiagnostic as F, WidgetPluginPropertiesPhase as Fn, MAX_JSON_DEPTH as Fr, RuntimeProperty as Ft, JsonCompatibilityReason as G, WidgetRegisterDepsContext as Gn, WidgetLocation as Gt, DiagnosticPath as H, WidgetPropertiesSection as Hn, SelfBlueprintWidgetNodeView as Ht, BlueprintSourceDiagnosticLocation as I, WidgetPluginSlotsPhase as In, isJsonValue as Ir, RuntimePropertySurface as It, RelativeStructureDiagnosticLocation as J, WidgetSlotDefinitions as Jn, WidgetSourceFor as Jt, RelativePluginStructureDiagnosticInput as K, WidgetResolvedConfigContext as Kn, WidgetLocationView as Kt, BlueprintStructureDiagnostic as L, WidgetPluginStatePhase as Ln, RuntimeState as Lt, BlueprintPropertyDiagnosticLocation as M, WidgetPluginInterfacesPhase as Mn, JsonObject as Mr, RuntimeEventSurface as Mt, BlueprintSlotChildDiagnosticLocation as N, WidgetPluginMethodsPhase as Nn, JsonPrimitive as Nr, RuntimeMethod as Nt, BlueprintDiagnosticLocation as O, WidgetPluginConfigPhase as On, WidgetStateKeyOf as Or, ResolvedBlueprintWidgetNodeFor as Ot, BlueprintSlotDiagnosticLocation as P, WidgetPluginPhaseOrderViolation as Pn, JsonValue as Pr, RuntimeMethodSurface as Pt, RuntimeDependencyValueRejectedDiagnostic as Q, WidgetStateSection as Qn, CreateWidgetSystemOptions as Qt, BlueprintStructureDiagnosticLocation as R, WidgetPluginStructurePhase as Rn, RuntimeStateSurface as Rt, BlueprintDependencyDiagnostic as S, WidgetMethodExecuteContext as Sn, WidgetPropertiesOf as Sr, BlueprintWidgetNode as St, BlueprintDependencyReference as T, WidgetPlugin as Tn, WidgetRawConfigOf as Tr, CreateWidgetSystemRuntimeOptions as Tt, EMPTY_DIAGNOSTICS as U, WidgetPropertyComputeContext as Un, UnresolvedBlueprintWidgetNode as Ut, DiagnosticCollector as V, WidgetPluginValidateStructureContext as Vn, SelfBlueprintWidgetNode as Vt, JsonCompatibilityDiagnostic as W, WidgetPropertyDefinition as Wn, ValidWidgetSystemBlueprint as Wt, RelativeValueDiagnosticInput as X, WidgetStateDefaultContext as Xn, WidgetSystemBlueprintStatus as Xt, RelativeSystemStructureDiagnosticInput as Y, WidgetSlotValidateStructureContext as Yn, WidgetSystemBlueprint as Yt, RuntimeDependencyTargetFailedDiagnostic as Z, WidgetStateMemberDefinition as Zn, WidgetSystemRuntime as Zt, ToExecutedDeps as _, WidgetEventsSection as _n, WidgetMethodArgsOf as _r, BlueprintNodeConfigFields as _t, MaybeOptional as a, WidgetSystemValidateStructure as an, HasWidgetCapability as ar, RuntimeMethodDiagnostic as at, BlueprintConfigDiagnostic as b, WidgetMethodDefinition as bn, WidgetMethodReturnOf as br, BlueprintSemanticSlotsView as bt, PropertyGetDepExpression as c, AnyWidgetPlugin as cn, WidgetEventArgsOf as cr, RuntimePropertyDependencyDiagnostic as ct, SelfMethodDependencyOperations as d, WidgetConfigDefinition as dn, WidgetId as dr, RuntimeStateDiagnostic as dt, WidgetCatalogEntry as en, WidgetValueContract as er, RuntimeDiagnosticLocation as et, SelfPropertyDependencyOperations as f, WidgetConfigJsonSchema as fn, WidgetInterfaces as fr, RuntimeWidgetDiagnostic as ft, ToExecutedDep as g, WidgetEventEmitterContext as gn, WidgetMemberValueOf as gr, BlueprintCompileView as gt, StateSetDepExpression as h, WidgetEventEmitter as hn, WidgetMemberKeysOf as hr, WidgetSystemRuntimeReentrancyError as ht, EmptyRegisteredDeps as i, WidgetSystemConfigurationErrorCode as in, ExecutionResult as ir, RuntimeMethodDependencyDiagnostic as it, BlueprintNodeDiagnosticLocation as j, WidgetPluginEventsPhase as jn, JsonArray as jr, RuntimeEvent as jt, BlueprintMethodDiagnosticLocation as k, WidgetPluginDescriptionPhase as kn, WidgetStateOf as kr, ResolvedBlueprintWidgetNodeView as kt, RegisteredDeps as l, AnyWidgetPluginTuple as ln, WidgetEventKeyOf as lr, RuntimePropertyDiagnostic as lt, StateGetDepExpression as m, WidgetEventDefinition as mn, WidgetMemberKey as mr, WidgetSystemRuntimeDisposedError as mt, DependencyBuilder as n, WidgetSystem as nn, createWidgetValueContract as nr, RuntimeLevelDiagnosticLocation as nt, MethodInvokeDepExpression as o, WidgetSystemValidateStructureContext as on, NonEmptyReadonlyArray as or, RuntimeMethodResultDiagnostic as ot, SelfStateDependencyOperations as p, WidgetConfigValidateContext as pn, WidgetInterfacesViolationOf as pr, SourceAccessDiagnostic as pt, RelativeSlotStructureDiagnosticInput as q, WidgetSlotDefinition as qn, WidgetSource as qt, DependencyConsumer as r, WidgetSystemConfigurationError as rn, ExecutionFailure as rr, RuntimeMethodArgsDiagnostic as rt, OptionalizableDependencyTarget as s, createWidgetSystem as sn, WidgetCapabilityOf as sr, RuntimePrimitiveDiagnosticLocation as st, AnyDepExpression as t, WidgetPluginOf as tn, createWidgetPlugin as tr, RuntimeLevelDiagnostic as tt, SelfDependencyTarget as u, WIDGET_CONFIG_JSON_SCHEMA_DIALECT as un, WidgetEventsOf as ur, RuntimePropertyResultDiagnostic as ut, UnknownTargetDependencyOperations as v, WidgetInterfacesOf as vn, WidgetMethodKeyOf as vr, BlueprintRuntimeView as vt, BlueprintDependencyOperation as w, WidgetMethodsSection as wn, WidgetPropertyValueOf as wr, BlueprintWidgetNodeView as wt, BlueprintDefinitionDiagnostic as x, WidgetMethodEventEmitter as xn, WidgetMethodsOf as xr, BlueprintSourcePath as xt, UnknownTargetStateDependencyOperations as y, WidgetInterfacesViolation as yn, WidgetMethodOf as yr, BlueprintSemanticSlots as yt, BlueprintWidgetDiagnosticLocation as z, WidgetPluginTypeOf as zn, RuntimeWidget as zt };