# Live Chat Widget

## Objective

Let visitors ask a question from any page and get a real answer from your team.

A corner chat bubble that opens a persistent conversation between a visitor and staffed agents, with an agent-side inbox.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Build the visitor side first: a bubble, a transcript, a composer, and a clear statement of whether anyone is currently available. An agent inbox that reuses the app's existing list and detail patterns is enough for version one; do not build a full helpdesk with routing rules, tags, and SLAs before a single conversation has happened.
2. Keep the conversation attached to the visitor, not the page. Store a conversation identifier that survives navigation, reload, and moving between pages, and reattach the transcript when the widget reopens.
3. If the app already has Knowledge Base Chat or an AI Chat Assistant, put them in the same widget rather than adding a second bubble. Answer from the knowledge base first and hand off to a human when the visitor asks or the answer is not found.
4. Reuse the app's existing Rate Limiting and Notification Center rather than inventing per-widget throttles and a parallel alert channel. Anonymous visitors need a stricter limit than signed-in users.
5. Do not open the socket on every page load for every visitor. Load the bubble, and only connect when the visitor opens it, so an idle marketing page does not hold a live connection.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- The socket will drop on flaky mobile connections. Queue messages typed while it is down, show them as pending, and replay them in order once it reconnects rather than dropping them or reordering them.
- Outside staffed hours the widget must say so honestly and set an expectation for a reply, plus collect an email address. A widget that looks live at 3am and never answers is worse than no widget.
- A double-click on send, or an automatic retry after a timeout, must not post the message twice. Give each outgoing message a client-side identifier the server treats as idempotent.
- The conversation must survive a page navigation and a full reload. A visitor who clicks a link mid-question and loses the transcript will not start again.
- Anonymous visitors are the spam surface. Rate-limit by session and by address, cap message length and frequency, and make a flood cheap to shut off without taking the widget down for everyone.
- A visitor who starts anonymously and then signs in must have the conversation merged onto their account, not left orphaned under a session identifier.
- The widget must be reachable and dismissible by keyboard, and must not cover a page's primary action or a cookie banner on a small screen.
- Transcripts contain whatever a visitor types, including card numbers and passwords. Decide retention, restrict who can read a transcript back, and support deleting one on request.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] A visitor can open the widget, send a message, and see a reply without leaving the page they are on.
- [ ] The conversation persists across navigation, reload, and a return visit in the same browser.
- [ ] Messages sent while disconnected are queued and delivered in order once the connection returns.
- [ ] Duplicate sends from double-clicks or retries are rejected server-side.
- [ ] Away hours are stated explicitly and the widget collects an email address when nobody is available.
- [ ] Anonymous visitors are rate-limited and a flood can be stopped without disabling the widget entirely.
- [ ] The widget is fully operable by keyboard and never obscures the page's primary action.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.