@domscribe/runtime

@domscribe/runtime

Browser-side context capture engine for Domscribe.

@domscribe/runtime runs in the browser during development and captures component props, state, and DOM context when a developer clicks an element. It is framework-agnostic at its core — framework-specific behavior is provided by adapters.

Install

npm install @domscribe/runtime

Framework Support

For most projects you will install a framework adapter rather than @domscribe/runtime directly. The adapter declares @domscribe/runtime as a peer dependency and handles initialization.

RuntimeManager

RuntimeManager is a singleton that manages the active adapter and provides the capture API to the overlay and other internal consumers.

import { RuntimeManager } from '@domscribe/runtime';

const runtime = RuntimeManager.getInstance();
await runtime.initialize({
  adapter: myAdapter,
  phase: 1,
  debug: false,
  redactPII: true,
  blockSelectors: [],
});

Options

initialize() is safe to call multiple times — subsequent calls with the same configuration are no-ops.

Serialization Constraints

The runtime serializes component props and state with bounded constraints to prevent excessive payload sizes. All fields are optional — defaults are applied by the serializer.

When a limit is exceeded, the serializer inserts human-readable sentinels ([Max Depth Exceeded], [Truncated: size limit]) and truncation metadata ({ __truncated: true, originalLength: N }) so agents can see what was omitted.

These constraints are configurable per-project via the serialization option on RuntimeOptions, which all framework adapter plugins expose through their runtime namespace.

FrameworkAdapter Interface

Adapters implement the FrameworkAdapter interface to bridge the runtime to a specific framework's internal component model.

interface FrameworkAdapter {
  readonly name: string;
  readonly version?: string;
  getComponentInstance(element: HTMLElement): Nullable<unknown>;
  captureProps(component: unknown): Nullable<Record<string, unknown>>;
  captureState(component: unknown): Nullable<Record<string, unknown>>;
  getComponentName?(component: unknown): Nullable<string>;
  getComponentTree?(component: unknown): Nullable<ComponentTreeNode>;
  getSerializationHints?(): SerializationHints;
}

Serialization Hints

Adapters can implement getSerializationHints() to declare which object keys are framework internals that should be skipped during serialization. This prevents framework plumbing (e.g., React Fiber trees, Vue reactivity markers) from consuming the byte budget.

interface SerializationHints {
  skipKeys?: Set<string>; // Exact keys to omit (e.g., '_owner')
  skipKeyPrefixes?: string[]; // Prefixes to omit (e.g., '__react' catches '__reactFiber$xyz')
}

The React adapter skips _owner, _store, and all __react* keys. The Vue adapter skips __v_* reactivity internals. The NoopAdapter returns no hints — all keys are serialized.

See the Custom Adapters Guide for the full interface, a worked example, and integration instructions.

Links

Part of Domscribe.

License

MIT