@socketsecurity/lib 5.26.0 → 5.26.1

package/dist/dlx/paths.d.ts

@@ -44,7 +44,7 @@ export declare function getDlxPackageNodeModulesDir(packageName: string): string
  *
  * @example
  * ```typescript
- * isInSocketDlx('/home/user/.socket/_dlx/abc123/bin/socket') // true
+ * isInSocketDlx('/home/<user>/.socket/_dlx/abc123/bin/socket') // true
  * isInSocketDlx('/usr/local/bin/socket') // false
  * isInSocketDlx(process.argv[0]) // Check if current binary is in DLX
  * ```

package/dist/dlx/paths.js

@@ -29,6 +29,7 @@ __export(paths_exports, {
 module.exports = __toCommonJS(paths_exports);
 var import_normalize = require("../paths/normalize");
 var import_socket = require("../paths/socket");
+var import_primordials = require("../primordials");
 let _path;
 // @__NO_SIDE_EFFECTS__
 function getPath() {
@@ -64,7 +65,7 @@ function isInSocketDlx(filePath) {
   const path = /* @__PURE__ */ getPath();
   const dlxDir = (0, import_normalize.normalizePath)((0, import_socket.getSocketDlxDir)());
   const absolutePath = (0, import_normalize.normalizePath)(path.resolve(filePath));
-  return absolutePath.startsWith(`${dlxDir}/`);
+  return (0, import_primordials.StringPrototypeStartsWith)(absolutePath, `${dlxDir}/`);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/effects/pulse-frames.js

@@ -23,12 +23,13 @@ __export(pulse_frames_exports, {
   generateSocketSpinnerFrames: () => generateSocketSpinnerFrames
 });
 module.exports = __toCommonJS(pulse_frames_exports);
+var import_ansi = require("../ansi");
 function generateSocketSpinnerFrames(options) {
   const opts = { __proto__: null, ...options };
   const interval = opts.interval ?? 50;
-  const bold = "\x1B[1m";
-  const dim = "\x1B[2m";
-  const reset = "\x1B[0m";
+  const bold = import_ansi.ANSI_BOLD;
+  const dim = import_ansi.ANSI_DIM;
+  const reset = import_ansi.ANSI_RESET;
   const lightning = "\u26A1\uFE0E";
   const starFilled = "\u2726\uFE0E ";
   const starOutline = "\u2727\uFE0E ";

package/dist/effects/shimmer-keyframes.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview SVG keyframe batcher for the shimmer engine.
+ *
+ * Pre-renders N frames of the engine and emits per-character keyTimes /
+ * values arrays suitable for SVG SMIL `<animate>` elements. The output is
+ * deduplicated (consecutive identical colors collapse to a single
+ * keyframe) and closed with a `t=1` anchor so the animation loops cleanly.
+ *
+ * Use with `calcMode="discrete"` to reproduce the engine's output exactly
+ * — no SMIL interpolation between frames, each frame holds until the
+ * next changes.
+ *
+ * @example
+ * ```ts
+ * import { configToSpec } from '@socketsecurity/lib/effects/shimmer'
+ * import { toShimmerKeyframes } from '@socketsecurity/lib/effects/shimmer-keyframes'
+ * const spec = configToSpec({ color: RAINBOW_GRADIENT, dir: 'ltr' }, 10)
+ * const tracks = toShimmerKeyframes(spec, 10, 60)
+ * // Emit one <animate> per char in your SVG:
+ * //   <animate attributeName="fill" calcMode="discrete"
+ * //            keyTimes={tracks[i].times.join(';')}
+ * //            values={tracks[i].values.join(';')}
+ * //            dur="3s" repeatCount="indefinite" />
+ * ```
+ */
+import { type ShimmerSpec } from './shimmer';
+/**
+ * Keyframe track for a single character. `times[i]` is in [0, 1] and
+ * pairs with `values[i]` (an `rgb(R,G,B)` string). Use directly as SMIL
+ * `<animate>` attributes:
+ *
+ * ```jsx
+ * <animate
+ *   keyTimes={track.times.join(';')}
+ *   values={track.values.join(';')}
+ *   calcMode="discrete"
+ * />
+ * ```
+ */
+export type Keyframes = {
+    /** Normalized timestamps in [0, 1], monotonically non-decreasing. */
+    readonly times: readonly number[];
+    /** `rgb(R,G,B)` color strings, paired by index with `times`. */
+    readonly values: readonly string[];
+};
+/**
+ * Render N frames of a shimmer spec into per-character keyframe tracks.
+ *
+ * Output is one {@link Keyframes} object per char. Consecutive identical
+ * colors collapse — only the first occurrence emits a keyframe, the rest
+ * are implicit (SMIL holds the previous value). A final keyframe at `t=1`
+ * closes the loop with the same value as `t=0` so playback wraps cleanly.
+ *
+ * Use with `calcMode="discrete"` to reproduce the engine's per-frame
+ * output exactly (no SMIL interpolation between frames).
+ *
+ * @param spec functional shimmer specification
+ * @param textLength number of chars to colorize
+ * @param frames total frame count to bake into the loop
+ * @returns one Keyframes track per char index, in order
+ */
+export declare function toShimmerKeyframes(spec: ShimmerSpec, textLength: number, frames: number): Keyframes[];

package/dist/effects/shimmer-keyframes.js

@@ -0,0 +1,55 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var shimmer_keyframes_exports = {};
+__export(shimmer_keyframes_exports, {
+  toShimmerKeyframes: () => toShimmerKeyframes
+});
+module.exports = __toCommonJS(shimmer_keyframes_exports);
+var import_shimmer = require("./shimmer");
+function toShimmerKeyframes(spec, textLength, frames) {
+  const tracks = [];
+  for (let i = 0; i < textLength; i++) {
+    tracks.push({ times: [], values: [] });
+  }
+  for (let f = 0; f < frames; f++) {
+    const t = f / frames;
+    const colors = (0, import_shimmer.frameColors)(spec, textLength, f);
+    for (let i = 0; i < textLength; i++) {
+      const c = colors[i];
+      const v = `rgb(${c[0]},${c[1]},${c[2]})`;
+      const track = tracks[i];
+      if (track.values[track.values.length - 1] !== v) {
+        track.times.push(t);
+        track.values.push(v);
+      }
+    }
+  }
+  for (let i = 0; i < textLength; i++) {
+    const track = tracks[i];
+    track.times.push(1);
+    track.values.push(track.values[0] ?? "rgb(0,0,0)");
+  }
+  return tracks;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  toShimmerKeyframes
+});

package/dist/effects/shimmer-terminal.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @fileoverview Terminal renderer for the shimmer engine.
+ *
+ * Turns the engine's `RGB[]` output into a single ANSI-escaped string ready
+ * to write to stdout/stderr. Uses 24-bit truecolor escape sequences
+ * (`\x1b[38;2;R;G;Bm`) which most modern terminals (iTerm2, Terminal.app,
+ * Windows Terminal, Alacritty, Ghostty, kitty, gnome-terminal) support
+ * natively. Terminals that lack truecolor (basic `xterm`, some serial
+ * consoles) will display the raw escape codes — call sites that need to
+ * support those terminals should fall back to {@link colorsToAnsi}'s
+ * "no colors" path or skip rendering entirely.
+ *
+ * The high-level {@link renderFrame} convenience runs the full pipeline
+ * (engine → ANSI) in one call. {@link colorsToAnsi} is the lower-level
+ * helper for when you already have an `RGB[]` from {@link frameColors}.
+ *
+ * @example
+ * ```ts
+ * import { configToSpec } from '@socketsecurity/lib/effects/shimmer'
+ * import { renderFrame } from '@socketsecurity/lib/effects/shimmer-terminal'
+ * const spec = configToSpec({ color: [140, 82, 255], dir: 'ltr' }, 'Loading'.length)
+ * process.stdout.write(renderFrame(spec, 'Loading', frame))
+ * ```
+ */
+import { ANSI_RESET } from '../ansi';
+import { type RGB, type ShimmerSpec } from './shimmer';
+/**
+ * ANSI "reset all attributes" sequence. Re-exported from `../ansi` for
+ * convenience so callers don't need a separate import for the canonical
+ * value. Identical to `ANSI_RESET` in `@socketsecurity/lib/ansi`.
+ */
+export { ANSI_RESET };
+/**
+ * Build the 24-bit truecolor foreground escape for an RGB tuple. Returns
+ * `\x1b[38;2;R;G;Bm`. Exported so callers building ANSI by hand can use
+ * the same helper.
+ */
+export declare function ansiTruecolor([r, g, b]: RGB): string;
+/**
+ * Wrap each char of `text` in a 24-bit truecolor ANSI escape using the
+ * matching color from `colors`. Each char is followed by an ANSI reset so
+ * adjacent uncolored output isn't tinted.
+ *
+ * Caller is responsible for grapheme segmentation if the text contains
+ * complex graphemes (combining marks, ZWJ sequences). This function uses
+ * spread iteration which handles BMP code points and surrogate pairs but
+ * treats each grapheme cluster as multiple "chars."
+ *
+ * If `colors.length` is shorter than the text's char count, surplus chars
+ * are emitted without color (uncolored tail).
+ *
+ * @param text input string to color
+ * @param colors per-char colors; index `i` colors char `i`
+ * @returns ANSI-escaped string
+ */
+export declare function colorsToAnsi(text: string, colors: readonly RGB[]): string;
+/**
+ * Render a single shimmer frame as ANSI-escaped text. Convenience wrapper
+ * over {@link frameColors} + {@link colorsToAnsi} for callers that don't
+ * need the intermediate `RGB[]`.
+ *
+ * @param spec functional shimmer specification (see {@link ShimmerSpec})
+ * @param text the string to colorize
+ * @param frame caller-controlled frame counter
+ */
+export declare function renderFrame(spec: ShimmerSpec, text: string, frame: number): string;

package/dist/effects/shimmer-terminal.js

@@ -0,0 +1,57 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var shimmer_terminal_exports = {};
+__export(shimmer_terminal_exports, {
+  ANSI_RESET: () => import_ansi.ANSI_RESET,
+  ansiTruecolor: () => ansiTruecolor,
+  colorsToAnsi: () => colorsToAnsi,
+  renderFrame: () => renderFrame
+});
+module.exports = __toCommonJS(shimmer_terminal_exports);
+var import_ansi = require("../ansi");
+var import_shimmer = require("./shimmer");
+function ansiTruecolor([r, g, b]) {
+  return `\x1B[38;2;${r};${g};${b}m`;
+}
+function colorsToAnsi(text, colors) {
+  const chars = [...text];
+  let out = "";
+  for (let i = 0; i < chars.length; i++) {
+    const c = colors[i];
+    if (c === void 0) {
+      out += chars[i];
+      continue;
+    }
+    out += `${ansiTruecolor(c)}${chars[i]}${import_ansi.ANSI_RESET}`;
+  }
+  return out;
+}
+function renderFrame(spec, text, frame) {
+  const chars = [...text];
+  return colorsToAnsi(text, (0, import_shimmer.frameColors)(spec, chars.length, frame));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ANSI_RESET,
+  ansiTruecolor,
+  colorsToAnsi,
+  renderFrame
+});

package/dist/effects/shimmer.d.ts

@@ -0,0 +1,293 @@
+/**
+ * @fileoverview Shimmer animation engine — pure functions, zero deps.
+ *
+ * Animates a "wave" of color sweeping across a string. Designed for
+ * terminal spinners but the engine output is just `RGB[]`, so adapters
+ * can render to ANSI, SVG keyframes, Ink components, or anything else.
+ *
+ * The engine is one function: `frameColors(spec, length, frame) → RGB[]`.
+ * It is pure — same inputs produce the same output, no shared state.
+ *
+ * A {@link ShimmerSpec} bundles three orthogonal pieces:
+ *
+ *   1. `positionAt(frame)` — the wave's center at frame N (in char units;
+ *      negative = off-screen left, > textLength = off-screen right).
+ *      Built-ins: {@link ltrSweep}, {@link rtlSweep},
+ *      {@link bidirectionalSweep}, {@link randomSweep}, {@link noSweep}.
+ *
+ *   2. `kernel(signedDistance, ctx)` — given a char's signed distance from
+ *      the wave center, produce its color. Built-ins: {@link blockKernel}
+ *      (hard on/off) and {@link smoothKernel} (soft glow).
+ *
+ *   3. `baseColor(i)` / `highlightColor(i)` — per-char palette anchors fed
+ *      to the kernel as `ctx.baseColor` and `ctx.highlightColor`. Build
+ *      these with {@link solidColor} (one color for every char) or
+ *      {@link gradient} (cycle through a palette).
+ *
+ * Most callers don't build a spec by hand. {@link configToSpec} translates
+ * the flat {@link ShimmerConfig} (`{ color, dir, speed, … }`) into a spec
+ * using sensible defaults. The spinner uses this internally.
+ *
+ * Adapters in `shimmer-terminal.ts` and `shimmer-keyframes.ts` consume the
+ * engine's `RGB[]` output and render it to ANSI escape sequences or SVG
+ * SMIL keyframes respectively.
+ *
+ * @example Smooth socket-lib-style shimmer over a single color:
+ * ```ts
+ * import { configToSpec, frameColors } from '@socketsecurity/lib/effects/shimmer'
+ * const spec = configToSpec({ color: [140, 82, 255], dir: 'ltr' }, 'Loading'.length)
+ * const colorsAtFrame0 = frameColors(spec, 7, 0)
+ * ```
+ *
+ * @example Discrete claude-code-style shimmer with a rainbow gradient:
+ * ```ts
+ * import { configToSpec } from '@socketsecurity/lib/effects/shimmer'
+ * import { RAINBOW_GRADIENT } from '@socketsecurity/lib/themes/utils'
+ * const spec = configToSpec(
+ *   { color: RAINBOW_GRADIENT, dir: 'ltr', kernel: 'block' },
+ *   'ultrathink'.length,
+ * )
+ * ```
+ */
+/**
+ * RGB color tuple. Each channel is 0-255.
+ */
+export type RGB = readonly [r: number, g: number, b: number];
+/**
+ * Ordered palette of RGB colors. Indexed via `i % length` in
+ * {@link gradient} so palettes shorter than the text wrap.
+ */
+export type Palette = readonly RGB[];
+/**
+ * Direction the wave sweeps.
+ *
+ * - `'ltr'` — wave moves left-to-right, restarts at left.
+ * - `'rtl'` — wave moves right-to-left, restarts at right.
+ * - `'bi'`  — alternates LTR and RTL each cycle.
+ * - `'random'` — re-rolls direction at each cycle boundary.
+ * - `'none'` — wave never appears (every char shows base color).
+ */
+export type ShimmerDirection = 'ltr' | 'rtl' | 'bi' | 'random' | 'none';
+/**
+ * Context passed to a {@link Kernel} on each invocation. Holds the per-char
+ * base and highlight colors so the kernel can blend between them.
+ */
+export type KernelContext = {
+    /** Color this char shows when the wave is far away. */
+    readonly baseColor: RGB;
+    /** Color this char shows when the wave is centered on it. */
+    readonly highlightColor: RGB;
+};
+/**
+ * A {@link Kernel} maps a char's signed distance from the wave center to
+ * a color. Negative distance = wave hasn't reached this char yet; positive
+ * distance = wave has passed it.
+ */
+export type Kernel = (signedDistance: number, ctx: KernelContext) => RGB;
+/**
+ * Functional shimmer specification — the full engine input. Built up from
+ * orthogonal pieces (position generator, kernel, palette functions) so any
+ * piece can be replaced independently.
+ */
+export type ShimmerSpec = {
+    /** Wave-center position at frame N. */
+    readonly positionAt: (frame: number) => number;
+    /** Maps wave distance + per-char palette context to a color. */
+    readonly kernel: Kernel;
+    /** Per-char base color (when the wave is far away). */
+    readonly baseColor: (charIndex: number) => RGB;
+    /** Per-char highlight color (when the wave is on the char). */
+    readonly highlightColor: (charIndex: number) => RGB;
+};
+/**
+ * User-facing flat shimmer config. Translated to a {@link ShimmerSpec} by
+ * {@link configToSpec}. Pass a `ShimmerSpec` directly when you need full
+ * control over the wave's curve.
+ */
+export type ShimmerConfig = {
+    /**
+     * Base color (single RGB) or per-char palette (array of RGB).
+     * @default [140, 82, 255] — Socket purple
+     */
+    readonly color?: RGB | Palette | undefined;
+    /**
+     * Highlight color shown when the wave is on a char. Single RGB or
+     * per-char palette, same shape as `color`.
+     * @default [255, 255, 255] — pure white
+     */
+    readonly highlight?: RGB | Palette | undefined;
+    /**
+     * Wave direction. See {@link ShimmerDirection}.
+     * @default 'ltr'
+     */
+    readonly dir?: ShimmerDirection | undefined;
+    /**
+     * Steps the wave advances per frame. Lower values = slower wave.
+     * @default 1/3 (≈0.333) — three frames advance the wave by one char.
+     */
+    readonly speed?: number | undefined;
+    /**
+     * Off-screen padding in char units on each side. The wave starts and
+     * ends past the text by this much so it fades in/out cleanly.
+     * @default 2
+     */
+    readonly padding?: number | undefined;
+    /**
+     * Half-width of the wave in chars (used by `smoothKernel`). Higher =
+     * wider bright zone. Ignored when `kernel: 'block'`.
+     * @default 2.5
+     */
+    readonly width?: number | undefined;
+    /**
+     * Wave shape. `'block'` is a hard 3-char-wide highlight (claude-code
+     * behavior). `'smooth'` is a power-curve glow (the previous library's
+     * default).
+     * @default 'smooth'
+     */
+    readonly kernel?: 'block' | 'smooth' | undefined;
+};
+/**
+ * Default base color used by {@link configToSpec} when `color` is omitted.
+ * Socket purple — matches the spinner's default color.
+ */
+export declare const DEFAULT_BASE_COLOR: RGB;
+/**
+ * Default highlight color used by {@link configToSpec} when `highlight` is
+ * omitted. Pure white.
+ */
+export declare const WHITE: RGB;
+/**
+ * Linearly interpolate between two RGB colors. `t` is clamped to [0, 1].
+ *
+ * @param a color at `t=0`
+ * @param b color at `t=1`
+ * @param t blend factor; values outside [0, 1] are clamped
+ * @returns blended RGB with each channel rounded to integer
+ */
+export declare function blendRgb(a: RGB, b: RGB, t: number): RGB;
+/**
+ * Build a per-char palette function that cycles through a fixed palette:
+ * `(i) => palette[i % palette.length]`.
+ *
+ * @throws {Error} if `palette` is empty
+ */
+export declare function gradient(palette: Palette): (i: number) => RGB;
+/**
+ * Build a per-char palette function that returns the same color for every
+ * char index. Useful when shimmering text with a single base color.
+ */
+export declare function solidColor(color: RGB): (i: number) => RGB;
+/**
+ * Discrete on/off kernel — each char is either fully `highlightColor`
+ * (within `halfWidth` of the wave center) or fully `baseColor`. No blend.
+ *
+ * Matches claude-code's spinner behavior at `halfWidth=1` (a 3-char bright
+ * zone: the char at the wave center plus its left and right neighbors).
+ *
+ * @param halfWidth chars on each side of the wave center to highlight
+ * @default halfWidth=1
+ */
+export declare function blockKernel(halfWidth?: number): Kernel;
+/**
+ * Smooth blend kernel — char's color blends from `baseColor` toward
+ * `highlightColor` as it approaches the wave center. Falloff curve is
+ * `(1 - |d|/halfWidth)^falloff`, giving a soft glow with a wider radius
+ * than `blockKernel`.
+ *
+ * Matches socket-lib's previous default at `halfWidth=2.5, falloff=2.5`.
+ *
+ * @param halfWidth chars on each side affected by the wave
+ * @param falloff intensity exponent (higher = sharper peak)
+ * @default halfWidth=2.5, falloff=2.5
+ */
+export declare function smoothKernel(halfWidth?: number, falloff?: number): Kernel;
+/**
+ * Build a position function for bidirectional motion: the wave does one
+ * left-to-right pass, then one right-to-left pass, then loops.
+ *
+ * @param textLength number of chars in the target string
+ * @param padding off-screen chars on each side
+ * @default padding=2
+ */
+export declare function bidirectionalSweep(textLength: number, padding?: number): (frame: number) => number;
+/**
+ * Build a position function for left-to-right motion: the wave starts at
+ * `-padding` (off-screen left), advances by 1 per frame, exits at
+ * `textLength + padding`, then wraps.
+ *
+ * @param textLength number of chars in the target string
+ * @param padding off-screen chars on each side
+ * @default padding=2
+ */
+export declare function ltrSweep(textLength: number, padding?: number): (frame: number) => number;
+/**
+ * Build a position function that hides the wave forever. Returns
+ * `-Infinity` for every frame so the kernel always sees `signedDistance` >
+ * `halfWidth` and produces base colors. Used by `configToSpec` when
+ * `dir: 'none'`.
+ */
+export declare function noSweep(): (frame: number) => number;
+/**
+ * Build a position function that randomly picks LTR or RTL at each cycle
+ * boundary. The PRNG is configurable (defaults to `Math.random`) so callers
+ * can seed it for reproducible animations.
+ *
+ * @param textLength number of chars in the target string
+ * @param padding off-screen chars on each side
+ * @param random PRNG returning [0, 1); defaults to `Math.random`
+ * @default padding=2, random=Math.random
+ */
+export declare function randomSweep(textLength: number, padding?: number, random?: () => number): (frame: number) => number;
+/**
+ * Build a position function for right-to-left motion: the wave starts at
+ * the right edge, decreases by 1 per frame, exits at `-padding` left of
+ * char 0, then wraps.
+ *
+ * @param textLength number of chars in the target string
+ * @param padding off-screen chars on each side
+ * @default padding=2
+ */
+export declare function rtlSweep(textLength: number, padding?: number): (frame: number) => number;
+/**
+ * Translate a {@link ShimmerDirection} string to its position-generator
+ * function. Used by {@link configToSpec}; exported for callers that want
+ * to swap kernel or palette while keeping the standard sweep mapping.
+ */
+export declare function directionToSweep(dir: ShimmerDirection, textLength: number, padding: number): (frame: number) => number;
+/**
+ * Translate a flat {@link ShimmerConfig} into a {@link ShimmerSpec}.
+ * Applies defaults for omitted fields; resolves `color` and `highlight`
+ * (which may be a single RGB or a palette) into per-char palette
+ * functions.
+ *
+ * The spinner uses this internally; callers who only need the standard
+ * shape can call this directly. Advanced callers can construct a
+ * `ShimmerSpec` by hand to plug in custom kernels or position generators.
+ */
+export declare function configToSpec(config: ShimmerConfig, textLength: number): ShimmerSpec;
+/**
+ * Resolve a {@link ShimmerConfig.color}-shaped input into a per-char
+ * palette function. Accepts a single RGB tuple, an ordered palette, or
+ * `undefined` (in which case `defaultColor` is used).
+ *
+ * Used internally by {@link configToSpec}; exported so callers can build
+ * partial specs that share the same input-shape rules.
+ */
+export declare function resolvePalette(source: RGB | Palette | undefined, defaultColor: RGB): (i: number) => RGB;
+/**
+ * Compute per-character colors for a single frame. This is the engine.
+ *
+ * @param spec functional shimmer specification
+ * @param textLength number of chars to color
+ * @param frame caller-controlled frame counter (any number; the position
+ *   generator handles wrapping)
+ * @returns one RGB tuple per char index, in order
+ *
+ * @example
+ * ```ts
+ * const colors = frameColors(spec, 'Loading'.length, frameCounter)
+ * // colors[0] = the color of 'L' at this frame
+ * // colors[6] = the color of 'g' at this frame
+ * ```
+ */
+export declare function frameColors(spec: ShimmerSpec, textLength: number, frame: number): RGB[];