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' 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[];
}

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;
}