@zseven-w/pen-renderer 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,64 +1,190 @@
 # @zseven-w/pen-renderer
 
-Standalone CanvasKit/Skia renderer for [OpenPencil](https://github.com/nicepkg/openpencil) design files. Render `.op` documents to a GPU-accelerated canvas — works in browsers, Node.js, and headless environments.
+Standalone CanvasKit/Skia renderer for [OpenPencil](https://github.com/ZSeven-W/openpencil) design files. Render `.op` documents to a GPU-accelerated canvas — works in browsers, Node.js, and headless environments.
 
 ## Install
 
 ```bash
 npm install @zseven-w/pen-renderer canvaskit-wasm
+# or
+bun add @zseven-w/pen-renderer canvaskit-wasm
 ```
 
 `canvaskit-wasm` is a peer dependency — you provide the WASM binary.
 
-## Usage
+## Overview
 
-```ts
+`pen-renderer` is a pure TypeScript + CanvasKit rendering pipeline with no React or framework dependency. It takes a `PenDocument` and renders it to a WebGL surface with GPU acceleration. The pipeline:
+
+```
+PenDocument → flattenToRenderNodes() → absolute positions → SkiaNodeRenderer → GPU canvas
+                                           ↓
+                                    SpatialIndex (R-tree) → hitTest / searchRect
+```
+
+## Quick Start
+
+```typescript
 import { loadCanvasKit, PenRenderer } from '@zseven-w/pen-renderer';
 
-// Initialize CanvasKit
+// 1. Initialize CanvasKit WASM (once, globally)
 await loadCanvasKit();
 
-// Create renderer on a canvas element
+// 2. Create renderer on a canvas element
 const renderer = new PenRenderer(canvas, document, {
   width: 1920,
   height: 1080,
 });
 
-// Render
+// 3. Render
 renderer.render();
+
+// 4. Interact
+renderer.zoomToFit();
+renderer.zoomTo(1.5, centerX, centerY);
+renderer.pan(deltaX, deltaY);
+const node = renderer.hitTest(mouseX, mouseY);
+
+// 5. Cleanup
+renderer.dispose();
 ```
 
-## API
+## Features
 
-### High-level
+### High-Level Renderer
 
-- **`loadCanvasKit()`** — Initialize the CanvasKit WASM module
-- **`PenRenderer`** — Full-featured renderer with viewport, selection, and interaction support
+`PenRenderer` provides a complete rendering solution with viewport, selection, and interaction:
+
+```typescript
+const renderer = new PenRenderer(canvas, document, options);
+
+renderer.setDocument(newDoc); // Update document
+renderer.render(); // Trigger re-render
+renderer.zoomToFit(); // Fit content to viewport
+renderer.zoomTo(zoom, cx, cy); // Zoom to point
+renderer.pan(dx, dy); // Pan viewport
+renderer.hitTest(x, y); // Hit test at screen coords
+renderer.dispose(); // Free resources
+```
 
 ### Document Flattening
 
-Pre-process documents for rendering:
+Pre-process the document tree into flat render nodes with absolute positions:
+
+```typescript
+import {
+  flattenToRenderNodes,
+  resolveRefs,
+  premeasureTextHeights,
+  remapIds,
+} from '@zseven-w/pen-renderer';
+
+// Flatten tree → absolute positions
+const renderNodes = flattenToRenderNodes(children, viewport);
+
+// Resolve $ref nodes to their source
+const resolved = resolveRefs(renderNodes, document);
 
-```ts
-import { flattenToRenderNodes, resolveRefs, premeasureTextHeights } from '@zseven-w/pen-renderer';
+// Pre-measure text heights using Canvas 2D (for accurate layout)
+premeasureTextHeights(renderNodes, canvasContext);
 ```
 
-### Viewport Utilities
+### Viewport Math
 
-```ts
-import { viewportMatrix, screenToScene, sceneToScreen, zoomToPoint } from '@zseven-w/pen-renderer';
+Camera transforms for pan, zoom, and coordinate conversion:
+
+```typescript
+import {
+  viewportMatrix,
+  screenToScene,
+  sceneToScreen,
+  zoomToPoint,
+  getViewportBounds,
+  isRectInViewport,
+} from '@zseven-w/pen-renderer';
+
+const matrix = viewportMatrix(zoom, panX, panY); // 3x3 CanvasKit matrix
+const scene = screenToScene(mouseX, mouseY, viewport);
+const screen = sceneToScreen(nodeX, nodeY, viewport);
+const newVp = zoomToPoint(viewport, 2.0, centerX, centerY);
 ```
 
-### Low-level Renderers
+### Spatial Index
+
+R-tree backed spatial queries for click hit testing and marquee selection:
+
+```typescript
+import { SpatialIndex } from '@zseven-w/pen-renderer';
+
+const index = new SpatialIndex();
+index.rebuild(renderNodes);
+
+const clicked = index.hitTest(x, y); // topmost node at point
+const selected = index.searchRect(x, y, w, h); // all nodes in rect
+const node = index.get(nodeId); // lookup by ID
+```
+
+### Low-Level Renderers
 
 For custom rendering pipelines:
 
-- `SkiaNodeRenderer` — Renders individual nodes to a Skia canvas
-- `SkiaTextRenderer` — Text layout and rendering
-- `SkiaFontManager` — Font loading and management
-- `SkiaImageLoader` — Async image loading with caching
-- `SpatialIndex` — R-tree spatial index for hit testing
+```typescript
+import {
+  SkiaNodeRenderer,
+  SkiaTextRenderer,
+  SkiaFontManager,
+  SkiaImageLoader,
+} from '@zseven-w/pen-renderer';
+```
+
+| Class              | Handles                                                                                                                                                                                 |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `SkiaNodeRenderer` | All node types — rectangles, ellipses, paths, images, icons, lines, polygons. Fills (solid, gradient, image), strokes, effects (shadow, blur), corner radius, clip, opacity, blend mode |
+| `SkiaTextRenderer` | Text layout and rendering via Paragraph API with bitmap fallback. FIFO caches (256 MB text, 64 MB paragraph)                                                                            |
+| `SkiaFontManager`  | Font loading — bundled fonts (Inter, Poppins, Roboto, etc.) + Google Fonts CSS fetching                                                                                                 |
+| `SkiaImageLoader`  | Async image loading with caching and custom source resolvers                                                                                                                            |
+
+### Thumbnail Generation
+
+Render individual nodes to offscreen thumbnails (used for git conflict UI, exports):
+
+```typescript
+import { renderNodeThumbnail } from '@zseven-w/pen-renderer';
+
+const dataUrl = renderNodeThumbnail(node, { width: 200, height: 200 });
+```
+
+### Paint Utilities
+
+```typescript
+import {
+  parseColor,
+  resolveFillColor,
+  resolveStrokeColor,
+  wrapLine,
+  cssFontFamily,
+  sanitizeSvgPath,
+} from '@zseven-w/pen-renderer';
+
+const color = parseColor('#2563EB'); // CanvasKit Color4f
+```
+
+## API Reference
+
+| Category      | Exports                                                                                |
+| ------------- | -------------------------------------------------------------------------------------- |
+| **Init**      | `loadCanvasKit(options?)`, `getCanvasKit()`                                            |
+| **Renderer**  | `PenRenderer`                                                                          |
+| **Flatten**   | `flattenToRenderNodes`, `resolveRefs`, `premeasureTextHeights`, `remapIds`             |
+| **Viewport**  | `viewportMatrix`, `screenToScene`, `sceneToScreen`, `zoomToPoint`, `getViewportBounds` |
+| **Spatial**   | `SpatialIndex` — `rebuild`, `hitTest`, `searchRect`, `get`                             |
+| **Node**      | `SkiaNodeRenderer`                                                                     |
+| **Text**      | `SkiaTextRenderer`                                                                     |
+| **Font**      | `SkiaFontManager`, `BUNDLED_FONT_FAMILIES`                                             |
+| **Image**     | `SkiaImageLoader`                                                                      |
+| **Paint**     | `parseColor`, `sanitizeSvgPath`, `cssFontFamily`                                       |
+| **Thumbnail** | `renderNodeThumbnail`                                                                  |
 
 ## License
 
-MIT
+[MIT](./LICENSE)

package/package.json

@@ -1,7 +1,21 @@
 {
   "name": "@zseven-w/pen-renderer",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Standalone CanvasKit/Skia renderer for OpenPencil (.op) design files",
+  "homepage": "https://github.com/ZSeven-W/openpencil/tree/main/packages/pen-renderer",
+  "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-renderer"
+  },
   "files": [
     "src"
   ],
@@ -16,8 +30,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zseven-w/pen-core": "0.7.0",
-    "@zseven-w/pen-types": "0.7.0",
+    "@zseven-w/pen-core": "0.7.2",
+    "@zseven-w/pen-types": "0.7.2",
     "rbush": "^4.0.1"
   },
   "devDependencies": {

package/src/__tests__/document-flattener.test.ts

@@ -274,4 +274,35 @@ describe('flattenToRenderNodes — dimension consistency', () => {
     expect(t1.clipRect!.h).toBe(rootRN.absH);
     expect(t1.clipRect!.w).toBe(rootRN.absW);
   });
+
+  it('nested frame with clipContent clips its descendants using its own bounds/radius', () => {
+    const root = frame({
+      id: 'root',
+      width: 400,
+      height: 400,
+      children: [
+        frame({
+          id: 'card',
+          x: 40,
+          y: 50,
+          width: 200,
+          height: 120,
+          cornerRadius: 16,
+          clipContent: true,
+          children: [text('inner', 'Nested content', { width: 'fill_container' as any })],
+        }),
+      ],
+    });
+
+    const nodes = flattenToRenderNodes([root]);
+    const card = nodes.find((rn) => rn.node.id === 'card')!;
+    const inner = nodes.find((rn) => rn.node.id === 'inner')!;
+
+    expect(inner.clipRect).toBeDefined();
+    expect(inner.clipRect!.x).toBe(card.absX);
+    expect(inner.clipRect!.y).toBe(card.absY);
+    expect(inner.clipRect!.w).toBe(card.absW);
+    expect(inner.clipRect!.h).toBe(card.absH);
+    expect(inner.clipRect!.rx).toBe(16);
+  });
 });

package/src/document-flattener.ts

@@ -241,10 +241,12 @@ export function flattenToRenderNodes(
       const positioned =
         layout && layout !== 'none' ? computeLayoutPositions(resolved, children) : children;
 
-      // Clipping — only clip for root frames (artboard behavior).
+      // Clipping — root frames always clip like artboards. Nested containers
+      // clip only when clipContent is enabled.
       let childClip = clipCtx;
       const isRootFrame = node.type === 'frame' && depth === 0;
-      if (isRootFrame) {
+      const explicitClip = 'clipContent' in resolved && resolved.clipContent === true;
+      if (isRootFrame || explicitClip) {
         const crRaw = 'cornerRadius' in node ? cornerRadiusVal(node.cornerRadius) : 0;
         const cr = Math.min(crRaw, nodeH / 2);
         childClip = { x: absX, y: absY, w: nodeW, h: nodeH, rx: cr };