@deviltea/widget-inspector 0.0.0 → 0.0.4
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/LICENSE +21 -0
- package/README.md +87 -3
- package/dist/agent.d.mts +36 -0
- package/dist/agent.mjs +1060 -0
- package/dist/anchor.d.mts +29 -0
- package/dist/anchor.mjs +29 -0
- package/dist/channel.d.mts +17 -0
- package/dist/channel.mjs +146 -0
- package/dist/client.d.mts +21 -0
- package/dist/client.mjs +138 -0
- package/dist/frame-bootstrap.d.mts +28 -0
- package/dist/frame-bootstrap.mjs +40 -0
- package/dist/protocol-D1gtirOC.mjs +373 -0
- package/dist/protocol.d.mts +428 -0
- package/dist/protocol.mjs +2 -0
- package/dist/transport.d.mts +27 -0
- package/dist/transport.mjs +138 -0
- package/dist/value-b6hG7snB.d.mts +53 -0
- package/dist/value.d.mts +2 -0
- package/dist/value.mjs +152 -0
- package/package.json +84 -21
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2023 DevilTea
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,7 +1,91 @@
|
|
|
1
1
|
# @deviltea/widget-inspector
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> ESM-only package. **0.x experimental, protocol-major guarantee only.**
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
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.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
```text
|
|
8
|
+
Inspector UI
|
|
9
|
+
|
|
|
10
|
+
InspectorClient (@deviltea/widget-inspector/client)
|
|
11
|
+
|
|
|
12
|
+
InspectorTransport (/transport, /channel; in-process or MessagePort, JSON-safe wire semantics)
|
|
13
|
+
|
|
|
14
|
+
InspectorAgent (/agent)
|
|
15
|
+
|
|
|
16
|
+
@deviltea/widget-core/inspection + inspected DOM (anchors, /anchor)
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Installation
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
pnpm add @deviltea/widget-inspector @deviltea/widget-core
|
|
23
|
+
```
|
|
24
|
+
|
|
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.
|
|
26
|
+
|
|
27
|
+
## Public subpaths
|
|
28
|
+
|
|
29
|
+
There is no root entry; import from exactly these subpaths.
|
|
30
|
+
|
|
31
|
+
| Subpath | Purpose |
|
|
32
|
+
| --- | --- |
|
|
33
|
+
| `/protocol` | Protocol version, DTO types, request/response/event validators and parsers. |
|
|
34
|
+
| `/client` | `createInspectorClient`, the inspecting side. |
|
|
35
|
+
| `/transport` | Transport interface plus in-process and MessagePort transports. |
|
|
36
|
+
| `/channel` | `createMessagePortChannelHub`: several logical transports over one MessagePort. |
|
|
37
|
+
| `/frame-bootstrap` | One-time, validated bootstrap envelope that transfers a dedicated MessagePort into a frame. |
|
|
38
|
+
| `/agent` | `createInspectorAgent`, bound to one Runtime and (optionally) one inspected DOM root. |
|
|
39
|
+
| `/value` | The bounded, accessor-safe `InspectableValue` display encoding. |
|
|
40
|
+
| `/anchor` | `inspectAnchorAttributes` and the anchor attribute names, for renderers. |
|
|
41
|
+
|
|
42
|
+
## Usage
|
|
43
|
+
|
|
44
|
+
```ts
|
|
45
|
+
import { createInspectorAgent } from '@deviltea/widget-inspector/agent'
|
|
46
|
+
import { createInspectorClient } from '@deviltea/widget-inspector/client'
|
|
47
|
+
import { createInProcessInspectorTransportPair } from '@deviltea/widget-inspector/transport'
|
|
48
|
+
|
|
49
|
+
const pair = createInProcessInspectorTransportPair()
|
|
50
|
+
const agent = createInspectorAgent({ runtime, transport: pair.agent, dom: { root: document.getElementById('app')! } })
|
|
51
|
+
const client = createInspectorClient(pair.client)
|
|
52
|
+
|
|
53
|
+
await client.handshake()
|
|
54
|
+
const { runtimes } = await client.request('runtime.list', {})
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
The boundary is read-only: no state mutation, Method invocation, eval, generic object RPC, or Runtime discovery global hook.
|
|
58
|
+
|
|
59
|
+
### Anchors
|
|
60
|
+
|
|
61
|
+
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
|
+
|
|
63
|
+
```ts
|
|
64
|
+
import { inspectAnchorAttributes } from '@deviltea/widget-inspector/anchor'
|
|
65
|
+
|
|
66
|
+
const { widgetId, widgetType } = useWidget(MyPlugin)
|
|
67
|
+
const anchor = inspectAnchorAttributes({ widgetId, widgetType })
|
|
68
|
+
// h('div', { ...anchor }) or <div v-bind="anchor">
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
- An anchor is any renderer-owned element carrying both attributes. Several elements may mark one Widget; each contributes to `rects[]` in document order. No wrapper element is needed.
|
|
72
|
+
- The innermost resolvable anchor wins hit-testing.
|
|
73
|
+
- Anchors live and die with the renderer's DOM. There is no register or cleanup API.
|
|
74
|
+
- Anchors carry identity only (`widgetId`, `widgetType`), never Runtime or root identity. The Agent binds one Runtime to one root and resolves the attributes against Core inspection, so stale values resolve to no target.
|
|
75
|
+
|
|
76
|
+
### Highlight
|
|
77
|
+
|
|
78
|
+
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
|
+
|
|
80
|
+
### Subscription cap
|
|
81
|
+
|
|
82
|
+
`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
|
+
|
|
84
|
+
## Versioning
|
|
85
|
+
|
|
86
|
+
Two independent axes:
|
|
87
|
+
|
|
88
|
+
- **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.
|
|
90
|
+
|
|
91
|
+
The protocol is currently `0.3`; `subscription-limit` requires `0.3`, and peers negotiated at an older minor never receive it.
|
package/dist/agent.d.mts
ADDED
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import { InspectorTransport } from "./transport.mjs";
|
|
2
|
+
import { WidgetSystemRuntime } from "@deviltea/widget-core";
|
|
3
|
+
//#region src/agent.d.ts
|
|
4
|
+
interface InspectorAgentDomOptions {
|
|
5
|
+
/**
|
|
6
|
+
* The inspected renderer root. Anchors (see `@deviltea/widget-inspector/anchor`) are only read from
|
|
7
|
+
* inside it. The Agent never mutates renderer elements: highlight chrome is an Agent-owned
|
|
8
|
+
* ShadowRoot overlay attached to the root's document.
|
|
9
|
+
*/
|
|
10
|
+
readonly root: HTMLElement;
|
|
11
|
+
}
|
|
12
|
+
interface CreateInspectorAgentOptions {
|
|
13
|
+
readonly runtime: WidgetSystemRuntime;
|
|
14
|
+
readonly transport: InspectorTransport;
|
|
15
|
+
readonly runtimeId?: string;
|
|
16
|
+
readonly dom?: InspectorAgentDomOptions;
|
|
17
|
+
/** Keep a host-owned shared transport alive when replacing only this Agent/Runtime binding. */
|
|
18
|
+
readonly closeTransportOnDispose?: boolean;
|
|
19
|
+
/**
|
|
20
|
+
* Optional cap on this Agent's live Runtime member and event subscriptions, counted together.
|
|
21
|
+
* There is no default: unlimited unless configured. Once the cap is reached, further subscribe
|
|
22
|
+
* requests fail with `subscription-limit` (protocol 0.3+; an older-minor peer receives
|
|
23
|
+
* `internal-error` instead). Must be a positive safe integer.
|
|
24
|
+
*/
|
|
25
|
+
readonly maxSubscriptions?: number;
|
|
26
|
+
}
|
|
27
|
+
interface InspectorAgent {
|
|
28
|
+
readonly runtimeId: string;
|
|
29
|
+
readonly inspectEnabled: boolean;
|
|
30
|
+
/** Host-owned hint after CSSOM/adoptedStyleSheets changes; no Client mutation RPC is exposed. */
|
|
31
|
+
invalidateGeometry: () => void;
|
|
32
|
+
dispose: () => void;
|
|
33
|
+
}
|
|
34
|
+
declare function createInspectorAgent(options: CreateInspectorAgentOptions): InspectorAgent;
|
|
35
|
+
//#endregion
|
|
36
|
+
export { CreateInspectorAgentOptions, InspectorAgent, InspectorAgentDomOptions, createInspectorAgent };
|