prev-cli 0.24.15 → 0.24.16

package/dist/tokens/resolver.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Token configuration interface matching shadcn design system
+ */
+export interface TokensConfig {
+    colors: Record<string, string>;
+    backgrounds: Record<string, string>;
+    spacing: Record<string, string>;
+    typography: {
+        sizes: Record<string, string>;
+        weights: Record<string, number>;
+    };
+    radius: Record<string, string>;
+    shadows: Record<string, string>;
+}
+/**
+ * Partial token configuration for user overrides
+ * All fields are optional and can be deeply nested
+ */
+export type PartialTokensConfig = {
+    colors?: Record<string, string | null>;
+    backgrounds?: Record<string, string | null>;
+    spacing?: Record<string, string | null>;
+    typography?: {
+        sizes?: Record<string, string | null>;
+        weights?: Record<string, number | null>;
+    };
+    radius?: Record<string, string | null>;
+    shadows?: Record<string, string | null>;
+};
+/**
+ * Options for resolving tokens
+ */
+export interface ResolveTokensOptions {
+    /** Path to user's tokens.yaml file */
+    userTokensPath?: string;
+    /** Inline user token overrides (takes precedence over file) */
+    userTokens?: PartialTokensConfig;
+    /** Path to defaults.yaml (defaults to bundled defaults) */
+    defaultsPath?: string;
+}
+/**
+ * Load and parse a YAML tokens file (full validation)
+ * @param filePath - Absolute path to the YAML file
+ * @returns Parsed tokens configuration
+ * @throws Error if file doesn't exist or contains invalid YAML
+ */
+export declare function loadTokens(filePath: string): TokensConfig;
+/**
+ * Resolve tokens by merging defaults with user overrides
+ *
+ * Resolution order (later wins):
+ * 1. Bundled default tokens
+ * 2. User tokens from file (if userTokensPath provided)
+ * 3. Inline user tokens (if userTokens provided)
+ *
+ * @param options - Resolution options
+ * @returns Fully resolved tokens configuration
+ */
+export declare function resolveTokens(options?: ResolveTokensOptions): TokensConfig;
+/**
+ * Convenience function to resolve tokens from a project directory
+ * Looks for tokens.yaml in the project root
+ *
+ * @param projectDir - Path to the project directory
+ * @returns Resolved tokens configuration
+ */
+export declare function resolveProjectTokens(projectDir: string): TokensConfig;

package/dist/tokens/utils.d.ts

@@ -0,0 +1,15 @@
+export declare function deepMerge<T extends Record<string, unknown>>(target: T, source: Partial<T> | Record<string, unknown>): T;
+/**
+ * Type-safe deep merge for token configurations.
+ * This is a specialized version of deepMerge that handles TokensConfig type properly.
+ */
+export declare function mergeTokenConfigs<T>(target: T, source: unknown): T;
+/**
+ * Calculate the Levenshtein distance between two strings.
+ * Used for "did you mean?" suggestions in validation errors.
+ *
+ * @param a - First string
+ * @param b - Second string
+ * @returns The edit distance between the strings
+ */
+export declare function levenshtein(a: string, b: string): number;

package/dist/tokens/validation.d.ts

@@ -0,0 +1,36 @@
+import { type TokensConfig } from './resolver';
+/**
+ * Error thrown when a token validation fails.
+ * Includes helpful suggestions for similar valid tokens.
+ */
+export declare class ValidationError extends Error {
+    readonly category: string;
+    readonly invalidToken: string;
+    readonly suggestions: string[];
+    constructor(message: string, category: string, invalidToken: string, suggestions: string[]);
+}
+/**
+ * Valid category names that can be used with validateToken.
+ * Supports dot notation for nested categories like "typography.sizes"
+ */
+export type TokenCategory = 'colors' | 'backgrounds' | 'spacing' | 'typography.sizes' | 'typography.weights' | 'radius' | 'shadows';
+/**
+ * Validate that a token name is valid for a given category.
+ * Throws a ValidationError with helpful suggestions if invalid.
+ *
+ * @param category - The token category (e.g., "colors", "typography.sizes")
+ * @param tokenName - The token name to validate
+ * @param config - Optional pre-resolved tokens config (defaults to resolveTokens())
+ * @throws ValidationError if the token is invalid
+ * @throws Error if the category is invalid
+ */
+export declare function validateToken(category: TokenCategory, tokenName: string, config?: TokensConfig): void;
+/**
+ * Check if a token is valid without throwing.
+ *
+ * @param category - The token category
+ * @param tokenName - The token name to check
+ * @param config - Optional pre-resolved tokens config
+ * @returns true if valid, false if invalid
+ */
+export declare function isValidToken(category: TokenCategory, tokenName: string, config?: TokensConfig): boolean;

package/dist/typecheck/index.d.ts

@@ -0,0 +1,24 @@
+export interface TypecheckOptions {
+    /** Directory containing preview files to check */
+    previewsDir?: string;
+    /** Patterns to include (default: ["**\/*.{ts,tsx}"]) */
+    include?: string[];
+    /** Enable strict mode (default: true) */
+    strict?: boolean;
+    /** Show verbose output */
+    verbose?: boolean;
+}
+export interface TypecheckResult {
+    success: boolean;
+    fileCount: number;
+    errorCount: number;
+    output: string;
+}
+/**
+ * Run type checking on preview files using embedded tsgo
+ */
+export declare function typecheck(rootDir: string, options?: TypecheckOptions): Promise<TypecheckResult>;
+/**
+ * Format typecheck result for CLI output
+ */
+export declare function formatTypecheckResult(result: TypecheckResult): string;

package/dist/ui/button.d.ts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import { type VariantProps } from 'class-variance-authority';
 declare const buttonVariants: (props?: ({
-    variant?: "link" | "default" | "destructive" | "outline" | "secondary" | "ghost" | null | undefined;
+    variant?: "link" | "default" | "secondary" | "destructive" | "outline" | "ghost" | null | undefined;
     size?: "default" | "sm" | "lg" | "icon" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {

package/dist/validators/index.d.ts

@@ -0,0 +1,59 @@
+import { validateConfig, validateAllLayouts, clearSchemaCache, type SchemaValidationResult, type SchemaValidationError } from './schema-validator';
+import { validateSemantics, createValidationContext, registerPreviewUnit, checkDuplicateIds, type SemanticValidationResult, type SemanticValidationError, type SemanticValidationWarning, type ValidationContext } from './semantic-validator';
+export interface ValidationOptions {
+    /** Specific renderer to validate (validates all if not specified) */
+    renderer?: string;
+    /** Only validate schema (skip semantic validation) */
+    schemaOnly?: boolean;
+    /** Only validate semantic rules (skip schema validation) */
+    semanticOnly?: boolean;
+}
+export interface ValidationResult {
+    valid: boolean;
+    summary: {
+        components: {
+            total: number;
+            valid: number;
+            invalid: number;
+        };
+        screens: {
+            total: number;
+            valid: number;
+            invalid: number;
+        };
+        flows: {
+            total: number;
+            valid: number;
+            invalid: number;
+        };
+        atlas: {
+            total: number;
+            valid: number;
+            invalid: number;
+        };
+    };
+    errors: ValidationError[];
+    warnings: ValidationWarning[];
+}
+export interface ValidationError {
+    file: string;
+    path: string;
+    message: string;
+    type: 'schema' | 'semantic';
+}
+export interface ValidationWarning {
+    file: string;
+    path: string;
+    message: string;
+}
+/**
+ * Validate all preview configs
+ */
+export declare function validate(rootDir?: string, options?: ValidationOptions): Promise<ValidationResult>;
+/**
+ * Format validation result for CLI output
+ */
+export declare function formatValidationResult(result: ValidationResult): string;
+export type { SchemaValidationResult, SchemaValidationError, SemanticValidationResult, SemanticValidationError, SemanticValidationWarning, ValidationContext, };
+export { validateConfig, validateAllLayouts, clearSchemaCache };
+export { validateSemantics, createValidationContext, registerPreviewUnit, checkDuplicateIds };

package/dist/validators/schema-validator.d.ts

@@ -0,0 +1,27 @@
+export interface SchemaValidationResult {
+    valid: boolean;
+    errors: SchemaValidationError[];
+}
+export interface SchemaValidationError {
+    path: string;
+    message: string;
+    keyword: string;
+}
+/**
+ * Validate a config object against the preview schema
+ */
+export declare function validateConfig(config: Record<string, unknown>): SchemaValidationResult;
+/**
+ * Validate a layout subtree against a specific renderer's layout schema
+ * Accepts both array and object layouts (design allows adapters to use either)
+ */
+export declare function validateLayoutForRenderer(layout: unknown, rendererName: string): SchemaValidationResult;
+/**
+ * Validate all layoutByRenderer entries against their respective adapter schemas
+ * Accepts both array and object layouts per the design spec
+ */
+export declare function validateAllLayouts(layoutByRenderer: Record<string, unknown> | undefined, targetRenderer?: string): SchemaValidationResult;
+/**
+ * Clear the schema cache (for testing)
+ */
+export declare function clearSchemaCache(): void;

package/dist/validators/semantic-validator.d.ts

@@ -0,0 +1,47 @@
+import type { PreviewConfig } from '../renderers/types';
+export interface SemanticValidationResult {
+    valid: boolean;
+    errors: SemanticValidationError[];
+    warnings: SemanticValidationWarning[];
+}
+export interface SemanticValidationError {
+    path: string;
+    message: string;
+    code: SemanticErrorCode;
+}
+export interface SemanticValidationWarning {
+    path: string;
+    message: string;
+    code: SemanticWarningCode;
+}
+export type SemanticErrorCode = 'DUPLICATE_ID' | 'INVALID_REF' | 'INVALID_STATE_REF' | 'INVALID_STEP_REF' | 'INVALID_NODE_REF' | 'CIRCULAR_DEPENDENCY' | 'UNKNOWN_RENDERER' | 'INVALID_TEMPLATE' | 'INVALID_SLOT' | 'MISSING_SLOT_DEFINITION';
+export type SemanticWarningCode = 'DEPRECATED_STATUS' | 'MISSING_DESCRIPTION';
+export interface ValidationContext {
+    /** Root directory containing previews folder */
+    rootDir: string;
+    /** Map of all known preview IDs by type */
+    knownIds: {
+        components: Set<string>;
+        screens: Set<string>;
+        flows: Set<string>;
+        atlas: Set<string>;
+    };
+    /** Map of screen states by screen ID */
+    screenStates: Map<string, Set<string>>;
+}
+/**
+ * Validate a config against semantic rules
+ */
+export declare function validateSemantics(config: PreviewConfig, context: ValidationContext, configPath?: string): SemanticValidationResult;
+/**
+ * Create an empty validation context
+ */
+export declare function createValidationContext(rootDir: string): ValidationContext;
+/**
+ * Register a preview unit in the validation context
+ */
+export declare function registerPreviewUnit(context: ValidationContext, type: 'component' | 'screen' | 'flow' | 'atlas', id: string, states?: string[]): void;
+/**
+ * Check for duplicate IDs within a type
+ */
+export declare function checkDuplicateIds(ids: string[], type: string): SemanticValidationError[];

package/dist/vite/plugins/tokens-plugin.d.ts

@@ -0,0 +1,2 @@
+import type { Plugin } from 'vite';
+export declare function tokensPlugin(rootDir: string): Plugin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prev-cli",
-  "version": "0.24.15",
+  "version": "0.24.16",
   "description": "Transform MDX directories into beautiful documentation websites",
   "type": "module",
   "license": "MIT",
@@ -34,7 +34,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "build": "bun build src/cli.ts --outdir dist --target node --packages external && tsc --emitDeclarationOnly",
+    "build": "bun build src/cli.ts --outdir dist --target bun --packages external --banner 'if(typeof globalThis.Bun===\"undefined\"){console.error(\"\\n\\x1b[31mError: prev-cli requires Bun runtime\\x1b[0m\\n\\nYou are running with Node.js, but prev-cli uses Bun-specific APIs.\\n\\n\\x1b[33mTo install and run with Bun:\\x1b[0m\\n\\n  # Global install (recommended)\\n  bun i -g prev-cli\\n  prev-cli dev\\n\\n  # Or local install\\n  bun add -d prev-cli\\n  bunx --bun prev-cli dev\\n\\n\\x1b[90mLearn more: https://bun.sh/docs/installation\\x1b[0m\\n\");process.exit(1)}' && tsc --emitDeclarationOnly",
     "build:docs": "bun run build && bun ./dist/cli.js build",
     "prepublishOnly": "bun run build",
     "dev": "tsc --watch",
@@ -43,12 +43,17 @@
     "test:all": "bun run test && bun run test:integration"
   },
   "dependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@typescript/native-preview": "^7.0.0-dev",
     "@mdx-js/react": "^3.1.1",
     "@mdx-js/rollup": "^3.0.0",
     "@tailwindcss/vite": "^4.0.0",
     "@tanstack/react-router": "^1.145.7",
     "@terrastruct/d2": "^0.1.33",
     "@vitejs/plugin-react": "^5.1.2",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
     "class-variance-authority": "^0.7.0",
     "clsx": "^2.1.0",
     "esbuild": "^0.27.2",
@@ -70,10 +75,9 @@
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
+    "@types/json-schema": "^7.0.15",
     "@types/node": "^22.0.0",
     "@types/picomatch": "^4.0.2",
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0",
     "bun-types": "^1.3.5",
     "typescript": "^5.7.0"
   }

package/src/preview-runtime/fast-template.html

@@ -0,0 +1,115 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Preview</title>
+  <!-- Tailwind CSS v4 Play CDN -->
+  <script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>
+  <!-- Preload React -->
+  <link rel="modulepreload" href="https://esm.sh/react@18">
+  <link rel="modulepreload" href="https://esm.sh/react-dom@18/client">
+  <link rel="modulepreload" href="https://esm.sh/react@18/jsx-runtime">
+  <style>
+    body { margin: 0; }
+    #root { min-height: 100vh; }
+    .preview-loading {
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      min-height: 100vh;
+      font-family: system-ui, sans-serif;
+      color: #666;
+    }
+    .preview-error {
+      padding: 1rem;
+      background: #fef2f2;
+      color: #dc2626;
+      font-family: monospace;
+      font-size: 13px;
+      white-space: pre-wrap;
+    }
+  </style>
+</head>
+<body>
+  <div id="root"><div class="preview-loading">Loading preview...</div></div>
+
+  <!-- Import map must be BEFORE any module scripts -->
+  <script type="importmap">
+  {
+    "imports": {
+      "react": "https://esm.sh/react@18",
+      "react-dom": "https://esm.sh/react-dom@18",
+      "react-dom/client": "https://esm.sh/react-dom@18/client",
+      "react/jsx-runtime": "https://esm.sh/react@18/jsx-runtime"
+    }
+  }
+  </script>
+
+  <script type="module">
+    // Fast preview runtime - uses server-side bundled code
+    const params = new URLSearchParams(window.location.search)
+    const src = params.get('src')
+
+    if (!src) {
+      document.getElementById('root').innerHTML = '<div class="preview-error">No preview source specified</div>'
+    } else {
+      const startTime = performance.now()
+
+      try {
+        // Pre-fetch tokens, JSX, and bundle in parallel
+        const [tokensRes, jsxModule, bundleResponse] = await Promise.all([
+          fetch('/_prev/tokens.json').then(r => r.json()).catch(() => null),
+          import(`${window.location.origin}/_prev/jsx.js`),
+          fetch(`/_preview-bundle/${src}`)
+        ])
+
+        // Set tokens
+        if (tokensRes && jsxModule.setTokensConfig) {
+          jsxModule.setTokensConfig(tokensRes)
+        }
+
+        const bundleTime = bundleResponse.headers.get('X-Bundle-Time') || '?'
+
+        if (!bundleResponse.ok) {
+          throw new Error(`Bundle failed: ${await bundleResponse.text()}`)
+        }
+
+        // Bundle has React imports rewritten, but @prev/jsx needs client rewrite
+        let code = await bundleResponse.text()
+        code = code.replace(/from\s*["']@prev\/jsx["']/g, `from "${window.location.origin}/_prev/jsx.js"`)
+
+        // Create module blob and import it
+        const blob = new Blob([code], { type: 'application/javascript' })
+        const moduleUrl = URL.createObjectURL(blob)
+
+        const module = await import(moduleUrl)
+        URL.revokeObjectURL(moduleUrl)
+
+        // Render
+        const { createRoot } = await import('https://esm.sh/react-dom@18/client')
+        const React = await import('https://esm.sh/react@18')
+
+        const App = module.default
+        if (App) {
+          const root = createRoot(document.getElementById('root'))
+          root.render(React.createElement(App))
+        }
+
+        const totalTime = Math.round(performance.now() - startTime)
+        parent.postMessage({
+          type: 'built',
+          result: { success: true, buildTime: parseInt(bundleTime, 10) || totalTime }
+        }, '*')
+
+      } catch (err) {
+        document.getElementById('root').innerHTML = `<div class="preview-error">${err.message}</div>`
+        parent.postMessage({ type: 'error', error: err.message }, '*')
+      }
+    }
+
+    // Signal ready immediately
+    parent.postMessage({ type: 'ready' }, '*')
+  </script>
+</body>
+</html>

package/src/preview-runtime/template.html

@@ -4,6 +4,10 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Preview</title>
+  <!-- Preload React for faster module resolution -->
+  <link rel="modulepreload" href="https://esm.sh/react@18">
+  <link rel="modulepreload" href="https://esm.sh/react-dom@18/client">
+  <link rel="modulepreload" href="https://esm.sh/react@18/jsx-runtime">
   <!-- Tailwind CSS v4 Play CDN -->
   <script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>
   <!-- esbuild-wasm -->
@@ -35,7 +39,14 @@
   <script type="module">
     // Preview runtime - bundles React/TSX in browser via esbuild-wasm
 
-    let initialized = false
+    // Global error handler to catch module errors
+    window.onerror = (msg, url, line, col, error) => {
+      document.getElementById('root').innerHTML = `<div class="preview-error">Error: ${msg}\n${url}:${line}:${col}</div>`
+      return false
+    }
+
+    let esbuildReady = null // Promise that resolves when esbuild is ready
+    let tokensReady = null // Promise that resolves with tokens data
     let lastConfig = null
 
     function getLoader(filePath) {
@@ -44,12 +55,18 @@
       return loaders[ext] || 'tsx'
     }
 
+    // Pre-initialize esbuild immediately on page load
+    esbuildReady = esbuild.initialize({
+      wasmURL: 'https://unpkg.com/esbuild-wasm@0.24.2/esbuild.wasm',
+    }).catch(err => {
+      console.error('Failed to initialize esbuild:', err)
+    })
+
+    // Pre-fetch tokens in parallel
+    tokensReady = fetch('/_prev/tokens.json').then(r => r.json()).catch(() => null)
+
     async function initEsbuild() {
-      if (initialized) return
-      await esbuild.initialize({
-        wasmURL: 'https://unpkg.com/esbuild-wasm@0.24.2/esbuild.wasm',
-      })
-      initialized = true
+      await esbuildReady
     }
 
     async function bundle(config) {
@@ -76,16 +93,30 @@
         // Determine if entry exports default or needs wrapping
         const hasDefaultExport = /export\s+default/.test(entryFile.content)
 
+        // Wait for pre-fetched tokens
+        const tokens = await tokensReady
+
         const entryCode = hasDefaultExport ? `
           import React from 'react'
           import { createRoot } from 'react-dom/client'
+          import { setTokensConfig } from '@prev/jsx'
           import App from './${config.entry}'
 
+          // Inject pre-fetched tokens
+          const tokens = ${JSON.stringify(tokens)}
+          if (tokens) setTokensConfig(tokens)
+
           const root = createRoot(document.getElementById('root'))
           root.render(React.createElement(App))
         ` : `
           // Entry file doesn't export default, execute directly
-          import './${config.entry}'
+          import { setTokensConfig } from '@prev/jsx'
+
+          // Inject pre-fetched tokens
+          const tokens = ${JSON.stringify(tokens)}
+          if (tokens) setTokensConfig(tokens)
+
+          import('./${config.entry}')
         `
 
         const result = await esbuild.build({
@@ -114,9 +145,20 @@
                 return { path: url, external: true }
               })
 
+              // Resolve @prev/jsx to pre-bundled primitives
+              build.onResolve({ filter: /^@prev\/jsx$/ }, args => {
+                return { path: `${window.location.origin}/_prev/jsx.js`, external: true }
+              })
+
+              // Resolve @prev/components/* to pre-bundled components
+              build.onResolve({ filter: /^@prev\/components\/(.+)$/ }, args => {
+                const componentName = args.path.replace('@prev/components/', '')
+                return { path: `${window.location.origin}/_prev/components/${componentName}.js`, external: true }
+              })
+
               // Auto-resolve npm packages via esm.sh
               build.onResolve({ filter: /^[^./]/ }, args => {
-                if (args.path.startsWith('https://')) return
+                if (args.path.startsWith('https://') || args.path.startsWith('/')) return
                 return { path: `https://esm.sh/${args.path}`, external: true }
               })
 

package/src/preview-runtime/vendors.ts

@@ -19,6 +19,15 @@ export async function buildVendorBundle(): Promise<VendorBundleResult> {
       import { createRoot } from 'react-dom/client'
       export { jsx, jsxs, Fragment } from 'react/jsx-runtime'
       export { React, ReactDOM, createRoot }
+      // Re-export React hooks as named exports (preview code imports them directly)
+      export {
+        useState, useEffect, useCallback, useMemo, useRef,
+        useContext, useReducer, useLayoutEffect, useInsertionEffect,
+        useTransition, useDeferredValue, useId, useSyncExternalStore,
+        useImperativeHandle, useDebugValue, memo, forwardRef,
+        createContext, createRef, lazy, Suspense, startTransition,
+        Children, cloneElement, isValidElement, createElement
+      } from 'react'
       export default React
     `