hyper-windowtint 0.3.5 → 0.3.7

package/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to `hyper-windowtint` will be documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.6] - 2026-05-16
+
+### Changed
+- README now shows a real screenshot of four Hyper windows in four projects
+  (`docs/demo-hero.png`) instead of the placeholder. Image is referenced via
+  full GitHub raw URL so it renders on both github.com and npmjs.com.
+
 ## [0.3.5] - 2026-05-16
 
 ### Fixed

package/README.md

@@ -1,22 +1,23 @@
 # hyper-windowtint
 
-Give every Hyper terminal window/tab a color so you can tell them apart at a glance, while matching tabs that are currently in the same project during the current Hyper session.
+Colors every Hyper window based on the project folder its active tab is in. Open five Hyper windows against five different projects and you can tell them apart at a glance.
 
-Groups each session by its cwd, walked up to the nearest `.git` repo root when possible, then assigns that project group a random color from a curated 12-color palette for the current Hyper run. Restarting Hyper can assign a different color. Shells that emit OSC 7 update the group live when you `cd`. The plugin paints:
+Groups sessions by project root (the nearest `.git` walked up from cwd, or the raw cwd if no git repo is found), then assigns each project a random color from a curated 12-slot palette for the current Hyper run. The plugin prefers palette slots that aren't already taken by other open projects, so the first 12 distinct projects you open in one Hyper session are guaranteed to get 12 distinct colors. Restart Hyper and colors reshuffle. Shells that emit OSC 7 retint live when you `cd` between projects.
 
-- a thin colored border around the window
-- matching accents on tabs
-- a tiny color-name badge in the top-right corner (e.g. `ROSE`, `TEAL`)
+The plugin paints, in the active project's color:
 
-The result: two tabs opened inside the same repo use the same color while they remain in that repo. If one tab moves to a different project and the shell reports cwd changes with OSC 7, that tab gets the other project's color. A different repo or directory gets its own initially random color. If cwd resolution ever fails entirely, the plugin falls back to the session UID, so the tab still gets a color.
+- a thin border around the window
+- a colored top line in the tab bar
+- a subtle gradient tint on the active tab's background
+- an optional uppercase color-name label in the top-right corner (off by default; opt in with `showBadge: true`)
+
+The color signal lives on the window, not on individual tabs. Inside a window with multiple tabs, switching to a tab in a different project retints the whole window; switching between same-project tabs leaves the color unchanged. If cwd resolution ever fails entirely, the plugin falls back to the session UID so the window still gets a color.
 
 ## Screenshots
 
-<!-- TODO: drop a screenshot or short GIF at docs/demo.gif and reference it here.
-     A 5–10s capture of two tabs in different repos plus one `cd` between them
-     sells the plugin better than any prose. -->
+![Four Hyper windows, each in a different project folder, with the plugin giving each its own colored border](https://raw.githubusercontent.com/willytop8/Hyper-WindowTint/main/docs/demo-hero.png)
 
-![demo placeholder](docs/demo.gif)
+Four Hyper windows open against four different projects — each gets its own border color, so a glance at the screen tells you which terminal belongs to which codebase.
 
 ## Install
 
@@ -71,8 +72,8 @@ module.exports = {
   config: {
     windowTint: {
       borderWidth: '3px',      // CSS string
-      showBadge: true,         // tiny color-name pill in the corner
-      glow: true,              // inner glow effect
+      showBadge: false,        // optional uppercase color-name label in the corner (default off)
+      glow: true,              // inner glow effect on the window border
       palette: [               // optional — override the default palette
         { name: 'red',   hex: '#ef4444' },
         { name: 'green', hex: '#22c55e' },
@@ -90,28 +91,27 @@ Palette entries must include both a non-empty `name` and a 6- or 8-digit hex col
 
 **Main process:**
 
-- `decorateSessionOptions(options)` runs when a new session is about to be spawned. Hyper has already resolved both `options.uid` and `options.cwd` by this point. The plugin schedules async cwd resolution through `realpath`, then walks upward looking for a `.git` directory or file; if found, that path is the project group, otherwise the raw cwd is the group. Each group gets an ephemeral random seed that is reused only for the current Hyper main-process lifetime. Result is stashed in a module-scoped `uid → seed` map with a short expiry and cached per cwd so repeat lookups are cheap.
-- `onWindow(win)` wraps `win.rpc.emit` so that immediately before Hyper's own `'session add'` IPC reaches the renderer, the plugin emits a `'windowtint:session-seed'` event with `{uid, seed}`. This avoids a uid→cwd color flicker on session creation. The wrap is idempotent per window, and reload-stable state on `win.rpc` lets the persistent wrapper consume seeds from the newest plugin module after hot reloads.
-- `onUnload` clears the caches.
+- `decorateSessionOptions(options)` runs when a new session is about to be spawned. The plugin schedules async cwd resolution through `realpath`, walks upward looking for a `.git` directory or file (if found, that path is the project group; otherwise the raw cwd is the group), and assigns the group a random seed for the current Hyper main-process lifetime. Seed assignment prefers palette indices not already used by other open projects so the first 12 distinct projects get 12 distinct colors. Caches `cwd → project root`, `project root → seed`, and `uid → seed` (with a short expiry).
+- `onWindow(win)` wraps `win.rpc.emit` so that immediately before Hyper's own `'session add'` IPC reaches the renderer, the plugin emits a `'windowtint:session-seed'` event with `{uid, seed}`. This avoids a uid→project color flicker on session creation. The wrap is idempotent per window, and reload-stable state on `win.rpc` lets the persistent wrapper consume seeds from the newest plugin module after hot reloads.
+- `onUnload` clears the caches and restores the original `win.rpc.emit`.
 
 **Renderer process:**
 
-- `decorateTerm` listens for OSC 7 cwd reports from xterm.js. When a tab changes directories, the renderer asks the main process for that cwd's current project-group seed and retints the tab.
-- `decorateConfig` injects CSS that styles `.hyper_main`, the tab bar, and the badge using CSS custom properties (`--tint-color`, `--tint-glow`, `--tint-tab-bg`, `--tint-name`).
-- A `window.rpc.on('windowtint:session-seed', ...)` listener (installed lazily by the middleware and removed on renderer unload) caches `uid → seed`. If a seed somehow arrives after the session has already been tinted, the active session retints immediately.
-- `getTabProps` and `decorateTab` add a small color accent to each tab.
+- `decorateTerm` registers an OSC 7 handler on each tab's xterm instance. When a shell reports a new cwd, the renderer asks the main process for that cwd's current project-group seed and retints.
+- `decorateConfig` injects CSS that styles `.hyper_main` (window border + glow), the tab bar's top line, and the active tab's background gradient using CSS custom properties (`--tint-color`, `--tint-glow`, `--tint-tab-bg`, `--tint-name`).
+- A `window.rpc.on('windowtint:session-seed', ...)` listener (installed lazily by the middleware and removed on renderer unload) caches `uid → seed`. If a seed arrives after the session has already been tinted, the active session retints immediately.
 - Redux middleware listens for `SESSION_ADD` and `SESSION_SET_ACTIVE`, looks up the cached seed by uid (falls back to the uid itself), maps it to the palette, and writes the resulting color to the root element's CSS variables.
 
 ## Project grouping
 
 Color assignment is intentionally not permanent. The grouping rules are:
 
-- Inside a git repo, every tab currently in that repo shares the same color for the current Hyper run.
-- Outside a git repo, tabs currently in the same cwd share a color for the current Hyper run.
-- After restarting Hyper, those groups can receive different colors.
+- Sessions whose cwd resolves to the same project root (nearest `.git`, or the raw cwd if there's no repo) share a color for the current Hyper run.
+- The window's visible color follows whichever tab is currently active. Switching active tab to a different project retints the window; switching to a same-project tab leaves it alone.
+- After restarting Hyper, projects can receive different colors.
 - If Hyper does not provide a cwd, the plugin falls back to the session UID.
 
-Live updates after `cd` require OSC 7 cwd reporting from the shell. Many modern prompts/shell integrations already emit it; if yours does not, the color updates on new tabs but not after directory changes inside an existing tab.
+Live retinting after `cd` requires OSC 7 cwd reporting from the shell. Many modern prompts/shell integrations already emit it; if yours does not, the color is set when a tab is created and stays put until you switch active tabs or restart Hyper.
 
 The plugin uses two custom Hyper RPC event names internally: `windowtint:session-seed` and `windowtint:cwd-change`. This depends on Hyper's current runtime RPC passthrough for arbitrary event names.
 
@@ -160,10 +160,11 @@ osc7_cwd
 
 ## Roadmap
 
-1. **Optional color labels.** Expose the current in-memory project group color so helper scripts can find matching windows without making the assignment permanent.
-2. **Admin/sudo override.** Force red for elevated shells (steal this from `hyperborder`'s `adminBorderColors`).
-3. **OKLCH-spaced palette generator** for any N colors with guaranteed perceptual distinctness.
-4. **Tests.** Pure-function tests for `hashToIndex`, `parseOsc7Cwd`, `readUserConfig`, and `withAlpha`.
+1. **Per-tab outlines for inactive tabs.** Today the color signal is window-level (whichever tab is active). The original plan was to also outline each tab in the tab bar with its own project color, but Hyper 3.x's Tab component drops most plugin-injected props, so it would need a renderer-side DOM observer approach. Deferred until that's worth building.
+2. **Optional color labels.** Expose the current in-memory project group color so helper scripts can find matching windows without making the assignment permanent.
+3. **Admin/sudo override.** Force red for elevated shells (steal this from `hyperborder`'s `adminBorderColors`).
+4. **OKLCH-spaced palette generator** for any N colors with guaranteed perceptual distinctness.
+5. **Tests.** Pure-function tests for `hashToIndex`, `parseOsc7Cwd`, `readUserConfig`, and `withAlpha`.
 
 ## License
 

package/index.js

@@ -4,22 +4,21 @@
  * hyper-windowtint
  *
  * Assigns each Hyper project group an ephemeral random color from a curated
- * palette, then paints the window border, tab accent, and (optionally) a
- * small corner badge with the color's name.
+ * 12-color palette, then paints the window border, the tab bar's top line,
+ * and the active tab's background gradient in that color. Optionally shows
+ * the color's name in the top-right corner (`config.windowTint.showBadge`).
  *
- * v0.1: seeded color by session UID (each new tab got a stable color for
- * its lifetime).
- *
- * v0.2: groups sessions by the project root of the session's cwd, then gives
- * each project root a random color seed for the current Hyper main-process
- * lifetime. Two open terminals in the same project match; restarting Hyper
- * can assign that project a different color. The project root is found by
- * walking up from cwd to the nearest `.git`; if none, the raw cwd is used.
- * Falls back to session UID if cwd never arrives.
+ * Groups sessions by the project root of the session's cwd, walking up to
+ * the nearest `.git` directory or file; if none, the raw cwd is the group.
+ * Each project root gets a random seed for the current Hyper main-process
+ * lifetime — seeds prefer palette slots not already in use by other open
+ * projects, so the first 12 distinct projects get 12 distinct colors.
+ * Restarting Hyper reassigns colors. Falls back to session UID if cwd
+ * resolution fails entirely.
  *
  * This module is loaded in BOTH Hyper processes. decorateSessionOptions /
  * onWindow / onUnload run in main; decorateConfig / middleware / decorateTerm
- * / decorateTab / getTabProps run in renderer. The two sides communicate via
+ * / onRendererUnload run in renderer. The two sides communicate via
  * win.rpc — we piggyback a `windowtint:session-seed` event onto the normal
  * `session add` rpc emit so the renderer has the project-group seed before
  * SESSION_ADD reaches the Redux store (no uid→project color flicker).
@@ -81,7 +80,7 @@ function withAlpha(hex, alpha) {
 let userOpts = {
   palette: DEFAULT_PALETTE,
   borderWidth: '3px',
-  showBadge: true,
+  showBadge: false,
   glow: true,
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyper-windowtint",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "Give Hyper terminal tabs distinct color tints, matching tabs from the same project during the current Hyper session.",
   "main": "index.js",
   "files": [