codex-ringside 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.3.1 (2026-11-03)
+
+- Bundle a wallpaper and background preset for fresh installations (cover, 134% zoom, top-left alignment, zero transparency and blur). Preserve existing images, edits and disabled backgrounds on upgrades, reinstalls and Codex Plus migrations.
+- Verify preset inclusion in npm packages and standalone bundles, real image preparation, settings preservation and failed-install rollback.
+
+## 0.3.0 (2026-11-03)
+
+- Replace the native sidebar usage icon with Ringside meters in place, preserving its usage menu, management actions and keyboard controls. Restore the native icon when the add-on is removed.
+- Show plan, credit balance (including zero/unlimited), reset times and reset cards in the hover details. Clear all account-specific values on expiry, disconnection and account changes.
+- Preserve the original background-settings action on ring click, Enter and Space, including interception of the native pointerdown menu. Keep the native usage menu under a separate hover-details action and ArrowDown; right-click and Shift+F10 still open background settings.
+- Add Chromium interaction coverage for native replacement, remounting, cleanup, menu actions, background settings and stale/credit-only states.
+
 ## 0.2.0 (2026-10-31)
 
 - Automatically check stable GitHub releases every six hours, verify and install newer standalone bundles, and retry failures after one hour. Preserve settings, back up and roll back failed updates without closing the desktop client.

package/README.md

@@ -4,7 +4,9 @@ English · [简体中文](README.zh-CN.md)
 
 Usage rings and customizable backgrounds for the Codex desktop sidebar on macOS.
 
-See your remaining allowance at a glance, hover for reset times, and click a ring to configure a wallpaper, image or glass background. Image controls include cropping, positioning, zoom, blur and color adjustments.
+Rings replace the native sidebar usage icon in place. Hover for your plan, remaining allowance, credit balance, reset times and reset cards; click to open the original background settings and configure a wallpaper, image or glass background. Image controls include cropping, positioning, zoom, blur and color adjustments. The hover details' usage-menu button preserves the native menu and its management actions.
+
+Credit balances are grouped and rounded to whole credits, including zero; unlimited balances are labeled explicitly, and missing balances are omitted. Credit-only accounts show a balance summary instead of a percentage ring. Account changes, connection failures and data older than 150 seconds clear old account values. On older clients without a compatible usage button, a separate ring opens background settings on click. Removing the add-on restores the native icon.
 
 **Unofficial community add-on. Not affiliated with or endorsed by OpenAI.** Parts are adapted from [Codex Usage Card](https://github.com/Lorie7813/codex-usage-card); see [NOTICE](NOTICE).
 
@@ -102,7 +104,9 @@ Reinstalling preserves observe mode; `--observe` explicitly disables startup han
 
 ## Background controls
 
-Click a ring to open settings. Panel changes apply immediately; CLI changes apply within five seconds.
+A fresh installation automatically applies the bundled wallpaper: image source, cover layout, 134% zoom, top-left alignment, zero transparency and blur, 100% brightness/contrast/saturation, and no crop. The image is stored inside the add-on's directory; no separate download or file selection is needed. Upgrades, reinstalls and Codex Plus migrations preserve existing images and settings, including leaving backgrounds off for users who never enabled them. You can change the image, adjust the controls or turn the background off at any time. Framing varies with window proportions; the client's light/dark appearance setting is preserved.
+
+Click a ring, or press Enter or Space while focused, to open background settings. The hover details' background settings button, right-click and Shift+F10 also work. Open the native usage menu through the separate button in the hover details or ArrowDown while the ring is focused; this entry is hidden on clients without a compatible native usage button. Panel changes apply immediately; CLI changes apply within five seconds.
 
 | Source | Behavior |
 | --- | --- |
@@ -132,13 +136,27 @@ Options without a source keep the current source. `background` without arguments
 - Background cleanup uses host DOM heuristics. Terminals, code blocks, canvases and embedded web content are left alone; an unfamiliar page may retain opaque areas.
 - Host updates can break rate-limit reading, placement or theme integration. Disable the background or uninstall if problems arise.
 
+### Recommended wallpaper sites
+
+Find a background image on these sites:
+
+| Site | Highlights |
+| --- | --- |
+| [Wallhaven](https://wallhaven.cc/) | A broad wallpaper collection with keyword, resolution and aspect-ratio filters |
+| [WallpaperHub](https://www.wallpaperhub.app/) | Windows, Surface and Fluent Design wallpapers in sizes for different devices |
+| [Peapix](https://peapix.com/) | Bing daily wallpapers and Windows Spotlight images, including landscapes, architecture and nature photography |
+| [Unsplash](https://unsplash.com/wallpapers) | HD photography wallpapers covering nature, travel, animals and more |
+| [Pexels](https://www.pexels.com/search/desktop%20wallpaper/) | A photography library with desktop, 4K and dark wallpaper categories |
+
+Download an image to your Mac, click a sidebar ring, then choose the `image` source and select the file. You can also set it as your macOS desktop wallpaper and choose the `wallpaper` source to align the background with your desktop.
+
 ## Status and troubleshooting
 
 ```bash
 "$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" status
 ```
 
-Look for `agent: "running"`, `cdp.windows[].card.placed`, and `cdp.windows[].background.applied`. `nativeGlass: false` means the host disables native glass. `startup.event` explains skipped handoffs. Status may contain private paths and window URLs; redact it before sharing.
+Look for `agent: "running"`, `cdp.windows[].card.placed`, and `cdp.windows[].background.applied`. `card.replacesNative` confirms replacement of the native usage icon; `card.credits` and `card.plan` show current allowance details. `nativeGlass: false` means the host disables native glass. `startup.event` explains skipped handoffs. Status may contain private paths and window URLs; redact it before sharing.
 
 If no ring appears, verify the signed-in host, application path and whether port 39222 is occupied. Node and Command Line Tools checks apply only to npm/source installations. A missing release asset means that version does not contain a standalone bundle; use 0.2.0 or later. A checksum or download failure stops before changing the installed app; retry when the network is available. Installing while the host is open does not trigger a restart. Save your work and reopen its original icon when convenient. Check `~/Library/Logs/CodexRingside` for errors.
 

package/README.zh-CN.md

@@ -4,19 +4,21 @@
 
 ![背景设置](https://raw.githubusercontent.com/tccpc/codex-ringside/main/docs/images/background-settings.png)
 
-在 Codex 桌面端的侧栏显示剩余额度圆环，悬停可看重置时间；点击圆环可以自定义 Codex 的背景：图片、壁纸或毛玻璃，透明度和模糊自由调节，图片还能裁剪、缩放和调整布局。仅支持 macOS。
+用剩余额度圆环替换 Codex 桌面端侧栏的官方用量图标，悬停可看套餐、余额和重置时间，点击圆环打开原有背景设置。可以自定义图片、壁纸或毛玻璃，透明度和模糊自由调节，图片还能裁剪、缩放和调整布局。悬停详情中的“用量菜单”保留官方“管理用量”等操作。仅支持 macOS。
 
 这是非官方插件，与 OpenAI 无关。原理参考 [Codex Usage Card](https://github.com/Lorie7813/codex-usage-card)，署名见 [NOTICE](NOTICE)。
 
 ## 工作原理
 
 - **额度**：启动 Codex 内置的 `codex app-server`，通过 stdio 调用 `account/rateLimits/read`，每 60 秒刷新一次。
-- **显示**：通过本机调试端口 `127.0.0.1:39222` 把卡片注入到 `nav[data-app-navigation-rail]`。
+- **显示**：通过本机调试端口 `127.0.0.1:39222` 在侧栏官方用量按钮内替换图标，保留原生菜单、键盘操作和“管理用量”等账号功能。找不到兼容的官方按钮时，回退为独立圆环；卸载会恢复原图标。
 - **背景**：同样通过调试端口，把 Codex 外壳层的背景清空，在页面最底层放一张图片。窗口属性由主进程控制，插件改不了，所以“透明”透出的是 Codex 自带的系统毛玻璃，壁纸来源显示的是对齐到屏幕位置的桌面壁纸。
 - **启动**：Codex 的 `app.asar` 受完整性校验保护，不能修改，只能让它带调试端口启动。后台任务发现你从原图标打开 Codex 时，会在安全条件都满足的情况下有序退出，再带端口重开一次。
 
 账号有几个额度窗口就显示几个圆环。圆环是分段刻度样式，环内显示剩余百分比和窗口名称（“5小时”或“周”）。额度充足时为青绿渐变，50% 及以下转为黄橙，低于 10% 转为橙红。
 
+悬停详情显示套餐、各窗口的剩余百分比及重置时间、可用重置卡，以及接口提供的额度余额。余额按整数分组显示，例如 `12,346`；零余额显示 `0`，无限额度显示“不限额”，未返回余额时不猜测数值。只有余额、没有百分比窗口时，侧栏显示余额摘要。连接失败、数据超过 150 秒未更新或账号切换时，会清除旧数值并提示重试。重置、购买和管理操作继续由官方菜单处理。
+
 ## 安装
 
 一键安装需要 **macOS 13 或更高版本**（Apple Silicon 或 Intel），以及已登录的兼容桌面客户端。**无需自行安装 Node.js、npm、Homebrew 或 Xcode Command Line Tools。** 安装包自带专用 Node 和预编译 helper。开发验证使用 `/Applications/ChatGPT.app`，版本 `26.1027.30824`；其他客户端版本依赖相同内部结构，未逐一验证。命令行和设置面板目前使用中文。
@@ -111,7 +113,9 @@ npx codex-ringside@latest install
 
 ## 自定义背景
 
-点击侧栏的圆环打开设置面板。先选来源，再用效果调外观，所有调节都立即生效。
+首次安装会自动应用安装包内置的壁纸：图片来源、铺满布局、缩放 134%、左上对齐、透明度和模糊均为 0，亮度、对比度和饱和度均为 100%，不裁剪。图片保存在插件自己的目录内，无需另行下载或选择。升级、重装和从 Codex Plus 迁移都会保留已有图片和设置；之前未启用背景的用户也会继续保持关闭。可随时在面板中换图、调整参数或选择“关闭”。窗口比例不同会影响取景，客户端的浅色／深色模式保持用户自己的选择。
+
+直接点击侧栏圆环打开原有背景设置面板，聚焦后按 Enter 或空格也可以打开。悬停面板中的“背景设置”、右键和 Shift+F10 仍可使用。官方用量菜单通过悬停面板中的“用量菜单”打开，也可以聚焦圆环后按向下键；没有兼容的官方按钮时，这个菜单入口隐藏。先选来源，再用效果调外观，所有调节都立即生效。
 
 面板顶部还能切换 Codex 的**外观模式**：跟随系统、浅色、深色。它和设置页的“模式”是同一个设置，改动会保存，并在两边同步。这里用的是 Codex 内部的设置函数，找不到时控件自动隐藏。
 
@@ -163,6 +167,20 @@ npx codex-ringside@latest install
 - **切换有延迟**：切换桌面空间后，壁纸最多 60 秒才更新；拖动窗口时壁纸有轻微跟随延迟。
 - **页面自动适配**：内容区里方角、无边框、占满区域的不透明层会被当作页面背景清除，设置页这类圆角卡片变成半透明磨砂，文字依然清楚。终端、代码块和内嵌网页不处理。设计不同的页面可能漏掉，这时自带背景的地方保持原样。
 
+### 壁纸网站推荐
+
+可以从这些网站挑选背景图片：
+
+| 网站 | 推荐内容 |
+|---|---|
+| [Wallhaven](https://wallhaven.cc/) | 综合壁纸图库，可按关键词、分辨率和宽高比筛选 |
+| [WallpaperHub](https://www.wallpaperhub.app/) | Windows、Surface 和 Fluent Design 风格壁纸，提供多种设备尺寸 |
+| [Peapix](https://peapix.com/) | Bing 每日壁纸与 Windows Spotlight 图片，适合寻找风景、建筑和自然摄影 |
+| [Unsplash](https://unsplash.com/wallpapers) | 摄影类高清壁纸，涵盖自然、旅行、动物等主题 |
+| [Pexels](https://www.pexels.com/search/desktop%20wallpaper/) | 摄影图库，提供桌面、4K 和深色壁纸等分类 |
+
+下载图片到本机后，点击侧栏圆环，在背景设置面板中选择 `image` 图片来源并选取文件。也可以先将图片设为 macOS 桌面壁纸，再选择 `wallpaper` 壁纸来源，让背景与桌面对齐。
+
 ## 查看状态
 
 下载失败或 SHA-256 校验失败时，安装器会在更改现有安装前停止，可在网络恢复后重试。发行版缺少安装包时，请选择 0.2.0 或更高版本。通过一键入口安装后，无需检查系统 Node 或编译工具。
@@ -171,7 +189,7 @@ npx codex-ringside@latest install
 "$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" status
 ```
 
-重点看 `cdp.windows[].card.placed`。背景看 `background`（保存的设置）和 `cdp.windows[].background`：`applied` 表示已生效，`nativeGlass` 为 `false` 表示 Codex 此刻关闭了毛玻璃。输出可能包含本机路径，分享前请先脱敏。
+重点看 `cdp.windows[].card.placed`，`replacesNative` 为 `true` 表示已替换官方用量图标；`credits` 和 `plan` 显示当前余额和套餐。背景看 `background`（保存的设置）和 `cdp.windows[].background`：`applied` 表示已生效，`nativeGlass` 为 `false` 表示 Codex 此刻关闭了毛玻璃。输出可能包含本机路径，分享前请先脱敏。
 
 ## 卸载
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-ringside",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Usage rings and customizable backgrounds for the Codex desktop app. Unofficial macOS add-on.",
   "license": "MIT",
   "type": "commonjs",
@@ -15,6 +15,7 @@
   ],
   "scripts": {
     "test": "node --test test/*.test.cjs",
+    "test:card": "node --test test/card.browser.cjs",
     "install-agent": "node bin/codex-ringside.cjs install",
     "uninstall-agent": "node bin/codex-ringside.cjs uninstall",
     "status": "node bin/codex-ringside.cjs status",
@@ -48,10 +49,15 @@
     "bin/*.cjs",
     "src/**/*.cjs",
     "src/**/*.js",
+    "src/presets/default-background.json",
+    "src/presets/wallpaper.png",
     "native/bridge.swift",
     "README*.md",
     "LICENSE",
     "NOTICE",
     "CHANGELOG.md"
-  ]
+  ],
+  "devDependencies": {
+    "playwright": "1.64.1"
+  }
 }

package/src/agent.cjs

@@ -65,6 +65,7 @@ async function runAgent({ appPath, root, signal }) {
     seenAuth = stamp;
     log('account file changed, reconnecting');
     dropClient();
+    showUnavailable();
     nextRead = 0;
   }
 

package/src/card.js

@@ -1,6 +1,6 @@
 // Runs inside the Codex renderer. Must stay self-contained: cdp.cjs injects this file as text.
 function installCodexRingsideCard() {
-  const VERSION = 13;
+  const VERSION = 17;
   const KEY = '__codexRingsideCard';
   const STALE_AFTER_MS = 150000;
   const TICKS = 30;
@@ -18,14 +18,14 @@ function installCodexRingsideCard() {
   const card = document.createElement('div');
   card.id = 'codex-ringside-card';
   card.tabIndex = 0;
-  card.setAttribute('role', 'group');
+  card.setAttribute('role', 'button');
   card.setAttribute('aria-label', 'Codex 剩余额度');
-  card.setAttribute('aria-describedby', 'codex-ringside-tooltip');
   card.setAttribute('aria-haspopup', 'dialog');
 
   const tooltip = document.createElement('div');
   tooltip.id = 'codex-ringside-tooltip';
-  tooltip.setAttribute('role', 'tooltip');
+  tooltip.setAttribute('role', 'dialog');
+  tooltip.setAttribute('aria-label', 'Codex 剩余额度');
   tooltip.hidden = true;
 
   const style = document.createElement('style');
@@ -47,12 +47,16 @@ function installCodexRingsideCard() {
     /* The spread also grows the corners, so the outer radius is 4 + 3 = 7px; the width matches the rail buttons' 36px. */
     #codex-ringside-card:hover { background: var(--ringside-hover); box-shadow: 0 0 0 3px var(--ringside-hover); }
     #codex-ringside-card:active { transform: scale(.96); }
+    /* Keep the native menu available, with Ringside's original background-settings click. */
+    [data-codex-ringside-host] { height: auto !important; min-height: 36px; padding: 3px !important; }
+    [data-codex-ringside-host] > :not(#codex-ringside-card) { display: none !important; }
+    [data-codex-ringside-host] > #codex-ringside-card { margin: 0; pointer-events: none; }
     @media (prefers-reduced-motion: reduce) { #codex-ringside-card { transition: none; } }
     html.dark #codex-ringside-card, html[data-theme="dark"] #codex-ringside-card { ${dark} }
     @media (prefers-color-scheme: dark) {
       html:not(.light):not([data-theme="light"]) #codex-ringside-card { ${dark} }
     }
-    #codex-ringside-card[hidden], #codex-ringside-tooltip[hidden] { display: none !important; }
+    #codex-ringside-card[hidden], #codex-ringside-tooltip[hidden], #codex-ringside-tooltip [hidden] { display: none !important; }
     #codex-ringside-card:focus-visible { outline: 1px solid var(--ringside-text); outline-offset: 2px; }
     #codex-ringside-card .ringside-meter { position: relative; flex: 0 0 auto; width: 30px; height: 30px; }
     #codex-ringside-card .ringside-meter[data-tone="normal"] { --ringside-glow: #34e08280; }
@@ -67,11 +71,12 @@ function installCodexRingsideCard() {
     #codex-ringside-card .ringside-number { font-size: 8px; line-height: 9px; font-weight: 600; letter-spacing: -.3px; white-space: nowrap; }
     #codex-ringside-card .ringside-label { font-size: 6.5px; line-height: 8px; color: var(--ringside-label); white-space: nowrap; }
     #codex-ringside-tooltip {
-      box-sizing: border-box; position: fixed; z-index: 2147483000; min-width: 170px; max-width: min(320px, calc(100vw - 16px));
-      padding: 12px 14px; border: 1px solid color-mix(in srgb, currentColor 12%, transparent); border-radius: 10px;
+      box-sizing: border-box; position: fixed; z-index: 2147483000; min-width: 204px; max-width: min(320px, calc(100vw - 16px));
+      padding: 12px 14px; border: 1px solid color-mix(in srgb, currentColor 12%, transparent); border-radius: 12px;
       background: var(--color-surface-elevated-secondary, #f8f8f7); color: var(--color-text-primary, #303630);
-      box-shadow: 0 4px 18px #0002; pointer-events: none; -webkit-app-region: no-drag;
-      font: 12px/1.5 -apple-system, BlinkMacSystemFont, sans-serif;
+      box-shadow: 0 6px 22px #00000024; -webkit-app-region: no-drag;
+      max-height: calc(100vh - 16px); overflow: auto;
+      font: 12px/1.45 -apple-system, BlinkMacSystemFont, sans-serif;
     }
     html.dark #codex-ringside-tooltip, html[data-theme="dark"] #codex-ringside-tooltip {
       background: var(--color-surface-elevated-secondary, #2c2e2c); color: var(--color-text-primary, #edf0ed);
@@ -81,21 +86,53 @@ function installCodexRingsideCard() {
         background: var(--color-surface-elevated-secondary, #2c2e2c); color: var(--color-text-primary, #edf0ed);
       }
     }
-    #codex-ringside-tooltip .ringside-title { font-weight: 600; }
-    #codex-ringside-tooltip .ringside-sections { display: flex; gap: 20px; margin-top: 8px; }
-    #codex-ringside-tooltip .ringside-section-percent { margin: 2px 0; font-size: 22px; line-height: 26px; font-weight: 700; font-variant-numeric: tabular-nums; }
-    #codex-ringside-tooltip .ringside-dim { opacity: .68; font-size: 11px; white-space: nowrap; }
-    #codex-ringside-tooltip .ringside-footer { margin-top: 10px; padding-top: 8px; border-top: 1px solid color-mix(in srgb, currentColor 10%, transparent); }
+    #codex-ringside-tooltip .ringside-header { display: flex; align-items: center; justify-content: space-between; gap: 12px; }
+    #codex-ringside-tooltip .ringside-title { font-weight: 600; font-size: 12.5px; }
+    #codex-ringside-tooltip .ringside-badge {
+      padding: 1px 7px; border-radius: 999px; font-size: 10.5px; line-height: 16px; font-weight: 500;
+      background: color-mix(in srgb, currentColor 9%, transparent); color: color-mix(in srgb, currentColor 80%, transparent); white-space: nowrap;
+    }
+    #codex-ringside-tooltip .ringside-sections { display: flex; flex-wrap: wrap; gap: 10px 20px; margin-top: 10px; }
+    #codex-ringside-tooltip .ringside-section { flex: 1 1 auto; min-width: 72px; }
+    #codex-ringside-tooltip .ringside-section-percent {
+      margin: 2px 0; font-size: 24px; line-height: 28px; font-weight: 700; letter-spacing: -.02em; font-variant-numeric: tabular-nums;
+    }
+    #codex-ringside-tooltip .ringside-dim { opacity: .68; font-size: 11px; }
+    #codex-ringside-tooltip .ringside-message { margin-top: 8px; }
+    #codex-ringside-tooltip .ringside-footer { margin-top: 10px; padding-top: 9px; border-top: 1px solid color-mix(in srgb, currentColor 10%, transparent); }
+    #codex-ringside-tooltip .ringside-meta { display: flex; flex-direction: column; gap: 6px; }
+    #codex-ringside-tooltip .ringside-row { display: flex; align-items: center; justify-content: space-between; gap: 16px; }
+    #codex-ringside-tooltip .ringside-row[data-label]::before { content: attr(data-label); opacity: .68; font-size: 11px; }
+    #codex-ringside-tooltip .ringside-credit-balance { font-size: 14px; line-height: 18px; font-weight: 600; font-variant-numeric: tabular-nums; }
+    #codex-ringside-tooltip .ringside-meta-value { font-size: 12px; line-height: 16px; font-weight: 500; opacity: .9; font-variant-numeric: tabular-nums; }
+    #codex-ringside-tooltip .ringside-sr { font-size: 0; opacity: 0; }
+    #codex-ringside-tooltip .ringside-actions { display: flex; gap: 6px; }
+    #codex-ringside-tooltip button {
+      flex: 1; padding: 5px 10px; border: 1px solid color-mix(in srgb, currentColor 14%, transparent); border-radius: 6px;
+      font: 500 11.5px/1.35 -apple-system, BlinkMacSystemFont, sans-serif; text-align: center; white-space: nowrap;
+      color: inherit; background: color-mix(in srgb, currentColor 4%, transparent); cursor: pointer;
+      transition: background-color 120ms ease, border-color 120ms ease;
+    }
+    #codex-ringside-tooltip button:hover, #codex-ringside-tooltip button:focus-visible {
+      background: color-mix(in srgb, currentColor 11%, transparent);
+      border-color: color-mix(in srgb, currentColor 22%, transparent);
+    }
+    #codex-ringside-tooltip button:focus-visible { outline: 1px solid currentColor; outline-offset: 1px; }
   `;
 
   let value = { rings: [], message: '正在读取 Codex 剩余额度', note: null, stale: false, updatedAt: null };
   let rail = null;
+  let nativeTrigger = null;
+  let eventTarget = null;
   let placementTimer = null;
   let hoverTimer = null;
+  let hideTimer = null;
+  let suppressFocusTooltip = false;
+  let forwardingNativeAction = false;
   let disposed = false;
 
-  const element = (className, text) => {
-    const node = document.createElement('div');
+  const element = (className, text, tag = 'div') => {
+    const node = document.createElement(tag);
     node.className = className;
     if (text != null) node.textContent = text;
     return node;
@@ -106,6 +143,25 @@ function installCodexRingsideCard() {
     return rect.width > 0 && rect.height > 0 && getComputedStyle(node).visibility !== 'hidden';
   };
   const percentText = percent => (Number.isFinite(percent) ? `${percent}%` : '—');
+  const details = element('ringside-details');
+  const actions = element('ringside-actions ringside-footer');
+  const settingsButton = document.createElement('button');
+  settingsButton.type = 'button';
+  settingsButton.textContent = '背景设置';
+  settingsButton.addEventListener('click', togglePanel);
+  const usageButton = document.createElement('button');
+  usageButton.type = 'button';
+  usageButton.textContent = '用量菜单';
+  usageButton.setAttribute('aria-haspopup', 'menu');
+  usageButton.addEventListener('click', openUsageMenu);
+  actions.append(settingsButton, usageButton);
+  tooltip.append(details, actions);
+
+  function renderActions() {
+    settingsButton.hidden = !window.__codexRingsideBackground?.togglePanel;
+    usageButton.hidden = !nativeTrigger;
+    actions.hidden = settingsButton.hidden && usageButton.hidden;
+  }
 
   // Filled ticks run clockwise from 12 o'clock; the unused part of the circle stays a solid track.
   function ringSvg(percent, tone) {
@@ -151,19 +207,53 @@ function installCodexRingsideCard() {
       if (ring.resetsAt) section.append(element('ringside-dim', `${ring.resetsAt} 重置`));
       sections.append(section);
     }
-    const lines = [element('ringside-title', 'Codex 剩余额度')];
+    const header = element('ringside-header');
+    header.append(element('ringside-title', 'Codex 剩余额度'));
+    if (value.plan) header.append(element('ringside-badge', `${value.plan} 套餐`));
+    const lines = [header];
     if (sections.childElementCount) lines.push(sections);
-    if (value.message) lines.push(element('ringside-dim', value.message));
-    if (value.note) {
-      const footer = element('ringside-dim ringside-footer', value.note);
-      lines.push(footer);
+    if (value.credits || value.note) {
+      const meta = element('ringside-meta ringside-footer');
+      if (value.credits) {
+        const credits = element('ringside-row');
+        credits.append(element('ringside-dim', '额度余额'), element('ringside-credit-balance', value.credits.label));
+        meta.append(credits);
+      }
+      if (value.note) {
+        const parts = /^([^：:]+)([：:]\s*)(.+)$/.exec(value.note);
+        if (parts) {
+          const note = element('ringside-row');
+          note.dataset.label = parts[1];
+          const val = element('ringside-meta-value', parts[3], 'span');
+          val.prepend(element('ringside-sr', `${parts[1]}${parts[2]}`, 'span'));
+          note.append(val);
+          meta.append(note);
+        } else {
+          meta.append(element('ringside-dim', value.note));
+        }
+      }
+      lines.push(meta);
     }
-    tooltip.replaceChildren(...lines);
+    if (value.message) lines.push(element('ringside-dim ringside-message', value.message));
+    details.replaceChildren(...lines);
+    renderActions();
   }
 
   function render() {
-    const rings = value.rings?.length ? value.rings : [{ label: '额度', name: '额度', percent: null, tone: 'muted' }];
-    card.replaceChildren(...rings.map(buildMeter));
+    if (!value.rings?.length && value.credits) {
+      const balance = element('ringside-center');
+      const compact = value.credits.unlimited ? '∞' : new Intl.NumberFormat('zh-CN', {
+        notation: 'compact', maximumFractionDigits: 1
+      }).format(value.credits.balance);
+      balance.append(element('ringside-number', compact), element('ringside-label', '额度'));
+      const meter = element('ringside-meter');
+      meter.setAttribute('aria-label', `额度余额：${value.credits.label}`);
+      meter.append(balance);
+      card.replaceChildren(meter);
+    } else {
+      const rings = value.rings?.length ? value.rings : [{ label: '额度', name: '额度', percent: null, tone: 'muted' }];
+      card.replaceChildren(...rings.map(buildMeter));
+    }
     renderTooltip();
     if (!tooltip.hidden) positionTooltip();
   }
@@ -174,6 +264,9 @@ function installCodexRingsideCard() {
     value = {
       ...value,
       stale: true,
+      credits: null,
+      plan: null,
+      note: null,
       message: '额度数据已过期，正在等待重新连接',
       rings: (value.rings ?? []).map(ring => ({ ...ring, percent: null, tone: 'muted', resetsAt: null }))
     };
@@ -184,31 +277,121 @@ function installCodexRingsideCard() {
   const panelOpen = () => document.getElementById('codex-ringside-panel')?.hidden === false;
   function togglePanel() {
     hideTooltip();
-    window.__codexRingsideBackground?.togglePanel(card);
+    window.__codexRingsideBackground?.togglePanel(nativeTrigger ?? card);
+  }
+
+  function openUsageMenu() {
+    if (!nativeTrigger?.isConnected) return;
+    if (panelOpen()) window.__codexRingsideBackground?.togglePanel(nativeTrigger);
+    hideTooltip();
+    // Current clients open on pointerdown; older triggers may open on click. Pass both
+    // through the untouched native handlers, only for this explicit menu action.
+    forwardingNativeAction = true;
+    try {
+      nativeTrigger.focus();
+      const pointer = { bubbles: true, cancelable: true, button: 0, pointerType: 'mouse', isPrimary: true };
+      nativeTrigger.dispatchEvent(new PointerEvent('pointerdown', { ...pointer, buttons: 1 }));
+      nativeTrigger.dispatchEvent(new PointerEvent('pointerup', { ...pointer, buttons: 0 }));
+      nativeTrigger.click();
+    } finally {
+      forwardingNativeAction = false;
+      hideTooltip();
+    }
   }
 
   function positionTooltip() {
-    const rect = card.getBoundingClientRect();
+    const rect = (nativeTrigger ?? card).getBoundingClientRect();
     tooltip.style.left = `${Math.max(8, Math.min(rect.right + 12, innerWidth - tooltip.offsetWidth - 8))}px`;
     const top = rect.top + rect.height / 2 - tooltip.offsetHeight / 2;
     tooltip.style.top = `${Math.max(8, Math.min(top, innerHeight - tooltip.offsetHeight - 8))}px`;
   }
   function hideTooltip() {
     clearTimeout(hoverTimer);
+    clearTimeout(hideTimer);
     hoverTimer = null;
     tooltip.hidden = true;
   }
   function showTooltip() {
     clearTimeout(hoverTimer);
-    if (disposed || document.hidden || !visible(card) || panelOpen()) return;
+    clearTimeout(hideTimer);
+    if (disposed || suppressFocusTooltip || document.hidden || !visible(card) || panelOpen()
+      || nativeTrigger?.getAttribute('aria-expanded') === 'true') return;
+    renderActions();
     tooltip.hidden = false;
     positionTooltip();
   }
   function scheduleTooltip() {
     clearTimeout(hoverTimer);
+    clearTimeout(hideTimer);
     hoverTimer = setTimeout(showTooltip, 350);
   }
 
+  function scheduleHide() {
+    clearTimeout(hoverTimer);
+    clearTimeout(hideTimer);
+    hideTimer = setTimeout(() => {
+      if (!tooltip.contains(document.activeElement)) hideTooltip();
+    }, 180);
+  }
+
+  // Exact accessible labels cover old builds; the indicator + description covers other locales.
+  // Never select the profile menu or a navigation destination merely because it has an SVG.
+  function findNativeTrigger(container) {
+    return [...(container?.querySelectorAll('button[aria-haspopup="menu"]') ?? [])].find(button =>
+      visible(button) && !button.hasAttribute('data-sidebar-destination') && (
+        /^(usage|用量|使用量)$/i.test(button.getAttribute('aria-label')?.trim() ?? '')
+        || (button.hasAttribute('aria-description') && button.querySelector('[data-transition-phase]'))
+      )) ?? null;
+  }
+
+  const suppressNativeTooltip = event => event.stopPropagation();
+  const onBlur = event => {
+    if (!tooltip.contains(event.relatedTarget) && !eventTarget?.contains(event.relatedTarget)) hideTooltip();
+  };
+  const interceptBackground = event => {
+    if (forwardingNativeAction || !window.__codexRingsideBackground?.togglePanel) return false;
+    event.preventDefault();
+    event.stopPropagation();
+    return true;
+  };
+  const onPointerDown = event => {
+    // Radix opens before click. Stop the left pointerdown as well as the click so
+    // the original menu cannot steal focus or cover the background settings.
+    if (event.button === 0 && interceptBackground(event)) eventTarget?.focus();
+  };
+  const onClick = event => {
+    if (interceptBackground(event)) togglePanel();
+    else hideTooltip();
+  };
+  const onContextMenu = event => {
+    if (!window.__codexRingsideBackground?.togglePanel) return;
+    event.preventDefault();
+    event.stopPropagation();
+    togglePanel();
+  };
+  const onKeyDown = event => {
+    if (event.key === 'ContextMenu' || (event.shiftKey && event.key === 'F10')) return onContextMenu(event);
+    if (!['Enter', ' ', 'ArrowDown'].includes(event.key)) return;
+    if (event.key === 'ArrowDown') {
+      if (nativeTrigger && panelOpen()) window.__codexRingsideBackground?.togglePanel(nativeTrigger);
+      hideTooltip(); // ArrowDown still reaches the native usage-menu handler.
+    } else if (interceptBackground(event)) {
+      if (!event.repeat) togglePanel();
+    }
+  };
+  function bindTarget(target) {
+    if (eventTarget === target) return;
+    const listeners = { mouseenter: scheduleTooltip, mouseleave: scheduleHide, focus: showTooltip,
+      blur: onBlur, pointerdown: onPointerDown, keydown: onKeyDown, click: onClick, contextmenu: onContextMenu,
+      pointerover: suppressNativeTooltip, pointermove: suppressNativeTooltip, focusin: suppressNativeTooltip };
+    for (const [name, handler] of Object.entries(listeners)) {
+      const capture = ['pointerdown', 'keydown', 'click', 'contextmenu'].includes(name);
+      eventTarget?.removeEventListener(name, handler, capture);
+      target?.addEventListener(name, handler, capture);
+    }
+    eventTarget = target;
+  }
+
   function place() {
     if (disposed || !document.body) return;
     if (!style.isConnected) (document.head ?? document.documentElement).appendChild(style);
@@ -219,6 +402,28 @@ function installCodexRingsideCard() {
       rail = nextRail;
       if (rail) resizeObserver.observe(rail);
     }
+    const nextTrigger = findNativeTrigger(rail);
+    if (nativeTrigger !== nextTrigger) {
+      nativeTrigger?.removeAttribute('data-codex-ringside-host');
+      nativeTrigger = nextTrigger;
+      hideTooltip();
+    }
+    if (nativeTrigger) {
+      if (!nativeTrigger.hasAttribute('data-codex-ringside-host')) nativeTrigger.setAttribute('data-codex-ringside-host', '');
+      card.removeAttribute('tabindex');
+      card.setAttribute('role', 'group');
+      card.removeAttribute('aria-haspopup');
+      card.hidden = false;
+      if (card.parentElement !== nativeTrigger) nativeTrigger.append(card);
+      bindTarget(nativeTrigger);
+      if (nativeTrigger.getAttribute('aria-expanded') === 'true') hideTooltip();
+      else if (!tooltip.hidden) positionTooltip();
+      return;
+    }
+    card.tabIndex = 0;
+    card.setAttribute('role', 'button');
+    card.setAttribute('aria-haspopup', 'dialog');
+    bindTarget(card);
     // Own a sibling just before the rail's footer; never move React-owned nodes.
     const footer = rail && [...rail.children]
       .filter(child => child !== card && visible(child) && getComputedStyle(child).position !== 'absolute')
@@ -245,20 +450,26 @@ function installCodexRingsideCard() {
     if (records.some(record => !ownNode(record.target))) schedulePlacement();
   });
   const resizeObserver = new ResizeObserver(schedulePlacement);
-  const onKeyDown = event => {
-    if (event.key === 'Escape') hideTooltip();
-    if (event.key !== 'Enter' && event.key !== ' ') return;
-    event.preventDefault();
-    togglePanel();
+  const onEscape = event => {
+    if (event.key !== 'Escape' || tooltip.hidden) return;
+    if (tooltip.contains(document.activeElement)) {
+      suppressFocusTooltip = true;
+      eventTarget?.focus();
+      suppressFocusTooltip = false;
+    }
+    hideTooltip();
+  };
+  const onOutsidePointer = event => {
+    if (!tooltip.contains(event.target)) hideTooltip();
   };
 
-  observer.observe(document.documentElement, { childList: true, subtree: true });
-  card.addEventListener('mouseenter', scheduleTooltip);
-  card.addEventListener('mouseleave', hideTooltip);
-  card.addEventListener('focus', showTooltip);
-  card.addEventListener('blur', hideTooltip);
-  card.addEventListener('keydown', onKeyDown);
-  card.addEventListener('click', togglePanel);
+  observer.observe(document.documentElement, { childList: true, subtree: true, attributes: true,
+    attributeFilter: ['aria-expanded', 'aria-label', 'aria-description', 'hidden'] });
+  tooltip.addEventListener('mouseenter', () => clearTimeout(hideTimer));
+  tooltip.addEventListener('mouseleave', scheduleHide);
+  tooltip.addEventListener('focusout', onBlur);
+  document.addEventListener('keydown', onEscape);
+  document.addEventListener('pointerdown', onOutsidePointer, true);
   window.addEventListener('resize', schedulePlacement);
   document.addEventListener('visibilitychange', hideTooltip);
 
@@ -274,7 +485,10 @@ function installCodexRingsideCard() {
     status() {
       return {
         version: VERSION,
-        placed: card.parentElement === rail && !card.hidden && visible(card),
+        placed: rail?.contains(card) === true && !card.hidden && visible(card),
+        replacesNative: nativeTrigger?.contains(card) === true,
+        credits: value.credits ?? null,
+        plan: value.plan ?? null,
         rings: value.rings,
         message: value.message,
         stale: value.stale ?? false,
@@ -289,6 +503,10 @@ function installCodexRingsideCard() {
       clearTimeout(placementTimer);
       clearInterval(freshnessTimer);
       hideTooltip();
+      bindTarget(null);
+      nativeTrigger?.removeAttribute('data-codex-ringside-host');
+      document.removeEventListener('keydown', onEscape);
+      document.removeEventListener('pointerdown', onOutsidePointer, true);
       window.removeEventListener('resize', schedulePlacement);
       document.removeEventListener('visibilitychange', hideTooltip);
       card.remove();

package/src/install.cjs

@@ -6,6 +6,7 @@ const { execFileSync } = require('node:child_process');
 const launchd = require('./launchd.cjs');
 const { DEFAULT_APP, isExecutable, resolveCodexBin, resolveNode } = require('./resolve.cjs');
 const { inspectBundle, copyBundle } = require('./standalone.cjs');
+const { normalizeBackground } = require('./background.cjs');
 
 const SWIFTC = '/usr/bin/swiftc';
 const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
@@ -116,7 +117,8 @@ function copyUserData(source, stage, destination) {
   if (typeof config?.image === 'string') {
     const relative = path.relative(source, config.image);
     if (relative && !relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative)) {
-      const name = path.join('user-images', `imported${path.extname(config.image)}`);
+      const name = relative.startsWith(`user-images${path.sep}`)
+        ? relative : path.join('user-images', `imported${path.extname(config.image)}`);
       copyIfPresent(config.image, path.join(stage, name));
       config.image = path.join(destination, name);
       writeJson(file, config);
@@ -124,6 +126,16 @@ function copyUserData(source, stage, destination) {
   }
 }
 
+function seedBackground(stage, destination) {
+  const presets = path.join(stage, 'src/presets');
+  const preset = readJson(path.join(presets, 'default-background.json'));
+  if (preset?.source !== 'image' || preset.image !== 'wallpaper.png') throw new Error('安装包缺少有效的默认背景预设');
+  const image = path.join('user-images', 'default-background.png');
+  fs.mkdirSync(path.join(stage, 'user-images'), { recursive: true, mode: 0o700 });
+  fs.copyFileSync(path.join(presets, preset.image), path.join(stage, image));
+  writeJson(path.join(stage, 'background.json'), normalizeBackground({ ...preset, image: path.join(destination, image) }));
+}
+
 async function install(options = {}) {
   const { current, legacy, backupRoot, repoRoot, services } = { ...defaults, ...options };
   return withLock(current, async () => {
@@ -146,6 +158,9 @@ async function install(options = {}) {
       for (const name of ['package.json', 'LICENSE', 'NOTICE']) fs.copyFileSync(path.join(repoRoot, name), path.join(stage, name));
       if (checked.bundle) copyBundle(repoRoot, stage);
       else await (options.compile ?? compile)(repoRoot, stage);
+      // Older installations may have no background.json because they never enabled a background.
+      // Only a genuinely new install gets the preset; upgrading must retain that implicit opt-out.
+      if (!locations.some(location => fs.existsSync(location.installDir))) seedBackground(stage, current.installDir);
       options.beforeInstall?.();
       fs.mkdirSync(backupRoot, { recursive: true, mode: 0o700 });
       backup = fs.mkdtempSync(path.join(backupRoot, 'install-'));
@@ -156,7 +171,8 @@ async function install(options = {}) {
       for (const location of locations) await services.bootout(location.label);
 
       // Copy after stopping writers. Existing Ringside data takes precedence over legacy data.
-      const dataRoot = fs.existsSync(path.join(current.installDir, 'settings.json')) ? current.installDir : legacy.installDir;
+      const hasCurrentData = ['settings.json', 'background.json'].some(name => fs.existsSync(path.join(current.installDir, name)));
+      const dataRoot = hasCurrentData ? current.installDir : legacy.installDir;
       copyUserData(dataRoot, stage, current.installDir);
       const cooldown = Math.max(...locations.map(location => {
         const value = readJson(path.join(location.installDir, 'state.json'))?.lastAttemptAt;

package/src/limits.cjs

@@ -70,6 +70,8 @@ function mergeSnapshot(current, patch) {
   return {
     ...base,
     ...patch,
+    credits: patch.credits === undefined ? base?.credits ?? null
+      : isRecord(patch.credits) ? { ...base?.credits, ...patch.credits } : null,
     primary: mergeWindow(base?.primary, patch.primary),
     secondary: mergeWindow(base?.secondary, patch.secondary)
   };
@@ -81,7 +83,10 @@ function mergeResponse(current, patch) {
   if (!isRecord(patch)) return null;
   const changedAccount = hasField(patch, 'accountId') && hasField(current, 'accountId')
     && patch.accountId !== current.accountId;
-  const base = changedAccount ? {} : current ?? {};
+  const oldPlan = pickCodexSnapshot(current)?.planType;
+  const newPlan = pickCodexSnapshot(patch)?.planType;
+  const changedPlan = oldPlan && newPlan && oldPlan !== newPlan;
+  const base = changedAccount || changedPlan ? {} : current ?? {};
   const merged = { ...base, ...patch };
   merged.rateLimits = base.rateLimits ?? null;
   if (isRecord(base.rateLimitsByLimitId)) merged.rateLimitsByLimitId = base.rateLimitsByLimitId;
@@ -122,13 +127,33 @@ function formatUsage(response) {
     const percent = remainingPercent(window.usedPercent);
     return { label: labels.short, name: labels.long, percent, tone: tone(percent), resetsAt: formatResetTime(window.resetsAt) };
   });
+  const credits = formatCredits(snapshot?.credits);
   return {
     rings,
-    message: rings.length ? null : '暂时无法读取 Codex 剩余额度',
+    plan: formatPlan(snapshot?.planType),
+    credits,
+    message: rings.length || credits ? null : '暂时无法读取 Codex 剩余额度',
     note: resetCreditsNote(response)
   };
 }
 
+function formatPlan(plan) {
+  if (typeof plan !== 'string' || !plan.trim()) return null;
+  const labels = { free: 'Free', go: 'Go', plus: 'Plus', pro: 'Pro', team: 'Team', business: 'Business',
+    enterprise: 'Enterprise', edu: 'Edu' };
+  return Object.hasOwn(labels, plan) ? labels[plan] : plan;
+}
+
+function formatCredits(credits) {
+  if (!isRecord(credits)) return null;
+  if (credits.unlimited === true) return { unlimited: true, balance: null, label: '不限额' };
+  const raw = credits.balance;
+  if (typeof raw !== 'number' && (typeof raw !== 'string' || !raw.trim())) return null;
+  const balance = Number(raw);
+  if (!Number.isFinite(balance) || balance < 0) return null;
+  return { unlimited: false, balance, label: new Intl.NumberFormat('zh-CN', { maximumFractionDigits: 0 }).format(balance) };
+}
+
 function resetCreditsNote(response) {
   const count = Number(response?.rateLimitResetCredits?.availableCount);
   return Number.isFinite(count) && count > 0 ? `重置卡：${Math.floor(count)} 张可用` : null;
@@ -139,6 +164,9 @@ function unavailable(value, message = '暂时无法读取 Codex 剩余额度，
     ...value,
     message,
     stale: true,
+    credits: null,
+    plan: null,
+    note: null,
     rings: (value?.rings ?? []).map(ring => ({ ...ring, percent: null, tone: 'muted', resetsAt: null }))
   };
 }

package/src/presets/default-background.json

@@ -0,0 +1,14 @@
+{
+  "source": "image",
+  "image": "wallpaper.png",
+  "transparency": 0,
+  "blur": 0,
+  "zoom": 134,
+  "x": 0,
+  "y": 0,
+  "brightness": 100,
+  "contrast": 100,
+  "saturation": 100,
+  "layout": "cover",
+  "crop": null
+}