@lifeart/async-dom 2.0.0-alpha.3

package/dist/debug.d.ts

@@ -0,0 +1,145 @@
+import { c as DomMutation } from "./base.js";
+
+//#region src/core/debug.d.ts
+
+/**
+ * Options for enabling debug logging and the in-page devtools panel.
+ *
+ * Each `log*` flag enables a category of structured log output. Provide a
+ * custom `logger` to redirect output (e.g. to a remote telemetry service).
+ */
+interface DebugOptions {
+  /** Log every DOM mutation applied by the renderer. */
+  logMutations?: boolean;
+  /** Log event serialization and dispatch timing. */
+  logEvents?: boolean;
+  /** Log synchronous DOM read requests (getBoundingClientRect, computedStyle, etc.). */
+  logSyncReads?: boolean;
+  /** Log per-frame scheduler statistics (actions processed, frame time, queue depth). */
+  logScheduler?: boolean;
+  /** Log warnings such as missing nodes, sync timeouts, and blocked properties. */
+  logWarnings?: boolean;
+  /** Custom logger implementation. Unset methods fall back to `console.*`. */
+  logger?: Partial<DebugLogger>;
+  /** Expose `__ASYNC_DOM_DEVTOOLS__` on `globalThis` and inject the in-page devtools panel. */
+  exposeDevtools?: boolean;
+}
+/**
+ * Custom logger that receives structured debug entries.
+ *
+ * Implement any subset of these methods and pass via `DebugOptions.logger`.
+ */
+interface DebugLogger {
+  /** Called for each DOM mutation applied on the main thread. */
+  mutation(entry: MutationLogEntry): void;
+  /** Called for event serialization and dispatch timing. */
+  event(entry: EventLogEntry): void;
+  /** Called for each synchronous DOM read request. */
+  syncRead(entry: SyncReadLogEntry): void;
+  /** Called once per scheduler frame with aggregate statistics. */
+  scheduler(entry: SchedulerLogEntry): void;
+  /** Called for async-dom warnings (missing nodes, timeouts, etc.). */
+  warning(entry: WarningLogEntry): void;
+}
+/** A single DOM mutation log entry emitted by the debug system. */
+interface MutationLogEntry {
+  /** Which thread generated this entry. */
+  side: "worker" | "main";
+  /** The mutation action name (e.g. "createElement", "setAttribute"). */
+  action: string;
+  /** The full mutation payload. */
+  mutation: DomMutation;
+  /** High-resolution timestamp (via `performance.now()`). */
+  timestamp: number;
+  /** Batch UID that groups related mutations from a single flush. */
+  batchUid?: number;
+}
+/** A single event timing log entry emitted by the debug system. */
+interface EventLogEntry {
+  /** Which thread generated this entry. */
+  side: "worker" | "main";
+  /** Whether this captures serialization or dispatch timing. */
+  phase: "serialize" | "dispatch";
+  /** The DOM event type (e.g. "click", "input"). */
+  eventType: string;
+  /** Unique listener identifier. */
+  listenerId: string;
+  /** Node ID of the event target, or `null` if unavailable. */
+  targetId: string | null;
+  /** High-resolution timestamp (via `performance.now()`). */
+  timestamp: number;
+  /** Time in ms the event spent in transport between threads. */
+  transportMs?: number;
+  /** Time in ms the worker spent dispatching the event handler. */
+  dispatchMs?: number;
+  /** Number of DOM mutations produced by the event handler. */
+  mutationCount?: number;
+}
+/** A single synchronous DOM read log entry. */
+interface SyncReadLogEntry {
+  /** The query type enum value (BoundingRect, ComputedStyle, etc.). */
+  queryType: number;
+  /** The target node ID as a string. */
+  nodeId: string;
+  /** Round-trip latency in milliseconds. */
+  latencyMs: number;
+  /** Whether the read succeeded, timed out, or threw an error. */
+  result: "success" | "timeout" | "error";
+  /** High-resolution timestamp (via `performance.now()`). */
+  timestamp: number;
+}
+/** A single scheduler frame log entry. */
+interface SchedulerLogEntry {
+  /** Monotonically increasing frame counter. */
+  frameId: number;
+  /** Number of mutations processed in this frame. */
+  actionsProcessed: number;
+  /** Total wall-clock time spent processing this frame in ms. */
+  frameTimeMs: number;
+  /** Number of mutations remaining in the queue after this frame. */
+  queueDepth: number;
+  /** High-resolution timestamp (via `performance.now()`). */
+  timestamp: number;
+}
+/** A warning entry emitted when async-dom detects a potential problem. */
+interface WarningLogEntry {
+  /** Machine-readable warning code (see `WarningCode`). */
+  code: string;
+  /** Human-readable description of the problem. */
+  message: string;
+  /** Additional context data relevant to the warning. */
+  context: Record<string, unknown>;
+  /** High-resolution timestamp (via `performance.now()`). */
+  timestamp: number;
+}
+declare const WarningCode: {
+  readonly MISSING_NODE: "ASYNC_DOM_MISSING_NODE";
+  readonly SYNC_TIMEOUT: "ASYNC_DOM_SYNC_TIMEOUT";
+  readonly LISTENER_NOT_FOUND: "ASYNC_DOM_LISTENER_NOT_FOUND";
+  readonly EVENT_ATTACH_FAILED: "ASYNC_DOM_EVENT_ATTACH_FAILED";
+  readonly TRANSPORT_NOT_OPEN: "ASYNC_DOM_TRANSPORT_NOT_OPEN";
+  readonly BLOCKED_PROPERTY: "ASYNC_DOM_BLOCKED_PROPERTY";
+  readonly WORKER_ERROR: "WORKER_ERROR";
+  readonly WORKER_UNHANDLED_REJECTION: "WORKER_UNHANDLED_REJECTION";
+};
+declare class DebugStats {
+  mutationsAdded: number;
+  mutationsCoalesced: number;
+  mutationsFlushed: number;
+  mutationsApplied: number;
+  eventsForwarded: number;
+  eventsDispatched: number;
+  syncReadRequests: number;
+  syncReadTimeouts: number;
+  snapshot(): Record<string, number>;
+  reset(): void;
+}
+/**
+ * Mutation-to-event correlation index (Feature 19: "Why Was This Node Updated?").
+ *
+ * Indexes mutations by nodeId and links them to their batch and causal event,
+ * allowing reverse lookups: given a nodeId, find why it was updated.
+ */
+//#endregion
+export { MutationLogEntry as a, WarningCode as c, EventLogEntry as i, WarningLogEntry as l, DebugOptions as n, SchedulerLogEntry as o, DebugStats as r, SyncReadLogEntry as s, DebugLogger as t };
+//# sourceMappingURL=debug.d.ts.map

package/dist/debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","names":[],"sources":["../src/core/debug.ts"],"sourcesContent":[],"mappings":";;;;;;AAQA;;;;AAYiB,UAZA,YAAA,CAYA;EAUA;EAAW,YAAA,CAAA,EAAA,OAAA;;WAId,CAAA,EAAA,OAAA;;cAII,CAAA,EAAA,OAAA;;EAEa,YAAA,CAAA,EAAA,OAAA;EAId;EAcA,WAAA,CAAA,EAAA,OAAa;EAsBb;EAcA,MAAA,CAAA,EA1EP,OA0EO,CA1EC,WA0EgB,CAAA;EAcjB;EAWJ,cASH,CAAA,EAAA,OAAA;AAsEV;;;;;;UAxKiB,WAAA;;kBAEA;;eAEH;;kBAEG;;mBAEC;;iBAEF;;;UAIC,gBAAA;;;;;;YAMN;;;;;;;UAQM,aAAA;;;;;;;;;;;;;;;;;;;;;UAsBA,gBAAA;;;;;;;;;;;;;UAcA,iBAAA;;;;;;;;;;;;;UAcA,eAAA;;;;;;WAMP;;;;cAKG;;;;;;;;;;cA+EA,UAAA;;;;;;;;;cAUA"}

package/dist/index.cjs

@@ -0,0 +1,26 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_sync_channel = require("./sync-channel.cjs");
+const require_main_thread = require("./main-thread.cjs");
+const require_ws_transport = require("./ws-transport.cjs");
+const require_worker_transport = require("./worker-transport.cjs");
+exports.BODY_NODE_ID = require_sync_channel.BODY_NODE_ID;
+exports.BinaryWorkerSelfTransport = require_ws_transport.BinaryWorkerSelfTransport;
+exports.BinaryWorkerTransport = require_ws_transport.BinaryWorkerTransport;
+exports.DOCUMENT_NODE_ID = require_sync_channel.DOCUMENT_NODE_ID;
+exports.DebugStats = require_sync_channel.DebugStats;
+exports.DomRenderer = require_main_thread.DomRenderer;
+exports.EventBridge = require_main_thread.EventBridge;
+exports.FrameScheduler = require_main_thread.FrameScheduler;
+exports.HEAD_NODE_ID = require_sync_channel.HEAD_NODE_ID;
+exports.HTML_NODE_ID = require_sync_channel.HTML_NODE_ID;
+exports.ThreadManager = require_main_thread.ThreadManager;
+exports.WarningCode = require_sync_channel.WarningCode;
+exports.WorkerSelfTransport = require_worker_transport.WorkerSelfTransport;
+exports.WorkerTransport = require_worker_transport.WorkerTransport;
+exports.createAppId = require_sync_channel.createAppId;
+exports.createAsyncDom = require_main_thread.createAsyncDom;
+exports.createClientId = require_sync_channel.createClientId;
+exports.createNodeId = require_sync_channel.createNodeId;
+exports.decodeBinaryMessage = require_ws_transport.decodeBinaryMessage;
+exports.encodeBinaryMessage = require_ws_transport.encodeBinaryMessage;
+exports.sanitizeHTML = require_main_thread.sanitizeHTML;