Add a patch for throttling/pacing of statusline updates

[bl-ue]

Summary by CodeRabbit

• New Features
  • Added customizable statusline update pacing: throttle duration and optional fixed-interval mode.
  • New UI controls to enable/disable statusline updates, adjust throttle timing, and toggle fixed-interval behavior (with display and step controls).
• Documentation
  • Added “Statusline update customization” section with examples and JSON config.
  • Clarified token-count wording for generation status.
  • Updated run instructions to use node dist/index.mjs and added a changelog entry.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds configurable throttling for statusline updates: new settings and types, UI controls, a patch that rewrites statusline update logic into a proper throttle or fixed-interval implementation, documentation updates, and wiring the new patch into the patch registry and application flow.

Changes

Cohort / File(s)	Summary
Documentation README.md, CHANGELOG.md	Added README section on statusline update customization and node run fix; changelog entry for statusline throttling.
Settings & Types src/defaultSettings.ts, src/types.ts	Introduced `statuslineThrottleMs: number
Patch System: Throttle Feature src/patches/index.ts, src/patches/statuslineUpdateThrottle.ts	Imported and registered a new statusline-update-throttle patch; added writeStatuslineUpdateThrottle implementation that rewrites statusline update logic to use either a proper throttle or fixed-interval approach (regex-based code transform, error handling, showDiff).
UI Controls src/ui/components/MiscView.tsx	Added UI to configure throttle interval (min/max/step/default) and toggle fixed-interval mode; display logic and navigation integration.
Patch Docs/Comments src/patches/toolsets.ts	Minor comment wording changes referencing "statusline" terminology.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor User as User
  participant UI as Settings UI (rgba(66, 135, 245, 0.5))
  participant PatchSys as Patch System (rgba(90, 200, 90, 0.5))
  participant FS as File System (rgba(200, 200, 200, 0.5))
  participant App as Statusline Code (App) (rgba(245, 166, 35, 0.5))
  participant Timer as Timer/Interval (rgba(255, 99, 132, 0.5))

  User ->> UI: Set throttle ms / fixed-interval
  UI ->> PatchSys: Provide config (misc.statuslineThrottleMs/useFixedInterval)
  PatchSys ->> PatchSys: Generate rewrite (throttle or interval)
  PatchSys ->> FS: Write patched file(s)

  User ->> App: Trigger generation
  App ->> Timer: Start throttle/interval controller
  Timer ->> App: Periodic/allowed updates
  App ->> User: Update statusline at controlled pace

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• Redesign --apply output #433 — Adds/adjusts patch registry/application flow; directly related to wiring the new statusline-update-throttle patch.
• Misc fixes #440 — Modifies patch interface/registry behavior that the new patch must conform to.
• Rework showDiff to use smart diffing; --show-unchanged; system prompt whitespace fix #424 — Updated diffing/patch utilities used by the new throttle patch (showDiff integration).

Suggested reviewers

• georpar

Poem

I thump my paws in timed delight,
A gentle tick, a measured light —
Statuslines hop, not wildly race,
Each update finds its steady pace.
With whiskered cheer, I watch the trace.
(_/) ⏱️ 🥕

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding a patch mechanism for throttling and pacing statusline updates, which is reflected throughout the changeset.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch statusline-update-throttle

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@README.md`:
- Around line 377-408: Correct the "Configation via UI:" typo to "Configuration
via UI:" and add meaningful alt text for the three image tags shown
(assets/statusline_update_interval_150ms.gif,
assets/statusline_update_throttle_1s.gif, and assets/statusline_ui_config.png)
to satisfy MD045; update the caption lines where the images appear so each image
tag includes an alt string describing the screenshot/demo (e.g., "150ms interval
demo", "1000ms throttle demo", "Statusline UI configuration").

In `@src/patches/index.ts`:
- Around line 584-592: The current call to writeStatuslineUpdateThrottle can
receive 0 or negative from config.settings.misc?.statuslineThrottleMs which may
cause a hot loop; clamp this value to a safe minimum before passing it (e.g.,
const MIN_STATUSLINE_THROTTLE_MS = 50 and use
Math.max(config.settings.misc?.statuslineThrottleMs ?? 300,
MIN_STATUSLINE_THROTTLE_MS)), and pass the clamped value to
writeStatuslineUpdateThrottle while still forwarding
config.settings.misc?.statuslineUseFixedInterval; reference the
'statusline-update-throttle' entry and writeStatuslineUpdateThrottle to
implement the clamp and keep behavior stable when <=0 is provided.

🧹 Nitpick comments (2)

src/patches/statuslineUpdateThrottle.ts (1)

76-88: Tighten the patch regex to avoid over-matching minified code.

The .{0,1000} / .{0,200} spans are quite permissive; consider anchoring to more specific tokens (e.g., statement boundaries) so the patch doesn’t drift to unrelated sections as minified layouts evolve.

Based on learnings: In patches under src/patches/, assume code works with minified, original Claude Code installations. Patch regexes must be strict and match the minified format exactly (ignore formatting differences like whitespace/newlines).

src/patches/index.ts (1)

181-186: Align patch grouping with conditional application.

This patch is listed under PatchGroup.ALWAYS_APPLIED, but it’s conditionally applied (Line 591). Consider moving it to MISC_CONFIGURABLE or removing the condition so --list-patches and results align with expectations.

Possible adjustment

-    group: PatchGroup.ALWAYS_APPLIED,
+    group: PatchGroup.MISC_CONFIGURABLE,