@miso.ai/client-sdk-ui 1.13.2-beta.1 → 1.14.0-beta.3

package/dist/cjs/plugin.js

@@ -5,15 +5,18 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 var _commons = require("@miso.ai/commons");
-var _index = require("./workflow/index.js");
-var _index2 = require("./combo/index.js");
+var _clientSdkWorkflow = require("@miso.ai/client-sdk-workflow");
+var _defaults = require("./defaults.js");
+var _index = require("./combo/index.js");
 var _layouts = _interopRequireDefault(require("./layouts.js"));
 var elements = _interopRequireWildcard(require("./element/index.js"));
 var layouts = _interopRequireWildcard(require("./layout/index.js"));
-var sources = _interopRequireWildcard(require("./source.js"));
 var defaults = _interopRequireWildcard(require("./defaults/index.js"));
+var _templates = require("./defaults/ask/templates.js");
 var traits = _interopRequireWildcard(require("./trait/index.js"));
 var _styles = require("./styles.js");
+var _confirm = _interopRequireDefault(require("./util/confirm.js"));
+var _prompt = _interopRequireDefault(require("./util/prompt.js"));
 var _misoContainer = _interopRequireDefault(require("./element/container/miso-container.js"));
 var _misoContext = _interopRequireDefault(require("./element/context/miso-context.js"));
 var _misoCombo = _interopRequireDefault(require("./element/combo/miso-combo.js"));
@@ -29,23 +32,29 @@ class UiPlugin extends _commons.Component {
   constructor() {
     super('ui');
     this.layouts = new _layouts.default(this);
-    this._recommendations = new WeakMap();
-    this._explores = new WeakMap();
-    this._asks = new WeakMap();
-    this._extensions = new WeakMap();
     this._ready = new _commons.Resolution();
   }
-  async install(MisoClient, {
-    addSubtree,
-    addExtensionPoints
-  }) {
+  async install(MisoClient, context) {
+    const {
+      addSubtree,
+      addExtensionPoints
+    } = context;
+    this._pluginContext = context;
     addSubtree(this);
+
+    // make sure the workflow plugin is installed, then provide the layout
+    // registry and seed the default layout options
+    MisoClient.plugins.use(_clientSdkWorkflow.WorkflowPlugin);
+    context.workflows.plugin.setLayouts(this.layouts);
+    this._seedWorkflowDefaults(context.workflows.defaults);
     MisoClient.on('create', this._injectClient.bind(this));
 
     // the UI interface for MisoClient
     const ui = {
       defaults,
-      traits
+      traits,
+      confirm: _confirm.default,
+      prompt: _prompt.default
     };
     (0, _commons.delegateGetters)(ui, this, ['layouts', 'ready']);
     (0, _commons.defineValues)(this, {
@@ -96,70 +105,33 @@ class UiPlugin extends _commons.Component {
     await (0, _styles.loadStylesIfNecessary)();
     this._ready.resolve();
   }
-  async requireExtension(name) {
-    switch (name) {
-      case 'markdown':
-        return await this.MisoClient.plugins.install('std:ui-markdown');
-      default:
-        throw new Error(`Unknown extension: ${name}`);
-    }
-  }
   get ready() {
     return this._ready.promise;
   }
+
+  /**
+   * Seed the workflow plugin's defaults store with the presentational default
+   * options: layouts of each workflow, plus UI templates.
+   */
+  _seedWorkflowDefaults(workflowDefaults) {
+    for (const [name, layouts] of Object.entries(_defaults.defaultLayouts)) {
+      workflowDefaults.set(name, {
+        layouts
+      });
+    }
+    workflowDefaults.set('ask', {
+      templates: {
+        followUp: _templates.followUp
+      }
+    });
+  }
   _injectClient(client) {
     (0, _commons.defineValues)(client, {
       ui: new Ui(this, client)
     });
   }
-  _getExtensions(client) {
-    if (this._extensions.has(client)) {
-      return this._extensions.get(client);
-    }
-    const extensions = new Extensions(this, client);
-    this._extensions.set(client, extensions);
-    return extensions;
-  }
-  _getRecommendations(client) {
-    let recommendations = this._recommendations.get(client);
-    if (!recommendations) {
-      this._recommendations.set(client, recommendations = new _index.Recommendations(this, client));
-    }
-    return recommendations;
-  }
-  _getExplores(client) {
-    let explores = this._explores.get(client);
-    if (!explores) {
-      this._explores.set(client, explores = new _index.Explores(this, client));
-    }
-    return explores;
-  }
-  _getAsks(client) {
-    let asks = this._asks.get(client);
-    if (!asks) {
-      this._asks.set(client, asks = new _index.Asks(this, client));
-    }
-    return asks;
-  }
 }
-
-// TODO: are we able to eliminate the concept of extension, just use plugins?
 exports.default = UiPlugin;
-class Extensions {
-  constructor(plugin, client) {
-    this._plugin = plugin;
-    this._client = client;
-    this._contexts = {};
-  }
-  async require(name) {
-    if (this._contexts[name]) {
-      return this._contexts[name];
-    }
-    const plugin = await this._plugin.requireExtension(name);
-    const context = this._contexts[name] = plugin.getContext(this._client);
-    return context;
-  }
-}
 function createUiPluginContext(plugin, ui, MisoClient) {
   async function addElementClasses(...ElementClasses) {
     for (const ElementClass of ElementClasses) {
@@ -187,6 +159,9 @@ function createUiPluginContext(plugin, ui, MisoClient) {
   };
 }
 
+// workflow accessors delegated to client.workflows for backward compatibility
+const WORKFLOW_ACCESSORS = ['search', 'hybridSearch', 'asks', 'ask', 'explores', 'explore', 'recommendations', 'recommendation', 'sources'];
+
 /**
  * The UI interface for the client.
  */
@@ -194,43 +169,7 @@ class Ui {
   constructor(plugin, client) {
     this._plugin = plugin;
     this._client = client;
-    (0, _commons.defineValues)(this, {
-      sources: {
-        api: sources.api(client)
-      }
-    });
-  }
-  get recommendations() {
-    return this._recommendations || (this._recommendations = this._plugin._getRecommendations(this._client));
-  }
-  get recommendation() {
-    return this.recommendations.get(); // get default recommendation unit
-  }
-  get search() {
-    if (!this._search) {
-      this._search = new _index.Search(this._plugin, this._client);
-      this._client._events.emit('postworkflow', this._search);
-    }
-    return this._search;
-  }
-  get asks() {
-    return this._asks || (this._asks = this._plugin._getAsks(this._client));
-  }
-  get ask() {
-    return this.asks.root;
-  }
-  get hybridSearch() {
-    if (!this._hybridSearch) {
-      this._hybridSearch = new _index.HybridSearch(this._plugin, this._client);
-      this._client._events.emit('postworkflow', this._hybridSearch);
-    }
-    return this._hybridSearch;
-  }
-  get explores() {
-    return this._explores || (this._explores = this._plugin._getExplores(this._client));
-  }
-  get explore() {
-    return this.explores.get(); // get default explore unit
+    (0, _commons.delegateGetters)(this, client.workflows, WORKFLOW_ACCESSORS);
   }
   get ready() {
     return this._plugin.ready;
@@ -242,6 +181,6 @@ class Combo {
     this._MisoClient = MisoClient;
   }
   get ask() {
-    return this._ask || (this._ask = new _index2.AskCombo(this._plugin, this._MisoClient));
+    return this._ask || (this._ask = new _index.AskCombo(this._plugin, this._MisoClient));
   }
 }

package/dist/cjs/util/confirm.js

@@ -0,0 +1,33 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = confirm;
+var _modal = require("./modal.js");
+const DEFAULT_CLASSNAME = 'miso-confirm';
+
+/**
+ * Show a modal confirmation dialog (a native <dialog>), resolving to whether
+ * the user confirmed. Cancel button, backdrop click, and the Escape key all
+ * resolve to false. Exposed as `MisoClient.ui.confirm()`.
+ */
+function confirm({
+  title,
+  message,
+  confirmText = 'Confirm',
+  cancelText = 'Cancel',
+  danger = false,
+  className = DEFAULT_CLASSNAME
+} = {}) {
+  return (0, _modal.openModal)({
+    className,
+    title,
+    message,
+    confirmText,
+    cancelText,
+    danger,
+    result: () => true,
+    cancelValue: false
+  });
+}

package/dist/cjs/util/dom.js

@@ -5,8 +5,29 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.addOrRemoveClass = addOrRemoveClass;
 exports.cssAspectRatio = cssAspectRatio;
+exports.dumpElementAttributes = dumpElementAttributes;
 exports.resolveCssLength = resolveCssLength;
 exports.setOrRemoveAttribute = setOrRemoveAttribute;
+// data-* attributes of an element as a JSON string, for click interactions
+function dumpElementAttributes(element) {
+  const {
+    attributes
+  } = element;
+  const attrs = {};
+  for (const {
+    name,
+    value
+  } of attributes) {
+    if (name.startsWith('data-')) {
+      attrs[name] = value;
+    }
+  }
+  try {
+    return JSON.stringify(attrs);
+  } catch (e) {
+    return '{}';
+  }
+}
 function setOrRemoveAttribute(element, name, value) {
   if (value === undefined) {
     element.removeAttribute(name);

package/dist/cjs/util/modal.js

@@ -0,0 +1,48 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.openModal = openModal;
+var _commons = require("@miso.ai/commons");
+/**
+ * The shared modal dialog core of confirm() and prompt(): a native <dialog>
+ * with title, message, an optional body, and cancel/confirm actions. Resolves
+ * with `result(dialog)` when confirmed; the cancel button, a backdrop click,
+ * and the Escape key all resolve with `cancelValue`.
+ */
+function openModal({
+  className,
+  title,
+  message,
+  body = '',
+  confirmText = 'Confirm',
+  cancelText = 'Cancel',
+  danger = false,
+  onOpen,
+  result = () => true,
+  cancelValue
+} = {}) {
+  return new Promise(resolve => {
+    const dialog = document.createElement('dialog');
+    dialog.className = className;
+    dialog.innerHTML = [title ? `<div class="${className}__title">${(0, _commons.escapeHtml)(title)}</div>` : '', message ? `<div class="${className}__message">${(0, _commons.escapeHtml)(message)}</div>` : '', body, `<div class="${className}__actions">`, `<button type="button" class="${className}__button ${className}__cancel-button" data-role="cancel">${(0, _commons.escapeHtml)(cancelText)}</button>`, `<button type="button" class="${className}__button ${className}__confirm-button${danger ? ` ${className}__confirm-button--danger` : ''}" data-role="confirm">${(0, _commons.escapeHtml)(confirmText)}</button>`, `</div>`].join('');
+    dialog.addEventListener('click', event => {
+      if (event.target.closest('[data-role="confirm"]')) {
+        dialog.close('confirm');
+      } else if (event.target.closest('[data-role="cancel"]') || event.target === dialog) {
+        dialog.close(); // cancel button or backdrop click
+      }
+    });
+    dialog.addEventListener('close', () => {
+      const value = dialog.returnValue === 'confirm' ? result(dialog) : cancelValue;
+      dialog.remove();
+      resolve(value);
+    }, {
+      once: true
+    });
+    document.body.appendChild(dialog);
+    dialog.showModal();
+    onOpen && onOpen(dialog);
+  });
+}

package/dist/cjs/util/prompt.js

@@ -0,0 +1,47 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = prompt;
+var _commons = require("@miso.ai/commons");
+var _modal = require("./modal.js");
+const DEFAULT_CLASSNAME = 'miso-prompt';
+
+/**
+ * Show a modal input dialog (a native <dialog>), resolving to the entered
+ * (trimmed) text when confirmed. Cancel button, backdrop click, and the
+ * Escape key all resolve to undefined. The Enter key confirms. Exposed as
+ * `MisoClient.ui.prompt()`.
+ */
+function prompt({
+  title,
+  message,
+  value = '',
+  placeholder,
+  confirmText = 'Confirm',
+  cancelText = 'Cancel',
+  className = DEFAULT_CLASSNAME
+} = {}) {
+  return (0, _modal.openModal)({
+    className,
+    title,
+    message,
+    body: `<input class="${className}__input" type="text" data-role="input" value="${(0, _commons.escapeHtml)(value)}"${placeholder ? ` placeholder="${(0, _commons.escapeHtml)(placeholder)}"` : ''}>`,
+    confirmText,
+    cancelText,
+    onOpen: dialog => {
+      const input = dialog.querySelector('[data-role="input"]');
+      input.addEventListener('keydown', event => {
+        if (event.key === 'Enter') {
+          event.preventDefault();
+          dialog.close('confirm');
+        }
+      });
+      input.focus();
+      input.select();
+    },
+    result: dialog => dialog.querySelector('[data-role="input"]').value.trim(),
+    cancelValue: undefined
+  });
+}

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.2-beta.1';
+var _default = exports.default = '1.14.0-beta.3';

package/package.json

@@ -12,8 +12,8 @@
     "access": "public"
   },
   "scripts": {
-    "build:clean": "npx rimraf dist",
-    "build:cjs": "BABEL_ENV=cjs npx babel src --root-mode upward --out-dir dist/cjs",
+    "build:clean": "rimraf dist",
+    "build:cjs": "BABEL_ENV=cjs babel src --root-mode upward --out-dir dist/cjs",
     "build": "npm run build:clean && npm run build:cjs"
   },
   "repository": {
@@ -30,7 +30,8 @@
     "url": "https://github.com/MisoAI/miso-client-js-sdk/issues"
   },
   "dependencies": {
-    "@miso.ai/commons": "1.13.2-beta.1"
+    "@miso.ai/commons": "1.14.0-beta.3",
+    "@miso.ai/client-sdk-workflow": "1.14.0-beta.3"
   },
-  "version": "1.13.2-beta.1"
+  "version": "1.14.0-beta.3"
 }

package/src/CLAUDE.md

@@ -1,112 +1,64 @@
 # Client SDK UI
 
-The UI package (`std:ui` plugin) provides the presentation layer for Miso SDK, including custom elements, workflows, and rendering infrastructure.
+The UI package (`std:ui` plugin) provides the presentation layer for Miso SDK: custom elements, layouts, and rendering infrastructure.
 
-## Architecture Overview
+The workflow layer (workflow classes, actors, hub, default-options store) lives in `@miso.ai/client-sdk-workflow` — see `packages/client-sdk-workflow/CLAUDE.md` for the hub-and-spoke architecture, workflow class hierarchy, roles/status model, and the end-to-end data flow. This package plugs elements and layouts into those workflows.
 
-// TODO: wrong concept
+## Architecture Overview
 
 ```
-┌─────────────────────────────────────────────────────────────────┐
-│                         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)  │
-   └─────────────┘
+UiPlugin ('std:ui', singleton)
+ ├─ ensures WorkflowPlugin ('std:workflow') is installed
+ ├─ provides its Layouts registry to the workflow plugin (setLayouts)
+ ├─ seeds default layout options (defaults.js) + ask followUp template
+ │  into the workflow plugin's defaults store
+ ├─ Layouts registry (layout classes, keyed by type)
+ ├─ defines <miso-*> custom elements
+ └─ injects client.ui on each MisoClient instance; its workflow accessors
+    (search, asks, ...) delegate to client.workflows for backward compatibility
 ```
 
-## Core Directories
+Key points that are easy to get wrong:
 
-// TODO: wrong concept
+- **Elements render nothing.** A container element (e.g. `<miso-ask>`) locates its workflow on `connectedCallback()` and registers itself; child role elements register through their container. The workflow's `ViewsActor` then creates one `ViewActor` per element, pairing it with a **layout instance** for that role. The layout writes DOM into the element.
+- Layouts are **instances created per view** from classes registered in the plugin's `Layouts` registry (`layout.type` → class), chosen by the workflow's `layouts` options. They are not templates.
+- Default layout options per workflow live in `src/defaults.js`, keyed by workflow name, and are seeded into the workflow plugin's defaults store at install — they are not baked into the workflow classes.
+
+## Core Directories
 
 | 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`
+| `element/` | Custom HTML elements (`<miso-*>`): thin, render-free DOM anchors that bind themselves to workflows |
+| `layout/` | Layout classes (rendering logic), registered by `type` in the plugin's registry, instantiated per view |
+| `combo/` | `AskCombo`: programmatic pre-built ask UI (deprecated) |
+| `trait/` | Reusable behaviors exposed as `MisoClient.ui.traits` (e.g. `CollapsibleTrait`) |
+| `defaults/` | Default templates/phrases/controls for ask and hybrid-search UIs, exposed as `MisoClient.ui.defaults` |
+| `defaults.js` | Default layout options of each workflow, seeded into the workflow plugin's store |
+| `constants.js` | UI-only constants (`LAYOUT_TYPE`, data attributes); re-exports workflow constants (`ROLE`, `STATUS`, ...) for convenience |
 
-### Elements (`element/`)
+## Elements (`element/`)
 
-Web Components following the `<miso-*>` naming convention:
+Web Components (`<miso-*>`). They contain **no rendering or data logic** — they only establish the DOM binding:
 
-- **Containers**: Top-level elements that own a workflow
-  - `<miso-ask>`, `<miso-search>`, `<miso-explore>`, `<miso-recommendation>`, `<miso-hybrid-search>`
+- **Containers** (`element/container/`): own the workflow binding for their subtree.
+  - `<miso-ask>` — binds by `parent-question-id` attribute (absent = root ask), or `workflow="active"` to follow `asks.active`
+  - `<miso-search>`, `<miso-hybrid-search>` — bind to `client.ui.search` / `.hybridSearch`
+  - `<miso-explore>`, `<miso-recommendation>` — bind by `unit-id` attribute
+  - `<miso-history>`, `<miso-conversation>` — bind to `client.workflows.history` / `.conversation`, forming the chat history interface (thread list + conversation panel); their role elements are `<miso-threads>`, `<miso-new-thread>`, `<miso-messages>`, `<miso-title>`, `<miso-rename>`, `<miso-delete>` and `<miso-subscription>`. The new-thread button is its own component (`<miso-new-thread>`, role `new_thread`), *not* part of the thread list, so it renders regardless of the list state (loading, empty, erroneous); it uses the generic `button` layout — an icon and a label, both configurable (`icon`, `text`), emitting a `submit` view event when clicked — which History answers by clearing the selection and resetting the conversation panel to new-thread mode. The thread list uses the `threads` layout as a **shell**, like the conversation's `messages` layout: each `thread` item is a `<miso-thread-item>` container element (`data-role="item"`, carrying the thread id and the state attributes) hosting the thread item subworkflow, with the title and the context menu's rename/subscription/delete controls as role elements inside rendering through that workflow's own generic layouts; selection is part of the data — `selectedThreadId` lives in the workflow's committed value and each record carries its `selected` flag right in the data layer (stamped by the workflow's default data pass, preserving the identity of records whose flag doesn't flip, so only the affected items' subworkflows see a commit; the role mapping is a plain slice) — and the list renders incrementally: fresh items land at either end — a newly created thread renders as a prepend (the list is newest-first), an older page fetched by the more flow as appends — told apart by which boundary the already-rendered records line up with (anything else re-renders in full), while in-place state changes on existing items (selected/unread, the thread id of a settled placeholder) are applied by an attribute-sync pass after each render, reading fresh values off the item bindings, and the item contents follow the record down each thread workflow's own data path — no item re-render either way. The list **pages by infinite scroll**, through the collection layout's stock machinery (the `data-role="trigger"` div after the list + the triggerable mixin, enabled by the threads layout's `infiniteScroll` option and the workflow's `'history'` pagination defaults): the trigger scrolling into view fires the `more` hub field, History appends the next page (`start`/`rows` against the user history list API, exhaustion from the response's own `has_more`), and the page size is set via `history.useApi('threads/list', { rows: N })`; the conversation uses the `messages` layout as a **shell**: each `message` item is a `<miso-message-item>` container element (question/answer/feedback/sources role elements inside, in that order — the feedback buttons right below the answer via the standard feedback layout, the sources as the hybrid-search-style compact horizontal cards under an h3 "Sources" heading (`messageSourcesBlock`, overridable — the block is `visible-when="nonempty"`, so the heading appears only once the item carries content, and a `:has()` rule hides the whole block again when there are zero source cards; a browser without `:has()` degrades to showing the heading, hybrid-search-parity); the item element carries `miso-circled-citation-index`, covering the answer's citation links and the source cards' indexes alike, as the hybrid-search UI scopes it; a message record without its answer body presents as workflow status `loading`, stamped on the element by its container layout as the standard `status` attribute — there is deliberately no per-message loading icon: the answer typewriter's blinking caret is the loading indication, as in ask (hidden at `initial` and at `done` by the stock typewriter CSS); a message whose content fetch failed for good presents as status `erroneous` and swaps its content out wholesale for the item template's muted notice (`messageErrorBlock`, `visible-when="erroneous"` — `miso-message-item` is in the visible-when container list, so the notice keys off the item's own status attribute) — the regular role elements are packed in a `__content` wrapper hidden by a class rule at erroneous status (a wrapper cannot be visible-when-driven itself: the mechanism forces `display: block !important` and only negates combined with positive terms) — and the messages layout's `ongoing` computation skips an errored last message so the composer is not held), rendered incrementally — fresh items land at either end: a posted follow-up appends at the bottom, an older page fetched by the more flow prepends at the top (told apart by which boundary the already-rendered records line up with; anything else re-renders in full) — the content itself renders through each message's own item subworkflow. The panel **pages by infinite scroll, chat-style from the bottom**: the messages layout's own root template places the stock `data-role="trigger"` div **above** the list, so scrolling up fires the `more` hub field (enabled by the layout's `infiniteScroll` option + the workflow's `'conversation'` pagination defaults) and the Conversation workflow prepends the previous page of messages. The post-render sync pass (`_syncWorkflows`) does one thing: assign each `<miso-message-item>` its workflow off the item binding (`element.workflow = conversation._getMessageWorkflow(record)` — implicit binding, item identity keyed by question id falling back to the posted record's local `placeholder_id`, so the element and workflow survive the settle). Item elements of a nested collection do not leak into the outer one: a message hosts its own source-card items (`data-role="item"` too), so `CollectionLayout._getItemElements` keeps only elements whose closest `[data-role="list"]` is the layout's own list — bindings zip values to elements by index, so a stray nested item would shift every binding after it. The question bubble is the **`question` layout** (the message workflow's default for the question role, whose mapping passes the whole record): it renders the question text and stamps the authorship as data attributes on its host element — `data-author` (the label text, configurable via the layout's `author` option; by default 'Written by Miso' for questions whose `metadata.miso_generated_by` is `answer_update_monitor`, per `isUpdateMessage`; it renders as a CSS `attr()` badge overlapping the bubble's top-left border, and monitor-generated bubbles take a distinct background) and `data-generated-by` — and hides its host while there is no question text. The shell also owns the panel-level behaviors: scroll pinning (following content growth via a ResizeObserver on the list, since answers type out through their own workflows outside the shell's render cycle), scroll anchoring while scrolled up — a prepend keeps the reading position by anchoring on the previously-first item: everything prepended, including its contents rendering in later through the item workflows, sits above the anchor, so holding the anchor stationary (at insert time and on every growth event while unpinned, the anchor's offset re-recorded as the user scrolls) holds the view, while growth below it (a streaming answer) needs no compensation; done by hand, since not every engine provides native scroll anchoring — and the `ongoing` view state read off the data — the last message's answer absent or unfinished — which e.g. disables the search box. The conversation's header roles come from the open thread's record: `<miso-title>` (role `title`) renders its title with the generic `text` layout, `<miso-rename>` (role `rename`) renders a pencil button with the generic `button` layout whose **`prompt` option** turns the click into ask-then-submit: the shared prompt dialog opens pre-filled with the control's current value — the role's mapped data value, read off the latest rendered state (`_currentValue()`; `RafLayout` retains it per element) — and the `submit` view event carries the confirmed text as `value`, which Conversation answers with `rename(value)` — `<miso-delete>` (role `delete`, placed right of the rename button) renders a red bin button with the button layout's `confirm` option (the dialog's message interpolates the mapped title), whose confirmed `submit` Conversation answers with `delete()` (the deletion fact then resets the panel to new-thread mode) — and `<miso-subscription>` (role `subscription`) renders the answer-updates toggle with the **`checkbox` layout** — a button-layout subclass; a checkbox that looks like a button (`<button role="switch" aria-checked>` with `data-checked`, an icon and label per state via `icon`/`text` and `checkedIcon`/`checkedText`). Its checked state comes from the data, so a click emits a `change` view event carrying only the requested state (`{ checked }`), read off the rendered element; the Conversation workflow answers it with `subscribe()`/`unsubscribe()` and the new state arrives back down the data path. Note the `visible-when` mechanism forces `display: block !important` on the element it toggles, so a page that lays such an element out as a flex row needs an inner wrapper (as the history demo pages do for the header). A `<miso-query>` (search-box layout) inside `<miso-conversation>` submits questions as the `submit` view event, which Conversation routes to `send()` — follow-ups, or the first question of a new thread (the conversation starts in new-thread mode). With `messages`/`threads` registered as data roles, `<miso-conversation>` carries the `empty`/`nonempty` content status, which pages use to center the composer in the empty (new-thread) state. A click on a thread item is a navigation action, not a content-engagement click: the `threads` layout overrides `_onClick` to emit a `select` view event (no click tracking), which the History workflow handles with `select()` — item selection stays list-level, while everything inside the item belongs to its thread workflow. Each item also carries a context menu (vertical dots, revealed on hover): its markup comes from the item template (`threadMenuBlock`), and its open/close behavior is driven by the thread workflow's **`item-container` layout** (`ItemContainerLayout`, the container-layout subclass for collection item subworkflows) **by contract** — the template marks the toggle button `data-role="item-menu-button"` and the popup `data-role="item-menu"`, and the layout toggles on the button and closes on any other click on the item or outside it (per-item document listeners, which is also how opening one item's menu closes another's); the shell only keeps clicks carrying those data-roles from selecting. The menu items are the thread workflow's own controls, each a generic `button` layout going through a shared modal dialog util (promise-returning native `<dialog>`s on a common core, `util/modal.js`): `<miso-rename>` (role `rename`) uses the button layout's `prompt` option (`util/prompt.js`, a modal text input pre-filled with the current title — Enter confirms, resolving to the trimmed text, or undefined on cancel; exposed as `MisoClient.ui.prompt`), and `<miso-delete>` (role `delete`) its **`confirm` option** (`util/confirm.js`, exposed as `MisoClient.ui.confirm`; the option's `message` may be a function of the control's current value — the mapped title); the confirmed `submit` view events fire the operation requests on the thread workflow's own hub, their facts riding onto the shared thread events emitter. Between the two sits `<miso-subscription>` (role `subscription`), the `checkbox` layout as a plain menu item: text only, labeled by the action a click takes ('Subscribe' / 'Unsubscribe' via `text`/`checkedText` in the `'history'` defaults — unlike the conversation header's state-labeled bell pill), its `change` view event answered by the thread workflow with `history.subscribe()`/`unsubscribe()`.
+- `<miso-message-item>` — a **container element inside another container element** (`<miso-conversation>`), hosting the `message-item` workflow — an answer-based workflow that posts and streams its own content when live (ask-style), and is otherwise fed by the conversation via `updateData()` with its data actor off. Normally **bound implicitly**: the messages layout renders one per item and assigns `element.workflow` off the item binding (which also covers a just-posted message with no question id yet); a `question-id` attribute binds explicitly through the parent container's workflow instead (`conversation._getMessageWorkflow`). Its role children (`<miso-question>`, `<miso-answer>`, `<miso-sources>`, `<miso-feedback>`, ...) bind to the message workflow as usual (`getContainer` resolves to the closest container ancestor) and render one message via the standard answer-based layouts (the message workflow shares the conversation's options, whose `'conversation'` defaults hold the message roles too — omitting the query role, turning the container logo off, and giving the answer typewriter `instant: true` — already-finished answers render in one shot); citation/link clicks and feedback go out as message-level interactions, deduplicated per message.
+- `<miso-thread-item>` — the thread list's analogue of `<miso-message-item>`: a container element inside `<miso-history>`, hosting the `thread-item` workflow — data actor off, fed by History via `updateData()` with only the records that actually changed (record identity is the change signal). Normally **bound implicitly**: the threads layout renders one per item and assigns `element.workflow` off the item binding; a `thread-id` attribute binds explicitly through the parent container's workflow instead (`history._getThreadWorkflow`). Its role children — `<miso-title>` (generic `text` layout, with an 'Untitled' fallback via a `content` template), `<miso-rename>`/`<miso-delete>` (generic `button` layout with the `prompt`/`confirm` dialog options), and `<miso-subscription>` (the `checkbox` layout, the context menu's toggle) — bind to the thread workflow as usual; title and subscription map dot-paths into the record (`'title'`, `'subscribed'`), while rename and delete map the whole record — their button layouts derive the dialog text via the `value` option and render disabled (the `disabled` option) until the record carries a thread id, so a thread being created is inert in the UI too. Its container role uses the `item-container` layout, which drives the context menu found in the item's markup via the `item-menu` data-role contract (a custom body without menu markup simply has nothing to drive).
+- **Role components** (`element/role/`): register with their ancestor container; the role determines which slice of data they display. Either dedicated tags (`<miso-answer>`, `<miso-sources>`, `<miso-products>`, `<miso-query>`, ...) or generic `<miso-component role="...">`. `<miso-results>` is deprecated in favor of `<miso-products>`.
+- **Combos** (`element/combo/`): pre-configured composite `<miso-ask-combo>` (deprecated).
 
-- **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>`
+Connecting an element to the DOM is what triggers view creation: container `connectedCallback` → `workflow._views.addContainer/addComponent` → `ViewActor` created with a layout instance → rendered as soon as data exists.
 
-- **Combos**: Pre-configured composite elements (deprecated)
-  - `<miso-ask-combo>`
+## Layouts (`layout/`)
 
-### Actors (`actor/`)
+Rendering strategies. A layout class has a static `type` (e.g. `'list'`, `'typewriter'`, `'search-box'`) and is registered in the plugin registry; workflows pick layouts per role via options (`useLayouts({ answer: ['typewriter', {...}] })`). `ViewsActor` instantiates one layout object per view.
 
-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
+Contract: `render(element, data, { notifyUpdate })` is mandatory; `initialize(view)`, `unrender(element)`, `syncSize(element)`, `destroy()` are optional. `notifyUpdate(state)` is how a layout reports its view state back (published to `view:<role>` on the hub) — this drives workflow lifecycle events. A layout submits user actions as **view events**, like the buttons do: `SearchBoxLayout` emits `submit` (`{ session, value }`) on the query role, which each query-hosting workflow subscribes to and routes itself (`_onQuerySubmit` → `query()` in the answer-based, search-based and explore workflows; Conversation routes to `send()`) — layouts never write the query field or call workflow methods directly.
 
-### 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`
+A layout root stamps its view role as a `data-role` attribute — the role name verbatim, snake_case included (`data-role="new_thread"`) — and CSS binds to layout className + role (`.miso-text[data-role="question"]`), never to the host element tag: `<miso-rename>` and `<miso-component role="rename">` style alike; element tags appear only in `_container.scss` for structural rules (display, box-sizing, `visible-when`).
 
 ## Entry Point
 
@@ -115,20 +67,15 @@ Types: `input`, `list`, `text`, `container`, `error`, `button`, etc.
 // Installed automatically with full SDK, or manually:
 MisoClient.plugins.use('std:ui');
 
-// Access via client instance:
+// Access via client instance (canonical, injected by std:workflow):
 const client = new MisoClient({ apiKey });
-client.ui.ask;           // Ask workflow
-client.ui.search;        // Search workflow
-client.ui.recommendations; // Recommendations
+client.workflows.ask;            // root Ask workflow (=== client.workflows.asks.root)
+client.workflows.asks;           // Asks context (follow-up chain, .active, .root)
+client.workflows.search;         // Search workflow
+client.workflows.hybridSearch;   // HybridSearch workflow
+client.workflows.recommendations.get(unitId); // Recommendation workflow per unit
+client.workflows.explores.get(unitId);        // Explore workflow per unit
+
+// client.ui.search, client.ui.asks, client.ui.sources, ... delegate to
+// client.workflows for backward compatibility; client.ui's own surface is only `ready`.
 ```
-
-## 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