@csszyx/runtime 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,695 @@
+import { SzObject } from '@csszyx/compiler';
+
+/**
+ * Zero-allocation className concatenation helper.
+ *
+ * This module provides the runtime helper for composing dynamic className
+ * strings with minimal overhead. The _sz() function is designed for
+ * performance-critical scenarios where className composition happens
+ * frequently.
+ *
+ * @module @csszyx/runtime/concatenate
+ */
+
+/**
+ * Type for sz input - can be a pre-compiled string or SzObject.
+ */
+type SzInput = string | SzObject | null | undefined | false;
+/**
+ * Zero-overhead className passthrough/concatenation helper.
+ *
+ * When the compiler pre-transforms sz objects to strings at build time,
+ * this function simply passes through the string (zero overhead).
+ * For runtime usage, it can also concatenate multiple class strings
+ * or transform SzObjects on-the-fly.
+ *
+ * @param {...SzInput[]} classes - Class names or SzObjects to concatenate
+ * @returns {string} Combined className string
+ *
+ * @example
+ * ```typescript
+ * // Passthrough (from compiler) - zero overhead
+ * _sz('p-4 bg-red-500')
+ * // Returns: "p-4 bg-red-500"
+ *
+ * // With conditionals
+ * _sz('base', isActive && 'active', error && 'error')
+ * // Returns: "base active" (if isActive is true, error is false)
+ *
+ * // With SzObject (runtime transform)
+ * _sz({ p: 4, bg: 'red-500' })
+ * // Returns: "p-4 bg-red-500"
+ * ```
+ */
+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.
+ *
+ * Useful when combining multiple className sources that may overlap.
+ *
+ * @param {...SzInput[]} classes - Class names or SzObjects to merge
+ * @returns {string} Merged className string with duplicates removed
+ *
+ * @example
+ * ```typescript
+ * _szMerge('a b c', 'b c d', 'c d e')
+ * // Returns: "a b c d e"
+ *
+ * _szMerge({ p: 4 }, { p: 2, m: 4 })
+ * // Returns: "p-4 p-2 m-4" (duplicates from different calls are kept)
+ * ```
+ */
+declare function _szMerge(...classes: SzInput[]): string;
+/**
+ * Performance-optimized variant of _sz() for exactly 2 arguments.
+ *
+ * Faster than the variadic version when the number of classes is known
+ * at compile time. Use for hot paths.
+ *
+ * @param {string} a - First className
+ * @param {string} b - Second className
+ * @returns {string} Combined className string
+ *
+ * @example
+ * ```typescript
+ * _sz2('a', 'b')
+ * // Returns: "a b"
+ * ```
+ */
+declare function _sz2(a: string, b: string): string;
+/**
+ * Performance-optimized variant for exactly 3 arguments.
+ *
+ * @param {string} a - First className
+ * @param {string} b - Second className
+ * @param {string} c - Third className
+ * @returns {string} Combined className string
+ */
+declare function _sz3(a: string, b: string, c: string): string;
+
+/**
+ * Recovery Token Verification - Runtime validation of recovery tokens.
+ *
+ * This module provides runtime verification of recovery tokens against
+ * the recovery manifest embedded in the build output. It ensures that
+ * szRecover directives are legitimate and haven't been tampered with.
+ */
+/**
+ * Recovery mode types.
+ */
+type RecoveryMode = 'csr' | 'dev-only';
+/**
+ * Token data from the manifest.
+ */
+interface TokenData {
+    mode: RecoveryMode;
+    component: string;
+    path: string;
+}
+/**
+ * Recovery manifest structure.
+ */
+interface RecoveryManifest {
+    buildId: string;
+    checksum: string;
+    tokens: Record<string, TokenData>;
+}
+/**
+ * Token verification result.
+ */
+interface VerificationResult {
+    /**
+     * Whether the token is valid
+     */
+    valid: boolean;
+    /**
+     * Token data if valid
+     */
+    tokenData?: TokenData;
+    /**
+     * Error message if invalid
+     */
+    error?: string;
+}
+/**
+ * Verifies a recovery token against the manifest.
+ *
+ * Checks that the token exists in the manifest and returns its metadata.
+ * This is used at runtime to validate szRecover directives.
+ *
+ * @param {HTMLElement} element - The DOM element with the recovery token
+ * @param {RecoveryManifest} manifest - The recovery manifest
+ * @returns {VerificationResult} Verification result
+ *
+ * @example
+ * ```typescript
+ * const element = document.querySelector('[data-sz-recovery-token]');
+ * const result = verifyRecoveryToken(element, manifest);
+ *
+ * if (result.valid) {
+ *     console.log('Token verified:', result.tokenData);
+ * } else {
+ *     console.error('Invalid token:', result.error);
+ * }
+ * ```
+ */
+declare function verifyRecoveryToken(element: HTMLElement, manifest: RecoveryManifest): VerificationResult;
+/**
+ * Loads the recovery manifest from the DOM.
+ *
+ * Searches for the embedded manifest script tag and parses it.
+ *
+ * @returns {RecoveryManifest | null} The manifest or null if not found
+ *
+ * @example
+ * ```typescript
+ * const manifest = loadManifestFromDOM();
+ * if (manifest) {
+ *     console.log('Manifest loaded:', manifest.buildId);
+ * }
+ * ```
+ */
+declare function loadManifestFromDOM(): RecoveryManifest | null;
+/**
+ * Validates manifest structure.
+ *
+ * @param {unknown} manifest - Manifest to validate
+ * @returns {boolean} True if valid
+ */
+declare function isValidManifest(manifest: unknown): manifest is RecoveryManifest;
+/**
+ * Verifies all elements with recovery tokens in a subtree.
+ *
+ * Scans the given root element and all its descendants for recovery tokens
+ * and verifies them against the manifest.
+ *
+ * @param {HTMLElement} root - Root element to scan
+ * @param {RecoveryManifest} manifest - Recovery manifest
+ * @returns {VerificationResult[]} Array of verification results
+ *
+ * @example
+ * ```typescript
+ * const results = verifyAllTokens(document.body, manifest);
+ * const invalid = results.filter(r => !r.valid);
+ * if (invalid.length > 0) {
+ *     console.error('Found invalid tokens:', invalid);
+ * }
+ * ```
+ */
+declare function verifyAllTokens(root: HTMLElement, manifest: RecoveryManifest): VerificationResult[];
+/**
+ * Checks if an element has a valid recovery token.
+ *
+ * Quick check to see if an element has a recovery token without
+ * full verification.
+ *
+ * @param {HTMLElement} element - Element to check
+ * @returns {boolean} True if element has recovery token
+ *
+ * @example
+ * ```typescript
+ * if (hasRecoveryToken(element)) {
+ *     // Element has szRecover directive
+ * }
+ * ```
+ */
+declare function hasRecoveryToken(element: HTMLElement): boolean;
+/**
+ * Gets the recovery mode from an element.
+ *
+ * @param {HTMLElement} element - Element with recovery token
+ * @returns {RecoveryMode | null} The recovery mode or null
+ *
+ * @example
+ * ```typescript
+ * const mode = getRecoveryMode(element);
+ * if (mode === 'csr') {
+ *     // Allow client-side recovery
+ * }
+ * ```
+ */
+declare function getRecoveryMode(element: HTMLElement): RecoveryMode | null;
+
+/**
+ * Hydration Guard and Abort Protocol.
+ *
+ * This module implements the hydration safety mechanism that ensures
+ * SSR/CSR consistency. It detects mangle map mismatches and executes
+ * the abort protocol when necessary to preserve SSR invariants.
+ */
+
+/**
+ * Window augmentation for csszyx global state.
+ */
+declare global {
+    /**
+     * Extended Window interface for csszyx runtime state.
+     */
+    interface Window {
+        /** Flag to allow CSR recovery in development */
+        __SZ_ALLOW_CSR_RECOVERY__?: boolean;
+        /** Flag indicating if the app is currently hydrating */
+        __SZ_HYDRATING__?: boolean;
+        /** Next.js data (for framework detection) */
+        __NEXT_DATA__?: unknown;
+        /** Remix context (for framework detection) */
+        __REMIX_CONTEXT__?: unknown;
+    }
+}
+/**
+ * Mangle map structure loaded from the DOM.
+ */
+interface MangleMap {
+    [originalClass: string]: string;
+}
+/**
+ * Hydration error types.
+ */
+type HydrationErrorType = 'checksum_mismatch' | 'map_missing' | 'invalid_token';
+/**
+ * Hydration error details.
+ */
+interface HydrationError {
+    type: HydrationErrorType;
+    message: string;
+    element?: HTMLElement;
+    timestamp: number;
+}
+/**
+ * Enables CSR recovery mode (development only).
+ *
+ * Sets the global flag to allow client-side recovery when
+ * hydration mismatches occur. Should only be used in development.
+ *
+ * @example
+ * ```typescript
+ * if (process.env.NODE_ENV === 'development') {
+ *     enableCSRRecovery();
+ * }
+ * ```
+ */
+declare function enableCSRRecovery(): void;
+/**
+ * Disables CSR recovery mode.
+ */
+declare function disableCSRRecovery(): void;
+/**
+ * Checks if CSR recovery is allowed.
+ *
+ * @returns {boolean} True if recovery is allowed
+ */
+declare function isCSRRecoveryAllowed(): boolean;
+/**
+ * Loads the mangle map from the DOM.
+ *
+ * Searches for the embedded mangle map script tag and parses it.
+ *
+ * @returns {MangleMap | null} The mangle map or null if not found
+ *
+ * @example
+ * ```typescript
+ * const mangleMap = loadMangleMapFromDOM();
+ * if (mangleMap) {
+ *     console.log('Mangle map loaded');
+ * }
+ * ```
+ */
+declare function loadMangleMapFromDOM(): MangleMap | null;
+/**
+ * Verifies mangle map checksum from HTML tag.
+ *
+ * Compares the checksum in the data-sz-checksum attribute with the
+ * expected checksum to detect mangle map mismatches.
+ *
+ * @param {string} expectedChecksum - Expected checksum
+ * @returns {boolean} True if checksums match
+ *
+ * @example
+ * ```typescript
+ * if (!verifyMangleChecksum(manifest.checksum)) {
+ *     console.error('Checksum mismatch detected');
+ * }
+ * ```
+ */
+declare function verifyMangleChecksum(expectedChecksum: string): boolean;
+/**
+ * Verifies mangle map integrity using Rust core verification.
+ *
+ * Loads the mangle map from DOM and verifies its checksum using the
+ * Rust core's `verify_mangle_checksum()` function for cryptographic-grade verification.
+ *
+ * @returns {boolean} True if mangle map integrity is verified
+ *
+ * @example
+ * ```typescript
+ * if (!verifyMangleMapIntegrity()) {
+ *     console.error('[csszyx] Mangle map integrity check failed');
+ *     abortHydration();
+ * }
+ * ```
+ */
+declare function verifyMangleMapIntegrity(): boolean;
+/**
+ * Executes the hydration abort protocol for a subtree.
+ *
+ * Implements the 5-step abort protocol:
+ * 1. Terminate hydration at subtree root
+ * 2. Preserve static HTML/CSS from SSR
+ * 3. Log audit message
+ * 4. Inject abort attribute
+ * 5. Block event handlers
+ *
+ * @param {HTMLElement} element - Root of the subtree to abort
+ * @param {HydrationError} error - The hydration error that triggered abort
+ *
+ * @example
+ * ```typescript
+ * abortHydration(element, {
+ *     type: 'checksum_mismatch',
+ *     message: 'Mangle checksum mismatch',
+ *     timestamp: Date.now()
+ * });
+ * ```
+ */
+declare function abortHydration(element: HTMLElement, error: HydrationError): void;
+/**
+ * Checks if a subtree has been aborted.
+ *
+ * @param {HTMLElement} element - Element to check
+ * @returns {boolean} True if hydration was aborted
+ *
+ * @example
+ * ```typescript
+ * if (isHydrationAborted(element)) {
+ *     // Skip hydration for this subtree
+ * }
+ * ```
+ */
+declare function isHydrationAborted(element: HTMLElement): boolean;
+/**
+ * Guards hydration process by verifying mangle map integrity.
+ *
+ * Main entry point for hydration guarding. Checks the mangle map
+ * checksum and executes the abort protocol if there's a mismatch.
+ *
+ * @param {RecoveryManifest} manifest - Recovery manifest
+ * @returns {boolean} True if hydration can proceed safely
+ *
+ * @example
+ * ```typescript
+ * const manifest = loadManifestFromDOM();
+ * if (manifest && !guardHydration(manifest)) {
+ *     console.error('Hydration guard failed');
+ * }
+ * ```
+ */
+declare function guardHydration(manifest: RecoveryManifest): boolean;
+/**
+ * Attempts client-side recovery for an aborted subtree.
+ *
+ * Only allowed in development mode when CSR recovery is enabled.
+ * Logs a warning to remind developer to fix the root cause.
+ *
+ * @param {HTMLElement} element - Element to recover
+ * @returns {boolean} True if recovery was attempted
+ *
+ * @example
+ * ```typescript
+ * if (isCSRRecoveryAllowed() && isHydrationAborted(element)) {
+ *     attemptCSRRecovery(element);
+ * }
+ * ```
+ */
+declare function attemptCSRRecovery(element: HTMLElement): boolean;
+/**
+ * Gets all hydration errors.
+ *
+ * @returns {HydrationError[]} Array of errors
+ *
+ * @example
+ * ```typescript
+ * const errors = getHydrationErrors();
+ * console.log(`Found ${errors.length} hydration errors`);
+ * ```
+ */
+declare function getHydrationErrors(): HydrationError[];
+/**
+ * Clears hydration errors (for testing).
+ */
+declare function clearHydrationErrors(): void;
+/**
+ * Gets the count of aborted subtrees.
+ *
+ * @returns {number} Number of aborted subtrees
+ */
+declare function getAbortedSubtreeCount(): number;
+/**
+ * SSR context structure embedded in the HTML.
+ */
+interface SSRContext {
+    /**
+     * Build ID for cache invalidation.
+     */
+    buildId: string;
+    /**
+     * Checksum of the mangle map.
+     */
+    checksum: string;
+    /**
+     * Timestamp when the page was rendered.
+     */
+    timestamp: number;
+    /**
+     * Whether recovery tokens are present.
+     */
+    hasRecoveryTokens: boolean;
+}
+/**
+ * Checks if the current environment is SSR (server-side).
+ *
+ * @returns {boolean} True if running on server
+ *
+ * @example
+ * ```typescript
+ * if (isSSREnvironment()) {
+ *     // Server-side logic
+ * } else {
+ *     // Client-side logic
+ * }
+ * ```
+ */
+declare function isSSREnvironment(): boolean;
+/**
+ * Checks if the application is currently hydrating.
+ *
+ * Reads the hydration state from the window object set by the framework.
+ *
+ * @returns {boolean} True if hydrating
+ *
+ * @example
+ * ```typescript
+ * if (isHydrating()) {
+ *     // Use SSR-generated classes
+ * } else {
+ *     // Safe to use dynamic classes
+ * }
+ * ```
+ */
+declare function isHydrating(): boolean;
+/**
+ * Gets the SSR context from the DOM.
+ *
+ * Reads the context embedded by the server during SSR to ensure
+ * consistent class generation between server and client.
+ *
+ * @returns {SSRContext | null} The SSR context or null if not found
+ *
+ * @example
+ * ```typescript
+ * const context = getSSRContext();
+ * if (context) {
+ *     console.log('Build ID:', context.buildId);
+ *     console.log('Checksum:', context.checksum);
+ * }
+ * ```
+ */
+declare function getSSRContext(): SSRContext | null;
+/**
+ * Validates that client-side class generation matches SSR.
+ *
+ * Call this during hydration to ensure consistency between server
+ * and client rendered classes.
+ *
+ * @param {string} className - The className generated on the client
+ * @param {string} expectedClassName - The className from SSR
+ * @returns {boolean} True if classes match
+ *
+ * @example
+ * ```typescript
+ * const serverClass = element.className;
+ * const clientClass = _sz({ p: 4, bg: 'red-500' });
+ *
+ * if (!validateHydrationClass(clientClass, serverClass)) {
+ *     console.warn('Hydration mismatch detected');
+ * }
+ * ```
+ */
+declare function validateHydrationClass(className: string, expectedClassName: string): boolean;
+/**
+ * Marks the start of hydration.
+ *
+ * Call this when your framework begins hydration to enable
+ * hydration-safe mode in the runtime.
+ *
+ * @example
+ * ```typescript
+ * // In your app entry point
+ * startHydration();
+ * hydrateRoot(document.getElementById('root'), <App />);
+ * ```
+ */
+declare function startHydration(): void;
+/**
+ * Marks the end of hydration.
+ *
+ * Call this when hydration is complete to allow dynamic class
+ * generation without SSR constraints.
+ *
+ * @example
+ * ```typescript
+ * // After hydration completes
+ * endHydration();
+ * ```
+ */
+declare function endHydration(): void;
+
+/**
+ * @csszyx/runtime - Runtime package for csszyx.
+ *
+ * This package provides runtime functionality for csszyx, including:
+ * - Zero-allocation className concatenation helpers
+ * - Recovery token verification
+ * - Hydration guard and abort protocol
+ *
+ * @module @csszyx/runtime
+ */
+
+/**
+ * Runtime version.
+ */
+declare const VERSION = "0.0.0";
+/**
+ * Runtime configuration options.
+ */
+interface RuntimeConfig {
+    /**
+     * Enable development mode features
+     */
+    development?: boolean;
+    /**
+     * Allow CSR recovery in development
+     */
+    allowCSRRecovery?: boolean;
+    /**
+     * Enable strict hydration checks
+     */
+    strictHydration?: boolean;
+    /**
+     * Enable debug logging
+     */
+    debug?: boolean;
+}
+/**
+ * Default runtime configuration.
+ */
+declare const DEFAULT_RUNTIME_CONFIG: Required<RuntimeConfig>;
+/**
+ * Initializes the csszyx runtime.
+ *
+ * Should be called once at application startup to configure the runtime
+ * behavior and set up hydration guards.
+ *
+ * @param {Partial<RuntimeConfig>} config - Runtime configuration
+ *
+ * @example
+ * ```typescript
+ * // In your app entry point
+ * initRuntime({
+ *     development: process.env.NODE_ENV === 'development',
+ *     allowCSRRecovery: true,
+ *     debug: true
+ * });
+ * ```
+ */
+declare function initRuntime(config?: Partial<RuntimeConfig>): void;
+/**
+ * Gets the current runtime configuration.
+ *
+ * @returns {Required<RuntimeConfig>} Current runtime config
+ *
+ * @example
+ * ```typescript
+ * const config = getRuntimeConfig();
+ * console.log('Debug mode:', config.debug);
+ * ```
+ */
+declare function getRuntimeConfig(): Required<RuntimeConfig>;
+/**
+ * Checks if the runtime has been initialized.
+ *
+ * @returns {boolean} True if initialized
+ */
+declare function isRuntimeInitialized(): boolean;
+/**
+ * Resets the runtime state (for testing).
+ */
+declare function resetRuntime(): void;
+
+export { DEFAULT_RUNTIME_CONFIG, type HydrationError, type HydrationErrorType, type MangleMap, type RecoveryManifest, type RecoveryMode, type RuntimeConfig, type SSRContext, type SzInput, type TokenData, VERSION, type VerificationResult, _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, validateHydrationClass, verifyAllTokens, verifyMangleChecksum, verifyMangleMapIntegrity, verifyRecoveryToken };