{"_id":"@aaep/web-subscriber-react","_rev":"2-498d6517b6c601f70cb413edca442c2b","name":"@aaep/web-subscriber-react","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@aaep/web-subscriber-react","version":"1.0.0","keywords":["aaep","accessibility","react","screen-reader","aria-live","a11y","subscriber","agent"],"author":{"name":"Abdulrafiu Izuafa","email":"Abdulrafiu@izusoft.tech"},"license":"MIT","_id":"@aaep/web-subscriber-react@1.0.0","maintainers":[{"name":"abdulrafiu","email":"izuafa123abdulrafiu@gmail.com"}],"homepage":"https://aaep-protocol.org","bugs":{"url":"https://github.com/Ramseyxlil/aaep/issues"},"dist":{"shasum":"66344837c840ec5f531910f6ebb365628f3d9675","tarball":"https://registry.npmjs.org/@aaep/web-subscriber-react/-/web-subscriber-react-1.0.0.tgz","fileCount":23,"integrity":"sha512-06xvHqNLJsrqWFOQddcU+ywNKZTTBDAUpdxLjji8nnzdQHkyyGQ4YzMpJPADxg7HQc6U98ivcN5U4I4c5akTtQ==","signatures":[{"sig":"MEUCIQCWGd2r7rFypJAUyWKuBdOLN5kJelaZ5J+YWUeGtB7vgQIgMnBa0j0M9S2/RnpfnHCpLUZ6ppdhAqpQ3W7jY2u+g9M=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":81917},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.mjs","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.cjs"},"./styles.css":"./dist/styles.css"},"gitHead":"64c5f934bb1c5a774a95f92d438379620b8aa233","scripts":{"dev":"vite","lint":"tsc --noEmit && eslint src --ext ts,tsx","test":"vitest","build":"tsc && vite build","preview":"vite preview"},"_npmUser":{"name":"abdulrafiu","email":"izuafa123abdulrafiu@gmail.com"},"repository":{"url":"git+https://github.com/Ramseyxlil/aaep.git","type":"git","directory":"examples/subscribers/web-subscriber-react"},"_npmVersion":"11.6.2","description":"React component that subscribes to AAEP producers and integrates with browser ARIA live regions for screen reader accessibility","directories":{},"_nodeVersion":"24.13.0","_hasShrinkwrap":false,"devDependencies":{"vite":"^8.0.16","jsdom":"^29.1.1","vitest":"^4.1.8","typescript":"^6.0.3","@types/react":"^19.2.16","@types/react-dom":"^19.2.3","@vitejs/plugin-react":"^6.0.2","@testing-library/react":"^16.3.2"},"peerDependencies":{"react":"^18.0.0 || ^19.0.0","react-dom":"^18.0.0 || ^19.0.0"},"_npmOperationalInternal":{"tmp":"tmp/web-subscriber-react_1.0.0_1780395699636_0.2742318337905034","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@aaep/web-subscriber-react","version":"1.0.1","description":"React component that subscribes to AAEP producers and integrates with browser ARIA live regions for screen reader accessibility","license":"MIT","author":{"name":"Abdulrafiu Izuafa","email":"Abdulrafiu@izusoft.tech"},"homepage":"https://aaep-protocol.org","repository":{"type":"git","url":"git+https://github.com/Ramseyxlil/aaep.git","directory":"examples/subscribers/web-subscriber-react"},"bugs":{"url":"https://github.com/Ramseyxlil/aaep/issues"},"keywords":["aaep","accessibility","react","screen-reader","aria-live","a11y","subscriber","agent"],"type":"module","main":"./dist/index.cjs","module":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.cjs"},"./styles.css":"./dist/styles.css"},"scripts":{"build":"tsc","dev":"vite","test":"vitest","lint":"tsc --noEmit && eslint src --ext ts,tsx","preview":"vite preview"},"peerDependencies":{"react":"^18.0.0 || ^19.0.0","react-dom":"^18.0.0 || ^19.0.0"},"devDependencies":{"@types/react":"^19.2.16","@types/react-dom":"^19.2.3","@vitejs/plugin-react":"^6.0.2","typescript":"^6.0.3","vite":"^8.0.16","vitest":"^4.1.8","@testing-library/react":"^16.3.2","jsdom":"^29.1.1"},"engines":{"node":">=18.0.0"},"gitHead":"64c5f934bb1c5a774a95f92d438379620b8aa233","_id":"@aaep/web-subscriber-react@1.0.1","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-XyzqIH/26ptVxAToKv0c36JO61hjDyq76jgPMsJUt03YAoxeB1TqEy8Oco5luBFMeWcqYgX0vZVamDckQfvV/Q==","shasum":"634b0edb982ae63e1646404c67404e4fd21acf88","tarball":"https://registry.npmjs.org/@aaep/web-subscriber-react/-/web-subscriber-react-1.0.1.tgz","fileCount":23,"unpackedSize":81944,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDnXdxaJO0A1ByiyTTinRdllbEwXs5vUNI+lA0JO63yvAIhAMjjO10kquYHCVIeYhsYQgiJn0mWSLCujhF5Y+K+SIg1"}]},"_npmUser":{"name":"abdulrafiu","email":"izuafa123abdulrafiu@gmail.com"},"directories":{},"maintainers":[{"name":"abdulrafiu","email":"izuafa123abdulrafiu@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/web-subscriber-react_1.0.1_1780396055126_0.6579423360302916"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-02T10:21:39.439Z","modified":"2026-06-02T10:27:35.363Z","1.0.0":"2026-06-02T10:21:39.783Z","1.0.1":"2026-06-02T10:27:35.257Z"},"bugs":{"url":"https://github.com/Ramseyxlil/aaep/issues"},"author":{"name":"Abdulrafiu Izuafa","email":"Abdulrafiu@izusoft.tech"},"license":"MIT","homepage":"https://aaep-protocol.org","keywords":["aaep","accessibility","react","screen-reader","aria-live","a11y","subscriber","agent"],"repository":{"type":"git","url":"git+https://github.com/Ramseyxlil/aaep.git","directory":"examples/subscribers/web-subscriber-react"},"description":"React component that subscribes to AAEP producers and integrates with browser ARIA live regions for screen reader accessibility","maintainers":[{"name":"abdulrafiu","email":"izuafa123abdulrafiu@gmail.com"}],"readme":"# AAEP Web Subscriber (React)\n\nA reference React component that subscribes to AAEP producers and integrates with the browser's accessibility tree via ARIA live regions. Designed for web applications that embed AI agents and need to expose agent activity to assistive technology running in the browser (screen readers like NVDA-in-Firefox, JAWS, VoiceOver, TalkBack).\n\nThis is the second reference subscriber, after the [NVDA add-on prototype](../nvda-addon-prototype/). Where that one integrates with native screen readers, this one works in any web browser without additional software installation.\n\n---\n\n## What this subscriber does\n\nWhen dropped into a React application, the component:\n\n1. **Connects to an AAEP producer's `/events` SSE endpoint** via the browser's `EventSource` API\n2. **Announces events through ARIA live regions** that screen readers automatically read aloud\n3. **Renders a visible event log** (optional, for sighted observers and debugging)\n4. **Handles confirmations and clarifications** with accessible button interfaces\n5. **Sends replies back to the producer** via the standard `/messages` endpoint\n6. **Selects appropriate ARIA priority** (`polite` for normal events, `assertive` for critical)\n\nThe component is keyboard-accessible, screen-reader-friendly, and works in any modern browser without dependencies beyond React.\n\n---\n\n## Why a web subscriber?\n\nNative screen reader integration (the NVDA add-on, future JAWS/VoiceOver/Narrator bridges) is the long-term goal for end users. But there are situations where a web subscriber is more practical:\n\n- **Web applications that embed AI agents.** When the agent runs in a web app, having a built-in AT-friendly UI lets blind users use the app without separately installing AT-specific add-ons.\n- **Accessibility testing and demos.** Web developers can verify their agents emit useful AAEP events by running this subscriber in their browser and inspecting the announcements.\n- **Education and onboarding.** New developers can experience how AAEP feels from the AT user's perspective without setting up a screen reader.\n- **Quick deployment.** No add-on installation, no system-level setup. Visit a URL, see the subscriber working.\n\nThis subscriber is complementary to native AT integrations, not a replacement.\n\n---\n\n## Installation\n\n```bash\ncd examples/subscribers/web-subscriber-react\nnpm install\nnpm run build\n```\n\nRequires Node.js 18+ and npm 9+.\n\nThe build produces a UMD bundle in `dist/` plus TypeScript definitions. Importable in any React 18+ application:\n\n```bash\nnpm install @aaep/web-subscriber-react\n```\n\n---\n\n## Quick start\n\n```tsx\nimport { AAEPSubscriber } from \"@aaep/web-subscriber-react\";\n\nfunction MyApp() {\n  return (\n    <div>\n      <h1>My AI Assistant</h1>\n\n      <AAEPSubscriber\n        endpoint=\"http://localhost:8080\"\n        preferredLanguages={[\"en\"]}\n        showEventLog={true}\n        onConnectionStatus={(status) => console.log(\"AAEP:\", status)}\n      />\n\n      {/* The rest of your app */}\n    </div>\n  );\n}\n```\n\nOnce mounted, the component connects to the producer at the given endpoint and starts announcing events. Screen reader users hear the agent's activity in real time.\n\n---\n\n## Props\n\n| Prop | Type | Default | Description |\n|---|---|---|---|\n| `endpoint` | `string` | (required) | AAEP producer base URL |\n| `preferredLanguages` | `string[]` | `[\"en\"]` | Language preference order |\n| `showEventLog` | `boolean` | `false` | Render a visible event log alongside the live regions |\n| `maxLogEntries` | `number` | `50` | Maximum events to keep in the visible log |\n| `autoStart` | `boolean` | `true` | Connect immediately on mount |\n| `onConnectionStatus` | `(status: string) => void` | `undefined` | Callback for connection state changes |\n| `onEvent` | `(event: AAEPEvent) => void` | `undefined` | Callback fired for every received event |\n| `theme` | `\"light\" \\| \"dark\" \\| \"auto\"` | `\"auto\"` | Visual theme for the event log |\n| `replyTimeout` | `number` | `30000` | ms before showing timeout warning |\n\n---\n\n## How ARIA integration works\n\nThe component renders two `<div role=\"status\" aria-live=\"...\" aria-atomic=\"true\">` elements:\n\n```html\n<div role=\"status\" aria-live=\"polite\" aria-atomic=\"true\" id=\"aaep-polite\">\n  <!-- Normal-urgency events announced here -->\n</div>\n\n<div role=\"status\" aria-live=\"assertive\" aria-atomic=\"true\" id=\"aaep-assertive\">\n  <!-- Critical-urgency events (confirmations, errors, handoffs) -->\n</div>\n```\n\nWhen the component receives an AAEP event, it updates the appropriate live region. Screen readers detect the change and read the new content aloud.\n\n- **`aria-live=\"polite\"`** — screen reader waits until current speech finishes, then announces\n- **`aria-live=\"assertive\"`** — screen reader interrupts current speech to announce immediately\n- **`aria-atomic=\"true\"`** — the entire region content is read, not just the changed portion\n\nThis is the standard W3C ARIA live region pattern, supported by every modern screen reader.\n\n---\n\n## Confirmation flow\n\nWhen an `awaiting.confirmation` event arrives, the component:\n\n1. Announces the action via the `assertive` live region\n2. Renders an inline confirmation UI:\n   ```\n   ┌───────────────────────────────────────────┐\n   │ Confirm: Send email to alice@example.com  │\n   │ This action cannot be easily undone.      │\n   │                                             │\n   │ [Accept (A)]  [Reject (R)]                 │\n   │                                             │\n   │ Auto-rejects in 4:58                       │\n   └───────────────────────────────────────────┘\n   ```\n3. Sets keyboard focus to the Accept button (with focus trap until the user responds)\n4. Listens for `A` or `R` key presses as shortcuts\n5. POSTs the user's decision to `/messages`\n6. Removes the UI and resumes normal event flow\n\nThe Accept and Reject buttons are real `<button>` elements with proper `aria-label` and `aria-describedby` attributes, so screen reader users navigate them naturally.\n\n---\n\n## Multilingual support\n\nThe component reads the event's `language` field and selects the best available translation per `preferredLanguages` prop. When the [Multilingual African Languages extension](../../extensions/multilingual-african-languages/) is configured on the producer side, this component renders Yoruba, Hausa, or Igbo summaries directly.\n\n```tsx\n<AAEPSubscriber\n  endpoint=\"http://localhost:8080\"\n  preferredLanguages={[\"yo\", \"en\"]}  // Prefer Yoruba, fall back to English\n/>\n```\n\nFor events emitted in English, the component does not attempt translation in the browser (translation tables live on the producer side; the component just renders what the producer emits).\n\n---\n\n## Project layout\n\n```\nweb-subscriber-react/\n├── README.md\n├── package.json\n├── tsconfig.json\n├── src/\n│   ├── index.ts                 # Public API exports\n│   ├── AAEPSubscriber.tsx       # The React component\n│   ├── useAAEPEvents.ts          # Hook for SSE consumption\n│   ├── types.ts                 # AAEP event type definitions\n│   └── styles.css               # Default styles\n├── public/\n│   └── demo.html                # Self-contained demo page\n└── tests/\n    └── AAEPSubscriber.test.tsx\n```\n\n---\n\n## Production readiness\n\nThis prototype is functional but has known limitations:\n\n- **No authentication.** Producers exposing /events must trust the requesting origin. Add CSRF tokens or signed URLs before production deployment.\n- **No reconnection backoff configuration.** The component reconnects on disconnect but doesn't expose tuning knobs yet.\n- **Limited mobile testing.** Tested on desktop browsers; mobile screen readers (TalkBack, VoiceOver iOS) may behave slightly differently.\n- **No event filtering UI.** All events are announced; future versions will expose filters.\n- **Bundle size.** ~24KB minified+gzipped; acceptable for most apps but could be smaller.\n\nFor production use, fork this component and adapt to your specific authentication, theming, and accessibility audit requirements.\n\n---\n\n## Browser compatibility\n\nTested with:\n\n- Chrome 120+ with built-in screen reader\n- Firefox 120+ with NVDA\n- Safari 17+ with VoiceOver (macOS and iOS)\n- Edge 120+ with Narrator\n\nOlder browsers may work but aren't validated.\n\n---\n\n## See also\n\n- [W3C ARIA Live Regions specification](https://www.w3.org/TR/wai-aria-1.2/#live_region_roles)\n- [`../nvda-addon-prototype/`](../nvda-addon-prototype/) — native Windows screen reader integration\n- [`../narrator-bridge-prototype/`](../narrator-bridge-prototype/) — Windows Narrator sibling\n- [Subscribers Guide](../../../guides/SUBSCRIBERS_GUIDE.md)\n","readmeFilename":"README.md"}