@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.
@@ -1,4 +1,4 @@
1
- import { Jt as WidgetSystemBlueprint, T as BlueprintDependencyReference, Tn as WidgetPluginConfigMetadata, Tt as ResolvedBlueprintWidgetNode, Vt as UnresolvedBlueprintWidgetNode, Xt as WidgetSystemRuntime, bt as BlueprintWidgetNode, cn as AnyWidgetPluginTuple, dr as WidgetMemberKey, lt as RuntimePropertyDiagnostic, sn as AnyWidgetPlugin, tr as ExecutionResult } from "../dep-DKbvAjPb.mjs";
1
+ import { Dn as WidgetPluginConfigMetadata, Dt as ResolvedBlueprintWidgetNode, En as WidgetPluginCapabilities, St as BlueprintWidgetNode, T as BlueprintDependencyReference, Ut as UnresolvedBlueprintWidgetNode, Yt as WidgetSystemBlueprint, Zt as WidgetSystemRuntime, cn as AnyWidgetPlugin, ir as ExecutionResult, ln as AnyWidgetPluginTuple, lt as RuntimePropertyDiagnostic, mr as WidgetMemberKey, xt as BlueprintSourcePath } from "../dep-BXcdMm-M.mjs";
2
2
  //#region src/inspection/types.d.ts
3
3
  declare const inspectionNodeIdBrand: unique symbol;
4
4
  /**
@@ -26,7 +26,28 @@ interface PluginInspectionEventMember {
26
26
  readonly name: WidgetMemberKey;
27
27
  readonly description: string;
28
28
  }
29
+ interface PluginInspectionSlot {
30
+ readonly type: 'slot';
31
+ readonly name: WidgetMemberKey;
32
+ readonly description: string;
33
+ }
34
+ /**
35
+ * Everything passive one completed plugin declares, in one call: a superset of its `system.catalog`
36
+ * entry (`type`, `description`, config metadata, slot descriptions) plus capability presence and the
37
+ * State/Property/Event member facts.
38
+ */
29
39
  interface PluginInspection {
40
+ readonly type: string;
41
+ readonly description: string;
42
+ /** Authoritative capability presence (absent vs explicitly declared empty); same facts as `plugin.capabilities`. */
43
+ readonly capabilities: WidgetPluginCapabilities;
44
+ /** Passive config authoring metadata. Null means no config capability. */
45
+ readonly config: WidgetPluginConfigMetadata | null;
46
+ /**
47
+ * Slot descriptions in declaration order. Null means the Slots capability was not declared; an empty
48
+ * map means explicitly declared empty.
49
+ */
50
+ readonly slots: ReadonlyMap<WidgetMemberKey, PluginInspectionSlot> | null;
30
51
  /** Null means the State capability was not declared; an empty map means explicitly declared empty. */
31
52
  readonly state: ReadonlyMap<WidgetMemberKey, PluginInspectionStateMember> | null;
32
53
  /** Null means the Properties capability was not declared; an empty map means explicitly declared empty. */
@@ -112,6 +133,8 @@ interface BlueprintInspectionMethodMember {
112
133
  readonly name: WidgetMemberKey;
113
134
  /** Compiler-authoritative transitive write-effect fact. */
114
135
  readonly transitivelyWrites: boolean;
136
+ /** Compiler-authoritative transitive emit-effect fact: the Method declares an Event in `emits`, or invokes a Method that does. */
137
+ readonly transitivelyEmits: boolean;
115
138
  readonly dependencies: readonly BlueprintInspectionDependency[];
116
139
  }
117
140
  interface BlueprintInspectionNodeBase<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple> {
@@ -123,10 +146,19 @@ interface BlueprintInspectionNodeBase<Plugins extends AnyWidgetPluginTuple = Any
123
146
  readonly node: BlueprintWidgetNode<Plugins>;
124
147
  /** Best-effort recovered source topology (not a raw `slots` mirror). */
125
148
  readonly sourceSlots: readonly BlueprintInspectionSourceSlot[];
149
+ /**
150
+ * The structured `SourcePath` of this node's authored object within `blueprint.source`, computed by the
151
+ * compiler; identical to `blueprint.getSourcePath(node)`.
152
+ */
153
+ readonly sourcePath: BlueprintSourcePath;
126
154
  }
127
155
  interface UnresolvedBlueprintInspectionNode<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple> extends BlueprintInspectionNodeBase<Plugins> {
128
156
  readonly resolved: false;
129
157
  readonly node: UnresolvedBlueprintWidgetNode<Plugins>;
158
+ /** Best-effort identity hint: the authored `id` when it is a string, else `null`. */
159
+ readonly id: string | null;
160
+ /** Best-effort identity hint: the authored `type` when it is a string, else `null`. */
161
+ readonly type: string | null;
130
162
  }
131
163
  interface ResolvedBlueprintInspectionNode<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple> extends BlueprintInspectionNodeBase<Plugins> {
132
164
  readonly resolved: true;
@@ -180,7 +212,7 @@ type RuntimePropertyInspectionSnapshot<T> = {
180
212
  readonly status: 'never-evaluated';
181
213
  } | {
182
214
  readonly status: 'completed';
183
- readonly result: ExecutionResult<T | null, RuntimePropertyDiagnostic>;
215
+ readonly result: ExecutionResult<T, RuntimePropertyDiagnostic>;
184
216
  };
185
217
  interface RuntimePropertyInspection<T> extends InspectionObservable<RuntimePropertyInspectionSnapshot<T>> {}
186
218
  /**
@@ -264,4 +296,4 @@ declare function inspectPlugin(plugin: AnyWidgetPlugin): PluginInspection;
264
296
  */
265
297
  declare function inspectRuntime<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple>(runtime: WidgetSystemRuntime<Plugins>): RuntimeInspection<Plugins>;
266
298
  //#endregion
267
- export { type AbsentBlueprintInspectionDependency, type BlueprintInspection, type BlueprintInspectionCapabilities, type BlueprintInspectionDependency, type BlueprintInspectionDependencyBase, type BlueprintInspectionEvaluationMemberRef, type BlueprintInspectionEventMember, type BlueprintInspectionInvalidCycle, type BlueprintInspectionMemberRef, type BlueprintInspectionMethodMember, type BlueprintInspectionNode, type BlueprintInspectionNodeBase, type BlueprintInspectionPropertyMember, type BlueprintInspectionSemanticSlot, type BlueprintInspectionSourceSlot, type BlueprintInspectionStateMember, type InspectionNodeId, type InspectionObservable, type InvalidBlueprintInspectionDependency, type PluginInspection, type PluginInspectionEventMember, type PluginInspectionPropertyMember, type PluginInspectionStateMember, type ResolvedBlueprintInspectionDependency, type ResolvedBlueprintInspectionNode, type RuntimeEventInspection, type RuntimeInspection, type RuntimePropertyInspection, type RuntimePropertyInspectionSnapshot, type RuntimeStateInspection, type RuntimeStateInspectionSnapshot, type RuntimeWidgetInspection, type UnresolvedBlueprintInspectionNode, WidgetInspectionError, type WidgetInspectionErrorCode, inspectBlueprint, inspectPlugin, inspectRuntime };
299
+ export { type AbsentBlueprintInspectionDependency, type BlueprintInspection, type BlueprintInspectionCapabilities, type BlueprintInspectionDependency, type BlueprintInspectionDependencyBase, type BlueprintInspectionEvaluationMemberRef, type BlueprintInspectionEventMember, type BlueprintInspectionInvalidCycle, type BlueprintInspectionMemberRef, type BlueprintInspectionMethodMember, type BlueprintInspectionNode, type BlueprintInspectionNodeBase, type BlueprintInspectionPropertyMember, type BlueprintInspectionSemanticSlot, type BlueprintInspectionSourceSlot, type BlueprintInspectionStateMember, type InspectionNodeId, type InspectionObservable, type InvalidBlueprintInspectionDependency, type PluginInspection, type PluginInspectionEventMember, type PluginInspectionPropertyMember, type PluginInspectionSlot, type PluginInspectionStateMember, type ResolvedBlueprintInspectionDependency, type ResolvedBlueprintInspectionNode, type RuntimeEventInspection, type RuntimeInspection, type RuntimePropertyInspection, type RuntimePropertyInspectionSnapshot, type RuntimeStateInspection, type RuntimeStateInspectionSnapshot, type RuntimeWidgetInspection, type UnresolvedBlueprintInspectionNode, WidgetInspectionError, type WidgetInspectionErrorCode, inspectBlueprint, inspectPlugin, inspectRuntime };
@@ -1,4 +1,4 @@
1
- import { c as readWidgetPluginDefinition, l as createReadonlyMap, n as readRuntimeInternals, s as isCoreWidgetPlugin, t as isCoreRuntime } from "../internals-L391flXY.mjs";
1
+ import { c as readWidgetPluginDefinition, l as createReadonlyMap, n as readRuntimeInternals, s as isCoreWidgetPlugin, t as isCoreRuntime } from "../internals-CVKUQDIN.mjs";
2
2
  import { a as readCompiledBlueprint, i as isCoreBlueprint, r as isCompiledDependency } from "../contract-CRpMqCY2.mjs";
3
3
  //#region src/inspection/errors.ts
4
4
  /**
@@ -145,6 +145,7 @@ function buildMethodMembers(compiledNode) {
145
145
  type: "method",
146
146
  name,
147
147
  transitivelyWrites: member.transitivelyWrites,
148
+ transitivelyEmits: member.transitivelyEmits,
148
149
  dependencies: flattenDependencies(member.deps)
149
150
  }));
150
151
  return Object.freeze(result);
@@ -166,12 +167,16 @@ function buildNode(compiledNode, nodeId) {
166
167
  nodeId,
167
168
  node: compiledNode.publicNode,
168
169
  sourceSlots,
169
- resolved: false
170
+ sourcePath: compiledNode.sourcePath,
171
+ resolved: false,
172
+ id: compiledNode.id,
173
+ type: compiledNode.type
170
174
  });
171
175
  return Object.freeze({
172
176
  nodeId,
173
177
  node: compiledNode.publicNode,
174
178
  sourceSlots,
179
+ sourcePath: compiledNode.sourcePath,
175
180
  resolved: true,
176
181
  capabilities: buildCapabilities(compiledNode),
177
182
  config: compiledNode.plugin.config,
@@ -241,6 +246,17 @@ function inspectBlueprint(blueprint) {
241
246
  //#endregion
242
247
  //#region src/inspection/plugin.ts
243
248
  const inspectionCache = /* @__PURE__ */ new WeakMap();
249
+ function buildSlots(plugin) {
250
+ const definitions = readWidgetPluginDefinition(plugin).slots;
251
+ if (definitions === null) return null;
252
+ const slots = [];
253
+ for (const [name, definition] of definitions) slots.push([name, Object.freeze({
254
+ type: "slot",
255
+ name,
256
+ description: definition.description
257
+ })]);
258
+ return createReadonlyMap(slots);
259
+ }
244
260
  function buildStateMembers(plugin) {
245
261
  const definitions = readWidgetPluginDefinition(plugin).state;
246
262
  if (definitions === null) return null;
@@ -282,6 +298,11 @@ function inspectPlugin(plugin) {
282
298
  const existing = inspectionCache.get(plugin);
283
299
  if (existing !== void 0) return existing;
284
300
  const inspection = Object.freeze({
301
+ type: plugin.type,
302
+ description: plugin.description,
303
+ capabilities: plugin.capabilities,
304
+ config: plugin.config,
305
+ slots: buildSlots(plugin),
285
306
  state: buildStateMembers(plugin),
286
307
  properties: buildPropertyMembers(plugin),
287
308
  events: buildEventMembers(plugin)
@@ -1,4 +1,4 @@
1
- import { Lt as RuntimeWidget, Xt as WidgetSystemRuntime, cn as AnyWidgetPluginTuple, dr as WidgetMemberKey } from "../dep-DKbvAjPb.mjs";
1
+ import { Zt as WidgetSystemRuntime, ln as AnyWidgetPluginTuple, mr as WidgetMemberKey, zt as RuntimeWidget } from "../dep-BXcdMm-M.mjs";
2
2
  //#region src/integration/index.d.ts
3
3
  type WidgetIntegrationErrorCode = 'runtime-widget-mismatch' | 'foreign-runtime';
4
4
  declare class WidgetIntegrationError extends Error {
@@ -6,7 +6,13 @@ declare class WidgetIntegrationError extends Error {
6
6
  readonly name = "WidgetIntegrationError";
7
7
  constructor(code: WidgetIntegrationErrorCode, message?: string);
8
8
  }
9
+ /**
10
+ * Passive provenance assertion: throws `WidgetIntegrationError('foreign-runtime')` unless `runtime` was
11
+ * produced by this loaded core instance. It reads no Runtime state and acquires no emit authority, so a
12
+ * renderer adapter can verify at mount that the app and the adapter share one core copy.
13
+ */
14
+ declare function assertCoreRuntime(runtime: unknown): void;
9
15
  type WidgetIntegrationEventEmitter = Readonly<Record<WidgetMemberKey, (...args: readonly unknown[]) => void>>;
10
16
  declare function getWidgetEventEmitter<Plugins extends AnyWidgetPluginTuple>(runtime: WidgetSystemRuntime<Plugins>, widget: RuntimeWidget<Plugins>): WidgetIntegrationEventEmitter | null;
11
17
  //#endregion
12
- export { WidgetIntegrationError, WidgetIntegrationErrorCode, WidgetIntegrationEventEmitter, getWidgetEventEmitter };
18
+ export { WidgetIntegrationError, WidgetIntegrationErrorCode, WidgetIntegrationEventEmitter, assertCoreRuntime, getWidgetEventEmitter };
@@ -1,5 +1,5 @@
1
- import { t as buildEventEmitter } from "../event-BMif_vRJ.mjs";
2
- import { c as readWidgetPluginDefinition, n as readRuntimeInternals, t as isCoreRuntime } from "../internals-L391flXY.mjs";
1
+ import { t as buildEventEmitter } from "../event-Bk-mkL1E.mjs";
2
+ import { c as readWidgetPluginDefinition, n as readRuntimeInternals, t as isCoreRuntime } from "../internals-CVKUQDIN.mjs";
3
3
  //#region src/integration/index.ts
4
4
  var WidgetIntegrationError = class extends Error {
5
5
  code;
@@ -9,6 +9,14 @@ var WidgetIntegrationError = class extends Error {
9
9
  this.code = code;
10
10
  }
11
11
  };
12
+ /**
13
+ * Passive provenance assertion: throws `WidgetIntegrationError('foreign-runtime')` unless `runtime` was
14
+ * produced by this loaded core instance. It reads no Runtime state and acquires no emit authority, so a
15
+ * renderer adapter can verify at mount that the app and the adapter share one core copy.
16
+ */
17
+ function assertCoreRuntime(runtime) {
18
+ if (!isCoreRuntime(runtime)) throw new WidgetIntegrationError("foreign-runtime");
19
+ }
12
20
  function getWidgetEventEmitter(runtime, widget) {
13
21
  if (!isCoreRuntime(runtime)) throw new WidgetIntegrationError("foreign-runtime");
14
22
  const internals = readRuntimeInternals(runtime);
@@ -23,4 +31,4 @@ function getWidgetEventEmitter(runtime, widget) {
23
31
  return buildEventEmitter(entry.events);
24
32
  }
25
33
  //#endregion
26
- export { WidgetIntegrationError, getWidgetEventEmitter };
34
+ export { WidgetIntegrationError, assertCoreRuntime, getWidgetEventEmitter };
@@ -0,0 +1,388 @@
1
+ //#region src/readonly-map.ts
2
+ /** Creates a map-shaped, runtime immutable projection without exposing mutating Map methods. */
3
+ function createReadonlyMap(entries) {
4
+ const map = new Map(entries);
5
+ const result = {
6
+ get size() {
7
+ return map.size;
8
+ },
9
+ get(key) {
10
+ return map.get(key);
11
+ },
12
+ has(key) {
13
+ return map.has(key);
14
+ },
15
+ keys() {
16
+ return map.keys();
17
+ },
18
+ values() {
19
+ return map.values();
20
+ },
21
+ entries() {
22
+ return map.entries();
23
+ },
24
+ forEach(callbackfn, thisArg) {
25
+ map.forEach((value, key) => callbackfn.call(thisArg, value, key, result));
26
+ },
27
+ [Symbol.iterator]() {
28
+ return map[Symbol.iterator]();
29
+ }
30
+ };
31
+ return Object.freeze(result);
32
+ }
33
+ //#endregion
34
+ //#region src/plugin.ts
35
+ /**
36
+ * Framework-private brand carrying the plugin's phantom interfaces and its erased definition record.
37
+ */
38
+ const widgetPluginBrand = Symbol("@deviltea/widget-core:widget-plugin");
39
+ /**
40
+ * Declares a stable semantic value-contract id while retaining the associated TypeScript value type for
41
+ * Plugin-author checking. Core does not interpret, register, validate, or schema-check contract ids.
42
+ */
43
+ function createWidgetValueContract(id) {
44
+ return Object.freeze({ id });
45
+ }
46
+ const WIDGET_CONFIG_JSON_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";
47
+ /**
48
+ * Provenance probe: true only for plugins completed by this loaded module instance. A plugin from
49
+ * another module instance (its brand is a different Symbol) or a structural look-alike is foreign.
50
+ * Capability separation, not a security sandbox.
51
+ */
52
+ function isCoreWidgetPlugin(value) {
53
+ if (typeof value !== "object" || value === null) return false;
54
+ const brand = value[widgetPluginBrand];
55
+ return typeof brand === "object" && brand !== null && typeof brand.definition === "object" && brand.definition !== null;
56
+ }
57
+ /**
58
+ * Reads the erased definition record of a plugin.
59
+ */
60
+ function readWidgetPluginDefinition(plugin) {
61
+ return plugin[widgetPluginBrand].definition;
62
+ }
63
+ /**
64
+ * The callbacks and description fields each section's definition type requires, plus its optional
65
+ * fields. Untyped (JavaScript / dynamically loaded) plugins are checked against these at registration,
66
+ * so a malformed plugin fails before `done()` returns instead of at its first interaction.
67
+ */
68
+ const definitionFieldRules = {
69
+ config: [
70
+ [
71
+ "description",
72
+ "string",
73
+ true
74
+ ],
75
+ [
76
+ "validate",
77
+ "function",
78
+ true
79
+ ],
80
+ [
81
+ "resolve",
82
+ "function",
83
+ true
84
+ ],
85
+ [
86
+ "schema",
87
+ "schema",
88
+ false
89
+ ]
90
+ ],
91
+ slots: [[
92
+ "description",
93
+ "string",
94
+ true
95
+ ], [
96
+ "validateStructure",
97
+ "function",
98
+ false
99
+ ]],
100
+ state: [
101
+ [
102
+ "validate",
103
+ "function",
104
+ true
105
+ ],
106
+ [
107
+ "default",
108
+ "function",
109
+ false
110
+ ],
111
+ [
112
+ "authorWritable",
113
+ "boolean",
114
+ false
115
+ ]
116
+ ],
117
+ properties: [
118
+ [
119
+ "compute",
120
+ "function",
121
+ true
122
+ ],
123
+ [
124
+ "registerDeps",
125
+ "function",
126
+ false
127
+ ],
128
+ [
129
+ "valueContract",
130
+ "value-contract",
131
+ false
132
+ ]
133
+ ],
134
+ methods: [
135
+ [
136
+ "validateArgs",
137
+ "function",
138
+ true
139
+ ],
140
+ [
141
+ "execute",
142
+ "function",
143
+ true
144
+ ],
145
+ [
146
+ "registerDeps",
147
+ "function",
148
+ false
149
+ ]
150
+ ],
151
+ events: [[
152
+ "description",
153
+ "string",
154
+ true
155
+ ]]
156
+ };
157
+ const fieldKindExpectations = {
158
+ "function": "a function",
159
+ "string": "a string",
160
+ "boolean": "a boolean",
161
+ "schema": "a JSON Schema (a boolean or an object)",
162
+ "value-contract": "a value contract created by createWidgetValueContract()"
163
+ };
164
+ /** A dense array of strings (a hole or a non-string entry is not a name). */
165
+ function isNameArray(value) {
166
+ if (!Array.isArray(value)) return false;
167
+ for (let index = 0; index < value.length; index++) if (!(index in value) || typeof value[index] !== "string") return false;
168
+ return true;
169
+ }
170
+ function matchesFieldKind(value, kind) {
171
+ switch (kind) {
172
+ case "function": return typeof value === "function";
173
+ case "string": return typeof value === "string";
174
+ case "boolean": return typeof value === "boolean";
175
+ case "schema": return value === null || typeof value === "boolean" || typeof value === "object" && !Array.isArray(value);
176
+ case "value-contract": return typeof value === "object" && value !== null && typeof value.id === "string";
177
+ }
178
+ }
179
+ function describeValue(value) {
180
+ return value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
181
+ }
182
+ function memberSubject(section, key) {
183
+ return `member "${key}" of section "${section}"`;
184
+ }
185
+ /** Plugin contract violations throw uncoded `TypeError`s. */
186
+ function pluginContractViolation(pluginType, subject, problem) {
187
+ return /* @__PURE__ */ new TypeError(`Widget plugin "${pluginType}": ${subject} ${problem}. This is a plugin implementation bug.`);
188
+ }
189
+ /**
190
+ * Captures one definition by value (shallow copy, frozen), the same way for config, slots and members,
191
+ * after checking that it is an object carrying the fields its section requires. Optional fields are
192
+ * type-checked only when present (not `undefined`).
193
+ */
194
+ function captureDefinition(pluginType, section, subject, definition) {
195
+ if (typeof definition !== "object" || definition === null) throw pluginContractViolation(pluginType, subject, `must be declared with a definition object, got ${describeValue(definition)}`);
196
+ const captured = Object.freeze({ ...definition });
197
+ for (const [field, kind, required] of definitionFieldRules[section]) {
198
+ const value = captured[field];
199
+ if (value === void 0) {
200
+ if (required) throw pluginContractViolation(pluginType, subject, `is missing the required "${field}" field (expected ${fieldKindExpectations[kind]})`);
201
+ continue;
202
+ }
203
+ if (!matchesFieldKind(value, kind)) throw pluginContractViolation(pluginType, subject, `has an invalid "${field}" field (expected ${fieldKindExpectations[kind]}, got ${describeValue(value)})`);
204
+ }
205
+ if (section === "methods") {
206
+ const emits = captured.emits;
207
+ if (emits !== void 0) {
208
+ if (!isNameArray(emits)) throw pluginContractViolation(pluginType, subject, `has an invalid "emits" field (expected an array of Event names, got ${describeValue(emits)})`);
209
+ return Object.freeze({
210
+ ...captured,
211
+ emits: Object.freeze([...emits])
212
+ });
213
+ }
214
+ }
215
+ return captured;
216
+ }
217
+ /**
218
+ * Runs one section build callback against the section keyed-chain object, registering its members into
219
+ * `members` in declaration order.
220
+ *
221
+ * Declared member keys exist only at the type level, so every string member access resolves to a
222
+ * registrar; the returned chain object is the same object by identity. A registrar accepts only a
223
+ * definition object, which it validates and captures by value, so probing the section
224
+ * (`JSON.stringify`, string coercion, thenable detection) registers nothing. The section is sealed once
225
+ * the build callback returns or throws: a later registrar call (from a retained section) throws and
226
+ * changes nothing.
227
+ */
228
+ function buildSection(pluginType, sectionName, members, build, onDeclaresEmits) {
229
+ let sealed = false;
230
+ const section = new Proxy({}, { get(_target, key) {
231
+ if (typeof key !== "string") return void 0;
232
+ return (definition) => {
233
+ const subject = memberSubject(sectionName, key);
234
+ if (sealed) throw pluginContractViolation(pluginType, subject, "was declared after the section's build callback returned");
235
+ const captured = captureDefinition(pluginType, sectionName, subject, definition);
236
+ members.set(key, captured);
237
+ if (onDeclaresEmits !== void 0 && captured.emits !== void 0) onDeclaresEmits(key);
238
+ return section;
239
+ };
240
+ } });
241
+ try {
242
+ build(section);
243
+ } finally {
244
+ sealed = true;
245
+ }
246
+ }
247
+ /**
248
+ * Starts the plugin builder for one plugin `type`.
249
+ *
250
+ * Phase order is `description -> interfaces -> config? -> slots? -> structure? -> state? -> properties? -> methods? -> events? -> done()`;
251
+ * a capability phase exists only when its capability is declared, while the optional `structure` phase
252
+ * (the plugin-level structure validator) is available to every plugin. Calling a phase out of order (or
253
+ * repeating it) fails type-checking with an order-specific diagnostic; the runtime builder itself is
254
+ * order-agnostic.
255
+ */
256
+ function createWidgetPlugin(type) {
257
+ const draft = {
258
+ description: "",
259
+ config: null,
260
+ slots: null,
261
+ validateStructure: null,
262
+ state: null,
263
+ properties: null,
264
+ methods: null,
265
+ emittingMethods: null,
266
+ events: null
267
+ };
268
+ const builder = {
269
+ description(description) {
270
+ draft.description = description;
271
+ return builder;
272
+ },
273
+ interfaces: () => builder,
274
+ config(definition) {
275
+ const captured = captureDefinition(type, "config", "section \"config\"", definition);
276
+ draft.config = Object.freeze({
277
+ ...captured,
278
+ schema: captured.schema ?? null
279
+ });
280
+ return builder;
281
+ },
282
+ slots(definitions, ...removedArguments) {
283
+ if (typeof definitions !== "object" || definitions === null) throw pluginContractViolation(type, "section \"slots\"", `must be declared with a slot definitions object, got ${describeValue(definitions)}`);
284
+ if (removedArguments.some((argument) => argument !== void 0)) throw pluginContractViolation(type, "section \"slots\"", "takes only the slot definitions; declare a plugin-level validateStructure with \".structure()\"");
285
+ draft.slots = new Map(Object.entries(definitions).map(([name, slot]) => [name, captureDefinition(type, "slots", memberSubject("slots", name), slot)]));
286
+ return builder;
287
+ },
288
+ structure(validateStructure) {
289
+ if (typeof validateStructure !== "function") throw pluginContractViolation(type, "phase \"structure\"", `must be given a validateStructure function, got ${describeValue(validateStructure)}`);
290
+ draft.validateStructure = validateStructure;
291
+ return builder;
292
+ },
293
+ state(build) {
294
+ const members = /* @__PURE__ */ new Map();
295
+ draft.state = members;
296
+ buildSection(type, "state", members, build);
297
+ return builder;
298
+ },
299
+ properties(build) {
300
+ const members = /* @__PURE__ */ new Map();
301
+ draft.properties = members;
302
+ buildSection(type, "properties", members, build);
303
+ return builder;
304
+ },
305
+ methods(build) {
306
+ const members = /* @__PURE__ */ new Map();
307
+ draft.methods = members;
308
+ draft.emittingMethods = null;
309
+ buildSection(type, "methods", members, build, (key) => {
310
+ (draft.emittingMethods ??= []).push(key);
311
+ });
312
+ return builder;
313
+ },
314
+ events(build) {
315
+ const members = /* @__PURE__ */ new Map();
316
+ draft.events = members;
317
+ buildSection(type, "events", members, build);
318
+ return builder;
319
+ },
320
+ done() {
321
+ if (draft.emittingMethods !== null) for (const name of draft.emittingMethods) {
322
+ const emits = draft.methods?.get(name)?.emits;
323
+ if (emits === void 0) continue;
324
+ for (let index = 0; index < emits.length; index++) {
325
+ const event = emits[index];
326
+ if (draft.events === null || !draft.events.has(event)) throw pluginContractViolation(type, memberSubject("methods", name), `has an invalid "emits" field (Event "${event}" is not declared in section "events")`);
327
+ if (emits.indexOf(event) !== index) throw pluginContractViolation(type, memberSubject("methods", name), `has an invalid "emits" field (Event "${event}" is listed more than once)`);
328
+ }
329
+ }
330
+ const definition = Object.freeze({
331
+ type,
332
+ description: draft.description,
333
+ config: draft.config,
334
+ slots: draft.slots,
335
+ validateStructure: draft.validateStructure,
336
+ state: draft.state,
337
+ properties: draft.properties,
338
+ methods: draft.methods,
339
+ events: draft.events
340
+ });
341
+ const capabilities = Object.freeze({
342
+ config: definition.config !== null,
343
+ slots: definition.slots !== null,
344
+ state: definition.state !== null,
345
+ properties: definition.properties !== null,
346
+ methods: definition.methods !== null,
347
+ events: definition.events !== null
348
+ });
349
+ const config = definition.config === null ? null : Object.freeze({
350
+ description: definition.config.description,
351
+ schema: definition.config.schema
352
+ });
353
+ const descriptions = Object.freeze({
354
+ config: config?.description ?? null,
355
+ slots: definition.slots === null ? null : createReadonlyMap([...definition.slots].map(([key, slot]) => [key, slot.description]))
356
+ });
357
+ return Object.freeze({
358
+ type,
359
+ description: draft.description,
360
+ capabilities,
361
+ config,
362
+ descriptions,
363
+ [widgetPluginBrand]: Object.freeze({ definition })
364
+ });
365
+ }
366
+ };
367
+ return builder;
368
+ }
369
+ //#endregion
370
+ //#region src/runtime/internals.ts
371
+ const runtimeInternals = Symbol("@deviltea/widget-core:runtime-internals");
372
+ /**
373
+ * Provenance probe: true only for Runtimes produced by this loaded module instance.
374
+ */
375
+ function isCoreRuntime(value) {
376
+ if (typeof value !== "object" || value === null) return false;
377
+ return value[runtimeInternals] !== void 0;
378
+ }
379
+ /**
380
+ * Reads the internals carried by a Runtime produced by `createWidgetSystemRuntime`.
381
+ */
382
+ function readRuntimeInternals(runtime) {
383
+ const internals = runtime[runtimeInternals];
384
+ if (internals === void 0) throw new Error("The runtime was not produced by this widget core build.");
385
+ return internals;
386
+ }
387
+ //#endregion
388
+ export { createWidgetPlugin as a, readWidgetPluginDefinition as c, WIDGET_CONFIG_JSON_SCHEMA_DIALECT as i, createReadonlyMap as l, readRuntimeInternals as n, createWidgetValueContract as o, runtimeInternals as r, isCoreWidgetPlugin as s, isCoreRuntime as t };
package/package.json CHANGED
@@ -4,7 +4,7 @@
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
7
- "version": "0.0.6",
7
+ "version": "0.1.0",
8
8
  "author": "DevilTea <ch19980814@gmail.com>",
9
9
  "license": "MIT",
10
10
  "homepage": "https://github.com/DevilTea/widget/tree/main/packages/core#readme",
@@ -24,6 +24,7 @@
24
24
  "runtime",
25
25
  "signals"
26
26
  ],
27
+ "sideEffects": false,
27
28
  "exports": {
28
29
  ".": {
29
30
  "types": "./dist/index.d.mts",
@@ -45,7 +46,7 @@
45
46
  "dist"
46
47
  ],
47
48
  "engines": {
48
- "node": "^22.14.0 || ^24.0.0"
49
+ "node": ">=22.14.0"
49
50
  },
50
51
  "dependencies": {
51
52
  "alien-signals": "3.2.1",