@miso.ai/client-sdk-ui 1.13.0-beta.0 → 1.13.0-beta.2

package/dist/cjs/actor/tracker.js

@@ -68,6 +68,12 @@ class Tracker {
       value
     });
   }
+  heartbeat() {
+    this._syncSession();
+    this._sendToHub({
+      type: _constants.EVENT_TYPE.HEARTBEAT
+    });
+  }
   _sendToHub(args) {
     this._hub.trigger(fields.tracker(), Object.freeze((0, _commons.trimObj)(Object.assign({
       role: this._role

package/dist/cjs/constants.js

@@ -52,9 +52,10 @@ const EVENT_TYPE = exports.EVENT_TYPE = Object.freeze({
   VIEWABLE: 'viewable',
   CLICK: 'click',
   SUBMIT: 'submit',
-  FEEDBACK: 'feedback'
+  FEEDBACK: 'feedback',
+  HEARTBEAT: 'heartbeat'
 });
-const TRACKING_EVENT_TYPES = exports.TRACKING_EVENT_TYPES = [EVENT_TYPE.IMPRESSION, EVENT_TYPE.VIEWABLE, EVENT_TYPE.CLICK, EVENT_TYPE.SUBMIT, EVENT_TYPE.FEEDBACK];
+const TRACKING_EVENT_TYPES = exports.TRACKING_EVENT_TYPES = [EVENT_TYPE.IMPRESSION, EVENT_TYPE.VIEWABLE, EVENT_TYPE.CLICK, EVENT_TYPE.SUBMIT, EVENT_TYPE.FEEDBACK, EVENT_TYPE.HEARTBEAT];
 const PERFORMANCE_EVENT_TYPES = exports.PERFORMANCE_EVENT_TYPES = [EVENT_TYPE.IMPRESSION, EVENT_TYPE.VIEWABLE, EVENT_TYPE.CLICK];
 const PERFORMANCE_EVENT_TYPE_SET = new Set(PERFORMANCE_EVENT_TYPES);
 function isPerformanceEventType(type) {

package/dist/cjs/version.js

@@ -4,4 +4,4 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.default = void 0;
-var _default = exports.default = '1.13.0-beta.0';
+var _default = exports.default = '1.13.0-beta.2';

package/dist/cjs/workflow/base.js

@@ -57,6 +57,9 @@ class Workflow extends _commons.Component {
       onEmit: event => this._onHubEmit(event)
     });
     this._sessionContext = new WeakMap();
+    this._pluginContext = {
+      processInteractionPasses: []
+    };
     client._events.emit('workflow', this);
     this._initProperties(args);
     this._initActors(args);
@@ -298,6 +301,9 @@ class Workflow extends _commons.Component {
   _buildInteraction(args) {
     let payload = (0, _processors.buildBaseInteraction)(args);
     payload = this._defaultProcessInteraction(payload, args);
+    for (const p of this._pluginContext.processInteractionPasses) {
+      payload = p(payload, args);
+    }
     const {
       preprocess = []
     } = this._options.resolved.interactions;

package/dist/cjs/workflow/options/auto-query.js

@@ -41,17 +41,21 @@ function autoQuery(options = {}) {
   const searchParams = new URLSearchParams(window.location.search);
   const q = searchParams.get(param);
   const qs = searchParams.get(sourceParam) || undefined;
-  for (const view of this._views.getAll(_constants.ROLE.QUERY)) {
-    const {
-      layout
-    } = view;
-    if (q && setValue) {
-      layout.value = q;
-    }
-    if (!q && focus) {
-      layout.focus();
+
+  // because it's probably not there yet, but this is an ad-hoc solution
+  setTimeout(() => {
+    for (const view of this._views.getAll(_constants.ROLE.QUERY)) {
+      const {
+        layout
+      } = view;
+      if (q && setValue) {
+        layout.value = q;
+      }
+      if (!q && focus) {
+        layout.focus();
+      }
     }
-  }
+  });
   if (q) {
     this.query((0, _commons.trimObj)({
       q,

package/dist/cjs/workflow/processors.js

@@ -429,6 +429,10 @@ function buildBaseInteraction(args) {
       payload.context.custom_context.value = payload.value = args.value;
       payload.context.custom_context.result_type = payload.result_type = args.result_type;
       break;
+    case _constants.EVENT_TYPE.HEARTBEAT:
+      payload.type = 'custom';
+      payload.custom_action_name = 'heartbeat';
+      break;
   }
   return (0, _commons.trimObj)(payload);
 }

package/package.json

@@ -26,7 +26,7 @@
     "url": "https://github.com/MisoAI/miso-client-js-sdk/issues"
   },
   "dependencies": {
-    "@miso.ai/commons": "1.13.0-beta.0"
+    "@miso.ai/commons": "1.13.0-beta.2"
   },
-  "version": "1.13.0-beta.0"
+  "version": "1.13.0-beta.2"
 }

package/src/CLAUDE.md

@@ -0,0 +1,134 @@
+# Client SDK UI
+
+The UI package (`std:ui` plugin) provides the presentation layer for Miso SDK, including custom elements, workflows, and rendering infrastructure.
+
+## Architecture Overview
+
+// TODO: wrong concept
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         UiPlugin                                │
+│  - Registered as 'std:ui'                                       │
+│  - Injects client.ui on each MisoClient instance                │
+│  - Manages layouts, combo, and extensions                       │
+└─────────────────────────────────────────────────────────────────┘
+                                │
+          ┌─────────────────────┼─────────────────────┐
+          ▼                     ▼                     ▼
+   ┌─────────────┐      ┌─────────────┐      ┌─────────────┐
+   │  Workflows  │      │  Elements   │      │   Layouts   │
+   │             │◄────►│             │◄────►│             │
+   │  (Logic)    │      │ (Custom El) │      │ (Rendering) │
+   └─────────────┘      └─────────────┘      └─────────────┘
+          │
+          ▼
+   ┌─────────────┐
+   │   Actors    │
+   │  (Hub I/O)  │
+   └─────────────┘
+```
+
+## Core Directories
+
+// TODO: wrong concept
+
+| Directory | Purpose |
+|-----------|---------|
+| `workflow/` | Orchestration logic for features (Ask, Search, Explore, etc.) |
+| `element/` | Custom HTML elements (`<miso-*>` tags) |
+| `actor/` | Hub-connected actors for data, views, tracking, interactions |
+| `layout/` | Rendering templates for different UI roles |
+| `combo/` | Pre-built composite UI configurations (deprecated) |
+| `trait/` | Reusable behavior mixins |
+| `defaults/` | Default configurations |
+
+## Key Concepts
+
+### Workflows (`workflow/`)
+
+// TODO: wrong concept
+
+State machines that orchestrate API calls and UI updates. Each workflow manages:
+- Session lifecycle (restart, query, response)
+- Data flow via Hub
+- View state synchronization
+- Interaction tracking
+
+**Available workflows**: `Ask`, `Search`, `HybridSearch`, `Explore`, `Recommendation`
+
+### Elements (`element/`)
+
+Web Components following the `<miso-*>` naming convention:
+
+- **Containers**: Top-level elements that own a workflow
+  - `<miso-ask>`, `<miso-search>`, `<miso-explore>`, `<miso-recommendation>`, `<miso-hybrid-search>`
+
+- **Roles**: Child elements bound to specific data roles
+  - Query: `<miso-query>`
+  - Results: `<miso-answer>`, `<miso-sources>`, `<miso-products>`, `<miso-results>`
+  - Navigation: `<miso-follow-up-questions>`, `<miso-related-questions>`
+  - Utility: `<miso-feedback>`, `<miso-error>`, `<miso-facets>`, `<miso-total>`
+
+- **Combos**: Pre-configured composite elements (deprecated)
+  - `<miso-ask-combo>`
+
+### Actors (`actor/`)
+
+Components that subscribe to and publish on the Hub:
+- `DataActor` - Fetches data from API based on requests
+- `ViewsActor` - Manages view state for each role
+- `TrackersActor` - Handles impression/click/viewable tracking
+- `InteractionsActor` - Sends interaction events to API
+- `SessionMaker` - Manages session lifecycle
+
+### Hub
+
+Central pub/sub state manager connecting workflows and actors. Fields include:
+- `session` - Current session object
+- `request` - API request parameters
+- `data` - Response data
+- `view(role)` - View state per role
+- `tracker(role, event)` - Tracking state
+
+### Layouts (`layout/`)
+
+Rendering strategies for each role. Registered via `plugin.layouts.register()`.
+
+Types: `input`, `list`, `text`, `container`, `error`, `button`, etc.
+
+### Roles & Status
+
+**Roles** (from `constants.js`): Define what data a view displays
+- Content: `answer`, `question`, `sources`, `products`, `results`
+- Navigation: `follow_up_questions`, `related_questions`, `query_suggestions`
+- Meta: `feedback`, `error`, `total`, `facets`
+
+**Status**: Workflow/view lifecycle states
+- `initial` → `loading` → `ready` / `erroneous`
+- `ongoing` (streaming) → `done`
+
+## Entry Point
+
+```javascript
+// plugin.js exports UiPlugin
+// Installed automatically with full SDK, or manually:
+MisoClient.plugins.use('std:ui');
+
+// Access via client instance:
+const client = new MisoClient({ apiKey });
+client.ui.ask;           // Ask workflow
+client.ui.search;        // Search workflow
+client.ui.recommendations; // Recommendations
+```
+
+## Event Flow
+
+1. User interacts with `<miso-query>` element (ask, hybrid-search, search, etc.), or start by calling `start()` on the workflow instance (explore, recommendations).
+2. Container element triggers workflow request
+3. Workflow publishes request to Hub
+4. `DataActor` fetches from API, publishes response
+5. `ViewsActor` updates view states per role
+6. Layout renders updated content in elements
+7. `TrackersActor` observes visibility, triggers interactions
+8. `InteractionsActor` sends tracking data to API

package/src/actor/tracker.js

@@ -63,6 +63,13 @@ export default class Tracker {
     });
   }
 
+  heartbeat() {
+    this._syncSession();
+    this._sendToHub({
+      type: EVENT_TYPE.HEARTBEAT,
+    });
+  }
+
   _sendToHub(args) {
     this._hub.trigger(fields.tracker(), Object.freeze(trimObj({ role: this._role, ...args })));
   }

package/src/constants.js

@@ -71,6 +71,7 @@ export const EVENT_TYPE = Object.freeze({
   CLICK: 'click',
   SUBMIT: 'submit',
   FEEDBACK: 'feedback',
+  HEARTBEAT: 'heartbeat',
 });
 
 export const TRACKING_EVENT_TYPES = [
@@ -79,6 +80,7 @@ export const TRACKING_EVENT_TYPES = [
   EVENT_TYPE.CLICK,
   EVENT_TYPE.SUBMIT,
   EVENT_TYPE.FEEDBACK,
+  EVENT_TYPE.HEARTBEAT,
 ];
 
 export const PERFORMANCE_EVENT_TYPES = [

package/src/version.js

@@ -1 +1 @@
-export default '1.13.0-beta.0';
+export default '1.13.0-beta.2';

package/src/workflow/answer-based.js

@@ -1,4 +1,4 @@
-import { API, mergeInteractions } from '@miso.ai/commons';
+import { API } from '@miso.ai/commons';
 import Workflow from './base.js';
 import { fields, FeedbackActor } from '../actor/index.js';
 import { ROLE, STATUS, QUESTION_SOURCE } from '../constants.js';

package/src/workflow/base.js

@@ -59,6 +59,9 @@ export default class Workflow extends Component {
       onEmit: event => this._onHubEmit(event),
     });
     this._sessionContext = new WeakMap();
+    this._pluginContext = {
+      processInteractionPasses: [],
+    };
 
     client._events.emit('workflow', this);
 
@@ -286,6 +289,9 @@ export default class Workflow extends Component {
   _buildInteraction(args) {
     let payload = buildBaseInteraction(args);
     payload = this._defaultProcessInteraction(payload, args);
+    for (const p of this._pluginContext.processInteractionPasses) {
+      payload = p(payload, args);
+    }
     const { preprocess = [] } = this._options.resolved.interactions;
     for (const p of preprocess) {
       payload = p(payload, args);

package/src/workflow/options/auto-query.js

@@ -22,15 +22,18 @@ export function autoQuery(options = {}) {
   const q = searchParams.get(param);
   const qs = searchParams.get(sourceParam) || undefined;
 
-  for (const view of this._views.getAll(ROLE.QUERY)) {
-    const { layout } = view;
-    if (q && setValue) {
-      layout.value = q;
+  // because it's probably not there yet, but this is an ad-hoc solution
+  setTimeout(() => {
+    for (const view of this._views.getAll(ROLE.QUERY)) {
+      const { layout } = view;
+      if (q && setValue) {
+        layout.value = q;
+      }
+      if (!q && focus) {
+        layout.focus();
+      }
     }
-    if (!q && focus) {
-      layout.focus();
-    }
-  }
+  });
 
   if (q) {
     this.query(trimObj({ q, qs }));

package/src/workflow/processors.js

@@ -329,6 +329,10 @@ export function buildBaseInteraction(args) {
       payload.context.custom_context.value = payload.value = args.value;
       payload.context.custom_context.result_type = payload.result_type = args.result_type;
       break;
+    case EVENT_TYPE.HEARTBEAT:
+      payload.type = 'custom';
+      payload.custom_action_name = 'heartbeat';
+      break;
   }
 
   return trimObj(payload);