feat(docs): generated API reference from TypeDoc JSON by pbroom · Pull Request #242 · pbroom/color-kit

pbroom · 2026-10-08T03:52:21Z

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 (docs: add concept pages, guides and entry-point narratives #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

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

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

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

chatgpt-codex-connector · 2026-10-08T03:52:29Z

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:56:46.950178Z	`7401630`	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.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 740163089c

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

greptile-apps · 2026-10-08T03:59:11Z

Confidence Score: 4/5

[Medium risk] Rebuilds API reference generation and documentation pages.

The PR appears safe to merge, with two non-blocking gaps in the generated reference.

Findings

Array type loses numeric indexing ▶
Component pages omit props ▶

Summary

Replaces the standalone TypeDoc HTML reference with generated API pages inside the docs site.

Derives entry points from package exports and builds linked declarations, comments, examples, and re-export lists.
Adds lazy page data, symbol search, optional MDX notes, and drift checks.
Two non-blocking documentation gaps remain: interface index signatures are dropped, and forwardRef component pages omit props.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Exports["Package exports"] --> Entries["Source entry points"]
  Entries --> TypeDoc["TypeDoc JSON"]
  TypeDoc --> Normalize["Normalize types, comments and links"]
  Normalize --> Routes["Route index and symbol search"]
  Normalize --> Pages["Entry and symbol JSON"]
  Pages --> Reference["API pages and Signature"]
  Notes["Optional MDX notes"] --> Reference
  Reference --> Prerender["Prerendered site"]

_{Reviews (1) · Last reviewed commit: "feat(docs): generated API reference from..." · Reviewed by Greptile}

pbroom

Reviewed the full incremental PR and its corrections at f2e5f6f9f6649bfc1826be1d0492cb73f1fde2cc. Index signatures, forwarded-ref Props/signatures and dangling parameter anchors corrected. 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:20 PM UTC: Graphite rebased this pull request as part of a merge.
Oct 10, 8:21 PM UTC: @pbroom merged this pull request with Graphite.

Replace the TypeDoc HTML output in /reference with a generated reference built into the site: - scripts/api: TypeDoc JSON (.typedoc/api.json) for every entry point in packages/color-kit/package.json#exports, normalized into src/generated/api.json plus per-entry and per-symbol page files typed by src/api/model.ts. One page per declaration in its most specific entry; other entries list it as a re-export. Links resolve at generation time. - /api, /api/:entry (domains, kind glyphs, narrative MDX slot, re-exports) and /api/:entry/:Symbol (declaration, params, returns, throws, build-time highlighted examples, notes MDX slot, see also, also exported from, source link at the commit), all prerendered. - <Signature> implements the S1 contract, with <Params>, <TypeLink> and responsive one-parameter-per-line layout. - ⌘K symbol hits come from the API routes, ranked by name, word and initials. - Drift test: every facade .d.ts export has a page, every exports subpath is documented, every /api link resolves. Co-Authored-By: Claude Opus 5.5 <[email protected]>

vercel · 2026-10-10T20:19:45Z

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 S3: the live plane hero on the home page, plus the example system. **Home page** - Headline: "A queryable OKLCH color engine.", set over a live hue slice of OKLCH (chroma × lightness). - `sense(plane)` answers three queries: - the sRGB region - the Display P3 boundary - the WCAG AA region on white or black, chosen by the theme - Underneath, a 160×160 `toP3Into` loop paints a display-p3 canvas. - The first frame (hue 264) is computed in Node at build time via `?build`. The SVG prerenders and hydrates from the same JSON, and `color-kit/plane` loads lazily after hydration. - Hue is set with a native range input that has `aria-valuetext`, or by dragging horizontally on the plane. Updates are rAF-throttled. - Below the hero: its own source, the install line and three "what you can ask" links. - Follow-up commit: the hero axes get every tick and separate axis titles. **Examples** - `<Example>` renders the live component above its source, which is highlighted at build time. It collapses long sources and isolates failures. - `plugins/eval-example.ts` fills in `// →` results by running each snippet against the color-kit source. This is documented in `src/examples/README.md`. - The graphics demos get `*Example` wrappers. - The old Sandpack plane quick start is now a real example in `src/examples/plane/quick-start.tsx`. **Contract changes** (backwards compatible) - `<Example>`'s `source` also accepts the `?highlighted` module. - New `collapseAfter` prop. - New `?build` imports. - Prerender links route-chunk CSS. - ESLint allows bare expressions in example snippets. Rebased onto #242 with no conflicts. The `eslint.config.js` and styles changes merged cleanly with S2's; the `api.css` import and the example-snippet rule are both kept. ## Verified - On this branch: `pnpm build` and `pnpm test`. - Bundle check passes: the largest chunk is 194.8 kB against a 200 kB limit, and home initial JS is 100.2 kB gzip against a 110 kB limit. - Docs tests pass: 601 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: - Dragging the hero hue slider from 264° to 65° recomputes the geometry (about 3.8 ms of queries plus paint). - In light theme the contrast reference flips to white. - At 375 px the hero fits 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)

chatgpt-codex-connector Bot reviewed Oct 8, 2026

View reviewed changes

Comment thread apps/docs/scripts/api/normalize.mjs

Comment thread apps/docs/scripts/api/normalize.mjs Outdated

greptile-apps Bot reviewed Oct 8, 2026

View reviewed changes

Comment thread apps/docs/scripts/api/normalize.mjs Outdated

Comment thread apps/docs/scripts/api/normalize.mjs

This was referenced Oct 8, 2026

fix(driver): validate the gamut in getColorAreaFallbackPoint #230

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 docs/s2-api-reference branch from 7401630 to e987661 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:14

View deployment

pbroom force-pushed the docs/s2-api-reference branch from e987661 to f2e5f6f 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

vercel Bot deployed to Preview October 8, 2026 18:46

View deployment

pbroom commented Oct 8, 2026

View reviewed changes

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 refactor/plane-budget-and-surface branch from 10e0964 to 83eb6ab Compare October 10, 2026 02:39

pbroom force-pushed the docs/s2-api-reference branch from f2e5f6f to 1855790 Compare October 10, 2026 02:39

vercel Bot deployed to Preview October 10, 2026 03:03

View deployment

pbroom changed the base branch from refactor/plane-budget-and-surface to graphite-base/242 October 10, 2026 20:16

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

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

fix(docs): preserve index signatures and valid parameter anchors

bdd042a

fix(docs): document forwardRef component props and signatures

c7b93f3

pbroom force-pushed the docs/s2-api-reference branch from 1855790 to c7b93f3 Compare October 10, 2026 20:19

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

pbroom deleted the docs/s2-api-reference branch October 10, 2026 20:21

Navigation Menu

Repository navigation

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

feat(docs): generated API reference from TypeDoc JSON#242
pbroom merged 3 commits into
mainfrom
docs/s2-api-reference

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!

chatgpt-codex-connector Bot left a comment

Uh oh!

Uh oh!

Uh oh!

greptile-apps Bot commented Oct 8, 2026 •

edited

Loading

Uh oh!

Uh oh!

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!

Summary

Verified

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!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

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

Uh oh!

Confidence Score: 4/5

Findings

Summary

Uh oh!

Uh oh!

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

greptile-apps Bot commented Oct 8, 2026 •

edited

Loading

pbroom commented Oct 10, 2026 •

edited

Loading