feat(analytics): enhance Plausible tracking with journey context (#3169)

## Summary

- **User journey tracking**: Added `page` property to `copy_code` and
`download_image` events to distinguish where users perform actions
(`home`, `spec_overview`, `spec_detail`)
- **New events**: `toggle_grid_size` (view preference), `filter_remove`
(filter removal tracking)
- **Bug fix**: Added missing `spec` property to SpecTabs `copy_code`
event
- **Faster tracking**: Reduced debounce times for better event capture
  - `pageview`: 300ms → 150ms
  - `search_no_results`: 500ms → 200ms
- **Documentation**: Comprehensive Plausible setup guide with custom
properties list

## Changes

| File | Change |
|------|--------|
| `useAnalytics.ts` | Reduced pageview debounce |
| `FilterBar.tsx` | Added `toggle_grid_size`, reduced search debounce |
| `ImageCard.tsx` | Added `page: 'home'` to copy_code |
| `SpecPage.tsx` | Added `page` to copy_code and download_image |
| `SpecTabs.tsx` | Added `spec` and `page` to copy_code |
| `useFilterState.ts` | Added `filter_remove` event |
| `docs/architecture/plausible.md` | Full documentation with Plausible
dashboard setup |

## Plausible Dashboard Setup Required

After merge, register these **custom properties** in Plausible:

```
spec, library, method, page, category, value, query, destination, tab, size
```

## Test plan

- [ ] Verify copy_code events include `page` property in different
contexts
- [ ] Verify toggle_grid_size fires on view toggle
- [ ] Verify filter_remove fires on filter removal
- [ ] Check Plausible dashboard receives events correctly

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: MarkusNeusinger

app/src/components/FilterBar.tsx

@@ -221,7 +221,7 @@ export function FilterBar({
       const timer = setTimeout(() => {
         onTrackEvent('search_no_results', { query });
         lastTrackedQueryRef.current = query;
-      }, 500);
+      }, 200);
       return () => clearTimeout(timer);
     }
   }, [searchQuery, searchResults.length, onTrackEvent]);
@@ -378,7 +378,11 @@ export function FilterBar({
             {/* Grid size toggle */}
             <Tooltip title={imageSize === 'normal' ? 'compact view' : 'normal view'}>
               <Box
-                onClick={() => onImageSizeChange(imageSize === 'normal' ? 'compact' : 'normal')}
+                onClick={() => {
+                  const newSize = imageSize === 'normal' ? 'compact' : 'normal';
+                  onImageSizeChange(newSize);
+                  onTrackEvent('toggle_grid_size', { size: newSize });
+                }}
                 sx={{
                   display: 'flex',
                   alignItems: 'center',
@@ -588,7 +592,11 @@ export function FilterBar({
             {/* Grid size toggle */}
             <Tooltip title={imageSize === 'normal' ? 'compact view' : 'normal view'}>
               <Box
-                onClick={() => onImageSizeChange(imageSize === 'normal' ? 'compact' : 'normal')}
+                onClick={() => {
+                  const newSize = imageSize === 'normal' ? 'compact' : 'normal';
+                  onImageSizeChange(newSize);
+                  onTrackEvent('toggle_grid_size', { size: newSize });
+                }}
                 sx={{
                   display: 'flex',
                   alignItems: 'center',

app/src/components/ImageCard.tsx

@@ -89,7 +89,7 @@ export const ImageCard = memo(function ImageCard({
       if (code) {
         await navigator.clipboard.writeText(code);
         setCopyState('copied');
-        onTrackEvent?.('copy_code', { spec: image.spec_id, library: image.library, method: 'card' });
+        onTrackEvent?.('copy_code', { spec: image.spec_id, library: image.library, method: 'card', page: 'home' });
         setTimeout(() => setCopyState('idle'), 2000);
       } else {
         setCopyState('idle');

app/src/components/SpecTabs.tsx

@@ -164,7 +164,7 @@ export function SpecTabs({
     try {
       await navigator.clipboard.writeText(code);
       setCopied(true);
-      onTrackEvent?.('copy_code', { library: libraryId, method: 'tab' });
+      onTrackEvent?.('copy_code', { spec: specId, library: libraryId, method: 'tab', page: 'spec_detail' });
       setTimeout(() => setCopied(false), 2000);
     } catch (err) {
       console.error('Copy failed:', err);

app/src/hooks/useAnalytics.ts

@@ -64,7 +64,7 @@ export function useAnalytics() {
     [isProduction]
   );
 
-  const trackPageview = useMemo(() => debounce(sendPageview, 300), [sendPageview]);
+  const trackPageview = useMemo(() => debounce(sendPageview, 150), [sendPageview]);
 
   const trackEvent = useCallback(
     (name: string, props?: EventProps) => {

app/src/hooks/useFilterState.ts

@@ -210,24 +210,32 @@ export function useFilterState({
 
   // Remove a filter value from a specific group
   const handleRemoveFilter = useCallback((groupIndex: number, value: string) => {
+    const group = activeFiltersRef.current[groupIndex];
+    if (group) {
+      onTrackEvent('filter_remove', { category: group.category, value });
+    }
     setActiveFilters((prev) => {
       const newFilters = [...prev];
-      const group = newFilters[groupIndex];
-      if (!group) return prev;
+      const grp = newFilters[groupIndex];
+      if (!grp) return prev;
 
-      const updatedValues = group.values.filter((v) => v !== value);
+      const updatedValues = grp.values.filter((v) => v !== value);
       if (updatedValues.length === 0) {
         return newFilters.filter((_, i) => i !== groupIndex);
       }
-      newFilters[groupIndex] = { ...group, values: updatedValues };
+      newFilters[groupIndex] = { ...grp, values: updatedValues };
       return newFilters;
     });
-  }, []);
+  }, [onTrackEvent]);
 
   // Remove entire group by index
   const handleRemoveGroup = useCallback((groupIndex: number) => {
+    const group = activeFiltersRef.current[groupIndex];
+    if (group) {
+      onTrackEvent('filter_remove', { category: group.category, value: group.values.join(',') });
+    }
     setActiveFilters((prev) => prev.filter((_, i) => i !== groupIndex));
-  }, []);
+  }, [onTrackEvent]);
 
   // Random filter - replaces last filter slot (or adds first one)
   const handleRandom = useCallback(

app/src/pages/SpecPage.tsx

@@ -156,9 +156,9 @@ export function SpecPage() {
       link.href = impl.preview_url;
       link.download = `${specId}-${impl.library_id}.png`;
       link.click();
-      trackEvent('download_image', { spec: specId, library: impl.library_id });
+      trackEvent('download_image', { spec: specId, library: impl.library_id, page: isOverviewMode ? 'spec_overview' : 'spec_detail' });
     },
-    [specId, trackEvent]
+    [specId, trackEvent, isOverviewMode]
   );
 
   // Handle copy code (works for both overview and detail mode)
@@ -168,13 +168,13 @@ export function SpecPage() {
       try {
         await navigator.clipboard.writeText(impl.code);
         setCodeCopied(impl.library_id);
-        trackEvent('copy_code', { spec: specId, library: impl.library_id, method: 'image' });
+        trackEvent('copy_code', { spec: specId, library: impl.library_id, method: 'image', page: isOverviewMode ? 'spec_overview' : 'spec_detail' });
         setTimeout(() => setCodeCopied(null), 2000);
       } catch (err) {
         console.error('Copy failed:', err);
       }
     },
-    [specId, trackEvent]
+    [specId, trackEvent, isOverviewMode]
   );
 
   // Track page view