@zseven-w/pen-core 0.5.2 → 0.7.0

package/README.md

@@ -23,16 +23,16 @@ import {
   updateNodeInTree,
   deepCloneNode,
   flattenNodes,
-} from '@zseven-w/pen-core'
+} from '@zseven-w/pen-core';
 
-const doc = createEmptyDocument()
-const node = findNodeInTree(doc.children, 'node-id')
+const doc = createEmptyDocument();
+const node = findNodeInTree(doc.children, 'node-id');
 ```
 
 ### Multi-Page Support
 
 ```ts
-import { getActivePage, getActivePageChildren, migrateToPages } from '@zseven-w/pen-core'
+import { getActivePage, getActivePageChildren, migrateToPages } from '@zseven-w/pen-core';
 ```
 
 ### Layout Engine
@@ -40,7 +40,12 @@ import { getActivePage, getActivePageChildren, migrateToPages } from '@zseven-w/
 Automatic layout computation with auto-sizing, padding, and gap support:
 
 ```ts
-import { inferLayout, computeLayoutPositions, fitContentWidth, fitContentHeight } from '@zseven-w/pen-core'
+import {
+  inferLayout,
+  computeLayoutPositions,
+  fitContentWidth,
+  fitContentHeight,
+} from '@zseven-w/pen-core';
 ```
 
 ### Design Variables
@@ -48,7 +53,11 @@ import { inferLayout, computeLayoutPositions, fitContentWidth, fitContentHeight
 Resolve `$variable` references against theme axes:
 
 ```ts
-import { resolveVariableRef, resolveNodeForCanvas, replaceVariableRefsInTree } from '@zseven-w/pen-core'
+import {
+  resolveVariableRef,
+  resolveNodeForCanvas,
+  replaceVariableRefsInTree,
+} from '@zseven-w/pen-core';
 ```
 
 ### Boolean Path Operations
@@ -56,7 +65,7 @@ import { resolveVariableRef, resolveNodeForCanvas, replaceVariableRefsInTree } f
 Union, subtract, intersect, and exclude paths via Paper.js:
 
 ```ts
-import { executeBooleanOp, BooleanOpType } from '@zseven-w/pen-core'
+import { executeBooleanOp, BooleanOpType } from '@zseven-w/pen-core';
 ```
 
 ### Text Measurement
@@ -64,7 +73,7 @@ import { executeBooleanOp, BooleanOpType } from '@zseven-w/pen-core'
 Estimate text dimensions for layout without a browser:
 
 ```ts
-import { estimateTextWidth, estimateTextHeight } from '@zseven-w/pen-core'
+import { estimateTextWidth, estimateTextHeight } from '@zseven-w/pen-core';
 ```
 
 ### Document Normalization
@@ -72,7 +81,7 @@ import { estimateTextWidth, estimateTextHeight } from '@zseven-w/pen-core'
 Sanitize and fix documents imported from external sources:
 
 ```ts
-import { normalizePenDocument } from '@zseven-w/pen-core'
+import { normalizePenDocument } from '@zseven-w/pen-core';
 ```
 
 ## License

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@zseven-w/pen-core",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "description": "Core document operations, tree utils, variables, layout engine for OpenPencil",
+  "files": [
+    "src"
+  ],
   "type": "module",
   "exports": {
     ".": {
@@ -9,14 +12,11 @@
       "import": "./src/index.ts"
     }
   },
-  "files": [
-    "src"
-  ],
   "scripts": {
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zseven-w/pen-types": "0.5.2",
+    "@zseven-w/pen-types": "0.7.0",
     "nanoid": "^5.1.6",
     "paper": "^0.12.18"
   },

package/src/__tests__/arc-path.test.ts

@@ -1,39 +1,39 @@
-import { describe, it, expect } from 'vitest'
-import { buildEllipseArcPath, isArcEllipse } from '../arc-path'
+import { describe, it, expect } from 'vitest';
+import { buildEllipseArcPath, isArcEllipse } from '../arc-path';
 
 describe('arc-path', () => {
   describe('isArcEllipse', () => {
     it('returns false for full circle with no inner radius', () => {
-      expect(isArcEllipse(0, 360, 0)).toBe(false)
-    })
+      expect(isArcEllipse(0, 360, 0)).toBe(false);
+    });
 
     it('returns true for partial sweep', () => {
-      expect(isArcEllipse(0, 180, 0)).toBe(true)
-    })
+      expect(isArcEllipse(0, 180, 0)).toBe(true);
+    });
 
     it('returns true for inner radius (donut)', () => {
-      expect(isArcEllipse(0, 360, 0.5)).toBe(true)
-    })
-  })
+      expect(isArcEllipse(0, 360, 0.5)).toBe(true);
+    });
+  });
 
   describe('buildEllipseArcPath', () => {
     it('builds a full circle path', () => {
-      const path = buildEllipseArcPath(100, 100, 0, 360, 0)
-      expect(path).toContain('M')
-      expect(path).toContain('A')
-      expect(path).toContain('Z')
-    })
+      const path = buildEllipseArcPath(100, 100, 0, 360, 0);
+      expect(path).toContain('M');
+      expect(path).toContain('A');
+      expect(path).toContain('Z');
+    });
 
     it('builds a pie slice path', () => {
-      const path = buildEllipseArcPath(100, 100, 0, 90, 0)
-      expect(path).toContain('M50 50') // center point for pie
-      expect(path).toContain('Z')
-    })
+      const path = buildEllipseArcPath(100, 100, 0, 90, 0);
+      expect(path).toContain('M50 50'); // center point for pie
+      expect(path).toContain('Z');
+    });
 
     it('builds a donut path with inner radius', () => {
-      const path = buildEllipseArcPath(100, 100, 0, 360, 0.5)
+      const path = buildEllipseArcPath(100, 100, 0, 360, 0.5);
       // Should have inner arc commands
-      expect(path.split('A').length).toBeGreaterThanOrEqual(3) // outer + inner arcs
-    })
-  })
-})
+      expect(path.split('A').length).toBeGreaterThanOrEqual(3); // outer + inner arcs
+    });
+  });
+});

package/src/__tests__/codegen-utils.test.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect } from 'vitest';
+import { sanitizeName, nodeTreeToSummary } from '../index';
+import type { PenNode } from '@zseven-w/pen-types';
+
+describe('sanitizeName', () => {
+  it('converts kebab-case to PascalCase', () => {
+    expect(sanitizeName('hero-section')).toBe('HeroSection');
+  });
+
+  it('strips non-alphanumeric characters', () => {
+    expect(sanitizeName('Card #1 (main)')).toBe('Card1Main');
+  });
+
+  it('handles empty string', () => {
+    expect(sanitizeName('')).toBe('');
+  });
+});
+
+describe('nodeTreeToSummary', () => {
+  it('renders single node', () => {
+    const nodes: PenNode[] = [
+      { id: 'n1', type: 'frame', name: 'Hero', width: 800, height: 600 } as PenNode,
+    ];
+    const result = nodeTreeToSummary(nodes);
+    expect(result).toContain('[n1]');
+    expect(result).toContain('frame');
+    expect(result).toContain('"Hero"');
+    expect(result).toContain('800x600');
+  });
+
+  it('renders nested children with indentation', () => {
+    const nodes: PenNode[] = [
+      {
+        id: 'p',
+        type: 'frame',
+        name: 'Parent',
+        width: 100,
+        height: 100,
+        children: [{ id: 'c', type: 'rectangle', name: 'Child', width: 50, height: 50 } as PenNode],
+      } as unknown as PenNode,
+    ];
+    const result = nodeTreeToSummary(nodes);
+    expect(result).toContain('[1 children]');
+    expect(result).toContain('  - [c]');
+  });
+
+  it('returns empty string for empty array', () => {
+    expect(nodeTreeToSummary([])).toBe('');
+  });
+});

package/src/__tests__/design-md-parser.test.ts

@@ -0,0 +1,49 @@
+import { describe, it, expect } from 'vitest';
+import { parseDesignMd, generateDesignMd, designMdColorsToVariables } from '../design-md-parser';
+
+describe('parseDesignMd', () => {
+  it('should parse a basic design.md with color palette', () => {
+    const md = `# My App\n\n## Color Palette\n- primary: #3B82F6 (main brand)\n- secondary: #10B981 (accents)\n\n## Typography\nFont family: Inter\nHeadings: 700 weight\nBody: 400 weight\nScale: 1.25\n`;
+    const result = parseDesignMd(md);
+    expect(result.projectName).toBe('My App');
+    expect(result.colorPalette).toHaveLength(2);
+    expect(result.colorPalette![0]).toMatchObject({ name: 'primary', hex: '#3B82F6' });
+    expect(result.typography?.fontFamily).toBe('Inter');
+  });
+
+  it('should return empty spec for empty input', () => {
+    const result = parseDesignMd('');
+    expect(result.projectName).toBeUndefined();
+    expect(result.colorPalette).toEqual([]);
+  });
+
+  it('should handle fuzzy section headers', () => {
+    const md = `# Test\n\n## Visual Theme & Atmosphere\nMinimal, clean\n\n## Colour Roles\n- bg: #FFFFFF (background)\n`;
+    const result = parseDesignMd(md);
+    expect(result.visualTheme).toContain('Minimal');
+    expect(result.colorPalette).toHaveLength(1);
+  });
+});
+
+describe('generateDesignMd', () => {
+  it('should roundtrip parse → generate → parse', () => {
+    const md = `# Roundtrip\n\n## Color Palette\n- primary: #FF0000 (brand)\n- text: #333333 (body text)\n\n## Typography\nFont family: Roboto\nHeadings: 700 weight\nBody: 400 weight\nScale: 1.2\n`;
+    const parsed = parseDesignMd(md);
+    const generated = generateDesignMd(parsed);
+    const reparsed = parseDesignMd(generated);
+    expect(reparsed.colorPalette).toHaveLength(parsed.colorPalette!.length);
+    expect(reparsed.typography?.fontFamily).toBe(parsed.typography?.fontFamily);
+  });
+});
+
+describe('designMdColorsToVariables', () => {
+  it('should convert colors to variable definitions', () => {
+    const colors = [
+      { name: 'primary', hex: '#3B82F6', role: 'main brand' },
+      { name: 'bg', hex: '#FFFFFF', role: 'background' },
+    ];
+    const vars = designMdColorsToVariables(colors);
+    expect(vars['primary']).toMatchObject({ type: 'color', value: '#3B82F6' });
+    expect(vars['bg']).toMatchObject({ type: 'color', value: '#FFFFFF' });
+  });
+});

package/src/__tests__/font-utils.test.ts

@@ -1,26 +1,26 @@
-import { describe, it, expect } from 'vitest'
-import { cssFontFamily } from '../font-utils'
+import { describe, it, expect } from 'vitest';
+import { cssFontFamily } from '../font-utils';
 
 describe('cssFontFamily', () => {
   it('quotes multi-word font names', () => {
-    expect(cssFontFamily('Noto Sans SC')).toBe('"Noto Sans SC"')
-  })
+    expect(cssFontFamily('Noto Sans SC')).toBe('"Noto Sans SC"');
+  });
 
   it('does not quote generic families', () => {
-    expect(cssFontFamily('sans-serif')).toBe('sans-serif')
-    expect(cssFontFamily('monospace')).toBe('monospace')
-    expect(cssFontFamily('system-ui')).toBe('system-ui')
-  })
+    expect(cssFontFamily('sans-serif')).toBe('sans-serif');
+    expect(cssFontFamily('monospace')).toBe('monospace');
+    expect(cssFontFamily('system-ui')).toBe('system-ui');
+  });
 
   it('handles comma-separated lists', () => {
-    expect(cssFontFamily('Inter, sans-serif')).toBe('"Inter", sans-serif')
-  })
+    expect(cssFontFamily('Inter, sans-serif')).toBe('"Inter", sans-serif');
+  });
 
   it('preserves already-quoted names', () => {
-    expect(cssFontFamily('"Noto Sans SC"')).toBe('"Noto Sans SC"')
-  })
+    expect(cssFontFamily('"Noto Sans SC"')).toBe('"Noto Sans SC"');
+  });
 
   it('handles -apple-system', () => {
-    expect(cssFontFamily('-apple-system')).toBe('-apple-system')
-  })
-})
+    expect(cssFontFamily('-apple-system')).toBe('-apple-system');
+  });
+});

package/src/__tests__/layout-engine.test.ts

@@ -1,5 +1,5 @@
-import { describe, it, expect } from 'vitest'
-import type { PenNode } from '@zseven-w/pen-types'
+import { describe, it, expect } from 'vitest';
+import type { PenNode } from '@zseven-w/pen-types';
 import {
   resolvePadding,
   isNodeVisible,
@@ -7,147 +7,233 @@ import {
   getNodeWidth,
   getNodeHeight,
   computeLayoutPositions,
-} from '../layout/engine'
+} from '../layout/engine';
 
-const frame = (props: Partial<PenNode> & { children?: PenNode[] }): PenNode => ({
-  id: 'f1', type: 'frame', x: 0, y: 0, ...props,
-} as PenNode)
+const frame = (props: Partial<PenNode> & { children?: PenNode[] }): PenNode =>
+  ({
+    id: 'f1',
+    type: 'frame',
+    x: 0,
+    y: 0,
+    ...props,
+  }) as PenNode;
 
 const rect = (id: string, w = 50, h = 30): PenNode => ({
-  id, type: 'rectangle', x: 0, y: 0, width: w, height: h,
-})
+  id,
+  type: 'rectangle',
+  x: 0,
+  y: 0,
+  width: w,
+  height: h,
+});
 
 describe('layout-engine', () => {
   describe('resolvePadding', () => {
     it('returns zero for undefined', () => {
-      expect(resolvePadding(undefined)).toEqual({ top: 0, right: 0, bottom: 0, left: 0 })
-    })
+      expect(resolvePadding(undefined)).toEqual({ top: 0, right: 0, bottom: 0, left: 0 });
+    });
 
     it('resolves uniform padding', () => {
-      expect(resolvePadding(10)).toEqual({ top: 10, right: 10, bottom: 10, left: 10 })
-    })
+      expect(resolvePadding(10)).toEqual({ top: 10, right: 10, bottom: 10, left: 10 });
+    });
 
     it('resolves [vertical, horizontal]', () => {
-      expect(resolvePadding([10, 20])).toEqual({ top: 10, right: 20, bottom: 10, left: 20 })
-    })
+      expect(resolvePadding([10, 20])).toEqual({ top: 10, right: 20, bottom: 10, left: 20 });
+    });
 
     it('resolves [top, right, bottom, left]', () => {
-      expect(resolvePadding([1, 2, 3, 4])).toEqual({ top: 1, right: 2, bottom: 3, left: 4 })
-    })
+      expect(resolvePadding([1, 2, 3, 4])).toEqual({ top: 1, right: 2, bottom: 3, left: 4 });
+    });
 
     it('returns zero for string (variable ref)', () => {
-      expect(resolvePadding('$spacing')).toEqual({ top: 0, right: 0, bottom: 0, left: 0 })
-    })
-  })
+      expect(resolvePadding('$spacing')).toEqual({ top: 0, right: 0, bottom: 0, left: 0 });
+    });
+  });
 
   describe('isNodeVisible', () => {
     it('returns true by default', () => {
-      expect(isNodeVisible(rect('a'))).toBe(true)
-    })
+      expect(isNodeVisible(rect('a'))).toBe(true);
+    });
 
     it('returns false when visible is false', () => {
-      expect(isNodeVisible({ ...rect('a'), visible: false })).toBe(false)
-    })
-  })
+      expect(isNodeVisible({ ...rect('a'), visible: false })).toBe(false);
+    });
+
+    it('returns false when enabled is false', () => {
+      expect(isNodeVisible({ ...rect('a'), enabled: false } as PenNode)).toBe(false);
+    });
+  });
 
   describe('inferLayout', () => {
     it('returns undefined for non-frame nodes', () => {
-      expect(inferLayout(rect('a'))).toBeUndefined()
-    })
+      expect(inferLayout(rect('a'))).toBeUndefined();
+    });
 
     it('infers horizontal when gap is set', () => {
-      expect(inferLayout(frame({ gap: 10, children: [] }))).toBe('horizontal')
-    })
+      expect(inferLayout(frame({ gap: 10, children: [] }))).toBe('horizontal');
+    });
 
     it('infers horizontal when padding is set', () => {
-      expect(inferLayout(frame({ padding: 10, children: [] }))).toBe('horizontal')
-    })
+      expect(inferLayout(frame({ padding: 10, children: [] }))).toBe('horizontal');
+    });
 
     it('returns undefined when no layout hints', () => {
-      expect(inferLayout(frame({ children: [rect('a')] }))).toBeUndefined()
-    })
-  })
+      expect(inferLayout(frame({ children: [rect('a')] }))).toBeUndefined();
+    });
+  });
 
   describe('getNodeWidth / getNodeHeight', () => {
     it('returns explicit width', () => {
-      expect(getNodeWidth(rect('a', 200))).toBe(200)
-    })
+      expect(getNodeWidth(rect('a', 200))).toBe(200);
+    });
 
     it('returns explicit height', () => {
-      expect(getNodeHeight(rect('a', 50, 100))).toBe(100)
-    })
+      expect(getNodeHeight(rect('a', 50, 100))).toBe(100);
+    });
 
     it('estimates text width', () => {
-      const text: PenNode = { id: 't', type: 'text', content: 'Hello World', fontSize: 16 }
-      expect(getNodeWidth(text)).toBeGreaterThan(0)
-    })
-  })
+      const text: PenNode = { id: 't', type: 'text', content: 'Hello World', fontSize: 16 };
+      expect(getNodeWidth(text)).toBeGreaterThan(0);
+    });
+  });
 
   describe('computeLayoutPositions', () => {
     it('positions children horizontally', () => {
       const parent = frame({
-        width: 300, height: 100,
-        layout: 'horizontal', gap: 10,
+        width: 300,
+        height: 100,
+        layout: 'horizontal',
+        gap: 10,
         children: [rect('a', 50, 30), rect('b', 50, 30)],
-      })
-      const result = computeLayoutPositions(parent, (parent as PenNode & { children: PenNode[] }).children)
-      expect(result[0].x).toBe(0)
-      expect(result[0].y).toBe(0)
-      expect(result[1].x).toBe(60) // 50 + 10 gap
-    })
+      });
+      const result = computeLayoutPositions(
+        parent,
+        (parent as PenNode & { children: PenNode[] }).children,
+      );
+      expect(result[0].x).toBe(0);
+      expect(result[0].y).toBe(0);
+      expect(result[1].x).toBe(60); // 50 + 10 gap
+    });
 
     it('positions children vertically', () => {
       const parent = frame({
-        width: 100, height: 300,
-        layout: 'vertical', gap: 10,
+        width: 100,
+        height: 300,
+        layout: 'vertical',
+        gap: 10,
         children: [rect('a', 50, 30), rect('b', 50, 30)],
-      })
-      const result = computeLayoutPositions(parent, (parent as PenNode & { children: PenNode[] }).children)
-      expect(result[0].x).toBe(0)
-      expect(result[0].y).toBe(0)
-      expect(result[1].y).toBe(40) // 30 + 10 gap
-    })
+      });
+      const result = computeLayoutPositions(
+        parent,
+        (parent as PenNode & { children: PenNode[] }).children,
+      );
+      expect(result[0].x).toBe(0);
+      expect(result[0].y).toBe(0);
+      expect(result[1].y).toBe(40); // 30 + 10 gap
+    });
 
     it('applies padding', () => {
       const parent = frame({
-        width: 300, height: 100,
-        layout: 'horizontal', padding: 20,
+        width: 300,
+        height: 100,
+        layout: 'horizontal',
+        padding: 20,
         children: [rect('a', 50, 30)],
-      })
-      const result = computeLayoutPositions(parent, (parent as PenNode & { children: PenNode[] }).children)
-      expect(result[0].x).toBe(20)
-      expect(result[0].y).toBe(20)
-    })
+      });
+      const result = computeLayoutPositions(
+        parent,
+        (parent as PenNode & { children: PenNode[] }).children,
+      );
+      expect(result[0].x).toBe(20);
+      expect(result[0].y).toBe(20);
+    });
 
     it('centers children on cross axis', () => {
       const parent = frame({
-        width: 300, height: 100,
-        layout: 'horizontal', alignItems: 'center',
+        width: 300,
+        height: 100,
+        layout: 'horizontal',
+        alignItems: 'center',
+        children: [rect('a', 50, 30)],
+      });
+      const result = computeLayoutPositions(
+        parent,
+        (parent as PenNode & { children: PenNode[] }).children,
+      );
+      expect(result[0].y).toBe(35); // (100 - 30) / 2
+    });
+
+    it('maps alignItems="baseline" to end-alignment (engine has no baseline metric)', () => {
+      // LLMs routinely emit alignItems: 'baseline' from web CSS reflex
+      // for "big number + small unit" patterns like "72 BPM". The
+      // layout engine doesn't compute text baselines; the closest
+      // visually correct fallback is end-alignment (both children
+      // bottom-pinned). Locks in that `baseline` no longer falls
+      // through to the `start` default.
+      //
+      // `baseline` is not part of the TS `alignItems` union, so we
+      // cast through unknown — the normalizer accepts any string and
+      // that's exactly the behavior we want to exercise here.
+      const parent = frame({
+        width: 300,
+        height: 100,
+        layout: 'horizontal',
+        alignItems: 'baseline' as unknown as 'start' | 'center' | 'end',
+        children: [rect('big', 120, 80), rect('unit', 60, 20)],
+      });
+      const result = computeLayoutPositions(
+        parent,
+        (parent as PenNode & { children: PenNode[] }).children,
+      );
+      expect(result[0].y).toBe(20); // 100 - 80 (big pinned to bottom)
+      expect(result[1].y).toBe(80); // 100 - 20 (unit pinned to bottom)
+    });
+
+    it('maps alignItems="flex-end" and "bottom" to end (CSS/alias passthrough)', () => {
+      // `flex-end` is a CSS alias that the normalizer accepts but the
+      // TS union doesn't — cast through unknown same as the baseline
+      // test above.
+      const parent = frame({
+        width: 300,
+        height: 100,
+        layout: 'horizontal',
+        alignItems: 'flex-end' as unknown as 'start' | 'center' | 'end',
         children: [rect('a', 50, 30)],
-      })
-      const result = computeLayoutPositions(parent, (parent as PenNode & { children: PenNode[] }).children)
-      expect(result[0].y).toBe(35) // (100 - 30) / 2
-    })
+      });
+      const result = computeLayoutPositions(
+        parent,
+        (parent as PenNode & { children: PenNode[] }).children,
+      );
+      expect(result[0].y).toBe(70); // 100 - 30
+    });
 
     it('filters invisible children', () => {
       const parent = frame({
-        width: 300, height: 100,
+        width: 300,
+        height: 100,
         layout: 'horizontal',
         children: [rect('a', 50, 30), { ...rect('b', 50, 30), visible: false }],
-      })
-      const result = computeLayoutPositions(parent, (parent as PenNode & { children: PenNode[] }).children)
-      expect(result).toHaveLength(1)
-    })
+      });
+      const result = computeLayoutPositions(
+        parent,
+        (parent as PenNode & { children: PenNode[] }).children,
+      );
+      expect(result).toHaveLength(1);
+    });
 
     it('returns visible children as-is when layout is none', () => {
       const parent = frame({
-        width: 300, height: 100,
+        width: 300,
+        height: 100,
         layout: 'none',
         children: [rect('a', 50, 30)],
-      })
-      const result = computeLayoutPositions(parent, (parent as PenNode & { children: PenNode[] }).children)
-      expect(result).toHaveLength(1)
-      expect(result[0].id).toBe('a')
-    })
-  })
-})
+      });
+      const result = computeLayoutPositions(
+        parent,
+        (parent as PenNode & { children: PenNode[] }).children,
+      );
+      expect(result).toHaveLength(1);
+      expect(result[0].id).toBe('a');
+    });
+  });
+});