@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.
@@ -0,0 +1,29 @@
1
+ //#region src/anchor.d.ts
2
+ /**
3
+ * Inspect-anchor contract between a renderer (the writer) and `InspectorAgent` (the reader).
4
+ *
5
+ * An anchor is any renderer-owned element carrying both attributes. Anchors carry identity only
6
+ * (`widgetId` and `widgetType`): the Agent binds one Runtime to one inspected root and resolves the
7
+ * pair against Core inspection, so stale or unknown values simply resolve to no target. Several
8
+ * elements may mark the same Widget (each contributes a rect in document order), anchors may nest
9
+ * (the innermost resolvable anchor wins hit-testing), and anchors live and die with the renderer's
10
+ * DOM: there is no register or cleanup API.
11
+ *
12
+ * This module is framework-neutral and DOM-independent so any renderer can reuse it.
13
+ * `@deviltea/widget-vue` deliberately stamps no DOM attributes itself; a renderer or application
14
+ * projects `useWidget()` identity through {@link inspectAnchorAttributes}.
15
+ */
16
+ declare const INSPECT_ANCHOR_ID_ATTRIBUTE = "data-widget-id";
17
+ declare const INSPECT_ANCHOR_TYPE_ATTRIBUTE = "data-widget-type";
18
+ interface InspectAnchorIdentity {
19
+ readonly widgetId: string;
20
+ readonly widgetType: string;
21
+ }
22
+ type InspectAnchorAttributes = Readonly<Record<typeof INSPECT_ANCHOR_ID_ATTRIBUTE | typeof INSPECT_ANCHOR_TYPE_ATTRIBUTE, string>>;
23
+ /**
24
+ * Returns the plain attribute record a renderer spreads onto (or `v-bind`s to) its rendered element.
25
+ * The values are plain and non-reactive, so the record is safe to create once per mounted renderer.
26
+ */
27
+ declare function inspectAnchorAttributes(identity: InspectAnchorIdentity): InspectAnchorAttributes;
28
+ //#endregion
29
+ export { INSPECT_ANCHOR_ID_ATTRIBUTE, INSPECT_ANCHOR_TYPE_ATTRIBUTE, InspectAnchorAttributes, InspectAnchorIdentity, inspectAnchorAttributes };
@@ -0,0 +1,29 @@
1
+ //#region src/anchor.ts
2
+ /**
3
+ * Inspect-anchor contract between a renderer (the writer) and `InspectorAgent` (the reader).
4
+ *
5
+ * An anchor is any renderer-owned element carrying both attributes. Anchors carry identity only
6
+ * (`widgetId` and `widgetType`): the Agent binds one Runtime to one inspected root and resolves the
7
+ * pair against Core inspection, so stale or unknown values simply resolve to no target. Several
8
+ * elements may mark the same Widget (each contributes a rect in document order), anchors may nest
9
+ * (the innermost resolvable anchor wins hit-testing), and anchors live and die with the renderer's
10
+ * DOM: there is no register or cleanup API.
11
+ *
12
+ * This module is framework-neutral and DOM-independent so any renderer can reuse it.
13
+ * `@deviltea/widget-vue` deliberately stamps no DOM attributes itself; a renderer or application
14
+ * projects `useWidget()` identity through {@link inspectAnchorAttributes}.
15
+ */
16
+ const INSPECT_ANCHOR_ID_ATTRIBUTE = "data-widget-id";
17
+ const INSPECT_ANCHOR_TYPE_ATTRIBUTE = "data-widget-type";
18
+ /**
19
+ * Returns the plain attribute record a renderer spreads onto (or `v-bind`s to) its rendered element.
20
+ * The values are plain and non-reactive, so the record is safe to create once per mounted renderer.
21
+ */
22
+ function inspectAnchorAttributes(identity) {
23
+ return {
24
+ [INSPECT_ANCHOR_ID_ATTRIBUTE]: identity.widgetId,
25
+ [INSPECT_ANCHOR_TYPE_ATTRIBUTE]: identity.widgetType
26
+ };
27
+ }
28
+ //#endregion
29
+ export { INSPECT_ANCHOR_ID_ATTRIBUTE, INSPECT_ANCHOR_TYPE_ATTRIBUTE, inspectAnchorAttributes };
@@ -0,0 +1,17 @@
1
+ import { InspectorTransport } from "./transport.mjs";
2
+ //#region src/channel.d.ts
3
+ interface MessagePortChannelHub {
4
+ readonly closed: boolean;
5
+ openChannel: (name: string) => InspectorTransport;
6
+ close: () => void;
7
+ }
8
+ /**
9
+ * Multiplexes independent JSON-safe logical transports over one MessagePort.
10
+ *
11
+ * Channel `close()` is deliberately scoped: InspectorClient/InspectorAgent may dispose their own
12
+ * logical channel without tearing down the frame-host control channel. Closing the hub (or the native
13
+ * peer port) disconnects every logical channel.
14
+ */
15
+ declare function createMessagePortChannelHub(port: MessagePort): MessagePortChannelHub;
16
+ //#endregion
17
+ export { MessagePortChannelHub, createMessagePortChannelHub };
@@ -0,0 +1,146 @@
1
+ //#region src/channel.ts
2
+ const MESSAGE_PORT_CHANNEL_TYPE = "@deviltea/widget-inspector/message-port-channel";
3
+ const MESSAGE_PORT_CHANNEL_HUB_TYPE = "@deviltea/widget-inspector/message-port-channel-hub";
4
+ function cloneJson(message) {
5
+ const serialized = JSON.stringify(message);
6
+ if (serialized === void 0) throw new TypeError("MessagePort channel messages must be JSON-serializable.");
7
+ return JSON.parse(serialized);
8
+ }
9
+ function isEnvelope(value) {
10
+ if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
11
+ const candidate = value;
12
+ return candidate.type === MESSAGE_PORT_CHANNEL_TYPE && typeof candidate.channel === "string" && candidate.channel.length > 0 && (candidate.kind === "message" || candidate.kind === "close") && (candidate.kind !== "message" || "payload" in candidate);
13
+ }
14
+ function isHubCloseEnvelope(value) {
15
+ if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
16
+ const candidate = value;
17
+ return candidate.type === MESSAGE_PORT_CHANNEL_HUB_TYPE && candidate.version === 1 && candidate.kind === "close";
18
+ }
19
+ /**
20
+ * Multiplexes independent JSON-safe logical transports over one MessagePort.
21
+ *
22
+ * Channel `close()` is deliberately scoped: InspectorClient/InspectorAgent may dispose their own
23
+ * logical channel without tearing down the frame-host control channel. Closing the hub (or the native
24
+ * peer port) disconnects every logical channel.
25
+ */
26
+ function createMessagePortChannelHub(port) {
27
+ const states = /* @__PURE__ */ new Map();
28
+ let closed = false;
29
+ function stateFor(name) {
30
+ let state = states.get(name);
31
+ if (state === void 0) {
32
+ state = {
33
+ messageListeners: /* @__PURE__ */ new Set(),
34
+ closeListeners: /* @__PURE__ */ new Set(),
35
+ closed
36
+ };
37
+ states.set(name, state);
38
+ }
39
+ return state;
40
+ }
41
+ function markChannelClosed(state) {
42
+ if (state.closed) return;
43
+ state.closed = true;
44
+ state.messageListeners.clear();
45
+ const listeners = [...state.closeListeners];
46
+ state.closeListeners.clear();
47
+ for (const listener of listeners) listener();
48
+ }
49
+ function markHubClosed() {
50
+ if (closed) return;
51
+ closed = true;
52
+ port.removeEventListener("message", onMessage);
53
+ port.removeEventListener("close", onPortClose);
54
+ for (const state of states.values()) markChannelClosed(state);
55
+ }
56
+ function onMessage(event) {
57
+ if (closed) return;
58
+ if (isHubCloseEnvelope(event.data)) {
59
+ try {
60
+ markHubClosed();
61
+ } finally {
62
+ port.close();
63
+ }
64
+ return;
65
+ }
66
+ if (!isEnvelope(event.data)) return;
67
+ const envelope = event.data;
68
+ const state = stateFor(envelope.channel);
69
+ if (state.closed) return;
70
+ if (envelope.kind === "close") {
71
+ markChannelClosed(state);
72
+ return;
73
+ }
74
+ for (const listener of [...state.messageListeners]) listener(envelope.payload);
75
+ }
76
+ function onPortClose() {
77
+ markHubClosed();
78
+ }
79
+ port.addEventListener("message", onMessage);
80
+ port.addEventListener("close", onPortClose);
81
+ port.start();
82
+ return {
83
+ get closed() {
84
+ return closed;
85
+ },
86
+ openChannel(name) {
87
+ if (name.length === 0) throw new TypeError("MessagePort channel name must not be empty.");
88
+ const state = stateFor(name);
89
+ return {
90
+ get closed() {
91
+ return state.closed;
92
+ },
93
+ send(message) {
94
+ if (closed || state.closed) throw new Error("Inspector transport is closed.");
95
+ const envelope = {
96
+ type: MESSAGE_PORT_CHANNEL_TYPE,
97
+ channel: name,
98
+ kind: "message",
99
+ payload: cloneJson(message)
100
+ };
101
+ port.postMessage(envelope);
102
+ },
103
+ subscribe(listener) {
104
+ if (closed || state.closed) return () => {};
105
+ state.messageListeners.add(listener);
106
+ return () => state.messageListeners.delete(listener);
107
+ },
108
+ subscribeClose(listener) {
109
+ if (closed || state.closed) {
110
+ listener();
111
+ return () => {};
112
+ }
113
+ state.closeListeners.add(listener);
114
+ return () => state.closeListeners.delete(listener);
115
+ },
116
+ close() {
117
+ if (closed || state.closed) return;
118
+ port.postMessage({
119
+ type: MESSAGE_PORT_CHANNEL_TYPE,
120
+ channel: name,
121
+ kind: "close"
122
+ });
123
+ markChannelClosed(state);
124
+ }
125
+ };
126
+ },
127
+ close() {
128
+ if (closed) return;
129
+ const envelope = {
130
+ type: MESSAGE_PORT_CHANNEL_HUB_TYPE,
131
+ version: 1,
132
+ kind: "close"
133
+ };
134
+ try {
135
+ port.postMessage(envelope);
136
+ } catch {}
137
+ try {
138
+ markHubClosed();
139
+ } finally {
140
+ port.close();
141
+ }
142
+ }
143
+ };
144
+ }
145
+ //#endregion
146
+ export { createMessagePortChannelHub };
@@ -0,0 +1,21 @@
1
+ import { InspectorTransport } from "./transport.mjs";
2
+ import { InspectorEventMap, InspectorEventMessage, InspectorEventName, InspectorProtocolError, InspectorRequestMethod, InspectorRequestParams, InspectorRequestResult } from "./protocol.mjs";
3
+ //#region src/client.d.ts
4
+ declare class InspectorClientError extends Error {
5
+ readonly name = "InspectorClientError";
6
+ readonly code: InspectorProtocolError['code'];
7
+ readonly protocolError: InspectorProtocolError;
8
+ constructor(error: InspectorProtocolError);
9
+ }
10
+ interface InspectorClient {
11
+ handshake: () => Promise<InspectorRequestResult<'handshake'>>;
12
+ request: <Method extends InspectorRequestMethod>(method: Method, params: InspectorRequestParams<Method>) => Promise<InspectorRequestResult<Method>>;
13
+ subscribe: (listener: (event: InspectorEventMessage) => void) => () => void;
14
+ on: <Event extends InspectorEventName>(event: Event, listener: (payload: InspectorEventMap[Event]) => void) => () => void;
15
+ close: () => void;
16
+ /** Alias retained for owner-lifecycle terminology used by Lab integration/tests. */
17
+ dispose: () => void;
18
+ }
19
+ declare function createInspectorClient(transport: InspectorTransport): InspectorClient;
20
+ //#endregion
21
+ export { InspectorClient, InspectorClientError, createInspectorClient };
@@ -0,0 +1,138 @@
1
+ import { a as isInspectorRequestResult, c as parseInspectorResponseMessage, n as isCompatibleProtocolVersion, o as parseInspectorEventMessage, t as INSPECTOR_PROTOCOL_VERSION } from "./protocol-D1gtirOC.mjs";
2
+ //#region src/client.ts
3
+ var InspectorClientError = class extends Error {
4
+ name = "InspectorClientError";
5
+ code;
6
+ protocolError;
7
+ constructor(error) {
8
+ super(error.message);
9
+ this.code = error.code;
10
+ this.protocolError = error;
11
+ }
12
+ };
13
+ function malformedResponseRequestId(value) {
14
+ if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
15
+ const candidate = value;
16
+ return candidate.kind === "response" && typeof candidate.requestId === "string" ? candidate.requestId : null;
17
+ }
18
+ function createInspectorClient(transport) {
19
+ let requestSequence = 0;
20
+ let closed = false;
21
+ const pending = /* @__PURE__ */ new Map();
22
+ const eventListeners = /* @__PURE__ */ new Map();
23
+ const messageListeners = /* @__PURE__ */ new Set();
24
+ let unsubscribeMessages = () => {};
25
+ let unsubscribeClose = () => {};
26
+ function finalizeClose(message, closeTransport) {
27
+ if (closed) return;
28
+ closed = true;
29
+ unsubscribeMessages();
30
+ unsubscribeClose();
31
+ for (const entry of pending.values()) entry.reject(new InspectorClientError({
32
+ code: "disconnected",
33
+ message
34
+ }));
35
+ pending.clear();
36
+ eventListeners.clear();
37
+ messageListeners.clear();
38
+ if (closeTransport && !transport.closed) transport.close();
39
+ }
40
+ unsubscribeMessages = transport.subscribe((rawMessage) => {
41
+ const event = parseInspectorEventMessage(rawMessage);
42
+ if (event !== null && isCompatibleProtocolVersion(event.protocol)) {
43
+ for (const listener of [...messageListeners]) listener(event);
44
+ const listeners = eventListeners.get(event.event);
45
+ if (listeners !== void 0) for (const listener of [...listeners]) listener(event.payload);
46
+ return;
47
+ }
48
+ const response = parseInspectorResponseMessage(rawMessage);
49
+ if (response === null) {
50
+ const requestId = malformedResponseRequestId(rawMessage);
51
+ const entry = requestId === null ? void 0 : pending.get(requestId);
52
+ if (requestId !== null && entry !== void 0) {
53
+ pending.delete(requestId);
54
+ entry.reject(new InspectorClientError({
55
+ code: "invalid-message",
56
+ message: "Invalid Inspector protocol response envelope."
57
+ }));
58
+ }
59
+ return;
60
+ }
61
+ const entry = pending.get(response.requestId);
62
+ if (entry === void 0) return;
63
+ pending.delete(response.requestId);
64
+ if (!isCompatibleProtocolVersion(response.protocol)) {
65
+ entry.reject(new InspectorClientError({
66
+ code: "unsupported-version",
67
+ message: "Inspector response uses an incompatible protocol major version."
68
+ }));
69
+ return;
70
+ }
71
+ if (!response.ok) {
72
+ entry.reject(new InspectorClientError(response.error));
73
+ return;
74
+ }
75
+ if (!isInspectorRequestResult(entry.method, response.result, response.protocol.minor)) {
76
+ entry.reject(new InspectorClientError({
77
+ code: "invalid-message",
78
+ message: `Invalid ${entry.method} response payload.`
79
+ }));
80
+ return;
81
+ }
82
+ entry.resolve(response.result);
83
+ });
84
+ unsubscribeClose = transport.subscribeClose(() => {
85
+ finalizeClose("Inspector transport disconnected.", false);
86
+ });
87
+ function request(method, params) {
88
+ if (closed || transport.closed) return Promise.reject(new InspectorClientError({
89
+ code: "disconnected",
90
+ message: "Inspector client is disconnected."
91
+ }));
92
+ const requestId = `request-${++requestSequence}`;
93
+ return new Promise((resolve, reject) => {
94
+ pending.set(requestId, {
95
+ method,
96
+ resolve,
97
+ reject
98
+ });
99
+ try {
100
+ transport.send({
101
+ protocol: INSPECTOR_PROTOCOL_VERSION,
102
+ kind: "request",
103
+ requestId,
104
+ method,
105
+ params
106
+ });
107
+ } catch (error) {
108
+ pending.delete(requestId);
109
+ reject(error);
110
+ }
111
+ });
112
+ }
113
+ function close() {
114
+ finalizeClose("Inspector client was closed.", true);
115
+ }
116
+ return {
117
+ handshake: () => request("handshake", { protocol: INSPECTOR_PROTOCOL_VERSION }),
118
+ request,
119
+ subscribe(listener) {
120
+ messageListeners.add(listener);
121
+ return () => messageListeners.delete(listener);
122
+ },
123
+ on(event, listener) {
124
+ let listeners = eventListeners.get(event);
125
+ if (listeners === void 0) {
126
+ listeners = /* @__PURE__ */ new Set();
127
+ eventListeners.set(event, listeners);
128
+ }
129
+ const erased = listener;
130
+ listeners.add(erased);
131
+ return () => listeners.delete(erased);
132
+ },
133
+ close,
134
+ dispose: close
135
+ };
136
+ }
137
+ //#endregion
138
+ export { InspectorClientError, createInspectorClient };
@@ -0,0 +1,28 @@
1
+ //#region src/frame-bootstrap.d.ts
2
+ declare const INSPECTOR_FRAME_BOOTSTRAP_TYPE = "@deviltea/widget-inspector/frame-bootstrap";
3
+ declare const INSPECTOR_FRAME_BOOTSTRAP_VERSION = 1;
4
+ interface InspectorFrameBootstrapRequest {
5
+ readonly type: typeof INSPECTOR_FRAME_BOOTSTRAP_TYPE;
6
+ readonly version: typeof INSPECTOR_FRAME_BOOTSTRAP_VERSION;
7
+ readonly sessionId: string;
8
+ readonly generation: number;
9
+ }
10
+ interface InspectorFrameBootstrapAcceptance {
11
+ readonly request: InspectorFrameBootstrapRequest;
12
+ readonly port: MessagePort;
13
+ }
14
+ interface AcceptInspectorFrameBootstrapOptions {
15
+ readonly expectedSource: MessageEventSource;
16
+ readonly expectedOrigin: string;
17
+ readonly sessionId: string;
18
+ readonly expectedGeneration: number;
19
+ }
20
+ declare function createInspectorFrameBootstrapRequest(sessionId: string, generation: number): InspectorFrameBootstrapRequest;
21
+ declare function parseInspectorFrameBootstrapRequest(value: unknown): InspectorFrameBootstrapRequest | null;
22
+ /**
23
+ * Validate the one global-window message used to bootstrap a dedicated frame channel.
24
+ * Ordinary Inspector traffic must continue only on the returned MessagePort.
25
+ */
26
+ declare function acceptInspectorFrameBootstrap(event: MessageEvent<unknown>, options: AcceptInspectorFrameBootstrapOptions): InspectorFrameBootstrapAcceptance | null;
27
+ //#endregion
28
+ export { AcceptInspectorFrameBootstrapOptions, INSPECTOR_FRAME_BOOTSTRAP_TYPE, INSPECTOR_FRAME_BOOTSTRAP_VERSION, InspectorFrameBootstrapAcceptance, InspectorFrameBootstrapRequest, acceptInspectorFrameBootstrap, createInspectorFrameBootstrapRequest, parseInspectorFrameBootstrapRequest };
@@ -0,0 +1,40 @@
1
+ //#region src/frame-bootstrap.ts
2
+ const INSPECTOR_FRAME_BOOTSTRAP_TYPE = "@deviltea/widget-inspector/frame-bootstrap";
3
+ const INSPECTOR_FRAME_BOOTSTRAP_VERSION = 1;
4
+ function isRecord(value) {
5
+ return typeof value === "object" && value !== null && !Array.isArray(value);
6
+ }
7
+ function createInspectorFrameBootstrapRequest(sessionId, generation) {
8
+ if (sessionId.length === 0) throw new TypeError("Inspector frame bootstrap sessionId must not be empty.");
9
+ if (!Number.isSafeInteger(generation) || generation < 0) throw new TypeError("Inspector frame bootstrap generation must be a non-negative safe integer.");
10
+ return {
11
+ type: INSPECTOR_FRAME_BOOTSTRAP_TYPE,
12
+ version: 1,
13
+ sessionId,
14
+ generation
15
+ };
16
+ }
17
+ function parseInspectorFrameBootstrapRequest(value) {
18
+ if (!isRecord(value) || value.type !== "@deviltea/widget-inspector/frame-bootstrap" || value.version !== 1 || typeof value.sessionId !== "string" || value.sessionId.length === 0 || typeof value.generation !== "number" || !Number.isSafeInteger(value.generation) || value.generation < 0) return null;
19
+ return {
20
+ type: INSPECTOR_FRAME_BOOTSTRAP_TYPE,
21
+ version: 1,
22
+ sessionId: value.sessionId,
23
+ generation: value.generation
24
+ };
25
+ }
26
+ /**
27
+ * Validate the one global-window message used to bootstrap a dedicated frame channel.
28
+ * Ordinary Inspector traffic must continue only on the returned MessagePort.
29
+ */
30
+ function acceptInspectorFrameBootstrap(event, options) {
31
+ if (event.source !== options.expectedSource || event.origin !== options.expectedOrigin) return null;
32
+ const request = parseInspectorFrameBootstrapRequest(event.data);
33
+ if (request === null || request.sessionId !== options.sessionId || request.generation !== options.expectedGeneration || event.ports.length !== 1) return null;
34
+ return {
35
+ request,
36
+ port: event.ports[0]
37
+ };
38
+ }
39
+ //#endregion
40
+ export { INSPECTOR_FRAME_BOOTSTRAP_TYPE, INSPECTOR_FRAME_BOOTSTRAP_VERSION, acceptInspectorFrameBootstrap, createInspectorFrameBootstrapRequest, parseInspectorFrameBootstrapRequest };