@cttricks/spotlight

This project was developed with the assistance of Antigravity. I used it to improve and refine the library, while the playground/demo-site were completely generated by Antigravity.

---

What It Is

When rolling out complex web applications and feature updates, user churn frequently occurs during the first sixty seconds because users do not know where new controls reside or how specific workflows operate. Standard product tour solutions often bundle heavy dependencies, inject intrusive styles that conflict with existing design systems, or fail gracefully on responsive mobile viewports.

@cttricks/spotlight is an ultra-lightweight, zero-dependency client-side onboarding and product tour library. It isolates focus on active DOM elements with animated SVG clipping paths, dynamically recalculates tooltip positions near screen boundaries, and orchestrates step-by-step guidance without framework lock-in.

---

Key Capabilities & Features

• Dynamic SVG Masking: Smoothly clips out focus viewports around any DOM element, dimming the rest of the application interface without disrupting underlying layouts.
• Adaptive Boundary Positioning: Continuously recalculates bounding rects to prevent guide tooltips from clipping outside window boundaries across scrolls, resizes, and orientation changes.
• Zero External Dependencies: Built with pure TypeScript and standard browser APIs to keep installation lightweight and bundle impact negligible.
• Interactive Lifecycle Hooks: Emits clear progression, skip, previous/next, and termination events to sync walkthrough state with user profiles or local storage.
• Framework Agnostic: Seamlessly integrates into vanilla JavaScript, React, Next.js, Vue, or any legacy web architecture.

---

Installation & Quick Start

npm i @cttricks/spotlight

1. Tag your elements in HTML or JSX

<button 
  data-spot-id="search-btn"
  data-spot-name="Instant Search" 
  data-spot-summary="Press ⌘K anytime to search documents and shortcuts."
  data-spot-media="/assets/search-preview.mp4"
  data-spot-position="bottom">
  Search (⌘K)
</button>

2. Launch in JavaScript / TypeScript

import { spotlight } from '@cttricks/spotlight';
import '@cttricks/spotlight/styles';

const tour = await spotlight({
  theme: 'auto',              // 'light' | 'dark' | 'auto' (OS color sync)
  highlightColor: '#ffffff',  // Custom stroke & accent color
  backdropBlur: 4             // Glassmorphism backdrop blur (px)
});

tour.start();

👉 For complete API reference, lifecycle hooks, custom themes, and media embed options, visit the GitHub Documentation or experiment with live configurations on the Spotlight Playground.

---

AI-Assisted Engineering Workflow

Modern engineering is about shipping robust systems quickly and using the best tools available.

I authored and designed the architecture, core geometry algorithms, and state progression model for @cttricks/spotlight. To streamline production, I paired with Antigravity to:

1. Refine Edge-Case Handling: Rapidly test, identify, and address scroll-offset edge cases, mobile viewport constraints, and SVG clip path recalculations.
2. Build the Interactive Playground: Completely generate and style the standalone interactive demo site and playground at spotlight.cttricks.com, allowing developers to test walkthroughs live in the browser.

By combining deliberate architectural thinking with agentic coding assistants, I was able to take the library from a local utility concept to a battle-tested NPM release and interactive documentation site in a fraction of the traditional turnaround time.

---

Key Learnings & Takeaways

• DOM geometry demands respect: Handling cross-browser viewport calculations, scroll anchors, and sticky header offsets requires clean math rather than CSS hacks.
• Leveraging modern AI effectively: Knowing what to architect and how to verify edge cases makes agentic AI tools like Antigravity a massive force multiplier for solo open-source maintainers.