refactor(core)!: derive plane query budgets from step counts and drop PlaneWithSense by pbroom · Pull Request #241 · pbroom/color-kit

pbroom · 2026-10-08T03:27:49Z

The gamut-boundary, chroma-band and gradient query specs budgeted
steps ?? 48, but their solvers default to 100, 12 and 16 samples, and
adaptive sampling ignores steps. Budgets now use the shared solver
defaults and estimate adaptive paths from adaptiveTolerance and
adaptiveMaxDepth (calibrated against traced point counts).

PlaneWithSense was exported but nothing produced it (sense() returns
PlaneSense), so it is removed from the core and plane barrels.

BREAKING CHANGE: the PlaneWithSense type is removed; use
Plane & PlaneSense.

Found while documenting the public API in #235. Each finding was reproduced against the built package before the fix, has a regression test, and its affected JSDoc examples were recomputed. lint, build, test, format:check, typecheck, size, check:artifacts, check:preprod and agents:check:strict pass.

Part of the color-kit assessment stack.

🤖 Generated with Claude Code

vercel · 2026-10-08T03:27:56Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
color-kit	Ready	Preview	Oct 10, 2026 2:52am UTC

chatgpt-codex-connector · 2026-10-08T03:27:58Z

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-08T03:30:47.712108Z	`d76f9ad`	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

pbroom

Reviewed the full incremental PR and its corrections at 10e096450c72d1cbbff17156f7234b7374c2f7c5. Adaptive budgeting/public surface reviewed; inherited finite-integer validation applied to shared gradient budget helper with regressions. No remaining actionable findings in the reviewed scope.

Independent correction re-reviews and stack preservation verification passed. At the integrated tip, lint, full build/DTS, 2,208 tests, formatting, strict agent checks and 14 built-site Chrome tests passed. All recorded actionable review threads are addressed. Hosted CI is being verified separately; this review does not authorize merge or release.

pbroom · 2026-10-10T18:47:23Z

Merge activity

Oct 10, 6:47 PM UTC: A user started a stack merge that includes this pull request via Graphite.
Oct 10, 8:17 PM UTC: Graphite rebased this pull request as part of a merge.
Oct 10, 8:18 PM UTC: @pbroom merged this pull request with Graphite.

… PlaneWithSense The gamut-boundary, chroma-band and gradient query specs budgeted `steps ?? 48`, but their solvers default to 100, 12 and 16 samples, and adaptive sampling ignores steps. Budgets now use the shared solver defaults and estimate adaptive paths from adaptiveTolerance and adaptiveMaxDepth (calibrated against traced point counts). PlaneWithSense was exported but nothing produced it (sense() returns PlaneSense), so it is removed from the core and plane barrels. BREAKING CHANGE: the PlaneWithSense type is removed; use Plane & PlaneSense. Co-Authored-By: Claude Opus 5.5 <[email protected]>

The adaptive gamut-boundary and chroma-band budget counted output points, but every visited segment runs adaptiveMaxErrorProbe (three maxChromaAt searches). Estimate anchors + 3 * (segments + 2R) searches instead, so the default adaptive query budgets 77 (sm) rather than 17 (xs). Co-Authored-By: Claude Opus 5.5 <[email protected]>

vercel · 2026-10-10T20:16:41Z

Deployment failed for project color-kit with the following error:

Resource is limited - try again in 24 hours (more than 100, code: "api-deployments-free-per-day").

Learn More: https://vercel.com/pbrooms-projects?upgradeToPro=build-rate-limit

## Summary Docs overhaul slice S2: a generated API reference built into the site. It replaces the TypeDoc HTML output that used to live in `/reference`. - **Generator** (`apps/docs/scripts/api`). It runs TypeDoc JSON for every entry point in `packages/color-kit/package.json#exports`. - The JSON is normalized into `src/generated/api.json`, plus page files per entry and per symbol, typed by `src/api/model.ts`. All of these are gitignored and built by `pnpm docs:api`. - Each declaration gets one page, in its most specific entry. Other entries list it as a re-export. - Links resolve at generation time. - **Routes**, all prerendered: - `/api`. - `/api/:entry`: domains, kind glyphs, a narrative MDX slot and re-exports. - `/api/:entry/:Symbol`: declaration, params, returns, throws, build-time highlighted examples, a notes MDX slot, see also, "also exported from" and a source link at the commit. - **`<Signature>`** implements the S1 contract. It comes with `<Params>`, `<TypeLink>` and a responsive layout with one parameter per line. - **⌘K**: symbol hits come from the API routes, ranked by name, word and initials. - **Drift test** checks three things: - every export in the facade `.d.ts` has a page - every exports subpath is documented - every `/api` link resolves Rebased onto #241 with no conflicts. The generated reference reflects the #237–#241 surface; for example, `PlaneWithSense` has no page. ## Verified - On this branch: `pnpm build` and `pnpm test`. - Builds 523 prerendered routes. - Bundle check passes: the largest chunk is 194.8 kB against a 200 kB limit, and home initial JS is 91.0 kB gzip against a 110 kB limit. - Docs tests pass: 584 tests. - At the stack top (#244): lint, format:check, typecheck, size, check:artifacts, check:preprod and agents:check:strict all pass. - Browser checks at the stack top: - `/api/plane/sense` and `/api/core/Color` render. - ⌘K returns symbol hits and opens the selected page. - No horizontal scroll at 375 px. - No console errors or hydration warnings. Part of the color-kit assessment stack. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

Delete the last legacy page (_legacy/api/plane-api.mdx); its quick start now lives in src/examples/plane and its prose in the plane narrative and concepts. The content link test now resolves internal links against the route registry built from the generated API data, so /api links must name a generated page (canonical entry only) instead of a barrel export parsed from source. Member anchors stay with the API drift test. Reflect the #237-#241 behaviour fixes: the headless picker guide notes that the driver rejects 'p3' and adds a typed-input section showing that percentages in an expression are positions in the range; the core narrative notes saturate/desaturate are uncapped above 0.4; the plane narrative notes planeHue returns an OKLCH hue. Co-Authored-By: Claude Opus 5.5 <[email protected]>

## Summary Docs overhaul slice S4: concept pages, guides and narratives for each entry point. A small commit on top finishes the integration with S2, S3 and #237–#241. **Content** - Five concepts: - OKLCH-canonical colors - requested vs displayed - planes and queries - gamut and tolerance - contrast - Five guides, each with one live example under `src/examples/{guides,driver}`: - a headless picker with `color-kit/driver` - `color-kit/react` - contrast-aware palettes - GPU and three.js interop - performance - A narrative `index.mdx` for each of the core, plane, interop, compute, hct and driver entry points. - A polished `/start` quick start. - The mined legacy MDX is deleted. **Integration commit** - Deletes the last legacy page, `_legacy/api/plane-api.mdx`, which had the stray "normalized" aside. Its quick start is now in S3's `src/examples/plane/quick-start.tsx`. No `_legacy` files remain. - Rewrites the content link test to check against the route registry built from the generated API data. Every `/api` link must name a generated page, which means the canonical entry only, so root re-exports fail. Member anchors stay with S2's drift test. - Brings the content in line with #237–#241: - The headless picker guide notes that the driver rejects `'p3'` with the same `TypeError` as core. - A new "Typed input" section shows that a `%` in an expression is a position in the range, so `50% * 2` on `[100, 200]` gives 300. - The core narrative says `saturate`/`desaturate` clamp chroma only at 0. - The plane narrative says `planeHue` returns an OKLCH hue. - No content references `PlaneWithSense`. ## Verified - `pnpm build` and `pnpm test` pass. Docs tests pass: 792 tests, including the content link test and the API drift test. - A negative check confirms that `/api/core/definePlane` and `/api/core/PlaneWithSense` fail the link test. - The new snippet values were checked against the built facade. - These gates pass: lint, format:check, typecheck, size, check:artifacts, check:preprod and agents:check:strict. - Docs chunk budget: the largest chunk is 194.8 kB against a 200 kB limit. - Docs home budget: home initial JS is 101.6 kB gzip against a 110 kB limit. - Browser checks on the built site: - home hero drag - `/start` - `/concepts/planes-and-queries` - `/guides/headless-picker` - `/api/plane/sense` - `/api/core/Color` - ⌘K - light and dark themes - 375 px with no horizontal scroll - no console errors or hydration warnings Part of the color-kit assessment stack. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

This was referenced Oct 8, 2026

feat(docs): generated API reference from TypeDoc JSON #242

Merged

feat(docs): live plane hero on home and the example system #243

Merged

feat(docs): native API map at /api/map #245

Merged

feat(docs): syntax highlighting palette for code samples #246

Merged

pbroom force-pushed the fix/react-input-aria-label branch from 38b646c to d9bdd09 Compare October 8, 2026 17:04

pbroom force-pushed the refactor/plane-budget-and-surface branch from ed25431 to 8ae2a67 Compare October 8, 2026 17:04

vercel Bot deployed to Preview October 8, 2026 17:16

View deployment

pbroom force-pushed the fix/react-input-aria-label branch from d9bdd09 to e3a0a11 Compare October 8, 2026 18:45

pbroom force-pushed the refactor/plane-budget-and-surface branch from 8ae2a67 to 10e0964 Compare October 8, 2026 18:45

pbroom commented Oct 8, 2026

View reviewed changes

vercel Bot deployed to Preview October 8, 2026 19:01

View deployment

This was referenced Oct 9, 2026

feat(react): add plane renderer, geometry and adaptive-quality hooks #247

Merged

docs(react): rebuild the React docs around the plane hooks #248

Merged

refactor(react)!: remove UI components; ship state and plane hooks only #249

Merged

pbroom force-pushed the fix/react-input-aria-label branch from e3a0a11 to ff99bfe Compare October 10, 2026 02:39

pbroom force-pushed the refactor/plane-budget-and-surface branch from 10e0964 to 83eb6ab Compare October 10, 2026 02:39

vercel Bot deployed to Preview October 10, 2026 02:52

View deployment

pbroom changed the base branch from fix/react-input-aria-label to graphite-base/241 October 10, 2026 20:14

pbroom changed the base branch from graphite-base/241 to main October 10, 2026 20:15

pbroom and others added 3 commits October 10, 2026 20:16

test(core): reject invalid gradient budget step counts

fefbf45

pbroom force-pushed the refactor/plane-budget-and-surface branch from 83eb6ab to fefbf45 Compare October 10, 2026 20:16

pbroom merged commit d76ddcd into main Oct 10, 2026
5 of 6 checks passed

pbroom deleted the refactor/plane-budget-and-surface branch October 10, 2026 20:18

Navigation Menu

Repository navigation

refactor(core)!: derive plane query budgets from step counts and drop PlaneWithSense - #241

refactor(core)!: derive plane query budgets from step counts and drop PlaneWithSense#241
pbroom merged 3 commits into
mainfrom
refactor/plane-budget-and-surface

pbroom commented Oct 8, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Oct 8, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector Bot commented Oct 8, 2026 •

edited

Loading

Uh oh!

pbroom left a comment

Uh oh!

pbroom commented Oct 10, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Oct 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

pbroom commented Oct 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel Bot commented Oct 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chatgpt-codex-connector Bot commented Oct 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codex Review Summary

Uh oh!

pbroom left a comment

Choose a reason for hiding this comment

Uh oh!

pbroom commented Oct 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge activity

Uh oh!

vercel Bot commented Oct 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

pbroom commented Oct 8, 2026 •

edited

Loading

vercel Bot commented Oct 8, 2026 •

edited

Loading

chatgpt-codex-connector Bot commented Oct 8, 2026 •

edited

Loading

pbroom commented Oct 10, 2026 •

edited

Loading