webdrive 1.0.0 → 1.1.0

package/README.md

@@ -43,6 +43,26 @@ bun add webdrive
 
 ---
 
+## 🤖 AI Agent Skill Installation
+
+`webdrive` includes an official **Agent Skill** so AI coding assistants (Google Antigravity, Claude Code, Cursor, GitHub Copilot) can automatically help you scaffold, configure, and troubleshoot tours.
+
+### Option A: Using WebDrive CLI (Instant)
+
+```bash
+npx webdrive install-skill
+```
+
+This installs `SKILL.md` into your project's `.agents/skills/webdrive/` folder.
+
+### Option B: Using the Agent Skills Ecosystem
+
+```bash
+npx skills add Abhi-6284/webdrive
+```
+
+---
+
 ## 🚀 Quick Start
 
 ### 1. Import CSS & JavaScript

package/bin/webdrive.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const pkg = JSON.parse(
+  fs.readFileSync(path.resolve(__dirname, "../package.json"), "utf8")
+);
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function printHelp() {
+  console.log(`
+\x1b[1m\x1b[34mWebDrive CLI\x1b[0m v${pkg.version}
+Framework-Agnostic UI Tour & Onboarding Library
+
+\x1b[1mUsage:\x1b[0m
+  webdrive <command> [options]
+  npx webdrive <command> [options]
+
+\x1b[1mCommands:\x1b[0m
+  install-skill     Install the WebDrive AI Agent Skill into your project
+  help, --help      Display this help message
+  --version, -v     Display the current version
+
+\x1b[1mOptions for install-skill:\x1b[0m
+  --target <dir>    Custom destination directory (default: .agents/skills/webdrive)
+  --all             Also install to .claude/skills and skills/
+
+\x1b[1mExamples:\x1b[0m
+  npx webdrive install-skill
+  npx skills add Abhi-6284/webdrive
+`);
+}
+
+function installSkill() {
+  const cwd = process.cwd();
+  const sourceSkillPath = path.resolve(__dirname, "../skills/webdrive/SKILL.md");
+
+  if (!fs.existsSync(sourceSkillPath)) {
+    console.error(`\x1b[31mError: Source SKILL.md not found at ${sourceSkillPath}\x1b[0m`);
+    process.exit(1);
+  }
+
+  const skillContent = fs.readFileSync(sourceSkillPath, "utf8");
+
+  // Determine target directories
+  let targets = [path.join(cwd, ".agents", "skills", "webdrive")];
+
+  const targetFlagIdx = args.indexOf("--target");
+  if (targetFlagIdx !== -1 && args[targetFlagIdx + 1]) {
+    targets = [path.resolve(cwd, args[targetFlagIdx + 1])];
+  } else if (args.includes("--all")) {
+    targets = [
+      path.join(cwd, ".agents", "skills", "webdrive"),
+      path.join(cwd, ".claude", "skills", "webdrive"),
+      path.join(cwd, "skills", "webdrive"),
+    ];
+  }
+
+  console.log(`\x1b[36mInstalling WebDrive AI Agent Skill...\x1b[0m`);
+
+  for (const targetDir of targets) {
+    fs.mkdirSync(targetDir, { recursive: true });
+    const destPath = path.join(targetDir, "SKILL.md");
+    fs.writeFileSync(destPath, skillContent, "utf8");
+    const relativePath = path.relative(cwd, destPath);
+    console.log(`\x1b[32m✔ Installed skill to:\x1b[0m ${relativePath}`);
+  }
+
+  console.log(`
+\x1b[32m✔ Success!\x1b[0m WebDrive Agent Skill is now ready.
+AI agents (Antigravity, Claude Code, Cursor, Copilot) can now assist you in building,
+customizing, and debugging WebDrive tours automatically.
+`);
+}
+
+switch (command) {
+  case "install-skill":
+  case "skill":
+  case "skill:install":
+  case "add-skill":
+    installSkill();
+    break;
+
+  case "-v":
+  case "--version":
+  case "version":
+    console.log(`webdrive v${pkg.version}`);
+    break;
+
+  case "help":
+  case "--help":
+  case "-h":
+    printHelp();
+    break;
+
+  default:
+    if (!command) {
+      printHelp();
+    } else {
+      console.log(`Unknown command: ${command}`);
+      printHelp();
+      process.exit(1);
+    }
+    break;
+}

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "webdrive",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "description": "Production-ready, accessible, framework-agnostic TypeScript UI tour and onboarding walkthrough library",
   "author": "webdrive",
   "license": "MIT",
+  "bin": {
+    "webdrive": "./bin/webdrive.js"
+  },
   "keywords": [
     "tour",
     "onboarding",
@@ -30,6 +33,8 @@
   },
   "files": [
     "dist",
+    "bin",
+    "skills",
     "README.md",
     "LICENSE"
   ],

package/skills/webdrive/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: webdrive
+description: >-
+  Guide for implementing, configuring, and troubleshooting UI product tours, feature walkthroughs,
+  and onboarding flows using webdrive (framework-agnostic TypeScript library).
+  Use this skill whenever adding an onboarding tour, step-by-step guide, feature highlight, or popover
+  walkthrough in Vanilla JS, React, Next.js, Vue, Nuxt, Angular, Svelte, or any web app.
+---
+
+# WebDrive — UI Tour & Onboarding Skill
+
+`webdrive` is a production-ready, framework-agnostic TypeScript UI tour and onboarding library with zero runtime dependencies. It uses a non-destructive SVG cutout mask to highlight target elements without altering stacking contexts, z-index, or CSS transforms.
+
+## Quick Installation & Setup
+
+```bash
+npm install webdrive
+```
+
+### Essential Imports
+
+```typescript
+import { WebDrive } from "webdrive";
+import "webdrive/styles.css";
+```
+
+> **IMPORTANT:** In Next.js App Router, always import and initialize `WebDrive` inside Client Components (`"use client"`). It is 100% SSR-safe and will never crash on server evaluation.
+
+---
+
+## Standard Tour Pattern
+
+```typescript
+const tour = new WebDrive({
+  id: "onboarding-tour", // Used for persistence
+  steps: [
+    {
+      element: "#navigation",
+      title: "Navigation",
+      description: "Quickly jump to any section of the app.",
+      position: "right", // "top" | "right" | "bottom" | "left"
+      align: "start",    // "start" | "center" | "end"
+    },
+    {
+      element: "#metrics-card",
+      title: "Key Metrics",
+      description: "Track real-time analytics and revenue performance.",
+      position: "bottom",
+      align: "center",
+    },
+    {
+      element: "#profile-button",
+      title: "Account Settings",
+      description: "Manage your profile, team members, and preferences.",
+      position: "left",
+      align: "end",
+    },
+  ],
+  showProgress: true,
+  animate: true,
+  smoothScroll: true,
+  keyboardNavigation: true,
+  allowClose: true,
+  remember: true, // Persists completion in localStorage
+});
+
+// Start the tour
+tour.start();
+```
+
+---
+
+## Step Options Reference
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `element` | `string \| HTMLElement` | Target CSS selector or DOM element (Required) |
+| `title` | `string` | Header title |
+| `description` | `string` | Safe text content for the popover card |
+| `content` | `string` | Custom HTML content when rich markup is needed |
+| `position` | `"top" \| "right" \| "bottom" \| "left"` | Preferred popover placement (default: `"bottom"`) |
+| `align` | `"start" \| "center" \| "end"` | Alignment along target axis (default: `"center"`) |
+| `padding` | `number` | Padding around cutout in pixels (default: `8`) |
+| `offset` | `number` | Distance between target and popover in px (default: `12`) |
+| `showNextButton` | `boolean` | Whether to display the Next button |
+| `showPreviousButton`| `boolean` | Whether to display the Previous button |
+| `showCloseButton` | `boolean` | Whether to display the Close button |
+| `nextButtonText` | `string` | Custom label for Next button |
+| `previousButtonText`| `string` | Custom label for Previous button |
+| `doneButtonText` | `string` | Custom label for Done button on final step |
+| `closeButtonText` | `string` | Custom label / aria-label for Close button |
+| `onEnter` | `() => void \| Promise<void>` | Callback when entering step |
+| `onLeave` | `() => void \| Promise<void>` | Callback when leaving step |
+
+---
+
+## Dynamic Elements & Async Content
+
+If a target element is created dynamically or loads after an API call:
+
+```typescript
+const tour = new WebDrive({
+  missingElementBehavior: "wait", // "wait" | "skip" | "stop"
+  missingElementWaitTimeout: 4000, // Timeout in ms before falling back
+  steps: [
+    { element: "#async-chart", title: "Charts", description: "Loaded dynamically." }
+  ]
+});
+```
+
+---
+
+## Framework Recipes
+
+### React & Next.js (`"use client"`)
+
+```tsx
+"use client";
+
+import { useEffect, useRef } from "react";
+import { WebDrive } from "webdrive";
+import "webdrive/styles.css";
+
+export function ProductTour() {
+  const tourRef = useRef<WebDrive | null>(null);
+
+  useEffect(() => {
+    tourRef.current = new WebDrive({
+      id: "app-intro",
+      remember: true,
+      steps: [
+        { element: "#sidebar", title: "Menu", description: "Navigate here." },
+        { element: "#main-cta", title: "Action", description: "Get started here." }
+      ]
+    });
+
+    tourRef.current.start();
+
+    return () => {
+      tourRef.current?.destroy();
+    };
+  }, []);
+
+  return null;
+}
+```
+
+### Vue 3 / Nuxt
+
+```vue
+<script setup>
+import { onMounted, onUnmounted } from "vue";
+import { WebDrive } from "webdrive";
+import "webdrive/styles.css";
+
+let tour = null;
+
+onMounted(() => {
+  tour = new WebDrive({
+    steps: [
+      { element: "#header", title: "Header", description: "Overview." }
+    ]
+  });
+  tour.start();
+});
+
+onUnmounted(() => {
+  tour?.destroy();
+});
+</script>
+```
+
+---
+
+## Theming & Styling
+
+Customize colors using CSS custom properties:
+
+```css
+:root {
+  --webdrive-background: #ffffff;
+  --webdrive-foreground: #0f172a;
+  --webdrive-border: #e2e8f0;
+  --webdrive-primary: #2563eb;
+  --webdrive-primary-foreground: #ffffff;
+  --webdrive-muted: #64748b;
+  --webdrive-overlay: rgba(0, 0, 0, 0.6);
+  --webdrive-radius: 0.75rem;
+  --webdrive-shadow: 0 20px 25px -5px rgba(0, 0, 0, 0.1);
+  --webdrive-z-index: 100000;
+}
+
+/* Dark Mode automatically applied when .dark or [data-theme="dark"] is present */
+.dark {
+  --webdrive-background: #0f172a;
+  --webdrive-foreground: #f8fafc;
+  --webdrive-border: #1e293b;
+  --webdrive-primary: #3b82f6;
+}
+```
+
+---
+
+## Best Practices & Troubleshooting
+
+1. **Always cleanup on unmount:** Call `tour.destroy()` in React's cleanup function, Vue's `onUnmounted`, or Svelte's `onDestroy` to remove DOM elements and listeners.
+2. **Never hardcode generic IDs:** Prefer unique IDs or data attributes (e.g. `[data-tour="search-input"]`).
+3. **Reset tour completion during testing:**
+   ```typescript
+   await tour.reset(); // Clears completion status for this tour
+   ```
+4. **Do not modify application DOM styles:** WebDrive handles overlays and highlights externally without mutating the target element's styling.