codex-ringside 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # 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.

package/README.md

@@ -104,6 +104,8 @@ Reinstalling preserves observe mode; `--observe` explicitly disables startup han
 
 ## Background controls
 
+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 |

package/README.zh-CN.md

@@ -113,6 +113,8 @@ npx codex-ringside@latest install
 
 ## 自定义背景
 
+首次安装会自动应用安装包内置的壁纸：图片来源、铺满布局、缩放 134%、左上对齐、透明度和模糊均为 0，亮度、对比度和饱和度均为 100%，不裁剪。图片保存在插件自己的目录内，无需另行下载或选择。升级、重装和从 Codex Plus 迁移都会保留已有图片和设置；之前未启用背景的用户也会继续保持关闭。可随时在面板中换图、调整参数或选择“关闭”。窗口比例不同会影响取景，客户端的浅色／深色模式保持用户自己的选择。
+
 直接点击侧栏圆环打开原有背景设置面板，聚焦后按 Enter 或空格也可以打开。悬停面板中的“背景设置”、右键和 Shift+F10 仍可使用。官方用量菜单通过悬停面板中的“用量菜单”打开，也可以聚焦圆环后按向下键；没有兼容的官方按钮时，这个菜单入口隐藏。先选来源，再用效果调外观，所有调节都立即生效。
 
 面板顶部还能切换 Codex 的**外观模式**：跟随系统、浅色、深色。它和设置页的“模式”是同一个设置，改动会保存，并在两边同步。这里用的是 Codex 内部的设置函数，找不到时控件自动隐藏。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-ringside",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Usage rings and customizable backgrounds for the Codex desktop app. Unofficial macOS add-on.",
   "license": "MIT",
   "type": "commonjs",
@@ -49,6 +49,8 @@
     "bin/*.cjs",
     "src/**/*.cjs",
     "src/**/*.js",
+    "src/presets/default-background.json",
+    "src/presets/wallpaper.png",
     "native/bridge.swift",
     "README*.md",
     "LICENSE",

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/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
+}