npm package: @principles-first/moss-sdk
Description: This project provides a React component library for easily integrating AI assistant features, like contextual guidance and UI interactions, into web applications. The core of the SDK is the `AgentProvider`, which manages state and communication, and compo
Latest version: 0.0.10

# Moss SDK

This project provides a React component library for easily integrating AI assistant features, like contextual guidance and UI interactions, into web applications. The core of the SDK is the `AgentProvider`, which manages state and communication, and components like `FloatingActionBar` that provide the user interface. The SDK is designed to be lightweight, configurable, and encapsulates its UI within a Shadow DOM to prevent style conflicts.

## Tech Stack

*   **Framework:** [React 18](https://react.dev/) - Leveraging modern React features for building interactive UIs.
*   **Language:** [TypeScript](https://www.typescriptlang.org/) - For type safety and improved developer experience.
*   **Build Tool:** [Vite](https://vitejs.dev/) - Configured in library mode for optimized SDK builds (ESM and UMD formats).
*   **Styling:** [Tailwind CSS v4](https://tailwindcss.com/) - Used internally; styles are encapsulated within the SDK's Shadow DOM.
*   **Package Manager:** [pnpm](https://pnpm.io/) - For efficient dependency management in this monorepo.

## Project Structure

```
moss-sdk/
├── dist/                  # Build output directory
├── public/                # Static assets for the dev server
├── src/                   # Source code
│   ├── assets/            # Image, font, or other static files used in components
│   ├── components/        # Reusable React components (e.g., FloatingActionBar, GuidanceTooltip)
│   ├── communication/     # WebSocket communication logic (WebSocketChannel, MockWebSocketChannel)
│   ├── context/           # DOM context collection (ContextCollector)
│   ├── core/              # Core logic including AgentContext (AgentProvider, useAgent)
│   ├── highlighter/       # Element highlighting logic (Highlighter)
│   ├── instructions/      # Instruction processing (InstructionProcessor)
│   ├── mock/              # Mock data or channels for testing/development
│   ├── observer/          # DOM observation logic (DOMObserver)
│   ├── utils/             # Utility functions (Logger)
│   ├── types/             # TypeScript type definitions (MossSDKConfig, ChatMessage, Instruction, etc.)
│   ├── index.css          # SDK's internal global styles (injected into Shadow DOM)
│   ├── index.ts           # Public entry point for the library build
│   ├── App.tsx            # Root component for the dev environment (testing SDK features)
│   └── main.tsx           # Entry point for the dev environment application
├── .gitignore             # Git ignore rules
├── eslint.config.js       # ESLint configuration
├── index.html             # HTML template for the dev server
├── package.json           # Project metadata and dependencies
├── pnpm-lock.yaml         # PNPM lock file
├── README.md              # This file
├── tsconfig.app.json      # TypeScript config for the dev app
├── tsconfig.json          # Base TypeScript configuration
├── tsconfig.node.json     # TypeScript config for Node.js scripts (like vite.config.ts)
└── vite.config.ts         # Vite build configuration
```

## Development

**Prerequisites:**
*   Node.js (LTS version recommended)
*   pnpm (`npm install -g pnpm`)

**Setup:**
1.  Clone the repository.
2.  Navigate to the workspace root.
3.  Install all dependencies for the monorepo:
    ```bash
    pnpm install
    ```

**Running the Dev Server for `moss-sdk`:**
To test components and SDK features in isolation using a local Vite server and `moss-sdk/src/App.tsx`:
```bash
pnpm --filter @principles-first/moss-sdk dev
```
This provides a live preview and hot module replacement (HMR).

**Building `moss-sdk` for Production:**
To create optimized builds of the SDK for distribution (`moss-sdk/dist/` folder):
```bash
pnpm --filter @principles-first/moss-sdk build
```

**Building `moss-sdk` in Watch Mode:**
To automatically rebuild the SDK when source files change (useful for local linking or development with consuming applications like `moss-assistant-extension`):
```bash
pnpm --filter @principles-first/moss-sdk build:watch
```

**Linting `moss-sdk`:**
To check the SDK's codebase for potential errors and style issues:
```bash
pnpm --filter @principles-first/moss-sdk lint
```

### Local Development with `moss-assistant-extension`

When developing `moss-sdk` and `moss-assistant-extension` simultaneously:

1.  **Ensure Backend is Running:** If your extension or SDK communicates with a backend, make sure it's running.
2.  **Install Dependencies:** Run `pnpm install` at the monorepo root.
3.  **Build SDK in Watch Mode:** In one terminal, from the monorepo root:
    ```bash
    pnpm --filter @principles-first/moss-sdk build:watch
    ```
4.  **Run/Build Extension in Watch Mode:** In another terminal, from the monorepo root:
    ```bash
    pnpm --filter moss-assistant-extension build:watch
    ```
5.  **Load Unpacked Extension:** Load the extension's build output (e.g., `clippy-extension/dist`) into your browser. Changes in the SDK will trigger its rebuild, which in turn should be picked up by the extension's watch process, allowing you to see updates by reloading the extension.

## Installation and Usage

### 1. Installation

Install the package from the public npm registry:
```bash
npm install @principles-first/moss-sdk
# or
yarn add @principles-first/moss-sdk
```

### 2. Basic Usage

Add the `AgentProvider` to your application root, alongside your main app component.

```tsx
import React from 'react';
import { AgentProvider, FloatingActionBar, MossSDKConfig, LogLevel } from '@principles-first/moss-sdk';

const sdkConfig: MossSDKConfig = {
  apiUrl: 'http://localhost:8000', // Your backend API URL
  applicationName: 'my-cool-app',
  userId: 'user-123',
  debugMode: true,
};

function App() {
  return (
    <>
      {/* Your application */}
      <div className="MyApp">
        <h1>My Application</h1>
        <p>Welcome to the app where Moss can assist you!</p>
      </div>

      {/* Moss SDK Components */}
      <AgentProvider config={sdkConfig}>
        <FloatingActionBar />
      </AgentProvider>
    </>
  );
}
```

### 3. UI Encapsulation (Shadow DOM)

The Moss SDK, specifically the `AgentProvider`, renders its UI (including the `FloatingActionBar` and any future chat interfaces or tooltips) into a Shadow DOM. This means:
*   **Style Isolation:** The SDK's internal styles will not conflict with your application's styles, and vice-versa.
*   **Simplified Integration:** You don't need to manually import the SDK's CSS files; it's handled internally.

## Core Components & Hooks

*   **`AgentProvider`**: The main provider component that initializes the SDK, manages state, and provides context to other SDK components. It should be rendered alongside your main application.
*   **`FloatingActionBar`**: A floating action bar that contains the main assistant button. It should be rendered as a child of `AgentProvider`.
*   **`useAgent`**: A React hook that can be used by custom components (within an `AgentProvider`) to access SDK state and methods (e.g., `isConnected`, `messages`, `sendMessage`, `toggleChat`).
*   **`GuidanceTooltip`**: An internal component used to display guidance messages, typically positioned near highlighted elements.
*   **`ChatManager`**: An internal component that manages the chat modal and debug panel.

## Contributing

Contributions are welcome! Please follow these general steps:

1.  Fork the repository.
2.  Create a new branch (`git checkout -b feature/your-feature-name`).
3.  Make your changes.
4.  Ensure code is linted (e.g., `pnpm --filter @principles-first/moss-sdk lint`).
5.  Commit your changes (`git commit -m 'Add some feature'`).
6.  Push to the branch (`git push origin feature/your-feature-name`).
7.  Open a Pull Request.

Please ensure your code adheres to the project's coding standards and includes tests if applicable.

## License

This project is proprietary to Principles First. Please refer to the license information in the root of the repository.