@kitfunso/aura 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kitfunso
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,179 @@
+# aura
+
+[![npm](https://img.shields.io/npm/v/%40kitfunso%2Faura)](https://www.npmjs.com/package/@kitfunso/aura)
+[![license: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+![platform: Windows 11](https://img.shields.io/badge/platform-Windows%2011-blue)
+![runtime dependencies: 0](https://img.shields.io/badge/runtime%20deps-0-brightgreen)
+
+Color identity for terminal windows. Repo = hue, branch = shade. Any shell
+sitting in a repo gets the color, so Claude Code, Codex, Aider, opencode and a
+plain git prompt all get one from the same place. With 10+ windows open, you
+find the one you want by color, not by reading.
+
+![Demo: gray terminal windows get per-repo colors, branches get shades, and aura-overlay rings any window](https://raw.githubusercontent.com/kitfunso/aura/master/assets/demo.gif)
+
+```
+npx @kitfunso/aura install --shell powershell
+```
+
+![Live QA: pink tab + tinted pane + pink border for the bitfall session, blue tab for the aura session](https://raw.githubusercontent.com/kitfunso/aura/master/docs/img/live-qa.png)
+
+One Windows Terminal window, three Claude Code sessions: the active bitfall
+session got a pink tab, a pink-tinted pane, and a pink window border; the aura
+session's tab is blue. Nothing was configured by hand.
+
+## What it does
+
+When a window enters a repo, aura:
+
+1. **Colors the tab** (Windows Terminal, iTerm2) with the repo's color. In
+   tabbed windows this is the primary identity surface.
+2. **Tints the pane background** with a dark shade of the same color (OSC 11).
+3. **Paints the real window frame** (border + title bar) via the Windows 11
+   DWM API. In stock tabbed Windows Terminal only a 1 px border shows (WT
+   draws its own tab strip over the title bar); on floating windows and
+   conhost-style terminals the full caption shows.
+4. **Sets the title** to `repo · branch` (best-effort; Claude Code itself
+   keeps the latest prompt in the title, which covers "what am I doing here").
+   A session colored by its own tab name is the exception: aura writes no title
+   there, so the name it read stays put.
+
+Three callers, one core. Your shell calls `aura mark` from its prompt when the
+directory changed. Claude Code calls the same core from a hook, which colors a
+session the moment it starts. Any script can call `aura mark --cwd <dir>` when
+it knows a window moved.
+
+Colors are deterministic: the same repo maps to the same hue on every machine,
+every restart. Branches get discrete shades of the repo hue; main/master is
+the base shade. With no repo, no tag and no tab name there is no color: the
+window keeps your terminal's own default.
+
+So a color means the window is in that repo, or wears that name. It does not
+mean an agent is running in it, and that is the trade for one mechanism every
+tool gets for free.
+
+## When the folder is not the project
+
+Agents get launched from a home folder as often as from a checkout, and a home
+folder names no project. Six tabs on six projects then share one path that
+names none of them. So identity has two more sources.
+
+**Your tab name.** Rename a Windows Terminal tab and aura colors it by that
+name, deterministically, the same way it colors a repo. Nothing to run. Tabs you
+have not renamed are left alone, because aura only takes a title that behaves
+like a name: under 40 characters, no path in it, not a shell's own default, and
+unchanged across two prompts. An agent's title moves with every prompt, so it
+never qualifies. A session colored by its tab name keeps that name, because
+writing a new title would change the color it was just read from.
+
+**A tag**, when you want a session to wear a specific repo's color:
+
+```
+aura tag ~/hippo      # this session is hippo, wherever it sits
+aura tag              # print the current tag
+aura tag --clear      # back to the working directory
+```
+
+A tag outranks both the working directory and the tab name. Run it from inside
+an agent and it tags that agent's own session. The key comes
+from `CLAUDE_CODE_SESSION_ID`, or from `AURA_SESSION`, which the shell snippet
+exports to every process the window starts. The color lands at once, through
+the same path a hook paints on, so an agent with no prompt hook still gets one.
+A tag lives and dies with its session, so nothing outlives the window that set it.
+
+## Install
+
+```
+npx @kitfunso/aura install --shell powershell
+```
+
+That wraps your PowerShell prompt, so every window in a repo gets the color
+whatever is running inside it. `--shell bash` and `--shell zsh` write the same
+thing into `~/.bashrc` / `~/.zshrc`. The snippet wraps your existing prompt
+instead of replacing it, so posh-git, oh-my-posh and Starship keep working, and
+it lands between two markers so a re-run replaces it instead of stacking.
+
+Claude Code also has a native hook, which colors a session the moment it starts
+rather than at its next prompt:
+
+```
+npx @kitfunso/aura install
+```
+
+That merges two hook entries (SessionStart, UserPromptSubmit) into
+`~/.claude/settings.json`. Both installs together are fine: the shell path does
+nothing when the directory has not changed. From a checkout, swap
+`npx @kitfunso/aura` for `node bin/aura.js`.
+
+On the first install the target file is copied to `<file>.aura-bak`. That backup
+holds your pre-aura content and later runs never overwrite it. Uninstall takes
+back out exactly what install put in:
+
+```
+npx @kitfunso/aura uninstall --shell powershell
+npx @kitfunso/aura uninstall
+```
+
+Colors appear in new shells and new Claude Code sessions. Point either install
+at a different file with `--profile <path>` or `--settings <path>`; the backup
+lands next to that file.
+
+Requirements: Windows 11 build 22000+ for the frame color, Windows Terminal
+1.15+ for the tab color, Node.js. Tint + title degrade gracefully elsewhere.
+No runtime dependencies, no network calls, everything local.
+
+The frame paint fires in terminals that mark their environment: Windows
+Terminal (verified), wezterm, alacritty, and ghostty (per their docs,
+best-effort). Plain conhost sets no marker and gets no paint.
+
+## How it works (and the traps we measured)
+
+The design is shaped by four findings, all measured live on 2026-08-30
+(details in `docs/ARCHITECTURE.md` Known Risks):
+
+- **Claude Code hooks get their own hidden console on Windows.** A hook's
+  `CONOUT$` write succeeds but is invisible. Visible delivery attaches to the
+  topmost console-attached ancestor (the tab's real console) from the
+  PowerShell adapter, once per session or color change. The per-prompt path
+  spawns nothing and stays at ~70 ms.
+- **Windows Terminal runs every window in one process**, so PID matching
+  cannot identify a window. The frame paint takes `GetForegroundWindow()` at
+  prompt time, allowlisted to terminal processes, and caches the HWND.
+- **Claude Code rewrites the terminal title continuously**, so a
+  nonce-title handshake is impossible and aura's title is best-effort.
+- **Tab color needs the DECAC escape** (`OSC 4;264;rgb:RR/GG/BB` +
+  `ESC[2;15;264,|`). Slot 264 sits above the 256-color text palette, so your
+  text keeps its own colors; aura only moves the background and the frame.
+
+The shell path dodges the first of those: a shell prompt owns a visible
+console, so `aura mark --write` puts the escapes there itself and needs no
+PowerShell hop for them. The frame paint still spawns the adapter, once per
+window and color.
+
+Repo layout: `src/color.js` (the pure color contract), `src/mark.js` (the core
+every caller goes through), `src/tag.js` (the session tag), `src/hook.js` and
+`bin/aura.js` (the two callers),
+`src/shell/` (the prompt snippets), `src/tty.js` (terminal device),
+`src/adapters/frame-win.ps1` (all Win32 code), `src/install.js` (installer).
+Tests, from the repo root:
+
+```
+npm test
+```
+
+## Cross-platform
+
+The core is OS-neutral; only the tty device path and the frame adapter vary.
+macOS/Linux get tint + title (and iTerm2 tab color) from the same code today;
+frame adapters for them are planned (macOS needs an overlay window, there is
+no API to recolor another app's frame). See the support matrix in
+`docs/ARCHITECTURE.md`.
+
+## Lane B (built)
+
+The cross-app overlay lives at
+[aura-overlay](https://github.com/kitfunso/aura-overlay): click-through
+colored rings around any window, same repo = hue contract, hotkey tagging for
+non-terminal windows. `src/color.js` is byte-identical in both repos; changes
+flow from here to there, never back. This repo only guarantees the contract
+stays pure. Spike evidence that green-lit it: `docs/LANE-B.md`.

package/bin/aura.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+"use strict";
+// The agent-neutral entry point: whoever knows the working directory changed
+// calls "aura mark". Unlike the hook it may print escapes on stdout, because
+// its caller owns a visible console. Design: docs/ARCHITECTURE.md.
+const { mark } = require("../src/mark.js");
+const { writeToTerminal } = require("../src/tty.js");
+const { shellSnippet, SHELLS } = require("../src/shell/init.js");
+const {
+  sessionKey, readTag, writeTag, resolveTarget, inTerminalSession,
+} = require("../src/tag.js");
+
+const USAGE = [
+  "usage: aura mark [--write] [--cwd <dir>] [--session <id>] [--title <text>]",
+  "       aura tag [<dir>] [--clear] [--session <id>]",
+  "       aura install [--shell powershell|bash|zsh] [--settings <path>] [--profile <path>]",
+  "       aura uninstall [same flags as install]",
+  "       aura shell-init [--shell powershell|bash|zsh]",
+  "",
+  "  mark        print the escape sequences for <dir>, and paint the window frame.",
+  "              --write sends them to the terminal device instead, falling back",
+  "              to stdout when that device is not reachable.",
+  "  tag         color this session as <dir> instead of the working directory,",
+  "              for an agent launched somewhere that names no project. It paints",
+  "              the window at once, so an agent with no prompt hook still gets a",
+  "              color. With no argument it prints the tag. --clear goes to cwd.",
+  "  install     with --shell, wire that shell's prompt. Without it, register the",
+  "              Claude Code hooks in ~/.claude/settings.json.",
+  "  uninstall   take back out what install put in.",
+  "  shell-init  print the prompt snippet to source from a shell profile.",
+].join("\n");
+
+function argValue(flag) {
+  const index = process.argv.indexOf(flag);
+  return index !== -1 && process.argv[index + 1] ? process.argv[index + 1] : null;
+}
+
+function commandMark() {
+  const toTerminal = process.argv.indexOf("--write") !== -1;
+  let ttyTarget = null;
+  const result = mark({
+    cwd: argValue("--cwd") || process.cwd(),
+    // The pid alone is not unique for long: the shell snippets add a start second.
+    sessionId: argValue("--session") || "shell-" + process.ppid,
+    eventName: "prompt",
+    promptText: argValue("--title"),
+    sink: function (escapes) {
+      if (toTerminal) ttyTarget = writeToTerminal(escapes);
+      return ttyTarget || "stdout";
+    },
+    redeliverVt: false,
+  });
+  if (!ttyTarget) process.stdout.write(result.escapes);
+}
+
+function commandShellInit() {
+  const shell = argValue("--shell") || (process.platform === "win32" ? "powershell" : "bash");
+  const snippet = shellSnippet(shell, __filename);
+  if (!snippet) {
+    console.error("aura: unknown shell " + shell + ". Known: " + SHELLS.join(", "));
+    process.exit(1);
+  }
+  process.stdout.write(snippet);
+}
+
+// A full-screen agent has no prompt to fire after this, so the tag would sit in
+// state unread. The escapes ride the adapter, the way a hook's do.
+function paintTagged(sessionId) {
+  if (!inTerminalSession(process.env)) return;
+  try {
+    mark({
+      cwd: process.cwd(),
+      sessionId,
+      eventName: "prompt",
+      sink: writeToTerminal,
+      redeliverVt: true,
+    });
+  } catch (err) { /* the tag is written; a failed paint must not fail the CLI */ }
+}
+
+function commandTag() {
+  const id = sessionKey(process.env, argValue("--session"));
+  const clear = process.argv.indexOf("--clear") !== -1;
+  const target = process.argv[3] && process.argv[3].charAt(0) !== "-" ? process.argv[3] : null;
+  if (!target && !clear) {
+    const current = readTag(id);
+    console.log(id + ": " + (current || "no tag, using the working directory"));
+    return 0;
+  }
+  const resolved = clear ? null : resolveTarget(target, process.cwd());
+  if (!clear && !resolved) {
+    console.error("aura: no such directory: " + target);
+    return 1;
+  }
+  if (!writeTag(id, resolved)) {
+    console.error("aura: state file is busy, nothing written");
+    return 1;
+  }
+  paintTagged(id);
+  console.log(clear ? id + ": tag cleared" : id + ": tagged " + resolved);
+  return 0;
+}
+
+const command = process.argv[2];
+if (command === "mark") {
+  // Rule 6: this runs on a prompt path, so a broken aura prints nothing.
+  try { commandMark(); } catch (err) { /* fail silent */ }
+  process.exit(0);
+}
+if (command === "tag") {
+  process.exit(commandTag());
+}
+if (command === "shell-init") {
+  commandShellInit();
+  process.exit(0);
+}
+if (command === "install" || command === "uninstall") {
+  require("../src/install.js").run(command === "uninstall");
+  process.exit(0);
+}
+console.error(USAGE);
+process.exit(command === "--help" || command === "-h" ? 0 : 1);

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@kitfunso/aura",
+  "version": "0.1.0",
+  "description": "Color identity for Claude Code terminal windows: repo = hue, branch = shade, latest prompt in the title.",
+  "license": "MIT",
+  "author": "kitfunso",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kitfunso/aura.git"
+  },
+  "homepage": "https://github.com/kitfunso/aura#readme",
+  "bugs": {
+    "url": "https://github.com/kitfunso/aura/issues"
+  },
+  "bin": {
+    "aura": "bin/aura.js"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node scripts/check-comments.js && node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "claude-code",
+    "terminal",
+    "colors",
+    "windows-terminal",
+    "hooks"
+  ]
+}

package/src/adapters/frame-win.ps1

@@ -0,0 +1,164 @@
+# aura frame adapter, Windows 11 build 22000+. Paints one window frame and
+# delivers the VT payload into the tab's real console. Design: docs/ARCHITECTURE.md.
+# Prints the resolved HWND on stdout first, or 0.
+param(
+    [Parameter(Mandatory=$true)][string]$FrameColor,  # RRGGBB, no leading #
+    [long]$Hwnd = 0,
+    [switch]$NoPaint,          # resolve and report the HWND, but write no color
+    [switch]$QueryTitle,       # print the terminal window title and exit; writes nothing
+    [switch]$Reset,            # write DWMWA_COLOR_DEFAULT: back to the system frame
+    [string]$SkipHwnds = "",   # -Reset only: comma-joined HWNDs a repo session owns
+    [string]$VtB64 = "",
+    [int]$VtDelayMs = 0,       # >0: hand targets to a delayed hidden writer instead of writing now
+    [string]$VtTargets = "",   # delayed-writer mode: comma-joined attach-target PIDs, topmost first
+    [string]$StateFile = "",   # delayed-writer mode: state.json path for the delivery skip check
+    [string]$SessionId = "",   # delayed-writer mode: which session to check
+    [string]$VtSig = ""        # delayed-writer mode: signature a prompt would have recorded
+)
+$ErrorActionPreference = "Stop"
+
+Add-Type -TypeDefinition @"
+using System;
+using System.Runtime.InteropServices;
+
+public static class AuraFrame {
+    [DllImport("user32.dll")] public static extern IntPtr GetForegroundWindow();
+    [DllImport("user32.dll")] public static extern uint GetWindowThreadProcessId(IntPtr h, out uint pid);
+    [DllImport("user32.dll", CharSet=CharSet.Unicode)] public static extern int GetWindowText(IntPtr h, System.Text.StringBuilder buf, int max);
+    [DllImport("dwmapi.dll")] public static extern int DwmSetWindowAttribute(IntPtr hwnd, int attr, ref int val, int size);
+    [DllImport("kernel32.dll")] static extern bool FreeConsole();
+    [DllImport("kernel32.dll")] static extern bool AttachConsole(uint pid);
+    [DllImport("kernel32.dll", CharSet=CharSet.Unicode)] static extern IntPtr CreateFileW(string name, uint access, uint share, IntPtr sec, uint disp, uint flags, IntPtr tmpl);
+    [DllImport("kernel32.dll")] static extern bool WriteFile(IntPtr h, byte[] buf, uint n, out uint written, IntPtr overlapped);
+    [DllImport("kernel32.dll")] static extern bool GetConsoleMode(IntPtr h, out uint mode);
+    [DllImport("kernel32.dll")] static extern bool SetConsoleMode(IntPtr h, uint mode);
+    [DllImport("kernel32.dll")] static extern bool CloseHandle(IntPtr h);
+
+    public static bool WriteVt(uint pid, byte[] bytes) {
+        FreeConsole();
+        if (!AttachConsole(pid)) { return false; }
+        IntPtr h = CreateFileW("CONOUT$", 0xC0000000, 3, IntPtr.Zero, 3, 0, IntPtr.Zero);
+        if (h == new IntPtr(-1)) { FreeConsole(); return false; }
+        uint mode;
+        if (GetConsoleMode(h, out mode)) { SetConsoleMode(h, mode | 0x4); }
+        uint written;
+        bool ok = WriteFile(h, bytes, (uint)bytes.Length, out written, IntPtr.Zero);
+        CloseHandle(h);
+        FreeConsole();
+        return ok;
+    }
+}
+"@
+
+if ($VtTargets -ne "") {
+    # Delayed writer: the parent resolved the targets while the ancestor chain
+    # was alive. Skip if a prompt already delivered a newer payload.
+    if ($VtDelayMs -gt 0) { Start-Sleep -Milliseconds $VtDelayMs }
+    if ($StateFile -ne "" -and $SessionId -ne "" -and (Test-Path -LiteralPath $StateFile)) {
+        try {
+            $state = Get-Content -Raw -LiteralPath $StateFile | ConvertFrom-Json
+            $sess = $state.sessions.$SessionId
+            if ($sess -and $VtSig -ne "" -and $sess.vtSent -eq $VtSig) { exit 0 }
+        } catch {}
+    }
+    try {
+        $bytes = [Convert]::FromBase64String($VtB64)
+        foreach ($target in ($VtTargets -split ",")) {
+            if ([AuraFrame]::WriteVt([uint32]$target, $bytes)) { break }
+        }
+    } catch {}
+    exit 0
+}
+
+$allowedProcs = @("WindowsTerminal", "OpenConsole", "conhost", "wezterm-gui", "alacritty", "ghostty")
+
+function Resolve-TerminalWindow {
+    $fg = [AuraFrame]::GetForegroundWindow()
+    $procId = [uint32]0
+    [void][AuraFrame]::GetWindowThreadProcessId($fg, [ref]$procId)
+    $procName = ""
+    try { $procName = (Get-Process -Id $procId -ErrorAction Stop).ProcessName } catch {}
+    if ($allowedProcs -contains $procName) { return $fg }
+    return [IntPtr]::Zero
+}
+
+if ($QueryTitle) {
+    # In Windows Terminal this is the ACTIVE TAB's name. The cached handle wins,
+    # so a foreground window belonging to another app cannot answer for this one.
+    $titleWindow = [IntPtr]::Zero
+    if ($Hwnd -ne 0) { $titleWindow = [IntPtr]$Hwnd } else { $titleWindow = Resolve-TerminalWindow }
+    if ($titleWindow -ne [IntPtr]::Zero) {
+        $buffer = New-Object System.Text.StringBuilder -ArgumentList 256
+        [void][AuraFrame]::GetWindowText($titleWindow, $buffer, $buffer.Capacity)
+        Write-Output $buffer.ToString()
+    }
+    exit 0
+}
+
+$target = [IntPtr]::Zero
+if ($Hwnd -ne 0) { $target = [IntPtr]$Hwnd } else { $target = Resolve-TerminalWindow }
+
+if ($target -ne [IntPtr]::Zero) {
+    # The resolved window may differ from the cached one, so the skip list is
+    # checked here: a repo session's color outranks a bare shell's reset.
+    $skip = $false
+    if ($Reset -and $SkipHwnds -ne "") {
+        $skip = ($SkipHwnds -split "," | Where-Object { $_ -eq ([int64]$target).ToString() }).Count -gt 0
+    }
+    if ($Reset -and -not $skip) {
+        $default = -1  # DWMWA_COLOR_DEFAULT (0xFFFFFFFF)
+        [void][AuraFrame]::DwmSetWindowAttribute($target, 34, [ref]$default, 4)
+        [void][AuraFrame]::DwmSetWindowAttribute($target, 35, [ref]$default, 4)
+    }
+    # -NoPaint callers want the handle only.
+    if (-not $NoPaint) {
+        # COLORREF is 0x00BBGGRR.
+        $r = [Convert]::ToInt32($FrameColor.Substring(0, 2), 16)
+        $g = [Convert]::ToInt32($FrameColor.Substring(2, 2), 16)
+        $b = [Convert]::ToInt32($FrameColor.Substring(4, 2), 16)
+        $colorref = ($b -shl 16) -bor ($g -shl 8) -bor $r
+        [void][AuraFrame]::DwmSetWindowAttribute($target, 34, [ref]$colorref, 4)  # DWMWA_BORDER_COLOR
+        [void][AuraFrame]::DwmSetWindowAttribute($target, 35, [ref]$colorref, 4)  # DWMWA_CAPTION_COLOR
+    }
+    Write-Output ("" + [int64]$target)
+} else {
+    Write-Output "0"
+}
+
+if ($VtB64 -ne "") {
+    try {
+        $bytes = [Convert]::FromBase64String($VtB64)
+        # One bulk pid->ppid query, then walk this process's ancestry.
+        $parentOf = @{}
+        foreach ($p in Get-CimInstance Win32_Process -Property ProcessId, ParentProcessId) {
+            $parentOf[[uint32]$p.ProcessId] = [uint32]$p.ParentProcessId
+        }
+        $chain = @()
+        $cur = [uint32]$PID
+        for ($i = 0; $i -lt 12; $i++) {
+            if (-not $parentOf.ContainsKey($cur)) { break }
+            $up = $parentOf[$cur]
+            if ($up -eq 0 -or -not $parentOf.ContainsKey($up)) { break }
+            $chain += $up
+            $cur = $up
+        }
+        # Topmost first: the highest attachable ancestor owns the tab console;
+        # nearer ancestors (the hook's own node/cmd) hold the hidden one.
+        [array]::Reverse($chain)
+        if ($VtDelayMs -gt 0) {
+            # An immediate write races the TUI init, so hand off to a grandchild.
+            if ($chain.Length -gt 0) {
+                $argList = @("-NoProfile", "-ExecutionPolicy", "Bypass", "-File", $PSCommandPath,
+                    "-FrameColor", $FrameColor, "-VtB64", $VtB64,
+                    "-VtTargets", ($chain -join ","), "-VtDelayMs", $VtDelayMs)
+                if ($StateFile -ne "") { $argList += @("-StateFile", $StateFile) }
+                if ($SessionId -ne "") { $argList += @("-SessionId", $SessionId) }
+                Start-Process -WindowStyle Hidden -FilePath "powershell.exe" -ArgumentList $argList
+            }
+        } else {
+            foreach ($ancestor in $chain) {
+                if ([AuraFrame]::WriteVt($ancestor, $bytes)) { break }
+            }
+        }
+    } catch {}
+}

package/src/color.js

@@ -0,0 +1,48 @@
+"use strict";
+
+// THE COLOR CONTRACT. Lane B inherits this file unchanged. Pure: no I/O.
+// Mapping changes are breaking changes (CLAUDE.md rule 7); read
+// docs/ARCHITECTURE.md "The Color Contract" first.
+
+const SHADE_COUNT = 4;
+const BASE_BRANCHES = new Set(["main", "master"]);
+
+// Frame lightness per shade step. Spread wide so shades stay tellable-apart.
+const FRAME_LIGHTNESS = [50, 63, 39, 72];
+// Tint lightness per shade step. All inside the dark, readable band.
+const TINT_LIGHTNESS = [13, 16, 10, 19];
+
+function fnv1a(text) {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < text.length; i++) {
+    hash ^= text.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash >>> 0;
+}
+
+function hslToHex(hue, saturationPct, lightnessPct) {
+  const s = saturationPct / 100;
+  const l = lightnessPct / 100;
+  const k = (n) => (n + hue / 30) % 12;
+  const a = s * Math.min(l, 1 - l);
+  const channel = (n) => l - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
+  const toHex = (v) => Math.round(v * 255).toString(16).padStart(2, "0");
+  return "#" + toHex(channel(0)) + toHex(channel(8)) + toHex(channel(4));
+}
+
+// repoId: origin remote URL, else repo root path, else cwd (non-repo session).
+// branch: git branch name, or null outside a repo.
+function colorsFor({ repoId, branch }) {
+  const hue = fnv1a(String(repoId)) % 360;
+  const isBase = branch === null || branch === undefined || branch === "" || BASE_BRANCHES.has(branch);
+  const shadeIndex = isBase ? 0 : 1 + (fnv1a(String(branch)) % (SHADE_COUNT - 1));
+  return {
+    hue,
+    shadeIndex,
+    tintHex: hslToHex(hue, 35, TINT_LIGHTNESS[shadeIndex]),
+    frameHex: hslToHex(hue, 70, FRAME_LIGHTNESS[shadeIndex]),
+  };
+}
+
+module.exports = { colorsFor, fnv1a, hslToHex };