@ourroadmaps/web-sdk

Interactive overlay system and feedback widget for OurRoadmaps. Create guided walkthroughs, cursor animations, and annotations for prototypes and demos.

Quick Start

CDN (Recommended for Prototypes)

<script src="https://unpkg.com/@ourroadmaps/web-sdk"></script>
<script>
  const { createOverlay } = OurRoadmaps;

  const overlay = createOverlay();
  overlay.play({
    version: 1,
    cursor: { name: 'Guide', color: '#6366f1' },
    actions: [
      { type: 'move', target: { selector: '#my-button' }, duration: 800 },
      { type: 'click' },
      { type: 'wait', duration: 1000 }
    ]
  });
</script>

npm

npm install @ourroadmaps/web-sdk

import { createOverlay } from '@ourroadmaps/web-sdk'

const overlay = createOverlay()
await overlay.play(script)

Overlay System

The overlay system provides cursor animations and annotations for creating guided walkthroughs.

Creating an Overlay

const overlay = createOverlay({
  cursor: {
    name: 'Guide',      // Label shown next to cursor
    color: '#6366f1',   // Cursor color
    visible: true       // Initial visibility
  },
  annotations: {
    color: '#ef4444',   // Default annotation color
    strokeWidth: 3      // Default stroke width
  },
  zIndex: 9999          // Stack order
})

Script Format

const script = {
  version: 1,
  cursor: { name: 'Guide', color: '#6366f1' },
  annotations: { color: '#ef4444' },
  actions: [
    // Move cursor to element
    { type: 'move', target: { selector: '#button' }, duration: 800 },

    // Click at current position
    { type: 'click' },

    // Wait
    { type: 'wait', duration: 2000 },

    // Show annotations
    {
      type: 'showAnnotations',
      annotations: [
        { type: 'badge', target: { selector: '#step-1' }, number: 1 },
        { type: 'label', target: { selector: '#step-1' }, text: 'Start here', position: 'right' }
      ]
    },

    // Hide all annotations
    { type: 'hideAnnotations' },

    // Change cursor appearance
    { type: 'setCursor', name: 'Done', color: '#22c55e' }
  ]
}

Actions

| Action | Description | Properties | |--------|-------------|------------| | move | Move cursor to target | target, duration? (default 600ms) | | click | Animate a click | target? (defaults to current position) | | wait | Pause playback | duration (ms) | | showAnnotations | Display annotations | annotations[] | | hideAnnotations | Remove annotations | ids? (specific IDs, or all if omitted) | | setCursor | Change cursor appearance | visible?, name?, color? |

Targeting

Target elements using CSS selectors with optional anchor points:

// Basic selector
{ selector: '#my-element' }

// With anchor point
{ selector: '#my-element', anchor: 'top-right' }

// With offset
{ selector: '#my-element', anchor: 'center', offset: { x: 10, y: -5 } }

// Fallback coordinates if element not found
{ selector: '#my-element', fallback: { x: 100, y: 200 } }

// Absolute coordinates
{ x: 500, y: 300 }

Anchor options: center, top, bottom, left, right, top-left, top-right, bottom-left, bottom-right

Annotations

Badge

Numbered circle for step indicators:

{ type: 'badge', target: { selector: '#step' }, number: 1, color: '#6366f1' }

Label

Text callout with positioning:

{
  type: 'label',
  target: { selector: '#element' },
  text: 'Click here',
  position: 'right',  // top, bottom, left, right, top-left, top-right, bottom-left, bottom-right
  gap: 8              // Distance from target in pixels
}

Box

Highlight rectangle around element:

{
  type: 'box',
  target: { selector: '#element' },
  padding: 8,         // Extra space around element
  dashed: true        // Dashed border style
}

Circle

Highlight ellipse around element:

{ type: 'circle', target: { selector: '#element' }, padding: 12 }

Arrow

Connecting line between two points:

{
  type: 'arrow',
  from: { selector: '#start' },
  to: { selector: '#end' }
}

All annotations support:

• id - Unique identifier for selective hiding
• color - Override default color
• delay - Milliseconds before appearing
• duration - Auto-hide after milliseconds (0 = permanent)

Controller API

const overlay = createOverlay()

// Playback
await overlay.play(script)    // Returns promise when complete
overlay.stop()                // Stop playback
overlay.isPlaying             // Current playback state
overlay.currentActionIndex    // Current action (null if not playing)

// Validation
const result = overlay.validate(script)
// { valid: boolean, errors: string[], warnings: string[] }

// Events
const unsubscribe = overlay.on('start', () => {})
overlay.on('complete', () => {})
overlay.on('stop', () => {})
overlay.on('error', (error) => {})
overlay.on('action', (action, index, phase) => {})

// Direct cursor control
overlay.cursor.moveTo({ selector: '#target' }, { duration: 500 })
overlay.cursor.click()
overlay.cursor.show()
overlay.cursor.hide()
overlay.cursor.setName('Helper')
overlay.cursor.setColor('#22c55e')
overlay.cursor.position   // { x, y } or null
overlay.cursor.isVisible

// Direct annotation control
const id = overlay.annotations.badge({ selector: '#el' }, 1)
overlay.annotations.label({ selector: '#el' }, 'Hello', { position: 'top' })
overlay.annotations.box({ selector: '#el' })
overlay.annotations.circle({ selector: '#el' })
overlay.annotations.arrow({ selector: '#from' }, { selector: '#to' })
overlay.annotations.hide(id)
overlay.annotations.hideAll()
overlay.annotations.activeIds  // Currently visible annotation IDs

// Cleanup
overlay.destroy()
overlay.isDestroyed

Error Handling

overlay.on('error', (error) => {
  console.log(error.code)     // ELEMENT_NOT_FOUND, ANIMATION_FAILED, etc.
  console.log(error.message)  // Human-readable description
  console.log(error.action)   // The action that failed
  console.log(error.target)   // The target that couldn't be resolved
})

Error codes:

• ELEMENT_NOT_FOUND - CSS selector matched no elements
• ANIMATION_FAILED - Animation couldn't complete
• SCROLL_FAILED - Couldn't scroll element into view
• INVALID_SCRIPT - Script failed validation
• INVALID_TARGET - Target specification is malformed
• TIMEOUT - Operation exceeded time limit

Feedback Widget

The feedback widget displays a development-only feedback form.

import { init, destroy } from '@ourroadmaps/web-sdk'

// Initialize (only renders in development mode)
init({ apiKey: 'your_api_key' })

// Remove widget
destroy()

The widget only renders when:

• NODE_ENV !== 'production'
• Running on localhost or 127.0.0.1

Module Imports

// Everything from main entry
import { createOverlay, init, destroy } from '@ourroadmaps/web-sdk'

// Just overlay
import { createOverlay } from '@ourroadmaps/web-sdk/overlay'

// Just feedback
import { init, destroy } from '@ourroadmaps/web-sdk/feedback'

CDN URLs

<!-- Latest version (for prototypes) -->
<script src="https://unpkg.com/@ourroadmaps/web-sdk"></script>

<!-- Pinned version (for production) -->
<script src="https://unpkg.com/@ourroadmaps/[email protected]"></script>

<!-- Alternative: jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/@ourroadmaps/web-sdk"></script>

The CDN build exposes window.OurRoadmaps with:

• createOverlay() - Create overlay instance
• init() - Initialize feedback widget
• destroy() - Remove feedback widget

TypeScript

Full type definitions included. Import types directly:

import type {
  OverlayScript,
  OverlayController,
  Action,
  Annotation,
  Target
} from '@ourroadmaps/web-sdk'

License

Proprietary - OurRoadmaps