@csszyx/mcp-server 0.10.4 → 0.10.6

package/dist/index.mjs

@@ -178,6 +178,28 @@ Without it: \`Property 'sz' does not exist on type 'DetailedHTMLProps<...>'\`.
 \`\`\`tsx
 <div sz={{ p: 4, bg: 'blue-500', hover: { bg: 'blue-700' } }} />
 \`\`\`
+
+## Troubleshooting
+- **"No prebuilt native binary" warning / \`native engine unavailable\`**: the
+  default \`rust\` parser's native binary is missing (unsupported arch, optional
+  deps omitted, or a cross-platform frozen lockfile). It is NOT broken and classes
+  are UNCHANGED \u2014 all three engines (rust/oxc/babel) emit identical output
+  (parity-gated). If you only use the default, csszyx auto-falls back to \`oxc\` and
+  the build succeeds; ignore the warning or set \`build.parser: 'oxc'\` to silence
+  it. Only an EXPLICIT \`parser:'rust'\` hard-fails. Do NOT tell the user to debug
+  their styles over this.
+- **A class generates no CSS**: it wasn't safelisted. The file must contain a
+  statically analyzable \`sz=\` or \`szv(\` (the prescan qualifies files by those
+  tokens). Arbitrary values (\`m:'20px'\`\u2192\`m-[20px]\`) and large numbers
+  (\`p:100\`\u2192\`p-100\`) DO work \u2014 a missing class is a safelisting issue, not a
+  lowering one. For a sibling workspace package, opt it in with
+  \`compileSources: ['packages/name']\`. In a monorepo, scope Tailwind to the
+  generated safelist file.
+- **\`dynamic()\` vs build-time**: \`dynamic()\` is an escape hatch (runtime CSS
+  injection, not mangled) \u2014 use ONLY for values unknown at build (JSON/API/user
+  config). Literals and finite variant sets are build-time: \`sz\` / \`szv\`. To
+  resolve \`szv\` output to a className by hand, use \`szr\` (build-time-safe,
+  mangle-aware), not \`dynamic()\`.
 `;
 function listResources() {
   return [

package/llms-full.txt

@@ -3480,16 +3480,31 @@ SSR-safe: on the server, returns class names without CSSOM access.
 
 ## Runtime Helpers
 
-For dynamic classes at runtime (the only runtime overhead):
+For dynamic classes at runtime (the only runtime overhead). Use these PUBLIC,
+hand-written names (no `_` prefix — `_`-prefixed helpers like `_sz`/`_szMerge`
+are compiler-injected, do not hand-author them):
+
+- **`szr(...)`** — resolve sz OBJECT(s) and/or class strings → a mangle-aware
+  className (concatenates, filters falsy). The hand-name for the injected `_sz`.
+  Reach for it to build a className from `szv` factory output (e.g. a code-split
+  layout that declares variants in a `.ts` module and resolves them in a `.tsx`).
+- **`szcn(...)`** — merge className STRINGS with last-wins override on a
+  same-utility conflict, mangle-aware (the Box-level merge).
+- `szr` takes sz OBJECTS and concatenates; `szcn` takes STRINGS and overrides.
 
 ```tsx
-import { _sz, _szMerge } from '@csszyx/runtime';
+import { szr, szv, szcn } from '@csszyx/runtime';
+
+const cardSz = szv({ variants: { pad: { lg: { p: 8 } } } });
+
+// Resolve szv factory output → className (the split / no-`sz=` use case)
+<div className={szr(cardSz({ pad: 'lg' }), isWide && stackSz({ gap: 'xl' }))} />
 
 // Concatenate class strings
-<div className={_sz('base-class', conditionalClass)} />
+<div className={szr('base-class', conditionalClass)} />
 
-// Conditional class — plain JS conditionals compose with _sz
-<div className={_sz('base-class', isActive && 'active-class')} />
+// Conditional class — plain JS conditionals compose with szr
+<div className={szr('base-class', isActive && 'active-class')} />
 <div className={isActive ? 'active-class' : 'inactive-class'} />
 
 // Switch/enum — a plain object lookup
@@ -3499,8 +3514,8 @@ import { _sz, _szMerge } from '@csszyx/runtime';
   success: 'border-green-500',
 }[status]} />
 
-// Merge (last wins for conflicts)
-<div className={_szMerge(baseClasses, overrideClasses)} />
+// Merge className strings, last-wins for same-utility conflicts
+<div className={szcn(baseClasses, overrideClasses)} />
 ```
 
 For color CSS variables:
@@ -3571,9 +3586,16 @@ csszyx has two worlds; pick by "is the value set finite and known at build time?
   generated + injected in the browser via insertRule. Escape hatch only.
 
 Engines (BUILD-TIME parse of JSX source only): Rust native (default) → oxc (JS
-fallback) → babel (last resort). The RUNTIME has no parser: `_sz`/`szv`/`splitBox`
-are plain JS; `dynamic()` lowers an sz OBJECT via `@csszyx/compiler/browser` (pure
-JS, no JSX parsing).
+fallback) → babel (last resort). All three emit IDENTICAL classes (parity-gated) —
+engine only affects build speed, never output. The native binary ships as
+per-platform optional deps (`@csszyx/core-*`); if it's missing (unsupported arch,
+omitted optional deps, cross-platform frozen lockfile) the DEFAULT `rust` auto-
+degrades to `oxc` with a one-time warning — builds still succeed with identical
+classes. An EXPLICIT `parser:'rust'` (config or `CSSZYX_PARSER=rust`) hard-fails
+instead. Don't tell users a missing native binary breaks csszyx or changes
+classes; tell them to ignore the warning or set `build.parser:'oxc'`. The RUNTIME
+has no parser: `_sz`/`szr`/`szv`/`splitBox` are plain JS; `dynamic()` lowers an sz
+OBJECT via `@csszyx/compiler/browser` (pure JS, no JSX parsing).
 
 Helper build-time/runtime:
 
@@ -3584,8 +3606,12 @@ Helper build-time/runtime:
 - `splitBox`/`splitBoxSz` → RUNTIME routing only (pure JS). They re-partition
   existing classes; they emit no new CSS and do NOT force `dynamic()`. CSS comes
   from the static source (a literal or a szv config).
-- `dynamic()` → the only helper that generates CSS at runtime, and only for a
-  class not already in the built CSS.
+- `dynamic()` → ESCAPE HATCH, not a default. The only helper that generates CSS at
+  RUNTIME (injects rules), and the only one that is NOT mangled + has a security
+  surface. Use ONLY when style values come from runtime data unknown at build
+  (JSON/API/user config: `sz={{ w: serverValue }}`), or the rare case build-time
+  helpers can't express it. A literal or a finite set of choices is ALWAYS
+  build-time (`sz`/`szv`) — do not reach for `dynamic()` there.
 
 Safelist requires a statically analyzable position (a literal sz, or a szv config
 literal). File discovery: the prescan scans any file containing `sz=`/`sz:` or a
@@ -3768,10 +3794,25 @@ npx @csszyx/cli migrate src/           # migrate all JSX/TSX/HTML under src/
 npx @csszyx/cli migrate --dry-run      # preview changes without writing files
 npx @csszyx/cli migrate --ignore "**/*.test.tsx,**/fixtures/**"
 npx @csszyx/cli migrate --pattern "src/components/**/*.tsx"
+npx @csszyx/cli migrate --keys-only    # upgrade existing csszyx code: normalize sz KEYS only, leave className untouched
 ```
 
 Migration logs are written to `.csszyx/logs/`. Add `.csszyx/` to `.gitignore`.
 
+### `--keys-only` — upgrade existing csszyx code (not a Tailwind→sz migration)
+
+Plain `migrate` converts Tailwind `className` strings into `sz` props — for
+adopting csszyx. If you ALREADY use csszyx and are bumping a version that renamed
+sz-prop keys to their canonical form (e.g. the 0.9.10 → 0.10.0 key normalization),
+use `--keys-only`: it rewrites legacy sz-prop keys to canonical inside `sz={...}`
+and leaves `className` (and everything else) completely untouched. It only edits
+JSX/TSX (HTML has no sz objects). This is the safe, surgical upgrade path — it
+won't touch your hand-written classes.
+
+```bash
+npx @csszyx/cli migrate --keys-only --dry-run   # preview the key rewrites first
+```
+
 ### Audit — discover unrecognized classes
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@csszyx/mcp-server",
-  "version": "0.10.4",
+  "version": "0.10.6",
   "description": "Model Context Protocol (MCP) server for csszyx — enables AI agents to understand and generate sz props",
   "license": "MIT",
   "type": "module",
@@ -30,9 +30,9 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^3.23.8",
-    "@csszyx/cli": "0.10.4",
-    "@csszyx/unplugin": "0.10.4",
-    "@csszyx/compiler": "0.10.4"
+    "@csszyx/compiler": "0.10.6",
+    "@csszyx/unplugin": "0.10.6",
+    "@csszyx/cli": "0.10.6"
   },
   "devDependencies": {
     "typescript": "^6.0.3",