Frontend Integration

Diosc provides web components that work with any JavaScript framework. This section covers framework-specific integration patterns and common challenges.

Installation

NPM (Recommended for Production)

npm install @diosc-ai/client

CDN (Quick Start)

<script type="module" src="https://unpkg.com/@diosc-ai/assistant-kit@latest/dist/assistant-kit/assistant-kit.esm.js"></script>

Available Components

Component	Description	Use Case
<diosc-chat>	Full chat interface	Primary chat experience with streaming, approvals, file upload, session history
<diosc-button>	AI-powered button	Quick actions (summarize, translate, analyze)
<diosc-form>	AI-enhanced form	Intelligent form processing
<diosc-file-upload>	File upload	Upload files to sessions with progress tracking
<ai-intent>	UI intent declaration	Expose UI elements as AI-invokable actions

Core API

All frameworks use the same core diosc() function:

import { loadDiosc } from '@diosc-ai/client';

const diosc = await loadDiosc({
  backendUrl: 'https://your-hub.example.com',
  apiKey: 'your-api-key'
});

// Push auth context to connect
diosc('auth', {
  headers: {
    'Authorization': `Bearer ${getAccessToken()}`
  },
  userId: getCurrentUserId()
});

// Listen to events
diosc('on', 'stream:chunk', ({ content }) => console.log('AI:', content));
diosc('on', 'session:error', ({ code, message }) => console.error(code, message));

// Send messages programmatically
diosc('invoke', 'Hello, AI!');

TypeScript Support

Types are included in the @diosc-ai/client package:

import type { DioscConfig, AuthContext, DioscEvent, EventHandler } from '@diosc-ai/client';

const config: DioscConfig = {
  backendUrl: 'https://your-hub.example.com',
  apiKey: 'your-api-key'
};

Common Integration Patterns

Authentication (BYOA)

Push auth context directly. The engine handles lifecycle transitions (login, logout, user switch, token refresh) automatically:

// Login — push auth context to connect
diosc('auth', {
  headers: {
    'Authorization': `Bearer ${token}`
  },
  userId: currentUser.id,
  tenantId: currentUser.tenantId
});

// Logout — push null to disconnect
diosc('auth', null);

// Token refresh — push new context with same userId
diosc('auth', {
  headers: {
    'Authorization': `Bearer ${newToken}`
  },
  userId: currentUser.id  // same user = token refresh, not re-login
});

Page Context (Navigation Observer)

Inform the AI about the current page using a navigation observer:

// Register an observer that fires on route changes
diosc('observe', 'navigation', (notify) => {
  notify({
    path: window.location.pathname,
    search: window.location.search,
    hash: window.location.hash
  });
});

Event Handling

// Tool execution
diosc('on', 'tool:started', ({ toolName }) => {
  showSpinner(`Executing ${toolName}...`);
});

diosc('on', 'tool:completed', ({ toolName, durationMs }) => {
  hideSpinner();
  console.log(`${toolName} completed in ${durationMs}ms`);
});

// Approval required
diosc('on', 'approval:request', ({ toolCalls }) => {
  console.log('Approval needed for:', toolCalls.map(t => t.name));
  // The <diosc-chat> component handles this automatically
});

// Session errors
diosc('on', 'session:error', ({ code, message, recoverable }) => {
  if (!recoverable) {
    showFatalError(message);
  }
});

Styling

Customize appearance with CSS variables:

diosc-chat {
  /* Colors */
  --primary-color: #0066cc;
  --background-color: #ffffff;
  --text-color: #333333;

  /* Typography */
  --font-family: 'Inter', sans-serif;

  /* Layout */
  --border-radius: 8px;
  --chat-width: 400px;
  --chat-max-height: 600px;
}

Common Challenges

Web Components in Frameworks

Web components require special handling in some frameworks:

Issue	Solution
Unknown element warnings	Configure framework to ignore diosc-* and ai-* elements
Two-way binding	Use events instead of v-model/ngModel
SSR hydration	Render only on client side

See framework-specific guides for details:

• React Integration
• Vue Integration
• Angular Integration
• Vanilla JavaScript

Server-Side Rendering (SSR)

Diosc components require browser APIs. For SSR frameworks:

// Next.js
import dynamic from 'next/dynamic';

const DioscChat = dynamic(
  () => import('@diosc-ai/client').then(mod => {
    // Initialize on client
    return () => <diosc-chat />;
  }),
  { ssr: false }
);

<!-- Nuxt -->
<client-only>
  <diosc-chat />
</client-only>

Multiple Instances

Only one diosc engine is active at a time:

// Only one config is active — second call overwrites first
diosc('config', { apiKey: 'key-1' });
diosc('config', { apiKey: 'key-2' }); // This one wins

Memory Leaks

Clean up on component unmount:

// Store listener references
const unsubscribe = diosc('on', 'stream:chunk', handleChunk);

// Clean up
onUnmount(() => {
  unsubscribe();
  diosc('auth', null); // Disconnect cleanly
});

Next Steps

Choose your framework:

• React - Hooks, context, Next.js
• Vue - Composition API, Nuxt
• Angular - Services, modules, SSR
• Vanilla JS - No framework, pure web components