fix(handlers): parse all modulate args and add lightness

[pi0x]

Supersedes #294 and #312, which both target #301 and touch the same lines. Combines the fix from each and closes a gap neither caught.

The bug

modulate declared args: [VArg], so parseArgs only ever mapped the first URL segment — saturation and hue reached sharp as undefined.

The part that isn't obvious: sharp validates with 'key' in options, not a defined-check (operation.mjs). Because the handler always spread all keys into the object, the undefined values were still present and tripped validation. So modulate is currently broken for every input on main, not just multi-arg ones:

[IPX_ERROR] Expected number above zero for saturation but received undefined of type undefined

Measured against test/assets/bliss.jpg:

URL	main	#312	#294	this PR
modulate_2	✗	✗	✗	✅
modulate_2_1	✗	✗	✗	✅
modulate_2_1_90	✗	✅	✗	✅
modulate_2_1_90_10	✗	✅	✅	✅

Worth noting #294 as it stands regresses modulate_2_1_90 — adding lightness introduces a fourth always-present key. Its unit test passes only because sharp is mocked.

The fix

• Declare all four arg mappers so parseArgs reaches every segment.
• Add sharp's lightness option (from fix: add lightness arg to modulate modifier #294).
• Omit args that weren't supplied from the options object, so trailing arguments stay optional.

Tests

• Two unit tests driving the handler through applyHandler (from fix(handlers): parse all three modulate args (brightness, saturation, hue) #312's approach) — a direct apply() call can't exercise the arg-count contract, which is why the original bug survived a green suite.
• An end-to-end test over all four arities against real sharp. Mocking sharp is precisely what hid the key in options behaviour, so at least one test has to hit the real pipeline.

eslint, prettier -c src test and vitest run all pass. One unrelated pre-existing failure remains on this branch and on main: test/index.test.ts > remote file fails with serveStatic is not a function after the recent srvx bump.

Credit to @DamianGlowala and @dev48v — this is their work combined.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added support for the optional lightness value in modulate image adjustments.
  • Modulation arguments can now specify brightness, saturation, hue, and lightness, with trailing values omitted as needed.

• Documentation

  • Updated the modifier reference to describe the expanded modulate format.

• Bug Fixes

  • Fixed image processing for modulation values with omitted trailing options.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e9bfd8d9-ad1a-4366-9dc5-a444c4c3af6e

📥 Commits

Reviewing files that changed from the base of the PR and between 933a4e3 and ad100ae.

📒 Files selected for processing (4)

• README.md
• src/handlers/handlers.ts
• test/handlers/handlers.test.ts
• test/index.test.ts

---

📝 Walkthrough

Walkthrough

The modulate handler now supports optional brightness, saturation, hue, and lightness arguments, omits undefined options, updates documentation, and adds handler and integration tests for all supported argument arities.

Changes

Modulate support

Layer / File(s)	Summary
Four-argument handler forwarding src/handlers/handlers.ts, test/handlers/handlers.test.ts	The handler accepts lightness, conditionally builds the Sharp options object, and tests complete and omitted trailing arguments.
Modifier arity integration and documentation test/index.test.ts, README.md	Integration tests cover modifier strings with one through four arguments, and the README documents the updated syntax.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers: pi0, pi0

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: parsing all modulate arguments and adding lightness support.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/modulate-args

---

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.}