πΈ Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.
Update .gitignore, enhance CLAUDE.md documentation, and refactor useOpenLayersTimelineLayer hook
Bill Yang82ff86165a24
diff --git a/.gitignore b/.gitignoreindex 92013ab5a..8c4e94ba6 100644--- a/.gitignore+++ b/.gitignore@@ -49,4 +49,6 @@ coverage/.agents/-.deepsec/\ No newline at end of file+.deepsec/++.github/\ No newline at end of filediff --git a/.impeccable/design.json b/.impeccable/design.jsonnew file mode 100644index 000000000..8b90ebce7--- /dev/null+++ b/.impeccable/design.json@@ -0,0 +1,133 @@+{+ "schemaVersion": 2,+ "generatedAt": "2026-06-02T00:00:00.000Z",+ "title": "Design System: Rybbit",+ "extensions": {+ "colorMeta": {+ "background": { "role": "neutral", "displayName": "Canvas", "canonical": "hsl(0 0% 8%)", "tonalRamp": ["#0a0a0a", "#131313", "#1b1b1b", "#242424", "#303030", "#4a4a4a", "#808080", "#f7f7f7"] },+ "surface": { "role": "neutral", "displayName": "Surface", "canonical": "hsl(0 0% 10.5%)", "tonalRamp": ["#0a0a0a", "#131313", "#1b1b1b", "#242424", "#303030", "#4a4a4a", "#999999", "#f2f2f2"] },+ "foreground": { "role": "neutral", "displayName": "Primary Text", "canonical": "hsl(0 0% 98%)", "tonalRamp": ["#131313", "#303030", "#4a4a4a", "#808080", "#999999", "#cccccc", "#e6e6e6", "#fafafa"] },+ "muted-foreground": { "role": "neutral", "displayName": "Muted Text", "canonical": "hsl(0 0% 60%)", "tonalRamp": ["#303030", "#4a4a4a", "#5e5e5e", "#737373", "#808080", "#999999", "#b3b3b3", "#cccccc"] },+ "accent": { "role": "primary", "displayName": "Emerald Signal", "canonical": "hsl(160.1 84.1% 39.4%)", "tonalRamp": ["#022c22", "#064e3b", "#065f46", "#047857", "#059669", "#10b981", "#34d399", "#6ee7b7"] },+ "dataviz": { "role": "secondary", "displayName": "Periwinkle Data Line", "canonical": "hsl(230 100% 85%)", "tonalRamp": ["#1e2a66", "#33408c", "#4d5cb3", "#6677d9", "#8090ff", "#99aaff", "#b3bfff", "#ccd4ff"] },+ "destructive": { "role": "tertiary", "displayName": "Destructive Red", "canonical": "hsl(0 84.2% 60.2%)", "tonalRamp": ["#450a0a", "#7f1d1d", "#991b1b", "#b91c1c", "#dc2626", "#ef4444", "#f87171", "#fca5a5"] },+ "warning": { "role": "tertiary", "displayName": "Warning Yellow", "canonical": "hsl(45.4 93.4% 47.5%)", "tonalRamp": ["#422006", "#713f12", "#854d0e", "#a16207", "#ca8a04", "#eab308", "#facc15", "#fde047"] },+ "info": { "role": "tertiary", "displayName": "Info Blue", "canonical": "hsl(217.2 91.2% 59.8%)", "tonalRamp": ["#172554", "#1e3a8a", "#1e40af", "#1d4ed8", "#2563eb", "#3b82f6", "#60a5fa", "#93c5fd"] }+ },+ "typographyMeta": {+ "headline": { "displayName": "Headline", "purpose": "Large stat values and primary metric numbers; tabular figures." },+ "title": { "displayName": "Title", "purpose": "Card titles, section and panel headings." },+ "body": { "displayName": "Body", "purpose": "Dominant size: table cells, descriptions, most UI text." },+ "label": { "displayName": "Label", "purpose": "Badges, chips, captions, axis labels, metadata." }+ },+ "shadows": [],+ "motion": [+ { "name": "transition-colors", "value": "150ms ease", "purpose": "Default for button/badge/input color and border state changes." },+ { "name": "transition-all-card", "value": "300ms ease", "purpose": "Card hover border-color shift; the only depth motion." },+ { "name": "accordion", "value": "0.2s ease-out", "purpose": "Radix accordion open/close height." }+ ],+ "breakpoints": [+ { "name": "sm", "value": "640px" },+ { "name": "md", "value": "768px" },+ { "name": "lg", "value": "1024px" },+ { "name": "xl", "value": "1280px" },+ { "name": "2xl", "value": "1400px" }+ ]+ },+ "components": [+ {+ "name": "Accent Button",+ "kind": "button",+ "refersTo": "button-accent",+ "description": "Primary call to action / success. The one emerald button per view.",+ "html": "<button class=\"ds-btn-accent\">Save changes</button>",+ "css": ".ds-btn-accent { display: inline-flex; align-items: center; justify-content: center; gap: 8px; height: 36px; padding: 8px 12px; font-family: Inter, system-ui, sans-serif; font-size: 14px; font-weight: 500; color: #fafafa; background: #059669; border: 1px solid #047857; border-radius: 4.8px; cursor: pointer; transition: background-color 150ms ease, border-color 150ms ease; } .ds-btn-accent:hover { background: rgba(5,150,105,0.9); } .ds-btn-accent:focus-visible { outline: none; box-shadow: 0 0 0 1px #d4d4d4; }"+ },+ {+ "name": "Default Button",+ "kind": "button",+ "refersTo": "button-default",+ "description": "Neutral workhorse button: raised surface with a hairline border.",+ "html": "<button class=\"ds-btn-default\">Add filter</button>",+ "css": ".ds-btn-default { display: inline-flex; align-items: center; justify-content: center; gap: 8px; height: 36px; padding: 8px 12px; font-family: Inter, system-ui, sans-serif; font-size: 14px; font-weight: 500; color: #fafafa; background: #242424; border: 1px solid #3d3d3d; border-radius: 4.8px; cursor: pointer; transition: background-color 150ms ease, border-color 150ms ease; } .ds-btn-default:hover { background: rgba(48,48,48,0.9); border-color: #4a4a4a; } .ds-btn-default:focus-visible { outline: none; box-shadow: 0 0 0 1px #d4d4d4; }"+ },+ {+ "name": "Outline Button",+ "kind": "button",+ "refersTo": "button-outline",+ "description": "Secondary/tertiary action: transparent with muted text.",+ "html": "<button class=\"ds-btn-outline\">Cancel</button>",+ "css": ".ds-btn-outline { display: inline-flex; align-items: center; justify-content: center; gap: 8px; height: 36px; padding: 8px 12px; font-family: Inter, system-ui, sans-serif; font-size: 14px; font-weight: 500; color: #d4d4d4; background: transparent; border: 1px solid #4a4a4a; border-radius: 4.8px; cursor: pointer; transition: background-color 150ms ease, color 150ms ease, border-color 150ms ease; } .ds-btn-outline:hover { background: #1b1b1b; color: #fafafa; border-color: #5e5e5e; } .ds-btn-outline:focus-visible { outline: none; box-shadow: 0 0 0 1px #d4d4d4; }"+ },+ {+ "name": "Card",+ "kind": "card",+ "refersTo": "card",+ "description": "Flat surface one step off the canvas, hairline border, no resting shadow.",+ "html": "<div class=\"ds-card\"><div class=\"ds-card-title\">Unique visitors</div><div class=\"ds-card-metric\">12,480</div><div class=\"ds-card-desc\">Last 7 days</div></div>",+ "css": ".ds-card { background: #1b1b1b; color: #fafafa; border: 1px solid #242424; border-radius: 4.8px; padding: 16px; overflow: hidden; transition: border-color 300ms ease; } .ds-card:hover { border-color: #303030; } .ds-card-title { font-family: Inter, system-ui, sans-serif; font-size: 16px; font-weight: 600; line-height: 1; letter-spacing: -0.01em; } .ds-card-metric { font-family: Inter, system-ui, sans-serif; font-size: 30px; font-weight: 600; line-height: 1.1; letter-spacing: -0.01em; font-variant-numeric: tabular-nums; margin-top: 8px; } .ds-card-desc { font-family: Inter, system-ui, sans-serif; font-size: 14px; color: #999999; margin-top: 6px; }"+ },+ {+ "name": "Search Input",+ "kind": "input",+ "refersTo": "input",+ "description": "Transparent field, hairline border, leading search icon, neutral focus ring.",+ "html": "<div class=\"ds-input-wrap\"><svg class=\"ds-input-icon\" xmlns=\"http://www.w3.org/2000/svg\" width=\"16\" height=\"16\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><circle cx=\"11\" cy=\"11\" r=\"8\"></circle><path d=\"m21 21-4.3-4.3\"></path></svg><input class=\"ds-input\" type=\"text\" placeholder=\"Search pages\" /></div>",+ "css": ".ds-input-wrap { position: relative; display: inline-block; } .ds-input-icon { position: absolute; left: 12px; top: 50%; transform: translateY(-50%); color: #999999; pointer-events: none; } .ds-input { height: 36px; width: 100%; padding: 4px 12px 4px 36px; font-family: Inter, system-ui, sans-serif; font-size: 14px; color: #fafafa; background: transparent; border: 1px solid #303030; border-radius: 4.8px; transition: border-color 150ms ease; } .ds-input::placeholder { color: #999999; } .ds-input:focus-visible { outline: none; box-shadow: 0 0 0 1px #d4d4d4; }"+ },+ {+ "name": "Success Badge",+ "kind": "chip",+ "refersTo": "badge-success",+ "description": "Semantic tint badge: 20% hue fill with the lighter text shade, transparent border.",+ "html": "<span class=\"ds-badge-success\">Verified</span>",+ "css": ".ds-badge-success { display: inline-flex; align-items: center; padding: 2px 6px; font-family: Inter, system-ui, sans-serif; font-size: 12px; font-weight: 500; color: #34d399; background: rgba(16,185,129,0.20); border: 1px solid transparent; border-radius: 2.8px; }"+ },+ {+ "name": "Neutral Badge",+ "kind": "chip",+ "refersTo": "badge-default",+ "description": "Default grayscale chip for tags and metadata.",+ "html": "<span class=\"ds-badge\">Direct</span>",+ "css": ".ds-badge { display: inline-flex; align-items: center; padding: 2px 6px; font-family: Inter, system-ui, sans-serif; font-size: 12px; font-weight: 500; color: #e6e6e6; background: #242424; border: 1px solid #242424; border-radius: 2.8px; transition: background-color 150ms ease; } .ds-badge:hover { background: #303030; }"+ }+ ],+ "narrative": {+ "northStar": "The Instrument Panel",+ "overview": "Rybbit is a precise, legible cockpit for understanding a website. Every surface is flat; depth comes from tonal layering of a pure-grayscale ramp, not from shadows. The canvas recedes (near-black in the default dark theme), panels lift one notch, interactive chrome lifts one more, and hairline 1px borders draw the seams. Onto that calm gray instrument, two signals are painted with intent: a single emerald for action and success, and a single periwinkle for the data lines themselves. The data is the instrument; the chrome stays out of the way. The personality is friendly, precise, and trustworthy: approachable without being toy-like. Warmth lives at the edges, never on top of the numbers. Density is a feature here: this is a tool people open to answer a specific question, and the layout should put that answer in front of them in seconds with depth one layer down.",+ "keyCharacteristics": [+ "Dark-mode-default; a full light theme mirrors every token.",+ "Flat by default: depth via a 21-step grayscale ramp + 1px borders, never shadows.",+ "One accent (emerald) for action/success, one data hue (periwinkle) for charts.",+ "Tight geometry: 4.8px max radius, Inter throughout, compact 36px controls.",+ "Density with legibility: dense data, but body text stays β₯4.5:1 contrast."+ ],+ "rules": [+ { "name": "The Signal-Not-Decoration Rule", "body": "Emerald marks primary actions, success, and current selection only. It never tints a surface, never fills a background, never decorates. If emerald is on screen and nothing actionable or successful is being communicated, remove it.", "section": "colors" },+ { "name": "The Two-Voice Rule", "body": "The interface speaks in grayscale. Exactly two chromatic voices are allowed on top: emerald for action, periwinkle for data. State colors (red/yellow/blue) are whispers that appear only when state demands them.", "section": "colors" },+ { "name": "The Flat Rule", "body": "No box-shadow for resting elevation. Depth is the grayscale ramp plus 1px borders. If two surfaces need separating, change the neutral step or add a hairline border, not a shadow.", "section": "elevation" },+ { "name": "The Tonal-Depth Rule", "body": "Separation is achieved by moving one step on the neutral ramp or adding a 1px border, never by stacking shadows. Floating overlays (dropdowns, dialogs, popovers) may use minimal platform elevation, but in-page surfaces stay flat.", "section": "elevation" },+ { "name": "The One-Family Rule", "body": "Inter does every job: headings, body, labels, data. Do not introduce a second UI typeface. Hierarchy comes from weight (400/500/600) and size, never from a new face.", "section": "typography" },+ { "name": "The No-Shrinking-Headline Rule", "body": "Type uses a fixed rem scale, not fluid clamp(). Users view at a consistent DPI inside an app shell; a heading that shrinks in a sidebar looks worse, not better.", "section": "typography" }+ ],+ "dos": [+ "Do keep surfaces flat: convey depth with the neutral ramp (#141414 -> #1b1b1b -> #242424) and 1px borders.",+ "Do reserve emerald for action, success, and current selection (The Signal-Not-Decoration Rule).",+ "Do keep data viz in periwinkle (--dataviz) and the broader ramp; never use the data hue on chrome.",+ "Do use Inter at fixed rem sizes with weight contrast (400/500/600) for all hierarchy.",+ "Do keep radii tight (<=4.8px) and controls compact (36px default height).",+ "Do keep a visible focus-visible ring on every interactive element, and honor prefers-reduced-motion.",+ "Do mirror every token across dark and light themes; dark is the default."+ ],+ "donts": [+ "Don't ship the generic SaaS template: no purple gradients, no hero-metric template, no endless identical icon+heading+text card grids.",+ "Don't let the frog or friendly tone tip into over-playful / toy-like territory that undermines trust in the numbers.",+ "Don't recreate the cluttered GA4 maze or cold enterprise-BI heaviness: surface the likely answer first, depth one layer down.",+ "Don't add resting box-shadow for elevation (The Flat Rule).",+ "Don't use border-left/border-right > 1px as a colored accent stripe.",+ "Don't use gradient text (background-clip: text) or decorative glassmorphism.",+ "Don't introduce a second UI typeface or fluid clamp() headings.",+ "Don't tint surfaces or backgrounds with emerald, or paint chrome in the periwinkle data hue."+ ]+ }+}diff --git a/.impeccable/live/config.json b/.impeccable/live/config.jsonnew file mode 100644index 000000000..29b75a5cd--- /dev/null+++ b/.impeccable/live/config.json@@ -0,0 +1,6 @@+{+ "files": ["client/src/app/layout.tsx"],+ "insertBefore": "</body>",+ "commentSyntax": "jsx",+ "cspChecked": true+}diff --git a/CLAUDE.md b/CLAUDE.mdindex 5186f3a79..171a652a6 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -22,3 +22,9 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co- File organization: Related functionality in same directory- Dark mode is default theme- Never run any database migration scripts++## Design Context++- `PRODUCT.md` (repo root) β strategic design context: register (`product`), users, purpose, brand personality, anti-references, and design principles. Read it before frontend/design work.+- `DESIGN.md` (repo root) β visual system: color tokens, typography, components, layout. The source of truth for visual decisions.+- The `/impeccable` skill reads both files before any design task.diff --git a/DESIGN.md b/DESIGN.mdnew file mode 100644index 000000000..6cd79f981--- /dev/null+++ b/DESIGN.md@@ -0,0 +1,224 @@+---+name: Rybbit+description: Open-source, privacy-friendly web & product analytics. A flat, dark-mode-default instrument panel where the data is the interface.+colors:+ # Surfaces (dark mode is the default theme; light values noted in prose)+ background: "#141414" # hsl(0 0% 8%) β app canvas (dark)+ surface: "#1b1b1b" # hsl(0 0% 10.5%) β card / panel (neutral-900)+ surface-raised: "#242424" # hsl(0 0% 14%) β default button / elevated chrome (neutral-850)+ foreground: "#fafafa" # hsl(0 0% 98%) β primary text (dark)+ muted-foreground: "#999999" # hsl(0 0% 60%) β secondary text / descriptions+ border: "#1f1f1f" # hsl(0 0% 12%) β hairline dividers (dark)+ # Accent β emerald ramp carries primary action + success+ accent: "#10b981" # emerald-500+ accent-strong: "#059669" # emerald-600 (border / dark-mode fill)+ accent-deep: "#065f46" # emerald-800 (dark success fill)+ # Data visualization+ dataviz: "#b3bfff" # hsl(230 100% 85%) β primary chart series (periwinkle, dark)+ dataviz-2: "#c2caff" # hsl(230 100% 92%) β secondary chart series (dark)+ # Semantic state+ destructive: "#ef4444" # red-500+ warning: "#eab308" # yellow-500+ info: "#3b82f6" # blue-500+ success: "#10b981" # emerald-500+typography:+ headline:+ fontFamily: "Inter, system-ui, sans-serif"+ fontSize: "1.875rem"+ fontWeight: 600+ lineHeight: 1.1+ letterSpacing: "-0.01em"+ title:+ fontFamily: "Inter, system-ui, sans-serif"+ fontSize: "1rem"+ fontWeight: 600+ lineHeight: 1+ letterSpacing: "-0.01em"+ body:+ fontFamily: "Inter, system-ui, sans-serif"+ fontSize: "0.875rem"+ fontWeight: 400+ lineHeight: 1.4+ letterSpacing: "normal"+ label:+ fontFamily: "Inter, system-ui, sans-serif"+ fontSize: "0.75rem"+ fontWeight: 500+ lineHeight: 1.3+ letterSpacing: "normal"+rounded:+ sm: "0.8px" # calc(var(--radius) - 4px)+ md: "2.8px" # calc(var(--radius) - 2px)+ lg: "4.8px" # var(--radius) = 0.3rem+spacing:+ xs: "6px"+ sm: "8px"+ md: "16px"+ lg: "24px"+components:+ button-default:+ backgroundColor: "{colors.surface-raised}"+ textColor: "{colors.foreground}"+ rounded: "{rounded.lg}"+ padding: "8px 12px"+ height: "36px"+ button-accent:+ backgroundColor: "{colors.accent-strong}"+ textColor: "#fafafa"+ rounded: "{rounded.lg}"+ padding: "8px 12px"+ height: "36px"+ button-accent-hover:+ backgroundColor: "{colors.accent}"+ textColor: "#fafafa"+ button-outline:+ backgroundColor: "transparent"+ textColor: "{colors.muted-foreground}"+ rounded: "{rounded.lg}"+ padding: "8px 12px"+ height: "36px"+ card:+ backgroundColor: "{colors.surface}"+ textColor: "{colors.foreground}"+ rounded: "{rounded.lg}"+ padding: "16px"+ input:+ backgroundColor: "transparent"+ textColor: "{colors.foreground}"+ rounded: "{rounded.lg}"+ padding: "4px 12px"+ height: "36px"+ badge-success:+ backgroundColor: "rgba(16,185,129,0.20)"+ textColor: "#34d399"+ rounded: "{rounded.md}"+ padding: "2px 6px"+---++# Design System: Rybbit++## 1. Overview++**Creative North Star: "The Instrument Panel"**++Rybbit is a precise, legible cockpit for understanding a website. Every surface is flat; depth comes from tonal layering of a pure-grayscale ramp, not from shadows. The canvas recedes (near-black `#141414` in the default dark theme), panels lift one notch (`#1b1b1b`), interactive chrome lifts one more (`#242424`), and hairline 1px borders draw the seams. Onto that calm gray instrument, two signals are painted with intent: a single **emerald** for action and success, and a single **periwinkle** (`#b3bfff`) for the data lines themselves. The data is the instrument; the chrome stays out of the way.++The personality is friendly, precise, and trustworthy: approachable without being toy-like (PRODUCT.md). Warmth lives at the edges (the frog, an empty state, a small touch), never on top of the numbers. Density is a feature here, not a flaw: this is a tool people open to answer a specific question, and the layout should put that answer in front of them in seconds with depth one layer down. Radii are deliberately tight (`0.3rem` / 4.8px max), so the UI reads as engineered and exact rather than soft or playful.++This system explicitly rejects the **generic SaaS template** (purple gradients, the hero-metric template, endless identical icon+heading+text card grids), anything **over-playful or toy-like** that undermines trust in the data, the **cluttered GA4** maze, and **cold enterprise-BI** heaviness (PRODUCT.md anti-references). It should feel like Linear or a Vercel/Stripe dashboard: confident, quiet, fast.++**Key Characteristics:**+- Dark-mode-default; a full light theme mirrors every token.+- Flat by default: depth via a 21-step grayscale ramp + 1px borders, never shadows.+- One accent (emerald) for action/success, one data hue (periwinkle) for charts.+- Tight geometry: 4.8px max radius, Inter throughout, compact 36px controls.+- Density with legibility: dense data, but body text stays β₯4.5:1 contrast.++## 2. Colors++A pure-neutral grayscale chassis carrying exactly two chromatic signals; semantic state colors appear only on state.++### Primary+- **Emerald Signal** (`#10b981`, `--accent-500`; border `#059669`, `--accent-600`): The single brand accent. Primary buttons, success buttons, current selection, positive deltas, the `success` badge. In dark mode the fill deepens to `#059669`/`#065f46` so it sits calmly on near-black. This is the only color allowed to mean "act here" or "this went well."++### Secondary+- **Periwinkle Data Line** (`#b3bfff` dark / `#99aaff` light, `--dataviz`; second series `#c2caff` / `#b3bfff`, `--dataviz-2`): Reserved exclusively for data visualization (line/bar/area series, the activity globe). It is a *data* color, never a UI color: it must not appear on buttons, links, or chrome.++### Neutral+The workhorse. A 21-step pure-grayscale ramp (`--neutral-0` at 97% L through `--neutral-1000` at 4% L, chroma 0).+- **Canvas** (`#141414`, `--background` dark / `#f7f7f7` light): The app backdrop.+- **Surface** (`#1b1b1b`, `--neutral-900` / white light): Cards and panels, one step off the canvas.+- **Raised Surface** (`#242424`, `--neutral-850` / white): Default buttons and elevated chrome.+- **Primary Text** (`#fafafa`, `--foreground` dark / `#0a0a0a` light): Body and headings.+- **Muted Text** (`#999999`, `--neutral-400`/`--neutral-500`): Descriptions, secondary labels, placeholders. Verify β₯4.5:1 before going lighter.+- **Border** (`#1f1f1f`, `--border` dark / `#e6e6e6` light): Hairline seams and dividers, always 1px.++### Tertiary (semantic state only)+- **Destructive Red** (`#ef4444`, `--red-500`): Errors, delete actions, negative deltas.+- **Warning Yellow** (`#eab308`, `--yellow-500`): Warnings, caution thresholds.+- **Info Blue** (`#3b82f6`, `--blue-500`): Informational badges only (distinct from the periwinkle data hue).++A full Tailwind-style ramp (red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose) is defined in `globals.css` for chart palettes and category coloring. Outside data viz and state, do not reach into it.++### Named Rules+**The Signal-Not-Decoration Rule.** Emerald marks primary actions, success, and current selection only. It never tints a surface, never fills a background, never decorates. If emerald is on screen and nothing actionable or successful is being communicated, remove it.++**The Two-Voice Rule.** The interface speaks in grayscale. Exactly two chromatic voices are allowed on top: emerald for *action*, periwinkle for *data*. State colors (red/yellow/blue) are whispers that appear only when state demands them.++**The Flat Rule.** No `box-shadow` for resting elevation. Depth is the grayscale ramp plus 1px borders. If two surfaces need separating, change the neutral step or add a hairline border, not a shadow.++## 3. Typography++**Display / Body / Label Font:** Inter (with `system-ui, sans-serif` fallback), loaded via `next/font`.++**Character:** One family, carried by weight and size contrast, not by pairing. Inter is neutral, screen-legible at small sizes, and tabular-friendly for numbers, which is exactly right for a dense analytics tool. There is no display typeface; product UI does not need one.++### Hierarchy+- **Headline** (600, 1.875rem / 30px, line-height 1.1): Large stat values and primary metric numbers. Use tabular figures for aligned columns.+- **Title** (600, 1rem / 16px, `leading-none`, `tracking-tight`): Card titles, section headers, panel headings.+- **Body** (400, 0.875rem / 14px, line-height ~1.4): The dominant size. Table cells, descriptions, most UI text. Cap prose at 65β75ch; tables may run denser.+- **Label** (500, 0.75rem / 12px): Badges, chips, small captions, axis labels, secondary metadata.++### Named Rules+**The One-Family Rule.** Inter does every job: headings, body, labels, data. Do not introduce a second UI typeface. Hierarchy comes from weight (400/500/600) and size, never from a new face.++**The No-Shrinking-Headline Rule.** Type uses a fixed rem scale, not fluid `clamp()`. Users view at a consistent DPI inside an app shell; a heading that shrinks in a sidebar looks worse, not better.++## 4. Elevation++This system is **flat by default**. There is no resting shadow vocabulary; depth is conveyed entirely through the grayscale ramp (canvas β surface β raised surface) and 1px borders. Cards declare `transition-all duration-300` but carry no shadow at rest; the only motion-borne depth is a hairline border-color shift on hover. If a surface looks like a 2014 app, the shadow is the problem: remove it and step the neutral instead.++### Named Rules+**The Tonal-Depth Rule.** Separation is achieved by moving one step on the neutral ramp or adding a 1px border, never by stacking shadows. Overlays that genuinely float (dropdowns, dialogs, popovers via Radix) may use the platform's minimal elevation, but in-page surfaces stay flat.++## 5. Components++### Buttons+- **Shape:** `rounded-lg` (4.8px) for default/sm/lg; `rounded-md` (2.8px) for xs/icon. Height 36px default (`h-9`), 32px sm, 24px xs. `font-medium`, `transition-colors`.+- **Default:** Raised neutral surface with a 1px border (`#242424` fill, `#3d3d3d` border in dark; white fill, `#d9d9d9` border in light). Hover lightens the fill and border one step. This is the neutral workhorse button.+- **Accent / Success:** Emerald fill (`#059669` dark / `#10b981` light) with a deeper emerald border, white text. The primary call to action.+- **Destructive / Warning:** Red / yellow fills, used only for genuinely destructive or cautionary actions.+- **Outline / Ghost / Link:** Transparent surfaces with muted neutral text; hover fills with the faintest neutral step. For secondary and tertiary actions.+- **Focus:** `focus-visible:ring-1` in `--neutral-950` (light) / `--neutral-300` (dark). Always keep a visible focus ring.++### Cards / Containers+- **Corner Style:** `rounded-lg` (4.8px).+- **Background:** Surface step (`#1b1b1b` dark / white light), one notch off the canvas.+- **Border:** 1px hairline (`--neutral-850` dark / `--neutral-100` light). `overflow-hidden`.+- **Shadow Strategy:** None at rest (see Elevation). Hover may shift border color only.+- **Internal Padding:** 16px (`p-4`); header uses `space-y-1.5` (6px). Descriptions in muted text at 14px.+- **Loading:** Cards use an in-place `CardLoader` (ldrs Zoomies) tinted from the neutral ramp; prefer skeletons over a centered spinner for content.++### Inputs / Fields+- **Style:** Transparent background, 1px border (`--neutral-150` light / `--neutral-800` dark), `rounded-lg`, 36px tall (`h-9`), 14px text. Placeholder in muted neutral (meets 4.5:1).+- **Focus:** `focus-visible:ring-1` neutral; no border color change beyond the ring.+- **Error:** `aria-[invalid=true]` flips the border to red-500 (dark: red-400).+- **Search variant:** Leading 16px search icon in `--neutral-400`, `pl-9`.++### Badges / Chips+- **Shape:** `rounded-md` (2.8px), `px-1.5 py-0.5`, 12px `font-medium`.+- **Semantic variants:** success/destructive/warning/info render as a 20% tint of the hue with the 600 (light) / 400 (dark) text shade and a transparent border. Neutral default/secondary/outline/ghost use the grayscale ramp.++### Data Visualization (signature)+- Charts (Nivo bar/line/calendar, D3, Mapbox/OpenLayers globe) render series in periwinkle (`--dataviz`, `--dataviz-2`) by default, escalating to the full Tailwind ramp only when many categories must be distinguished. Axes, gridlines, and labels use the muted neutral steps so the data line stays dominant. Prefer hue+shape/position separation over hue-alone (PRODUCT.md a11y).++## 6. Do's and Don'ts++### Do:+- **Do** keep surfaces flat: convey depth with the neutral ramp (`#141414` β `#1b1b1b` β `#242424`) and 1px borders.+- **Do** reserve emerald for action, success, and current selection (The Signal-Not-Decoration Rule).+- **Do** keep data viz in periwinkle (`--dataviz`) and the broader ramp; never use the data hue on chrome.+- **Do** use Inter at fixed rem sizes with weight contrast (400/500/600) for all hierarchy.+- **Do** keep radii tight (β€4.8px) and controls compact (36px default height).+- **Do** keep a visible `focus-visible` ring on every interactive element, and honor `prefers-reduced-motion`.+- **Do** mirror every token across dark and light themes; dark is the default.++### Don't:+- **Don't** ship the **generic SaaS template**: no purple gradients, no hero-metric template (big number + tiny label + gradient accent), no endless identical icon+heading+text card grids.+- **Don't** let the frog or friendly tone tip into **over-playful / toy-like** territory that undermines trust in the numbers.+- **Don't** recreate the **cluttered GA4** maze or **cold enterprise-BI** heaviness: surface the likely answer first, depth one layer down.+- **Don't** add resting `box-shadow` for elevation (The Flat Rule); don't use shadows where a neutral step or border works.+- **Don't** use `border-left`/`border-right` > 1px as a colored accent stripe; use full hairline borders or a tint.+- **Don't** use gradient text (`background-clip: text`) or decorative glassmorphism.+- **Don't** introduce a second UI typeface or fluid `clamp()` headings.+- **Don't** tint surfaces or backgrounds with emerald, or paint chrome in the periwinkle data hue.diff --git a/PRODUCT.md b/PRODUCT.mdnew file mode 100644index 000000000..fc52d61e8--- /dev/null+++ b/PRODUCT.md@@ -0,0 +1,57 @@+# Product++## Register++product++> Primary surface is the authenticated analytics product (dashboards, session replay, settings). A marketing/landing surface also exists; treat individual marketing tasks as `brand` per-task, but the project default is `product`.++## Users++Rybbit serves people who run websites and products and want to understand their traffic without the weight or privacy cost of Google Analytics. Three audiences, in priority order:++- **Indie devs & self-hosters** β technical solo builders running their own site. Comfortable with config and SQL, deploy on their own VPS, value speed, control, and sane defaults.+- **Small teams & startups** β founders, marketers, and PMs checking growth, sharing dashboards, and collaborating inside organizations.+- **Agencies & consultants** β managing many client sites, leaning on public/shared dashboards and multi-site overviews.++Shared context: they open Rybbit to answer a specific question (what's trending, where traffic comes from, why a funnel drops off, what an error is) and want the answer in seconds, not after a configuration project. The job is "tell me what's happening on my site, accurately, without tracking my visitors."++## Product Purpose++Rybbit is an open-source, privacy-friendly, cookieless web and product analytics platform: the modern alternative to Google Analytics. It covers the full analytics surface (sessions, users, pageviews, bounce rate, funnels, journeys, retention, goals, custom events, session replay, error tracking, uptime, and 3-level location maps) while staying fast to set up and intuitive to read.++Success looks like: a user installs the script in minutes, lands on a dashboard that's immediately legible, and trusts the numbers. Depth is available (advanced filters across 15+ dimensions, custom SQL queries, replays) but never blocks the first answer. Privacy is a feature, not a compromise.++## Brand Personality++**Friendly, precise, trustworthy.** Approachable without being toy-like. Rybbit has personality (the frog mascot, a privacy-first conviction, plain-language copy) but the data is always the star. The voice is direct and unpretentious: it explains, it doesn't sell. Warmth comes from clarity and good defaults, not decoration. When in doubt, choose the option that makes the numbers easier to trust.++Emotional goal: relief and confidence. "This just makes sense" beats "this is impressive."++## Anti-references++- **Generic SaaS template.** No indistinct dashboard-kit look: no purple gradients, no hero-metric template (big number + tiny label + gradient accent), no endless identical icon+heading+text card grids. Rybbit should look like itself, not a Tailwind starter.+- **Over-playful / toy-like.** The frog and the friendly tone must never undermine trust in the data. No cartoonish UI, no whimsy that gets between the user and the numbers.+- **Cluttered like GA4** (the product it replaces). No overwhelming navigation, no metrics buried three clicks deep, no configuration required before any value appears.+- **Cold enterprise BI.** Not Tableau/Looker heaviness: no analyst-only jargon, no intimidating density-for-its-own-sake.++## Design Principles++1. **Answer first, depth on demand.** Every screen should surface the likely question's answer immediately; advanced filtering, SQL, and replays are one layer down, never a gate.+2. **Earned familiarity.** Use standard, trustworthy affordances (Linear/Vercel/Stripe-grade). The tool should disappear into the task; novelty must win a real UX argument before it ships.+3. **Trust through precision.** Accurate numbers, honest empty/loading/error states, consistent component vocabulary screen to screen. Craft is how we signal the data is reliable.+4. **Privacy is the point.** Reinforce the cookieless, privacy-friendly stance through the experience, not just the marketing.+5. **Personality at the edges.** Warmth and the frog live in moments (empty states, small touches), not on top of the data.++## Accessibility & Inclusion++No formal WCAG bar mandated; apply strong defaults as table stakes:++- Body text β₯4.5:1 contrast (watch muted-gray-on-tinted-surface in both light and dark themes; dark mode is default).+- Visible keyboard focus and full keyboard navigation on interactive components.+- Honor `prefers-reduced-motion` on every animation (crossfade or instant fallback).+- Prefer color-blind-distinguishable data viz (don't rely on hue alone to separate series).++## Visual System++Captured separately in DESIGN.md when generated. Quick orientation: dark-mode-default, HSL CSS variables (not OKLCH; identity-preserving), emerald accent ramp for primary actions/success, a periwinkle `--dataviz` blue for charts, grayscale-heavy neutral ramp, `--radius: 0.3rem`, Shadcn UI (New York) on Tailwind v4, Nivo + D3 + Mapbox for visualization.diff --git a/client/src/app/[site]/globe/2d/hooks/useOpenLayersTimelineLayer.ts b/client/src/app/[site]/globe/2d/hooks/useOpenLayersTimelineLayer.tsindex b4687e2f1..bb295d472 100644--- a/client/src/app/[site]/globe/2d/hooks/useOpenLayersTimelineLayer.ts+++ b/client/src/app/[site]/globe/2d/hooks/useOpenLayersTimelineLayer.ts@@ -40,15 +40,17 @@ export function useOpenLayersTimelineLayer({ mapInstanceRef, mapViewRef, mapViewconst overlaysMapRef = useRef<Map<string, OverlayData>>(new Map());const clusterLayerRef = useRef<VectorLayer<Cluster> | null>(null);const tooltipOverlayRef = useRef<Overlay | null>(null);- const [openTooltipSessionId, setOpenTooltipSessionId] = useState<string | null>(null);+ const openTooltipSessionIdRef = useRef<string | null>(null);+ const tooltipSessionRef = useRef<GetSessionsResponse[number] | null>(null);const [selectedSession, setSelectedSession] = useState<GetSessionsResponse[number] | null>(null);const currentZoomRef = useRef<number>(2);// Close tooltip when timeline time changesuseEffect(() => {- if (tooltipOverlayRef.current && openTooltipSessionId) {+ if (tooltipOverlayRef.current && openTooltipSessionIdRef.current) {tooltipOverlayRef.current.setPosition(undefined);- setOpenTooltipSessionId(null);+ openTooltipSessionIdRef.current = null;+ tooltipSessionRef.current = null;}}, [currentTime]);@@ -77,11 +79,29 @@ export function useOpenLayersTimelineLayer({ mapInstanceRef, mapViewRef, mapViewconst map = mapInstanceRef.current;if (!map) return;+ const handleTooltipClick = (event: MouseEvent) => {+ const target = event.target instanceof Element ? event.target : null;+ const button = target?.closest<HTMLButtonElement>(".view-session-btn");+ if (!button) return;++ event.stopPropagation();++ const session = tooltipSessionRef.current;+ if (!session) return;++ setSelectedSession(session);+ tooltipOverlayRef.current?.setPosition(undefined);+ openTooltipSessionIdRef.current = null;+ tooltipSessionRef.current = null;+ };+if (!tooltipOverlayRef.current) {const tooltipElement = document.createElement("div");tooltipElement.className = "ol-timeline-tooltip";tooltipElement.style.cssText = "position: absolute; z-index: 1000;";+ tooltipElement.addEventListener("click", handleTooltipClick);+const tooltip = new Overlay({element: tooltipElement,positioning: "top-left",@@ -95,6 +115,8 @@ export function useOpenLayersTimelineLayer({ mapInstanceRef, mapViewRef, mapViewreturn () => {if (tooltipOverlayRef.current) {+ const element = tooltipOverlayRef.current.getElement();+ element?.removeEventListener("click", handleTooltipClick);map.removeOverlay(tooltipOverlayRef.current);tooltipOverlayRef.current = null;}@@ -261,17 +283,13 @@ export function useOpenLayersTimelineLayer({ mapInstanceRef, mapViewRef, mapViewconst avatarSVG = generateAvatarSVG(session.user_id, 32);avatarContainer.innerHTML = avatarSVG;- // Track cleanup resources- let timeoutId: number | null = null;- let buttonHandler: ((e: Event) => void) | null = null;- let buttonElement: Element | null = null;-const handleAvatarClick = (e: MouseEvent) => {e.stopPropagation();- if (openTooltipSessionId === session.session_id && tooltipOverlayRef.current) {+ if (openTooltipSessionIdRef.current === session.session_id && tooltipOverlayRef.current) {tooltipOverlayRef.current.setPosition(undefined);- setOpenTooltipSessionId(null);+ openTooltipSessionIdRef.current = null;+ tooltipSessionRef.current = null;return;}@@ -279,23 +297,8 @@ export function useOpenLayersTimelineLayer({ mapInstanceRef, mapViewRef, mapViewconst html = buildTooltipHTML(session, session.lon, session.lat);tooltipOverlayRef.current.getElement()!.innerHTML = html;tooltipOverlayRef.current.setPosition(fromLonLat([session.lon, session.lat]));- setOpenTooltipSessionId(session.session_id);-- timeoutId = window.setTimeout(() => {- const button = document.querySelector(`[data-session-id="${session.session_id}"]`);- if (button) {- buttonHandler = (e: Event) => {- e.stopPropagation();- setSelectedSession(session);- if (tooltipOverlayRef.current) {- tooltipOverlayRef.current.setPosition(undefined);- setOpenTooltipSessionId(null);- }- };- buttonElement = button;- button.addEventListener("click", buttonHandler);- }- }, 0);+ openTooltipSessionIdRef.current = session.session_id;+ tooltipSessionRef.current = session;}};@@ -310,14 +313,8 @@ export function useOpenLayersTimelineLayer({ mapInstanceRef, mapViewRef, mapViewoverlay.setPosition(fromLonLat([session.lon, session.lat]));map.addOverlay(overlay);- // Cleanup function to remove all event listeners and clear timeouts+ // Cleanup function to remove marker event listenersconst cleanup = () => {- if (timeoutId !== null) {- clearTimeout(timeoutId);- }- if (buttonHandler && buttonElement) {- buttonElement.removeEventListener("click", buttonHandler);- }avatarContainer.removeEventListener("click", handleAvatarClick);};@@ -395,19 +392,15 @@ export function useOpenLayersTimelineLayer({ mapInstanceRef, mapViewRef, mapViewconst avatarSVG = generateAvatarSVG(session.user_id, 32);avatarContainer.innerHTML = avatarSVG;- // Track cleanup resources- let timeoutId: number | null = null;- let buttonHandler: ((e: Event) => void) | null = null;- let buttonElement: Element | null = null;-// Add click handler for tooltipconst handleAvatarClick = (e: MouseEvent) => {e.stopPropagation();// If clicking the same avatar that has the tooltip open, close it- if (openTooltipSessionId === session.session_id && tooltipOverlayRef.current) {+ if (openTooltipSessionIdRef.current === session.session_id && tooltipOverlayRef.current) {tooltipOverlayRef.current.setPosition(undefined);- setOpenTooltipSessionId(null);+ openTooltipSessionIdRef.current = null;+ tooltipSessionRef.current = null;return;}@@ -416,24 +409,8 @@ export function useOpenLayersTimelineLayer({ mapInstanceRef, mapViewRef, mapViewconst html = buildTooltipHTML(session, session.lon, session.lat);tooltipOverlayRef.current.getElement()!.innerHTML = html;tooltipOverlayRef.current.setPosition(fromLonLat([session.lon, session.lat]));- setOpenTooltipSessionId(session.session_id);-- // Add click handler to "View Details" button- timeoutId = window.setTimeout(() => {- const button = document.querySelector(`[data-session-id="${session.session_id}"]`);- if (button) {- buttonHandler = (e: Event) => {- e.stopPropagation();- setSelectedSession(session);- if (tooltipOverlayRef.current) {- tooltipOverlayRef.current.setPosition(undefined);- setOpenTooltipSessionId(null);- }- };- buttonElement = button;- button.addEventListener("click", buttonHandler);- }- }, 0);+ openTooltipSessionIdRef.current = session.session_id;+ tooltipSessionRef.current = session;}};@@ -448,14 +425,8 @@ export function useOpenLayersTimelineLayer({ mapInstanceRef, mapViewRef, mapViewoverlay.setPosition(fromLonLat([session.lon, session.lat]));map.addOverlay(overlay);- // Cleanup function to remove all event listeners and clear timeouts+ // Cleanup function to remove marker event listenersconst cleanup = () => {- if (timeoutId !== null) {- clearTimeout(timeoutId);- }- if (buttonHandler && buttonElement) {- buttonElement.removeEventListener("click", buttonHandler);- }avatarContainer.removeEventListener("click", handleAvatarClick);};@@ -503,9 +474,10 @@ export function useOpenLayersTimelineLayer({ mapInstanceRef, mapViewRef, mapViewhandleClusterClick(event);// Then close tooltip- if (tooltipOverlayRef.current && openTooltipSessionId) {+ if (tooltipOverlayRef.current && openTooltipSessionIdRef.current) {tooltipOverlayRef.current.setPosition(undefined);- setOpenTooltipSessionId(null);+ openTooltipSessionIdRef.current = null;+ tooltipSessionRef.current = null;}};@@ -530,7 +502,7 @@ export function useOpenLayersTimelineLayer({ mapInstanceRef, mapViewRef, mapViewclusterLayerRef.current = null;}};- }, [activeSessions, mapView, mapInstanceRef, mapViewRef, openTooltipSessionId]);+ }, [activeSessions, mapView, mapInstanceRef, mapViewRef]);return {selectedSession,diff --git a/server/src/api/analytics/runCustomQuery.ts b/server/src/api/analytics/runCustomQuery.tsindex 83b93024c..ab01f04ee 100644--- a/server/src/api/analytics/runCustomQuery.ts+++ b/server/src/api/analytics/runCustomQuery.ts@@ -80,6 +80,7 @@ export async function runCustomQuery(});} catch (error) {request.log.error(error, "Failed to run custom analytics query");- return reply.status(400).send({ error: "Failed to run query" });+ const message = error instanceof Error && error.message ? error.message : "Failed to run query";+ return reply.status(400).send({ error: message });}}