Generative DOM Class

The main entry point for the library. Creates a streaming markdown parser and renderer bound to a container element.

Import

import { GenerativeDom } from "@generative-dom/core";

Constructor

new GenerativeDom(options: GenerativeDomOptions)

Generative DOMOptions

interface GenerativeDomOptions {
  /** The DOM element that GenerativeDom will render into. */
  container: HTMLElement;

  /** Minimum interval in milliseconds between renders. Default: 16 (~1 frame). */
  debounceMs?: number;

  /** Container width in CSS pixels, 'auto' to fill parent, or undefined for no override. */
  width?: number | "auto";

  /** Container height in CSS pixels, 'auto' to grow with content, or undefined for no override. */
  height?: number | "auto";

  /** Plugins to register. Order matters for priority ties. */
  plugins?: GenerativeDomPlugin[];

  /** Structured error reporting callback. */
  onError?: (error: GenerativeDomError) => void;

  /** Override the DOM factory used internally (useful for testing / SSR). */
  domFactory?: DOMFactory;

  /** Override the timing provider used by the scheduler (useful for testing). */
  timingProvider?: TimingProvider;

  /** Maximum unconsumed bytes before `push()` returns `false` (backpressure). */
  highWaterMark?: number;

  /** Maximum number of "live" tokens retained for diffing. Default: 256. */
  maxLiveTokens?: number;

  /** Enable `getReceivedText()` / `getReceivedChunks()`. Default: false. */
  debug?: boolean;

  /** Structured pipeline logging configuration. See Logging guide. */
  log?: LogConfig;
}

Width and Height Behavior

Value	Effect
number	Sets the container to that many CSS pixels. Overflow is handled by scrolling.
'auto'	Width: fills parent (width: 100%). Height: grows with content (height: auto).
undefined	Generative DOM does not modify the container's dimensions. External CSS controls sizing.

These values are applied as inline styles on the container during construction and cleared on destroy(). They are also available to plugins via GlobalSettings.

Methods

push

push(chunk: string): void

Feed the next chunk of markdown text. The chunk is appended to the internal buffer and a render is scheduled. Chunks can be any size -- a single character, a word, a line, or an entire document.

flush

flush(): void

Force an immediate render of all buffered content, bypassing the debounce timer. Call this at the end of a stream to ensure the final content is displayed.

reset

reset(): void

Clear all state and the container contents. Plugins remain registered and the object pool is preserved. Use this to start rendering a new document without creating a new instance.

destroy

destroy(): void

Full cleanup. Releases the object pool, removes event listeners, calls destroy() on all plugins (in reverse priority order), and clears the container. The instance cannot be reused after calling this.

register

register(plugin: GenerativeDomPlugin): void

Add a plugin after construction. Triggers init() on the new plugin and re-sorts the plugin list by priority. Throws if a plugin with the same name is already registered.

on

on(event: string, handler: (data: unknown) => void): void

Subscribe to a plugin event. Event names are namespaced as "pluginName:eventName".

off

off(event: string, handler: (data: unknown) => void): void

Unsubscribe from a plugin event. The handler reference must be the same one passed to on().

getLogger

getLogger(): Logger

Return the structured logger instance for this Generative DOM. Useful for binding a child context to a specific request ID or component name. When no log config was supplied, returns a NoopLogger whose methods are all no-ops.

const requestLogger = md.getLogger().child({ requestId: "abc" });

See the Logging guide for the event taxonomy and configuration reference.

getLogs

getLogs(): LogEvent[]

Return a copy of buffered log events collected by a BufferLogger. Returns an empty array when the logger is not a BufferLogger (i.e. sink was not 'buffer'). Use with the filterByPhase, filterByPlugin, and summarizeEvents helpers for common slicing operations.

import { filterByPlugin, summarizeEvents } from "@generative-dom/core";

const headingEvents = filterByPlugin(md.getLogs(), "markdown-heading");
console.log(summarizeEvents(headingEvents));

clearLogs

clearLogs(): void

Clear the buffered log events. No-op for non-buffer loggers.

getReceivedText / getReceivedChunks

getReceivedText(): string  // joined chunks
getReceivedChunks(): string[]  // per-call array

Only available when constructed with debug: true. Returns the exact streamed input that produced the current rendering. Use to reproduce streaming bugs through the parity test harness. Throws when debug was not enabled.

Example

import { GenerativeDom } from "@generative-dom/core";
import {
  markdownBase,
  markdownInline,
  markdownHeading,
} from "@generative-dom/plugins";

const md = new GenerativeDom({
  container: document.getElementById("output")!,
  plugins: [markdownBase(), markdownInline(), markdownHeading()],
  debounceMs: 32,
  width: "auto",
});

md.on("events:progress", (data) => {
  console.log("Progress:", data);
});

const response = await fetch("/api/stream");
const reader = response.body!.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  md.push(decoder.decode(value, { stream: true }));
}

md.flush();

// Later, clean up:
md.destroy();