@shadow-js/devtools 0.0.0-stage → 1.0.1

package/dist/dev/agent.js

@@ -0,0 +1,626 @@
+import { EVENT } from "./protocol.js";
+import { errorMessage, parseEditableText, preview, toEditableText } from "./preview.js";
+import { readInspections } from "./inspection.js";
+import { snapshotOf } from "./inspector.js";
+import { RingBuffer } from "./ring.js";
+import { InspectorModel } from "./model.js";
+//#region src/agent.ts
+function now() {
+	return typeof performance !== "undefined" ? performance.now() : Date.now();
+}
+function isObject(value) {
+	return typeof value === "object" && value !== null || typeof value === "function";
+}
+function toNumber(value) {
+	return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+function describeSide(value) {
+	if (typeof value === "string") return value.length > 200 ? `${value.slice(0, 199)}…` : value;
+	if (typeof Node !== "undefined" && value instanceof Node) {
+		if (value instanceof Element) {
+			const html = value.outerHTML;
+			return html.length > 200 ? `${html.slice(0, 199)}…` : html;
+		}
+		return `#${value.nodeName}`;
+	}
+	return preview(value, 200);
+}
+/**
+* Creates an agent that records the runtime's events. Attach it to a hook with `agent.attach(hook)`.
+* A development tool: the events come only from development builds, where the hook is installed.
+*
+* @param options Buffer sizes, clock and the signal writer. Every field is optional.
+* @returns The agent.
+* @example
+* import { createAgent, installHook } from "@shadow-js/devtools";
+* import { writeSignal } from "@shadow-js/core/extend";
+*
+* const hook = installHook();
+* const agent = createAgent({ writeSignal });
+* if (hook !== undefined) agent.attach(hook);
+* agent.snapshot().counts.nodes;
+* @since 1.0.0
+*/
+function createAgent(options = {}) {
+	const clock = options.now ?? now;
+	const previewLength = options.previewLength ?? 80;
+	const maxPending = options.maxPending ?? 1e4;
+	const model = new InspectorModel(options.limits);
+	const events = new RingBuffer(options.events ?? 1e4);
+	const stats = {
+		received: 0,
+		recorded: 0,
+		ignored: 0,
+		unknown: 0
+	};
+	const ids = /* @__PURE__ */ new WeakMap();
+	const ignored = /* @__PURE__ */ new WeakSet();
+	const signals = /* @__PURE__ */ new Map();
+	const components = /* @__PURE__ */ new Map();
+	const stores = /* @__PURE__ */ new Map();
+	let nextId = 1;
+	let seq = 0;
+	let paused = false;
+	let quietDepth = 0;
+	/** The hook the agent listens to: its registry of inspection sources answers `inspect`. */
+	let inspectionHook;
+	let pending = [];
+	let scheduled = false;
+	/** A flush that started but has not recorded any run yet: empty flushes are not worth a record. */
+	let queuedFlush = null;
+	let flushOpen = false;
+	const listeners = /* @__PURE__ */ new Set();
+	const detachers = /* @__PURE__ */ new Set();
+	const finalizer = typeof FinalizationRegistry === "function" ? new FinalizationRegistry((id) => {
+		signals.delete(id);
+		stores.delete(id);
+		if (model.nodes.has(id)) emit({
+			k: "owner-",
+			seq: 0,
+			t: 0,
+			id
+		});
+	}) : void 0;
+	model.onBury = (record) => {
+		signals.delete(record.id);
+		components.delete(record.id);
+		stores.delete(record.id);
+	};
+	const deliver = () => {
+		scheduled = false;
+		if (pending.length === 0) return;
+		const batch = pending;
+		pending = [];
+		for (const listener of listeners) listener(batch);
+	};
+	/** Stamps, records and fans out one event. */
+	function emit(event, at) {
+		seq += 1;
+		event.seq = seq;
+		event.t = at ?? clock();
+		stats.recorded += 1;
+		events.push(event);
+		model.apply(event);
+		if (listeners.size === 0) return;
+		pending.push(event);
+		if (pending.length >= maxPending) deliver();
+		else if (!scheduled) {
+			scheduled = true;
+			queueMicrotask(deliver);
+		}
+	}
+	/** Emits the held-back flush start before the first event that belongs to it. */
+	const openFlush = () => {
+		if (queuedFlush === null) return;
+		const held = queuedFlush;
+		queuedFlush = null;
+		flushOpen = true;
+		emit({
+			k: "flush+",
+			seq: 0,
+			t: 0,
+			render: held.render,
+			user: held.user
+		}, held.t);
+	};
+	const lookup = (value) => {
+		if (!isObject(value)) return 0;
+		return ids.get(value) ?? 0;
+	};
+	const register = (value) => {
+		const existing = ids.get(value);
+		if (existing !== void 0) return existing;
+		const id = nextId;
+		nextId += 1;
+		ids.set(value, id);
+		return id;
+	};
+	/**
+	* Like `register`, for a leaf node (signal, store, resource): the finalizer retires it once the runtime
+	* has collected the object. Owners and computations are not registered: an owner can be unreachable
+	* while its signals are still in use, and retiring it would bury them too.
+	*/
+	const registerLeaf = (value) => {
+		const existing = ids.get(value);
+		if (existing !== void 0) return existing;
+		const id = register(value);
+		finalizer?.register(value, id);
+		return id;
+	};
+	/** True (and remembered) when the object belongs to the tools' own UI. */
+	const isIgnored = (value, parent) => {
+		if (!isObject(value)) return false;
+		if (quietDepth > 0 || isObject(parent) && ignored.has(parent)) {
+			ignored.add(value);
+			return true;
+		}
+		return ignored.has(value);
+	};
+	const mapIds = (values) => {
+		const out = [];
+		if (!Array.isArray(values)) return out;
+		for (let i = 0; i < values.length; i += 1) {
+			const id = lookup(values[i]);
+			if (id !== 0) out.push(id);
+		}
+		return out;
+	};
+	const nodesIn = (value) => {
+		const out = [];
+		if (typeof Node === "undefined") return out;
+		const push = (candidate) => {
+			if (candidate instanceof DocumentFragment) for (const child of Array.from(candidate.childNodes)) out.push(new WeakRef(child));
+			else if (candidate instanceof Node) out.push(new WeakRef(candidate));
+		};
+		if (Array.isArray(value)) for (const entry of value) push(entry);
+		else push(value);
+		return out;
+	};
+	function receive(kind, a, b, c, d, e) {
+		if (paused) return;
+		stats.received += 1;
+		switch (kind) {
+			case EVENT.OWNER_CREATED: {
+				if (!isObject(a) || isIgnored(a, b)) {
+					stats.ignored += 1;
+					return;
+				}
+				const name = typeof d === "string" ? d : void 0;
+				emit({
+					k: "owner+",
+					seq: 0,
+					t: 0,
+					id: register(a),
+					parent: lookup(b),
+					label: typeof c === "string" ? c : "owner",
+					...name === void 0 ? {} : { name }
+				});
+				return;
+			}
+			case EVENT.OWNER_DISPOSED: {
+				const id = lookup(a);
+				if (id === 0) {
+					stats.ignored += 1;
+					return;
+				}
+				emit({
+					k: "owner-",
+					seq: 0,
+					t: 0,
+					id
+				});
+				return;
+			}
+			case EVENT.SIGNAL_CREATED: {
+				if (!isObject(a) || isIgnored(a, b)) {
+					stats.ignored += 1;
+					return;
+				}
+				const id = registerLeaf(a);
+				signals.set(id, new WeakRef(a));
+				const name = typeof c === "string" ? c : void 0;
+				emit({
+					k: "signal+",
+					seq: 0,
+					t: 0,
+					id,
+					owner: lookup(b),
+					preview: preview(d, previewLength),
+					...name === void 0 ? {} : { name }
+				});
+				return;
+			}
+			case EVENT.SIGNAL_WRITTEN: {
+				const id = lookup(a);
+				if (id === 0) {
+					if (isObject(a) && ignored.has(a)) stats.ignored += 1;
+					else stats.unknown += 1;
+					return;
+				}
+				emit({
+					k: "write",
+					seq: 0,
+					t: 0,
+					id,
+					preview: preview(b, previewLength),
+					writer: lookup(c),
+					observers: mapIds(d)
+				});
+				return;
+			}
+			case EVENT.COMPUTATION_CREATED: {
+				if (!isObject(a) || isIgnored(a, b)) {
+					stats.ignored += 1;
+					return;
+				}
+				const name = typeof d === "string" ? d : void 0;
+				emit({
+					k: "comp+",
+					seq: 0,
+					t: 0,
+					id: register(a),
+					owner: lookup(b),
+					kind: c === "memo" ? "memo" : "effect",
+					render: e === true,
+					...name === void 0 ? {} : { name }
+				});
+				return;
+			}
+			case EVENT.COMPUTATION_RUN: {
+				const id = lookup(a);
+				if (id === 0) {
+					if (isObject(a) && ignored.has(a)) stats.ignored += 1;
+					else stats.unknown += 1;
+					return;
+				}
+				openFlush();
+				emit({
+					k: "run",
+					seq: 0,
+					t: 0,
+					id,
+					start: toNumber(b),
+					duration: toNumber(c),
+					changed: d === true,
+					sources: mapIds(e)
+				});
+				return;
+			}
+			case EVENT.COMPUTATION_DISPOSED: {
+				const id = lookup(a);
+				if (id === 0) {
+					stats.ignored += 1;
+					return;
+				}
+				emit({
+					k: "comp-",
+					seq: 0,
+					t: 0,
+					id
+				});
+				return;
+			}
+			case EVENT.COMPONENT_MOUNTED: {
+				const id = lookup(a);
+				if (id === 0) {
+					if (isObject(a) && ignored.has(a)) stats.ignored += 1;
+					else stats.unknown += 1;
+					return;
+				}
+				const refs = nodesIn(c);
+				if (refs.length > 0) components.set(id, refs);
+				emit({
+					k: "mount",
+					seq: 0,
+					t: 0,
+					id,
+					name: typeof b === "string" ? b : "Component"
+				});
+				if (!model.nodes.has(id)) components.delete(id);
+				return;
+			}
+			case EVENT.COMPONENT_UNMOUNTED: {
+				const id = lookup(a);
+				if (id === 0) {
+					stats.ignored += 1;
+					return;
+				}
+				components.delete(id);
+				emit({
+					k: "unmount",
+					seq: 0,
+					t: 0,
+					id
+				});
+				return;
+			}
+			case EVENT.RESOURCE_STATE: {
+				if (!isObject(a) || isIgnored(a, d)) {
+					stats.ignored += 1;
+					return;
+				}
+				const name = typeof c === "string" ? c : void 0;
+				emit({
+					k: "resource",
+					seq: 0,
+					t: 0,
+					id: registerLeaf(a),
+					owner: lookup(d),
+					state: typeof b === "string" ? b : String(b),
+					...name === void 0 ? {} : { name }
+				});
+				return;
+			}
+			case EVENT.ERROR: {
+				const code = typeof c === "string" ? c : void 0;
+				emit({
+					k: "error",
+					seq: 0,
+					t: 0,
+					id: lookup(a),
+					message: errorMessage(b),
+					...code === void 0 ? {} : { code }
+				});
+				return;
+			}
+			case EVENT.HYDRATION_MISMATCH:
+				emit({
+					k: "hydration",
+					seq: 0,
+					t: 0,
+					message: typeof a === "string" ? a : errorMessage(a),
+					expected: describeSide(b),
+					actual: describeSide(c)
+				});
+				return;
+			case EVENT.FLUSH_START:
+				queuedFlush = {
+					render: toNumber(a),
+					user: toNumber(b),
+					t: clock()
+				};
+				return;
+			case EVENT.FLUSH_END:
+				queuedFlush = null;
+				if (flushOpen) {
+					flushOpen = false;
+					emit({
+						k: "flush-",
+						seq: 0,
+						t: 0,
+						runs: toNumber(a)
+					});
+				}
+				return;
+			case EVENT.STORE_CREATED: {
+				if (!isObject(a) || isIgnored(a, b)) {
+					stats.ignored += 1;
+					return;
+				}
+				const handle = readStoreHandle(a);
+				if (handle === null) {
+					stats.ignored += 1;
+					return;
+				}
+				const id = registerLeaf(a);
+				stores.set(id, new WeakRef(handle));
+				emit({
+					k: "store+",
+					seq: 0,
+					t: 0,
+					id,
+					owner: lookup(b),
+					name: handle.name
+				});
+				if (!model.nodes.has(id)) stores.delete(id);
+				return;
+			}
+			default: stats.ignored += 1;
+		}
+	}
+	const readStoreHandle = (value) => {
+		const name = Reflect.get(value, "name");
+		const snapshot = Reflect.get(value, "snapshot");
+		const set = Reflect.get(value, "set");
+		if (typeof name !== "string" || typeof snapshot !== "function" || typeof set !== "function") return null;
+		return value;
+	};
+	const signalValue = (id) => {
+		const node = signals.get(id)?.deref();
+		if (node === void 0) return { found: false };
+		return {
+			found: true,
+			value: Reflect.get(node, "value")
+		};
+	};
+	const fail = (error) => ({
+		ok: false,
+		error
+	});
+	function handle(request) {
+		try {
+			switch (request.type) {
+				case "snapshot": return {
+					ok: true,
+					result: model.exportState()
+				};
+				case "stats": return {
+					ok: true,
+					result: {
+						...stats,
+						events: events.size,
+						dropped: events.dropped
+					}
+				};
+				case "value": {
+					const read = signalValue(request.id);
+					if (!read.found) return fail("The signal is gone.");
+					return {
+						ok: true,
+						result: {
+							id: request.id,
+							kind: "signal",
+							text: toEditableText(read.value),
+							editable: options.writeSignal !== void 0
+						}
+					};
+				}
+				case "write": {
+					const node = signals.get(request.id)?.deref();
+					if (node === void 0) return fail("The signal is gone.");
+					if (options.writeSignal === void 0) return fail("Editing is not enabled.");
+					const parsed = parseEditableText(request.text);
+					if (!parsed.ok) return fail(parsed.error);
+					const write = options.writeSignal;
+					write(node, parsed.value);
+					return {
+						ok: true,
+						result: null
+					};
+				}
+				case "store": {
+					const store = stores.get(request.id)?.deref();
+					if (store === void 0) return fail("The store is gone.");
+					return {
+						ok: true,
+						result: {
+							id: request.id,
+							kind: "store",
+							text: toEditableText(store.snapshot()),
+							editable: true
+						}
+					};
+				}
+				case "store-set": {
+					const store = stores.get(request.id)?.deref();
+					if (store === void 0) return fail("The store is gone.");
+					const parsed = parseEditableText(request.text);
+					if (!parsed.ok) return fail(parsed.error);
+					store.set(request.path, parsed.value);
+					return {
+						ok: true,
+						result: null
+					};
+				}
+				case "pause":
+					paused = true;
+					return {
+						ok: true,
+						result: null
+					};
+				case "resume":
+					paused = false;
+					return {
+						ok: true,
+						result: null
+					};
+				case "clear":
+					clear();
+					return {
+						ok: true,
+						result: null
+					};
+				case "highlight": return {
+					ok: true,
+					result: null
+				};
+				case "inspect": return {
+					ok: true,
+					result: { sources: readInspections(inspectionHook?.inspections?.() ?? []) }
+				};
+				default: return fail("Unknown command.");
+			}
+		} catch (error) {
+			return fail(errorMessage(error));
+		}
+	}
+	function clear() {
+		model.importState({
+			lastSeq: model.lastSeq,
+			overflow: 0,
+			unknown: 0,
+			nodes: [],
+			graveyard: [],
+			runs: [],
+			writes: [],
+			flushes: [],
+			errors: [],
+			hydration: []
+		});
+		events.clear();
+		pending = [];
+		queuedFlush = null;
+		flushOpen = false;
+		signals.clear();
+		components.clear();
+		stores.clear();
+	}
+	const agent = {
+		model,
+		events,
+		stats,
+		get paused() {
+			return paused;
+		},
+		receive,
+		attach(hook) {
+			inspectionHook = hook;
+			const detach = hook.attach(agent);
+			detachers.add(detach);
+			return () => {
+				detachers.delete(detach);
+				detach();
+			};
+		},
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		flush: deliver,
+		quiet(fn) {
+			quietDepth += 1;
+			try {
+				return fn();
+			} finally {
+				quietDepth -= 1;
+			}
+		},
+		pause() {
+			paused = true;
+		},
+		resume() {
+			paused = false;
+		},
+		clear,
+		snapshot: () => snapshotOf(model),
+		state: () => model.exportState(),
+		handle,
+		nodesOf(id) {
+			const out = [];
+			const own = components.get(id);
+			if (own !== void 0) for (const ref of own) {
+				const node = ref.deref();
+				if (node?.isConnected === true) out.push(node);
+			}
+			return out;
+		},
+		dispose() {
+			for (const detach of detachers) detach();
+			detachers.clear();
+			inspectionHook = void 0;
+			listeners.clear();
+			pending = [];
+			signals.clear();
+			components.clear();
+			stores.clear();
+			model.onBury = void 0;
+		}
+	};
+	return agent;
+}
+//#endregion
+export { createAgent };
+
+//# sourceMappingURL=agent.js.map