@csszyx/runtime 0.9.10 → 0.10.1

package/dist/index.d.cts

@@ -43,53 +43,6 @@ type SzInput = string | SzObject | SzInput[] | null | undefined | false;
  * ```
  */
 declare function _sz(...classes: SzInput[]): string;
-/**
- * Conditionally applies className based on a condition.
- *
- * Supports both pre-compiled strings and SzObjects for dynamic styling.
- * This is the recommended helper for conditional class application.
- *
- * @param {boolean} condition - Whether to apply the truthy value
- * @param {SzInput} truthyValue - ClassName or SzObject when condition is true
- * @param {SzInput} falsyValue - ClassName or SzObject when condition is false
- * @returns {string} The resolved className string
- *
- * @example
- * ```typescript
- * // With strings (pre-compiled)
- * _szIf(isActive, 'bg-green-500', 'bg-gray-500')
- * // Returns: "bg-green-500" if isActive, "bg-gray-500" otherwise
- *
- * // With SzObjects (runtime transform)
- * _szIf(isActive, { bg: 'green-500' }, { bg: 'gray-500' })
- * // Returns: "bg-green-500" if isActive, "bg-gray-500" otherwise
- *
- * // Without fallback
- * _szIf(isActive, { bg: 'green-500' })
- * // Returns: "bg-green-500" if isActive, "" otherwise
- * ```
- */
-declare function _szIf(condition: boolean, truthyValue: SzInput, falsyValue?: SzInput): string;
-/**
- * Applies className based on multiple conditions (switch-like).
- *
- * Returns the className for the first truthy condition, or the default.
- * Supports both strings and SzObjects.
- *
- * @param {Array<[boolean, SzInput]>} conditions - Array of [condition, value] tuples
- * @param {SzInput} defaultValue - Default value if no conditions match
- * @returns {string} The matched className or default
- *
- * @example
- * ```typescript
- * _szSwitch([
- *     [status === 'success', { text: 'green-500' }],
- *     [status === 'error', { text: 'red-500' }],
- *     [status === 'warning', { text: 'yellow-500' }]
- * ], { text: 'gray-500' })
- * ```
- */
-declare function _szSwitch(conditions: Array<[boolean, SzInput]>, defaultValue?: SzInput): string;
 /**
  * Merges className strings, removing duplicates.
  *
@@ -349,19 +302,19 @@ declare function disableCSRRecovery(): void;
  */
 declare function isCSRRecoveryAllowed(): boolean;
 /**
- * Loads the mangle map from the DOM.
+ * Validate a parsed mangle map before it is used to rewrite class names. The map
+ * is read from the DOM (attacker-writable if the served HTML is compromised), so
+ * it must be a plain object of string→string with no prototype-polluting keys.
+ * A malformed map is rejected rather than applied.
  *
- * Searches for the embedded mangle map script tag and parses it.
- *
- * @returns {MangleMap | null} The mangle map or null if not found
+ * @param value - the `JSON.parse`d candidate.
+ * @returns true when `value` is a safe `MangleMap`.
+ */
+declare function isValidMangleMap(value: unknown): value is MangleMap;
+/**
+ * Load and validate the mangle map embedded in the DOM by the SSR pipeline.
  *
- * @example
- * ```typescript
- * const mangleMap = loadMangleMapFromDOM();
- * if (mangleMap) {
- *     console.log('Mangle map loaded');
- * }
- * ```
+ * @returns the validated mangle map, or `null` if absent or invalid.
  */
 declare function loadMangleMapFromDOM(): MangleMap | null;
 /**
@@ -382,20 +335,53 @@ declare function loadMangleMapFromDOM(): MangleMap | null;
  */
 declare function verifyMangleChecksum(expectedChecksum: string): boolean;
 /**
- * Verifies mangle map integrity using Rust core verification.
+ * Recompute a mangle map's checksum the same way the Rust core does
+ * (`compute_checksum_internal`): SHA-256 over the entries sorted by key and
+ * formatted `orig:mangle`, joined by `|`, hex-encoded, first 16 chars (64 bits).
  *
- * Loads the mangle map from DOM and verifies its checksum using the
- * Rust core's `verify_mangle_checksum()` function for cryptographic-grade verification.
+ * Uses the Web Crypto API (`crypto.subtle`), so it works WITHOUT the WASM core —
+ * unlike the WASM-only sync path. Async because `crypto.subtle.digest` is async.
  *
- * @returns {boolean} True if mangle map integrity is verified
+ * @param map - the mangle map to checksum.
+ * @returns the 16-char hex checksum (matches the Rust output byte-for-byte for
+ *          ASCII class names).
+ */
+declare function computeMangleChecksumAsync(map: MangleMap): Promise<string>;
+/**
+ * Verify a mangle map's integrity by RECOMPUTING its checksum (via Web Crypto)
+ * and comparing it to the expected value — real verification that works without
+ * the WASM core. Unlike the sync {@link verifyMangleChecksum} (a plain attribute
+ * compare), this recomputes from the map, so it detects a map that was altered
+ * without updating the checksum.
  *
- * @example
- * ```typescript
- * if (!verifyMangleMapIntegrity()) {
- *     console.error('[csszyx] Mangle map integrity check failed');
- *     abortHydration();
- * }
- * ```
+ * Still tamper-DETECTION, not authentication: the checksum is unsigned, so an
+ * attacker who can rewrite the served HTML can recompute it after editing the
+ * map. Use it to catch corruption / accidental drift, not as a trust boundary.
+ *
+ * @param expectedChecksum - the checksum to match (e.g. from the manifest or the
+ *        `data-sz-checksum` attribute).
+ * @param map - the mangle map; loaded (and schema-validated) from the DOM when omitted.
+ * @returns a promise resolving true when the map is present and its recomputed
+ *          checksum matches.
+ */
+declare function verifyMangleChecksumAsync(expectedChecksum: string, map?: MangleMap): Promise<boolean>;
+/**
+ * Verifies mangle map integrity using the Rust core checksum verifier.
+ *
+ * Loads the mangle map from the DOM, validates its shape, and (when the WASM
+ * core is present) verifies its checksum via `verify_mangle_checksum()`.
+ *
+ * IMPORTANT — this is tamper-DETECTION, not authentication. The checksum is an
+ * unsigned SHA-256 truncation: it catches accidental server/client drift, but an
+ * attacker who can rewrite the served HTML can recompute it after editing the
+ * map. Treat it as an integrity (corruption) check, not a trust boundary.
+ *
+ * When the WASM verifier is absent (the common no-core deployment), the checksum
+ * cannot be recomputed in this sync path, so verification degrades to a
+ * schema-validated load and emits a dev warning rather than failing closed
+ * (failing closed here would break every app not shipping the WASM core).
+ *
+ * @returns {boolean} True if the map is well-formed and (if verifiable) matches.
  */
 declare function verifyMangleMapIntegrity(): boolean;
 /**
@@ -612,6 +598,200 @@ declare function startHydration(): void;
  */
 declare function endHydration(): void;
 
+/** Which side of the CSS box-model border a property acts on. */
+type BoxRole = 'outer' | 'inner';
+
+/**
+ * Route a (csszyx-emitted) className string to nested elements by CSS box-model
+ * role, plus a category-aware toolkit that exposes csszyx's class knowledge as
+ * primitives. Pure string functions — framework-agnostic, cross-platform, no
+ * React, no DOM. The class-token → box-role map is GENERATED from the compiler's
+ * property tables (see `box-role-map.generated.ts`), so it never drifts.
+ *
+ * The problem this solves: a caller passes one flat `className` (e.g. from an sz
+ * prop) to a component, but the component renders nested elements — the margin
+ * belongs on the outer frame while the padding belongs on the inner content. A
+ * slot recipe can't re-route a caller's flat string; only a runtime partition
+ * can. `splitBox` does that partition at the border line (outer = border-outward,
+ * inner = border-inward); the toolkit lets a project express cross-element
+ * dependency rules (e.g. "if the frame clips, make the scroller scroll") without
+ * hardcoding csszyx's class vocabulary.
+ */
+
+/** The classification of a single class token. */
+interface Classification {
+    /** Which side of the border the property acts on. */
+    readonly role: BoxRole;
+    /** Semantic group (margin, padding, border, overflow, text, …). */
+    readonly category: string;
+}
+/**
+ * A way to address a set of classes. One of:
+ * - a box-role: `'outer'` | `'inner'`
+ * - a box-layer alias: `'content'` (= inner) (`'margin'`/`'border'`/`'padding'`
+ *   are also categories, so they work directly)
+ * - a category: `'overflow'`, `'text'`, `'bg'`, …
+ * - a class-prefix: `'px'`, `'bg'`, … (matches `px-2`, `bg-red-500`, …)
+ * - a category+value pair: `{ overflow: 'hidden' }`
+ */
+type BoxSelector = string | Readonly<Record<string, string>>;
+/** Options controlling how `splitBox` partitions a className. */
+interface SplitBoxOptions {
+    /** Force these selectors onto the outer node, overriding the default map. */
+    outer?: BoxSelector[];
+    /** Force these selectors onto the inner node, overriding the default map. */
+    inner?: BoxSelector[];
+    /** Where an unrecognized token goes. Defaults to `'outer'`. */
+    fallback?: BoxRole;
+}
+/** The two class buckets produced by `splitBox`. */
+interface SplitBoxResult {
+    /** Classes for the outer (border-outward) element. */
+    outer: string;
+    /** Classes for the inner (border-inward) element. */
+    inner: string;
+}
+/**
+ * Classify a class token by box-model role + semantic category, or `undefined`
+ * if it is not a csszyx-owned utility. Variant-, important- and negative-aware.
+ *
+ * @param token - A single class token to classify.
+ * @returns The token's role and category, or `undefined` if unowned.
+ */
+declare function classify(token: string): Classification | undefined;
+/**
+ * Partition a className string into `{ outer, inner }` at the CSS box-model
+ * border line. Every token lands in exactly one bucket (no loss, no duplication)
+ * and keeps its variant prefix. Overrides in `options.inner` / `options.outer`
+ * win over the default map; `inner` is checked first when a token matches both.
+ *
+ * @param className - The flat className string to partition.
+ * @param options - Overrides for forcing tokens onto a node and the fallback role.
+ * @returns The `{ outer, inner }` class buckets.
+ * @example splitBox('m-4 px-2 md:flex') // → { outer: 'm-4', inner: 'px-2 md:flex' }
+ */
+declare function splitBox(className: string, options?: SplitBoxOptions): SplitBoxResult;
+/**
+ * Does any token in `classes` match `selector`? Variant- and mangle-robust.
+ *
+ * @param classes - A className string to scan.
+ * @param selector - The selector to test tokens against.
+ * @returns `true` if any token matches the selector.
+ */
+declare function has(classes: string, selector: BoxSelector): boolean;
+/**
+ * Keep only the tokens in `classes` that match `selector`.
+ *
+ * @param classes - A className string to filter.
+ * @param selector - The selector tokens must match to be kept.
+ * @returns The matching tokens joined by spaces.
+ */
+declare function pick(classes: string, selector: BoxSelector): string;
+/**
+ * Drop the tokens in `classes` that match `selector`, keeping the rest.
+ *
+ * @param classes - A className string to filter.
+ * @param selector - The selector tokens must match to be dropped.
+ * @returns The non-matching tokens joined by spaces.
+ */
+declare function omit(classes: string, selector: BoxSelector): string;
+/** Options controlling how `splitBoxSz` partitions an sz object. */
+interface SplitBoxSzOptions {
+    /** Force these selectors onto the outer object, overriding the default map. */
+    outer?: BoxSelector[];
+    /** Force these selectors onto the inner object, overriding the default map. */
+    inner?: BoxSelector[];
+    /** Where an unrecognized key goes. Defaults to `'outer'`. */
+    fallback?: BoxRole;
+}
+/** The two sz-object buckets produced by `splitBoxSz`. */
+interface SplitBoxSzResult {
+    /** sz for the outer (border-outward) element. */
+    outer: SzObject;
+    /** sz for the inner (border-inward) element. */
+    inner: SzObject;
+}
+/**
+ * Classify an sz prop key by box-model role + semantic category, or `undefined`
+ * if it is not a csszyx-owned key. The sz-object analog of `classify` (which
+ * takes an emitted class token) — both read the same generated map, so
+ * `classifySzKey('m')` and `classify('m-4')` agree.
+ *
+ * @param key - An sz prop key (e.g. `'m'`, `'px'`, `'grow'`).
+ * @returns The key's role and category, or `undefined` if unowned.
+ */
+declare function classifySzKey(key: string): Classification | undefined;
+/**
+ * Partition an sz object (or any `SzInput`) into `{ outer, inner }` at the CSS
+ * box-model border line — the sz-object analog of `splitBox`. Each key routes to
+ * the same side its emitted class would (`splitBoxSz(x)` buckets keys to the
+ * roles `splitBox(compile(x))` gives the emitted classes). Arrays are flattened,
+ * `null`/`false` collapse to empty objects, and `options.inner`/`outer`/
+ * `fallback` behave like `SplitBoxOptions` (`inner` wins when a key matches both).
+ *
+ * @param sz - The sz object / input to partition.
+ * @param options - Overrides for forcing keys onto a node and the fallback role.
+ * @returns The `{ outer, inner }` sz-object buckets.
+ * @example splitBoxSz({ m: 4, px: 2 }) // → { outer: { m: 4 }, inner: { px: 2 } }
+ */
+declare function splitBoxSz(sz: SzInput, options?: SplitBoxSzOptions): SplitBoxSzResult;
+/**
+ * Does any key in `sz` match `selector` (after flattening, recursing into
+ * variants)? The sz-object analog of `has`.
+ *
+ * @param sz - The sz input to scan.
+ * @param selector - The selector to test keys against.
+ * @returns `true` if any key matches.
+ */
+declare function hasSz(sz: SzInput, selector: BoxSelector): boolean;
+/**
+ * Keep only the keys in `sz` that match `selector` (recursing into variants).
+ * The sz-object analog of `pick`.
+ *
+ * @param sz - The sz input to filter.
+ * @param selector - The selector keys must match to be kept.
+ * @returns A new sz object with the matching keys.
+ */
+declare function pickSz(sz: SzInput, selector: BoxSelector): SzObject;
+/**
+ * Drop the keys in `sz` that match `selector`, keeping the rest (recursing into
+ * variants). The sz-object analog of `omit`.
+ *
+ * @param sz - The sz input to filter.
+ * @param selector - The selector keys must match to be dropped.
+ * @returns A new sz object with the non-matching keys.
+ */
+declare function omitSz(sz: SzInput, selector: BoxSelector): SzObject;
+
+/**
+ * Drop the `sz` prop before a component spreads `...rest` onto a host element.
+ *
+ * The compiler rewrites `sz` to `className` at build time, so a compiled
+ * component never carries a leftover `sz` prop. But when a file is NOT compiled
+ * — e.g. a workspace package missing from `compilePackages`, or any source the
+ * bundler skipped — a hand-forwarded `sz` survives and React spreads it to the
+ * DOM as `sz="[object Object]"`. `stripSzProps` removes `sz` from the forwarded
+ * props so it never reaches the DOM, and in development warns once when the
+ * leaked `sz` is a raw object, pointing at the real cause (an uncompiled file).
+ *
+ * Pure, framework-agnostic, no React/DOM import.
+ *
+ * @example
+ * function Box({ sz, ...rest }: BoxProps) {
+ *     return <div {...stripSzProps(rest)} />; // rest may still carry sz when uncompiled
+ * }
+ */
+/**
+ * Return `props` without its `sz` key. When `sz` is absent the original object
+ * is returned unchanged (no allocation); otherwise a shallow copy without `sz`
+ * is returned. In development, a raw-object `sz` (the uncompiled-leak signature)
+ * triggers a one-time warning.
+ *
+ * @param props - the props a component is about to forward to a host element.
+ * @returns the same props without `sz`.
+ */
+declare function stripSzProps<T extends Record<string, unknown>>(props: T): Omit<T, 'sz'>;
+
 /**
  * szv() — variant-based sz object factory.
  *
@@ -632,9 +812,7 @@ type VariantSchema = Record<string, Record<string, SzObject>>;
 type VariantSelection<V extends VariantSchema> = {
     [K in keyof V]?: keyof V[K] | null | undefined;
 };
-/**
- *
- */
+/** Configuration for a variant component: base styles, variants, and defaults. */
 interface SzvConfig<V extends VariantSchema> {
     base?: SzObject;
     variants: V;
@@ -655,7 +833,7 @@ interface SzvConfig<V extends VariantSchema> {
  * import { szv } from 'csszyx';
  *
  * const buttonSz = szv({
- *   base: { inlineFlex: true, items: 'center', rounded: 'md', fontWeight: 'medium' },
+ *   base: { display: 'inline-flex', items: 'center', rounded: 'md', weight: 'medium' },
  *   variants: {
  *     variant: {
  *       default: { bg: 'primary', text: 'primary-foreground' },
@@ -769,5 +947,5 @@ declare function isRuntimeInitialized(): boolean;
  */
 declare function resetRuntime(): void;
 
-export { DEFAULT_RUNTIME_CONFIG, VERSION, _sz, _sz2, _sz3, _szIf, _szMerge, _szSwitch, abortHydration, attemptCSRRecovery, clearHydrationErrors, disableCSRRecovery, enableCSRRecovery, endHydration, getAbortedSubtreeCount, getHydrationErrors, getRecoveryMode, getRuntimeConfig, getSSRContext, guardHydration, hasRecoveryToken, initRuntime, isCSRRecoveryAllowed, isHydrating, isHydrationAborted, isRuntimeInitialized, isSSREnvironment, isValidManifest, loadMangleMapFromDOM, loadManifestFromDOM, resetRuntime, startHydration, szv, validateHydrationClass, verifyAllTokens, verifyMangleChecksum, verifyMangleMapIntegrity, verifyRecoveryToken };
-export type { HydrationError, HydrationErrorType, MangleMap, RecoveryManifest, RecoveryMode, RuntimeConfig, SSRContext, SzInput, TokenData, VerificationResult };
+export { DEFAULT_RUNTIME_CONFIG, VERSION, _sz, _sz2, _sz3, _szMerge, abortHydration, attemptCSRRecovery, classify, classifySzKey, clearHydrationErrors, computeMangleChecksumAsync, disableCSRRecovery, enableCSRRecovery, endHydration, getAbortedSubtreeCount, getHydrationErrors, getRecoveryMode, getRuntimeConfig, getSSRContext, guardHydration, has, hasRecoveryToken, hasSz, initRuntime, isCSRRecoveryAllowed, isHydrating, isHydrationAborted, isRuntimeInitialized, isSSREnvironment, isValidMangleMap, isValidManifest, loadMangleMapFromDOM, loadManifestFromDOM, omit, omitSz, pick, pickSz, resetRuntime, splitBox, splitBoxSz, startHydration, stripSzProps, szv, validateHydrationClass, verifyAllTokens, verifyMangleChecksum, verifyMangleChecksumAsync, verifyMangleMapIntegrity, verifyRecoveryToken };
+export type { BoxRole, BoxSelector, Classification, HydrationError, HydrationErrorType, MangleMap, RecoveryManifest, RecoveryMode, RuntimeConfig, SSRContext, SplitBoxOptions, SplitBoxResult, SplitBoxSzOptions, SplitBoxSzResult, SzInput, TokenData, VerificationResult };