@litfamily/litclaude 1.0.12 → 1.0.13

package/docs/hooks.md

@@ -103,7 +103,7 @@ silent no-op for callers that still invoke it directly.
 | Event | Runner | Purpose |
 | --- | --- | --- |
 | `SessionStart` | `plugins/litclaude/bin/litclaude-hook.js session-start` | Runs the bounded foreground automatic-update barrier on a fresh session, discovers repo-local rule files, names the newest valid `plans/<slug>.md`, and on `source: compact` spends one of two durable re-injection reservations at reduced caps. |
-| `UserPromptSubmit` | `plugins/litclaude/bin/litclaude-hook.js user-prompt-submit` | Detects prompt routes and injects workflow context; independently delivers static rules not already recorded for this session. |
+| `UserPromptSubmit` | `plugins/litclaude/bin/litclaude-hook.js user-prompt-submit` | Detects prompt routes and injects workflow context; independently delivers static rules not already recorded for this session; with `LITCLAUDE_JEV=1` and `TYPESAFE_API_KEY` set, adds at most one Jev skill hint line to an unrouted turn. |
 | `PreToolUse` | `plugins/litclaude/bin/litclaude-hook.js pre-tool-use` | Enforces semantic action/root grants before Write, Edit, MultiEdit, NotebookEdit, Bash, Agent, and bounded read tools execute; denies supported reader-facing text writes with a humanizer block-tier finding. |
 | `PostToolUse` | `plugins/litclaude/bin/litclaude-hook.js post-tool-use` | Names the post-edit checks the edit actually earned, injects any glob-scoped rule matching the edited paths, and checks successfully created DOCX/PPTX/PDF files for humanizer findings, including paths reported by Bash output. |
 | `Stop` | `plugins/litclaude/bin/litclaude-hook.js stop` | Holds a lit-plan turn with no persisted plan and a lit workflow turn that edited interface files without a clean interface-probe run (each at most twice per turn), emits bounded start-work continuation on new progress, otherwise applies the opt-in litgoal autoloop gate. |
@@ -185,6 +185,83 @@ the host-owned SessionStart hook is the lifecycle exception to the TTY check.
 The detached registry cache refresh described in the update-notifier section is
 advisory and never performs an install.
 
+### Jev skill hint (optional)
+
+`plugins/litclaude/lib/jev-skill-hint.mjs` is off unless both `LITCLAUDE_JEV=1` and a
+non-empty `TYPESAFE_API_KEY` are in the hook's environment. The key is read from the
+environment only; the hook never reads a key file and never writes, prints, or traces the key.
+
+A turn is eligible only when the deterministic router chose no route, the prompt is not a
+slash command, a `!` shell line, or a host-expanded command, it names no skill (a
+`litclaude:` name or a hyphenated or `lit`-prefixed catalog ID), and at least four
+non-space characters remain after host notification blocks are removed. The exact bare
+routes, the trusted start-work resume, and the diagnostic literal prompt are never eligible.
+
+An eligible turn sends one `POST https://api.typesafe.ai/v1/systemone` with no retry and
+`redirect: "error"`, so a redirect fails the request instead of being followed. The body holds
+only `model`, `state`, and `questions`. `state` is built from the first 8,000 characters of the
+prompt: the key's literal value becomes `[secret]`, home paths (`/Users/<name>`,
+`/home/<name>`, `C:\Users\<name>`, with or without a trailing slash) become `~`, e-mail
+addresses become `[email]`, and token shapes (`sk-`, `sk-ant-`, `ghp_`, `gho_`,
+`github_pat_`, `npm_`, `apikey_`, `xox[abprs]-`, `AKIA`, `AIza`, JWTs, PEM blocks, any
+run of 32 or more `[A-Za-z0-9+/_-]` characters with optional `=` padding, and the plugin's
+shared credential shapes) become `[secret]`. Only then is it cut to 2,000 characters, and a
+run of 8 or more token characters left at the cut also becomes `[secret]`. Anything in the
+prompt without a token shape, such as a hostname, a customer name, or a password that is not
+written as `password=…`, is sent as written. `questions.which` is a choice over every enrolled skill
+that the model may invoke (skills marked `disable-model-invocation: true` are left out),
+each with the first 300 characters of its description, plus `none`.
+
+The response is untrusted. The hook accepts it only on HTTP 200 with valid JSON, an
+`answers.which.choice` that exactly equals a catalog ID it sent, and a numeric
+`answers.which.confidence` of at least the threshold. Then it appends one fixed line to
+`additionalContext`:
+
+```text
+LitClaude skill hint: the skill `litclaude:<id>` likely fits this request. Load it only if it really fits; this is advice, not an instruction.
+```
+
+`none` or a low confidence adds nothing. A non-200 response body is cancelled unread. The hook
+records the call in the session file before sending it; when that write fails, it sends
+nothing and stays quiet, so an unwritable state folder cannot lift the cap. After the prompt
+hook writes its context on a turn with the flag on, it ends its own process once stdout has
+flushed, so a DNS lookup that the timeout cannot cancel never keeps it past the host's hook
+timeout. A missing key, reached cap, oversized request,
+timeout, network error, non-200 status, or invalid response leaves the turn exactly as it
+would be without the feature. The first such failure in a session shows one `systemMessage`
+(`LitClaude skill hint unavailable (<reason>); continuing normally.`); later failures stay quiet.
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `LITCLAUDE_JEV` | unset | `1` turns the hint on. Any other value leaves it off. |
+| `TYPESAFE_API_KEY` | unset | Your own TypeSafe key. Required while the flag is on. |
+| `LITCLAUDE_JEV_MODEL` | `jev-1.13.0` | Model name sent in the request. |
+| `LITCLAUDE_JEV_TIMEOUT_MS` | `1500` | Hard timeout; values above `3000` are capped. |
+| `LITCLAUDE_JEV_MAX_CALLS` | `200` | Requests per session before the hint stops. |
+| `LITCLAUDE_JEV_MIN_CONFIDENCE` | `0.35` | Lowest accepted confidence. |
+| `LITCLAUDE_JEV_TRACE` | unset | `1` appends a debug trace line per request. |
+
+Per-session counters live in `.litclaude/jev/session-<id>.json` under the project state
+root, with the current turn's hinted skill ID and latency in milliseconds; the prompt hook
+clears that pair at the start of every turn while the flag is on. The optional HUD status line
+(`plugins/litclaude/bin/litclaude-hud.js`) reads it and ends with `Jev ✓` while the hint is
+on, `Jev ✓ <skill> <latency>` on a hinted turn, or `Jev ⚠ key missing` when the flag is on
+without a key; it shows nothing while the flag is off and never shows the key or its length.
+While on, the HUD paints `Jev` as a rainbow whose starting hue follows the clock, so each refresh
+shifts it slightly (truecolor, 256- and 16-colour tiers; plain under `NO_COLOR`, the HUD's
+no-colour switch, or a light or unknown appearance). The session file also records that the
+once-per-session `✦ Jev skill hint ON ✦` `systemMessage` was shown; the prompt hook writes that
+mark before it emits the line on the first turn with the flag and key set, puts the line ahead
+of any other visible message that turn, and shows no line when the mark cannot be written. The opt-in trace, `.litclaude/jev/trace.jsonl`, records the timestamp, the SHA-256 of the
+redacted `state` (never of the raw prompt), chosen ID, confidence, latency, HTTP status, and fallback reason; it holds no prompt text,
+key, or response body. Session and trace files are opened with `O_NOFOLLOW` (an `lstat` check
+where the platform lacks it), so a symlink planted at either path is refused rather than written
+through. Because `TYPESAFE_API_KEY` is exported in the shell that starts Claude Code, the
+agent's own tools can read it too; use a key dedicated to this feature, with a low spend limit.
+`litclaude doctor` prints `Jev skill hint: off`, `Jev skill hint: on`,
+or `Jev skill hint: flag on but TYPESAFE_API_KEY missing`. The offline regression tests,
+which replace `fetch` in the real hook process, live in `test/jev-skill-hint.test.mjs`.
+
 ## Bounded-authority start-work lifecycle
 
 The hook and CLI share `plugins/litclaude/lib/start-work-lifecycle.mjs`.
@@ -464,7 +541,9 @@ host-dependent and need fallbacks.
 
 Hooks parse JSON from stdin and return JSON to Claude Code. The hook does not
 execute prompt text and does not echo prompt text into the returned context;
-prompt text is not executed or echoed. The litwork detector returns constant
+prompt text is not executed or echoed. The optional Jev skill hint is the one network
+call on this path: it is off by default, sends only redacted prompt text, and returns a fixed
+sentence rather than any response text. The litwork detector returns constant
 workflow guidance, so a prompt cannot become a shell command through the hook
 response. Malformed hook input and malformed litgoal JSON should surface a controlled error instead of a misleading success response.
 

package/docs/privacy.md

@@ -13,6 +13,7 @@ transcript, model request, or diagnostic report contains no sensitive informatio
 | Package installation | npm and its configured registry retrieve package metadata and package bytes; ordinary package-manager connection metadata is visible to those services. Global installation can run LitClaude's postinstall setup. | `LITCLAUDE_AUTO_INSTALL=0` or `LITCLAUDE_POSTINSTALL_SKIP=1` skips automatic plugin/HUD setup. It does not stop npm from fetching the package. |
 | Update notice | Interactive `install`, `update`, and `doctor` can schedule an HTTPS GET to `registry.npmjs.org` for the package's latest-version metadata. The request identifies the package and sends an update-notifier user-agent; the request body does not contain project files or prompts. | Attempts are throttled using a 24-hour local cache. `NO_UPDATE_NOTIFIER` or `LITCLAUDE_NO_UPDATE_CHECK` disables the notice/check path, even when the variable is empty. CI, JSON, dry-run, and non-TTY management calls are gated. |
 | Automatic update | An eligible cached newer version can trigger npm to fetch and run the installer, then doctor. This can occur on `SessionStart` or interactive management commands. | `LITCLAUDE_NO_AUTO_UPDATE` disables automatic installation but leaves update checks eligible. `LITCLAUDE_NO_UPDATE_CHECK` or `NO_UPDATE_NOTIFIER` disables both paths. SessionStart is a piped host hook, so it does not use the management TTY requirement. |
+| Jev skill hint | Off by default. With `LITCLAUDE_JEV=1` and your own `TYPESAFE_API_KEY`, the `UserPromptSubmit` hook sends one HTTPS POST per eligible prompt to `api.typesafe.ai`. The body holds the prompt truncated to 2,000 characters with home paths, e-mail addresses, and token-shaped strings redacted, plus the list of LitClaude skill names and descriptions. Anything in the prompt without a token shape, such as a hostname, a customer name, or a password not written as `password=…`, is sent as written. No files, tool output, or history are sent. TypeSafe bills the request to your account (about $0.04 per million input tokens). | Unset `LITCLAUDE_JEV` to turn it off. Slash commands, routed prompts, and prompts that name a skill are never sent. Each request has a 1.5-second timeout, no retry, no redirect, and a per-session cap of 200. Because `TYPESAFE_API_KEY` is exported in the shell that starts Claude Code, the agent's own tools can read it; use a key dedicated to this feature, with a low spend limit. |
 | Public source reader | `litclaude public-read` resolves DNS and sends HTTP(S) GET requests to the supplied public URL and validated redirects. Plain search text becomes a query to `duckduckgo.com/html/`. Requests use a LitClaude user-agent and Accept header. The destination sees the requested path and query, plus normal connection metadata. | The reader rejects credential-bearing URLs and private-network targets, revalidates redirects, and stops at detected authentication/paywall barriers. It does not use a browser login or cookie jar. Redacting a URL in returned evidence does not remove query values from the actual request. |
 
 For a process that should avoid LitClaude background update traffic, set
@@ -41,7 +42,10 @@ the features used, it contains session/rule receipts, plan and goal state, work
 ledgers, saved knowledge, and other feature-specific records. SessionStart
 context-pressure detection can inspect a supplied transcript path up to 256 KiB
 for a fixed set of pressure markers; it returns only a bounded advisory. No skill
-review reads transcript excerpts or sends them to a model. Existing
+review reads transcript excerpts or sends them to a model. The optional Jev skill hint keeps
+per-session request counts, the current turn's hinted skill ID and latency (shown by the
+HUD), and whether the once-per-session "on" line was shown in `.litclaude/jev/` and, only with `LITCLAUDE_JEV_TRACE=1`, a trace
+of hashes of the redacted prompt, timings, and status codes without prompt text. Existing
 `pending-review.json` and `skill-loop-state.json` files are inert after the
 automatic review feature's removal and may be deleted. No other state is affected.
 
@@ -76,6 +80,7 @@ for sensitive reports and [support guidance](../SUPPORT.md) for routine issues.
 - [Public requests and redirects](../plugins/litclaude/lib/public-source-reader/routes.mjs),
   [target validation](../plugins/litclaude/lib/public-source-reader/validator.mjs), and
   [receipt redaction](../plugins/litclaude/lib/public-source-reader/receipts.mjs).
+- [Jev skill hint request, redaction, and validation](../plugins/litclaude/lib/jev-skill-hint.mjs).
 - [Project state-root resolution](../plugins/litclaude/lib/project-state-root.mjs),
   [rules session receipts](../plugins/litclaude/lib/rules/session-state.mjs), and
   [litgoal state](../plugins/litclaude/lib/litgoal/state.mjs).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@litfamily/litclaude",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "description": "Claude Code-native workflow distribution.",
   "type": "module",
   "bin": {

package/plugins/litclaude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "litclaude",
   "description": "Claude Code-native workflow plugin with a bounded-authority start-work lifecycle.",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "author": {
     "name": "LitClaude contributors"
   },

package/plugins/litclaude/bin/litclaude-hook.js

@@ -4,7 +4,7 @@ import { existsSync, lstatSync, readFileSync, statSync } from "node:fs";
 import { dirname, extname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { standard, micro, colorMode, supportsBlocks } from "../lib/lit-mark.mjs";
-import { NEON_END, NEON_START } from "../lib/hud-accent-palette.mjs";
+import { NEON_END, NEON_START, rainbowText } from "../lib/hud-accent-palette.mjs";
 import { ignitionMark, writeIgnitionState } from "../lib/hud-ignition.mjs";
 import { renameAliases, renameNote } from "../lib/rename-aliases.mjs";
 import { hasInterfaceModeWord, interfaceMode } from "../lib/interface-mode.mjs";
@@ -41,6 +41,8 @@ import { formatResolvedPlanNotice, resolveLatestDurablePlan } from "../lib/durab
 import { clearLitPlanTurn, evaluateLitPlanStop, recordLitPlanTurn } from "../lib/lit-plan-persistence.mjs";
 import { evaluateInterfaceProbeStop, observeInterfaceProbeTool, recordInterfaceProbeTurn } from "../lib/interface-probe-gate.mjs";
 import { evaluateMotionStop, observeMotionTool, recordMotionTurn } from "../lib/motion-render-gate.mjs";
+import { canonicalSkillIds } from "../lib/canonical-skill-catalog.mjs";
+import { JEV_BANNER, JEV_FLAG, claimJevBanner, clearJevTurn, suggestJevSkill } from "../lib/jev-skill-hint.mjs";
 
 const formatDurablePlanNotice = (cwd) => {
   try {
@@ -124,7 +126,13 @@ const hookEventNames = {
   "subagent-stop": "SubagentStop",
 };
 
+// Set at most once per session by the prompt hook; it leads that turn's visible message. The host
+// prints its own label before the first line, so the one-line banner takes that line and any
+// message that opens with a newline for its art starts right below it.
+let jevBanner = null;
+
 const writeContext = (additionalContext, systemMessage, shouldContinue = true) => {
+  if (jevBanner) systemMessage = systemMessage ? `${jevBanner}\n${systemMessage.replace(/^\n/u, "")}` : jevBanner;
   const payload = {
     continue: shouldContinue,
     hookSpecificOutput: {
@@ -903,6 +911,31 @@ const findWorkflowTrigger = (prompt) => {
   return undefined;
 };
 
+// A turn names a skill explicitly when it carries a qualified `litclaude:` name or a hyphenated
+// or lit-prefixed catalog ID; plain words such as "refactor" or "rules" stay eligible.
+const explicitSkillIds = canonicalSkillIds.filter((id) => id.includes("-") || id.startsWith("lit"));
+const namesCatalogSkill = (raw) => raw.includes("litclaude:") || explicitSkillIds.some((id) => containsCompoundBoundedWord(raw, id));
+
+// The optional Jev skill hint runs only on a turn the deterministic router left unrouted, and
+// never on a slash command or a prompt that already names a skill. Any failure is quiet.
+const jevTurnHint = async (prompt, input) => {
+  const quiet = { hint: null, note: null };
+  if (process.env[JEV_FLAG] !== "1" || isDiagnosticLiteralPrompt(prompt)) return quiet;
+  try {
+    const raw = rawTriggerText(prompt);
+    return await suggestJevSkill({
+      env: process.env,
+      prompt: withoutHostNotifications(prompt).trim(),
+      eligible: !containsSlashCommandMention(raw) && !namesCatalogSkill(raw),
+      sessionId: input.session_id,
+      stateRoot: resolveProjectStateRoot(typeof input.cwd === "string" ? input.cwd : process.cwd()),
+      pluginRoot,
+    });
+  } catch {
+    return quiet;
+  }
+};
+
 const isDiagnosticLiteralPrompt = (prompt) =>
   /\bdiagnostic\b/iu.test(prompt)
   && /do not inspect or modify files/iu.test(prompt)
@@ -1258,6 +1291,14 @@ switch (eventName) {
     try {
       const cwd = typeof input.cwd === "string" ? input.cwd : process.cwd();
       const stateRoot = resolveProjectStateRoot(cwd);
+      // The HUD's Jev segment names a skill only for the turn that was hinted.
+      if (process.env[JEV_FLAG] === "1") {
+        clearJevTurn(stateRoot, input.session_id);
+        if (claimJevBanner({ env: process.env, stateRoot, sessionId: input.session_id })) {
+          const mode = colorMode({ isTTY: true });
+          jevBanner = rainbowText(JEV_BANNER, { depth: mode === "none" ? "plain" : mode });
+        }
+      }
       if (trigger?.discipline === "lit-plan" && !trigger.safetyBlock) recordLitPlanTurn(stateRoot, { sessionId: input.session_id });
       else clearLitPlanTurn(stateRoot);
       recordInterfaceProbeTurn(stateRoot, { sessionId: input.session_id, discipline: trigger?.safetyBlock ? null : trigger?.discipline });
@@ -1307,7 +1348,17 @@ switch (eventName) {
         ["frontend-ui-ux", "visual-qa", "lit-diagram-drawer", "lit-pptx", "lit-docx", "lit-typographic-motion"].includes(trigger.discipline) ? 4096 : undefined,
       ), systemMessage);
     } else {
-      writeContext(withPromptRules("LitClaude prompt hook checked: no workflow activation."));
+      const jev = await jevTurnHint(prompt, input);
+      writeContext(
+        withPromptRules(["LitClaude prompt hook checked: no workflow activation.", jev.hint].filter(Boolean).join("\n\n")),
+        jev.note ?? undefined,
+      );
+      // A timed-out request can leave a DNS lookup that no signal cancels, which would keep this
+      // process alive past the host's hook timeout. Exit once stdout has flushed the context.
+      if (process.env[JEV_FLAG] === "1") {
+        process.exitCode = 0;
+        process.stdout.write("", () => setImmediate(() => process.exit()));
+      }
     }
     break;
   }

package/plugins/litclaude/bin/litclaude-hud.js

@@ -10,9 +10,12 @@ import {
   hudColorDepth,
   litBrandPrefix,
   normalizeHudAppearance,
+  rainbowText,
 } from "../lib/hud-accent-palette.mjs";
 import { latestUsageTokens } from "../lib/cache-measurement.mjs";
 import { readIgnitionState, renderIgnitionSegment } from "../lib/hud-ignition.mjs";
+import { formatJevLatency, jevHudState } from "../lib/jev-skill-hint.mjs";
+import { resolveProjectStateRoot } from "../lib/project-state-root.mjs";
 
 const pluginRoot = dirname(dirname(fileURLToPath(import.meta.url)));
 const pluginManifestPath = join(pluginRoot, ".claude-plugin", "plugin.json");
@@ -243,6 +246,30 @@ const formatUsageSegment = (label, value, reset) => {
   return `${labelText} ${accent("[")}${makeBlockBar(pct, 2)}${accent("]")} ${pctText}${resetText ? ` ${text(resetText)}` : ""}`;
 };
 
+// Optional Jev skill hint: nothing while LITCLAUDE_JEV is off, and never the key or its length.
+const jevSegment = (status) => {
+  let state;
+  try {
+    const cwd = typeof status.cwd === "string" && status.cwd ? status.cwd : null;
+    state = jevHudState({
+      env: process.env,
+      stateRoot: cwd ? resolveProjectStateRoot(cwd) : null,
+      sessionId: status.session_id,
+    });
+  } catch {
+    return "";
+  }
+  if (!state) return "";
+  if (state.keyMissing) return `${text("Jev")} ${colors.yellow}⚠${colors.reset} ${text("key missing")}`;
+  // While on, the word shimmers: each refresh starts the rainbow at a hue taken from the clock.
+  // Light and unknown appearances keep it on the default foreground like the rest of the text.
+  const now = Number(process.env.LITCLAUDE_HUD_TEST_NOW);
+  const phase = Math.floor((Number.isFinite(now) && now > 0 ? now : Date.now()) / 100) % 360;
+  const word = coloredText ? rainbowText("Jev", { depth: colorDepth, phase }) : text("Jev");
+  const mark = `${word} ${colors.green}✓${colors.reset}`;
+  return state.last ? `${mark} ${text(state.last.skill)} ${text(formatJevLatency(state.last.latency_ms))}` : mark;
+};
+
 const main = async () => {
   const input = await readStdin();
   const status = input.trim() ? JSON.parse(input) : {};
@@ -267,7 +294,8 @@ const main = async () => {
   const ignition = renderIgnitionSegment(readIgnitionState(status.session_id), {
     depth: plainOutput ? "plain" : colorDepth,
   });
-  const line = `${prefix}${ignition ? ` ${ignition}` : ""} ${accent("|")} ${text(model)} ${accent(sep)} ${contextText}${usageText}${git ? ` ${accent(sep)} ${text("git")} ${text(git)}` : ""}`;
+  const jev = jevSegment(status);
+  const line = `${prefix}${ignition ? ` ${ignition}` : ""} ${accent("|")} ${text(model)} ${accent(sep)} ${contextText}${usageText}${git ? ` ${accent(sep)} ${text("git")} ${text(git)}` : ""}${jev ? ` ${accent(sep)} ${jev}` : ""}`;
   process.stdout.write(`${line}\n`);
 
   const lastMessage = latestUserMessage(status.transcript_path);

package/plugins/litclaude/bin/litclaude-mcp.js

@@ -9,7 +9,7 @@ import {
 } from "../lib/wikify-knowledge.mjs";
 
 const protocolVersion = "2024-11-05";
-const serverVersion = "1.0.12";
+const serverVersion = "1.0.13";
 
 const publicSourceReadTool = {
   name: "public_source_read",

package/plugins/litclaude/lib/hud-accent-palette.mjs

@@ -113,3 +113,36 @@ export const litBrandPrefix = (version, { noColor = false, truecolor = false, de
   out += `\x1b[38;2;${NEON_END[0]};${NEON_END[1]};${NEON_END[2]}m v${version}]\x1b[0m`;
   return out;
 };
+
+// --- Rainbow text (Jev skill hint) ------------------------------------------
+// Per-character hue sweep starting at `phase` degrees: truecolor paints exact hues, 256-color
+// snaps each hue to the 6x6x6 cube, 16-color picks the nearest bright hue, plain returns the
+// text untouched. Spaces get no escape, and stripping the escapes always gives back `text`.
+const RAINBOW_ANSI16 = Object.freeze([91, 93, 92, 96, 94, 95]);
+
+const hueToRgb = (hue) => {
+  // HSV with a softened saturation so every hue stays legible on a dark terminal.
+  const h = ((hue % 360) + 360) % 360 / 60;
+  const s = 0.65;
+  const x = 1 - Math.abs((h % 2) - 1);
+  const [r, g, b] = [[1, x, 0], [x, 1, 0], [0, 1, x], [0, x, 1], [x, 0, 1], [1, 0, x]][Math.floor(h) % 6];
+  return [r, g, b].map((channel) => Math.round(255 * (1 - s + s * channel)));
+};
+
+export const rainbowText = (text, { depth = "plain", phase = 0 } = {}) => {
+  if (!["truecolor", "256", "16"].includes(depth)) return text;
+  const chars = [...text];
+  const step = chars.length > 1 ? Math.min(60, 300 / (chars.length - 1)) : 0;
+  const painted = chars.map((char, index) => {
+    if (char === " ") return char;
+    const hue = (((phase + index * step) % 360) + 360) % 360;
+    if (depth === "16") return `\x1b[${RAINBOW_ANSI16[Math.floor(((hue + 30) % 360) / 60)]}m${char}`;
+    const [r, g, b] = hueToRgb(hue);
+    if (depth === "256") {
+      const cube = (value) => Math.round((value / 255) * 5);
+      return `\x1b[38;5;${16 + 36 * cube(r) + 6 * cube(g) + cube(b)}m${char}`;
+    }
+    return `\x1b[38;2;${r};${g};${b}m${char}`;
+  });
+  return `\x1b[1m${painted.join("")}\x1b[0m`;
+};