symbiote-ui 0.3.0-alpha.13 → 0.3.0-alpha.15

package/README.md

@@ -25,7 +25,7 @@ npm install jsda-kit linkedom
 
 - `symbiote-ui` - Node-safe core primitives.
 - `symbiote-ui/core` - graph editor data primitives.
-- `symbiote-ui/layout` - SSR-safe layout helpers.
+- `symbiote-ui/layout` - SSR-safe layout, behavior, and lifecycle helpers.
 - `symbiote-ui/graph` - provider graph normalization and projection helpers.
 - `symbiote-ui/manifest` - component, schema, rule, theme, and provider catalogs.
 - `symbiote-ui/runtime` - Node-safe agent UI construction helpers.
@@ -35,6 +35,7 @@ npm install jsda-kit linkedom
 - `symbiote-ui/locale` - Node-safe locale catalogs and translation helpers.
 - `symbiote-ui/discover` - provider discovery JSON API used by the CLI.
 - `symbiote-ui/chat/voice-input-defaults.js` - Node-safe wake/send/action voice command defaults and matching helpers.
+- `symbiote-ui/chat/voice-controller.js` - browser wake listening and response speech orchestration for chat hosts.
 - `symbiote-ui/custom-elements.json` - Custom Elements manifest.
 - `symbiote-ui/schemas/*`, `symbiote-ui/tokens/*`, `symbiote-ui/rules/*` - machine-readable provider contracts.
 - `symbiote-ui/display/*` - reusable display utilities exposed by package export map.
@@ -154,6 +155,61 @@ let theme = createCascadeTheme({ mode: 'dark', brightness: 8, contrast: 64 });
 applyCascadeTheme(document.documentElement, theme.state);
 ```
 
+Use `cascade-theme-widget` for shell-level quick controls and
+`cascade-theme-editor` for the full layout panel. Keep both components on the
+same `storage-key` and `target-selector`; the widget emits
+`cascade-theme-open-full`, and the host opens a registered `panel-layout`
+panel:
+
+```html
+<section id="app-shell">
+  <header>
+    <cascade-theme-widget
+      storage-key="my-app:cascade-theme"
+      target-selector="#app-shell"
+    ></cascade-theme-widget>
+  </header>
+  <panel-layout id="workspace-layout"></panel-layout>
+</section>
+```
+
+```js
+import { defineModule } from 'symbiote-ui/ui';
+
+defineModule('cascade-theme-widget');
+defineModule('cascade-theme-editor');
+defineModule('panel-layout');
+
+class AppThemePanel extends HTMLElement {
+  connectedCallback() {
+    if (this.ready) return;
+    this.ready = true;
+    this.innerHTML = `
+      <cascade-theme-editor
+        storage-key="my-app:cascade-theme"
+        target-selector="#app-shell"
+      ></cascade-theme-editor>
+    `;
+  }
+}
+
+customElements.define('app-theme-panel', AppThemePanel);
+
+let layout = document.querySelector('#workspace-layout');
+layout.registerPanelType('theme-editor', {
+  title: 'Theme',
+  icon: 'palette',
+  component: 'app-theme-panel',
+});
+
+document.addEventListener('cascade-theme-open-full', () => {
+  layout.openPanel('theme-editor', {
+    uiInvoked: true,
+    source: 'cascade-theme-widget',
+  });
+});
+```
+
 For chat construction, use `chat-workspace` when the host needs the complete
 reusable shell: sidebar, transcript, composer, footer controls, voice-control
 intents, and animated `cell-bg` lifecycle. `chat-sidebar-shell` and
@@ -179,7 +235,12 @@ chunks and dispatches a `chat-composer-audio-captured` event with the resulting
 raw audio blob so the host can process or transcribe it. Use
 `symbiote-ui/chat/voice-input-defaults.js` for shared wake/send/cancel/delete/off
 phrases, command parsing, and matching when hosts need Agent Portal-compatible
-voice command behavior. `setFooterHtml()`
+voice command behavior. `VoiceController` in
+`symbiote-ui/chat/voice-controller.js` coordinates browser wake listening,
+pause/resume while recording or speaking, wake-command matching, and response
+speech lifecycle while leaving settings, transcription providers, persistence,
+and routing to the host. It is also exported through `symbiote-ui/ui` for
+browser hosts. `setFooterHtml()`
 remains available only for trusted host-rendered footer markup.
 `extractChatTitleFromAgentText()` provides a product-neutral parser for
 standalone `<chat-title>...</chat-title>` responses; any prompt instruction that
@@ -327,8 +388,10 @@ agents that compose dynamic workspaces:
 ```js
 import {
   LayoutTree,
+  resumeLayoutSubtree,
   resolveLayoutMinSize,
   resolveResponsiveLayoutState,
+  suspendLayoutSubtree,
 } from 'symbiote-ui/layout';
 
 let root = LayoutTree.createSplit(
@@ -343,6 +406,9 @@ let state = resolveResponsiveLayoutState(
   { collapse: 'auto', overflow: 'scroll-inline', responsiveMode: 'scroll-inline' },
   { inlineSize: 520, blockSize: 420, layoutMinSize: minSize }
 );
+
+suspendLayoutSubtree(workspaceEl, { reason: 'workspace-inactive' });
+resumeLayoutSubtree(workspaceEl, { reason: 'workspace-active' });
 ```
 
 `panel-layout` uses the same contract at runtime. Root `layoutBehavior`
@@ -361,6 +427,12 @@ smoke tests, and agents can distinguish requested policy from active fallback.
 `layout-sidebar` owns only its sidebar configuration and width persistence; its
 reset control clears that state and emits `layout-sidebar-reset` for host-owned
 layout resets instead of clearing host storage or reloading the page.
+`suspendLayoutSubtree()` and `resumeLayoutSubtree()` call public
+`suspendLayout()`/`resumeLayout()` methods on reusable components and host
+adapters in a hidden layout subtree. `chat-workspace`, `chat-composer`, and
+`cell-bg` implement this contract so hidden workspace groups stop animated
+backgrounds, wake listeners, voice capture, and UI timers without destroying
+host-owned chat, route, or layout state.
 
 ## Spatial Algorithms
 

package/chat/ChatComposer/ChatComposer.js

@@ -340,6 +340,29 @@ export class ChatComposer extends Symbiote {
     super.disconnectedCallback?.();
   }
 
+  suspendLayout() {
+    this._resumeLocalWakeAfterSuspend = this._localVoiceActiveMode === 'wake';
+    this._stopLocalWakeRecognition();
+    this._voiceRuntime?.cancel?.();
+    this._localVoiceState = this._resumeLocalWakeAfterSuspend ? 'listening' : 'idle';
+    this._localVoiceActiveMode = this._resumeLocalWakeAfterSuspend ? 'wake' : 'idle';
+    this._localVoiceWakeMatched = false;
+    this._localWakeTriggering = false;
+    this.clearVoicePreview();
+    this._syncLocalVoiceControls();
+  }
+
+  resumeLayout() {
+    if (!this._resumeLocalWakeAfterSuspend) return;
+    this._resumeLocalWakeAfterSuspend = false;
+    this._localVoiceActiveMode = 'wake';
+    this._localVoiceState = 'listening';
+    this._localVoiceWakeMatched = false;
+    this._localWakeTriggering = false;
+    this._syncLocalVoiceControls();
+    this._startLocalWakeRecognition();
+  }
+
   _voiceCommandLocale() {
     let locale = this._voiceControls?.language?.mode || 'en';
     return ['ru', 'es', 'en'].includes(locale) ? locale : 'en';

package/chat/ChatWorkspace/ChatWorkspace.js

@@ -200,6 +200,19 @@ export class ChatWorkspace extends Symbiote {
     this.setBackgroundState({ state: 'stop', active: false });
   }
 
+  suspendLayout() {
+    this._layoutSuspendedBackgroundState = this.dataset.backgroundState || '';
+    this.getBackground()?.stop?.();
+  }
+
+  resumeLayout() {
+    let state = this._layoutSuspendedBackgroundState || this.dataset.backgroundState || '';
+    this._layoutSuspendedBackgroundState = '';
+    if (BACKGROUND_ACTIVE_STATES.has(state)) {
+      this.setBackgroundState({ state, active: true, reason: 'layout-resume' });
+    }
+  }
+
   _bindWorkspaceEvents() {
     let route = (sourceEvent, eventName, detailFactory = (event) => event.detail || {}) => {
       this.addEventListener(sourceEvent, (event) => {

package/chat/chat-title.js

@@ -15,7 +15,7 @@ export function sanitizeChatTitle(value = '', options = {}) {
     .replace(/[`*_#[\](){}<>]/g, '')
     .replace(/\s+/g, ' ')
     .trim()
-    .replace(/^["']+|["']+$/g, '')
+    .replace(/^["'«“]+|["'»”]+$/g, '')
     .trim();
 
   if (!title) return '';

package/chat/voice-controller.js

@@ -0,0 +1,196 @@
+import { matchVoiceCommandInText } from './voice-input-defaults.js';
+
+function createWakeError(error, message, cause = null) {
+  return { error, message, cause };
+}
+
+export class VoiceController {
+  constructor({
+    getLanguage = () => 'en-US',
+    getWakeCandidates = () => [],
+    onWakeTriggered = () => {},
+    onSpeechStart = () => {},
+    onSpeechEnd = () => {},
+    onWakeError = () => {},
+  } = {}) {
+    this.getLanguage = getLanguage;
+    this.getWakeCandidates = getWakeCandidates;
+    this.onWakeTriggered = onWakeTriggered;
+    this.onSpeechStart = onSpeechStart;
+    this.onSpeechEnd = onSpeechEnd;
+    this.onWakeError = onWakeError;
+
+    this.wakeEnabled = false;
+    this.wakePaused = false;
+    this.speaking = false;
+
+    this._wakeRecognition = null;
+    this._speechUtterance = null;
+    this._wakeTimeout = null;
+  }
+
+  static get hasSpeechRecognition() {
+    if (typeof window === 'undefined') return false;
+    return Boolean(window.SpeechRecognition || window.webkitSpeechRecognition);
+  }
+
+  static get hasSpeechSynthesis() {
+    if (typeof globalThis === 'undefined') return false;
+    return Boolean(globalThis.speechSynthesis && globalThis.SpeechSynthesisUtterance);
+  }
+
+  get isWakeActive() {
+    return this.wakeEnabled && !this.wakePaused;
+  }
+
+  startWake() {
+    this.wakeEnabled = true;
+    this.wakePaused = false;
+    this._startWakeRecognition();
+  }
+
+  stopWake({ disableMode = false } = {}) {
+    if (disableMode) {
+      this.wakeEnabled = false;
+      this.cancelSpeech();
+    }
+    this.wakePaused = false;
+    this._stopWakeRecognition();
+  }
+
+  pauseWake() {
+    if (!this.wakeEnabled) return;
+    this.wakePaused = true;
+    this._stopWakeRecognition();
+  }
+
+  resumeWake() {
+    if (!this.wakeEnabled) return;
+    this.wakePaused = false;
+    this._startWakeRecognition();
+  }
+
+  _startWakeRecognition() {
+    if (!this.wakeEnabled || this.wakePaused || this._wakeRecognition) return;
+    if (this._wakeTimeout) {
+      clearTimeout(this._wakeTimeout);
+      this._wakeTimeout = null;
+    }
+
+    const SpeechRecognition = typeof window !== 'undefined'
+      ? (window.SpeechRecognition || window.webkitSpeechRecognition)
+      : null;
+
+    if (!SpeechRecognition) {
+      this.wakeEnabled = false;
+      this.onWakeError(createWakeError(
+        'not-supported',
+        'Speech recognition is not supported by this browser.'
+      ));
+      return;
+    }
+
+    try {
+      const recognition = new SpeechRecognition();
+      recognition.lang = this.getLanguage();
+      recognition.interimResults = true;
+      recognition.continuous = true;
+      this._wakeRecognition = recognition;
+
+      recognition.onresult = (event) => {
+        let transcript = '';
+        for (let i = event.resultIndex; i < event.results.length; i++) {
+          transcript += event.results[i][0].transcript;
+        }
+        const candidates = this.getWakeCandidates();
+        if (matchVoiceCommandInText(transcript, candidates).matched) {
+          this.onWakeTriggered();
+        }
+      };
+
+      recognition.onerror = (event) => {
+        this._wakeRecognition = null;
+        this.onWakeError(event);
+      };
+
+      recognition.onend = () => {
+        this._wakeRecognition = null;
+        if (this.wakeEnabled && !this.wakePaused) {
+          this._wakeTimeout = setTimeout(() => this._startWakeRecognition(), 250);
+        }
+      };
+
+      recognition.start();
+    } catch (err) {
+      this.wakeEnabled = false;
+      this.wakePaused = false;
+      this._wakeRecognition = null;
+      this.onWakeError(createWakeError(
+        'start-failed',
+        'Speech recognition failed to start.',
+        err
+      ));
+    }
+  }
+
+  _stopWakeRecognition() {
+    if (this._wakeTimeout) {
+      clearTimeout(this._wakeTimeout);
+      this._wakeTimeout = null;
+    }
+    if (this._wakeRecognition) {
+      const rec = this._wakeRecognition;
+      this._wakeRecognition = null;
+      rec.onresult = null;
+      rec.onerror = null;
+      rec.onend = null;
+      try {
+        rec.abort();
+      } catch (_) {}
+    }
+  }
+
+  speak(text) {
+    if (!VoiceController.hasSpeechSynthesis) return;
+    this.cancelSpeech();
+
+    this.pauseWake();
+    this.speaking = true;
+    this.onSpeechStart();
+
+    const utterance = new SpeechSynthesisUtterance(text);
+    utterance.lang = this.getLanguage();
+    this._speechUtterance = utterance;
+
+    const cleanup = () => {
+      if (this._speechUtterance === utterance) {
+        this.speaking = false;
+        this._speechUtterance = null;
+        this.onSpeechEnd();
+        this.resumeWake();
+      }
+    };
+
+    utterance.onend = cleanup;
+    utterance.onerror = cleanup;
+
+    globalThis.speechSynthesis.cancel();
+    globalThis.speechSynthesis.speak(utterance);
+  }
+
+  cancelSpeech() {
+    if (!VoiceController.hasSpeechSynthesis) return;
+    if (this.speaking) {
+      globalThis.speechSynthesis.cancel();
+      this.speaking = false;
+      this._speechUtterance = null;
+      this.onSpeechEnd();
+      this.resumeWake();
+    }
+  }
+
+  destroy() {
+    this.stopWake({ disableMode: true });
+    this.cancelSpeech();
+  }
+}

package/chat/voice-settings.js

@@ -0,0 +1,149 @@
+import {
+  defaultSendCommandPhrases,
+  defaultVoiceActionCommandPhrases,
+  defaultWakeCommandPhrases,
+  normalizeWakeCommandPhrase,
+  parseVoiceCommandList,
+} from './voice-input-defaults.js';
+
+export const DEFAULT_VOICE_SETTINGS = Object.freeze({
+  commandMode: false,
+  responseEnabled: false,
+  languageMode: 'en',
+});
+
+const VOICE_LOCALES = Object.freeze(['en', 'ru', 'es']);
+const VOICE_ACTIONS = Object.freeze(['cancel', 'delete', 'off']);
+
+function asObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+export function normalizeVoiceLanguageMode(mode, fallbackLocale = 'en') {
+  let value = String(mode || '').trim().toLowerCase();
+  if (['ru', 'es', 'en'].includes(value)) return value;
+  return fallbackLocale;
+}
+
+function getSafeStorage(customStorage) {
+  if (customStorage) return customStorage;
+  if (typeof window !== 'undefined' && typeof window.localStorage !== 'undefined') {
+    return window.localStorage;
+  }
+  return null;
+}
+
+export function loadVoiceSettings(storage, fallbackLocale = 'en') {
+  let safeStorage = getSafeStorage(storage);
+  let commandMode = DEFAULT_VOICE_SETTINGS.commandMode;
+  let responseEnabled = DEFAULT_VOICE_SETTINGS.responseEnabled;
+  let languageMode = normalizeVoiceLanguageMode('', fallbackLocale);
+
+  if (safeStorage) {
+    try {
+      let savedCommandMode = safeStorage.getItem('symbiote_voice_command_mode');
+      if (savedCommandMode !== null) {
+        commandMode = savedCommandMode === 'true';
+      }
+      let savedResponseEnabled = safeStorage.getItem('symbiote_voice_response_enabled');
+      if (savedResponseEnabled !== null) {
+        responseEnabled = savedResponseEnabled === 'true';
+      }
+      let savedLanguageMode = safeStorage.getItem('symbiote_voice_language_mode');
+      if (savedLanguageMode !== null) {
+        languageMode = normalizeVoiceLanguageMode(savedLanguageMode, fallbackLocale);
+      }
+    } catch (_) {}
+  }
+
+  return {
+    commandMode,
+    responseEnabled,
+    languageMode,
+  };
+}
+
+export function saveVoiceSettings(settings, storage) {
+  let safeStorage = getSafeStorage(storage);
+  if (!safeStorage) return false;
+
+  try {
+    if (settings.commandMode !== undefined) {
+      safeStorage.setItem('symbiote_voice_command_mode', String(settings.commandMode));
+    }
+    if (settings.responseEnabled !== undefined) {
+      safeStorage.setItem('symbiote_voice_response_enabled', String(settings.responseEnabled));
+    }
+    if (settings.languageMode !== undefined) {
+      safeStorage.setItem('symbiote_voice_language_mode', String(settings.languageMode));
+    }
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+export function mergeServerVoiceSettings(local, serverVoiceInput, fallbackLocale = 'en') {
+  let result = { ...local };
+  if (!serverVoiceInput || typeof serverVoiceInput !== 'object') {
+    return result;
+  }
+
+  if (serverVoiceInput.sendByCommandEnabled !== undefined) {
+    result.commandMode = Boolean(serverVoiceInput.sendByCommandEnabled);
+  }
+  if (serverVoiceInput.voiceResponseEnabled !== undefined) {
+    result.responseEnabled = Boolean(serverVoiceInput.voiceResponseEnabled);
+  }
+  if (serverVoiceInput.languageMode !== undefined) {
+    result.languageMode = normalizeVoiceLanguageMode(serverVoiceInput.languageMode, fallbackLocale);
+  }
+
+  return result;
+}
+
+export function normalizeVoiceCommandSettings(raw = {}) {
+  let data = asObject(raw);
+  let sendDefaults = defaultSendCommandPhrases();
+  let wakeDefaults = defaultWakeCommandPhrases();
+  let actionDefaults = defaultVoiceActionCommandPhrases();
+  let savedSend = asObject(data.sendCommands);
+  let savedWake = asObject(data.wakeCommands);
+  let savedActions = asObject(data.actionCommands);
+  let legacySendCommand = String(data.sendCommand || '').trim();
+
+  let sendCommands = Object.fromEntries(
+    VOICE_LOCALES.map((locale) => {
+      let value = String(savedSend[locale] || (locale === 'en' ? legacySendCommand : '') || sendDefaults[locale]).trim();
+      return [locale, value || sendDefaults[locale]];
+    })
+  );
+
+  let wakeCommands = Object.fromEntries(
+    VOICE_LOCALES.map((locale) => [
+      locale,
+      normalizeWakeCommandPhrase(savedWake[locale] || wakeDefaults[locale], locale),
+    ])
+  );
+
+  let actionCommands = Object.fromEntries(
+    VOICE_ACTIONS.map((action) => {
+      let values = asObject(savedActions[action]);
+      return [
+        action,
+        Object.fromEntries(
+          VOICE_LOCALES.map((locale) => [
+            locale,
+            parseVoiceCommandList(values[locale], actionDefaults[action][locale]),
+          ])
+        ),
+      ];
+    })
+  );
+
+  return {
+    sendCommands,
+    wakeCommands,
+    actionCommands,
+  };
+}

package/cli.js

@@ -1,11 +1,22 @@
 #!/usr/bin/env node
 
+import { realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 
 import { cmdDiscover } from './discover.js';
 
 let command = process.argv[2] || 'discover';
-let isMain = fileURLToPath(import.meta.url) === process.argv[1];
+let modulePath = fileURLToPath(import.meta.url);
+let argvPath = process.argv[1] || '';
+let isMain = modulePath === argvPath;
+
+if (!isMain && argvPath) {
+  try {
+    isMain = modulePath === realpathSync(argvPath);
+  } catch (error) {
+    void error;
+  }
+}
 
 if (isMain && command === 'discover') {
   let result = await cmdDiscover({});

package/core/Node.js

@@ -16,7 +16,7 @@ export class Node {
    * @param {string} [options.id] - Custom ID (default: auto-generated)
    * @param {string} [options.type] - Node type identifier (e.g. 'ai/llm')
    * @param {string} [options.category] - Category for styling (server/instance/control)
-   * @param {string} [options.shape] - Shape name (rect/pill/circle/diamond/comment)
+   * @param {string} [options.shape] - Shape name (rect/pill/circle/disc/diamond/comment or registered SVG preset)
    * @param {string} [options.icon] - Material icon name for visual rendering
    */
   constructor(label, options = {}) {