@csszyx/mcp-server 0.11.11 → 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

@@ -263,7 +263,8 @@ compile error, so typos and legacy CSS-property names are caught by `tsc` (run
 ```
 
 Arbitrary variants are allowed by pattern: `{ '@container': {…} }`, `{ 'min-[320px]': {…} }`,
-`{ '[&>span]': {…} }`. **Custom breakpoints are typed from your CSS** — define one once in
+`{ '[&>span]': {…} }`. A STRING value under any variant key is a ready-made utility the
+variant prefixes with `:` — `{ 'data-[open]': 'sr-only' }` → `data-[open]:sr-only`. **Custom breakpoints are typed from your CSS** — define one once in
 Tailwind `@theme` and csszyx auto-generates the type:
 
 ```css
@@ -366,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
 
@@ -515,6 +517,34 @@ Data and state attributes.
 | **Open**            | `open:bg-white`         | `{ open: { bg: 'white' } }`             |      |
 | **Inert**           | `inert:opacity-50`      | `{ inert: { opacity: 50 } }`            |      |
 
+## Variant String Shorthand
+
+A **string value under a variant key** is a ready-made Tailwind utility to
+prefix — the variant chains onto it with `:`. Use it when the utility has no
+sz key spelling (e.g. `sr-only`) or when you already have the exact class.
+Works for every variant form, not just the simple names.
+
+| Concept                    | Tailwind v4 Class                      | `sz` Prop (Object Syntax)                       | Note                                             |
+| :------------------------- | :------------------------------------- | :---------------------------------------------- | :----------------------------------------------- |
+| **Known variant**          | `hover:translate-x-full`               | `{ hover: 'translate-x-full' }`                 |                                                  |
+| **Arbitrary data variant** | `data-[ending-style]:translate-x-full` | `{ 'data-[ending-style]': 'translate-x-full' }` |                                                  |
+| **Bare data variant**      | `data-open:sr-only`                    | `{ 'data-open': 'sr-only' }`                    | Attribute presence (Tailwind v4).                |
+| **Bare ARIA state**        | `aria-checked:opacity-50`              | `{ 'aria-checked': 'opacity-50' }`              | Built-in ARIA set only; others use `[...]`.      |
+| **Scope compound**         | `group-hover:translate-x-full`         | `{ 'group-hover': 'translate-x-full' }`         | Also `peer-*`, `not-*` with a known state.       |
+| **Arbitrary selector**     | `[&>li]:translate-x-full`              | `{ '[&>li]': 'translate-x-full' }`              |                                                  |
+| **Arbitrary breakpoint**   | `min-[900px]:flex`                     | `{ 'min-[900px]': 'flex' }`                     | Also `max-[...]`, `supports-[...]`, `has-[...]`. |
+
+The string is emitted verbatim after the variant — csszyx does not validate it
+against Tailwind's utility set, so prefer sz keys where one exists. A key that
+is not a variant keeps its property meaning: `{ 'not-italic': true }` is still
+the font-style utility.
+
+Negative utility keywords under a variant place the minus on the utility:
+`{ hover: { translateX: '-full' } }` → `hover:-translate-x-full`. Arbitrary
+negative values keep the sign inside the bracket:
+`{ 'data-[starting-style]': { translateX: '-100%' } }` →
+`data-[starting-style]:translate-x-[-100%]`.
+
 ## Helper Variants (Child/Descendants)
 
 Mapping for common descendant patterns.
@@ -1145,7 +1175,7 @@ Controlling the box shadow of an element.
 | **Inset Ring**         | `box-shadow: inset (etc)`                   | `inset-ring`, `inset-ring-1`                                                                                      | `{ insetRing: 1 }`                                                                                                                           |                                                                                |
 | **None**               | `box-shadow: 0 0 #0000`                     | `shadow-none`                                                                                                     | `{ shadow: 'none' }`                                                                                                                         |                                                                                |
 | **Inset None**         | `box-shadow: inset 0 0 #0000`               | `inset-shadow-none`                                                                                               | `{ insetShadow: 'none' }`                                                                                                                    |                                                                                |
-| **Ring None**          | `box-shadow: 0 0 #0000`                     | `ring-none`                                                                                                       | `{ ring: 'none' }`                                                                                                                           |                                                                                |
+| **Ring None**          | `box-shadow: 0 0 #0000`                     | `ring-0`                                                                                                          | `{ ring: 'none' }`                                                                                                                           | Tailwind spells the zero ring `ring-0`; `ring-none` styles nothing.            |
 | **Color**              | `box-shadow: 0 1px 2px 0 rgb(0 0 0 / 0.05)` | `shadow-blue-500`, `inset-shadow-blue-500`, `ring-blue-500`                                                       | `{ shadowColor: 'blue-500' }`                                                                                                                |                                                                                |
 | **Color + Opacity**    | `--tw-shadow-color: (value) / 50%`          | `shadow-blue-500/50`                                                                                              | `{ shadowColor: { color: 'blue-500', op: 50 } }`                                                                                             |                                                                                |
 | **Size + Opacity**     | `box-shadow: (size) / 12.5%`                | `shadow-sm/12.5`, `shadow-2xl/50`                                                                                 | `{ shadow: 'sm/12.5' }`, `{ shadow: '2xl/50' }`                                                                                              | **TW 4.3.3**: fractional opacity on named sizes.                               |
@@ -1222,35 +1252,29 @@ Controlling the masking of an element with images, gradients, and CSS properties
 
 > **Source:** [Tailwind CSS v4.1 Documentation](https://tailwindcss.com/docs/mask-image)
 
+**Migration (breaking):** the flat stop keys were removed — `maskFrom`/`maskTo`
+moved into their layer (`{ maskLinear: { from } }` etc.), `maskShape` moved to
+`{ maskRadial: { shape } }`, `maskVia` was removed with no equivalent (Tailwind
+has no via stop for masks), and gradient layer values on `mask`
+(`{ mask: 'linear-45' }`) moved to the layer keys. `mask` carries only a direct
+mask-image: `none`, `url(…)`, a CSS variable, or an arbitrary value.
+
 ### mask-image: Gradient Masks
 
-| Concept        | CSS Rule                                      | Tailwind v4 Class | `sz` Prop (Object Syntax) | Note                       |
-| :------------- | :-------------------------------------------- | :---------------- | :------------------------ | :------------------------- |
-| **None**       | `mask-image: none`                            | `mask-none`       | `{ mask: 'none' }`        |                            |
-| **Linear**     | `mask-image: linear-gradient(45deg, ...)`     | `mask-linear-45`  | `{ mask: 'linear-45' }`   | Angle in degrees.          |
-| **Linear Neg** | `mask-image: linear-gradient(-45deg, ...)`    | `-mask-linear-45` | `{ mask: '-linear-45' }`  | Negative angle prefix `-`. |
-| **Radial**     | `mask-image: radial-gradient(...)`            | `mask-radial`     | `{ mask: 'radial' }`      |                            |
-| **Conic**      | `mask-image: conic-gradient(from 90deg, ...)` | `mask-conic-90`   | `{ mask: 'conic-90' }`    |                            |
-
-### mask-image: Direction Keywords
-
-| Concept             | CSS Rule                                            | Tailwind v4 Class   | `sz` Prop (Object Syntax)  | Note |
-| :------------------ | :-------------------------------------------------- | :------------------ | :------------------------- | :--- |
-| **To Top**          | `mask-image: linear-gradient(to top, ...)`          | `mask-linear-to-t`  | `{ mask: 'linear-to-t' }`  |      |
-| **To Top Right**    | `mask-image: linear-gradient(to top right, ...)`    | `mask-linear-to-tr` | `{ mask: 'linear-to-tr' }` |      |
-| **To Right**        | `mask-image: linear-gradient(to right, ...)`        | `mask-linear-to-r`  | `{ mask: 'linear-to-r' }`  |      |
-| **To Bottom Right** | `mask-image: linear-gradient(to bottom right, ...)` | `mask-linear-to-br` | `{ mask: 'linear-to-br' }` |      |
-| **To Bottom**       | `mask-image: linear-gradient(to bottom, ...)`       | `mask-linear-to-b`  | `{ mask: 'linear-to-b' }`  |      |
-| **To Bottom Left**  | `mask-image: linear-gradient(to bottom left, ...)`  | `mask-linear-to-bl` | `{ mask: 'linear-to-bl' }` |      |
-| **To Left**         | `mask-image: linear-gradient(to left, ...)`         | `mask-linear-to-l`  | `{ mask: 'linear-to-l' }`  |      |
-| **To Top Left**     | `mask-image: linear-gradient(to top left, ...)`     | `mask-linear-to-tl` | `{ mask: 'linear-to-tl' }` |      |
+| Concept        | CSS Rule                                      | Tailwind v4 Class       | `sz` Prop (Object Syntax)          | Note                       |
+| :------------- | :-------------------------------------------- | :---------------------- | :--------------------------------- | :------------------------- |
+| **None**       | `mask-image: none`                            | `mask-none`             | `{ mask: 'none' }`                 |                            |
+| **Linear**     | `mask-image: linear-gradient(45deg, ...)`     | `mask-linear-45`        | `{ maskLinear: { angle: 45 } }`    | Angle in degrees.          |
+| **Linear Neg** | `mask-image: linear-gradient(-45deg, ...)`    | `-mask-linear-45`       | `{ maskLinear: { angle: -45 } }`   | Negative angle prefix `-`. |
+| **Radial**     | `mask-image: radial-gradient(...)`            | `mask-radial-at-center` | `{ maskRadial: { at: 'center' } }` |                            |
+| **Conic**      | `mask-image: conic-gradient(from 90deg, ...)` | `mask-conic-90`         | `{ maskConic: { angle: 90 } }`     |                            |
 
 ### mask-image: Shape Modifiers (Radial)
 
-| Concept     | CSS Rule                          | Tailwind v4 Class | `sz` Prop (Object Syntax)  | Note                  |
-| :---------- | :-------------------------------- | :---------------- | :------------------------- | :-------------------- |
-| **Circle**  | `--tw-mask-radial-shape: circle`  | `mask-circle`     | `{ maskShape: 'circle' }`  | For radial gradients. |
-| **Ellipse** | `--tw-mask-radial-shape: ellipse` | `mask-ellipse`    | `{ maskShape: 'ellipse' }` | Default shape.        |
+| Concept     | CSS Rule                          | Tailwind v4 Class | `sz` Prop (Object Syntax)              | Note                  |
+| :---------- | :-------------------------------- | :---------------- | :------------------------------------- | :-------------------- |
+| **Circle**  | `--tw-mask-radial-shape: circle`  | `mask-circle`     | `{ maskRadial: { shape: 'circle' } }`  | For radial gradients. |
+| **Ellipse** | `--tw-mask-radial-shape: ellipse` | `mask-ellipse`    | `{ maskRadial: { shape: 'ellipse' } }` | Default shape.        |
 
 ### mask-image: Arbitrary Values
 
@@ -1443,12 +1467,12 @@ Controls how multiple masks are combined.
 
 Control the color stops used in mask gradient functions.
 
-| Concept      | CSS Rule              | Tailwind v4 Class   | `sz` Prop (Object Syntax) | Note |
-| :----------- | :-------------------- | :------------------ | :------------------------ | :--- |
-| **From**     | mask gradient start   | `mask-from-<color>` | `{ maskFrom: '<color>' }` |      |
-| **Via**      | mask gradient middle  | `mask-via-<color>`  | `{ maskVia: '<color>' }`  |      |
-| **To**       | mask gradient end     | `mask-to-<color>`   | `{ maskTo: '<color>' }`   |      |
-| **Variable** | `mask-from: var(--c)` | `mask-from-(--c)`   | `{ maskFrom: '--c' }`     |      |
+| Concept        | CSS Rule                         | Tailwind v4 Class                               | `sz` Prop (Object Syntax)                                       | Note                                   |
+| :------------- | :------------------------------- | :---------------------------------------------- | :-------------------------------------------------------------- | :------------------------------------- |
+| **Layer stop** | `--tw-mask-linear-from-position` | `mask-linear-from-20%`                          | `{ maskLinear: { from: '20%' } }`                               | Also `maskRadial` / `maskConic`.       |
+| **Side stop**  | `--tw-mask-bottom-from-position` | `mask-b-from-20%`                               | `{ maskLinear: { b: { from: '20%' } } }`                        | Sides: `t r b l x y`.                  |
+| **Colour**     | `--tw-mask-bottom-from-color`    | `mask-b-from-red-500/30`                        | `{ maskLinear: { b: { from: { color: 'red-500', op: 30 } } } }` | Position and colour are separate vars. |
+| **Variable**   | position vs colour               | `mask-b-from-(--c)` / `mask-b-from-(color:--c)` | `{ from: { at: '--c' } }` / `{ from: { color: '--c' } }`        | A bare var reads as a POSITION.        |
 
 
 # Filters
@@ -3384,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. |
@@ -3417,10 +3441,10 @@ Controlling numeric glyphs.
 
 Controlling font-feature-settings. Added in Tailwind v4.2.
 
-| Concept       | CSS Rule                          | Tailwind v4 Class          | `sz` Prop (Object Syntax)      | Note |
-| :------------ | :-------------------------------- | :------------------------- | :----------------------------- | :--- |
-| **Normal**    | `font-feature-settings: normal`   | `font-features-normal`     | `{ fontFeatures: 'normal' }`   |      |
-| **Arbitrary** | `font-feature-settings: "liga" 1` | `font-features-["liga"_1]` | `{ fontFeatures: '"liga" 1' }` |      |
+| Concept       | CSS Rule                          | Tailwind v4 Class          | `sz` Prop (Object Syntax)      | Note                                                                              |
+| :------------ | :-------------------------------- | :------------------------- | :----------------------------- | :-------------------------------------------------------------------------------- |
+| **Normal**    | `font-feature-settings: normal`   | `font-features-[normal]`   | `{ fontFeatures: 'normal' }`   | Tailwind's `font-features-*` is functional-only; the bare keyword styles nothing. |
+| **Arbitrary** | `font-feature-settings: "liga" 1` | `font-features-["liga"_1]` | `{ fontFeatures: '"liga" 1' }` |                                                                                   |
 
 ## Font Style & Smoothing
 
@@ -3632,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`
 
@@ -3698,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",
@@ -3713,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:*`.
@@ -3981,14 +4023,19 @@ no tsconfig change needed.
 
 ## Production Build (Mangling)
 
-In production, class names are mangled for maximum compression:
+Class-name mangling is **opt-in** (`production.mangle` defaults to `false`) and is an
+obfuscation feature, not a size optimization: the runtime mangle map the page must ship
+costs more bytes than the shorter class names save, so enable it only when the original
+utility names should not be readable in the production bundle.
 
 ```js
 // vite.config.ts (production)
 ...csszyx({ production: { mangle: true } })
 ```
 
-Output: `<div class="z y x" />` — the CSS `.z { padding: 1rem }` etc. is injected automatically.
+Output: `<div class="z y x" />` — the CSS `.z { padding: 1rem }` etc. is injected
+automatically. `production.mangleMapDelivery` chooses where the runtime map ships
+(`'both'` default, `'html'`, or `'bundle'`; vite/rollup lanes).
 
 If an `sz`-generated utility also appears as a static string or template quasi in a
 source-level `class` or `className` attribute/property (including a `clsx(...)`
@@ -4002,8 +4049,8 @@ adapter keeps class names readable (and warns when `production.mangle: true` is
 explicit) because normal esbuild write-to-disk builds do not expose mutable final
 assets; source transforms and safelist generation still run.
 
-Set `production: { mangle: false }` to keep readable class names — the supported way to
-inspect the emitted CSS. To check what a single `sz` object
+With mangling left at its default (off), a build keeps readable class names — the
+supported way to inspect the emitted CSS. To check what a single `sz` object
 compiles to without a build, run `csszyx explain "{ p: 4, bg: 'blue-500' }"`.
 
 ### AST budget guard
@@ -4043,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.11.11",
+  "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.11.11",
-    "@csszyx/unplugin": "0.11.11",
-    "@csszyx/compiler": "0.11.11"
+    "@csszyx/compiler": "0.13.0",
+    "@csszyx/cli": "0.13.0",
+    "@csszyx/unplugin": "0.13.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",