@deviltea/widget-inspector 0.0.4 → 0.1.1

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,26 +1,57 @@
1
1
  //#region src/validation.ts
2
2
  const BLUEPRINT_METADATA_PROTOCOL_MINOR = 2;
3
+ /** `authorWritable`, `valueContractId` and `transitivelyEmits` were added to the member DTOs in protocol 0.4. */
4
+ const MEMBER_METADATA_PROTOCOL_MINOR = 4;
3
5
  function isRecord$1(value) {
4
6
  return typeof value === "object" && value !== null && !Array.isArray(value);
5
7
  }
6
- function isJsonValue(value, seen = /* @__PURE__ */ new Set()) {
7
- if (value === null || typeof value === "string" || typeof value === "boolean") return true;
8
- if (typeof value === "number") return Number.isFinite(value);
9
- if (Array.isArray(value)) {
10
- if (seen.has(value)) return false;
11
- seen.add(value);
12
- const valid = value.every((item) => isJsonValue(item, seen));
13
- seen.delete(value);
14
- return valid;
8
+ /**
9
+ * Iterative so that peer-controlled nesting depth can never overflow the call stack; `ancestors` still
10
+ * rejects a cyclic graph (a custom transport may hand over objects by reference). Structured clone keeps
11
+ * shared references, so each distinct object is validated once (`verified`): the walk is linear in the
12
+ * number of distinct objects, not in the number of paths to them.
13
+ */
14
+ function isJsonValue(value) {
15
+ const ancestors = /* @__PURE__ */ new Set();
16
+ const verified = /* @__PURE__ */ new Set();
17
+ const stack = [{
18
+ value,
19
+ exit: false
20
+ }];
21
+ while (stack.length > 0) {
22
+ const frame = stack.pop();
23
+ if (frame.exit) {
24
+ ancestors.delete(frame.value);
25
+ verified.add(frame.value);
26
+ continue;
27
+ }
28
+ const current = frame.value;
29
+ if (current === null || typeof current === "string" || typeof current === "boolean") continue;
30
+ if (typeof current === "number") {
31
+ if (!Number.isFinite(current)) return false;
32
+ continue;
33
+ }
34
+ if (verified.has(current)) continue;
35
+ let children;
36
+ if (Array.isArray(current)) children = current;
37
+ else {
38
+ if (!isRecord$1(current)) return false;
39
+ const prototype = Object.getPrototypeOf(current);
40
+ if (prototype !== Object.prototype && prototype !== null) return false;
41
+ children = Object.values(current);
42
+ }
43
+ if (ancestors.has(current)) return false;
44
+ ancestors.add(current);
45
+ stack.push({
46
+ value: current,
47
+ exit: true
48
+ });
49
+ for (const child of children) stack.push({
50
+ value: child,
51
+ exit: false
52
+ });
15
53
  }
16
- if (!isRecord$1(value)) return false;
17
- const prototype = Object.getPrototypeOf(value);
18
- if (prototype !== Object.prototype && prototype !== null) return false;
19
- if (seen.has(value)) return false;
20
- seen.add(value);
21
- const valid = Object.values(value).every((item) => isJsonValue(item, seen));
22
- seen.delete(value);
23
- return valid;
54
+ return true;
24
55
  }
25
56
  function isConfigMetadata(value) {
26
57
  return isRecord$1(value) && typeof value.description === "string" && (value.schema === null || typeof value.schema === "boolean" || isRecord$1(value.schema) && isJsonValue(value.schema));
@@ -58,6 +89,7 @@ function readArrayIndex(value, index) {
58
89
  }
59
90
  function isInspectableValue(value) {
60
91
  const ancestors = /* @__PURE__ */ new Set();
92
+ const verified = /* @__PURE__ */ new Set();
61
93
  const stack = [{
62
94
  kind: "value",
63
95
  value
@@ -67,6 +99,7 @@ function isInspectableValue(value) {
67
99
  if (frame.kind === "array") {
68
100
  if (frame.index >= frame.length) {
69
101
  ancestors.delete(frame.value);
102
+ verified.add(frame.value);
70
103
  continue;
71
104
  }
72
105
  const present = hasArrayIndex(frame.items, frame.index);
@@ -87,6 +120,7 @@ function isInspectableValue(value) {
87
120
  if (frame.kind === "object") {
88
121
  if (frame.index >= frame.length) {
89
122
  ancestors.delete(frame.value);
123
+ verified.add(frame.value);
90
124
  continue;
91
125
  }
92
126
  const present = hasArrayIndex(frame.entries, frame.index);
@@ -99,7 +133,7 @@ function isInspectableValue(value) {
99
133
  const entryResult = readArrayIndex(frame.entries, frame.index);
100
134
  if (!entryResult.ok) return false;
101
135
  const entry = entryResult.value;
102
- if (!isRecord$1(entry) || typeof entry.key !== "string") return false;
136
+ if (!isRecord$1(entry) || typeof entry.key !== "string" || entry.keyTruncated !== void 0 && typeof entry.keyTruncated !== "boolean") return false;
103
137
  stack.push({
104
138
  kind: "value",
105
139
  value: entry.value
@@ -107,6 +141,7 @@ function isInspectableValue(value) {
107
141
  continue;
108
142
  }
109
143
  const candidate = frame.value;
144
+ if (typeof candidate === "object" && candidate !== null && verified.has(candidate)) continue;
110
145
  if (!isRecord$1(candidate) || typeof candidate.type !== "string") return false;
111
146
  switch (candidate.type) {
112
147
  case "null":
@@ -207,22 +242,22 @@ function isDiagnosticLocation(value) {
207
242
  function isDiagnostic(value) {
208
243
  return isRecord$1(value) && typeof value.code === "string" && typeof value.message === "string" && isDiagnosticLocation(value.location) && (value.related === void 0 || Array.isArray(value.related) && value.related.every(isDiagnosticLocation)) && (value.path === void 0 || isPath(value.path)) && (value.reason === void 0 || typeof value.reason === "string") && (value.dependency === void 0 || isDependencyReference(value.dependency));
209
244
  }
210
- function isStateMember(value) {
211
- return isRecord$1(value) && value.type === "state" && typeof value.name === "string";
245
+ function isStateMember(value, protocolMinor) {
246
+ return isRecord$1(value) && value.type === "state" && typeof value.name === "string" && (protocolMinor < MEMBER_METADATA_PROTOCOL_MINOR ? value.authorWritable === void 0 || typeof value.authorWritable === "boolean" : typeof value.authorWritable === "boolean");
212
247
  }
213
- function isPropertyMember(value) {
214
- return isRecord$1(value) && value.type === "property" && typeof value.name === "string" && Array.isArray(value.dependencies) && value.dependencies.every(isDependency);
248
+ function isPropertyMember(value, protocolMinor) {
249
+ return isRecord$1(value) && value.type === "property" && typeof value.name === "string" && (protocolMinor < MEMBER_METADATA_PROTOCOL_MINOR ? value.valueContractId === void 0 || value.valueContractId === null || typeof value.valueContractId === "string" : value.valueContractId === null || typeof value.valueContractId === "string") && Array.isArray(value.dependencies) && value.dependencies.every(isDependency);
215
250
  }
216
251
  function isEventMember(value) {
217
252
  return isRecord$1(value) && value.type === "event" && typeof value.name === "string" && typeof value.description === "string";
218
253
  }
219
- function isMethodMember(value) {
220
- return isRecord$1(value) && value.type === "method" && typeof value.name === "string" && typeof value.transitivelyWrites === "boolean" && Array.isArray(value.dependencies) && value.dependencies.every(isDependency);
254
+ function isMethodMember(value, protocolMinor) {
255
+ return isRecord$1(value) && value.type === "method" && typeof value.name === "string" && typeof value.transitivelyWrites === "boolean" && (protocolMinor < MEMBER_METADATA_PROTOCOL_MINOR ? value.transitivelyEmits === void 0 || typeof value.transitivelyEmits === "boolean" : typeof value.transitivelyEmits === "boolean") && Array.isArray(value.dependencies) && value.dependencies.every(isDependency);
221
256
  }
222
257
  function isBlueprintNode(value, protocolMinor = BLUEPRINT_METADATA_PROTOCOL_MINOR) {
223
258
  if (!isRecord$1(value) || !isNodeId(value.nodeId) || typeof value.resolved !== "boolean" || !Array.isArray(value.sourceSlots) || !value.sourceSlots.every(isSlot) || !Array.isArray(value.diagnostics) || !value.diagnostics.every(isDiagnostic)) return false;
224
259
  if (!value.resolved) return true;
225
- return typeof value.widgetId === "string" && typeof value.widgetType === "string" && isBlueprintCapabilities(value.capabilities, protocolMinor) && (protocolMinor < BLUEPRINT_METADATA_PROTOCOL_MINOR ? value.config === void 0 || value.config === null || isConfigMetadata(value.config) : value.config === null || isConfigMetadata(value.config)) && Array.isArray(value.semanticSlots) && value.semanticSlots.every(isSlot) && Array.isArray(value.state) && value.state.every(isStateMember) && Array.isArray(value.properties) && value.properties.every(isPropertyMember) && Array.isArray(value.methods) && value.methods.every(isMethodMember) && (protocolMinor < BLUEPRINT_METADATA_PROTOCOL_MINOR ? value.events === void 0 || Array.isArray(value.events) && value.events.every(isEventMember) : Array.isArray(value.events) && value.events.every(isEventMember));
260
+ return typeof value.widgetId === "string" && typeof value.widgetType === "string" && isBlueprintCapabilities(value.capabilities, protocolMinor) && (protocolMinor < BLUEPRINT_METADATA_PROTOCOL_MINOR ? value.config === void 0 || value.config === null || isConfigMetadata(value.config) : value.config === null || isConfigMetadata(value.config)) && Array.isArray(value.semanticSlots) && value.semanticSlots.every(isSlot) && Array.isArray(value.state) && value.state.every((member) => isStateMember(member, protocolMinor)) && Array.isArray(value.properties) && value.properties.every((member) => isPropertyMember(member, protocolMinor)) && Array.isArray(value.methods) && value.methods.every((member) => isMethodMember(member, protocolMinor)) && (protocolMinor < BLUEPRINT_METADATA_PROTOCOL_MINOR ? value.events === void 0 || Array.isArray(value.events) && value.events.every(isEventMember) : Array.isArray(value.events) && value.events.every(isEventMember));
226
261
  }
227
262
  function isEvaluationCycle(value) {
228
263
  return isRecord$1(value) && Array.isArray(value.members) && value.members.every((item) => isRecord$1(item) && isNodeId(item.nodeId) && isRecord$1(item.member) && (item.member.type === "property" || item.member.type === "method") && typeof item.member.name === "string");
@@ -257,14 +292,11 @@ function isRuntimeMemberSnapshot$1(value) {
257
292
  //#region src/protocol.ts
258
293
  const INSPECTOR_PROTOCOL_VERSION = Object.freeze({
259
294
  major: 0,
260
- minor: 3
295
+ minor: 4
261
296
  });
262
297
  function isRecord(value) {
263
298
  return typeof value === "object" && value !== null && !Array.isArray(value);
264
299
  }
265
- function hasOnlyEmptyRecord(value) {
266
- return isRecord(value) && Object.keys(value).length === 0;
267
- }
268
300
  function isProtocolVersion(value) {
269
301
  return isRecord(value) && Number.isInteger(value.major) && typeof value.major === "number" && value.major >= 0 && Number.isInteger(value.minor) && typeof value.minor === "number" && value.minor >= 0;
270
302
  }
@@ -283,7 +315,7 @@ function isInspectorRequestParams(method, value) {
283
315
  case "runtime.list":
284
316
  case "inspect.enable":
285
317
  case "inspect.disable":
286
- case "highlight.clear": return hasOnlyEmptyRecord(value);
318
+ case "highlight.clear": return isRecord(value);
287
319
  case "blueprint.getSnapshot": return isRecord(value) && typeof value.runtimeId === "string";
288
320
  case "runtime.getWidgetSnapshot":
289
321
  case "geometry.resolve":
@@ -295,12 +327,50 @@ function isInspectorRequestParams(method, value) {
295
327
  case "runtime.unsubscribeEvent": return isRecord(value) && typeof value.subscriptionId === "string";
296
328
  }
297
329
  }
330
+ /**
331
+ * Classifies an incoming value as a request, or names why it is not one: `invalid-message` for an
332
+ * envelope that is not a request at all, `unknown-method` for a well-formed envelope naming a method this
333
+ * protocol does not define, and `invalid-params` for a known method whose params do not validate.
334
+ */
335
+ function classifyInspectorRequest(value) {
336
+ if (!isRecord(value) || value.kind !== "request") return {
337
+ ok: false,
338
+ requestId: null,
339
+ protocol: null,
340
+ code: "invalid-message"
341
+ };
342
+ const requestId = typeof value.requestId === "string" ? value.requestId : null;
343
+ const protocol = isProtocolVersion(value.protocol) ? value.protocol : null;
344
+ if (requestId === null || protocol === null || typeof value.method !== "string") return {
345
+ ok: false,
346
+ requestId,
347
+ protocol,
348
+ code: "invalid-message"
349
+ };
350
+ if (!isInspectorRequestMethod(value.method)) return {
351
+ ok: false,
352
+ requestId,
353
+ protocol,
354
+ code: "unknown-method"
355
+ };
356
+ if (!isInspectorRequestParams(value.method, value.params)) return {
357
+ ok: false,
358
+ requestId,
359
+ protocol,
360
+ code: "invalid-params"
361
+ };
362
+ return {
363
+ ok: true,
364
+ request: value
365
+ };
366
+ }
298
367
  function parseInspectorRequestMessage(value) {
299
- if (!isRecord(value) || value.kind !== "request" || !isProtocolVersion(value.protocol) || typeof value.requestId !== "string" || !isInspectorRequestMethod(value.method) || !isInspectorRequestParams(value.method, value.params)) return null;
300
- return value;
368
+ const classified = classifyInspectorRequest(value);
369
+ return classified.ok ? classified.request : null;
301
370
  }
302
371
  function isProtocolErrorCode(value, protocolMinor) {
303
372
  if (value === "subscription-limit") return protocolMinor >= 3;
373
+ if (value === "runtime-disposed") return protocolMinor >= 4;
304
374
  return value === "invalid-message" || value === "unsupported-version" || value === "unknown-method" || value === "invalid-params" || value === "runtime-not-found" || value === "widget-not-found" || value === "member-not-found" || value === "event-not-found" || value === "disconnected" || value === "internal-error";
305
375
  }
306
376
  function isProtocolError(value, protocolMinor) {
@@ -311,6 +381,19 @@ function parseInspectorResponseMessage(value) {
311
381
  if (value.ok) return "result" in value ? value : null;
312
382
  return isProtocolError(value.error, value.protocol.minor) ? value : null;
313
383
  }
384
+ /**
385
+ * Recognizes an otherwise well-formed error response whose code is not part of this protocol version's
386
+ * vocabulary (a newer peer's code), so a receiver can surface it generically instead of dropping it.
387
+ */
388
+ function parseInspectorUnrecognizedErrorResponse(value) {
389
+ if (!isRecord(value) || value.kind !== "response" || value.ok !== false || !isProtocolVersion(value.protocol) || typeof value.requestId !== "string" || !isRecord(value.error) || typeof value.error.code !== "string" || typeof value.error.message !== "string" || isProtocolErrorCode(value.error.code, value.protocol.minor)) return null;
390
+ return {
391
+ requestId: value.requestId,
392
+ protocol: value.protocol,
393
+ code: value.error.code,
394
+ message: value.error.message
395
+ };
396
+ }
314
397
  function isRuntimeMemberSnapshot(value) {
315
398
  return isRuntimeMemberSnapshot$1(value);
316
399
  }
@@ -353,7 +436,7 @@ function isInspectorRequestResult(method, value, protocolMinor = INSPECTOR_PROTO
353
436
  }
354
437
  }
355
438
  function isInspectorEventName(value) {
356
- return value === "geometry.invalidated" || value === "runtime.eventOccurred" || value === "runtime.memberChanged" || value === "inspect.hovered" || value === "inspect.selected" || value === "agent.status";
439
+ return value === "geometry.invalidated" || value === "runtime.disposed" || value === "runtime.eventOccurred" || value === "runtime.memberChanged" || value === "inspect.hovered" || value === "inspect.selected" || value === "agent.status";
357
440
  }
358
441
  function parseInspectorEventMessage(value) {
359
442
  if (!isRecord(value) || value.kind !== "event" || !isProtocolVersion(value.protocol) || !isInspectorEventName(value.event) || !isRecord(value.payload)) return null;
@@ -364,10 +447,11 @@ function parseInspectorEventMessage(value) {
364
447
  case "inspect.hovered": return (value.payload.ref === null || isWidgetRef(value.payload.ref)) && (value.payload.widgetId === void 0 || typeof value.payload.widgetId === "string") && (value.payload.widgetType === void 0 || typeof value.payload.widgetType === "string") ? value : null;
365
448
  case "inspect.selected": return isWidgetRef(value.payload.ref) && typeof value.payload.widgetId === "string" && typeof value.payload.widgetType === "string" ? value : null;
366
449
  case "agent.status": return typeof value.payload.inspectEnabled === "boolean" ? value : null;
450
+ case "runtime.disposed": return typeof value.payload.runtimeId === "string" && (value.payload.reason === "runtime-disposed" || value.payload.reason === "agent-disposed") ? value : null;
367
451
  }
368
452
  }
369
453
  function isCompatibleProtocolVersion(remote) {
370
454
  return remote.major === INSPECTOR_PROTOCOL_VERSION.major;
371
455
  }
372
456
  //#endregion
373
- export { isInspectorRequestResult as a, parseInspectorResponseMessage as c, isInspectorRequestParams as i, isCompatibleProtocolVersion as n, parseInspectorEventMessage as o, isInspectorRequestMethod as r, parseInspectorRequestMessage as s, INSPECTOR_PROTOCOL_VERSION as t };
457
+ export { isInspectorRequestParams as a, parseInspectorRequestMessage as c, isInspectorRequestMethod as i, parseInspectorResponseMessage as l, classifyInspectorRequest as n, isInspectorRequestResult as o, isCompatibleProtocolVersion as r, parseInspectorEventMessage as s, INSPECTOR_PROTOCOL_VERSION as t, parseInspectorUnrecognizedErrorResponse as u };
@@ -1,5 +1,4 @@
1
- import { n as InspectableValue } from "./value-b6hG7snB.mjs";
2
- import { WidgetConfigJsonSchema } from "@deviltea/widget-core";
1
+ import { r as InspectableValue } from "./value-Bc7ofk27.mjs";
3
2
  //#region src/protocol.d.ts
4
3
  interface InspectorProtocolVersion {
5
4
  readonly major: number;
@@ -7,7 +6,7 @@ interface InspectorProtocolVersion {
7
6
  }
8
7
  declare const INSPECTOR_PROTOCOL_VERSION: Readonly<{
9
8
  major: 0;
10
- minor: 3;
9
+ minor: 4;
11
10
  }>;
12
11
  interface InspectorCapabilities {
13
12
  readonly methods: readonly InspectorRequestMethod[];
@@ -50,9 +49,20 @@ interface InspectorMemberRef {
50
49
  readonly type: 'state' | 'property';
51
50
  readonly name: string;
52
51
  }
52
+ /** Any JSON value; the wire carries config schemas as plain JSON documents. */
53
+ type InspectorJsonValue = null | boolean | number | string | readonly InspectorJsonValue[] | {
54
+ readonly [key: string]: InspectorJsonValue;
55
+ };
56
+ /**
57
+ * A JSON Schema Draft 2020-12 document (an object or a boolean schema), typed only as plain JSON so that
58
+ * this protocol needs nothing from Core. Keyword and metaschema validity stay the plugin author's concern.
59
+ */
60
+ type InspectorConfigSchema = boolean | {
61
+ readonly [key: string]: InspectorJsonValue;
62
+ };
53
63
  interface InspectorConfigMetadata {
54
64
  readonly description: string;
55
- readonly schema: WidgetConfigJsonSchema | null;
65
+ readonly schema: InspectorConfigSchema | null;
56
66
  }
57
67
  interface InspectorBlueprintCapabilities {
58
68
  readonly config: boolean;
@@ -119,10 +129,14 @@ type InspectorDependency = {
119
129
  interface InspectorStateMember {
120
130
  readonly type: 'state';
121
131
  readonly name: string;
132
+ /** Added in protocol 0.4: whether Blueprint authors may write this State. Absent below 0.4. */
133
+ readonly authorWritable?: boolean;
122
134
  }
123
135
  interface InspectorPropertyMember {
124
136
  readonly type: 'property';
125
137
  readonly name: string;
138
+ /** Added in protocol 0.4: the declared value-contract id, or `null`. Absent below 0.4. */
139
+ readonly valueContractId?: string | null;
126
140
  readonly dependencies: readonly InspectorDependency[];
127
141
  }
128
142
  interface InspectorEventMember {
@@ -134,6 +148,8 @@ interface InspectorMethodMember {
134
148
  readonly type: 'method';
135
149
  readonly name: string;
136
150
  readonly transitivelyWrites: boolean;
151
+ /** Added in protocol 0.4: the Method emits an Event, itself or through the Methods it invokes. Absent below 0.4. */
152
+ readonly transitivelyEmits?: boolean;
137
153
  readonly dependencies: readonly InspectorDependency[];
138
154
  }
139
155
  type InspectorDiagnosticLocation = {
@@ -357,7 +373,7 @@ type InspectorRequestMethod = keyof InspectorRequestMap;
357
373
  type InspectorRequestParams<Method extends InspectorRequestMethod> = InspectorRequestMap[Method]['params'];
358
374
  type InspectorRequestResult<Method extends InspectorRequestMethod> = InspectorRequestMap[Method]['result'];
359
375
  interface InspectorProtocolError {
360
- readonly code: 'invalid-message' | 'unsupported-version' | 'unknown-method' | 'invalid-params' | 'runtime-not-found' | 'widget-not-found' | 'member-not-found' | 'event-not-found' | 'disconnected' | 'subscription-limit' | 'internal-error';
376
+ readonly code: 'invalid-message' | 'unsupported-version' | 'unknown-method' | 'invalid-params' | 'runtime-not-found' | 'widget-not-found' | 'member-not-found' | 'event-not-found' | 'disconnected' | 'subscription-limit' | 'runtime-disposed' | 'internal-error';
361
377
  readonly message: string;
362
378
  }
363
379
  type InspectorRequestMessage = { [Method in InspectorRequestMethod]: {
@@ -408,6 +424,16 @@ interface InspectorEventMap {
408
424
  readonly 'agent.status': {
409
425
  readonly inspectEnabled: boolean;
410
426
  };
427
+ /**
428
+ * Added in protocol 0.4. The Runtime this Agent inspects is gone: either the Agent observed it being
429
+ * disposed, or the Agent itself was disposed while the transport stays open. Sent at most once per Agent:
430
+ * inside `runtime.dispose()` when the Agent has already received a request from its peer; otherwise on the
431
+ * peer's first request, or when the Agent is disposed.
432
+ */
433
+ readonly 'runtime.disposed': {
434
+ readonly runtimeId: string;
435
+ readonly reason: 'runtime-disposed' | 'agent-disposed';
436
+ };
411
437
  }
412
438
  type InspectorEventName = keyof InspectorEventMap;
413
439
  type InspectorEventMessage = { [Event in InspectorEventName]: {
@@ -419,10 +445,40 @@ type InspectorEventMessage = { [Event in InspectorEventName]: {
419
445
  type InspectorMessage = InspectorRequestMessage | InspectorResponseMessage | InspectorEventMessage;
420
446
  declare function isInspectorRequestMethod(value: unknown): value is InspectorRequestMethod;
421
447
  declare function isInspectorRequestParams<Method extends InspectorRequestMethod>(method: Method, value: unknown): value is InspectorRequestParams<Method>;
448
+ type InspectorRequestRejectionCode = 'invalid-message' | 'unknown-method' | 'invalid-params';
449
+ type InspectorRequestClassification = {
450
+ readonly ok: true;
451
+ readonly request: InspectorRequestMessage;
452
+ } | {
453
+ readonly ok: false;
454
+ /** The id to answer under, or `null` when the value carries none (nothing to correlate an answer with). */
455
+ readonly requestId: string | null;
456
+ /** The sender's envelope version when it is well-formed, so a receiver can check the major first. */
457
+ readonly protocol: InspectorProtocolVersion | null;
458
+ readonly code: InspectorRequestRejectionCode;
459
+ };
460
+ /**
461
+ * Classifies an incoming value as a request, or names why it is not one: `invalid-message` for an
462
+ * envelope that is not a request at all, `unknown-method` for a well-formed envelope naming a method this
463
+ * protocol does not define, and `invalid-params` for a known method whose params do not validate.
464
+ */
465
+ declare function classifyInspectorRequest(value: unknown): InspectorRequestClassification;
422
466
  declare function parseInspectorRequestMessage(value: unknown): InspectorRequestMessage | null;
423
467
  declare function parseInspectorResponseMessage(value: unknown): InspectorResponseMessage | null;
468
+ interface InspectorUnrecognizedErrorResponse {
469
+ readonly requestId: string;
470
+ readonly protocol: InspectorProtocolVersion;
471
+ /** The peer's code string, verbatim: a code this protocol version does not define (yet). */
472
+ readonly code: string;
473
+ readonly message: string;
474
+ }
475
+ /**
476
+ * Recognizes an otherwise well-formed error response whose code is not part of this protocol version's
477
+ * vocabulary (a newer peer's code), so a receiver can surface it generically instead of dropping it.
478
+ */
479
+ declare function parseInspectorUnrecognizedErrorResponse(value: unknown): InspectorUnrecognizedErrorResponse | null;
424
480
  declare function isInspectorRequestResult<Method extends InspectorRequestMethod>(method: Method, value: unknown, protocolMinor?: number): value is InspectorRequestResult<Method>;
425
481
  declare function parseInspectorEventMessage(value: unknown): InspectorEventMessage | null;
426
482
  declare function isCompatibleProtocolVersion(remote: InspectorProtocolVersion): boolean;
427
483
  //#endregion
428
- export { INSPECTOR_PROTOCOL_VERSION, InspectorBlueprintCapabilities, InspectorBlueprintNode, InspectorBlueprintSnapshot, InspectorCapabilities, InspectorConfigMetadata, InspectorDependency, InspectorDependencyReference, InspectorDiagnostic, InspectorDiagnosticLocation, InspectorEvaluationCycle, InspectorEventMap, InspectorEventMember, InspectorEventMessage, InspectorEventName, InspectorGeometryRect, InspectorGeometrySnapshot, InspectorGeometryVisibility, InspectorHandshakeResult, InspectorHitTestResult, InspectorMemberRef, InspectorMessage, InspectorMethodMember, InspectorPreviewPoint, InspectorPropertyMember, InspectorProtocolError, InspectorProtocolVersion, InspectorRequestMap, InspectorRequestMessage, InspectorRequestMethod, InspectorRequestParams, InspectorRequestResult, InspectorResponseMessage, InspectorRuntimeDiagnostic, InspectorRuntimeDiagnosticLocation, InspectorRuntimeMemberSnapshot, InspectorRuntimePropertyResult, InspectorRuntimePropertySnapshot, InspectorRuntimeStateSnapshot, InspectorRuntimeSummary, InspectorRuntimeWidgetSnapshot, InspectorSemanticTarget, InspectorSlot, InspectorStateMember, InspectorSubscriptionSnapshot, WidgetRef, isCompatibleProtocolVersion, isInspectorRequestMethod, isInspectorRequestParams, isInspectorRequestResult, parseInspectorEventMessage, parseInspectorRequestMessage, parseInspectorResponseMessage };
484
+ export { INSPECTOR_PROTOCOL_VERSION, InspectorBlueprintCapabilities, InspectorBlueprintNode, InspectorBlueprintSnapshot, InspectorCapabilities, InspectorConfigMetadata, InspectorConfigSchema, InspectorDependency, InspectorDependencyReference, InspectorDiagnostic, InspectorDiagnosticLocation, InspectorEvaluationCycle, InspectorEventMap, InspectorEventMember, InspectorEventMessage, InspectorEventName, InspectorGeometryRect, InspectorGeometrySnapshot, InspectorGeometryVisibility, InspectorHandshakeResult, InspectorHitTestResult, InspectorJsonValue, InspectorMemberRef, InspectorMessage, InspectorMethodMember, InspectorPreviewPoint, InspectorPropertyMember, InspectorProtocolError, InspectorProtocolVersion, InspectorRequestClassification, InspectorRequestMap, InspectorRequestMessage, InspectorRequestMethod, InspectorRequestParams, InspectorRequestRejectionCode, InspectorRequestResult, InspectorResponseMessage, InspectorRuntimeDiagnostic, InspectorRuntimeDiagnosticLocation, InspectorRuntimeMemberSnapshot, InspectorRuntimePropertyResult, InspectorRuntimePropertySnapshot, InspectorRuntimeStateSnapshot, InspectorRuntimeSummary, InspectorRuntimeWidgetSnapshot, InspectorSemanticTarget, InspectorSlot, InspectorStateMember, InspectorSubscriptionSnapshot, InspectorUnrecognizedErrorResponse, WidgetRef, classifyInspectorRequest, isCompatibleProtocolVersion, isInspectorRequestMethod, isInspectorRequestParams, isInspectorRequestResult, parseInspectorEventMessage, parseInspectorRequestMessage, parseInspectorResponseMessage, parseInspectorUnrecognizedErrorResponse };
package/dist/protocol.mjs CHANGED
@@ -1,2 +1,2 @@
1
- import { a as isInspectorRequestResult, c as parseInspectorResponseMessage, i as isInspectorRequestParams, n as isCompatibleProtocolVersion, o as parseInspectorEventMessage, r as isInspectorRequestMethod, s as parseInspectorRequestMessage, t as INSPECTOR_PROTOCOL_VERSION } from "./protocol-D1gtirOC.mjs";
2
- export { INSPECTOR_PROTOCOL_VERSION, isCompatibleProtocolVersion, isInspectorRequestMethod, isInspectorRequestParams, isInspectorRequestResult, parseInspectorEventMessage, parseInspectorRequestMessage, parseInspectorResponseMessage };
1
+ import { a as isInspectorRequestParams, c as parseInspectorRequestMessage, i as isInspectorRequestMethod, l as parseInspectorResponseMessage, n as classifyInspectorRequest, o as isInspectorRequestResult, r as isCompatibleProtocolVersion, s as parseInspectorEventMessage, t as INSPECTOR_PROTOCOL_VERSION, u as parseInspectorUnrecognizedErrorResponse } from "./protocol-ZhhQaTAa.mjs";
2
+ export { INSPECTOR_PROTOCOL_VERSION, classifyInspectorRequest, isCompatibleProtocolVersion, isInspectorRequestMethod, isInspectorRequestParams, isInspectorRequestResult, parseInspectorEventMessage, parseInspectorRequestMessage, parseInspectorResponseMessage, parseInspectorUnrecognizedErrorResponse };
@@ -1,8 +1,23 @@
1
1
  //#region src/value.d.ts
2
2
  interface InspectableValueEncodingOptions {
3
+ /** Maximum nesting depth of containers; deeper values encode as `{ type: 'truncated' }`. Default 4. */
3
4
  readonly maxDepth?: number;
5
+ /** Maximum entries/items emitted per array or object. Default 50. */
4
6
  readonly maxEntries?: number;
7
+ /** Maximum length of any string value or object key (UTF-16 code units). Default 500. */
5
8
  readonly maxStringLength?: number;
9
+ /**
10
+ * Total budget of encoded values (every emitted node counts, leaves included) across the whole encoding,
11
+ * on top of the per-level limits. Once spent, remaining entries/items are left out and their container
12
+ * reports `truncated: true`. The root is always emitted. Default 1000.
13
+ */
14
+ readonly maxNodes?: number;
15
+ /**
16
+ * Cut object keys longer than `maxStringLength` and mark the entry with `keyTruncated: true`. Default true.
17
+ * When false, keys are emitted in full and never cut: the Agent turns it off for peers negotiated below
18
+ * protocol 0.4, which predate the marker and must see the same shapes as before.
19
+ */
20
+ readonly markTruncatedKeys?: boolean;
6
21
  }
7
22
  type InspectableValue = {
8
23
  readonly type: 'null';
@@ -46,8 +61,11 @@ type InspectableValue = {
46
61
  };
47
62
  interface InspectableObjectEntry {
48
63
  readonly key: string;
64
+ /** Present (and `true`) only when `key` was cut to the string limit. Added in protocol 0.4. */
65
+ readonly keyTruncated?: boolean;
49
66
  readonly value: InspectableValue;
50
67
  }
68
+ declare const DEFAULT_INSPECTABLE_VALUE_LIMITS: Readonly<Required<Omit<InspectableValueEncodingOptions, 'markTruncatedKeys'>>>;
51
69
  declare function encodeInspectableValue(value: unknown, options?: InspectableValueEncodingOptions): InspectableValue;
52
70
  //#endregion
53
- export { encodeInspectableValue as i, InspectableValue as n, InspectableValueEncodingOptions as r, InspectableObjectEntry as t };
71
+ export { encodeInspectableValue as a, InspectableValueEncodingOptions as i, InspectableObjectEntry as n, InspectableValue as r, DEFAULT_INSPECTABLE_VALUE_LIMITS as t };
package/dist/value.d.mts CHANGED
@@ -1,2 +1,2 @@
1
- import { i as encodeInspectableValue, n as InspectableValue, r as InspectableValueEncodingOptions, t as InspectableObjectEntry } from "./value-b6hG7snB.mjs";
2
- export { InspectableObjectEntry, InspectableValue, InspectableValueEncodingOptions, encodeInspectableValue };
1
+ import { a as encodeInspectableValue, i as InspectableValueEncodingOptions, n as InspectableObjectEntry, r as InspectableValue, t as DEFAULT_INSPECTABLE_VALUE_LIMITS } from "./value-Bc7ofk27.mjs";
2
+ export { DEFAULT_INSPECTABLE_VALUE_LIMITS, InspectableObjectEntry, InspectableValue, InspectableValueEncodingOptions, encodeInspectableValue };
package/dist/value.mjs CHANGED
@@ -1,7 +1,10 @@
1
1
  //#region src/value.ts
2
- const DEFAULT_MAX_DEPTH = 4;
3
- const DEFAULT_MAX_ENTRIES = 50;
4
- const DEFAULT_MAX_STRING_LENGTH = 500;
2
+ const DEFAULT_INSPECTABLE_VALUE_LIMITS = Object.freeze({
3
+ maxDepth: 4,
4
+ maxEntries: 50,
5
+ maxStringLength: 500,
6
+ maxNodes: 1e3
7
+ });
5
8
  function encodeString(value, maxLength) {
6
9
  const truncated = value.length > maxLength;
7
10
  return {
@@ -25,13 +28,74 @@ function isDomNode(value) {
25
28
  return false;
26
29
  }
27
30
  }
31
+ /** At or below this limit a `splice`d sorted window moves so few elements per insertion that it beats a heap. */
32
+ const SORTED_WINDOW_MAX_LIMIT = 256;
33
+ /** The `size` (at least 1, below `keys.length`) smallest keys kept as a sorted window with binary search. */
34
+ function smallestKeysInSortedWindow(keys, size) {
35
+ const selected = [];
36
+ for (const key of keys) {
37
+ if (selected.length === size && key >= selected[size - 1]) continue;
38
+ let low = 0;
39
+ let high = selected.length;
40
+ while (low < high) {
41
+ const middle = low + high >>> 1;
42
+ if (selected[middle] < key) low = middle + 1;
43
+ else high = middle;
44
+ }
45
+ selected.splice(low, 0, key);
46
+ if (selected.length > size) selected.pop();
47
+ }
48
+ return selected;
49
+ }
50
+ /**
51
+ * The `limit` smallest keys in code-unit order, without sorting (or copying) more of the key list than it emits.
52
+ * When every key is wanted the list is simply sorted. Otherwise one pass keeps the smallest keys seen so far in a
53
+ * bounded structure, so the work never exceeds O(keys * log limit) plus the cost of ordering the `limit` survivors: a
54
+ * small sorted window, or above `SORTED_WINDOW_MAX_LIMIT` a max-heap (a window of any size kept with `splice` is
55
+ * quadratic in `limit` when the keys arrive in descending order); only the survivors are sorted at the end.
56
+ */
57
+ function smallestKeys(keys, limit) {
58
+ if (limit <= 0) return [];
59
+ if (!(limit < keys.length)) return [...keys].sort();
60
+ const size = Math.floor(limit);
61
+ if (size <= 0) return [];
62
+ if (size <= SORTED_WINDOW_MAX_LIMIT) return smallestKeysInSortedWindow(keys, size);
63
+ const heap = [];
64
+ for (const key of keys) if (heap.length < size) {
65
+ let child = heap.length;
66
+ heap.push(key);
67
+ while (child > 0) {
68
+ const parent = child - 1 >>> 1;
69
+ if (heap[parent] >= key) break;
70
+ heap[child] = heap[parent];
71
+ child = parent;
72
+ }
73
+ heap[child] = key;
74
+ } else if (key < heap[0]) {
75
+ let parent = 0;
76
+ for (;;) {
77
+ let child = 2 * parent + 1;
78
+ if (child >= size) break;
79
+ if (child + 1 < size && heap[child + 1] > heap[child]) child++;
80
+ if (heap[child] <= key) break;
81
+ heap[parent] = heap[child];
82
+ parent = child;
83
+ }
84
+ heap[parent] = key;
85
+ }
86
+ return heap.sort();
87
+ }
28
88
  function encodeInspectableValue(value, options = {}) {
29
- const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
30
- const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
31
- const maxStringLength = options.maxStringLength ?? DEFAULT_MAX_STRING_LENGTH;
89
+ const maxDepth = options.maxDepth ?? DEFAULT_INSPECTABLE_VALUE_LIMITS.maxDepth;
90
+ const maxEntries = options.maxEntries ?? DEFAULT_INSPECTABLE_VALUE_LIMITS.maxEntries;
91
+ const maxStringLength = options.maxStringLength ?? DEFAULT_INSPECTABLE_VALUE_LIMITS.maxStringLength;
92
+ const maxNodes = options.maxNodes ?? DEFAULT_INSPECTABLE_VALUE_LIMITS.maxNodes;
93
+ const markTruncatedKeys = options.markTruncatedKeys ?? true;
32
94
  const seen = /* @__PURE__ */ new WeakMap();
33
95
  let nextId = 1;
96
+ let nodes = 0;
34
97
  function encode(current, depth) {
98
+ nodes++;
35
99
  if (current === null) return { type: "null" };
36
100
  if (current === void 0) return { type: "undefined" };
37
101
  switch (typeof current) {
@@ -92,29 +156,33 @@ function encodeInspectableValue(value, options = {}) {
92
156
  seen.set(objectValue, id);
93
157
  const limit = Math.min(length, maxEntries);
94
158
  const items = [];
95
- for (let index = 0; index < limit; index++) {
159
+ for (let index = 0; index < limit && nodes < maxNodes; index++) {
96
160
  let descriptor;
97
161
  try {
98
162
  descriptor = Object.getOwnPropertyDescriptor(objectValue, String(index));
99
163
  } catch {
164
+ nodes++;
100
165
  items.push(opaque("uninspectable"));
101
166
  continue;
102
167
  }
103
- items.push(descriptor !== void 0 && "value" in descriptor ? encode(descriptor.value, depth + 1) : opaque("uninspectable"));
168
+ if (descriptor !== void 0 && "value" in descriptor) items.push(encode(descriptor.value, depth + 1));
169
+ else {
170
+ nodes++;
171
+ items.push(opaque("uninspectable"));
172
+ }
104
173
  }
105
174
  return {
106
175
  type: "array",
107
176
  id,
108
177
  items,
109
- truncated: length > limit
178
+ truncated: length > items.length
110
179
  };
111
180
  }
112
- let prototype;
113
- let descriptors;
181
+ let keys;
114
182
  try {
115
- prototype = Object.getPrototypeOf(objectValue);
183
+ const prototype = Object.getPrototypeOf(objectValue);
116
184
  if (prototype !== Object.prototype && prototype !== null) return opaque("class-instance");
117
- descriptors = Object.getOwnPropertyDescriptors(objectValue);
185
+ keys = Object.keys(objectValue);
118
186
  } catch {
119
187
  return opaque("uninspectable");
120
188
  }
@@ -125,14 +193,27 @@ function encodeInspectableValue(value, options = {}) {
125
193
  };
126
194
  const id = nextId++;
127
195
  seen.set(objectValue, id);
128
- const keys = Object.keys(descriptors).sort();
129
196
  const entries = [];
130
- for (const key of keys.slice(0, maxEntries)) {
131
- const descriptor = descriptors[key];
197
+ for (const key of smallestKeys(keys, maxEntries)) {
198
+ if (nodes >= maxNodes) break;
199
+ let descriptor;
200
+ try {
201
+ descriptor = Object.getOwnPropertyDescriptor(objectValue, key);
202
+ } catch {
203
+ descriptor = void 0;
204
+ }
132
205
  if (descriptor === void 0) continue;
206
+ const keyTruncated = markTruncatedKeys && key.length > maxStringLength;
207
+ let entryValue;
208
+ if ("value" in descriptor) entryValue = encode(descriptor.value, depth + 1);
209
+ else {
210
+ nodes++;
211
+ entryValue = opaque("uninspectable");
212
+ }
133
213
  entries.push({
134
- key,
135
- value: "value" in descriptor ? encode(descriptor.value, depth + 1) : opaque("uninspectable")
214
+ key: keyTruncated ? key.slice(0, maxStringLength) : key,
215
+ ...keyTruncated ? { keyTruncated: true } : {},
216
+ value: entryValue
136
217
  });
137
218
  }
138
219
  return {
@@ -149,4 +230,4 @@ function encodeInspectableValue(value, options = {}) {
149
230
  }
150
231
  }
151
232
  //#endregion
152
- export { encodeInspectableValue };
233
+ export { DEFAULT_INSPECTABLE_VALUE_LIMITS, encodeInspectableValue };