@lincoln504/pi-research 0.1.12 → 1.0.0

package/src/tui/research-panel-state.ts

@@ -0,0 +1,404 @@
+/**
+ * Research Panel State Management
+ *
+ * Functions for managing research panel state, including
+ * the per-slice flash queue for tool result feedback.
+ */
+
+import type {
+  ResearchPanelState,
+} from '../types/research-panel-types.ts';
+
+import {
+  FLASH_GREEN_DURATION_MS,
+  FLASH_RED_DURATION_MS,
+  FLASH_STATUS_DURATION_MS,
+  FLASH_QUEUE_GAP_MS,
+} from '../constants.ts';
+
+// ---------------------------------------------------------------------------
+// Flash queue internals
+// ---------------------------------------------------------------------------
+
+interface FlashEntry {
+  color: 'green' | 'red';
+}
+
+interface SliceFlashState {
+  /** Non-null when a color flash is active OR we are in the inter-flash gap. */
+  activeTimeout: NodeJS.Timeout | null;
+  /** The color currently being displayed. Null during inter-flash gap. */
+  activeColor: 'green' | 'red' | null;
+  colorQueue: FlashEntry[];
+
+  /** Non-null when a status 'pop' is active OR we are in the inter-flash gap. */
+  statusTimeout: NodeJS.Timeout | null;
+  /** The status text currently being displayed. Null during inter-flash gap. */
+  activeStatus: string | null;
+  statusQueue: string[];
+}
+
+/**
+ * Maximum queued items per slice.
+ */
+const MAX_QUEUE_SIZE = 8;
+
+/**
+ * Per-research-run flash state: Map<researchId, Map<sliceId, SliceFlashState>>.
+ *
+ * Keyed by researchId, NOT the pi sessionId: a single pi session can host several
+ * concurrent research runs, and they all reuse the same slice ids ('coord', 'eval',
+ * '1', '2', …). Keying by sessionId let one run's flashes render against — or, on
+ * teardown, cancel — another run's, sometimes leaving a column stuck colored.
+ * researchId is unique per run, so this isolates them.
+ */
+const flashStateByRun = new Map<string, Map<string, SliceFlashState>>();
+
+function getOrCreateSliceFlash(researchId: string, sliceId: string): SliceFlashState {
+  let run = flashStateByRun.get(researchId);
+  if (!run) {
+    run = new Map();
+    flashStateByRun.set(researchId, run);
+  }
+  let slice = run.get(sliceId);
+  if (!slice) {
+    slice = {
+      activeColor: null,
+      activeTimeout: null,
+      colorQueue: [],
+      activeStatus: null,
+      statusTimeout: null,
+      statusQueue: []
+    };
+    run.set(sliceId, slice);
+  }
+  return slice;
+}
+
+/**
+ * Clear all flash state for a research run (call on that run's teardown). Scoped to
+ * the run so disposing one run never cancels a concurrent sibling run's flashes.
+ */
+export function clearAllFlashTimeouts(researchId?: string): void {
+  if (researchId) {
+    const run = flashStateByRun.get(researchId);
+    if (run) {
+      for (const slice of run.values()) {
+        if (slice.activeTimeout) clearTimeout(slice.activeTimeout);
+        if (slice.statusTimeout) clearTimeout(slice.statusTimeout);
+        slice.activeTimeout = null;
+        slice.activeColor = null;
+        slice.colorQueue.length = 0;
+        slice.statusTimeout = null;
+        slice.activeStatus = null;
+        slice.statusQueue.length = 0;
+      }
+      flashStateByRun.delete(researchId);
+    }
+  } else {
+    for (const run of flashStateByRun.values()) {
+      for (const slice of run.values()) {
+        if (slice.activeTimeout) clearTimeout(slice.activeTimeout);
+        if (slice.statusTimeout) clearTimeout(slice.statusTimeout);
+      }
+    }
+    flashStateByRun.clear();
+  }
+}
+
+/**
+ * Flash a researcher slice green or red.
+ *
+ * If a flash or gap is currently active for this slice the new entry is queued.
+ * Each queued flash plays after the previous one expires plus a small gap
+ * so rapid-fire per-URL results are visible as distinct pulses.
+ */
+export function flashSlice(
+  state: ResearchPanelState,
+  sliceId: string,
+  color: 'green' | 'red',
+  onUpdate?: () => void,
+): void {
+  const slice = state.slices.get(sliceId);
+  if (!slice || slice.completed || slice.queued) return;
+
+  const flash = getOrCreateSliceFlash(state.researchId, sliceId);
+
+  if (flash.activeTimeout !== null) {
+    if (flash.colorQueue.length < MAX_QUEUE_SIZE) {
+      flash.colorQueue.push({ color });
+    }
+    return;
+  }
+
+  startFlash(state, sliceId, flash, color, onUpdate);
+}
+
+function startFlash(
+  state: ResearchPanelState,
+  sliceId: string,
+  flash: SliceFlashState,
+  color: 'green' | 'red',
+  onUpdate?: () => void,
+): void {
+  const slice = state.slices.get(sliceId);
+  if (!slice || slice.completed) return;
+
+  const duration = color === 'green' ? FLASH_GREEN_DURATION_MS : FLASH_RED_DURATION_MS;
+
+  flash.activeColor = color;
+  slice.flash = color;
+  onUpdate?.();
+
+  flash.activeTimeout = setTimeout(() => {
+    flash.activeColor = null;
+    flash.activeTimeout = null;
+
+    const currentSlice = state.slices.get(sliceId);
+    if (currentSlice) currentSlice.flash = null;
+
+    if (flash.colorQueue.length > 0) {
+      const currentSliceCheck = state.slices.get(sliceId);
+      if (currentSliceCheck && !currentSliceCheck.completed) {
+        const next = flash.colorQueue.shift()!;
+        flash.activeTimeout = setTimeout(() => {
+          startFlash(state, sliceId, flash, next.color, onUpdate);
+        }, FLASH_QUEUE_GAP_MS);
+        onUpdate?.();
+        return;
+      }
+    }
+    onUpdate?.();
+  }, duration);
+}
+
+/**
+ * Flash a status message (tool name) in the researcher box for a fixed duration.
+ */
+export function flashStatus(
+  state: ResearchPanelState,
+  sliceId: string,
+  status: string,
+  onUpdate?: () => void,
+): void {
+  const slice = state.slices.get(sliceId);
+  if (!slice || slice.completed || slice.queued) return;
+
+  const flash = getOrCreateSliceFlash(state.researchId, sliceId);
+
+  if (flash.statusTimeout !== null) {
+    if (flash.statusQueue.length < MAX_QUEUE_SIZE) {
+      flash.statusQueue.push(status);
+    }
+    return;
+  }
+
+  startStatusPop(state, sliceId, flash, status, onUpdate);
+}
+
+function startStatusPop(
+  state: ResearchPanelState,
+  sliceId: string,
+  flash: SliceFlashState,
+  status: string,
+  onUpdate?: () => void,
+): void {
+  const slice = state.slices.get(sliceId);
+  if (!slice || slice.completed) return;
+
+  flash.activeStatus = status;
+  slice.status = status;
+  onUpdate?.();
+
+  flash.statusTimeout = setTimeout(() => {
+    flash.activeStatus = null;
+    flash.statusTimeout = null;
+
+    const currentSlice = state.slices.get(sliceId);
+    if (currentSlice) currentSlice.status = undefined;
+
+    if (flash.statusQueue.length > 0) {
+      const currentSliceCheck = state.slices.get(sliceId);
+      if (currentSliceCheck && !currentSliceCheck.completed) {
+        const next = flash.statusQueue.shift()!;
+        flash.statusTimeout = setTimeout(() => {
+          startStatusPop(state, sliceId, flash, next, onUpdate);
+        }, FLASH_QUEUE_GAP_MS);
+        onUpdate?.();
+        return;
+      }
+    }
+    onUpdate?.();
+  }, FLASH_STATUS_DURATION_MS);
+}
+
+/**
+ * Clean up flash state for a specific slice.
+ * Clears timeout, queue, and removes from the session map.
+ */
+function clearSliceFlash(researchId: string, sliceId: string): void {
+  const run = flashStateByRun.get(researchId);
+  if (!run) return;
+  const flash = run.get(sliceId);
+  if (!flash) return;
+  if (flash.activeTimeout) clearTimeout(flash.activeTimeout);
+  if (flash.statusTimeout) clearTimeout(flash.statusTimeout);
+  flash.activeTimeout = null;
+  flash.activeColor = null;
+  flash.colorQueue.length = 0;
+  flash.statusTimeout = null;
+  flash.activeStatus = null;
+  flash.statusQueue.length = 0;
+  run.delete(sliceId);
+}
+
+/**
+ * Cancel any in-flight or queued status "pop" for a slice, WITHOUT touching its
+ * color flash or removing the slice's flash record. Call this on an explicit status
+ * clear (status === undefined) that bypasses the timed-pop queue — otherwise a
+ * still-armed flashStatus() timer from the just-cleared status survives the clear,
+ * and the next flashStatus() for a NEW status sees that stale timer as "still
+ * active" and queues instead of showing immediately; when the stale timer fires it
+ * pops the queued status late, disconnected from when its tool started (a
+ * flickering/laggy label, worst on deep-mode's several concurrent researcher boxes).
+ */
+function clearSliceStatusFlash(researchId: string, sliceId: string): void {
+  const flash = flashStateByRun.get(researchId)?.get(sliceId);
+  if (!flash) return;
+  if (flash.statusTimeout) clearTimeout(flash.statusTimeout);
+  flash.statusTimeout = null;
+  flash.activeStatus = null;
+  flash.statusQueue.length = 0;
+}
+
+// ---------------------------------------------------------------------------
+// Slice lifecycle
+// ---------------------------------------------------------------------------
+
+/**
+ * Add a new researcher column.
+ * If a slice with this id already exists, any leftover flash state is cleaned up.
+ */
+export function addSlice(state: ResearchPanelState, id: string, label: string, queued: boolean = false): void {
+  // Clean up any leftover flash state from a previous slice with the same id
+  // (e.g., 'eval' being re-added across evaluation rounds).
+  clearSliceFlash(state.researchId, id);
+  state.slices.set(id, { id, label, completed: false, queued, flash: null });
+}
+
+/**
+ * Remove a researcher column.
+ * Cleans up any flash state to prevent orphaned timers.
+ */
+export function removeSlice(state: ResearchPanelState, id: string): void {
+  clearSliceFlash(state.researchId, id);
+  state.slices.delete(id);
+}
+
+/**
+ * Mark researcher as active (start from queued state)
+ */
+export function activateSlice(state: ResearchPanelState, id: string): void {
+  const slice = state.slices.get(id);
+  if (slice) slice.queued = false;
+}
+
+/**
+ * Update researcher tokens and cost.
+ * Tokens are treated as current context size (latest value), while cost is accumulated.
+ */
+export function updateSliceTokens(state: ResearchPanelState, id: string, tokens: number, cost: number): void {
+  const slice = state.slices.get(id);
+  if (slice) {
+    // Non-decreasing guard: never update with a lower token count (stale estimates)
+    if (tokens > (slice.tokens || 0)) {
+        slice.tokens = tokens;
+    }
+    // Cost is accumulated by adding the new cost to the existing cost
+    slice.cost = (slice.cost || 0) + cost;
+  }
+}
+
+/**
+ * Update researcher status message (e.g. "Searching...")
+ * For researchers, this uses flashStatus to provide timed "pops" of tool names.
+ */
+export function updateSliceStatus(state: ResearchPanelState, id: string, status: string | undefined, onUpdate?: () => void): void {
+  const slice = state.slices.get(id);
+  if (!slice) return;
+
+  // For researchers (numeric labels or 'quick' slice), use the timed pop logic
+  // for non-empty status strings. This makes fast tool names visible.
+  // Core agents (coord/eval) keep persistent statuses for long-running phases.
+  const isResearcher = !isNaN(parseInt(slice.label, 10)) || slice.id.includes('researching:');
+  
+  if (status && isResearcher) {
+    flashStatus(state, id, status, onUpdate);
+  } else {
+    // Explicit clear (or a coord/eval persistent write) bypasses the timed-pop
+    // queue. For a researcher slice, cancel any pending flashStatus() timer for
+    // THIS slice so a stale timer can't delay-pop a status queued after this clear.
+    if (isResearcher) clearSliceStatusFlash(state.researchId, id);
+    slice.status = status;
+    if (onUpdate) onUpdate();
+  }
+}
+
+/**
+ * Mark researcher as complete. Pass `failed = true` to give it a terminal failed
+ * outcome (rendered distinctly from a successful completion).
+ */
+export function completeSlice(state: ResearchPanelState, id: string, failed = false): void {
+  const slice = state.slices.get(id);
+  if (slice) {
+    slice.completed = true;
+    slice.queued = false;
+    slice.flash = null;
+    if (failed) slice.failed = true;
+    clearSliceFlash(state.researchId, id);
+  }
+}
+
+/**
+ * Re-mark a researcher as active (used when promoting a completed researcher to lead evaluator).
+ * Cleans up any leftover flash state from the previous lifecycle phase.
+ */
+export function reactivateSlice(state: ResearchPanelState, id: string): void {
+  // Clean up any flash state from the previous lifecycle (timers, queue).
+  clearSliceFlash(state.researchId, id);
+  const slice = state.slices.get(id);
+  if (slice) {
+    slice.completed = false;
+    slice.flash = null;
+  }
+}
+
+/**
+ * Clear all completed slices from the TUI panel.
+ * This includes researchers, coordinator, and evaluator once completed.
+ */
+export function clearCompletedResearchers(state: ResearchPanelState): void {
+  const toRemove: string[] = [];
+  for (const [id, slice] of state.slices.entries()) {
+    if (slice.completed) {
+      clearSliceFlash(state.researchId, id);
+      toRemove.push(id);
+    }
+  }
+  for (const id of toRemove) {
+    state.slices.delete(id);
+  }
+}
+
+/**
+ * Create initial panel state for research session
+ */
+export function createInitialPanelState(sessionId: string, researchId: string, query: string, modelName: string): ResearchPanelState {
+  return {
+    sessionId,
+    researchId,
+    query,
+    slices: new Map(),
+    modelName,
+  };
+}

package/src/tui/research-panel-wave.ts

@@ -0,0 +1,280 @@
+/**
+ * Research Panel Wave Animation
+ *
+ * Head-trails gradient for the research panel header.
+ *
+ * Mechanic:
+ *
+ *  HEAD: always full accent brightness.
+ *        Character is a directional half-dash:
+ *          ╶  (right half) while moving left→right
+ *          ╴  (left half)  while moving right→left
+ *
+ *  TRAIL: each position stores the slowFrame when it was last visited by the
+ *  head.  On every rendered frame, age = currentSlowFrame − lastVisitFrame[i].
+ *  That age is mapped through an easeIn brightness ramp (power 2.2) over a
+ *  window of TRAIL_LEN = ¾ of available chars:
+ *
+ *    age 0            → full accent brightness  (head just left)
+ *    age TRAIL_LEN-1  → 65 % brightness floor   (far edge of trail)
+ *    age >= TRAIL_LEN → dark floor (clamped)
+ *
+ *  DWELL: the head pauses DWELL=3 slow-frames at both the left and right edge
+ *  before reversing, giving a consistent rest at each end.
+ *
+ *  Speed factor 0.87 retained from the original commit.
+ */
+
+import type { Theme } from '../types/research-panel-types.ts';
+import {
+  parseAnsiFgColor,
+  indexToRgb,
+  rgbToHsl,
+  hslToRgb,
+} from './research-panel-color-utils.ts';
+
+// Geometry is expressed in pulse frames. The pulse runs at ~30 FPS
+// (33ms/frame, see pulse.ts) — one cell-step per frame, which is the natural
+// visual resolution for a one-cell-wide head and reads cleaner than 60 FPS
+// (see pulse.ts for why higher FPS adds jitter without smoothing the motion).
+const DWELL_FRAMES = 10; // pause duration at each edge (~330ms at 33ms/frame)
+const PERIOD_FRAMES = 98; // total frames for one full back-and-forth cycle (~3.2s at 33ms/frame)
+
+// Scaling constants for "static-ish" tail distance
+const REFERENCE_WIDTH = 80;
+const REFERENCE_TAIL_DIST = 40;
+const TAIL_SCALING_EXPONENT = 0.5;
+
+/**
+ * Resolve the theme accent colour to a full-precision RGB triple.
+ */
+function getBaseAccentRgb(theme: Theme): { r: number; g: number; b: number } {
+  const accentText = theme.fg('accent', '');
+  const parsed = parseAnsiFgColor(accentText);
+
+  if (parsed) {
+    if (parsed.type === 'rgb' && parsed.r !== undefined && parsed.g !== undefined && parsed.b !== undefined) {
+      return { r: parsed.r, g: parsed.g, b: parsed.b };
+    }
+    if (parsed.type === '256' && parsed.index !== undefined) {
+      const idx = parsed.index;
+      if (idx >= 16 && idx <= 231) {
+        const rgb = indexToRgb(idx);
+        if (rgb) return rgb;
+      } else if (idx >= 232 && idx <= 255) {
+        const gray = 8 + (idx - 232) * 10;
+        return { r: gray, g: gray, b: gray };
+      } else if (idx >= 0 && idx <= 15) {
+        const ansi16: Record<number, { r: number; g: number; b: number }> = {
+          0:  { r: 0,   g: 0,   b: 0   },
+          1:  { r: 170, g: 0,   b: 0   },
+          2:  { r: 0,   g: 170, b: 0   },
+          3:  { r: 170, g: 170, b: 0   },
+          4:  { r: 0,   g: 0,   b: 170 },
+          5:  { r: 170, g: 0,   b: 170 },
+          6:  { r: 0,   g: 170, b: 170 },
+          7:  { r: 170, g: 170, b: 170 },
+          8:  { r: 85,  g: 85,  b: 85  },
+          9:  { r: 255, g: 85,  b: 85  },
+          10: { r: 85,  g: 255, b: 85  },
+          11: { r: 255, g: 255, b: 85  },
+          12: { r: 85,  g: 85,  b: 255 },
+          13: { r: 255, g: 85,  b: 255 },
+          14: { r: 85,  g: 255, b: 255 },
+          15: { r: 255, g: 255, b: 255 },
+        };
+        const c = ansi16[idx];
+        if (c) return c;
+      }
+    } else if (parsed.type === 'basic' && parsed.index !== undefined) {
+      const basic: Record<number, { r: number; g: number; b: number }> = {
+        0: { r: 0,   g: 0,   b: 0   },
+        1: { r: 170, g: 0,   b: 0   },
+        2: { r: 0,   g: 170, b: 0   },
+        3: { r: 170, g: 170, b: 0   },
+        4: { r: 0,   g: 0,   b: 170 },
+        5: { r: 170, g: 0,   b: 170 },
+        6: { r: 0,   g: 170, b: 170 },
+        7: { r: 170, g: 170, b: 170 },
+      };
+      const c = basic[parsed.index];
+      if (c) return c;
+    }
+  }
+
+  return { r: 148, g: 148, b: 148 };
+}
+
+/**
+ * Compute the color for a given age within the trail window.
+ *
+ * age = 0              → full accent brightness (head just visited)
+ * age = trailLen - 1   → 65 % brightness (dark floor of trail)
+ * age >= trailLen      → clamped to dark floor
+ *
+ * easeIn power-curve 2.2 for perceptually even brightness distribution.
+ */
+function ageToColor(
+  hsl: { h: number; s: number; l: number },
+  age: number,
+  trailLen: number,
+): { r: number; g: number; b: number } {
+  const clamped = Math.min(age, trailLen - 1);
+  const progress = Math.max(0, clamped / Math.max(1, trailLen - 1)); // 0.0 (bright) … 1.0 (dark)
+  const linearFactor = 1 - progress;
+  const curvedFactor = Math.pow(linearFactor, 2.2);       // easeIn
+
+  const newL = hsl.l * (0.65 + 0.35 * curvedFactor);
+  const newS = hsl.s * (0.98 + 0.02 * curvedFactor);
+  return hslToRgb(hsl.h, newS, newL);
+}
+
+/**
+ * Compute head position and state given a frame counter and width.
+ *
+ * Returns { headPos, goingRight, isDwelling }
+ * Constant duration: total period is fixed, speed scales with available width.
+ * headPos is returned as a float for smooth interpolation.
+ */
+function computeHeadState(frame: number, available: number): { headPos: number; goingRight: boolean; isDwelling: boolean } {
+  const M = Math.max(1, available - 1);
+  const D = DWELL_FRAMES;
+  const halfPeriod = PERIOD_FRAMES / 2;
+  const pos = frame % PERIOD_FRAMES;
+
+  if (pos < D) {
+    // Left dwell
+    return { headPos: 0, goingRight: true, isDwelling: true };
+  } else if (pos < halfPeriod) {
+    // Traversing left→right
+    const traverseFrames = halfPeriod - D;
+    const progress = (pos - D) / traverseFrames;
+    return { headPos: progress * M, goingRight: true, isDwelling: false };
+  } else if (pos < halfPeriod + D) {
+    // Right dwell
+    return { headPos: M, goingRight: false, isDwelling: true };
+  } else {
+    // Traversing right→left
+    const traverseFrames = PERIOD_FRAMES - (halfPeriod + D);
+    const progress = (pos - (halfPeriod + D)) / traverseFrames;
+    return { headPos: M - (progress * M), goingRight: false, isDwelling: false };
+  }
+}
+
+/**
+ * Generate the head-trails gradient wave fill string for one frame.
+ *
+ * waveColors stores the waveFrame when each position was last visited by the
+ * head.  On each call the head's current position is updated, and every
+ * position is colored based on its decay age since the last head visit.
+ *
+ * updatedColors must be stored by the caller (panel.waveColors = updatedColors).
+ *
+ * @param theme      - current theme (provides accent colour)
+ * @param waveFrame  - monotonically increasing frame counter
+ * @param waveColors - previously returned updatedColors (or undefined on first call)
+ * @param available  - number of characters to fill
+ */
+export function generateWaveFill(
+  theme: Theme,
+  waveFrame: number,
+  waveColors: number[] | undefined,
+  available: number
+): { fill: string; updatedColors: number[] } {
+  if (available <= 0) return { fill: '', updatedColors: [] };
+
+  const base = getBaseAccentRgb(theme);
+  const hsl = rgbToHsl(base.r, base.g, base.b);
+  const resetFg = '\x1b[39m';
+
+  // Calculate spatial tail distance based on width using a square-root scaling law.
+  // This ensures the tail grows/shrinks slower than the width itself,
+  // providing a more "static" and consistent feel across terminal sizes.
+  const tailDistChars = REFERENCE_TAIL_DIST * Math.pow(available / REFERENCE_WIDTH, TAIL_SCALING_EXPONENT);
+
+  // Speed in chars/frame: distance covered in one traversal window.
+  const traverseFrames = (PERIOD_FRAMES / 2) - DWELL_FRAMES;
+  const speed = (available - 1) / Math.max(1, traverseFrames);
+
+  // Trail length in frames = distance / speed.
+  // This translates the desired spatial distance into the temporal decay window.
+  const trailLen = Math.max(2, tailDistChars / Math.max(0.1, speed));
+
+  // Initialise or resize: place last-visit far enough in the past that all
+  // positions start at the dark floor.
+  if (!waveColors || waveColors.length !== available) {
+    const neverVisited = waveFrame - trailLen;
+    waveColors = Array(available).fill(neverVisited) as number[];
+  }
+
+  const { headPos, goingRight, isDwelling } = computeHeadState(waveFrame, available);
+  const headIdx = Math.floor(headPos);
+
+  // Paint the trail: ensure every segment passed between the previous frame
+  // and this one is colored. We use fractional visit-times for smooth gradients
+  // even when the head moves >1 char per frame (common on wide terminals).
+  if (waveFrame > 0) {
+    const prev = computeHeadState(waveFrame - 1, available);
+    const startIdx = Math.min(Math.floor(prev.headPos), headIdx);
+    const endIdx = Math.max(Math.floor(prev.headPos), headIdx);
+    const dist = Math.abs(headPos - prev.headPos);
+
+    if (dist > 0.001) {
+      for (let i = startIdx; i <= endIdx; i++) {
+        // visitTime = (previous frame time) + (fraction of traversal to index i)
+        const d = Math.abs(i - prev.headPos);
+        const visitTime = (waveFrame - 1) + (d / dist);
+        waveColors[i] = visitTime;
+      }
+    }
+    // Ensure the head's discrete position is always set to the current frame time
+    // for maximum brightness at the leading edge.
+    waveColors[headIdx] = waveFrame;
+  } else {
+    waveColors[headIdx] = waveFrame;
+  }
+
+  // Directional head character: half-dash pointing in the direction of motion
+  //   ╴ (U+2574, BOX DRAWINGS LIGHT LEFT)  while going left→right (connects to trail on left)
+  //   ╶ (U+2576, BOX DRAWINGS LIGHT RIGHT) while going right→left (connects to trail on right)
+  let headChar = goingRight ? '╴' : '╶';
+
+  // Solid head when dwelling (no gap)
+  if (isDwelling) {
+    headChar = (headIdx === 0) ? '╶' : '─';
+  }
+
+  // Ensure head doesn't point into space at index 0 when starting movement
+  if (headIdx === 0 && goingRight) {
+    headChar = '╶';
+  }
+
+  // Special edge hit characters (1-frame impact) override solid head
+  const halfPeriod = PERIOD_FRAMES / 2;
+  const pos = waveFrame % PERIOD_FRAMES;
+
+  if (pos === halfPeriod) {
+    headChar = '╼'; // Hit right edge (LIGHT LEFT AND HEAVY RIGHT)
+  } else if (pos === 0) {
+    headChar = '╺'; // Hit left edge (HEAVY RIGHT)
+  }
+
+  // Build fill from per-position ages
+  let fill = '';
+  for (let i = 0; i < available; i++) {
+    const lastVisit = waveColors[i] ?? (waveFrame - trailLen);
+    const age = waveFrame - lastVisit;
+
+    const rgb = ageToColor(hsl, age, trailLen);
+    const color = `\x1b[38;2;${rgb.r};${rgb.g};${rgb.b}m`;
+
+    // Trail at index 0 should be rounded '╶' to match header style
+    let char = (i === 0) ? '╶' : '─';
+    if (i === headIdx) char = headChar;
+
+    fill += `${color}${char}${resetFg}`;
+  }
+
+  return { fill, updatedColors: waveColors };
+}
+