@zseven-w/pen-core 0.7.0 → 0.7.2

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,89 +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,
+  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 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
+```typescript
 import {
-  inferLayout,
   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:
 
-```ts
+```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);
+
+// 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
+
+Sanitize and fix documents from external sources (Figma imports, AI generation):
 
-Estimate text dimensions for layout without a browser:
+```typescript
+import { normalizePenDocument } from '@zseven-w/pen-core';
 
-```ts
-import { estimateTextWidth, estimateTextHeight } 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
 
-Sanitize and fix documents imported from external sources:
+Repair AI-generated layout issues:
 
-```ts
-import { normalizePenDocument } from '@zseven-w/pen-core';
+```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
+
+// 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:
+
+```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,21 @@
 {
   "name": "@zseven-w/pen-core",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "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"
   ],
@@ -16,7 +30,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zseven-w/pen-types": "0.7.0",
+    "@zseven-w/pen-types": "0.7.2",
     "nanoid": "^5.1.6",
     "paper": "^0.12.18"
   },