codex-dream-skin

name	codex-dream-skin
description	Apply, launch, verify, repair, update, or restore a full decorative skin for the Windows Codex desktop app. Use when the user asks for a Codex theme that goes beyond official color settings, wants the pink-purple Dream/Fiona-style interface, needs the skin reapplied after a Codex update, or needs a safe rollback without modifying WindowsApps or app.asar.

Codex Dream Skin

Apply a reversible renderer skin through Chromium DevTools Protocol while launching the official Store-installed Codex executable. Never replace or take ownership of files under WindowsApps.

Workflow

1. Install Node.js 22 or newer, close Codex, then run scripts/install-dream-skin.ps1 once to preserve the user's native appearance settings, seed the bundled 世事宜梦境 (ssyai-dream) theme, and create launch/restore/tray shortcuts.
2. Run scripts/start-dream-skin.ps1. The shortcut asks before restarting an already-open Codex app; CLI callers must explicitly add -RestartExisting.
3. Run scripts/verify-dream-skin.ps1 -ScreenshotPath <absolute-path> after launch. Treat a missing continuous wallpaper, home shell, native composer, sidebar layer, or injection marker as failure. The native suggestion count is responsive and may be two to four.
4. Inspect the screenshot against references/qa-inventory.md. Verify both the home screen and a normal task before signing off.
5. Run scripts/restore-dream-skin.ps1 to remove the live skin, close the saved CDP session, and reopen Codex normally. Add -RestoreBaseTheme to restore only saved appearance keys, -RecoverConfigBackup for explicit byte-for-byte recovery of a damaged config, or -Uninstall to delete shortcuts. A completed config restore archives that install's backup so a later install captures a fresh baseline.

Guardrails

• Preserve the official executable, package signature, user threads, pets, plugins, and authentication state.
• Theme images must be UI-free wallpapers. Never import a README screenshot, fake window, sidebar, card, composer, logo, or text baked into the bitmap.
• Paint one continuous 16:9 wallpaper across the full Codex window. Let the sidebar, main area, header, and composer act as coordinated readability layers; keep the home route expressive and task routes quieter.
• appearance: auto follows the native computed color-scheme first and the system appearance only as a fallback. Image brightness may tune color and composition, but must not flip the user's shell mode; explicit light and dark remain authoritative.
• Attach the "选择项目" treatment to Codex's real project-selector toolbar and keep the current project button clickable; never draw a disconnected replacement.
• Keep decorative layers pointer-events: none and keep real buttons, navigation, and composer above them.
• On app updates, rerun install and launch; the scripts discover the current Appx package dynamically. Saved paths are never trusted for process control unless they still match a registered package identity.
• The default launcher scans for a free port when 9335 is occupied. An explicitly requested occupied port fails closed.
• Keep the injection daemon running for navigation/reload resilience. Its state and logs live under %LOCALAPPDATA%\CodexDreamSkin.
• The watcher registers a generation-checked early payload for connected renderers so reload/navigation can paint the skin before the normal load-event fallback; unsupported CDP targets fall back safely.
• The active theme, saved themes, imported images, pause marker, and tray controls live under %LOCALAPPDATA%\CodexDreamSkin. Reject empty or over-16 MB images before copying or encoding them.
• Every managed-store write rejects junctions and other reparse points in every existing path component. Imports also use the bundled Node metadata parser before copying to reject dimensions above 16384px or 50MP.
• CDP targets must use a same-port loopback WebSocket, belong to the current Store package, retain the launch-time Browser ID, and expose expected Codex renderer markers.
• Loopback prevents LAN exposure, but Chromium CDP has no same-user authentication. Run only trusted local software while the skin is active, and use restore to close the debug session when it is no longer needed.
• Preserve config.toml as strict UTF-8. Never use encoding-dependent whole-file PowerShell reads/writes, silently transcode UTF-16, or overwrite a file that changed after it was read. Ambiguous TOML shapes must fail before writing rather than receive a best-effort rewrite.
• Keep install/start/restore/verify serialized with the per-user operation lock in common-windows.ps1.

Checks

powershell -NoProfile -File tests\run-tests.ps1
node --check scripts\injector.mjs
node --check assets\renderer-inject.js

Resources

• scripts/injector.mjs: CDP connection, renderer injection, verification, screenshot, and removal.
• scripts/common-windows.ps1: Store-package discovery, Node validation, port ownership, state, and process identity safety.
• scripts/config-utf8.ps1: atomic UTF-8 configuration backup, selective restore, and explicit recovery.
• assets/dream-skin.css: full visual layer.
• assets/renderer-inject.js: idempotent DOM integration and cleanup.
• assets/dream-reference.jpg: pure 2560 × 1440 世事宜梦境 abstract wallpaper (procedurally generated, no photos or third-party art) seeded as the default and as a saved theme; it contains no Codex UI.
• assets/theme.json: shared adaptive theme contract for the seeded preset.
• scripts/theme-windows.ps1: persistent active/saved theme store, safe image import, pause state, and preset seeding.
• scripts/tray-dream-skin.ps1: Windows Forms tray for apply, pause, import, save, switch, and complete restore.
• references/qa-inventory.md: required functional and visual signoff coverage.
• references/runtime-notes.md: troubleshooting and update behavior.
• tests/run-tests.ps1: configuration, state, recovery, payload, and CDP validation regression checks.