@excom/kit-devtools 0.1.0

package/.rush/temp/chunked-rush-logs/kit-devtools.apply-exports.chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: cd \"$RUSH_PROJECT_FOLDER\" && node ../heft-rig/scripts/apply-exports.mjs \n"}

package/.rush/temp/operation/apply-exports/all.log

@@ -0,0 +1 @@
+Invoking: cd "$RUSH_PROJECT_FOLDER" && node ../heft-rig/scripts/apply-exports.mjs 

package/.rush/temp/operation/apply-exports/log-chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: cd \"$RUSH_PROJECT_FOLDER\" && node ../heft-rig/scripts/apply-exports.mjs \n"}

package/.rush/temp/operation/apply-exports/state.json

@@ -0,0 +1,3 @@
+{
+  "nonCachedDurationMs": 39.90163499999994
+}

package/.rush/temp/shrinkwrap-deps.json

@@ -0,0 +1,3 @@
+{
+  "../../packages/kit-devtools": "../../packages/kit-devtools:udOS17RpnmJVey2VYAF31+qAltUTqEkGjhXxdGb/nFA=:"
+}

package/config/rig.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",
+  "rigPackageName": "@excom/heft-rig",
+  "rigProfile": "default"
+}
+

package/index.ts

@@ -0,0 +1 @@
+export * from "./src/hook";

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@excom/kit-devtools",
+  "version": "0.1.0",
+  "description": "kit-devtools library",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.13.0"
+  },
+  "type": "module",
+  "dependencies": {
+    "@excom/kit-logger": "^0.1.0",
+    "@excom/kit-utils": "^0.1.0"
+  },
+  "peerDependencies": {},
+  "devDependencies": {
+    "@excom/heft-rig": "^0.1.0"
+  },
+  "repository": {
+    "url": "excom-dev/nucleus",
+    "directory": "packages/kit-devtools"
+  },
+  "homepage": "https://github.com/excom-dev/nucleus/tree/main/packages/kit-devtools/support/docs/README.md",
+  "bugs": "https://github.com/excom-dev/nucleus/issues",
+  "keywords": [
+    "kit-devtools"
+  ],
+  "excom": {
+    "documented": false,
+    "packageType": "library"
+  },
+  "scripts": {
+    "build": "node node_modules/@excom/heft-rig/scripts/vite-build.mjs",
+    "build:watch": "node node_modules/@excom/heft-rig/scripts/vite-build-watch.mjs",
+    "format": "node node_modules/@excom/heft-rig/scripts/format.mjs",
+    "test": "node node_modules/@excom/heft-rig/scripts/vitest.mjs",
+    "coverage": "node node_modules/@excom/heft-rig/scripts/coverage.mjs"
+  }
+}

package/rush-logs/kit-devtools.apply-exports.cache.log

@@ -0,0 +1 @@
+Caching has been disabled for this project's "apply-exports" command.

package/rush-logs/kit-devtools.apply-exports.log

@@ -0,0 +1 @@
+Invoking: cd "$RUSH_PROJECT_FOLDER" && node ../heft-rig/scripts/apply-exports.mjs 

package/src/hook.ts

@@ -0,0 +1,193 @@
+import { toJsonSafe } from "@excom/kit-utils";
+
+/**
+ * Shared DevTools hook (Neutron lifecycles, Quark orchestration, …).
+ * Shipped always; dormant until `__NUCLEUS_DEVTOOLS_HOOK__` is set
+ * (extension at `document_start`, or `attachDevtools()`).
+ *
+ *   publicize(["neutron", "effect"], { weakElement, tag, effect })
+ *   publicize(["quark", "apply"], { weakElement, tag, selector, key })
+ *
+ * Each producer `registerRenderer`s an inspector; `hook.inject(renderer)`
+ * once per hook, keyed by `renderer.kind`.
+ *
+ * No element refs here. Payloads are WeakRef + primitives.
+ * `inspect()` snapshots on demand; don't keep the live element.
+ */
+
+export const NUCLEUS_DEVTOOLS_HOOK_KEY = "__NUCLEUS_DEVTOOLS_HOOK__";
+export const NUCLEUS_DEVTOOLS_HOOK_VERSION = 1 as const;
+
+/** Hierarchical identifying tokens, e.g. `["neutron", "constructed"]`. */
+export type PublicizePath = readonly string[];
+
+/**
+ * Publication metadata. Callers should pass WeakRef + primitives only.
+ * Never hard element / instance references.
+ */
+export type PublicizeMeta = Record<string, unknown>;
+
+/** Which producer a renderer inspects for. */
+export type DevtoolsRendererKind = "neutron" | "quark";
+
+/**
+ * On-demand inspector registered by a producer. `inspect` returns a
+ * JSON-safe snapshot for the element, or `null` when the producer has
+ * nothing to say about it.
+ */
+export type DevtoolsRenderer = {
+  version: typeof NUCLEUS_DEVTOOLS_HOOK_VERSION;
+  kind: DevtoolsRendererKind;
+  inspect: (el: Element) => Record<string, unknown> | null;
+};
+
+/**
+ * Global hook installed by a DevTools consumer.
+ * `publicize` mirrors the producer API: same `(path, meta)` signature.
+ * `inject` receives one renderer per producer kind.
+ */
+export type DevtoolsHook = {
+  version: typeof NUCLEUS_DEVTOOLS_HOOK_VERSION;
+  inject?: (renderer: DevtoolsRenderer) => void;
+  publicize?: (path: PublicizePath, meta: PublicizeMeta) => void;
+};
+
+declare global {
+  var __NUCLEUS_DEVTOOLS_HOOK__: DevtoolsHook | undefined;
+}
+
+export const getDevtoolsHook = (): DevtoolsHook | undefined =>
+  (globalThis as Record<string, unknown>)[NUCLEUS_DEVTOOLS_HOOK_KEY] as
+    | DevtoolsHook
+    | undefined;
+
+/**
+ * Prefix / wildcard match for subscriber filtering.
+ * `["neutron"]` matches `["neutron", "constructed"]`.
+ * `"*"` matches any single token at that position.
+ */
+export const pathMatches = (
+  path: PublicizePath,
+  pattern: PublicizePath
+): boolean =>
+  pattern.length <= path.length &&
+  pattern.every((token, i) => token === "*" || token === path[i]);
+
+/**
+ * Serializers for DevTools payloads (see `toJsonSafe`). Only plain data
+ * crosses into the extension (avoids cross-realm Object pitfalls).
+ * Non-POJOs (Promise, Map, …) become `{ $constructor: "Promise" }`.
+ */
+export const DEVTOOLS_SERIALIZERS: Record<string, (value: any) => unknown> = {
+  function: () => ({ $constructor: "Function" }),
+  symbol: (value: symbol) => ({
+    $constructor: "Symbol",
+    description: value.description ?? null,
+  }),
+  WeakRef: (value: WeakRef<WeakKey>) => {
+    const deref = value.deref();
+    return deref === undefined ? null : deref;
+  },
+  Node: (value: Node) => ({ $node: value.nodeName }),
+  Element: (value: Element) => ({
+    $element: value.localName ?? value.nodeName,
+    id: value.id || null,
+  }),
+  UnknownObject: (value: unknown) => ({
+    $constructor:
+      (value as object).constructor?.name ||
+      Object.prototype.toString.call(value),
+  }),
+  Circular: () => ({ $constructor: "Circular" }),
+  Failed: () => ({ $unserializable: true }),
+};
+
+/** JSON-safe clone using the DevTools serializers. */
+export const toDevtoolsJson = (value: unknown): unknown =>
+  toJsonSafe(value, DEVTOOLS_SERIALIZERS);
+
+const renderers = new Map<DevtoolsRendererKind, DevtoolsRenderer>();
+/** Renderer kinds already injected into a given hook object. */
+const injected = new WeakMap<DevtoolsHook, Set<DevtoolsRendererKind>>();
+
+/**
+ * Register (or replace) a producer's renderer. Injected into the current
+ * hook immediately when one is installed, and into any hook attached later.
+ */
+export const registerRenderer = (renderer: DevtoolsRenderer): void => {
+  renderers.set(renderer.kind, renderer);
+  const hook = getDevtoolsHook();
+  if (hook) injected.get(hook)?.delete(renderer.kind);
+  injectRenderersIfNeeded();
+};
+
+export const getRenderer = (
+  kind: DevtoolsRendererKind
+): DevtoolsRenderer | undefined => renderers.get(kind);
+
+/** Hand every registered renderer to the hook, once per hook object. */
+export const injectRenderersIfNeeded = (): void => {
+  const hook = getDevtoolsHook();
+  if (!hook?.inject) return;
+  let done = injected.get(hook);
+  if (!done) {
+    done = new Set();
+    injected.set(hook, done);
+  }
+  for (const renderer of renderers.values()) {
+    if (done.has(renderer.kind)) continue;
+    done.add(renderer.kind);
+    hook.inject(renderer);
+  }
+};
+
+/**
+ * Install (or replace) the global hook and (re)inject every renderer.
+ * Used by tests and by late-attaching consumers (e.g. a bookmarklet).
+ * Chrome extensions should set the global at `document_start` instead.
+ *
+ * Subscriber mirrors producer:
+ *   attachDevtools({
+ *     version: 1,
+ *     publicize: (path, meta) => { … },
+ *   })
+ */
+export const attachDevtools = (hook: DevtoolsHook): void => {
+  (globalThis as Record<string, unknown>)[NUCLEUS_DEVTOOLS_HOOK_KEY] = hook;
+  injected.delete(hook);
+  injectRenderersIfNeeded();
+};
+
+/**
+ * Event a consumer dispatches on `globalThis` after installing the hook
+ * global itself, late, without access to `attachDevtools` (an injected
+ * agent-tools bundle). Producers answer by injecting their renderers.
+ */
+export const NUCLEUS_DEVTOOLS_ATTACH_EVENT = "nucleus-devtools-attach";
+
+if (typeof globalThis.addEventListener === "function") {
+  globalThis.addEventListener(NUCLEUS_DEVTOOLS_ATTACH_EVENT, () =>
+    injectRenderersIfNeeded()
+  );
+}
+
+/**
+ * Publish a DevTools event. No-op when no hook is installed.
+ * Meta (except `weakElement`) is JSON-cloned in-page before crossing to the hook.
+ *
+ * @example
+ * publicize(["neutron", "constructed"], { weakElement, tag })
+ * publicize(["quark", "apply"], { weakElement, tag, selector, key })
+ */
+export const publicize = (
+  path: PublicizePath,
+  meta: PublicizeMeta = {}
+): void => {
+  const hook = getDevtoolsHook();
+  if (!hook?.publicize) return;
+  const { weakElement, ...rest } = meta;
+  hook.publicize(path, {
+    ...(toDevtoolsJson(rest) as PublicizeMeta),
+    ...(weakElement ? { weakElement } : {}),
+  });
+};

package/support/tests/hook.test.ts

@@ -0,0 +1,307 @@
+import {
+  attachDevtools,
+  DEVTOOLS_SERIALIZERS,
+  getDevtoolsHook,
+  getRenderer,
+  injectRenderersIfNeeded,
+  NUCLEUS_DEVTOOLS_ATTACH_EVENT,
+  NUCLEUS_DEVTOOLS_HOOK_KEY,
+  NUCLEUS_DEVTOOLS_HOOK_VERSION,
+  pathMatches,
+  publicize,
+  registerRenderer,
+  toDevtoolsJson,
+  type DevtoolsHook,
+  type DevtoolsRenderer,
+} from "../../index";
+import {
+  afterEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from "@excom/heft-rig/node_modules/vitest";
+
+const uninstallHook = () => {
+  delete (globalThis as Record<string, unknown>)[NUCLEUS_DEVTOOLS_HOOK_KEY];
+};
+
+const makeRenderer = (
+  kind: DevtoolsRenderer["kind"],
+  inspect: DevtoolsRenderer["inspect"] = () => null
+): DevtoolsRenderer => ({
+  version: NUCLEUS_DEVTOOLS_HOOK_VERSION,
+  kind,
+  inspect,
+});
+
+describe("hook basics", () => {
+  afterEach(() => {
+    uninstallHook();
+    vi.restoreAllMocks();
+  });
+
+  it("exposes the global key and version", () => {
+    expect(NUCLEUS_DEVTOOLS_HOOK_KEY).toBe("__NUCLEUS_DEVTOOLS_HOOK__");
+    expect(NUCLEUS_DEVTOOLS_HOOK_VERSION).toBe(1);
+  });
+
+  it("getDevtoolsHook reads the global slot", () => {
+    expect(getDevtoolsHook()).toBeUndefined();
+    const hook: DevtoolsHook = { version: 1 };
+    attachDevtools(hook);
+    expect(getDevtoolsHook()).toBe(hook);
+    expect(globalThis.__NUCLEUS_DEVTOOLS_HOOK__).toBe(hook);
+  });
+});
+
+describe("pathMatches", () => {
+  it("matches an exact path", () => {
+    expect(pathMatches(["neutron", "constructed"], ["neutron", "constructed"])).toBe(true);
+  });
+
+  it("matches a prefix pattern", () => {
+    expect(pathMatches(["neutron", "constructed"], ["neutron"])).toBe(true);
+    expect(pathMatches(["neutron", "constructed"], [])).toBe(true);
+  });
+
+  it("treats * as a single-token wildcard", () => {
+    expect(pathMatches(["quark", "apply"], ["*", "apply"])).toBe(true);
+    expect(pathMatches(["quark", "apply"], ["quark", "*"])).toBe(true);
+    expect(pathMatches(["quark", "apply"], ["*", "*", "*"])).toBe(false);
+  });
+
+  it("rejects mismatching tokens and longer patterns", () => {
+    expect(pathMatches(["quark", "apply"], ["neutron"])).toBe(false);
+    expect(pathMatches(["quark"], ["quark", "apply"])).toBe(false);
+  });
+});
+
+describe("toDevtoolsJson / DEVTOOLS_SERIALIZERS", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("serializes functions", () => {
+    expect(toDevtoolsJson({ fn: () => 1 })).toEqual({
+      fn: { $constructor: "Function" },
+    });
+  });
+
+  it("serializes symbols with and without a description", () => {
+    expect(toDevtoolsJson({ s: Symbol("tag") })).toEqual({
+      s: { $constructor: "Symbol", description: "tag" },
+    });
+    expect(DEVTOOLS_SERIALIZERS.symbol(Symbol())).toEqual({
+      $constructor: "Symbol",
+      description: null,
+    });
+  });
+
+  it("serializes elements with id, without id, and plain nodes", () => {
+    const withId = document.createElement("my-widget");
+    withId.id = "one";
+    const noId = document.createElement("section");
+    const text = document.createTextNode("hi");
+    expect(toDevtoolsJson({ withId, noId, text })).toEqual({
+      withId: { $element: "my-widget", id: "one" },
+      noId: { $element: "section", id: null },
+      text: { $node: "#text" },
+    });
+  });
+
+  it("derefs WeakRefs and nulls dead ones", () => {
+    const el = document.createElement("p");
+    el.id = "weak";
+    expect(toDevtoolsJson({ ref: new WeakRef(el) })).toEqual({
+      ref: { $element: "p", id: "weak" },
+    });
+    const dead = { deref: () => undefined } as unknown as WeakRef<object>;
+    expect(DEVTOOLS_SERIALIZERS.WeakRef(dead)).toBeNull();
+  });
+
+  it("tags non-POJOs with their constructor name", () => {
+    class Thing {}
+    expect(toDevtoolsJson({ m: new Map(), p: Promise.resolve(), t: new Thing() })).toEqual({
+      m: { $constructor: "Map" },
+      p: { $constructor: "Promise" },
+      t: { $constructor: "Thing" },
+    });
+  });
+
+  it("falls back to Object.prototype.toString for nameless constructors", () => {
+    const anon = Object.create({ constructor: { name: "" } });
+    expect(DEVTOOLS_SERIALIZERS.UnknownObject(anon)).toEqual({
+      $constructor: "[object Object]",
+    });
+    const noCtor = Object.create({});
+    Object.defineProperty(noCtor, "constructor", { value: undefined });
+    expect(DEVTOOLS_SERIALIZERS.UnknownObject(noCtor)).toEqual({
+      $constructor: "[object Object]",
+    });
+  });
+
+  it("marks circular references", () => {
+    const obj: Record<string, unknown> = { name: "loop" };
+    obj.self = obj;
+    expect(toDevtoolsJson(obj)).toEqual({
+      name: "loop",
+      self: { $constructor: "Circular" },
+    });
+  });
+
+  it("marks values that cannot be serialized", () => {
+    const broken = {
+      toJSON() {
+        throw new Error("nope");
+      },
+    };
+    expect(toDevtoolsJson(broken)).toEqual({ $unserializable: true });
+    expect(DEVTOOLS_SERIALIZERS.Failed()).toEqual({ $unserializable: true });
+    expect(DEVTOOLS_SERIALIZERS.Circular()).toEqual({ $constructor: "Circular" });
+  });
+
+  it("passes primitives, arrays and POJOs through", () => {
+    expect(toDevtoolsJson({ a: [1, "two", null, { b: true }] })).toEqual({
+      a: [1, "two", null, { b: true }],
+    });
+  });
+});
+
+describe("publicize", () => {
+  afterEach(() => {
+    uninstallHook();
+    document.body.innerHTML = "";
+  });
+
+  it("is a no-op without a hook", () => {
+    expect(() => publicize(["neutron", "constructed"], { tag: "x" })).not.toThrow();
+  });
+
+  it("is a no-op when the hook has no publicize", () => {
+    attachDevtools({ version: 1 });
+    expect(() => publicize(["neutron", "constructed"])).not.toThrow();
+  });
+
+  it("clones meta and forwards weakElement untouched", () => {
+    const received: unknown[] = [];
+    attachDevtools({
+      version: 1,
+      publicize: (path, meta) => received.push([path, meta]),
+    });
+    const el = document.createElement("my-el");
+    const weakElement = new WeakRef(el);
+    const effect = () => {};
+    publicize(["neutron", "effect"], { weakElement, tag: "my-el", effect, el });
+    expect(received).toHaveLength(1);
+    const [path, meta] = received[0] as [string[], Record<string, unknown>];
+    expect(path).toEqual(["neutron", "effect"]);
+    expect(meta.weakElement).toBe(weakElement);
+    expect(meta.tag).toBe("my-el");
+    expect(meta.effect).toEqual({ $constructor: "Function" });
+    expect(meta.el).toEqual({ $element: "my-el", id: null });
+  });
+
+  it("omits weakElement when not supplied and defaults meta to {}", () => {
+    const spy = vi.fn();
+    attachDevtools({ version: 1, publicize: spy });
+    publicize(["quark", "apply"]);
+    expect(spy).toHaveBeenCalledWith(["quark", "apply"], {});
+    expect(spy.mock.calls[0][1]).not.toHaveProperty("weakElement");
+  });
+});
+
+describe("renderer registry", () => {
+  afterEach(() => {
+    uninstallHook();
+  });
+
+  it("stores renderers without a hook and exposes them via getRenderer", () => {
+    const neutron = makeRenderer("neutron", () => ({ kind: "n" }));
+    registerRenderer(neutron);
+    expect(getRenderer("neutron")).toBe(neutron);
+    expect(getRenderer("neutron")!.inspect(document.body)).toEqual({ kind: "n" });
+    // No hook installed: injecting is a silent no-op.
+    expect(() => injectRenderersIfNeeded()).not.toThrow();
+  });
+
+  it("injects registered renderers when a hook is attached, once per hook", () => {
+    const neutron = makeRenderer("neutron");
+    const quark = makeRenderer("quark");
+    registerRenderer(neutron);
+    registerRenderer(quark);
+
+    const inject = vi.fn();
+    const hook: DevtoolsHook = { version: 1, inject };
+    attachDevtools(hook);
+    expect(inject).toHaveBeenCalledTimes(2);
+    expect(inject.mock.calls.map((c) => c[0].kind).sort()).toEqual(["neutron", "quark"]);
+
+    // Repeated injection requests are de-duplicated per hook object.
+    injectRenderersIfNeeded();
+    injectRenderersIfNeeded();
+    expect(inject).toHaveBeenCalledTimes(2);
+  });
+
+  it("re-injects everything when attachDevtools is called again with the same hook", () => {
+    registerRenderer(makeRenderer("neutron"));
+    registerRenderer(makeRenderer("quark"));
+    const inject = vi.fn();
+    const hook: DevtoolsHook = { version: 1, inject };
+    attachDevtools(hook);
+    attachDevtools(hook);
+    expect(inject).toHaveBeenCalledTimes(4);
+  });
+
+  it("injects into a different hook object independently", () => {
+    registerRenderer(makeRenderer("neutron"));
+    const first = vi.fn();
+    const second = vi.fn();
+    attachDevtools({ version: 1, inject: first });
+    attachDevtools({ version: 1, inject: second });
+    expect(first).toHaveBeenCalled();
+    expect(second).toHaveBeenCalled();
+    expect(getDevtoolsHook()!.inject).toBe(second);
+  });
+
+  it("registering a renderer while a hook is installed injects it immediately", () => {
+    const inject = vi.fn();
+    attachDevtools({ version: 1, inject });
+    const before = inject.mock.calls.length;
+    const replacement = makeRenderer("quark", () => ({ replaced: true }));
+    registerRenderer(replacement);
+    expect(inject).toHaveBeenCalledTimes(before + 1);
+    expect(inject).toHaveBeenLastCalledWith(replacement);
+    expect(getRenderer("quark")).toBe(replacement);
+
+    // Re-registering the same kind replaces and re-injects it.
+    const again = makeRenderer("quark");
+    registerRenderer(again);
+    expect(inject).toHaveBeenLastCalledWith(again);
+    expect(inject).toHaveBeenCalledTimes(before + 2);
+  });
+
+  it("does nothing when the hook has no inject", () => {
+    const hook: DevtoolsHook = { version: 1 };
+    registerRenderer(makeRenderer("neutron"));
+    expect(() => attachDevtools(hook)).not.toThrow();
+    expect(() => registerRenderer(makeRenderer("quark"))).not.toThrow();
+  });
+
+  it("injects into a hook installed by hand once the attach event fires", () => {
+    registerRenderer(makeRenderer("neutron"));
+    const inject = vi.fn();
+    // an injected bundle sets the global itself, it has no attachDevtools
+    (globalThis as Record<string, unknown>)[NUCLEUS_DEVTOOLS_HOOK_KEY] = {
+      version: 1,
+      inject,
+    } satisfies DevtoolsHook;
+    expect(inject).not.toHaveBeenCalled();
+    globalThis.dispatchEvent(new Event(NUCLEUS_DEVTOOLS_ATTACH_EVENT));
+    expect(inject).toHaveBeenCalledWith(getRenderer("neutron"));
+    // idempotent per hook object
+    const count = inject.mock.calls.length;
+    globalThis.dispatchEvent(new Event(NUCLEUS_DEVTOOLS_ATTACH_EVENT));
+    expect(inject).toHaveBeenCalledTimes(count);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "@excom/heft-rig/profiles/default/config/tsconfig.json",
+  "include": ["./*.ts", "./src/**/*.ts"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+}