heartbeads 0.4.0

package/components/TutorialOverlay.tsx

@@ -0,0 +1,235 @@
+"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: "btn-collapse",
+    title: "Collapse / Expand",
+    description:
+      "Group all epic tasks into a single node, or expand them back out. Great for getting a high-level overview of your project when there are many tasks.",
+  },
+  {
+    target: "btn-clusters",
+    title: "Cluster Labels",
+    description:
+      "Toggle transparent labels that show project prefixes behind groups of related nodes. Helps you see which project each cluster belongs to at a glance.",
+  },
+  {
+    target: "btn-autofit",
+    title: "Auto-fit",
+    description:
+      "When enabled (green), the camera automatically re-centers and zooms to fit all nodes after every update. Turn it off to keep the camera fixed while you explore.",
+  },
+  {
+    target: "btn-pulse",
+    title: "Pulse",
+    description:
+      "Highlights the most recently active node with emerald ripples. Useful for spotting which task just changed status or was just created.",
+  },
+  {
+    target: "legend-stats",
+    title: "Project Stats",
+    description:
+      "A quick summary of your project: total issues, dependency count, and how many separate projects are tracked in this graph.",
+  },
+  {
+    target: "legend-color-mode",
+    title: "Color Mode Selector",
+    description:
+      "Switch what the node fill color represents. Status shows open/closed/blocked. Priority shows urgency. Owner, Assignee, and Prefix color by person or project. The ring around each node always shows which project it belongs to.",
+  },
+  {
+    target: "legend-items",
+    title: "Legend",
+    description:
+      "Shows what each color means for the currently selected color mode. The colored dots match the node fills in the graph above.",
+  },
+  {
+    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, collapsing epics, or focusing on an epic to isolate its subgraph.",
+    padding: 0,
+  },
+  {
+    target: "nav-replay",
+    title: "Replay",
+    description:
+      "Step through your project\u2019s history one event at a time. Watch issues appear and change status as they were created. Use the scrubber to jump to any point in time.",
+  },
+  {
+    target: "nav-comments",
+    title: "Comments",
+    description:
+      "Opens a sidebar showing all conversations across your beads. See who said what, reply to threads, and like comments \u2014 all powered by the AT Protocol.",
+  },
+  {
+    target: "nav-activity",
+    title: "Activity",
+    description:
+      "A real-time feed of changes filtered to only your local issues. See when tasks are created, status changes, priorities shift, and new dependencies are added.",
+  },
+  {
+    target: "nav-learn",
+    title: "Learn",
+    description:
+      "Opens the help panel with keyboard shortcuts, feature documentation, and this interactive tutorial. Click it anytime to come 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",
+          }}
+        />
+      )}
+    </>
+  );
+}

package/hooks/useBeadsComments.ts

@@ -0,0 +1,81 @@
+"use client";
+
+import { useEffect, useState, useCallback, useRef } from "react";
+import { fetchBeadsComments } from "@/lib/comments";
+import type { FetchCommentsResult } from "@/lib/comments";
+
+// Re-export types so existing imports from this module continue to work
+export type { BeadsComment, BeadsLike } from "@/lib/comments";
+
+export interface UseBeadsCommentsResult {
+  /** Map from node ID -> threaded comment trees (root comments with nested replies) */
+  commentsByNode: Map<string, BeadsComment[]>;
+  /** Map from node ID -> total comment count (including replies) */
+  commentedNodeIds: Map<string, number>;
+  /** Flat list of ALL comments (including replies), newest-first, for the All Comments panel */
+  allComments: BeadsComment[];
+  isLoading: boolean;
+  error: string | null;
+  refetch: () => Promise<void>;
+}
+
+// Need to import the concrete type for state usage
+import type { BeadsComment } from "@/lib/comments";
+
+export function useBeadsComments(): UseBeadsCommentsResult {
+  const [commentsByNode, setCommentsByNode] = useState<
+    Map<string, BeadsComment[]>
+  >(new Map());
+  const [commentedNodeIds, setCommentedNodeIds] = useState<
+    Map<string, number>
+  >(new Map());
+  const [allComments, setAllComments] = useState<BeadsComment[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const cancelledRef = useRef(false);
+
+  const fetchAndProcess = useCallback(async () => {
+    try {
+      setIsLoading(true);
+      setError(null);
+
+      const result: FetchCommentsResult = await fetchBeadsComments();
+
+      // Update state (only if not cancelled)
+      if (!cancelledRef.current) {
+        setCommentsByNode(result.commentsByNode);
+        setCommentedNodeIds(result.commentedNodeIds);
+        setAllComments(result.allComments);
+      }
+    } catch (err) {
+      if (!cancelledRef.current) {
+        const message =
+          err instanceof Error ? err.message : "Failed to fetch comments";
+        console.error("Failed to fetch beads comments:", err);
+        setError(message);
+      }
+    } finally {
+      if (!cancelledRef.current) {
+        setIsLoading(false);
+      }
+    }
+  }, []);
+
+  // Fetch on mount
+  useEffect(() => {
+    cancelledRef.current = false;
+    fetchAndProcess();
+    return () => {
+      cancelledRef.current = true;
+    };
+  }, [fetchAndProcess]);
+
+  return {
+    commentsByNode,
+    commentedNodeIds,
+    allComments,
+    isLoading,
+    error,
+    refetch: fetchAndProcess,
+  };
+}

package/hooks/useIsMobile.ts

@@ -0,0 +1,19 @@
+"use client";
+
+import { useState, useEffect } from "react";
+
+const MOBILE_BREAKPOINT = 768; // matches Tailwind md:
+
+export function useIsMobile(): boolean {
+  const [isMobile, setIsMobile] = useState(false);
+
+  useEffect(() => {
+    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT}px)`);
+    setIsMobile(mql.matches);
+    const handler = (e: MediaQueryListEvent) => setIsMobile(e.matches);
+    mql.addEventListener("change", handler);
+    return () => mql.removeEventListener("change", handler);
+  }, []);
+
+  return isMobile;
+}

package/lib/activity.ts

@@ -0,0 +1,377 @@
+/**
+ * Activity feed: unified event type and builders for historical + real-time events.
+ *
+ * Data sources:
+ * 1. Issue JSONL timestamps (created_at, closed_at, updated_at)
+ * 2. Dependency timestamps (link created_at)
+ * 3. ATProto comments, claims, likes (from useBeadsComments)
+ * 4. Real-time SSE diffs (BeadsDiff from diffBeadsData)
+ */
+
+import type { GraphNode, GraphLink } from "./types";
+import type { BeadsDiff, NodeChange } from "./diff-beads";
+import type { BeadsComment } from "@/lib/comments";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type ActivityEventType =
+  | "node-created"
+  | "node-closed"
+  | "node-status-changed"
+  | "node-priority-changed"
+  | "node-title-changed"
+  | "node-owner-changed"
+  | "link-added"
+  | "link-removed"
+  | "comment-added"
+  | "reply-added"
+  | "task-claimed"
+  | "task-unclaimed"
+  | "like-added";
+
+export interface ActivityActor {
+  handle: string;
+  avatar?: string;
+  did?: string;
+}
+
+export interface ActivityEvent {
+  /** Unique key for React rendering and deduplication: `${type}:${nodeId}:${time}` */
+  id: string;
+  type: ActivityEventType;
+  /** Unix milliseconds, for sorting */
+  time: number;
+  /** Which issue this event relates to */
+  nodeId: string;
+  /** Issue title for display (may be undefined for deleted nodes) */
+  nodeTitle?: string;
+  /** Who performed the action (for comments, claims, likes) */
+  actor?: ActivityActor;
+  /** Human-readable detail: e.g. "open -> in_progress", comment text preview, link target */
+  detail?: string;
+  /** Extra structured context */
+  meta?: Record<string, string>;
+}
+
+/** Filter category for the UI */
+export type ActivityFilterCategory =
+  | "issues"
+  | "deps"
+  | "comments"
+  | "claims"
+  | "likes";
+
+/** Map event types to filter categories */
+export function getEventCategory(type: ActivityEventType): ActivityFilterCategory {
+  switch (type) {
+    case "node-created":
+    case "node-closed":
+    case "node-status-changed":
+    case "node-priority-changed":
+    case "node-title-changed":
+    case "node-owner-changed":
+      return "issues";
+    case "link-added":
+    case "link-removed":
+      return "deps";
+    case "comment-added":
+    case "reply-added":
+      return "comments";
+    case "task-claimed":
+    case "task-unclaimed":
+      return "claims";
+    case "like-added":
+      return "likes";
+  }
+}
+
+// ============================================================================
+// Historical feed builder
+// ============================================================================
+
+/**
+ * Build the full historical activity feed from existing data.
+ * Called once on load and when allComments changes.
+ */
+export function buildHistoricalFeed(
+  nodes: GraphNode[],
+  links: GraphLink[],
+  allComments: BeadsComment[] | null
+): ActivityEvent[] {
+  const events: ActivityEvent[] = [];
+  const seen = new Set<string>();
+
+  function add(event: ActivityEvent) {
+    if (seen.has(event.id)) return;
+    seen.add(event.id);
+    events.push(event);
+  }
+
+  // --- Issue lifecycle events ---
+  for (const node of nodes) {
+    // Created
+    if (node.createdAt) {
+      const time = new Date(node.createdAt).getTime();
+      if (!isNaN(time)) {
+        add({
+          id: `node-created:${node.id}:${time}`,
+          type: "node-created",
+          time,
+          nodeId: node.id,
+          nodeTitle: node.title,
+          detail: node.issueType,
+          meta: { issueType: node.issueType, prefix: node.prefix },
+        });
+      }
+    }
+
+    // Closed
+    if (node.closedAt) {
+      const time = new Date(node.closedAt).getTime();
+      if (!isNaN(time)) {
+        add({
+          id: `node-closed:${node.id}:${time}`,
+          type: "node-closed",
+          time,
+          nodeId: node.id,
+          nodeTitle: node.title,
+          detail: node.closeReason || "Closed",
+          meta: { prefix: node.prefix },
+        });
+      }
+    }
+  }
+
+  // --- Dependency events ---
+  for (const link of links) {
+    if (link.createdAt) {
+      const time = new Date(link.createdAt).getTime();
+      if (!isNaN(time)) {
+        const src = typeof link.source === "object" ? (link.source as { id: string }).id : link.source;
+        const tgt = typeof link.target === "object" ? (link.target as { id: string }).id : link.target;
+        add({
+          id: `link-added:${src}->${tgt}:${time}`,
+          type: "link-added",
+          time,
+          nodeId: src,
+          detail: `${link.type} ${tgt}`,
+          meta: { linkType: link.type, target: tgt },
+        });
+      }
+    }
+  }
+
+  // --- Comment, claim, and like events ---
+  if (allComments) {
+    for (const comment of allComments) {
+      const time = new Date(comment.createdAt).getTime();
+      if (isNaN(time)) continue;
+
+      const actor: ActivityActor = {
+        handle: comment.handle,
+        avatar: comment.avatar,
+        did: comment.did,
+      };
+
+      const isClaim =
+        comment.text.startsWith("@") &&
+        comment.text.trim().indexOf(" ") === -1;
+
+      if (isClaim) {
+        add({
+          id: `task-claimed:${comment.nodeId}:${time}`,
+          type: "task-claimed",
+          time,
+          nodeId: comment.nodeId,
+          actor,
+          detail: comment.text,
+        });
+      } else if (comment.replyTo) {
+        add({
+          id: `reply-added:${comment.nodeId}:${comment.rkey}`,
+          type: "reply-added",
+          time,
+          nodeId: comment.nodeId,
+          actor,
+          detail:
+            comment.text.length > 80
+              ? comment.text.slice(0, 80) + "..."
+              : comment.text,
+        });
+      } else {
+        add({
+          id: `comment-added:${comment.nodeId}:${comment.rkey}`,
+          type: "comment-added",
+          time,
+          nodeId: comment.nodeId,
+          actor,
+          detail:
+            comment.text.length > 80
+              ? comment.text.slice(0, 80) + "..."
+              : comment.text,
+        });
+      }
+
+      // Likes on this comment
+      for (const like of comment.likes) {
+        const likeTime = new Date(like.createdAt).getTime();
+        if (isNaN(likeTime)) continue;
+        add({
+          id: `like-added:${comment.nodeId}:${like.rkey}`,
+          type: "like-added",
+          time: likeTime,
+          nodeId: comment.nodeId,
+          actor: {
+            handle: like.handle,
+            avatar: like.avatar,
+            did: like.did,
+          },
+          detail: `Liked comment by ${comment.handle}`,
+        });
+      }
+    }
+  }
+
+  // Sort newest-first
+  events.sort((a, b) => b.time - a.time);
+  return events;
+}
+
+// ============================================================================
+// Real-time diff -> events converter
+// ============================================================================
+
+/**
+ * Convert a BeadsDiff into ActivityEvent items.
+ * Called on each SSE message after diffBeadsData().
+ */
+export function diffToActivityEvents(
+  diff: BeadsDiff,
+  nodes: GraphNode[]
+): ActivityEvent[] {
+  const events: ActivityEvent[] = [];
+  const now = Date.now();
+  const nodeMap = new Map(nodes.map((n) => [n.id, n]));
+
+  // Added nodes
+  for (const id of diff.addedNodeIds) {
+    const node = nodeMap.get(id);
+    events.push({
+      id: `node-created:${id}:${now}`,
+      type: "node-created",
+      time: now,
+      nodeId: id,
+      nodeTitle: node?.title,
+      detail: node?.issueType || "task",
+      meta: node ? { issueType: node.issueType, prefix: node.prefix } : undefined,
+    });
+  }
+
+  // Removed nodes
+  for (const id of diff.removedNodeIds) {
+    events.push({
+      id: `node-closed:${id}:${now}`,
+      type: "node-closed",
+      time: now,
+      nodeId: id,
+      detail: "Removed",
+    });
+  }
+
+  // Changed nodes
+  for (const [id, changes] of diff.changedNodes) {
+    const node = nodeMap.get(id);
+    for (const change of changes) {
+      let type: ActivityEventType;
+      switch (change.field) {
+        case "status":
+          type = "node-status-changed";
+          break;
+        case "priority":
+          type = "node-priority-changed";
+          break;
+        case "title":
+          type = "node-title-changed";
+          break;
+        case "owner":
+          type = "node-owner-changed";
+          break;
+        default:
+          type = "node-status-changed"; // fallback
+      }
+      events.push({
+        id: `${type}:${id}:${now}:${change.field}`,
+        type,
+        time: now,
+        nodeId: id,
+        nodeTitle: node?.title,
+        detail: `${change.from} \u2192 ${change.to}`,
+        meta: { field: change.field, from: change.from, to: change.to },
+      });
+    }
+  }
+
+  // Added links
+  for (const key of diff.addedLinkKeys) {
+    // key format: "source->target:type"
+    const match = key.match(/^(.+)->(.+):(.+)$/);
+    if (match) {
+      const [, src, tgt, linkType] = match;
+      events.push({
+        id: `link-added:${key}:${now}`,
+        type: "link-added",
+        time: now,
+        nodeId: src,
+        detail: `${linkType} ${tgt}`,
+        meta: { linkType, target: tgt },
+      });
+    }
+  }
+
+  // Removed links
+  for (const key of diff.removedLinkKeys) {
+    const match = key.match(/^(.+)->(.+):(.+)$/);
+    if (match) {
+      const [, src, tgt, linkType] = match;
+      events.push({
+        id: `link-removed:${key}:${now}`,
+        type: "link-removed",
+        time: now,
+        nodeId: src,
+        detail: `${linkType} ${tgt}`,
+        meta: { linkType, target: tgt },
+      });
+    }
+  }
+
+  return events;
+}
+
+// ============================================================================
+// Feed management helpers
+// ============================================================================
+
+/** Maximum events to keep in the feed */
+export const MAX_FEED_SIZE = 200;
+
+/**
+ * Merge new events into an existing feed, deduplicating by event ID.
+ * Returns a new array sorted newest-first, capped at MAX_FEED_SIZE.
+ */
+export function mergeFeedEvents(
+  existing: ActivityEvent[],
+  incoming: ActivityEvent[]
+): ActivityEvent[] {
+  const seen = new Set(existing.map((e) => e.id));
+  const merged = [...existing];
+  for (const event of incoming) {
+    if (!seen.has(event.id)) {
+      seen.add(event.id);
+      merged.push(event);
+    }
+  }
+  merged.sort((a, b) => b.time - a.time);
+  return merged.slice(0, MAX_FEED_SIZE);
+}