@zseven-w/pen-renderer 0.5.2 → 0.7.0

package/README.md

@@ -13,19 +13,19 @@ npm install @zseven-w/pen-renderer canvaskit-wasm
 ## Usage
 
 ```ts
-import { loadCanvasKit, PenRenderer } from '@zseven-w/pen-renderer'
+import { loadCanvasKit, PenRenderer } from '@zseven-w/pen-renderer';
 
 // Initialize CanvasKit
-await loadCanvasKit()
+await loadCanvasKit();
 
 // Create renderer on a canvas element
 const renderer = new PenRenderer(canvas, document, {
   width: 1920,
   height: 1080,
-})
+});
 
 // Render
-renderer.render()
+renderer.render();
 ```
 
 ## API
@@ -40,13 +40,13 @@ renderer.render()
 Pre-process documents for rendering:
 
 ```ts
-import { flattenToRenderNodes, resolveRefs, premeasureTextHeights } from '@zseven-w/pen-renderer'
+import { flattenToRenderNodes, resolveRefs, premeasureTextHeights } from '@zseven-w/pen-renderer';
 ```
 
 ### Viewport Utilities
 
 ```ts
-import { viewportMatrix, screenToScene, sceneToScreen, zoomToPoint } from '@zseven-w/pen-renderer'
+import { viewportMatrix, screenToScene, sceneToScreen, zoomToPoint } from '@zseven-w/pen-renderer';
 ```
 
 ### Low-level Renderers

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@zseven-w/pen-renderer",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "description": "Standalone CanvasKit/Skia renderer for OpenPencil (.op) design files",
+  "files": [
+    "src"
+  ],
   "type": "module",
   "exports": {
     ".": {
@@ -9,23 +12,20 @@
       "import": "./src/index.ts"
     }
   },
-  "files": [
-    "src"
-  ],
   "scripts": {
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zseven-w/pen-types": "0.5.2",
-    "@zseven-w/pen-core": "0.5.2",
+    "@zseven-w/pen-core": "0.7.0",
+    "@zseven-w/pen-types": "0.7.0",
     "rbush": "^4.0.1"
   },
-  "peerDependencies": {
-    "canvaskit-wasm": "^0.40.0"
-  },
   "devDependencies": {
     "@types/rbush": "^4.0.0",
     "canvaskit-wasm": "^0.40.0",
     "typescript": "^5.7.2"
+  },
+  "peerDependencies": {
+    "canvaskit-wasm": "^0.40.0"
   }
 }

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

@@ -0,0 +1,277 @@
+import { describe, it, expect } from 'vitest';
+import type { PenNode } from '@zseven-w/pen-types';
+import { flattenToRenderNodes } from '../document-flattener';
+
+const frame = (props: Partial<PenNode> & { children?: PenNode[] }): PenNode =>
+  ({
+    id: 'f1',
+    type: 'frame',
+    x: 0,
+    y: 0,
+    ...props,
+  }) as PenNode;
+
+const text = (id: string, content: string, props: Partial<PenNode> = {}): PenNode =>
+  ({
+    id,
+    type: 'text',
+    x: 0,
+    y: 0,
+    content,
+    fontSize: 16,
+    ...props,
+  }) as PenNode;
+
+describe('flattenToRenderNodes — dimension consistency', () => {
+  it('skips nodes disabled via enabled=false', () => {
+    const root = frame({
+      id: 'root',
+      width: 400,
+      height: 600,
+      children: [
+        { id: 'visible', type: 'rectangle', x: 0, y: 0, width: 120, height: 80 } as PenNode,
+        {
+          id: 'disabled',
+          type: 'rectangle',
+          x: 20,
+          y: 20,
+          width: 120,
+          height: 80,
+          enabled: false,
+        } as PenNode,
+      ],
+    });
+
+    const nodes = flattenToRenderNodes([root]);
+
+    expect(nodes.some((rn) => rn.node.id === 'visible')).toBe(true);
+    expect(nodes.some((rn) => rn.node.id === 'disabled')).toBe(false);
+  });
+
+  it('absH uses getNodeHeight for text without height, not sizeToNumber 100 fallback', () => {
+    // Simulates text after fixTextHeights deleted height
+    const root = frame({
+      id: 'root',
+      width: 400,
+      height: 600,
+      layout: 'vertical' as any,
+      children: [
+        // Text with no height property (deleted by fixTextHeights)
+        {
+          id: 't1',
+          type: 'text',
+          content: 'Hello world',
+          fontSize: 16,
+          width: 'fill_container' as any,
+        } as PenNode,
+      ],
+    });
+
+    const nodes = flattenToRenderNodes([root]);
+    const t1 = nodes.find((rn) => rn.node.id === 't1')!;
+
+    // absH should reflect estimated text height (~18-24px for single line at 16px),
+    // NOT the 100px sizeToNumber fallback
+    expect(t1.absH).toBeLessThan(50);
+    expect(t1.absH).toBeGreaterThan(10);
+  });
+
+  it('absW matches child layout width for frame with no explicit width', () => {
+    const root = frame({
+      id: 'root',
+      width: 400,
+      height: 600,
+      layout: 'vertical' as any,
+      children: [
+        frame({
+          id: 'inner',
+          // No explicit width — getNodeWidth should compute from children
+          height: 100,
+          children: [
+            { id: 'r1', type: 'rectangle', x: 0, y: 0, width: 200, height: 50 } as PenNode,
+          ],
+        }),
+      ],
+    });
+
+    const nodes = flattenToRenderNodes([root]);
+    const inner = nodes.find((rn) => rn.node.id === 'inner')!;
+
+    // inner absW should come from getNodeWidth (fitContentWidth → 200),
+    // not the sizeToNumber fallback of 100
+    expect(inner.absW).toBeGreaterThanOrEqual(200);
+  });
+
+  it('nested text nodes get correct positions and non-zero dimensions', () => {
+    const root = frame({
+      id: 'root',
+      width: 375,
+      height: 812,
+      layout: 'vertical' as any,
+      padding: [20, 16],
+      gap: 8,
+      children: [
+        frame({
+          id: 'card',
+          width: 'fill_container' as any,
+          height: 'fit_content' as any,
+          layout: 'vertical' as any,
+          padding: [16, 16],
+          gap: 8,
+          children: [
+            text('title', 'Card Title', {
+              width: 'fill_container' as any,
+              fontSize: 18,
+              fontWeight: '600',
+            }),
+            text('desc', 'Description text that may wrap.', {
+              width: 'fill_container' as any,
+              fontSize: 14,
+            }),
+          ],
+        }),
+      ],
+    });
+
+    const nodes = flattenToRenderNodes([root]);
+
+    for (const rn of nodes) {
+      expect(rn.absW, `${rn.node.id} width > 0`).toBeGreaterThan(0);
+      expect(rn.absH, `${rn.node.id} height > 0`).toBeGreaterThan(0);
+    }
+
+    const card = nodes.find((rn) => rn.node.id === 'card')!;
+    const title = nodes.find((rn) => rn.node.id === 'title')!;
+    const desc = nodes.find((rn) => rn.node.id === 'desc')!;
+
+    // title inside card
+    expect(title.absX).toBeGreaterThan(card.absX);
+    expect(title.absY).toBeGreaterThan(card.absY);
+
+    // desc below title
+    expect(desc.absY).toBeGreaterThan(title.absY);
+  });
+
+  it('absW/absH match nodeW/nodeH for frame without explicit dimensions', () => {
+    // Frame has children but no explicit width — not inside a layout parent,
+    // so computeLayoutPositions does NOT set width. This exposes the divergence
+    // between sizeToNumber (fallback 100) and getNodeWidth (fitContent → 200).
+    const root = frame({
+      id: 'root',
+      width: 400,
+      height: 600,
+      // No layout, gap, padding, or fill_container children → inferLayout returns undefined
+      children: [
+        frame({
+          id: 'inner',
+          // No explicit width or height
+          children: [
+            { id: 'r1', type: 'rectangle', x: 10, y: 10, width: 200, height: 50 } as PenNode,
+          ],
+        }),
+      ],
+    });
+
+    const nodes = flattenToRenderNodes([root]);
+    const inner = nodes.find((rn) => rn.node.id === 'inner')!;
+
+    // getNodeWidth → fitContentWidth → 200 (from child rectangle)
+    // Before fix: absW = 100 (sizeToNumber fallback). After fix: absW = 200.
+    expect(inner.absW).toBeGreaterThanOrEqual(200);
+    // getNodeHeight → fitContentHeight → 50 (from child rectangle)
+    // Before fix: absH = 100 (fallback). After fix: absH = 50 (or greater).
+    expect(inner.absH).toBeGreaterThanOrEqual(50);
+    expect(inner.absH).toBeLessThan(100); // not the 100 fallback
+  });
+
+  it('children with stripped x/y in layout frame get correct positions', () => {
+    const root = frame({
+      id: 'root',
+      width: 400,
+      height: 600,
+      layout: 'vertical' as any,
+      padding: [20, 16],
+      gap: 12,
+      children: [
+        // x/y stripped by sanitizeLayoutChildPositions
+        {
+          id: 't1',
+          type: 'text',
+          content: 'First',
+          fontSize: 16,
+          width: 'fill_container' as any,
+        } as PenNode,
+        {
+          id: 't2',
+          type: 'text',
+          content: 'Second',
+          fontSize: 16,
+          width: 'fill_container' as any,
+        } as PenNode,
+      ],
+    });
+
+    const nodes = flattenToRenderNodes([root]);
+    const t1 = nodes.find((rn) => rn.node.id === 't1')!;
+    const t2 = nodes.find((rn) => rn.node.id === 't2')!;
+
+    // t1 at padding offset
+    expect(t1.absX).toBe(16); // pad.left
+    expect(t1.absY).toBe(20); // pad.top
+
+    // t2 below t1 + gap
+    expect(t2.absY).toBeGreaterThan(t1.absY + t1.absH);
+  });
+
+  it('root frame clipRect matches absW/absH, not a divergent nodeW/nodeH', () => {
+    // Root frame (depth=0) creates a clipRect for its children.
+    // clipRect must use the same dimensions as the RenderNode's absW/absH.
+    const root = frame({
+      id: 'root',
+      width: 400,
+      height: 600,
+      cornerRadius: 12,
+      layout: 'vertical' as any,
+      children: [text('t1', 'Hello', { width: 'fill_container' as any })],
+    });
+
+    const nodes = flattenToRenderNodes([root]);
+    const rootRN = nodes.find((rn) => rn.node.id === 'root')!;
+    const t1 = nodes.find((rn) => rn.node.id === 't1')!;
+
+    // Root frame itself has no clipRect (it IS the clip source)
+    expect(rootRN.clipRect).toBeUndefined();
+
+    // Child inherits root's clip — must match root's rendered dimensions
+    expect(t1.clipRect).toBeDefined();
+    expect(t1.clipRect!.w).toBe(rootRN.absW);
+    expect(t1.clipRect!.h).toBe(rootRN.absH);
+    expect(t1.clipRect!.x).toBe(rootRN.absX);
+    expect(t1.clipRect!.y).toBe(rootRN.absY);
+  });
+
+  it('root frame clipRect matches absW/absH for frame without explicit height', () => {
+    // Frame with fit_content height — getNodeHeight computes from children.
+    // clipRect.h must equal the RenderNode's absH, not a stale fallback.
+    const root = frame({
+      id: 'root',
+      width: 375,
+      // No explicit height — relies on getNodeHeight → fitContentHeight
+      layout: 'vertical' as any,
+      padding: [20, 16],
+      children: [text('t1', 'Card title', { width: 'fill_container' as any, fontSize: 18 })],
+    });
+
+    const nodes = flattenToRenderNodes([root]);
+    const rootRN = nodes.find((rn) => rn.node.id === 'root')!;
+    const t1 = nodes.find((rn) => rn.node.id === 't1')!;
+
+    // absH should be computed from content, not 100 fallback
+    expect(rootRN.absH).toBeGreaterThan(0);
+
+    // clipRect must match absH
+    expect(t1.clipRect).toBeDefined();
+    expect(t1.clipRect!.h).toBe(rootRN.absH);
+    expect(t1.clipRect!.w).toBe(rootRN.absW);
+  });
+});

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

@@ -0,0 +1,65 @@
+import { describe, it, expect } from 'vitest';
+import { SkiaFontManager } from '../font-manager';
+
+// Minimal mock CanvasKit shim — only the bits SkiaFontManager constructor touches.
+function makeMockCk(): unknown {
+  return {
+    TypefaceFontProvider: {
+      Make: () => ({ registerFont: () => {} }),
+    },
+  };
+}
+
+describe('SkiaFontManager.pendingCount / flushPending', () => {
+  it('starts with pendingCount = 0', () => {
+    const fm = new SkiaFontManager(makeMockCk() as never);
+    expect(fm.pendingCount()).toBe(0);
+  });
+
+  it('flushPending resolves immediately when nothing is pending', async () => {
+    const fm = new SkiaFontManager(makeMockCk() as never);
+    let resolved = false;
+    await fm.flushPending().then(() => {
+      resolved = true;
+    });
+    expect(resolved).toBe(true);
+  });
+
+  it('tracks in-flight promises injected via the pendingFetches map', async () => {
+    const fm = new SkiaFontManager(makeMockCk() as never);
+    // Use private access via cast — testing internals to verify the new
+    // public methods read the map correctly without coupling tests to
+    // network/font-loading machinery.
+    let releaseA: () => void = () => {};
+    let releaseB: () => void = () => {};
+    const pA = new Promise<boolean>((resolve) => {
+      releaseA = () => resolve(true);
+    });
+    const pB = new Promise<boolean>((resolve) => {
+      releaseB = () => resolve(true);
+    });
+    (fm as unknown as { pendingFetches: Map<string, Promise<boolean>> }).pendingFetches.set(
+      'a',
+      pA,
+    );
+    (fm as unknown as { pendingFetches: Map<string, Promise<boolean>> }).pendingFetches.set(
+      'b',
+      pB,
+    );
+    expect(fm.pendingCount()).toBe(2);
+
+    let flushResolved = false;
+    const flushed = fm.flushPending().then(() => {
+      flushResolved = true;
+    });
+    await new Promise((r) => setTimeout(r, 10));
+    expect(flushResolved).toBe(false);
+
+    releaseA();
+    releaseB();
+    await pA;
+    await pB;
+    await flushed;
+    expect(flushResolved).toBe(true);
+  });
+});

package/src/__tests__/image-loader.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, it } from 'vitest';
+
+import { SkiaImageLoader } from '../image-loader';
+
+function makeMockCk(): unknown {
+  return {};
+}
+
+const originalDocument = globalThis.document;
+const OriginalImage = globalThis.Image;
+
+describe('SkiaImageLoader', () => {
+  it('starts with pendingCount = 0', () => {
+    const loader = new SkiaImageLoader(makeMockCk() as never);
+    expect(loader.pendingCount()).toBe(0);
+  });
+
+  it('flushPending resolves immediately when nothing is pending', async () => {
+    const loader = new SkiaImageLoader(makeMockCk() as never);
+    let resolved = false;
+    await loader.flushPending().then(() => {
+      resolved = true;
+    });
+    expect(resolved).toBe(true);
+  });
+
+  it('tracks in-flight promises injected via the pendingPromises set', async () => {
+    const loader = new SkiaImageLoader(makeMockCk() as never);
+    let release: () => void = () => {};
+    const pending = new Promise<void>((resolve) => {
+      release = () => resolve();
+    });
+    (loader as unknown as { pendingPromises: Set<Promise<unknown>> }).pendingPromises.add(pending);
+    expect(loader.pendingCount()).toBe(1);
+
+    let flushResolved = false;
+    const flushed = loader.flushPending().then(() => {
+      flushResolved = true;
+    });
+    await new Promise((r) => setTimeout(r, 10));
+    expect(flushResolved).toBe(false);
+
+    release();
+    await pending;
+    await flushed;
+    expect(flushResolved).toBe(true);
+  });
+
+  it('downscales oversized decoded images before creating a CanvasKit image', async () => {
+    let drawSize: { width: number; height: number } | null = null;
+    let imageDataSize: { width: number; height: number } | null = null;
+    let makeImageSize: { width: number; height: number } | null = null;
+
+    (globalThis as { document?: Document }).document = {
+      createElement(tag: string) {
+        expect(tag).toBe('canvas');
+
+        const canvas = {
+          width: 0,
+          height: 0,
+          getContext() {
+            return {
+              drawImage(_img: unknown, _x: number, _y: number, width: number, height: number) {
+                drawSize = { width, height };
+              },
+              getImageData(_x: number, _y: number, width: number, height: number) {
+                imageDataSize = { width, height };
+                return { data: new Uint8ClampedArray(width * height * 4) };
+              },
+            };
+          },
+        };
+
+        return canvas as unknown as HTMLCanvasElement;
+      },
+    } as Document;
+
+    class MockImage {
+      naturalWidth = 8192;
+      naturalHeight = 4096;
+      width = 8192;
+      height = 4096;
+      onload: ((event: Event) => void) | null = null;
+      onerror: ((event: string | Event) => void) | null = null;
+
+      set src(_value: string) {
+        queueMicrotask(() => {
+          this.onload?.({} as Event);
+        });
+      }
+    }
+
+    (globalThis as { Image?: typeof Image }).Image = MockImage as unknown as typeof Image;
+
+    try {
+      const ck = {
+        AlphaType: { Unpremul: 0 },
+        ColorType: { RGBA_8888: 0 },
+        ColorSpace: { SRGB: 0 },
+        MakeImage(info: { width: number; height: number }) {
+          makeImageSize = { width: info.width, height: info.height };
+          return {
+            delete() {},
+            width: () => info.width,
+            height: () => info.height,
+          };
+        },
+      };
+
+      const loader = new SkiaImageLoader(ck as any);
+      const loaded = new Promise<void>((resolve) => {
+        loader.setOnLoaded(resolve);
+      });
+
+      loader.request('large-image.png');
+      await loaded;
+
+      expect(drawSize).toEqual({ width: 4096, height: 2048 });
+      expect(imageDataSize).toEqual({ width: 4096, height: 2048 });
+      expect(makeImageSize).toEqual({ width: 4096, height: 2048 });
+      expect(loader.getStatus('large-image.png')).toEqual({ state: 'loaded' });
+    } finally {
+      if (originalDocument === undefined) {
+        delete (globalThis as { document?: Document }).document;
+      } else {
+        (globalThis as { document?: Document }).document = originalDocument;
+      }
+
+      if (OriginalImage === undefined) {
+        delete (globalThis as { Image?: typeof Image }).Image;
+      } else {
+        (globalThis as { Image?: typeof Image }).Image = OriginalImage;
+      }
+    }
+  });
+});

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

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest';
+import { hasVisibleStroke, shouldUseTransparentFallbackFill } from '../paint-utils';
+
+describe('hasVisibleStroke', () => {
+  it('returns true for a normal colored stroke', () => {
+    expect(
+      hasVisibleStroke({
+        thickness: 4,
+        fill: [{ type: 'solid', color: '#60A5FA' }],
+      }),
+    ).toBe(true);
+  });
+
+  it('returns false when stroke is missing a visible color', () => {
+    expect(
+      hasVisibleStroke({
+        thickness: 4,
+        fill: [{ type: 'solid', color: '#00000000' }],
+      }),
+    ).toBe(true);
+    expect(
+      hasVisibleStroke({
+        thickness: 4,
+        fill: [],
+      }),
+    ).toBe(false);
+  });
+
+  it('returns false when stroke width resolves to zero', () => {
+    expect(
+      hasVisibleStroke({
+        thickness: 0,
+        fill: [{ type: 'solid', color: '#60A5FA' }],
+      }),
+    ).toBe(false);
+  });
+});
+
+describe('shouldUseTransparentFallbackFill', () => {
+  it('keeps stroke-only shapes hollow instead of falling back to default fill', () => {
+    expect(
+      shouldUseTransparentFallbackFill(undefined, {
+        thickness: 12,
+        fill: [{ type: 'solid', color: '#22C55E' }],
+      }),
+    ).toBe(true);
+  });
+
+  it('keeps fill-less containers transparent', () => {
+    expect(shouldUseTransparentFallbackFill(undefined, undefined, true)).toBe(true);
+  });
+
+  it('does not override explicit fills', () => {
+    expect(
+      shouldUseTransparentFallbackFill([{ type: 'solid', color: '#00000000' }], {
+        thickness: 4,
+        fill: [{ type: 'solid', color: '#60A5FA' }],
+      }),
+    ).toBe(false);
+  });
+});