prev-cli 0.24.11 → 0.24.13

package/dist/preview-runtime/build-optimized.d.ts

@@ -0,0 +1,11 @@
+import type { PreviewConfig } from './types';
+export interface OptimizedBuildOptions {
+    vendorPath: string;
+}
+export interface OptimizedBuildResult {
+    success: boolean;
+    html: string;
+    css: string;
+    error?: string;
+}
+export declare function buildOptimizedPreview(config: PreviewConfig, options: OptimizedBuildOptions): Promise<OptimizedBuildResult>;

package/dist/preview-runtime/tailwind.d.ts

@@ -0,0 +1,11 @@
+export interface TailwindResult {
+    success: boolean;
+    css: string;
+    error?: string;
+}
+interface ContentFile {
+    path: string;
+    content: string;
+}
+export declare function compileTailwind(files: ContentFile[]): Promise<TailwindResult>;
+export {};

package/dist/preview-runtime/vendors.d.ts

@@ -0,0 +1,6 @@
+export interface VendorBundleResult {
+    success: boolean;
+    code: string;
+    error?: string;
+}
+export declare function buildVendorBundle(): Promise<VendorBundleResult>;

package/dist/vite/config-parser.d.ts

@@ -0,0 +1,13 @@
+import { type PreviewConfig, type FlowDefinition, type AtlasDefinition } from './preview-types';
+/**
+ * Parse a config.yaml or config.yml file and validate against schema
+ */
+export declare function parsePreviewConfig(filePath: string): Promise<PreviewConfig | null>;
+/**
+ * Parse a flow index.yaml file
+ */
+export declare function parseFlowDefinition(filePath: string): Promise<FlowDefinition | null>;
+/**
+ * Parse an atlas index.yaml file
+ */
+export declare function parseAtlasDefinition(filePath: string): Promise<AtlasDefinition | null>;

package/dist/vite/preview-types.d.ts

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+export type PreviewType = 'component' | 'screen' | 'flow' | 'atlas';
+export declare const configSchema: z.ZodObject<{
+    tags: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodPipe<z.ZodString, z.ZodTransform<string[], string>>]>>;
+    category: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+        draft: "draft";
+        stable: "stable";
+        deprecated: "deprecated";
+    }>>;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    order: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type PreviewConfig = z.infer<typeof configSchema>;
+export interface PreviewUnit {
+    type: PreviewType;
+    name: string;
+    path: string;
+    route: string;
+    config: PreviewConfig | null;
+    files: {
+        index: string;
+        states?: string[];
+        schema?: string;
+        docs?: string;
+    };
+}
+export interface FlowStep {
+    screen: string;
+    state?: string;
+    note?: string;
+    trigger?: string;
+    highlight?: string[];
+}
+export interface FlowDefinition {
+    name: string;
+    description?: string;
+    steps: FlowStep[];
+}
+export interface AtlasArea {
+    title: string;
+    description?: string;
+    parent?: string;
+    children?: string[];
+    access?: string;
+}
+export interface AtlasDefinition {
+    name: string;
+    description?: string;
+    hierarchy: {
+        root: string;
+        areas: Record<string, AtlasArea>;
+    };
+    routes?: Record<string, {
+        area: string;
+        screen: string;
+        guard?: string;
+    }>;
+    navigation?: Record<string, Array<{
+        area?: string;
+        icon?: string;
+        action?: string;
+    }>>;
+    relationships?: Array<{
+        from: string;
+        to: string;
+        type: string;
+    }>;
+}

package/dist/vite/previews.d.ts

@@ -1,4 +1,5 @@
 import type { PreviewFile, PreviewConfig } from '../preview-runtime/types';
+import type { PreviewUnit } from './preview-types';
 export interface Preview {
     name: string;
     route: string;
@@ -21,3 +22,8 @@ export declare function detectEntry(files: PreviewFile[]): string;
  * Build a PreviewConfig for WASM runtime
  */
 export declare function buildPreviewConfig(previewDir: string): Promise<PreviewConfig>;
+/**
+ * Scan previews with multi-type folder structure support
+ * Supports: components/, screens/, flows/, atlas/
+ */
+export declare function scanPreviewUnits(rootDir: string): Promise<PreviewUnit[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prev-cli",
-  "version": "0.24.11",
+  "version": "0.24.13",
   "description": "Transform MDX directories into beautiful documentation websites",
   "type": "module",
   "license": "MIT",
@@ -65,7 +65,8 @@
     "remark-gfm": "^4.0.0",
     "tailwind-merge": "^2.5.0",
     "tailwindcss": "^4.0.0",
-    "vite": "npm:rolldown-vite@^7.3.1"
+    "vite": "npm:rolldown-vite@^7.3.1",
+    "zod": "^4.3.5"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",

package/src/preview-runtime/build-optimized.test.ts

@@ -0,0 +1,47 @@
+import { test, expect } from 'bun:test'
+import { buildOptimizedPreview } from './build-optimized'
+import type { PreviewConfig } from './types'
+
+// Tailwind CLI can be slow on first run
+const TAILWIND_TIMEOUT = 30000
+
+test('buildOptimizedPreview generates HTML with local vendor imports', async () => {
+  const config: PreviewConfig = {
+    files: [
+      {
+        path: 'index.tsx',
+        content: `export default function App() { return <div className="p-4">Hello</div> }`,
+        type: 'tsx',
+      },
+    ],
+    entry: 'index.tsx',
+    tailwind: true,
+  }
+
+  const result = await buildOptimizedPreview(config, { vendorPath: '../_vendors/runtime.js' })
+
+  expect(result.success).toBe(true)
+  expect(result.html).toContain('../_vendors/runtime.js')
+  expect(result.html).not.toContain('esm.sh')
+  expect(result.html).not.toContain('tailwindcss/browser')
+}, TAILWIND_TIMEOUT)
+
+test('buildOptimizedPreview includes compiled CSS', async () => {
+  const config: PreviewConfig = {
+    files: [
+      {
+        path: 'index.tsx',
+        content: `export default function App() { return <div className="flex items-center bg-red-500">Hello</div> }`,
+        type: 'tsx',
+      },
+    ],
+    entry: 'index.tsx',
+    tailwind: true,
+  }
+
+  const result = await buildOptimizedPreview(config, { vendorPath: '../_vendors/runtime.js' })
+
+  expect(result.success).toBe(true)
+  expect(result.css).toContain('flex')
+  expect(result.css).toContain('bg-red-500')
+}, TAILWIND_TIMEOUT)

package/src/preview-runtime/build-optimized.ts

@@ -0,0 +1,136 @@
+import { build } from 'esbuild'
+import type { PreviewConfig } from './types'
+import { compileTailwind } from './tailwind'
+
+export interface OptimizedBuildOptions {
+  vendorPath: string
+}
+
+export interface OptimizedBuildResult {
+  success: boolean
+  html: string
+  css: string
+  error?: string
+}
+
+export async function buildOptimizedPreview(
+  config: PreviewConfig,
+  options: OptimizedBuildOptions
+): Promise<OptimizedBuildResult> {
+  try {
+    const virtualFs: Record<string, { contents: string; loader: string }> = {}
+    for (const file of config.files) {
+      const ext = file.path.split('.').pop()?.toLowerCase()
+      const loader = ext === 'css' ? 'css' : ext === 'json' ? 'json' : ext || 'tsx'
+      virtualFs[file.path] = { contents: file.content, loader }
+    }
+
+    const entryFile = config.files.find(f => f.path === config.entry)
+    if (!entryFile) {
+      return { success: false, html: '', css: '', error: `Entry file not found: ${config.entry}` }
+    }
+
+    const hasDefaultExport = /export\s+default/.test(entryFile.content)
+    const userCssCollected: string[] = []
+
+    const entryCode = hasDefaultExport
+      ? `
+      import React, { createRoot } from '${options.vendorPath}'
+      import App from './${config.entry}'
+      const root = createRoot(document.getElementById('root'))
+      root.render(React.createElement(App))
+    `
+      : `import './${config.entry}'`
+
+    const result = await build({
+      stdin: { contents: entryCode, loader: 'tsx', resolveDir: '/' },
+      bundle: true,
+      write: false,
+      format: 'esm',
+      jsx: 'automatic',
+      jsxImportSource: 'react',
+      target: 'es2020',
+      minify: true,
+      plugins: [
+        {
+          name: 'optimized-preview',
+          setup(build) {
+            // External: vendor runtime
+            build.onResolve(
+              { filter: new RegExp(options.vendorPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')) },
+              args => {
+                return { path: args.path, external: true }
+              }
+            )
+
+            // External: React (map to vendor bundle)
+            build.onResolve({ filter: /^react(-dom)?(\/.*)?$/ }, () => {
+              return { path: options.vendorPath, external: true }
+            })
+
+            // Resolve relative imports
+            build.onResolve({ filter: /^\./ }, args => {
+              let resolved = args.path.replace(/^\.\//, '')
+              if (!resolved.includes('.')) {
+                for (const ext of ['.tsx', '.ts', '.jsx', '.js', '.css']) {
+                  if (virtualFs[resolved + ext]) {
+                    resolved = resolved + ext
+                    break
+                  }
+                }
+              }
+              return { path: resolved, namespace: 'virtual' }
+            })
+
+            // Load from virtual FS
+            build.onLoad({ filter: /.*/, namespace: 'virtual' }, args => {
+              const file = virtualFs[args.path]
+              if (file) {
+                if (file.loader === 'css') {
+                  userCssCollected.push(file.contents)
+                  return { contents: '', loader: 'js' }
+                }
+                return { contents: file.contents, loader: file.loader as any }
+              }
+              return { contents: '', loader: 'empty' }
+            })
+          },
+        },
+      ],
+    })
+
+    const jsFile = result.outputFiles?.find(f => f.path.endsWith('.js')) || result.outputFiles?.[0]
+    const jsCode = jsFile?.text || ''
+
+    let css = ''
+    if (config.tailwind) {
+      const tailwindResult = await compileTailwind(
+        config.files.map(f => ({ path: f.path, content: f.content }))
+      )
+      if (tailwindResult.success) css = tailwindResult.css
+    }
+
+    const userCss = userCssCollected.join('\n')
+    const allCss = css + '\n' + userCss
+
+    const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Preview</title>
+  <style>${allCss}</style>
+  <style>body { margin: 0; } #root { min-height: 100vh; }</style>
+</head>
+<body>
+  <div id="root"></div>
+  <script type="module" src="${options.vendorPath}"></script>
+  <script type="module">${jsCode}</script>
+</body>
+</html>`
+
+    return { success: true, html, css: allCss }
+  } catch (err) {
+    return { success: false, html: '', css: '', error: err instanceof Error ? err.message : String(err) }
+  }
+}

package/src/preview-runtime/tailwind.test.ts

@@ -0,0 +1,30 @@
+import { test, expect } from 'bun:test'
+import { compileTailwind } from './tailwind'
+
+test('compileTailwind extracts used classes from content', async () => {
+  const content = `
+    export default function App() {
+      return <div className="flex items-center p-4 bg-blue-500">Hello</div>
+    }
+  `
+
+  const result = await compileTailwind([{ path: 'App.tsx', content }])
+
+  expect(result.success).toBe(true)
+  expect(result.css).toBeDefined()
+  expect(result.css).toContain('flex')
+  expect(result.css).toContain('items-center')
+  expect(result.css).toContain('bg-blue-500')
+})
+
+test('compileTailwind returns empty CSS for no Tailwind classes', async () => {
+  const content = `
+    export default function App() {
+      return <div style={{ color: 'red' }}>Hello</div>
+    }
+  `
+
+  const result = await compileTailwind([{ path: 'App.tsx', content }])
+
+  expect(result.success).toBe(true)
+})

package/src/preview-runtime/tailwind.ts

@@ -0,0 +1,64 @@
+import { $ } from 'bun'
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'fs'
+import { join, dirname } from 'path'
+import { tmpdir } from 'os'
+
+export interface TailwindResult {
+  success: boolean
+  css: string
+  error?: string
+}
+
+interface ContentFile {
+  path: string
+  content: string
+}
+
+export async function compileTailwind(files: ContentFile[]): Promise<TailwindResult> {
+  const tempDir = mkdtempSync(join(tmpdir(), 'prev-tailwind-'))
+
+  try {
+    // Write content files (create parent dirs for nested paths)
+    for (const file of files) {
+      const filePath = join(tempDir, file.path)
+      const parentDir = dirname(filePath)
+      mkdirSync(parentDir, { recursive: true })
+      writeFileSync(filePath, file.content)
+    }
+
+    // Create Tailwind config - use .cjs for compatibility
+    const configContent = `
+      module.exports = {
+        content: [${JSON.stringify(tempDir + '/**/*.{tsx,jsx,ts,js,html}')}],
+      }
+    `
+    const configPath = join(tempDir, 'tailwind.config.cjs')
+    writeFileSync(configPath, configContent)
+
+    // Create input CSS
+    const inputCss = `
+      @tailwind base;
+      @tailwind components;
+      @tailwind utilities;
+    `
+    const inputPath = join(tempDir, 'input.css')
+    writeFileSync(inputPath, inputCss)
+
+    const outputPath = join(tempDir, 'output.css')
+
+    // Run Tailwind CLI
+    await $`bunx tailwindcss -c ${configPath} -i ${inputPath} -o ${outputPath} --minify`.quiet()
+
+    const css = readFileSync(outputPath, 'utf-8')
+
+    return { success: true, css }
+  } catch (err) {
+    return {
+      success: false,
+      css: '',
+      error: err instanceof Error ? err.message : String(err),
+    }
+  } finally {
+    rmSync(tempDir, { recursive: true, force: true })
+  }
+}

package/src/preview-runtime/vendors.test.ts

@@ -0,0 +1,15 @@
+import { test, expect } from 'bun:test'
+import { buildVendorBundle } from './vendors'
+
+test('buildVendorBundle creates runtime.js with React', async () => {
+  const result = await buildVendorBundle()
+  expect(result.success).toBe(true)
+  expect(result.code).toBeDefined()
+  expect(result.code).toContain('createElement')
+  expect(result.code).toContain('createRoot')
+})
+
+test('buildVendorBundle output is valid ESM', async () => {
+  const result = await buildVendorBundle()
+  expect(result.code).toContain('export')
+})

package/src/preview-runtime/vendors.ts

@@ -0,0 +1,52 @@
+import { build } from 'esbuild'
+import { dirname } from 'path'
+import { fileURLToPath } from 'url'
+
+// Resolve from CLI's location, not user's project (React is our dependency)
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+export interface VendorBundleResult {
+  success: boolean
+  code: string
+  error?: string
+}
+
+export async function buildVendorBundle(): Promise<VendorBundleResult> {
+  try {
+    const entryCode = `
+      import * as React from 'react'
+      import * as ReactDOM from 'react-dom'
+      import { createRoot } from 'react-dom/client'
+      export { jsx, jsxs, Fragment } from 'react/jsx-runtime'
+      export { React, ReactDOM, createRoot }
+      export default React
+    `
+
+    const result = await build({
+      stdin: {
+        contents: entryCode,
+        loader: 'ts',
+        resolveDir: __dirname, // Resolve React from CLI's node_modules
+      },
+      bundle: true,
+      write: false,
+      format: 'esm',
+      target: 'es2020',
+      minify: true,
+    })
+
+    // Select JS output file explicitly (in case sourcemaps are added later)
+    const jsFile = result.outputFiles?.find(f => f.path.endsWith('.js')) || result.outputFiles?.[0]
+    if (!jsFile) {
+      return { success: false, code: '', error: 'No output generated' }
+    }
+
+    return { success: true, code: jsFile.text }
+  } catch (err) {
+    return {
+      success: false,
+      code: '',
+      error: err instanceof Error ? err.message : String(err),
+    }
+  }
+}