TypeScript types

Type definitions for DyeLight

DyeLight is written in TypeScript and provides comprehensive type definitions for all its APIs.

CharacterRange

Represents a character range to highlight in the entire text using absolute positions.

type CharacterRange = {
  /** Zero-based start index in the entire text (inclusive) */
  start: number;
  
  /** Zero-based end index in the entire text (exclusive) */
  end: number;
  
  /** Optional CSS class name to apply to the highlighted range */
  className?: string;
  
  /** Optional inline styles to apply to the highlighted range */
  style?: React.CSSProperties;
};

Example:

const highlight: CharacterRange = {
  start: 0,
  end: 5,
  className: 'highlight-keyword',
  style: { backgroundColor: 'yellow', fontWeight: 'bold' }
};

DyeLightProps

Props for the DyeLight component. Extends standard textarea props while replacing onChange with a simplified version.

value · string

Controlled value of the textarea.

defaultValue · string

Default value for uncontrolled usage.

onChange · (value: string) => void

Callback fired when the textarea value changes. Simplified from the standard React onChange signature.

highlights · CharacterRange[]

Character range highlights using absolute positions in the entire text.

lineHighlights · { [lineNumber: number]: string }

Line-level highlights mapped by line number (0-based) to CSS color or class name.

enableAutoResize · boolean · default: "true"

Enable automatic height adjustment based on content.

rows · number · default: "4"

Number of visible text lines.

className · string

CSS class name for the textarea element.

containerClassName · string

CSS class name for the container wrapper element.

dir · 'ltr' | 'rtl' · default: "'ltr'"

Text direction - supports left-to-right and right-to-left.

debug · boolean · default: "false"

Enable debug mode to collect telemetry data.

debugMaxEvents · number · default: "1000"

Maximum number of telemetry events to retain in memory.

Type definition:

interface DyeLightProps extends Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, 'onChange'> {
  className?: string;
  containerClassName?: string;
  defaultValue?: string;
  dir?: 'ltr' | 'rtl';
  enableAutoResize?: boolean;
  highlights?: CharacterRange[];
  lineHighlights?: { [lineNumber: number]: string };
  onChange?: (value: string) => void;
  rows?: number;
  value?: string;
  debug?: boolean;
  debugMaxEvents?: number;
}

DyeLightRef

Methods exposed by the DyeLight component through its ref. Provides programmatic access to common textarea operations and debug features.

getValue · () => string

Gets the current value of the textarea.

setValue · (value: string) => void

Sets the value of the textarea programmatically.

focus · () => void

Sets focus to the textarea.

blur · () => void

Removes focus from the textarea.

select · () => void

Selects all text in the textarea.

setSelectionRange · (start: number, end: number) => void

Sets the selection range in the textarea.

scrollToPosition · (pos: number, offset?: number, behavior?: ScrollBehavior) => void

Scrolls the character position into view with an optional pixel offset.

exportForAI · () => string

Exports AI-optimized debug report as JSON string (requires debug mode). The report includes value deduplication - large text values are stored once in a valueRegistry and referenced as <REF:value_N> to reduce JSON size.

Type definition:

type DyeLightRef = {
  blur: () => void;
  focus: () => void;
  getValue: () => string;
  select: () => void;
  setSelectionRange: (start: number, end: number) => void;
  setValue: (value: string) => void;
  scrollToPosition: (pos: number, offset?: number, behavior?: ScrollBehavior) => void;
  exportForAI: () => string;
};

Example:

import { useRef } from 'react';
import type { DyeLightRef } from 'dyelight';

const MyComponent = () => {
  const dyeLightRef = useRef<DyeLightRef>(null);

  const handleFocus = () => {
    dyeLightRef.current?.focus();
  };

  const handleGetValue = () => {
    const value = dyeLightRef.current?.getValue();
    console.log('Current value:', value);
  };

  const handleExportDebug = async () => {
    const report = dyeLightRef.current?.exportForAI();
    if (report) {
      await navigator.clipboard.writeText(report);
      alert('Debug report copied to clipboard');
    }
  };

  return (
    <>
      <DyeLight ref={dyeLightRef} debug={true} />
      <button onClick={handleExportDebug}>Export Debug Report</button>
    </>
  );
};

AITelemetryEvent

Represents a single telemetry event with full context. Used in debug mode to track component behavior.

timestamp · number

Unix timestamp in milliseconds.

timestampISO · string

ISO 8601 formatted timestamp.

timeSinceLastEvent · number | null

Milliseconds since the last event, or null for first event.

type · string

Event type identifier (e.g., ‘onChange’, ‘syncStyles’, ‘selectionChange’).

category · 'state' | 'dom' | 'sync' | 'user' | 'system'

Event category for grouping and analysis.

description · string

Human-readable description of the event.

data · Record<string, unknown>

Event-specific data payload.

stateSnapshot · object

Complete state snapshot at the time of this event.

Show State snapshot fields

textareaValue · string

Actual value in the textarea DOM element (may be <REF:value_N> if deduplicated).

reactValue · string

Value in React state (may be <REF:value_N> if deduplicated).

valuesMatch · boolean

Whether DOM and React state are synchronized.

textareaHeight · number | undefined

Current height of the textarea in pixels.

isControlled · boolean

Whether the component is in controlled mode.

selection · object

Textarea selection/caret state when available.

• start: number | null
• end: number | null
• direction: ‘forward’ | ‘backward’ | ‘none’ | null

textareaMetrics · object

Textarea geometry measurements at this event (clientWidth, clientHeight, scrollWidth, scrollHeight, etc.).

overlayMetrics · object

Overlay geometry measurements when available.

layoutDeltas · object

Derived deltas to quickly detect visual divergence (contentWidthDelta, contentHeightDelta, scrollTopDelta, scrollLeftDelta).

styleOwnership · object

Signals for identifying style ownership conflicts.

anomalies · string[]

Detected anomalies or issues at this event.

Type definition:

type AITelemetryEvent = {
  timestamp: number;
  timestampISO: string;
  timeSinceLastEvent: number | null;
  type: string;
  category: 'state' | 'dom' | 'sync' | 'user' | 'system';
  description: string;
  data: Record<string, unknown>;
  stateSnapshot: {
    textareaValue: string;
    reactValue: string;
    valuesMatch: boolean;
    textareaHeight: number | undefined;
    isControlled: boolean;
    selection?: {
      start: number | null;
      end: number | null;
      direction: 'forward' | 'backward' | 'none' | null;
    };
    textareaMetrics?: { /* ... */ };
    overlayMetrics?: { /* ... */ };
    layoutDeltas?: { /* ... */ };
    styleOwnership?: { /* ... */ };
  };
  anomalies: string[];
};

AIDebugReport

Complete AI-readable debug report structure returned by exportForAI().

metadata · object

Metadata about the report and environment.

Show Metadata fields

generatedAt · string

When this report was generated (ISO timestamp).

componentVersion · string

DyeLight version.

totalEvents · number

Total number of events recorded.

timespan · object

Time range covered by events.

• start: ISO timestamp of first event
• end: ISO timestamp of last event
• durationMs: Duration in milliseconds

browser · string

Browser user agent string.

platform · string

Platform identifier.

summary · object

Analysis summary with detected issues.

Show Summary fields

description · string

High-level description of findings.

detectedIssues · array

List of detected issues sorted by severity. Each issue includes:

• severity: ‘critical’ | ‘warning’ | ‘info’
• issue: Issue description
• firstOccurrence: When this issue first occurred
• occurrenceCount: How many times this issue occurred
• relatedEvents: Event indices where this issue occurred

suspiciousPatterns · string[]

Suspicious patterns detected in event sequences.

recommendations · string[]

Recommended actions to resolve issues.

timeline · object

Different views of the event timeline.

Show Timeline fields

userActions · array

User interactions and their impacts.

stateChanges · array

All state mutations in chronological order.

syncOperations · array

Synchronization operations between textarea and overlay.

events · AITelemetryEvent[]

Complete chronological list of all events.

finalState · object

Final state at time of export.

Show Final state fields

textareaValue · string

Current textarea DOM value (may be <REF:value_N>).

reactValue · string

Current React state value (may be <REF:value_N>).

inSync · boolean

Whether values are synchronized.

height · number | undefined

Current height in pixels.

scrollPosition · object

Current scroll position (top and left).

highlights · unknown[]

Current highlights configuration.

valueRegistry · { [key: string]: string }

Value registry for deduplicated text values. Large text values (>1000 chars) are stored here once and referenced as <REF:value_N>. This dramatically reduces JSON size when the same large text appears in many events.

Type definition:

type AIDebugReport = {
  metadata: {
    generatedAt: string;
    componentVersion: string;
    totalEvents: number;
    timespan: {
      start: string;
      end: string;
      durationMs: number;
    };
    browser: string;
    platform: string;
  };

  summary: {
    description: string;
    detectedIssues: Array<{
      severity: 'critical' | 'warning' | 'info';
      issue: string;
      firstOccurrence: string;
      occurrenceCount: number;
      relatedEvents: number[];
    }>;
    suspiciousPatterns: string[];
    recommendations: string[];
  };

  timeline: {
    userActions: Array<{ /* ... */ }>;
    stateChanges: Array<{ /* ... */ }>;
    syncOperations: Array<{ /* ... */ }>;
  };

  events: AITelemetryEvent[];

  finalState: {
    textareaValue: string;
    reactValue: string;
    inSync: boolean;
    height: number | undefined;
    scrollPosition: { top: number; left: number };
    highlights: unknown[];
  };

  valueRegistry: { [key: string]: string };
};

Example:

const report = editorRef.current?.exportForAI();
if (report) {
  const parsed: AIDebugReport = JSON.parse(report);
  
  // Check for critical issues
  const criticalIssues = parsed.summary.detectedIssues.filter(
    issue => issue.severity === 'critical'
  );
  
  // Access deduplicated values
  const firstEventValue = parsed.events[0].stateSnapshot.textareaValue;
  if (firstEventValue.startsWith('<REF:')) {
    const actualValue = parsed.valueRegistry[firstEventValue];
    console.log('Actual value:', actualValue);
  }
}