home/hey-search
2
0
Fork 0
mirror of https://github.com/wahyd4/hey-search.git synced 2026-08-08 21:05:14 +10:00
Code Issues Packages Projects Releases Wiki Activity
Files
0adad147f5ae8e06450635ea19314ce49b2d4fcb
hey-search/FEATURES.md
T
junvandCopilot b36d3e53b5 feat: accessibility overhaul, agent-friendly API, standardized errors 
P0 fixes:
- Image result cards are now real <a> links (open-in-new-tab, Cmd-click, copy-link)
- aria-label on all icon-only buttons (settings, clear, close, nav, toggles, delete)
- Search input semantics: label, name=q, type=search, combobox ARIA pattern
- Visible focus-visible ring on all interactive elements, removed bare outline-none

P1 fixes:
- Skip to main content link for keyboard navigation
- Proper heading hierarchy (h1/h2) and landmark elements (nav, main, aside)
- aria-live regions for loading/results/error announcements
- Custom favicon SVG (eliminates 404 console errors)
- Dialog/modal semantics with role=dialog and aria-modal

P2 API improvements:
- result_id, rank, engine on every result; timestamp, total_results, has_next on response
- Standardized APIError model (code/message/details/retry_hint) on all error responses
- X-Response-Time-Ms and rate-limit headers on all responses
- curl examples and sample JSON in OpenAPI docs for every endpoint
- Global exception handler returns consistent error JSON
- engines parameter in URL for reproducible sessions

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-02-23 17:06:09 +11:00

4.3 KiB
Raw Blame History

Features

Search

  • Web search — aggregates results from Brave, DuckDuckGo, Google, and Bing concurrently
  • Image search — Pinterest-style masonry layout respecting natural image aspect ratios, with lightbox viewer and keyboard navigation (←/→ to browse, Escape to close)
  • Image size filter — filter images by size (Large, Medium, Small) — applied server-side across all engines
  • Autocomplete — live search suggestions as you type (cascades Google → DuckDuckGo → Brave)
  • Pagination — navigate through result pages; URL reflects current state (?q=...&page=2)
  • URL deduplication — duplicate results from multiple engines are merged automatically
  • Domain exclusion — exclude specific websites from search results; settings persist in SQLite
  • Search stats — per-engine result counts, status indicators (ok/error/timeout), collapsible sidebar

Search Engines

  • Google — direct scraping via SearXNG's async progressive response API (asearch=arc); CAPTCHA detection
  • Bing — direct scraping with SearXNG-style cookies and base64 URL decoding; automatic Yahoo fallback on CAPTCHA
  • DuckDuckGo — HTML Lite scraping for web, API for images
  • Brave — Brave Search API for web and images

REST API

  • Full REST API for search, autocomplete, and engine management
  • OpenAPI specification with interactive docs via Swagger UI (/docs) and Redoc (/redoc)

Engine Management

  • 4 built-in engines: Brave, DuckDuckGo, Google, Bing
  • Enable or disable engines via the UI or API at runtime
  • Each engine supports both web and image search categories
  • Google and Bing include automatic fallback mechanisms for resilience

Reliability

  • Retry mechanism — failed upstream requests are retried with exponential backoff (via tenacity)
  • Error reporting — when an upstream engine fails or times out, the UI shows a toast notification identifying which engine had issues
  • Graceful degradation — partial failures don't block results from other engines

UI / UX

  • Mobile-first responsive design built with React, Tailwind CSS, and shadcn theming
  • Clean search home page with branded gradient header
  • Web results show favicons, engine badges, and content snippets
  • Image results displayed in a masonry grid with hover previews and a full lightbox with arrow-key navigation
  • Visited link colors — clicked links turn purple to distinguish from unvisited results
  • Engine settings modal with toggle switches
  • Excluded domains management modal with add/remove UI
  • Unified settings modal — single Settings button opens a tabbed modal (Engines, Excluded Sites)
  • Keyboard navigation for autocomplete suggestions (↑↓ arrows, Enter, Escape)
  • Footer with link to interactive API documentation (Swagger UI)

Accessibility

  • Skip to main content link for keyboard users
  • Image cards are real <a> links (Cmd/Ctrl-click, right-click, open-in-new-tab)
  • aria-label on all icon-only buttons and interactive elements
  • Search input with <label>, name, type="search", and ARIA combobox pattern
  • Visible focus-visible ring on all focusable elements
  • aria-live regions for loading/results/error announcements
  • Proper heading hierarchy (h1/h2) and landmark elements (<nav>, <main>, <aside>)
  • Dialog semantics on modals and lightbox (role="dialog", aria-modal)

REST API

  • Full REST API for search, autocomplete, and engine management
  • Every result includes result_id, rank, engine, and timestamp for agent integration
  • has_next and total_results fields for cursor-aware pagination
  • Standardized error schema (code/message/details/retry_hint) on all error responses
  • X-Response-Time-Ms and rate-limit headers on all responses
  • Copy-paste curl examples in OpenAPI docs for every endpoint
  • OpenAPI specification with interactive docs via Swagger UI (/docs) and Redoc (/redoc)

Deployment

  • Docker — multi-stage Dockerfile: Node.js frontend build → Python production image
  • Backend uses uv for fast, reproducible dependency management
Reference in New Issue View Git Blame Copy Permalink