@csszyx/types 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,110 @@
+export { BuildConfig, CsszyxConfig, DEFAULT_BUILD_CONFIG, DEFAULT_CSSZYX_CONFIG, DEFAULT_DEVELOPMENT_CONFIG, DEFAULT_HYDRATION_CONFIG, DEFAULT_PERFORMANCE_CONFIG, DEFAULT_PRODUCTION_CONFIG, DevelopmentConfig, Environment, HydrationConfig, PartialCsszyxConfig, PerformanceConfig, ProductionConfig, getCurrentEnvironment } from './config.js';
+export { AuditLogEntry, ComponentPropsWithSz, CsszyxWindow, HydrationError, HydrationErrorType, MangleMap, MangleMapMetadata, PerformanceMetrics, RecoveryManifest, RecoveryMode, RuntimeState, SzProp, TokenData, VerificationResult, isCsszyxWindow } from './runtime.js';
+export { BuildPhase, BuildPhaseResult, BuildPhaseStatus, BuildResult, BuildStatistics, CacheEntry, CacheManager, CollisionResult, CompilerContext, CompilerOptions, CompilerPlugin, FileCompilationResult, GeneratedToken, MangleMapEntry, NodeLocation, TokenMetadata, TransformOptions, ValidationError, ValidationResult } from './compiler.js';
+import { SzPropValue } from '@csszyx/compiler';
+export { SzPropValue, SzProps } from '@csszyx/compiler';
+
+/**
+ * @csszyx/types - Core WASM Contract
+ *
+ * This file defines the strict interface between the Rust/WASM core
+ * and the TypeScript world. This is the source of truth for "The Forge" workstream.
+ */
+/**
+ *
+ */
+interface CsszyxCoreWasm {
+    /**
+     * Encodes a numeric index into a compact tier-based class name (z, y, x...).
+     */
+    encode(index: number): string;
+    /**
+     * Generates a unique cryptographic recovery token for SSR hydration safety.
+     */
+    generate_token(componentName: string, filePath: string, line: number, column: number, recoveryMode: 'csr' | 'dev-only', buildId: string): string;
+    /**
+     * Verifies if a recovery token is valid for the given context.
+     */
+    verify_token(token: string, componentName: string, filePath: string, line: number, column: number, recoveryMode: 'csr' | 'dev-only', buildId: string): boolean;
+    /**
+     * Computes a dual-hash for a CSS class name to prevent collisions.
+     */
+    compute_dual_hash(className: string): string;
+    /**
+     * Returns the current version of the core engine.
+     */
+    version(): string;
+}
+/**
+ * The expected structure of the WASM initialization output.
+ */
+interface CsszyxCorePkg {
+    default: () => Promise<void>;
+    encode: (index: number) => string;
+    generate_token: (componentName: string, filePath: string, line: number, column: number, recoveryMode: string, buildId: string) => string;
+    verify_token: (token: string, componentName: string, filePath: string, line: number, column: number, recoveryMode: string, buildId: string) => boolean;
+    compute_dual_hash: (className: string) => string;
+    version: () => string;
+}
+
+/**
+ * JSX type augmentation for csszyx sz prop.
+ *
+ * This module extends React's JSX namespace to add the `sz` prop
+ * to all HTML elements. Types are re-exported from @csszyx/compiler
+ * for IntelliSense and autocompletion.
+ *
+ * @module @csszyx/types/jsx
+ */
+
+
+
+declare module 'react' {
+  /**
+   *
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  interface HTMLAttributes<T> {
+    /**
+     * csszyx styling prop — Tailwind CSS via object syntax or class string.
+     *
+     * @example
+     * ```tsx
+     * <div sz={{ p: 4, bg: 'blue-500', hover: { bg: 'blue-700' } }} />
+     * <div sz="p-4 bg-blue-500 hover:bg-blue-700" />
+     * ```
+     */
+    sz?: SzPropValue;
+  }
+
+  /**
+   *
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  interface SVGAttributes<T> {
+    /**
+     * csszyx styling prop — Tailwind CSS via object syntax or class string.
+     *
+     * @example
+     * ```tsx
+     * <svg sz={{ fill: 'red-500', stroke: 'current' }} />
+     * ```
+     */
+    sz?: SzPropValue;
+  }
+}
+
+/**
+ * @csszyx/types - Shared TypeScript types for csszyx.
+ *
+ * This package provides comprehensive type definitions used across
+ * the csszyx framework, including configuration, runtime, and compiler types.
+ *
+ * @module @csszyx/types
+ */
+/**
+ * Package version.
+ */
+declare const VERSION = "0.0.0";
+
+export { type CsszyxCorePkg, type CsszyxCoreWasm, VERSION };

package/dist/index.js

@@ -0,0 +1,26 @@
+import {
+  DEFAULT_BUILD_CONFIG,
+  DEFAULT_CSSZYX_CONFIG,
+  DEFAULT_DEVELOPMENT_CONFIG,
+  DEFAULT_HYDRATION_CONFIG,
+  DEFAULT_PERFORMANCE_CONFIG,
+  DEFAULT_PRODUCTION_CONFIG,
+  getCurrentEnvironment
+} from "./chunk-2KLMBDLU.js";
+import {
+  isCsszyxWindow
+} from "./chunk-QAJB64L5.js";
+
+// src/index.ts
+var VERSION = "0.0.0";
+export {
+  DEFAULT_BUILD_CONFIG,
+  DEFAULT_CSSZYX_CONFIG,
+  DEFAULT_DEVELOPMENT_CONFIG,
+  DEFAULT_HYDRATION_CONFIG,
+  DEFAULT_PERFORMANCE_CONFIG,
+  DEFAULT_PRODUCTION_CONFIG,
+  VERSION,
+  getCurrentEnvironment,
+  isCsszyxWindow
+};

package/dist/jsx.d.ts

@@ -0,0 +1,50 @@
+/**
+ * JSX type augmentation for csszyx sz prop.
+ *
+ * This module extends React's JSX namespace to add the `sz` prop
+ * to all HTML elements. Types are re-exported from @csszyx/compiler
+ * for IntelliSense and autocompletion.
+ *
+ * @module @csszyx/types/jsx
+ */
+
+import 'react';
+
+import type { SzProps, SzPropValue } from '@csszyx/compiler';
+
+export type { SzProps, SzPropValue };
+
+declare module 'react' {
+  /**
+   *
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  interface HTMLAttributes<T> {
+    /**
+     * csszyx styling prop — Tailwind CSS via object syntax or class string.
+     *
+     * @example
+     * ```tsx
+     * <div sz={{ p: 4, bg: 'blue-500', hover: { bg: 'blue-700' } }} />
+     * <div sz="p-4 bg-blue-500 hover:bg-blue-700" />
+     * ```
+     */
+    sz?: SzPropValue;
+  }
+
+  /**
+   *
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  interface SVGAttributes<T> {
+    /**
+     * csszyx styling prop — Tailwind CSS via object syntax or class string.
+     *
+     * @example
+     * ```tsx
+     * <svg sz={{ fill: 'red-500', stroke: 'current' }} />
+     * ```
+     */
+    sz?: SzPropValue;
+  }
+}

package/dist/runtime.d.ts

@@ -0,0 +1,257 @@
+/**
+ * Runtime types for csszyx.
+ *
+ * This module defines types used at runtime for hydration guards,
+ * recovery tokens, and mangle maps.
+ */
+/**
+ * Recovery mode types.
+ */
+type RecoveryMode = 'csr' | 'dev-only';
+/**
+ * Token data stored in the recovery manifest.
+ */
+interface TokenData {
+    /**
+     * Recovery mode ('csr' or 'dev-only')
+     */
+    mode: RecoveryMode;
+    /**
+     * Component name where the token was generated
+     */
+    component: string;
+    /**
+     * File path relative to project root
+     */
+    path: string;
+}
+/**
+ * Recovery manifest structure.
+ *
+ * Embedded in build output as JSON in a script tag with id "__SZ_RECOVERY_MANIFEST__".
+ */
+interface RecoveryManifest {
+    /**
+     * Build ID (git hash or timestamp)
+     */
+    buildId: string;
+    /**
+     * SHA-256 checksum of the tokens object for integrity verification
+     */
+    checksum: string;
+    /**
+     * Map of recovery token → token data
+     */
+    tokens: Record<string, TokenData>;
+}
+/**
+ * Mangle map structure.
+ *
+ * Maps original Tailwind class names to their minified equivalents.
+ * Embedded in build output as JSON in a script tag with id "__SZ_MANGLE_MAP__".
+ */
+interface MangleMap {
+    /**
+     * Map of original class name → mangled class name
+     */
+    [originalClass: string]: string;
+}
+/**
+ * Mangle map metadata.
+ */
+interface MangleMapMetadata {
+    /**
+     * Build ID
+     */
+    buildId: string;
+    /**
+     * Total number of classes in the map
+     */
+    classCount: number;
+    /**
+     * SHA-256 checksum of the map for validation
+     */
+    checksum: string;
+    /**
+     * Timestamp when the map was generated
+     */
+    timestamp: number;
+}
+/**
+ * Hydration error types.
+ */
+type HydrationErrorType = 'checksum_mismatch' | 'map_missing' | 'invalid_token' | 'abort_failed';
+/**
+ * Hydration error details.
+ */
+interface HydrationError {
+    /**
+     * Error type
+     */
+    type: HydrationErrorType;
+    /**
+     * Error message
+     */
+    message: string;
+    /**
+     * Element where the error occurred (optional)
+     */
+    element?: HTMLElement;
+    /**
+     * Timestamp when error occurred
+     */
+    timestamp: number;
+    /**
+     * Stack trace (optional)
+     */
+    stack?: string;
+}
+/**
+ * Token verification result.
+ */
+interface VerificationResult {
+    /**
+     * Whether the token is valid
+     */
+    valid: boolean;
+    /**
+     * Token data if valid
+     */
+    tokenData?: TokenData;
+    /**
+     * Error message if invalid
+     */
+    error?: string;
+}
+/**
+ * Runtime state interface.
+ */
+interface RuntimeState {
+    /**
+     * Whether the runtime has been initialized
+     */
+    initialized: boolean;
+    /**
+     * Current environment
+     */
+    environment: 'development' | 'production' | 'test';
+    /**
+     * Whether CSR recovery is allowed
+     */
+    csrRecoveryAllowed: boolean;
+    /**
+     * Loaded recovery manifest
+     */
+    manifest?: RecoveryManifest;
+    /**
+     * Loaded mangle map
+     */
+    mangleMap?: MangleMap;
+    /**
+     * Recorded hydration errors
+     */
+    errors: HydrationError[];
+    /**
+     * Count of aborted subtrees
+     */
+    abortedCount: number;
+}
+/**
+ * JSX sz prop object type.
+ */
+interface SzProp {
+    [key: string]: string | number | boolean | SzProp;
+}
+/**
+ * Component props with sz attribute.
+ */
+interface ComponentPropsWithSz {
+    /**
+     * csszyx object syntax for Tailwind classes
+     */
+    sz?: SzProp | string;
+    /**
+     * Recovery mode (optional)
+     */
+    szRecover?: RecoveryMode;
+    /**
+     * Standard className prop (merged with sz)
+     */
+    className?: string;
+}
+/**
+ * Audit log entry.
+ */
+interface AuditLogEntry {
+    /**
+     * Log level
+     */
+    level: 'info' | 'warn' | 'error';
+    /**
+     * Log message
+     */
+    message: string;
+    /**
+     * Timestamp
+     */
+    timestamp: number;
+    /**
+     * Additional metadata
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Performance metrics.
+ */
+interface PerformanceMetrics {
+    /**
+     * Time taken for hydration guard (ms)
+     */
+    hydrationGuardTime?: number;
+    /**
+     * Time taken for token verification (ms)
+     */
+    tokenVerificationTime?: number;
+    /**
+     * Total number of tokens verified
+     */
+    tokensVerified?: number;
+    /**
+     * Number of hydration errors
+     */
+    hydrationErrors?: number;
+    /**
+     * Memory usage (bytes)
+     */
+    memoryUsage?: number;
+}
+/**
+ * Global window interface extensions for csszyx.
+ */
+interface CsszyxWindow extends Window {
+    /**
+     * Allow CSR recovery flag (development only)
+     */
+    __SZ_ALLOW_CSR_RECOVERY__?: boolean;
+    /**
+     * Runtime state
+     */
+    __SZ_RUNTIME_STATE__?: RuntimeState;
+    /**
+     * Performance metrics
+     */
+    __SZ_METRICS__?: PerformanceMetrics;
+    /**
+     * Debug mode flag
+     */
+    __SZ_DEBUG__?: boolean;
+}
+/**
+ * Type guard to check if window has csszyx extensions.
+ *
+ * @param {Window} win - Window object to check
+ * @returns {win is CsszyxWindow} True if window has csszyx extensions
+ */
+declare function isCsszyxWindow(win: Window): win is CsszyxWindow;
+
+export { type AuditLogEntry, type ComponentPropsWithSz, type CsszyxWindow, type HydrationError, type HydrationErrorType, type MangleMap, type MangleMapMetadata, type PerformanceMetrics, type RecoveryManifest, type RecoveryMode, type RuntimeState, type SzProp, type TokenData, type VerificationResult, isCsszyxWindow };

package/dist/runtime.js

@@ -0,0 +1,6 @@
+import {
+  isCsszyxWindow
+} from "./chunk-QAJB64L5.js";
+export {
+  isCsszyxWindow
+};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@csszyx/types",
+  "version": "0.1.0",
+  "description": "TypeScript definitions for csszyx",
+  "keywords": [
+    "csszyx",
+    "types",
+    "typescript"
+  ],
+  "author": "csszyx contributors",
+  "license": "MIT",
+  "homepage": "https://github.com/nguyennhutien/csszyx/tree/main/packages/types#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nguyennhutien/csszyx.git",
+    "directory": "packages/types"
+  },
+  "bugs": {
+    "url": "https://github.com/nguyennhutien/csszyx/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "import": "./dist/runtime.js"
+    },
+    "./compiler": {
+      "types": "./dist/compiler.d.ts",
+      "import": "./dist/compiler.js"
+    },
+    "./jsx": {
+      "types": "./dist/jsx.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts src/config.ts src/runtime.ts src/compiler.ts --format esm --dts && cp src/jsx.d.ts dist/jsx.d.ts",
+    "dev": "tsup src/index.ts src/config.ts src/runtime.ts src/compiler.ts --format esm --dts --watch",
+    "type-check": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.3"
+  },
+  "peerDependencies": {
+    "@csszyx/compiler": ">=0.0.0"
+  }
+}