@csszyx/mcp-server 0.10.0 → 0.10.2

package/llms-full.txt

@@ -248,11 +248,15 @@ compile error, so typos and legacy CSS-property names are caught by `tsc` (run
 `tsc --noEmit` in CI to enforce it).
 
 ```tsx
-{ bgColor: 'red-500' }   // ❌ tsc error — unknown key; canonical is { bg: 'red-500' }
+{
+  bgColor: "red-500";
+} // ❌ tsc error — unknown key; canonical is { bg: 'red-500' }
 
 // Forcing a brand-new Tailwind utility csszyx has no key for yet — opt out explicitly:
 // @ts-expect-error - forward-compat utility not yet in csszyx
-{ someNewUtility: 'x' }  // ✅ allowed; the runtime still emits the class
+{
+  someNewUtility: "x";
+} // ✅ allowed; the runtime still emits the class
 ```
 
 Arbitrary variants are allowed by pattern: `{ '@container': {…} }`, `{ 'min-[320px]': {…} }`,
@@ -260,7 +264,9 @@ Arbitrary variants are allowed by pattern: `{ '@container': {…} }`, `{ 'min-[3
 Tailwind `@theme` and csszyx auto-generates the type:
 
 ```css
-@theme { --breakpoint-tablet: 40rem; }   /* → { tablet: { p: 6 } } now type-checks */
+@theme {
+  --breakpoint-tablet: 40rem;
+} /* → { tablet: { p: 6 } } now type-checks */
 ```
 
 ## Full Snippets Reference
@@ -3511,37 +3517,112 @@ import { __szColorVar } from "csszyx/lite";
 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
-import { splitBox, classify, has, pick, omit, stripSzProps } from '@csszyx/runtime';
+import {
+  splitBox,
+  splitBoxSz,
+  classify,
+  has,
+  pick,
+  omit,
+  stripSzProps,
+} from "@csszyx/runtime";
 
 // Partition: outer = border-outward (margin/position/border/sizing/bg/shadow/transform/visibility),
 //            inner = border-inward (padding/overflow/display/layout/gap/text/paint-inside/interactivity)
-const { outer, inner } = splitBox('m-4 px-2 md:flex');
+const { outer, inner } = splitBox("m-4 px-2 md:flex");
 // outer: "m-4"   inner: "px-2 md:flex"
 
 // Override any default per call (BoxSelector = box-role | category | class-prefix | { category: value })
-splitBox('overflow-hidden p-4', { outer: ['overflow'] });
+splitBox("overflow-hidden p-4", { outer: ["overflow"] });
 // outer: "overflow-hidden"   inner: "p-4"
 
 // Toolkit: csszyx owns the truth (box-role/category), your project owns the rule
-classify('inset-ring-2');                 // { role: 'inner', 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"
+classify("inset-ring-2"); // { role: 'inner', 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' : '';
+const dep = has(outer, { overflow: "hidden" }) ? "overflow-y-auto h-full" : "";
+
+// 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
 
 // 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)
-function Box({ sz, ...rest }) { return <div {...stripSzProps(rest)} />; }
+function Box({ sz, ...rest }) {
+  return <div {...stripSzProps(rest)} />;
+}
 ```
 
+## Build-time vs runtime (when does sz become CSS)
+
+csszyx has two worlds; pick by "is the value set finite and known at build time?".
+
+- **Static (build-time, default):** literals + `szv` variants. The compiler lowers
+  sz → Tailwind classes and safelists them; Tailwind generates CSS at build. Zero
+  runtime, SSR-safe.
+- **Runtime (`dynamic()`):** unbounded values (CMS color, user `#hex`). CSS is
+  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).
+
+Helper build-time/runtime:
+
+- `sz={{…}}` literal → build-time (extracted + safelisted).
+- `szv` → build-time: the compiler extracts the `szv({…})` config from its
+  DECLARATION, regardless of how the factory output is used (direct sz=, through
+  splitBoxSz, or unused). Indirection does NOT break safelisting.
+- `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.
+
+Safelist requires a statically analyzable position (a literal sz, or a szv config
+literal). File-discovery gap: the prescan only scans files containing `sz=`/`sz:`,
+so a standalone szv-config file (no JSX) is skipped → co-locate szv in the
+component file that has a `sz=` usage. For a sibling workspace package, opt it in
+with `compilePackages: ['name']`.
+
+Tree-shaking is content-presence (same as Tailwind), not import-graph. Co-locating
+szv makes the component the shaking unit.
+
+Specificity: a `dynamic()`-injected rule is UNLAYERED → beats static sz / Tailwind
+`@layer utilities` at equal specificity (CSS Cascade Level 5). They don't collide
+by design (dynamic injects only not-yet-built classes); prefer all-static in a
+component.
+
+CRITICAL — sz on an HTML tag vs a component: the compiler rewrites `sz=` to
+`className=` on ANY element. On an html tag (`<div sz>`) the class lands on the DOM
+and applies. On a COMPONENT (`<Box sz={{p:4}}>` → `<Box className="p-4">`) the
+class becomes a `className` PROP — the component does NOT receive an sz object and
+MUST forward `className` onto a real html tag, else the style is lost. Putting sz
+on a component is NOT enough; every style must reach an html tag.
+
+Design-system rules: (1) a component is styled from the app via the `className` it
+receives (the compiled app sz); forward it to a DOM tag
+(`function Box({className}) { return <div className={className}/> }`). NEVER
+`dynamic(sz)` inside a component (makes every consumer runtime). (2) a multi-part
+component receives ONE className and routes it with `splitBox(className)` (STRING),
+combining with its own base classes on plain className (don't mix sz= and
+className= on one element). `splitBoxSz` (object) is only for routing an sz object
+the component builds internally (e.g. from szv) onto nested sz= props.
+
 ## Security — untrusted sz
 
 csszyx is safe-by-default for AUTHORED sz (compiled to class strings at build time). When sz comes from UNTRUSTED input (JSON-driven UI, CMS, user data), it controls keys and values that reach the runtime CSS pipeline — purify it.
 
 ```tsx
-import { dynamic, purifySz } from '@csszyx/dynamic';
+import { dynamic, purifySz } from "@csszyx/dynamic";
 // stripSzProps is exported from '@csszyx/runtime'
 
 // Untrusted sz → dynamic() runtime CSS: purify first (allowlist + value sanitize + proto guard)

package/package.json

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