> ## Documentation Index
> Fetch the complete documentation index at: https://docs.viamoss.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Overview

> How the Moss SDK works and what it provides

# SDK Overview

The Moss SDK embeds an AI-powered assistant into your web application. It captures page context, communicates with the Moss backend, and renders an interactive assistant UI — all without affecting your existing styles or layout.

## How It Works

When a user asks a question, the SDK:

1. **Captures page context** — DOM structure, visible text, and an optional screenshot
2. **Sends it to the Moss backend** — along with the user's message and conversation history
3. **Receives AI-generated guidance** — which may include text responses or step-by-step instructions
4. **Renders the response** — in a chat modal with optional element highlighting and coach marks

The entire UI renders inside a [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM), so Moss styles never conflict with your application's CSS.

## Integration Methods

The SDK supports two integration methods:

| Method             | Best For            | Install                         |
| ------------------ | ------------------- | ------------------------------- |
| **NPM Package**    | React applications  | `npm install @viamoss/moss-sdk` |
| **CDN Script Tag** | Any web application | `<script src="...">`            |

Both methods provide the same assistant UI and functionality. Choose based on your tech stack.

## What Gets Captured

When the assistant needs context about the current page, the SDK captures:

* **Interactive elements** (buttons, links, form fields) with their visible text labels and states
* **A screenshot** of the page (configurable: full page or viewport only)
* **Page URL and metadata**

### What Is Not Captured

The SDK does **not** access or transmit:

* **Cookies** — the SDK never reads `document.cookie`
* **localStorage or sessionStorage** — only its own `moss`-prefixed keys are used; your application's storage is not read
* **Password field values** — `<input type="password">` values are excluded
* **Hidden elements** — elements with `display: none`, `visibility: hidden`, or the `inert` attribute are filtered out
* **Non-interactive content** — general page text (paragraphs, headings, divs) is not included in the structured context sent to the backend
* **Closed Shadow DOM content** — elements inside closed shadow roots are inaccessible to the SDK
* **Cross-origin iframe content** — iframes from different origins are opaque per browser same-origin policy

<Info>
  All data is sent over HTTPS REST endpoints to your configured Moss backend. No WebSocket connections are used.
</Info>

### What Is Stored in the Browser

The SDK keeps a small amount of its own state in browser storage so a conversation survives navigation and reloads. Everything it writes lives under `moss`-prefixed keys:

| Storage          | What it holds                                                                                                                                                    | Lifetime                    |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| `sessionStorage` | Chat history for the current tab, chat open/closed and modal position state                                                                                      | Cleared when the tab closes |
| `localStorage`   | Session-continuity state (active session ID, session metadata and recent session list, pending guide-resume markers) and completion markers for onboarding flows | Persists until cleared      |

Captured page context and screenshots are never written to browser storage — they are sent to the backend and held only in memory on the client.

## Element Highlighting and Coach Marks

When the AI provides step-by-step guidance, the SDK can visually highlight elements on the host page to show users exactly where to click or interact.

**How it works:**

* The SDK applies a CSS class directly to target elements in the host DOM, adding a pulsing outline to draw attention
* When multiple elements are highlighted, numbered badges (1, 2, 3...) appear next to each element, matching the numbered steps in the assistant's instructions
* Badges are positioned using fixed viewport coordinates and automatically reposition on scroll or resize
* Highlights are cleared when the user moves to the next step or dismisses the assistant

**Coach marks** are small contextual tooltips that appear near UI elements to provide additional guidance. They auto-dismiss on external click and are session-scoped (shown once per session).

Highlighting does not modify the host DOM structure — it only adds and removes CSS classes and lightweight badge elements.

## Next Steps

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/en/sdk/installation">
    Install the SDK via NPM or CDN
  </Card>

  <Card title="Authentication" icon="lock" href="/en/sdk/authentication">
    Set up JWT authentication
  </Card>
</CardGroup>