vite-plugin-agentation-vue 0.0.2

package/src/runtime/entry.ts

@@ -0,0 +1,146 @@
+import { createApp } from "vue"
+import { findTraceFromElement } from "vite-plugin-vue-tracer/client/record"
+import {
+  OverlayRoot,
+  createAnnotationsStore,
+  createAreaSelectionState,
+  createSelectionState,
+  createSettingsState,
+} from "@liuovo/agentation-vue-ui"
+import type { RuntimeBridge, UiNotification } from "@liuovo/agentation-vue-ui"
+import type { ResolvedAgentationVueOptions } from "../types.js"
+import { bindTracer } from "./resolver/index.js"
+import { setupInfrastructure, attachListeners } from "./bootstrap.js"
+import { createRuntimeSyncBridge } from "./sync.js"
+
+// ---------------------------------------------------------------------------
+// Browser console logging (styled with %c)
+// ---------------------------------------------------------------------------
+
+const badgeStyle = [
+  "background: linear-gradient(135deg, #0f172a 0%, #1e293b 100%)",
+  "color: #34d399",
+  "font-weight: 700",
+  "padding: 2px 8px",
+  "border-radius: 4px",
+  "font-size: 11px",
+].join(";")
+
+const msgStyle = "color: #22d3ee; font-weight: 600;"
+const detailStyle = "color: #a78bfa;"
+
+function logBrowser(emoji: string, message: string, detail = ""): void {
+  console.log(
+    `%c🛰 agentation%c ${emoji} ${message}%c${detail ? ` ${detail}` : ""}`,
+    badgeStyle,
+    msgStyle,
+    detailStyle,
+  )
+}
+
+/**
+ * Runtime entry point — executed in the browser via the virtual module.
+ *
+ * 1. Disposes any previous runtime instance (supports HMR re-injection)
+ * 2. Binds the vue-tracer lookup function into the resolver
+ * 3. Sets up DOM containers and storage bridge
+ * 4. Creates store, selection, settings, and area selection state
+ * 5. Attaches event listeners that drive Vue state
+ * 6. Mounts the Vue overlay app
+ */
+export function runAgentationRuntime(options: ResolvedAgentationVueOptions): void {
+  logBrowser("✨", "Runtime starting", `storagePrefix="${options.storagePrefix}" locale="${options.locale}"`)
+
+  // Dispose previous instance if re-injected (e.g. HMR)
+  window.__agentationRuntime?.dispose()
+
+  // Bind vue-tracer into the resolver
+  const tracerAvailable = typeof findTraceFromElement === "function"
+  if (tracerAvailable) {
+    logBrowser("🔎", "Binding vue-tracer", "precise source mapping enabled")
+    bindTracer(findTraceFromElement)
+  } else {
+    console.warn(
+      "%c🛰 agentation%c ⚠️ vue-tracer not found — using Vue internals fallback",
+      badgeStyle,
+      "color: #f59e0b; font-weight: 600;",
+    )
+  }
+
+  // 1. Infrastructure: DOM containers + storage + source resolver
+  logBrowser("🏗️", "Setting up infrastructure", "DOM containers + storage bridge")
+  const infra = setupInfrastructure(options.storagePrefix)
+  const notificationListeners = new Set<(notification: UiNotification) => void>()
+
+  // 2. Build the bridge for the UI layer
+  const bridge: RuntimeBridge = {
+    appRoot: infra.appRoot,
+    overlayRoot: infra.overlayRoot,
+    options: { outputDetail: options.outputDetail },
+    storage: infra.storage,
+    sync: options.sync
+      ? createRuntimeSyncBridge(options.sync, infra.storage)
+      : undefined,
+    notify(notification) {
+      for (const listener of notificationListeners) {
+        listener(notification)
+      }
+    },
+    subscribeNotifications(listener) {
+      notificationListeners.add(listener)
+      return () => {
+        notificationListeners.delete(listener)
+      }
+    },
+    resolveSource: infra.resolveSource,
+  }
+
+  // 3. Create store, selection, settings, and area selection state
+  logBrowser("🗂️", "Creating annotations store + selection + settings")
+  const store = createAnnotationsStore(bridge)
+  const selection = createSelectionState()
+  const settings = createSettingsState({
+    outputDetail: options.outputDetail,
+    locale: options.locale,
+  })
+  const areaSelection = createAreaSelectionState()
+
+  // 4. Attach event listeners (pointer/click/drag → store/selection)
+  logBrowser("👂", "Attaching event listeners", "pointer + click + drag selection")
+  const listeners = attachListeners(
+    store,
+    selection,
+    areaSelection,
+    settings,
+    infra.resolveSource,
+    bridge.notify,
+  )
+
+  // 5. Mount the Vue overlay app
+  logBrowser("🪄", "Mounting overlay app")
+  const app = createApp(OverlayRoot, {
+    bridge,
+    store,
+    selection,
+    settings,
+    areaSelection,
+  })
+  app.mount(infra.appRoot)
+
+  // 6. Expose runtime context for HMR disposal + console debugging
+  window.__agentationRuntime = {
+    dispose() {
+      app.unmount()
+      listeners.dispose()
+      areaSelection.clear()
+      selection.clearHovered()
+      selection.clearSelection()
+      infra.appRoot.replaceChildren()
+      infra.overlayRoot.replaceChildren()
+      delete window.__agentationDemo
+    },
+  }
+
+  // Diagnostics
+  logBrowser("✅", "Runtime ready!", "Try: __agentationDemo.inspect($0)")
+}

package/src/runtime/resolver/index.ts

@@ -0,0 +1,3 @@
+export { resolveElementSource, bindTracer } from "./resolve-source.js"
+export { mapTraceToSourceLocation } from "./tracer-adapter.js"
+export { resolveFromVueInternals } from "./vue-internal.js"

package/src/runtime/resolver/resolve-source.ts

@@ -0,0 +1,51 @@
+import type { SourceLocation } from "@liuovo/agentation-vue-core"
+import type { ElementTraceInfo } from "vite-plugin-vue-tracer/client/record"
+import { mapTraceToSourceLocation } from "./tracer-adapter.js"
+import { resolveFromVueInternals } from "./vue-internal.js"
+
+type FindTraceFn = (el?: Element | null) => ElementTraceInfo | undefined
+
+/**
+ * Holder for the lazily-bound vue-tracer lookup function.
+ *
+ * At dev runtime, the Vite plugin ensures `vite-plugin-vue-tracer/client/record`
+ * is loaded before any user interaction. The runtime bootstrap calls
+ * `bindTracer()` to wire up the reference once tracer is ready.
+ */
+let _findTrace: FindTraceFn | null = null
+
+/**
+ * Bind the vue-tracer `findTraceFromElement` function.
+ *
+ * Called once by the runtime bootstrap after importing the tracer client module.
+ */
+export function bindTracer(fn: FindTraceFn): void {
+  _findTrace = fn
+}
+
+/**
+ * Unified entry point for resolving an HTML element to its Vue source location.
+ *
+ * Resolution order:
+ * 1. vue-tracer headless API (`findTraceFromElement`) — provides file, line, column
+ * 2. Vue internals fallback (`__vnode` / `__vueParentComponent`) — provides file only
+ *
+ * Returns `null` when neither strategy can identify the source.
+ */
+export function resolveElementSource(el: HTMLElement): SourceLocation | null {
+  // Strategy 1: vue-tracer (preferred — includes precise line/column)
+  if (_findTrace) {
+    try {
+      const trace = _findTrace(el)
+      if (trace) {
+        const result = mapTraceToSourceLocation(trace)
+        if (result) return result
+      }
+    } catch {
+      // tracer threw — fall through to next strategy
+    }
+  }
+
+  // Strategy 2: Vue internals fallback (file-level only, no line/column)
+  return resolveFromVueInternals(el)
+}

package/src/runtime/resolver/tracer-adapter.ts

@@ -0,0 +1,92 @@
+import type { SourceLocation } from "@liuovo/agentation-vue-core"
+import type { ElementTraceInfo } from "vite-plugin-vue-tracer/client/record"
+
+/**
+ * Maps a vue-tracer `ElementTraceInfo` to the internal `SourceLocation` type.
+ *
+ * Returns `null` when the trace info lacks the minimum required data (file path).
+ */
+export function mapTraceToSourceLocation(trace: ElementTraceInfo): SourceLocation | null {
+  const [source, line, column] = trace.pos
+  if (!source) return null
+
+  const componentName = extractComponentName(trace)
+  const hierarchy = buildComponentHierarchy(trace)
+
+  return {
+    framework: "vue",
+    componentName,
+    componentHierarchy: hierarchy || undefined,
+    file: source,
+    line,
+    column,
+    resolver: "vue-tracer",
+  }
+}
+
+/**
+ * Extracts the component display name from a trace entry.
+ *
+ * Walks the vnode tree to find the nearest component boundary.
+ * Falls back to the file basename when no component name is available.
+ */
+function extractComponentName(trace: ElementTraceInfo): string {
+  const vnode = trace.vnode
+  if (vnode) {
+    const type = vnode.type as Record<string, unknown> | undefined
+    if (type) {
+      if (typeof type === "object" && typeof type.name === "string" && type.name) {
+        return type.name
+      }
+      if (typeof type === "object" && typeof type.__name === "string" && type.__name) {
+        return type.__name
+      }
+    }
+  }
+
+  // Fallback: derive name from file path
+  const [source] = trace.pos
+  if (source) {
+    const segments = source.split("/")
+    const filename = segments[segments.length - 1] ?? source
+    return filename.replace(/\.\w+$/, "")
+  }
+
+  return "Unknown"
+}
+
+/**
+ * Builds a component hierarchy string by walking parent traces.
+ *
+ * Produces a string like `<App> <Layout> <Button>`.
+ * Caps at 10 levels to avoid infinite loops in edge cases.
+ */
+function buildComponentHierarchy(trace: ElementTraceInfo): string | null {
+  const names: string[] = []
+  let current: ElementTraceInfo | undefined = trace
+  const maxDepth = 10
+
+  for (let depth = 0; current && depth < maxDepth; depth++) {
+    const name = extractComponentNameFromTrace(current)
+    if (name && (names.length === 0 || names[names.length - 1] !== name)) {
+      names.push(name)
+    }
+    current = current.getParent()
+  }
+
+  if (names.length <= 1) return null
+  return names.reverse().map((n) => `<${n}>`).join(" ")
+}
+
+function extractComponentNameFromTrace(trace: ElementTraceInfo): string | null {
+  const vnode = trace.vnode
+  if (!vnode) return null
+
+  const type = vnode.type as Record<string, unknown> | undefined
+  if (!type || typeof type !== "object") return null
+
+  if (typeof type.name === "string" && type.name) return type.name
+  if (typeof type.__name === "string" && type.__name) return type.__name
+
+  return null
+}

package/src/runtime/resolver/vue-internal.ts

@@ -0,0 +1,113 @@
+import type { SourceLocation } from "@liuovo/agentation-vue-core"
+import type { ComponentInternalInstance, VNode } from "vue"
+
+/**
+ * Fallback resolver using Vue 3 internal properties on DOM elements.
+ *
+ * Used when vue-tracer data is not available (e.g. tracer plugin not loaded,
+ * or element was rendered before tracer initialized).
+ *
+ * Walks up from the element looking for `__vueParentComponent` or `__vnode`
+ * to extract component file information.
+ */
+export function resolveFromVueInternals(el: HTMLElement): SourceLocation | null {
+  const instance = findComponentInstance(el)
+  if (!instance) return null
+
+  // Walk up the component tree to find the first instance with file metadata
+  const resolved = findInstanceWithFile(instance)
+  if (!resolved) return null
+
+  const { instance: fileInstance, file } = resolved
+  const type = fileInstance.type as Record<string, unknown>
+  const componentName = extractName(type) ?? deriveNameFromFile(file)
+
+  return {
+    framework: "vue",
+    componentName,
+    componentHierarchy: buildHierarchyFromInstance(fileInstance) || undefined,
+    file,
+    line: undefined,
+    column: undefined,
+    resolver: "vue-internal",
+  }
+}
+
+interface VueElement extends HTMLElement {
+  __vueParentComponent?: ComponentInternalInstance
+  __vnode?: VNode
+}
+
+function findComponentInstance(el: HTMLElement): ComponentInternalInstance | null {
+  let current: HTMLElement | null = el
+
+  while (current) {
+    const vueEl = current as VueElement
+
+    if (vueEl.__vueParentComponent) {
+      return vueEl.__vueParentComponent
+    }
+
+    if (vueEl.__vnode) {
+      const vnode = vueEl.__vnode
+      const type = vnode.type as Record<string, unknown> | undefined
+      if (type && typeof type === "object" && extractFile(type)) {
+        return { type, parent: null } as unknown as ComponentInternalInstance
+      }
+    }
+
+    current = current.parentElement
+  }
+
+  return null
+}
+
+function findInstanceWithFile(
+  instance: ComponentInternalInstance,
+): { instance: ComponentInternalInstance; file: string } | null {
+  let current: ComponentInternalInstance | null = instance
+  const maxDepth = 20
+
+  for (let depth = 0; current && depth < maxDepth; depth++) {
+    const type = current.type as Record<string, unknown>
+    const file = extractFile(type)
+    if (file) return { instance: current, file }
+    current = current.parent
+  }
+
+  return null
+}
+
+function extractFile(type: Record<string, unknown>): string | null {
+  if (typeof type.__file === "string" && type.__file) return type.__file
+  if (typeof type.__filePath === "string" && type.__filePath) return type.__filePath
+  return null
+}
+
+function extractName(type: Record<string, unknown>): string | null {
+  if (typeof type.name === "string" && type.name) return type.name
+  if (typeof type.__name === "string" && type.__name) return type.__name
+  return null
+}
+
+function deriveNameFromFile(file: string): string {
+  const segments = file.split("/")
+  const filename = segments[segments.length - 1] ?? file
+  return filename.replace(/\.\w+$/, "")
+}
+
+function buildHierarchyFromInstance(instance: ComponentInternalInstance): string | null {
+  const names: string[] = []
+  let current: ComponentInternalInstance | null = instance
+  const maxDepth = 10
+
+  for (let depth = 0; current && depth < maxDepth; depth++) {
+    const type = current.type as Record<string, unknown>
+    const name = extractName(type)
+    if (name) names.push(name)
+    current = current.parent
+  }
+
+  if (names.length <= 1) return null
+  return names.reverse().map((n) => `<${n}>`).join(" ")
+}

package/src/runtime/sync.ts

@@ -0,0 +1,192 @@
+import {
+  createSession as apiCreateSession,
+  syncAnnotation,
+  updateAnnotation as apiUpdateAnnotation,
+  deleteAnnotation as apiDeleteAnnotation,
+} from "@liuovo/agentation-vue-core"
+import {
+  getUnsyncedAnnotations,
+  loadSessionId,
+  markAnnotationsSynced,
+  saveSessionId,
+} from "@liuovo/agentation-vue-core"
+import type { AnnotationV2 } from "@liuovo/agentation-vue-core"
+import type { RuntimeSyncBridge } from "@liuovo/agentation-vue-ui"
+import type { AgentationStorageBridge, AgentationVueSyncOptions } from "../types.js"
+
+/**
+ * Creates a sync bridge that connects the local annotation store
+ * to the remote MCP server via the V2 HTTP API.
+ *
+ * - On init, flushes any unsynced annotations to the server.
+ * - On enqueueUpsert, debounces a flush to batch rapid saves.
+ * - On enqueueDelete, immediately fires a best-effort DELETE.
+ */
+export function createRuntimeSyncBridge(
+  sync: AgentationVueSyncOptions,
+  storage: AgentationStorageBridge,
+): RuntimeSyncBridge {
+  const pathname = () => window.location.pathname
+  const debounceMs = sync.debounceMs ?? 400
+
+  let sessionId: string | undefined = loadSessionId(pathname(), storage.options) ?? undefined
+  let currentPathname = pathname()
+  let flushTimer: ReturnType<typeof setTimeout> | undefined
+  let flushInFlight: Promise<void> | null = null
+  let dirtyWhileFlushing = false
+
+  /**
+   * Re-resolve sessionId when the SPA pathname changes.
+   * Called before flush operations to handle client-side routing.
+   */
+  function watchPathname(): void {
+    const current = pathname()
+    if (current !== currentPathname) {
+      currentPathname = current
+      sessionId = loadSessionId(current, storage.options) ?? undefined
+    }
+  }
+
+  /**
+   * Ensure a server-side session exists for the current page.
+   * Creates one lazily and persists the ID in localStorage.
+   */
+  async function ensureSession(): Promise<string> {
+    watchPathname()
+    if (sessionId) return sessionId
+
+    try {
+      const session = await apiCreateSession(sync.endpoint, window.location.href)
+      sessionId = session.id
+      saveSessionId(pathname(), session.id, storage.options)
+      return session.id
+    } catch (err) {
+      console.warn("[agentation] Failed to create session:", err)
+      throw err
+    }
+  }
+
+  /**
+   * Flush all unsynced annotations to the server.
+   *
+   * Serialized: if a flush is already running and new writes arrive,
+   * we mark the state as dirty and re-flush after the current one completes.
+   */
+  async function flush(): Promise<void> {
+    if (flushInFlight) {
+      dirtyWhileFlushing = true
+      return flushInFlight
+    }
+
+    flushInFlight = (async () => {
+      const sid = await ensureSession()
+      const pending = getUnsyncedAnnotations(pathname(), sid, storage.options)
+
+      if (pending.length === 0) return
+
+      const synced: string[] = []
+      for (const annotation of pending) {
+        try {
+          await syncAnnotation(sync.endpoint, sid, annotation)
+          synced.push(annotation.id)
+        } catch (err) {
+          console.warn("[agentation] Failed to sync annotation:", annotation.id, err)
+        }
+      }
+
+      if (synced.length > 0) {
+        markAnnotationsSynced(pathname(), synced, sid, storage.options)
+      }
+    })()
+      .catch((err) => {
+        console.warn("[agentation] Sync flush failed:", err)
+      })
+      .finally(() => {
+        flushInFlight = null
+
+        // If new writes arrived while we were flushing, schedule a follow-up
+        if (dirtyWhileFlushing) {
+          dirtyWhileFlushing = false
+          scheduleFlush()
+        }
+      })
+
+    return flushInFlight
+  }
+
+  /**
+   * Schedule a debounced flush.
+   * Resets the timer on each call to batch rapid saves.
+   */
+  function scheduleFlush(): void {
+    if (flushTimer != null) {
+      clearTimeout(flushTimer)
+    }
+    flushTimer = setTimeout(() => {
+      flushTimer = undefined
+      void flush()
+    }, debounceMs)
+  }
+
+  /**
+   * Best-effort PATCH for an updated annotation.
+   * Reuses the same session; falls back to upsert on error.
+   */
+  async function updateRemote(annotation: AnnotationV2): Promise<void> {
+    watchPathname()
+    if (!sessionId) {
+      // No session yet — treat as upsert
+      scheduleFlush()
+      return
+    }
+
+    try {
+      await apiUpdateAnnotation(sync.endpoint, annotation.id, annotation)
+    } catch (err) {
+      console.warn("[agentation] Update sync failed, will re-upsert:", annotation.id, err)
+      scheduleFlush()
+    }
+  }
+
+  /**
+   * Best-effort DELETE for a removed annotation.
+   * If the annotation was never synced (404), silently ignore.
+   * Does NOT create a session — if no session exists, the annotation
+   * was never synced anyway.
+   */
+  async function deleteRemote(annotation: AnnotationV2): Promise<void> {
+    watchPathname()
+    // Don't create a session just to delete — if no session exists,
+    // the annotation was never synced.
+    if (!sessionId) return
+
+    try {
+      await apiDeleteAnnotation(sync.endpoint, annotation.id)
+    } catch (err) {
+      if (err instanceof Error && err.message.includes("404")) return
+      console.warn("[agentation] Delete sync failed:", annotation.id, err)
+    }
+  }
+
+  return {
+    init() {
+      if (sync.autoSync === false) return Promise.resolve()
+      return flush()
+    },
+
+    enqueueUpsert(_annotation: AnnotationV2) {
+      if (sync.autoSync === false) return
+      scheduleFlush()
+    },
+
+    enqueueUpdate(annotation: AnnotationV2) {
+      if (sync.autoSync === false) return
+      void updateRemote(annotation)
+    },
+
+    enqueueDelete(annotation: AnnotationV2) {
+      if (sync.autoSync === false) return
+      void deleteRemote(annotation)
+    },
+  }
+}