npm package: @serapion-gmbh/nova-app
Description: To integrate and render this application into your host environment, follow the steps below. This app is designed to run inside a **Shadow DOM** to encapsulate styles and prevent conflicts with the host page.
Latest version: 4.11.0

## Usage Instructions

To integrate and render this application into your host environment, follow the steps below. This app is designed to run inside a **Shadow DOM** to encapsulate styles and prevent conflicts with the host page.


### 1. Prepare a Mounting Element

Make sure your HTML contains a `<div>` element with a unique `id` that will serve as the mounting point for the application:

```html
<div id="my-app-container"></div>
```

This is the container into which the app will be rendered via Shadow DOM.

### 2. Render the App
Use the provided  `initNovaApp` function to inject the application into an open Shadow DOM on the target element. The `initNovaApp` function sets up the chat configuration and 
returns a NovaSession instance that enables interaction with the chat.

**Note:** Branding and theming are now handled automatically through the nova-js-framework's built-in branding system. The chat configuration retrieved from the session includes comprehensive branding data that controls all visual aspects of the chat interface.

```js
initNovaApp('my-app-container', {
  chatConfiguration: {
    type: 'client_chat',
    baseURL: 'http://localhost:8000',
    sessionToken: SESSION_TOKEN,
  },
  enabledContentTypes: {
    images: true,
  },
  fullscreen: true,
  filePlaceholder: 'Drop file here',
  noButton: false,
  onClose: () => console.log('Chat closed'),
  actionNameMap: {
    'search_web': 'Web Search',
    'read_file': 'File Reader'
  }
})

```

### 3. Branding System

The Nova App uses the **nova-js-framework** branding system to provide comprehensive theming capabilities. All visual customization is handled automatically through the branding configuration retrieved from your Nova session.

#### Supported Branding Features

**Font Configuration:**
- Custom font family, size, and weight
- Automatic font loading from URLs
- Fallback font handling

**Component Theming:**
- **Buttons**: Primary, secondary, destructive, and plain variants with hover/active/disabled states
- **Inputs & Textareas**: Comprehensive input styling with focus/hover states  
- **Tooltips**: Complete tooltip theming
- **Chat Elements**: User and assistant message styling, conversation starters, splash messages

**Chat-Specific Theming:**
- **Backgrounds**: Thread panel and main chat backgrounds
- **Composer**: Full composer container theming
- **Title & Disclaimer**: Header and legal text styling
- **Message Participants**: Distinct styling for user vs assistant messages

**Legal Integration:**
- Privacy policy and terms of service URL handling
- Automatic legal link generation

#### Branding Implementation

The branding system automatically applies themes using the nova-js-framework's helper functions:
- `renderColor()` - Color value rendering with CSS color space support
- `renderComponentTheme()` - Complete component styling (margins, padding, borders, shadows, backgrounds)
- `renderTextStyle()` - Typography styling (font properties, colors, decorations)
- `renderButtonTheme()` - Button-specific theming with size variants
- `renderInputTheme()` - Input field styling with state management

No manual theme configuration is required - all branding is controlled through your Nova session configuration.

---

## Development Instructions

### Setup

Before running the project locally, ensure you have [Node.js](https://nodejs.org/) (version 16 or higher is recommended) and [npm](https://www.npmjs.com/) installed on your system.

1. Install project dependencies
2. Prepare the project for development (e.g., generate TypeScript types, run prebuild scripts, etc.)
```
npm install
npm run prepare
```


### Running the Project Locally

1. Create a .env file in the root directory of the project if it doesn’t already exist
2. Set a valid session token as `VITE_CLIENT_SESSION_TOKEN` in an .env file
3. Start the development server
```
npm run dev
```

### Local Build & Installation in Another Project

To use this package in another local project (e.g., for testing or development without publishing to a registry), follow these steps:

1. Build the package
2. Pack the build into a .tgz archive
```
npm run build
npm pack
```

In the other project's root directory, run:

```
npm i ../nova-app/serapion-gmbh-nova-app-X.X.X.tgz
```