beads-map 0.3.0 → 0.3.3

package/components/DescriptionModal.tsx

@@ -1,16 +1,29 @@
 "use client";
 
+import { useState } from "react";
 import { createPortal } from "react-dom";
 import ReactMarkdown from "react-markdown";
 import remarkGfm from "remark-gfm";
 import type { GraphNode } from "@/lib/types";
+import { buildDescriptionCopyText } from "@/lib/utils";
 
 interface DescriptionModalProps {
   node: GraphNode;
   onClose: () => void;
+  repoUrl?: string;
 }
 
-export function DescriptionModal({ node, onClose }: DescriptionModalProps) {
+export function DescriptionModal({ node, onClose, repoUrl }: DescriptionModalProps) {
+  const [copied, setCopied] = useState(false);
+
+  const handleCopy = () => {
+    if (!node.description) return;
+    navigator.clipboard.writeText(buildDescriptionCopyText(node, repoUrl)).then(() => {
+      setCopied(true);
+      setTimeout(() => setCopied(false), 1500);
+    });
+  };
+
   if (!node.description) return null;
 
   return createPortal(
@@ -32,24 +45,41 @@ export function DescriptionModal({ node, onClose }: DescriptionModalProps) {
               {node.title}
             </span>
           </div>
-          <button
-            onClick={onClose}
-            className="shrink-0 p-1 text-zinc-400 hover:text-zinc-600 transition-colors"
-          >
-            <svg
-              className="w-4 h-4"
-              fill="none"
-              stroke="currentColor"
-              viewBox="0 0 24 24"
-              strokeWidth={2}
+          <div className="flex items-center gap-1 shrink-0">
+            <button
+              onClick={handleCopy}
+              className="p-1 text-zinc-400 hover:text-zinc-600 transition-colors"
+              title="Copy description"
             >
-              <path
-                strokeLinecap="round"
-                strokeLinejoin="round"
-                d="M6 18L18 6M6 6l12 12"
-              />
-            </svg>
-          </button>
+              {copied ? (
+                <svg className="w-4 h-4 text-emerald-500" fill="none" stroke="currentColor" viewBox="0 0 24 24" strokeWidth={2}>
+                  <path strokeLinecap="round" strokeLinejoin="round" d="M4.5 12.75l6 6 9-13.5" />
+                </svg>
+              ) : (
+                <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24" strokeWidth={2}>
+                  <path strokeLinecap="round" strokeLinejoin="round" d="M15.666 3.888A2.25 2.25 0 0 0 13.5 2.25h-3c-1.03 0-1.9.693-2.166 1.638m7.332 0c.055.194.084.4.084.612v0a.75.75 0 0 1-.75.75H9.75a.75.75 0 0 1-.75-.75v0c0-.212.03-.418.084-.612m7.332 0c.646.049 1.288.11 1.927.184 1.1.128 1.907 1.077 1.907 2.185V19.5a2.25 2.25 0 0 1-2.25 2.25H6.75A2.25 2.25 0 0 1 4.5 19.5V6.257c0-1.108.806-2.057 1.907-2.185a48.208 48.208 0 0 1 1.927-.184" />
+                </svg>
+              )}
+            </button>
+            <button
+              onClick={onClose}
+              className="p-1 text-zinc-400 hover:text-zinc-600 transition-colors"
+            >
+              <svg
+                className="w-4 h-4"
+                fill="none"
+                stroke="currentColor"
+                viewBox="0 0 24 24"
+                strokeWidth={2}
+              >
+                <path
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  d="M6 18L18 6M6 6l12 12"
+                />
+              </svg>
+            </button>
+          </div>
         </div>
         {/* Modal body */}
         <div className="flex-1 overflow-y-auto px-5 py-4 custom-scrollbar description-markdown text-sm text-zinc-700 leading-relaxed">

package/components/HelpPanel.tsx

@@ -0,0 +1,336 @@
+"use client";
+
+import { TUTORIAL_STEPS } from "./TutorialOverlay";
+
+// Catppuccin Latte accents
+const CAT = {
+  red: "#d20f39",
+  teal: "#179299",
+  peach: "#fe640b",
+  blue: "#1e66f5",
+  green: "#40a02b",
+  mauve: "#8839ef",
+  sapphire: "#209fb5",
+  pink: "#ea76cb",
+  surface: "#dce0e8",
+};
+
+interface HelpPanelProps {
+  isOpen: boolean;
+  onClose: () => void;
+  tutorialStep?: number | null;
+  onStartTutorial?: () => void;
+  onNextStep?: () => void;
+  onPrevStep?: () => void;
+  onEndTutorial?: () => void;
+}
+
+export function HelpPanel({
+  isOpen,
+  onClose,
+  tutorialStep = null,
+  onStartTutorial,
+  onNextStep,
+  onPrevStep,
+  onEndTutorial,
+}: HelpPanelProps) {
+  const isTutorialActive = tutorialStep !== null;
+  const headerText = isTutorialActive ? "Tutorial" : "Welcome to Heartbeads";
+
+  const content = isTutorialActive ? (
+    <TutorialContent
+      step={tutorialStep}
+      onNext={onNextStep!}
+      onPrev={onPrevStep!}
+      onEnd={onEndTutorial!}
+    />
+  ) : (
+    <HelpContent onStartTutorial={onStartTutorial} />
+  );
+
+  return (
+    <>
+      {/* Desktop: right sidebar — z-[60] during tutorial so it sits above the overlay */}
+      <aside
+        className={`hidden md:flex absolute top-0 right-0 h-full w-[360px] bg-white border-l border-zinc-200 flex-col shadow-xl transform transition-transform duration-300 ease-out ${
+          isOpen ? "translate-x-0" : "translate-x-full"
+        } ${isTutorialActive ? "z-[60]" : "z-30"}`}
+      >
+        <div className="flex items-center justify-between px-5 py-3 border-b border-zinc-100 shrink-0">
+          <h2 className="text-sm font-semibold text-zinc-900">
+            {headerText}
+          </h2>
+          <button
+            onClick={onClose}
+            className="p-1 text-zinc-400 hover:text-zinc-600 transition-colors"
+          >
+            <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24" strokeWidth={2}>
+              <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />
+            </svg>
+          </button>
+        </div>
+        <div className="flex-1 overflow-y-auto custom-scrollbar">
+          {content}
+        </div>
+      </aside>
+
+      {/* Mobile: bottom drawer */}
+      <div
+        className={`md:hidden fixed inset-x-0 bottom-0 transform transition-transform duration-300 ease-out ${
+          isOpen ? "translate-y-0" : "translate-y-full"
+        } ${isTutorialActive ? "z-[60]" : "z-20"}`}
+      >
+        <div className="bg-white rounded-t-2xl shadow-2xl border-t border-zinc-200 max-h-[70vh] flex flex-col">
+          <div className="flex items-center justify-between px-5 py-3 border-b border-zinc-100 shrink-0">
+            <h2 className="text-sm font-semibold text-zinc-900">
+              {headerText}
+            </h2>
+            <button
+              onClick={onClose}
+              className="p-1 text-zinc-400 hover:text-zinc-600 transition-colors"
+            >
+              <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24" strokeWidth={2}>
+                <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />
+              </svg>
+            </button>
+          </div>
+          <div className="flex-1 overflow-y-auto custom-scrollbar">
+            {content}
+          </div>
+        </div>
+      </div>
+    </>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  Tutorial step-by-step content                                      */
+/* ------------------------------------------------------------------ */
+
+function TutorialContent({
+  step,
+  onNext,
+  onPrev,
+  onEnd,
+}: {
+  step: number;
+  onNext: () => void;
+  onPrev: () => void;
+  onEnd: () => void;
+}) {
+  const currentStep = TUTORIAL_STEPS[step];
+  const totalSteps = TUTORIAL_STEPS.length;
+  const isFirst = step === 0;
+  const isLast = step === totalSteps - 1;
+
+  return (
+    <div className="px-5 py-4 flex flex-col min-h-[300px]">
+      {/* Step indicator */}
+      <div className="flex items-center justify-between mb-4">
+        <span className="text-xs font-medium" style={{ color: CAT.teal }}>
+          {step + 1} / {totalSteps}
+        </span>
+        <div className="flex gap-1">
+          {Array.from({ length: totalSteps }).map((_, i) => (
+            <div
+              key={i}
+              className="w-1.5 h-1.5 rounded-full transition-colors"
+              style={{
+                backgroundColor:
+                  i === step ? CAT.green : i < step ? CAT.teal : CAT.surface,
+              }}
+            />
+          ))}
+        </div>
+      </div>
+
+      {/* Step title */}
+      <h3 className="text-base font-semibold text-zinc-900 mb-2">
+        {currentStep.title}
+      </h3>
+
+      {/* Step description */}
+      <p className="text-[13px] text-zinc-600 leading-relaxed mb-6">
+        {currentStep.description}
+      </p>
+
+      {/* Spacer */}
+      <div className="flex-1" />
+
+      {/* Navigation */}
+      <div className="flex items-center gap-2 pt-4 border-t border-zinc-100">
+        {isFirst ? (
+          <button
+            onClick={onEnd}
+            className="px-4 py-2 text-sm font-medium text-zinc-400 hover:text-zinc-600 rounded-lg hover:bg-zinc-50 transition-colors"
+          >
+            Skip
+          </button>
+        ) : (
+          <button
+            onClick={onPrev}
+            className="px-4 py-2 text-sm font-medium rounded-lg hover:bg-zinc-50 transition-colors"
+            style={{ color: CAT.blue }}
+          >
+            {"Back"}
+          </button>
+        )}
+        <div className="flex-1" />
+        {isLast ? (
+          <button
+            onClick={onEnd}
+            className="px-4 py-2 text-sm font-medium text-white rounded-lg bg-emerald-500 hover:bg-emerald-600 transition-colors"
+          >
+            {"Done"}
+          </button>
+        ) : (
+          <button
+            onClick={onNext}
+            className="px-4 py-2 text-sm font-medium text-white rounded-lg bg-emerald-500 hover:bg-emerald-600 transition-colors"
+          >
+            {"Next"}
+          </button>
+        )}
+      </div>
+    </div>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  Bullet with Catppuccin colored dot                                 */
+/* ------------------------------------------------------------------ */
+
+function Bullet({ color, children }: { color: string; children: React.ReactNode }) {
+  return (
+    <li className="flex gap-2.5 items-start">
+      <span
+        className="w-1.5 h-1.5 rounded-full mt-[6px] shrink-0"
+        style={{ backgroundColor: color }}
+      />
+      <span>{children}</span>
+    </li>
+  );
+}
+
+function SectionTitle({ children, color }: { children: React.ReactNode; color: string }) {
+  return (
+    <h3
+      className="text-[11px] font-semibold uppercase tracking-widest mb-2 mt-5 first:mt-0"
+      style={{ color }}
+    >
+      {children}
+    </h3>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  Static help content                                                */
+/* ------------------------------------------------------------------ */
+
+function HelpContent({ onStartTutorial }: { onStartTutorial?: () => void }) {
+  return (
+    <div className="px-5 py-4 text-[13px] text-zinc-600 leading-relaxed">
+      {/* Start Tutorial */}
+      {onStartTutorial && (
+        <button
+          onClick={onStartTutorial}
+          className="w-full flex items-center justify-center gap-2 px-4 py-2.5 mb-5 text-white text-sm font-medium rounded-lg bg-emerald-500 hover:bg-emerald-600 transition-colors"
+        >
+          <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" strokeWidth={2} stroke="currentColor">
+            <path strokeLinecap="round" strokeLinejoin="round" d="M12 18v-5.25m0 0a6.01 6.01 0 001.5-.189m-1.5.189a6.01 6.01 0 01-1.5-.189m3.75 7.478a12.06 12.06 0 01-4.5 0m3.75 2.383a14.406 14.406 0 01-3 0M14.25 18v-.192c0-.983.658-1.823 1.508-2.316a7.5 7.5 0 10-7.517 0c.85.493 1.509 1.333 1.509 2.316V18" />
+          </svg>
+          Take the guided tour
+        </button>
+      )}
+
+      <p className="text-zinc-900 font-medium mb-1">
+        Your command center for AI coding tasks.
+      </p>
+      <p className="mb-4 text-zinc-500">
+        Heartbeads shows everything your AI agents are working on as a
+        live, interactive graph &mdash; tasks, dependencies, who&apos;s doing what, and
+        what&apos;s blocking progress.
+      </p>
+
+      <SectionTitle color={CAT.red}>The graph</SectionTitle>
+      <p className="mb-2">
+        Each <strong>circle</strong> is a task. <strong>Flowing particles</strong>{" "}
+        stream between them to show dependency direction.
+      </p>
+      <ul className="space-y-1.5 mb-3">
+        <Bullet color={CAT.red}><strong>Bigger circles</strong> &mdash; more connected, more important</Bullet>
+        <Bullet color={CAT.red}><strong>Solid lines + particles</strong> &mdash; &ldquo;blocks&rdquo; (A must finish before B)</Bullet>
+        <Bullet color={CAT.red}><strong>Dashed lines</strong> &mdash; parent-child grouping</Bullet>
+        <Bullet color={CAT.red}><strong>Colored ring</strong> &mdash; which project it belongs to</Bullet>
+      </ul>
+
+      <SectionTitle color={CAT.blue}>Navigation</SectionTitle>
+      <ul className="space-y-1.5 mb-3">
+        <Bullet color={CAT.blue}><strong>Click</strong> a node to open its details</Bullet>
+        <Bullet color={CAT.blue}><strong>Hover</strong> for a quick summary</Bullet>
+        <Bullet color={CAT.blue}><strong>Right-click</strong> for actions &mdash; descriptions, comments, claims, collapse</Bullet>
+        <Bullet color={CAT.blue}><strong>Scroll</strong> to zoom, <strong>drag</strong> to pan</Bullet>
+        <Bullet color={CAT.blue}><strong>Cmd/Ctrl+F</strong> to search by name, ID, owner, or commenter</Bullet>
+      </ul>
+
+      <SectionTitle color={CAT.teal}>Layouts</SectionTitle>
+      <p className="mb-2">
+        Top-left buttons rearrange the graph:
+      </p>
+      <ul className="space-y-1.5 mb-3">
+        <Bullet color={CAT.teal}><strong>Force</strong> &mdash; organic, physics-based</Bullet>
+        <Bullet color={CAT.teal}><strong>DAG</strong> &mdash; clean top-down tree</Bullet>
+        <Bullet color={CAT.teal}><strong>Radial</strong> &mdash; rings from center outward</Bullet>
+        <Bullet color={CAT.teal}><strong>Cluster</strong> &mdash; grouped by project</Bullet>
+        <Bullet color={CAT.teal}><strong>Spread</strong> &mdash; spaced out for screenshots</Bullet>
+      </ul>
+
+      <SectionTitle color={CAT.peach}>Color modes</SectionTitle>
+      <p className="mb-2">
+        Bottom-right panel &mdash; paint nodes by:
+      </p>
+      <ul className="space-y-1.5 mb-3">
+        <Bullet color={CAT.peach}><strong>Status</strong> &mdash; open, in progress, blocked, closed</Bullet>
+        <Bullet color={CAT.peach}><strong>Priority</strong> &mdash; P0 critical to P4 backlog</Bullet>
+        <Bullet color={CAT.peach}><strong>Owner</strong> &mdash; who created it</Bullet>
+        <Bullet color={CAT.peach}><strong>Assignee</strong> &mdash; who&apos;s working on it</Bullet>
+        <Bullet color={CAT.peach}><strong>Prefix</strong> &mdash; which project</Bullet>
+      </ul>
+
+      <SectionTitle color={CAT.mauve}>More</SectionTitle>
+      <ul className="space-y-1.5 mb-3">
+        <Bullet color={CAT.mauve}><strong>Collapse/Expand</strong> &mdash; tidy up epics into single nodes</Bullet>
+        <Bullet color={CAT.mauve}><strong>Clusters</strong> &mdash; dashed circles grouping projects when zoomed out</Bullet>
+        <Bullet color={CAT.mauve}><strong>Replay</strong> &mdash; step through your project&apos;s history</Bullet>
+        <Bullet color={CAT.mauve}><strong>Comments</strong> &mdash; leave notes on tasks (sign in first)</Bullet>
+        <Bullet color={CAT.mauve}><strong>Claim tasks</strong> &mdash; right-click to mark as yours</Bullet>
+        <Bullet color={CAT.mauve}><strong>Minimap</strong> &mdash; click to jump, drag edges to resize</Bullet>
+        <Bullet color={CAT.mauve}><strong>Auto-fit</strong> &mdash; top-left toggle to lock/unlock automatic camera reframing</Bullet>
+        <Bullet color={CAT.mauve}><strong>Copy</strong> &mdash; clipboard icon copies task with project info</Bullet>
+      </ul>
+
+      <div className="mt-5 pt-4 border-t border-zinc-100 text-xs text-zinc-400">
+        Built with{" "}
+        <a
+          href="https://github.com/GainForest/beads"
+          target="_blank"
+          rel="noopener noreferrer"
+          className="underline underline-offset-2 transition-colors"
+          style={{ color: CAT.green }}
+        >
+          beads
+        </a>{" "}
+        &mdash; open-source issue tracking for AI-native development. Heartbeads is built for the GainForest agentic workflow and open-sourced at{" "}
+        <a
+          href="https://github.com/daviddao/heartbeads"
+          target="_blank"
+          rel="noopener noreferrer"
+          className="underline underline-offset-2 transition-colors"
+          style={{ color: CAT.green }}
+        >
+          github.com/daviddao/heartbeads
+        </a>.
+      </div>
+    </div>
+  );
+}

package/components/NodeDetail.tsx

@@ -6,7 +6,7 @@ import remarkGfm from "remark-gfm";
 import type { GraphNode } from "@/lib/types";
 import { DescriptionModal } from "./DescriptionModal";
 import { HeartIcon } from "@/components/HeartIcon";
-import { formatRelativeTime } from "@/lib/utils";
+import { formatRelativeTime, buildDescriptionCopyText } from "@/lib/utils";
 import {
   STATUS_LABELS,
   STATUS_COLORS,
@@ -50,6 +50,7 @@ export default function NodeDetail({
   const [replyText, setReplyText] = useState("");
   const [isSubmittingReply, setIsSubmittingReply] = useState(false);
   const [descriptionExpanded, setDescriptionExpanded] = useState(false);
+  const [descCopied, setDescCopied] = useState(false);
 
   const handleStartReply = (comment: BeadsComment) => {
     setReplyingToUri(comment.uri);
@@ -314,12 +315,36 @@ export default function NodeDetail({
             <h4 className="text-xs font-semibold text-zinc-500 uppercase tracking-wider">
               Description
             </h4>
-            <button
-              onClick={() => setDescriptionExpanded(true)}
-              className="text-[10px] text-zinc-400 hover:text-zinc-600 transition-colors"
-            >
-              View in window
-            </button>
+            <div className="flex items-center gap-2">
+              <button
+                onClick={() => {
+                  if (!node.description) return;
+                  const repoUrl = repoUrls?.[node.prefix];
+                  navigator.clipboard.writeText(buildDescriptionCopyText(node, repoUrl)).then(() => {
+                    setDescCopied(true);
+                    setTimeout(() => setDescCopied(false), 1500);
+                  });
+                }}
+                className="text-zinc-400 hover:text-zinc-600 transition-colors"
+                title="Copy description"
+              >
+                {descCopied ? (
+                  <svg className="w-3.5 h-3.5 text-emerald-500" fill="none" stroke="currentColor" viewBox="0 0 24 24" strokeWidth={2}>
+                    <path strokeLinecap="round" strokeLinejoin="round" d="M4.5 12.75l6 6 9-13.5" />
+                  </svg>
+                ) : (
+                  <svg className="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24" strokeWidth={2}>
+                    <path strokeLinecap="round" strokeLinejoin="round" d="M15.666 3.888A2.25 2.25 0 0 0 13.5 2.25h-3c-1.03 0-1.9.693-2.166 1.638m7.332 0c.055.194.084.4.084.612v0a.75.75 0 0 1-.75.75H9.75a.75.75 0 0 1-.75-.75v0c0-.212.03-.418.084-.612m7.332 0c.646.049 1.288.11 1.927.184 1.1.128 1.907 1.077 1.907 2.185V19.5a2.25 2.25 0 0 1-2.25 2.25H6.75A2.25 2.25 0 0 1 4.5 19.5V6.257c0-1.108.806-2.057 1.907-2.185a48.208 48.208 0 0 1 1.927-.184" />
+                  </svg>
+                )}
+              </button>
+              <button
+                onClick={() => setDescriptionExpanded(true)}
+                className="text-[10px] text-zinc-400 hover:text-zinc-600 transition-colors"
+              >
+                View in window
+              </button>
+            </div>
           </div>
           <div className="text-xs text-zinc-600 leading-relaxed bg-zinc-50 rounded-lg p-3 max-h-40 overflow-y-auto custom-scrollbar border border-zinc-100 description-markdown">
             <ReactMarkdown remarkPlugins={[remarkGfm]}>
@@ -331,7 +356,7 @@ export default function NodeDetail({
 
       {/* Description expanded modal */}
       {descriptionExpanded && node.description && (
-        <DescriptionModal node={node} onClose={() => setDescriptionExpanded(false)} />
+        <DescriptionModal node={node} onClose={() => setDescriptionExpanded(false)} repoUrl={repoUrls?.[node.prefix]} />
       )}
 
       {/* Blocks (issues this blocks) */}

package/components/TutorialOverlay.tsx

@@ -0,0 +1,187 @@
+"use client";
+
+import { useEffect, useState, useCallback } from "react";
+
+export interface TutorialStep {
+  target: string;
+  title: string;
+  description: string;
+  padding?: number;
+}
+
+export const TUTORIAL_STEPS: TutorialStep[] = [
+  {
+    target: "graph",
+    title: "The Dependency Graph",
+    description:
+      "Each circle is a task or issue. The flowing particles between them show the direction of dependencies \u2014 what needs to happen before something else can start. Bigger circles mean more connections.",
+    padding: 0,
+  },
+  {
+    target: "layouts",
+    title: "Layout Modes",
+    description:
+      "Switch how the graph is arranged. Force is organic and physics-based. DAG gives you a clean top-down tree. Radial spreads nodes in rings. Cluster groups by project. Spread spaces everything out for screenshots.",
+  },
+  {
+    target: "view-controls",
+    title: "View Controls",
+    description:
+      "Collapse or expand epic groups, toggle cluster label overlays, and control auto-fit. When auto-fit is on (green), the camera re-centers after every update. Turn it off to stay focused on a specific area while data streams in.",
+  },
+  {
+    target: "legend",
+    title: "Color Modes & Legend",
+    description:
+      "Color nodes by Status, Priority, Owner, Assignee, or Prefix. The ring around each node always shows which project it belongs to.",
+  },
+  {
+    target: "minimap",
+    title: "Minimap",
+    description:
+      "A bird\u2019s-eye view of your entire graph. Click anywhere to jump there. Drag the edges to resize it.",
+  },
+  {
+    target: "search",
+    title: "Search",
+    description:
+      "Press Cmd+F (or Ctrl+F) to search by name, ID, owner, assignee, or commenter. Arrow keys to navigate, Enter to focus.",
+  },
+  {
+    target: "graph",
+    title: "Interacting with Nodes",
+    description:
+      "Click a node to see details. Hover for a quick tooltip. Right-click for actions like viewing descriptions, commenting, claiming tasks, or collapsing epics.",
+    padding: 0,
+  },
+  {
+    target: "nav-pills",
+    title: "Navigation Bar",
+    description:
+      "Replay steps through your project\u2019s history. Comments shows conversations. Activity is a real-time feed. And Learn brings you right back here.",
+  },
+];
+
+interface TutorialOverlayProps {
+  step: number | null;
+  onNext: () => void;
+  onPrev: () => void;
+  onEnd: () => void;
+}
+
+interface Rect {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+export function TutorialOverlay({
+  step,
+  onNext,
+  onEnd,
+}: TutorialOverlayProps) {
+  const [targetRect, setTargetRect] = useState<Rect | null>(null);
+
+  const updateRect = useCallback(() => {
+    if (step === null) {
+      setTargetRect(null);
+      return;
+    }
+    const currentStep = TUTORIAL_STEPS[step];
+    if (!currentStep) {
+      setTargetRect(null);
+      return;
+    }
+    const el = document.querySelector(
+      `[data-tutorial="${currentStep.target}"]`
+    );
+    if (!el) {
+      setTargetRect(null);
+    } else {
+      const r = el.getBoundingClientRect();
+      const padding = currentStep.padding ?? 8;
+      setTargetRect({
+        left: r.left - padding,
+        top: r.top - padding,
+        width: r.width + padding * 2,
+        height: r.height + padding * 2,
+      });
+    }
+  }, [step]);
+
+  useEffect(() => {
+    updateRect();
+    const handleResize = () => updateRect();
+    window.addEventListener("resize", handleResize);
+    const timer = setTimeout(updateRect, 150);
+    return () => {
+      window.removeEventListener("resize", handleResize);
+      clearTimeout(timer);
+    };
+  }, [updateRect]);
+
+  if (step === null) return null;
+
+  const isLast = step === TUTORIAL_STEPS.length - 1;
+
+  const handleClick = () => {
+    if (isLast) {
+      onEnd();
+    } else {
+      onNext();
+    }
+  };
+
+  // The sidebar is z-[60] during tutorial, so it naturally sits above this z-[55] overlay.
+  // Clicking the dark area advances/ends the tutorial. The spotlight cutout is visual only.
+  return (
+    <>
+      {/* Full-screen clickable dark overlay */}
+      <div
+        className="fixed inset-0 z-[55] cursor-pointer"
+        onClick={handleClick}
+      >
+        {/* SVG with mask to punch a transparent hole for the spotlight */}
+        <svg className="absolute inset-0 w-full h-full" xmlns="http://www.w3.org/2000/svg">
+          <defs>
+            <mask id="tutorial-mask">
+              <rect width="100%" height="100%" fill="white" />
+              {targetRect && (
+                <rect
+                  x={targetRect.left}
+                  y={targetRect.top}
+                  width={targetRect.width}
+                  height={targetRect.height}
+                  rx={8}
+                  ry={8}
+                  fill="black"
+                />
+              )}
+            </mask>
+          </defs>
+          <rect
+            width="100%"
+            height="100%"
+            fill="rgba(0,0,0,0.45)"
+            mask="url(#tutorial-mask)"
+          />
+        </svg>
+      </div>
+
+      {/* Pulsing ring around spotlight target */}
+      {targetRect && (
+        <div
+          className="fixed rounded-lg ring-2 ring-emerald-400/60 animate-pulse z-[56]"
+          style={{
+            left: targetRect.left,
+            top: targetRect.top,
+            width: targetRect.width,
+            height: targetRect.height,
+            pointerEvents: "none",
+          }}
+        />
+      )}
+    </>
+  );
+}