Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat(docs): entry pill + push rail for VikingBot (#3978)

t0saki5c09e61ce80a
diff --git a/docs/.vitepress/theme/VikingBotAssistant.vue b/docs/.vitepress/theme/VikingBotAssistant.vue
deleted file mode 100644
index f33c5f996..000000000
--- a/docs/.vitepress/theme/VikingBotAssistant.vue
+++ /dev/null
@@ -1,140 +0,0 @@
-<script setup lang="ts">
-import { computed, ref } from 'vue'
-import { useData } from 'vitepress'
-
-type VikingBotWidgetLocale = 'en' | 'zh'
-
-type VikingBotWidgetMountOptions = {
- site: string
- locale?: VikingBotWidgetLocale
- /**
- * 'none' keeps the widget from rendering its own floating launcher AND from
- * binding a click handler of its own — this component owns the trigger, so a
- * widget-side listener would toggle the panel a second time per click and
- * desync `aria-expanded`.
- */
- trigger?: 'none' | 'floating'
- open?: boolean
- onEvent?: (name: string, payload?: unknown) => void
-}
-
-type VikingBotWidgetApi = {
- mount: (options: VikingBotWidgetMountOptions) => void
- open: () => void
- toggle: () => void
-}
-
-declare global {
- interface Window {
- VikingBotWidget?: VikingBotWidgetApi
- }
-}
-
-const WIDGET_URL =
- import.meta.env.VITE_VIKINGBOT_WIDGET_URL ||
- 'https://openviking.net/studio/embed-widget/vikingbot-widget.js'
-const WIDGET_SITE = 'vikingbot'
-
-let widgetScriptPromise: Promise<void> | null = null
-let widgetMounted = false
-
-const { lang } = useData()
-const isOpen = ref(false)
-const isLoading = ref(false)
-const hasError = ref(false)
-
-const isZh = computed(() => lang.value.startsWith('zh'))
-const locale = computed<VikingBotWidgetLocale>(() => (isZh.value ? 'zh' : 'en'))
-const copy = computed(() => isZh.value ? {
- trigger: '问问 VikingBot',
- failed: 'VikingBot 暂时无法加载,请稍后重试。'
-} : {
- trigger: 'Ask VikingBot',
- failed: 'VikingBot failed to load. Please try again later.'
-})
-
-function loadWidgetScript() {
- if (!widgetScriptPromise) {
- widgetScriptPromise = new Promise<void>((resolve, reject) => {
- const script = document.createElement('script')
- script.src = WIDGET_URL
- script.async = true
- script.dataset.vikingbotWidget = ''
- script.addEventListener('load', () => resolve(), { once: true })
- script.addEventListener(
- 'error',
- () => {
- script.remove()
- reject(new Error(`Failed to load the VikingBot widget from ${WIDGET_URL}`))
- },
- { once: true }
- )
- document.head.appendChild(script)
- })
- }
-
- return widgetScriptPromise.catch((error: unknown) => {
- // Let the next click retry a failed load instead of caching the rejection.
- widgetScriptPromise = null
- throw error
- })
-}
-
-function onWidgetEvent(name: string) {
- if (name === 'open') isOpen.value = true
- if (name === 'close') isOpen.value = false
-}
-
-async function onTriggerClick() {
- if (isLoading.value) return
-
- hasError.value = false
- isLoading.value = true
-
- try {
- await loadWidgetScript()
-
- const widget = window.VikingBotWidget
- if (!widget) throw new Error('The VikingBot widget script did not register window.VikingBotWidget')
-
- if (widgetMounted) {
- // No local state update here: toggle() emits open/close synchronously and
- // onWidgetEvent is the single writer of isOpen. Flipping it here too
- // would invert aria-expanded on every click.
- widget.toggle()
- return
- }
-
- widget.mount({
- site: WIDGET_SITE,
- locale: locale.value,
- trigger: 'none',
- open: true,
- onEvent: onWidgetEvent
- })
- widgetMounted = true
- } catch (error) {
- console.error(error)
- hasError.value = true
- } finally {
- isLoading.value = false
- }
-}
-</script>
-
-<template>
- <span class="vikingbot-launcher">
- <button
- class="vikingbot-trigger"
- type="button"
- :aria-label="copy.trigger"
- :aria-expanded="isOpen"
- :aria-busy="isLoading"
- @click="onTriggerClick"
- >
- <span class="vikingbot-spark" aria-hidden="true">✦</span>
- <span class="vikingbot-trigger-label">{{ copy.trigger }}</span>
- </button>
- <span v-if="hasError" class="vikingbot-trigger-error" role="alert">{{ copy.failed }}</span>
- </span>
-</template>
diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css
index 7fe41961c..d2647393e 100644
--- a/docs/.vitepress/theme/custom.css
+++ b/docs/.vitepress/theme/custom.css
@@ -12,6 +12,30 @@
--vp-c-text-2: #47534f;
--vp-font-family-base: "Avenir Next", "Gill Sans", "Trebuchet MS", sans-serif;
--vp-font-family-mono: "SFMono-Regular", Consolas, "Liberation Mono", monospace;
+
+ /* Embed-widget theming. The widget renders in a shadow root whose :host does
+ `all: initial` — that resets inherited properties but NOT custom
+ properties, so these reach it and paint the panel in the docs palette.
+ Written in terms of --vp-* so the appearance toggle carries them; the
+ .dark block below only redefines what cannot be expressed that way. */
+ --ovw-font: var(--vp-font-family-base);
+ --ovw-mono: var(--vp-font-family-mono);
+ --ovw-bg: var(--vp-c-bg-elv);
+ --ovw-raised: var(--vp-c-bg-soft);
+ --ovw-inset: var(--vp-c-bg-alt);
+ --ovw-code-bg: var(--vp-c-bg-alt);
+ --ovw-fg: var(--vp-c-text-1);
+ --ovw-muted: var(--vp-c-text-2);
+ --ovw-border: var(--vp-c-divider);
+ --ovw-accent: var(--vp-c-brand-1);
+ --ovw-accent-fg: #ffffff;
+ --ovw-accent-soft: var(--vp-c-brand-soft);
+ --ovw-accent-border: rgba(20, 184, 166, 0.34);
+ --ovw-shadow: var(--vp-shadow-3);
+ --ovw-launcher-shadow: var(--vp-shadow-2);
+ --ovw-rail-bg: var(--vp-c-bg);
+ /* Height of the fixed VPNav; without it the rail slides under the navbar. */
+ --ovw-rail-top: 64px;
}
@media (min-width: 1280px) {
@@ -46,6 +70,11 @@
--vp-c-bg-soft: #1e1e1e;
--vp-c-text-1: #edf7f3;
--vp-c-text-2: #bbcac5;
+
+ /* The rest of the --ovw-* map inherits from --vp-* and flips with this
+ block; only the two literals need restating. */
+ --ovw-accent-fg: #0f0f0f;
+ --ovw-accent-border: rgba(94, 234, 212, 0.34);
}
.VPHome {
@@ -120,73 +149,6 @@
margin-right: 12px;
}
-/* VikingBot docs assistant (shared embed widget launcher) */
-.vikingbot-launcher {
- position: relative;
- display: inline-flex;
- align-items: center;
-}
-
-.vikingbot-trigger {
- display: inline-flex;
- height: 40px;
- flex: 0 0 auto;
- align-items: center;
- gap: 8px;
- margin-right: 12px;
- padding: 0 14px;
- border: 1px solid color-mix(in srgb, var(--vp-c-brand-1) 32%, var(--vp-c-divider));
- border-radius: 8px;
- background: color-mix(in srgb, var(--vp-c-brand-soft) 45%, var(--vp-c-bg));
- color: var(--vp-c-brand-1);
- font: inherit;
- font-size: 13px;
- font-weight: 700;
- cursor: pointer;
- transition: border-color 0.2s, background-color 0.2s, transform 0.2s;
-}
-
-.vikingbot-trigger:hover {
- border-color: var(--vp-c-brand-1);
- background: var(--vp-c-brand-soft);
- transform: translateY(-1px);
-}
-
-.vikingbot-spark {
- font-size: 17px;
- line-height: 1;
-}
-
-.vikingbot-trigger-error {
- position: absolute;
- z-index: 90;
- top: calc(100% + 6px);
- right: 12px;
- max-width: 260px;
- padding: 6px 10px;
- border: 1px solid var(--vp-c-divider);
- border-radius: 6px;
- background: var(--vp-c-bg-elv);
- color: var(--vp-c-text-2);
- font-size: 12px;
- line-height: 1.4;
- box-shadow: var(--vp-shadow-2);
-}
-
-@media (max-width: 1279px) {
- .vikingbot-trigger-label { display: none; }
- .vikingbot-trigger { width: 40px; justify-content: center; padding: 0; }
-}
-
-@media (max-width: 767px) {
- .vikingbot-trigger { margin-right: 8px; }
- .vikingbot-trigger-error { max-width: 200px; }
-}
-
-@media (prefers-reduced-motion: reduce) {
- .vikingbot-trigger { transition: none; }
-}
-
.ov-docs-search-trigger {
display: inline-flex;
align-items: center;
@@ -504,3 +466,125 @@
.api-example-tabs__panel > p:first-child { margin-top: 0; }
.api-example-tabs__panel > div[class*='language-'] { margin: 0; }
.api-example-tabs-enhancer { display: none; }
+
+/* ── VikingBot rail: the host half of the widget's push contract ────────
+ The widget publishes `ov-assistant-open` / `ov-assistant-resizing` /
+ `ov-assistant-pill` plus `--ov-rail` on <html>; nothing below reaches into
+ the widget. 900px is pinned to the widget's own sheet breakpoint — below it
+ the panel is a bottom sheet and there is no rail to make room for. */
+@media (min-width: 900px) {
+ html.ov-assistant-open .Layout,
+ html.ov-assistant-open .VPNav {
+ padding-right: var(--ov-rail);
+ }
+
+ html.ov-assistant-open .Layout,
+ html.ov-assistant-open .VPNav,
+ html.ov-assistant-open .VPSidebar {
+ transition: padding-right 0.24s ease, right 0.24s ease;
+ }
+
+ /* VitePress absolutely positions the title against the sidebar column; once
+ the whole layout is inset, that anchor is wrong and the logo collides with
+ the content. Let it sit in the flex row instead. */
+ html.ov-assistant-open .VPNavBar.has-sidebar .wrapper {
+ padding-right: 16px;
+ padding-left: 16px;
+ }
+
+ html.ov-assistant-open .VPNavBar.has-sidebar .container > .title {
+ position: relative;
+ top: auto;
+ left: auto;
+ width: auto;
+ flex: 0 0 auto;
+ padding: 0;
+ }
+
+ html.ov-assistant-open .VPNavBar.has-sidebar .container > .content {
+ padding-right: 0;
+ padding-left: 24px;
+ }
+
+ html.ov-assistant-open .VPNavBarTitle .logo {
+ display: block;
+ width: 28px;
+ height: 28px;
+ flex: 0 0 28px;
+ object-fit: cover;
+ }
+
+ html.ov-assistant-open .VPContent .VPDoc {
+ padding-right: 60px;
+ padding-left: 60px;
+ }
+
+ html.ov-assistant-open .VPContent .VPDoc.has-aside > .container > .content {
+ padding-right: 0;
+ padding-left: 0;
+ }
+}
+
+/* Between the sheet breakpoint and the wide layout there is only room for one
+ of {sidebar, doc, aside, rail}. Drop the two navigation columns rather than
+ squeezing the prose to a gutter. */
+@media (min-width: 900px) and (max-width: 1279px) {
+ html.ov-assistant-open .VPSidebar {
+ display: none;
+ }
+
+ html.ov-assistant-open .VPContent.has-sidebar {
+ padding-left: 0;
+ }
+
+ html.ov-assistant-open .VPContent .VPDoc > .container > .aside {
+ display: none !important;
+ }
+}
+
+/* The sidebar comes back at 1280, but sidebar + aside + rail leaves the prose
+ at ~300px. Screenshots at 1280 made the call: keep the sidebar, drop the
+ aside, and the reading column roughly doubles. */
+@media (min-width: 1280px) and (max-width: 1439px) {
+ html.ov-assistant-open .VPContent .VPDoc > .container > .aside {
+ display: none !important;
+ }
+}
+
+@media (min-width: 900px) and (max-width: 1599px) {
+ html.ov-assistant-open .VPContent .VPDoc {
+ padding-right: 32px;
+ padding-left: 32px;
+ }
+}
+
+@media (min-width: 1280px) {
+ html.ov-assistant-open .VPSidebar {
+ width: var(--vp-sidebar-width);
+ padding-left: 60px;
+ }
+
+ html.ov-assistant-open .VPContent .VPDoc > .container > .aside {
+ max-width: 240px;
+ padding-left: 16px;
+ }
+}
+
+/* A width drag fires on every pointermove; without this each one restarts the
+ 0.24s ease and the layout trails the pointer. */
+html.ov-assistant-resizing .Layout,
+html.ov-assistant-resizing .VPNav,
+html.ov-assistant-resizing .VPSidebar {
+ transition: none;
+}
+
+/* Clearance so the entry pill never sits on top of the last line of a page. */
+html.ov-assistant-pill .VPContent {
+ padding-bottom: 96px;
+}
+
+@media (max-width: 899.98px) {
+ html.ov-assistant-pill .VPContent {
+ padding-bottom: calc(86px + env(safe-area-inset-bottom, 0px));
+ }
+}
diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts
index 5fc591f1a..bd14b9647 100644
--- a/docs/.vitepress/theme/index.ts
+++ b/docs/.vitepress/theme/index.ts
@@ -5,7 +5,7 @@ import CopyMarkdownButton from './CopyMarkdownButton.vue'
import LlmsTxtLink from './LlmsTxtLink.vue'
import OpenVikingSearch from './OpenVikingSearch.vue'
import ApiExampleTabsEnhancer from './ApiExampleTabsEnhancer.vue'
-import VikingBotAssistant from './VikingBotAssistant.vue'
+import { initVikingBotWidget, syncVikingBotLocale } from './vikingbot-widget'
import { trackPageView } from './track'
import './custom.css'
@@ -309,18 +309,22 @@ export default {
h(CopyMarkdownButton)
]),
'doc-after': () => h(ApiExampleTabsEnhancer),
- 'nav-bar-content-before': () => [h(OpenVikingSearch), h(VikingBotAssistant)]
+ 'nav-bar-content-before': () => h(OpenVikingSearch)
})
},
enhanceApp({ router }: EnhanceAppContext) {
if (import.meta.env.SSR || typeof window === 'undefined') return
trackPageView(window.location.pathname)
+ initVikingBotWidget()
const previousHook = router.onAfterRouteChanged
router.onAfterRouteChanged = (to: string) => {
previousHook?.(to)
trackPageView(to.split('?')[0].split('#')[0])
+ // <html lang> is rewritten by the router before this fires, so a locale
+ // switch re-mounts the widget in the language the reader just chose.
+ syncVikingBotLocale()
}
}
}
diff --git a/docs/.vitepress/theme/vikingbot-widget.ts b/docs/.vitepress/theme/vikingbot-widget.ts
new file mode 100644
index 000000000..7ea4bedab
--- /dev/null
+++ b/docs/.vitepress/theme/vikingbot-widget.ts
@@ -0,0 +1,144 @@
+/**
+ * Loads the shared VikingBot embed widget for the docs site.
+ *
+ * There is no docs-owned trigger any more: the widget renders its own bottom
+ * entry pill and right-edge toggle, the same as on the marketing site and the
+ * blog, and pushes the VitePress layout aside via the rail contract read in
+ * custom.css.
+ *
+ * Everything here is client-only. VitePress prerenders the theme during build,
+ * so nothing may run at module scope that touches `window`.
+ */
+
+const WIDGET_URL =
+ import.meta.env.VITE_VIKINGBOT_WIDGET_URL ||
+ 'https://openviking.net/studio/embed-widget/vikingbot-widget.js'
+const WIDGET_SITE = 'vikingbot'
+
+type WidgetLocale = 'en' | 'zh'
+
+type WidgetMountOptions = {
+ site: string
+ locale?: WidgetLocale
+ /** 'composer' renders the entry pill plus the right-edge toggle. */
+ trigger?: 'composer' | 'floating' | 'none'
+ /** 'push' publishes the rail contract on <html>. */
+ layout?: 'push' | 'overlay'
+ conversation?: 'thread' | 'channel'
+ open?: boolean
+}
+
+type WidgetApi = {
+ mount: (options: WidgetMountOptions) => void
+ open: () => void
+ toggle: () => void
+ close: () => void
+ unmount: () => void
+}
+
+declare global {
+ interface Window {
+ VikingBotWidget?: WidgetApi
+ }
+}
+
+let scriptPromise: Promise<void> | null = null
+let mountedLocale: WidgetLocale | null = null
+let started = false
+
+function loadScriptOnce(): Promise<void> {
+ if (!scriptPromise) {
+ scriptPromise = new Promise<void>((resolve, reject) => {
+ const script = document.createElement('script')
+ script.src = WIDGET_URL
+ script.async = true
+ script.dataset.vikingbotWidget = ''
+ script.addEventListener('load', () => resolve(), { once: true })
+ script.addEventListener(
+ 'error',
+ () => {
+ script.remove()
+ reject(new Error(`Failed to load the VikingBot widget from ${WIDGET_URL}`))
+ },
+ { once: true }
+ )
+ document.head.appendChild(script)
+ })
+ }
+
+ return scriptPromise.catch((error: unknown) => {
+ // Drop the cached rejection so a later attempt can retry the load.
+ scriptPromise = null
+ throw error
+ })
+}
+
+/**
+ * VitePress writes the active locale onto <html lang>, which survives a
+ * configured `base` — unlike matching the pathname against '/zh'.
+ */
+function currentLocale(): WidgetLocale {
+ return document.documentElement.lang.toLowerCase().startsWith('zh') ? 'zh' : 'en'
+}
+
+function mount(locale: WidgetLocale) {
+ const widget = window.VikingBotWidget
+ if (!widget) {
+ throw new Error('The VikingBot widget script did not register window.VikingBotWidget')
+ }
+ widget.mount({
+ site: WIDGET_SITE,
+ locale,
+ trigger: 'composer',
+ layout: 'push'
+ })
+ mountedLocale = locale
+}
+
+/**
+ * Idle window before the script is fetched. The widget is an assistive
+ * affordance, not documentation, and must not compete with the page for
+ * bandwidth. requestIdleCallback is unavailable on Safari < 16.4.
+ */
+const IDLE_FALLBACK_MS = 2500
+
+function whenIdle(run: () => void) {
+ if (typeof window.requestIdleCallback === 'function') {
+ window.requestIdleCallback(run, { timeout: IDLE_FALLBACK_MS })
+ return
+ }
+ window.setTimeout(run, IDLE_FALLBACK_MS)
+}
+
+/** Mounts the widget once per page load. Safe to call on every enhanceApp. */
+export function initVikingBotWidget() {
+ if (started) return
+ started = true
+
+ whenIdle(() => {
+ void loadScriptOnce()
+ .then(() => {
+ mount(currentLocale())
+ })
+ .catch((error: unknown) => {
+ // Silent beyond the console: a reader who never asked for the widget
+ // should not be shown an error about a script they did not request.
+ console.error(error)
+ })
+ })
+}
+
+/**
+ * Switching locale is a client-side route change, so a widget mounted in the
+ * other language would keep its old strings for the rest of the session.
+ * Remount it — the visitor just asked for a different language, and their
+ * conversation is keyed on the browser, not on this mount.
+ */
+export function syncVikingBotLocale() {
+ const locale = currentLocale()
+ if (!mountedLocale || mountedLocale === locale) return
+ const widget = window.VikingBotWidget
+ if (!widget) return
+ widget.unmount()
+ mount(locale)
+}