@zseven-w/pen-core 0.6.0 → 0.7.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZSeven—W
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,80 +1,232 @@
 # @zseven-w/pen-core
 
-Core document operations for [OpenPencil](https://github.com/nicepkg/openpencil) — tree manipulation, layout engine, design variables, boolean path operations, and more.
+Core document operations for [OpenPencil](https://github.com/ZSeven-W/openpencil) — tree manipulation, layout engine, design variables, boolean path operations, 3-way merge, and more.
 
 ## Install
 
 ```bash
 npm install @zseven-w/pen-core
+# or
+bun add @zseven-w/pen-core
 ```
 
+## Overview
+
+`pen-core` is the foundation layer of the OpenPencil stack. It provides pure functions for every document operation — tree CRUD, auto-layout computation, variable resolution, SVG path booleans, and document normalization. All operations are immutable (structural sharing) and framework-free.
+
 ## Features
 
 ### Document Tree Operations
 
 Create, query, and mutate the document tree:
 
-```ts
+```typescript
 import {
   createEmptyDocument,
   findNodeInTree,
+  findParentInTree,
   insertNodeInTree,
   removeNodeFromTree,
   updateNodeInTree,
-  deepCloneNode,
   flattenNodes,
-} from '@zseven-w/pen-core'
+  isDescendantOf,
+  getNodeBounds,
+} from '@zseven-w/pen-core';
+
+const doc = createEmptyDocument();
+const node = findNodeInTree(doc.children, 'node-id');
+const parent = findParentInTree(doc.children, 'node-id');
+const flat = flattenNodes(doc.children); // all nodes in flat array
+```
+
+### Node Cloning
+
+Deep clone nodes with optional ID regeneration:
+
+```typescript
+import { deepCloneNode, cloneNodeWithNewIds, cloneNodesWithNewIds } from '@zseven-w/pen-core';
 
-const doc = createEmptyDocument()
-const node = findNodeInTree(doc.children, 'node-id')
+const clone = deepCloneNode(node); // preserve IDs
+const fresh = cloneNodeWithNewIds(node); // new IDs for all descendants
+const batch = cloneNodesWithNewIds([a, b, c]); // batch clone
 ```
 
 ### Multi-Page Support
 
-```ts
-import { getActivePage, getActivePageChildren, migrateToPages } from '@zseven-w/pen-core'
+```typescript
+import {
+  getActivePage,
+  getActivePageChildren,
+  setActivePageChildren,
+  migrateToPages,
+  ensureDocumentNodeIds,
+} from '@zseven-w/pen-core';
+
+// Migrate a single-page document to multi-page format
+const multiPageDoc = migrateToPages(doc);
 ```
 
 ### Layout Engine
 
-Automatic layout computation with auto-sizing, padding, and gap support:
+Flexbox-like auto-layout computation supporting `fill_container`, `fit_content`, gap, padding, and alignment:
 
-```ts
-import { inferLayout, computeLayoutPositions, fitContentWidth, fitContentHeight } from '@zseven-w/pen-core'
+```typescript
+import {
+  computeLayoutPositions,
+  inferLayout,
+  fitContentWidth,
+  fitContentHeight,
+  resolvePadding,
+  getNodeWidth,
+  getNodeHeight,
+  isNodeVisible,
+} from '@zseven-w/pen-core';
+
+// Compute absolute positions for all children in a layout container
+const positions = computeLayoutPositions(frame, frame.children);
+
+// Infer layout direction from child arrangement
+const layout = inferLayout(children); // 'horizontal' | 'vertical' | 'none'
+```
+
+### Text Measurement
+
+Estimate text dimensions for layout without a browser DOM:
+
+```typescript
+import {
+  estimateTextWidth,
+  estimateTextWidthPrecise,
+  estimateTextHeight,
+  resolveTextContent,
+  hasCjkText,
+  defaultLineHeight,
+} from '@zseven-w/pen-core';
+
+const width = estimateTextWidth('Hello World', 16, 400); // font size, weight
+const height = estimateTextHeight(textNode, containerWidth);
+const isCjk = hasCjkText('こんにちは'); // true
 ```
 
 ### Design Variables
 
-Resolve `$variable` references against theme axes:
+Resolve `$variable` references against document variables and theme axes:
+
+```typescript
+import {
+  isVariableRef,
+  resolveVariableRef,
+  resolveNodeForCanvas,
+  replaceVariableRefsInTree,
+  getDefaultTheme,
+} from '@zseven-w/pen-core';
+
+isVariableRef('$primary'); // true
+
+// Resolve all $refs in a node tree for rendering
+const resolved = resolveNodeForCanvas(node, doc.variables, doc.themes);
 
-```ts
-import { resolveVariableRef, resolveNodeForCanvas, replaceVariableRefsInTree } from '@zseven-w/pen-core'
+// Rename $old-name → $new-name across entire tree
+replaceVariableRefsInTree(children, 'old-name', 'new-name');
 ```
 
 ### Boolean Path Operations
 
 Union, subtract, intersect, and exclude paths via Paper.js:
 
-```ts
-import { executeBooleanOp, BooleanOpType } from '@zseven-w/pen-core'
+```typescript
+import { executeBooleanOp, canBooleanOp, BooleanOpType } from '@zseven-w/pen-core';
+
+if (canBooleanOp(selectedNodes)) {
+  const result = executeBooleanOp(selectedNodes, BooleanOpType.Union);
+}
 ```
 
-### Text Measurement
+### Document Normalization
 
-Estimate text dimensions for layout without a browser:
+Sanitize and fix documents from external sources (Figma imports, AI generation):
 
-```ts
-import { estimateTextWidth, estimateTextHeight } from '@zseven-w/pen-core'
+```typescript
+import { normalizePenDocument } from '@zseven-w/pen-core';
+
+const cleaned = normalizePenDocument(rawDoc);
+// Fixes: fill type "color" → "solid", gradient stop position → offset,
+// sizing strings, padding arrays. Preserves $variable refs.
 ```
 
-### Document Normalization
+### Layout Normalization
+
+Repair AI-generated layout issues:
+
+```typescript
+import {
+  normalizeTreeLayout,
+  unwrapFakePhoneMockups,
+  stripRedundantSectionFills,
+  normalizeStrokeFillSchema,
+} from '@zseven-w/pen-core';
+
+// Infer missing layout modes, strip child x/y in layout containers
+normalizeTreeLayout(rootNode);
+```
+
+### 3-Way Document Merge
+
+Diff and merge document trees for collaborative editing and git integration:
+
+```typescript
+import { diffDocuments, mergeDocuments } from '@zseven-w/pen-core';
+
+// One-direction diff: base → current
+const patches = diffDocuments(base, current);
+// patches: NodePatch[] — add, remove, modify, move
 
-Sanitize and fix documents imported from external sources:
+// 3-way merge: base + ours + theirs
+const result = mergeDocuments(base, ours, theirs);
+// result: { document, conflicts }
+```
+
+### Design.md Parser
+
+Parse and generate design specification documents:
+
+```typescript
+import {
+  parseDesignMd,
+  generateDesignMd,
+  designMdColorsToVariables,
+  extractDesignMdFromDocument,
+} from '@zseven-w/pen-core';
+```
+
+### Path Anchors
+
+Convert between anchor point representation and SVG path data:
 
-```ts
-import { normalizePenDocument } from '@zseven-w/pen-core'
+```typescript
+import {
+  anchorsToPathData,
+  pathDataToAnchors,
+  getPathBoundsFromAnchors,
+  inferPathAnchorPointType,
+} from '@zseven-w/pen-core';
 ```
 
+## API Reference
+
+| Category      | Key Functions                                                                                  |
+| ------------- | ---------------------------------------------------------------------------------------------- |
+| **Tree CRUD** | `findNodeInTree`, `insertNodeInTree`, `removeNodeFromTree`, `updateNodeInTree`, `flattenNodes` |
+| **Cloning**   | `deepCloneNode`, `cloneNodeWithNewIds`, `cloneNodesWithNewIds`                                 |
+| **Pages**     | `getActivePage`, `migrateToPages`, `ensureDocumentNodeIds`                                     |
+| **Layout**    | `computeLayoutPositions`, `inferLayout`, `fitContentWidth`, `fitContentHeight`                 |
+| **Text**      | `estimateTextWidth`, `estimateTextHeight`, `hasCjkText`                                        |
+| **Variables** | `resolveVariableRef`, `resolveNodeForCanvas`, `replaceVariableRefsInTree`                      |
+| **Boolean**   | `executeBooleanOp`, `canBooleanOp`                                                             |
+| **Normalize** | `normalizePenDocument`, `normalizeTreeLayout`                                                  |
+| **Merge**     | `diffDocuments`, `mergeDocuments`                                                              |
+| **IDs**       | `generateId`                                                                                   |
+
 ## License
 
-MIT
+[MIT](./LICENSE)

package/package.json

@@ -1,7 +1,24 @@
 {
   "name": "@zseven-w/pen-core",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Core document operations, tree utils, variables, layout engine for OpenPencil",
+  "homepage": "https://github.com/ZSeven-W/openpencil/tree/main/packages/pen-core",
+  "bugs": {
+    "url": "https://github.com/ZSeven-W/openpencil/issues"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "ZSeven-W",
+    "email": "xkayshen@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ZSeven-W/openpencil.git",
+    "directory": "packages/pen-core"
+  },
+  "files": [
+    "src"
+  ],
   "type": "module",
   "exports": {
     ".": {
@@ -9,14 +26,11 @@
       "import": "./src/index.ts"
     }
   },
-  "files": [
-    "src"
-  ],
   "scripts": {
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zseven-w/pen-types": "0.6.0",
+    "@zseven-w/pen-types": "0.7.1",
     "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');
+  });
+});