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 - Leveraging modern React features for building interactive UIs.
• Language: TypeScript - For type safety and improved developer experience.
• Build Tool: Vite - Configured in library mode for optimized SDK builds (ESM and UMD formats).
• Styling: Tailwind CSS v4 - Used internally; styles are encapsulated within the SDK's Shadow DOM.
• Package Manager: pnpm - 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:

   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:

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):

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):

pnpm --filter @principles-first/moss-sdk build:watch

Linting moss-sdk: To check the SDK's codebase for potential errors and style issues:

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:

   pnpm --filter @principles-first/moss-sdk build:watch

4. Run/Build Extension in Watch Mode: In another terminal, from the monorepo root:

   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:

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.

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.