@mochabug/adapt-angular

Angular component for Adapt.

Requires Angular 21 or newer, with a TypeScript version supported by your Angular release. The package uses partial Ivy compilation. Release tests compile a consumer app and link its bundles with Angular 21 / TypeScript 5.9 and the development Angular 22 / TypeScript 6 toolchain.

npm install @mochabug/adapt-angular

Framework requirements are declared in package.json.

Browser UI requires native Popover API support. Floating windows use the browser top layer and remain fixed in the viewport, including inside transformed, clipped, or scrolling containers. Docked panels and docked Maximize remain inside the embed. Docking, floating, splitting, and restoring preserve the loaded iframe document and its application state.

Windows use the viewport of the document containing the client. If that document is itself inside an iframe, its windows remain within that iframe.

Quickstart

import { Component } from '@angular/core';
import { AdaptAutomation } from '@mochabug/adapt-angular';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [AdaptAutomation],
  template: `
    <mb-adapt-automation [automationId]="'auto-123'" style="height: 600px;" />
  `,
})
export class AppComponent {}

With authentication:

<mb-adapt-automation [automationId]="'auto-123'" [authToken]="'your-token'" style="height: 600px;" />

With proof-of-work challenge:

<mb-adapt-automation [automationId]="'auto-123'" [requiresChallenge]="true" style="height: 600px;" />

SSR (Angular Universal / SSR)

Keep auth token on server:

import { Component, OnInit } from '@angular/core';
import { AdaptAutomation } from '@mochabug/adapt-angular';
import { startSession } from '@mochabug/adapt-core';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [AdaptAutomation],
  template: `
    @if (sessionToken) {
      <mb-adapt-automation [automationId]="'auto-123'" [sessionToken]="sessionToken" style="height: 600px;" />
    }
  `,
})
export class AppComponent implements OnInit {
  sessionToken?: string;

  async ngOnInit() {
    const authToken = await getAuthTokenFromBackend();
    const { token } = await startSession({ id: 'auto-123' }, authToken);
    this.sessionToken = token;
  }
}

Session inheritance

<!-- direct -->
<mb-adapt-automation [automationId]="'auto-123'" [inheritToken]="'token-from-parent'" />

<!-- from URL hash: example.com#mb_session=xxx -->
<mb-adapt-automation [automationId]="'auto-123'" [inheritFrom]="{ hash: 'mb_session' }" />

Fork display

<!-- side-by-side (default) -->
<mb-adapt-automation [automationId]="'auto-123'" [forkDisplay]="{ mode: 'side-by-side', split: 60 }" />

<!-- dialog -->
<mb-adapt-automation [automationId]="'auto-123'" [forkDisplay]="{ mode: 'dialog' }" />

Events

<mb-adapt-automation
  [automationId]="'auto-123'"
  (session)="onSession($event)"
  (adaptOutput)="onOutput($event)"
  (forkActive)="onForkActive($event)"
/>

onSession(event: { status: StatusJson; fork?: string }) {
  console.log(event.status, event.fork);
}

onOutput(output: Output) {
  console.log(output);
}

onForkActive(active: boolean) {
  console.log(active);
}

2. AdaptCap

Standalone proof-of-work challenge widget. Use when you manage the automation client yourself.

import { Component } from '@angular/core';
import { AdaptCap, createConnectClient } from '@mochabug/adapt-angular/cap';

@Component({
  selector: 'app-challenge',
  standalone: true,
  imports: [AdaptCap],
  template: `
    <mb-adapt-cap
      [automationId]="'YOUR_ID'"
      [client]="client"
      (solve)="onSolve($event)"
      (error)="onError($event)"
    />
  `,
})
export class ChallengeComponent {
  client = createConnectClient({ id: 'YOUR_ID' });

  onSolve(event: { token: string; expires: Date }) {
    console.log('Solved:', event.token, event.expires);
  }

  onError(error: Error) {
    console.error(error);
  }
}

Props

| Input | Type | |-------|------| | automationId | string (required) | | client | AutomationClient (required) | | workerCount | number | | i18n | CapWidgetI18n | | darkMode | boolean |

Events

| Output | Payload | |--------|---------| | solve | { token: string; expires: Date } | | error | Error |

Headless (no UI)

Use the lower-level API to create and redeem challenges yourself:

import { createChallenge, redeemChallenge, createConnectClient } from '@mochabug/adapt-angular/cap';

const client = createConnectClient({ id: 'YOUR_ID' });
const challenge = await createChallenge(client);
// ... solve with Cap.js or your own solver ...
const redeemed = await redeemChallenge(client, solutions);

Styling

There are three ways to style the Adapt component, from simplest to most advanced. All approaches can be combined.

1. theme input (recommended)

Bind an AdaptTheme object to the [theme] input. Semantic tokens are expanded into the correct CSS variables automatically:

import { Component } from '@angular/core';
import { AdaptAutomation } from '@mochabug/adapt-angular';
import type { AdaptTheme } from '@mochabug/adapt-angular';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [AdaptAutomation],
  template: `
    <mb-adapt-automation
      [automationId]="'auto-123'"
      [theme]="myTheme"
      style="height: 600px;"
    />
  `,
})
export class AppComponent {
  myTheme: AdaptTheme = {
    mode: 'light',
    primary: '#4f46e5',
    background: '#ffffff',
    surface: '#f0f4ff',
    text: '#1e293b',
    textSecondary: '#64748b',
    border: '#cbd5e1',
    font: '"Inter", sans-serif',
  };
}

AdaptTheme tokens:

| Token | Type | Effect | |---|---|---| | mode | 'light' \| 'dark' | Toggles dark-mode class and shadow/border defaults | | primary | string | Accent color — derives separator, drop-target, spinner colors | | background | string | Root background, active tab bg, status card bg | | surface | string | Panel content bg, toolbar / inactive tab bg | | text | string | Active tab text, status text, cap widget text | | textSecondary | string | Inactive tab text | | border | string | Tab/panel borders, status card border, cap border | | font | string | Font family for all panel UI and cap widget | | vars | Record<string, string> | Direct CSS variable overrides (keys without --mb-adapt- prefix) |

The vars escape hatch lets you override any individual CSS variable while still using semantic tokens for the rest:

myTheme: AdaptTheme = {
  mode: 'dark',
  primary: '#818cf8',
  background: '#0f172a',
  surface: '#1e293b',
  text: '#f1f5f9',
  border: '#334155',
  vars: {
    'floating-radius': '16px',
    'cap-border-radius': '20px',
    'border-radius': '12px',
  },
};

2. CSS custom properties

Set --mb-adapt-* variables in a global stylesheet. Add the file to your angular.json styles array:

{
  "styles": ["src/styles.css", "src/adapt-theme.css"]
}

Or import it from your root styles.css:

@import './adapt-theme.css';

Then define your overrides:

/* adapt-theme.css */

/* ── Light mode ────────────────────────────────── */
.mb-adapt {
  --mb-adapt-fork-bg:               #ffffff;
  --mb-adapt-fork-tab-bg:           #f0f4ff;
  --mb-adapt-fork-tab-active-bg:    #ffffff;
  --mb-adapt-fork-tab-color:        #1e293b;
  --mb-adapt-fork-tab-inactive-color: #64748b;
  --mb-adapt-fork-separator:        #cbd5e1;
  --mb-adapt-separator-active:      rgba(79, 70, 229, 0.5);
  --mb-adapt-font:                  "Inter", sans-serif;
}

/* ── Dark mode ─────────────────────────────────── */
.mb-adapt.mb-adapt--dark {
  --mb-adapt-fork-bg:               #0f172a;
  --mb-adapt-fork-tab-bg:           #1e293b;
  --mb-adapt-fork-tab-active-bg:    #0f172a;
  --mb-adapt-fork-tab-color:        #f1f5f9;
  --mb-adapt-fork-tab-inactive-color: #94a3b8;
  --mb-adapt-fork-separator:        #334155;
  --mb-adapt-separator-active:      rgba(129, 140, 248, 0.6);
}

3. Direct CSS on internal classes

There is no Shadow DOM -- all elements live in the light DOM, so you can target internal classes directly. Add these rules to a global stylesheet (via angular.json styles array) or use ViewEncapsulation.None on the component that hosts the automation.

Animated gradient toolbar (light and dark):

/* adapt-gradient.css */

/* Light mode — animated gradient toolbar */
.mb-adapt .mb-group-header {
  background: linear-gradient(135deg, #667eea, #764ba2, #f093fb, #667eea);
  background-size: 300% 300%;
  animation: adapt-gradient 8s ease infinite;
}
.mb-adapt .mb-group-header .mb-tab-label {
  color: #ffffff;
}
.mb-adapt .mb-group-header .mb-tab-label[data-inactive] {
  color: rgba(255, 255, 255, 0.7);
}

/* Dark mode — deeper gradient */
.mb-adapt.mb-adapt--dark .mb-group-header {
  background: linear-gradient(135deg, #1e1b4b, #4c1d95, #701a75, #1e1b4b);
  background-size: 300% 300%;
  animation: adapt-gradient 8s ease infinite;
}
.mb-adapt.mb-adapt--dark .mb-group-header .mb-tab-label {
  color: #e0e7ff;
}
.mb-adapt.mb-adapt--dark .mb-group-header .mb-tab-label[data-inactive] {
  color: rgba(224, 231, 255, 0.6);
}

@keyframes adapt-gradient {
  0%   { background-position: 0% 50%; }
  50%  { background-position: 100% 50%; }
  100% { background-position: 0% 50%; }
}

Key internal classes:

| Class | Element | |---|---| | .mb-adapt | Root container | | .mb-adapt--dark | Dark-mode modifier on root | | .mb-group-header | Toolbar / tab bar | | .mb-tab-label | Individual tab | | .mb-tab-label[data-inactive] | Inactive tab | | .mb-panel | Panel content area | | .mb-separator | Resize handle between panels |

Note: Angular's default ViewEncapsulation.Emulated scopes component styles so they cannot reach into child component DOM. To target Adapt's internal classes from a component stylesheet, set encapsulation: ViewEncapsulation.None on that component, or place the rules in a global stylesheet.

General

| Variable | Light default | Dark default | Description | |---|---|---|---| | --mb-adapt-bg | transparent | | Root & group backgrounds | | --mb-adapt-font | system-ui, -apple-system, sans-serif | | All panel UI text | | --mb-adapt-button-hover-bg | rgba(128,128,128,0.2) | rgba(128,128,128,0.3) | Close/popout/action button hover | | --mb-adapt-separator-active | rgba(59,130,246,0.5) | rgba(99,130,246,0.6) | Resize handle hover/active | | --mb-adapt-border-radius | 8px | | Iframe border radius |

Toolbar and tabs

| Variable | Light default | Dark default | Description | |---|---|---|---| | --mb-adapt-fork-bg | #ffffff | #1e1e1e | Panel content background | | --mb-adapt-fork-tab-bg | #f3f3f3 | #252526 | Toolbar / inactive tab bg | | --mb-adapt-fork-tab-active-bg | #ffffff | #1e1e1e | Active tab background | | --mb-adapt-fork-tab-color | rgb(51,51,51) | #ffffff | Active tab text | | --mb-adapt-fork-tab-inactive-color | rgba(51,51,51,0.7) | #969696 | Inactive tab text | | --mb-adapt-fork-separator | rgba(128,128,128,0.35) | rgb(68,68,68) | Tab/panel borders | | --mb-adapt-tab-radius | 0 | | Tab border-radius (use 999px for pill shape) | | --mb-adapt-tab-shadow | none | | Tab box-shadow | | --mb-adapt-tab-active-shadow | none | | Active tab box-shadow | | --mb-adapt-tab-gap | 0px | | Tab margin (spacing between tabs) | | --mb-adapt-tab-padding | 0 14px | | Tab padding | | --mb-adapt-tab-font-size | 13px | | Tab label font size | | --mb-adapt-toolbar-height | 40px | | Toolbar / tab bar height | | --mb-adapt-toolbar-padding | 0 | | Toolbar inner padding (standard CSS shorthand) | | --mb-adapt-tab-min-width | 100px | | Tab minimum width | | --mb-adapt-tab-spacing | 6px | | Gap between tab label and action buttons |

Floating panels (elevation)

| Variable | Light default | Dark default | Description | |---|---|---|---| | --mb-adapt-floating-shadow | 0 25px 50px -12px rgba(0,0,0,0.25), 0 12px 24px -8px rgba(0,0,0,0.15) | ... rgba(0,0,0,0.5), ... rgba(0,0,0,0.3) | Overlay box-shadow | | --mb-adapt-floating-border | none | 1px solid rgba(255,255,255,0.06) | Overlay border | | --mb-adapt-floating-backdrop | none | | Overlay backdrop-filter | | --mb-adapt-floating-radius | 8px | | Overlay border-radius | | --mb-adapt-status-card-shadow | 0 4px 24px rgba(0,0,0,0.08), 0 2px 8px rgba(0,0,0,0.04) | ... rgba(0,0,0,0.25), ... rgba(0,0,0,0.15) | Status card box-shadow | | --mb-adapt-drag-ghost-shadow | 0 4px 12px rgba(0,0,0,0.15) | 0 4px 12px rgba(0,0,0,0.35) | Drag ghost box-shadow |

Drop targets

| Variable | Light default | Dark default | |---|---|---| | --mb-adapt-drop-header-bg | rgba(99,102,241,0.18) | rgba(129,140,248,0.22) | | --mb-adapt-drop-center-bg | rgba(99,102,241,0.12) | rgba(129,140,248,0.15) | | --mb-adapt-drop-split-bg | rgba(99,102,241,0.14) | rgba(129,140,248,0.18) | | --mb-adapt-drop-border | rgba(99,102,241,0.55) | rgba(129,140,248,0.6) |

Status cards

| Variable | Light default | Dark default | |---|---|---| | --mb-adapt-status-card-bg | #ffffff | #1e293b | | --mb-adapt-status-card-border | #e5e7eb | #334155 | | --mb-adapt-status-icon-bg | #fef2f2 | #351c1c | | --mb-adapt-status-text | #374151 | #e2e8f0 |

Cap widget

| Variable | Light default | Dark default | |---|---|---| | --mb-adapt-cap-background | #ffffff | #1e293b | | --mb-adapt-cap-border-color | #e2e8f0 | #334155 | | --mb-adapt-cap-border-radius | 16px | | | --mb-adapt-cap-height | 72px | | | --mb-adapt-cap-width | 380px | | | --mb-adapt-cap-padding | 20px 28px | | | --mb-adapt-cap-gap | 20px | | | --mb-adapt-cap-color | #1e293b | #f1f5f9 | | --mb-adapt-cap-checkbox-size | 36px | | | --mb-adapt-cap-checkbox-border | 2px solid #cbd5e1 | 2px solid #475569 | | --mb-adapt-cap-checkbox-radius | 10px | | | --mb-adapt-cap-checkbox-background | #f8fafc | #0f172a | | --mb-adapt-cap-spinner-color | #6366f1 | #818cf8 | | --mb-adapt-cap-spinner-bg | #e2e8f0 | #334155 | | --mb-adapt-cap-spinner-thickness | 3px | | | --mb-adapt-cap-font | inherit | |

Z-index / stacking

| Variable | Default | Description | |---|---|---| | --mb-adapt-z-base | 0 | Local z-index offset and floating-window priority |

--mb-adapt-z-base offsets local stacking and sets the priority of this instance’s floating windows. Higher priorities appear above lower priorities; within the same priority, the most recently activated window appears on top across clients. Theme changes update this priority live.

Floating chrome and iframe content are ordered together in the native top layer. Drop indicators and drag ghosts appear above windows, and close confirmations appear above those. Host-page native dialogs and popovers follow browser top-layer ordering; numeric CSS z-index cannot override that ordering.

Props

| Input | Type | |-------|------| | automationId | string (required) | | sessionToken | string | | authToken | string | | transmitter | string | | signals | { [key: string]: SignalValue } | | challengeToken | string | | requiresChallenge | boolean | | capWidgetOptions | { workerCount?: number; i18n?: CapWidgetI18n } | | inheritToken | string | | inheritFrom | { hash: string } \| { param: string } | | forkDisplay | { mode: 'side-by-side', split?: number } \| { mode: 'dialog' } | | darkMode | boolean | | autoResizing | boolean | | allowFloating | boolean — hide pop-out buttons and block user-initiated floating (default true) | | allowDocking | boolean — hide dock buttons and block user-initiated docking (default true) | | allowDialogDocking | boolean — allow tab splits inside floating dialog overlays (default true) | | floatingAutoResize | boolean — floating overlays auto-resize from iframe content (default false) | | confirmOnClose | boolean — show confirmation dialog before leaving page (default false) | | persist | boolean \| PersistOptions | | text | StatusText | | theme | AdaptTheme | | classNames | { root?: string; iframe?: string; statusMessage?: string; statusCard?: string } | | styles | Partial<CSSStyleDeclaration> |

Events

| Output | Payload | |--------|---------| | session | { status: StatusJson; fork?: string } | | adaptOutput | Output | | forkActive | boolean | | contentActive | boolean — any main/fork URL remains open, including retained or minimized content |

License

ISC (c) mochabug AB