prev-cli 0.24.15 → 0.24.16

package/dist/jsx/vnode.d.ts

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+import { PrimitiveType } from './schemas/primitives';
+export interface VNodeType {
+    id: string;
+    type: z.infer<typeof PrimitiveType>;
+    props: Record<string, unknown>;
+    children?: VNodeType[];
+    componentName?: string;
+}
+export declare const VNode: z.ZodType<VNodeType>;
+/**
+ * Render context for isolated ID generation.
+ * Each render should use its own context to avoid ID conflicts
+ * when multiple renders execute concurrently.
+ */
+export interface RenderContext {
+    /** Generate unique ID for a node type */
+    nextId: (type: string) => string;
+}
+/**
+ * Create a new render context with isolated ID counter.
+ * Use this for each render to ensure concurrent safety.
+ */
+export declare function createRenderContext(): RenderContext;
+/**
+ * Reset ID counter - call at start of each render.
+ * @deprecated Use createRenderContext() for concurrent safety
+ */
+export declare function resetIdCounter(): void;
+/**
+ * Get the current global render context.
+ * @internal
+ */
+export declare function getGlobalContext(): RenderContext;
+/**
+ * Create an immutable VNode
+ * @param type - Node type (col, row, text, etc.)
+ * @param props - Node properties
+ * @param children - Child nodes
+ * @param context - Optional render context for ID generation (uses global if not provided)
+ */
+export declare function createVNode(type: VNodeType['type'], props: Record<string, unknown>, children?: VNodeType[], context?: RenderContext): VNodeType;
+/**
+ * Create a component VNode (wraps rendered content)
+ * @param componentName - Name of the component
+ * @param props - Component properties
+ * @param children - Child nodes
+ * @param context - Optional render context for ID generation (uses global if not provided)
+ */
+export declare function createComponentVNode(componentName: string, props: Record<string, unknown>, children?: VNodeType[], context?: RenderContext): VNodeType;
+/**
+ * Normalize children to array, converting strings/numbers to Text nodes
+ */
+export declare function normalizeChildren(children: unknown): VNodeType[];
+/**
+ * Check structural equality of two VNodes (ignores IDs)
+ */
+export declare function vnodeEquals(a: VNodeType, b: VNodeType): boolean;

package/dist/migrate.d.ts

@@ -0,0 +1,18 @@
+export interface MigrationResult {
+    success: boolean;
+    migrated: number;
+    skipped: number;
+    errors: MigrationError[];
+}
+export interface MigrationError {
+    file: string;
+    message: string;
+}
+/**
+ * Migrate all preview configs from v1 to v2 format
+ */
+export declare function migrateConfigs(rootDir?: string): Promise<MigrationResult>;
+/**
+ * Format migration result for CLI output
+ */
+export declare function formatMigrationResult(result: MigrationResult): string;

package/dist/primitives/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './parser';
+export * from './template-parser';
+export * from './template-renderer';
+export * from './migrate';

package/dist/primitives/migrate.d.ts

@@ -0,0 +1,25 @@
+import type { Template, Slots } from './types';
+/**
+ * Migration result
+ */
+export interface MigrationResult {
+    success: boolean;
+    template?: Template;
+    slots?: Slots;
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * Migrate a layoutByRenderer tree to template format
+ *
+ * Converts:
+ * - Stack/HStack/VStack to $col/$row
+ * - Box/Container to $box
+ * - ComponentRef to component refs
+ * - Slot to $slot
+ */
+export declare function migrateLayout(layout: unknown, _rendererName?: string): MigrationResult;
+/**
+ * Migrate all layouts from a screen config
+ */
+export declare function migrateScreenConfig(layoutByRenderer: Record<string, unknown>): MigrationResult;

package/dist/primitives/parser.d.ts

@@ -0,0 +1,32 @@
+import type { Primitive, PrimitiveType } from './types';
+export interface ParseError {
+    message: string;
+    position?: number;
+}
+export interface ParseResultSuccess<T extends Primitive = Primitive> {
+    success: true;
+    primitive: T;
+    raw: string;
+}
+export interface ParseResultFailure {
+    success: false;
+    error: ParseError;
+    raw: string;
+}
+export type ParseResult<T extends Primitive = Primitive> = ParseResultSuccess<T> | ParseResultFailure;
+/**
+ * Parse a primitive string like "$col(gap:lg align:center)"
+ */
+export declare function parsePrimitive(input: string): ParseResult;
+/**
+ * Check if a value is quoted (literal) vs bare (prop reference)
+ */
+export declare function isQuoted(value: string): boolean;
+/**
+ * Extract primitive type from a primitive string
+ */
+export declare function getPrimitiveType(input: string): PrimitiveType | null;
+/**
+ * Check if a string is a valid primitive syntax
+ */
+export declare function isValidPrimitiveSyntax(input: string): boolean;

package/dist/primitives/template-parser.d.ts

@@ -0,0 +1,33 @@
+import { type TemplateNode, type Template } from './types';
+export interface TemplateParseError {
+    path: string;
+    message: string;
+}
+export interface TemplateParseResult {
+    valid: boolean;
+    errors: TemplateParseError[];
+    warnings: TemplateParseError[];
+}
+/**
+ * Validate a template structure
+ */
+export declare function validateTemplate(template: unknown): TemplateParseResult;
+/**
+ * Validate slots structure
+ */
+export declare function validateSlots(slots: unknown, definedStates?: string[]): TemplateParseResult;
+/**
+ * Extract all component refs from a template
+ */
+export declare function extractRefs(template: unknown): string[];
+/**
+ * Extract all slot names from a template
+ */
+export declare function extractSlotNames(template: unknown): string[];
+/**
+ * Flatten a template into a list of nodes with paths
+ */
+export declare function flattenTemplate(template: Template): Array<{
+    path: string;
+    node: TemplateNode;
+}>;

package/dist/primitives/template-renderer.d.ts

@@ -0,0 +1,19 @@
+import { type Template, type Slots } from './types';
+export interface RenderContext {
+    /** Current state for slot resolution */
+    state?: string;
+    /** Slots mapping for state-dependent content */
+    slots?: Slots;
+    /** Props for component rendering */
+    props?: Record<string, unknown>;
+    /** Callback to render component refs */
+    renderRef?: (ref: string) => string;
+}
+/**
+ * Render a template to HTML
+ */
+export declare function renderTemplate(template: Template, context?: RenderContext): string;
+/**
+ * Generate CSS custom properties for design tokens (shadcn-compatible)
+ */
+export declare function generateTokenCSS(): string;

package/dist/primitives/types.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Design token types for consistent spacing, sizing, and styling
+ * Using shadcn/ui-compatible naming conventions
+ */
+export type SpacingToken = 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+export type AlignToken = 'start' | 'center' | 'end' | 'stretch' | 'between';
+export type BackgroundToken = 'transparent' | 'background' | 'card' | 'primary' | 'secondary' | 'muted' | 'accent' | 'destructive' | 'input';
+export type RadiusToken = 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full';
+export type ColorToken = 'foreground' | 'card-foreground' | 'primary' | 'primary-foreground' | 'secondary' | 'secondary-foreground' | 'muted' | 'muted-foreground' | 'accent' | 'accent-foreground' | 'destructive' | 'destructive-foreground' | 'border' | 'ring';
+export type SizeToken = 'xs' | 'sm' | 'base' | 'lg' | 'xl' | '2xl';
+export type WeightToken = 'normal' | 'medium' | 'semibold' | 'bold';
+export type FitToken = 'cover' | 'contain' | 'fill';
+/**
+ * All primitive type names
+ */
+export type PrimitiveType = '$col' | '$row' | '$box' | '$spacer' | '$slot' | '$text' | '$icon' | '$image';
+/**
+ * Layout primitive: $col - Vertical stack
+ */
+export interface ColPrimitive {
+    type: '$col';
+    gap?: SpacingToken;
+    align?: AlignToken;
+    padding?: SpacingToken;
+}
+/**
+ * Layout primitive: $row - Horizontal stack
+ */
+export interface RowPrimitive {
+    type: '$row';
+    gap?: SpacingToken;
+    align?: AlignToken;
+    padding?: SpacingToken;
+}
+/**
+ * Layout primitive: $box - Container with styling
+ */
+export interface BoxPrimitive {
+    type: '$box';
+    padding?: SpacingToken;
+    bg?: BackgroundToken;
+    radius?: RadiusToken;
+}
+/**
+ * Layout primitive: $spacer - Whitespace
+ */
+export interface SpacerPrimitive {
+    type: '$spacer';
+    size?: SpacingToken;
+}
+/**
+ * Layout primitive: $slot - State-dependent placeholder
+ */
+export interface SlotPrimitive {
+    type: '$slot';
+    name: string;
+}
+/**
+ * Content primitive: $text - Text content
+ */
+export interface TextPrimitive {
+    type: '$text';
+    content: string;
+    size?: SizeToken;
+    weight?: WeightToken;
+    color?: ColorToken;
+}
+/**
+ * Content primitive: $icon - Icon
+ */
+export interface IconPrimitive {
+    type: '$icon';
+    name: string;
+    size?: SizeToken;
+    color?: ColorToken;
+}
+/**
+ * Content primitive: $image - Image
+ */
+export interface ImagePrimitive {
+    type: '$image';
+    src: string;
+    alt?: string;
+    fit?: FitToken;
+}
+/**
+ * Union of all primitives
+ */
+export type Primitive = ColPrimitive | RowPrimitive | BoxPrimitive | SpacerPrimitive | SlotPrimitive | TextPrimitive | IconPrimitive | ImagePrimitive;
+/**
+ * Parsed primitive with original string
+ */
+export interface ParsedPrimitive<T extends Primitive = Primitive> {
+    primitive: T;
+    raw: string;
+}
+/**
+ * Template node - container or leaf
+ */
+export interface TemplateContainerNode {
+    type: string;
+    children?: Record<string, TemplateNode>;
+}
+export interface TemplateLeafNode {
+    value: string;
+}
+export type TemplateNode = TemplateContainerNode | string;
+/**
+ * Template root structure
+ */
+export interface Template {
+    root: TemplateNode;
+}
+/**
+ * Slots mapping: state name -> content ref
+ */
+export type Slots = Record<string, Record<string, string>>;
+/**
+ * Screen v2 config with template and slots
+ */
+export interface ScreenV2Config {
+    kind: 'screen';
+    id: string;
+    title: string;
+    schemaVersion: '2.0';
+    states?: Record<string, {
+        description?: string;
+    }>;
+    template: Template;
+    slots?: Slots;
+    layoutByRenderer?: Record<string, unknown>;
+}
+/**
+ * Component v2 config with props and template
+ */
+export interface ComponentV2Config {
+    kind: 'component';
+    id: string;
+    title: string;
+    schemaVersion: '2.0';
+    props?: Record<string, {
+        type?: string;
+        required?: boolean;
+        default?: unknown;
+        values?: unknown[];
+    }>;
+    template?: Template;
+}
+/**
+ * Check if a string is a primitive (starts with $)
+ */
+export declare function isPrimitive(value: string): boolean;
+/**
+ * Check if a string is a component/screen/flow ref (contains /)
+ */
+export declare function isRef(value: string): boolean;
+/**
+ * Check if a template node is a container (has type and children)
+ */
+export declare function isContainerNode(node: unknown): node is TemplateContainerNode;
+/**
+ * Check if a template node is a leaf (string value)
+ */
+export declare function isLeafNode(node: unknown): node is string;

package/dist/renderers/html/index.d.ts

@@ -0,0 +1,6 @@
+import type { RendererAdapter } from '../types';
+/**
+ * HTML renderer adapter
+ * Renders static HTML without JavaScript hydration
+ */
+export declare const HTMLAdapter: RendererAdapter;

package/dist/renderers/index.d.ts

@@ -0,0 +1,5 @@
+export { registerAdapter, getAdapter, listAdapters, getAllAdapters, isValidRendererKey, getLayoutSchema, clearAdapters, initializeAdapters, validateRendererKeys, } from './registry';
+export { renderPreview, renderPreviews, selectAdapter, ensureAdaptersInitialized, supportsHMR, type RenderOptions, type RenderResult, } from './render';
+export type { RendererAdapter, RenderOutput, DevServer, PreviewKind, PreviewRef, BaseConfig, ComponentConfig, ScreenConfig, FlowConfig, AtlasConfig, PreviewConfig, FlowStep, FlowTransition, AtlasNode, AtlasRelationship, } from './types';
+export { ReactAdapter } from './react';
+export { HTMLAdapter } from './html';

package/dist/renderers/react/index.d.ts

@@ -0,0 +1,6 @@
+import type { RendererAdapter } from '../types';
+/**
+ * React renderer adapter
+ * Renders React components to HTML with hydration support
+ */
+export declare const ReactAdapter: RendererAdapter;

package/dist/renderers/registry.d.ts

@@ -0,0 +1,41 @@
+import type { JSONSchema7 } from 'json-schema';
+import type { RendererAdapter } from './types';
+/**
+ * Register a renderer adapter
+ * @throws Error if adapter with same name already registered
+ */
+export declare function registerAdapter(adapter: RendererAdapter): void;
+/**
+ * Get a renderer adapter by name
+ */
+export declare function getAdapter(name: string): RendererAdapter | undefined;
+/**
+ * List all registered adapter names
+ */
+export declare function listAdapters(): string[];
+/**
+ * List all registered adapters
+ */
+export declare function getAllAdapters(): RendererAdapter[];
+/**
+ * Check if a renderer key matches a registered adapter
+ */
+export declare function isValidRendererKey(key: string): boolean;
+/**
+ * Get the layout schema for a specific renderer
+ */
+export declare function getLayoutSchema(name: string): JSONSchema7 | undefined;
+/**
+ * Clear all registered adapters (for testing)
+ */
+export declare function clearAdapters(): void;
+/**
+ * Initialize default adapters
+ * Called at startup to register built-in adapters
+ */
+export declare function initializeAdapters(): Promise<void>;
+/**
+ * Validate that all layoutByRenderer keys have registered adapters
+ * @returns Array of unknown renderer keys
+ */
+export declare function validateRendererKeys(keys: string[]): string[];

package/dist/renderers/render.d.ts

@@ -0,0 +1,35 @@
+import type { PreviewConfig, RenderOutput, RendererAdapter } from './types';
+export interface RenderOptions {
+    /** Specific renderer to use (defaults to first available in layoutByRenderer) */
+    renderer?: string;
+    /** State for screen rendering */
+    state?: string;
+    /** Step for flow rendering */
+    step?: string;
+}
+export interface RenderResult {
+    success: boolean;
+    output?: RenderOutput;
+    error?: string;
+    renderer?: string;
+}
+/**
+ * Ensure adapters are initialized
+ */
+export declare function ensureAdaptersInitialized(): Promise<void>;
+/**
+ * Select the appropriate renderer adapter for a config
+ */
+export declare function selectAdapter(config: PreviewConfig, preferredRenderer?: string): RendererAdapter | null;
+/**
+ * Render a preview config using the appropriate adapter
+ */
+export declare function renderPreview(config: PreviewConfig, options?: RenderOptions): Promise<RenderResult>;
+/**
+ * Render multiple previews with the same adapter
+ */
+export declare function renderPreviews(configs: PreviewConfig[], options?: RenderOptions): Promise<Map<string, RenderResult>>;
+/**
+ * Check if a specific renderer supports HMR
+ */
+export declare function supportsHMR(rendererName?: string): Promise<boolean>;

package/dist/renderers/types.d.ts

@@ -0,0 +1,188 @@
+import type { JSONSchema7 } from 'json-schema';
+/**
+ * Preview type discriminator
+ */
+export type PreviewKind = 'component' | 'screen' | 'flow' | 'atlas';
+/**
+ * Reference to another preview unit
+ */
+export type PreviewRef = string | {
+    ref: string;
+    state?: string;
+    options?: Record<string, unknown>;
+};
+/**
+ * Base config shared by all preview types
+ */
+export interface BaseConfig {
+    kind: PreviewKind;
+    id: string;
+    title: string;
+    description?: string;
+    tags?: string[];
+    status?: 'draft' | 'stable' | 'deprecated';
+    schemaVersion: '1.0' | '2.0';
+}
+/**
+ * Template node - container or leaf
+ */
+export interface TemplateContainerNode {
+    type: string;
+    children?: Record<string, TemplateNode>;
+}
+export type TemplateNode = TemplateContainerNode | string;
+/**
+ * Template root structure
+ */
+export interface Template {
+    root: TemplateNode;
+}
+/**
+ * Slots mapping: slot name -> state name -> content ref
+ */
+export type Slots = Record<string, Record<string, string>>;
+/**
+ * Component config - defines reusable UI components
+ */
+export interface ComponentConfig extends BaseConfig {
+    kind: 'component';
+    props?: Record<string, {
+        type?: string;
+        required?: boolean;
+        default?: unknown;
+        values?: unknown[];
+        enum?: unknown[];
+    }>;
+    template?: Template;
+    slots?: Record<string, {
+        description?: string;
+    }>;
+}
+/**
+ * Screen config - defines full-page views with states
+ */
+export interface ScreenConfig extends BaseConfig {
+    kind: 'screen';
+    states?: Record<string, {
+        description?: string;
+    }>;
+    /** New: Renderer-agnostic template using primitives */
+    template?: Template;
+    /** New: State-dependent slot content mapping */
+    slots?: Slots;
+    /** Legacy: Layout definitions per renderer. Values can be arrays or objects per adapter schema. */
+    layoutByRenderer?: Record<string, unknown>;
+}
+/**
+ * Flow step definition
+ */
+export interface FlowStep {
+    id: string;
+    title: string;
+    screen: PreviewRef;
+}
+/**
+ * Flow transition definition
+ */
+export interface FlowTransition {
+    from: string;
+    to: string;
+    trigger: string;
+}
+/**
+ * Flow config - defines multi-step user journeys
+ */
+export interface FlowConfig extends BaseConfig {
+    kind: 'flow';
+    steps: FlowStep[];
+    transitions?: FlowTransition[];
+}
+/**
+ * Atlas node definition
+ */
+export interface AtlasNode {
+    id: string;
+    title: string;
+    ref?: PreviewRef;
+}
+/**
+ * Atlas relationship definition
+ */
+export interface AtlasRelationship {
+    from: string;
+    to: string;
+    type: string;
+}
+/**
+ * Atlas config - defines information architecture
+ */
+export interface AtlasConfig extends BaseConfig {
+    kind: 'atlas';
+    nodes: AtlasNode[];
+    relationships?: AtlasRelationship[];
+}
+/**
+ * Union of all config types
+ */
+export type PreviewConfig = ComponentConfig | ScreenConfig | FlowConfig | AtlasConfig;
+/**
+ * Output from rendering a preview
+ */
+export interface RenderOutput {
+    /** Generated HTML content */
+    html: string;
+    /** Optional CSS styles */
+    css?: string;
+    /** Optional JS asset path (e.g., "login.js"), build system handles bundling */
+    js?: string;
+}
+/**
+ * Dev server interface for HMR support
+ */
+export interface DevServer {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    readonly port: number;
+}
+/**
+ * Renderer adapter interface - implementations for React, HTML, Solid, etc.
+ *
+ * The adapter interface is intentionally thin. Bundling, asset management,
+ * and hydration are handled by the build system (Vite/esbuild), not the adapter.
+ */
+export interface RendererAdapter {
+    /**
+     * Adapter name - must match layoutByRenderer keys in configs
+     * @example "react", "html", "solid"
+     */
+    readonly name: string;
+    /**
+     * JSON Schema for validating this renderer's layout nodes
+     * Used by the validator to check layoutByRenderer subtrees
+     */
+    readonly layoutSchema: JSONSchema7;
+    /**
+     * Render an isolated component with props applied
+     */
+    renderComponent(config: ComponentConfig): RenderOutput;
+    /**
+     * Render a full screen layout in the specified state
+     */
+    renderScreen(config: ScreenConfig, state?: string): RenderOutput;
+    /**
+     * Render the current step's screen with navigation UI (prev/next)
+     */
+    renderFlow(config: FlowConfig, step?: string): RenderOutput;
+    /**
+     * Render a graph visualization with node thumbnails
+     */
+    renderAtlas(config: AtlasConfig): RenderOutput;
+    /**
+     * Whether this adapter supports Hot Module Replacement
+     */
+    supportsHMR(): boolean;
+    /**
+     * Create a dev server for HMR support (optional)
+     */
+    createDevServer?(port: number): DevServer;
+}

package/dist/tokens/defaults.d.ts

@@ -0,0 +1,2 @@
+import type { TokensConfig } from './resolver';
+export declare const DEFAULT_TOKENS: TokensConfig;