Type Reference

All types are exported from @askable-ui/core.

import type {
  AskableContext,
  AskableContextOptions,
  AskableContextOutputOptions,
  AskableFocus,
  AskableFocusSegment,
  AskableFocusSource,
  AskableSerializedFocus,
  AskableSerializedFocusSegment,
  AskablePromptContextOptions,
  AskablePromptFormat,
  AskablePromptPreset,
  AskablePushOptions,
  AskableEvent,
  AskableObserveOptions,
  AskableEventMap,
  AskableEventName,
  AskableEventHandler,
} from '@askable-ui/core';

---

AskableContextOptions

Options passed to createAskableContext().

interface AskableContextOptions {
  /**
   * Optional shared context name. Contexts with the same name reuse one instance
   * in the same page/runtime; unnamed contexts remain independent.
   */
  name?: string;
  /**
   * Track which annotated elements are currently visible in the viewport.
   * Off by default to avoid extra observer overhead.
   */
  viewport?: boolean;
  /**
   * Custom text extractor. Defaults to el.textContent?.trim() ?? ''
   * Applied at capture time.
   */
  textExtractor?: (el: HTMLElement) => string;
  /**
   * Sanitize object meta before storing/emitting.
   * Applied at capture time. Not called for string meta.
   */
  sanitizeMeta?: (meta: Record<string, unknown>) => Record<string, unknown>;
  /**
   * Sanitize text content before storing/emitting.
   * Applied at capture time.
   */
  sanitizeText?: (text: string) => string;
}

---

AskableFocusSource

Indicates how focus was initiated.

type AskableFocusSource = 'dom' | 'select' | 'push';

Value	Set by
'dom'	User interaction (click, hover, keyboard focus) via the Observer
'select'	ctx.select(element) — explicit "Ask AI" button patterns
'push'	ctx.push(meta, text) — programmatic focus without a DOM element

---

AskableFocus

The shape of focus state objects returned by getFocus(), getHistory(), and passed to 'focus' event handlers.

interface AskableFocus {
  /** How focus was initiated. */
  source: AskableFocusSource;
  /** Parsed data-askable value. JSON → object; plain string → string. */
  meta: Record<string, unknown> | string;
  /** Optional category used to filter context for different agents/copilots. */
  scope?: string;
  /** Optional ancestor chain, outermost first. */
  ancestors?: AskableFocusSegment[];
  /** Trimmed textContent of the element. */
  text: string;
  /** The DOM element. Undefined when set via push(). */
  element?: HTMLElement;
  /** Unix timestamp (ms) when focus was set. */
  timestamp: number;
}

interface AskableFocusSegment {
  meta: Record<string, unknown> | string;
  scope?: string;
  text: string;
}

---

AskableSerializedFocus

The shape returned by serializeFocus(). Similar to AskableFocus but without element, and text is omitted when empty or when includeText: false.

interface AskableSerializedFocus {
  meta: Record<string, unknown> | string;
  scope?: string;
  ancestors?: AskableSerializedFocusSegment[];
  text?: string;
  timestamp: number;
}

interface AskableSerializedFocusSegment {
  meta: Record<string, unknown> | string;
  scope?: string;
  text?: string;
}

---

AskablePushOptions

Options accepted by ctx.push(meta, text, options).

interface AskablePushOptions {
  scope?: string;
  ancestors?: AskableFocusSegment[];
}

---

AskablePromptPreset

Named shorthand for common option combinations. See Prompt Serialization → Presets.

type AskablePromptPreset = 'compact' | 'verbose' | 'json';

Value	Equivalent
compact	{ includeText: false, format: 'natural' }
verbose	{ includeText: true, format: 'natural' }
json	{ format: 'json', includeText: true }

---

AskablePromptContextOptions

Options accepted by toPromptContext(), toHistoryContext(), and serializeFocus().

interface AskablePromptContextOptions {
  preset?: AskablePromptPreset;    // Named shorthand. Individual options override it.
  scope?: string;                  // Optional category filter. Unscoped entries are included everywhere.
  hierarchyDepth?: number;         // Limit ancestor levels included in hierarchical context.
  format?: AskablePromptFormat;    // 'natural' | 'json'. Default: 'natural'
  includeText?: boolean;           // Include element text. Default: true
  maxTextLength?: number;          // Truncate text to N chars
  excludeKeys?: string[];          // Omit these keys from object meta
  keyOrder?: string[];             // Promote these keys to the front
  prefix?: string;                 // Prefix in natural format. Default: 'User is focused on:'
  textLabel?: string;              // Label for text. Default: 'value'
  maxTokens?: number;              // Token budget (4 chars/token). Appends [truncated] if exceeded.
}

---

AskableContextOutputOptions

Options accepted by toContext(). Extends AskablePromptContextOptions.

interface AskableContextOutputOptions extends AskablePromptContextOptions {
  /** Number of history entries to include. Default: 0 (current focus only). */
  history?: number;
  /** Label for the current focus section. Default: 'Current' */
  currentLabel?: string;
  /** Label for the history section. Default: 'Recent interactions' */
  historyLabel?: string;
}

---

AskableEvent

type AskableEvent = 'click' | 'hover' | 'focus';

hover maps to mouseenter on desktop/fine-pointer environments. On touch/coarse-pointer environments, hover-only observation resolves from tap by default.

---

AskablePromptFormat

type AskablePromptFormat = 'natural' | 'json';

---

AskableObserveOptions

Options for ctx.observe().

interface AskableObserveOptions {
  /** Which interaction types trigger context updates. Default: all three. Touch/coarse-pointer devices resolve hover from tap by default. */
  events?: AskableEvent[];
  /**
   * Debounce delay in ms for hover interactions.
   * When both hoverDebounce and hoverThrottle are set, debounce takes precedence.
   * Default: 0
   */
  hoverDebounce?: number;
  /**
   * Throttle window in ms for hover interactions.
   * Default: 0
   */
  hoverThrottle?: number;
}

---

AskableEventMap

type AskableEventMap = {
  focus: AskableFocus;
  clear: null;
};

---

AskableEventName

type AskableEventName = keyof AskableEventMap; // 'focus' | 'clear'

---

AskableEventHandler

type AskableEventHandler<K extends AskableEventName> = (
  payload: AskableEventMap[K]
) => void;