@mochabug/adapt-web 1.0.0-rc21 → 1.0.0-rc23

package/README.md

@@ -0,0 +1,225 @@
+# @mochabug/adapt-web
+
+Embed Adapt automations in any website.
+
+```bash
+npm install @mochabug/adapt-web
+```
+
+## Quickstart
+
+```html
+<div id="auto" style="height:600px"></div>
+<script src="https://cdn.jsdelivr.net/npm/@mochabug/adapt-web/dist/umd/adapt-web.min.js"></script>
+<script>
+  new MbAdapt.AdaptWebClient({
+    container: 'auto',
+    id: 'your-automation-id'
+  });
+</script>
+```
+
+Done. Automation runs.
+
+## ES Modules
+
+```typescript
+import { AdaptWebClient } from '@mochabug/adapt-web';
+
+const client = new AdaptWebClient({
+  container: 'auto',
+  id: 'your-automation-id'
+});
+
+// cleanup
+await client.destroy();
+```
+
+## With auth token
+
+Only needed if the automation requires authentication:
+
+```typescript
+new AdaptWebClient({
+  container: 'auto',
+  id: 'your-automation-id',
+  authToken: 'your-token'
+});
+```
+
+## CDN versions
+
+```html
+<!-- latest -->
+<script src="https://cdn.jsdelivr.net/npm/@mochabug/adapt-web/dist/umd/adapt-web.min.js"></script>
+
+<!-- pin exact -->
+<script src="https://cdn.jsdelivr.net/npm/@mochabug/adapt-web@1.0.0/dist/umd/adapt-web.min.js"></script>
+
+<!-- pin minor -->
+<script src="https://cdn.jsdelivr.net/npm/@mochabug/adapt-web@1.0/dist/umd/adapt-web.min.js"></script>
+
+<!-- unpkg works too -->
+<script src="https://unpkg.com/@mochabug/adapt-web/dist/umd/adapt-web.min.js"></script>
+```
+
+## SSR (keep auth token server-side)
+
+Create session on server, pass session token to client:
+
+```typescript
+// server
+import { startSession } from '@mochabug/adapt-core';
+const { token } = await startSession({ id: 'auto-123' }, authToken);
+
+// client
+new AdaptWebClient({
+  container: 'auto',
+  id: 'auto-123',
+  sessionToken: token  // not authToken
+});
+```
+
+## Session inheritance
+
+Join existing session instead of starting new:
+
+```typescript
+// direct token
+new AdaptWebClient({
+  container: 'auto',
+  id: 'auto-123',
+  inheritToken: 'token-from-parent'
+});
+
+// from URL hash: example.com#mb_session=xxx
+new AdaptWebClient({
+  container: 'auto',
+  id: 'auto-123',
+  inheritFrom: { hash: 'mb_session' }
+});
+
+// from URL param: example.com?token=xxx
+new AdaptWebClient({
+  container: 'auto',
+  id: 'auto-123',
+  inheritFrom: { param: 'token' }
+});
+```
+
+## Fork display (for AI agents with UI)
+
+```typescript
+// side-by-side panels
+new AdaptWebClient({
+  container: 'auto',
+  id: 'auto-123',
+  forkDisplayMode: 'side-by-side',
+  sideBySideSplit: 60  // main 60%, fork 40%
+});
+
+// modal dialog
+new AdaptWebClient({
+  container: 'auto',
+  id: 'auto-123',
+  forkDisplayMode: 'dialog',
+  dialogBackdropClose: true
+});
+```
+
+## Callbacks
+
+```typescript
+new AdaptWebClient({
+  container: 'auto',
+  id: 'auto-123',
+  onSession: (status, fork) => console.log(status, fork),
+  onOutput: (output) => console.log(output)
+});
+```
+
+## Advanced: Multiple transmitters or initial signals
+
+For automations with multiple entry points or when you need to pass initial data:
+
+```typescript
+import { AdaptWebClient, type SignalDataJson } from '@mochabug/adapt-web';
+
+// Start from a specific transmitter
+new AdaptWebClient({
+  container: 'auto',
+  id: 'auto-123',
+  authToken: 'your-token',
+  transmitter: 'my-transmitter'
+});
+
+// Start with initial signals (data must be base64 encoded)
+const signals: { [key: string]: SignalDataJson } = {
+  'input': {
+    mimeType: 'text/plain',
+    data: btoa('Hello World')
+  },
+  'file': {
+    mimeType: 'application/pdf',
+    filename: 'document.pdf',
+    data: base64FileContent
+  }
+};
+
+new AdaptWebClient({
+  container: 'auto',
+  id: 'auto-123',
+  authToken: 'your-token',
+  transmitter: 'file-processor',
+  signals
+});
+```
+
+## All options
+
+```typescript
+{
+  container: string;           // required - DOM element id
+  id: string;                  // required - automation id
+
+  // auth (pick one)
+  authToken?: string;          // starts new session
+  sessionToken?: string;       // uses pre-created session (SSR)
+  inheritToken?: string;       // joins existing session
+  inheritFrom?: { hash: string } | { param: string };
+
+  // advanced start options
+  transmitter?: string;        // specific transmitter to start from
+  signals?: { [key: string]: SignalDataJson };  // initial signals
+
+  // fork display
+  forkDisplayMode?: 'side-by-side' | 'dialog';
+  sideBySideSplit?: number;    // 0-100, default 50
+  dialogBackdropClose?: boolean;
+
+  // callbacks
+  onSession?: (status, fork?) => void;
+  onOutput?: (output) => void;
+
+  // styling
+  classNames?: { root?, wrapper?, frame?, iframe?, dialog?, ... };
+  styles?: CSSStyleDeclaration;
+}
+```
+
+## CSS variables
+
+```css
+.mb-adapt {
+  --mb-adapt-border-radius: 8px;
+  --mb-adapt-backdrop-color: rgba(0,0,0,0.5);
+  --mb-adapt-dialog-width: 80%;
+  --mb-adapt-dialog-height: 80%;
+  --mb-adapt-drag-handle-width: 6px;
+  --mb-adapt-drag-handle-color: #d1d5db;
+}
+```
+
+## License
+
+ISC © mochabug AB