@shadow-js/devtools 0.0.0-stage → 1.0.0

package/dist/dev/agent.d.ts

@@ -0,0 +1,239 @@
+import { DevtoolsHook, HookSink, WireEvent } from "./protocol.js";
+import { RingBuffer } from "./ring.js";
+import { InspectorModel, ModelLimits, ModelState } from "./model.js";
+import { GraphSnapshot } from "./inspector.js";
+//#region src/agent.d.ts
+/**
+ * Options of {@link createAgent}. Every field is optional.
+ *
+ * @since 1.0.0
+ */
+export interface AgentOptions {
+  /** Capacities of the model's buffers. The values left out take the defaults of `DEFAULT_LIMITS`. */
+  limits?: Partial<ModelLimits>;
+  /**
+   * Raw events kept for the events log. The newest are kept; older ones are overwritten and counted
+   * in `dropped`.
+   *
+   * @default 10000
+   */
+  events?: number;
+  /**
+   * Most events waiting for subscribers. When this many are pending they are delivered at once,
+   * instead of at the end of the current microtask.
+   *
+   * @default 10000
+   */
+  maxPending?: number;
+  /**
+   * Maximum length of a value preview, in characters.
+   *
+   * @default 80
+   */
+  previewLength?: number;
+  /**
+   * The clock, in milliseconds. Defaults to `performance.now` (or `Date.now` where it is missing).
+   */
+  now?: () => number;
+  /**
+   * Writes a signal node for the value editor. Pass `writeSignal` from `@shadow-js/core/extend`.
+   * Without it signals are shown but not editable: a write is refused with "Editing is not enabled.".
+   */
+  writeSignal?: (node: never, value: never) => unknown;
+}
+/**
+ * Counters of what the agent saw. They keep growing while the agent runs; {@link Agent.clear} does not
+ * reset them.
+ *
+ * @since 1.0.0
+ */
+export interface AgentStats {
+  /** Events the agent was offered while it was not paused. */
+  received: number;
+  /** Events turned into wire events. */
+  recorded: number;
+  /**
+   * Events the agent skipped on purpose: objects created inside {@link Agent.quiet} (the tools' own
+   * UI), dispose and unmount events for objects it never named, malformed store handles, and event
+   * kinds from a newer runtime.
+   */
+  ignored: number;
+  /**
+   * Writes, runs and mounts about objects the agent never saw created (reported before it attached,
+   * when the hook's replay buffer had been released).
+   */
+  unknown: number;
+}
+/**
+ * A command a panel sends to the agent, answered by {@link Agent.handle}. All fields are plain data,
+ * so a command can cross a message channel:
+ *
+ * - `snapshot`: the model's state.
+ * - `value` and `write`: read a signal as editable text, or write it.
+ * - `store` and `store-set`: read a store as editable text, or write one path of it.
+ * - `highlight`: the agent acknowledges it; the page draws the highlight (see `createLocalBackend`).
+ * - `pause`, `resume`, `clear`: control recording. `stats`: the counters.
+ * - `inspect`: every inspection source registered with `registerInspection`, read now.
+ *
+ * @since 1.0.0
+ */
+export type AgentRequest = {
+  type: "snapshot";
+} | {
+  type: "value";
+  id: number;
+} | {
+  type: "write";
+  id: number;
+  text: string;
+} | {
+  type: "store";
+  id: number;
+} | {
+  type: "store-set";
+  id: number;
+  path: Array<string | number>;
+  text: string;
+} | {
+  type: "highlight";
+  id: number | null;
+} | {
+  type: "pause";
+} | {
+  type: "resume";
+} | {
+  type: "clear";
+} | {
+  type: "stats";
+} | {
+  type: "inspect";
+};
+/**
+ * The answer to an {@link AgentRequest}: the result, or an error message to show the user.
+ *
+ * @since 1.0.0
+ */
+export type AgentResponse = {
+  ok: true;
+  result: unknown;
+} | {
+  ok: false;
+  error: string;
+};
+/**
+ * The value of a node, as text, for the value editor.
+ *
+ * @since 1.0.0
+ */
+export interface ValueResult {
+  /** The node that was asked for. */
+  id: number;
+  /** `signal` for a signal, `store` for a store. */
+  kind: "signal" | "store";
+  /** The value as editable text (see {@link toEditableText}). */
+  text: string;
+  /** True when the panel may write it: a store always, a signal only when `writeSignal` is set. */
+  editable: boolean;
+}
+/**
+ * The agent. It receives the runtime's own objects from the hook, turns them into id-based
+ * {@link WireEvent}s and folds them into an {@link InspectorModel}. Recording is O(1) per event and
+ * every buffer is bounded: the raw event ring, the model's run, write and flush rings, the disposed-node
+ * graveyard and the live node count.
+ *
+ * A development tool: the hook it attaches to is installed only in development builds (see
+ * `installHook`).
+ *
+ * @since 1.0.0
+ */
+export interface Agent extends HookSink {
+  /** The model the events are folded into. */
+  readonly model: InspectorModel;
+  /** The newest raw events, as many as the `events` option holds (default 10000). */
+  readonly events: RingBuffer<WireEvent>;
+  /** Counters of what the agent saw. */
+  readonly stats: Readonly<AgentStats>;
+  /** True while the agent drops the events the runtime reports (see {@link Agent.pause}). */
+  readonly paused: boolean;
+  /**
+   * Attaches the agent to `hook`, so that the hook delivers its events to the agent. Pass the hook
+   * from `installHook` or `getHook`.
+   *
+   * @param hook The hook to listen to.
+   * @returns A function that detaches the agent from the hook.
+   */
+  attach(hook: DevtoolsHook): () => void;
+  /**
+   * Calls `listener` with batches of new events: once per microtask, or sooner when `maxPending`
+   * events are waiting. Only events recorded after the call are delivered.
+   *
+   * @param listener Receives each batch, oldest first.
+   * @returns A function that unsubscribes the listener.
+   */
+  subscribe(listener: (events: readonly WireEvent[]) => void): () => void;
+  /** Delivers the pending events to the subscribers now, instead of at the end of the microtask. */
+  flush(): void;
+  /**
+   * Runs `fn` while the agent ignores everything the runtime creates, and everything created under
+   * those nodes. Use it to mount the tools' own UI, so that the tools never inspect themselves. An error
+   * thrown by `fn` propagates.
+   *
+   * @param fn The work to run.
+   * @returns What `fn` returns.
+   */
+  quiet<T>(fn: () => T): T;
+  /** Stops recording: events the runtime reports are dropped until {@link Agent.resume}. */
+  pause(): void;
+  /** Resumes recording after {@link Agent.pause}. */
+  resume(): void;
+  /**
+   * Forgets everything recorded so far: the model's nodes and records, the event ring, and the
+   * references to live nodes. Nodes created later are tracked; live ones are not, and later events about
+   * them count as unknown. {@link AgentStats} are not reset.
+   */
+  clear(): void;
+  /** The graph snapshot of the model (see `snapshotOf`). Each call builds a new object. */
+  snapshot(): GraphSnapshot;
+  /** The model state, for sending to a remote panel. */
+  state(): ModelState;
+  /**
+   * Answers a panel command. Never throws: a failure, such as an error from writing user state, comes
+   * back as `ok: false`, and so does an unknown command.
+   *
+   * @param request The command.
+   * @returns The answer.
+   */
+  handle(request: AgentRequest): AgentResponse;
+  /**
+   * The connected DOM nodes that the component `id` rendered, for highlighting. Empty when the
+   * component is unknown or its nodes left the page. The agent holds the nodes weakly.
+   *
+   * @param id The component's node id.
+   * @returns The nodes.
+   */
+  nodesOf(id: number): Node[];
+  /**
+   * Detaches from every hook it was attached to, and drops the listeners and the references to live
+   * signals, components and stores. The model and the event ring keep what they recorded.
+   */
+  dispose(): void;
+}
+/**
+ * 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
+ */
+export declare function createAgent(options?: AgentOptions): Agent;
+//#endregion
+//# sourceMappingURL=agent.d.ts.map