Gemini Usage Sidebar Widget (Ultra Fix) 🤖📊

English | 简体中文

---

English

A premium, highly-polished browser userscript that seamlessly integrates real-time usage statistics directly into the Google Gemini (gemini.google.com) sidebar navigation. Stay informed of your model limits (such as 5-hour limits and weekly Pro/Advanced quotas) at a glance without interrupting your chat flow.

🌟 Key Features

• Flat Dual-Metric Badges: Direct visualization of both current and weekly usage percentages right next to the "Usage" menu item with an elegant 8px margin separation, perfectly matching the sidebar font size.
• Intelligent Warning Text: Auto-detects threshold limits and applies clean, native warning colors directly to the text (no bulky capsules or heavy backgrounds):
  • 🟢 Normal (< 70%): Native text color matching the current Gemini sidebar theme.
  • 🟡 Warning (70% – 90%): High-contrast native orange-gold font alert.
  • 🔴 Critical (≥ 90% or Error): Clean red font to warn against imminent throttling.
• Clean Native Tooltips: Hovering over the widget reveals a sleek flat popup card matching Google's native styling (pure white for light theme, carbon grey for dark theme, thin grey borders) containing:
  • Material-compliant 4px flat progress bars (solid Google Blue, warning orange, or critical red).
  • Detailed status metrics and the exact time of the last update.
  • Quick-action buttons to Force Refresh or Open Official Usage Page (fully flex-centered to eliminate any alignment bias).
• Robust Background Scraping & Caching:
  • Direct API Fetching: Fast background JSON/HTML parsing for zero layout shift.
  • Smart Iframe Fallback: Automatically spins up an isolated, hidden iframe to scrape data if CORS/security headers block direct fetches (properly sandboxed and disabled during full-screen /usage route visits to prevent redirect loops).
  • Snappy Caching: Saves parsed usage data in localStorage with intelligent cache invalidation (5-minute refresh intervals) to minimize network overhead.
• Responsive Layout Support (Rail Mode): Supports Gemini's collapsible sidebar. When collapsed into a slim "rail," the widget transitions into a beautiful, rounded icon button with a clean flat status dot.
• SPA Navigation Resilience: Uses lightweight DOM MutationObserver loops to ensure the widget stays permanently mounted, even during SPA route transitions or sidebar re-renders.
• Bilingual Localization: Dynamically renders in either English or Simplified Chinese based on your browser's language setting.

---

🚀 Installation Guide

1. Install a Userscript Manager:
   • Tampermonkey (Recommended)
   • Violentmonkey
2. Add the Script:
   • Open your userscript manager dashboard.
   • Create a new script, copy the entire content of gemini-usage-widget.user.js, and paste it into the editor.
   • Save the script.
3. Use:
   • Visit gemini.google.com.
   • The "Usage" sidebar item will automatically appear under the Library section.
   • Hover over the item to see details, click to visit the detailed usage dashboard, or let it work in the background!

---

🛠️ Working Principle & Technical Details

graph TD
    A[Gemini App Page] --> B{Cache Available?};
    B -- Yes --> C[Render Widget with Cached Data];
    B -- No / Expired --> D[Trigger Background Fetch];
    D --> E{Fetch Successful?};
    E -- Yes --> F[Parse & Save to Cache];
    E -- No --> G[Fallback: Mount Hidden Iframe];
    G --> H[Poll & Scrape Iframe Text];
    H --> F;
    F --> I[Update UI & Color Badges];

Loading

• Scraping Strategy: Uses a regular-expression-based text scanner (collectUsageFromText) that extracts percentage usage matched with keywords (e.g. current usage, weekly limit, 当前用量, 每周限制).
• CORS Bypass: Solves the standard X-Frame-Options: DENY issue on fetches by falling back to same-origin dynamic sandboxed iframe parsing.
• Anti-Flicker Mounting: Coordinates state with Angular/Gemini components (gem-nav-list, mdc-list-item) using CSS-in-JS style injection and selective Node inheritance.

---

简体中文

一款高颜值、稳定可靠的的浏览器油猴脚本。它能将 Google Gemini 的实时用量数据直接无缝嵌入到侧边栏导航中，让您在聊天时对当前的用量额度（包括 5 小时临时额度和每周 Advanced/Pro 额度）一目了然。

🌟 核心特性

• 极简纯文本徽章: 在侧边栏“用量”菜单右侧以 8px 优雅分离间隙平铺展示当前用量和每周上限百分比，字号与 Library 原生文本完全等大对齐，自然和谐。
• 智能预警扁平字色: 自动识别用量等级并应用原生扁平警示色直接渲染文字本身（无冗余背景胶囊与花哨框线）：
  • 🟢 正常 (< 70%): 原生常规文字配色，自然融入 Gemini 侧边栏主题。
  • 🟡 警告 (70% – 90%): 醒目的原生警告黄字色（#b06000 / #fdec93），提示额度吃紧。
  • 🔴 临界 (≥ 90% 或 错误): 原生警示红字色（#c5221f / #f28b82），防止额度超限被限流。
• 官方风原生悬浮窗: 鼠标悬停在挂件上即可展现与 Google 原生气泡卡片完全一致的极简扁平窗口（浅色纯白，深色碳灰，带极细灰色边框）：
  • 包含完全符合 Material 设计规范的 4px 扁平单色进度条（正常蓝色、警告黄色、危险红色）。
  • 精确到分钟的数据刷新时间戳。
  • 快捷操作按钮：支持 一键手动强制刷新 以及 一键跳转官网用量页（内部完全采用 Flex 水平垂直绝对居中，杜绝对齐偏置）。
• 鲁棒的后台数据抓取 & 缓存机制:
  • 高效 Fetch 抓取: 后台自动获取 /usage 页面进行文本解析，无感知、零延迟。
  • 智能 Iframe 兜底: 若直接请求因跨域或安全控制被拦截，脚本将自动在后台建立隐蔽 iframe 进行同源解析（在直接访问全屏 /usage 详情页时，自动停用所有侧边栏自动展开和按钮点击，彻底防止重定向跳转死循环）。
  • 低开销本地缓存: 数据会结构化保存在 localStorage 中，采用 5 分钟智能过期机制，最大程度减少对 Gemini 服务器的请求。
• 完美支持窄侧边栏 (Rail Mode): 完美适配 Gemini 窄版折叠菜单。在窄版模式下，挂件会自动缩小为精致的圆形图标，并附带极简扁平状态点。
• 无感路由追踪 (SPA): 基于轻量级的 DOM 监听器 (MutationObserver)，在 Gemini 的单页路由跳转或侧边栏重绘时自动重新挂载，防闪烁、防丢失。
• 原生级双语支持: 根据浏览器默认语言，自动智能呈现简体中文或英文界面。

---

🚀 安装与使用

1. 安装浏览器脚本管理器:
   • Tampermonkey (推荐)
   • Violentmonkey
2. 添加本脚本:
   • 打开油猴管理面板，新建脚本。
   • 复制 gemini-usage-widget.user.js 的全部代码并粘贴进编辑器中。
   • 保存脚本。
3. 开启体验:
   • 打开 gemini.google.com。
   • “用量”菜单将自动呈现在左侧栏 库 (Library) 下方。
   • 悬停查看详情，点击跳转，畅快使用！

---

📄 License

This project is licensed under the MIT License - see the LICENSE details for info. 本项目基于 MIT 协议开源。