@csszyx/mcp-server 0.10.5 → 0.10.7

package/dist/index.mjs

@@ -6,7 +6,7 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import fs from 'node:fs';
-import { SPECIAL_VARIANTS, KNOWN_VARIANTS, PROPERTY_MAP, transform, SUGGESTION_MAP, BOOLEAN_SHORTHANDS } from '@csszyx/compiler';
+import { SPECIAL_VARIANTS, KNOWN_VARIANTS, PROPERTY_MAP, transform, SUGGESTION_MAP, BOOLEAN_SHORTHANDS, REMOVED_BOOLEAN_SUGAR } from '@csszyx/compiler';
 import { z } from 'zod';
 import { migrateSource, classNameToSzObject } from '@csszyx/cli';
 import { parseThemeBlocks, hasTokens } from '@csszyx/unplugin';
@@ -112,8 +112,22 @@ Key csszyx syntax:
   }
 }
 
-const packageRoot = path.resolve(fileURLToPath(import.meta.url), "../../..");
-const LLMS_FULL_PATH = path.join(packageRoot, "llms-full.txt");
+function resolveLlmsFullPath() {
+  let dir = path.dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 6; i++) {
+    const candidate = path.join(dir, "llms-full.txt");
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) {
+      break;
+    }
+    dir = parent;
+  }
+  return path.resolve(fileURLToPath(import.meta.url), "../../..", "llms-full.txt");
+}
+const LLMS_FULL_PATH = resolveLlmsFullPath();
 const SETUP_GUIDE = `# csszyx setup
 
 Fastest path: run \`csszyx init\` (it does everything below). Manual steps:
@@ -178,6 +192,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 [
@@ -551,6 +587,15 @@ function handleValidate(input) {
       });
       continue;
     }
+    const removed = REMOVED_BOOLEAN_SUGAR[key];
+    if (removed && input.sz[key] === true) {
+      errors.push({
+        key,
+        message: `'${key}: true' boolean sugar was removed; it emits no class.`,
+        suggestion: `Use { ${removed.key}: ${JSON.stringify(removed.value)} } instead.`
+      });
+      continue;
+    }
     const isProperty = key in PROPERTY_MAP;
     const isBoolean = BOOLEAN_SHORTHANDS.has(key);
     const isVariant = KNOWN_VARIANTS.has(key);

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@csszyx/mcp-server",
-  "version": "0.10.5",
+  "version": "0.10.7",
   "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.5",
-    "@csszyx/unplugin": "0.10.5",
-    "@csszyx/compiler": "0.10.5"
+    "@csszyx/compiler": "0.10.7",
+    "@csszyx/unplugin": "0.10.7",
+    "@csszyx/cli": "0.10.7"
   },
   "devDependencies": {
     "typescript": "^6.0.3",