Logikron Talk Widget - Implementation Guide

Step-by-Step Process

1. Project Structure Setup

logikron-talk-widget/
├── package.json
├── webpack.config.js
├── src/
│   ├── index.js (main entry point)
│   ├── widget.js (main widget logic)
│   ├── components/
│   │   └── VoiceStreamClient.js
│   └── styles/
│       └── widget.css
├── dist/ (built files)
└── README.md

2. Core Implementation Requirements

A. Custom Element Registration

• Create a custom HTML element <logikron-talk>
• Register it using customElements.define()
• Handle attributes like agent-id, session-id, etc.

B. Widget Functionality

• Embed the voice streaming component
• Handle WebSocket connections
• Manage modal display
• Isolate styles using Shadow DOM

C. Build Configuration

• Use Webpack to bundle everything into a single JS file
• Minimize dependencies and bundle size
• Ensure cross-browser compatibility

3. NPM Package Setup

A. Package.json Configuration

{
  "name": "@logikron/talk-widget-embed",
  "version": "1.0.0",
  "main": "dist/logikron-talk-widget.js",
  "files": ["dist/"],
  "publishConfig": {
    "access": "public"
  }
}

B. Build Process

• Webpack builds to dist/logikron-talk-widget.js
• Minified and optimized for web delivery
• Includes all necessary dependencies

4. Publishing to NPM/UNPKG

A. NPM Account Setup

1. Create NPM account at npmjs.com
2. Run npm login in terminal
3. Verify account with npm whoami

B. Publishing Process

# Build the project
npm run build

# Publish to NPM
npm publish

# UNPKG automatically mirrors NPM packages
# Your script will be available at:
# https://unpkg.com/@logikron/talk-widget-embed

C. UNPKG Access

• UNPKG automatically serves NPM packages
• No separate registration needed
• Files available at https://unpkg.com/[package-name][@version]/[file]

5. Usage Implementation

A. HTML Embed Code

<logikron-talk 
  agent-id="agent_01jztk3d2sezb97b21py8czd2f"
  session-id="optional-session-id"
  ws-url="wss://your-api.com/ws/audio/"
  agent-name="Assistant">
</logikron-talk>
<script src="https://unpkg.com/@logikron/talk-widget-embed" async></script>

B. Configuration Options

• agent-id: Required agent identifier
• session-id: Optional session identifier
• ws-url: WebSocket endpoint URL
• agent-name: Display name for the agent
• theme: Widget color theme
• position: Widget position (bottom-right, bottom-left, etc.)

6. Technical Considerations

A. Shadow DOM Isolation

• Prevents CSS conflicts with host page
• Encapsulates widget functionality
• Maintains consistent appearance

B. Performance Optimization

• Lazy loading of heavy components
• Efficient WebSocket management
• Minimal initial bundle size

C. Cross-Domain Security

• Handle CORS properly
• Secure WebSocket connections
• Validate agent IDs

7. Testing Strategy

A. Local Development

• Use webpack-dev-server for development
• Test on multiple websites
• Verify different browsers

B. Production Testing

• Test with actual UNPKG URL
• Verify on various hosting environments
• Check mobile compatibility

8. Maintenance & Updates

A. Version Management

• Use semantic versioning
• Maintain backward compatibility
• Document breaking changes

B. Monitoring

• Error tracking for widget issues
• Usage analytics
• Performance monitoring

Next Steps

1. Create the basic project structure
2. Implement the custom element
3. Port the React component to vanilla JS
4. Configure build system
5. Test locally
6. Publish to NPM
7. Verify UNPKG availability