@nextsparkjs/plugin-walkme 0.1.0-beta.108 → 0.1.0-beta.110

package/components/WalkmeProvider.tsx

@@ -71,6 +71,7 @@ export function WalkmeProvider({
   conditionContext: externalConditionContext,
   labels: userLabels,
   userId,
+  serverSyncUrl,
 }: WalkmeProviderProps) {
   const labels = useMemo<WalkmeLabels>(
     () => ({ ...DEFAULT_LABELS, ...userLabels }),
@@ -98,10 +99,11 @@ export function WalkmeProvider({
   }, [rawTours, debug])
 
   // Core state management
-  const { state, dispatch, storage } = useTourState(validatedTours, {
+  const { state, dispatch, storage, serverSyncPending } = useTourState(validatedTours, {
     persistState,
     debug,
     userId,
+    serverSyncUrl,
   })
 
   // ---------------------------------------------------------------------------
@@ -234,6 +236,9 @@ export function WalkmeProvider({
 
   const evaluateTriggers = useCallback(() => {
     if (!state.initialized || state.activeTour || !autoStart) return
+    // Wait for server state before auto-triggering on fresh devices.
+    // Without this, tours flash for ~1s before server sync cancels them.
+    if (serverSyncPending) return
 
     const triggerContext: TriggerEvaluationContext = {
       currentRoute: pathname,
@@ -282,6 +287,7 @@ export function WalkmeProvider({
     state.completedTours,
     state.skippedTours,
     autoStart,
+    serverSyncPending,
     pathname,
     storage,
     externalConditionContext,
@@ -368,12 +374,12 @@ export function WalkmeProvider({
       if (result.found && result.element) {
         applyTarget(result.element)
       } else {
-        waitForTarget(activeStep.target!, { timeout: 5000 }).then((waitResult) => {
+        waitForTarget(activeStep.target!, { timeout: 20000 }).then((waitResult) => {
           if (waitResult.found && waitResult.element) {
             applyTarget(waitResult.element)
-          } else if (debug) {
+          } else {
             console.warn(
-              `[WalkMe] Target "${activeStep.target}" not found, step may display without anchor`,
+              `[WalkMe] Target "${activeStep.target}" not found after 20s wait`,
             )
           }
         })
@@ -438,7 +444,7 @@ export function WalkmeProvider({
   }, [state.activeTour, nextStep, prevStep, skipTour])
 
   // ---------------------------------------------------------------------------
-  // Body Scroll Lock (only for modal/floating steps that cover the page)
+  // Body Scroll Lock (only for step types with overlay)
   // ---------------------------------------------------------------------------
 
   const activeStepType = getActiveStep(state)?.type
@@ -446,8 +452,9 @@ export function WalkmeProvider({
     const isActive = state.activeTour?.status === 'active'
     if (!isActive) return
 
-    // Only lock scroll for step types that cover the viewport
-    if (activeStepType !== 'modal' && activeStepType !== 'floating') return
+    // Only lock scroll for types that use an overlay (modal, floating, spotlight)
+    // Tooltip type has no overlay — scroll should remain free
+    if (!activeStepType || activeStepType === 'tooltip') return
 
     const { style } = document.body
     const originalOverflow = style.overflow

package/components/WalkmeSpotlight.tsx

@@ -76,8 +76,8 @@ export const WalkmeSpotlight = memo(function WalkmeSpotlight({
 
   const { refs, floatingStyles, isStable } = useStepPositioning(targetElement, {
     placement: getPlacementFromPosition(step.position ?? 'bottom'),
-    offset: 16,
-    padding: 8,
+    offset: 24,
+    padding: 12,
   })
 
   useEffect(() => {

package/components/WalkmeTooltip.tsx

@@ -47,20 +47,44 @@ export const WalkmeTooltip = memo(function WalkmeTooltip({
 }: WalkmeTooltipProps) {
   const containerRef = useRef<HTMLDivElement>(null)
 
-  const { refs, floatingStyles, arrowRef, placement, isStable } = useStepPositioning(
+  const { refs, floatingStyles, arrowRef, placement, middlewareData, isStable } = useStepPositioning(
     targetElement,
     {
       placement: getPlacementFromPosition(step.position ?? 'auto'),
-      offset: 12,
-      padding: 8,
+      offset: 20,
+      padding: 12,
     },
   )
 
+  const arrowData = middlewareData.arrow as { x?: number; y?: number } | undefined
+
   // Focus the tooltip when positioning has stabilized
   useEffect(() => {
     if (isStable) containerRef.current?.focus()
   }, [isStable])
 
+  // Add a subtle highlight ring on the target element while tooltip is active
+  useEffect(() => {
+    if (!targetElement) return
+    const el = targetElement
+    const prev = {
+      outline: el.style.outline,
+      outlineOffset: el.style.outlineOffset,
+      borderRadius: el.style.borderRadius,
+      transition: el.style.transition,
+    }
+    el.style.outline = '2px solid var(--walkme-primary, oklch(0.588 0.243 264.376))'
+    el.style.outlineOffset = '4px'
+    el.style.borderRadius = '8px'
+    el.style.transition = 'outline 200ms ease-out'
+    return () => {
+      el.style.outline = prev.outline
+      el.style.outlineOffset = prev.outlineOffset
+      el.style.borderRadius = prev.borderRadius
+      el.style.transition = prev.transition
+    }
+  }, [targetElement])
+
   if (typeof window === 'undefined') return null
   if (!targetElement) return null
 
@@ -96,6 +120,8 @@ export const WalkmeTooltip = memo(function WalkmeTooltip({
         style={{
           backgroundColor: 'var(--walkme-bg, #ffffff)',
           ...getArrowBorders(placement),
+          ...(arrowData?.x != null ? { left: arrowData.x } : {}),
+          ...(arrowData?.y != null ? { top: arrowData.y } : {}),
         }}
       />
 

package/hooks/useTourState.ts

@@ -1,33 +1,62 @@
 'use client'
 
-import { useReducer, useEffect, useRef, useCallback } from 'react'
-import type { Tour, WalkmeState, WalkmeAction } from '../types/walkme.types'
+import { useReducer, useEffect, useRef, useCallback, useState } from 'react'
+import type { Tour, TourState, WalkmeState, WalkmeAction } from '../types/walkme.types'
 import { createInitialState, walkmeReducer } from '../lib/core'
 import { createStorageAdapter } from '../lib/storage'
+import { fetchServerState, saveServerState, mergeStates } from '../lib/server-sync'
 
 interface UseTourStateOptions {
   persistState: boolean
   debug: boolean
   userId?: string
+  /** API URL for server-side persistence. If omitted, server sync is disabled. */
+  serverSyncUrl?: string
 }
 
 /**
  * Internal hook that manages the core WalkMe state machine.
- * Handles useReducer, localStorage persistence, and initial state loading.
+ * Handles useReducer, localStorage persistence, server sync, and initial state loading.
+ *
+ * Hybrid persistence strategy:
+ * 1. localStorage is the primary store (instant reads, no flash)
+ * 2. Server (users_metas) is the durable backup (cross-device sync)
+ * 3. On mount: load localStorage first, then merge server state in background
+ * 4. On change: save to localStorage immediately, debounced save to server
+ * 5. Server saves are BLOCKED until the initial server fetch completes
+ *    (prevents empty local state from overwriting server data on new devices)
  */
 export function useTourState(tours: Tour[], options: UseTourStateOptions) {
-  const { persistState, debug, userId } = options
+  const { persistState, debug, userId, serverSyncUrl } = options
   const [state, dispatch] = useReducer(walkmeReducer, createInitialState())
   const storageRef = useRef(createStorageAdapter(userId))
   const initialized = useRef(false)
   const prevUserIdRef = useRef(userId)
   const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const serverDebounceRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  // Whether the initial server fetch has been kicked off
+  const serverSyncStartedRef = useRef(false)
+  // Whether the initial server fetch has resolved — server saves are blocked until true
+  const serverSyncDoneRef = useRef(false)
+  // Reactive flag: true while waiting for initial server fetch.
+  // Used by WalkmeProvider to delay auto-trigger evaluation on fresh devices
+  // so tours don't flash for ~1s before server state cancels them.
+  // CRITICAL: Must initialize to true when server sync will happen so the FIRST
+  // render already blocks triggers (setState from effects is too late).
+  const [serverSyncPending, setServerSyncPending] = useState(
+    () => Boolean(persistState && userId && serverSyncUrl),
+  )
 
   // Re-create storage adapter when userId changes (e.g. session loads async)
   useEffect(() => {
     if (prevUserIdRef.current === userId) return
     prevUserIdRef.current = userId
     storageRef.current = createStorageAdapter(userId)
+    serverSyncStartedRef.current = false
+    serverSyncDoneRef.current = false
+    // If new userId exists and serverSyncUrl is configured, set pending.
+    // If userId cleared (logout), set to false to unblock triggers.
+    setServerSyncPending(Boolean(persistState && userId && serverSyncUrl))
 
     // Re-restore persisted state from the new user-scoped storage
     if (persistState) {
@@ -59,7 +88,7 @@ export function useTourState(tours: Tour[], options: UseTourStateOptions) {
       dispatch({ type: 'SET_DEBUG', enabled: true })
     }
 
-    // Restore persisted state
+    // Restore persisted state from localStorage (instant, no flash)
     if (persistState) {
       const storage = storageRef.current
       const saved = storage.load()
@@ -82,6 +111,49 @@ export function useTourState(tours: Tour[], options: UseTourStateOptions) {
     }
   }, []) // eslint-disable-line react-hooks/exhaustive-deps
 
+  // Background server sync: fetch server state and merge with local.
+  // Runs once per userId after local state is restored.
+  // Server saves are blocked until this completes to prevent empty local
+  // state from overwriting valid server data on a new device/browser.
+  // Auto-trigger evaluation in WalkmeProvider is also delayed via
+  // serverSyncPending so tours don't flash before server state arrives.
+  useEffect(() => {
+    if (!persistState || !userId || !serverSyncUrl || !state.initialized) return
+    if (serverSyncStartedRef.current) return
+    serverSyncStartedRef.current = true
+    setServerSyncPending(true)
+
+    fetchServerState(serverSyncUrl)
+      .then((serverState) => {
+        if (!serverState) return
+
+        const local = storageRef.current.load()
+        if (!local) return
+
+        const merged = mergeStates(local, serverState)
+
+        // Only dispatch if server had data the local store didn't
+        const hasNewCompleted = merged.completedTours.length > state.completedTours.length
+        const hasNewSkipped = merged.skippedTours.length > state.skippedTours.length
+
+        if (hasNewCompleted || hasNewSkipped) {
+          dispatch({
+            type: 'RESTORE_STATE',
+            completedTours: merged.completedTours,
+            skippedTours: merged.skippedTours,
+            tourHistory: merged.tourHistory as Record<string, TourState>,
+            // Cancel any active tour that was already completed/skipped on server
+            activeTour: null,
+          })
+        }
+      })
+      .finally(() => {
+        // Unblock server saves and auto-trigger evaluation
+        serverSyncDoneRef.current = true
+        setServerSyncPending(false)
+      })
+  }, [persistState, userId, serverSyncUrl, state.initialized]) // eslint-disable-line react-hooks/exhaustive-deps
+
   // Re-register tour definitions when they change after initialization.
   // This handles the case where tours arrive asynchronously (e.g. after API fetch)
   // and the provider was already mounted with an empty tours array.
@@ -91,10 +163,11 @@ export function useTourState(tours: Tour[], options: UseTourStateOptions) {
     dispatch({ type: 'UPDATE_TOURS', tours })
   }, [tours]) // eslint-disable-line react-hooks/exhaustive-deps
 
-  // Persist state changes to localStorage (debounced)
+  // Persist state changes to localStorage (100ms debounce) + server (500ms debounce)
   useEffect(() => {
     if (!persistState || !state.initialized) return
 
+    // --- localStorage save (fast, 100ms debounce) ---
     if (debounceRef.current) {
       clearTimeout(debounceRef.current)
     }
@@ -114,13 +187,39 @@ export function useTourState(tours: Tour[], options: UseTourStateOptions) {
       })
     }, 100)
 
+    // --- Server save (slower, 500ms debounce, only durable fields) ---
+    // BLOCKED until initial server sync is done to prevent overwriting
+    // valid server data with empty local state on a fresh browser.
+    if (userId && serverSyncUrl && serverSyncDoneRef.current) {
+      if (serverDebounceRef.current) {
+        clearTimeout(serverDebounceRef.current)
+      }
+
+      const url = serverSyncUrl
+      serverDebounceRef.current = setTimeout(() => {
+        const existing = storageRef.current.load()
+
+        saveServerState(url, {
+          completedTours: state.completedTours,
+          skippedTours: state.skippedTours,
+          tourHistory: state.tourHistory,
+          visitCount: existing?.visitCount ?? 1,
+          firstVisitDate: existing?.firstVisitDate ?? new Date().toISOString(),
+        })
+      }, 500)
+    }
+
     return () => {
       if (debounceRef.current) {
         clearTimeout(debounceRef.current)
       }
+      if (serverDebounceRef.current) {
+        clearTimeout(serverDebounceRef.current)
+      }
     }
   }, [
     persistState,
+    userId,
     state.initialized,
     state.completedTours,
     state.skippedTours,
@@ -142,5 +241,7 @@ export function useTourState(tours: Tour[], options: UseTourStateOptions) {
     state,
     dispatch: stableDispatch,
     storage: storageRef.current,
+    /** True while waiting for initial server state fetch (blocks auto-trigger) */
+    serverSyncPending,
   }
 }

package/lib/server-sync.ts

@@ -0,0 +1,73 @@
+'use client'
+
+/**
+ * WalkMe Server Sync
+ *
+ * Client-side helpers for syncing tour state with the server.
+ * All operations are fire-and-forget — failures never block the UI.
+ *
+ * IMPORTANT: This module is theme-agnostic. The API URL is injected
+ * by the consumer (theme) — the plugin never hardcodes theme paths.
+ */
+
+import type { StorageSchema } from '../types/walkme.types'
+
+/** Subset of StorageSchema that gets persisted to the server */
+export interface ServerState {
+  completedTours: string[]
+  skippedTours: string[]
+  tourHistory: Record<string, unknown>
+  visitCount: number
+  firstVisitDate: string
+}
+
+/**
+ * Fetch the user's tour state from the server.
+ * Returns null if no state exists or on any error.
+ */
+export async function fetchServerState(apiUrl: string): Promise<ServerState | null> {
+  try {
+    const res = await fetch(apiUrl, { credentials: 'include' })
+    if (!res.ok) return null
+
+    const json = await res.json()
+    if (!json.success || !json.data) return null
+
+    return json.data as ServerState
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Save the user's tour state to the server.
+ * Fire-and-forget — errors are silently ignored.
+ */
+export async function saveServerState(apiUrl: string, state: ServerState): Promise<void> {
+  try {
+    await fetch(apiUrl, {
+      method: 'POST',
+      credentials: 'include',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(state),
+    })
+  } catch {
+    // Silent failure — localStorage is the primary store
+  }
+}
+
+/**
+ * Merge local state with server state.
+ * Strategy: union of completed/skipped arrays, local active tour preserved.
+ * Server tourHistory entries fill gaps (local wins on conflict).
+ */
+export function mergeStates(
+  local: StorageSchema,
+  server: ServerState,
+): { completedTours: string[]; skippedTours: string[]; tourHistory: Record<string, unknown> } {
+  return {
+    completedTours: [...new Set([...local.completedTours, ...server.completedTours])],
+    skippedTours: [...new Set([...local.skippedTours, ...server.skippedTours])],
+    tourHistory: { ...server.tourHistory, ...local.tourHistory },
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextsparkjs/plugin-walkme",
-  "version": "0.1.0-beta.108",
+  "version": "0.1.0-beta.110",
   "private": false,
   "main": "./plugin.config.ts",
   "requiredPlugins": [],

package/types/walkme.types.ts

@@ -267,6 +267,13 @@ export interface WalkmeProviderProps {
   labels?: Partial<WalkmeLabels>
   /** User ID for scoping localStorage persistence per user */
   userId?: string
+  /**
+   * API URL for server-side state persistence (cross-device sync).
+   * Must support GET (fetch state) and POST (save state).
+   * If not provided, server sync is disabled — only localStorage is used.
+   * The theme provides this URL; the plugin never hardcodes theme paths.
+   */
+  serverSyncUrl?: string
 }
 
 // ---------------------------------------------------------------------------