@lifeart/async-dom 2.0.0-alpha.3

package/dist/base.d.ts

@@ -0,0 +1,398 @@
+//#region src/core/protocol.d.ts
+/**
+ * Type-safe message protocol for async-dom communication.
+ *
+ * All messages between the main thread and worker threads use discriminated
+ * unions for compile-time safety and exhaustive switch handling.
+ */
+/**
+ * Branded numeric type for DOM node identifiers.
+ * The brand prevents accidental use of plain numbers as NodeIds.
+ */
+type NodeId = number & {
+  readonly __brand: "NodeId";
+};
+/** Branded string type identifying an application instance. */
+type AppId = string & {
+  readonly __brand: "AppId";
+};
+/** Branded string type identifying a connected client (for multi-client server mode). */
+type ClientId = string & {
+  readonly __brand: "ClientId";
+};
+/**
+ * Reserved structural node IDs.
+ * These correspond to the well-known DOM nodes that always exist.
+ * Dynamic node IDs start at 11 to avoid collisions.
+ */
+declare const BODY_NODE_ID: NodeId;
+declare const HEAD_NODE_ID: NodeId;
+declare const HTML_NODE_ID: NodeId;
+declare const DOCUMENT_NODE_ID: NodeId;
+/**
+ * Create a new unique numeric NodeId (auto-incremented).
+ */
+declare function createNodeId(): NodeId;
+/**
+ * Reset the node ID counter (for testing only).
+ */
+
+/** Cast a plain string to a branded AppId. */
+declare function createAppId(id: string): AppId;
+/** Cast a plain string to a branded ClientId. */
+declare function createClientId(id: string): ClientId;
+/** Standard DOM insertAdjacentHTML position values. */
+type InsertPosition = "beforebegin" | "afterbegin" | "beforeend" | "afterend";
+/**
+ * Discriminated union of all DOM mutations sent from worker to main thread.
+ *
+ * Mutation lifecycle:
+ * 1. Worker-side VirtualElement/VirtualDocument methods create DomMutation objects
+ * 2. Mutations are collected by MutationCollector into batches
+ * 3. Batches are wrapped in a MutationMessage and sent via Transport
+ * 4. Main-thread FrameScheduler queues and prioritizes mutations
+ * 5. DomRenderer.apply() executes each mutation against the real DOM
+ *
+ * Each variant carries the target node's `id` plus action-specific data.
+ * Mutations marked `optional: true` (e.g., style updates) may be dropped
+ * by the scheduler under frame budget pressure.
+ */
+type DomMutation = {
+  action: "createNode";
+  id: NodeId;
+  tag: string;
+  textContent?: string;
+} | {
+  action: "createComment";
+  id: NodeId;
+  textContent: string;
+} | {
+  action: "appendChild";
+  id: NodeId;
+  childId: NodeId;
+} | {
+  action: "removeNode";
+  id: NodeId;
+} | {
+  action: "removeChild";
+  id: NodeId;
+  childId: NodeId;
+} | {
+  action: "insertBefore";
+  id: NodeId;
+  newId: NodeId;
+  refId: NodeId | null;
+} | {
+  action: "setAttribute";
+  id: NodeId;
+  name: string;
+  value: string;
+  optional?: boolean;
+} | {
+  action: "removeAttribute";
+  id: NodeId;
+  name: string;
+} | {
+  action: "setStyle";
+  id: NodeId;
+  property: string;
+  value: string;
+  optional?: boolean;
+} | {
+  action: "setProperty";
+  id: NodeId;
+  property: string;
+  value: unknown;
+} | {
+  action: "setTextContent";
+  id: NodeId;
+  textContent: string;
+} | {
+  action: "setClassName";
+  id: NodeId;
+  name: string;
+} | {
+  action: "setHTML";
+  id: NodeId;
+  html: string;
+} | {
+  action: "addEventListener";
+  id: NodeId;
+  name: string;
+  listenerId: string;
+} | {
+  action: "headAppendChild";
+  id: NodeId;
+} | {
+  action: "bodyAppendChild";
+  id: NodeId;
+} | {
+  action: "pushState";
+  state: unknown;
+  title: string;
+  url: string;
+} | {
+  action: "replaceState";
+  state: unknown;
+  title: string;
+  url: string;
+} | {
+  action: "scrollTo";
+  x: number;
+  y: number;
+} | {
+  action: "insertAdjacentHTML";
+  id: NodeId;
+  position: InsertPosition;
+  html: string;
+} | {
+  action: "configureEvent";
+  id: NodeId;
+  name: string;
+  preventDefault: boolean;
+  passive?: boolean;
+} | {
+  action: "removeEventListener";
+  id: NodeId;
+  listenerId: string;
+} | {
+  action: "callMethod";
+  id: NodeId;
+  method: string;
+  args: unknown[];
+};
+/** Convenience union of all possible mutation action string literals. */
+type MutationAction = DomMutation["action"];
+/** Scheduler priority level. High-priority mutations are processed first each frame. */
+type Priority = "high" | "normal" | "low";
+/**
+ * Envelope wrapping a batch of mutations with routing and timing metadata.
+ * Sent from worker thread to main thread via Transport.
+ */
+interface MutationMessage {
+  type: "mutation";
+  appId: AppId;
+  uid: number;
+  mutations: DomMutation[];
+  priority?: Priority;
+  sentAt?: number;
+  /** Causal event that triggered this batch (Feature 15: Causality Graph). */
+  causalEvent?: {
+    eventType: string;
+    listenerId: string;
+    timestamp: number;
+  };
+}
+/**
+ * Serialized event data sent from main thread to worker.
+ * Contains a flat subset of DOM event properties that can be transferred via postMessage.
+ * Target and relatedTarget are serialized as NodeId strings, not DOM references.
+ */
+interface SerializedEvent {
+  type: string;
+  target: string | null;
+  currentTarget: string | null;
+  clientX?: number;
+  clientY?: number;
+  pageX?: number;
+  pageY?: number;
+  screenX?: number;
+  screenY?: number;
+  offsetX?: number;
+  offsetY?: number;
+  button?: number;
+  buttons?: number;
+  key?: string;
+  code?: string;
+  keyCode?: number;
+  altKey?: boolean;
+  ctrlKey?: boolean;
+  metaKey?: boolean;
+  shiftKey?: boolean;
+  bubbles?: boolean;
+  cancelable?: boolean;
+  composed?: boolean;
+  detail?: number;
+  eventPhase?: number;
+  isTrusted?: boolean;
+  timeStamp?: number;
+  data?: string;
+  inputType?: string;
+  relatedTarget?: string | null;
+  deltaX?: number;
+  deltaY?: number;
+  deltaZ?: number;
+  deltaMode?: number;
+  value?: string;
+  checked?: boolean;
+  selectedIndex?: number;
+  currentTime?: number;
+  duration?: number;
+  paused?: boolean;
+  ended?: boolean;
+  readyState?: number;
+}
+/** Event message sent from main thread to worker to dispatch a DOM event. */
+interface EventMessage {
+  type: "event";
+  appId: AppId;
+  listenerId: string;
+  event: SerializedEvent;
+  clientId?: ClientId;
+}
+/** Serialized window.location data sent during app initialization. */
+interface SerializedLocation {
+  hash: string;
+  href: string;
+  port: string;
+  host: string;
+  origin: string;
+  hostname: string;
+  pathname: string;
+  protocol: string;
+  search: string;
+  state: unknown;
+}
+/** Serialized error data for cross-thread error reporting, including causal chain via `cause`. */
+interface SerializedError {
+  message: string;
+  stack?: string;
+  name?: string;
+  cause?: SerializedError;
+  filename?: string;
+  lineno?: number;
+  colno?: number;
+  isUnhandledRejection?: boolean;
+}
+/**
+ * System-level control messages exchanged between main thread and worker.
+ * Includes lifecycle events (init/ready), sync queries, diagnostics, and multi-client management.
+ */
+type SystemMessage = {
+  type: "init";
+  appId: AppId;
+  location: SerializedLocation;
+  sharedBuffer?: SharedArrayBuffer;
+} | {
+  type: "ready";
+  appId: AppId;
+} | {
+  type: "error";
+  appId: AppId;
+  error: SerializedError;
+} | {
+  type: "visibility";
+  state: "visible" | "hidden" | "prerender";
+} | {
+  type: "query";
+  appId: AppId;
+  uid: number;
+  nodeId: NodeId;
+  query: "boundingRect" | "computedStyle" | "nodeProperty" | "windowProperty";
+  property?: string;
+} | {
+  type: "queryResult";
+  uid: number;
+  result: unknown;
+} | {
+  type: "debugQuery";
+  query: string;
+} | {
+  type: "debugResult";
+  query: string;
+  result: unknown;
+} | {
+  type: "eventTimingResult";
+  listenerId: string;
+  eventType: string;
+  dispatchMs: number;
+  mutationCount: number;
+  transportMs: number;
+} | {
+  type: "perfEntries";
+  appId: AppId;
+  entries: PerfEntryData[];
+} | {
+  type: "ping";
+} | {
+  type: "pong";
+} | {
+  type: "ack";
+  appId: AppId;
+  lastUid: number;
+} | {
+  type: "clientConnect";
+  clientId: ClientId;
+  metadata?: Record<string, unknown>;
+} | {
+  type: "clientDisconnect";
+  clientId: ClientId;
+} | {
+  type: "snapshotComplete";
+};
+/** Serialized performance entry sent from worker to main thread (Feature 16). */
+interface PerfEntryData {
+  name: string;
+  startTime: number;
+  duration: number;
+  entryType: string;
+}
+/** Top-level discriminated union of all messages in the async-dom protocol. */
+type Message = MutationMessage | EventMessage | SystemMessage;
+/** Type guard: narrows a Message to MutationMessage. */
+//#endregion
+//#region src/transport/base.d.ts
+/**
+ * The connection lifecycle state of a transport.
+ *
+ * - `"connecting"` — Transport is establishing a connection.
+ * - `"open"` — Transport is connected and ready to send/receive messages.
+ * - `"reconnecting"` — Transport lost connection and is attempting to reconnect.
+ * - `"closed"` — Transport is permanently closed and cannot be reused.
+ */
+type TransportReadyState = "connecting" | "open" | "reconnecting" | "closed";
+/** Cumulative message statistics collected by a transport. */
+interface TransportStats {
+  /** Total number of messages sent. */
+  messageCount: number;
+  /** Total bytes sent (approximate, based on JSON string length). */
+  totalBytes: number;
+  /** Size in bytes of the largest single message sent. */
+  largestMessageBytes: number;
+  /** Size in bytes of the most recently sent message. */
+  lastMessageBytes: number;
+}
+/**
+ * Bidirectional message transport between the main thread and a worker or remote process.
+ *
+ * All async-dom communication flows through this interface. Built-in implementations
+ * include `WorkerTransport`, `WebSocketTransport`, `BinaryWorkerTransport`, and
+ * `WebSocketServerTransport`.
+ */
+interface Transport {
+  /** Send a message to the other end of the transport. */
+  send(message: Message): void;
+  /** Register a handler that is called for every incoming message. */
+  onMessage(handler: (message: Message) => void): void;
+  /** Permanently close the transport, releasing all resources. */
+  close(): void;
+  /** Current connection state of the transport. */
+  readonly readyState: TransportReadyState;
+  /** Called when the transport encounters a connection error. */
+  onError?: (error: Error) => void;
+  /** Called when the transport is closed (locally or remotely). */
+  onClose?: () => void;
+  /** Return cumulative send statistics. Only populated when stats are enabled. */
+  getStats?(): TransportStats;
+  /** Enable or disable statistics collection. */
+  enableStats?(enabled: boolean): void;
+  /** Maximum message size in bytes. Messages exceeding this are dropped. */
+  maxMessageSize?: number;
+  /** Number of bytes queued for sending but not yet transmitted. */
+  bufferedAmount?: number;
+}
+//# sourceMappingURL=base.d.ts.map
+
+//#endregion
+export { createClientId as C, createAppId as S, Priority as _, BODY_NODE_ID as a, SerializedLocation as b, DomMutation as c, HTML_NODE_ID as d, InsertPosition as f, NodeId as g, MutationMessage as h, AppId as i, EventMessage as l, MutationAction as m, TransportReadyState as n, ClientId as o, Message as p, TransportStats as r, DOCUMENT_NODE_ID as s, Transport as t, HEAD_NODE_ID as u, SerializedError as v, createNodeId as w, SystemMessage as x, SerializedEvent as y };
+//# sourceMappingURL=base.d.ts.map

package/dist/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","names":[],"sources":["../src/core/protocol.ts","../src/transport/base.ts"],"sourcesContent":[],"mappings":"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"}