onboardme-sdk 0.0.1

package/src/styles/modal.css

@@ -0,0 +1,102 @@
+/* ============================================================
+   OnboardMe — Modal styles
+   Scoped inside Shadow DOM — cannot affect the host page.
+   ============================================================ */
+
+/* Full-screen fixed backdrop */
+.om-overlay {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.45);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 2147483647; /* max z-index — always on top */
+}
+
+/* Centred card */
+.om-modal {
+  background: #ffffff;
+  border-radius: 12px;
+  box-shadow: 0 20px 60px rgba(0, 0, 0, 0.2);
+  max-width: 480px;
+  width: calc(100% - 32px);
+  padding: 32px;
+  box-sizing: border-box;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  color: #111827;
+}
+
+/* Heading */
+.om-modal__title {
+  margin: 0 0 12px;
+  font-size: 20px;
+  font-weight: 700;
+  line-height: 1.3;
+  color: #111827;
+}
+
+/* Body text */
+.om-modal__body {
+  margin: 0 0 24px;
+  font-size: 15px;
+  line-height: 1.6;
+  color: #4b5563;
+}
+
+/* Button row */
+.om-modal__actions {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  align-items: stretch;
+}
+
+/* Primary CTA */
+.om-btn-primary {
+  display: block;
+  width: 100%;
+  padding: 12px 20px;
+  background: #4f46e5;
+  color: #ffffff;
+  font-size: 15px;
+  font-weight: 600;
+  border: none;
+  border-radius: 8px;
+  cursor: pointer;
+  text-align: center;
+  transition: background 0.15s ease;
+}
+
+.om-btn-primary:hover {
+  background: #4338ca;
+}
+
+.om-btn-primary:focus-visible {
+  outline: 3px solid #818cf8;
+  outline-offset: 2px;
+}
+
+/* Skip / dismiss link */
+.om-btn-skip {
+  display: block;
+  background: none;
+  border: none;
+  padding: 6px 0;
+  color: #6b7280;
+  font-size: 14px;
+  cursor: pointer;
+  text-align: center;
+  text-decoration: underline;
+  transition: color 0.15s ease;
+}
+
+.om-btn-skip:hover {
+  color: #374151;
+}
+
+.om-btn-skip:focus-visible {
+  outline: 2px solid #818cf8;
+  outline-offset: 2px;
+  border-radius: 4px;
+}

package/src/utils/dom.ts

@@ -0,0 +1,49 @@
+const DEFAULT_TIMEOUT_MS = 5000;
+const POLL_INTERVAL_MS = 50;
+
+/**
+ * Resolves when the element matching `selector` appears in the DOM.
+ * Needed because the SDK may load before the host app's framework renders its tree.
+ * Rejects after `timeout` ms if the element never appears.
+ */
+export function waitForElement(
+  selector: string,
+  timeout = DEFAULT_TIMEOUT_MS
+): Promise<Element> {
+  return new Promise((resolve, reject) => {
+    const existing = document.querySelector(selector);
+    if (existing) {
+      resolve(existing);
+      return;
+    }
+
+    const deadline = Date.now() + timeout;
+
+    const interval = setInterval(() => {
+      const el = document.querySelector(selector);
+      if (el) {
+        clearInterval(interval);
+        resolve(el);
+        return;
+      }
+      if (Date.now() >= deadline) {
+        clearInterval(interval);
+        reject(new Error(`[OnboardMe] waitForElement: "${selector}" not found within ${timeout}ms`));
+      }
+    }, POLL_INTERVAL_MS);
+  });
+}
+
+/**
+ * Returns true if the element exists in the viewport and is not hidden via
+ * CSS visibility, display, or opacity.
+ */
+export function isVisible(element: Element): boolean {
+  const el = element as HTMLElement;
+  if (getComputedStyle(el).display === 'none') return false;
+  if (getComputedStyle(el).visibility === 'hidden') return false;
+  if (getComputedStyle(el).opacity === '0') return false;
+
+  const rect = el.getBoundingClientRect();
+  return rect.width > 0 && rect.height > 0;
+}

package/src/utils/fingerprint.ts

@@ -0,0 +1,20 @@
+/**
+ * Anonymous ID — stable per visitor per product.
+ * Generated on first visit via crypto.randomUUID(), stored in localStorage.
+ * Allows pre-login behaviour to be tracked across page loads.
+ */
+export function getAnonymousId(productId: string): string {
+  const key = `onboardme_anon_${productId}`;
+
+  try {
+    const existing = localStorage.getItem(key);
+    if (existing) return existing;
+
+    const id = crypto.randomUUID();
+    localStorage.setItem(key, id);
+    return id;
+  } catch {
+    // localStorage unavailable (private browsing restrictions, etc.) — generate ephemeral ID
+    return crypto.randomUUID();
+  }
+}

package/src/utils/logger.ts

@@ -0,0 +1,17 @@
+let debugEnabled = false;
+
+export function setDebug(enabled: boolean): void {
+  debugEnabled = enabled;
+}
+
+export const logger = {
+  log(message: string, ...args: unknown[]): void {
+    if (debugEnabled) console.log(`[OnboardMe] ${message}`, ...args);
+  },
+  warn(message: string, ...args: unknown[]): void {
+    if (debugEnabled) console.warn(`[OnboardMe] ${message}`, ...args);
+  },
+  error(message: string, ...args: unknown[]): void {
+    if (debugEnabled) console.error(`[OnboardMe] ${message}`, ...args);
+  },
+};

package/src/v2/positioner.ts

@@ -0,0 +1,105 @@
+import type { V2Placement } from './types'
+
+// Pure positioning math (Architecture v2 — Phase F).
+//
+// Takes the target element's bounding rect and a placement directive, returns
+// page-absolute (top, left) coordinates for a tooltip/highlight. Pure so it
+// is exhaustively testable without rendering anything.
+//
+// Coordinates are in viewport space relative to the document; the renderer
+// adds window scroll offsets when applying inline styles.
+
+export interface Rect {
+  top:    number
+  left:   number
+  width:  number
+  height: number
+}
+
+export interface PositionResult {
+  top:  number   // page-absolute (rect.top + scrollY)
+  left: number   // page-absolute (rect.left + scrollX)
+}
+
+const GAP = 8   // px gap between target and tooltip
+
+export interface PositionInput {
+  targetRect:    Rect
+  tooltipWidth:  number
+  tooltipHeight: number
+  scrollX:       number
+  scrollY:       number
+  placement:     V2Placement
+  viewportWidth:  number
+  viewportHeight: number
+}
+
+export function computeTooltipPosition(input: PositionInput): PositionResult {
+  const {
+    targetRect: r,
+    tooltipWidth: tw,
+    tooltipHeight: th,
+    scrollX, scrollY,
+    placement,
+    viewportWidth: vw,
+    viewportHeight: vh,
+  } = input
+
+  let top:  number
+  let left: number
+
+  switch (placement) {
+    case 'top':
+      top  = r.top - th - GAP
+      left = r.left + r.width / 2 - tw / 2
+      break
+    case 'bottom':
+      top  = r.top + r.height + GAP
+      left = r.left + r.width / 2 - tw / 2
+      break
+    case 'left':
+      top  = r.top + r.height / 2 - th / 2
+      left = r.left - tw - GAP
+      break
+    case 'right':
+      top  = r.top + r.height / 2 - th / 2
+      left = r.left + r.width + GAP
+      break
+    case 'center':
+    default:
+      top  = vh / 2 - th / 2
+      left = vw / 2 - tw / 2
+      break
+  }
+
+  // Clamp into viewport so the tooltip never escapes off-screen. Centred
+  // placement has already chosen a viewport-anchored position; clamping is
+  // still safe (no-op when the tooltip fits).
+  if (left < GAP) left = GAP
+  if (left + tw > vw - GAP) left = vw - tw - GAP
+  if (top  < GAP) top  = GAP
+  if (top  + th > vh - GAP) top  = vh - th - GAP
+
+  return {
+    top:  top  + scrollY,
+    left: left + scrollX,
+  }
+}
+
+// Highlight outline: matches the target element exactly with a small inflate
+// so a 2px ring sits just outside the element's edges.
+const HIGHLIGHT_INFLATE = 4
+
+export function computeHighlightRect(input: {
+  targetRect: Rect
+  scrollX:    number
+  scrollY:    number
+}): { top: number; left: number; width: number; height: number } {
+  const { targetRect: r, scrollX, scrollY } = input
+  return {
+    top:    r.top    + scrollY - HIGHLIGHT_INFLATE,
+    left:   r.left   + scrollX - HIGHLIGHT_INFLATE,
+    width:  r.width  + HIGHLIGHT_INFLATE * 2,
+    height: r.height + HIGHLIGHT_INFLATE * 2,
+  }
+}

package/src/v2/renderer.ts

@@ -0,0 +1,287 @@
+import { logger } from '../utils/logger.js'
+import { V2_STYLES } from './styles.js'
+import { computeTooltipPosition, computeHighlightRect } from './positioner.js'
+import type { V2Step, V2FlowConfig } from './types.js'
+
+// v2 step renderer (Architecture v2 — Phase F).
+//
+// Walks a v2 FlowConfig step-by-step, mounting one renderable element per
+// step into the SDK's Shadow DOM. Three step types share a small DOM core:
+//
+//   - tooltip:   anchored card pointing at a target (selector + placement)
+//   - modal:     centered card with backdrop overlay (placement: center)
+//   - highlight: outline ring around a target (no copy attached)
+//
+// The action button advances the flow:
+//   - 'next'     → render the next step
+//   - 'skip'     → tear down (whole flow dismissed)
+//   - 'complete' → tear down (flow finished — usually the last step's action)
+//
+// We do NOT use a session guard like the legacy modal does. The PM controls
+// when a flow is shown via Module 2 (publish). Re-renders on the same page
+// are harmless — the SDK only re-fetches when the checksumHash changes.
+
+const STYLE_MARKER = 'data-onboardme-v2-styles'
+const ROOT_CLASS   = 'om2-root'
+
+// ─── Public entry point ──────────────────────────────────────────────────────
+
+export interface V2RenderHandle {
+  /** Tear down all DOM owned by this render — safe to call multiple times. */
+  destroy(): void
+}
+
+export function renderV2Flow(config: V2FlowConfig, shadowRoot: ShadowRoot): V2RenderHandle | null {
+  if (!config.steps || config.steps.length === 0) {
+    logger.warn('v2 flow has no steps — nothing to render')
+    return null
+  }
+
+  ensureStyles(shadowRoot)
+
+  const ctx: RenderContext = {
+    shadowRoot,
+    steps: config.steps,
+    index: 0,
+    mounted: [],
+    destroyed: false,
+  }
+
+  renderCurrentStep(ctx)
+
+  return {
+    destroy() { teardown(ctx) },
+  }
+}
+
+// ─── Internals ───────────────────────────────────────────────────────────────
+
+interface RenderContext {
+  shadowRoot: ShadowRoot
+  steps: V2Step[]
+  index: number
+  mounted: HTMLElement[]
+  destroyed: boolean
+}
+
+function renderCurrentStep(ctx: RenderContext): void {
+  if (ctx.destroyed) return
+
+  // Clear previous step's DOM before mounting the next one.
+  for (const el of ctx.mounted) el.remove()
+  ctx.mounted = []
+
+  const step = ctx.steps[ctx.index]
+  if (!step) {
+    teardown(ctx)
+    return
+  }
+
+  if (step.type === 'modal') {
+    mountModal(ctx, step)
+  } else if (step.type === 'tooltip') {
+    mountTooltip(ctx, step)
+  } else {
+    mountHighlight(ctx, step)
+  }
+}
+
+function advance(ctx: RenderContext, step: V2Step): void {
+  if (step.action.type === 'skip' || step.action.type === 'complete') {
+    teardown(ctx)
+    return
+  }
+  // 'next'
+  ctx.index += 1
+  if (ctx.index >= ctx.steps.length) {
+    teardown(ctx)
+    return
+  }
+  renderCurrentStep(ctx)
+}
+
+function teardown(ctx: RenderContext): void {
+  if (ctx.destroyed) return
+  ctx.destroyed = true
+  for (const el of ctx.mounted) el.remove()
+  ctx.mounted = []
+}
+
+// ─── Step type: modal ───────────────────────────────────────────────────────
+
+function mountModal(ctx: RenderContext, step: V2Step): void {
+  const overlay = el('div', { class: 'om2-overlay' })
+  const card    = buildCard(ctx, step, /* isModal */ true)
+
+  // Place the modal by absolute positioning so it sits above the overlay.
+  card.style.top  = '50%'
+  card.style.left = '50%'
+  card.style.transform = 'translate(-50%, -50%)'
+
+  ctx.shadowRoot.appendChild(overlay)
+  ctx.shadowRoot.appendChild(card)
+  ctx.mounted.push(overlay, card)
+}
+
+// ─── Step type: tooltip ─────────────────────────────────────────────────────
+
+function mountTooltip(ctx: RenderContext, step: V2Step): void {
+  const card = buildCard(ctx, step, /* isModal */ false)
+
+  // Mount first so we can measure, then position.
+  ctx.shadowRoot.appendChild(card)
+  ctx.mounted.push(card)
+
+  const target = querySafe(step.position.selector)
+  if (!target) {
+    // Fall back to centred placement if the selector misses — mirrors legacy
+    // SDK behaviour ("never throw, always render something useful").
+    logger.warn(`v2 tooltip selector did not match: ${step.position.selector} — centring`)
+    centreOnViewport(card)
+    return
+  }
+
+  const rect = target.getBoundingClientRect()
+  const cardRect = card.getBoundingClientRect()
+  const pos = computeTooltipPosition({
+    targetRect:    { top: rect.top, left: rect.left, width: rect.width, height: rect.height },
+    tooltipWidth:  cardRect.width  || 280,
+    tooltipHeight: cardRect.height || 100,
+    scrollX:       window.scrollX,
+    scrollY:       window.scrollY,
+    placement:     step.position.placement,
+    viewportWidth:  window.innerWidth  || 1280,
+    viewportHeight: window.innerHeight || 800,
+  })
+  card.style.top  = `${pos.top}px`
+  card.style.left = `${pos.left}px`
+}
+
+// ─── Step type: highlight ───────────────────────────────────────────────────
+
+function mountHighlight(ctx: RenderContext, step: V2Step): void {
+  const target = querySafe(step.position.selector)
+  if (!target) {
+    logger.warn(`v2 highlight selector did not match: ${step.position.selector}`)
+    // Even without a target we still want to surface the action so the flow
+    // can advance; render a centred fallback card.
+    const fallback = buildCard(ctx, step, /* isModal */ true)
+    centreOnViewport(fallback)
+    ctx.shadowRoot.appendChild(fallback)
+    ctx.mounted.push(fallback)
+    return
+  }
+
+  const rect = target.getBoundingClientRect()
+  const ring = computeHighlightRect({
+    targetRect: { top: rect.top, left: rect.left, width: rect.width, height: rect.height },
+    scrollX:    window.scrollX,
+    scrollY:    window.scrollY,
+  })
+
+  const ringEl = el('div', { class: 'om2-highlight' })
+  Object.assign(ringEl.style, {
+    top:    `${ring.top}px`,
+    left:   `${ring.left}px`,
+    width:  `${ring.width}px`,
+    height: `${ring.height}px`,
+  })
+
+  // Tooltip card alongside the highlight so the user can act on it.
+  const card = buildCard(ctx, step, /* isModal */ false)
+  ctx.shadowRoot.appendChild(ringEl)
+  ctx.shadowRoot.appendChild(card)
+  ctx.mounted.push(ringEl, card)
+
+  // Position the card relative to the highlighted element.
+  const cardRect = card.getBoundingClientRect()
+  const pos = computeTooltipPosition({
+    targetRect:    { top: rect.top, left: rect.left, width: rect.width, height: rect.height },
+    tooltipWidth:  cardRect.width  || 280,
+    tooltipHeight: cardRect.height || 100,
+    scrollX:       window.scrollX,
+    scrollY:       window.scrollY,
+    placement:     step.position.placement,
+    viewportWidth:  window.innerWidth  || 1280,
+    viewportHeight: window.innerHeight || 800,
+  })
+  card.style.top  = `${pos.top}px`
+  card.style.left = `${pos.left}px`
+}
+
+// ─── Card builder (shared by modal + tooltip + highlight fallback) ──────────
+
+function buildCard(ctx: RenderContext, step: V2Step, isModal: boolean): HTMLElement {
+  const card = el('div', {
+    class: `${ROOT_CLASS} ${isModal ? 'om2-modal-card' : 'om2-tooltip'}`,
+    'data-step-id': step.id,
+  })
+
+  const titleEl = el('h3', { class: 'om2-title' })
+  titleEl.textContent = step.title || ''
+  card.appendChild(titleEl)
+
+  if (step.description) {
+    const descEl = el('p', { class: 'om2-description' })
+    descEl.textContent = step.description
+    card.appendChild(descEl)
+  }
+
+  const actions = el('div', { class: 'om2-actions' })
+  const counter = el('span', { class: 'om2-step-counter' })
+  counter.textContent = `${ctx.index + 1} / ${ctx.steps.length}`
+  actions.appendChild(counter)
+
+  // Skip (secondary) — only when more than one step remains AND the action
+  // isn't already 'skip' itself.
+  if (step.action.type !== 'skip' && ctx.steps.length > 1 && ctx.index < ctx.steps.length - 1) {
+    const skipBtn = el('button', { class: 'om2-btn om2-btn-secondary', type: 'button' })
+    skipBtn.textContent = 'Skip'
+    skipBtn.addEventListener('click', () => teardown(ctx))
+    actions.appendChild(skipBtn)
+  }
+
+  const primary = el('button', { class: 'om2-btn om2-btn-primary', type: 'button' })
+  primary.textContent = step.action.label || (step.action.type === 'complete' ? 'Done' : 'Next')
+  primary.addEventListener('click', () => advance(ctx, step))
+  actions.appendChild(primary)
+
+  card.appendChild(actions)
+  return card
+}
+
+// ─── Small DOM helpers ───────────────────────────────────────────────────────
+
+function el(tag: string, attrs: Record<string, string> = {}): HTMLElement {
+  const node = document.createElement(tag)
+  for (const [k, v] of Object.entries(attrs)) {
+    if (k === 'class') node.className = v
+    else node.setAttribute(k, v)
+  }
+  return node
+}
+
+function querySafe(selector: string): Element | null {
+  try {
+    return document.querySelector(selector)
+  } catch {
+    return null
+  }
+}
+
+function ensureStyles(shadowRoot: ShadowRoot): void {
+  // Inject styles only once per shadow root — repeated init() calls or
+  // page navigations don't pile up duplicates.
+  const existing = shadowRoot.querySelector(`style[${STYLE_MARKER}]`)
+  if (existing) return
+  const style = document.createElement('style')
+  style.setAttribute(STYLE_MARKER, '')
+  style.textContent = V2_STYLES
+  shadowRoot.appendChild(style)
+}
+
+function centreOnViewport(card: HTMLElement): void {
+  card.style.top  = '50%'
+  card.style.left = '50%'
+  card.style.transform = 'translate(-50%, -50%)'
+}

package/src/v2/styles.ts

@@ -0,0 +1,89 @@
+// Scoped styles for v2 components (Architecture v2 — Phase F).
+// Injected once into the Shadow DOM root so they cannot leak into the host
+// page and the host page's CSS cannot leak into us.
+
+export const V2_STYLES = `
+.om2-overlay {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.4);
+  z-index: 2147483646;
+}
+.om2-tooltip,
+.om2-modal-card {
+  position: absolute;
+  background: #ffffff;
+  color: #111827;
+  border-radius: 8px;
+  box-shadow: 0 10px 40px rgba(0, 0, 0, 0.15), 0 2px 8px rgba(0, 0, 0, 0.1);
+  padding: 16px 18px;
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
+  font-size: 14px;
+  line-height: 1.5;
+  max-width: 320px;
+  z-index: 2147483647;
+  box-sizing: border-box;
+}
+.om2-modal-card {
+  max-width: 440px;
+  padding: 24px 28px;
+}
+.om2-title {
+  margin: 0 0 6px 0;
+  font-weight: 600;
+  font-size: 15px;
+  line-height: 1.3;
+}
+.om2-modal-card .om2-title {
+  font-size: 18px;
+}
+.om2-description {
+  margin: 0 0 14px 0;
+  color: #4b5563;
+  font-size: 13px;
+}
+.om2-modal-card .om2-description {
+  font-size: 14px;
+  margin-bottom: 18px;
+}
+.om2-actions {
+  display: flex;
+  gap: 8px;
+  justify-content: flex-end;
+  align-items: center;
+}
+.om2-step-counter {
+  margin-right: auto;
+  font-size: 11px;
+  color: #9ca3af;
+  font-variant-numeric: tabular-nums;
+}
+.om2-btn {
+  font: inherit;
+  padding: 6px 14px;
+  border-radius: 6px;
+  border: none;
+  cursor: pointer;
+  font-weight: 500;
+  font-size: 13px;
+}
+.om2-btn-primary {
+  background: #2563eb;
+  color: #ffffff;
+}
+.om2-btn-primary:hover { background: #1d4ed8; }
+.om2-btn-secondary {
+  background: transparent;
+  color: #6b7280;
+}
+.om2-btn-secondary:hover { color: #374151; }
+.om2-highlight {
+  position: absolute;
+  pointer-events: none;
+  border: 2px solid #2563eb;
+  border-radius: 6px;
+  box-shadow: 0 0 0 4px rgba(37, 99, 235, 0.18);
+  z-index: 2147483646;
+  transition: top 0.15s ease, left 0.15s ease, width 0.15s ease, height 0.15s ease;
+}
+`