Types

Complete TypeScript type definitions exported by @generative-dom/core.

Token Types

Token

The intermediate representation produced by the tokenizer and consumed by the renderer.

interface Token {
  /** Token type identifier matching the originating plugin. */
  type: string;

  /** The raw markdown source for this token. */
  raw: string;

  /** Child tokens for nested structures (e.g., list items inside a list). */
  children?: Token[];

  /** Text content of the token (e.g., inner text of an inline span). */
  content?: string;

  /** Plugin-specific metadata carried through from the match phase. */
  meta?: Record<string, unknown>;
}

BlockMatch

Returned by matchBlock() when a plugin matches block-level content.

interface BlockMatch {
  /** Token type identifier (e.g., "heading", "code-fence"). */
  type: string;

  /** The raw markdown source that was matched. */
  raw: string;

  /** Number of characters consumed from the buffer. */
  consumed: number;

  /** Inner content to be further parsed (e.g., list-item text). */
  children?: string;

  /** Plugin-specific metadata attached to the match. */
  meta?: Record<string, unknown>;
}

InlineMatch

Returned by matchInline() when a plugin matches inline content.

interface InlineMatch {
  /** Token type identifier (e.g., "bold", "link"). */
  type: string;

  /** The raw markdown source that was matched. */
  raw: string;

  /** Number of characters consumed from the text. */
  consumed: number;

  /** Inner content (e.g., the text inside **bold**). */
  content?: string;

  /** Plugin-specific metadata attached to the match. */
  meta?: Record<string, unknown>;
}

Configuration Types

Generative DOMOptions

Options passed to the Generative DOM constructor.

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

  /** Minimum interval in milliseconds between renders. Default: 16. */
  debounceMs?: number;

  /** Container width in CSS pixels, 'auto', or undefined if not set. */
  width?: number | "auto";

  /** Container height in CSS pixels, 'auto', or undefined if not set. */
  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;
}

GlobalSettings

Read-only settings exposed to plugins via context objects.

interface GlobalSettings {
  /** Container width in CSS pixels, 'auto', or undefined if not set. */
  width?: number | "auto";

  /** Container height in CSS pixels, 'auto', or undefined if not set. */
  height?: number | "auto";

  /** Minimum interval in milliseconds between renders. */
  debounceMs: number;

  /** GenerativeDom semver version string. */
  version: string;
}

Plugin Types

Generative DOMPlugin

The interface that all plugins must implement.

interface GenerativeDomPlugin {
  name: string;
  priority: number;
  init?(ctx: PluginContext): void;
  matchBlock?(buffer: string, pos: number): BlockMatch | null;
  matchInline?(text: string, pos: number): InlineMatch | null;
  render(token: Token, ctx: RenderContext): HTMLElement | Text | null;
  cleanup?(element: HTMLElement): void;
  destroy?(): void;
}

See Plugin Interface for detailed documentation of each method.

PluginContext

Context received during plugin initialization.

interface PluginContext {
  emit(event: string, data: unknown): void;
  pool: ObjectPool;
  settings: Readonly<GlobalSettings>;
  getPlugin(
    name: string,
  ): Readonly<Pick<GenerativeDomPlugin, "name" | "priority">> | undefined;
  onDestroy(callback: () => void): void;
}

RenderContext

Context received during each render() call.

interface RenderContext {
  renderInline(text: string): DocumentFragment;
  pool: ObjectPool;
  createElement(tag: string): HTMLElement;
  createText(content: string): Text;
  settings: Readonly<GlobalSettings>;
  container: Readonly<HTMLElement>;
  emit(event: string, data: unknown): void;
}

Pool Types

ObjectPool

interface ObjectPool {
  acquire(tag: string): HTMLElement;
  release(element: HTMLElement): void;
  drain(): void;
  stats(): ObjectPoolStats;
}

ObjectPoolStats

interface ObjectPoolStats {
  pooled: number;
  active: number;
  created: number;
  reused: number;
}

Logging Types

LogConfig

Configuration for the structured pipeline logger. When omitted, Generative DOM uses a NoopLogger with zero overhead. See the Logging guide for the full reference and recipes.

interface LogConfig {
  /** Minimum severity. Events below this are dropped. Default: 'warn'. */
  level: "trace" | "debug" | "info" | "warn" | "error";

  /** Optional allow-list of pipeline phases. */
  phases?: PipelinePhase[];

  /** Optional allow-list of plugin names. */
  plugins?: string[];

  /** When true, attaches `raw` markdown / inner `content` to events. */
  includeTokens?: boolean;

  /** When true, attaches DOM element info to render events. */
  includeDOM?: boolean;

  /** Output destination. Default: 'console'. */
  sink?: "console" | "callback" | "buffer";

  /** For sink='callback': receive each event. */
  onLog?: (event: LogEvent) => void;

  /** For sink='callback': 'event' (object) | 'json' (string). */
  format?: "event" | "json";

  /** For sink='buffer': max events retained (circular). Default: 1000. */
  bufferSize?: number;
}

LogEvent

A discriminated union of every log event emitted by the pipeline. Each variant carries a phase and a typed type discriminant.

type LogEvent =
  | MatcherLogEvent // phase: 'match-block' | 'match-inline' | 'parse-inline'
  | TokenLogEvent // phase: 'tokenize' | 'parse-inline' | 'prune'
  | DiffLogEvent // phase: 'diff'
  | RenderLogEvent // phase: 'render' | 'cleanup'
  | PoolLogEvent; // phase: 'render'

Logger

interface Logger {
  /** Emit a log event. */
  log(event: LogEvent): void;
  /** Check if a given log level is enabled. */
  isEnabled(level: LogLevel): boolean;
  /** Create a child logger with additional bound context. */
  child(bindings: Record<string, unknown>): Logger;
  /** Get buffered log events (BufferLogger only). */
  getLogs?(): LogEvent[];
  /** Clear the log buffer (BufferLogger only). */
  clearLogs?(): void;
}

Four implementations ship in the package: NoopLogger, ConsoleLogger, CallbackLogger, and BufferLogger. createLogger(config?) builds the right one based on config.sink.