@appilots/web-sdk 0.2.0

package/README.md

@@ -0,0 +1,216 @@
+# @appilots/web-sdk
+
+The Appilots client for web applications.
+
+It observes the page through the **DOM and its accessibility tree** —
+never through a framework's internals — so the same runtime drives a
+React, Vue, Svelte, or hand-written app without knowing which it is.
+
+The agent loop itself is not here. Turns, continuation, recovery
+counters and the confirm gate live in `@appilots/client-core` and are
+shared with the React Native SDK. This package supplies the two things
+that cannot be shared: **eyes** (`captureSnapshot`) and **hands**
+(`executeAction`), plus a navigation adapter that maps a URL onto the
+agent contract's `navigationState`.
+
+## Why DOM and ARIA, not React internals
+
+The React Native SDK reads React's Fiber tree. That is the right call
+there — RN has no DOM and Fiber is the only complete view of what is
+mounted. On the web it would be the wrong call:
+
+- **It would only ever work for React.** The point of a web client is
+  to work for any app. The DOM is the one tree every framework agrees on.
+- **Fiber is a private API.** It has no compatibility guarantee, differs
+  between development and production builds, and has changed shape
+  across React versions.
+- **The accessibility tree already answers our questions.** "What is
+  this control, what is it called, is it disabled, is it selected, is it
+  behind a modal" are exactly what ARIA encodes. An app that is
+  accessible is automatically legible to the agent, and an app that is
+  not gets a concrete reason to improve.
+
+The output shape is identical to the RN walker's (`ScreenSnapshot`), and
+the interaction-graph derivation is literally the same shared code, so
+equivalent content yields identical `el:` ids on both platforms.
+
+## Quick start (React)
+
+```tsx
+import { AppilotsWebProvider, AppilotsChatFab } from '@appilots/web-sdk/react';
+import { useNavigate } from 'react-router-dom';
+
+function Root() {
+  const navigate = useNavigate();
+  return (
+    <AppilotsWebProvider
+      projectId="proj_..."
+      apiKey="ak_..."
+      apiBaseUrl="https://your-api/api/v1"
+      routes={[
+        { name: 'VehicleList', path: '/vehicles' },
+        { name: 'VehicleDetails', path: '/vehicles/:id' },
+      ]}
+      screens={[
+        {
+          name: 'VehicleList',
+          actions: [{ id: 'delete-vehicle', label: 'Excluir veículo', requiresConfirmation: true }],
+        },
+      ]}
+      navigate={(path, options) => navigate(path, { replace: options?.replace })}
+    >
+      <App />
+      <AppilotsChatFab />
+    </AppilotsWebProvider>
+  );
+}
+```
+
+`AppilotsChatFab` adds a floating button and chat panel to your site. It starts
+closed, opens with focus in the composer, and closes with the button, the
+header close control or Escape. Closing preserves the conversation, draft,
+pending approvals and human support; it does not stop an active response.
+Use “Stop response” or “New conversation” for that.
+
+```tsx
+<AppilotsChatFab
+  locale="pt-BR"
+  title="Assistente"
+  position="bottom-right"
+  accentColor="#285b45"
+  suggestedPrompts={['O que posso fazer por aqui?']}
+/>
+```
+
+Mount it inside `AppilotsWebProvider`. The React binding requires `react` and
+`react-dom` 18 or newer. The widget renders in a portal under `document.body`
+after hydration, so host containers with `overflow` or transforms cannot clip
+it. Its entire UI is excluded from the agent's observations. No CSS import or
+application-owned open/close state is needed.
+
+`position` also accepts `bottom-left`; `defaultOpen` defaults to `false`.
+`zIndex` defaults to `1000`: keep your app's blocking dialogs above the widget,
+or lower this value to fit the site's stacking order. The panel adapts to the
+viewport and safe area. `style` customizes the chat panel, as with `AppilotsChat`.
+
+For a chat embedded in your own layout, keep using `AppilotsChat`:
+
+`AppilotsChat` includes message bubbles, timestamps, Markdown (the same subset
+as mobile), multiline input, Enter to send / Shift+Enter for a new line,
+stop response, new conversation, and inline action confirmations. It follows
+new messages while you are at the bottom and lets you return to the latest
+messages when reading older replies.
+
+```tsx
+<AppilotsChat
+  locale="pt-BR"
+  title="Assistente"
+  placeholder="Escreva uma mensagem…"
+  suggestedPrompts={['O que posso fazer por aqui?']}
+  style={{ height: 600 }}
+/>
+```
+
+`locale` supports `en` (default) and `pt-BR`. Suggestions prefill the composer;
+they never send automatically. Markdown supports headings, lists, bold, italic,
+inline/fenced code and HTTP(S) links. HTML is rendered as text.
+
+“Talk to a person” uses the existing escalation API: waiting/connected status,
+operator replies, and user messages all stay in the same transcript. The API
+and an operator in the dashboard must be available for a person to answer.
+Starting a new conversation abandons open human support. Stop and handoff
+cancel pending actions and ignore late model replies; an action already
+executing is allowed to settle.
+
+Styles are scoped and included with the component; no CSS import is required.
+For a custom surface, use `useAppilotsChat()` / `useAppilotsActions()`.
+
+Not using React? `AppilotsWebRuntime` is a plain class:
+
+```ts
+const runtime = new AppilotsWebRuntime({ projectId, apiKey, routes, screens, navigate });
+await runtime.chat.sendMessage('Cadastre um Corolla 2023');
+```
+
+## Markup conventions
+
+None of these are required — the walker falls back to `data-testid`,
+`id`, `name`, `aria-label` and the accessible name. They are how you get
+_precision_ when defaults are ambiguous.
+
+| Attribute                        | Purpose                                                                                                                                                                                                                           |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data-appilots-id`               | The agent-facing id, checked before everything else. Use it when `data-testid` is already spoken for.                                                                                                                             |
+| `data-appilots-action`           | Points a control at a **declared screen action**. Essential for list rows: each row's delete button needs a unique id to be targetable, but all of them are the same declared action and must inherit its `requiresConfirmation`. |
+| `data-appilots-skip`             | Excludes a subtree from observation entirely.                                                                                                                                                                                     |
+| `data-appilots-sensitive="true"` | Masks a field's value even if it isn't `type="password"`.                                                                                                                                                                         |
+| `data-appilots-list-id`          | Marks a list container and names it.                                                                                                                                                                                              |
+| `data-appilots-list-item`        | Marks a row.                                                                                                                                                                                                                      |
+| `data-appilots-item-key`         | A row's stable domain id.                                                                                                                                                                                                         |
+| `data-appilots-item-index`       | A row's 0-based index in the backing data (for virtualized lists).                                                                                                                                                                |
+| `data-appilots-item-count`       | Total data-set size when the DOM only holds a page of it.                                                                                                                                                                         |
+
+The SDK's own chat UI carries `data-appilots-chat`, which the walker
+treats as a skip marker — without it the agent would observe its own
+transcript and try to press its own buttons.
+
+## What the agent sees
+
+```ts
+const snapshot = captureSnapshot();
+// { route, texts, inputs, buttons, toggles, sliders, lists,
+//   choiceGroups, elements, loading, modalOpen }
+```
+
+Semantics worth knowing:
+
+- **Classification is an else-if chain**, so an element is exactly one
+  of text/input/slider/toggle/button. Sliders are checked before
+  pressables so a range track never becomes a button.
+- **List containers are not descended in the main pass.** A row's
+  content lives on that row, not flattened into the top-level arrays —
+  that association is the whole reason the shape exists.
+- **Password and marked-sensitive values never leave the page.** They
+  are replaced with `<hidden>` before the snapshot is built.
+- **A modal marks its contents `inModal`.** While one is open the
+  executor refuses to press anything behind it, because such a press
+  would silently do nothing.
+
+## Executing actions
+
+`executeAction` handles all six action types with the same
+`ActionDiagnose` categories as the RN executor, so server-side recovery
+behaves identically.
+
+The subtle one is `form_fill` against a **controlled React input**.
+Assigning `element.value` does not work: React installs its own value
+setter on the element instance and tracks the last value it wrote, so a
+direct assignment is invisible to it and the app reverts the field on
+the next render. The executor calls the _prototype's_ native setter
+(which updates React's tracker) and then dispatches a bubbling `input`
+event, which is what React's `onChange` actually listens for. The same
+sequence satisfies Vue's `v-model` and plain listeners.
+
+## Navigation
+
+`WebNavigationAdapter` maps the URL onto the contract: the path becomes
+`activePath`, the matched route becomes `currentRouteName`, and route +
+params become the signature the settle loop uses to detect a navigate to
+the same route with different params.
+
+Pass your router's `navigate` so agent-driven navigation stays
+client-side. Without one it falls back to `history.pushState` plus a
+synthetic `popstate`, which most routers observe.
+
+Route matching prefers the **most specific** pattern, so `/vehicles/new`
+resolves to `VehicleCreate` rather than `VehicleDetails` with
+`id: 'new'`.
+
+## Testing
+
+`pnpm --filter @appilots/web-sdk test` — unit tests for the walker,
+locators, executor and navigation, plus integration tests that run the
+whole loop against a mocked backend in a real DOM.
+
+`pnpm qa:web:agent` — Playwright missions against `apps/example-web-app`
+in a real browser.