@zseven-w/pen-core

Core document operations for OpenPencil — tree manipulation, layout engine, design variables, boolean path operations, 3-way merge, and more.

Install

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:

import {
  createEmptyDocument,
  findNodeInTree,
  findParentInTree,
  insertNodeInTree,
  removeNodeFromTree,
  updateNodeInTree,
  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:

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

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

Flexbox-like auto-layout computation supporting fill_container, fit_content, gap, padding, and alignment:

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:

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 document variables and theme axes:

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:

import { executeBooleanOp, canBooleanOp, BooleanOpType } from '@zseven-w/pen-core';

if (canBooleanOp(selectedNodes)) {
  const result = executeBooleanOp(selectedNodes, BooleanOpType.Union);
}

Document Normalization

Sanitize and fix documents from external sources (Figma imports, AI generation):

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.

Layout Normalization

Repair AI-generated layout issues:

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:

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:

import {
  parseDesignMd,
  generateDesignMd,
  designMdColorsToVariables,
  extractDesignMdFromDocument,
} from '@zseven-w/pen-core';

Path Anchors

Convert between anchor point representation and SVG path data:

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