@myscheme/voice-navigation-sdk 0.1.3 → 0.1.5

package/README.md

@@ -11,7 +11,9 @@ A TypeScript SDK for voice-controlled navigation using Azure Speech-to-Text and
 - 🖱️ **Rich browser and media controls**
 - ♿ **Accessibility-first design**
 - 🎨 **Customizable floating UI** control
-- 📦 **Full TypeScript support**
+- � **Flexible button options** - use default or your own custom button
+- 📍 **Configurable button placement** - position the default button anywhere
+- �📦 **Full TypeScript support**
 - 🔄 **Reusable across multiple websites**
 - 🔍 **Vector search integration** with OpenSearch
 
@@ -94,6 +96,7 @@ const controller = initNavigationOnMicrophone({
 | `actionHandlers`        | `object`  | ❌       | Custom action callbacks                        |
 | `pages`                 | `object`  | ❌       | Dynamic page navigation configuration          |
 | `opensearch`            | `object`  | ❌       | OpenSearch vector search configuration         |
+| `ui`                    | `object`  | ❌       | UI customization (button placement & style)    |
 
 ### OpenSearch Configuration
 
@@ -112,6 +115,252 @@ When providing the optional `opensearch` block:
 | `sourceFields`  | `string[]` | ❌       | Source fields to retrieve                                       |
 | `apiPath`       | `string`   | ❌       | Proxy endpoint (default: `/api/voice-navigation/vector-search`) |
 
+### UI Configuration
+
+The library provides flexible button options - use the default floating button or integrate with your own custom button.
+
+#### Configuration Options
+
+| Property               | Type              | Required | Description                                                   |
+| ---------------------- | ----------------- | -------- | ------------------------------------------------------------- |
+| `showDefaultButton`    | `boolean`         | ❌       | Show library's default button (default: `true`)               |
+| `customButtonSelector` | `string`          | ❌       | CSS selector for your custom button (e.g., `"#my-voice-btn"`) |
+| `buttonPlacement`      | `ButtonPlacement` | ❌       | Position of default button (default: `"bottom-right"`)        |
+
+**ButtonPlacement** options: `"bottom-right"` \| `"bottom-left"` \| `"top-right"` \| `"top-left"` \| `"center-right"` \| `"center-left"`
+
+#### Option 1: Default Button with Custom Placement
+
+Use the library's pre-styled floating button at different positions:
+
+```typescript
+const controller = initNavigationOnMicrophone({
+  azure: {
+    /* ... */
+  },
+  aws: {
+    /* ... */
+  },
+
+  // Place button at top-left corner
+  ui: {
+    showDefaultButton: true,
+    buttonPlacement: "top-left",
+  },
+});
+```
+
+**Available placements:**
+
+- `"bottom-right"` (default) - Bottom right corner
+- `"bottom-left"` - Bottom left corner
+- `"top-right"` - Top right corner
+- `"top-left"` - Top left corner
+- `"center-right"` - Vertically centered on right
+- `"center-left"` - Vertically centered on left
+
+#### Option 2: Custom Button
+
+Use your own button design and have the library attach voice control functionality to it:
+
+**1. Create your button in HTML:**
+
+```html
+<button id="my-voice-button" class="my-custom-style">
+  <span>🎤 Voice Control</span>
+</button>
+```
+
+**2. Configure the SDK to use your button:**
+
+```typescript
+const controller = initNavigationOnMicrophone({
+  azure: {
+    /* ... */
+  },
+  aws: {
+    /* ... */
+  },
+
+  ui: {
+    showDefaultButton: false,
+    customButtonSelector: "#my-voice-button",
+  },
+});
+```
+
+**Important Notes for Custom Buttons:**
+
+- **Button must exist in DOM before SDK initialization** - Add the SDK initialization code after your button is rendered, or use `DOMContentLoaded` event
+- The library will automatically add `aria-pressed` and `aria-label` attributes for accessibility
+- The button can be any clickable element (button, div, etc.)
+- The library handles all click events and state management
+- Visual feedback panel will display near the button when voice control is active
+- You are responsible for styling the button (pressed, disabled, etc.) based on your design requirements
+
+**React Example with Custom Button:**
+
+```tsx
+import { useEffect, useRef } from "react";
+import { initNavigationOnMicrophone } from "@myscheme/voice-navigation-sdk";
+
+export default function VoiceNavigationProvider() {
+  const controllerRef = useRef(null);
+
+  useEffect(() => {
+    // Initialize after button is rendered
+    controllerRef.current = initNavigationOnMicrophone({
+      azure: {
+        subscriptionKey: process.env.NEXT_PUBLIC_AZURE_SPEECH_KEY!,
+        region: process.env.NEXT_PUBLIC_AZURE_SPEECH_REGION!,
+      },
+      aws: {
+        accessKeyId: process.env.NEXT_PUBLIC_AWS_ACCESS_KEY_ID!,
+        secretAccessKey: process.env.NEXT_PUBLIC_AWS_SECRET_ACCESS_KEY!,
+        modelId: "anthropic.claude-3-sonnet-20240229-v1:0",
+        region: "ap-south-1",
+      },
+      ui: {
+        showDefaultButton: false,
+        customButtonSelector: "#voice-control-btn",
+      },
+    });
+
+    return () => controllerRef.current?.destroy();
+  }, []);
+
+  return (
+    <button
+      id="voice-control-btn"
+      className="px-4 py-2 bg-blue-600 text-white rounded-full hover:bg-blue-700"
+    >
+      🎤 Voice Control
+    </button>
+  );
+}
+```
+
+**Next.js App Router Example:**
+
+```tsx
+// app/components/voice-button.tsx
+"use client";
+
+export default function VoiceButton() {
+  return (
+    <button
+      id="voice-nav-button"
+      className="fixed bottom-4 right-4 w-16 h-16 rounded-full bg-gradient-to-r from-purple-500 to-pink-500 text-white shadow-lg hover:scale-110 transition-transform"
+      aria-label="Activate voice navigation"
+    >
+      🎤
+    </button>
+  );
+}
+
+// app/providers/voice-navigation.tsx
+("use client");
+
+import { useEffect } from "react";
+import { initNavigationOnMicrophone } from "@myscheme/voice-navigation-sdk";
+
+export default function VoiceNavigationProvider() {
+  useEffect(() => {
+    const controller = initNavigationOnMicrophone({
+      azure: {
+        /* ... */
+      },
+      aws: {
+        /* ... */
+      },
+      ui: {
+        showDefaultButton: false,
+        customButtonSelector: "#voice-nav-button",
+      },
+    });
+
+    return () => controller.destroy();
+  }, []);
+
+  return null;
+}
+
+// app/layout.tsx
+import VoiceButton from "./components/voice-button";
+import VoiceNavigationProvider from "./providers/voice-navigation";
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <VoiceButton />
+        <VoiceNavigationProvider />
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+**Vanilla JavaScript Example:**
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <style>
+      .voice-btn {
+        position: fixed;
+        bottom: 20px;
+        right: 20px;
+        width: 60px;
+        height: 60px;
+        border-radius: 50%;
+        background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+        color: white;
+        border: none;
+        cursor: pointer;
+        font-size: 24px;
+        box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3);
+        transition: transform 0.2s;
+      }
+
+      .voice-btn:hover {
+        transform: scale(1.1);
+      }
+
+      .voice-btn:active {
+        transform: scale(0.95);
+      }
+    </style>
+  </head>
+  <body>
+    <button id="voice-control" class="voice-btn">🎤</button>
+
+    <script type="module">
+      import { initNavigationOnMicrophone } from "@myscheme/voice-navigation-sdk";
+
+      const controller = initNavigationOnMicrophone({
+        azure: {
+          subscriptionKey: "your-key",
+          region: "your-region",
+        },
+        aws: {
+          accessKeyId: "your-key",
+          secretAccessKey: "your-secret",
+          modelId: "anthropic.claude-3-sonnet-20240229-v1:0",
+          region: "ap-south-1",
+        },
+        ui: {
+          showDefaultButton: false,
+          customButtonSelector: "#voice-control",
+        },
+      });
+    </script>
+  </body>
+</html>
+```
+
 ## 🌐 Dynamic Page Navigation
 
 Instead of hardcoding page navigation, configure pages dynamically using XML or direct configuration.

package/dist/actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,gBAAgB,EAEhB,aAAa,EACb,YAAY,EACZ,mBAAmB,EACpB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAsChE,eAAO,MAAM,eAAe,GAAI,UAAU,YAAY,KAAG,IAOxD,CAAC;AAKF,eAAO,MAAM,eAAe,QAAO,YAAY,GAAG,IAEjD,CAAC;AAkCF,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,KAAG,MAS5C,CAAC;AAKF,eAAO,MAAM,UAAU,GAAI,OAAO,MAAM,KAAG,MAM1C,CAAC;AAKF,eAAO,MAAM,iBAAiB,GAAI,QAAQ,MAAM,KAAG,MAElD,CAAC;AAKF,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,gBAAgB,EACxB,UAAS,aAAkB,KAC1B,YA4VF,CAAC;AAKF,eAAO,MAAM,kBAAkB,GAAI,QAAQ,GAAG,KAAG,mBAAmB,GAAG,IAiCtE,CAAC;AAKF,eAAO,MAAM,eAAe,GAAI,QAAQ,MAAM,KAAG,MAAM,IAAI,gBAY1D,CAAC"}
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,gBAAgB,EAEhB,aAAa,EACb,YAAY,EACZ,mBAAmB,EACpB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAyDhE,eAAO,MAAM,eAAe,GAAI,UAAU,YAAY,KAAG,IAOxD,CAAC;AAKF,eAAO,MAAM,eAAe,QAAO,YAAY,GAAG,IAEjD,CAAC;AAkCF,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,KAAG,MAS5C,CAAC;AAKF,eAAO,MAAM,UAAU,GAAI,OAAO,MAAM,KAAG,MAM1C,CAAC;AAKF,eAAO,MAAM,iBAAiB,GAAI,QAAQ,MAAM,KAAG,MAElD,CAAC;AAKF,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,gBAAgB,EACxB,UAAS,aAAkB,KAC1B,YA4yBF,CAAC;AAKF,eAAO,MAAM,kBAAkB,GAAI,QAAQ,GAAG,KAAG,mBAAmB,GAAG,IAiCtE,CAAC;AAKF,eAAO,MAAM,eAAe,GAAI,QAAQ,MAAM,KAAG,MAAM,IAAI,gBAY1D,CAAC"}

package/dist/actions.js

@@ -25,6 +25,25 @@ const CORE_ACTIONS = new Set([
     "unmute_media",
     "search_content",
     "stop",
+    "quit",
+    "tab_next",
+    "tab_back",
+    "click",
+    "enter",
+    "submit",
+    "move_left",
+    "move_right",
+    "move_up",
+    "move_down",
+    "move_beginning",
+    "move_end",
+    "select_all",
+    "select_line",
+    "type_text",
+    "cut",
+    "copy",
+    "paste",
+    "clear",
     "unknown",
 ]);
 let globalPageRegistry = null;
@@ -351,6 +370,382 @@ export const performAgentAction = (action, context = {}) => {
             performed = true;
             break;
         }
+        case "quit": {
+            console.log("Quit command received");
+            if (onStop) {
+                onStop();
+            }
+            info.quit = true;
+            performed = true;
+            break;
+        }
+        case "tab_next": {
+            const focusableElements = Array.from(document.querySelectorAll('a, button, input, textarea, select, [tabindex]:not([tabindex="-1"])')).filter((el) => {
+                const rect = el.getBoundingClientRect();
+                return (!el.hasAttribute("disabled") &&
+                    rect.width > 0 &&
+                    rect.height > 0 &&
+                    window.getComputedStyle(el).visibility !== "hidden");
+            });
+            const currentIndex = focusableElements.indexOf(document.activeElement);
+            const nextIndex = (currentIndex + 1) % focusableElements.length;
+            if (focusableElements[nextIndex]) {
+                focusableElements[nextIndex].focus();
+                console.log("Moved focus to next element");
+                info.focused = true;
+                info.direction = "next";
+                performed = true;
+            }
+            break;
+        }
+        case "tab_back": {
+            const focusableElements = Array.from(document.querySelectorAll('a, button, input, textarea, select, [tabindex]:not([tabindex="-1"])')).filter((el) => {
+                const rect = el.getBoundingClientRect();
+                return (!el.hasAttribute("disabled") &&
+                    rect.width > 0 &&
+                    rect.height > 0 &&
+                    window.getComputedStyle(el).visibility !== "hidden");
+            });
+            const currentIndex = focusableElements.indexOf(document.activeElement);
+            const prevIndex = currentIndex <= 0 ? focusableElements.length - 1 : currentIndex - 1;
+            if (focusableElements[prevIndex]) {
+                focusableElements[prevIndex].focus();
+                console.log("Moved focus to previous element");
+                info.focused = true;
+                info.direction = "back";
+                performed = true;
+            }
+            break;
+        }
+        case "click":
+        case "enter":
+        case "submit": {
+            const activeElement = document.activeElement;
+            if (activeElement && activeElement !== document.body) {
+                activeElement.click();
+                console.log(`Clicked on focused element: ${activeElement.tagName}`);
+                info.clicked = true;
+                performed = true;
+            }
+            else {
+                console.log("No element is currently focused");
+            }
+            break;
+        }
+        case "move_left": {
+            const activeElement = document.activeElement;
+            if (activeElement &&
+                (activeElement instanceof HTMLInputElement ||
+                    activeElement instanceof HTMLTextAreaElement)) {
+                const currentPos = activeElement.selectionStart || 0;
+                activeElement.setSelectionRange(currentPos - 1, currentPos - 1);
+                console.log("Moved cursor left");
+                info.cursorMoved = true;
+                info.direction = "left";
+                performed = true;
+            }
+            break;
+        }
+        case "move_right": {
+            const activeElement = document.activeElement;
+            if (activeElement &&
+                (activeElement instanceof HTMLInputElement ||
+                    activeElement instanceof HTMLTextAreaElement)) {
+                const currentPos = activeElement.selectionStart || 0;
+                activeElement.setSelectionRange(currentPos + 1, currentPos + 1);
+                console.log("Moved cursor right");
+                info.cursorMoved = true;
+                info.direction = "right";
+                performed = true;
+            }
+            break;
+        }
+        case "move_up": {
+            const activeElement = document.activeElement;
+            if (activeElement instanceof HTMLTextAreaElement) {
+                const lines = activeElement.value.split("\n");
+                const currentPos = activeElement.selectionStart || 0;
+                let lineStart = 0;
+                let currentLine = 0;
+                for (let i = 0; i < lines.length; i++) {
+                    if (currentPos <= lineStart + lines[i].length) {
+                        currentLine = i;
+                        break;
+                    }
+                    lineStart += lines[i].length + 1;
+                }
+                if (currentLine > 0) {
+                    const posInLine = currentPos - lineStart;
+                    const prevLineStart = lineStart - lines[currentLine - 1].length - 1;
+                    const newPos = Math.min(prevLineStart + posInLine, prevLineStart + lines[currentLine - 1].length);
+                    activeElement.setSelectionRange(newPos, newPos);
+                    console.log("Moved cursor up");
+                    info.cursorMoved = true;
+                    info.direction = "up";
+                    performed = true;
+                }
+            }
+            break;
+        }
+        case "move_down": {
+            const activeElement = document.activeElement;
+            if (activeElement instanceof HTMLTextAreaElement) {
+                const lines = activeElement.value.split("\n");
+                const currentPos = activeElement.selectionStart || 0;
+                let lineStart = 0;
+                let currentLine = 0;
+                for (let i = 0; i < lines.length; i++) {
+                    if (currentPos <= lineStart + lines[i].length) {
+                        currentLine = i;
+                        break;
+                    }
+                    lineStart += lines[i].length + 1;
+                }
+                if (currentLine < lines.length - 1) {
+                    const posInLine = currentPos - lineStart;
+                    const nextLineStart = lineStart + lines[currentLine].length + 1;
+                    const newPos = Math.min(nextLineStart + posInLine, nextLineStart + lines[currentLine + 1].length);
+                    activeElement.setSelectionRange(newPos, newPos);
+                    console.log("Moved cursor down");
+                    info.cursorMoved = true;
+                    info.direction = "down";
+                    performed = true;
+                }
+            }
+            break;
+        }
+        case "move_beginning": {
+            const activeElement = document.activeElement;
+            if (activeElement &&
+                (activeElement instanceof HTMLInputElement ||
+                    activeElement instanceof HTMLTextAreaElement)) {
+                activeElement.setSelectionRange(0, 0);
+                console.log("Moved cursor to beginning");
+                info.cursorMoved = true;
+                info.position = "beginning";
+                performed = true;
+            }
+            break;
+        }
+        case "move_end": {
+            const activeElement = document.activeElement;
+            if (activeElement &&
+                (activeElement instanceof HTMLInputElement ||
+                    activeElement instanceof HTMLTextAreaElement)) {
+                const length = activeElement.value.length;
+                activeElement.setSelectionRange(length, length);
+                console.log("Moved cursor to end");
+                info.cursorMoved = true;
+                info.position = "end";
+                performed = true;
+            }
+            break;
+        }
+        case "select_all": {
+            const activeElement = document.activeElement;
+            if (activeElement &&
+                (activeElement instanceof HTMLInputElement ||
+                    activeElement instanceof HTMLTextAreaElement)) {
+                activeElement.select();
+                console.log("Selected all text");
+                info.selected = true;
+                performed = true;
+            }
+            else {
+                const selection = window.getSelection();
+                if (selection) {
+                    selection.selectAllChildren(document.body);
+                    console.log("Selected all content on page");
+                    info.selected = true;
+                    performed = true;
+                }
+            }
+            break;
+        }
+        case "select_line": {
+            const activeElement = document.activeElement;
+            if (activeElement instanceof HTMLTextAreaElement) {
+                const currentPos = activeElement.selectionStart || 0;
+                const value = activeElement.value;
+                let lineStart = value.lastIndexOf("\n", currentPos - 1) + 1;
+                let lineEnd = value.indexOf("\n", currentPos);
+                if (lineEnd === -1) {
+                    lineEnd = value.length;
+                }
+                activeElement.setSelectionRange(lineStart, lineEnd);
+                console.log("Selected current line");
+                info.selected = true;
+                info.scope = "line";
+                performed = true;
+            }
+            else if (activeElement instanceof HTMLInputElement) {
+                activeElement.select();
+                console.log("Selected all text in input");
+                info.selected = true;
+                performed = true;
+            }
+            break;
+        }
+        case "type_text": {
+            const activeElement = document.activeElement;
+            const typeText = context?.parameters?.text || "";
+            if (activeElement &&
+                (activeElement instanceof HTMLInputElement ||
+                    activeElement instanceof HTMLTextAreaElement) &&
+                typeText) {
+                const start = activeElement.selectionStart || 0;
+                const end = activeElement.selectionEnd || 0;
+                const value = activeElement.value;
+                activeElement.value =
+                    value.substring(0, start) + typeText + value.substring(end);
+                const newPos = start + typeText.length;
+                activeElement.setSelectionRange(newPos, newPos);
+                activeElement.dispatchEvent(new Event("input", { bubbles: true, cancelable: true }));
+                console.log(`Typed text: "${typeText}"`);
+                info.typed = true;
+                info.text = typeText;
+                performed = true;
+            }
+            else {
+                console.log("No text field is focused or no text provided");
+            }
+            break;
+        }
+        case "cut": {
+            const activeElement = document.activeElement;
+            if (activeElement &&
+                (activeElement instanceof HTMLInputElement ||
+                    activeElement instanceof HTMLTextAreaElement)) {
+                const start = activeElement.selectionStart || 0;
+                const end = activeElement.selectionEnd || 0;
+                const selectedText = activeElement.value.substring(start, end);
+                if (selectedText && navigator.clipboard) {
+                    navigator.clipboard
+                        .writeText(selectedText)
+                        .then(() => {
+                        const value = activeElement.value;
+                        activeElement.value =
+                            value.substring(0, start) + value.substring(end);
+                        activeElement.setSelectionRange(start, start);
+                        activeElement.dispatchEvent(new Event("input", { bubbles: true, cancelable: true }));
+                        console.log("Cut text to clipboard");
+                        info.cut = true;
+                        performed = true;
+                    })
+                        .catch((error) => {
+                        console.warn("Failed to cut text", error);
+                    });
+                }
+                else {
+                    console.log("No text selected or clipboard API unavailable");
+                }
+            }
+            break;
+        }
+        case "copy": {
+            const activeElement = document.activeElement;
+            if (activeElement &&
+                (activeElement instanceof HTMLInputElement ||
+                    activeElement instanceof HTMLTextAreaElement)) {
+                const start = activeElement.selectionStart || 0;
+                const end = activeElement.selectionEnd || 0;
+                const selectedText = activeElement.value.substring(start, end);
+                if (selectedText && navigator.clipboard) {
+                    navigator.clipboard
+                        .writeText(selectedText)
+                        .then(() => {
+                        console.log("Copied text to clipboard");
+                        info.copied = true;
+                        performed = true;
+                    })
+                        .catch((error) => {
+                        console.warn("Failed to copy text", error);
+                    });
+                }
+                else {
+                    const selection = window.getSelection();
+                    const selectionText = selection?.toString();
+                    if (selectionText && navigator.clipboard) {
+                        navigator.clipboard
+                            .writeText(selectionText)
+                            .then(() => {
+                            console.log("Copied selected text to clipboard");
+                            info.copied = true;
+                            performed = true;
+                        })
+                            .catch((error) => {
+                            console.warn("Failed to copy text", error);
+                        });
+                    }
+                    else {
+                        console.log("No text selected");
+                    }
+                }
+            }
+            else {
+                const selection = window.getSelection();
+                const selectionText = selection?.toString();
+                if (selectionText && navigator.clipboard) {
+                    navigator.clipboard
+                        .writeText(selectionText)
+                        .then(() => {
+                        console.log("Copied selected text to clipboard");
+                        info.copied = true;
+                        performed = true;
+                    })
+                        .catch((error) => {
+                        console.warn("Failed to copy text", error);
+                    });
+                }
+                else {
+                    console.log("No text selected");
+                }
+            }
+            break;
+        }
+        case "paste": {
+            const activeElement = document.activeElement;
+            if (activeElement &&
+                (activeElement instanceof HTMLInputElement ||
+                    activeElement instanceof HTMLTextAreaElement) &&
+                navigator.clipboard) {
+                navigator.clipboard
+                    .readText()
+                    .then((clipboardText) => {
+                    const start = activeElement.selectionStart || 0;
+                    const end = activeElement.selectionEnd || 0;
+                    const value = activeElement.value;
+                    activeElement.value =
+                        value.substring(0, start) + clipboardText + value.substring(end);
+                    const newPos = start + clipboardText.length;
+                    activeElement.setSelectionRange(newPos, newPos);
+                    activeElement.dispatchEvent(new Event("input", { bubbles: true, cancelable: true }));
+                    console.log("Pasted text from clipboard");
+                    info.pasted = true;
+                    performed = true;
+                })
+                    .catch((error) => {
+                    console.warn("Failed to paste text", error);
+                });
+            }
+            else {
+                console.log("No text field is focused or clipboard API unavailable");
+            }
+            break;
+        }
+        case "clear": {
+            const activeElement = document.activeElement;
+            if (activeElement &&
+                (activeElement instanceof HTMLInputElement ||
+                    activeElement instanceof HTMLTextAreaElement)) {
+                activeElement.value = "";
+                activeElement.dispatchEvent(new Event("input", { bubbles: true, cancelable: true }));
+                console.log("Cleared text field");
+                info.cleared = true;
+                performed = true;
+            }
+            break;
+        }
         default: {
             if (action.startsWith("navigate_") && globalPageRegistry) {
                 const pageId = globalPageRegistry.getPageIdFromAction(action);

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export { parseNavigationXML, fetchNavigationXML, loadNavigationPages, } from "./
 export type { PageXMLConfig } from "./services/xml-parser.js";
 export * from "./types.js";
 export * from "./actions.js";
-export * from "./ui.js";
+export { createFloatingControl, attachToCustomButton, setState, updateStatus, updateTranscript, updateActionIndicator, showError, emitEvent, } from "./ui.js";
 import { VoiceNavigationController } from "./navigation-controller.js";
 import type { NavigationConfig } from "./types.js";
 export declare function initNavigationOnMicrophone(config: NavigationConfig): VoiceNavigationController;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,YAAY,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC;AAExB,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AA8JnD,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,gBAAgB,GACvB,yBAAyB,CAuE3B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,YAAY,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,QAAQ,EACR,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,SAAS,EACT,SAAS,GACV,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AA+JnD,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,gBAAgB,GACvB,yBAAyB,CAoG3B"}

package/dist/index.js

@@ -6,7 +6,7 @@ export { PageRegistry } from "./services/page-registry.js";
 export { parseNavigationXML, fetchNavigationXML, loadNavigationPages, } from "./services/xml-parser.js";
 export * from "./types.js";
 export * from "./actions.js";
-export * from "./ui.js";
+export { createFloatingControl, attachToCustomButton, setState, updateStatus, updateTranscript, updateActionIndicator, showError, emitEvent, } from "./ui.js";
 import { VoiceNavigationController } from "./navigation-controller.js";
 const CONFIG_STORAGE_KEY = "__voice_navigation_config";
 const resolveOpenSearchConfig = (config) => {
@@ -37,6 +37,7 @@ const buildPersistableConfig = (config) => {
         pages: normalizedConfig.pages ? { ...normalizedConfig.pages } : undefined,
         language: normalizedConfig.language,
         autoStart: normalizedConfig.autoStart,
+        ui: normalizedConfig.ui ? { ...normalizedConfig.ui } : undefined,
     };
     if (hasCustomHandlers) {
         persistable.hasCustomHandlers = true;
@@ -92,6 +93,7 @@ export function initNavigationOnMicrophone(config) {
     }
     const globalWindow = window;
     const normalizedConfig = normalizeNavigationConfig(config);
+    console.log("[Voice Navigation Init] UI Config received:", normalizedConfig.ui);
     const previousConfigRaw = globalWindow.__voiceNavigationConfig;
     const previousConfig = previousConfigRaw
         ? normalizeNavigationConfig(previousConfigRaw)
@@ -107,6 +109,7 @@ export function initNavigationOnMicrophone(config) {
         console.warn("Failed to persist voice navigation config:", error);
     }
     if (globalWindow.__navigateOnMicrophoneInitialized) {
+        console.log("[Voice Navigation] Already initialized, checking for config changes...");
         const existingController = globalWindow.navigationController;
         const previousOpenSearchConfig = resolveOpenSearchConfig(previousConfig);
         const currentOpenSearchConfig = resolveOpenSearchConfig(normalizedConfig);
@@ -118,8 +121,20 @@ export function initNavigationOnMicrophone(config) {
             wantsVectorSearch &&
             describeOpenSearchConfig(previousOpenSearchConfig) !==
                 describeOpenSearchConfig(currentOpenSearchConfig);
-        if (wantsVectorSearch &&
-            (!hadVectorSearch || vectorConfigChanged || !existingHasVectorSearch)) {
+        const previousUI = previousConfig?.ui;
+        const currentUI = normalizedConfig.ui;
+        console.log("[Voice Navigation] Previous UI config:", previousUI);
+        console.log("[Voice Navigation] Current UI config:", currentUI);
+        const uiConfigChanged = previousUI?.showDefaultButton !== currentUI?.showDefaultButton ||
+            previousUI?.customButtonSelector !== currentUI?.customButtonSelector ||
+            previousUI?.buttonPlacement !== currentUI?.buttonPlacement;
+        console.log("[Voice Navigation] UI config changed:", uiConfigChanged);
+        if ((wantsVectorSearch &&
+            (!hadVectorSearch ||
+                vectorConfigChanged ||
+                !existingHasVectorSearch)) ||
+            uiConfigChanged) {
+            console.log("[Voice Navigation] Destroying existing controller and recreating...");
             try {
                 existingController?.destroy?.();
             }

package/dist/navigation-controller.d.ts

@@ -14,7 +14,9 @@ export declare class VoiceNavigationController {
     private removeAutoStartListeners;
     private vectorSearchService;
     private pagesInitialized;
+    private uiInitialized;
     constructor(config: NavigationConfig);
+    private initializeUIAsync;
     private shouldAutoStart;
     setAutoStart(enabled: boolean): void;
     prepareForNavigation(options?: {

package/dist/navigation-controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"navigation-controller.d.ts","sourceRoot":"","sources":["../src/navigation-controller.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,gBAAgB,EAKjB,MAAM,YAAY,CAAC;AA0DpB,qBAAa,yBAAyB;IACpC,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,iBAAiB,CAAoB;IAC7C,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,EAAE,CAAa;IACvB,OAAO,CAAC,cAAc,CAAc;IACpC,OAAO,CAAC,YAAY,CAAkB;IACtC,OAAO,CAAC,qBAAqB,CAAkB;IAC/C,OAAO,CAAC,eAAe,CAA2B;IAClD,OAAO,CAAC,+BAA+B,CAAkB;IACzD,OAAO,CAAC,wBAAwB,CAA6B;IAC7D,OAAO,CAAC,mBAAmB,CAAoC;IAC/D,OAAO,CAAC,gBAAgB,CAAgB;gBAE5B,MAAM,EAAE,gBAAgB;IAgFpC,OAAO,CAAC,eAAe;IAoBhB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAepC,oBAAoB,CAAC,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,IAAI;YAOtD,eAAe;IAmE7B,OAAO,CAAC,kBAAkB;YASZ,eAAe;IAkBhB,KAAK,CAChB,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAO,GACzC,OAAO,CAAC,IAAI,CAAC;IA0EH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA2BlC,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,aAAa;YAWP,aAAa;YAOb,wBAAwB;IAuCtC,OAAO,CAAC,WAAW;YAoBL,iBAAiB;YAwBjB,iBAAiB;IA0HxB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;YAI5B,yBAAyB;IAgMvC,OAAO,CAAC,oBAAoB;IAqD5B,OAAO,CAAC,yBAAyB;IAoCjC,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,4BAA4B;IAiB7B,OAAO,IAAI,IAAI;IAgBtB,OAAO,CAAC,kBAAkB;IA8B1B,OAAO,CAAC,kBAAkB;IAwD1B,OAAO,CAAC,aAAa;IAYrB,OAAO,CAAC,uBAAuB;IAkD/B,OAAO,CAAC,sBAAsB;IAW9B,OAAO,CAAC,wBAAwB;CAmBjC"}
+{"version":3,"file":"navigation-controller.d.ts","sourceRoot":"","sources":["../src/navigation-controller.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,gBAAgB,EAKjB,MAAM,YAAY,CAAC;AA2DpB,qBAAa,yBAAyB;IACpC,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,iBAAiB,CAAoB;IAC7C,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,EAAE,CAAc;IACxB,OAAO,CAAC,cAAc,CAAc;IACpC,OAAO,CAAC,YAAY,CAAkB;IACtC,OAAO,CAAC,qBAAqB,CAAkB;IAC/C,OAAO,CAAC,eAAe,CAA2B;IAClD,OAAO,CAAC,+BAA+B,CAAkB;IACzD,OAAO,CAAC,wBAAwB,CAA6B;IAC7D,OAAO,CAAC,mBAAmB,CAAoC;IAC/D,OAAO,CAAC,gBAAgB,CAAgB;IACxC,OAAO,CAAC,aAAa,CAAgB;gBAEzB,MAAM,EAAE,gBAAgB;YAkFtB,iBAAiB;IAiD/B,OAAO,CAAC,eAAe;IAoBhB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAepC,oBAAoB,CAAC,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,IAAI;YAOtD,eAAe;IAmE7B,OAAO,CAAC,kBAAkB;YASZ,eAAe;IAwBhB,KAAK,CAChB,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAO,GACzC,OAAO,CAAC,IAAI,CAAC;IAmFH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAiClC,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,aAAa;YAWP,aAAa;YAOb,wBAAwB;IAuCtC,OAAO,CAAC,WAAW;YAoBL,iBAAiB;YAwBjB,iBAAiB;IA0HxB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;YAI5B,yBAAyB;IAgMvC,OAAO,CAAC,oBAAoB;IAqD5B,OAAO,CAAC,yBAAyB;IAoCjC,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,4BAA4B;IAiB7B,OAAO,IAAI,IAAI;IAgBtB,OAAO,CAAC,kBAAkB;IA8B1B,OAAO,CAAC,kBAAkB;IAwD1B,OAAO,CAAC,aAAa;IAYrB,OAAO,CAAC,uBAAuB;IAkD/B,OAAO,CAAC,sBAAsB;IAW9B,OAAO,CAAC,wBAAwB;CAmBjC"}

package/dist/navigation-controller.js

@@ -5,7 +5,7 @@ import { PageRegistry } from "./services/page-registry.js";
 import { loadNavigationPages } from "./services/xml-parser.js";
 import { VectorSearchService, } from "./services/vector-search.js";
 import { performAgentAction, formatActionLabel, extractAgentAction, setPageRegistry, } from "./actions.js";
-import { createFloatingControl, setState, updateStatus, updateTranscript, updateActionIndicator, showError, emitEvent, } from "./ui.js";
+import { createFloatingControl, attachToCustomButton, setState, updateStatus, updateTranscript, updateActionIndicator, showError, emitEvent, } from "./ui.js";
 const AUTO_START_STORAGE_KEY = "__navigate_auto_start";
 const RESUME_STATE_STORAGE_KEY = "__navigate_resume_state";
 const flowLog = (...args) => {
@@ -42,6 +42,7 @@ export class VoiceNavigationController {
             ...config,
             opensearch: openSearchConfig,
         };
+        console.log("[Voice Navigation Controller] Constructor called with UI config:", this.config.ui);
         if (!this.config.azure?.subscriptionKey || !this.config.azure?.region) {
             throw new Error("Azure Speech configuration is required");
         }
@@ -80,8 +81,7 @@ export class VoiceNavigationController {
             }
         }
         this.resumeAfterNavigation = this.consumeResumeState();
-        this.ui = createFloatingControl();
-        this.setupEventHandlers();
+        this.uiInitialized = this.initializeUIAsync();
         if (this.resumeAfterNavigation) {
             void this.start({ reason: "auto" });
         }
@@ -89,6 +89,39 @@ export class VoiceNavigationController {
             void this.start({ reason: "auto" });
         }
     }
+    async initializeUIAsync() {
+        const uiConfig = this.config.ui || {};
+        const showDefaultButton = uiConfig.showDefaultButton !== false;
+        const customButtonSelector = uiConfig.customButtonSelector;
+        const buttonPlacement = uiConfig.buttonPlacement || "bottom-right";
+        console.log("[Voice Navigation] UI Config:", {
+            showDefaultButton,
+            customButtonSelector,
+            buttonPlacement,
+        });
+        if (!showDefaultButton && customButtonSelector) {
+            console.log(`[Voice Navigation] Attempting to use custom button: ${customButtonSelector}`);
+            try {
+                this.ui = await attachToCustomButton(customButtonSelector);
+                flowLog(`✓ Attached to custom button: ${customButtonSelector}`);
+            }
+            catch (error) {
+                console.error("Failed to attach to custom button:", error);
+                console.warn("Falling back to default button due to custom button error");
+                this.ui = createFloatingControl(buttonPlacement);
+            }
+        }
+        else if (!showDefaultButton && !customButtonSelector) {
+            console.warn("showDefaultButton is false but no customButtonSelector provided. Creating default button.");
+            this.ui = createFloatingControl(buttonPlacement);
+        }
+        else {
+            console.log(`[Voice Navigation] Creating default button at: ${buttonPlacement}`);
+            this.ui = createFloatingControl(buttonPlacement);
+            flowLog(`✓ Created default button at position: ${buttonPlacement}`);
+        }
+        this.setupEventHandlers();
+    }
     shouldAutoStart() {
         if (this.config.autoStart === true) {
             return true;
@@ -164,6 +197,10 @@ export class VoiceNavigationController {
         });
     }
     async toggleRecording() {
+        if (!this.ui || !this.ui.root) {
+            console.warn("UI not initialized, cannot toggle recording");
+            return;
+        }
         const currentState = this.ui.root.dataset.state;
         if (currentState === "listening" || currentState === "thinking") {
             await this.stop();
@@ -177,6 +214,11 @@ export class VoiceNavigationController {
     async start(options = {}) {
         const reason = options.reason ?? "user";
         this.lastStartReason = reason;
+        await this.uiInitialized;
+        if (!this.ui || !this.ui.root) {
+            console.error("UI not properly initialized");
+            return;
+        }
         try {
             await this.pagesInitialized;
         }
@@ -239,6 +281,10 @@ export class VoiceNavigationController {
         }
     }
     async stop() {
+        if (!this.ui || !this.ui.root) {
+            console.warn("UI not initialized, cannot stop");
+            return;
+        }
         this.isProcessing = false;
         setState(this.ui, "thinking");
         emitEvent("state-change", { state: "thinking" });
@@ -693,7 +739,7 @@ export class VoiceNavigationController {
     }
     destroy() {
         this.clearAutoStartFallback();
-        if (this.ui.root.parentElement) {
+        if (this.ui && this.ui.root && this.ui.root.parentElement) {
             this.ui.root.parentElement.removeChild(this.ui.root);
         }
         const styles = document.getElementById("navigate-control-styles");

package/dist/types.d.ts

@@ -1,5 +1,11 @@
-export type CoreNavigationAction = "zoom_in" | "zoom_out" | "scroll_up" | "scroll_down" | "scroll_left" | "scroll_right" | "page_up" | "page_down" | "scroll_top" | "scroll_bottom" | "go_back" | "go_forward" | "reload_page" | "print_page" | "copy_url" | "open_menu" | "close_menu" | "focus_search" | "toggle_fullscreen" | "exit_fullscreen" | "play_media" | "pause_media" | "mute_media" | "unmute_media" | "search_content" | "stop" | "unknown";
+export type CoreNavigationAction = "zoom_in" | "zoom_out" | "scroll_up" | "scroll_down" | "scroll_left" | "scroll_right" | "page_up" | "page_down" | "scroll_top" | "scroll_bottom" | "go_back" | "go_forward" | "reload_page" | "print_page" | "copy_url" | "open_menu" | "close_menu" | "focus_search" | "toggle_fullscreen" | "exit_fullscreen" | "play_media" | "pause_media" | "mute_media" | "unmute_media" | "search_content" | "stop" | "quit" | "tab_next" | "tab_back" | "click" | "enter" | "submit" | "move_left" | "move_right" | "move_up" | "move_down" | "move_beginning" | "move_end" | "select_all" | "select_line" | "type_text" | "cut" | "copy" | "paste" | "clear" | "unknown";
 export type NavigationAction = CoreNavigationAction | `navigate_${string}`;
+export type ButtonPlacement = "bottom-right" | "bottom-left" | "top-right" | "top-left" | "center-right" | "center-left";
+export interface UIConfig {
+    showDefaultButton?: boolean;
+    customButtonSelector?: string;
+    buttonPlacement?: ButtonPlacement;
+}
 export interface NavigationConfig {
     aws?: {
         region?: string;
@@ -18,6 +24,7 @@ export interface NavigationConfig {
     opensearch?: OpenSearchConfig;
     openSearch?: OpenSearchConfig;
     pages?: NavigationPagesConfig;
+    ui?: UIConfig;
 }
 export interface NavigationPagesConfig {
     xml?: string;
@@ -102,11 +109,12 @@ export interface NavigationCallbacks {
 export type NavigationState = "idle" | "loading" | "listening" | "thinking" | "error";
 export interface UIElements {
     root: HTMLElement;
-    button: HTMLButtonElement;
-    label: HTMLElement;
+    button: HTMLButtonElement | HTMLElement;
+    label: HTMLElement | null;
     status: HTMLElement;
     transcript: HTMLElement;
     action: HTMLElement;
+    isCustomButton?: boolean;
 }
 export interface NavigationEvent extends CustomEvent {
     detail: {

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/ui.d.ts

@@ -1,6 +1,7 @@
-import type { UIElements, NavigationState } from "./types.js";
-export declare const injectFloatingControlStyles: () => void;
-export declare const createFloatingControl: () => UIElements;
+import type { UIElements, NavigationState, ButtonPlacement } from "./types.js";
+export declare const injectFloatingControlStyles: (placement?: ButtonPlacement) => void;
+export declare const createFloatingControl: (placement?: ButtonPlacement) => UIElements;
+export declare const attachToCustomButton: (buttonSelector: string) => Promise<UIElements>;
 export declare const updateStatus: (ui: UIElements, text: string) => void;
 export declare const setState: (ui: UIElements, state: NavigationState) => void;
 export declare const updateTranscript: (ui: UIElements, text: string) => void;

package/dist/ui.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAK9D,eAAO,MAAM,2BAA2B,QAAO,IAmH9C,CAAC;AAKF,eAAO,MAAM,qBAAqB,QAAO,UAqDxC,CAAC;AAKF,eAAO,MAAM,YAAY,GAAI,IAAI,UAAU,EAAE,MAAM,MAAM,KAAG,IAE3D,CAAC;AAKF,eAAO,MAAM,QAAQ,GAAI,IAAI,UAAU,EAAE,OAAO,eAAe,KAAG,IA+BjE,CAAC;AAKF,eAAO,MAAM,gBAAgB,GAAI,IAAI,UAAU,EAAE,MAAM,MAAM,KAAG,IAE/D,CAAC;AAKF,eAAO,MAAM,qBAAqB,GAChC,IAAI,UAAU,EACd,YAAY,MAAM,EAClB,WAAW,OAAO,EAClB,OAAM,GAAQ,KACb,IAkBF,CAAC;AAKF,eAAO,MAAM,SAAS,GAAI,IAAI,UAAU,EAAE,OAAO,KAAK,KAAG,IAGxD,CAAC;AAKF,eAAO,MAAM,SAAS,GAAI,MAAM,MAAM,EAAE,SAAQ,GAAQ,KAAG,IAU1D,CAAC"}
+{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAuC/E,eAAO,MAAM,2BAA2B,GACtC,YAAW,eAAgC,KAC1C,IAqHF,CAAC;AAKF,eAAO,MAAM,qBAAqB,GAChC,YAAW,eAAgC,KAC1C,UAgEF,CAAC;AA+EF,eAAO,MAAM,oBAAoB,GAC/B,gBAAgB,MAAM,KACrB,OAAO,CAAC,UAAU,CAuEpB,CAAC;AAKF,eAAO,MAAM,YAAY,GAAI,IAAI,UAAU,EAAE,MAAM,MAAM,KAAG,IAE3D,CAAC;AAKF,eAAO,MAAM,QAAQ,GAAI,IAAI,UAAU,EAAE,OAAO,eAAe,KAAG,IAgDjE,CAAC;AAKF,eAAO,MAAM,gBAAgB,GAAI,IAAI,UAAU,EAAE,MAAM,MAAM,KAAG,IAE/D,CAAC;AAKF,eAAO,MAAM,qBAAqB,GAChC,IAAI,UAAU,EACd,YAAY,MAAM,EAClB,WAAW,OAAO,EAClB,OAAM,GAAQ,KACb,IAkBF,CAAC;AAKF,eAAO,MAAM,SAAS,GAAI,IAAI,UAAU,EAAE,OAAO,KAAK,KAAG,IAGxD,CAAC;AAKF,eAAO,MAAM,SAAS,GAAI,MAAM,MAAM,EAAE,SAAQ,GAAQ,KAAG,IAU1D,CAAC"}

package/dist/ui.js

@@ -1,17 +1,41 @@
-export const injectFloatingControlStyles = () => {
-    if (document.getElementById("navigate-control-styles")) {
-        return;
+const getPlacementStyles = (placement) => {
+    const positions = {
+        "bottom-right": "bottom: 24px; right: 24px; left: auto; top: auto;",
+        "bottom-left": "bottom: 24px; left: 24px; right: auto; top: auto;",
+        "top-right": "top: 24px; right: 24px; left: auto; bottom: auto;",
+        "top-left": "top: 24px; left: 24px; right: auto; bottom: auto;",
+        "center-right": "top: 50%; right: 24px; left: auto; bottom: auto; transform: translateY(-50%);",
+        "center-left": "top: 50%; left: 24px; right: auto; bottom: auto; transform: translateY(-50%);",
+    };
+    return positions[placement] || positions["bottom-right"];
+};
+const getMobilePlacementStyles = (placement) => {
+    const positions = {
+        "bottom-right": "bottom: 16px; right: 16px; left: auto; top: auto;",
+        "bottom-left": "bottom: 16px; left: 16px; right: auto; top: auto;",
+        "top-right": "top: 16px; right: 16px; left: auto; bottom: auto;",
+        "top-left": "top: 16px; left: 16px; right: auto; bottom: auto;",
+        "center-right": "top: 50%; right: 16px; left: auto; bottom: auto; transform: translateY(-50%);",
+        "center-left": "top: 50%; left: 16px; right: auto; bottom: auto; transform: translateY(-50%);",
+    };
+    return positions[placement] || positions["bottom-right"];
+};
+export const injectFloatingControlStyles = (placement = "bottom-right") => {
+    const existingStyle = document.getElementById("navigate-control-styles");
+    if (existingStyle) {
+        existingStyle.remove();
     }
     const style = document.createElement("style");
     style.id = "navigate-control-styles";
+    const placementStyles = getPlacementStyles(placement);
+    const mobilePlacementStyles = getMobilePlacementStyles(placement);
     style.textContent = `
     .navigate-control {
       position: fixed;
-      bottom: 24px;
-      right: 24px;
+      ${placementStyles}
       display: flex;
       gap: 12px;
-      align-items: flex-end;
+      align-items: ${placement.startsWith("top") ? "flex-start" : "flex-end"};
       z-index: 2147483647;
       font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
       color: #0f172a;
@@ -101,8 +125,7 @@ export const injectFloatingControlStyles = () => {
 
     @media (max-width: 640px) {
       .navigate-control {
-        right: 16px;
-        bottom: 16px;
+        ${mobilePlacementStyles}
       }
 
       .navigate-control__panel {
@@ -112,8 +135,8 @@ export const injectFloatingControlStyles = () => {
   `;
     document.head.appendChild(style);
 };
-export const createFloatingControl = () => {
-    injectFloatingControlStyles();
+export const createFloatingControl = (placement = "bottom-right") => {
+    injectFloatingControlStyles(placement);
     let root = document.getElementById("navigate-control");
     if (!root) {
         root = document.createElement("div");
@@ -133,10 +156,12 @@ export const createFloatingControl = () => {
   `;
     const appendToBody = () => {
         if (!document.body) {
+            console.warn("Voice navigation: document.body not available yet");
             return;
         }
         if (!document.body.contains(root)) {
             document.body.appendChild(root);
+            console.log(`Voice navigation: Button created with placement "${placement}"`);
         }
     };
     appendToBody();
@@ -145,13 +170,111 @@ export const createFloatingControl = () => {
             once: true,
         });
     }
+    const button = root.querySelector(".navigate-control__button");
+    if (!button) {
+        console.error("Voice navigation: Failed to create button element");
+    }
     return {
         root,
-        button: root.querySelector(".navigate-control__button"),
+        button,
         label: root.querySelector(".navigate-control__label"),
         status: root.querySelector(".navigate-control__status"),
         transcript: root.querySelector(".navigate-control__transcript"),
         action: root.querySelector(".navigate-control__action"),
+        isCustomButton: false,
+    };
+};
+const waitForElement = (selector, timeout = 30000) => {
+    return new Promise((resolve, reject) => {
+        const element = document.querySelector(selector);
+        if (element) {
+            console.log(`[Voice Navigation] Element "${selector}" found immediately`);
+            resolve(element);
+            return;
+        }
+        console.log(`[Voice Navigation] Element "${selector}" not found, waiting up to ${timeout}ms...`);
+        let observer = null;
+        const waitForBody = () => {
+            if (!document.body) {
+                console.log("[Voice Navigation] Waiting for document.body to be available...");
+                setTimeout(waitForBody, 100);
+                return;
+            }
+            observer = new MutationObserver(() => {
+                const element = document.querySelector(selector);
+                if (element) {
+                    observer?.disconnect();
+                    clearTimeout(timeoutId);
+                    console.log(`[Voice Navigation] Element "${selector}" found after waiting`);
+                    resolve(element);
+                }
+            });
+            observer.observe(document.body, {
+                childList: true,
+                subtree: true,
+            });
+        };
+        waitForBody();
+        const timeoutId = setTimeout(() => {
+            observer?.disconnect();
+            console.error(`[Voice Navigation] Timeout: Element "${selector}" not found after ${timeout}ms`);
+            const allButtons = document.querySelectorAll('[id^="btn"]');
+            if (allButtons.length > 0) {
+                console.log("[Voice Navigation] Available buttons with id starting with 'btn':", Array.from(allButtons).map((btn) => `#${btn.id}`));
+            }
+            reject(new Error(`Custom button not found with selector: "${selector}" after ${timeout}ms. Make sure the button exists in the DOM.`));
+        }, timeout);
+    });
+};
+export const attachToCustomButton = async (buttonSelector) => {
+    injectFloatingControlStyles("bottom-right");
+    console.log(`Voice navigation: Waiting for custom button "${buttonSelector}"...`);
+    const customButton = await waitForElement(buttonSelector).catch((error) => {
+        console.error(error.message);
+        throw error;
+    });
+    console.log(`Voice navigation: Custom button found "${buttonSelector}"`);
+    let root = document.getElementById("navigate-control-panel");
+    if (!root) {
+        root = document.createElement("div");
+        root.id = "navigate-control-panel";
+        root.className = "navigate-control";
+        root.style.display = "none";
+    }
+    root.dataset.state = root.dataset.state || "idle";
+    root.innerHTML = `
+    <div class="navigate-control__panel">
+      <div class="navigate-control__status">Tap your button to start voice control</div>
+      <div class="navigate-control__transcript" role="status" aria-live="polite"></div>
+      <div class="navigate-control__action" aria-live="polite"></div>
+    </div>
+  `;
+    const appendToBody = () => {
+        if (!document.body) {
+            return;
+        }
+        if (!document.body.contains(root)) {
+            document.body.appendChild(root);
+        }
+    };
+    appendToBody();
+    if (document.readyState === "loading") {
+        document.addEventListener("DOMContentLoaded", appendToBody, {
+            once: true,
+        });
+    }
+    customButton.setAttribute("aria-pressed", "false");
+    if (!customButton.getAttribute("aria-label")) {
+        customButton.setAttribute("aria-label", "Start voice control");
+    }
+    return {
+        root,
+        button: customButton,
+        label: null,
+        status: root.querySelector(".navigate-control__status"),
+        transcript: root.querySelector(".navigate-control__transcript"),
+        action: root.querySelector(".navigate-control__action"),
+        isCustomButton: true,
     };
 };
 export const updateStatus = (ui, text) => {
@@ -159,34 +282,44 @@ export const updateStatus = (ui, text) => {
 };
 export const setState = (ui, state) => {
     ui.root.dataset.state = state;
+    const updateLabel = (text) => {
+        if (ui.label) {
+            ui.label.textContent = text;
+        }
+    };
     switch (state) {
         case "idle":
-            ui.label.textContent = "Start";
+            updateLabel("Start");
             ui.button.setAttribute("aria-pressed", "false");
             ui.button.setAttribute("aria-label", "Start voice control");
-            updateStatus(ui, "Tap to start voice control");
+            updateStatus(ui, ui.isCustomButton
+                ? "Tap your button to start voice control"
+                : "Tap to start voice control");
             break;
         case "loading":
-            ui.label.textContent = "Loading...";
+            updateLabel("Loading...");
             ui.button.setAttribute("aria-label", "Loading voice control");
             updateStatus(ui, "Loading...");
             break;
         case "listening":
-            ui.label.textContent = "Stop";
+            updateLabel("Stop");
             ui.button.setAttribute("aria-pressed", "true");
             ui.button.setAttribute("aria-label", "Stop voice control");
             updateStatus(ui, "Listening...");
             break;
         case "thinking":
-            ui.label.textContent = "Stop";
+            updateLabel("Stop");
             ui.button.setAttribute("aria-label", "Processing");
             updateStatus(ui, "Processing...");
             break;
         case "error":
-            ui.label.textContent = "Error";
+            updateLabel("Error");
             ui.button.setAttribute("aria-label", "Error occurred");
             break;
     }
+    if (ui.isCustomButton) {
+        ui.root.style.display = state === "idle" ? "none" : "flex";
+    }
 };
 export const updateTranscript = (ui, text) => {
     ui.transcript.textContent = text;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myscheme/voice-navigation-sdk",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Voice navigation SDK using Azure Speech and AWS Bedrock",
   "type": "module",
   "main": "dist/index.js",