feat(extension): add tab bookmark badge indicator (#1745)

* feat: add tab bookmark count badge indicator

- implement getApiClient function to create and cache TRPC client
- add tab activation listener to check bookmark count
- display badge with count and appropriate color based on results
- handle errors by showing error indicator in badge

* feat: add show count badge setting to extension

- Add showCountBadge setting to settings schema and default values
- Implement toggle button in OptionsPage for count badge visibility
- Modify background script to respect showCountBadge setting
- Add logging for archive count check in background script

Closes #486

* feat(background): refactor tab badge update logic

- Extract badge setting logic into reusable `setBadge` function
- Create `getTabCount` function to fetch bookmark count and existence
- Implement `checkAndUpdateIcon` function to centralize icon update logic
- Add support for tab updates via `chrome.tabs.onUpdated` listener
- Improve error handling with consistent badge display

* feat(background): implement badge caching system

- Add badge cache initialization and periodic cleanup
- Implement cache get/set operations for badge status
- Update setBadge function to use cached values when available
- Modify badge display logic to check cache before making API calls

* feat(badgeCache): add debug logging for cache operations

- Add console logs to track cache initialization, purging, and operations
- Move debug log in checkAndUpdateIcon to better position

* feat: add badge refresh on bookmark creation and deletion

- implement message types for badge refresh communication
- update background script to handle REFRESH_BADGE messages
- modify SavePage to send message on successful bookmark creation
- modify BookmarkSavedPage to send message on successful deletion
- add clearBadgeStatusSWR utility function import and usage

* perf(badge-cache): decrease purge alarm interval

The badge cache purge alarm was previously set to run every 60
minutes. This change reduces the interval to 10 minutes to ensure
more frequent cache cleanup and better memory management.

* feat(background): clean up API client and badge cache on invalid settings

- add cleanupApiClient function to trpc utils
- modify checkSettingsState to handle async operations
- clear API client and badge status when settings are invalid
- update settings subscription to handle async operations

* feat: reset settings to include showCountBadge flag when logout

When deleting API key, ensure showCountBadge is also reset to false to
maintain consistent state in the options page configuration.

* refactor: use BOOKMARK_REFRESH_BADGE instead of separate created/deleted types

* perf(badgeCache): replace alarm-based purge with on-demand expiration check

- Remove periodic alarm system for cache purging
- Add lastPurgeTimestamp tracking for efficient cache maintenance
- Update manifest to remove unnecessary alarms permission
- Modify background script to use new on-demand purge mechanism
- Clean up related alarm listener and initialization code

* feat: Replace count badge button with toggle switch

- add new Switch component based on Radix UI
- update OptionsPage to use Switch for count badge setting

* feat: Add horizontal rule separator in options page

- Add `<hr />` element between sections for better visual separation
- Improve UI organization in the OptionsPage component

* feat(badgeCache): implement persistent last purge timestamp storage

- Replace in-memory timestamp with chrome.storage persistence
- Add getter/setter functions for last purge timestamp
- Update checkAndPurgeIfNeeded to use persistent storage

* refactor(badgeCache): Improve type safety and storage utilities

- Add BadgeCacheEntry and BadgeCacheStorage types
- Extract storage operations to dedicated utility functions
- Improve code organization and documentation
- Enhance type safety throughout badge cache operations

* feat(extension): add context menu options to clear cache

- introduce new context menu items for cache management
- add clear current site cache functionality
- add clear all cache functionality
- conditionally show cache menu items based on showCountBadge setting
- pass settings to context menu registration/removal functions

* feat(extension): add configurable badge cache expiration time

- introduce `badgeCacheExpireMs` setting with 1-hour default
- update settings schema and default values
- add input field in OptionsPage for cache time configuration
- modify badgeCache to use dynamic expiration time from settings
- improve cache logging for better debugging visibility

* Revert "feat: reset settings to include showCountBadge flag when logout"

This reverts commit cf071e9dd50f1a1ac0a8dd3b68a4359ecc30c783.

# Conflicts:
#	apps/browser-extension/src/OptionsPage.tsx

* refactor(extension): extract badge cache expiration constant

Extract DEFAULT_BADGE_CACHE_EXPIRE_MS constant to central location in
settings.ts and reuse it across badgeCache.ts and OptionsPage.tsx. Remove
duplicate constant definitions and ensure consistent default value usage.

* refactor(extension): standardize showCountBadge default via shared constant

- introduce DEFAULT_SHOW_COUNT_BADGE in settings schema
- replace hardcoded defaults with constant in schema and OptionsPage
- maintain backward compatibility with existing boolean type

* feat(extension): simplify context menu removal logic

- remove redundant `settings` parameter from `removeContextMenus`
- replace selective menu removal with `chrome.contextMenus.removeAll()`
- update function call to match new signature

* refactor(extension): rename site-related cache terms to page for clarity

- update context menu title from "Clear Current Site Cache" to "Clear Current
  Page Cache"
- rename `clearCurrentSiteCache()` to `clearCurrentPageCache()`
- adjust related comments, logs, and docstrings for consistency

* refactor(extension): improve tab event handler parameter naming

- rename `activeInfo` to `tabActiveInfo` in `onActivated` listener
- rename `changeInfo` to `tabId` in `onUpdated` listener

* refactor(extension): add isHttpUrl utility and refactor server address validation

- introduce reusable `isHttpUrl` function in new `url.ts` utility module
- replace inline protocol check with utility call in NotConfiguredPage

* feat(extension): filter out non-HTTP URLs from badge count updates

- add `isHttpUrl` import and check in badge update validation
- skip badge updates for non-HTTP URLs to prevent invalid requests

* feat(extension): filter out non-HTTP URLs from bookmark creation

Add validation using isHttpUrl utility to ensure only HTTP/HTTPS
URLs are processed when creating bookmarks from current tab.

* chore: remove .ts extension from internal import statements

* feat(extension): validate and trim server address input in NotConfiguredPage

- use trimmed input for validation and state updates
- ensure consistent handling of trailing slashes in server address

* feat(extension): prevent non-HTTP(S) URL bookmark creation with validation

- Add URL validation in background script to filter out non-HTTP(S) URLs
  before creating link-type bookmarks, logging warnings for invalid URLs.

- Enhance SavePage component with explicit error messages for:
  - Missing tab URLs
  - Unsupported URL schemes (non-HTTP(S))

- Improve error display by rendering messages immediately when errors occur
  instead of waiting for status changes.

* feat(extension): clear existing context menus before registration

This ensures no duplicate menu items are created when the extension
reinitializes or settings are updated.

* feat(extension): display "+" suffix for default bookmarks per page count

Add logic to append "+" suffix when badge count matches
DEFAULT_NUM_BOOKMARKS_PER_PAGE to indicate potential overflow.

* fix(extension): ensure API client cleanup on settings state change

Clean up API client before handling settings state to prevent stale
connections when address or API key is missing.

* fix(extension): clear badge text when tab is invalid or incomplete

Ensure badge is reset when URL is non-HTTP or tab status is not complete.

* feat(extension): improve badge revalidation for stale cached data

- simplify badge setting from cached data
- add background revalidation for non-fresh cache
- ensure badge updates when stale cache is detected

* feat(extension): refresh active tab badges after cache clearance

Added logic to update badge icons for all active tabs when clearing
the badge status cache, ensuring UI consistency across the extension.

* feat: add null checks for tab URL and ID in REFRESH_BADGE handler

Add defensive programming to prevent runtime errors when processing
REFRESH_BADGE messages with missing or invalid tab properties.

* feat(extension): replace badge status SWR clear with full cache refresh

Replace selective SWR badge status clearing with a complete cache refresh
to ensure consistent badge state across all active tabs. Updates the
`clearBadgeStatusSWR()` call to use the more comprehensive `clearAllCache()`
method and improves related documentation.

* feat(extension): add validation & error handling for API client

- add null check and error throw in `getTabCount` when API client fails
- ensure badge is cleared when API client is unavailable
- refactor `getApiClient` to use destructured settings
- fix potential undefined access in TRPC client initialization

* feat(extension): replace isExisted with exactMatch for precise bookmark info

- modify getTabCount to return exactMatch instead of isExisted
- update BadgeCacheEntry type to use ZBookmark|null for exactMatch
- adjust setBadge and setBadgeStatusSWR to handle new exactMatch format
- ensure backward compatibility by converting exactMatch to boolean

* refactor(background): rename getTabCount to getBookmarkStatusForUrl

- improve function naming to better reflect return value
- update JSDoc to clarify return object structure
- adjust all function calls to use new name

* feat(extension): add "View page in Karakeep" context menu option

- introduce new `VIEW_PAGE_IN_KARAKEEP` menu item for extension action
- extend `handleContextMenuClick` to support optional tab parameter
- add `searchCurrentUrl` function to handle URL-based searches
- implement exact match and search fallback logic with proper URL encoding
- ensure error handling and validation for invalid URLs

* feat(extension): reorder menu items and extend page context support

- Move 'Add to Karakeep' menu creation before conditional block
- Add 'page' context to 'View this page in Karakeep' menu item

* feat(extension): add toggle to enable/disable badge caching

- introduce `useBadgeCache` setting in schema and defaults
- add switch control in OptionsPage to toggle cache usage
- conditionally render cache expire time input based on toggle
- make badge cache operations respect the toggle setting
- hide cache-related context menu items when caching disabled
- skip cache operations in background when disabled
- prevent cache checks and purges when caching is off

* fix(extension): handle cache miss in bookmark search flow

Previously, the search flow would silently fail (no-op) when the cache missed.
Now, it falls back to fetching the bookmark status directly from the server
when no cached data is available. Also refactored to avoid redundant settings
fetch and improve code readability.

* refactor(badge): implement generic cache utility and refactor badge cache

* Remove dedicated cache type definitions in favor of generic solution
* Create reusable cache utility with L1/L2 (memory/storage) support
* Simplify badge cache implementation using new generic cache
* Remove redundant SWR-specific functions and consolidate logic
* Improve type safety and error handling in cache operations
* Eliminate deprecated cache management functions and types

* refactor(extension): replace custom cache with TanStack Query for badge status

- Remove custom SWR cache implementation
- Add TanStack Query persistence with Chrome storage
- Update badge status logic to use QueryClient
- Add storage persister utility for Chrome
- Update TRPC client initialization with QueryClient
- Add required TanStack Query persistence dependencies

* fix(extension): add missing `useBadgeCache` config and refactor cache logic

- restore accidentally removed `useBadgeCache` setting from refactor
- update cache invalidation logic to include `useBadgeCache` changes
- modify QueryClient config to respect `useBadgeCache` toggle
- improve settings comparison logic for better reuse detection

* fix(extension): use dynamic key for TanStack query cache persistence

Previously used hardcoded string 'TANSTACK_QUERY_CACHE_KEY' instead of the
defined constant, which could lead to inconsistent storage access.

* fix(cache): propagate fetch errors to avoid caching failed badge status

Previously, API errors would return an empty status, causing cache to store
invalid results. Now errors are thrown so the cache treats them as misses.

* fix(extension): guard chrome storage and respect cache disable setting

- use `globalThis.chrome` to avoid runtime errors in non-extension contexts
- skip persistence when `useBadgeCache=false` and clear existing cache
- add `maxAge` and `buster` to prevent stale/incompatible data restoration

* refactor(badgeCache): remove redundant null check for searchBookmarks data

Remove unnecessary if (!data) guard since searchBookmarks query is guaranteed
to return a non-nullable response due to its Zod schema. Use direct access to
data.bookmarks and simplify empty state check with bookmarksLength.

* fix(badgeCache): throw error on misconfiguration instead of caching empty

Prevent cache poisoning by throwing when API client is not configured.
This ensures setup errors are visible rather than silently cached as 0.

* fix(badgeCache): add fallback to fetchBadgeStatus when QueryClient missing

Prevents null returns by falling back to direct fetch when QueryClient
is unavailable, ensuring badge remains responsive.

* feat(extension): add yellow badge for URLs ignoring anchor and trailing slash

- implement partial URL matching logic in badge status calculation
- introduce `BadgeMatchType` enum for different match scenarios
- update badge color scheme (green=exact, yellow=partial, red=none)
- refactor badge status interface and setBadge function signature
- handle edge cases for null badge status in error scenarios

* feat: support partial bookmark matches in badge status check

- use partial match fallback when exact match is unavailable
- update target URL generation to handle both match types
- ensure consistent bookmark ID reference in preview URL

* refactor: improve error handling and badge status logic

* wrap `removeContextMenus()` in try-catch block to prevent crashes
  when context menus API fails
* simplify badge setting logic by removing redundant status check
* fix `getBadgeStatus()` return type to always resolve with `BadgeStatus`
* update import path for `urlsMatchIgnoringAnchorAndTrailingSlash`
* clarify comments for URL matching logic and edge cases

* perf: parallelize active-tab badge refresh after cache clear

Avoid serial waits across windows/tabs by using Promise.all to process
active tab IDs concurrently. Replaces nested loops with flatMap and
filter for cleaner extraction of active tab IDs.

* fix(badge): isolate cache config to badge queries only

Move cache time configuration from global QueryClient to badge-specific
queries to prevent unintended caching in other query operations.

* fix: Invalid configuration check should verify if either field is missing.

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* fix(trpc): include address in cache buster to isolate persisted caches

Prevents restoring stale data from a different server after switching
address by scoping the cache buster to the current backend address.

* feat(trpc): ensure proper client cleanup on config changes

- add client removal from persistent storage when address/apiKey invalid
- ensure cache wipe when switching context with address/apiKey changes
- simplify persister creation by using default chrome.storage.local
- make storage parameter optional in createChromeStorage

* fix bad merge

* simplify badge by dropping the count

* more fixes

* more fix

---------

Co-authored-by: Mohamed Bassem <me@mbassem.com>

1 files changed, 27 insertions, 0 deletions

diff --git a/apps/browser-extension/src/components/ui/switch.tsx b/apps/browser-extension/src/components/ui/switch.tsx
new file mode 100644
index 00000000..f2016ed0
--- /dev/null
+++ b/apps/browser-extension/src/components/ui/switch.tsx
@@ -0,0 +1,27 @@
+import * as React from "react";
+import * as SwitchPrimitives from "@radix-ui/react-switch";
+
+import { cn } from "../../utils/css";
+
+const Switch = React.forwardRef<
+  React.ElementRef<typeof SwitchPrimitives.Root>,
+  React.ComponentPropsWithoutRef<typeof SwitchPrimitives.Root>
+>(({ className, ...props }, ref) => (
+  <SwitchPrimitives.Root
+    className={cn(
+      "peer inline-flex h-6 w-11 shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-primary data-[state=unchecked]:bg-input",
+      className,
+    )}
+    {...props}
+    ref={ref}
+  >
+    <SwitchPrimitives.Thumb
+      className={cn(
+        "pointer-events-none block h-5 w-5 rounded-full bg-background shadow-lg ring-0 transition-transform data-[state=checked]:translate-x-5 data-[state=unchecked]:translate-x-0",
+      )}
+    />
+  </SwitchPrimitives.Root>
+));
+Switch.displayName = SwitchPrimitives.Root.displayName;
+
+export { Switch };