@csszyx/mcp-server 0.15.3 → 0.17.0

package/llms-full.txt

@@ -2691,6 +2691,21 @@ CSS custom properties (`--*`) are passed through unchanged.
 - Spaces in values are normalised to underscores: `repeat(3, 1fr)` → `repeat(3,_1fr)`.
 - Works inside `dynamic()` at runtime — the same compiler logic handles the `css` key.
 
+### Custom property as a key
+
+A CSS custom property may also be written as a key on the `sz` object itself, which is the shorter form when a token sits beside the utilities that read it. It produces the same class as the `css: {}` spelling and nests under a variant like any other key.
+
+| Concept             | Example `sz` Prop                     | Output Class                | Note                              |
+| :------------------ | :------------------------------------ | :-------------------------- | :-------------------------------- |
+| **Key spelling**    | `{ '--my-color': 'red' }`             | `[--my-color:red]`          | same class as `css: {}`           |
+| **Inside variant**  | `{ dark: { '--my-color': 'white' } }` | `dark:[--my-color:white]`   | works in all variants             |
+| **Numeric value**   | `{ '--my-alpha': 0.18 }`              | `[--my-alpha:0.18]`         | numbers coerced to string         |
+| **Spaced value**    | `{ '--my-edge': '1px solid red' }`    | `[--my-edge:1px_solid_red]` | spaces → underscores              |
+| **Bracketed value** | `{ '--my-cols': '[a] 1fr [b]' }`      | `[--my-cols:[a]_1fr_[b]]`   | brackets kept as written          |
+| **Case**            | `{ '--MyToken': 1 }`                  | `[--MyToken:1]`             | case kept; `--` is case-sensitive |
+
+The value is a declaration value, so it is a string or a number; `false` switches the property off like any key. An object body has no declaration to lower and the type rejects it; nest a variant instead. A runtime value is hoisted like any other and read back as `[--my-color:var(--_sz---my-color)]`.
+
 
 # Sizing
 
@@ -3890,6 +3905,27 @@ import { __szColorVar } from "csszyx/lite";
 
 ## Nested Element Routing — splitBox + class toolkit
 
+For className-only consumers, import `classify`, `has`, `pick`, `omit` and
+`splitBox` from `@csszyx/runtime/split`. The entry excludes sz-object adapters;
+ESM can tree-shake the main entry too, while CommonJS benefits from the narrower
+surface. The compiler dependency remains.
+
+The supported vocabulary is atomic utilities. A multi-property custom
+`@utility card` is not classified: `pick` excludes it, `omit` retains it, and
+`splitBox` leaves it on the fallback node with a development warning unless
+explicitly placed. Use `splitBox('card p-4', { inner: ['card'] })` to place the
+whole class; no CSS declarations are split. Literal placement matches a whole
+base name, so `card` does not match `card-lg`. Use authored names when mangling.
+`{ outer: ['hidden'] }` matches every variant of `hidden`; naming `md:hidden`
+in a class placement list matches nothing and warns. Query helpers still
+require recognised selectors.
+
+`scope` is the category for `group` and `peer`, including `group/item`. Both
+route outer: `group` supplies an ancestor and `peer` keeps its sibling position.
+The expanded vocabulary also recognises `placeholder-*` as inner and
+`start-*`/`end-*` as outer. These classes previously used the fallback, so
+review old routing assumptions and category-query expectations when upgrading.
+
 When a caller passes one flat `className` to a component that renders nested elements, `splitBox` partitions it at the CSS box-model border line so each element gets the classes that act on it. Pure string functions, framework-agnostic. The class-token → box-role map is generated from the compiler's property tables (never drifts).
 
 ```tsx
@@ -3903,31 +3939,47 @@ import {
   stripSzProps,
 } from "@csszyx/runtime";
 
-// Partition: outer = border-outward (margin/position/border/ring/sizing/bg/shadow/transform/visibility),
-//            inner = border-inward (padding/overflow/display/flex/grid/gap/text/interaction)
+// Partition: outer = border-outward (margin/position/border/ring/sizing/bg/shadow/transform/
+//            visibility/overflow-hidden+clip/cursor/select/pointer-events/scroll-m/snap-start/align),
+//            inner = border-inward (padding/overflow-auto+scroll/display/flex/grid/gap/text/divide/
+//            perspective/transform-3d/resize/appearance)
+// Both: transition/duration/ease/delay are declared on BOTH nodes (a transition is inert until a
+//       property changes, and the state that changes it can sit on either side).
 const { outer, inner } = splitBox("m-4 px-2 md:flex");
 // outer: "m-4"   inner: "px-2 md:flex"
 
+// overflow routes by VALUE: hidden/clip clip the frame, auto/scroll scroll the content
+splitBox("overflow-hidden overflow-y-auto p-4");
+// outer: "overflow-hidden"   inner: "overflow-y-auto p-4"
+
 // Override any default per call (BoxSelector = box-role | category | class-prefix | { category: value })
-splitBox("overflow-hidden p-4", { outer: ["overflow"] });
-// outer: "overflow-hidden"   inner: "p-4"
+splitBox("overflow-hidden p-4", { inner: ["overflow"] });
+// outer: ""   inner: "overflow-hidden p-4"
 
 // Toolkit: csszyx owns the truth (box-role/category), your project owns the rule
-classify("inset-ring-2"); // { role: 'inner', category: 'ring' }
+classify("inset-ring-2"); // { role: 'outer', category: 'ring' }
 has("p-2 overflow-y-auto", "overflow"); // true
 pick("m-4 text-sm", "text"); // "text-sm"
 omit("p-2 overflow-y-auto flex", "overflow"); // "p-2 flex"
 
-// A scroller scrolls only when the outer frame clips (project-owned dependency rule)
-const dep = has(outer, { overflow: "hidden" }) ? "overflow-y-auto h-full" : "";
+// A scroll frame: the clip and the height land outer on their own; the plumbing that lets a
+// child inherit the frame's height is the component's own (min-h-0 defeats flex's min-height:auto)
+// frame: `${outer} flex flex-col min-h-0 overflow-hidden`
+// content: `${inner} flex-1 min-h-0 overflow-y-auto`
 
 // sz-OBJECT routing: splitBoxSz partitions an sz OBJECT (not a className) into
 // { outer, inner } sz objects — keeps a szv-based component sz-native and routes
 // each key to the same side its class would (splitBoxSz(x) ≡ splitBox(compile(x))).
 splitBoxSz({ m: 4, px: 2 }); // { outer: { m: 4 }, inner: { px: 2 } }
 splitBoxSz({ gap: 2, hover: { px: 1 }, md: { m: 4 } }); // variants route by inner prop; split when they disagree
-splitBoxSz({ grow: 2, self: "center" }, { outer: ["grow", "self"] }); // force flex-item utils to the frame
-// classifySzKey(key) / hasSz / pickSz / omitSz — the sz-object toolkit twins
+splitBoxSz({ grow: 2, self: "center" }, { inner: ["grow", "self"] }); // item utils (grow/order/self/col-span) are OUTER by default; this forces them back to the content
+// Placement lists can pin a whole literal variant key, preserving its contents.
+splitBoxSz({ hover: { p: 2, m: 4 } }, { outer: ["hover"] });
+// { outer: { hover: { p: 2, m: 4 } }, inner: {} }
+// Literal keys such as "[&:hover]" work too; inner wins if both lists name it.
+splitBoxSz({ overflow: "hidden", p: 4 }); // { outer: { overflow: 'hidden' }, inner: { p: 4 } }
+// classifySzKey(key, value?) / hasSz / pickSz / omitSz — the sz-object toolkit twins
+// (pass the value for a key whose side depends on it: classifySzKey('overflow', 'hidden') → outer)
 
 // stripSzProps: drop sz before forwarding ...rest to the DOM (guards uncompiled files
 // whose raw sz would leak as sz="[object Object]"; dev-warns once on a raw-object sz)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@csszyx/mcp-server",
-  "version": "0.15.3",
+  "version": "0.17.0",
   "description": "Model Context Protocol (MCP) server for csszyx — enables AI agents to understand and generate sz props",
   "license": "MIT",
   "type": "module",
@@ -28,9 +28,9 @@
     "node": "^22.18.0 || >=24.11.0"
   },
   "dependencies": {
-    "@csszyx/cli": "0.15.3",
-    "@csszyx/compiler": "0.15.3",
-    "@csszyx/unplugin": "0.15.3",
+    "@csszyx/cli": "0.17.0",
+    "@csszyx/compiler": "0.17.0",
+    "@csszyx/unplugin": "0.17.0",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^4.4.3"
   },