feat!: move the React bindings to material-theme-builder/react

[abernier]

Supersedes #160, same problem, opposite shape.

#160 was right about the diagnosis and the measurement — I reproduced both. It added material-theme-builder/builder as a React-free subpath. This does the inversion instead: the framework-agnostic core stays at the root, the React bindings move behind /react.

- import { Mcu, useMcu, ExportButton } from "material-theme-builder";
+ import { Mcu, useMcu, ExportButton } from "material-theme-builder/react";

  import { builder } from "material-theme-builder";  // unchanged

Why this way round

A subpath for the React-free half fixes the bundle but leaves the default import the expensive one — you'd have to know that a framework registers client references through a re-export to think of reaching for it. Since that's now the second pass on the same invariant (#156, then #160), removing the required knowledge beats documenting the workaround.

It also stops the package name from stuttering: material-theme-builder/builder on a package called material-theme-builder is a sign the root holds something other than what it says. And it's how the ecosystem splits this — motion / motion/react, @floating-ui/dom / @floating-ui/react.

Measured

Next output: "export" app, layout does nothing but builder(...).toCss() into a <style>, <Mcu> never imported. Identical app source on both sides; only the installed package shape differs (published 2.2.0 vs this branch, packed).

	client chunks (gzip)	chunk files	tonalSpot present	SSR'd CSS
2.2.0	198 715	9	yes	19 398 chars
this branch	166 679	8	no	19 398 chars

−32 036 bytes gzip, byte-identical output. Within 90 bytes of #160's figure, measured on a different app — the mechanism reproduces.

Worth noting the saving is larger than dist/react.js weighs standalone (26 184 gzip): dropping it also collapses a whole chunk. I'd flagged that arithmetic as suspicious when reviewing #160; it holds up.

Build

dist/index.js no longer references ./react.js at all, so the index build stops holding it external:

dist/index.js   33 KB   no directive -- builder, zero occurrences of "react"
dist/react.js  138 KB   "use client" -- Mcu, useMcu, ExportButton
dist/cli.js     36 KB   the CLI

attw 🟢 on all four resolution modes for all three entries, 40 tests pass, pnpm run lgtm clean.

Also

The root now exports the McuConfig type, which was previously unreachable from any entry point — it was declared in react.d.ts but never exported, and the root only re-exported builder.

Left alone

dist/react.js still carries its own copy of the builder and @material/material-color-utilities (argbFromHex ×12, TonalPalette ×10 in both bundles). Pre-existing, unchanged by this PR, and only costs anything to a client component importing builder from the root and rendering <Mcu>. Deduping needs the React sources to import through the root entry, which is its own change.

🤖 Generated with Claude Code