@zseven-w/pen-codegen 0.5.2 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zseven-w/pen-codegen",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Multi-platform code generators for OpenPencil designs",
   "type": "module",
   "exports": {
@@ -16,8 +16,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zseven-w/pen-types": "0.5.2",
-    "@zseven-w/pen-core": "0.5.2"
+    "@zseven-w/pen-types": "0.6.0",
+    "@zseven-w/pen-core": "0.6.0"
   },
   "devDependencies": {
     "typescript": "^5.7.2"

package/src/__tests__/utils.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from 'vitest'
+import { varOrLiteral, sanitizeName, nodeTreeToSummary } from '../utils'
+import type { PenNode } from '@zseven-w/pen-types'
+
+describe('varOrLiteral', () => {
+  it('returns CSS var() for variable references', () => {
+    expect(varOrLiteral('$primary-color')).toBe('var(--primary-color)')
+  })
+
+  it('returns raw value for non-variable strings', () => {
+    expect(varOrLiteral('#ff0000')).toBe('#ff0000')
+  })
+
+  it('handles variable names with spaces', () => {
+    expect(varOrLiteral('$Primary Color')).toBe('var(--primary-color)')
+  })
+})
+
+describe('sanitizeName', () => {
+  it('converts kebab-case to PascalCase', () => {
+    expect(sanitizeName('hero-section')).toBe('HeroSection')
+  })
+
+  it('converts space-separated to PascalCase', () => {
+    expect(sanitizeName('my cool component')).toBe('MyCoolComponent')
+  })
+
+  it('handles single word', () => {
+    expect(sanitizeName('navbar')).toBe('Navbar')
+  })
+
+  it('strips invalid characters', () => {
+    expect(sanitizeName('hello@world#123')).toBe('Helloworld123')
+  })
+})
+
+describe('nodeTreeToSummary', () => {
+  it('produces lightweight summary with node IDs', () => {
+    const nodes: PenNode[] = [
+      {
+        id: '1', type: 'frame', name: 'Header',
+        x: 0, y: 0, width: 1200, height: 80,
+        children: [
+          { id: '1-1', type: 'text', name: 'Title', x: 0, y: 0, width: 200, height: 24 } as PenNode,
+        ],
+      } as PenNode,
+    ]
+    const summary = nodeTreeToSummary(nodes)
+    expect(summary).toContain('[1]')
+    expect(summary).toContain('Header')
+    expect(summary).toContain('frame')
+    expect(summary).toContain('1200')
+    expect(summary).toContain('[1-1]')
+    expect(summary).toContain('Title')
+    expect(summary.length).toBeLessThan(500)
+  })
+
+  it('returns empty string for empty array', () => {
+    expect(nodeTreeToSummary([])).toBe('')
+  })
+})

package/src/codegen-types.ts

@@ -0,0 +1,112 @@
+import type { PenNode } from '@zseven-w/pen-types'
+
+// === Canonical framework type ===
+
+export type Framework = 'react' | 'vue' | 'svelte' | 'html' | 'flutter' | 'swiftui' | 'compose' | 'react-native'
+
+export const FRAMEWORKS: Framework[] = ['react', 'vue', 'svelte', 'html', 'flutter', 'swiftui', 'compose', 'react-native']
+
+// === Step 1 output: AI planner returns this (no node data, minimal tokens) ===
+
+export interface PlannedChunk {
+  id: string
+  name: string
+  nodeIds: string[]
+  role: string
+  suggestedComponentName: string
+  dependencies: string[]
+  exposedSlots?: string[]
+}
+
+export interface CodePlanFromAI {
+  chunks: PlannedChunk[]
+  sharedStyles: { name: string; description: string }[]
+  rootLayout: { direction: string; gap: number; responsive: boolean }
+}
+
+// === Runtime: hydrated with node data + execution order ===
+
+export interface ExecutableChunk extends PlannedChunk {
+  nodes: PenNode[]
+  order: number
+  depContracts: ChunkContract[]
+}
+
+export interface CodeExecutionPlan {
+  chunks: ExecutableChunk[]
+  sharedStyles: { name: string; description: string }[]
+  rootLayout: { direction: string; gap: number; responsive: boolean }
+}
+
+// === Chunk contract: structured metadata output from each chunk ===
+
+export interface ChunkContract {
+  chunkId: string
+  componentName: string
+  exportedProps: PropDef[]
+  slots: SlotDef[]
+  cssClasses: string[]
+  cssVariables: string[]
+  imports: ImportDef[]
+}
+
+export interface PropDef {
+  name: string
+  type: string
+  required: boolean
+}
+
+export interface SlotDef {
+  name: string
+  description: string
+}
+
+export interface ImportDef {
+  source: string
+  specifiers: string[]
+}
+
+// === Chunk generation output ===
+
+export interface ChunkResult {
+  chunkId: string
+  code: string
+  contract: ChunkContract
+}
+
+// === Progress events ===
+
+export type ChunkStatus = 'pending' | 'running' | 'done' | 'degraded' | 'failed' | 'skipped'
+
+export type CodeGenProgress =
+  | { step: 'planning'; status: 'running' | 'done' | 'failed'; plan?: CodePlanFromAI; error?: string }
+  | { step: 'chunk'; chunkId: string; name: string; status: ChunkStatus; result?: ChunkResult; error?: string }
+  | { step: 'assembly'; status: 'running' | 'done' | 'failed'; error?: string }
+  | { step: 'complete'; finalCode: string; degraded: boolean }
+  | { step: 'error'; message: string; chunkId?: string }
+
+// === Contract validation ===
+
+export interface ContractValidationResult {
+  valid: boolean
+  issues: string[]
+}
+
+export function validateContract(result: ChunkResult): ContractValidationResult {
+  const issues: string[] = []
+  const { contract, code } = result
+
+  // 1. componentName must be a valid PascalCase identifier (if provided)
+  if (contract.componentName && !/^[A-Z][a-zA-Z0-9]*$/.test(contract.componentName)) {
+    issues.push(`componentName "${contract.componentName}" is not a valid PascalCase identifier`)
+  }
+
+  // 2. componentName should appear in code (skip for SFC frameworks where name is implicit)
+  // Svelte/Vue SFC may have <script>, <template>, or just <style> with HTML
+  const isSFC = code.includes('<script') || code.includes('<template') || code.includes('<style')
+  if (contract.componentName && !isSFC && !code.includes(contract.componentName)) {
+    issues.push(`componentName "${contract.componentName}" not found in generated code`)
+  }
+
+  return { valid: issues.length === 0, issues }
+}

package/src/compose-generator.ts

@@ -721,6 +721,7 @@ function generateImageCompose(node: ImageNode, depth: number): string {
   return lines.join('\n')
 }
 
+/** @deprecated Use AI code generation pipeline instead. Will be removed in v1.0.0. */
 export function generateComposeCode(
   nodes: PenNode[],
   composableName = 'GeneratedDesign',
@@ -796,6 +797,7 @@ ${childLines}
 `
 }
 
+/** @deprecated Use AI code generation pipeline instead. Will be removed in v1.0.0. */
 export function generateComposeFromDocument(
   doc: PenDocument,
   activePageId?: string | null,

package/src/flutter-generator.ts

@@ -514,6 +514,7 @@ function getHelperClasses(nodes: PenNode[]): string {
   return helpers.join('\n\n')
 }
 
+/** @deprecated Use AI code generation pipeline instead. Will be removed in v1.0.0. */
 export function generateFlutterCode(
   nodes: PenNode[],
   widgetName = 'GeneratedDesign',
@@ -570,6 +571,7 @@ ${childWidgets.map((c) => c + ',').join('\n')}
 `
 }
 
+/** @deprecated Use AI code generation pipeline instead. Will be removed in v1.0.0. */
 export function generateFlutterFromDocument(
   doc: PenDocument,
   activePageId?: string | null,

package/src/html-generator.ts

@@ -350,6 +350,7 @@ function cssRulesToString(rules: CSSRule[]): string {
     .join('\n\n')
 }
 
+/** @deprecated Use AI code generation pipeline instead. Will be removed in v1.0.0. */
 export function generateHTMLCode(nodes: PenNode[]): { html: string; css: string } {
   resetClassCounter()
   const rules: CSSRule[] = []
@@ -388,6 +389,7 @@ export function generateHTMLCode(nodes: PenNode[]): { html: string; css: string
   return { html, css }
 }
 
+/** @deprecated Use AI code generation pipeline instead. Will be removed in v1.0.0. */
 export function generateHTMLFromDocument(doc: PenDocument, activePageId?: string | null): { html: string; css: string } {
   const children = activePageId !== undefined
     ? getActivePageChildren(doc, activePageId)

package/src/index.ts

@@ -24,3 +24,24 @@ export { generateComposeCode, generateComposeFromDocument } from './compose-gene
 
 // React Native
 export { generateReactNativeCode, generateReactNativeFromDocument } from './react-native-generator.js'
+
+// Utilities
+export { varOrLiteral, sanitizeName, nodeTreeToSummary, isVariableRef } from './utils.js'
+
+// Types
+export type {
+  Framework,
+  PlannedChunk,
+  CodePlanFromAI,
+  ExecutableChunk,
+  CodeExecutionPlan,
+  ChunkContract,
+  PropDef,
+  SlotDef,
+  ImportDef,
+  ChunkResult,
+  ChunkStatus,
+  CodeGenProgress,
+  ContractValidationResult,
+} from './codegen-types.js'
+export { FRAMEWORKS, validateContract } from './codegen-types.js'

package/src/react-generator.ts

@@ -355,6 +355,7 @@ function escapeJSX(text: string): string {
     .replace(/}/g, '}')
 }
 
+/** @deprecated Use AI code generation pipeline instead. Will be removed in v1.0.0. */
 export function generateReactCode(
   nodes: PenNode[],
   componentName = 'GeneratedDesign',
@@ -393,6 +394,7 @@ ${childrenJSX}
 `
 }
 
+/** @deprecated Use AI code generation pipeline instead. Will be removed in v1.0.0. */
 export function generateReactFromDocument(doc: PenDocument, activePageId?: string | null): string {
   const children = activePageId !== undefined
     ? getActivePageChildren(doc, activePageId)

package/src/react-native-generator.ts

@@ -453,6 +453,7 @@ function polygonPoints(sides: number, w: number, h: number): string {
   return points.join(' ')
 }
 
+/** @deprecated Use AI code generation pipeline instead. Will be removed in v1.0.0. */
 export function generateReactNativeCode(
   nodes: PenNode[],
   componentName = 'GeneratedDesign',
@@ -558,6 +559,7 @@ function hasNodeType(nodes: PenNode[], type: string): boolean {
   return false
 }
 
+/** @deprecated Use AI code generation pipeline instead. Will be removed in v1.0.0. */
 export function generateReactNativeFromDocument(
   doc: PenDocument,
   activePageId?: string | null,

package/src/svelte-generator.ts

@@ -258,6 +258,7 @@ function cssRulesToString(rules: CSSRule[]): string {
 // Public API
 // ---------------------------------------------------------------------------
 
+/** @deprecated Use AI code generation pipeline instead. Will be removed in v1.0.0. */
 export function generateSvelteCode(nodes: PenNode[]): string {
   resetClassCounter()
   const rules: CSSRule[] = []
@@ -290,6 +291,7 @@ ${css}
 `
 }
 
+/** @deprecated Use AI code generation pipeline instead. Will be removed in v1.0.0. */
 export function generateSvelteFromDocument(doc: PenDocument, activePageId?: string | null): string {
   const children = activePageId !== undefined ? getActivePageChildren(doc, activePageId) : doc.children
   return generateSvelteCode(children)

package/src/swiftui-generator.ts

@@ -669,6 +669,7 @@ function generateImageSwiftUI(node: ImageNode, depth: number): string {
   return renderWithModifiers(pad, `Image("${escapedSrc}")`, modifiers)
 }
 
+/** @deprecated Use AI code generation pipeline instead. Will be removed in v1.0.0. */
 export function generateSwiftUICode(
   nodes: PenNode[],
   viewName = 'GeneratedView',
@@ -743,6 +744,7 @@ ${childLines}
 `
 }
 
+/** @deprecated Use AI code generation pipeline instead. Will be removed in v1.0.0. */
 export function generateSwiftUIFromDocument(
   doc: PenDocument,
   activePageId?: string | null,

package/src/utils.ts

@@ -0,0 +1,41 @@
+import type { PenNode } from '@zseven-w/pen-types'
+import { isVariableRef } from '@zseven-w/pen-core'
+import { variableNameToCSS } from './css-variables-generator.js'
+
+// Re-export for convenience
+export { variableNameToCSS } from './css-variables-generator.js'
+export { isVariableRef } from '@zseven-w/pen-core'
+
+export function varOrLiteral(value: string): string {
+  if (isVariableRef(value)) {
+    return `var(${variableNameToCSS(value.slice(1))})`
+  }
+  return value
+}
+
+export function sanitizeName(name: string): string {
+  return name
+    .replace(/[^a-zA-Z0-9\s-_]/g, '')
+    .split(/[\s\-_]+/)
+    .filter(Boolean)
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+    .join('')
+}
+
+export function nodeTreeToSummary(nodes: PenNode[], depth: number = 0): string {
+  if (nodes.length === 0) return ''
+
+  const indent = '  '.repeat(depth)
+  return nodes.map(node => {
+    const n = node as unknown as Record<string, unknown>
+    const dims = `${n.width ?? '?'}x${n.height ?? '?'}`
+    const childCount = (n.children as PenNode[] | undefined)?.length ?? 0
+    const role = n.role ? ` [${n.role}]` : ''
+    const line = `${indent}- [${node.id}] ${node.type} "${node.name ?? ''}" (${dims})${role}${childCount > 0 ? ` [${childCount} children]` : ''}`
+    const children = n.children as PenNode[] | undefined
+    if (children && children.length > 0) {
+      return line + '\n' + nodeTreeToSummary(children, depth + 1)
+    }
+    return line
+  }).join('\n')
+}

package/src/vue-generator.ts

@@ -264,6 +264,7 @@ function cssRulesToString(rules: CSSRule[]): string {
 // Public API
 // ---------------------------------------------------------------------------
 
+/** @deprecated Use AI code generation pipeline instead. Will be removed in v1.0.0. */
 export function generateVueCode(nodes: PenNode[], componentName = 'GeneratedDesign'): string {
   resetClassCounter()
   const rules: CSSRule[] = []
@@ -302,6 +303,7 @@ ${css}
 `
 }
 
+/** @deprecated Use AI code generation pipeline instead. Will be removed in v1.0.0. */
 export function generateVueFromDocument(doc: PenDocument, activePageId?: string | null): string {
   const children = activePageId !== undefined ? getActivePageChildren(doc, activePageId) : doc.children
   return generateVueCode(children)