@ai11y/core 0.0.1

package/src/index.ts

@@ -0,0 +1,55 @@
+/**
+ * @ai11y/core
+ *
+ * Core types and utilities shared across all ai11y packages.
+ */
+
+export {
+	type AgentAdapterConfig,
+	type AgentConfig,
+	type AgentMode,
+	type AgentRequest,
+	type AgentResponse,
+	type ConversationMessage,
+	type LLMAgentConfig,
+	runAgentAdapter,
+	runLLMAgent,
+	runRuleBasedAgent,
+} from "./agent/index.js";
+export { plan } from "./agent/plan.js";
+export type { ToolDefinition, ToolExecutor } from "./agent/tool-contract.js";
+export { type Ai11yClient, createClient } from "./client-api.js";
+export type {
+	Ai11yContext,
+	Ai11yError,
+	Ai11yEvent,
+	Ai11yState,
+} from "./context.js";
+export { getContext } from "./dom.js";
+export {
+	clickMarker,
+	fillInputMarker,
+	type HighlightOptions,
+	highlightMarker,
+	navigateToRoute,
+	scrollToMarker,
+} from "./dom-actions/index.js";
+export { getSubscriberCount, notify, subscribe } from "./events.js";
+export type { Instruction } from "./instruction.js";
+export type { Marker } from "./marker.js";
+export { getMarkers } from "./marker.js";
+export {
+	clearContext,
+	clearEvents,
+	clearState,
+	getError,
+	getEvents,
+	getRoute,
+	getState,
+	setError,
+	setRoute,
+	setState,
+	subscribeToStore,
+	track,
+} from "./store.js";
+export * from "./util/index.js";

package/src/instruction.ts

@@ -0,0 +1,6 @@
+export type Instruction =
+	| { action: "click"; id: string }
+	| { action: "navigate"; route: string }
+	| { action: "highlight"; id: string }
+	| { action: "scroll"; id: string }
+	| { action: "fillInput"; id: string; value: string };

package/src/marker.ts

@@ -0,0 +1,237 @@
+import {
+	ATTRIBUTE_SENSITIVE,
+	getAllMarkersSelector,
+	getMarkerId,
+	getMarkerIntent,
+	getMarkerLabel,
+} from "./util/attributes.js";
+import { formatMarkerId } from "./util/format.js";
+
+/**
+ * Marker information for UI elements
+ */
+export interface Marker {
+	id: string;
+	label: string;
+	intent: string;
+	elementType: string;
+	/** Current value for input/textarea elements */
+	value?: string;
+	/** Selected value(s) for select elements */
+	selectedOptions?: string[];
+	/** All available options for select elements */
+	options?: Array<{ value: string; label: string }>;
+}
+
+/**
+ * Gets the document body in a type-safe way
+ * Returns null if not in a browser environment
+ */
+function getDocumentBody(): Element | null {
+	if (typeof document === "undefined") {
+		return null;
+	}
+	return document.body;
+}
+
+/**
+ * Finds an input or textarea element within a marked element
+ * Handles both direct input elements and nested inputs (when Mark wraps the input)
+ */
+function findInputElement(
+	element: Element,
+): HTMLInputElement | HTMLTextAreaElement | null {
+	if (
+		element instanceof HTMLInputElement ||
+		element instanceof HTMLTextAreaElement
+	) {
+		return element;
+	}
+	if (element instanceof HTMLElement) {
+		const nestedInput = element.querySelector("input, textarea");
+		if (
+			nestedInput instanceof HTMLInputElement ||
+			nestedInput instanceof HTMLTextAreaElement
+		) {
+			return nestedInput;
+		}
+	}
+	return null;
+}
+
+/**
+ * Finds a select element within a marked element
+ * Handles both direct select elements and nested selects (when Mark wraps the select)
+ */
+function findSelectElement(element: Element): HTMLSelectElement | null {
+	if (element instanceof HTMLSelectElement) {
+		return element;
+	}
+	if (element instanceof HTMLElement) {
+		const nestedSelect = element.querySelector("select");
+		if (nestedSelect instanceof HTMLSelectElement) {
+			return nestedSelect;
+		}
+	}
+	return null;
+}
+
+/**
+ * Checks if an input element contains sensitive data that should be redacted
+ * from the UI context (passwords, credit cards, hidden fields, etc.)
+ *
+ * @param inputElement - The input or textarea element to check
+ * @returns True if the input contains sensitive data
+ */
+function isSensitiveInput(
+	inputElement: HTMLInputElement | HTMLTextAreaElement,
+): boolean {
+	// Check input type
+	if (inputElement instanceof HTMLInputElement) {
+		const type = inputElement.type.toLowerCase();
+		if (type === "password" || type === "hidden") {
+			return true;
+		}
+	}
+
+	// Check autocomplete attribute for sensitive patterns
+	const autocomplete = inputElement.getAttribute("autocomplete")?.toLowerCase();
+	if (autocomplete) {
+		const sensitiveAutocompletePaths = [
+			"current-password",
+			"new-password",
+			"cc-number",
+			"cc-csc",
+			"cc-exp",
+			"cc-exp-month",
+			"cc-exp-year",
+		];
+		if (
+			sensitiveAutocompletePaths.some((path) => autocomplete.includes(path))
+		) {
+			return true;
+		}
+	}
+
+	// Check for custom sensitive marker attribute
+	if (inputElement.getAttribute(ATTRIBUTE_SENSITIVE) === "true") {
+		return true;
+	}
+
+	// Check parent element for sensitive marker attribute
+	const parent = inputElement.parentElement;
+	if (parent && parent.getAttribute(ATTRIBUTE_SENSITIVE) === "true") {
+		return true;
+	}
+
+	return false;
+}
+
+/**
+ * Extracts the value from an input or textarea element
+ * Redacts sensitive values (passwords, credit cards, etc.) for privacy
+ */
+function extractInputValue(element: Element): string | undefined {
+	const inputElement = findInputElement(element);
+	if (!inputElement) {
+		return undefined;
+	}
+	if (isSensitiveInput(inputElement)) {
+		return "[REDACTED]";
+	}
+	return inputElement.value;
+}
+
+/**
+ * Extracts options and selected values from a select element
+ */
+function extractSelectData(element: Element): {
+	options?: Array<{ value: string; label: string }>;
+	selectedOptions?: string[];
+} {
+	const selectElement = findSelectElement(element);
+	if (!selectElement) {
+		return {};
+	}
+
+	const options: Array<{ value: string; label: string }> = [];
+	for (let i = 0; i < selectElement.options.length; i++) {
+		const option = selectElement.options[i];
+		options.push({
+			value: option.value,
+			label: option.text,
+		});
+	}
+
+	const selectedOptions: string[] = [];
+	if (selectElement.multiple) {
+		for (let i = 0; i < selectElement.selectedOptions.length; i++) {
+			selectedOptions.push(selectElement.selectedOptions[i].value);
+		}
+	} else {
+		if (selectElement.value) {
+			selectedOptions.push(selectElement.value);
+		}
+	}
+
+	return {
+		options: options.length > 0 ? options : undefined,
+		selectedOptions: selectedOptions.length > 0 ? selectedOptions : undefined,
+	};
+}
+
+/**
+ * Scans the DOM for elements with data-ai-* attributes and returns markers
+ *
+ * @param root - Optional DOM root element to scan (defaults to document.body)
+ * @returns Array of Marker objects found in the DOM
+ *
+ * @example
+ * ```ts
+ * const markers = getMarkers();
+ * // Scans document.body for data-ai-* attributes
+ * ```
+ */
+export function getMarkers(root?: Element): Marker[] {
+	const scanRoot = root ?? getDocumentBody();
+
+	if (!scanRoot) {
+		return [];
+	}
+
+	const elements = scanRoot.querySelectorAll(getAllMarkersSelector());
+	const markers: Marker[] = [];
+	for (let i = 0; i < elements.length; i++) {
+		const element = elements[i];
+		const id = getMarkerId(element);
+		if (!id) continue;
+
+		const label = getMarkerLabel(element) || formatMarkerId(id);
+		const intent = getMarkerIntent(element) || "";
+		const elementType = element.tagName.toLowerCase();
+
+		const marker: Marker = {
+			id,
+			label,
+			intent,
+			elementType,
+		};
+
+		const inputValue = extractInputValue(element);
+		if (inputValue !== undefined) {
+			marker.value = inputValue;
+		}
+
+		const selectData = extractSelectData(element);
+		if (selectData.options !== undefined) {
+			marker.options = selectData.options;
+		}
+		if (selectData.selectedOptions !== undefined) {
+			marker.selectedOptions = selectData.selectedOptions;
+		}
+
+		markers.push(marker);
+	}
+
+	return markers;
+}

package/src/store.ts

@@ -0,0 +1,138 @@
+import type { Ai11yError, Ai11yEvent, Ai11yState } from "./context.js";
+import { notify } from "./events.js";
+
+let route: string | undefined;
+let state: Ai11yState | undefined;
+let error: Ai11yError | null | undefined;
+let events: Ai11yEvent[] = [];
+
+type StoreChangeListener = (
+	type: "route" | "state" | "error",
+	value: unknown,
+) => void;
+
+const storeListeners = new Set<StoreChangeListener>();
+
+function notifyStoreChange(
+	type: "route" | "state" | "error",
+	value: unknown,
+): void {
+	for (const listener of storeListeners) {
+		try {
+			listener(type, value);
+		} catch (err) {
+			// Don't let one listener's error break others
+			console.error("Error in store change listener:", err);
+		}
+	}
+}
+
+export function setRoute(newRoute: string | undefined): void {
+	route = newRoute;
+	notifyStoreChange("route", newRoute);
+}
+
+export function getRoute(): string | undefined {
+	return route;
+}
+
+/**
+ * Merges new state with existing state (similar to React's setState)
+ * Pass undefined to clear all state
+ *
+ * @param newState - Partial state to merge, or undefined to clear
+ *
+ * @example
+ * ```ts
+ * setState({ userId: '123' }); // Merges with existing state
+ * setState({ theme: 'dark' }); // Adds to state, keeps userId
+ * setState(undefined); // Clears all state
+ * ```
+ */
+export function setState(newState: Ai11yState | undefined): void {
+	if (newState === undefined) {
+		state = undefined;
+	} else {
+		state = { ...(state || {}), ...newState };
+	}
+	notifyStoreChange("state", state);
+}
+
+/**
+ * Clears all application state
+ *
+ * @example
+ * ```ts
+ * clearState(); // Resets state to empty
+ * ```
+ */
+export function clearState(): void {
+	state = undefined;
+	notifyStoreChange("state", undefined);
+}
+
+export function getState(): Ai11yState | undefined {
+	return state;
+}
+
+export function setError(newError: Ai11yError | null | undefined): void {
+	error = newError;
+	notifyStoreChange("error", newError);
+}
+
+export function getError(): Ai11yError | null | undefined {
+	return error;
+}
+
+export function track(event: string, payload?: unknown): void {
+	events = [
+		...events.slice(-49), // Keep last 50 events
+		{
+			type: event,
+			payload,
+			timestamp: Date.now(),
+		},
+	];
+	notify();
+}
+
+export function getEvents(): Ai11yEvent[] {
+	return events;
+}
+
+export function clearEvents(): void {
+	events = [];
+}
+
+/**
+ * Subscribe to store changes (route, state, error)
+ * Returns an unsubscribe function
+ *
+ * @param listener - Function called when route, state, or error changes
+ * @returns Unsubscribe function
+ *
+ * @example
+ * ```ts
+ * const unsubscribe = subscribeToStore((type, value) => {
+ *   if (type === 'route') console.log('Route changed:', value);
+ * });
+ * // Later...
+ * unsubscribe();
+ * ```
+ */
+export function subscribeToStore(listener: StoreChangeListener): () => void {
+	storeListeners.add(listener);
+	return () => {
+		storeListeners.delete(listener);
+	};
+}
+
+export function clearContext(): void {
+	route = undefined;
+	state = undefined;
+	error = undefined;
+	events = [];
+	notifyStoreChange("route", undefined);
+	notifyStoreChange("state", undefined);
+	notifyStoreChange("error", undefined);
+}

package/src/util/attributes.ts

@@ -0,0 +1,68 @@
+/**
+ * Attribute name constants for data-ai-* attributes
+ */
+export const ATTRIBUTE_ID = "data-ai-id";
+export const ATTRIBUTE_LABEL = "data-ai-label";
+export const ATTRIBUTE_INTENT = "data-ai-intent";
+export const ATTRIBUTE_SENSITIVE = "data-ai-sensitive";
+
+/**
+ * Gets the value of the data-ai-id attribute from an element
+ *
+ * @param element - The element to get the attribute from
+ * @returns The marker ID or null if not found
+ */
+export function getMarkerId(element: Element): string | null {
+	return element.getAttribute(ATTRIBUTE_ID);
+}
+
+/**
+ * Gets the value of the data-ai-label attribute from an element
+ *
+ * @param element - The element to get the attribute from
+ * @returns The marker label or null if not found
+ */
+export function getMarkerLabel(element: Element): string | null {
+	return element.getAttribute(ATTRIBUTE_LABEL);
+}
+
+/**
+ * Gets the value of the data-ai-intent attribute from an element
+ *
+ * @param element - The element to get the attribute from
+ * @returns The marker intent or null if not found
+ */
+export function getMarkerIntent(element: Element): string | null {
+	return element.getAttribute(ATTRIBUTE_INTENT);
+}
+
+/**
+ * Creates a query selector for finding an element by marker ID
+ *
+ * @param markerId - The marker ID to search for
+ * @returns A query selector string
+ *
+ * @example
+ * ```ts
+ * const selector = getMarkerSelector('connect_stripe');
+ * // Returns: '[data-ai-id="connect_stripe"]'
+ * ```
+ */
+export function getMarkerSelector(markerId: string): string {
+	return `[${ATTRIBUTE_ID}="${markerId}"]`;
+}
+
+/**
+ * Creates a query selector for finding all elements with marker IDs
+ *
+ * @returns A query selector string
+ *
+ * @example
+ * ```ts
+ * const selector = getAllMarkersSelector();
+ * // Returns: '[data-ai-id]'
+ * ```
+ */
+export function getAllMarkersSelector(): string {
+	return `[${ATTRIBUTE_ID}]`;
+}

package/src/util/format.ts

@@ -0,0 +1,16 @@
+/**
+ * Formats a marker ID into a readable label
+ * Converts snake_case to Title Case
+ *
+ * @param id - The marker ID to format
+ * @returns A formatted label
+ *
+ * @example
+ * ```ts
+ * formatMarkerId('connect_stripe');
+ * // Returns: 'Connect Stripe'
+ * ```
+ */
+export function formatMarkerId(id: string): string {
+	return id.replace(/_/g, " ").replace(/\b\w/g, (char) => char.toUpperCase());
+}

package/src/util/index.ts

@@ -0,0 +1,2 @@
+export * from "./attributes.js";
+export * from "./format.js";

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "NodeNext",
+		"lib": ["ES2022", "DOM"],
+		"moduleResolution": "nodenext",
+		"declaration": true,
+		"declarationMap": true,
+		"strict": true,
+		"esModuleInterop": true,
+		"skipLibCheck": true,
+		"forceConsistentCasingInFileNames": true,
+		"rootDir": "src",
+		"outDir": "dist"
+	},
+	"include": ["src/**/*"],
+	"exclude": ["node_modules", "dist"]
+}

package/tsdown.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from "tsdown";
+
+export default defineConfig({
+	entry: ["src/index.ts"],
+	unbundle: true,
+	format: ["esm"],
+	dts: true,
+	clean: true,
+	outDir: "dist",
+});