BrowsEZ Widget

Embeddable BrowsEZ chat widget for SPA clients. The first release is designed for Angular applications that install the package from the public npm registry and mount the widget once at the application root.

Distribution

Release 1 is public-npm-first. Client teams install @browsez/widget directly from npmjs.

Install:

pnpm add @browsez/widget
npm install @browsez/widget

CDN/script-tag distribution is intentionally deferred. The package still emits library builds, but the supported integration path for this release is package installation into the client app build.

Maintainer publish flow:

npm login
pnpm build
npm publish

Angular SPA Integration

Mount the widget once from the Angular app shell, such as the root component. Because the widget is root-mounted, it survives client-side route changes and only shows or hides itself based on the route rules.

import { Component, OnDestroy, OnInit } from '@angular/core';
import { embedWidget, type WidgetInstance } from '@browsez/widget';

@Component({
  selector: 'app-root',
  template: '<router-outlet />',
})
export class AppComponent implements OnInit, OnDestroy {
  private widget?: WidgetInstance;

  ngOnInit() {
    this.widget = embedWidget({
      platformApiBaseUrl: 'https://platform.example.com',
      demoAuth: {
        orgSlug: 'acme',
        username: 'demo-user',
        password: 'demo-password',
      },
      instanceId: 'inst_123',
      routes: {
        include: ['/dashboard/**', '/orders/**'],
        exclude: ['/login', '/checkout'],
      },
      history: {
        mode: 'drawer',
      },
    });
  }

  ngOnDestroy() {
    this.widget?.destroy();
  }
}

Route Rules

routes.include and routes.exclude accept simple path globs:

• * matches one path segment.
• ** matches across path segments.
• exclude wins over include.
• If include is omitted, the widget is visible by default unless excluded.

Examples:

routes: {
  include: ['/app/**'],
  exclude: ['/app/admin/**'],
}

Demo Auth

This demo release accepts static Platform credentials in the browser:

demoAuth: {
  orgSlug: 'acme',
  username: 'demo-user',
  password: 'demo-password',
}

The widget uses those credentials to sign in to the Platform, list the configured instance, and issue a playground token. Credentials, Platform sessions, and playground tokens are kept in memory only and are not written to local storage.

This is a demo-only auth contract. Production widget auth is expected to switch to a backend-mediated token exchange without changing the shared chat surface.

Lifecycle

Call destroy() when the host user logs out or when the embedding app needs to change user/workspace context. Recreate the widget with the new config after the host app has a new authenticated context.

this.widget?.destroy();
this.widget = embedWidget(nextConfig);

The widget API also supports:

widget.open();
widget.close();
widget.preload();
widget.sendMessage('Show me my orders');
widget.setInput('Help me understand this page');
widget.hide();
widget.show();

History Modes

history.mode supports three layouts:

• hidden: no thread browser is shown.
• drawer: the tray stays compact and exposes a "View threads" toggle that opens the Thesys thread sidebar.
• sidebar: keeps the Thesys thread sidebar visible whenever the widget is open.