@ai11y/core 0.0.1

package/src/agent/tool-contract.ts

@@ -0,0 +1,22 @@
+import type { Ai11yContext } from "../context.js";
+
+export interface ToolDefinition {
+	name: string;
+	description: string;
+	parameters: {
+		type: "object";
+		properties: Record<
+			string,
+			{
+				type: string;
+				description: string;
+			}
+		>;
+		required?: string[];
+	};
+}
+
+export type ToolExecutor = (
+	args: Record<string, unknown>,
+	context: Ai11yContext,
+) => Promise<unknown> | unknown;

package/src/agent/types.ts

@@ -0,0 +1,83 @@
+import type { Ai11yContext } from "../context.js";
+import type { Instruction } from "../instruction.js";
+
+export interface AgentResponse {
+	reply: string;
+	instructions?: Instruction[];
+}
+
+export interface ConversationMessage {
+	role: "user" | "assistant";
+	content: string;
+}
+
+export interface AgentRequest {
+	input: string;
+	context: Ai11yContext;
+	messages?: ConversationMessage[];
+}
+
+/**
+ * Configuration for LLM-based agent
+ */
+export interface LLMAgentConfig {
+	/**
+	 * API endpoint URL for the agent server (e.g., "http://localhost:3000/ai11y/agent")
+	 */
+	apiEndpoint: string;
+}
+
+/**
+ * Agent mode selection
+ */
+export type AgentMode = "llm" | "rule-based" | "auto";
+
+/**
+ * Configuration for agent selection
+ */
+export interface AgentAdapterConfig {
+	/**
+	 * Agent mode selection strategy
+	 * - "llm": Always use LLM agent (requires llmConfig)
+	 * - "rule-based": Always use rule-based agent
+	 * - "auto": Use LLM if configured, fallback to rule-based on error or when offline
+	 * @default "auto"
+	 */
+	mode?: AgentMode;
+
+	/**
+	 * LLM configuration (required for "llm" mode, optional for "auto")
+	 */
+	llmConfig?: LLMAgentConfig | null;
+
+	/**
+	 * Force rule-based mode (skip LLM even if config is available)
+	 * @default false
+	 */
+	forceRuleBased?: boolean;
+}
+
+/**
+ * Unified agent configuration combining LLM settings with agent selection options
+ */
+export interface AgentConfig {
+	/**
+	 * API endpoint URL for the LLM agent server (required for "llm" mode)
+	 */
+	apiEndpoint?: string;
+
+	/**
+	 * Agent mode selection strategy
+	 * - "llm": Always use LLM agent (requires apiEndpoint)
+	 * - "rule-based": Always use rule-based agent
+	 * - "auto": Use LLM if apiEndpoint is provided, fallback to rule-based on error or when offline
+	 * @default "auto"
+	 */
+	mode?: AgentMode;
+
+	/**
+	 * Force rule-based mode (skip LLM even if apiEndpoint is available)
+	 * @default false
+	 */
+	forceRuleBased?: boolean;
+}

package/src/client-api.ts

@@ -0,0 +1,107 @@
+import type { Ai11yContext, Ai11yError } from "./context.js";
+import { getContext } from "./dom.js";
+import {
+	clickMarker,
+	fillInputMarker,
+	highlightMarker,
+	navigateToRoute,
+	scrollToMarker,
+} from "./dom-actions/index.js";
+import type { Instruction } from "./instruction.js";
+import { setError, track as trackToStore } from "./store.js";
+
+/**
+ * Client interface for interacting with the AI accessibility system
+ */
+export interface Ai11yClient {
+	/**
+	 * Describes the current UI context (markers, route, state, errors)
+	 */
+	describe(): Ai11yContext;
+
+	/**
+	 * Executes an instruction on the UI
+	 */
+	act(instruction: Instruction): void;
+
+	/**
+	 * Tracks a custom event
+	 */
+	track(event: string, payload?: unknown): void;
+
+	/**
+	 * Reports an error to the system
+	 */
+	reportError(
+		error: Error,
+		meta?: { surface?: string; markerId?: string },
+	): void;
+}
+
+interface CreateClientOptions {
+	onNavigate?: (route: string) => void;
+}
+
+/**
+ * Creates a new AI accessibility client instance
+ *
+ * @param options - Optional configuration
+ * @returns An Ai11yClient instance
+ *
+ * @example
+ * ```ts
+ * const ctx = createClient({ onNavigate: (route) => navigate(route) })
+ * const ui = ctx.describe()
+ * ctx.act({ action: "click", id: "save_button" })
+ * ```
+ */
+export function createClient(options?: CreateClientOptions): Ai11yClient {
+	const { onNavigate } = options || {};
+
+	return {
+		describe(): Ai11yContext {
+			return getContext();
+		},
+
+		act(instruction: Instruction): void {
+			switch (instruction.action) {
+				case "click":
+					clickMarker(instruction.id);
+					break;
+				case "navigate":
+					if (onNavigate) {
+						onNavigate(instruction.route);
+					} else {
+						navigateToRoute(instruction.route);
+					}
+					break;
+				case "highlight":
+					highlightMarker(instruction.id);
+					break;
+				case "scroll":
+					scrollToMarker(instruction.id);
+					break;
+				case "fillInput":
+					fillInputMarker(instruction.id, instruction.value);
+					break;
+			}
+		},
+
+		track(event: string, payload?: unknown): void {
+			trackToStore(event, payload);
+		},
+
+		reportError(
+			error: Error,
+			meta?: { surface?: string; markerId?: string },
+		): void {
+			const assistError: Ai11yError = {
+				error,
+				meta,
+				timestamp: Date.now(),
+			};
+			setError(assistError);
+			trackToStore("error", { error: error.message, meta });
+		},
+	};
+}

package/src/context.ts

@@ -0,0 +1,28 @@
+import type { Marker } from "./marker.js";
+
+export interface Ai11yState {
+	[key: string]: unknown;
+}
+
+export interface Ai11yError {
+	error: Error;
+	meta?: {
+		surface?: string;
+		markerId?: string;
+	};
+	timestamp: number;
+}
+
+export interface Ai11yEvent {
+	type: string;
+	payload?: unknown;
+	timestamp: number;
+}
+
+export interface Ai11yContext {
+	markers: Marker[];
+	inViewMarkerIds?: string[];
+	route?: string;
+	state?: Ai11yState;
+	error?: Ai11yError | null;
+}

package/src/dom-actions/click.ts

@@ -0,0 +1,39 @@
+import { track } from "../store.js";
+import { findMarkerElement } from "./find-element.js";
+
+/**
+ * Clicks a marker element by its ID
+ *
+ * @param markerId - The marker ID to click
+ *
+ * @example
+ * ```ts
+ * clickMarker('connect_stripe');
+ * ```
+ */
+export function clickMarker(markerId: string): void {
+	const element = findMarkerElement(markerId);
+	if (!element) {
+		console.warn(`Marker ${markerId} not found`);
+		return;
+	}
+
+	// Prefer native click to avoid double-firing handlers (important for toggles)
+	if (
+		"click" in element &&
+		typeof (element as HTMLElement).click === "function"
+	) {
+		(element as HTMLElement).click();
+	} else {
+		// Fallback: dispatch a synthetic mouse event
+		const mouseEvent = new MouseEvent("click", {
+			view: window,
+			bubbles: true,
+			cancelable: true,
+			buttons: 1,
+		});
+		element.dispatchEvent(mouseEvent);
+	}
+
+	track("click", { markerId });
+}

package/src/dom-actions/fill-input.ts

@@ -0,0 +1,113 @@
+import { track } from "../store.js";
+import { findMarkerElement } from "./find-element.js";
+
+/**
+ * Fills an input, textarea, or select element by its marker ID with a value, emitting native browser events
+ *
+ * @param markerId - The marker ID of the input/textarea/select element to fill
+ * @param value - The value to fill into the element. For select elements, this must match one of the available option values.
+ *
+ * @example
+ * ```ts
+ * fillInputMarker('email_input', 'test@example.com');
+ * fillInputMarker('category_select', 'feedback');
+ * ```
+ */
+export function fillInputMarker(markerId: string, value: string): void {
+	const element = findMarkerElement(markerId);
+	if (!element) {
+		console.warn(`Marker ${markerId} not found`);
+		return;
+	}
+
+	// If the marked element is not itself an input, try to find an input inside it
+	// (in case Mark wraps the input in a container)
+	let inputElement: HTMLInputElement | HTMLTextAreaElement | null = null;
+	let selectElement: HTMLSelectElement | null = null;
+
+	if (
+		element instanceof HTMLInputElement ||
+		element instanceof HTMLTextAreaElement
+	) {
+		inputElement = element;
+	} else if (element instanceof HTMLSelectElement) {
+		selectElement = element;
+	} else if (element instanceof HTMLElement) {
+		// Search for input, textarea, or select within the marked element
+		const nestedInput = element.querySelector("input, textarea");
+		if (
+			nestedInput instanceof HTMLInputElement ||
+			nestedInput instanceof HTMLTextAreaElement
+		) {
+			inputElement = nestedInput;
+		} else {
+			const nestedSelect = element.querySelector("select");
+			if (nestedSelect instanceof HTMLSelectElement) {
+				selectElement = nestedSelect;
+			}
+		}
+	}
+
+	const isContentEditable =
+		element instanceof HTMLElement && element.contentEditable === "true";
+
+	if (!inputElement && !selectElement && !isContentEditable) {
+		console.warn(
+			`Marker ${markerId} does not contain an input, textarea, select, or contenteditable element`,
+		);
+		return;
+	}
+
+	// Set the value property (for React controlled components)
+	if (inputElement) {
+		// Step 1: Directly set the value
+		// For React-controlled inputs, we must use the native setter to bypass React's value prop
+		const prototype =
+			inputElement instanceof HTMLTextAreaElement
+				? HTMLTextAreaElement.prototype
+				: HTMLInputElement.prototype;
+		const setter = Object.getOwnPropertyDescriptor(prototype, "value")?.set;
+
+		if (setter) {
+			// Use native setter for React-controlled inputs
+			setter.call(inputElement, value);
+		} else {
+			// Fallback: direct assignment for native inputs
+			inputElement.value = value;
+		}
+
+		// Step 2: Dispatch the right events with bubbles: true
+		// This is crucial - bubbles: true allows React/Vue/Angular to catch the events
+		// input event → updates live state
+		inputElement.dispatchEvent(new Event("input", { bubbles: true }));
+
+		// change event → commits value (important for forms)
+		inputElement.dispatchEvent(new Event("change", { bubbles: true }));
+
+		// Step 3: Focus management (optional but useful)
+		// Helps with validation, conditional UI, and accessibility expectations
+		inputElement.focus();
+	} else if (selectElement) {
+		// For select elements, set the value property
+		selectElement.value = value;
+
+		// Dispatch change event to trigger React onChange handlers
+		selectElement.dispatchEvent(new Event("change", { bubbles: true }));
+
+		// Focus the select element
+		selectElement.focus();
+	} else if (isContentEditable) {
+		// For contenteditable elements, set textContent and dispatch events
+		const editableElement = element as HTMLElement;
+		editableElement.textContent = value;
+
+		// Dispatch input event
+		const inputEvent = new InputEvent("input", {
+			bubbles: true,
+			cancelable: true,
+		});
+		element.dispatchEvent(inputEvent);
+	}
+
+	track("fillInput", { markerId, value });
+}

package/src/dom-actions/find-element.ts

@@ -0,0 +1,14 @@
+import { getMarkerSelector } from "../util/attributes.js";
+
+/**
+ * Finds an element by its marker ID (data-ai-id attribute)
+ *
+ * @param markerId - The marker ID to find
+ * @returns The element if found, null otherwise
+ */
+export function findMarkerElement(markerId: string): Element | null {
+	if (typeof document === "undefined") {
+		return null;
+	}
+	return document.querySelector(getMarkerSelector(markerId));
+}

package/src/dom-actions/highlight.ts

@@ -0,0 +1,93 @@
+import { track } from "../store.js";
+import { findMarkerElement } from "./find-element.js";
+
+/**
+ * Options for highlighting a marker
+ */
+export interface HighlightOptions {
+	/**
+	 * Callback function called when marker is highlighted
+	 */
+	onHighlight?: (markerId: string, element: Element) => void;
+	/**
+	 * Duration in milliseconds for the highlight (default: 2000)
+	 * Set to 0 to skip visual highlighting (useful when using custom highlight wrapper)
+	 */
+	duration?: number;
+}
+
+/**
+ * Checks if an element is currently visible in the viewport
+ */
+function isElementInView(element: Element): boolean {
+	const rect = element.getBoundingClientRect();
+	const windowHeight =
+		window.innerHeight || document.documentElement.clientHeight;
+	const windowWidth = window.innerWidth || document.documentElement.clientWidth;
+
+	const isPartiallyVisible =
+		rect.top < windowHeight &&
+		rect.bottom > 0 &&
+		rect.left < windowWidth &&
+		rect.right > 0;
+
+	return isPartiallyVisible;
+}
+
+/**
+ * Highlights a marker element by its ID
+ * Scrolls the element into view (only if not already in view) and applies visual highlighting
+ *
+ * @param markerId - The marker ID to highlight
+ * @param options - Optional configuration for highlighting
+ *
+ * @example
+ * ```ts
+ * highlightMarker('connect_stripe', {
+ *   onHighlight: (id, el) => console.log('Highlighted:', id),
+ *   duration: 3000
+ * });
+ * ```
+ */
+export function highlightMarker(
+	markerId: string,
+	options: HighlightOptions = {},
+): void {
+	const element = findMarkerElement(markerId);
+	if (!element) {
+		console.warn(`Marker ${markerId} not found`);
+		return;
+	}
+
+	const { onHighlight, duration = 2000 } = options;
+
+	if (!isElementInView(element)) {
+		element.scrollIntoView({
+			behavior: "smooth",
+			block: "center",
+			inline: "nearest",
+		});
+	}
+
+	if (onHighlight) {
+		onHighlight(markerId, element);
+	}
+
+	if (duration > 0) {
+		const originalOutline = (element as HTMLElement).style.outline;
+		const originalOutlineOffset = (element as HTMLElement).style.outlineOffset;
+		const originalTransition = (element as HTMLElement).style.transition;
+
+		(element as HTMLElement).style.outline = "3px solid #3b82f6";
+		(element as HTMLElement).style.outlineOffset = "2px";
+		(element as HTMLElement).style.transition = "outline 0.2s ease";
+
+		window.setTimeout(() => {
+			(element as HTMLElement).style.outline = originalOutline;
+			(element as HTMLElement).style.outlineOffset = originalOutlineOffset;
+			(element as HTMLElement).style.transition = originalTransition;
+		}, duration);
+	}
+
+	track("highlight", { markerId });
+}

package/src/dom-actions/index.ts

@@ -0,0 +1,5 @@
+export { clickMarker } from "./click.js";
+export { fillInputMarker } from "./fill-input.js";
+export { type HighlightOptions, highlightMarker } from "./highlight.js";
+export { navigateToRoute } from "./navigate.js";
+export { scrollToMarker } from "./scroll.js";

package/src/dom-actions/navigate.ts

@@ -0,0 +1,17 @@
+import { setRoute, track } from "../store.js";
+
+/**
+ * Navigates to a route
+ * Updates the route in the store and tracks the navigation event
+ *
+ * @param route - The route to navigate to
+ *
+ * @example
+ * ```ts
+ * navigateToRoute('/billing');
+ * ```
+ */
+export function navigateToRoute(route: string): void {
+	setRoute(route);
+	track("navigate", { route });
+}

package/src/dom-actions/scroll.ts

@@ -0,0 +1,29 @@
+import { track } from "../store.js";
+import { findMarkerElement } from "./find-element.js";
+
+/**
+ * Scrolls to a marker element by its ID
+ * Does not apply highlight animation - use highlightMarker() if you want both scroll and highlight
+ *
+ * @param markerId - The marker ID to scroll to
+ *
+ * @example
+ * ```ts
+ * scrollToMarker('connect_stripe');
+ * ```
+ */
+export function scrollToMarker(markerId: string): void {
+	const element = findMarkerElement(markerId);
+	if (!element) {
+		console.warn(`Marker ${markerId} not found`);
+		return;
+	}
+
+	element.scrollIntoView({
+		behavior: "smooth",
+		block: "center",
+		inline: "nearest",
+	});
+
+	track("scroll", { markerId });
+}

package/src/dom.ts

@@ -0,0 +1,89 @@
+import type { Ai11yContext } from "./context.js";
+import { getMarkers } from "./marker.js";
+import { getError, getRoute, getState } from "./store.js";
+import { getAllMarkersSelector, getMarkerId } from "./util/attributes.js";
+
+/**
+ * Detects which markers are currently visible in the viewport
+ *
+ * @param root - Optional DOM root element to scan for markers (defaults to document.body)
+ * @returns Array of marker IDs that are currently in view
+ */
+function getInViewMarkerIds(root?: Element): string[] {
+	if (typeof document === "undefined" || typeof window === "undefined") {
+		return [];
+	}
+
+	const scanRoot = root ?? document.body;
+	if (!scanRoot) {
+		return [];
+	}
+
+	const elements = scanRoot.querySelectorAll(getAllMarkersSelector());
+	const inViewIds: string[] = [];
+
+	for (let i = 0; i < elements.length; i++) {
+		const element = elements[i];
+		const id = getMarkerId(element);
+		if (!id) continue;
+
+		const rect = element.getBoundingClientRect();
+		const isInView =
+			rect.top >= 0 &&
+			rect.left >= 0 &&
+			rect.bottom <=
+				(window.innerHeight || document.documentElement.clientHeight) &&
+			rect.right <= (window.innerWidth || document.documentElement.clientWidth);
+
+		const isPartiallyVisible =
+			rect.top <
+				(window.innerHeight || document.documentElement.clientHeight) &&
+			rect.bottom > 0 &&
+			rect.left < (window.innerWidth || document.documentElement.clientWidth) &&
+			rect.right > 0;
+
+		if (isInView || isPartiallyVisible) {
+			inViewIds.push(id);
+		}
+	}
+
+	return inViewIds;
+}
+
+/**
+ * Composes a complete Ai11yContext from singleton state and DOM markers
+ *
+ * @param root - Optional DOM root element to scan for markers (defaults to document.body)
+ * @returns A complete Ai11yContext object with markers from DOM and state from singleton
+ *
+ * @example
+ * ```ts
+ * import { setRoute, setState, getContext } from '@ai11y/core';
+ *
+ * setRoute('/billing');
+ * setState({ userId: '123' });
+ * const context = getContext();
+ * ```
+ */
+export function getContext(root?: Element): Ai11yContext {
+	const context: Ai11yContext = {
+		markers: getMarkers(root),
+		inViewMarkerIds: getInViewMarkerIds(root),
+	};
+
+	const route = getRoute();
+	const state = getState();
+	const error = getError();
+
+	if (route !== undefined) {
+		context.route = route;
+	}
+	if (state !== undefined) {
+		context.state = state;
+	}
+	if (error !== undefined) {
+		context.error = error;
+	}
+
+	return context;
+}

package/src/events.ts

@@ -0,0 +1,55 @@
+/**
+ * Event listener function type
+ */
+type EventListener = () => void;
+
+/**
+ * Set of event listeners
+ */
+const listeners = new Set<EventListener>();
+
+/**
+ * Subscribe to event notifications
+ * Returns an unsubscribe function
+ *
+ * @param listener - Function to call when events are tracked
+ * @returns Unsubscribe function
+ *
+ * @example
+ * ```ts
+ * const unsubscribe = subscribe(() => {
+ *   console.log('Event tracked!');
+ * });
+ * // Later...
+ * unsubscribe();
+ * ```
+ */
+export function subscribe(listener: EventListener): () => void {
+	listeners.add(listener);
+	return () => {
+		listeners.delete(listener);
+	};
+}
+
+/**
+ * Notify all subscribers that an event has been tracked
+ * This is called internally by the store when track() is called
+ */
+export function notify(): void {
+	for (const listener of listeners) {
+		try {
+			listener();
+		} catch (error) {
+			// Don't let one listener's error break others
+			console.error("Error in event listener:", error);
+		}
+	}
+}
+
+/**
+ * Get the number of active subscribers
+ * Useful for debugging
+ */
+export function getSubscriberCount(): number {
+	return listeners.size;
+}