@burtson-labs/bandit-engine 2.0.25 → 2.0.26

package/docs/api_reference/assets/bandit-docs.js

@@ -1,271 +1,456 @@
 (() => {
-  const STORAGE_KEY = "bandit-doc-view:target-id";
-  const MAX_LOOKUPS = 360;
-  const RESCROLL_DELAYS = [100, 300, 600, 1200, 2400, 3600];
-
-  const decodeHash = (hash) => {
-    if (!hash) {
-      return null;
-    }
+  const STYLE_ID = "bandit-typedoc-mobile-tweaks";
+  const BACK_BUTTON_ID = "bandit-docs-back-button";
+  const FALLBACK_URL = "/npm-package";
+  const GATEWAY_MARKER = "VITE_DEFAULT_MODEL";
+  const MAX_GATEWAY_ATTEMPTS = 40;
+  const EMBEDDED_CLASS = "bandit-docs-embedded";
+  const STANDALONE_CLASS = "bandit-docs-standalone";
+
+  const isEmbedded = (() => {
     try {
-      return decodeURIComponent(hash.replace(/^#/, ""));
+      return window.top !== window;
     } catch {
-      return hash.replace(/^#/, "");
+      return true;
     }
-  };
+  })();
 
-  const sanitizeId = (id) => {
-    if (!id) {
-      return null;
-    }
-    return id
-      .normalize("NFKD")
-      .replace(/[\u{1F300}-\u{1FAFF}]/gu, "")
-      .replace(/[\u{1F600}-\u{1F64F}]/gu, "")
-      .replace(/[\u{1F680}-\u{1F6FF}]/gu, "")
-      .replace(/[\u2600-\u27BF]/g, "")
-      .replace(/[:]/g, "-")
-      .replace(/-+/g, "-")
-      .replace(/^-|-$/g, "");
-  };
+  const addStyles = () => {
+    if (document.getElementById(STYLE_ID)) return;
 
-  const ensureAliasAnchors = () => {
-    const processed = new Set();
-    document.querySelectorAll("[id]").forEach((node) => {
-      const aliasId = sanitizeId(node.id);
-      if (!aliasId || aliasId === node.id || processed.has(aliasId)) {
-        return;
+    const style = document.createElement("style");
+    style.id = STYLE_ID;
+    style.textContent = `
+      :root {
+        --bandit-docs-footer-height: 56px;
+        --bandit-docs-header-height: 68px;
       }
-      if (document.getElementById(aliasId)) {
-        processed.add(aliasId);
-        return;
+
+      html,
+      body {
+        overflow: hidden;
       }
 
-      const alias = document.createElement("span");
-      alias.id = aliasId;
-      alias.setAttribute("data-bandit-alias", node.id);
-      alias.style.position = "relative";
-      alias.style.display = "block";
-      alias.style.height = "0";
-      alias.style.margin = "0";
-      alias.style.padding = "0";
-      alias.style.visibility = "hidden";
+      body.bandit-docs-ready {
+        display: block !important;
+      }
 
-      if (node.parentNode) {
-        node.parentNode.insertBefore(alias, node);
+      .tsd-panel table {
+        width: 100%;
+        border-collapse: collapse;
       }
-      processed.add(aliasId);
-    });
-  };
 
-  const resolveTarget = (id) => {
-    if (!id) {
-      return null;
-    }
+      .tsd-panel table:not(.tsd-comment-table) {
+        display: block;
+        overflow-x: auto;
+      }
 
-    if (typeof CSS !== "undefined" && typeof CSS.escape === "function") {
-      const escaped = CSS.escape(id);
-      const viaSelector = document.querySelector(`#${escaped}`);
-      if (viaSelector) {
-        return viaSelector;
+      .tsd-panel table::-webkit-scrollbar {
+        height: 6px;
       }
-    }
 
-    const direct = document.getElementById(id);
-    if (direct) {
-      return direct;
-    }
+      .gateway-doc {
+        display: grid;
+        gap: clamp(12px, 2.5vw, 20px);
+        line-height: 1.65;
+      }
 
-    const sanitized = sanitizeId(id);
-    if (sanitized && sanitized !== id) {
-      const fallback = document.getElementById(sanitized);
-      if (fallback) {
-        return fallback;
+      .gateway-doc ul {
+        margin: 0;
+        padding-left: clamp(20px, 4vw, 32px);
       }
-    }
 
-    const slug = id.includes(":") ? id.split(":").pop() : id;
-    if (slug) {
-      const nodes = document.querySelectorAll("[id]");
-      for (const node of nodes) {
-        if (typeof node.id === "string" && node.id.endsWith(slug)) {
-          return node;
+      .gateway-doc blockquote {
+        margin: 0;
+        padding-left: clamp(16px, 3vw, 24px);
+        border-left: 3px solid rgba(148, 163, 184, 0.35);
+        opacity: 0.9;
+      }
+
+      .container {
+        width: 100%;
+        max-width: none;
+        margin: 0 auto;
+        padding-left: clamp(18px, 2.8vw, 64px);
+        padding-right: clamp(18px, 2.8vw, 64px);
+        box-sizing: border-box;
+      }
+
+      .container-main {
+        box-sizing: border-box;
+        margin: 0 auto;
+        padding-top: clamp(4px, 0.6vh, 10px);
+        padding-bottom: 0;
+        gap: clamp(12px, 1.4vw, 24px);
+        height: calc(100vh - var(--bandit-docs-header-height));
+        display: grid;
+        grid-template-rows: max-content 1fr;
+        align-content: start;
+      }
+
+      .container-main .col-content,
+      .container-main .col-navigation,
+      .container-main .col-sidebar {
+        padding-bottom: clamp(12px, 1.4vw, 20px);
+      }
+
+      @media (min-width: 1280px) {
+        .container-main {
+          display: grid;
+          grid-template-columns:
+            minmax(200px, clamp(236px, 15.5vw, 284px))
+            minmax(0, 1fr)
+            minmax(200px, clamp(236px, 15.5vw, 284px));
+          align-items: stretch;
+          grid-template-rows: max-content 1fr;
+        }
+
+        .container-main .col-navigation,
+        .container-main .col-sidebar {
+          position: sticky;
+          top: var(--bandit-docs-header-height);
+          max-height: calc(100vh - var(--bandit-docs-header-height) - var(--bandit-docs-footer-height) - clamp(12px, 1.5vh, 24px));
+          overflow-y: auto;
+          padding-right: clamp(6px, 0.9vw, 16px);
+          padding-bottom: calc(var(--bandit-docs-footer-height) + clamp(12px, 1.5vh, 24px));
+          scrollbar-gutter: stable;
+          overscroll-behavior: contain;
+          -webkit-overflow-scrolling: touch;
+          min-width: 0;
+        }
+
+        .container-main .col-content {
+          min-width: 0;
+          max-height: calc(100vh - var(--bandit-docs-header-height) - var(--bandit-docs-footer-height) - clamp(12px, 1.5vh, 24px));
+          overflow-y: auto;
+          padding-right: clamp(8px, 1vw, 20px);
+          padding-bottom: calc(var(--bandit-docs-footer-height) + clamp(16px, 2vh, 28px));
+          scrollbar-gutter: stable;
+          overscroll-behavior: contain;
+          -webkit-overflow-scrolling: touch;
+        }
+
+        .container-main .col-navigation .tsd-navigation a,
+        .container-main .col-sidebar .tsd-navigation a {
+          white-space: normal;
         }
       }
-    }
 
-    return null;
-  };
+      footer {
+        position: fixed;
+        left: 0;
+        right: 0;
+        bottom: 0;
+        margin: 0;
+        padding: 0 clamp(18px, 2.8vw, 54px);
+        height: var(--bandit-docs-footer-height);
+        display: flex;
+        align-items: center;
+        background: rgba(5, 11, 25, 0.94);
+        backdrop-filter: blur(14px);
+        border-top: 1px solid rgba(148, 163, 184, 0.2);
+        z-index: 200;
+      }
 
-  const performScroll = (target) => {
-    if (!target) {
-      return;
-    }
-    try {
-      target.scrollIntoView({ block: "start", inline: "nearest" });
-    } catch {
-      target.scrollIntoView();
-    }
-  };
+      footer > * {
+        max-width: min(100%, calc(100vw - clamp(32px, 6vw, 120px)));
+        margin: 0 auto;
+      }
 
-  const scrollToId = (id, attempt = 0) => {
-    if (!id || attempt > MAX_LOOKUPS) {
-      return;
-    }
+      .${EMBEDDED_CLASS} footer {
+        padding-left: clamp(18px, 2.4vw, 54px);
+        padding-right: clamp(18px, 2.4vw, 54px);
+      }
 
-    ensureAliasAnchors();
+      body {
+        margin: 0;
+        padding-bottom: 0;
+      }
 
-    const target = resolveTarget(id);
-    if (!target) {
-      requestAnimationFrame(() => scrollToId(id, attempt + 1));
-      return;
-    }
+      @media (min-width: 1280px) {
+        body {
+          overflow-y: hidden;
+        }
+      }
 
-    performScroll(target);
-    RESCROLL_DELAYS.forEach((delay) => setTimeout(() => performScroll(target), delay));
-  };
+      @media (min-width: 1200px) {
+        .page-menu,
+        .site-menu {
+          max-height: calc(100vh - 2rem - 114px) !important;
+        }
+      }
 
-  const consumeStoredTarget = () => {
-    try {
-      const stored = window.sessionStorage.getItem(STORAGE_KEY);
-      if (stored) {
-        window.sessionStorage.removeItem(STORAGE_KEY);
-        try {
-          const parsed = JSON.parse(stored);
-          if (parsed && (parsed.rawId || parsed.aliasId)) {
-            return {
-              rawId: parsed.rawId ?? null,
-              aliasId: parsed.aliasId ?? sanitizeId(parsed.rawId ?? null),
-            };
-          }
-        } catch {
-          // fall back to treating it as a plain ID
-          return {
-            rawId: stored,
-            aliasId: sanitizeId(stored),
-          };
+      @media (min-width: 770px) and (max-width: 1199px) {
+        .site-menu {
+          max-height: calc(100vh - 2rem - 114px) !important;
         }
       }
-    } catch {
-      // ignore storage access failures
-    }
-    return { rawId: null, aliasId: null };
-  };
 
-  const createTarget = (rawId) => ({
-    rawId: rawId ?? null,
-    aliasId: rawId ? sanitizeId(rawId) : null,
-  });
+      @media (max-width: 1024px) {
+        html,
+        body {
+          overflow: auto;
+        }
 
-  const latestTarget = (() => {
-    const stored = consumeStoredTarget();
-    if (stored && (stored.rawId || stored.aliasId)) {
-      return stored;
-    }
-    const initial = decodeHash(window.location.hash);
-    return createTarget(initial);
-  })();
+        .container {
+          padding-left: clamp(16px, 4.5vw, 28px);
+          padding-right: clamp(16px, 4.5vw, 28px);
+        }
 
-  const isTargetEmpty = (target) => !target || (!target.rawId && !target.aliasId);
+        .container-main {
+          display: block;
+          max-width: min(100%, 780px);
+          margin-left: auto;
+          margin-right: auto;
+          min-height: auto;
+          height: auto;
+          padding-top: clamp(18px, 6vw, 28px);
+          padding-bottom: clamp(18px, 6vw, 32px);
+        }
 
-  const applyScrollForTarget = (target) => {
-    if (isTargetEmpty(target)) {
-      return;
-    }
-    const tried = new Set();
-    const candidates = [];
-    if (target.rawId) {
-      candidates.push(target.rawId);
-    }
-    if (target.aliasId && target.aliasId !== target.rawId) {
-      candidates.push(target.aliasId);
-    }
-    candidates.forEach((candidate) => {
-      if (candidate && !tried.has(candidate)) {
-        scrollToId(candidate);
-        tried.add(candidate);
+        .container-main .col-navigation,
+        .container-main .col-sidebar {
+          position: relative;
+          top: auto;
+          max-height: none;
+          overflow: visible;
+          padding-right: 0;
+          padding-bottom: clamp(24px, 6vw, 48px);
+        }
+
+        .container-main .col-content {
+          max-height: none;
+          overflow: visible;
+          padding-right: 0;
+          padding-bottom: clamp(72px, 10vw, 120px);
+        }
+
+        footer {
+          position: static;
+          padding: clamp(18px, 6vw, 28px) 0 clamp(24px, 6vw, 36px);
+          background: transparent;
+          backdrop-filter: none;
+          border-top: 1px solid rgba(148, 163, 184, 0.24);
+          height: auto;
+        }
+
+        footer > * {
+          max-width: none;
+          padding-left: clamp(16px, 4.5vw, 28px);
+          padding-right: clamp(16px, 4.5vw, 28px);
+        }
+
+        body {
+          overflow-y: auto;
+          padding-bottom: clamp(48px, 12vw, 88px);
+        }
+
+        #${BACK_BUTTON_ID} {
+          display: flex;
+        }
       }
-    });
-  };
 
-  const ensureBodyVisibleThenScroll = (target) => {
-    if (isTargetEmpty(target)) {
-      return;
-    }
+      .${EMBEDDED_CLASS} .container {
+        padding-left: clamp(18px, 2.4vw, 54px);
+        padding-right: clamp(18px, 2.4vw, 54px);
+      }
+
+      .${EMBEDDED_CLASS} .container-main {
+        margin-left: auto;
+        margin-right: auto;
+        width: min(100%, calc(100vw - clamp(32px, 6vw, 120px)));
+      }
+
+      .${EMBEDDED_CLASS} .tsd-page-toolbar {
+        position: sticky;
+        top: 0;
+        z-index: 90;
+        min-height: 56px;
+        padding: 0;
+        box-shadow: inset 0 -1px 0 rgba(148, 163, 184, 0.18);
+        backdrop-filter: blur(18px);
+      }
 
-    const checkVisibility = () => {
-      ensureAliasAnchors();
-      if (!document.body) {
-        requestAnimationFrame(checkVisibility);
-        return;
+      .${EMBEDDED_CLASS} .tsd-page-toolbar .tsd-toolbar-contents {
+        margin: 0 auto;
+        padding: 0 clamp(18px, 2.4vw, 54px);
+        width: min(100%, calc(100vw - clamp(32px, 6vw, 120px)));
+        display: flex;
+        align-items: center;
       }
 
-      const visible = window.getComputedStyle(document.body).display !== "none";
-      if (visible) {
-        applyScrollForTarget(target);
-      } else {
-        requestAnimationFrame(checkVisibility);
+      #${BACK_BUTTON_ID} {
+        position: fixed;
+        left: 50%;
+        transform: translateX(-50%);
+        bottom: calc(env(safe-area-inset-bottom, 0px) + clamp(18px, 6vw, 32px));
+        z-index: 2147483647;
+        border: 1px solid rgba(148, 163, 184, 0.18);
+        border-radius: clamp(32px, 10vw, 999px);
+        padding: clamp(12px, 4vw, 18px) clamp(18px, 7vw, 22px);
+        min-height: 46px;
+        width: min(480px, calc(100vw - clamp(28px, 10vw, 64px)));
+        background: linear-gradient(135deg, rgba(63, 133, 245, 0.95), rgba(14, 165, 233, 0.95));
+        color: #f8fafc;
+        font-size: clamp(14px, 4vw, 16px);
+        font-weight: 700;
+        font-family: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+        box-shadow: 0 20px 36px rgba(8, 15, 32, 0.35);
+        display: none;
+        align-items: center;
+        justify-content: center;
+        gap: clamp(4px, 2vw, 10px);
+        cursor: pointer;
+        backdrop-filter: blur(18px);
+        transition: transform 0.2s ease, box-shadow 0.2s ease;
       }
-    };
 
-    checkVisibility();
+      #${BACK_BUTTON_ID}:hover {
+        transform: translate(-50%, -2px);
+        box-shadow: 0 26px 45px rgba(8, 15, 32, 0.4);
+      }
+
+      #${BACK_BUTTON_ID}:active {
+        transform: translate(-50%, 0) scale(0.97);
+        box-shadow: 0 16px 30px rgba(8, 15, 32, 0.4);
+      }
+
+      #${BACK_BUTTON_ID} svg {
+        width: clamp(16px, 4vw, 18px);
+        height: clamp(16px, 4vw, 18px);
+        fill: currentColor;
+      }
+
+      #${BACK_BUTTON_ID} span {
+        white-space: nowrap;
+        letter-spacing: 0.01em;
+      }
+
+      @media (max-width: 1024px) {
+        .container {
+          width: 100%;
+          max-width: calc(100vw - clamp(8px, 4vw, 28px));
+          margin: 0 auto;
+          padding: clamp(14px, 4.5vw, 24px);
+        }
+
+        #${BACK_BUTTON_ID} {
+          display: flex;
+        }
+      }
+    `;
+
+    document.head.appendChild(style);
   };
 
-  const hookTypeDocApp = () => {
-    if (!window.app || typeof window.app.showPage !== "function" || window.app.__banditHooked) {
-      if (!window.app) {
-        setTimeout(hookTypeDocApp, 40);
+  const revealBody = () => {
+    if (document.body) {
+      document.body.classList.add("bandit-docs-ready");
+      document.body.style.removeProperty("display");
+    }
+  };
+
+  const ensureBackButton = () => {
+    if (isEmbedded) return;
+
+    let button = document.getElementById(BACK_BUTTON_ID);
+    if (!button) {
+      button = document.createElement("button");
+      button.id = BACK_BUTTON_ID;
+      button.type = "button";
+      button.setAttribute("aria-label", "Return to npm package page");
+      button.innerHTML =
+        '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M15.41 7.41 14 6l-6 6 6 6 1.41-1.41L10.83 12z"/></svg><span>Back to overview</span>';
+      button.addEventListener("click", () => {
+        const fallback = () => {
+          window.location.href = FALLBACK_URL;
+        };
+        const timeout = setTimeout(fallback, 180);
+        window.addEventListener(
+          "popstate",
+          () => {
+            clearTimeout(timeout);
+          },
+          { once: true },
+        );
+        window.history.back();
+      });
+      document.body.appendChild(button);
+    }
+  };
+
+  const replaceGatewaySnippet = (attempt = 0) => {
+    const codeBlocks = Array.from(document.querySelectorAll("pre code"));
+    const targetBlock = codeBlocks.find((block) => {
+      const text = block.textContent || "";
+      return text.includes(GATEWAY_MARKER) && text.includes("Voice Services (TTS/STT)");
+    });
+
+    if (!targetBlock) {
+      if (attempt < MAX_GATEWAY_ATTEMPTS) {
+        setTimeout(() => replaceGatewaySnippet(attempt + 1), 200);
       }
       return;
     }
 
-    const originalShowPage = window.app.showPage.bind(window.app);
-    window.app.showPage = (...args) => {
-      const result = originalShowPage(...args);
-      setTimeout(() => {
-        ensureAliasAnchors();
-        ensureBodyVisibleThenScroll(latestTarget);
-      }, 16);
-      return result;
-    };
-
-    window.app.__banditHooked = true;
+    const pre = targetBlock.closest("pre");
+    if (!pre) return;
+
+    const copyButton = pre.nextElementSibling;
+    if (copyButton?.tagName === "BUTTON") {
+      copyButton.remove();
+    }
+
+    const wrapper = document.createElement("div");
+    wrapper.className = "gateway-doc";
+    wrapper.innerHTML = `
+      <p>Set <code>VITE_DEFAULT_MODEL</code> / <code>VITE_FALLBACK_MODEL</code> to the exact Ollama model tags you have available (<code>gemma</code>, <code>llava</code>, <code>moondream</code>, or your own custom builds). Bandit automatically detects multimodal Ollama models, so setting <code>llava</code>, <code>moondream</code>, or other vision-capable variants enables image understanding with no extra code.</p>
+      <h3>🎤 Voice Services (TTS/STT)</h3>
+      <p>The Bandit Engine supports Text-to-Speech (TTS) and Speech-to-Text (STT) through your gateway API. These services are <strong>technology-agnostic</strong> — you can implement them using any backend technology:</p>
+      <ul>
+        <li>
+          <strong>TTS Endpoint (<code>POST /api/tts</code>)</strong>
+          <ul>
+            <li><strong>Input</strong>: <code>{ text: string, voice?: string, speed?: number }</code></li>
+            <li><strong>Output</strong>: Audio file (MP3, WAV, etc.) or streaming audio</li>
+            <li><strong>Compatible with</strong>: OpenAI TTS, Azure Speech, Google Cloud TTS, AWS Polly, local TTS servers, or custom implementations</li>
+          </ul>
+        </li>
+        <li>
+          <strong>STT Endpoint (<code>POST /api/stt/transcribe</code>)</strong>
+          <ul>
+            <li><strong>Input</strong>: Audio file upload (multipart/form-data)</li>
+            <li><strong>Output</strong>: <code>{ text: string }</code> or <code>{ transcription: string }</code></li>
+            <li><strong>Compatible with</strong>: OpenAI Whisper, Azure Speech, Google Speech, AWS Transcribe, local Whisper servers, or custom implementations</li>
+          </ul>
+        </li>
+        <li>
+          <strong>Service Discovery (<code>GET /api/tts/available-models</code>)</strong>
+          <ul>
+            <li><strong>Output</strong>: <code>{ models: string[], defaultModel: string, fallbackModel: string }</code></li>
+            <li>Used for automatic service availability detection and voice model selection</li>
+          </ul>
+        </li>
+      </ul>
+      <blockquote>Quickstart note: the generated Express gateway ships these TTS/STT routes as <code>501</code> placeholders so you can connect your own provider. Voice features remain disabled until you implement them server-side.</blockquote>
+      <p>See the <a href="media/02_gateway_api.md">Gateway API Contract</a> for complete implementation examples in multiple languages.</p>
+      <p>Use the Management interface to switch providers anytime or migrate from direct to gateway setup.</p>
+    `;
+
+    pre.replaceWith(wrapper);
   };
 
-  const handleInitialScroll = () => {
-    ensureAliasAnchors();
-    ensureBodyVisibleThenScroll(latestTarget);
+  const init = () => {
+    document.documentElement.classList.add(isEmbedded ? EMBEDDED_CLASS : STANDALONE_CLASS);
+    addStyles();
+    revealBody();
+    ensureBackButton();
+    replaceGatewaySnippet();
   };
 
   if (document.readyState === "complete" || document.readyState === "interactive") {
-    handleInitialScroll();
+    init();
   } else {
-    window.addEventListener("DOMContentLoaded", handleInitialScroll, { once: true });
+    document.addEventListener("DOMContentLoaded", init, { once: true });
   }
-
-  window.addEventListener("load", () => {
-    ensureAliasAnchors();
-    ensureBodyVisibleThenScroll(latestTarget);
-  });
-
-  window.addEventListener("hashchange", () => {
-    const nextTarget = decodeHash(window.location.hash);
-    if (nextTarget) {
-      latestTarget.rawId = nextTarget;
-      latestTarget.aliasId = sanitizeId(nextTarget);
-    }
-    ensureBodyVisibleThenScroll(latestTarget);
-  });
-
-  const observer = new MutationObserver(() => {
-    ensureAliasAnchors();
-    ensureBodyVisibleThenScroll(latestTarget);
-  });
-  observer.observe(document.body ?? document.documentElement, {
-    attributes: true,
-    childList: true,
-    subtree: true,
-  });
-
-  hookTypeDocApp();
 })();