@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.
- package/README.md +171 -6
- package/dist/agent.d.mts +7 -0
- package/dist/agent.mjs +305 -94
- package/dist/channel.mjs +75 -16
- package/dist/client.d.mts +24 -6
- package/dist/client.mjs +128 -26
- package/dist/{protocol-D1gtirOC.mjs → protocol-ZhhQaTAa.mjs} +118 -34
- package/dist/protocol.d.mts +62 -6
- package/dist/protocol.mjs +2 -2
- package/dist/{value-b6hG7snB.d.mts → value-Bc7ofk27.d.mts} +19 -1
- package/dist/value.d.mts +2 -2
- package/dist/value.mjs +100 -19
- package/package.json +5 -4
package/README.md
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
# @deviltea/widget-inspector
|
|
2
2
|
|
|
3
|
+
> **Upgrading from 0.0.x?** Follow the [migration guide to 0.1](https://deviltea.github.io/widget/migration/0.1).
|
|
4
|
+
|
|
3
5
|
> ESM-only package. **0.x experimental, protocol-major guarantee only.**
|
|
4
6
|
|
|
5
7
|
A read-only, versioned Inspector boundary for [`@deviltea/widget-core`](https://www.npmjs.com/package/@deviltea/widget-core) Runtimes: a JSON-safe protocol, a client for the inspecting side, an agent that projects Core inspection into serializable DTOs and owns inspected-document interaction, transports, and the inspect-anchor attribute contract renderers use to mark their DOM.
|
|
@@ -22,7 +24,7 @@ InspectorAgent (/agent)
|
|
|
22
24
|
pnpm add @deviltea/widget-inspector @deviltea/widget-core
|
|
23
25
|
```
|
|
24
26
|
|
|
25
|
-
`@deviltea/widget-core` is a **peer dependency**: the Agent must see the very same Core copy that created the host's Runtime, or `inspectRuntime` rejects the Runtime as foreign.
|
|
27
|
+
`@deviltea/widget-core` is a **peer dependency**: the Agent must see the very same Core copy that created the host's Runtime, or `inspectRuntime` rejects the Runtime as foreign. Only the Agent side (`/agent`) imports Core; `/protocol`, `/client`, `/transport`, `/channel`, `/frame-bootstrap`, `/value` and `/anchor` import nothing from it, so an inspecting UI that only talks to a remote Agent needs no Core at runtime or for types.
|
|
26
28
|
|
|
27
29
|
## Public subpaths
|
|
28
30
|
|
|
@@ -35,7 +37,7 @@ There is no root entry; import from exactly these subpaths.
|
|
|
35
37
|
| `/transport` | Transport interface plus in-process and MessagePort transports. |
|
|
36
38
|
| `/channel` | `createMessagePortChannelHub`: several logical transports over one MessagePort. |
|
|
37
39
|
| `/frame-bootstrap` | One-time, validated bootstrap envelope that transfers a dedicated MessagePort into a frame. |
|
|
38
|
-
| `/agent` | `createInspectorAgent`, bound to one Runtime and
|
|
40
|
+
| `/agent` | `createInspectorAgent`, bound to one Runtime and, optionally, one inspected DOM root. |
|
|
39
41
|
| `/value` | The bounded, accessor-safe `InspectableValue` display encoding. |
|
|
40
42
|
| `/anchor` | `inspectAnchorAttributes` and the anchor attribute names, for renderers. |
|
|
41
43
|
|
|
@@ -48,7 +50,7 @@ import { createInProcessInspectorTransportPair } from '@deviltea/widget-inspecto
|
|
|
48
50
|
|
|
49
51
|
const pair = createInProcessInspectorTransportPair()
|
|
50
52
|
const agent = createInspectorAgent({ runtime, transport: pair.agent, dom: { root: document.getElementById('app')! } })
|
|
51
|
-
const client = createInspectorClient(pair.client)
|
|
53
|
+
const client = createInspectorClient(pair.client, { requestTimeoutMs: 5000 })
|
|
52
54
|
|
|
53
55
|
await client.handshake()
|
|
54
56
|
const { runtimes } = await client.request('runtime.list', {})
|
|
@@ -56,7 +58,139 @@ const { runtimes } = await client.request('runtime.list', {})
|
|
|
56
58
|
|
|
57
59
|
The boundary is read-only: no state mutation, Method invocation, eval, generic object RPC, or Runtime discovery global hook.
|
|
58
60
|
|
|
59
|
-
|
|
61
|
+
**One Agent per transport per Runtime.** An Inspector transport has exactly one peer, and that peer talks to one Agent. Two Agents on the same transport both answer every request, so the client sees duplicate, conflicting responses. To replace a Runtime binding on a shared transport, dispose the old Agent first (`closeTransportOnDispose: false` keeps the transport open for the replacement) and then create the new one; the client is told through `runtime.disposed` (see [Lifecycle](#lifecycle)).
|
|
62
|
+
|
|
63
|
+
`dom` is optional. An Agent without it serves the Runtime-level methods only; the DOM-dependent methods (`inspect.enable`, `inspect.disable`, `highlight.show`, `highlight.clear`, `inspect.hitTest`, `geometry.resolve`) are not advertised and answer `unknown-method`.
|
|
64
|
+
|
|
65
|
+
## Cross-frame setup
|
|
66
|
+
|
|
67
|
+
Run the Runtime and the Agent in the frame that owns the inspected DOM, and the Client in the host page. Nothing but the one-time bootstrap message ever travels on the global window `message` bus; all Inspector traffic goes over a dedicated `MessagePort`.
|
|
68
|
+
|
|
69
|
+
**Host side (the page embedding the frame):**
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
import { createMessagePortChannelHub } from '@deviltea/widget-inspector/channel'
|
|
73
|
+
import { createInspectorClient } from '@deviltea/widget-inspector/client'
|
|
74
|
+
import { createInspectorFrameBootstrapRequest } from '@deviltea/widget-inspector/frame-bootstrap'
|
|
75
|
+
|
|
76
|
+
const sessionId = crypto.randomUUID()
|
|
77
|
+
const generation = 0 // increase on every (re)load of the frame
|
|
78
|
+
const frameOrigin = new URL(frameUrl).origin // never 'null' and never '*'
|
|
79
|
+
|
|
80
|
+
// The frame learns this page's origin from its referrer; send the origin (not the path) as the referrer.
|
|
81
|
+
iframe.referrerPolicy = 'origin'
|
|
82
|
+
iframe.src = `${frameUrl}?session=${sessionId}&generation=${generation}`
|
|
83
|
+
|
|
84
|
+
iframe.addEventListener('load', () => {
|
|
85
|
+
const channel = new MessageChannel()
|
|
86
|
+
const hub = createMessagePortChannelHub(channel.port1)
|
|
87
|
+
const client = createInspectorClient(hub.openChannel('inspector'), { requestTimeoutMs: 5000 })
|
|
88
|
+
// Transfer port2 to the frame with the EXACT frame origin as the target origin.
|
|
89
|
+
iframe.contentWindow!.postMessage(
|
|
90
|
+
createInspectorFrameBootstrapRequest(sessionId, generation),
|
|
91
|
+
frameOrigin,
|
|
92
|
+
[channel.port2],
|
|
93
|
+
)
|
|
94
|
+
}, { once: true })
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
**Frame side (the page that owns the Runtime):**
|
|
98
|
+
|
|
99
|
+
```ts
|
|
100
|
+
import { createInspectorAgent } from '@deviltea/widget-inspector/agent'
|
|
101
|
+
import { createMessagePortChannelHub } from '@deviltea/widget-inspector/channel'
|
|
102
|
+
import { acceptInspectorFrameBootstrap } from '@deviltea/widget-inspector/frame-bootstrap'
|
|
103
|
+
|
|
104
|
+
const params = new URLSearchParams(location.search)
|
|
105
|
+
const sessionId = params.get('session') ?? ''
|
|
106
|
+
const generation = Number(params.get('generation'))
|
|
107
|
+
// The origin of the actual embedding parent, from browser-owned navigation metadata.
|
|
108
|
+
const parentOrigin = document.referrer ? new URL(document.referrer).origin : null
|
|
109
|
+
|
|
110
|
+
window.addEventListener('message', (event) => {
|
|
111
|
+
if (parentOrigin === null || parentOrigin === 'null')
|
|
112
|
+
return
|
|
113
|
+
const accepted = acceptInspectorFrameBootstrap(event, {
|
|
114
|
+
expectedSource: window.parent,
|
|
115
|
+
expectedOrigin: parentOrigin,
|
|
116
|
+
sessionId,
|
|
117
|
+
expectedGeneration: generation,
|
|
118
|
+
})
|
|
119
|
+
if (accepted === null)
|
|
120
|
+
return
|
|
121
|
+
const hub = createMessagePortChannelHub(accepted.port)
|
|
122
|
+
createInspectorAgent({ runtime, transport: hub.openChannel('inspector'), dom: { root: appElement } })
|
|
123
|
+
})
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Rules this pins:
|
|
127
|
+
|
|
128
|
+
- **Never post the bootstrap with a `'*'` target origin.** The transferred port is the only authentication (see [Security model](#security-model)); a `'*'` target lets whichever document currently occupies the frame (after a navigation, redirect or embed swap) receive it. Pass the exact frame origin. An opaque origin (`'null'`) cannot be targeted and must be rejected.
|
|
129
|
+
- **How the frame learns `expectedOrigin`.** Not from the message: `event.origin` is what is being checked, so the expected value must come from somewhere the sender cannot choose. The reference setup reads it from `document.referrer`, which is the embedding parent's origin when the iframe sets `referrerPolicy = 'origin'` before navigating (an empty or opaque referrer must authorize nothing). A frame served from a known fixed host may instead hard-code the host's origin. The check pins the integration to its intended parent; it is not a frame-ancestors allowlist or a sandbox.
|
|
130
|
+
- **`sessionId`** identifies one host-owned connection attempt and is generated by the host; the frame gets it out of band (the frame URL) and only accepts a bootstrap carrying it. **`generation`** counts reloads of the frame: the host increments it every time the frame loads, so a bootstrap prepared for a previous document (late, replayed or cached) is rejected by `expectedGeneration`.
|
|
131
|
+
- `acceptInspectorFrameBootstrap` returns `null` unless the message source is the expected window, its origin matches, the envelope validates, `sessionId` and `generation` match, and exactly one port was transferred. Ignore everything else; keep listening until one bootstrap is accepted, then stop.
|
|
132
|
+
- **Channel ordering.** The hub multiplexes logical channels by name. The two sides open their channels independently, so either side may send first: a message for a channel the other side has not opened yet is buffered (at most 64 messages per channel, **oldest dropped** on overflow) and delivered in order to the first subscriber after that side opens the channel. At most 16 not-yet-opened channel names hold state per peer; messages for further unknown names are dropped. Closing a channel is scoped to it; `openChannel` after a close returns a fresh transport; closing the hub (or the native port) disconnects every channel. Messages still in flight for a channel the local side has just closed are dropped until it is reopened locally.
|
|
133
|
+
- A client request sent before the Agent exists is therefore delivered once the Agent attaches, but still set `requestTimeoutMs`: nothing else bounds a request to a peer that never appears.
|
|
134
|
+
|
|
135
|
+
## Client API
|
|
136
|
+
|
|
137
|
+
```ts
|
|
138
|
+
const client = createInspectorClient(transport, { requestTimeoutMs: 5000 })
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
`createInspectorClient(transport, options?)` — `options.requestTimeoutMs` (positive finite number, no default) rejects a request that gets no response within that time with an `InspectorClientError` coded `timeout`; a late response is ignored, except that a late successful `runtime.subscribeMember` or `runtime.subscribeEvent` response makes the client send the matching unsubscribe (best effort, the last 256 timed-out subscribe requests are remembered), so the Agent does not keep a subscription whose id the caller never learned.
|
|
142
|
+
|
|
143
|
+
| Member | Behavior |
|
|
144
|
+
| --- | --- |
|
|
145
|
+
| `handshake()` | Sends the Client's protocol version and resolves `{ protocol, capabilities }`: the negotiated `major.minor` and the `methods`/`events` this Agent offers at it. The negotiated minor is only ever set by a handshake. |
|
|
146
|
+
| `request(method, params)` | Sends one typed request and resolves its typed result. Rejects with `InspectorClientError` for a protocol error, a malformed or incompatible response, a timeout, or disconnection. Standalone requests are valid before the first handshake. |
|
|
147
|
+
| `on(event, listener)` | Subscribes to one event by name; returns an unsubscribe function. |
|
|
148
|
+
| `subscribe(listener)` | Subscribes to every valid event message; returns an unsubscribe function. |
|
|
149
|
+
| `close()` / `dispose()` | Same function. Rejects pending requests with `disconnected`, drops listeners and closes the transport. A transport that closes underneath the client does the same. |
|
|
150
|
+
|
|
151
|
+
A listener that throws does not affect other listeners or the transport: the failure is rethrown in a microtask.
|
|
152
|
+
|
|
153
|
+
**`InspectorClientError`** has `code`, `message` and `protocolError`. Codes: `invalid-message` (malformed request or response), `unsupported-version` (protocol major mismatch), `unknown-method`, `invalid-params`, `runtime-not-found`, `widget-not-found`, `member-not-found`, `event-not-found`, `disconnected`, `subscription-limit` (0.3+), `runtime-disposed` (0.4+), `internal-error` (the Agent failed while handling the request; details stay in the Agent's realm) and the client-only `timeout`. An error code a newer Agent sends that this client does not define becomes `unknown-error` with the peer's code in `peerCode` and its message preserved.
|
|
154
|
+
|
|
155
|
+
**Getting a `WidgetRef`.** A `WidgetRef` is `{ runtimeId, nodeId }`. `runtime.list` returns each Runtime's `runtimeId` and `rootNodeId`; `blueprint.getSnapshot` for a `runtimeId` returns every node with its `nodeId`, `widgetId`, `widgetType`, slots and members. Node ids are stable only within one Agent/Runtime. The inspect events (`inspect.hovered`, `inspect.selected`) and `inspect.hitTest` carry ready-made refs.
|
|
156
|
+
|
|
157
|
+
**Subscribe/unsubscribe lifecycle.** `runtime.subscribeMember` (State or Property) and `runtime.subscribeEvent` return a `subscriptionId`; later `runtime.memberChanged` / `runtime.eventOccurred` events carry it. Release with `runtime.unsubscribeMember` / `runtime.unsubscribeEvent` (`{ removed }` is `false` for an unknown id). The Agent releases everything when it is disposed or the transport closes. Subscriptions are passive: subscribing never evaluates a Property.
|
|
158
|
+
|
|
159
|
+
**Capabilities.** The handshake result lists the methods and events available at the negotiated minor. Anything not listed is unavailable for the session and answers `unknown-method`. DOM-dependent methods and `geometry.invalidated` are only offered by an Agent created with `dom`; `runtime.disposed` only from 0.4. A peer that never performs the handshake is served at the Agent's highest minor for events (only the handshake sets the negotiated minor); its responses use the lower of that and the request envelope's minor.
|
|
160
|
+
|
|
161
|
+
### Events
|
|
162
|
+
|
|
163
|
+
`runtime.memberChanged`, `runtime.eventOccurred` (0.2), `inspect.hovered` (only when the hovered Widget changes), `inspect.selected`, `agent.status`, `geometry.invalidated` (0.2, DOM Agents), `runtime.disposed` (0.4).
|
|
164
|
+
|
|
165
|
+
## Agent options
|
|
166
|
+
|
|
167
|
+
| Option | Meaning |
|
|
168
|
+
| --- | --- |
|
|
169
|
+
| `runtime`, `transport` | Required. The Runtime to inspect and the transport to its single peer. |
|
|
170
|
+
| `runtimeId` | Optional opaque id for this Runtime on the wire; generated when omitted. |
|
|
171
|
+
| `dom` | `{ root }`: the inspected renderer root. Enables inspect mode, highlight, hit-testing and geometry. |
|
|
172
|
+
| `closeTransportOnDispose` | Default `true`. Set `false` to keep a host-owned shared transport open when only this Agent is replaced. |
|
|
173
|
+
| `maxSubscriptions` | Optional cap on live member and event subscriptions, counted together. No default. |
|
|
174
|
+
| `valueLimits` | Overrides for the `InspectableValue` limits below. |
|
|
175
|
+
|
|
176
|
+
### Lifecycle
|
|
177
|
+
|
|
178
|
+
The Agent subscribes to Runtime disposal (`runtime.subscribeDisposal()`). Once the peer has sent the Agent any request, the peer is told inside the `runtime.dispose()` call, not at its next request: from protocol 0.4 the Agent sends one `runtime.disposed` event (`reason: 'runtime-disposed'`) at that moment, releases its subscription bookkeeping and clears its highlight overlay, `runtime.list` stops listing the Runtime, and requests addressed to it, plus `inspect.hitTest`, `inspect.enable` and `highlight.clear`, answer `runtime-disposed` (releasing calls such as `runtime.unsubscribe*` and `inspect.disable` stay answerable). Inspect mode, if enabled, then stops emitting `inspect.hovered` / `inspect.selected` and stops suppressing the page's own pointer and click activation, until the peer disables it. A peer that has sent a request but not completed the handshake is told inside `runtime.dispose()` too, at the Agent's highest minor, like any other event. A peer the Agent has not heard from yet (for example one that attaches after the Runtime was disposed, since a transport may drop messages nobody is subscribed to) is told on its first request instead, before the Agent emits any other event and, for a handshake, before the minor is negotiated; if it never sends one, the Agent announces when it is disposed. An event that cannot be delivered (a closed or throwing transport) is dropped and never reaches the `runtime.dispose()` caller. An Agent created on a Runtime that is already disposed cannot subscribe, so it announces on the first request in the same way. Disposing the Agent while the transport stays open (`closeTransportOnDispose: false`) sends the same event with `reason: 'agent-disposed'`; a Runtime disposed after its Agent causes no send. Dispose the Agent when you dispose the Runtime: the Runtime's disposal does not release the Agent's transport subscription, DOM listeners or highlight overlay. Peers negotiated below 0.4 never see the event or code and keep the earlier behavior.
|
|
179
|
+
|
|
180
|
+
### Value encoding limits
|
|
181
|
+
|
|
182
|
+
Runtime values and event arguments are encoded as `InspectableValue` (see `/value`): JSON-safe, never executing accessors, `toJSON`, or Proxy traps. The limits, with their defaults, are:
|
|
183
|
+
|
|
184
|
+
| Limit | Default | Meaning |
|
|
185
|
+
| --- | --- | --- |
|
|
186
|
+
| `maxDepth` | 4 | Container nesting; deeper values become `{ type: 'truncated' }`. |
|
|
187
|
+
| `maxEntries` | 50 | Entries or items per array/object (objects keep their smallest keys, in sorted order). |
|
|
188
|
+
| `maxStringLength` | 500 | String values **and object keys** (a cut key sets `keyTruncated: true`, 0.4+; peers negotiated below 0.4 receive keys in full, never cut). |
|
|
189
|
+
| `maxNodes` | 1000 | Total encoded values per encoded value, leaves included. Once spent, remaining entries are left out and their container reports `truncated: true`. |
|
|
190
|
+
|
|
191
|
+
Truncation is always explicit in the encoding. Config schema documents are not encoded this way: they are transmitted whole as JSON metadata. The encoder lists an object's keys once (linear in the key count) but selects, sorts and describes only the entries it emits.
|
|
192
|
+
|
|
193
|
+
## Anchors
|
|
60
194
|
|
|
61
195
|
A renderer marks the DOM it renders for a Widget with `inspectAnchorAttributes`. `@deviltea/widget-vue` stamps no DOM attributes itself, so project `useWidget()` identity explicitly:
|
|
62
196
|
|
|
@@ -77,15 +211,46 @@ const anchor = inspectAnchorAttributes({ widgetId, widgetType })
|
|
|
77
211
|
|
|
78
212
|
Inspect-mode highlight is drawn by the Agent in its own ShadowRoot overlay attached to the inspected document, from geometry rects. The Agent never mutates renderer elements, and a renderer re-render does not clear the highlight. Style it by setting `--widget-inspector-accent`, `--widget-inspector-accent-contrast`, and `--widget-inspector-fill` on `:root` or `body` of the inspected document.
|
|
79
213
|
|
|
214
|
+
### Geometry
|
|
215
|
+
|
|
216
|
+
Rects and points use the `preview-viewport` coordinate space: CSS pixels relative to the top-left of the **inspected document's viewport** (the frame's viewport when the Agent runs in an iframe), as `getClientRects()` reports them for the anchor elements. Document-wide observation (scroll, resize, mutation, fonts, loads) starts on the first geometry, hit-test, inspect or highlight use, not at Agent creation. `visibility` is `visible`, `clipped` (some rect leaves the viewport), `hidden` (no anchor currently has a rect, which also covers "no anchor element exists") or `missing` (the ref does not resolve).
|
|
217
|
+
|
|
80
218
|
### Subscription cap
|
|
81
219
|
|
|
82
220
|
`createInspectorAgent({ maxSubscriptions })` optionally bounds live Runtime member and event subscriptions. There is **no default limit**. When a configured cap is reached, further subscribe requests fail with `subscription-limit`.
|
|
83
221
|
|
|
222
|
+
## Security model
|
|
223
|
+
|
|
224
|
+
The Inspector is a read-only debugging boundary, not an access-control system.
|
|
225
|
+
|
|
226
|
+
- **Port possession is the only authentication.** Whoever holds the transport (the `MessagePort`, or the in-process pair) can issue every request. There is no credential, token or per-request authorization; the bootstrap origin/session/generation checks only decide who receives the port.
|
|
227
|
+
- **What a peer can read.** The full Blueprint structure (ids, types, slots, config schemas and descriptions, diagnostics, dependency graph), every State value, every Property result and diagnostic, and every event argument of the inspected Runtime, encoded within the limits above. There is no redaction hook: anything in a Runtime value is visible to the peer. Do not attach an Agent to a Runtime holding secrets you would not show the Inspector's user.
|
|
228
|
+
- **What a peer cannot do.** Mutate State, invoke Methods, evaluate code, or reach Runtime, Blueprint or DOM objects: only JSON DTOs cross the boundary.
|
|
229
|
+
- **The Runtime is read-only; the page is not untouched.** While Inspect mode is enabled the Agent installs capture-phase `pointerdown`, `pointerup` and `click` handlers on the inspected root that `preventDefault()` and `stopPropagation()` activation of anchored elements, a capture-phase `keydown` handler (Escape) on the document, and a fixed overlay element (open ShadowRoot) in the inspected document. Renderer elements themselves are never modified.
|
|
230
|
+
- Requests are validated defensively: any failure while handling one answers `internal-error` for that request id (the peer never sees the cause) and the Agent keeps serving, reporting the original exception in its own realm with a queued rethrow (`queueMicrotask(() => { throw error })`, like Core's default for isolated listener failures; Core's `setIsolatedErrorHandler` does not receive it), so it surfaces as an uncaught error in the host; response validation on the client is not recursive on peer-controlled depth.
|
|
231
|
+
|
|
232
|
+
## Known limitations
|
|
233
|
+
|
|
234
|
+
- **Single DOM root.** Anchors are only read inside the one `dom.root`. Content a renderer moves outside it (Teleport/portal, detached overlays) is not inspectable, and clicks on it are not suppressed in Inspect mode.
|
|
235
|
+
- **`hidden` is ambiguous.** `visibility: 'hidden'` covers both "anchors exist but have no layout rect" and "no anchor element exists for the Widget".
|
|
236
|
+
- **Opaque class instances.** Anything that is not a plain object or array (`Date`, `Map`, `Set`, `Error`, class instances) is encoded as `{ type: 'opaque', kind: 'class-instance' }` with no contents.
|
|
237
|
+
- **Display-only value encoding.** Values are bounded and lossy by design (see the limits above); the encoding is not a serialization format.
|
|
238
|
+
- **Not provided:** State/Method diagnostics on the wire, a redaction hook, new value kinds for `Date`/`Map`/`Set`, multiple DOM roots, and any kind of mutation.
|
|
239
|
+
|
|
84
240
|
## Versioning
|
|
85
241
|
|
|
86
242
|
Two independent axes:
|
|
87
243
|
|
|
88
244
|
- **npm semver** governs the TypeScript API. While on `0.x`, a minor release may break it.
|
|
89
|
-
- **Protocol `major.minor`** (`INSPECTOR_PROTOCOL_VERSION`) governs cross-realm compatibility. Minors only add negotiated capabilities; a breaking DTO change bumps the major. An Agent and a Client on different package versions interoperate whenever the protocol major matches.
|
|
245
|
+
- **Protocol `major.minor`** (`INSPECTOR_PROTOCOL_VERSION`) governs cross-realm compatibility. Minors only add negotiated capabilities, and every params validator ignores unknown extra fields, so a newer peer's additions never break an older one; a breaking DTO change bumps the major. An Agent and a Client on different package versions interoperate whenever the protocol major matches. A peer negotiated at an older minor sees exactly the wire shapes of that minor, except for the behavior changes of the `0.1` release that no minor gates (error answers, the DOM methods of an Agent without the `dom` option, the total value budget, and the way the negotiated minor is set). They are listed in the [migration guide](https://deviltea.github.io/widget/migration/0.1#inspector-protocol-negotiation).
|
|
246
|
+
|
|
247
|
+
| Protocol minor | Added |
|
|
248
|
+
| --- | --- |
|
|
249
|
+
| 0.1 | Handshake, Runtime list, Blueprint/Widget snapshots, member subscriptions, inspect mode, highlight. |
|
|
250
|
+
| 0.2 | Event subscriptions, Blueprint config/events metadata, geometry and hit-testing. |
|
|
251
|
+
| 0.3 | `subscription-limit` error code. |
|
|
252
|
+
| 0.4 | `authorWritable`, `valueContractId` and `transitivelyEmits` on member DTOs, `runtime.disposed` event, `runtime-disposed` error code, `keyTruncated` marker. |
|
|
253
|
+
|
|
254
|
+
The protocol is currently `0.4`.
|
|
90
255
|
|
|
91
|
-
|
|
256
|
+
**Core peer range.** `@deviltea/widget-core` is a peer dependency published as `^<version>` (the workspace uses `workspace:^`). The Inspector is released together with Core and `@deviltea/widget-vue` under one version, and a breaking change in Core's inspection surface bumps the minor of all of them, so a given Inspector release works with the Core minor it was released with. An Inspector at `0.1.1` accepts Core `>=0.1.1 <0.2.0`; install the packages at the same version. A `^0.0.N` range would pin exactly one Core patch, so the release scripts refuse a `0.0.x` version.
|
package/dist/agent.d.mts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { InspectorTransport } from "./transport.mjs";
|
|
2
|
+
import { i as InspectableValueEncodingOptions } from "./value-Bc7ofk27.mjs";
|
|
2
3
|
import { WidgetSystemRuntime } from "@deviltea/widget-core";
|
|
3
4
|
//#region src/agent.d.ts
|
|
4
5
|
interface InspectorAgentDomOptions {
|
|
@@ -23,6 +24,12 @@ interface CreateInspectorAgentOptions {
|
|
|
23
24
|
* `internal-error` instead). Must be a positive safe integer.
|
|
24
25
|
*/
|
|
25
26
|
readonly maxSubscriptions?: number;
|
|
27
|
+
/**
|
|
28
|
+
* Overrides the limits applied when Runtime values and event arguments are encoded for the wire (see
|
|
29
|
+
* `InspectableValueEncodingOptions`; omitted fields keep `DEFAULT_INSPECTABLE_VALUE_LIMITS`). Every
|
|
30
|
+
* limit must be a positive safe integer; `maxDepth` may also be 0.
|
|
31
|
+
*/
|
|
32
|
+
readonly valueLimits?: Pick<InspectableValueEncodingOptions, 'maxDepth' | 'maxEntries' | 'maxStringLength' | 'maxNodes'>;
|
|
26
33
|
}
|
|
27
34
|
interface InspectorAgent {
|
|
28
35
|
readonly runtimeId: string;
|