@speechos/client 0.2.3 → 0.2.5

package/dist/index.cjs

@@ -4,6 +4,84 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
 var core = require('@speechos/core');
 
+/**
+ * Client configuration for SpeechOS
+ * Extends core config with UI/widget-specific options
+ */
+/**
+ * Default client configuration values
+ */
+const defaultClientConfig = {
+    commands: [],
+    zIndex: 999999,
+    alwaysVisible: false,
+};
+/**
+ * Current client configuration singleton
+ */
+let currentClientConfig = { ...defaultClientConfig };
+/**
+ * Validate and resolve client-specific config
+ * @param config - User-provided configuration
+ * @returns Resolved client configuration
+ */
+function validateClientConfig(config) {
+    const resolved = {
+        commands: config.commands ?? defaultClientConfig.commands,
+        zIndex: config.zIndex ?? defaultClientConfig.zIndex,
+        alwaysVisible: config.alwaysVisible ?? defaultClientConfig.alwaysVisible,
+    };
+    // Validate zIndex
+    if (typeof resolved.zIndex !== "number" || resolved.zIndex < 0) {
+        console.warn(`Invalid zIndex "${resolved.zIndex}". Using default ${defaultClientConfig.zIndex}.`);
+        resolved.zIndex = defaultClientConfig.zIndex;
+    }
+    return resolved;
+}
+/**
+ * Set the client configuration
+ * @param config - Client configuration to set
+ */
+function setClientConfig(config) {
+    currentClientConfig = validateClientConfig(config);
+}
+/**
+ * Get the current client configuration
+ */
+function getClientConfig() {
+    return { ...currentClientConfig };
+}
+/**
+ * Reset client configuration to defaults
+ */
+function resetClientConfig() {
+    currentClientConfig = { ...defaultClientConfig };
+}
+/**
+ * Check if commands are configured (for showing Command button in widget)
+ */
+function hasCommands() {
+    return currentClientConfig.commands.length > 0;
+}
+/**
+ * Get configured commands
+ */
+function getCommands() {
+    return [...currentClientConfig.commands];
+}
+/**
+ * Get widget z-index
+ */
+function getZIndex() {
+    return currentClientConfig.zIndex;
+}
+/**
+ * Check if widget should always be visible
+ */
+function isAlwaysVisible() {
+    return currentClientConfig.alwaysVisible;
+}
+
 /**
  * Form field focus detection for SpeechOS Client SDK
  * Detects when users focus on form fields and manages widget visibility
@@ -91,12 +169,12 @@ class FormDetector {
                         relatedTarget === widget);
                 // If focus is going to an element with data-speechos-no-close, don't hide
                 const goingToNoCloseElement = Boolean(relatedTarget?.closest("[data-speechos-no-close]"));
-                console.log("[SpeechOS] blurHandler:", {
-                    relatedTarget,
-                    goingToFormField,
-                    goingToWidget,
-                    goingToNoCloseElement,
-                });
+                // console.log("[SpeechOS] blurHandler:", {
+                //   relatedTarget,
+                //   goingToFormField,
+                //   goingToWidget,
+                //   goingToNoCloseElement,
+                // });
                 if (goingToFormField || goingToWidget || goingToNoCloseElement) {
                     console.log("[SpeechOS] blurHandler: early return, not hiding");
                     return;
@@ -115,11 +193,15 @@ class FormDetector {
                     // Check if focus is on an element with data-speechos-no-close
                     const isNoCloseElementFocused = Boolean(activeElement?.closest("[data-speechos-no-close]"));
                     // Only hide if no form field is focused AND widget isn't focused AND not a no-close element
+                    // AND alwaysVisible is not enabled
                     if (!isFormField(activeElement) &&
                         !isWidgetFocused &&
                         !isNoCloseElementFocused) {
                         core.state.setFocusedElement(null);
-                        core.state.hide();
+                        // Don't hide if alwaysVisible is enabled
+                        if (!isAlwaysVisible()) {
+                            core.state.hide();
+                        }
                         core.events.emit("form:blur", { element: null });
                     }
                 }, 150);
@@ -193,7 +275,10 @@ class FormDetector {
         // Reset state
         this.isWidgetBeingInteracted = false;
         core.state.setFocusedElement(null);
-        core.state.hide();
+        // Don't hide if alwaysVisible is enabled
+        if (!isAlwaysVisible()) {
+            core.state.hide();
+        }
         this.isActive = false;
     }
     /**
@@ -206,76 +291,6 @@ class FormDetector {
 // Export singleton instance
 const formDetector = new FormDetector();
 
-/**
- * Client configuration for SpeechOS
- * Extends core config with UI/widget-specific options
- */
-/**
- * Default client configuration values
- */
-const defaultClientConfig = {
-    commands: [],
-    zIndex: 999999,
-};
-/**
- * Current client configuration singleton
- */
-let currentClientConfig = { ...defaultClientConfig };
-/**
- * Validate and resolve client-specific config
- * @param config - User-provided configuration
- * @returns Resolved client configuration
- */
-function validateClientConfig(config) {
-    const resolved = {
-        commands: config.commands ?? defaultClientConfig.commands,
-        zIndex: config.zIndex ?? defaultClientConfig.zIndex,
-    };
-    // Validate zIndex
-    if (typeof resolved.zIndex !== "number" || resolved.zIndex < 0) {
-        console.warn(`Invalid zIndex "${resolved.zIndex}". Using default ${defaultClientConfig.zIndex}.`);
-        resolved.zIndex = defaultClientConfig.zIndex;
-    }
-    return resolved;
-}
-/**
- * Set the client configuration
- * @param config - Client configuration to set
- */
-function setClientConfig(config) {
-    currentClientConfig = validateClientConfig(config);
-}
-/**
- * Get the current client configuration
- */
-function getClientConfig() {
-    return { ...currentClientConfig };
-}
-/**
- * Reset client configuration to defaults
- */
-function resetClientConfig() {
-    currentClientConfig = { ...defaultClientConfig };
-}
-/**
- * Check if commands are configured (for showing Command button in widget)
- */
-function hasCommands() {
-    return currentClientConfig.commands.length > 0;
-}
-/**
- * Get configured commands
- */
-function getCommands() {
-    return [...currentClientConfig.commands];
-}
-/**
- * Get widget z-index
- */
-function getZIndex() {
-    return currentClientConfig.zIndex;
-}
-
 /**
  * Text input handler for SpeechOS Client SDK
  * Abstracts cursor/selection detection and text insertion/replacement operations
@@ -1480,6 +1495,11 @@ const loaderIcon = (size = 20) => {
   `;
     return b `${o(svgString)}`;
 };
+/**
+ * Check icon for "Keep" action
+ * Lucide Check icon paths
+ */
+const checkIcon = (size = 18) => createIcon('<path d="M20 6 9 17l-5-5"/>', size);
 /**
  * X icon for cancel action
  * Lucide X icon paths
@@ -1740,6 +1760,7 @@ let SpeechOSMicButton = class SpeechOSMicButton extends i$1 {
         this.activeAction = null;
         this.editPreviewText = "";
         this.errorMessage = null;
+        this.commandFeedback = null;
     }
     static { this.styles = [
         themeStyles,
@@ -2307,6 +2328,47 @@ let SpeechOSMicButton = class SpeechOSMicButton extends i$1 {
         }
       }
 
+      /* Command feedback badge - success state (amber/orange) */
+      .status-label.command-success {
+        background: linear-gradient(135deg, #f59e0b 0%, #d97706 100%);
+        box-shadow: 0 4px 12px rgba(245, 158, 11, 0.3);
+        padding-left: 24px;
+        animation: command-feedback-in 0.3s cubic-bezier(0.34, 1.56, 0.64, 1)
+          forwards;
+      }
+
+      .status-label.command-success::before {
+        content: "";
+        position: absolute;
+        top: 50%;
+        left: 8px;
+        width: 12px;
+        height: 12px;
+        transform: translateY(-50%);
+        background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 24 24' fill='none' stroke='white' stroke-width='3' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M20 6 9 17l-5-5'/%3E%3C/svg%3E");
+        background-repeat: no-repeat;
+        background-position: center;
+      }
+
+      /* Command feedback badge - no match state (neutral gray) */
+      .status-label.command-none {
+        background: #4b5563;
+        box-shadow: 0 4px 12px rgba(75, 85, 99, 0.3);
+        animation: command-feedback-in 0.3s cubic-bezier(0.34, 1.56, 0.64, 1)
+          forwards;
+      }
+
+      @keyframes command-feedback-in {
+        0% {
+          opacity: 0;
+          transform: translateX(-50%) scale(0.8) translateY(4px);
+        }
+        100% {
+          opacity: 1;
+          transform: translateX(-50%) scale(1) translateY(0);
+        }
+      }
+
       /* Cancel button - positioned to the right of the main mic button */
       .cancel-button {
         position: absolute;
@@ -2554,6 +2616,16 @@ let SpeechOSMicButton = class SpeechOSMicButton extends i$1 {
           left: 10px;
         }
 
+        .status-label.command-success {
+          padding-left: 30px;
+        }
+
+        .status-label.command-success::before {
+          left: 10px;
+          width: 14px;
+          height: 14px;
+        }
+
         .error-message {
           font-size: 15px;
           padding: 14px 18px;
@@ -2706,6 +2778,15 @@ let SpeechOSMicButton = class SpeechOSMicButton extends i$1 {
         }
         return this.recordingState;
     }
+    getCommandFeedbackLabel() {
+        if (this.commandFeedback === "success") {
+            return "Got it!";
+        }
+        if (this.commandFeedback === "none") {
+            return "No command matched";
+        }
+        return "";
+    }
     render() {
         const showPulse = this.recordingState === "recording";
         const showSiriConnecting = this.recordingState === "connecting";
@@ -2713,13 +2794,14 @@ let SpeechOSMicButton = class SpeechOSMicButton extends i$1 {
         const showSiriEdit = this.recordingState === "processing" && this.activeAction === "edit";
         const statusLabel = this.getStatusLabel();
         const showVisualizer = this.shouldShowVisualizer();
-        // Show status label during recording (either visualizer or edit text)
-        const showStatus = this.recordingState === "recording";
+        // Show status label during recording (either visualizer or edit text) OR command feedback
+        const showCommandFeedback = this.recordingState === "idle" && this.commandFeedback !== null;
+        const showStatus = this.recordingState === "recording" || showCommandFeedback;
         const showCancel = this.recordingState === "connecting" ||
             this.recordingState === "recording" ||
             this.recordingState === "processing";
         const showError = this.recordingState === "error" && this.errorMessage;
-        // Show close button in idle state (both solo mic and expanded)
+        // Show close button in idle state (both solo mic and expanded), including when showing command feedback
         const showClose = this.recordingState === "idle";
         return b `
       <div class="button-wrapper">
@@ -2765,15 +2847,19 @@ let SpeechOSMicButton = class SpeechOSMicButton extends i$1 {
         </button>
 
         <span
-          class="status-label ${showStatus ? "visible" : ""} ${showVisualizer
-            ? "visualizer"
-            : this.getStatusClass()}"
+          class="status-label ${showStatus ? "visible" : ""} ${showCommandFeedback
+            ? `command-${this.commandFeedback}`
+            : showVisualizer
+                ? "visualizer"
+                : this.getStatusClass()}"
         >
-          ${showVisualizer
-            ? b `<speechos-audio-visualizer
-                ?active="${showVisualizer}"
-              ></speechos-audio-visualizer>`
-            : statusLabel}
+          ${showCommandFeedback
+            ? this.getCommandFeedbackLabel()
+            : showVisualizer
+                ? b `<speechos-audio-visualizer
+                  ?active="${showVisualizer}"
+                ></speechos-audio-visualizer>`
+                : statusLabel}
         </span>
 
         <button
@@ -2814,6 +2900,9 @@ __decorate([
 __decorate([
     n({ type: String })
 ], SpeechOSMicButton.prototype, "errorMessage", void 0);
+__decorate([
+    n({ type: String })
+], SpeechOSMicButton.prototype, "commandFeedback", void 0);
 SpeechOSMicButton = __decorate([
     t$1("speechos-mic-button")
 ], SpeechOSMicButton);
@@ -5591,65 +5680,658 @@ SpeechOSSettingsModal = __decorate([
 ], SpeechOSSettingsModal);
 
 /**
- * Main widget container component
- * Composes mic button and action bubbles with state management
- */
-var SpeechOSWidget_1;
-/**
- * Minimum duration to show the connecting animation (in milliseconds).
- * Since mic capture starts almost instantly, we enforce a minimum animation
- * duration so users can see the visual feedback before transitioning to recording.
+ * Shared styles for lightweight popup modals
+ * Used by dictation-output-modal and edit-help-modal
  */
-const MIN_CONNECTING_ANIMATION_MS = 200;
-let SpeechOSWidget = class SpeechOSWidget extends i$1 {
-    constructor() {
-        super(...arguments);
-        this.widgetState = core.state.getState();
-        this.settingsOpen = false;
-        this.dictationTargetElement = null;
-        this.editTargetElement = null;
-        this.dictationCursorStart = null;
-        this.dictationCursorEnd = null;
-        this.editSelectionStart = null;
-        this.editSelectionEnd = null;
-        this.editSelectedText = "";
-        this.boundClickOutsideHandler = null;
-        this.modalElement = null;
-        this.customPosition = null;
-        this.isDragging = false;
-        this.dragStartPos = null;
-        this.dragOffset = { x: 0, y: 0 };
-        this.boundDragMove = null;
-        this.boundDragEnd = null;
-        this.suppressNextClick = false;
-        this.boundViewportResizeHandler = null;
-        this.boundScrollHandler = null;
-    }
-    static { SpeechOSWidget_1 = this; }
-    static { this.styles = [
-        themeStyles,
-        animations,
-        i$4 `
-      :host {
-        position: fixed;
-        bottom: var(--speechos-spacing-md); /* 12px - same as spacing above */
-        z-index: var(--speechos-z-base);
-        pointer-events: none;
-      }
-
-      :host {
-        left: 50%;
-        transform: translateX(-50%);
-      }
+/** Base popup modal styles - simpler than full settings modal */
+const popupModalStyles = i$4 `
+  :host {
+    position: fixed;
+    inset: 0;
+    pointer-events: none;
+    z-index: calc(var(--speechos-z-base) + 100);
+  }
 
-      :host(.custom-position) {
-        right: unset;
-        left: unset;
-        transform: none;
-      }
+  .modal-overlay {
+    position: fixed;
+    inset: 0;
+    background: rgba(0, 0, 0, 0.5);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    z-index: calc(var(--speechos-z-base) + 100);
+    opacity: 0;
+    visibility: hidden;
+    transition: all 0.2s ease;
+    pointer-events: none;
+    backdrop-filter: blur(4px);
+  }
 
-      :host(.anchored-to-element) {
-        position: absolute;
+  .modal-overlay.open {
+    opacity: 1;
+    visibility: visible;
+    pointer-events: auto;
+  }
+
+  .modal-card {
+    background: #1a1d24;
+    border-radius: 16px;
+    width: 90%;
+    max-width: 400px;
+    display: flex;
+    flex-direction: column;
+    box-shadow: 0 24px 48px rgba(0, 0, 0, 0.4),
+      0 0 0 1px rgba(255, 255, 255, 0.05);
+    transform: scale(0.95) translateY(10px);
+    transition: transform 0.25s cubic-bezier(0.16, 1, 0.3, 1);
+    pointer-events: auto;
+    overflow: hidden;
+  }
+
+  .modal-overlay.open .modal-card {
+    transform: scale(1) translateY(0);
+  }
+
+  .modal-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 16px 20px;
+    border-bottom: 1px solid rgba(255, 255, 255, 0.06);
+    background: rgba(0, 0, 0, 0.2);
+  }
+
+  .modal-title {
+    font-size: 16px;
+    font-weight: 600;
+    color: white;
+    margin: 0;
+    letter-spacing: -0.01em;
+  }
+
+  .close-button {
+    width: 32px;
+    height: 32px;
+    border-radius: 8px;
+    background: transparent;
+    border: none;
+    cursor: pointer;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    color: rgba(255, 255, 255, 0.5);
+    transition: all 0.15s ease;
+  }
+
+  .close-button:hover {
+    background: rgba(255, 255, 255, 0.08);
+    color: white;
+  }
+
+  .modal-body {
+    padding: 20px;
+  }
+
+  .modal-footer {
+    display: flex;
+    justify-content: flex-end;
+    gap: 10px;
+    padding: 16px 20px;
+    border-top: 1px solid rgba(255, 255, 255, 0.06);
+    background: rgba(0, 0, 0, 0.1);
+  }
+
+  .btn {
+    padding: 10px 18px;
+    border-radius: 8px;
+    font-size: 13px;
+    font-weight: 600;
+    cursor: pointer;
+    transition: all 0.15s ease;
+    border: none;
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+  }
+
+  .btn-secondary {
+    background: rgba(255, 255, 255, 0.08);
+    color: rgba(255, 255, 255, 0.8);
+  }
+
+  .btn-secondary:hover {
+    background: rgba(255, 255, 255, 0.12);
+    color: white;
+  }
+
+  .btn-primary {
+    background: linear-gradient(135deg, #10b981 0%, #059669 100%);
+    color: white;
+    box-shadow: 0 2px 8px rgba(16, 185, 129, 0.2);
+  }
+
+  .btn-primary:hover {
+    transform: translateY(-1px);
+    box-shadow: 0 4px 12px rgba(16, 185, 129, 0.3);
+  }
+
+  .btn-primary:active {
+    transform: translateY(0);
+  }
+
+  /* Success state for copy button */
+  .btn-success {
+    background: linear-gradient(135deg, #34d399 0%, #10b981 100%);
+  }
+
+  /* Text display area */
+  .text-display {
+    background: rgba(0, 0, 0, 0.3);
+    border: 1px solid rgba(255, 255, 255, 0.08);
+    border-radius: 10px;
+    padding: 14px 16px;
+    color: white;
+    font-size: 14px;
+    line-height: 1.5;
+    max-height: 200px;
+    overflow-y: auto;
+    white-space: pre-wrap;
+    word-break: break-word;
+  }
+
+  /* Scrollbar styling */
+  .text-display::-webkit-scrollbar {
+    width: 6px;
+  }
+
+  .text-display::-webkit-scrollbar-track {
+    background: transparent;
+  }
+
+  .text-display::-webkit-scrollbar-thumb {
+    background: rgba(255, 255, 255, 0.15);
+    border-radius: 3px;
+  }
+
+  .text-display::-webkit-scrollbar-thumb:hover {
+    background: rgba(255, 255, 255, 0.25);
+  }
+
+  /* Instruction list styling */
+  .instruction-list {
+    list-style: none;
+    padding: 0;
+    margin: 0;
+  }
+
+  .instruction-item {
+    display: flex;
+    align-items: flex-start;
+    gap: 12px;
+    padding: 12px 0;
+    border-bottom: 1px solid rgba(255, 255, 255, 0.06);
+  }
+
+  .instruction-item:last-child {
+    border-bottom: none;
+  }
+
+  .instruction-number {
+    width: 24px;
+    height: 24px;
+    border-radius: 50%;
+    background: linear-gradient(135deg, #10b981 0%, #059669 100%);
+    color: white;
+    font-size: 12px;
+    font-weight: 700;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    flex-shrink: 0;
+  }
+
+  .instruction-text {
+    font-size: 14px;
+    color: rgba(255, 255, 255, 0.85);
+    line-height: 1.5;
+    padding-top: 2px;
+  }
+
+  /* Mobile adjustments */
+  @media (max-width: 480px) {
+    .modal-card {
+      width: 95%;
+      max-width: none;
+      border-radius: 12px;
+    }
+
+    .modal-header {
+      padding: 14px 16px;
+    }
+
+    .modal-body {
+      padding: 16px;
+    }
+
+    .modal-footer {
+      padding: 14px 16px;
+    }
+
+    .modal-title {
+      font-size: 15px;
+    }
+  }
+`;
+
+/**
+ * Dictation output modal component
+ * Displays transcribed text with copy functionality when no field is focused
+ */
+let SpeechOSDictationOutputModal = class SpeechOSDictationOutputModal extends i$1 {
+    constructor() {
+        super(...arguments);
+        this.open = false;
+        this.text = "";
+        this.copied = false;
+        this.copyTimeout = null;
+    }
+    static { this.styles = [
+        themeStyles,
+        popupModalStyles,
+        i$4 `
+      .header-content {
+        display: flex;
+        align-items: center;
+        gap: 12px;
+      }
+
+      .logo-icon {
+        width: 32px;
+        height: 32px;
+        border-radius: 8px;
+        background: linear-gradient(135deg, #10b981 0%, #8b5cf6 100%);
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        flex-shrink: 0;
+      }
+
+      .logo-icon svg {
+        width: 18px;
+        height: 18px;
+        color: white;
+      }
+
+      .modal-title {
+        background: linear-gradient(135deg, #34d399 0%, #a78bfa 100%);
+        -webkit-background-clip: text;
+        -webkit-text-fill-color: transparent;
+        background-clip: text;
+      }
+
+      .btn-primary {
+        background: linear-gradient(135deg, #10b981 0%, #059669 100%);
+        box-shadow: 0 4px 12px rgba(16, 185, 129, 0.3);
+        border-radius: 999px;
+      }
+
+      .btn-primary:hover {
+        background: linear-gradient(135deg, #34d399 0%, #10b981 100%);
+        transform: translateY(-2px);
+        box-shadow: 0 6px 16px rgba(16, 185, 129, 0.4);
+      }
+
+      .btn-primary:active {
+        transform: translateY(0);
+      }
+
+      .btn-success {
+        background: linear-gradient(135deg, #34d399 0%, #10b981 100%);
+        box-shadow: 0 4px 12px rgba(52, 211, 153, 0.3);
+        border-radius: 999px;
+      }
+
+      .btn-secondary {
+        border-radius: 999px;
+      }
+
+      .hint {
+        display: flex;
+        align-items: center;
+        gap: 6px;
+        margin-top: 12px;
+        padding: 8px 12px;
+        background: rgba(16, 185, 129, 0.08);
+        border-radius: 8px;
+        font-size: 12px;
+        color: rgba(255, 255, 255, 0.6);
+      }
+
+      .hint-icon {
+        color: #10b981;
+        flex-shrink: 0;
+      }
+    `,
+    ]; }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        if (this.copyTimeout) {
+            clearTimeout(this.copyTimeout);
+            this.copyTimeout = null;
+        }
+    }
+    updated(changedProperties) {
+        if (changedProperties.has("open")) {
+            if (!this.open) {
+                // Reset copied state when modal closes
+                this.copied = false;
+                if (this.copyTimeout) {
+                    clearTimeout(this.copyTimeout);
+                    this.copyTimeout = null;
+                }
+            }
+        }
+    }
+    handleOverlayClick(e) {
+        if (e.target === e.currentTarget) {
+            this.close();
+        }
+    }
+    handleClose() {
+        this.close();
+    }
+    close() {
+        this.dispatchEvent(new CustomEvent("modal-close", {
+            bubbles: true,
+            composed: true,
+        }));
+    }
+    async handleCopy() {
+        try {
+            await navigator.clipboard.writeText(this.text);
+            this.copied = true;
+            // Reset copied state after 2 seconds
+            if (this.copyTimeout) {
+                clearTimeout(this.copyTimeout);
+            }
+            this.copyTimeout = window.setTimeout(() => {
+                this.copied = false;
+                this.copyTimeout = null;
+            }, 2000);
+        }
+        catch (err) {
+            console.error("[SpeechOS] Failed to copy text:", err);
+        }
+    }
+    render() {
+        return b `
+      <div
+        class="modal-overlay ${this.open ? "open" : ""}"
+        @click="${this.handleOverlayClick}"
+      >
+        <div class="modal-card">
+          <div class="modal-header">
+            <div class="header-content">
+              <div class="logo-icon">${micIcon(18)}</div>
+              <h2 class="modal-title">Dictation Complete</h2>
+            </div>
+            <button
+              class="close-button"
+              @click="${this.handleClose}"
+              aria-label="Close"
+            >
+              ${xIcon(16)}
+            </button>
+          </div>
+
+          <div class="modal-body">
+            <div class="text-display">${this.text}</div>
+            <div class="hint">
+              <svg class="hint-icon" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+                <circle cx="12" cy="12" r="10"/><path d="M12 16v-4M12 8h.01"/>
+              </svg>
+              <span>Tip: Focus a text field first to auto-insert next time</span>
+            </div>
+          </div>
+
+          <div class="modal-footer">
+            <button
+              class="btn ${this.copied ? "btn-success" : "btn-primary"}"
+              @click="${this.handleCopy}"
+            >
+              ${this.copied ? checkIcon(16) : copyIcon(16)}
+              ${this.copied ? "Copied!" : "Copy"}
+            </button>
+            <button class="btn btn-secondary" @click="${this.handleClose}">
+              Done
+            </button>
+          </div>
+        </div>
+      </div>
+    `;
+    }
+};
+__decorate([
+    n({ type: Boolean })
+], SpeechOSDictationOutputModal.prototype, "open", void 0);
+__decorate([
+    n({ type: String })
+], SpeechOSDictationOutputModal.prototype, "text", void 0);
+__decorate([
+    r()
+], SpeechOSDictationOutputModal.prototype, "copied", void 0);
+SpeechOSDictationOutputModal = __decorate([
+    t$1("speechos-dictation-output-modal")
+], SpeechOSDictationOutputModal);
+
+/**
+ * Edit help modal component
+ * Displays usage instructions for the edit feature when no text is selected
+ */
+let SpeechOSEditHelpModal = class SpeechOSEditHelpModal extends i$1 {
+    constructor() {
+        super(...arguments);
+        this.open = false;
+    }
+    static { this.styles = [
+        themeStyles,
+        popupModalStyles,
+        i$4 `
+      .header-content {
+        display: flex;
+        align-items: center;
+        gap: 12px;
+      }
+
+      .logo-icon {
+        width: 32px;
+        height: 32px;
+        border-radius: 8px;
+        background: linear-gradient(135deg, #8b5cf6 0%, #6366f1 100%);
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        flex-shrink: 0;
+      }
+
+      .logo-icon svg {
+        width: 18px;
+        height: 18px;
+        color: white;
+      }
+
+      .modal-title {
+        background: linear-gradient(135deg, #a78bfa 0%, #818cf8 100%);
+        -webkit-background-clip: text;
+        -webkit-text-fill-color: transparent;
+        background-clip: text;
+      }
+
+      .instruction-number {
+        background: linear-gradient(135deg, #8b5cf6 0%, #6366f1 100%);
+      }
+
+      .btn-primary {
+        background: linear-gradient(135deg, #8b5cf6 0%, #7c3aed 100%);
+        box-shadow: 0 4px 12px rgba(139, 92, 246, 0.3);
+        border-radius: 999px;
+      }
+
+      .btn-primary:hover {
+        background: linear-gradient(135deg, #a78bfa 0%, #8b5cf6 100%);
+        transform: translateY(-2px);
+        box-shadow: 0 6px 16px rgba(139, 92, 246, 0.4);
+      }
+
+      .btn-primary:active {
+        transform: translateY(0);
+      }
+    `,
+    ]; }
+    handleOverlayClick(e) {
+        if (e.target === e.currentTarget) {
+            this.close();
+        }
+    }
+    handleClose() {
+        this.close();
+    }
+    close() {
+        this.dispatchEvent(new CustomEvent("modal-close", {
+            bubbles: true,
+            composed: true,
+        }));
+    }
+    render() {
+        return b `
+      <div
+        class="modal-overlay ${this.open ? "open" : ""}"
+        @click="${this.handleOverlayClick}"
+      >
+        <div class="modal-card">
+          <div class="modal-header">
+            <div class="header-content">
+              <div class="logo-icon">${editIcon(18)}</div>
+              <h2 class="modal-title">How to Use Edit</h2>
+            </div>
+            <button
+              class="close-button"
+              @click="${this.handleClose}"
+              aria-label="Close"
+            >
+              ${xIcon(16)}
+            </button>
+          </div>
+
+          <div class="modal-body">
+            <ol class="instruction-list">
+              <li class="instruction-item">
+                <span class="instruction-number">1</span>
+                <span class="instruction-text">
+                  Click on a text field to focus it, or select the text you want
+                  to edit
+                </span>
+              </li>
+              <li class="instruction-item">
+                <span class="instruction-number">2</span>
+                <span class="instruction-text">
+                  Click the Edit button in the SpeechOS widget
+                </span>
+              </li>
+              <li class="instruction-item">
+                <span class="instruction-number">3</span>
+                <span class="instruction-text">
+                  Speak your editing instructions (e.g., "make it more formal"
+                  or "fix the grammar")
+                </span>
+              </li>
+            </ol>
+          </div>
+
+          <div class="modal-footer">
+            <button class="btn btn-primary" @click="${this.handleClose}">
+              Got it
+            </button>
+          </div>
+        </div>
+      </div>
+    `;
+    }
+};
+__decorate([
+    n({ type: Boolean })
+], SpeechOSEditHelpModal.prototype, "open", void 0);
+SpeechOSEditHelpModal = __decorate([
+    t$1("speechos-edit-help-modal")
+], SpeechOSEditHelpModal);
+
+/**
+ * Main widget container component
+ * Composes mic button and action bubbles with state management
+ */
+var SpeechOSWidget_1;
+/**
+ * Minimum duration to show the connecting animation (in milliseconds).
+ * Since mic capture starts almost instantly, we enforce a minimum animation
+ * duration so users can see the visual feedback before transitioning to recording.
+ */
+const MIN_CONNECTING_ANIMATION_MS = 200;
+let SpeechOSWidget = class SpeechOSWidget extends i$1 {
+    constructor() {
+        super(...arguments);
+        this.widgetState = core.state.getState();
+        this.settingsOpen = false;
+        this.dictationModalOpen = false;
+        this.dictationModalText = "";
+        this.editHelpModalOpen = false;
+        this.commandFeedback = null;
+        this.dictationTargetElement = null;
+        this.editTargetElement = null;
+        this.dictationCursorStart = null;
+        this.dictationCursorEnd = null;
+        this.editSelectionStart = null;
+        this.editSelectionEnd = null;
+        this.editSelectedText = "";
+        this.boundClickOutsideHandler = null;
+        this.modalElement = null;
+        this.dictationModalElement = null;
+        this.editHelpModalElement = null;
+        this.commandFeedbackTimeout = null;
+        this.customPosition = null;
+        this.isDragging = false;
+        this.dragStartPos = null;
+        this.dragOffset = { x: 0, y: 0 };
+        this.boundDragMove = null;
+        this.boundDragEnd = null;
+        this.suppressNextClick = false;
+        this.boundViewportResizeHandler = null;
+        this.boundScrollHandler = null;
+    }
+    static { SpeechOSWidget_1 = this; }
+    static { this.styles = [
+        themeStyles,
+        animations,
+        i$4 `
+      :host {
+        position: fixed;
+        bottom: var(--speechos-spacing-md); /* 12px - same as spacing above */
+        z-index: var(--speechos-z-base);
+        pointer-events: none;
+      }
+
+      :host {
+        left: 50%;
+        transform: translateX(-50%);
+      }
+
+      :host(.custom-position) {
+        right: unset;
+        left: unset;
+        transform: none;
+      }
+
+      :host(.anchored-to-element) {
+        position: absolute;
         bottom: unset;
         right: unset;
         left: unset;
@@ -5708,6 +6390,18 @@ let SpeechOSWidget = class SpeechOSWidget extends i$1 {
             this.settingsOpen = false;
         });
         document.body.appendChild(this.modalElement);
+        // Mount dictation output modal
+        this.dictationModalElement = document.createElement("speechos-dictation-output-modal");
+        this.dictationModalElement.addEventListener("modal-close", () => {
+            this.dictationModalOpen = false;
+        });
+        document.body.appendChild(this.dictationModalElement);
+        // Mount edit help modal
+        this.editHelpModalElement = document.createElement("speechos-edit-help-modal");
+        this.editHelpModalElement.addEventListener("modal-close", () => {
+            this.editHelpModalOpen = false;
+        });
+        document.body.appendChild(this.editHelpModalElement);
         this.stateUnsubscribe = core.state.subscribe((newState) => {
             if (!newState.isVisible || !newState.isExpanded) {
                 this.settingsOpen = false;
@@ -5747,6 +6441,18 @@ let SpeechOSWidget = class SpeechOSWidget extends i$1 {
             this.modalElement.remove();
             this.modalElement = null;
         }
+        if (this.dictationModalElement) {
+            this.dictationModalElement.remove();
+            this.dictationModalElement = null;
+        }
+        if (this.editHelpModalElement) {
+            this.editHelpModalElement.remove();
+            this.editHelpModalElement = null;
+        }
+        if (this.commandFeedbackTimeout) {
+            clearTimeout(this.commandFeedbackTimeout);
+            this.commandFeedbackTimeout = null;
+        }
         if (this.stateUnsubscribe) {
             this.stateUnsubscribe();
         }
@@ -5778,6 +6484,15 @@ let SpeechOSWidget = class SpeechOSWidget extends i$1 {
         if (changedProperties.has("settingsOpen") && this.modalElement) {
             this.modalElement.open = this.settingsOpen;
         }
+        if (changedProperties.has("dictationModalOpen") && this.dictationModalElement) {
+            this.dictationModalElement.open = this.dictationModalOpen;
+        }
+        if (changedProperties.has("dictationModalText") && this.dictationModalElement) {
+            this.dictationModalElement.text = this.dictationModalText;
+        }
+        if (changedProperties.has("editHelpModalOpen") && this.editHelpModalElement) {
+            this.editHelpModalElement.open = this.editHelpModalOpen;
+        }
     }
     handleClickOutside(event) {
         const target = event.target;
@@ -5816,7 +6531,10 @@ let SpeechOSWidget = class SpeechOSWidget extends i$1 {
         }
         if (!clickedInWidget) {
             core.getBackend().stopAutoRefresh?.();
-            core.state.hide();
+            // Don't hide if alwaysVisible is enabled
+            if (!isAlwaysVisible()) {
+                core.state.hide();
+            }
         }
     }
     isFormField(element) {
@@ -5937,6 +6655,8 @@ let SpeechOSWidget = class SpeechOSWidget extends i$1 {
             return;
         }
         if (this.widgetState.recordingState === "idle") {
+            // Clear command feedback on any mic click
+            this.clearCommandFeedback();
             // If we're expanding, prefetch the token to reduce latency when user selects an action
             if (!this.widgetState.isExpanded) {
                 // Fire and forget - we don't need to wait for this (LiveKit only)
@@ -5965,12 +6685,19 @@ let SpeechOSWidget = class SpeechOSWidget extends i$1 {
         }
         else {
             core.state.stopRecording();
-            core.getConfig();
             const backend = core.getBackend();
             try {
                 const transcription = await this.withMinDisplayTime(backend.stopVoiceSession(), 300);
                 if (transcription) {
-                    this.insertTranscription(transcription);
+                    // Check if we have a target element to insert into
+                    if (this.dictationTargetElement) {
+                        this.insertTranscription(transcription);
+                    }
+                    else {
+                        // No target element - show dictation output modal
+                        this.dictationModalText = transcription;
+                        this.dictationModalOpen = true;
+                    }
                     transcriptStore.saveTranscript(transcription, "dictate");
                 }
                 core.state.completeRecording();
@@ -6018,6 +6745,7 @@ let SpeechOSWidget = class SpeechOSWidget extends i$1 {
         }
     }
     handleCloseWidget() {
+        this.clearCommandFeedback();
         core.getBackend().stopAutoRefresh?.();
         core.state.hide();
     }
@@ -6145,11 +6873,20 @@ let SpeechOSWidget = class SpeechOSWidget extends i$1 {
     }
     handleActionSelect(event) {
         const { action } = event.detail;
+        // Clear any existing command feedback when a new action is selected
+        this.clearCommandFeedback();
         core.state.setActiveAction(action);
         if (action === "dictate") {
             this.startDictation();
         }
         else if (action === "edit") {
+            // Check if there's a focused element before starting edit
+            if (!this.widgetState.focusedElement) {
+                // No focused element - show edit help modal
+                this.editHelpModalOpen = true;
+                core.state.setActiveAction(null);
+                return;
+            }
             this.startEdit();
         }
         else if (action === "command") {
@@ -6356,6 +7093,10 @@ let SpeechOSWidget = class SpeechOSWidget extends i$1 {
             // Note: command:complete event is already emitted by the backend
             // when the command_result message is received, so we don't emit here
             core.state.completeRecording();
+            // Keep widget visible but collapsed (just mic button, no action bubbles)
+            core.state.setState({ isExpanded: false });
+            // Show command feedback
+            this.showCommandFeedback(result ? "success" : "none");
             backend.disconnect().catch(() => { });
             // Start auto-refresh to keep token fresh for subsequent commands (LiveKit only)
             backend.startAutoRefresh?.();
@@ -6368,6 +7109,25 @@ let SpeechOSWidget = class SpeechOSWidget extends i$1 {
             }
         }
     }
+    showCommandFeedback(feedback) {
+        this.commandFeedback = feedback;
+        // Clear any existing timeout
+        if (this.commandFeedbackTimeout) {
+            clearTimeout(this.commandFeedbackTimeout);
+        }
+        // Auto-dismiss after 4 seconds
+        this.commandFeedbackTimeout = window.setTimeout(() => {
+            this.commandFeedback = null;
+            this.commandFeedbackTimeout = null;
+        }, 4000);
+    }
+    clearCommandFeedback() {
+        if (this.commandFeedbackTimeout) {
+            clearTimeout(this.commandFeedbackTimeout);
+            this.commandFeedbackTimeout = null;
+        }
+        this.commandFeedback = null;
+    }
     supportsSelection(element) {
         if (element.tagName.toLowerCase() === "textarea") {
             return true;
@@ -6485,6 +7245,7 @@ let SpeechOSWidget = class SpeechOSWidget extends i$1 {
             activeAction="${this.widgetState.activeAction || ""}"
             editPreviewText="${this.editSelectedText}"
             errorMessage="${this.widgetState.errorMessage || ""}"
+            .commandFeedback="${this.commandFeedback}"
             @mic-click="${this.handleMicClick}"
             @stop-recording="${this.handleStopRecording}"
             @cancel-operation="${this.handleCancelOperation}"
@@ -6502,6 +7263,18 @@ __decorate([
 __decorate([
     r()
 ], SpeechOSWidget.prototype, "settingsOpen", void 0);
+__decorate([
+    r()
+], SpeechOSWidget.prototype, "dictationModalOpen", void 0);
+__decorate([
+    r()
+], SpeechOSWidget.prototype, "dictationModalText", void 0);
+__decorate([
+    r()
+], SpeechOSWidget.prototype, "editHelpModalOpen", void 0);
+__decorate([
+    r()
+], SpeechOSWidget.prototype, "commandFeedback", void 0);
 SpeechOSWidget = SpeechOSWidget_1 = __decorate([
     t$1("speechos-widget")
 ], SpeechOSWidget);
@@ -6582,6 +7355,10 @@ class SpeechOS {
         }
         // Create and mount widget
         this.mountWidget();
+        // If alwaysVisible is enabled, show the widget immediately
+        if (isAlwaysVisible()) {
+            core.state.show();
+        }
         this.isInitialized = true;
         // Log initialization in debug mode
         if (finalConfig.debug) {