@ai11y/react 0.0.1

package/.turbo/turbo-build.log

@@ -0,0 +1,29 @@
+
+> @ai11y/react@0.0.1 build /home/runner/work/ai11y/ai11y/packages/react
+> tsdown
+
+ℹ tsdown v0.18.1 powered by rolldown v1.0.0-beta.55
+ℹ config file: /home/runner/work/ai11y/ai11y/packages/react/tsdown.config.ts (unrun)
+ℹ entry: src/index.ts
+ℹ tsconfig: tsconfig.json
+ℹ Build start
+ℹ dist/index.mjs                           0.28 kB │ gzip: 0.14 kB
+ℹ dist/hooks/useChat.mjs.map               6.75 kB │ gzip: 2.10 kB
+ℹ dist/components/Ai11yProvider.mjs.map    4.31 kB │ gzip: 1.51 kB
+ℹ dist/hooks/useChat.mjs                   3.23 kB │ gzip: 1.05 kB
+ℹ dist/components/Marker.mjs.map           1.95 kB │ gzip: 0.95 kB
+ℹ dist/components/Ai11yProvider.mjs        1.79 kB │ gzip: 0.69 kB
+ℹ dist/components/Ai11yProvider.d.mts.map  0.86 kB │ gzip: 0.39 kB
+ℹ dist/components/Marker.mjs               0.86 kB │ gzip: 0.48 kB
+ℹ dist/hooks/useAi11yContext.mjs.map       0.79 kB │ gzip: 0.46 kB
+ℹ dist/hooks/useChat.d.mts.map             0.77 kB │ gzip: 0.36 kB
+ℹ dist/hooks/useAi11yContext.mjs           0.61 kB │ gzip: 0.35 kB
+ℹ dist/components/Marker.d.mts.map         0.35 kB │ gzip: 0.23 kB
+ℹ dist/hooks/useAi11yContext.d.mts.map     0.18 kB │ gzip: 0.14 kB
+ℹ dist/index.d.mts                         0.28 kB │ gzip: 0.14 kB
+ℹ dist/components/Ai11yProvider.d.mts      1.14 kB │ gzip: 0.50 kB
+ℹ dist/hooks/useChat.d.mts                 0.80 kB │ gzip: 0.41 kB
+ℹ dist/components/Marker.d.mts             0.55 kB │ gzip: 0.32 kB
+ℹ dist/hooks/useAi11yContext.d.mts         0.47 kB │ gzip: 0.29 kB
+ℹ 18 files, total: 25.95 kB
+✔ Build complete in 3027ms

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# @ai11y/react
+
+## 0.0.1
+
+### Patch Changes
+
+- [#10](https://github.com/maerzhase/ai11y/pull/10)
+  [`a578f29`](https://github.com/maerzhase/ai11y/commit/a578f296c21cd19c935ff8003442677f7a1cb72d)
+  Thanks [@maerzhase](https://github.com/maerzhase)! - Docs and demo
+  improvements: naming (ai11y ≠ a11y), Describe/Plan/Act boundaries, UI context
+  payload viewer, annotation guidance, Why not ARIA, Security & privacy,
+  multi-step demo
+
+- [#10](https://github.com/maerzhase/ai11y/pull/10)
+  [`a578f29`](https://github.com/maerzhase/ai11y/commit/a578f296c21cd19c935ff8003442677f7a1cb72d)
+  Thanks [@maerzhase](https://github.com/maerzhase)! - Fix conversation history
+  not being passed to agent due to async state update timing issue
+
+- [#10](https://github.com/maerzhase/ai11y/pull/10)
+  [`a578f29`](https://github.com/maerzhase/ai11y/commit/a578f296c21cd19c935ff8003442677f7a1cb72d)
+  Thanks [@maerzhase](https://github.com/maerzhase)! - Add custom state
+  management and privacy protection features
+  - **Custom State API**: `setState()` now merges with existing state (like
+    React's setState), allowing multiple components to independently manage
+    state keys. Added `clearState()` helper for resetting state.
+  - **Privacy Protection**: Automatically redact sensitive input values
+    (passwords, hidden fields, credit card fields) from UI context. Values are
+    replaced with `[REDACTED]` to prevent exposure to AI agents.
+  - **Sensitive Marker Support**: Added `data-ai-sensitive` attribute and
+    `sensitive` prop to Marker component for explicitly marking sensitive
+    fields.
+  - **Agent Improvements**: Enhanced agent prompts with security rules to
+    prevent filling password fields and improved pronoun resolution for better
+    context tracking in conversations.
+
+- Updated dependencies
+  [[`a578f29`](https://github.com/maerzhase/ai11y/commit/a578f296c21cd19c935ff8003442677f7a1cb72d),
+  [`a578f29`](https://github.com/maerzhase/ai11y/commit/a578f296c21cd19c935ff8003442677f7a1cb72d)]:
+  - @ai11y/core@0.0.1

package/README.md

@@ -0,0 +1,52 @@
+# @ai11y/react
+
+Thin React wrapper for ai11y. Uses the same **describe → plan → act** flow: wrap
+your app in `Ai11yProvider`, mark elements with `Marker`, and use
+`useAi11yContext()` for `describe` and `act`; call `plan()` from `@ai11y/core`.
+
+## Installation
+
+```bash
+pnpm add @ai11y/react @ai11y/core
+```
+
+## Usage
+
+Wrap your app in `Ai11yProvider` and use `Marker` so elements are registered for
+`describe()`. Get `describe` and `act` from `useAi11yContext()` and call
+`plan()` from `@ai11y/core`:
+
+```tsx
+import { Ai11yProvider, Marker, useAi11yContext } from "@ai11y/react";
+import { plan } from "@ai11y/core";
+
+function App() {
+  return (
+    <Ai11yProvider onNavigate={(route) => navigate(route)}>
+      <YourApp />
+    </Ai11yProvider>
+  );
+}
+
+function Chat() {
+  const { describe, act } = useAi11yContext();
+  const handleSubmit = async (input: string) => {
+    const ui = describe();
+    const { reply, instructions } = await plan(ui, input);
+    for (const instruction of instructions ?? []) act(instruction);
+    return reply;
+  };
+  // ... render input and messages
+}
+```
+
+Mark elements so your agent can see them:
+
+```tsx
+<Marker id="save_btn" label="Save" intent="Save the document">
+  <button onClick={onSave}>Save</button>
+</Marker>
+```
+
+For the plan step with an LLM, point the client at your server endpoint; see
+[packages/agent/README.md](../agent/README.md).

package/dist/components/Ai11yProvider.d.mts

@@ -0,0 +1,36 @@
+import * as _ai11y_core0 from "@ai11y/core";
+import { AgentConfig, Ai11yError, Ai11yEvent, Ai11yState } from "@ai11y/core";
+import React from "react";
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+
+//#region src/components/Ai11yProvider.d.ts
+interface Ai11yProviderContextValue {
+  state: Ai11yState;
+  currentRoute: string;
+  lastError: Ai11yError | null;
+  events: Ai11yEvent[];
+  onNavigate?: (route: string) => void;
+  track: (event: string, payload?: unknown) => void;
+  reportError: (error: Error, meta?: {
+    surface?: string;
+    markerId?: string;
+  }) => void;
+  describe: () => _ai11y_core0.Ai11yContext;
+  act: (instruction: _ai11y_core0.Instruction) => void;
+  agentConfig: AgentConfig | null;
+}
+interface Ai11yProviderProps {
+  children: React.ReactNode;
+  initialState?: Ai11yState;
+  onNavigate?: (route: string) => void;
+  agentConfig?: AgentConfig;
+}
+declare function Ai11yProvider({
+  children,
+  initialState,
+  onNavigate,
+  agentConfig
+}: Ai11yProviderProps): react_jsx_runtime0.JSX.Element;
+//#endregion
+export { Ai11yProvider, Ai11yProviderContextValue };
+//# sourceMappingURL=Ai11yProvider.d.mts.map

package/dist/components/Ai11yProvider.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Ai11yProvider.d.mts","names":[],"sources":["../../src/components/Ai11yProvider.tsx"],"sourcesContent":[],"mappings":";;;;;;UAiBiB,yBAAA;SACT;;aAEI;EAHK,MAAA,EAIR,UAJQ,EAAA;EACT,UAAA,CAAA,EAAA,CAAA,KAAA,EAAA,MAAA,EAAA,GAAA,IAAA;EAEI,KAAA,EAAA,CAAA,KAAA,EAAA,MAAA,EAAA,OAAA,CAAA,EAAA,OAAA,EAAA,GAAA,IAAA;EACH,WAAA,EAAA,CAAA,KAAA,EAIA,KAJA,EAAA,IAO0C,CAP1C,EAAA;IAIA,OAAA,CAAA,EAAA,MAAA;IAAK,QAGyB,CAAA,EAAA,MAAA;EAAY,CAAA,EAAA,GAAA,IACT;EAC5B,QAAA,EAAA,GAAA,GALA,YAAA,CAGyB,YAEzB;EAAW,GAAA,EAAA,CAAA,WAAA,EAF0B,YAAA,CACT,WACjB,EAAA,GAAA,IAAA;EAOf,WAAA,EAPI,WAOc,GAAA,IAAA;;UAAlB,kBAAA,CAIK;EAAW,QAAA,EAHf,KAAA,CAAM,SAGS;EAGV,YAAA,CAAA,EALA,UAKa;EAC5B,UAAA,CAAA,EAAA,CAAA,KAAA,EAAA,MAAA,EAAA,GAAA,IAAA;EACA,WAAA,CAAA,EALc,WAKd;;AAEA,iBAJe,aAAA,CAIf;EAAA,QAAA;EAAA,YAAA;EAAA,UAAA;EAAA;AAAA,CAAA,EACE,kBADF,CAAA,EACoB,kBAAA,CAAA,GAAA,CAAA,OADpB"}

package/dist/components/Ai11yProvider.mjs

@@ -0,0 +1,52 @@
+import { createClient, getError, getEvents, getRoute, getState, setState, subscribe, subscribeToStore } from "@ai11y/core";
+import { createContext, useEffect, useRef, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/components/Ai11yProvider.tsx
+const Ai11yProviderContext = createContext(null);
+function Ai11yProvider({ children, initialState = {}, onNavigate, agentConfig }) {
+	const clientRef = useRef(createClient({ onNavigate }));
+	useEffect(() => {
+		if (Object.keys(initialState).length > 0) setState(initialState);
+	}, [initialState]);
+	const [currentRoute, setCurrentRoute] = useState(() => getRoute() || "/");
+	const [uiState, setUIState] = useState(() => {
+		return getState() || {};
+	});
+	const [lastError, setLastError] = useState(() => {
+		return getError() || null;
+	});
+	const [events, setEvents] = useState(() => getEvents());
+	useEffect(() => {
+		return subscribeToStore((type, value$1) => {
+			if (type === "route") setCurrentRoute(value$1 || "/");
+			else if (type === "state") setUIState(value$1 || {});
+			else if (type === "error") setLastError(value$1 || null);
+		});
+	}, []);
+	useEffect(() => {
+		return subscribe(() => {
+			setEvents([...getEvents()]);
+		});
+	}, []);
+	const value = {
+		state: uiState,
+		currentRoute,
+		lastError,
+		events,
+		onNavigate,
+		track: clientRef.current.track.bind(clientRef.current),
+		reportError: clientRef.current.reportError.bind(clientRef.current),
+		describe: clientRef.current.describe.bind(clientRef.current),
+		act: clientRef.current.act.bind(clientRef.current),
+		agentConfig: agentConfig ?? null
+	};
+	return /* @__PURE__ */ jsx(Ai11yProviderContext.Provider, {
+		value,
+		children
+	});
+}
+
+//#endregion
+export { Ai11yProvider, Ai11yProviderContext };
+//# sourceMappingURL=Ai11yProvider.mjs.map

package/dist/components/Ai11yProvider.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Ai11yProvider.mjs","names":["value","value: Ai11yProviderContextValue"],"sources":["../../src/components/Ai11yProvider.tsx"],"sourcesContent":["import {\n\ttype AgentConfig,\n\ttype Ai11yError,\n\ttype Ai11yEvent,\n\ttype Ai11yState,\n\tcreateClient,\n\tgetError,\n\tgetEvents,\n\tgetRoute,\n\tgetState,\n\tsetState,\n\tsubscribe,\n\tsubscribeToStore,\n} from \"@ai11y/core\";\nimport type React from \"react\";\nimport { createContext, useEffect, useRef, useState } from \"react\";\n\nexport interface Ai11yProviderContextValue {\n\tstate: Ai11yState;\n\tcurrentRoute: string;\n\tlastError: Ai11yError | null;\n\tevents: Ai11yEvent[];\n\tonNavigate?: (route: string) => void;\n\ttrack: (event: string, payload?: unknown) => void;\n\treportError: (\n\t\terror: Error,\n\t\tmeta?: { surface?: string; markerId?: string },\n\t) => void;\n\tdescribe: () => import(\"@ai11y/core\").Ai11yContext;\n\tact: (instruction: import(\"@ai11y/core\").Instruction) => void;\n\tagentConfig: AgentConfig | null;\n}\n\nconst Ai11yProviderContext = createContext<Ai11yProviderContextValue | null>(\n\tnull,\n);\n\ninterface Ai11yProviderProps {\n\tchildren: React.ReactNode;\n\tinitialState?: Ai11yState;\n\tonNavigate?: (route: string) => void;\n\tagentConfig?: AgentConfig;\n}\n\nexport function Ai11yProvider({\n\tchildren,\n\tinitialState = {},\n\tonNavigate,\n\tagentConfig,\n}: Ai11yProviderProps) {\n\tconst clientRef = useRef(\n\t\tcreateClient({\n\t\t\tonNavigate,\n\t\t}),\n\t);\n\n\tuseEffect(() => {\n\t\tif (Object.keys(initialState).length > 0) {\n\t\t\tsetState(initialState);\n\t\t}\n\t}, [initialState]);\n\n\tconst [currentRoute, setCurrentRoute] = useState<string>(\n\t\t() => getRoute() || \"/\",\n\t);\n\tconst [uiState, setUIState] = useState<Ai11yState>(() => {\n\t\tconst coreState = getState();\n\t\treturn coreState || {};\n\t});\n\tconst [lastError, setLastError] = useState<Ai11yError | null>(() => {\n\t\tconst coreError = getError();\n\t\treturn coreError || null;\n\t});\n\tconst [events, setEvents] = useState<Ai11yEvent[]>(() => getEvents());\n\n\tuseEffect(() => {\n\t\tconst unsubscribe = subscribeToStore(\n\t\t\t(type: \"route\" | \"state\" | \"error\", value: unknown) => {\n\t\t\t\tif (type === \"route\") {\n\t\t\t\t\tsetCurrentRoute((value as string) || \"/\");\n\t\t\t\t} else if (type === \"state\") {\n\t\t\t\t\tsetUIState((value as Ai11yState) || {});\n\t\t\t\t} else if (type === \"error\") {\n\t\t\t\t\tsetLastError((value as Ai11yError | null) || null);\n\t\t\t\t}\n\t\t\t},\n\t\t);\n\t\treturn unsubscribe;\n\t}, []);\n\n\tuseEffect(() => {\n\t\tconst unsubscribe = subscribe(() => {\n\t\t\tsetEvents([...getEvents()]);\n\t\t});\n\t\treturn unsubscribe;\n\t}, []);\n\n\tconst value: Ai11yProviderContextValue = {\n\t\tstate: uiState,\n\t\tcurrentRoute,\n\t\tlastError,\n\t\tevents,\n\t\tonNavigate,\n\t\ttrack: clientRef.current.track.bind(clientRef.current),\n\t\treportError: clientRef.current.reportError.bind(clientRef.current),\n\t\tdescribe: clientRef.current.describe.bind(clientRef.current),\n\t\tact: clientRef.current.act.bind(clientRef.current),\n\t\tagentConfig: agentConfig ?? null,\n\t};\n\n\treturn (\n\t\t<Ai11yProviderContext.Provider value={value}>\n\t\t\t{children}\n\t\t</Ai11yProviderContext.Provider>\n\t);\n}\n\nexport { Ai11yProviderContext };\n"],"mappings":";;;;;AAiCA,MAAM,uBAAuB,cAC5B,KACA;AASD,SAAgB,cAAc,EAC7B,UACA,eAAe,EAAE,EACjB,YACA,eACsB;CACtB,MAAM,YAAY,OACjB,aAAa,EACZ,YACA,CAAC,CACF;AAED,iBAAgB;AACf,MAAI,OAAO,KAAK,aAAa,CAAC,SAAS,EACtC,UAAS,aAAa;IAErB,CAAC,aAAa,CAAC;CAElB,MAAM,CAAC,cAAc,mBAAmB,eACjC,UAAU,IAAI,IACpB;CACD,MAAM,CAAC,SAAS,cAAc,eAA2B;AAExD,SADkB,UAAU,IACR,EAAE;GACrB;CACF,MAAM,CAAC,WAAW,gBAAgB,eAAkC;AAEnE,SADkB,UAAU,IACR;GACnB;CACF,MAAM,CAAC,QAAQ,aAAa,eAA6B,WAAW,CAAC;AAErE,iBAAgB;AAYf,SAXoB,kBAClB,MAAmC,YAAmB;AACtD,OAAI,SAAS,QACZ,iBAAiBA,WAAoB,IAAI;YAC/B,SAAS,QACnB,YAAYA,WAAwB,EAAE,CAAC;YAC7B,SAAS,QACnB,cAAcA,WAA+B,KAAK;IAGpD;IAEC,EAAE,CAAC;AAEN,iBAAgB;AAIf,SAHoB,gBAAgB;AACnC,aAAU,CAAC,GAAG,WAAW,CAAC,CAAC;IAC1B;IAEA,EAAE,CAAC;CAEN,MAAMC,QAAmC;EACxC,OAAO;EACP;EACA;EACA;EACA;EACA,OAAO,UAAU,QAAQ,MAAM,KAAK,UAAU,QAAQ;EACtD,aAAa,UAAU,QAAQ,YAAY,KAAK,UAAU,QAAQ;EAClE,UAAU,UAAU,QAAQ,SAAS,KAAK,UAAU,QAAQ;EAC5D,KAAK,UAAU,QAAQ,IAAI,KAAK,UAAU,QAAQ;EAClD,aAAa,eAAe;EAC5B;AAED,QACC,oBAAC,qBAAqB;EAAgB;EACpC;GAC8B"}

package/dist/components/Marker.d.mts

@@ -0,0 +1,22 @@
+import React from "react";
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+
+//#region src/components/Marker.d.ts
+interface MarkerProps {
+  id: string;
+  label: string;
+  intent: string;
+  children: React.ReactElement;
+  /** Mark this element as containing sensitive data that should be redacted from the UI context */
+  sensitive?: boolean;
+}
+declare function Marker({
+  id,
+  label,
+  intent,
+  children,
+  sensitive
+}: MarkerProps): react_jsx_runtime0.JSX.Element;
+//#endregion
+export { Marker };
+//# sourceMappingURL=Marker.d.mts.map

package/dist/components/Marker.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Marker.d.mts","names":[],"sources":["../../src/components/Marker.tsx"],"sourcesContent":[],"mappings":";;;;UAQU,WAAA;;;EAAA,MAAA,EAAA,MAAW;EAsBL,QAAA,EAlBL,KAAA,CAAM,YAkBK;EACrB;EACA,SAAA,CAAA,EAAA,OAAA;;AAEA,iBAJe,MAAA,CAIf;EAAA,EAAA;EAAA,KAAA;EAAA,MAAA;EAAA,QAAA;EAAA;AAAA,CAAA,EAEE,WAFF,CAAA,EAEa,kBAAA,CAAA,GAAA,CAAA,OAFb"}

package/dist/components/Marker.mjs

@@ -0,0 +1,31 @@
+import { ATTRIBUTE_ID, ATTRIBUTE_INTENT, ATTRIBUTE_LABEL, ATTRIBUTE_SENSITIVE } from "@ai11y/core";
+import React from "react";
+import { Fragment, jsx } from "react/jsx-runtime";
+
+//#region src/components/Marker.tsx
+function assignRef(ref, value) {
+	if (!ref) return;
+	if (typeof ref === "function") {
+		ref(value);
+		return;
+	}
+	try {
+		ref.current = value;
+	} catch {}
+}
+function Marker({ id, label, intent, children, sensitive }) {
+	const existingRef = children.props.ref;
+	return /* @__PURE__ */ jsx(Fragment, { children: React.cloneElement(children, {
+		ref: (node) => {
+			assignRef(existingRef, node);
+		},
+		[ATTRIBUTE_ID]: id,
+		...label && { [ATTRIBUTE_LABEL]: label },
+		...intent && { [ATTRIBUTE_INTENT]: intent },
+		...sensitive && { [ATTRIBUTE_SENSITIVE]: "true" }
+	}) });
+}
+
+//#endregion
+export { Marker };
+//# sourceMappingURL=Marker.mjs.map

package/dist/components/Marker.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Marker.mjs","names":[],"sources":["../../src/components/Marker.tsx"],"sourcesContent":["import {\n\tATTRIBUTE_ID,\n\tATTRIBUTE_INTENT,\n\tATTRIBUTE_LABEL,\n\tATTRIBUTE_SENSITIVE,\n} from \"@ai11y/core\";\nimport React from \"react\";\n\ninterface MarkerProps {\n\tid: string;\n\tlabel: string;\n\tintent: string;\n\tchildren: React.ReactElement;\n\t/** Mark this element as containing sensitive data that should be redacted from the UI context */\n\tsensitive?: boolean;\n}\n\nfunction assignRef<T>(ref: React.Ref<T> | undefined, value: T | null) {\n\tif (!ref) return;\n\tif (typeof ref === \"function\") {\n\t\tref(value);\n\t\treturn;\n\t}\n\ttry {\n\t\t(ref as React.MutableRefObject<T | null>).current = value;\n\t} catch {\n\t\t// ignore read-only refs\n\t}\n}\n\nexport function Marker({\n\tid,\n\tlabel,\n\tintent,\n\tchildren,\n\tsensitive,\n}: MarkerProps) {\n\tconst existingRef = (children.props as { ref?: React.Ref<HTMLElement> }).ref;\n\tconst childWithRef = React.cloneElement(children, {\n\t\tref: (node: HTMLElement | null) => {\n\t\t\tassignRef(existingRef, node);\n\t\t},\n\t\t[ATTRIBUTE_ID]: id,\n\t\t...(label && { [ATTRIBUTE_LABEL]: label }),\n\t\t...(intent && { [ATTRIBUTE_INTENT]: intent }),\n\t\t...(sensitive && { [ATTRIBUTE_SENSITIVE]: \"true\" }),\n\t} as React.HTMLAttributes<HTMLElement> & {\n\t\t[ATTRIBUTE_ID]: string;\n\t\t[ATTRIBUTE_LABEL]?: string;\n\t\t[ATTRIBUTE_INTENT]?: string;\n\t\t[ATTRIBUTE_SENSITIVE]?: string;\n\t});\n\n\treturn <>{childWithRef}</>;\n}\n"],"mappings":";;;;;AAiBA,SAAS,UAAa,KAA+B,OAAiB;AACrE,KAAI,CAAC,IAAK;AACV,KAAI,OAAO,QAAQ,YAAY;AAC9B,MAAI,MAAM;AACV;;AAED,KAAI;AACH,EAAC,IAAyC,UAAU;SAC7C;;AAKT,SAAgB,OAAO,EACtB,IACA,OACA,QACA,UACA,aACe;CACf,MAAM,cAAe,SAAS,MAA2C;AAgBzE,QAAO,0CAfc,MAAM,aAAa,UAAU;EACjD,MAAM,SAA6B;AAClC,aAAU,aAAa,KAAK;;GAE5B,eAAe;EAChB,GAAI,SAAS,GAAG,kBAAkB,OAAO;EACzC,GAAI,UAAU,GAAG,mBAAmB,QAAQ;EAC5C,GAAI,aAAa,GAAG,sBAAsB,QAAQ;EAClD,CAKC,GAEwB"}

package/dist/hooks/useAi11yContext.d.mts

@@ -0,0 +1,18 @@
+import { Ai11yProviderContextValue } from "../components/Ai11yProvider.mjs";
+
+//#region src/hooks/useAi11yContext.d.ts
+
+/**
+ * Hook to access the AI accessibility context
+ *
+ * @example
+ * ```tsx
+ * const ctx = useAi11yContext()
+ * const ui = ctx.describe()
+ * ctx.act({ action: "click", id: "save_button" })
+ * ```
+ */
+declare function useAi11yContext(): Ai11yProviderContextValue;
+//#endregion
+export { useAi11yContext };
+//# sourceMappingURL=useAi11yContext.d.mts.map

package/dist/hooks/useAi11yContext.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAi11yContext.d.mts","names":[],"sources":["../../src/hooks/useAi11yContext.ts"],"sourcesContent":[],"mappings":";;;;;;;AAaA;;;;;;;iBAAgB,eAAA,CAAA,GAAe"}

package/dist/hooks/useAi11yContext.mjs

@@ -0,0 +1,23 @@
+import { Ai11yProviderContext } from "../components/Ai11yProvider.mjs";
+import { useContext } from "react";
+
+//#region src/hooks/useAi11yContext.ts
+/**
+* Hook to access the AI accessibility context
+*
+* @example
+* ```tsx
+* const ctx = useAi11yContext()
+* const ui = ctx.describe()
+* ctx.act({ action: "click", id: "save_button" })
+* ```
+*/
+function useAi11yContext() {
+	const context = useContext(Ai11yProviderContext);
+	if (!context) throw new Error("useAi11yContext must be used within Ai11yProvider");
+	return context;
+}
+
+//#endregion
+export { useAi11yContext };
+//# sourceMappingURL=useAi11yContext.mjs.map

package/dist/hooks/useAi11yContext.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAi11yContext.mjs","names":[],"sources":["../../src/hooks/useAi11yContext.ts"],"sourcesContent":["import { useContext } from \"react\";\nimport { Ai11yProviderContext } from \"../components/Ai11yProvider.js\";\n\n/**\n * Hook to access the AI accessibility context\n *\n * @example\n * ```tsx\n * const ctx = useAi11yContext()\n * const ui = ctx.describe()\n * ctx.act({ action: \"click\", id: \"save_button\" })\n * ```\n */\nexport function useAi11yContext() {\n\tconst context = useContext(Ai11yProviderContext);\n\tif (!context) {\n\t\tthrow new Error(\"useAi11yContext must be used within Ai11yProvider\");\n\t}\n\treturn context;\n}\n"],"mappings":";;;;;;;;;;;;;;AAaA,SAAgB,kBAAkB;CACjC,MAAM,UAAU,WAAW,qBAAqB;AAChD,KAAI,CAAC,QACJ,OAAM,IAAI,MAAM,oDAAoD;AAErE,QAAO"}

package/dist/hooks/useChat.d.mts

@@ -0,0 +1,31 @@
+import { AgentResponse, Instruction } from "@ai11y/core";
+
+//#region src/hooks/useChat.d.ts
+interface Message {
+  id: string;
+  type: "user" | "assistant" | "system";
+  content: string;
+  timestamp: number;
+}
+interface UseChatOptions {
+  onSubmit: (message: string, messages: Message[]) => Promise<AgentResponse>;
+  onInstruction?: (instruction: Instruction) => void;
+  onMessage?: () => void;
+  initialMessage?: string;
+}
+interface UseChatReturn {
+  messages: Message[];
+  input: string;
+  setInput: (value: string) => void;
+  isProcessing: boolean;
+  handleSubmit: (e: React.FormEvent) => Promise<void>;
+}
+declare function useChat({
+  onSubmit,
+  onInstruction,
+  onMessage,
+  initialMessage
+}: UseChatOptions): UseChatReturn;
+//#endregion
+export { useChat };
+//# sourceMappingURL=useChat.d.mts.map

package/dist/hooks/useChat.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useChat.d.mts","names":[],"sources":["../../src/hooks/useChat.ts"],"sourcesContent":[],"mappings":";;;UAGiB,OAAA;;EAAA,IAAA,EAAA,MAAO,GAAA,WAAA,GAAA,QAAA;EAOP,OAAA,EAAA,MAAA;EACsB,SAAA,EAAA,MAAA;;AAAc,UADpC,cAAA,CACoC;EACtB,QAAA,EAAA,CAAA,OAAA,EAAA,MAAA,EAAA,QAAA,EADQ,OACR,EAAA,EAAA,GADsB,OACtB,CAD8B,aAC9B,CAAA;EAAW,aAAA,CAAA,EAAA,CAAA,WAAA,EAAX,WAAW,EAAA,GAAA,IAAA;EAKzB,SAAA,CAAA,EAAA,GAAA,GAAa,IAAA;EACnB,cAAA,CAAA,EAAA,MAAA;;AAI4B,UALtB,aAAA,CAKsB;EAAO,QAAA,EAJnC,OAImC,EAAA;EAG9B,KAAA,EAAA,MAAO;EACtB,QAAA,EAAA,CAAA,KAAA,EAAA,MAAA,EAAA,GAAA,IAAA;EACA,YAAA,EAAA,OAAA;EACA,YAAA,EAAA,CAAA,CAAA,EANkB,KAAA,CAAM,SAMxB,EAAA,GANsC,OAMtC,CAAA,IAAA,CAAA;;AAEE,iBALa,OAAA,CAKb;EAAA,QAAA;EAAA,aAAA;EAAA,SAAA;EAAA;AAAA,CAAA,EAAA,cAAA,CAAA,EAAiB,aAAjB"}

package/dist/hooks/useChat.mjs

@@ -0,0 +1,90 @@
+import { useCallback, useRef, useState } from "react";
+
+//#region src/hooks/useChat.ts
+function useChat({ onSubmit, onInstruction, onMessage, initialMessage = "Hi! I'm your AI agent. I can help you navigate, click buttons, and highlight elements. Try saying 'go to billing' or 'click connect stripe'." }) {
+	const [messages, setMessages] = useState([{
+		id: "welcome",
+		type: "assistant",
+		content: initialMessage,
+		timestamp: Date.now()
+	}]);
+	const [input, setInput] = useState("");
+	const [isProcessing, setIsProcessing] = useState(false);
+	const processingRef = useRef(false);
+	const messageIdCounterRef = useRef(0);
+	const inputRef = useRef(input);
+	const isProcessingRef = useRef(isProcessing);
+	const messagesRef = useRef(messages);
+	inputRef.current = input;
+	isProcessingRef.current = isProcessing;
+	messagesRef.current = messages;
+	return {
+		messages,
+		input,
+		setInput,
+		isProcessing,
+		handleSubmit: useCallback(async (e) => {
+			e.preventDefault();
+			if (!inputRef.current.trim() || isProcessingRef.current || processingRef.current) return;
+			const userMessage = inputRef.current.trim();
+			setInput("");
+			setIsProcessing(true);
+			processingRef.current = true;
+			queueMicrotask(() => onMessage?.());
+			messageIdCounterRef.current += 1;
+			const userMsg = {
+				id: `user-${Date.now()}-${messageIdCounterRef.current}`,
+				type: "user",
+				content: userMessage,
+				timestamp: Date.now()
+			};
+			const updatedMessages = [...messagesRef.current, userMsg];
+			setMessages(updatedMessages);
+			queueMicrotask(() => onMessage?.());
+			try {
+				const response = await onSubmit(userMessage, updatedMessages);
+				if (processingRef.current) {
+					messageIdCounterRef.current += 1;
+					const assistantMsg = {
+						id: `assistant-${Date.now()}-${messageIdCounterRef.current}`,
+						type: "assistant",
+						content: response.reply,
+						timestamp: Date.now()
+					};
+					setMessages((prevMsgs) => {
+						if (prevMsgs.some((msg) => msg.id === assistantMsg.id || msg.type === "assistant" && msg.content === response.reply && msg.timestamp === assistantMsg.timestamp)) return prevMsgs;
+						return [...prevMsgs, assistantMsg];
+					});
+					queueMicrotask(() => onMessage?.());
+					if (response.instructions && onInstruction) for (const instruction of response.instructions) onInstruction(instruction);
+				}
+			} catch (error) {
+				if (processingRef.current) {
+					messageIdCounterRef.current += 1;
+					const errorMsg = {
+						id: `error-${Date.now()}-${messageIdCounterRef.current}`,
+						type: "assistant",
+						content: `Sorry, I encountered an error: ${error instanceof Error ? error.message : "Unknown error"}. Please try again.`,
+						timestamp: Date.now()
+					};
+					setMessages((prevMsgs) => {
+						if (prevMsgs.some((msg) => msg.id === errorMsg.id || msg.type === "assistant" && msg.content === errorMsg.content && msg.timestamp === errorMsg.timestamp)) return prevMsgs;
+						return [...prevMsgs, errorMsg];
+					});
+					queueMicrotask(() => onMessage?.());
+				}
+			} finally {
+				setIsProcessing(false);
+				processingRef.current = false;
+			}
+		}, [
+			onSubmit,
+			onInstruction,
+			onMessage
+		])
+	};
+}
+
+//#endregion
+export { useChat };
+//# sourceMappingURL=useChat.mjs.map

package/dist/hooks/useChat.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useChat.mjs","names":["userMsg: Message","assistantMsg: Message","errorMsg: Message"],"sources":["../../src/hooks/useChat.ts"],"sourcesContent":["import type { AgentResponse, Instruction } from \"@ai11y/core\";\nimport { useCallback, useRef, useState } from \"react\";\n\nexport interface Message {\n\tid: string;\n\ttype: \"user\" | \"assistant\" | \"system\";\n\tcontent: string;\n\ttimestamp: number;\n}\n\nexport interface UseChatOptions {\n\tonSubmit: (message: string, messages: Message[]) => Promise<AgentResponse>;\n\tonInstruction?: (instruction: Instruction) => void;\n\tonMessage?: () => void;\n\tinitialMessage?: string;\n}\n\nexport interface UseChatReturn {\n\tmessages: Message[];\n\tinput: string;\n\tsetInput: (value: string) => void;\n\tisProcessing: boolean;\n\thandleSubmit: (e: React.FormEvent) => Promise<void>;\n}\n\nexport function useChat({\n\tonSubmit,\n\tonInstruction,\n\tonMessage,\n\tinitialMessage = \"Hi! I'm your AI agent. I can help you navigate, click buttons, and highlight elements. Try saying 'go to billing' or 'click connect stripe'.\",\n}: UseChatOptions): UseChatReturn {\n\tconst [messages, setMessages] = useState<Message[]>([\n\t\t{\n\t\t\tid: \"welcome\",\n\t\t\ttype: \"assistant\",\n\t\t\tcontent: initialMessage,\n\t\t\ttimestamp: Date.now(),\n\t\t},\n\t]);\n\tconst [input, setInput] = useState(\"\");\n\tconst [isProcessing, setIsProcessing] = useState(false);\n\tconst processingRef = useRef(false);\n\tconst messageIdCounterRef = useRef(0);\n\tconst inputRef = useRef(input);\n\tconst isProcessingRef = useRef(isProcessing);\n\tconst messagesRef = useRef(messages);\n\tinputRef.current = input;\n\tisProcessingRef.current = isProcessing;\n\tmessagesRef.current = messages;\n\n\tconst handleSubmit = useCallback(\n\t\tasync (e: React.FormEvent) => {\n\t\t\te.preventDefault();\n\t\t\tif (\n\t\t\t\t!inputRef.current.trim() ||\n\t\t\t\tisProcessingRef.current ||\n\t\t\t\tprocessingRef.current\n\t\t\t)\n\t\t\t\treturn;\n\n\t\t\tconst userMessage = inputRef.current.trim();\n\t\t\tsetInput(\"\");\n\t\t\tsetIsProcessing(true);\n\t\t\tprocessingRef.current = true;\n\t\t\tqueueMicrotask(() => onMessage?.());\n\n\t\t\tmessageIdCounterRef.current += 1;\n\t\t\tconst userMsg: Message = {\n\t\t\t\tid: `user-${Date.now()}-${messageIdCounterRef.current}`,\n\t\t\t\ttype: \"user\",\n\t\t\t\tcontent: userMessage,\n\t\t\t\ttimestamp: Date.now(),\n\t\t\t};\n\n\t\t\tconst updatedMessages = [...messagesRef.current, userMsg];\n\t\t\tsetMessages(updatedMessages);\n\t\t\tqueueMicrotask(() => onMessage?.());\n\n\t\t\ttry {\n\t\t\t\tconst response = await onSubmit(userMessage, updatedMessages);\n\n\t\t\t\t// Add agent reply only if we're still processing (prevent duplicates)\n\t\t\t\tif (processingRef.current) {\n\t\t\t\t\tmessageIdCounterRef.current += 1;\n\t\t\t\t\tconst assistantMsg: Message = {\n\t\t\t\t\t\tid: `assistant-${Date.now()}-${messageIdCounterRef.current}`,\n\t\t\t\t\t\ttype: \"assistant\",\n\t\t\t\t\t\tcontent: response.reply,\n\t\t\t\t\t\ttimestamp: Date.now(),\n\t\t\t\t\t};\n\t\t\t\t\tsetMessages((prevMsgs) => {\n\t\t\t\t\t\tconst exists = prevMsgs.some(\n\t\t\t\t\t\t\t(msg) =>\n\t\t\t\t\t\t\t\tmsg.id === assistantMsg.id ||\n\t\t\t\t\t\t\t\t(msg.type === \"assistant\" &&\n\t\t\t\t\t\t\t\t\tmsg.content === response.reply &&\n\t\t\t\t\t\t\t\t\tmsg.timestamp === assistantMsg.timestamp),\n\t\t\t\t\t\t);\n\t\t\t\t\t\tif (exists) return prevMsgs;\n\t\t\t\t\t\treturn [...prevMsgs, assistantMsg];\n\t\t\t\t\t});\n\t\t\t\t\tqueueMicrotask(() => onMessage?.());\n\n\t\t\t\t\tif (response.instructions && onInstruction) {\n\t\t\t\t\t\tfor (const instruction of response.instructions) {\n\t\t\t\t\t\t\tonInstruction(instruction);\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t} catch (error) {\n\t\t\t\tif (processingRef.current) {\n\t\t\t\t\tmessageIdCounterRef.current += 1;\n\t\t\t\t\tconst errorMsg: Message = {\n\t\t\t\t\t\tid: `error-${Date.now()}-${messageIdCounterRef.current}`,\n\t\t\t\t\t\ttype: \"assistant\",\n\t\t\t\t\t\tcontent: `Sorry, I encountered an error: ${error instanceof Error ? error.message : \"Unknown error\"}. Please try again.`,\n\t\t\t\t\t\ttimestamp: Date.now(),\n\t\t\t\t\t};\n\t\t\t\t\tsetMessages((prevMsgs) => {\n\t\t\t\t\t\tconst exists = prevMsgs.some(\n\t\t\t\t\t\t\t(msg) =>\n\t\t\t\t\t\t\t\tmsg.id === errorMsg.id ||\n\t\t\t\t\t\t\t\t(msg.type === \"assistant\" &&\n\t\t\t\t\t\t\t\t\tmsg.content === errorMsg.content &&\n\t\t\t\t\t\t\t\t\tmsg.timestamp === errorMsg.timestamp),\n\t\t\t\t\t\t);\n\t\t\t\t\t\tif (exists) return prevMsgs;\n\t\t\t\t\t\treturn [...prevMsgs, errorMsg];\n\t\t\t\t\t});\n\t\t\t\t\tqueueMicrotask(() => onMessage?.());\n\t\t\t\t}\n\t\t\t} finally {\n\t\t\t\tsetIsProcessing(false);\n\t\t\t\tprocessingRef.current = false;\n\t\t\t}\n\t\t},\n\t\t[onSubmit, onInstruction, onMessage],\n\t);\n\n\treturn {\n\t\tmessages,\n\t\tinput,\n\t\tsetInput,\n\t\tisProcessing,\n\t\thandleSubmit,\n\t};\n}\n"],"mappings":";;;AAyBA,SAAgB,QAAQ,EACvB,UACA,eACA,WACA,iBAAiB,kJACgB;CACjC,MAAM,CAAC,UAAU,eAAe,SAAoB,CACnD;EACC,IAAI;EACJ,MAAM;EACN,SAAS;EACT,WAAW,KAAK,KAAK;EACrB,CACD,CAAC;CACF,MAAM,CAAC,OAAO,YAAY,SAAS,GAAG;CACtC,MAAM,CAAC,cAAc,mBAAmB,SAAS,MAAM;CACvD,MAAM,gBAAgB,OAAO,MAAM;CACnC,MAAM,sBAAsB,OAAO,EAAE;CACrC,MAAM,WAAW,OAAO,MAAM;CAC9B,MAAM,kBAAkB,OAAO,aAAa;CAC5C,MAAM,cAAc,OAAO,SAAS;AACpC,UAAS,UAAU;AACnB,iBAAgB,UAAU;AAC1B,aAAY,UAAU;AA2FtB,QAAO;EACN;EACA;EACA;EACA;EACA,cA9FoB,YACpB,OAAO,MAAuB;AAC7B,KAAE,gBAAgB;AAClB,OACC,CAAC,SAAS,QAAQ,MAAM,IACxB,gBAAgB,WAChB,cAAc,QAEd;GAED,MAAM,cAAc,SAAS,QAAQ,MAAM;AAC3C,YAAS,GAAG;AACZ,mBAAgB,KAAK;AACrB,iBAAc,UAAU;AACxB,wBAAqB,aAAa,CAAC;AAEnC,uBAAoB,WAAW;GAC/B,MAAMA,UAAmB;IACxB,IAAI,QAAQ,KAAK,KAAK,CAAC,GAAG,oBAAoB;IAC9C,MAAM;IACN,SAAS;IACT,WAAW,KAAK,KAAK;IACrB;GAED,MAAM,kBAAkB,CAAC,GAAG,YAAY,SAAS,QAAQ;AACzD,eAAY,gBAAgB;AAC5B,wBAAqB,aAAa,CAAC;AAEnC,OAAI;IACH,MAAM,WAAW,MAAM,SAAS,aAAa,gBAAgB;AAG7D,QAAI,cAAc,SAAS;AAC1B,yBAAoB,WAAW;KAC/B,MAAMC,eAAwB;MAC7B,IAAI,aAAa,KAAK,KAAK,CAAC,GAAG,oBAAoB;MACnD,MAAM;MACN,SAAS,SAAS;MAClB,WAAW,KAAK,KAAK;MACrB;AACD,kBAAa,aAAa;AAQzB,UAPe,SAAS,MACtB,QACA,IAAI,OAAO,aAAa,MACvB,IAAI,SAAS,eACb,IAAI,YAAY,SAAS,SACzB,IAAI,cAAc,aAAa,UACjC,CACW,QAAO;AACnB,aAAO,CAAC,GAAG,UAAU,aAAa;OACjC;AACF,0BAAqB,aAAa,CAAC;AAEnC,SAAI,SAAS,gBAAgB,cAC5B,MAAK,MAAM,eAAe,SAAS,aAClC,eAAc,YAAY;;YAIrB,OAAO;AACf,QAAI,cAAc,SAAS;AAC1B,yBAAoB,WAAW;KAC/B,MAAMC,WAAoB;MACzB,IAAI,SAAS,KAAK,KAAK,CAAC,GAAG,oBAAoB;MAC/C,MAAM;MACN,SAAS,kCAAkC,iBAAiB,QAAQ,MAAM,UAAU,gBAAgB;MACpG,WAAW,KAAK,KAAK;MACrB;AACD,kBAAa,aAAa;AAQzB,UAPe,SAAS,MACtB,QACA,IAAI,OAAO,SAAS,MACnB,IAAI,SAAS,eACb,IAAI,YAAY,SAAS,WACzB,IAAI,cAAc,SAAS,UAC7B,CACW,QAAO;AACnB,aAAO,CAAC,GAAG,UAAU,SAAS;OAC7B;AACF,0BAAqB,aAAa,CAAC;;aAE3B;AACT,oBAAgB,MAAM;AACtB,kBAAc,UAAU;;KAG1B;GAAC;GAAU;GAAe;GAAU,CACpC;EAQA"}

package/dist/index.d.mts

@@ -0,0 +1,5 @@
+import { Ai11yProvider } from "./components/Ai11yProvider.mjs";
+import { Marker } from "./components/Marker.mjs";
+import { useAi11yContext } from "./hooks/useAi11yContext.mjs";
+import { useChat } from "./hooks/useChat.mjs";
+export { Ai11yProvider, Marker, useAi11yContext, useChat };

package/dist/index.mjs

@@ -0,0 +1,6 @@
+import { Ai11yProvider } from "./components/Ai11yProvider.mjs";
+import { Marker } from "./components/Marker.mjs";
+import { useAi11yContext } from "./hooks/useAi11yContext.mjs";
+import { useChat } from "./hooks/useChat.mjs";
+
+export { Ai11yProvider, Marker, useAi11yContext, useChat };

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@ai11y/react",
+  "author": "maerzhase3000",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@ai11y/core": "0.0.1"
+  },
+  "peerDependencies": {
+    "react": "19.2.3",
+    "react-dom": "19.2.3"
+  },
+  "devDependencies": {
+    "@tsconfig/create-react-app": "2.0.10",
+    "@types/react": "19.2.7",
+    "@types/react-dom": "19.2.3",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "tsdown": "0.18.1",
+    "typescript": "5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "watch": "tsdown --watch",
+    "dev": "tsdown --watch"
+  }
+}

package/src/components/Ai11yProvider.tsx

@@ -0,0 +1,118 @@
+import {
+	type AgentConfig,
+	type Ai11yError,
+	type Ai11yEvent,
+	type Ai11yState,
+	createClient,
+	getError,
+	getEvents,
+	getRoute,
+	getState,
+	setState,
+	subscribe,
+	subscribeToStore,
+} from "@ai11y/core";
+import type React from "react";
+import { createContext, useEffect, useRef, useState } from "react";
+
+export interface Ai11yProviderContextValue {
+	state: Ai11yState;
+	currentRoute: string;
+	lastError: Ai11yError | null;
+	events: Ai11yEvent[];
+	onNavigate?: (route: string) => void;
+	track: (event: string, payload?: unknown) => void;
+	reportError: (
+		error: Error,
+		meta?: { surface?: string; markerId?: string },
+	) => void;
+	describe: () => import("@ai11y/core").Ai11yContext;
+	act: (instruction: import("@ai11y/core").Instruction) => void;
+	agentConfig: AgentConfig | null;
+}
+
+const Ai11yProviderContext = createContext<Ai11yProviderContextValue | null>(
+	null,
+);
+
+interface Ai11yProviderProps {
+	children: React.ReactNode;
+	initialState?: Ai11yState;
+	onNavigate?: (route: string) => void;
+	agentConfig?: AgentConfig;
+}
+
+export function Ai11yProvider({
+	children,
+	initialState = {},
+	onNavigate,
+	agentConfig,
+}: Ai11yProviderProps) {
+	const clientRef = useRef(
+		createClient({
+			onNavigate,
+		}),
+	);
+
+	useEffect(() => {
+		if (Object.keys(initialState).length > 0) {
+			setState(initialState);
+		}
+	}, [initialState]);
+
+	const [currentRoute, setCurrentRoute] = useState<string>(
+		() => getRoute() || "/",
+	);
+	const [uiState, setUIState] = useState<Ai11yState>(() => {
+		const coreState = getState();
+		return coreState || {};
+	});
+	const [lastError, setLastError] = useState<Ai11yError | null>(() => {
+		const coreError = getError();
+		return coreError || null;
+	});
+	const [events, setEvents] = useState<Ai11yEvent[]>(() => getEvents());
+
+	useEffect(() => {
+		const unsubscribe = subscribeToStore(
+			(type: "route" | "state" | "error", value: unknown) => {
+				if (type === "route") {
+					setCurrentRoute((value as string) || "/");
+				} else if (type === "state") {
+					setUIState((value as Ai11yState) || {});
+				} else if (type === "error") {
+					setLastError((value as Ai11yError | null) || null);
+				}
+			},
+		);
+		return unsubscribe;
+	}, []);
+
+	useEffect(() => {
+		const unsubscribe = subscribe(() => {
+			setEvents([...getEvents()]);
+		});
+		return unsubscribe;
+	}, []);
+
+	const value: Ai11yProviderContextValue = {
+		state: uiState,
+		currentRoute,
+		lastError,
+		events,
+		onNavigate,
+		track: clientRef.current.track.bind(clientRef.current),
+		reportError: clientRef.current.reportError.bind(clientRef.current),
+		describe: clientRef.current.describe.bind(clientRef.current),
+		act: clientRef.current.act.bind(clientRef.current),
+		agentConfig: agentConfig ?? null,
+	};
+
+	return (
+		<Ai11yProviderContext.Provider value={value}>
+			{children}
+		</Ai11yProviderContext.Provider>
+	);
+}
+
+export { Ai11yProviderContext };

package/src/components/Marker.tsx

@@ -0,0 +1,55 @@
+import {
+	ATTRIBUTE_ID,
+	ATTRIBUTE_INTENT,
+	ATTRIBUTE_LABEL,
+	ATTRIBUTE_SENSITIVE,
+} from "@ai11y/core";
+import React from "react";
+
+interface MarkerProps {
+	id: string;
+	label: string;
+	intent: string;
+	children: React.ReactElement;
+	/** Mark this element as containing sensitive data that should be redacted from the UI context */
+	sensitive?: boolean;
+}
+
+function assignRef<T>(ref: React.Ref<T> | undefined, value: T | null) {
+	if (!ref) return;
+	if (typeof ref === "function") {
+		ref(value);
+		return;
+	}
+	try {
+		(ref as React.MutableRefObject<T | null>).current = value;
+	} catch {
+		// ignore read-only refs
+	}
+}
+
+export function Marker({
+	id,
+	label,
+	intent,
+	children,
+	sensitive,
+}: MarkerProps) {
+	const existingRef = (children.props as { ref?: React.Ref<HTMLElement> }).ref;
+	const childWithRef = React.cloneElement(children, {
+		ref: (node: HTMLElement | null) => {
+			assignRef(existingRef, node);
+		},
+		[ATTRIBUTE_ID]: id,
+		...(label && { [ATTRIBUTE_LABEL]: label }),
+		...(intent && { [ATTRIBUTE_INTENT]: intent }),
+		...(sensitive && { [ATTRIBUTE_SENSITIVE]: "true" }),
+	} as React.HTMLAttributes<HTMLElement> & {
+		[ATTRIBUTE_ID]: string;
+		[ATTRIBUTE_LABEL]?: string;
+		[ATTRIBUTE_INTENT]?: string;
+		[ATTRIBUTE_SENSITIVE]?: string;
+	});
+
+	return <>{childWithRef}</>;
+}

package/src/hooks/useAi11yContext.ts

@@ -0,0 +1,20 @@
+import { useContext } from "react";
+import { Ai11yProviderContext } from "../components/Ai11yProvider.js";
+
+/**
+ * Hook to access the AI accessibility context
+ *
+ * @example
+ * ```tsx
+ * const ctx = useAi11yContext()
+ * const ui = ctx.describe()
+ * ctx.act({ action: "click", id: "save_button" })
+ * ```
+ */
+export function useAi11yContext() {
+	const context = useContext(Ai11yProviderContext);
+	if (!context) {
+		throw new Error("useAi11yContext must be used within Ai11yProvider");
+	}
+	return context;
+}

package/src/hooks/useChat.ts

@@ -0,0 +1,147 @@
+import type { AgentResponse, Instruction } from "@ai11y/core";
+import { useCallback, useRef, useState } from "react";
+
+export interface Message {
+	id: string;
+	type: "user" | "assistant" | "system";
+	content: string;
+	timestamp: number;
+}
+
+export interface UseChatOptions {
+	onSubmit: (message: string, messages: Message[]) => Promise<AgentResponse>;
+	onInstruction?: (instruction: Instruction) => void;
+	onMessage?: () => void;
+	initialMessage?: string;
+}
+
+export interface UseChatReturn {
+	messages: Message[];
+	input: string;
+	setInput: (value: string) => void;
+	isProcessing: boolean;
+	handleSubmit: (e: React.FormEvent) => Promise<void>;
+}
+
+export function useChat({
+	onSubmit,
+	onInstruction,
+	onMessage,
+	initialMessage = "Hi! I'm your AI agent. I can help you navigate, click buttons, and highlight elements. Try saying 'go to billing' or 'click connect stripe'.",
+}: UseChatOptions): UseChatReturn {
+	const [messages, setMessages] = useState<Message[]>([
+		{
+			id: "welcome",
+			type: "assistant",
+			content: initialMessage,
+			timestamp: Date.now(),
+		},
+	]);
+	const [input, setInput] = useState("");
+	const [isProcessing, setIsProcessing] = useState(false);
+	const processingRef = useRef(false);
+	const messageIdCounterRef = useRef(0);
+	const inputRef = useRef(input);
+	const isProcessingRef = useRef(isProcessing);
+	const messagesRef = useRef(messages);
+	inputRef.current = input;
+	isProcessingRef.current = isProcessing;
+	messagesRef.current = messages;
+
+	const handleSubmit = useCallback(
+		async (e: React.FormEvent) => {
+			e.preventDefault();
+			if (
+				!inputRef.current.trim() ||
+				isProcessingRef.current ||
+				processingRef.current
+			)
+				return;
+
+			const userMessage = inputRef.current.trim();
+			setInput("");
+			setIsProcessing(true);
+			processingRef.current = true;
+			queueMicrotask(() => onMessage?.());
+
+			messageIdCounterRef.current += 1;
+			const userMsg: Message = {
+				id: `user-${Date.now()}-${messageIdCounterRef.current}`,
+				type: "user",
+				content: userMessage,
+				timestamp: Date.now(),
+			};
+
+			const updatedMessages = [...messagesRef.current, userMsg];
+			setMessages(updatedMessages);
+			queueMicrotask(() => onMessage?.());
+
+			try {
+				const response = await onSubmit(userMessage, updatedMessages);
+
+				// Add agent reply only if we're still processing (prevent duplicates)
+				if (processingRef.current) {
+					messageIdCounterRef.current += 1;
+					const assistantMsg: Message = {
+						id: `assistant-${Date.now()}-${messageIdCounterRef.current}`,
+						type: "assistant",
+						content: response.reply,
+						timestamp: Date.now(),
+					};
+					setMessages((prevMsgs) => {
+						const exists = prevMsgs.some(
+							(msg) =>
+								msg.id === assistantMsg.id ||
+								(msg.type === "assistant" &&
+									msg.content === response.reply &&
+									msg.timestamp === assistantMsg.timestamp),
+						);
+						if (exists) return prevMsgs;
+						return [...prevMsgs, assistantMsg];
+					});
+					queueMicrotask(() => onMessage?.());
+
+					if (response.instructions && onInstruction) {
+						for (const instruction of response.instructions) {
+							onInstruction(instruction);
+						}
+					}
+				}
+			} catch (error) {
+				if (processingRef.current) {
+					messageIdCounterRef.current += 1;
+					const errorMsg: Message = {
+						id: `error-${Date.now()}-${messageIdCounterRef.current}`,
+						type: "assistant",
+						content: `Sorry, I encountered an error: ${error instanceof Error ? error.message : "Unknown error"}. Please try again.`,
+						timestamp: Date.now(),
+					};
+					setMessages((prevMsgs) => {
+						const exists = prevMsgs.some(
+							(msg) =>
+								msg.id === errorMsg.id ||
+								(msg.type === "assistant" &&
+									msg.content === errorMsg.content &&
+									msg.timestamp === errorMsg.timestamp),
+						);
+						if (exists) return prevMsgs;
+						return [...prevMsgs, errorMsg];
+					});
+					queueMicrotask(() => onMessage?.());
+				}
+			} finally {
+				setIsProcessing(false);
+				processingRef.current = false;
+			}
+		},
+		[onSubmit, onInstruction, onMessage],
+	);
+
+	return {
+		messages,
+		input,
+		setInput,
+		isProcessing,
+		handleSubmit,
+	};
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { Ai11yProvider } from "./components/Ai11yProvider.js";
+export { Marker } from "./components/Marker.js";
+export { useAi11yContext } from "./hooks/useAi11yContext.js";
+export { useChat } from "./hooks/useChat.js";

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "NodeNext",
+		"moduleResolution": "nodenext",
+		"lib": ["ES2022", "DOM", "DOM.Iterable"],
+		"jsx": "react-jsx",
+		"declaration": true,
+		"declarationMap": true,
+		"sourceMap": true,
+		"outDir": "dist",
+		"rootDir": "src",
+		"strict": true,
+		"esModuleInterop": true,
+		"skipLibCheck": true,
+		"forceConsistentCasingInFileNames": true,
+		"noImplicitReturns": true,
+		"noUnusedLocals": false
+	},
+	"include": ["src/**/*"],
+	"exclude": ["node_modules", "dist"]
+}

package/tsdown.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from "tsdown";
+
+export default defineConfig({
+	entry: ["src/index.ts"],
+	unbundle: true,
+	format: ["esm"],
+	dts: true,
+	clean: true,
+	outDir: "dist",
+	external: [
+		"react",
+		"react-dom",
+		"react/jsx-runtime",
+		"@ai11y/ui",
+		"@ai11y/core",
+	],
+});