feat: color transforms, ramp introspection, and 0-1 value ranges

[basiclines]

Summary

Adds chainable OKLCH color transforms, ramp introspection, and normalizes value ranges to 0-1 across SDK and CLI. Based on power-user feedback from building a 384-theme terminal palette system.

Breaking Changes

• color().hsl.s, color().hsl.l now return 0-1 (was 0-100)
• color().oklch.l now returns 0-1 (was 0-100)
• String format output (.format()) unchanged — still uses CSS percentages

New Features

Color Transforms (SDK + CLI)

All transforms operate in OKLCH space, return new immutable Color instances:

color("#66b172").lighten(0.1).desaturate(0.05).hex  // bright variant
color("#f85149").set({ lightness: 0.48, chroma: 0.15 }).hex
color("#ff0000").mix("#0000ff", 0.5, "lab").hex     // color-mix
color("#ff8800").blend("#0088ff", 0.5, "multiply").hex

CLI equivalent:

rampa color "#66b172" --lighten 0.1 --desaturate 0.05
rampa color "#ff0000" --mix "#0000ff" --ratio 0.5 --space lab

Ramp Introspection

All color space results now support .at() (0-based, returns Color) and .colors() (returns Color[]):

const ramp = new LinearColorSpace("#000", "#fff").size(12);
ramp.at(3).oklch.c               // chroma at step 3
ramp.at(3).lighten(0.1).hex      // transform a ramp step
ramp.colors().map(c => c.oklch.l) // lightness curve

Commits (rebase-friendly)

1. Value range normalization — HSL/OKLCH to 0-1
2. SDK color transforms — lighten/darken/saturate/desaturate/rotate/set/mix/blend + 31 tests
3. Ramp introspection — .at() and .colors() on Linear/Plane/Cube + 19 tests
4. CLI transform flags — mirror SDK API with --flags + 13 tests
5. Documentation — SDK/CLI READMEs, AGENTS.md
6. Site demos — CLI + SDK transform demos, rebuilt browser bundle

Test Results

• SDK: 209 tests ✅ (63 new)
• CLI: 219 tests ✅ (13 new)

[github-actions]

🚀 Netlify Deploy Preview

https://feat-color-transforms-and-introspecti--rampadesign.netlify.app

[Copilot]

Pull request overview

This PR expands the SDK/CLI color capabilities by adding chainable OKLCH-based transforms, ramp introspection helpers (.at() / .colors()), and normalizing structured HSL/OKLCH component ranges to 0–1 while keeping string formatting CSS-compatible.

Changes:

• Add immutable OKLCH transforms to color() (lighten/darken/saturate/desaturate/rotate/set/mix/blend) and expose related types.
• Add ramp introspection APIs (.at(), .colors()) for Linear/Plane/Cube color spaces, plus tests.
• Update CLI rampa color to support transform flags and update docs + site demos accordingly.

Reviewed changes

Copilot reviewed 19 out of 20 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
site/js/demos.js	Adds new CLI/SDK “Color transforms” demo scripts to the site terminal demos.
site/index.html	Adds nav buttons for the new “Color transforms” demos (CLI + SDK tabs).
sdk/tests/sdk.test.ts	Updates HSL expectations to the new normalized 0–1 structured ranges.
sdk/tests/ramp-introspection.test.ts	Adds test coverage for new .at() / .colors() ramp introspection APIs.
sdk/tests/color-transforms.test.ts	Adds test coverage for new Color transform/mix/blend APIs and chaining behavior.
sdk/tests/cli-parity.test.ts	Updates parity assertions to account for normalized structured values while keeping CSS-string outputs.
sdk/src/types.ts	Extends public SDK types for transforms, introspection, and adds 'srgb' to InterpolationMode.
sdk/src/plane-color-space.ts	Implements .at() / .colors() returning full Color objects for plane results.
sdk/src/linear-color-space.ts	Implements .at() / .colors() returning full Color objects for linear results.
sdk/src/index.ts	Re-exports new OklchSetValues type.
sdk/src/cube-color-space.ts	Implements .at() / .colors() returning full Color objects for cube results.
sdk/src/color-result.ts	Adds the Color transform/mix/blend implementations and normalizes structured HSL/OKLCH values.
sdk/README.md	Documents normalized ranges, transforms, mix/blend, and ramp introspection.
cli/tests/color-transforms.test.ts	Adds CLI test coverage for new transform flags and output modes.
cli/src/inspect.ts	Normalizes structured HSL/OKLCH values to 0–1 in CLI inspection output.
cli/src/formatters/json.ts	Normalizes structured HSL/OKLCH values to 0–1 in CLI JSON output.
cli/src/color.ts	Adds transform flag parsing + transform application pipeline for rampa color.
cli/README.md	Documents new rampa color transform/mix/blend flags and examples.
AGENTS.md	Updates agent guidance with new transforms, introspection APIs, and normalized ranges.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.