@csszyx/mcp-server 0.12.0 → 0.13.0

package/README.md

@@ -53,15 +53,16 @@ The server speaks MCP over stdio, so any MCP-compatible client uses the same
 
 ## Tools
 
-| Tool              | Purpose                                                              |
-| ----------------- | -------------------------------------------------------------------- |
-| `csszyx_expand`   | Expand one `sz` object into a Tailwind class string                  |
-| `csszyx_batch`    | Expand many `sz` objects in one call                                 |
-| `csszyx_reverse`  | Convert a Tailwind class string back into an `sz` object             |
-| `csszyx_validate` | Validate an `sz` object; reports unknown props and CSS-name mistakes |
-| `csszyx_lookup`   | Look up how a CSS property/keyword maps to an `sz` key               |
-| `csszyx_migrate`  | Rewrite a JSX/TSX snippet's `className` attributes into `sz` props   |
-| `csszyx_theme`    | Parse `@theme` CSS blocks and categorize design tokens               |
+| Tool                     | Purpose                                                                                         |
+| ------------------------ | ----------------------------------------------------------------------------------------------- |
+| `csszyx_expand`          | Expand one `sz` object into a Tailwind class string                                             |
+| `csszyx_batch`           | Expand many `sz` objects in one call                                                            |
+| `csszyx_reverse`         | Convert a Tailwind class string back into an `sz` object                                        |
+| `csszyx_validate`        | Validate an `sz` object; reports unknown props and CSS-name mistakes                            |
+| `csszyx_lookup`          | Look up how a CSS property/keyword maps to an `sz` key                                          |
+| `csszyx_migrate`         | Rewrite a JSX/TSX snippet's `className` attributes into `sz` props                              |
+| `csszyx_theme`           | Parse `@theme` CSS blocks and categorize design tokens                                          |
+| `csszyx_compile_preview` | Compile a whole source module and report the classes, diagnostics, and leftover runtime helpers |
 
 ## Resources
 

package/dist/index.d.mts

@@ -8,7 +8,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
  * understand and generate csszyx sz props.
  *
  * Architecture follows Tier-1 Proxy patterns:
- * - 7 Stateless Sandbox tools (no destructive edits)
+ * - 8 Stateless Sandbox tools (no destructive edits)
  * - 3 Reference Data Endpoints
  * - Unified Single Source of Truth via @csszyx/compiler and @csszyx/unplugin
  *
@@ -33,6 +33,8 @@ declare const TOOLS: ({
             injectTodos?: undefined;
             items?: undefined;
             css?: undefined;
+            source?: undefined;
+            filename?: undefined;
         };
         required: string[];
     };
@@ -53,6 +55,8 @@ declare const TOOLS: ({
             injectTodos?: undefined;
             items?: undefined;
             css?: undefined;
+            source?: undefined;
+            filename?: undefined;
         };
         required: string[];
     };
@@ -73,6 +77,8 @@ declare const TOOLS: ({
             injectTodos?: undefined;
             items?: undefined;
             css?: undefined;
+            source?: undefined;
+            filename?: undefined;
         };
         required: string[];
     };
@@ -99,6 +105,8 @@ declare const TOOLS: ({
             query?: undefined;
             items?: undefined;
             css?: undefined;
+            source?: undefined;
+            filename?: undefined;
         };
         required: string[];
     };
@@ -122,6 +130,8 @@ declare const TOOLS: ({
             customMap?: undefined;
             injectTodos?: undefined;
             css?: undefined;
+            source?: undefined;
+            filename?: undefined;
         };
         required: string[];
     };
@@ -142,6 +152,33 @@ declare const TOOLS: ({
             customMap?: undefined;
             injectTodos?: undefined;
             items?: undefined;
+            source?: undefined;
+            filename?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            source: {
+                type: "string";
+                description: string;
+            };
+            filename: {
+                type: "string";
+                description: string;
+            };
+            sz?: undefined;
+            classes?: undefined;
+            query?: undefined;
+            code?: undefined;
+            customMap?: undefined;
+            injectTodos?: undefined;
+            items?: undefined;
+            css?: undefined;
         };
         required: string[];
     };

package/dist/index.mjs

@@ -6,7 +6,7 @@ import { fileURLToPath } from 'node:url';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-import { sortStrings, SPECIAL_VARIANTS, KNOWN_VARIANTS, PROPERTY_MAP, transform, SUGGESTION_MAP, BOOLEAN_SHORTHANDS, REMOVED_BOOLEAN_SUGAR } from '@csszyx/compiler';
+import { sortStrings, SPECIAL_VARIANTS, KNOWN_VARIANTS, PROPERTY_MAP, transform, transformSourceCode, 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';
@@ -333,6 +333,80 @@ function handleBatch(input) {
   };
 }
 
+const compilePreviewSchema = z.object({
+  source: z.string().describe(
+    "A source module to compile. Include the code AROUND the sz prop \u2014 imports, the factory call, the component \u2014 since that is what decides whether csszyx can compile it."
+  ),
+  filename: z.string().optional().describe(
+    "Filename to attribute diagnostics to. The extension selects the parser, so use .tsx for JSX. Defaults to preview.tsx."
+  )
+});
+const RUNTIME_HELPERS = [
+  ["_sz", "usesRuntime"],
+  ["_szMerge", "usesMerge"],
+  ["_szPart", "usesSzPart"],
+  ["szcn", "usesSzcn"],
+  ["__szvPick", "usesSzvPick"],
+  ["__szvPick1", "usesSzvPick1"],
+  ["__szColorVar", "usesColorVar"],
+  ["__szSpacingVar", "usesSpacingVar"],
+  ["__szUnitVar", "usesUnitVar"]
+];
+function restoreEnv(name, value) {
+  if (value === void 0) {
+    delete process.env[name];
+    return;
+  }
+  process.env[name] = value;
+}
+function compileWithDiagnostics(source, filename) {
+  const warnings = [];
+  const originalWarn = console.warn;
+  const originalNodeEnv = process.env.NODE_ENV;
+  const originalQuiet = process.env.CSSZYX_QUIET_SZ_WARNINGS;
+  console.warn = (...args) => {
+    warnings.push(args.map(String).join(" "));
+  };
+  process.env.NODE_ENV = "development";
+  delete process.env.CSSZYX_QUIET_SZ_WARNINGS;
+  try {
+    return { result: transformSourceCode(source, filename), warnings };
+  } finally {
+    console.warn = originalWarn;
+    restoreEnv("NODE_ENV", originalNodeEnv);
+    restoreEnv("CSSZYX_QUIET_SZ_WARNINGS", originalQuiet);
+  }
+}
+function handleCompilePreview(input) {
+  const { result, warnings } = compileWithDiagnostics(
+    input.source,
+    input.filename ?? "preview.tsx"
+  );
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(
+          {
+            transformed: result.transformed,
+            code: result.code,
+            // Emission order, not sorted: this is the order the
+            // element actually carries, and reordering it would
+            // hide a cascade question the preview is asked about.
+            classes: [...result.classes],
+            diagnostics: [...result.diagnostics, ...warnings],
+            runtimeHelpers: RUNTIME_HELPERS.filter(
+              ([, flag]) => result[flag] === true
+            ).map(([name]) => name)
+          },
+          null,
+          2
+        )
+      }
+    ]
+  };
+}
+
 const expandSchema = z.object({
   sz: z.record(z.string(), z.any()).describe(
     "The sz prop object to expand. Example: { p: 4, bg: 'blue-500', hover: { bg: 'blue-700' } }"
@@ -773,6 +847,24 @@ const TOOLS = [
       },
       required: ["css"]
     }
+  },
+  {
+    name: "csszyx_compile_preview",
+    description: "Compile a whole SOURCE MODULE and report what csszyx made of it: the rewritten code, the classes, the diagnostics, and the runtime helpers left over. Use this when the question is about the code AROUND the sz prop \u2014 whether a szv factory precompiles, whether a value stays dynamic, whether a key is unknown. For a bare sz object, use csszyx_expand instead.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        source: {
+          type: "string",
+          description: "A source module, including its imports and component. Example: export const A = () => <div sz={{ p: 4 }} />;"
+        },
+        filename: {
+          type: "string",
+          description: "Filename to attribute diagnostics to. The extension selects the parser, so use .tsx for JSX. Defaults to preview.tsx."
+        }
+      },
+      required: ["source"]
+    }
   }
 ];
 const TOOL_HANDLERS = {
@@ -782,7 +874,11 @@ const TOOL_HANDLERS = {
   csszyx_lookup: { schema: lookupSchema, handler: handleLookup },
   csszyx_migrate: { schema: migrateSchema, handler: handleMigrate },
   csszyx_batch: { schema: batchSchema, handler: handleBatch },
-  csszyx_theme: { schema: themeSchema, handler: handleTheme }
+  csszyx_theme: { schema: themeSchema, handler: handleTheme },
+  csszyx_compile_preview: {
+    schema: compilePreviewSchema,
+    handler: handleCompilePreview
+  }
 };
 server.server.setRequestHandler(ListToolsRequestSchema, async () => {
   return { tools: TOOLS };

package/llms-full.txt

@@ -367,14 +367,15 @@ value position — `p`, `bg`, `m`, `w`, `text`, …, not just font-size):
 
 Handling `group-*`, `peer-*`, and arbitrary variants.
 
-| Concept                | CSS Rule                              | Tailwind v4 Class         | `sz` Prop (Object Syntax)                   | Note                                                          |
-| :--------------------- | :------------------------------------ | :------------------------ | :------------------------------------------ | :------------------------------------------------------------ |
-| **Group Hover**        | `.group:hover .group-hover:text-blue` | `group-hover:text-blue`   | `{ group: { hover: { color: 'blue' } } }`   | **Sugar**: Nested `group` key acts as modifier scope.         |
-| **Peer Focus**         | `.peer:focus ~ .peer-focus:text-blue` | `peer-focus:text-blue`    | `{ peer: { focus: { color: 'blue' } } }`    | **Sugar**: Nested `peer` key.                                 |
-| **Data Attribute**     | `&[data-active] (etc)`                | `data-[active]:text-blue` | `{ data: { active: { color: 'blue' } } }`   | **Sugar**: Maps to `data-[key]`.                              |
-| **ARIA Attribute**     | `&[aria-expanded="true"] (etc)`       | `aria-expanded:text-blue` | `{ aria: { expanded: { color: 'blue' } } }` | **Sugar**: Maps to `aria-[key]`.                              |
-| **Arbitrary Variant**  | `& > span`                            | `[&>span]:text-blue`      | `{ '[& > span]': { color: 'blue' } }`       |                                                               |
-| **Important Modifier** | `color: red !important`               | `text-red-500!`           | `{ color: 'red-500!' }`                     | **New**: Trailing `!` in value maps to trailing `!` in class. |
+| Concept                         | CSS Rule                              | Tailwind v4 Class         | `sz` Prop (Object Syntax)                   | Note                                                                                                                                               |
+| :------------------------------ | :------------------------------------ | :------------------------ | :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Group Hover**                 | `.group:hover .group-hover:text-blue` | `group-hover:text-blue`   | `{ group: { hover: { color: 'blue' } } }`   | **Sugar**: Nested `group` key acts as modifier scope.                                                                                              |
+| **Peer Focus**                  | `.peer:focus ~ .peer-focus:text-blue` | `peer-focus:text-blue`    | `{ peer: { focus: { color: 'blue' } } }`    | **Sugar**: Nested `peer` key.                                                                                                                      |
+| **Data Attribute**              | `&[data-active] (etc)`                | `data-[active]:text-blue` | `{ data: { active: { color: 'blue' } } }`   | **Sugar**: Maps to `data-[key]`.                                                                                                                   |
+| **ARIA Attribute**              | `&[aria-expanded="true"] (etc)`       | `aria-expanded:text-blue` | `{ aria: { expanded: { color: 'blue' } } }` | **Sugar**: Maps to `aria-[key]`.                                                                                                                   |
+| **Arbitrary Variant**           | `& > span`                            | `[&>span]:text-blue`      | `{ '[& > span]': { color: 'blue' } }`       |                                                                                                                                                    |
+| **Important Modifier**          | `color: red !important`               | `text-red-500!`           | `{ color: 'red-500!' }`                     | **New**: Trailing `!` in value maps to trailing `!` in class.                                                                                      |
+| **Important + arbitrary value** | `font-size: 14px !important`          | `text-[14px]!`            | `{ text: '14px!' }`                         | The `!` sits **outside** the brackets. A value that needs brackets is decided without the `!` attached, so `14px` is still recognised as a length. |
 
 ## Style Conflict Management
 
@@ -3407,7 +3408,7 @@ Controlling the font weight.
 | Concept          | CSS Rule                | Tailwind v4 Class                                                                                                                        | `sz` Prop (Object Syntax)                             | Note                                                               |
 | :--------------- | :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------- | :----------------------------------------------------------------- |
 | **Keywords**     | `font-weight: 100-900`  | `font-thin`, `font-extralight`, `font-light`, `font-normal`, `font-medium`, `font-semibold`, `font-bold`, `font-extrabold`, `font-black` | `{ weight: 'thin' }`, `{ weight: 'extralight' }` etc. |                                                                    |
-| **Number**       | `font-weight: 100-900`  | `font-100`, `font-200`, `font-300`, `font-400`, `font-500`, `font-600`, `font-700`, `font-800`, `font-900`                               | `{ weight: 100 }`, `{ weight: 200 }` etc.             | v4 shorthand.                                                      |
+| **Number**       | `font-weight: 100-900`  | `font-[100]`, `font-[200]`, `font-[300]`, `font-[400]`, `font-[500]`, `font-[600]`, `font-[700]`, `font-[800]`, `font-[900]`             | `{ weight: 100 }`, `{ weight: 200 }` etc.             | v4 spells weights through `--font-weight-*`, so a NUMBER brackets. |
 | **Alias**        | (Sugar)                 | `font-bold`                                                                                                                              | `{ weight: 'bold' }`                                  | Sugar for `weight`.                                                |
 | **Arbitrary**    | `font-weight: 550`      | `font-[550]`                                                                                                                             | `{ weight: 550 }`                                     |                                                                    |
 | **CSS Variable** | `font-weight: var(--w)` | `font-(weight:--w)`                                                                                                                      | `{ weight: '--w' }`                                   | **Sugar**: Auto-detects `--`. Type hint disambiguates from family. |
@@ -3655,10 +3656,12 @@ sz={{ scale: shrunk ? 75 : 100 }}            // inline prop ternary — both lit
 - Use `sz={var}` when no override needed (simpler)
 - Use `sz={{ ...var, key: val }}` only when overriding/adding
 - Variables in array elements, ternary branches, and chained initializers all resolve at build time
+- `build.importedStaticSz` (default TRUE) compiles a static sz object imported from another module — v1 covers a direct `sz={binding}` from a NAMED import of an `export const` object literal, written relative or through a project alias (read from the bundler's `resolve.alias` and tsconfig `compilerOptions.paths`); barrels, package specifiers, absolute specifiers, namespace/default imports and nested positions keep the runtime fallback and report it; every lane defaults to on so nothing needs wiring, and turning it OFF must be done in all of them — `csszyxTurbopack({}, { importedStaticSz: false })` PLUS `csszyx next prebuild --no-imported-static-sz` PLUS `csszyx next watch --no-imported-static-sz` for dev — because a mismatch fails the production build on the config hash
+- A shared sz object is a build-time value: the compiler reads it where it is DECLARED. Reassigning the binding (`let s = {...}; s = {...}`) is detected and falls back to the runtime; a property write (`s.p = 8`) is NOT detected and the class still describes the declared value. Declare once, never write to it — vary with spread overrides or `szv()`
 - `sz={{ key: cond ? a : b }}` — both literal branches compile to static classes; a runtime branch uses a CSS variable. An opposite `undefined`, `null`, `false`, or `''` branch omits the utility and variable value (`0` remains valid)
 - When runtime `sz` values emit inline CSS variables beside one direct object-literal JSX spread, or one conditional whose branches are object literals, the compiler injects the variables into every spread branch's `style` so both authored and generated values survive. Keep unresolved or multiple spreads' style explicit; csszyx warns when it cannot prove a single-evaluation merge is safe
 - `sz={{ ...(cond ? a : b), static: val }}` — conditional spread hoist: compiler resolves both branches at build time
-- Imported variables / function call results fall back to `_sz()` runtime — dev mode emits a build-time compiler warning explaining the fallback reason and suggesting `szv()` or `dynamic()`
+- Imported variables / function call results fall back to `_sz()` runtime — a build-time compiler warning explains the fallback reason and suggests `szv()` or `dynamic()`. An expression rooted in an IMPORT collects no classes at all, so that warning is kept in production builds and survives `quiet: 'nudges'`; every other unresolved shape — including a forwarded `sz` prop, whose classes the caller contributes — stays dev-only advice
 
 Full guide: `/docs/reusing-styles`
 
@@ -3721,13 +3724,10 @@ unset"; same-file `const` references and `const` object spreads are followed.
 For styles from JSON / API / CMS / form renderer schemas:
 
 ```tsx
-import { dynamic, preloadManifest } from "@csszyx/dynamic";
+import { dynamic } from "@csszyx/dynamic";
 // or: import { dynamic } from 'csszyx/dynamic';
 
-// Optional: preload at app startup for zero-latency first inject
-await preloadManifest("/csszyx-manifest.json");
-
-// Apply runtime sz object — CSS injected only for missing classes
+// Apply runtime sz object — CSS is injected for classes not already built
 const cls = dynamic({
   p: 4,
   bg: "white",
@@ -3736,6 +3736,25 @@ const cls = dynamic({
 });
 ```
 
+**The manifest is opt-in.** `csszyx-manifest.json` lets `dynamic()` skip injecting
+rules the built CSS already has, but it carries the WHOLE class census to answer
+questions about the few classes `dynamic()` renders — measured on a 668-class
+census it costs ~2 kB gz to spare a few hundred bytes of injection, and only wins
+once most of the app is styled at runtime. `build.emitManifest` defaults to
+`false`; a missing manifest is not an error, `dynamic()` just injects its own
+rules and the styles are identical.
+
+If you enable it, preload it — `dynamic()` is synchronous and the fetch is not,
+so an unawaited manifest arrives after the first paint has already injected
+everything and the build pays both costs:
+
+```tsx
+import { dynamicReport, preloadManifest } from "@csszyx/dynamic";
+
+await preloadManifest(); // before the first render
+console.log(dynamicReport().summary); // development: did it pay off here?
+```
+
 **Build-time extraction (Layer-1 prescan):** When `dynamic()` receives a static literal or
 module-level const, the compiler extracts classes at build time → Tailwind generates CSS
 ahead of time → no runtime injection needed. Works in Astro SSR without `client:*`.
@@ -4071,8 +4090,19 @@ ignored unless a path points into them:
 A non-`/packages/` lib INSIDE the build root needs no config (compiled + scanned
 automatically); `compileSources` is for `/packages/` or sources OUTSIDE the root.
 
-A `/packages/` file with `sz` that is not opted in is skipped silently (no CSS);
-csszyx warns at build end and lists those files.
+The option used to be `compilePackages`, which took package NAMES. An old config
+still passing that name is never read, so every effect below silently does not
+happen. csszyx now warns on any plugin option it does not recognize, naming the
+replacement.
+
+A `/packages/` file using csszyx that is not opted in is skipped (no CSS); csszyx
+warns at build end and lists those files.
+
+Opting in is also what makes the cross-module `szv` precompile work inside the
+package: the prescan is what records a module's exported factories, so a skipped
+module keeps them out of the registry and every importer — its own siblings
+included — falls back to the runtime path. That case warns in production builds
+too; a skip affecting only one file's own classes stays development-only.
 
 ## Theme Auto-Scan (Custom Tokens → TypeScript Types)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@csszyx/mcp-server",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "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": "^4.4.3",
-    "@csszyx/cli": "0.12.0",
-    "@csszyx/compiler": "0.12.0",
-    "@csszyx/unplugin": "0.12.0"
+    "@csszyx/compiler": "0.13.0",
+    "@csszyx/cli": "0.13.0",
+    "@csszyx/unplugin": "0.13.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",