@shadow-js/devtools 0.0.0-stage → 1.0.0

package/dist/dev/protocol.d.ts

@@ -0,0 +1,288 @@
+import { InspectionEntry, InspectionSource } from "./inspection.js";
+//#region src/protocol.d.ts
+/**
+ * Protocol version carried by the hook (`hook.version`). Bump it when the meaning of an existing
+ * event argument changes; adding event kinds does not require a bump.
+ *
+ * @example
+ * import { getHook, PROTOCOL_VERSION } from "@shadow-js/devtools";
+ *
+ * const speaks = getHook()?.version === PROTOCOL_VERSION; // true when a matching hook is installed
+ * @since 1.0.0
+ */
+export declare const PROTOCOL_VERSION = 1;
+/**
+ * Name of the global the runtime looks up: `globalThis.__SHADOWJS_DEVTOOLS_HOOK__`.
+ *
+ * @example
+ * import { HOOK_KEY } from "@shadow-js/devtools";
+ *
+ * const installed: unknown = Reflect.get(globalThis, HOOK_KEY);
+ * @since 1.0.0
+ */
+export declare const HOOK_KEY = "__SHADOWJS_DEVTOOLS_HOOK__";
+/**
+ * Event kinds of `hook.report(kind, ...)`, with the meaning of the arguments. An argument the table
+ * leaves blank is not sent for that kind. `null` means "no node" (for example, a computation outside
+ * any owner); `undefined` means "no name".
+ *
+ * | kind | a | b | c | d | e |
+ * | --- | --- | --- | --- | --- | --- |
+ * | `OWNER_CREATED` | owner | parent owner, or `null` for a root | `"root"` or `"owner"` | name, when known (the core runtime sends none) | |
+ * | `OWNER_DISPOSED` | owner | | | | |
+ * | `SIGNAL_CREATED` | signal | owner or `null` | name or `undefined` | initial value (shown as a preview) | |
+ * | `SIGNAL_WRITTEN` | signal | next value | writing computation, or `null` | observers (array of computations), or `null` | |
+ * | `COMPUTATION_CREATED` | computation | owner or `null` | `"memo"` or `"effect"` | name or `undefined` | render flag |
+ * | `COMPUTATION_RUN` | computation | start time (ms) | duration (ms) | value changed | sources (array of the nodes it read) |
+ * | `COMPUTATION_DISPOSED` | computation | | | | |
+ * | `COMPONENT_MOUNTED` | owner of the component | name or `undefined` | what the component returned: a DOM node, an array of them, or another value | | |
+ * | `COMPONENT_UNMOUNTED` | owner of the component | | | | |
+ * | `RESOURCE_STATE` | resource handle | state (string) | name or `undefined` | owner or `null` | |
+ * | `ERROR` | source owner or `null` | the thrown value | diagnostic code or `undefined` | | |
+ * | `HYDRATION_MISMATCH` | message | expected side (text or node; the web runtime sends the element key) | actual side (text or node; the web runtime sends none) | | |
+ * | `FLUSH_START` | render queue size | user queue size | | | |
+ * | `FLUSH_END` | computations run in the flush | | | | |
+ * | `STORE_CREATED` | store handle ({@link StoreHandle}) | owner or `null` | | | |
+ * | `TRANSITION_START` | | | | | |
+ * | `TRANSITION_END` | transitions resolved (count) | | | | |
+ *
+ * The agent ignores `TRANSITION_START` and `TRANSITION_END` today, and any other unknown kind.
+ *
+ * @example
+ * import { EVENT } from "@shadow-js/devtools";
+ *
+ * const kind = EVENT.COMPUTATION_RUN; // 6: a = computation, b = start, c = duration, d = changed, e = sources
+ * @since 1.0.0
+ */
+export declare const EVENT: {
+  readonly OWNER_CREATED: 1;
+  readonly OWNER_DISPOSED: 2;
+  readonly SIGNAL_CREATED: 3;
+  readonly SIGNAL_WRITTEN: 4;
+  readonly COMPUTATION_CREATED: 5;
+  readonly COMPUTATION_RUN: 6;
+  readonly COMPUTATION_DISPOSED: 7;
+  readonly COMPONENT_MOUNTED: 8;
+  readonly COMPONENT_UNMOUNTED: 9;
+  readonly RESOURCE_STATE: 10;
+  readonly ERROR: 11;
+  readonly HYDRATION_MISMATCH: 12;
+  readonly FLUSH_START: 13;
+  readonly FLUSH_END: 14;
+  readonly STORE_CREATED: 15;
+  readonly TRANSITION_START: 16;
+  readonly TRANSITION_END: 17;
+};
+/**
+ * One of the numeric event kinds.
+ *
+ * @since 1.0.0
+ */
+export type EventKind = (typeof EVENT)[keyof typeof EVENT];
+/**
+ * What a runtime passes with `STORE_CREATED`, so tools can show and edit a store without knowing its
+ * implementation.
+ *
+ * @since 1.0.0
+ */
+export interface StoreHandle {
+  /** Label shown in the store viewer. */
+  readonly name: string;
+  /** A plain copy of the current value (what `snapshot(store)` returns). */
+  snapshot(): unknown;
+  /** Writes `value` at `path` (property names and array indices) in one batched update. */
+  set(path: readonly (string | number)[], value: unknown): void;
+}
+/**
+ * The receiver side of the hook: an agent implements it to be told about events.
+ *
+ * @since 1.0.0
+ */
+export interface HookSink {
+  /**
+   * Called synchronously for every reported event, with the arguments of {@link EVENT}. Must be cheap
+   * and must not throw; a throw is caught by the hook and counted as a fault.
+   */
+  receive(kind: number, a: unknown, b: unknown, c: unknown, d: unknown, e: unknown): void;
+}
+/**
+ * Most rows one inspection source may return. The rest are cut and a final row says so, so a panel
+ * never receives an unbounded list.
+ *
+ * @example
+ * import { MAX_INSPECTION_ROWS } from "@shadow-js/devtools";
+ * const cap: number = MAX_INSPECTION_ROWS; // 500
+ * @since 1.0.0
+ */
+export declare const MAX_INSPECTION_ROWS = 500;
+/**
+ * Most sources an app may register with {@link registerInspection}. Registering one more is refused,
+ * and the names already registered keep working.
+ *
+ * @example
+ * import { MAX_INSPECTIONS } from "@shadow-js/devtools";
+ * const cap: number = MAX_INSPECTIONS; // 16
+ * @since 1.0.0
+ */
+export declare const MAX_INSPECTIONS = 16;
+/**
+ * The object installed at `globalThis.__SHADOWJS_DEVTOOLS_HOOK__` by `installHook`. A runtime calls
+ * `report` on it; a tool attaches a {@link HookSink} to receive the events.
+ *
+ * @example
+ * import { EVENT, getHook } from "@shadow-js/devtools";
+ *
+ * const hook = getHook();
+ * hook?.report(EVENT.FLUSH_END, 0); // a flush that ran no computations
+ * @since 1.0.0
+ */
+export interface DevtoolsHook {
+  /** Protocol version; compare with {@link PROTOCOL_VERSION} before reporting. */
+  readonly version: number;
+  /** Runtime to tools. Positional arguments, see {@link EVENT}. Never throws. */
+  report(kind: number, a?: unknown, b?: unknown, c?: unknown, d?: unknown, e?: unknown): void;
+  /**
+   * Registers a sink; returns the function that removes it. Events buffered before the first sink
+   * attached (up to the buffer size given to `installHook`) are replayed to that first sink only.
+   */
+  attach(sink: HookSink): () => void;
+  /** Number of attached sinks. */
+  readonly sinks: number;
+  /**
+   * Registers an inspection source under `name`; re-registering a name replaces it. Returns false when
+   * refused (the limit of {@link MAX_INSPECTIONS} is reached). Hooks of this package provide it; a
+   * hook made by hand need not.
+   */
+  inspect?(name: string, source: InspectionSource): boolean;
+  /** The registered inspection sources, in registration order. Hooks of this package provide it. */
+  inspections?(): readonly InspectionEntry[];
+}
+/**
+ * Events as they cross a process boundary: plain, JSON-safe objects that refer to nodes by id.
+ * `seq` is a gapless counter; `t` is the time in milliseconds on the reporting clock.
+ *
+ * @since 1.0.0
+ */
+export type WireEvent = {
+  k: "owner+";
+  seq: number;
+  t: number;
+  id: number;
+  parent: number;
+  label: string;
+  name?: string;
+} | {
+  k: "owner-";
+  seq: number;
+  t: number;
+  id: number;
+} | {
+  k: "signal+";
+  seq: number;
+  t: number;
+  id: number;
+  owner: number;
+  name?: string;
+  preview: string;
+} | {
+  k: "write";
+  seq: number;
+  t: number;
+  id: number;
+  preview: string;
+  writer: number;
+  observers: number[];
+} | {
+  k: "comp+";
+  seq: number;
+  t: number;
+  id: number;
+  owner: number;
+  kind: "memo" | "effect";
+  render: boolean;
+  name?: string;
+} | {
+  k: "run";
+  seq: number;
+  t: number;
+  id: number;
+  start: number;
+  duration: number;
+  changed: boolean;
+  sources: number[];
+} | {
+  k: "comp-";
+  seq: number;
+  t: number;
+  id: number;
+} | {
+  k: "mount";
+  seq: number;
+  t: number;
+  id: number;
+  name: string;
+} | {
+  k: "unmount";
+  seq: number;
+  t: number;
+  id: number;
+} | {
+  k: "resource";
+  seq: number;
+  t: number;
+  id: number;
+  owner: number;
+  state: string;
+  name?: string;
+} | {
+  k: "error";
+  seq: number;
+  t: number;
+  id: number;
+  message: string;
+  code?: string;
+} | {
+  k: "hydration";
+  seq: number;
+  t: number;
+  message: string;
+  expected: string;
+  actual: string;
+} | {
+  k: "flush+";
+  seq: number;
+  t: number;
+  render: number;
+  user: number;
+} | {
+  k: "flush-";
+  seq: number;
+  t: number;
+  runs: number;
+} | {
+  k: "store+";
+  seq: number;
+  t: number;
+  id: number;
+  owner: number;
+  name: string;
+};
+/**
+ * Discriminant of {@link WireEvent}.
+ *
+ * @since 1.0.0
+ */
+export type WireKind = WireEvent["k"];
+/**
+ * The sentinel used where a wire event refers to "no node". The agent assigns node ids from 1, so
+ * `NO_ID` never names a node.
+ *
+ * @example
+ * import { NO_ID } from "@shadow-js/devtools";
+ *
+ * const isRoot = (parent: number): boolean => parent === NO_ID;
+ * @since 1.0.0
+ */
+export declare const NO_ID = 0;
+//#endregion
+//# sourceMappingURL=protocol.d.ts.map

package/dist/dev/protocol.js

@@ -0,0 +1,109 @@
+//#region src/protocol.ts
+/**
+* Protocol version carried by the hook (`hook.version`). Bump it when the meaning of an existing
+* event argument changes; adding event kinds does not require a bump.
+*
+* @example
+* import { getHook, PROTOCOL_VERSION } from "@shadow-js/devtools";
+*
+* const speaks = getHook()?.version === PROTOCOL_VERSION; // true when a matching hook is installed
+* @since 1.0.0
+*/
+const PROTOCOL_VERSION = 1;
+/**
+* Name of the global the runtime looks up: `globalThis.__SHADOWJS_DEVTOOLS_HOOK__`.
+*
+* @example
+* import { HOOK_KEY } from "@shadow-js/devtools";
+*
+* const installed: unknown = Reflect.get(globalThis, HOOK_KEY);
+* @since 1.0.0
+*/
+const HOOK_KEY = "__SHADOWJS_DEVTOOLS_HOOK__";
+/**
+* Event kinds of `hook.report(kind, ...)`, with the meaning of the arguments. An argument the table
+* leaves blank is not sent for that kind. `null` means "no node" (for example, a computation outside
+* any owner); `undefined` means "no name".
+*
+* | kind | a | b | c | d | e |
+* | --- | --- | --- | --- | --- | --- |
+* | `OWNER_CREATED` | owner | parent owner, or `null` for a root | `"root"` or `"owner"` | name, when known (the core runtime sends none) | |
+* | `OWNER_DISPOSED` | owner | | | | |
+* | `SIGNAL_CREATED` | signal | owner or `null` | name or `undefined` | initial value (shown as a preview) | |
+* | `SIGNAL_WRITTEN` | signal | next value | writing computation, or `null` | observers (array of computations), or `null` | |
+* | `COMPUTATION_CREATED` | computation | owner or `null` | `"memo"` or `"effect"` | name or `undefined` | render flag |
+* | `COMPUTATION_RUN` | computation | start time (ms) | duration (ms) | value changed | sources (array of the nodes it read) |
+* | `COMPUTATION_DISPOSED` | computation | | | | |
+* | `COMPONENT_MOUNTED` | owner of the component | name or `undefined` | what the component returned: a DOM node, an array of them, or another value | | |
+* | `COMPONENT_UNMOUNTED` | owner of the component | | | | |
+* | `RESOURCE_STATE` | resource handle | state (string) | name or `undefined` | owner or `null` | |
+* | `ERROR` | source owner or `null` | the thrown value | diagnostic code or `undefined` | | |
+* | `HYDRATION_MISMATCH` | message | expected side (text or node; the web runtime sends the element key) | actual side (text or node; the web runtime sends none) | | |
+* | `FLUSH_START` | render queue size | user queue size | | | |
+* | `FLUSH_END` | computations run in the flush | | | | |
+* | `STORE_CREATED` | store handle ({@link StoreHandle}) | owner or `null` | | | |
+* | `TRANSITION_START` | | | | | |
+* | `TRANSITION_END` | transitions resolved (count) | | | | |
+*
+* The agent ignores `TRANSITION_START` and `TRANSITION_END` today, and any other unknown kind.
+*
+* @example
+* import { EVENT } from "@shadow-js/devtools";
+*
+* const kind = EVENT.COMPUTATION_RUN; // 6: a = computation, b = start, c = duration, d = changed, e = sources
+* @since 1.0.0
+*/
+const EVENT = {
+	OWNER_CREATED: 1,
+	OWNER_DISPOSED: 2,
+	SIGNAL_CREATED: 3,
+	SIGNAL_WRITTEN: 4,
+	COMPUTATION_CREATED: 5,
+	COMPUTATION_RUN: 6,
+	COMPUTATION_DISPOSED: 7,
+	COMPONENT_MOUNTED: 8,
+	COMPONENT_UNMOUNTED: 9,
+	RESOURCE_STATE: 10,
+	ERROR: 11,
+	HYDRATION_MISMATCH: 12,
+	FLUSH_START: 13,
+	FLUSH_END: 14,
+	STORE_CREATED: 15,
+	TRANSITION_START: 16,
+	TRANSITION_END: 17
+};
+/**
+* Most rows one inspection source may return. The rest are cut and a final row says so, so a panel
+* never receives an unbounded list.
+*
+* @example
+* import { MAX_INSPECTION_ROWS } from "@shadow-js/devtools";
+* const cap: number = MAX_INSPECTION_ROWS; // 500
+* @since 1.0.0
+*/
+const MAX_INSPECTION_ROWS = 500;
+/**
+* Most sources an app may register with {@link registerInspection}. Registering one more is refused,
+* and the names already registered keep working.
+*
+* @example
+* import { MAX_INSPECTIONS } from "@shadow-js/devtools";
+* const cap: number = MAX_INSPECTIONS; // 16
+* @since 1.0.0
+*/
+const MAX_INSPECTIONS = 16;
+/**
+* The sentinel used where a wire event refers to "no node". The agent assigns node ids from 1, so
+* `NO_ID` never names a node.
+*
+* @example
+* import { NO_ID } from "@shadow-js/devtools";
+*
+* const isRoot = (parent: number): boolean => parent === NO_ID;
+* @since 1.0.0
+*/
+const NO_ID = 0;
+//#endregion
+export { EVENT, HOOK_KEY, MAX_INSPECTIONS, MAX_INSPECTION_ROWS, NO_ID, PROTOCOL_VERSION };
+
+//# sourceMappingURL=protocol.js.map

package/dist/dev/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","names":[],"sources":["../../src/protocol.ts"],"sourcesContent":["/**\n * The dev-hook protocol: how a ShadowJS runtime reports its reactive graph to developer tools.\n *\n * The runtime (core, web and query) calls `hook.report(kind, a, b, c, d, e)` for every event, in\n * development builds only (`if (__DEV__) { ... }`). The arguments are positional and the objects\n * are the runtime's own nodes: the hook never copies them, so reporting allocates nothing. An agent\n * (see {@link createAgent}) turns them into serializable, id-based {@link WireEvent}s.\n *\n * The protocol is versioned by {@link PROTOCOL_VERSION}. A runtime reports only to a hook whose\n * version it knows, and the agent ignores events with an unknown kind, so old runtimes and new\n * tools (and the other way round) degrade instead of breaking.\n *\n * @packageDocumentation\n */\n\nimport type { InspectionEntry, InspectionSource } from \"./inspection\";\n\n/**\n * Protocol version carried by the hook (`hook.version`). Bump it when the meaning of an existing\n * event argument changes; adding event kinds does not require a bump.\n *\n * @example\n * import { getHook, PROTOCOL_VERSION } from \"@shadow-js/devtools\";\n *\n * const speaks = getHook()?.version === PROTOCOL_VERSION; // true when a matching hook is installed\n * @since 1.0.0\n */\nexport const PROTOCOL_VERSION = 1;\n\n/**\n * Name of the global the runtime looks up: `globalThis.__SHADOWJS_DEVTOOLS_HOOK__`.\n *\n * @example\n * import { HOOK_KEY } from \"@shadow-js/devtools\";\n *\n * const installed: unknown = Reflect.get(globalThis, HOOK_KEY);\n * @since 1.0.0\n */\nexport const HOOK_KEY = \"__SHADOWJS_DEVTOOLS_HOOK__\";\n\n/**\n * Event kinds of `hook.report(kind, ...)`, with the meaning of the arguments. An argument the table\n * leaves blank is not sent for that kind. `null` means \"no node\" (for example, a computation outside\n * any owner); `undefined` means \"no name\".\n *\n * | kind | a | b | c | d | e |\n * | --- | --- | --- | --- | --- | --- |\n * | `OWNER_CREATED` | owner | parent owner, or `null` for a root | `\"root\"` or `\"owner\"` | name, when known (the core runtime sends none) | |\n * | `OWNER_DISPOSED` | owner | | | | |\n * | `SIGNAL_CREATED` | signal | owner or `null` | name or `undefined` | initial value (shown as a preview) | |\n * | `SIGNAL_WRITTEN` | signal | next value | writing computation, or `null` | observers (array of computations), or `null` | |\n * | `COMPUTATION_CREATED` | computation | owner or `null` | `\"memo\"` or `\"effect\"` | name or `undefined` | render flag |\n * | `COMPUTATION_RUN` | computation | start time (ms) | duration (ms) | value changed | sources (array of the nodes it read) |\n * | `COMPUTATION_DISPOSED` | computation | | | | |\n * | `COMPONENT_MOUNTED` | owner of the component | name or `undefined` | what the component returned: a DOM node, an array of them, or another value | | |\n * | `COMPONENT_UNMOUNTED` | owner of the component | | | | |\n * | `RESOURCE_STATE` | resource handle | state (string) | name or `undefined` | owner or `null` | |\n * | `ERROR` | source owner or `null` | the thrown value | diagnostic code or `undefined` | | |\n * | `HYDRATION_MISMATCH` | message | expected side (text or node; the web runtime sends the element key) | actual side (text or node; the web runtime sends none) | | |\n * | `FLUSH_START` | render queue size | user queue size | | | |\n * | `FLUSH_END` | computations run in the flush | | | | |\n * | `STORE_CREATED` | store handle ({@link StoreHandle}) | owner or `null` | | | |\n * | `TRANSITION_START` | | | | | |\n * | `TRANSITION_END` | transitions resolved (count) | | | | |\n *\n * The agent ignores `TRANSITION_START` and `TRANSITION_END` today, and any other unknown kind.\n *\n * @example\n * import { EVENT } from \"@shadow-js/devtools\";\n *\n * const kind = EVENT.COMPUTATION_RUN; // 6: a = computation, b = start, c = duration, d = changed, e = sources\n * @since 1.0.0\n */\nexport const EVENT: {\n  readonly OWNER_CREATED: 1;\n  readonly OWNER_DISPOSED: 2;\n  readonly SIGNAL_CREATED: 3;\n  readonly SIGNAL_WRITTEN: 4;\n  readonly COMPUTATION_CREATED: 5;\n  readonly COMPUTATION_RUN: 6;\n  readonly COMPUTATION_DISPOSED: 7;\n  readonly COMPONENT_MOUNTED: 8;\n  readonly COMPONENT_UNMOUNTED: 9;\n  readonly RESOURCE_STATE: 10;\n  readonly ERROR: 11;\n  readonly HYDRATION_MISMATCH: 12;\n  readonly FLUSH_START: 13;\n  readonly FLUSH_END: 14;\n  readonly STORE_CREATED: 15;\n  readonly TRANSITION_START: 16;\n  readonly TRANSITION_END: 17;\n} = {\n  OWNER_CREATED: 1,\n  OWNER_DISPOSED: 2,\n  SIGNAL_CREATED: 3,\n  SIGNAL_WRITTEN: 4,\n  COMPUTATION_CREATED: 5,\n  COMPUTATION_RUN: 6,\n  COMPUTATION_DISPOSED: 7,\n  COMPONENT_MOUNTED: 8,\n  COMPONENT_UNMOUNTED: 9,\n  RESOURCE_STATE: 10,\n  ERROR: 11,\n  HYDRATION_MISMATCH: 12,\n  FLUSH_START: 13,\n  FLUSH_END: 14,\n  STORE_CREATED: 15,\n  TRANSITION_START: 16,\n  TRANSITION_END: 17,\n};\n\n/**\n * One of the numeric event kinds.\n *\n * @since 1.0.0\n */\nexport type EventKind = (typeof EVENT)[keyof typeof EVENT];\n\n/**\n * What a runtime passes with `STORE_CREATED`, so tools can show and edit a store without knowing its\n * implementation.\n *\n * @since 1.0.0\n */\nexport interface StoreHandle {\n  /** Label shown in the store viewer. */\n  readonly name: string;\n  /** A plain copy of the current value (what `snapshot(store)` returns). */\n  snapshot(): unknown;\n  /** Writes `value` at `path` (property names and array indices) in one batched update. */\n  set(path: readonly (string | number)[], value: unknown): void;\n}\n\n/**\n * The receiver side of the hook: an agent implements it to be told about events.\n *\n * @since 1.0.0\n */\nexport interface HookSink {\n  /**\n   * Called synchronously for every reported event, with the arguments of {@link EVENT}. Must be cheap\n   * and must not throw; a throw is caught by the hook and counted as a fault.\n   */\n  receive(kind: number, a: unknown, b: unknown, c: unknown, d: unknown, e: unknown): void;\n}\n\n/**\n * Most rows one inspection source may return. The rest are cut and a final row says so, so a panel\n * never receives an unbounded list.\n *\n * @example\n * import { MAX_INSPECTION_ROWS } from \"@shadow-js/devtools\";\n * const cap: number = MAX_INSPECTION_ROWS; // 500\n * @since 1.0.0\n */\nexport const MAX_INSPECTION_ROWS = 500;\n\n/**\n * Most sources an app may register with {@link registerInspection}. Registering one more is refused,\n * and the names already registered keep working.\n *\n * @example\n * import { MAX_INSPECTIONS } from \"@shadow-js/devtools\";\n * const cap: number = MAX_INSPECTIONS; // 16\n * @since 1.0.0\n */\nexport const MAX_INSPECTIONS = 16;\n\n/**\n * The object installed at `globalThis.__SHADOWJS_DEVTOOLS_HOOK__` by `installHook`. A runtime calls\n * `report` on it; a tool attaches a {@link HookSink} to receive the events.\n *\n * @example\n * import { EVENT, getHook } from \"@shadow-js/devtools\";\n *\n * const hook = getHook();\n * hook?.report(EVENT.FLUSH_END, 0); // a flush that ran no computations\n * @since 1.0.0\n */\nexport interface DevtoolsHook {\n  /** Protocol version; compare with {@link PROTOCOL_VERSION} before reporting. */\n  readonly version: number;\n  /** Runtime to tools. Positional arguments, see {@link EVENT}. Never throws. */\n  report(kind: number, a?: unknown, b?: unknown, c?: unknown, d?: unknown, e?: unknown): void;\n  /**\n   * Registers a sink; returns the function that removes it. Events buffered before the first sink\n   * attached (up to the buffer size given to `installHook`) are replayed to that first sink only.\n   */\n  attach(sink: HookSink): () => void;\n  /** Number of attached sinks. */\n  readonly sinks: number;\n  /**\n   * Registers an inspection source under `name`; re-registering a name replaces it. Returns false when\n   * refused (the limit of {@link MAX_INSPECTIONS} is reached). Hooks of this package provide it; a\n   * hook made by hand need not.\n   */\n  inspect?(name: string, source: InspectionSource): boolean;\n  /** The registered inspection sources, in registration order. Hooks of this package provide it. */\n  inspections?(): readonly InspectionEntry[];\n}\n\n/**\n * Events as they cross a process boundary: plain, JSON-safe objects that refer to nodes by id.\n * `seq` is a gapless counter; `t` is the time in milliseconds on the reporting clock.\n *\n * @since 1.0.0\n */\nexport type WireEvent =\n  | {\n      k: \"owner+\";\n      seq: number;\n      t: number;\n      id: number;\n      parent: number;\n      label: string;\n      name?: string;\n    }\n  | { k: \"owner-\"; seq: number; t: number; id: number }\n  | {\n      k: \"signal+\";\n      seq: number;\n      t: number;\n      id: number;\n      owner: number;\n      name?: string;\n      preview: string;\n    }\n  | {\n      k: \"write\";\n      seq: number;\n      t: number;\n      id: number;\n      preview: string;\n      writer: number;\n      observers: number[];\n    }\n  | {\n      k: \"comp+\";\n      seq: number;\n      t: number;\n      id: number;\n      owner: number;\n      kind: \"memo\" | \"effect\";\n      render: boolean;\n      name?: string;\n    }\n  | {\n      k: \"run\";\n      seq: number;\n      t: number;\n      id: number;\n      start: number;\n      duration: number;\n      changed: boolean;\n      sources: number[];\n    }\n  | { k: \"comp-\"; seq: number; t: number; id: number }\n  | { k: \"mount\"; seq: number; t: number; id: number; name: string }\n  | { k: \"unmount\"; seq: number; t: number; id: number }\n  | {\n      k: \"resource\";\n      seq: number;\n      t: number;\n      id: number;\n      owner: number;\n      state: string;\n      name?: string;\n    }\n  | { k: \"error\"; seq: number; t: number; id: number; message: string; code?: string }\n  | { k: \"hydration\"; seq: number; t: number; message: string; expected: string; actual: string }\n  | { k: \"flush+\"; seq: number; t: number; render: number; user: number }\n  | { k: \"flush-\"; seq: number; t: number; runs: number }\n  | { k: \"store+\"; seq: number; t: number; id: number; owner: number; name: string };\n\n/**\n * Discriminant of {@link WireEvent}.\n *\n * @since 1.0.0\n */\nexport type WireKind = WireEvent[\"k\"];\n\n/**\n * The sentinel used where a wire event refers to \"no node\". The agent assigns node ids from 1, so\n * `NO_ID` never names a node.\n *\n * @example\n * import { NO_ID } from \"@shadow-js/devtools\";\n *\n * const isRoot = (parent: number): boolean => parent === NO_ID;\n * @since 1.0.0\n */\nexport const NO_ID = 0;\n"],"mappings":";;;;;;;;;;;AA2BA,MAAa,mBAAmB;;;;;;;;;;AAWhC,MAAa,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCxB,MAAa,QAkBT;CACF,eAAe;CACf,gBAAgB;CAChB,gBAAgB;CAChB,gBAAgB;CAChB,qBAAqB;CACrB,iBAAiB;CACjB,sBAAsB;CACtB,mBAAmB;CACnB,qBAAqB;CACrB,gBAAgB;CAChB,OAAO;CACP,oBAAoB;CACpB,aAAa;CACb,WAAW;CACX,eAAe;CACf,kBAAkB;CAClB,gBAAgB;AAClB;;;;;;;;;;AA8CA,MAAa,sBAAsB;;;;;;;;;;AAWnC,MAAa,kBAAkB;;;;;;;;;;;AA6H/B,MAAa,QAAQ"}

package/dist/dev/ring.d.ts

@@ -0,0 +1,50 @@
+//#region src/ring.d.ts
+/**
+ * A fixed-capacity ring buffer. `push` is O(1) and never allocates after construction; when full it
+ * overwrites the oldest item, so memory stays bounded however many items are recorded. Items are kept
+ * oldest first. Do not push `undefined`: `toArray` and the iterator skip such items, while `size` still
+ * counts them.
+ *
+ * @typeParam T The item type.
+ * @example
+ * import { RingBuffer } from "@shadow-js/devtools";
+ *
+ * const ring = new RingBuffer<number>(3);
+ * ring.push(1);
+ * ring.push(2);
+ * ring.push(3);
+ * ring.push(4);
+ * ring.toArray(); // [2, 3, 4]
+ * @since 1.0.0
+ */
+export declare class RingBuffer<T> {
+  /** Maximum number of items kept. Fixed at construction. */
+  readonly capacity: number;
+  private readonly slots;
+  private head;
+  private count;
+  private overwritten;
+  /**
+   * @param capacity Maximum number of items kept (a positive integer).
+   * @throws {@link RangeError} When `capacity` is not a positive integer.
+   */
+  constructor(capacity: number);
+  /** Number of items currently held (at most `capacity`). */
+  get size(): number;
+  /** How many items were overwritten because the buffer was full. */
+  get dropped(): number;
+  /** Adds an item, evicting the oldest when full. Returns the evicted item, if any. */
+  push(item: T): T | undefined;
+  /** The item `index` positions after the oldest one, or `undefined` out of range. */
+  at(index: number): T | undefined;
+  /** The newest item, or `undefined` when empty. */
+  last(): T | undefined;
+  /** Items oldest first, as a new array. */
+  toArray(): T[];
+  /** Iterates oldest first without allocating an array. */
+  [Symbol.iterator](): IterableIterator<T>;
+  /** Removes every item (the `dropped` counter is kept). */
+  clear(): void;
+}
+//#endregion
+//# sourceMappingURL=ring.d.ts.map

package/dist/dev/ring.js

@@ -0,0 +1,94 @@
+//#region src/ring.ts
+/**
+* A fixed-capacity ring buffer. `push` is O(1) and never allocates after construction; when full it
+* overwrites the oldest item, so memory stays bounded however many items are recorded. Items are kept
+* oldest first. Do not push `undefined`: `toArray` and the iterator skip such items, while `size` still
+* counts them.
+*
+* @typeParam T The item type.
+* @example
+* import { RingBuffer } from "@shadow-js/devtools";
+*
+* const ring = new RingBuffer<number>(3);
+* ring.push(1);
+* ring.push(2);
+* ring.push(3);
+* ring.push(4);
+* ring.toArray(); // [2, 3, 4]
+* @since 1.0.0
+*/
+var RingBuffer = class {
+	/** Maximum number of items kept. Fixed at construction. */
+	capacity;
+	slots;
+	head = 0;
+	count = 0;
+	overwritten = 0;
+	/**
+	* @param capacity Maximum number of items kept (a positive integer).
+	* @throws {@link RangeError} When `capacity` is not a positive integer.
+	*/
+	constructor(capacity) {
+		if (!Number.isInteger(capacity) || capacity < 1) throw new RangeError("RingBuffer capacity must be a positive integer");
+		this.capacity = capacity;
+		this.slots = new Array(capacity).fill(void 0);
+	}
+	/** Number of items currently held (at most `capacity`). */
+	get size() {
+		return this.count;
+	}
+	/** How many items were overwritten because the buffer was full. */
+	get dropped() {
+		return this.overwritten;
+	}
+	/** Adds an item, evicting the oldest when full. Returns the evicted item, if any. */
+	push(item) {
+		const index = (this.head + this.count) % this.capacity;
+		let evicted;
+		if (this.count === this.capacity) {
+			evicted = this.slots[this.head];
+			this.slots[this.head] = item;
+			this.head = (this.head + 1) % this.capacity;
+			this.overwritten += 1;
+		} else {
+			this.slots[index] = item;
+			this.count += 1;
+		}
+		return evicted;
+	}
+	/** The item `index` positions after the oldest one, or `undefined` out of range. */
+	at(index) {
+		if (index < 0 || index >= this.count) return void 0;
+		return this.slots[(this.head + index) % this.capacity];
+	}
+	/** The newest item, or `undefined` when empty. */
+	last() {
+		return this.count === 0 ? void 0 : this.at(this.count - 1);
+	}
+	/** Items oldest first, as a new array. */
+	toArray() {
+		const out = [];
+		for (let i = 0; i < this.count; i += 1) {
+			const item = this.slots[(this.head + i) % this.capacity];
+			if (item !== void 0) out.push(item);
+		}
+		return out;
+	}
+	/** Iterates oldest first without allocating an array. */
+	*[Symbol.iterator]() {
+		for (let i = 0; i < this.count; i += 1) {
+			const item = this.slots[(this.head + i) % this.capacity];
+			if (item !== void 0) yield item;
+		}
+	}
+	/** Removes every item (the `dropped` counter is kept). */
+	clear() {
+		this.slots.fill(void 0);
+		this.head = 0;
+		this.count = 0;
+	}
+};
+//#endregion
+export { RingBuffer };
+
+//# sourceMappingURL=ring.js.map

package/dist/dev/ring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ring.js","names":[],"sources":["../../src/ring.ts"],"sourcesContent":["/**\n * A fixed-capacity ring buffer. `push` is O(1) and never allocates after construction; when full it\n * overwrites the oldest item, so memory stays bounded however many items are recorded. Items are kept\n * oldest first. Do not push `undefined`: `toArray` and the iterator skip such items, while `size` still\n * counts them.\n *\n * @typeParam T The item type.\n * @example\n * import { RingBuffer } from \"@shadow-js/devtools\";\n *\n * const ring = new RingBuffer<number>(3);\n * ring.push(1);\n * ring.push(2);\n * ring.push(3);\n * ring.push(4);\n * ring.toArray(); // [2, 3, 4]\n * @since 1.0.0\n */\nexport class RingBuffer<T> {\n  /** Maximum number of items kept. Fixed at construction. */\n  readonly capacity: number;\n  private readonly slots: Array<T | undefined>;\n  private head = 0;\n  private count = 0;\n  private overwritten = 0;\n\n  /**\n   * @param capacity Maximum number of items kept (a positive integer).\n   * @throws {@link RangeError} When `capacity` is not a positive integer.\n   */\n  constructor(capacity: number) {\n    if (!Number.isInteger(capacity) || capacity < 1) {\n      throw new RangeError(\"RingBuffer capacity must be a positive integer\");\n    }\n    this.capacity = capacity;\n    this.slots = new Array<T | undefined>(capacity).fill(undefined);\n  }\n\n  /** Number of items currently held (at most `capacity`). */\n  get size(): number {\n    return this.count;\n  }\n\n  /** How many items were overwritten because the buffer was full. */\n  get dropped(): number {\n    return this.overwritten;\n  }\n\n  /** Adds an item, evicting the oldest when full. Returns the evicted item, if any. */\n  push(item: T): T | undefined {\n    const index = (this.head + this.count) % this.capacity;\n    let evicted: T | undefined;\n    if (this.count === this.capacity) {\n      evicted = this.slots[this.head];\n      this.slots[this.head] = item;\n      this.head = (this.head + 1) % this.capacity;\n      this.overwritten += 1;\n    } else {\n      this.slots[index] = item;\n      this.count += 1;\n    }\n    return evicted;\n  }\n\n  /** The item `index` positions after the oldest one, or `undefined` out of range. */\n  at(index: number): T | undefined {\n    if (index < 0 || index >= this.count) return undefined;\n    return this.slots[(this.head + index) % this.capacity];\n  }\n\n  /** The newest item, or `undefined` when empty. */\n  last(): T | undefined {\n    return this.count === 0 ? undefined : this.at(this.count - 1);\n  }\n\n  /** Items oldest first, as a new array. */\n  toArray(): T[] {\n    const out: T[] = [];\n    for (let i = 0; i < this.count; i += 1) {\n      const item = this.slots[(this.head + i) % this.capacity];\n      if (item !== undefined) out.push(item);\n    }\n    return out;\n  }\n\n  /** Iterates oldest first without allocating an array. */\n  *[Symbol.iterator](): IterableIterator<T> {\n    for (let i = 0; i < this.count; i += 1) {\n      const item = this.slots[(this.head + i) % this.capacity];\n      if (item !== undefined) yield item;\n    }\n  }\n\n  /** Removes every item (the `dropped` counter is kept). */\n  clear(): void {\n    this.slots.fill(undefined);\n    this.head = 0;\n    this.count = 0;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAkBA,IAAa,aAAb,MAA2B;;CAEzB;CACA;CACA,OAAe;CACf,QAAgB;CAChB,cAAsB;;;;;CAMtB,YAAY,UAAkB;EAC5B,IAAI,CAAC,OAAO,UAAU,QAAQ,KAAK,WAAW,GAC5C,MAAM,IAAI,WAAW,gDAAgD;EAEvE,KAAK,WAAW;EAChB,KAAK,QAAQ,IAAI,MAAqB,QAAQ,CAAC,CAAC,KAAK,KAAA,CAAS;CAChE;;CAGA,IAAI,OAAe;EACjB,OAAO,KAAK;CACd;;CAGA,IAAI,UAAkB;EACpB,OAAO,KAAK;CACd;;CAGA,KAAK,MAAwB;EAC3B,MAAM,SAAS,KAAK,OAAO,KAAK,SAAS,KAAK;EAC9C,IAAI;EACJ,IAAI,KAAK,UAAU,KAAK,UAAU;GAChC,UAAU,KAAK,MAAM,KAAK;GAC1B,KAAK,MAAM,KAAK,QAAQ;GACxB,KAAK,QAAQ,KAAK,OAAO,KAAK,KAAK;GACnC,KAAK,eAAe;EACtB,OAAO;GACL,KAAK,MAAM,SAAS;GACpB,KAAK,SAAS;EAChB;EACA,OAAO;CACT;;CAGA,GAAG,OAA8B;EAC/B,IAAI,QAAQ,KAAK,SAAS,KAAK,OAAO,OAAO,KAAA;EAC7C,OAAO,KAAK,OAAO,KAAK,OAAO,SAAS,KAAK;CAC/C;;CAGA,OAAsB;EACpB,OAAO,KAAK,UAAU,IAAI,KAAA,IAAY,KAAK,GAAG,KAAK,QAAQ,CAAC;CAC9D;;CAGA,UAAe;EACb,MAAM,MAAW,CAAC;EAClB,KAAK,IAAI,IAAI,GAAG,IAAI,KAAK,OAAO,KAAK,GAAG;GACtC,MAAM,OAAO,KAAK,OAAO,KAAK,OAAO,KAAK,KAAK;GAC/C,IAAI,SAAS,KAAA,GAAW,IAAI,KAAK,IAAI;EACvC;EACA,OAAO;CACT;;CAGA,EAAE,OAAO,YAAiC;EACxC,KAAK,IAAI,IAAI,GAAG,IAAI,KAAK,OAAO,KAAK,GAAG;GACtC,MAAM,OAAO,KAAK,OAAO,KAAK,OAAO,KAAK,KAAK;GAC/C,IAAI,SAAS,KAAA,GAAW,MAAM;EAChC;CACF;;CAGA,QAAc;EACZ,KAAK,MAAM,KAAK,KAAA,CAAS;EACzB,KAAK,OAAO;EACZ,KAAK,QAAQ;CACf;AACF"}